Class CEikMenuPane

CEikMenuPane

Support

Supported from 6.0

Description

A menu pane.

Menu panes are opened by activating the menu title (CEikMenuPaneTitle / MENU_TITLE) which is displayed in the menu bar (CEikMenuBar / MENU_BAR). They can also be cascaded from a menu item (CEikMenuPaneItem / MENU_ITEM) or launched by a menu button (CEikMenuButton).

Menu panes may be defined using a MENU_PANE resource.

Derivation

CBase Base class for all classes to be instantiated on the heap CCoeControl Control base class from which all other controls are derived CEikBorderedControl A control which is drawn surrounded by a rectangular border CEikMenuPane A menu pane

Defined in CEikMenuPane:
AddMenuItemL(), CEikMenuPane(), CItemArray, Close(), CloseCascadeMenu(), ConstructFromResourceL(), ConstructL(), DeleteMenuItem(), Draw(), FocusChanged(), GetColorUseListL(), HandlePointerEventL(), HandleResourceChange(), InputCapabilities(), InsertMenuItemAtL(), ItemAndPos(), ItemData(), MenuButtons(), MenuItemCommandId(), MenuItemIndex(), MoveHighlightTo(), NumberOfItemsInPane(), OfferKeyEventL(), Reset(), SelectedItem(), SetArrowHeadScrollBar(), SetItemArray(), SetItemArrayOwnedExternally(), SetItemButtonState(), SetItemDimmed(), SetItemTextL(), SetLaunchingButton(), SetScrollBarOnLeft(), SetSelectedItem(), StartDisplayingMenuPane(), THotKeyDisplayText, ~CEikMenuPane()

Inherited from CBase:
operator new()

Inherited from CCoeControl:
ActivateGc(), ActivateL(), BackedUpWindow(), CapturesPointer(), ClaimPointerGrab(), CloseWindow(), ComponentControl(), ControlContext(), ControlEnv(), CopyControlContextFrom(), CountComponentControls(), CreateBackedUpWindowL(), CreateWindowL(), DeactivateGc(), DrawDeferred(), DrawNow(), DrawableWindow(), EnableDragEvents(), GetColor(), GetHelpContext(), GrabbingComponent(), HandleComponentControlsResourceChange(), HandlePointerBufferReadyL(), HandleRedrawEvent(), IgnoreEventsUntilNextPointerUp(), Index(), IsActivated(), IsBackedUp(), IsBeingDestroyed(), IsBlank(), IsDimmed(), IsFocused(), IsNonFocusing(), IsReadyToDraw(), IsVisible(), MakeVisible(), MinimumSize(), Observer(), OverrideColorL(), OwnsWindow(), Position(), PositionChanged(), PositionRelativeToScreen(), PrepareForFocusGainL(), PrepareForFocusLossL(), Rect(), RecursivelyMergedInputCapabilities(), ReportEventL(), ResetGc(), SetAllowStrayPointers(), SetBlank(), SetCanDrawOutsideRect(), SetComponentsToInheritVisibility(), SetContainerWindow(), SetContainerWindowL(), SetControlContext(), SetCornerAndSize(), SetCornerAndSizeL(), SetDimmed(), SetExtent(), SetExtentL(), SetExtentToWholeScreen(), SetExtentToWholeScreenL(), SetFocus(), SetFocusing(), SetGloballyCapturing(), SetNeighbor(), SetNonFocusing(), SetObserver(), SetPointerCapture(), SetPosition(), SetRect(), SetRectL(), SetSize(), SetSizeL(), SetSizeWithoutNotification(), SetSizeWithoutNotificationL(), Size(), SizeChanged(), SizeChangedL(), SystemGc(), Window()

Inherited from CEikBorderedControl:
Border(), HasBorder(), SetAdjacent(), SetBorder(), iBorder

CEikMenuPane(MEikMenuObserver* aMenuObserver);

Description

Constructs a menu pane object with the specified observer.

Parameters

MEikMenuObserver* aMenuObserver Menu observer.

void ConstructL(CEikMenuPane* aOwner);

Description

Completes construction of a menu pane object.

This is where a menu is the owner of a cascade menu. See also ConstructFromResourceL().

Parameters

