3.1.4 Application Type

appuifw

app

class Application

Instances of Application type have the following attributes:

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

exit_key_handler: A callable object 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 is a list of the following kinds of items:

(title, callback) which creates a regular menu item
(title, ((title, callback)[...])) which creates a submenu

title (Unicode) is the name of the item and callback the associated callable object. 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"Subitem 1", subitem1),
                         (u"Subitem 2", subitem2)))]

screen

The screen area used by an application. See Figure 3.3 for example screens. 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 the application that is visible in the application's title pane. Must be Unicode.

focus

A callable object that is called with integer as parameter (0 = focus lost, 1 = focus regained) when the application receives focus or it is switched to background. Focus is received e.g. when the application is switched from background to foreground or when the focus is regained from screensaver. Similarly when the screensaver is displayed, focus is lost.

Examples:

>>> import appuifw
>>> def cb(fg):
...   if(fg):
...     print "foreground"
...   else:
...     print "background"
...
>>> appuifw.app.focus=cb
>>> # switch to background, following text is printed from callback:
>>> background
>>> # switch to foreground, following text is printed from callback:
>>> foreground

Note: An improper callback can cause adverse effects. If you, for example, define a callback which takes no parameters you will receive never-ending TypeError exceptions on the Nokia 6600.

orientation: Available only for S60 3rdEd. The orientation of the application. The orientation of the application can be one of the following values: 'automatic' (this is the default value), 'portrait' or 'landscape'.

Instances of Application type have the following methods:

activate_tab( index): Activates the tab index counting from zero.

full_name( ): Returns the full name, in Unicode, of the native application in whose context the current Python interpreter session runs.

uid( ): Returns the UID, 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 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.

layout( layout_id)

Note: Available from S60 2ndEd FP3 onwards (inclusive).

Returns as a tuple the size and the position of the requested layout_id. The logical layouts are outlined partly in Figure 3.2. The position is given from the top left corner. The layout_id can be one of the constants defined in module appuifw^3.1:

EScreen: Screen.

EApplicationWindow: Window that fills the entire screen.

EStatusPane: Indicates common components for most of the applications.

EMainPane: The application main pane is used in all the applications.

EControlPane: Control pane.

ESignalPane: The signal pane is used to indicate signal strength.

EContextPane: The context pane is used to indicate an active application.

ETitlePane: Used to indicate the subject or the name of the main pane content.

EBatteryPane: The battery pane is used to indicate battery strength.

EUniversalIndicatorPane: The universal indicator pane is used to indicate items that require the user's attention while browsing applications.

ENaviPane: The navi pane is used to indicate navigation within an application, to provide context sensitive information to the user while entering or editing data, or to show additional information.

EFindPane: A fixed find pane is used with lists instead of the find pop-up window.

EWallpaperPane: Wallpaper pane.

EIndicatorPane: The universal indicator pane is used to indicate items that require the user's attention while browsing applications.

EAColumn: Used generally to display small sized graphics or heading texts.

EBColumn: Used generally to display large sized icons or heading texts.

ECColumn: Used generally to display data entered by the user. Overlaps with the D column.

EDColumn: Used generally to display additional icons. Overlaps with the C column.

EStaconTop: Top part of status and control panes in landscape layout.

EStaconBottom: Bottom part of status and control panes in landscape layout.

EStatusPaneBottom: Bottom part of status pane in landscape layout.

EControlPaneBottom: Bottom part of control pane in landscape layout.

EControlPaneTop: Top part of control pane in landscape layout.

EStatusPaneTop: Top part of status pane in landscape layout.

Example:

>>> import appuifw
>>> appuifw.app.layout(appuifw.EMainPane)
((176, 144), (0, 44))
>>> # size and position (x, y) of the main pane in Nokia N70

Footnotes

...appuifw ^3.1

Descriptions of the values are from the S60 SDK documentation [4].

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