Documentation

JQMListView

A JQMListView object displays a list of items. Each item can have a label, thumbnail image and a count badge, and you can define an event handler to be called when the item is tapped. Lists can also contain dividers to divide the list into sections.

By setting the object's properties, either at design-time in Handheld Designer, or at run-time in code, you can:

  • Access the list's existing items with the items array property.
  • Add a new item with the appendItem() method.
  • Add a new divider with the appendDivider() method.

Example:

// create a simple list view:
var listview = new JQMListView();
listview.appendDivider("Divider #1");
listview.appendItem("Item #1");
listview.appendItem("Item #2");
listview.appendItem("Item #3");
listview.appendItem("Item #4");

For more detail, view the full object documentation on HandheldDesigner.com.

Object Properties & Methods

 appendDividerAdds a new divider to the end of the list view.
 appendItemAdds a new item to the end of the list view.
 autodividersAutomatically generate dividers for the list view items.
 filterProvide a search box for the list.
 filterPlaceholderCustomize the filter placeholder text.
 gotoPageTransitionPage transition used by the list item's gotoPage properties.
 heightThe height of the object, measured in pixels.
 iconDefines the default icon used by the list view's items.
 idThe object's unique identifier. Also used as the variable name in code.
 insertDividerInserts a new divider into the list view.
 insertItemInserts a new item into the list view.
 insetInset list views are styled to be inset on the page.
 itemsAn array of all items in the list view.
 leftThe location of the left of the object from the left edge of the page, measured in pixels.
 onClickEvent that occurs when a list view item is tapped/clicked.
 removeAllItemsRemoves all items from the list view.
 themeThe default theme for the list view items.
 topThe location of the top of the object, as measured from the top of the page, in pixels.
 userdataAn object for storing user data.
 widthThe width of the object, measured in pixels.
 wordwrapControls whether text in the list view is truncated or word-wrapped.
 zIndexThe stack order of the object. Objects with higher numbers appear in front of objects with lower numbers.

appendDivider

MethodFirst available in version 1.1.0

Adds a new divider to the end of the list view.

Usage:

listview.appendDivider(divider);

Arguments:

divider Either a String specifying the label of the new divider, or a JavaScript object containing the properties to be set on the new divider. (optional)

Returns the new JQMListViewDivider object.

Example:

var divider = listview.appendDivider();
divider.label = "Divider";

As a convenience, you can set the label of the new divider by passing it to the appendDivider method:

var divider = listview.appendDivider("Divider");

Or, set multiple properties of the new divider by passing a JavaScript object:

listview.appendDivider({
	label: "Divider",
	theme: "e"
});

appendItem

MethodFirst available in version 1.1.0

Adds a new item to the end of the list view.

Usage:

listview.appendItem(item);

Arguments:

item Either a String specifying the label of the new item, or a JavaScript object containing the properties to be set on the new item. (optional)

Returns the new JQMListViewItem object.

Example:

var item = listview.appendItem();
item.label = "The Item";
item.onClick = someFunction;

As a convenience, you can set the label of the new item by passing it to the appendItem method:

var item = listview.appendItem("The Item");
item.onClick = someFunction;

Or, set multiple properties of the new item by passing a JavaScript object:

listview.appendItem({
	label: "The Item",
	thumbnailImage: "thumbnail1.png",
	onClick: someFunction
});

autodividers

PropertyFirst available in version 1.4.0

Automatically generate dividers for the list view items.

Note: This property is read-only at runtime.

filter

PropertyFirst available in version 1.4.0

Provides a search box for the list, allowing the user to search/filter the contents of the listview.

Note: This property is read-only at runtime.

filterPlaceholder

PropertyFirst available in version 1.4.0

Customize the placeholder text in the search/filter edit box.

Note: This property is read-only at runtime.

gotoPageTransition

PropertyFirst available in version 1.3.0

Page transition used by the list item's gotoPage properties. Can be one of the following values:

  • "fade"
  • "pop"
  • "flip"
  • "turn"
  • "flow"
  • "slidefade"
  • "slide"
  • "slideup"
  • "slidedown"
  • "none" (or empty)

In addition, reverse versions of the transition can be set by adding "reverse" to the property value. For example: "slide reverse".

Note: Transitions are only enabled when using jQuery Mobile AJAX page loading. This option can be enabled in the Project Settings menu.

height

PropertyFirst available in version 1.1.0

The height of the object, measured in pixels.

Example:

// get the height of object1
var h = object1.height;

// set the height of object1
object1.height = 64;

icon

PropertyFirst available in version 1.2.0

Defines the default icon used by the list view's items.

Can be one of the following values:

blank (default icon: arrow-r)
false (no icons)
alert
arrow-d
arrow-l
arrow-r
arrow-u
back
check
delete
forward
gear
grid
home
info
minus
plus
refresh
search
star

Example:

// set the default icon to the "gear" icon
listview.icon = "gear";