CEikMenuPane* aOwner Menu pane owner.

~CEikMenuPane();

Description

Destructs the menu pane and any associated resources, unless they are externally owned.

void Reset();

Description

Destroys the menu pane's item array.

void SetItemTextL(TInt aCommandId, TInt aRid);

Description

Sets the text in a menu item from resource.

Parameters

TInt aCommandId The command (as defined in an .hrh file) associated with this menu item. This identifies the menu item whose text is to be set. TInt aRid The resource ID of the menu item text.

void SetItemTextL(TInt aCommandId, const TDesC& aDes);

Description

Sets the text in a menu item.

Parameters

TInt aCommandId The command (as defined in an .hrh file) associated with this menu item. This identifies the menu item whose text is to be set. const TDesC& aDes New item text.

void SetItemDimmed(TInt aCommandId,TBool aDimmed);

Description

Dims (greys out) or undims a menu item.

Dimming indicates that user input is not accepted.

Parameters

TInt aCommandId The command (as defined in an .hrh file) associated with this menu item. This identifies the menu item whose text is to be dimmed or un-dimmed. TBool aDimmed ETrue to dim this menu item. EFalse to un-dim this menu item.

void SetItemButtonState(TInt aCommandId,TInt aButtonState);

Description

Sets the state of the specified menu item.

Parameters

TInt aCommandId The command (as defined in an .hrh file) associated with this menu item. This identifies the menu item for which the state is set or unset. TInt aButtonState EEikMenuItemSymbolOn, or EEikMenuItemSymbolIndeterminate.

void AddMenuItemL(const TItem::SData& aMenuItem);

Description

Adds a menu item dynamically by creating a new menu item, setting its data to aMenuItem and appending it to the pane's menu item array.

Updates the menu's scroll bar to take account of the new item.

Parameters

const TItem::SData& aMenuItem The menu item to add.

void AddMenuItemL(CEikMenuPaneItem* aMenuItem);

Support

Supported from 6.1

Description

Adds a new menu item to the menu pane.

Updates the menu's scroll bar to take account of the new item. Note that the item is appended after the existing items — see InsertMenuItemAtL().

Parameters

CEikMenuPaneItem* aMenuItem The menu item to add.

void DeleteMenuItem(TInt aCommandId);

Description

Deletes the specified item in the menu pane.

Parameters

TInt aCommandId The menu item to delete.

void SetSelectedItem(TInt aSelectedItem);

Description

Sets the selected menu item.

Parameters

TInt aSelectedItem The menu item to set as selected.

void StartDisplayingMenuPane (const CEikHotKeyTable* aHotKeyTable,const TPoint& aTargetPos, const CEikMenuPaneTitle* aMenuPaneTitle,TInt aMinTitleWidth, TPopupTargetPosType aTargetType);

Description

Displays a menu pane.

Displays the menu pane with the corner identified by aTargetType in the position specified by aTargetPos. This function uses aMinTitleWidth to calculate the area required to display the menu pane, taking into account whether the menu is a cascading menu or popup menu.

Parameters

const CEikHotKeyTable* aHotKeyTable Optional hotkey table. const TPoint& aTargetPos Position of the corner of the menu pane identified by aTargetType. const CEikMenuPaneTitle* aMenuPaneTitle The menu pane's title. TInt aMinTitleWidth Minimum width of the menu's title. TPopupTargetPosType aTargetType The corner of the menu pane to which aTargetPos relates. The default is the top left corner.

void Close();

Description

Closes the menu pane.

Destroys the command button area container if one exists, closes the window if the menu pane owns one.

void CloseCascadeMenu();

Description

Closes and destroys any current cascade menu and takes focus back.

Does nothing if no cascade menu exists.

void InsertMenuItemAtL(const CEikMenuPaneItem::SData& aMenuItemData, TInt aIndex);

Description

Inserts a new menu item.

The item is inserted into the menu pane's array of menu items at the position identified by aIndex. This is done by creating a new menu item, setting its data to aMenuItemData and inserting it into the pane's menu item array. This function also updates the menu's scroll bar to take account of the new item. If the index is beyond the end of the array, the item is appended to it.

Parameters

