Selector API

Modifying a widget usually requires having direct access the object. This may not always be the most convenient or efficient way to work with complex UIs. The Tabris.js selector API allows referencing widgets without using an instance, and even manipulating multiple widgets at once.

Selector Strings

A selector string describes an existing widget that we want to work with. There are different formats for these strings, which will look familiar to you if you know CSS.

"*" - Matches all widgets.

"Type" - Matches all widgets of the given type, e.g. "Button" matches all button widgets.

".class" - Matches all widgets that have the given class in their class list, e.g. ".foo" matches a widget with class set to "foo" or "foo bar”.

"#id" - Matches all widgets with the given id, e.g. "#foo" matches all widgets with the id “foo”.

The id of a widget is a property like any other. It’s initial value is undefined, so you always have to assign one yourself, usually when creating the widget.

new tabris.TextView({id: "myLabel"});

Id’s don’t have to be unique, but it is strongly recommended that they are so within a page.

The class property is a string containing a whitespace separated list of “classes”. A class is an arbitrary name for a state or category the widget should be identifiable by. It may only contain alphanumeric characters, “_” and “-“.

new tabris.TextView({class: "label important"});

Classes may be freely mixed, re-used and changed on any widget at any time.

Working with Selectors

To find a widget anywhere in the current page, simply call page.find(selector). This will return a WidgetCollection with all widgets within the page that match the given selector. You can further narrow the search scope by using page.children(selector), or by calling either of these methods on a container within the page.

It is also possible to search through all widgets in the current widget tree, using tabris.ui.find(selector). However, this is rarely practical. Instead, you may use tabris.ui to find all current pages (tabris.ui.children("Page")), actions (tabris.ui.children("Action")) or the drawer (tabris.ui.children("Drawer")).

A selector may also be given in LayoutData instead of a the widget itself. This even works if the referenced widget is not yet created.

The apply method

How it works

apply({<selector: properties>*})

The apply method uses selectors to apply different sets of properties to different widgets in one call. It is available on all widgets, but most commonly used on Page.

It is better to use the aspect ratio of the page as a basis for selecting a layout than the device orientation. This is because when the device is re-oriented, the page is first re-sized, and then rotated in an animation. Also, in future Tabris.js versions a page may not always have the same aspect ratio as the screen.