3.1.3 Module Level Functions

The following free functions - functions that do not belong to any class - are defined in the appuifw module:

available_fonts( ): Returns a list (Unicode) of all fonts available in the device.

touch_enabled( ): Returns 'True' if the device supports touch input, 'False' otherwise.

query( label, type[, initial_value])

Performs a query with a single-field dialog. The prompt is set to label, and the type of the dialog is defined by type. The value of type can be any of the following strings:

'text'
'code'
'number'
'date'
'time'
'query'
'float'

The type of the optional initial_value parameter and the returned input depend on the value of type:

For text fields, ('text', 'code') it is Unicode
For number fields, it is numeric
For date fields, it is seconds since epoch rounded down to the nearest local midnight

A simple confirmation query and time query take no initial value and return True/None and seconds since local midnight, correspondingly. All queries return None if the users cancel the dialog.

For 'float' query the initial_value setting has no effect.

multi_query( label_1, label_2): A two-field text (Unicode) input dialog. Returns the input values as a 2-tuple. Returns None if the users cancel the dialog.

note( text[, type[, global]]): Displays a note dialog of the chosen type with text (Unicode). The default value for type is 'info', which is automatically used if type is not set. type can be one of the following strings: 'error', 'info' or 'conf'.
If global (integer) is any other value than zero a global note is displayed. A global note is displayed even if the Python application calling this function is in background. The same set of types is supported as in standard note.

popup_menu( list[, label]): A pop-up menu style dialog. list representing the menu contents can be a list of Unicode strings or a list of Unicode string pairs (tuples). The resulting dialog list is then a single-style or a double-style list. A single-style list is shown in full; whereas a double-style list shows the items one at a time. Returns None if the user cancels the operation.

selection_list( choices[, search_field=0]): Executes a dialog that allows the users to select a list item and returns the index of the chosen item, or None if the selection is cancelled by the users. choices is a list of Unicode strings. search_field is 0 (disabled) by default and is optional. Setting it to 1 enables a search field (find pane) that facilitates searching for items in long lists. If enabled, the search field appears after you press a letter key.

multi_selection_list( choices[, style='checkbox', search_field=0])

Executes a dialog that allows the users to select multiple list items. Returns a tuple of indexes (a pair of Unicode strings) of the chosen items, or empty tuple if the no selection is made by the users. choices is a list of Unicode strings. style is an optional string; the default value being 'checkbox'. If 'checkbox' is given, the list will be a checkbox list, where empty checkboxes indicate what items can be marked. The other possible value that can be set for style is 'checkmark'. If 'checkmark' is given, the list will be a markable list, which lists items but does not indicate specifically that items can be selected. To select items on a markable list, use the 'Options' that has Mark/Unmark or the Edit key to select an item and the Navigation key to browse the list. For example views on checkbox and markable lists, see Figure 3.4. search_field is 0 (disabled) by default and is optional. Setting it to 1 enables a search field (find pane) that facilitates searching for items in long lists. If enabled, the search field is always visible with checkbox lists; with markable lists it appears by pressing a letter key.

Example:

tuple = appuifw.multi_selection_list([u'Harry', u'Ron', u'Hermione', u'Voldemort'], style='checkmark', search_field=1)

**Figure 3.4:** Examples of a checkbox list (left) and a markable list (right)
$\includegraphics[width=\screenwidth]{markable-list}$

See About this document... for information on suggesting changes.