PyS60 Tutorial appuifw Module note

PyS60 Tutorial appuifw Module note

appuifw Module

===========

The appuifw module offers an interface to Series 60 UI application framework.

The services of this interface may only be used in the context of the main thread, that is, the initial thread of a UI application script.

1) Module Level Function

==================

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

available_fonts()

Retrieves a list (Unicode) of all fonts available in the device.

Example:

deviceFonts = appuifw.available_fonts()

-------------------------------------------------------

input 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:

1 'text'

2 'code'

3 'number'

4 'date'

5 'time'

6 'query'

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

o For text fields, ('text', 'code') it is Unicode

o For number fields, it is numeric

o 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.

---------------------------------------------------------

(input_1, input_2) multi_query(label_1, label_2)

A two-field text (Unicode) input dialog. Returns None if the users cancel the dialog.

----------------------------------------------------------

note(text [, type])

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'.

----------------------------------------------------------

index 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 users cancel the operation. Return index of chosen menu.

----------------------------------------------------------

index selection_list(choices=list [, 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=list [, search_field=0]) consists of keywords and values, where

# 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.

----------------------------------------------------------

(indexes) multi_selection_list(choices=list [, 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 None if the selection is cancelled by the users. (choices=list [, style='checkmark', search_field=0])

consists of keywords and values, where

# 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 Navigation key to browse the list and the Edit key to select an item. For example views on

checkbox and markable lists.

# 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(L, style='checkmark', search_field=1)

----------------------------------------------------------

2) Application Type

==================

A single implicit instance(object) of type "Application" always exists when appuifw module is present and can be

referred to with the name app.

New instances cannot be created by a Python program.

A) Instances(object) of "Application" type have the following attributes or member variable

----------------------------------------------------------------------------------------------------------------------

body

The UI control that is visible in the application’s main window. Currently either Text, a Listbox object, Canvas, or None.

The thing that appeared in the body of the application.

----------------------------------------------------------

exit_key_handler

A callable object(similar to function) that is called when the user presses the Exit softkey. Setting exit_key_handler

to None sets it back to the default value.

----------------------------------------------------------

menu

This can be:

# a list of (title, callback) pairs, where each pair describes an item in the application’s menu bar, or

# a list of (title, ((title, callback),...)) pairs, where the tuple of Unicode strings ((title, callback),...) creates a submenu.

title (Unicode) is the name of the item and callback the associated callable object(similar to function). The maximum

allowed number of items in a menu, or items in a submenu, or submenus in a menu is 30.

Example:

appuifw.app.menu = [(u"item 1", item1),

(u"Submenu 1", ((u"sub item 1", subitem1),

(u"sub item 2", subitem2) ))

]

Here 'item 1','sub item 1','sub item 2' are item names(unicode strings).

Here callable object 'item1','subitem1','subitem2' are called when selecting the corresponding items.

----------------------------------------------------------

screen

The screen area used by an application. The appearance of the application on the screen can

be affected by setting one of the following values: 'normal', 'large', and 'full'.

Examples:

appuifw.app.screen='normal' (a normal screen with title pane and softkeys)

appuifw.app.screen='large' (only softkeys visible)

appuifw.app.screen='full' (a full screen)

----------------------------------------------------------

title

The title, in Unicode, that is visible in the application’s title pane.

----------------------------------------------------------

B) Instances of "Application" type have the following methods:

---------------------------------------------------------------------------------

activate_tab(index)

Activates the tab, index counting from zero.

----------------------------------------------------------

name full_name()

Retrieves the full name, in Unicode, of the native application in whose context the current Python interpreter session runs.

----------------------------------------------------------

set_exit()

Requests a graceful exit from the application as soon as the current script execution returns.

----------------------------------------------------------

set_tabs(tab_texts [,callback=None])

Sets tabs with given names on them in the navigation bar; tab_texts is a list of Unicode strings. When the users navigate

between tabs, callback(similar to function) gets called with the index of the active tab as an argument. Tabs can be disabled

by giving an empty or one-item tab_texts list.

----------------------------------------------------------

3) Form Type

==================

Form implements a dynamically configurable, editable multi-field dialog. Form caters for advanced dialog use cases with

requirements such as free selectability of the combination of fields, possibility of validating the user input, and automatically

producing the contents of some dialog fields before allowing the closing of the dialog.

Form([fields=field_list, flags=flag])

For creates a Form instance (object).

# field_list consists of tuples: (label, type [,value]), where

# label is a Unicode string

# type is one of the following strings: 'text', 'number', 'date', 'time',or 'combo'

# value, depending on type: Unicode string, numeric, float (seconds since Unix epoch rounded down to the nearest local midnight),

float (seconds since local midnight), or ([unicode_string choices], index)

Form can also be configured and populated after construction. The configuration flags are visible as an attribute. Form implements

the list protocol that can be used for setting the form fields, as well as obtaining their values after the dialog has been executed.

A) Instances (object) of Form type have the following attributes:

----------------------------------------------------------------------------------

flags

This 'flags' attribute holds the values of the various configuration flags. Currently supported flags are:

FFormEditModeOnly

When this flag is set, the form remains in edit mode while execute runs.

FFormViewModeOnly

When this flag is set, the form cannot be edited at all.

FFormAutoLabelEdit

This flag enables support for allowing the end-users to edit the labels of the form fields.

FFormAutoFormEdit

This flag enables automatic support for allowing the end-users to add and delete the form fields. Note that this is an experimental

feature and is not guaranteed to work with all SDK versions.

FFormDoubleSpaced

When this flag is set, double-spaced layout is applied when the form is executed: one field takes two lines, as the label and the

value field are on different lines.

menu

A list of (title, callback) pairs, where each pair describes an item in the form’s menu bar that is active while the dialog is being

executed. title (Unicode) is the name of the item and callback the associated callable object.

save_hook

This attribute can be set to a callable object that receives one argument and returns a Boolean value. It gets called every time

the users want to save the contents of an executing Form dialog. A candidate list for new form content − a list representing the

currently visible state of the UI − is given as an argument. The list can be modified by save_hook. If save_hook returns True, the

candidate list is set as the new contents of the form. Otherwise, the form UI is reset to reflect the field list contained in Form object.

B) Instances of Form type have the following methods:

---------------------------------------------------------------------------

execute()

Executes the dialog by making it visible on the UI. (User Interface)

insert(), pop(), length(), subscription, subscription-assignment

A subset of the list interface to access the form instance as a list. The subscript notation f[i] can be used to access or modify

the i-th element of the form f. Same limitations as discussed above in the context of the flag FFormAutoFormEdit apply to modifying

a form while it is executing. The ability to change the schema of a form while it is executing is an experimental feature.

4) Text Type

==================

5) Listbox Type

==================

********************************************************************************