1 /*

     2 * Copyright (c) 1997-1999 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 #if !defined(__EIKMENUP_H__)

    20 #define __EIKMENUP_H__

    21 

    22 #if !defined(__EIKBCTRL_H__)

    23 #include <eikbctrl.h>

    24 #endif

    25 

    26 #if !defined(__EIKDEF_H__)

    27 #include <eikdef.h>

    28 #endif

    29 

    30 #if !defined(__EIKSBOBS_H__)

    31 #include <eiksbobs.h> // for TEikScrollEvent

    32 #endif

    33 

    34 #include <bidi.h>

    35 

    36 // FORWARD DECLARATIONS

    37 class MEikMenuObserver;

    38 class CEikHotKeyTable;

    39 class CEikMenuPaneTitle;

    40 class CEikButtonBase;

    41 class CEikScrollBarFrame;

    42 class CEikScrollBar;

    43 class TEikScrollBarModel;

    44 class CGulIcon;

    45 class CEikMenuPaneExtension ;

    46 class CEikCba;

    47 class CAknItemActionMenuData;

    48 

    49 // CONSTANTS

    50 const TInt KScaleableTextSeparator = 0x0001;

    51 

    52 /**

    53   * A helper class for extending CEikMenuPaneItem without breaking binary 

    54   * compability.

    55   */

    56 class CExtendedItemData : public CBase

    57     {

    58     

    59 public:

    60     

    61     /**

    62      * Destructor.

    63      */

    64     ~CExtendedItemData();

    65     

    66 public:

    67     

    68     /** Two packaked bitmaps: bitmap icon and mask for it. */

    69     CGulIcon* iIcon;

    70     

    71     /** Scalable text buffer. */

    72     HBufC* iScaleableText;    

    73     };

    74 

    75 

    76 /**

    77  * The @c CEikMenuPaneItem class encapsulates the data needed to define a menu

    78  * pane item and provides some of the functionality required to display the 

    79  * item.

    80  *

    81  * @since ER5U

    82  */

    83 class CEikMenuPaneItem : public CBase

    84     {

    85     

    86 public:

    87     

    88     /** Struct to menu pane item. */

    89     struct SData

    90         {

    91         

    92         /** Nominal text length.*/

    93         enum { ENominalTextLength=40 };

    94         

    95         /** 

    96          * ID of the command to issue when the menu item using this @c SData is 

    97          * selected.

    98          */

    99         TInt iCommandId;

   100         

   101         /** Resource ID of a menu pane to cascade from this item. */

   102         TInt iCascadeId;

   103         

   104         /** 

   105          * Flags used internally by @c CEikMenuPane and accessible through 

   106          * functions such as @c CEikMenuPane::SetItemDimmed().

   107          */

   108         TInt iFlags;

   109         

   110         /** The text buffer displayed in the main area of the menu item. */

   111         TBuf<ENominalTextLength> iText; // less than this actually stored

   112         

   113         /** 

   114          * Additional descriptive text about the item. This is used by @c 

   115          * CEikMenuPane to display hotkey names.

   116          */

   117         TBuf<1> iExtraText;

   118         };

   119         

   120 public:

   121 

   122     /**

   123      * C++ default constructor.

   124      */

   125     IMPORT_C CEikMenuPaneItem();

   126     

   127     /**

   128      * Destructor.

   129      */

   130     IMPORT_C ~CEikMenuPaneItem();

   131     

   132     /**

   133      * Sets a menu item icon. This replaces any icon already set for the menu

   134      * item.

   135      *

   136      * @param aIcon Menu item icon consisting of a picture bitmap and a mask 

   137      *        bitmap.

   138      */

   139     IMPORT_C void SetIcon(CGulIcon* aIcon);

   140     

   141     /**

   142      * Draws the menu item icon.

   143      * 

   144      * @param aGc Graphics context to which the icon is drawn.

   145      * @param aRect Rectangle in which the icon is drawn. 

   146      * @param aDimmed If @c ETrue the icon is drawn dimmed. 

   147      * @param aBitmapSpaceRequired Length of one side of the square required to 

   148      *        contain the bitmap.

   149      */

   150     IMPORT_C void DrawItemIcon(CWindowGc& aGc, 

   151                                TRect aRect, 

   152                                TBool aDimmed, 

   153                                TInt aBitmapSpaceRequired) const;

   154     

   155     /**

   156      * Construct an icon from bitmaps. 

   157      * 

   158      * Constructs a new icon for the menu item, taking ownership of the picture

   159      * bitmap aBitmap and the mask bitmap aMask unless the bitmaps are 

   160      * externally owned.

   161      * 

   162      * @param aBitmap Picture bitmap.

   163      * @param aMask Mask bitmap.

   164      */

   165     IMPORT_C void CreateIconL(CFbsBitmap* aBitmap, 

   166                               CFbsBitmap* aMask);

   167     

   168     /**

   169      * Gets a pointer to the menu item's icon picture bitmap. This does not 

   170      * imply transfer of ownership.

   171      * 

   172      * @return Picture bitmap.

   173      */

   174     IMPORT_C CFbsBitmap* IconBitmap() const;

   175     

   176     /**

   177      * Gets a pointer to the menu item's icon mask bitmap. This does not imply

   178      * transfer of ownership.

   179      * 

   180      * @return Mask bitmap.

   181      */

   182     IMPORT_C CFbsBitmap* IconMask() const;

   183     

   184     /**

   185      * Sets icon bitmap ownership.

   186      * Sets the menu item's icon bitmaps as externally owned if @c 

   187      * aOwnedExternally is @c ETrue.

   188      * 

   189      * @param aOwnedExternally If @c ETrue bitmaps are set as externally owned. 

   190      *        @c If EFalse bitmaps are set as not being externally owned. 

   191      */

   192     IMPORT_C void SetBitmapsOwnedExternally(TBool aOwnedExternally);

   193     

   194     /**

   195      * Sets the picture bitmap. Transfers ownership unless the bitmaps are 

   196      * already owned externally.

   197      * 

   198      * @param aBitmap Picture bitmap.

   199      */

   200     IMPORT_C void SetIconBitmapL(CFbsBitmap* aBitmap);

   201     

   202     /**

   203      * Sets the mask bitmap. Transfers ownership unless the bitmaps are already

   204      * owned externally.

   205      * 

   206      * @param aMask Mask bitmap.

   207      */

   208     IMPORT_C void SetIconMaskL(CFbsBitmap* aMask);

   209     

   210     /**

   211      * Returns scaleable text. If there isn't scaleable text available then

   212      * this method returns @c iData.iText.

   213      * 

   214      * @return Pointer to TPtrC object that contains scaleable text.

   215      */

   216     IMPORT_C TPtrC ScaleableText() const;

   217     

   218     /**

   219      * Sets scaleable text. @c iData.iText is set to first text version.

   220      * 

   221      * @param aText Scalable text.

   222      */

   223     IMPORT_C void SetScaleableTextL(const TDesC& aText);

   224 

   225 private:

   226     inline void CreateExtendedDataBlock();

   227     inline TBool IsScaleableText(const TDesC& aText) const;

   228     TPtrC GetNominalText(const TDesC& aText);

   229 

   230 public:

   231 

   232     /** The y position of the menu pane item. */

   233     TInt iPos;

   234     

   235     /** The menu pane item's hotkey text. */

   236     TInt iHotKeyCode;

   237     

   238     /** Information from an SData struct. */

   239     SData  iData;

   240 

   241 private:

   242     CExtendedItemData* iExtendedData;

   243     };

   244 

   245 

   246 inline void CEikMenuPaneItem::CreateExtendedDataBlock()

   247     {

   248     if (!iExtendedData)

   249         {

   250         TRAPD(err, ( iExtendedData = new (ELeave) CExtendedItemData() ) );

   251         }

   252     }

   253 

   254 

   255 inline TBool CEikMenuPaneItem::IsScaleableText(const TDesC& aText) const

   256     {

   257     return aText.Locate( TChar( KScaleableTextSeparator ) ) != KErrNotFound;

   258     }

   259 

   260 

   261 /**

   262  * Menu panes are opened by activating the menu title 

   263  * @c (CEikMenuPaneTitle / MENU_TITLE) which is displayed in the menu bar @c 

   264  * (CEikMenuBar / MENU_BAR). They can also be cascaded from a menu item @c

   265  * (CEikMenuPaneItem / MENU_ITEM) or launched by a menu button @c 

   266  * (CEikMenuButton). 

   267  *

   268  * Menu panes may be defined using a @c MENU_PANE resource.

   269  */

   270 class CEikMenuPane : public CEikBorderedControl

   271     {

   272 private:

   273     enum {ENothingSelected=-1};

   274     class CMenuScroller;

   275     friend class CMenuScroller;

   276     friend class CEikMenuPaneExtension;

   277 public:

   278     

   279     /** The text to be displayed for a hotkey. */

   280     typedef TBuf<20> THotKeyDisplayText;

   281     

   282 public:

   283 

   284     /**

   285      * This class provides a constructor to create an array of menu pane items

   286      * and a destructor to destroy an array of menu pane items.

   287      */

   288     class CItemArray:public CArrayPtrFlat<CEikMenuPaneItem>

   289         {

   290         

   291     public:

   292         

   293         /**

   294          * C++ default constructor that creates a flat array of menu pane 

   295          * items.

   296          */

   297         IMPORT_C CItemArray();

   298         

   299         /**

   300          * Destructor.

   301          */

   302         IMPORT_C ~CItemArray();

   303         

   304         /**

   305          * Appends @c CEikMenuPaneItem class object to array.

   306          *

   307          * @param aMenuItem The menu item to add.

   308          */        

   309         IMPORT_C void AddItemL(CEikMenuPaneItem* aMenuItem);

   310         };

   311 

   312 public:

   313 

   314     /**

   315      * Destructor.

   316      */

   317     IMPORT_C ~CEikMenuPane();

   318     

   319     /**

   320      * C++ default constructor. Constructs a menu pane object with the 

   321      * specified observer.

   322      * 

   323      * @param aMenuObserver Menu observer.

   324      */

   325     IMPORT_C CEikMenuPane(MEikMenuObserver* aMenuObserver);

   326 

   327     /**

   328      * Handles 2nd base construction. Completes construction of a menu pane object. 

   329      * 

   330      * @param aOwner Menu pane owner ( for cascade menu ).

   331      * @param aEditMenuObserver Observer for the edit menu. In default this is 

   332      *        @c NULL.

   333      */

   334     IMPORT_C void ConstructL(CEikMenuPane* aOwner, 

   335                              MEikMenuObserver* aEditMenuObserver = NULL);

   336     

   337     /**

   338      * Destroys the menu pane's item array.

   339      */

   340     IMPORT_C void Reset();

   341     

   342 public: // framework

   343 

   344     /**

   345      * From @c CcoeControl.

   346      *

   347      * Handles key events offered to the menu by the control environment and 

   348      * provides an appropriate implementation of @c 

   349      * CCoeControl::OfferKeyEventL(). 

   350      * 

   351      * @param aKeyEvent The key event. 

   352      * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or @c 

   353      *        EEventKeyDown.

   354      */

   355     IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

   356                                          TEventCode aType);

   357     

   358     /**

   359      * From @c CcoeControl.

   360      *

   361      * Handles a pointer event on the menu.

   362      * 

   363      * @param aPointerEvent The pointer event to handle.

   364      */

   365     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   366     

   367     /**

   368      * From @c CcoeControl.

   369      *

   370      * Gets the list of logical colours employed in the drawing of the control, 

   371      * paired with an explanation of how they are used. Appends the list into 

   372      * @c aColorUseList.

   373      * 

   374      * @since 005u

   375      * @param aColorUseList The list of colours paired with explanations.

   376      */

   377     IMPORT_C virtual void GetColorUseListL(

   378         CArrayFix<TCoeColorUse>& aColorUseList) const; 

   379     

   380     /**

   381      * From @c CcoeControl.

   382      *

   383      * Handles a change to the menu's resources which are shared across the

   384      * environment. For example, colours or fonts.

   385      * 

   386      * @since 005u

   387      * @param aType The type of resource that has changed.

   388      */

   389     IMPORT_C virtual void HandleResourceChange(TInt aType);         // not available before Release 005u

   390 

   391 private: // from base class

   392 

   393     /**

   394      * Not implemented.

   395      * 

   396      * @param Not used.

   397      * @return NULL

   398      */

   399     IMPORT_C void* ExtensionInterface( TUid aInterface );

   400     

   401 public: // from MCoeInputObserver

   402     

   403     /**

   404      * From @c CCoeControl.

   405      *

   406      * Gets the list box’s input capabilities as set through the list box flags.

   407      *

   408      * @return List box input capabilities.

   409      */

   410     IMPORT_C TCoeInputCapabilities InputCapabilities() const;

   411     

   412 protected: // from base class

   413     

   414     /** 

   415      * From @c CCoeControl

   416      * 

   417      * Draw a control called by window server. 

   418      *

   419      * All controls, except blank controls, should implement this function. The

   420      * default implementation draws a blank control. This function is used for

   421      * window server-initiated redrawing of controls, and for some 

   422      * application-initiated drawing. It should be implemented by each control,

   423      * but  is only called from within @c CCoeControl's member functions, and 

   424      * not from the derived class. For this reason it is a private member 

   425      * function of @c CCoeControl.

   426      *

   427      * The rectangle aRect indicates the region of the control that needs to be

   428      * redrawn. The implementation of @c Draw() must always draw to every pixel 

   429      * within this rectangle.

   430      *

   431      * @param aRect The region of the control to be redrawn. 

   432      *        Co-ordinates are relative to the control's origin (top left 

   433      *        corner). Optional, not used currently.

   434      */

   435     IMPORT_C void Draw(const TRect& aRect) const;

   436     

   437     /**

   438      * From @c CCoeControl.

   439      *

   440      * Takes any action required when the menu pane gains or loses focus, 

   441      * to change its appearance for example.

   442      * 

   443      * @param aDrawNow If @c EDrawNow the menu pane is redrawn. If @c 

   444      *        ENoDrawNow the menu pane is not redrawn.

   445      */

   446     IMPORT_C void FocusChanged(TDrawNow aDrawNow);

   447     

   448     /**

   449      * From @c CCoeControl.

   450      *

   451      * Constructs the menu pane using the specified resource reader.

   452      * Fills the menu item array with the list of menu items provided by the

   453      * resource file.

   454      * 

   455      * @param aReader The resource reader to use.

   456      * @leave KErrNoMemory Memory allocation failure earlier construction.     

   457      */

   458     IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

   459     

   460 public: // new functions

   461 

   462     /**

   463      * Adds a menu item dynamically by creating a new menu item, setting its 

   464      * data to @c aMenuItem and appending it to the pane's menu item array. 

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

   466      * 

   467      * @param aMenuItem The menu item to add.

   468      *        NOTICE that @c SData is a structure so all fields in it should be

   469      *        set to avoid any unexpected behaviour.

   470      */

   471     IMPORT_C void AddMenuItemL(const CEikMenuPaneItem::SData& aMenuItem);

   472     

   473     /**

   474      * Adds a menu item dynamically by creating a new menu item, setting its 

   475      * data to @c aMenuItem and inserting it into the pane's menu item array. 

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

   477      * 

   478      * @param aMenuItem The menu item to add. NOTICE that @c SData is a 

   479      *        structure so all fields in it should be set to avoid any 

   480      *        unexpected behaviour.

   481      * @param aPreviousId The id of the item after which the new item should be

   482      *        added.

   483      */

   484     IMPORT_C void AddMenuItemL(const CEikMenuPaneItem::SData& aMenuItem, 

   485                                TInt aPreviousId);

   486     

   487     /**

   488      * Adds menu items dynamically by creating new menu items from resource 

   489      * and inserts them into the pane's menu item array. 

   490      * 

   491      * @param aResourceId The ID of the resource for the menu item.

   492      * @param aPreviousId The ID of the previous menu item, after which this 

   493      *        newly created item should be added.

   494      * @param aAddSeperator Shouldn't be used as separator is not not supported

   495      *        anymore.

   496      */

   497     IMPORT_C void AddMenuItemsL(TInt aResourceId, 

   498                                 TInt aPreviousId = 0,

   499                                 TBool aAddSeperator = EFalse);

   500     

   501     /**

   502      * Deletes the specified item in the menu pane.

   503      * 

   504      * @param aCommandId The ID for the item to be deleted.

   505      */

   506     IMPORT_C void DeleteMenuItem(TInt aCommandId);

   507     

   508     /**

   509      * Deletes the items between specified items.

   510      * 

   511      * @param aStartIndex The index of the item after which items should be 

   512      *        deleted.

   513      * @param aEndIndex The index of the item up to which items should be 

   514      *        deleted.

   515      */

   516     IMPORT_C void DeleteBetweenMenuItems(TInt aStartIndex, 

   517                                          TInt aEndIndex);

   518     

   519     /**

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

   521      * 

   522      * @param aCommandId The command ID of the menu item for which data is 

   523      *        obtained.

   524      * @return Reference to struct that contains command id.

   525      */

   526     IMPORT_C CEikMenuPaneItem::SData& ItemData(TInt aCommandId);

   527     

   528     /**

   529      * Gets a pointer to the specified menu item. Also gets the position of the

   530      * item within the menu pane. Panics if there are no menu items in the menu

   531      * pane. Panics if the menu pane id does not identify any menu pane item in

   532      * the array.

   533      * 

   534      * @param aCommandId The ID of the menu item for which a pointer is 

   535      *        returned. 

   536      * @param aPos On return, the position of the menu item with an ID of 

   537      *        aCommandId.

   538      * @return A pointer to the menu item.

   539      * @panic EEikPanicNoSuchMenuItem Panics if there are no menu items in the

   540      *                                menu pane or if the menu pane id does not

   541      *                                identify any menu pane item in the array.

   542      */

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

   544     

   545     /**

   546      * Displays the menu pane with the corner identified by @c aTargetType in 

   547      * the position specified by @c aTargetPos. This function uses @c 

   548      * aMinTitleWidth to calculate the area required to display the menu pane,

   549      * taking into account whether the menu is a cascading menu or popup menu.

   550      * 

   551      * @param aHotKeyTable Optional hotkey table. 

   552      * @param aTargetPos Position of the corner of the menu pane identified by 

   553      *        @c aTargetType. 

   554      * @param aMenuPaneTitle The menu pane's title.

   555      * @param aMinWidth Minimum width of the menu's title.

   556      * @param aTargetType The corner of the menu pane to which @c aTargetPos 

   557      *        relates. The default is the top left corner. Possible: @c 

   558      *        EPopupTargetTopLeft, @c EPopupTargetTopRight, 

   559      *        @cEPopupTargetBottomLeft, @c EPopupTargetBottomRight.

   560      */

   561     IMPORT_C void StartDisplayingMenuPane(

   562             const CEikHotKeyTable* aHotKeyTable,                               

   563             const TPoint& aTargetPos, 

   564             const CEikMenuPaneTitle* aMenuPaneTitle,

   565             TInt aMinWidth,  

   566             TPopupTargetPosType aTargetType = EPopupTargetTopLeft);

   567             

   568     /**

   569      * Sets the text in a menu item.

   570      * 

   571      * @param aCommandId The command (as defined in an .hrh file) associated

   572      *        with this menu item. This identifies the menu item whose text is

   573      *        to be set. 

   574      * @param aDes New item text.

   575      */                                      

   576     IMPORT_C void SetItemTextL(TInt aCommandId,

   577                                const TDesC& aDes);

   578     

   579     /**

   580      * Sets the text in a menu item from resource.

   581      *

   582      * @param aCommandId The command (as defined in an .hrh file) associated 

   583      *        with this menu item. This identifies the menu item whose text is

   584      *        to be set. 

   585      * @param aRid The resource ID of the menu item text. 

   586      */

   587     IMPORT_C void SetItemTextL(TInt aCommandId,

   588                                TInt aRid);

   589                                

   590     /**

   591      * Dims (greys out) or undims a menu item. Dimming indicates that user 

   592      * input is not accepted.

   593      * 

   594      * @param aCommandId The command (as defined in an .hrh file) associated

   595      *        with this menu item. This identifies the menu item whose text is

   596      *        to be dimmed or un-dimmed. 

   597      * @param aDimmed @c ETrue to dim this menu item. @c EFalse to un-dim this

   598      *        menu item.

   599      */

   600     IMPORT_C void SetItemDimmed(TInt aCommandId,

   601                                 TBool aDimmed);

   602                                 

   603     /**

   604      * Sets the item to be indicated or not. It should be used to change the

   605      * state of radio buttons or check box items. It has real effect only 

   606      * starting from S60 v3.0.

   607      * 

   608      * @param aCommandId The command (as defined in an .hrh file) associated 

   609      *        with this menu item. This identifies the menu item for which the 

   610      *        state is set or unset. 

   611      * @param aButtonState should be @c EEikMenuItemSymbolOn or @c

   612      *        EEikMenuItemSymbolIndeterminate

   613      */                           

   614     IMPORT_C void SetItemButtonState(TInt aCommandId,

   615                                      TInt aButtonState);

   616     

   617     /**

   618      * Sets the selected menu item.

   619      * 

   620      * @param aSelectedItem The index of the item to get selected

   621      */                                

   622     IMPORT_C void SetSelectedItem(TInt aSelectedItem);

   623     

   624     /**

   625      * Gets the position of the selected menu item.

   626      * 

   627      * @return The position of the selected menu item.

   628      */

   629     IMPORT_C TInt SelectedItem() const;

   630     

   631     /**

   632      * Closes and destroys any current cascade menu and takes focus back. Does

   633      * nothing if no cascade menu exists.

   634      */

   635     IMPORT_C void CloseCascadeMenu();

   636     

   637     /**

   638      * Sets the array containing the list of menu items for the current menu 

   639      * pane.

   640      * 

   641      * @param aItemArray The menu item array for the menu pane.

   642      */

   643     IMPORT_C void SetItemArray(CItemArray* aItemArray);

   644     

   645     /**

   646      * Set menu item array ownership.

   647      * 

   648      * @param aOwnedExternally If @c ETrue the menu pane's menu item array is 

   649      *        set as externally owned. If @c EFalse the menu pane's menu item 

   650      *        array is set as not externally owned.

   651      */

   652     IMPORT_C void SetItemArrayOwnedExternally(TBool aOwnedExternally);

   653     

   654     /**

   655      * Sets the specified button to launch the menu pane. Doesn't have any 

   656      * effect in current implementation.

   657      * 

   658      * @param aButton The button to set as launching the menu.

   659      */

   660     IMPORT_C void SetLaunchingButton(CEikButtonBase* aButton);

   661     

   662     /**

   663      * Moves the menu pane highlight to a newly selected menu item identified

   664      * by @c aNewSelectedItem. Scrolls the menu to show the new selected item

   665      * if necessary and redraws only the newly selected item and the currently

   666      * selected item if possible.

   667      * 

   668      * @param aNewSelectedItem The newly selected menu item index.

   669      */

   670     IMPORT_C void MoveHighlightTo(TInt aNewSelectedItem);

   671     

   672     /**

   673      * Gets the number of menu items within the menu pane.

   674      *

   675      * @return Number of menu items within menu pane.

   676      */

   677     IMPORT_C TInt NumberOfItemsInPane() const;

   678     

   679     /**

   680      * Closes the menu pane.

   681      */

   682     IMPORT_C void Close();

   683     

   684     /**

   685      * From @ CCoeControl

   686      *

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

   688      * 

   689      * @since Platform 004.

   690      * @param aKeyEvent The key event.

   691      * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or @c

   692      *        EEventKeyDown. 

   693      * @param aConsumeAllKeys If @c ETrue this function returns @c 

   694      *        EKeyWasConsumed regardless of whether it was used. If @c EFalse

   695      *        the key event is consumed if possible and either @c 

   696      *        EKeyWasConsumed or @c EKeyWasNotConsumed is returned as 

   697      *        appropriate.

   698      */

   699     IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

   700                                          TEventCode aType,

   701                                          TBool aConsumeAllKeys); // not available before Platform 004

   702     

   703     /**

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

   705      * 

   706      * @param aOnLeft If @c ETrue the scroll bar will occupy the left side of

   707      *        the menu pane.

   708      */                                     

   709     IMPORT_C void SetScrollBarOnLeft(TBool aOnLeft);

   710     

   711     /**

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

   713      * 

   714      * @param aArrowHead If @c ETrue the menu pane uses an arrow head scroll 

   715      *        bar.

   716      */

   717     IMPORT_C void SetArrowHeadScrollBar(TBool aArrowHead);

   718     

   719 // new for AVKON

   720     

   721     /**

   722      * Moves highlight to the next item or to the first one if last item is 

   723      * selected. 

   724      */

   725     IMPORT_C void NavigateToNextItem();

   726     

   727     /**

   728      * Inserts the menu item to the specified position.

   729      * 

   730      * @param aMenuItem The menu item to add. NOTICE @c SData is the structure

   731      *        and all fileds should be initialized.

   732      * @param aPosition The position of newly created item in the array.

   733      */

   734     IMPORT_C void InsertMenuItemL(const CEikMenuPaneItem::SData& aMenuItem, 

   735                                   TInt aPosition);

   736     

   737     /**

   738      * Checks whether menu pane contains the menu item and returns position of

   739      * it if the item is found.

   740      * 

   741      * @param[in] aCommandId The command ID of the item to be searched for.

   742      * @param[out] aPosition On return contains position of the item.

   743      * @return @c ETrue if item was found. Otherwise @c EFalse.

   744      */

   745     IMPORT_C TBool MenuItemExists(TInt aCommandId, 

   746                                   TInt& aPosition);

   747     

   748     /**

   749      * Checks whether the menu pane is a cascade menu or a main menu. 

   750      *

   751      * @return @c ETrue if the menu pane is cascade menu and @c EFalse if the

   752      *         menu pane is the main menu.

   753      */

   754     IMPORT_C TBool IsCascadeMenuPane() const;

   755     

   756     /**

   757      * Enables or disables text scrolling functionality. It is disabled by 

   758      * default.

   759      * 

   760      * @param aEnable @c ETrue to enable text scrolling functionality.

   761      */

   762     IMPORT_C void EnableMarqueeL(const TBool aEnable); 

   763 

   764     /**

   765      * Report that selection was done for the currently highlighted item.

   766      */

   767     void ActivateCurrentItemL();

   768     

   769     /**

   770      * Closes cascade menu if there is one and it is active.

   771      */

   772     TBool CancelActiveMenuPane();

   773     

   774     /**

   775      * Deletes dimmed items from the menu item array.

   776      */

   777     void FilterDimmedItems();

   778 

   779     /**

   780      * Gets the menu pane for the cascade menu.

   781      *

   782      * @return The menu pane for the cascade menu.

   783      */

   784     IMPORT_C CEikMenuPane* CascadeMenuPane();

   785     

   786     /**

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

   788      * 

   789      * @since S60 3.1

   790      * @param aItemIndex The index of the item in the items array.

   791      * @return The menu item's data.

   792      * @leave  KErrArgument Wrong @aItemIndex.

   793      */

   794     IMPORT_C CEikMenuPaneItem::SData& ItemDataByIndexL(TInt aItemIndex);

   795 

   796     /**

   797      * Creates and enables a special characters row to be used in the edit 

   798      * menu.

   799      *

   800      * @since S60 3.1 

   801      * @param aSpecialChars Buffer that holds the selected characters after 

   802      *                      user has selected them.

   803      */

   804     IMPORT_C void ConstructMenuSctRowL( TDes& aSpecialChars );

   805 

   806     /**

   807      * Returns the command id of the specified menu item. The function panics

   808      * if aIndex doesn't exist or is out of range.

   809      * @param aIndex The index of the menu item for which the command ID is returned.

   810      * @since 3.1

   811      */

   812     IMPORT_C TInt MenuItemCommandId( TInt aIndex ) const;

   813 

   814     /**

   815      * Creates and enables a special characters row to be used in the edit menu.

   816      * The special character row is constructed from the given special character table.

   817      *

   818      * @param aSpecialChars Buffer that holds the selected characters after 

   819      * user has selected them.

   820      * @param aResourceId The special character table resource id to define the 

   821      * characters in the row.

   822      *

   823      * @since S60 3.1

   824      */

   825     IMPORT_C void ConstructMenuSctRowL( TDes& aSpecialChars, TInt aResourceId );

   826 

   827     /**

   828      * Creates and enables a special characters row to be used in the edit menu.

   829      * The special character row is constructed from the given special character dialog.

   830      *

   831      * @param aSpecialChars Buffer that holds the selected characters after 

   832      * user has selected them.

   833      * @param aResourceId The special character dialog  resource id that contains a special character table

   834      *

   835      * @since S60 3.2

   836      */

   837     IMPORT_C void ConstructMenuSctRowFromDialogL( TDes& aSpecialChars, TInt aResourceId );

   838 

   839     /**

   840      * Creates and enables a special characters row to be used in the edit menu.

   841      * The special character row is constructed from the given special character dialog.

   842      *

   843      * @param aCharCase the charcase used by menu sct

   844      * @param aSpecialChars Buffer that holds the selected characters after

   845      * user has selected them.

   846      * @param aResourceId The special character dialog  resource id that contains a special character table

   847      *

   848      * @since S60 3.2

   849      */

   850     IMPORT_C void ConstructMenuSctRowFromDialogL( TInt aCharCase, TDes& aSpecialChars, TInt aResourceId );

   851 

   852     /**

   853      * Sets menu item as item specific command.

   854      * 

   855      * @param aCommandId The command associated with this menu item.

   856      * @param aItemSpecific ETrue to define the menu item item specific,

   857      * EFalse otherwise.

   858      */

   859     IMPORT_C void SetItemSpecific( TInt aCommandId, TBool aItemSpecific );

   860 

   861     /**

   862      * Sets the embedded cba to options menu

   863      *

   864      * @param aCba Cba to embed to menu

   865      * 

   866      * @since S60 v5.2

   867      */

   868     void SetEmbeddedCba( CEikCba* aCba );

   869 

   870     /**

   871      * Closes and destroys any current cascade menu and takes focus back. Does

   872      * nothing if no cascade menu exists.

   873      * 

   874      * @param aMainMenuClosing ETrue if main menu is also to be closed.

   875      */

   876     void CloseCascadeMenu( TBool aMainMenuClosing );

   877 

   878     /**

   879      * Symbian two-phased constructor for menu panes that are created for

   880      * item specific menus.

   881      * 

   882      * @internal

   883      * @since S60 v5.2

   884      * @return Created menu pane. Ownership transfers to caller.

   885      */

   886     static CEikMenuPane* NewItemCommandMenuL( MEikMenuObserver* aObserver );

   887 

   888     /**

   889      * Sets item specific commands dimmed.

   890      * 

   891      * @internal

   892      * @since S60 v5.2

   893      */

   894     void SetItemCommandsDimmed();

   895 

   896     /**

   897      * Adds menu items to this menu and item action menu data. 

   898      * 

   899      * @internal

   900      * @since S60 v5.2

   901      * @param aMenuData Item action menu data.

   902      */

   903     void AddMenuItemsToItemActionMenuL(

   904             CAknItemActionMenuData& aMenuData );

   905 

   906     /**

   907      * Adds cascade menu items to item action menu data.

   908      * 

   909      * @internal

   910      * @since S60 v5.2

   911      * @param aCascadeId Cascade menu id.

   912      * @param aItemSpecific If ETrue, adds only item specific items.

   913      * @param aMenuData Item action menu data.

   914      */

   915     void AddCascadeMenuItemsToActionMenuL(

   916             TInt aCascadeId,

   917             TBool aItemSpecific,

   918             CAknItemActionMenuData& aMenuData );

   919     

   920     /**

   921      * Enables the default highlight in menu

   922      */

   923     void SetDefaultHighlight();

   924     

   925 private:

   926     enum { EInvalidCurrentSize=0x01, EBackgroundFaded=0x02 };

   927     

   928 private: // new functions

   929     TRect CalculateSizeAndPosition() ;

   930     enum THighlightType {ENoHighlight,EDrawHighlight,ERemoveHighlight};

   931     void DrawItem( TInt aItem, THighlightType aHighlight ) const;

   932     void DrawItem(CWindowGc& aGc,TInt aItem, THighlightType aHighlight) const;

   933     void ReportSelectionMadeL( TBool aAbortTransition = ETrue );

   934     void ReportCanceled();

   935     void LaunchCascadeMenuL(TInt aCascadeMenuId);

   936     void DoLaunchCascadeMenuL(TInt aCascadeMenuId);

   937     void TryLaunchCascadeMenuL(const CEikMenuPaneItem& aItem);

   938     void PrepareGcForDrawingItems(CGraphicsContext& aGc) const;

   939     TBool ItemArrayOwnedExternally() const;

   940     TBool IsHotKeyL(const TInt modifiers,const TInt aCode);

   941     TBool MoveToItemL(TInt aCode, TInt aModifiers);

   942     void HandleScrollEventL(CEikScrollBar* aScrollBar,TEikScrollEvent aEventType);

   943     void CreateScrollBarFrame();

   944     void UpdateScrollBar();

   945     void DoUpdateScrollBarL();

   946     void UpdateScrollBarThumbs();

   947     static TInt UpdateScrollBarCallBackL(TAny* aObj);

   948     TRect ViewRect() const;

   949     TInt TotalItemHeight() const;

   950     void ScrollToMakeItemVisible(TInt aItemIndex);

   951     void Scroll(TInt aAmount);

   952     TBool CheckCreateScroller();

   953     void CheckCreateScrollerL();

   954     void ResetItemArray();

   955     void CreateItemArrayL();

   956     void CreateIconFromResourceL(TResourceReader& aReader, CEikMenuPaneItem& aItem) const;

   957 

   958     // Skin support for menu

   959     void UpdateBackgroundContext(const TRect& aWindowRect);

   960 

   961     // Support method for highlight animation

   962     void RepaintHighlight() const;

   963 

   964 private: // from CCoeControl

   965     IMPORT_C void Reserved_1();

   966     IMPORT_C void Reserved_2();

   967 

   968 private : // new functions

   969     void LoadCascadeBitmapL() ;

   970 

   971     // Support for check mark, from v3.0

   972     void LoadCheckMarkBitmapL();

   973     TBool MenuHasCheckBoxOn() const;

   974     // Support for radio button, from v3.0

   975     void LoadRadioButtonBitmapL();

   976     TBool IsItemMemberOfRadioButtonGroup(TInt aItem) const ;

   977     // for drawing,from v3.0

   978     TBool MenuHasIcon() const;

   979 

   980     TRect CalculateSizeAndPositionScalable( const TRect& aWindowRect, TInt aNumItemsInPane ) ;

   981     TRect HighlightRect() const;

   982     void PrepareHighlightFrame() const;

   983     void SetCascadedIconSize() const;

   984 

   985     // fixes marquee flickering

   986     friend class CAknMarqueeControl;

   987     

   988     CEikMenuPaneExtension* Extension() const;

   989     

   990     /**

   991      * Creates menu pane's extension object if it doesn't exist yet.

   992      */

   993     void CheckCreateExtensionL();

   994 

   995 protected: // from CoeControl

   996 

   997     /**

   998      * From @c CCoeControl.

   999      *

  1000      * Retrieves an object of the same type as that encapsulated in aId. Other

  1001      * than in the case where @c NULL is returned, the object returned must be 

  1002      * of the same object type - that is, the @c ETypeId member of the object

  1003      * pointed to by the pointer returned by this function must be equal to the

  1004      * @c iUid member of @c aId.

  1005      *

  1006      * @since SDK 7.0s

  1007      * @param aId An encapsulated object type ID.

  1008      * @return Encapsulates the pointer to the object provided. Note that the 

  1009      *         encapsulated pointer may be @c NULL.

  1010      */

  1011     IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

  1012 

  1013 public: // From CoeControl.

  1014     

  1015     /**

  1016      * From @c CoeControl.

  1017      *

  1018      * Gets the number of controls contained in a compound control. This 

  1019      * function should be implemented by all compound controls.

  1020      * 

  1021      * Note: 

  1022      * In SDK 6.1 this was changed from protected to public.

  1023      * 

  1024      * @return The number of component controls contained by this control.

  1025      */

  1026     IMPORT_C TInt CountComponentControls() const;

  1027     

  1028     /**

  1029      * From @c CoeControl.

  1030      *

  1031      * Gets the specified component of a compound control. This function should?

  1032      * be implemented by all compound controls.

  1033      *

  1034      * Note:

  1035      * Within a compound control, each component control is identified by an 

  1036      * index, where the index depends on the order the controls were added: the

  1037      * first is given an index of 0, the next an index of 1, and so on.

  1038      *

  1039      * @param[in, out] aIndex The index of the control to get.

  1040      * @return The component control with an index of @c aIndex.

  1041      */

  1042     IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

  1043     

  1044 protected: // new functions

  1045 

  1046     /**

  1047      * Gets the maximum number of items which can be seen simultaneously.

  1048      *

  1049      * @return The maximum number of items which can be seen simultaneously.

  1050      */

  1051     TInt NumberOfItemsThatFitInView() const;

  1052     

  1053 private: // data

  1054     friend class CEikMenuButton;

  1055     MEikMenuObserver* iMenuObserver;

  1056     MEikMenuObserver* iEditMenuObserver;

  1057     CEikMenuPane* iCascadeMenuPane;

  1058     const CEikMenuPaneTitle* iMenuPaneTitle;

  1059     const CEikHotKeyTable* iHotKeyTable;

  1060     CEikMenuPane* iOwner;

  1061     CItemArray* iItemArray;

  1062     TBool iArrayOwnedExternally;

  1063     TBool iAllowPointerUpEvents;

  1064     TInt iNumberOfDragEvents;

  1065     TInt iSelectedItem;

  1066     TInt iItemHeight;

  1067     TInt iBaseLine;

  1068     TInt iHotkeyColWidth;

  1069     TInt iFlags;

  1070     CEikScrollBarFrame* iSBFrame;

  1071     CMenuScroller* iScroller;

  1072     CEikButtonBase* iLaunchingButton; // for popouts only

  1073     TInt iSubPopupWidth; // 0..2

  1074     TInt iSpare;

  1075     CEikMenuPaneExtension* iExtension ;

  1076 

  1077     };

  1078 

  1079 #endif

  1080