Const CEikMenuPaneItem::SData& aMenuItemData Data for the new menu item. TInt aIndex The index into the menu pane's array of menu items at which to insert the new menu item.

void InsertMenuItemAtL(CEikMenuPaneItem* aMenuItem, TInt aIndex);

Support

Supported from 6.1

Description

Inserts a new menu item at index aIndex within the menu pane. Updates the menu's scroll bar to take account of the new item. If the index is beyond the end of the menu pane's array of menu items, the item is appended to the array.

Parameters

CEikMenuPaneItem* aMenuItem The new menu item. TInt aIndex The index into the menu pane's array of menu items at which to insert the new menu item.

void MoveHighlightTo(TInt aNewSelectedItem);

Description

Moves the menu pane highlight.

Moves the menu pane highlight to a newly selected menu item identified by aNewSelectedItem. Scrolls the menu to show the new selected item if necessary and redraws only the newly selected item and the currently selected item if possible.

Parameters

TInt aNewSelectedItem The newly selected menu item.

void SetArrowHeadScrollBar(TBool aArrowHead);

Description

Sets whether the menu pane uses an arrow head scroll bar.

Parameters

TBool aArrowHead If ETrue the menu pane uses an arrow head scroll bar.

void SetItemArray(CItemArray* aItemArray);

Description

Sets the array containing the list of menu items for the current menu pane.

Parameters

CItemArray* aItemArray The menu item array for the menu pane.

void SetItemArrayOwnedExternally(TBool aOwnedExternally);

Description

Set menu item array ownership.

Parameters

TBool aOwnedExternally If ETrue the menu pane's menu item array is set as externally owned. If EFalse the menu pane's menu item array is set as not externally owned.

void SetLaunchingButton(CEikButtonBase* aButton);

Description

Sets the specified button to launch the menu pane.

Parameters

CEikButtonBase* aButton The button to set as launching the menu.

void SetScrollBarOnLeft(TBool aOnLeft);

Description

Sets whether the scroll bar occupies the left side of the menu pane.

Parameters

TBool aOnLeft If ETrue the scroll bar will occupy the left side of the menu pane.

void GetColorUseListL(CArrayFix<TCoeColorUse>& aColorUseList) const;

Description

Gets the list of logical colours employed in the drawing of the control, paired with an explanation of how they are used.

Appends the list into aColorUseList.

Parameters

CArrayFix<TCoeColorUse>& aColorUseList The list of colours paired with explanations.

TCoeInputCapabilities InputCapabilities() const;

Description

Gets the input capabilities of the menu pane which accepts all text.

Return value

TCoeInputCapabilities The menu's input capabilities.

CEikMenuPaneItem* ItemAndPos(TInt aCommandId,TInt& aPos);

Description

Gets a pointer to the specified menu item. Also gets the position of the item within the menu pane. Panics if there are no menu items in the menu pane. Panics if the menu pane id does not identify any menu pane item in the array.

Parameters

TInt aCommandId The ID of the menu item for which a pointer is returned. TInt& aPos On return, the position of the menu item with an ID of aCommandId.

Return value

CEikMenuPaneItem* Pointer to the menu item with an ID of aCommandId.

CEikMenuPaneItem::SData& ItemData(TInt aCommandId);

Description

Gets a reference to the data in the specified menu item.

Parameters

TInt aCommandId The menu item for which data is obtained.

Return value

CEikMenuPaneItem::SData& The menu item's data.

TInt MenuItemCommandId(TInt aIndex);

Description

Gets the CommandId of the specified menu item.

This function panics if aIndex does not exist. Panics if the index is out of range.

Parameters

TInt aIndex The index of the menu item for which the command ID is returned.

Return value

TInt The command ID of the menu item at aIndex.

TInt MenuItemIndex(TInt aCommandId);

Description

Gets the index of the menu item with a command ID of aCommandId.

This function panics if aCommandId does not exist.

Parameters

TInt aCommandId The command ID of the menu item for which the index is returned.

Return value

TInt The index of the menu item with a command ID of aCommandId.

TInt NumberOfItemsInPane() const;

Description

Gets the number of menu items within the menu pane.

Return value

TInt The number of menu items within the menu pane.

TInt SelectedItem() const;

Description

