3.1.7 Listbox Type

**Figure 3.6:** Listbox with icons
$\includegraphics[width=\screenwidth]{listbox-with-icons}$

An instance of this UI control type is visible as a listbox, also known as a list in Symbian, that can be configured to be a single-line item or a double-item listbox. Figure 3.6 shows a single-line item Listbox with icons. For more information on the MBM and MIF formats, see Section 3.1.8.

class Listbox( list, callback)

Creates a Listbox instance. A callable object callback gets called when a listbox selection has been made. list defines the content of the listbox and can be one of the following:

A normal (single-line item) listbox: a list of Unicode strings, for example [unicode_string item1, unicode_string item2]
A double-item listbox: a two-element tuple of Unicode strings , for example [(unicode_string item1, unicode_string item1description), (unicode_string item2, unicode_string item2description)]
A normal (single-line item) listbox with graphics: a two-element tuple consisting of a Unicode string and an Icon object, for example [(unicode_string item1, icon1), (unicode_string item2, icon2)].
A double-item listbox with graphics: a three-element tuple consisting of two Unicode strings and one Icon object, for example [(unicode_string item1, unicode_string item1description, icon1), (unicode_string item2, unicode_string item2description, icon2)]

Example: To produce a normal (single-line item) listbox with graphics:

icon1 = appuifw.Icon(u"z:\\resource\\apps\\avkon2.mbm", 28, 29)
icon2 = appuifw.Icon(u"z:\\resource\\apps\\avkon2.mbm", 40, 41)
entries = [(u"Signal", icon1),
           (u"Battery", icon2)]
lb = appuifw.Listbox(entries, lbox_observe)

Note: Known issue: Using this widget in large/full screen mode results in an unrefreshed area at the bottom of the screen.

Instances of Listbox type have the following methods and properties:

bind( event_code, callback): Binds the callable Python object callback to event event_code. The key codes are defined in the key_codes library module. The call bind(event_code, None) clears an existing binding. In the current implementation the event is always passed also to the underlying native UI control.

current( ): Returns the currently selected item's index in the Listbox.

set_list( list[, current]): Sets the Listbox content to a list of Unicode strings or a list of tuples of Unicode strings. The accepted structures of list are the same as in the Listbox constructor. The optional argument current is the index of the focused list item.

size: The size of the Listbox as a tuple (width, height) - Read only.

position: The coordinates (as a tuple) of the top left corner of the Listbox - Read only.

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