classicui_pub/options_menu_api/inc/EIKMENUP.H
changeset 0 2f259fa3e83a
child 4 8ca85d2f0db7
equal deleted inserted replaced
-1:000000000000 0:2f259fa3e83a
       
     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