Gets the position of the selected menu item.

Return value

TInt The position of the selected menu item.

CEikButtonGroupContainer* MenuButtons() const;

Description

Gets a pointer to the associated button group.

Ownership is not transferred.

Return value

CEikButtonGroupContainer* A pointer to the associated button group, this is NULL if there is no such group.

void HandlePointerEventL(const TPointerEvent& aPointerEvent);

Description

Handles a pointer event on the menu.

Parameters

const TPointerEvent& aPointerEvent The pointer event to handle.

void HandleResourceChange(TInt aType);

Description

Handles a change to the menu's resources of the specified type, which are shared across the environment, colours or fonts for example.

Parameters

TInt aType The type of resource that has changed.

TKeyResponse OfferKeyEventL (const TKeyEvent& aKeyEvent,TEventCode aType);

Description

Handles key events offered to the menu by the control environment and provides an appropriate implementation of CCoeControl::OfferKeyEventL().

Parameters

const TKeyEvent& aKeyEvent The key event. TEventCode aType The type of key event: EEventKey, EEventKeyUp or EEventKeyDown.

Return value

TKeyResponse Indicates whether or not the key event was used.

TKeyResponse OfferKeyEventL (const TKeyEvent& aKeyEvent,TEventCode aType,TBool aConsumeAllKeys);

Description

Handles key events offered to the menu by the control environment.

Provides an appropriate implementation of CCoeControl::OfferKeyEventL().

Parameters

const TKeyEvent& aKeyEvent The key event. TEventCode aType The type of key event: EEventKey, EEventKeyUp or EEventKeyDown. TBool aConsumeAllKeys If ETrue this function returns EKeyWasConsumed regardless of whether it was used. If EFalse the key event is consumed if possible and either EKeyWasConsumed or EKeyWasNotConsumed is returned as appropriate.

Return value

TKeyResponse Indicates whether or not the key event was used. If aConsumeAllKeys is ETrue this will always be EKeyWasConsumed.

protected: void ConstructFromResourceL(TResourceReader& aReader);

Description

Constructs the menu pane using the specified resource reader.

Fills the menu item array with the list of menu items provided by the resource file.

Parameters

TResourceReader& aReader The resource reader to use.

protected: void Draw(const TRect& aRect) const; protected

Description

Redraws an area of the menu pane.

Parameters

const TRect& aRect Optional. If supplied, the co-ordinates must be relative to the menu pane's top left corner.

protected: void FocusChanged(TDrawNow aDrawNow);

Description

Takes any action required when the menu pane gains or loses focus, to change its appearance for example.

Parameters

TDrawNow aDrawNow If EDrawNow the menu pane is redrawn. If ENoDrawNow the menu pane is not redrawn.

CItemArray

Description

This class provides a constructor to create an array of menu pane items and a destructor to destroy an array of menu pane items.

Derivation

CArrayFix A thin templated base class for arrays of fixed length objects CArrayFixBase Base class for arrays of fixed length objects CArrayPtr A thin templated base class for arrays of pointers to objects CArrayPtrFlat Array of pointers to objects implemented using a flat dynamic buffer CBase Base class for all classes to be instantiated on the heap CEikMenuPane::CItemArray This class provides a constructor to create an array of menu pane items and a destructor to destroy an array of menu pane items

Defined in CEikMenuPane::CItemArray:
CItemArray(), ~CItemArray()

Inherited from CArrayFix:
AppendL(), AppendL()Append, Array(), At(), Back(), End(), ExpandL(), ExtendL(), Find(), FindIsq(), InsertIsqAllowDuplicatesL(), InsertIsqL(), InsertL(), ResizeL(), operator[]

Inherited from CArrayFixBase:
Compress(), Count(), Delete(), Length(), Reset(), Sort()

Inherited from CArrayPtr:
ResetAndDestroy()

Inherited from CArrayPtrFlat:
SetReserveL()

Inherited from CBase:
operator new()

CItemArray();

Description

Creates a flat array of menu pane items.

~CItemArray();

Description

Destructor

Resets and destroys array of menu pane items.

typedef TBuf<20> CEikMenuPane::THotKeyDisplayText;

Description

The text to be displayed for a hotkey.