|
Nokia N97 SDK Example Applications Guide |
1. About this Example
2. Architecture
3. Design and Implementation
The instructions of using the application are simple. The user should open the Options menu, which contains "Show Help" menu item. This menu item is inserted by the AIW Help Provider. Selecting that item creates a request to the AIW Help provider to show the help content. This request goes first to the AIW Framework, which then forwards it to the relevant providers (the Help provider in this case).
The example application demonstrates also the attach/detach functionality of the AIW Framework. Numeric keys '1' and '2' can be used to attach and detach so called AIW interest to the AIW Framework. When the consumer's interest is attached, the Help provider can add its menu item to the Options menu. In the other hand, when the interest is not attached, only an AIW placeholder for the Help command is shown in the menu. The attach status and the number of attached providers is also shown in the main view of the example application.
The service provider, which does the actual help launching, is in normal circumstances the AIW Help Provider. As all AIW providers, it is an ECOM plugin, and should exist by default in the SDK environment. Because of the nature of the AIW Framework, there may also exist other AIW providers offering the help service. In that case, the additional services are also displayed as menu items in the Options menu. On the other hand, if there are no help providers in the environment, no AIW menu items are displayed in the menu.
Note that the required capabilities are provider specific. This means that the AIW Framework does not exactly state which capabilities are required for a consumer application, but these depend on the AIW providers used. Using the Help AIW provider does not require any capabilities.
AIWConsumerBasics.rss file, in R_AIWCONSUMERBASICS_MENUINTEREST resource. The interest contains only items for menu services, i.e. the application is not interested in using so called base
services.
This application is interested in showing help content, so the corresponding AIW command is KAiwCmdHelp. This command is used in the criteria item. The criteria id for this menu service is EAIWConsumerBasicsHelpPlaceholder, and is used for mapping the criteria item to a menu item. The content type is not needed, and therefore a wildcard type
("*") can be used.
MENU_PANE defines the menu of the application. It contains an ordinary (non-AIW) menu item for exiting the application, but it also
contains an AIW menu placeholder, in which the AIW providers can add their menu items.
CAiwServiceHandler is needed. It is dynamically allocated in CAIWConsumerBasicsAppUi::ConstructL() method. The next thing to do is to attach all interests to the AIW Framework. This is done by calling Service Handler's AttachMenuL(). If we would like to use AIW base services, the AttachL() method should be called for them.
An important issue to note is that if the user is opening a submenu, which includes only AIW menu items, it must be handled
by the AIW Framework. Therefore, Service Handler's HandleSubmenuL() method is called first. Only if this method returns EFalse, we should continue the menu initialization. (In this application we don't have an AIW submenus, so this call is actually
not needed. However, it is needed if using automatic AIW submenus with AIW_CASCADE_ID or AIW_INTELLIGENT_CASCADE_ID flags, so it is left for a reference.)
After HandleSubmenuL() call, it is possible to add application specific initialization code. Finally, the Service Handler's InitializeMenuPaneL() method should be called for AIW menus. This method allows the providers to replace the application's menu placeholders with
their AIW menu items.
HandleCommandL() method is called each time when the user selects a menu item from the options menu. This is also the case when an AIW menu
item is selected. The AIW commands cannot be recognized by the example application, so all the unidentified commands need
to be forwarded to the AIW Framework.
Usually, only the ExecuteMenuCmdL() method needs to be called for an AIW (i.e. unidentified) command. However, in this example application, we need to set up
the help parameters every time before calling the ExecuteMenuCmdL(). These kind of initialisations might be quite time consuming. To avoid this problem, the AIW Framework introduces a method
called ServiceCmdByMenuCmd(). By using it, it is possible to obtain the AIW service command id by the menu command id. With that information, it is possible
to make the parameter data initialisation only if the user is actually going to execute the KAiwCmdHelp command.
When executing the Help AIW service command, two parameters need to be passed to the Help provider. These parameters are the
help context UID and the help context string. To transfer these values, we need to create two TAiwGenericParam objects with semantic Id EGenericParamHelpItem. The parameter values are packed in TAiwVariant objects, which are automatically given some TVariantTypeId value. In this case, the required values are EVariantTypeTUid (for context UID) and EVariantTypeDesC (for context string). The TAiwGenericParam objects are then appended to a generic parameter list, which is transferred to the Help AIW provider via Service Handler's
ExecuteMenuCmdL().
|
© Nokia 2009 |