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.

directional_pad: A boolean flag which controls the appearance of a virtual 4-way directional pad that is displayed either at the bottom of the screen or on the right hand corner depending on the orientation when using a Canvas. This is enabled by default on devices that do not have a physical left and right soft key. This value is ignored on other devices, hence setting it to either True or False will have no effect.
Set it to True to enable 4-way directional pad and False to disable it.

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.

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.

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)))]

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

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'    # normal screen with title pane and softkey labels
appuifw.app.screen='large'     # only softkey labels visible
appuifw.app.screen='full'      # full screen mode on all devices

title: The title of the application that is visible in the application's title pane. Must be Unicode.

track_allocations

Set this to true if the interpreter should track all memory allocations and then free the memory which was not explicitly released before application exit. The default value of this attribute is true. As a consequence if there are any memory leaks in the 3rd party extension modules they will be released at the end. To check if there are memory leaks(for debugging purposes) the following approach can be used :


appuifw.app.track_allocations = false

import my_extension
my_extension.do_something()

appuifw.app.track_allocations = true

If the extension leaks memory then it will be reported at application exit.

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.

layout( layout_id)

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

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.

uid( ): Returns the UID, in Unicode, of the native application in whose context the current Python interpreter session runs.

Footnotes

...appuifw ^3.1

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

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