Documentation

JQMHeaderToolbar

A JQMHeaderToolbar object displays a header toolbar at the top of the page. The toolbar can display a title, and can optionally include buttons on the left or right side.

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

  • Define the title text to appear in the center of the header with the title property.
  • Fix the toolbar to the top of the page by setting the position property to "fixed".
  • Display buttons in the toolbar with the leftButtonLabel, leftButtonIcon, rightButtonLabel and rightButtonIcon properties.
  • Remove buttons from a header with the removeLeftButton() and removeRightButton() methods.
  • Give the header a navigation bar by adding items to the header's navbar property.

Example:

// create a toolbar:
var header = new JQMHeaderToolbar();
header.title = "Page Header";
header.leftButtonLabel = "Back";
header.leftButtonIcon = "arrow-l";
header.leftButtonTheme = "b";
header.leftButtonGotoPage = "main";

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

Object Properties & Methods

Events
 leftButtonOnClickEvent that occurs when the left button is tapped/clicked.
 navbarOnClickDefault onClick event for the toolbar's JQMNavbar.
 rightButtonOnClickEvent that occurs when the right button is tapped/clicked.
 idThe object's unique identifier. Also used as the variable name in code.
 leftButtonGotoPageGo to this page when the button is tapped.
 leftButtonGotoPageTransitionPage transition used by the leftButtonGotoPage property.
 leftButtonIconAdds an icon image to the toolbar's left button.
 leftButtonIconposDefines the left button icon's position.
 leftButtonLabelThe text on the toolbar's left button.
 leftButtonThemeThe color scheme used to display the toolbar's left button.
 navbarOptional navigation bar to display in the toolbar.
 navbarIconposPosition of icons in the toolbar's JQMNavbar.
 navbarItemsItems in the header's JQMNavbar.
 positionDetermines whether the toolbar has a fixed position.
 rightButtonGotoPageGo to this page when the button is tapped.
 rightButtonGotoPageTransitionPage transition used by the rightButtonGotoPage property.
 rightButtonIconAdds an icon image to the toolbar's right button.
 rightButtonIconposDefines the right button icon's position.
 rightButtonLabelThe text on the toolbar's right button.
 rightButtonThemeThe color scheme used to display the toolbar's right button.
 themeThe color scheme used to display the control.
 titleThe title text displayed in the center of the toolbar.
 userdataAn object for storing user data.

leftButtonOnClick

EventFirst available in version 1.1.0

Event that occurs when the left button is tapped/clicked. The property is set by selecting an HDFunction object within Handheld Designer, or defined at runtime.

In code, the property can be set to reference an existing function:

toolbar.leftButtonOnClick = someExistingFunction;

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

toolbar.leftButtonOnClick = function(event) {
	// this code will be executed when the event is triggered
	object2.value = "The event was triggered";
};

navbarOnClick

EventFirst available in version 1.2.0

Default onClick event for the toolbar's JQMNavbar navigation bar. Equivalent to accessing toolbar.navbar.onClick.

Example:

toolbar.navbarOnClick = function(event) {
	console.log("on click");
};

rightButtonOnClick

EventFirst available in version 1.1.0

Event that occurs when the right button is tapped/clicked. The property is set by selecting an HDFunction object within Handheld Designer, or defined at runtime.

In code, the property can be set to reference an existing function:

toolbar.rightButtonOnClick = someExistingFunction;

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

toolbar.rightButtonOnClick = function(event) {
	// this code will be executed when the event is triggered
	object2.value = "The event was triggered";
};

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;

leftButtonGotoPage

PropertyFirst available in version 1.3.0

Go to this page when the left button is tapped. Using the value "(back)" will automatically navigate the user to the previous page.

You can also select the transition used when changing pages with the leftButtonGotoPageTransition property.

leftButtonGotoPageTransition

PropertyFirst available in version 1.3.0

Page transition used by the leftButtonGotoPage property when changing pages. 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.

leftButtonIcon

PropertyFirst available in version 1.1.0

Adds an icon image to the toolbar's left button.

Can be one of the following values:

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

Example:

// give the left button a "gear" icon
header.leftButtonIcon = "gear";

leftButtonIconpos

PropertyFirst available in version 1.1.0

Defines the left button icon's position.

Can be one of the following values:

left (or blank)Left side of control
rightRight side of control
topTop of control
bottomBottom of control
notextControl has only icon, no text.

Example:

// place the icon on the right
toolbar.leftButtonIconpos = "right";

leftButtonLabel

PropertyFirst available in version 1.1.0

The text on the toolbar's left button.

Example:

// set the left button's text
toolbar.leftButtonLabel = "Back";

leftButtonTheme

PropertyFirst available in version 1.1.0

The color scheme used to display the toolbar's left button. 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":
toolbar.leftButtonTheme = "a";

navbar

PropertyFirst available in version 1.2.0

Optional JQMNavbar navigation bar to display in the toolbar.

Example:

toolbar.navbar = new JQMNavbar();
toolbar.navbar.appendItem("Option 1");
toolbar.navbar.appendItem("Option 2");	
toolbar.navbar.appendItem("Option 3");

navbarIconpos

PropertyFirst available in version 1.2.0

Position of icons in the toolbar's JQMNavbar navigation bar. Equivalent to accessing toolbar.navbar.iconpos.

Example:

// set the iconpos to "top"
toolbar.navbarIconpos = "top";

navbarItems

PropertyFirst available in version 1.2.0

Items in the toolbar's JQMNavbar navigation bar. Equivalent to accessing toolbar.navbar.items.

Example:

// make the first item active
toolbar.navbarItems[0].active = true;

position

PropertyFirst available in version 1.2.0

Determines whether the header has a fixed position, or scrolls with the page. Set to "fixed" to give the toolbar a fixed position.

Example:

header.position = "fixed";

rightButtonGotoPage

PropertyFirst available in version 1.3.0

Go to this page when the right button is tapped. Using the value "(back)" will automatically navigate the user to the previous page.

You can also select the transition used when changing pages with the rightButtonGotoPageTransition property.

rightButtonGotoPageTransition

PropertyFirst available in version 1.3.0

Page transition used by the rightButtonGotoPage property when changing pages. 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.

rightButtonIcon

PropertyFirst available in version 1.1.0

Adds an icon image to the toolbar's right button.

Can be one of the following values:

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

Example:

// give the right button a "gear" icon
toolbar.rightButtonIcon = "gear";

rightButtonIconpos

PropertyFirst available in version 1.1.0

Defines the right button icon's position.

Can be one of the following values:

left (or blank)Left side of control
rightRight side of control
topTop of control
bottomBottom of control
notextControl has only icon, no text.

Example:

// place the icon on the right
toolbar.rightButtonIconpos = "right";

rightButtonLabel

PropertyFirst available in version 1.1.0

The text on the toolbar's right button.

Example:

// set the right button's text
toolbar.rightButtonLabel = "Next";

rightButtonTheme

PropertyFirst available in version 1.1.0

The color scheme used to display the toolbar's right button. 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":
toolbar.leftButtonTheme = "a";

theme

PropertyFirst available in version 1.1.0

The color scheme used to display the control. 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":
control1.theme = "a";

title

PropertyFirst available in version 1.1.0

Defines the title text displayed in the center of the toolbar.

Example:

// set the title
toolbar.title = "Toolbar Title";

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++;
	}
}

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