diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/eikmenub.h --- a/epoc32/include/mw/eikmenub.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/eikmenub.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,740 @@ -eikmenub.h +/* +* Copyright (c) 1997-1999 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* +*/ + + +#if !defined(__EIKMENUB_H__) +#define __EIKMENUB_H__ + +#if !defined(__EIKDEF_H__) +#include +#endif + +#if !defined(__EIKBCTRL_H__) +#include +#endif + +#if !defined(__EIKMENUP_H__) +#include +#endif + +#include +#include +#include + +class CEikHotKeyTable; +class CEikMenuBarExtension; + + +/** + * The CEikMenuBarTitle class encapsulates the data needed to define a menu bar title and + * provides some of the functionality required to display the title. + * + * @since ER5U + */ +class CEikMenuBarTitle : public CBase + { +public: + /** + * Defines a menu bar. See also @c MEikMenuObserver::DynInitMenuPaneL(). + * See also @c MENU_TITLE for details of the resource interface to menu + * items. + */ + struct SData + { + enum { + /** Nominal legth of the text. */ + ENominalTextLength=40 + }; + /** + * The resource ID from which the menu pane is constructed. + */ + TInt iMenuPaneResourceId; + /** + * The text to display on the menu pane. + */ + TBuf iText; // less than this actually stored + }; +public: + /** + * C++ default constructor. + */ + IMPORT_C CEikMenuBarTitle(); + /** + * Destructor. + */ + IMPORT_C ~CEikMenuBarTitle(); + /** + * Sets the title icon. + * + * @param aIcon The icon to set. + */ + IMPORT_C void SetIcon(CGulIcon* aIcon); + + /** + * Sets whether the bitmap and mask are owned externally or not. + * + * @param aOwnedExternally @c ETrue if bitmaps are set as externally owned. + * @c EFalse if bitmaps are set as not being externally owned. + */ + IMPORT_C void SetBitmapsOwnedExternally(TBool aOwnedExternally); + + /** + * Draws the title icon to the graphics context @c aGc, inside the rect @c + * aRect with an offset from the left side of the rectangle of size @c + * aLeftMargin. + * + * @param aGc Window graphic context. + * @param aRect Rectangle area. + * @param aLeftMargin Left margin. + */ + IMPORT_C void DrawIcon(CWindowGc& aGc, TRect aRect, TInt aLeftMargin) const; + + /** + * Constructs a new icon for the title, taking ownership of the picture + * bitmap and the mask bitmap unless they are externally owned. + * + * @param aBitmap Bitmap. + * @param aMask Mask of the bitmap. + */ + IMPORT_C void CreateIconL(CFbsBitmap* aBitmap, CFbsBitmap* aMask); + + /** + * Sets the bitmap for the icon. Transfers + * ownership unless the bitmaps are owned externally. + * + * @param aBitmap Bitmap + */ + IMPORT_C void SetIconBitmapL(CFbsBitmap* aBitmap); + + /** + * Sets the bitmap mask for the icon. Transfers ownership + * unless the bitmaps are owned externally. + * + * @param aMask Mask of a bitmap. + */ + IMPORT_C void SetIconMaskL(CFbsBitmap* aMask); + + /** + * Gets a pointer to the title icon’s bitmap. Does not imply transfer of + * ownership. + * + * @return Pointer to the title icon’s bitmap. + */ + IMPORT_C CFbsBitmap* IconBitmap() const; + + /** + * Gets a pointer to the title icon’s bitmap mask. Does not imply transfer + * of ownership. + * + * @return Pointer to the title icon’s bitmap mask. + */ + IMPORT_C CFbsBitmap* IconMask() const; + +public: // other functions + + /** + * Gets the value of the extra left margin for the title text which will + * take into account the width of the title icon. + * + * @return Value of extra left margin. + */ + TInt ExtraLeftMargin() const; + + /** + * Adjusts the value of the title text baseline offset @c aBaseLine to take + * into account any size of the title icon. + * + * @param[in,out] aBaseLine Gets result of baseline. + * @param[in,out] aTitleHeight Gets result of height. + */ + void CalculateBaseLine(TInt& aBaseLine, TInt& aTitleHeight); + +public: + + /** The title’s position on the menu bar. */ + TInt iPos; + + /** The title’s width. */ + TInt iWidth; + + /** The menu bar title text. */ + SData iData; + + /** Flags used internally by the menu bar title. */ + TInt iTitleFlags; + +private: + CGulIcon* iIcon; + }; + +/** + * Menu bars are constructed from @c MENU_BAR resources and issue application + * commands which should be handled by overriding @c + * CEikAppUi::HandleCommandL(). + */ +class CEikMenuBar : public CEikBorderedControl, + public MEikCommandObserver, + public MAknIntermediateState + { + +public: + + /** + * Declares an object type for a class, in order to allow the object + * provider mechanism to locate and provide objects from the class. + */ + DECLARE_TYPE_ID(0x101F4106) + + /** Specifies the menu item within the menu pane. */ + struct SCursor + { + /** Index of a title in the menu bar. */ + TInt iMenuPaneIndex; + + /** Index of an item in a menu pane. */ + TInt iMenuItemIndex; + }; + + /** */ + struct SPosition + { + /** */ + TInt iMenuId; + + /** */ + SCursor iMenuCursorPos; + }; + + enum TMenuType { + /** + * Options menu launched from the Options softkey. + * This is the default value. + */ + EMenuOptions = 0, + + /** + * Context sensitive menu that is launched from selection key + * when the application supports it. + */ + EMenuContext = 1, + + /** + * Edit menu containing editing specific items. + */ + EMenuEdit = 2, + + /** + * Options menu launched from the Options softkey. Task swapper item + * is not shown. + */ + EMenuOptionsNoTaskSwapper = 3 + }; + + friend class CEikMenuPaneTitle; + +private: + + enum {ENothingSelected=-1}; + +public: + + /** + * Destructor. + */ + IMPORT_C ~CEikMenuBar(); + + /** + * C++ default constructor. + */ + IMPORT_C CEikMenuBar(); + +public: // framework + + /** + * From @c CCoeControl + * + * Handles key events offered to the menu by the control environment and + * provides an appropriate implementation of + * @c CCoeControl::OfferKeyEventL(). + * + * @param aKeyEvent The key event. + * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or @c + * EEventKeyDown. + * + * @return Indicates whether or not the key event was used by this control. + */ + IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, + TEventCode aType); + + /** + * From @c CCoeControl + * + * Handles pointer events. This function gets called whenever a pointer + * event occurs in the control, i.e. when the pointer is within the + * control's extent, or when the control has grabbed the pointer. The + * control should implement this function to handle pointer events. + * + * Note: events of type @c EButton1Down are processed before @c + * HandlePointerEventL() is called, in order to transfer keyboard focus to + * the control in which the @c EButton1Down event occurred. + * + * If overriding @c HandlePointerEventL(), the implementation must include + * a base call to @c CCoeControl's @c HandlePointerEventL(). + * + * @param aPointerEvent The pointer event. + */ + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent); + + /** + * From @c CCoeControl + * + * Not implemented. + * + * @param Not used. + */ + IMPORT_C void Draw(const TRect& aRect) const; + +private: + + /** + * From CAknControl + */ + IMPORT_C void* ExtensionInterface( TUid aInterface ); + +private: // from MCoeInputObserver + + IMPORT_C TCoeInputCapabilities InputCapabilities() const; + +public: + + /** + * This class enables construction, and destruction of an array of + * information about menu bar titles. + */ + class CTitleArray : public CArrayPtrFlat + { + + public: + + /** + * Destructor. + */ + IMPORT_C ~CTitleArray(); + + /** + * C++ default constructor. + */ + IMPORT_C CTitleArray(); + + /** + * Adds the menu bar title @c aMenuTitle to the end of the array owned + * by the menu bar and transfers ownership. + * + * @param aMenuTitle Append object to flat array. + */ + IMPORT_C void AddTitleL(CEikMenuBarTitle* aMenuTitle); + + /** + * Deletes selected index into array. + * + * @param aResource Array index that will be delete. + */ + void DeleteResource(TInt aResource); + }; + +public: // new functions + + /** + * Second phase constructor for a menu bar. + * + * @param aMenuObserver The menu's observer. + * @param aHotKeyResourceId The ID of the resource, of type HOTKEY from + * which the hotkey table is created. This is optional. By default + * it's nil. + * @param aMenuTitleResourceId The ID of the resource, of type @c MENU_BAR + * from which the menu title array is created. This is optional. By + * default it's nil. + */ + + IMPORT_C void ConstructL(MEikMenuObserver* aMenuObserver, + TInt aHotKeyResourceId=0, + TInt aMenuTitleResourceId=0); + + /** + * Second phase constructor for a menu bar which builds the menu bar from + * the given resource file. + * + * @param aReader The resource reader. + */ + IMPORT_C void ConstructFromResourceL(TResourceReader& aReader); + + /** + * Not implemented + * + * @param aHotKeyResourceId Not used. + * @param aMenuTitleResourceId Not used. + * @param aDisplayNow Not used. + */ + IMPORT_C void ChangeMenuBarL(TInt aHotKeyResourceId=0, + TInt aMenuTitleResourceId=0, + TInt aDisplayNow=ETrue); + + /** + * Not implemented! + * + * @param aHotKeyTable Not used. + * @return NULL. + */ + IMPORT_C CEikHotKeyTable* SetHotKeyTable(CEikHotKeyTable* aHotKeyTable); + + /** + * Sets the menu’s resource ID. + * + * @param aMenuTitleResourceId The ID of the resource to use. + */ + IMPORT_C void SetMenuTitleResourceId(TInt aMenuTitleResourceId); + + /** + * + * + * @param aMenuTitleResourceId + */ + IMPORT_C void SetContextMenuTitleResourceId(TInt aMenuTitleResourceId); + + /** + * Not implemented. + * + * @param aTitleArray Not used. + */ + IMPORT_C void SetMenuTitleArray(CTitleArray* aTitleArray); + + /** + * Not implemented. + * + * @param aOwnedExternally Not used. + */ + IMPORT_C void SetTitleArrayOwnedExternally(TBool aOwnedExternally); + + /** + * Sets the cursor to the specifed menu pane and menu item. + * + * @param aCursor The menu pane and menu item to which the cursor is set. + * @return A @c SCursor structure holding the menu item within the menu + * pane. + */ + IMPORT_C SCursor SetMenuCursor(const SCursor& aCursor); + + /** + * Stops displaying the menu bar. + * + * This function causes the menu bar to disappear from the screen until it + * is invoked again by the user. In most circumstances this is done by the + * @c Uikon framework, so an application program will not normally need to + * use this function. + */ + IMPORT_C void StopDisplayingMenuBar(); + + /** + * Displays the menu bar. + * + * If the menu is not already displayed, this function displays the menu + * bar and allows the user to make a selection. In most circumstances this + * is done by the @c Uikon framework, so an application program will not + * normally need to use this function. + */ + IMPORT_C void TryDisplayMenuBarL(); + IMPORT_C void TryDisplayContextMenuBarL(); + /** + * If the menu is not already displayed, this function displays the menu + * bar without fep menu and allows the user to make a selection. In most + * circumstances this is done by the @c Uikon framework, so an application + * program will not normally need to use this function. + */ + IMPORT_C void TryDisplayMenuBarWithoutFepMenusL(); + + /** + * Not implemented. + * + * @param aNewSelectedTitle Not used + * @param aNewSelectedItem Not used. + */ + IMPORT_C void MoveHighlightToL(TInt aNewSelectedTitle, + TInt aNewSelectedItem=0); + + /** + * Not implemented. + * + * @param aItem Not used. + */ + IMPORT_C void DrawItem(TInt aItem) const; + + /** + * Gets a pointer to the menu’s hot key table. + */ + CEikHotKeyTable* HotKeyTable() const { return(iHotKeyTable); } + + /** + * Gets the index of the menu pane selected by the cursor. + * + * @return The index of the selected menu pane. + */ + IMPORT_C TInt SelectedTitle(); + + /** + * Gets the index of the menu item selected by the cursor. + * + * @return The index of the selected menu item. + */ + IMPORT_C TInt SelectedItem(); + + /** + * Searches for the menu item that corresponds to the specified command. + * + * @param aCommandId The ID to search for. + * @param aPaneindex Menu pane index. + * @param aItemindex Menu item index. + */ + IMPORT_C virtual void FindCommandIdInResourceL(TInt aCommandId, + TInt& aPaneindex, + TInt& aItemindex); + + /** + * Gets a menu pane resource. + * + * @return The pointer to @c CEikMenuPane object containing a menu pane + * resource. + */ + IMPORT_C CEikMenuPane* MenuPane(); + + /** + * If the menu bar is visible, removes the menu bar height from the top of + * @c aRect and returns the new rectangle in a new value of @c aRect. + * + * @param[in,out] aRect A rectangle that on return is reduced in height by + * the height of the menu bar. + */ + IMPORT_C void ReduceRect(TRect& aRect) const; + + /** + * Gets array of information about the menu bar titles. + * + * @return Pointer to @c CTitleArray object containing array of information + * about menu bar titles. + */ + IMPORT_C CTitleArray* TitleArray(); + + /** + * Sets menu observer interface. + * + * @param aEditMenuObserver Menu observer interface. + */ + IMPORT_C void SetEditMenuObserver(MEikMenuObserver* aEditMenuObserver); + + /** + * Sets the menu observer interface to @c NULL. + * + * @param aEditMenuObserver Menu observer interface that will be set to @c + * NULL. + */ + IMPORT_C void RemoveEditMenuObserver(MEikMenuObserver* aEditMenuObserver); + + /** + * Allows the client to determine if the menubar instance is displayed. + * + * @return @c Etrue if displayed and @c EFalse if not. + */ + IMPORT_C TBool IsDisplayed(); + + /** + * Sets type of the menu. Menu can be for example Options menu launched from + * Options softkey or context sensitive menu launched from the selection key. + * By default the launched menu is options menu. + * @since S60 3.1 + * @param aMenuType One of values of CEikMenuBar::TMenuType enumeration. + */ + IMPORT_C void SetMenuType(TMenuType aMenuType); + +private: // from MAknIntermediateState + + void CloseState(); + +public: // from CCoeControl + + /** + * From @c CCoeControl. + * + * Gets the list of logical colours used to draw the control. + * + * The list includes an explanation of how each colour is used. By default, + * this function has an empty implementation. + * + * @since 5.1 SDK. + * @param aColorUseList The colour list. + */ + IMPORT_C virtual void GetColorUseListL( + CArrayFix& aColorUseList) const; + + /** + * From @c CCoeControl. + * + * Handles a change to the control's resources. + * + * The types of resources handled are those which are shared across the + * environment, e.g. colours or fonts. + * + * @since 5.1 SDK. + * @param aType A message UID value. The most common is @c + * KEikMessageColorSchemeChange which controls get when the colour + * scheme is changed. Other examples include: @c + * KEikMessageFadeAllWindows, @c KEikMessageUnfadeWindows, @c + * KEikMessageZoomChange, @c KEikMessageVirtualCursorStateChange, @c + * KEikMessageCapsLock, @c KEikMessagePrepareForSave. + */ + IMPORT_C virtual void HandleResourceChange(TInt aType); + +private: // from CCoeControl + IMPORT_C void Reserved_1(); + IMPORT_C void Reserved_2(); + // from MEikCommandObserver + void ProcessCommandL(TInt aCommandId); +private: // from MObjectProvider + TTypeUid::Ptr MopSupplyObject(TTypeUid aId); +private: + void StartDisplayingMenuBarL(); + void HideMenuPane(); + void SaveCurrentMenuPositionL(); + void SetCursorPositionFromArray(); + TBool MenuHasItems() const; + void SetMenuHasItems(); + TBool MenuHasPane() const; + void SetMenuHasPane(); + TBool TitleArrayOwnedExternally() const; + void ResetTitleArray(); + void CreateTitleArrayL(); + void SetMenuPaneFlag(TInt aFlag); + void AddFEPMenuL(); + void AddMenuIfNotPresentL(TInt aResourceId); + void UpdateTitleTextBaseline(); +private: + enum TEikMenuFlags {ETitleArrayOwnedExternally=0x01,EMenuHasItems=0x02,EMenuHasPane=0x04,EBackgroundFaded=0x08, ESoundsInstalled=0x10}; + CEikButtonGroupContainer* iMenuCba; + MEikMenuObserver* iMenuObserver; + MEikMenuObserver* iEditMenuObserver; + MEikMenuObserver* iActiveEditMenuObserver; + CEikMenuPane* iMenuPane; + CEikHotKeyTable* iHotKeyTable; + SCursor iCursor; + TInt iMenuTitleResourceId; + TInt iMenuPaneResourceId; + TInt iMenuHotKeyResourceId; + TInt iSelectedTitle; + TInt iBaseLine; + TInt iMenuTitleLeftSpace; + TInt iMenuFlags; + CTitleArray* iTitleArray; + CArrayFixFlat* iPastMenuPosArray; + TBool iPreventFepMenu; + friend class CEikMenuBarExtension; + CEikMenuBarExtension* iExt; + }; + + /** + * This class is not intended to be used by application programmers. + */ +class CEikMenuPaneTitle : public CEikBorderedControl + { + +public: + + /** + * Default C++ constructor + */ + IMPORT_C CEikMenuPaneTitle(CEikMenuBar* aMenuBar); + + /** + * Second phase constructor for a menu bar. By default Symbian 2nd phase + * constructor is private. + */ + IMPORT_C void ConstructL(); + + /** + * Not implemented + * + * @param aSelectedTitle Not used. + */ + IMPORT_C void SetSelectedTitle(TInt aSelectedTitle); + + /** + * Not implemented + * + * @param aRect Not used. + */ + IMPORT_C void Draw(const TRect& aRect) const; + + /** + * Gets the menu pane title’s margins. + * + * @return The menu pane title’s margins. + */ + IMPORT_C TMargins Margins() const; + + /** + * Not implemented + */ + IMPORT_C void Close(); + +public:// framework + + /** + * Not implemented. + * + * @param aPointerEvent Not used. + */ + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent); + + /** + * From @c CCoeControl. + * + * Gets the list of logical colours used to draw the control. + * + * The list includes an explanation of how each colour is used. By default, + * this function has an empty implementation. + * + * Since 5.1 SDK. + * + * @param aColorUseList The colour list. + */ + IMPORT_C virtual void GetColorUseListL(CArrayFix& aColorUseList) const; // not available before Release 005u + + /** + * Not implemented + * + * @param aType Not used. + */ + IMPORT_C virtual void HandleResourceChange(TInt aType); // not available before Release 005u + +private: + /** + * From CAknControl + */ + IMPORT_C void* ExtensionInterface( TUid aInterface ); +private: + CEikMenuBar* const iMenuBar; + TInt iSelectedTitle; + }; + +#endif