Figure 1: Relevant constituents of Popups API
The API exposes the functionality through which the user can create, initialize, change a popup list control as well as retrieve user selection from them. Furthermore there is a way to add a find box to the popup list that would interact to provide a UI based filtering mechanism.
The main functionality of this API is available through the CAknPopupList class.
The class is mostly used in situations when the user is required to select
an item from a list. There can be cases when a list is just providing read-only
information to the user (e.g. today’s call list).
The CAknPopupList class furthermore provides the necessary
framework for adding the listbox to the control stack, attaching commands
to the CBA relevant to the list box type, and processing all key events. The
class also removes itself from the control stack and removes the CBA bindings
when the user dismisses the popup list.
The list placed into the popup list can be of any kind such as a regular
text list, markable list or multi-selection list as long as they are derived
from the CEikListBox class. Popup API does not provide any
means to register popup list specific observers to it. If it is important
to observe state changes (e.g. the title needs to be changed as user moves
the highlight) then registering a list observer to the contained list is recommended.
This API provides also a popup heading component, encapsulated in the CAknPopupHeadingPane class.
It provides functions to modify the title text and set header image and animation.
The CAknPopupHeadingPane class is used by popup list, message
and list queries.
The main use cases of Popups API are:
A number of classes are directly or indirectly involved when using Popups API.
The class diagram in Figure 1 shows that popup uses a CEikListBox created
by the client and maintains a reference to it throughout its lifetime. A heading
of type CAknPopupHeadingPane is optionally created depending
on whether the user specified a title or not. A find box (CAknSearchField)
is created optionally while the CBA softkeys are an integral part of the popup
(the user can specify on construction what CBA structure to use and it can
be changed later too).
Figure 1: Relevant constituents of Popups API
