williamr@2: /*
williamr@2: * Copyright (c) 1997-1999 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #if !defined(__EIKMENUP_H__)
williamr@2: #define __EIKMENUP_H__
williamr@2: 
williamr@2: #if !defined(__EIKBCTRL_H__)
williamr@2: #include <eikbctrl.h>
williamr@2: #endif
williamr@2: 
williamr@2: #if !defined(__EIKDEF_H__)
williamr@2: #include <eikdef.h>
williamr@2: #endif
williamr@2: 
williamr@2: #if !defined(__EIKSBOBS_H__)
williamr@2: #include <eiksbobs.h> // for TEikScrollEvent
williamr@2: #endif
williamr@2: 
williamr@2: #include <bidi.h>
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: class MEikMenuObserver;
williamr@2: class CEikHotKeyTable;
williamr@2: class CEikMenuPaneTitle;
williamr@2: class CEikButtonBase;
williamr@2: class CEikScrollBarFrame;
williamr@2: class CEikScrollBar;
williamr@2: class TEikScrollBarModel;
williamr@2: class CGulIcon;
williamr@2: class CEikMenuPaneExtension ;
williamr@2: 
williamr@2: // CONSTANTS
williamr@2: const TInt KScaleableTextSeparator = 0x0001;
williamr@2: 
williamr@2: /**
williamr@2:   * A helper class for extending CEikMenuPaneItem without breaking binary 
williamr@2:   * compability.
williamr@2:   */
williamr@2: class CExtendedItemData : public CBase
williamr@2:     {
williamr@2:     
williamr@2: public:
williamr@2:     
williamr@2:     /**
williamr@2:      * Destructor.
williamr@2:      */
williamr@2:     ~CExtendedItemData();
williamr@2:     
williamr@2: public:
williamr@2:     
williamr@2:     /** Two packaked bitmaps: bitmap icon and mask for it. */
williamr@2:     CGulIcon* iIcon;
williamr@2:     
williamr@2:     /** Scalable text buffer. */
williamr@2:     HBufC* iScaleableText;    
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  * The @c CEikMenuPaneItem class encapsulates the data needed to define a menu
williamr@2:  * pane item and provides some of the functionality required to display the 
williamr@2:  * item.
williamr@2:  *
williamr@2:  * @since ER5U
williamr@2:  */
williamr@2: class CEikMenuPaneItem : public CBase
williamr@2:     {
williamr@2:     
williamr@2: public:
williamr@2:     
williamr@2:     /** Struct to menu pane item. */
williamr@2:     struct SData
williamr@2:         {
williamr@2:         
williamr@2:         /** Nominal text length.*/
williamr@2:         enum { ENominalTextLength=40 };
williamr@2:         
williamr@2:         /** 
williamr@2:          * ID of the command to issue when the menu item using this @c SData is 
williamr@2:          * selected.
williamr@2:          */
williamr@2:         TInt iCommandId;
williamr@2:         
williamr@2:         /** Resource ID of a menu pane to cascade from this item. */
williamr@2:         TInt iCascadeId;
williamr@2:         
williamr@2:         /** 
williamr@2:          * Flags used internally by @c CEikMenuPane and accessible through 
williamr@2:          * functions such as @c CEikMenuPane::SetItemDimmed().
williamr@2:          */
williamr@2:         TInt iFlags;
williamr@2:         
williamr@2:         /** The text buffer displayed in the main area of the menu item. */
williamr@2:         TBuf<ENominalTextLength> iText; // less than this actually stored
williamr@2:         
williamr@2:         /** 
williamr@2:          * Additional descriptive text about the item. This is used by @c 
williamr@2:          * CEikMenuPane to display hotkey names.
williamr@2:          */
williamr@2:         TBuf<1> iExtraText;
williamr@2:         };
williamr@2:         
williamr@2: public:
williamr@2: 
williamr@2:     /**
williamr@2:      * C++ default constructor.
williamr@2:      */
williamr@2:     IMPORT_C CEikMenuPaneItem();
williamr@2:     
williamr@2:     /**
williamr@2:      * Destructor.
williamr@2:      */
williamr@2:     IMPORT_C ~CEikMenuPaneItem();
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets a menu item icon. This replaces any icon already set for the menu
williamr@2:      * item.
williamr@2:      *
williamr@2:      * @param aIcon Menu item icon consisting of a picture bitmap and a mask 
williamr@2:      *        bitmap.
williamr@2:      */
williamr@2:     IMPORT_C void SetIcon(CGulIcon* aIcon);
williamr@2:     
williamr@2:     /**
williamr@2:      * Draws the menu item icon.
williamr@2:      * 
williamr@2:      * @param aGc Graphics context to which the icon is drawn.
williamr@2:      * @param aRect Rectangle in which the icon is drawn. 
williamr@2:      * @param aDimmed If @c ETrue the icon is drawn dimmed. 
williamr@2:      * @param aBitmapSpaceRequired Length of one side of the square required to 
williamr@2:      *        contain the bitmap.
williamr@2:      */
williamr@2:     IMPORT_C void DrawItemIcon(CWindowGc& aGc, 
williamr@2:                                TRect aRect, 
williamr@2:                                TBool aDimmed, 
williamr@2:                                TInt aBitmapSpaceRequired) const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Construct an icon from bitmaps. 
williamr@2:      * 
williamr@2:      * Constructs a new icon for the menu item, taking ownership of the picture
williamr@2:      * bitmap aBitmap and the mask bitmap aMask unless the bitmaps are 
williamr@2:      * externally owned.
williamr@2:      * 
williamr@2:      * @param aBitmap Picture bitmap.
williamr@2:      * @param aMask Mask bitmap.
williamr@2:      */
williamr@2:     IMPORT_C void CreateIconL(CFbsBitmap* aBitmap, 
williamr@2:                               CFbsBitmap* aMask);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets a pointer to the menu item's icon picture bitmap. This does not 
williamr@2:      * imply transfer of ownership.
williamr@2:      * 
williamr@2:      * @return Picture bitmap.
williamr@2:      */
williamr@2:     IMPORT_C CFbsBitmap* IconBitmap() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets a pointer to the menu item's icon mask bitmap. This does not imply
williamr@2:      * transfer of ownership.
williamr@2:      * 
williamr@2:      * @return Mask bitmap.
williamr@2:      */
williamr@2:     IMPORT_C CFbsBitmap* IconMask() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets icon bitmap ownership.
williamr@2:      * Sets the menu item's icon bitmaps as externally owned if @c 
williamr@2:      * aOwnedExternally is @c ETrue.
williamr@2:      * 
williamr@2:      * @param aOwnedExternally If @c ETrue bitmaps are set as externally owned. 
williamr@2:      *        @c If EFalse bitmaps are set as not being externally owned. 
williamr@2:      */
williamr@2:     IMPORT_C void SetBitmapsOwnedExternally(TBool aOwnedExternally);
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the picture bitmap. Transfers ownership unless the bitmaps are 
williamr@2:      * already owned externally.
williamr@2:      * 
williamr@2:      * @param aBitmap Picture bitmap.
williamr@2:      */
williamr@2:     IMPORT_C void SetIconBitmapL(CFbsBitmap* aBitmap);
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the mask bitmap. Transfers ownership unless the bitmaps are already
williamr@2:      * owned externally.
williamr@2:      * 
williamr@2:      * @param aMask Mask bitmap.
williamr@2:      */
williamr@2:     IMPORT_C void SetIconMaskL(CFbsBitmap* aMask);
williamr@2:     
williamr@2:     /**
williamr@2:      * Returns scaleable text. If there isn't scaleable text available then
williamr@2:      * this method returns @c iData.iText.
williamr@2:      * 
williamr@2:      * @return Pointer to TPtrC object that contains scaleable text.
williamr@2:      */
williamr@2:     IMPORT_C TPtrC ScaleableText() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets scaleable text. @c iData.iText is set to first text version.
williamr@2:      * 
williamr@2:      * @param aText Scalable text.
williamr@2:      */
williamr@2:     IMPORT_C void SetScaleableTextL(const TDesC& aText);
williamr@2: 
williamr@2: private:
williamr@2:     inline void CreateExtendedDataBlock();
williamr@2:     inline TBool IsScaleableText(const TDesC& aText) const;
williamr@2:     TPtrC GetNominalText(const TDesC& aText);
williamr@2: 
williamr@2: public:
williamr@2: 
williamr@2:     /** The y position of the menu pane item. */
williamr@2:     TInt iPos;
williamr@2:     
williamr@2:     /** The menu pane item's hotkey text. */
williamr@2:     TInt iHotKeyCode;
williamr@2:     
williamr@2:     /** Information from an SData struct. */
williamr@2:     SData  iData;
williamr@2: 
williamr@2: private:
williamr@2:     CExtendedItemData* iExtendedData;
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: inline void CEikMenuPaneItem::CreateExtendedDataBlock()
williamr@2:     {
williamr@2:     if (!iExtendedData)
williamr@2:         {
williamr@2:         TRAPD(err, ( iExtendedData = new (ELeave) CExtendedItemData() ) );
williamr@2:         }
williamr@2:     }
williamr@2: 
williamr@2: 
williamr@2: inline TBool CEikMenuPaneItem::IsScaleableText(const TDesC& aText) const
williamr@2:     {
williamr@2:     return (aText.Locate(TChar(KScaleableTextSeparator)) == KErrNotFound ? EFalse : ETrue);
williamr@2:     }
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2:  * Menu panes are opened by activating the menu title 
williamr@2:  * @c (CEikMenuPaneTitle / MENU_TITLE) which is displayed in the menu bar @c 
williamr@2:  * (CEikMenuBar / MENU_BAR). They can also be cascaded from a menu item @c
williamr@2:  * (CEikMenuPaneItem / MENU_ITEM) or launched by a menu button @c 
williamr@2:  * (CEikMenuButton). 
williamr@2:  *
williamr@2:  * Menu panes may be defined using a @c MENU_PANE resource.
williamr@2:  */
williamr@2: class CEikMenuPane : public CEikBorderedControl
williamr@2:     {
williamr@2: private:
williamr@2:     enum {ENothingSelected=-1};
williamr@2:     class CMenuScroller;
williamr@2:     friend class CMenuScroller;
williamr@2:     friend class CEikMenuPaneExtension;
williamr@2: public:
williamr@2:     
williamr@2:     /** The text to be displayed for a hotkey. */
williamr@2:     typedef TBuf<20> THotKeyDisplayText;
williamr@2:     
williamr@2: public:
williamr@2: 
williamr@2:     /**
williamr@2:      * This class provides a constructor to create an array of menu pane items
williamr@2:      * and a destructor to destroy an array of menu pane items.
williamr@2:      */
williamr@2:     class CItemArray:public CArrayPtrFlat<CEikMenuPaneItem>
williamr@2:         {
williamr@2:         
williamr@2:     public:
williamr@2:         
williamr@2:         /**
williamr@2:          * C++ default constructor that creates a flat array of menu pane 
williamr@2:          * items.
williamr@2:          */
williamr@2:         IMPORT_C CItemArray();
williamr@2:         
williamr@2:         /**
williamr@2:          * Destructor.
williamr@2:          */
williamr@2:         IMPORT_C ~CItemArray();
williamr@2:         
williamr@2:         /**
williamr@2:          * Appends @c CEikMenuPaneItem class object to array.
williamr@2:          *
williamr@2:          * @param aMenuItem The menu item to add.
williamr@2:          */        
williamr@2:         IMPORT_C void AddItemL(CEikMenuPaneItem* aMenuItem);
williamr@2:         };
williamr@2: 
williamr@2: public:
williamr@2: 
williamr@2:     /**
williamr@2:      * Destructor.
williamr@2:      */
williamr@2:     IMPORT_C ~CEikMenuPane();
williamr@2:     
williamr@2:     /**
williamr@2:      * C++ default constructor. Constructs a menu pane object with the 
williamr@2:      * specified observer.
williamr@2:      * 
williamr@2:      * @param aMenuObserver Menu observer.
williamr@2:      */
williamr@2:     IMPORT_C CEikMenuPane(MEikMenuObserver* aMenuObserver);
williamr@2: 
williamr@2:     /**
williamr@2:      * Handles 2nd base construction. Completes construction of a menu pane object. 
williamr@2:      * 
williamr@2:      * @param aOwner Menu pane owner ( for cascade menu ).
williamr@2:      * @param aEditMenuObserver Observer for the edit menu. In default this is 
williamr@2:      *        @c NULL.
williamr@2:      */
williamr@2:     IMPORT_C void ConstructL(CEikMenuPane* aOwner, 
williamr@2:                              MEikMenuObserver* aEditMenuObserver = NULL);
williamr@2:     
williamr@2:     /**
williamr@2:      * Destroys the menu pane's item array.
williamr@2:      */
williamr@2:     IMPORT_C void Reset();
williamr@2:     
williamr@2: public: // framework
williamr@2: 
williamr@2:     /**
williamr@2:      * From @c CcoeControl.
williamr@2:      *
williamr@2:      * Handles key events offered to the menu by the control environment and 
williamr@2:      * provides an appropriate implementation of @c 
williamr@2:      * CCoeControl::OfferKeyEventL(). 
williamr@2:      * 
williamr@2:      * @param aKeyEvent The key event. 
williamr@2:      * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or @c 
williamr@2:      *        EEventKeyDown.
williamr@2:      */
williamr@2:     IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
williamr@2:                                          TEventCode aType);
williamr@2:     
williamr@2:     /**
williamr@2:      * From @c CcoeControl.
williamr@2:      *
williamr@2:      * Handles a pointer event on the menu.
williamr@2:      * 
williamr@2:      * @param aPointerEvent The pointer event to handle.
williamr@2:      */
williamr@2:     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
williamr@2:     
williamr@2:     /**
williamr@2:      * From @c CcoeControl.
williamr@2:      *
williamr@2:      * Gets the list of logical colours employed in the drawing of the control, 
williamr@2:      * paired with an explanation of how they are used. Appends the list into 
williamr@2:      * @c aColorUseList.
williamr@2:      * 
williamr@2:      * @since 005u
williamr@2:      * @param aColorUseList The list of colours paired with explanations.
williamr@2:      */
williamr@2:     IMPORT_C virtual void GetColorUseListL(
williamr@2:         CArrayFix<TCoeColorUse>& aColorUseList) const; 
williamr@2:     
williamr@2:     /**
williamr@2:      * From @c CcoeControl.
williamr@2:      *
williamr@2:      * Handles a change to the menu's resources which are shared across the
williamr@2:      * environment. For example, colours or fonts.
williamr@2:      * 
williamr@2:      * @since 005u
williamr@2:      * @param aType The type of resource that has changed.
williamr@2:      */
williamr@2:     IMPORT_C virtual void HandleResourceChange(TInt aType);         // not available before Release 005u
williamr@2: 
williamr@2: private: // from base class
williamr@2: 
williamr@2:     /**
williamr@2:      * Not implemented.
williamr@2:      * 
williamr@2:      * @param Not used.
williamr@2:      * @return NULL
williamr@2:      */
williamr@2:     IMPORT_C void* ExtensionInterface( TUid aInterface );
williamr@2:     
williamr@2: public: // from MCoeInputObserver
williamr@2:     
williamr@2:     /**
williamr@2:      * From @c CCoeControl.
williamr@2:      *
williamr@2:      * Gets the list box’s input capabilities as set through the list box flags.
williamr@2:      *
williamr@2:      * @return List box input capabilities.
williamr@2:      */
williamr@2:     IMPORT_C TCoeInputCapabilities InputCapabilities() const;
williamr@2:     
williamr@2: protected: // from base class
williamr@2:     
williamr@2:     /** 
williamr@2:      * From @c CCoeControl
williamr@2:      * 
williamr@2:      * Draw a control called by window server. 
williamr@2:      *
williamr@2:      * All controls, except blank controls, should implement this function. The
williamr@2:      * default implementation draws a blank control. This function is used for
williamr@2:      * window server-initiated redrawing of controls, and for some 
williamr@2:      * application-initiated drawing. It should be implemented by each control,
williamr@2:      * but  is only called from within @c CCoeControl's member functions, and 
williamr@2:      * not from the derived class. For this reason it is a private member 
williamr@2:      * function of @c CCoeControl.
williamr@2:      *
williamr@2:      * The rectangle aRect indicates the region of the control that needs to be
williamr@2:      * redrawn. The implementation of @c Draw() must always draw to every pixel 
williamr@2:      * within this rectangle.
williamr@2:      *
williamr@2:      * @param aRect The region of the control to be redrawn. 
williamr@2:      *        Co-ordinates are relative to the control's origin (top left 
williamr@2:      *        corner). Optional, not used currently.
williamr@2:      */
williamr@2:     IMPORT_C void Draw(const TRect& aRect) const;
williamr@2:     
williamr@2:     /**
williamr@2:      * From @c CCoeControl.
williamr@2:      *
williamr@2:      * Takes any action required when the menu pane gains or loses focus, 
williamr@2:      * to change its appearance for example.
williamr@2:      * 
williamr@2:      * @param aDrawNow If @c EDrawNow the menu pane is redrawn. If @c 
williamr@2:      *        ENoDrawNow the menu pane is not redrawn.
williamr@2:      */
williamr@2:     IMPORT_C void FocusChanged(TDrawNow aDrawNow);
williamr@2:     
williamr@2:     /**
williamr@2:      * From @c CCoeControl.
williamr@2:      *
williamr@2:      * Constructs the menu pane using the specified resource reader.
williamr@2:      * Fills the menu item array with the list of menu items provided by the
williamr@2:      * resource file.
williamr@2:      * 
williamr@2:      * @param aReader The resource reader to use.
williamr@2:      * @leave KErrNoMemory Memory allocation failure earlier construction.     
williamr@2:      */
williamr@2:     IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);
williamr@2:     
williamr@2: public: // new functions
williamr@2: 
williamr@2:     /**
williamr@2:      * Adds a menu item dynamically by creating a new menu item, setting its 
williamr@2:      * data to @c aMenuItem and appending it to the pane's menu item array. 
williamr@2:      * Updates the menu's scroll bar to take account of the new item.
williamr@2:      * 
williamr@2:      * @param aMenuItem The menu item to add.
williamr@2:      *        NOTICE that @c SData is a structure so all fields in it should be
williamr@2:      *        set to avoid any unexpected behaviour.
williamr@2:      */
williamr@2:     IMPORT_C void AddMenuItemL(const CEikMenuPaneItem::SData& aMenuItem);
williamr@2:     
williamr@2:     /**
williamr@2:      * Adds a menu item dynamically by creating a new menu item, setting its 
williamr@2:      * data to @c aMenuItem and inserting it into the pane's menu item array. 
williamr@2:      * Updates the menu's scroll bar to take account of the new item.
williamr@2:      * 
williamr@2:      * @param aMenuItem The menu item to add. NOTICE that @c SData is a 
williamr@2:      *        structure so all fields in it should be set to avoid any 
williamr@2:      *        unexpected behaviour.
williamr@2:      * @param aPreviousId The id of the item after which the new item should be
williamr@2:      *        added.
williamr@2:      */
williamr@2:     IMPORT_C void AddMenuItemL(const CEikMenuPaneItem::SData& aMenuItem, 
williamr@2:                                TInt aPreviousId);
williamr@2:     
williamr@2:     /**
williamr@2:      * Adds menu items dynamically by creating new menu items from resource 
williamr@2:      * and inserts them into the pane's menu item array. 
williamr@2:      * 
williamr@2:      * @param aResourceId The ID of the resource for the menu item.
williamr@2:      * @param aPreviousId The ID of the previous menu item, after which this 
williamr@2:      *        newly created item should be added.
williamr@2:      * @param aAddSeperator Shouldn't be used as separator is not not supported
williamr@2:      *        anymore.
williamr@2:      */
williamr@2:     IMPORT_C void AddMenuItemsL(TInt aResourceId, 
williamr@2:                                 TInt aPreviousId = 0,
williamr@2:                                 TBool aAddSeperator = EFalse);
williamr@2:     
williamr@2:     /**
williamr@2:      * Deletes the specified item in the menu pane.
williamr@2:      * 
williamr@2:      * @param aCommandId The ID for the item to be deleted.
williamr@2:      */
williamr@2:     IMPORT_C void DeleteMenuItem(TInt aCommandId);
williamr@2:     
williamr@2:     /**
williamr@2:      * Deletes the items between specified items.
williamr@2:      * 
williamr@2:      * @param aStartIndex The index of the item after which items should be 
williamr@2:      *        deleted.
williamr@2:      * @param aEndIndex The index of the item up to which items should be 
williamr@2:      *        deleted.
williamr@2:      */
williamr@2:     IMPORT_C void DeleteBetweenMenuItems(TInt aStartIndex, 
williamr@2:                                          TInt aEndIndex);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets a reference to the data in the specified menu item.
williamr@2:      * 
williamr@2:      * @param aCommandId The command ID of the menu item for which data is 
williamr@2:      *        obtained.
williamr@2:      * @return Reference to struct that contains command id.
williamr@2:      */
williamr@2:     IMPORT_C CEikMenuPaneItem::SData& ItemData(TInt aCommandId);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets a pointer to the specified menu item. Also gets the position of the
williamr@2:      * item within the menu pane. Panics if there are no menu items in the menu
williamr@2:      * pane. Panics if the menu pane id does not identify any menu pane item in
williamr@2:      * the array.
williamr@2:      * 
williamr@2:      * @param aCommandId The ID of the menu item for which a pointer is 
williamr@2:      *        returned. 
williamr@2:      * @param aPos On return, the position of the menu item with an ID of 
williamr@2:      *        aCommandId.
williamr@2:      * @return A pointer to the menu item.
williamr@2:      * @panic EEikPanicNoSuchMenuItem Panics if there are no menu items in the
williamr@2:      *                                menu pane or if the menu pane id does not
williamr@2:      *                                identify any menu pane item in the array.
williamr@2:      */
williamr@2:     IMPORT_C CEikMenuPaneItem* ItemAndPos(TInt aCommandId,TInt& aPos);
williamr@2:     
williamr@2:     /**
williamr@2:      * Displays the menu pane with the corner identified by @c aTargetType in 
williamr@2:      * the position specified by @c aTargetPos. This function uses @c 
williamr@2:      * aMinTitleWidth to calculate the area required to display the menu pane,
williamr@2:      * taking into account whether the menu is a cascading menu or popup menu.
williamr@2:      * 
williamr@2:      * @param aHotKeyTable Optional hotkey table. 
williamr@2:      * @param aTargetPos Position of the corner of the menu pane identified by 
williamr@2:      *        @c aTargetType. 
williamr@2:      * @param aMenuPaneTitle The menu pane's title.
williamr@2:      * @param aMinWidth Minimum width of the menu's title.
williamr@2:      * @param aTargetType The corner of the menu pane to which @c aTargetPos 
williamr@2:      *        relates. The default is the top left corner. Possible: @c 
williamr@2:      *        EPopupTargetTopLeft, @c EPopupTargetTopRight, 
williamr@2:      *        @cEPopupTargetBottomLeft, @c EPopupTargetBottomRight.
williamr@2:      */
williamr@2:     IMPORT_C void StartDisplayingMenuPane(
williamr@2:             const CEikHotKeyTable* aHotKeyTable,                               
williamr@2:             const TPoint& aTargetPos, 
williamr@2:             const CEikMenuPaneTitle* aMenuPaneTitle,
williamr@2:             TInt aMinWidth,  
williamr@2:             TPopupTargetPosType aTargetType = EPopupTargetTopLeft);
williamr@2:             
williamr@2:     /**
williamr@2:      * Sets the text in a menu item.
williamr@2:      * 
williamr@2:      * @param aCommandId The command (as defined in an .hrh file) associated
williamr@2:      *        with this menu item. This identifies the menu item whose text is
williamr@2:      *        to be set. 
williamr@2:      * @param aDes New item text.
williamr@2:      */                                      
williamr@2:     IMPORT_C void SetItemTextL(TInt aCommandId,
williamr@2:                                const TDesC& aDes);
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the text in a menu item from resource.
williamr@2:      *
williamr@2:      * @param aCommandId The command (as defined in an .hrh file) associated 
williamr@2:      *        with this menu item. This identifies the menu item whose text is
williamr@2:      *        to be set. 
williamr@2:      * @param aRid The resource ID of the menu item text. 
williamr@2:      */
williamr@2:     IMPORT_C void SetItemTextL(TInt aCommandId,
williamr@2:                                TInt aRid);
williamr@2:                                
williamr@2:     /**
williamr@2:      * Dims (greys out) or undims a menu item. Dimming indicates that user 
williamr@2:      * input is not accepted.
williamr@2:      * 
williamr@2:      * @param aCommandId The command (as defined in an .hrh file) associated
williamr@2:      *        with this menu item. This identifies the menu item whose text is
williamr@2:      *        to be dimmed or un-dimmed. 
williamr@2:      * @param aDimmed @c ETrue to dim this menu item. @c EFalse to un-dim this
williamr@2:      *        menu item.
williamr@2:      */
williamr@2:     IMPORT_C void SetItemDimmed(TInt aCommandId,
williamr@2:                                 TBool aDimmed);
williamr@2:                                 
williamr@2:     /**
williamr@2:      * Sets the item to be indicated or not. It should be used to change the
williamr@2:      * state of radio buttons or check box items. It has real effect only 
williamr@2:      * starting from S60 v3.0.
williamr@2:      * 
williamr@2:      * @param aCommandId The command (as defined in an .hrh file) associated 
williamr@2:      *        with this menu item. This identifies the menu item for which the 
williamr@2:      *        state is set or unset. 
williamr@2:      * @param aButtonState should be @c EEikMenuItemSymbolOn or @c
williamr@2:      *        EEikMenuItemSymbolIndeterminate
williamr@2:      */                           
williamr@2:     IMPORT_C void SetItemButtonState(TInt aCommandId,
williamr@2:                                      TInt aButtonState);
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the selected menu item.
williamr@2:      * 
williamr@2:      * @param aSelectedItem The index of the item to get selected
williamr@2:      */                                
williamr@2:     IMPORT_C void SetSelectedItem(TInt aSelectedItem);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets the position of the selected menu item.
williamr@2:      * 
williamr@2:      * @return The position of the selected menu item.
williamr@2:      */
williamr@2:     IMPORT_C TInt SelectedItem() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Closes and destroys any current cascade menu and takes focus back. Does
williamr@2:      * nothing if no cascade menu exists.
williamr@2:      */
williamr@2:     IMPORT_C void CloseCascadeMenu();
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the array containing the list of menu items for the current menu 
williamr@2:      * pane.
williamr@2:      * 
williamr@2:      * @param aItemArray The menu item array for the menu pane.
williamr@2:      */
williamr@2:     IMPORT_C void SetItemArray(CItemArray* aItemArray);
williamr@2:     
williamr@2:     /**
williamr@2:      * Set menu item array ownership.
williamr@2:      * 
williamr@2:      * @param aOwnedExternally If @c ETrue the menu pane's menu item array is 
williamr@2:      *        set as externally owned. If @c EFalse the menu pane's menu item 
williamr@2:      *        array is set as not externally owned.
williamr@2:      */
williamr@2:     IMPORT_C void SetItemArrayOwnedExternally(TBool aOwnedExternally);
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets the specified button to launch the menu pane. Doesn't have any 
williamr@2:      * effect in current implementation.
williamr@2:      * 
williamr@2:      * @param aButton The button to set as launching the menu.
williamr@2:      */
williamr@2:     IMPORT_C void SetLaunchingButton(CEikButtonBase* aButton);
williamr@2:     
williamr@2:     /**
williamr@2:      * Moves the menu pane highlight to a newly selected menu item identified
williamr@2:      * by @c aNewSelectedItem. Scrolls the menu to show the new selected item
williamr@2:      * if necessary and redraws only the newly selected item and the currently
williamr@2:      * selected item if possible.
williamr@2:      * 
williamr@2:      * @param aNewSelectedItem The newly selected menu item index.
williamr@2:      */
williamr@2:     IMPORT_C void MoveHighlightTo(TInt aNewSelectedItem);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets the number of menu items within the menu pane.
williamr@2:      *
williamr@2:      * @return Number of menu items within menu pane.
williamr@2:      */
williamr@2:     IMPORT_C TInt NumberOfItemsInPane() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Closes the menu pane.
williamr@2:      */
williamr@2:     IMPORT_C void Close();
williamr@2:     
williamr@2:     /**
williamr@2:      * From @ CCoeControl
williamr@2:      *
williamr@2:      * Handles key events offered to the menu by the control environment.
williamr@2:      * 
williamr@2:      * @since Platform 004.
williamr@2:      * @param aKeyEvent The key event.
williamr@2:      * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or @c
williamr@2:      *        EEventKeyDown. 
williamr@2:      * @param aConsumeAllKeys If @c ETrue this function returns @c 
williamr@2:      *        EKeyWasConsumed regardless of whether it was used. If @c EFalse
williamr@2:      *        the key event is consumed if possible and either @c 
williamr@2:      *        EKeyWasConsumed or @c EKeyWasNotConsumed is returned as 
williamr@2:      *        appropriate.
williamr@2:      */
williamr@2:     IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
williamr@2:                                          TEventCode aType,
williamr@2:                                          TBool aConsumeAllKeys); // not available before Platform 004
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets whether the scroll bar occupies the left side of the menu pane.
williamr@2:      * 
williamr@2:      * @param aOnLeft If @c ETrue the scroll bar will occupy the left side of
williamr@2:      *        the menu pane.
williamr@2:      */                                     
williamr@2:     IMPORT_C void SetScrollBarOnLeft(TBool aOnLeft);
williamr@2:     
williamr@2:     /**
williamr@2:      * Sets whether the menu pane uses an arrow head scroll bar.
williamr@2:      * 
williamr@2:      * @param aArrowHead If @c ETrue the menu pane uses an arrow head scroll 
williamr@2:      *        bar.
williamr@2:      */
williamr@2:     IMPORT_C void SetArrowHeadScrollBar(TBool aArrowHead);
williamr@2:     
williamr@2: // new for AVKON
williamr@2:     
williamr@2:     /**
williamr@2:      * Moves highlight to the next item or to the first one if last item is 
williamr@2:      * selected. 
williamr@2:      */
williamr@2:     IMPORT_C void NavigateToNextItem();
williamr@2:     
williamr@2:     /**
williamr@2:      * Inserts the menu item to the specified position.
williamr@2:      * 
williamr@2:      * @param aMenuItem The menu item to add. NOTICE @c SData is the structure
williamr@2:      *        and all fileds should be initialized.
williamr@2:      * @param aPosition The position of newly created item in the array.
williamr@2:      */
williamr@2:     IMPORT_C void InsertMenuItemL(const CEikMenuPaneItem::SData& aMenuItem, 
williamr@2:                                   TInt aPosition);
williamr@2:     
williamr@2:     /**
williamr@2:      * Checks whether menu pane contains the menu item and returns position of
williamr@2:      * it if the item is found.
williamr@2:      * 
williamr@2:      * @param[in] aCommandId The command ID of the item to be searched for.
williamr@2:      * @param[out] aPosition On return contains position of the item.
williamr@2:      * @return @c ETrue if item was found. Otherwise @c EFalse.
williamr@2:      */
williamr@2:     IMPORT_C TBool MenuItemExists(TInt aCommandId, 
williamr@2:                                   TInt& aPosition);
williamr@2:     
williamr@2:     /**
williamr@2:      * Checks whether the menu pane is a cascade menu or a main menu. 
williamr@2:      *
williamr@2:      * @return @c ETrue if the menu pane is cascade menu and @c EFalse if the
williamr@2:      *         menu pane is the main menu.
williamr@2:      */
williamr@2:     IMPORT_C TBool IsCascadeMenuPane() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Enables or disables text scrolling functionality. It is disabled by 
williamr@2:      * default.
williamr@2:      * 
williamr@2:      * @param aEnable @c ETrue to enable text scrolling functionality.
williamr@2:      */
williamr@2:     IMPORT_C void EnableMarqueeL(const TBool aEnable); 
williamr@2: 
williamr@2:     /**
williamr@2:      * Report that selection was done for the currently highlighted item.
williamr@2:      */
williamr@2:     void ActivateCurrentItemL();
williamr@2:     
williamr@2:     /**
williamr@2:      * Closes cascade menu if there is one and it is active.
williamr@2:      */
williamr@2:     TBool CancelActiveMenuPane();
williamr@2:     
williamr@2:     /**
williamr@2:      * Deletes dimmed items from the menu item array.
williamr@2:      */
williamr@2:     void FilterDimmedItems();
williamr@2:     
williamr@2:     /**
williamr@2:      * Not implemented.
williamr@2:      *
williamr@2:      * @param aWidth Not used.
williamr@2:      */
williamr@2:     void ClipMenuItems(TInt aWidth);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets the menu pane for the cascade menu.
williamr@2:      *
williamr@2:      * @return The menu pane for the cascade menu.
williamr@2:      */
williamr@2:     IMPORT_C CEikMenuPane* CascadeMenuPane();
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets a reference to the data in the specified menu item.
williamr@2:      * 
williamr@2:      * @since S60 3.1
williamr@2:      * @param aItemIndex The index of the item in the items array.
williamr@2:      * @return The menu item's data.
williamr@2:      * @leave  KErrArgument Wrong @aItemIndex.
williamr@2:      */
williamr@2:     IMPORT_C CEikMenuPaneItem::SData& ItemDataByIndexL(TInt aItemIndex);
williamr@2:     
williamr@2:     /**
williamr@2:      * Checks if the position of the menu was set from outside.
williamr@2:      *
williamr@2:      * @since S60 3.1
williamr@2:      * @return @c ETrue in case when position of the menu was set from outside.
williamr@2:      */
williamr@2:     TBool IsPositionToBeForced() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * Creates and enables a special characters row to be used in the edit 
williamr@2:      * menu.
williamr@2:      *
williamr@2:      * @since S60 3.1 
williamr@2:      * @param aSpecialChars Buffer that holds the selected characters after 
williamr@2:      *                      user has selected them.
williamr@2:      */
williamr@2:     IMPORT_C void ConstructMenuSctRowL( TDes& aSpecialChars );
williamr@2: 
williamr@2:     /**
williamr@2:      * Returns the command id of the specified menu item. The function panics
williamr@2:      * if aIndex doesn't exist or is out of range.
williamr@2:      * @param aIndex The index of the menu item for which the command ID is returned.
williamr@2:      * @since 3.1
williamr@2:      */
williamr@2:     IMPORT_C TInt MenuItemCommandId( TInt aIndex ) const;
williamr@2: 
williamr@2:     
williamr@2:     /**
williamr@2:      * Creates and enables a special characters row to be used in the edit menu.
williamr@2:      * The special character row is constructed from the given special character table.
williamr@2:      *
williamr@2:      * @param aSpecialChars Buffer that holds the selected characters after 
williamr@2:      * user has selected them.
williamr@2:      * @param aResourceId The special character table resource id to define the 
williamr@2:      * characters in the row.
williamr@2:      *
williamr@2:      * @since S60 3.1
williamr@2:      */
williamr@2:     IMPORT_C void ConstructMenuSctRowL( TDes& aSpecialChars, TInt aResourceId );
williamr@2: 
williamr@2:     /**
williamr@2:      * Creates and enables a special characters row to be used in the edit menu.
williamr@2:      * The special character row is constructed from the given special character dialog.
williamr@2:      *
williamr@2:      * @param aSpecialChars Buffer that holds the selected characters after 
williamr@2:      * user has selected them.
williamr@2:      * @param aResourceId The special character dialog  resource id that contains a special character table
williamr@2:      *
williamr@2:      * @since S60 3.2
williamr@2:      */
williamr@2:     IMPORT_C void ConstructMenuSctRowFromDialogL( TDes& aSpecialChars, TInt aResourceId );
williamr@2: 
williamr@2:     /**
williamr@2:      * Creates and enables a special characters row to be used in the edit menu.
williamr@2:      * The special character row is constructed from the given special character dialog.
williamr@2:      *
williamr@2:      * @param aCharCase the charcase used by menu sct
williamr@2:      * @param aSpecialChars Buffer that holds the selected characters after
williamr@2:      * user has selected them.
williamr@2:      * @param aResourceId The special character dialog  resource id that contains a special character table
williamr@2:      *
williamr@2:      * @since S60 3.2
williamr@2:      */
williamr@2:     IMPORT_C void ConstructMenuSctRowFromDialogL( TInt aCharCase, TDes& aSpecialChars, TInt aResourceId );
williamr@2: 
williamr@2: private:
williamr@2:     enum { EInvalidCurrentSize=0x01, EBackgroundFaded=0x02 };
williamr@2:     
williamr@2: private: // new functions
williamr@2:     TRect CalculateSizeAndPosition() ;
williamr@2:     enum THighlightType {ENoHighlight,EDrawHighlight,ERemoveHighlight};
williamr@2:     void DrawItem(CWindowGc& aGc,TInt aItem, THighlightType aHighlight) const;
williamr@2:     void FindHotKeyDisplayText(TDes& aDes,const CEikMenuPaneItem& aItem) const;
williamr@2:     void ReportSelectionMadeL( TBool aAbortTransition = ETrue );
williamr@2:     void ReportCanceled();
williamr@2:     void GiveVisualFeedback();
williamr@2:     void LaunchCascadeMenuL(TInt aCascadeMenuId);
williamr@2:     void DoLaunchCascadeMenuL(TInt aCascadeMenuId);
williamr@2:     void TryLaunchCascadeMenuL(const CEikMenuPaneItem& aItem);
williamr@2:     void PrepareGcForDrawingItems(CGraphicsContext& aGc) const;
williamr@2:     TBool ItemArrayOwnedExternally() const;
williamr@2:     TBool IsHotKeyL(const TInt modifiers,const TInt aCode);
williamr@2:     TBool MoveToItemL(TInt aCode, TInt aModifiers);
williamr@2:     void HandleScrollEventL(CEikScrollBar* aScrollBar,TEikScrollEvent aEventType);
williamr@2:     void CreateScrollBarFrame();
williamr@2:     void UpdateScrollBar();
williamr@2:     void DoUpdateScrollBarL();
williamr@2:     void UpdateScrollBarThumbs();
williamr@2:     static TInt UpdateScrollBarCallBackL(TAny* aObj);
williamr@2:     TRect ViewRect() const;
williamr@2: //    TInt NumberOfItemsThatFitInView() const;
williamr@2:     TInt TotalItemHeight() const;
williamr@2:     void ScrollToMakeItemVisible(TInt aItemIndex);
williamr@2:     void Scroll(TInt aAmount);
williamr@2:     TBool CheckCreateScroller();
williamr@2:     void CheckCreateScrollerL();
williamr@2:     void ResetItemArray();
williamr@2:     void CreateItemArrayL();
williamr@2:     void SetVScrollBarFlag();
williamr@2:     TInt TopHighlightGap() const;
williamr@2:     TInt BottomHighlightGap() const;
williamr@2:     TInt EvaluateMaxIconWidth() const;
williamr@2:     void CreateIconFromResourceL(TResourceReader& aReader, CEikMenuPaneItem& aItem) const;
williamr@2:     // new for AVKON
williamr@2:     void AnimateMenuPane(const TPoint& aNewPos);
williamr@2: 
williamr@2:     // To make layout correct
williamr@2:     TRect ListMenuPane() const;
williamr@2:     TRect PopupMenuWindow() const;
williamr@2:     TRect PopupSubmenuWindow() const;
williamr@2: 
williamr@2:     // Skin support for menu
williamr@2:     void UpdateBackgroundContext(const TRect& aWindowRect);
williamr@2: 
williamr@2:     // Support method for highlight animation
williamr@2:     void RepaintHighlight() const;
williamr@2: 
williamr@2: private: // from CCoeControl
williamr@2:     IMPORT_C void Reserved_1();
williamr@2:     IMPORT_C void Reserved_2();
williamr@2: 
williamr@2: private : // new functions
williamr@2:     void LoadCascadeBitmapL() ;
williamr@2: 
williamr@2:     // Support for check mark, from v3.0
williamr@2:     void LoadCheckMarkBitmapL();
williamr@2:     TBool MenuHasCheckBoxOn() const;
williamr@2:     // Support for radio button, from v3.0
williamr@2:     void LoadRadioButtonBitmapL();
williamr@2:     TBool IsItemMemberOfRadioButtonGroup(TInt aItem) const ;
williamr@2:     // for drawing,from v3.0
williamr@2:     TBool MenuHasIcon() const;
williamr@2: 
williamr@2:     TRect CalculateSizeAndPositionScalable( const TRect& aWindowRect, TInt aNumItemsInPane ) ;
williamr@2:     TRect HighlightRect() const;
williamr@2:     void PrepareHighlightFrame() const;
williamr@2:     void SetCascadedIconSize() const;
williamr@2: 
williamr@2:     // fixes marquee flickering
williamr@2:     friend class CAknMarqueeControl;
williamr@2:     static TInt RedrawMarqueeEvent( TAny* aControl );
williamr@2:     
williamr@2:     CEikMenuPaneExtension* Extension() const;
williamr@2: 
williamr@2: protected: // from CoeControl
williamr@2: 
williamr@2:     /**
williamr@2:      * From @c CCoeControl.
williamr@2:      *
williamr@2:      * Retrieves an object of the same type as that encapsulated in aId. Other
williamr@2:      * than in the case where @c NULL is returned, the object returned must be 
williamr@2:      * of the same object type - that is, the @c ETypeId member of the object
williamr@2:      * pointed to by the pointer returned by this function must be equal to the
williamr@2:      * @c iUid member of @c aId.
williamr@2:      *
williamr@2:      * @since SDK 7.0s
williamr@2:      * @param aId An encapsulated object type ID.
williamr@2:      * @return Encapsulates the pointer to the object provided. Note that the 
williamr@2:      *         encapsulated pointer may be @c NULL.
williamr@2:      */
williamr@2:     IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
williamr@2: 
williamr@2: public: // From CoeControl.
williamr@2:     
williamr@2:     /**
williamr@2:      * From @c CoeControl.
williamr@2:      *
williamr@2:      * Gets the number of controls contained in a compound control. This 
williamr@2:      * function should be implemented by all compound controls.
williamr@2:      * 
williamr@2:      * Note: 
williamr@2:      * In SDK 6.1 this was changed from protected to public.
williamr@2:      * 
williamr@2:      * @return The number of component controls contained by this control.
williamr@2:      */
williamr@2:     IMPORT_C TInt CountComponentControls() const;
williamr@2:     
williamr@2:     /**
williamr@2:      * From @c CoeControl.
williamr@2:      *
williamr@2:      * Gets the specified component of a compound control. This function should´
williamr@2:      * be implemented by all compound controls.
williamr@2:      *
williamr@2:      * Note:
williamr@2:      * Within a compound control, each component control is identified by an 
williamr@2:      * index, where the index depends on the order the controls were added: the
williamr@2:      * first is given an index of 0, the next an index of 1, and so on.
williamr@2:      *
williamr@2:      * @param[in, out] aIndex The index of the control to get.
williamr@2:      * @return The component control with an index of @c aIndex.
williamr@2:      */
williamr@2:     IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;
williamr@2:     
williamr@2: protected: // new functions
williamr@2:     
williamr@2:     /**
williamr@2:      * Disables sliding effect
williamr@2:      * By default is enabled if there is enough memory.
williamr@2:      *
williamr@2:      * @since 3.1
williamr@2:      */
williamr@2:     void DisableAnimation();
williamr@2:     
williamr@2:     /**
williamr@2:      * The position of the menu will be changed according to the one 
williamr@2:      * which is specified by arguments in StartDisplayingMenuPane()
williamr@2:      * By default those arguments are not used.
williamr@2:      *
williamr@2:      * @since 3.1
williamr@2:      * @param aForced @c Etrue if arguments are used.
williamr@2:      */
williamr@2:     void SetPositionToBeForced(TBool aForced);
williamr@2:     
williamr@2:     /**
williamr@2:      * Gets the maximum number of items which can be seen simultaneously.
williamr@2:      *
williamr@2:      * @return The maximum number of items which can be seen simultaneously.
williamr@2:      */
williamr@2:     TInt NumberOfItemsThatFitInView() const;
williamr@2:     
williamr@2:     void DrawNow();    
williamr@2:     
williamr@2: private: // data
williamr@2:     friend class CEikMenuButton;
williamr@2:     MEikMenuObserver* iMenuObserver;
williamr@2:     MEikMenuObserver* iEditMenuObserver;
williamr@2:     CEikMenuPane* iCascadeMenuPane;
williamr@2:     const CEikMenuPaneTitle* iMenuPaneTitle;
williamr@2:     const CEikHotKeyTable* iHotKeyTable;
williamr@2:     CEikMenuPane* iOwner;
williamr@2:     CItemArray* iItemArray;
williamr@2:     TBool iArrayOwnedExternally;
williamr@2:     TBool iAllowPointerUpEvents;
williamr@2:     TInt iNumberOfDragEvents;
williamr@2:     TInt iSelectedItem;
williamr@2:     TInt iItemHeight;
williamr@2:     TInt iBaseLine;
williamr@2:     TInt iHotkeyColWidth;
williamr@2:     TInt iFlags;
williamr@2:     CEikScrollBarFrame* iSBFrame;
williamr@2:     CMenuScroller* iScroller;
williamr@2:     CEikButtonBase* iLaunchingButton; // for popouts only
williamr@2:     TInt iSubPopupWidth; // 0..2
williamr@2:     TBool iEnableAnimation;
williamr@2:     CEikMenuPaneExtension* iExtension ;  // iSpare used for extension class pointer.
williamr@2: 
williamr@2:     };
williamr@2: 
williamr@2: #endif
williamr@2: