UIQ Controls - Task Menu

This guide explains the UIQ control Task Menu (CQikTaskMenu). The Task Menu is a control that contains a collection of Tasks. A Task is a configured DNL that launches another application or view. A Task can also launch a specified viewer with a given file and file syntax. When the Task Menu is launched, the Tasks are displayed in a Menu Pane. When the user selects an item from the menu, the associated Task is executed and the Task Menu is closed.

The Task Menu is not a regular control that is visible in the UI. The control is simply a piece of logic which uses the Menu Pane control to fulfill its purposes. The Task Menu is constructed using two resource structs, one for the commands used in the Menu Pane and one for the tasks associated with the commands. The commands in the Task Menu are specified in the same way as in CEikMenuPane, using QIK_COMMAND in the resource definition. Interaction with the Menu Pane is, however, different. The Task Menu handles the commands and launches the Tasks internally, though others may still observe the commands.

The following functionality can be used by the application developer:

• Define the tasks that can be carried out,

• Define the menu items to be displayed,

• Add menu items,

• Set the menu observer.

See the API documentation for Task Menu (CQikTaskMenu).

The Task Menu is used integrated with the Menu Pane control.

See the API documentation for Menu Pane (CEikMenuPane).

Task Menu inherits from CBase and contains a CEikMenuPane

This section explains how the control is constructed, used and destroyed. Source code examples are used and explained to illustrate how the Task Menu control is used.

Use the following #include directive:

#include <QikTaskMenu.h>

Use the following LIBRARY directive in the project's mmp-file:

LIBRARY Qikcore.lib

Resource files can be used to construct the Task Menu. The resource to use is defined by the QIK_TASK_MENU_ENTRY struct, defined in Qikon.rh. The struct looks like this:

STRUCT QIK_TASK_MENU_ENTRY
    {
    LONG appUid=0;
    LONG viewUid=0;
    LONG paramUid=0;
    LTEXT info="";
    LTEXT fileFormat="";
    LTEXT fileName="";
    LTEXT filePath="";
    LONG commandId=0;
    }

The values given in the struct definition are default values. The struct contains the following:

• appUid contains the ID of the application the DNL activates,

• viewUid contains the ID of the view the DNL activates in the application,

• paramUid is the parameter for the DNL,

• info contains the text that is displayed in the Infoprint,

• fileFormat describes the file syntax for a viewer with UID = appUID,

• fileName contains the name of the file to create for viewers,

• filePath contains the path to the file,

• commandId contains the ID of the command that is associated with the task.

The only way to construct a Task Menu is to specify it in the resource file and let the framework construct it from there.

This section covers the one way of constructing a Task Menu.

3.3.1 Construction with View Framework Using Data from a Resource File

The example below describes how to construct a Task Menu using the view framework. In this example it is assumed that a view is already created.

1) Declare an enumeration for the Task Menu command to be used in a *.hrh file. Hrh files are files to be included both in resource files (*.rss) and C++ files.

/* Declare command ID in a *.hrh file for use both in resource and cpp */
enum TMyCommands
    {
    EMyCmdCreateANewSMS,
    EMyCmdCreateANewMMS
    };

2) The unique ID, UID, for each application needs to be defined in the *.rss file. The Messagings UIDs can be found in QMappExtInferface.h.

#define KUidMsgAppUid 0x100051E3 // Messaging app UID
#define KUidMsgBaseViewUid 0x1000520f // DNL UID for base view.
#define KUidMsgListViewUid 0x10005210 // DNL UID for list view.

// DNL Creation commands
#define KUidQMappCreateEmail 0x1004
#define KUidQMappCreateFax 0x1006
#define KUidQMappCreateSms 0x1005
#define KUidQMappCreateMms 0x100B

3) There are two stucts that need to be declared in the resource (*.rss) file. Declare a QIK_COMMAND_LIST containing QIK_COMMANDS.

RESOURCE QIK_COMMAND_LIST r_my_r_my_task_menu_command_list
    {
    items=
        {
        QIK_COMMAND
            {
            id=EMyCmdCreateANewSMS;
            type=EQikCommandTypeScreen;
            cpfFlags=EQikCpfFlagReplaceContainerPopoutDone;
            text="Task: Create SMS";
            },
        QIK_COMMAND
            {
            id=EMyCmdCreateANewMMS;
            type=EQikCommandTypeScreen;
            cpfFlags=EQikCpfFlagReplaceContainerPopoutDone;
            text="Task: Create MMS";
            }
        };
    }

4) Declare an ARRAY resource with items of QIK_TASK_MENU_ENTRY. The link between a QIK_COMMAND and a QIK_TASK_MENU_ENTRY is the command IDs that are declared in the *.hrh file.

RESOURCE ARRAY r_my_r_my_task_menu_entries
    {
    items =
        {
        QIK_TASK_MENU_ENTRY
            {
            appUid = KUidMsgAppUid;
            viewUid = KUidMsgBaseViewUid;
            paramUid = KUidQMappCreateSms;
            info="New SMS";
            commandId=EMyCmdCreateANewSMS;
            },
        QIK_TASK_MENU_ENTRY
            {
            appUid = KUidMsgAppUid;
            viewUid = KUidMsgBaseViewUid;
            paramUid =KUidQMappCreateMms;
            info="New MMS";
            commandId=EMyCmdCreateANewMMS;
            }
        };
    }

5) The view framework constructs the Task Menu described in this example with this code:

CQikTaskMenu* myTaskMenu=CQikTaskMenu::NewL(R_MY_R_MY_TASK_MENU_COMMAND_LIST, R_MY_TASK_MENU_ENTRIES);
CleanupStack::PushL(myTaskMenu);
                
// Contains the text segment that will be sent in a DNL or stored in a file for a viewer.
// aTaskBuf has the default value KNullDesC so a task can be launched without a task buffer.
TDesC des(KNullDesC);

myTaskMenu->LaunchMenuL(des);
CleanupStack::Pop(myTaskMenu);

6) The result should look something like this:

3.3.2 Construction with Your Own C++ Code Using Data from a Resource File

Not applicable.

3.3.3 Construction Solely from C++ Code

Not applicable.

3.3.4 Construction with the Dialog Framework Using Data from a Resource File

Not applicable.

Destruction of the Task Menu is handled by the framework.

Subclassing Task Menu is not recommended.

DNL

Direct Navigation Link. A way to switch view or application.

Task

A configured DNL which either sends a DNL to the specified application or launches a viewer for a specified file. The task is specified by the resource struct QIK_TASK_MENU_ENTRY.