UIQ Controls - Menu Popout

This guide explains the UIQ control Menu Popout (CQikMenuPopout). The Menu Popout allows you to display a Menu Pane (CEikMenuPane) at an arbitrary position. It is normally used to display a menu pane in response to the selection of an on-screen item. In UI configurations with touch screens (EQikTouchScreenYes) you might display it at the position where the user taps with the pen. When selecting an item via softkeys, you might want the menu to be displayed above the selected item or as a menu pane just above the softkey buttons.

The pictures above show typical usage of the Menu Popout.

The following functionality can be used by the application developer:

• Set the position of the popout's origin,

• Set which of the popout's corners are to be placed at the origin. Legal values are EPopupTargetTopLeft, EPopupTargetTopRight, EPopupTargetBottomLeft, EPopupTargetBottomRight,

• Set if the popout should fill the entire width of the client rect or be automatically adjusted to the width of the text (default).

See the API documentation for the Menu Popout (CQikMenuPopout).

Menu Popout inherits from CBase and owns a CEikMenuPane.

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

Use the following #include directive:

#include <QikMenuPopout.h>

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

LIBRARY qikcore.lib

You can construct the Menu Popout with commands specified in a QIK_COMMAND_LIST in the applications resource file; the resource name is referenced from code when it is to be created:

RESOURCE QIK_COMMAND_LIST r_menupopout_commands
  {
  items=
    {
    QIK_COMMAND
      {
      id = ECmdMenuPopoutCmd1;
      type=EQikCommandTypeScreen;
      text = "First Menu Popout item";
      },
    QIK_COMMAND
      {
      id = ECmdMenuPopoutCmd2;
      type=EQikCommandTypeScreen;
      text = "Second Menu Popout item";
      }
    };
  }

This section discusses the two ways of constructing and launching the control. The Menu Popout is constructed and launched from code; however, the commands can be added from code or read from a resource file.

The example below describes how you can construct a Menu Popout with data from a resource file with your own C++ code.

In your constructor, create the Menu Popout:

iMenuPopout = CQikMenuPopout::NewL(*iEikonEnv, *this);

To finish creation and launch the Menu Popout below and to the right of where the pen is tapped:

void TestApp::HandlePointerEventL(const TPointerEvent& aPointerEvent)
  {
  switch(aPointerEvent.iType)
    {
    case TPointerEvent::EButton1Up:
      TPoint position(aPointerEvent.iPosition);
      position += iEikonEnv->EikAppUi()->ClientRect().iTl;
      iMenuPopout->SetCommandListL(R_MENUPOPOUT_COMMANDS);
      iMenuPopout->DisplayL(position, EPopupTargetTopLeft);
      break;

    default:
      break;        
    }
  }

The positioning of the Menu Popout is absolute. As the position of the pointer event is relative to the client rect, we need to add these two together to get the position for the Menu Popout.

The example below describes how to construct a Menu Popout when the commands to display are obtained by other means than the application resource file.

For this example, it is assumed that your class has an array of commands to be added to the Menu Popout:

RPointerArray<CQikCommand> iCommands;

In the constructor you create the Menu Popout:

iMenuPopout = CQikMenuPopout::NewL(*iEikonEnv, *this);

If you are re-using the Menu Popout, that is, using it with different commands at different times, you should reset it before use:

iMenuPopout->ResetL();

Then, when you are ready to add commands and display it:

count = iCommands.Count();
for(TInt i=0; i < count; i++)
  {
  iMenuPopout->AddCommandL(*iCommands[i]);
  }

TPoint position = PositionRelativeToScreen();
position.iY += Size().iHeight;
TRAP_IGNORE(iMenuPopout->DisplayL(position, EPopupTargetBottomLeft, ETrue));

This section covers the most common functions used for interacting with the control.

3.4.1 How to be notified when a selection is made

In order to be notified when a command is selected you need to implement HandleCommandL.

void TestApp::HandleCommandL(CQikCommand& aCommand)
  {
  aCommand->ExecuteL();
  }

3.4.2 How to Get the CEikMenuPane

The Menu Popout uses a CEikMenuPane and it is possible to get a pointer to it for direct manipulation. Note: Calling ResetL() will invalidate this pointer!

CEikMenuPane* menuPane;
menuPane = iMenuPopout->MenuPane();

Destroying the control is just a matter of invoking operator delete on the Menu Popout object.

Subclassing Menu Popout is not recommended.