id

PropertyFirst available in version 1.1.0

The object's unique identifier. Also used as the variable name in code.

Example:

// get height of object with the id "object1".
var h = object1.height;

insertDivider

MethodFirst available in version 1.1.0

Inserts a new divider into the list view before an existing divider.

Usage:

listview.insertDivider(before, divider);

Arguments:

before Index (number, zero-based) of the divider before which the new divider will be inserted. (required) divider Either a String specifying the label of the new divider, or a JavaScript object containing the properties to be set on the new divider. (optional)

Returns the new JQMListViewDivider object.

Example:

// add a new divider to the beginning of the list view
var divider = listview.insertDivider(0);
divider.label = "Divider";

As a convenience, you can set the label of the new divider by passing it as the second argument to the insertDivider method:

var divider = listview.insertDivider(0, "Divider");

Or, set multiple properties of the new divider by passing a JavaScript object:

listview.insertDivider(0, {
	label: "Divider",
	theme: "e"
});

insertItem

MethodFirst available in version 1.1.0

Inserts a new item into the list view before an existing item.

Usage:

listview.insertItem(before, item);

Arguments:

before Index (number, zero-based) of the item before which the new item will be inserted. (required) item Either a String specifying the label of the new item, or a JavaScript object containing the properties to be set on the new item. (optional)

Returns the new JQMListViewItem object.

Example:

// add a new item to the beginning of the list view
var item = listview.insertItem(0);
item.label = "The Item";
item.onClick = someFunction;

As a convenience, you can set the label of the new item by passing it as the second argument to the insertItem method:

var item = listview.insertItem(0, "The Item");
item.onClick = someFunction;

Or, set multiple properties of the new item by passing a JavaScript object:

listview.insertItem(0, {
	label: "The Item",
	thumbnailImage: "thumbnail1.png",
	onClick: someFunction
});

inset

PropertyFirst available in version 1.2.0

Inset list views are styled to be inset on the page. They have rounded corners and are best displayed less than the full width of the page.

Note: This property is read-only at runtime.

items

PropertyFirst available in version 1.1.0

An array of all items in the list view. Array elements will either be JQMListViewItem or JQMListViewDivider objects. (For simple identification, JQMListViewDivider objects have a divider property set to true.)

The property is read-only.

Example:

for(var i = 0; i < listview.items.length; i+)
{
	if(listview.items[i].divider == true)
	{
		console.log(listview.items[i].label + " is a divider");
	}
}

left

PropertyFirst available in version 1.1.0

The location of the left of the object from the left edge of the page, measured in pixels.

Example:

// get the left location of object1
var x = object1.left;

// set the left location of object1
object1.left = 64;

onClick

EventFirst available in version 1.1.0

Event that occurs when a list view item is tapped/clicked. Note that this event is only called if no onClick event handler is defined for the individual item tapped. Also note that in the context of the event handler, the this variable refers to the JQMListViewItem, and not the list view itself.

The property can be set to reference an existing function:

listview.onClick = someExistingFunction;

Or, you can define an anonymous function containing the code to be executed by the event:

listview.onClick = function(event) {
	console.log("The event was triggered");
};

removeAllItems

MethodFirst available in version 1.1.0

Removes all items from the list view.

Usage:

listview.removeAllItems();

Example:

listview.removeAllItems();

theme

PropertyFirst available in version 1.3.2

The default theme for the list view items. The specific colors used are defined by the jQuery Mobile theme used by your application.

If you are using the default theme, values "a" through "e" are defined.

Example:

// use theme "a":
listview1.theme = "a";

This property is not available at run-time.

top

PropertyFirst available in version 1.1.0

The location of the top of the object, as measured from the top of the page, in pixels.

Example:

// get the top location of object1
var y = object1.top;

// set the top location of object1
object1.top = 64;

userdata

PropertyFirst available in version 1.1.0

An JavaScript object for storing user data. You can use this property to store data for later use. (For example, to share data between event handlers.)

Example:

// track the number of times a button is clicked:
function button1_onClick(event) {
	if(button1.userdata.timesClicked === undefined)
	{
		button1.userdata.timesClicked = 0;
	}
	else
	{
		button1.userdata.timesClicked++;
	}
}

width

PropertyFirst available in version 1.1.0

The width of the object, measured in pixels.

Example:

// get the width of object1
var w = object1.width;

// set the width of object1
object1.width = 64;

wordwrap

PropertyFirst available in version 1.2.0

Controls whether text in the list view is truncated or word-wrapped when it is too long to fit in the available width.

zIndex

PropertyFirst available in version 1.1.0

The stack order of the object. Objects with higher numbers appear in front of objects with lower numbers.

Example:

// "raise" the object
var z = object1.zIndex;
z += 10;

object1.zIndex = z;

Copyright © 2010-2017, Handheld Designer, LLC, All Rights Reserved.
Made by hand in New England, USA.