1 eikbtgpc.h

     1 /*

     2 * Copyright (c) 2002-2007 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  EIKON button group container class definition.

    15 *

    16 */

    17 

    18 

    19 #ifndef __EIKBTGPC_H__

    20 #define __EIKBTGPC_H__

    21 

    22 #include <coecntrl.h>

    23 #include <eikbtgrp.h>

    24 #include <eikcmobs.h>

    25 #include <lafpublc.h>

    26 #include <uikon.hrh>

    27 

    28 #include <akncontrol.h>

    29 

    30 class MEikCommandObserver;

    31 class CEikButtonGroupStack;

    32 class CEikCommandButton;

    33 class CEikListBox;

    34 

    35 /**

    36  * The CEikButtonGroupContainer class provides a wrapper around the different button arrays

    37  * used in pen and no-pen devices. 

    38  *

    39  * @lib eikcoctl.lib 

    40  * @since S60 0.9 

    41  */

    42 NONSHARABLE_CLASS(CEikButtonGroupContainer) : public CAknControl, public MEikCommandObserver

    43     {

    44 public:

    45     /** 

    46      * Declares an object type for a class, in order to allow the object

    47      * provider mechanism to locate and provide objects from the class.

    48      */

    49     DECLARE_TYPE_ID(0x101F4107)

    50 

    51     /**

    52      * Describes how the container is being used.

    53      *

    54      * The enumeration is used by the system to create the appropriate (UI variant-specific)

    55      * button group for the specified type.

    56      */

    57     enum TUse

    58         {

    59         EView          = SLafButtonGroupContainer::EView,         ///< In a view.

    60         EDialog        = SLafButtonGroupContainer::EDialog,       ///< In a dialog.

    61         EToolbar       = SLafButtonGroupContainer::EToolbar,      ///< In a toolbar.

    62         ECba           = SLafButtonGroupContainer::ECba,          ///< In a control button array.

    63         EDialogButtons = SLafButtonGroupContainer::EDialogButtons ///< In dialog buttons.

    64         };

    65         

    66     /**

    67      * Describes the orientation of the container.

    68      */        

    69     enum TOrientation

    70         {

    71         EVertical   = SLafButtonGroupContainer::EVertical,  ///< Buttons are laid out vertically.

    72         EHorizontal = SLafButtonGroupContainer::EHorizontal ///< Buttons are laid out horizontally.

    73         };

    74         

    75     /**

    76      * Relative positions of the container and the control which uses it.

    77      */        

    78     enum TLocation

    79         {

    80         /** The button group is internal to the control which is using it. E.g. dialog buttons. */

    81         EInternal   = SLafButtonGroupContainer::EInternal, 

    82         

    83         /** The button group is external to the control which is using it. E.g. toolbar or cba. */

    84         EExternal   = SLafButtonGroupContainer::EExternal  

    85         };

    86         

    87     /**

    88      * Flags for the display of hotkeys.

    89      */        

    90     enum THotKeyFlags

    91         {

    92         EShowHotKey      = 0x01, ///< Hotkeys for commands should be shown.

    93         EPlainHotKey     = 0x02  ///< Hotkeys for commands should not be shown.

    94         };

    95         

    96     /** 

    97      * Additional flags.

    98      */         

    99     enum TFlags

   100         {

   101         EAddToStack      = 0x01, ///< Not used.

   102         EDelayActivation = 0x02, ///< If set, the container is not activated during construction.

   103         EUseMaxSize      = 0x04  ///< Not used.

   104         };

   105         

   106     /**

   107      * Defines the positions for each command.   

   108      */   

   109     enum TCommandPosition

   110         {

   111         ELeftSoftkeyPosition    = 0, ///< Position for left softkey.

   112         ERightSoftkeyPosition   = 2, ///< Position for right softkey.

   113         EMiddleSoftkeyPosition  = 3  ///< Position for middle softkey.

   114         };

   115         

   116 public:

   117     /**

   118      * Creates a button group container in its own window.

   119      *

   120      * @param aUse The button group's type. 

   121      * @param aOrientation The button group's orientation. You need specify this 

   122      *                     only for devices that can layout their buttons either 

   123      *                     horizontally or vertically.

   124      * @param aCommandObserver A command observer to be notified of commands on 

   125      *                         the container.

   126      * @param aResourceId A resource containing descriptions of buttons in the group. 

   127      *                    This can be NULL if buttons are to be added dynamically.

   128      * @param aFlags The button group's flags.

   129      * @return Button group container object.

   130      */ 

   131     IMPORT_C static CEikButtonGroupContainer* NewL(

   132         TUse aUse,

   133         TOrientation aOrientation,

   134         MEikCommandObserver* aCommandObserver,

   135         TInt aResourceId,

   136         TUint aFlags = EAddToStack);

   137 

   138     /**

   139      * Creates a button group container in its parent control's window.

   140      *

   141      * @param aUse The button group's type.

   142      * @param aOrientation The button group's orientation. You need specify this 

   143      *                     only for devices that can layout their buttons either 

   144      *                     horizontally or vertically.

   145      * @param aCommandObserver A command observer to be notified of commands on 

   146      *                         the container.

   147      * @param aResourceId A resource containing descriptions of buttons in the group. 

   148      *                    This can be NULL if buttons are to be added dynamically.

   149      * @param aParent The control's parent.

   150      * @param aFlags The button group's flags.

   151      * @return Button group container object.

   152      */         

   153     IMPORT_C static CEikButtonGroupContainer* NewL(

   154         TUse aUse,

   155         TOrientation aOrientation,

   156         MEikCommandObserver* aCommandObserver,

   157         TInt aResourceId,

   158         const CCoeControl& aParent,

   159         TUint aFlags = EAddToStack);

   160 

   161     /**

   162      * Creates a button group container in given window group.

   163      *

   164      * @param aUse The button group's type.

   165      * @param aOrientation The button group's orientation. You need specify this 

   166      *                     only for devices that can layout their buttons either 

   167      *                     horizontally or vertically.

   168      * @param aCommandObserver A command observer to be notified of commands on 

   169      *                         the container.

   170      * @param aResourceId A resource containing descriptions of buttons in the group. 

   171      *                    This can be NULL if buttons are to be added dynamically.

   172      * @param aParentWg The parent window group.

   173      * @param aFlags The button group's flags.

   174      * @return Button group container object.

   175      */        

   176     IMPORT_C static CEikButtonGroupContainer* NewL(

   177         TUse aUse,

   178         TOrientation aOrientation,

   179         MEikCommandObserver* aCommandObserver,

   180         TInt aResourceId,

   181         RWindowGroup& aParentWg,

   182         TUint aFlags = EAddToStack);

   183 

   184     /**

   185      * Destructor.

   186      */        

   187     IMPORT_C ~CEikButtonGroupContainer();

   188 

   189     /**

   190      * Gets a pointer to an application's currently active CEikButtonGroupContainer (if any).

   191      *

   192      * Returns NULL if there are no containers active or none suitable for sharing. 

   193      * Ownership of the returned pointer is not transferred.

   194      *

   195      * @return Pointer to the button group container.

   196      */    

   197     IMPORT_C static CEikButtonGroupContainer* Current();

   198     

   199 public:

   200     /**

   201      * Sets a command button's text label and command ID.

   202      *

   203      * @param aPosition The position within the button group of the button to change.

   204      *                  If the position is out of range this function raises a panic.

   205      * @param aCommandId Command ID the button will send.

   206      * @param aText Text for the button.

   207      */

   208     inline void SetCommandL(

   209         TInt aPosition, 

   210         TInt aCommandId, 

   211         const TDesC& aText);

   212 

   213     /**

   214      * Sets a command button's bitmap and command ID.

   215      *

   216      * @param aPosition The position within the button group of the button to change. 

   217      *                  If the position is out of range this function raises a panic.

   218      * @param aCommandId Command ID the button will send.

   219      * @param aBitmap The bitmap for the button.

   220      * @param aMask The mask bitmap for aBitmap.

   221      */    

   222     inline void SetCommandL(

   223         TInt aPosition, 

   224         TInt aCommandId, 

   225         const CFbsBitmap& aBitmap,

   226         const CFbsBitmap& aMask);

   227 

   228     /**

   229      * Sets a command button's bitmap, text and command ID.

   230      *

   231      * @param aPosition The position within the button group of the button to change. 

   232      *                  If the position is out of range, the function raises a panic.

   233      * @param aCommandId Command ID the button will send.

   234      * @param aText The text for the button.

   235      * @param aBitmap The bitmap for the button.

   236      * @param aMask The mask bitmap for aBitmap.

   237      */        

   238     inline void SetCommandL(

   239         TInt aPosition, 

   240         TInt aCommandId, 

   241         const TDesC& aText,

   242         const CFbsBitmap& aBitmap,

   243         const CFbsBitmap& aMask);

   244 

   245     /**

   246      * Sets a command button's bitmap and command ID. The bitmap and its mask are read

   247      * from a file.

   248      *

   249      * @param aPosition The position within the button group of the button to change.

   250      *                  If the position is out of range, the function raises a panic.

   251      * @param aCommandId Command ID the button will send.

   252      * @param aFile A multi-bitmap file, containing mask and bitmap images.

   253      * @param aBitmapId ID of the bitmap within aFile.

   254      * @param aMaskId ID of the mask within aFile.

   255      */        

   256     inline void SetCommandL(

   257         TInt aPosition, 

   258         TInt aCommandId, 

   259         const TDesC& aFile,

   260         TInt aBitmapId,

   261         TInt aMaskId);

   262 

   263     /**

   264      * Sets a command button's bitmap, text label and command ID. The bitmap and its 

   265      * mask are read from a file.

   266      *

   267      * @param aPosition The position within the button group of the button to change.

   268      *                  If the position is out of range, the function raises a panic.

   269      * @param aCommandId Command ID the button will send.

   270      * @param aText The text for the button.

   271      * @param aFile A multi-bitmap file, containing mask and bitmap images.

   272      * @param aBitmapId ID of the bitmap within aFile.

   273      * @param aMaskId ID of the mask within aFile.

   274      */        

   275     inline void SetCommandL(

   276         TInt aPosition, 

   277         TInt aCommandId, 

   278         const TDesC& aText,

   279         const TDesC& aFile,

   280         TInt aBitmapId,

   281         TInt aMaskId);

   282 

   283     /**

   284      * Sets a command button's bitmap, text label and command ID. The bitmap, mask,

   285      * text and command ID are all read from resource.

   286      *

   287      * @param aPosition The position within the button group of the button to change.

   288      *                  If the position is out of range, the function raises a panic.

   289      * @param aResourceId Resource ID specifying the text, bitmaps and command ID.

   290      */        

   291     inline void SetCommandL(

   292         TInt aPosition, 

   293         TInt aResourceId);

   294 

   295     /**

   296      * Sets a command button's text. The button to change is identified by its command ID.

   297      *

   298      * @param aCommandId Command ID of the button to change.

   299      * @param aText The text for the button.

   300      * @leave KErrNotFound The ID cannot be matched to any button.

   301      */        

   302     inline void SetCommandL(

   303         TInt aCommandId, 

   304         const TDesC& aText);

   305 

   306     /**

   307      * Sets a command button's bitmap and mask. The button to change is identified 

   308      * by its command ID.

   309      *

   310      * @param aCommandId Command ID of the button to change.

   311      * @param aBitmap Bitmap for the button.

   312      * @param aMask Mask bitmap for aBitmap.

   313      * @leave KErrNotFound The ID cannot be matched to any button.

   314      */        

   315     inline void SetCommandL(

   316         TInt aCommandId, 

   317         const CFbsBitmap& aBitmap,

   318         const CFbsBitmap& aMask);

   319 

   320     /**

   321      * Sets a command button's bitmap, mask and text. The button to change is 

   322      * identified by its command ID.

   323      *

   324      * @param aCommandId Command ID of the button to change.

   325      * @param aText Text for the button.

   326      * @param aBitmap Bitmap for the button.

   327      * @param aMask Mask bitmap for aBitmap.

   328      */        

   329     inline void SetCommandL(

   330         TInt aCommandId, 

   331         const TDesC& aText,

   332         const CFbsBitmap& aBitmap,

   333         const CFbsBitmap& aMask);

   334 

   335     /**

   336      * Sets a command button's bitmap and mask. The bitmap and mask are read from 

   337      * a multi bitmap file. The button to change is identified by its command ID.

   338      *

   339      * @param aCommandId Command ID of the button to change.

   340      * @param aFile A multi-bitmap file, containing mask and bitmap images.

   341      * @param aBitmapId ID of the bitmap within aFile.

   342      * @param aMaskId ID of the mask within aFile.

   343      */        

   344     inline void SetCommandL(

   345         TInt aCommandId, 

   346         const TDesC& aFile,

   347         TInt aBitmapId,

   348         TInt aMaskId);

   349 

   350     /**

   351      * Sets a command button's bitmap, mask and text. The bitmap and its mask are read 

   352      * from a multi bitmap file. The button to change is identified by its command ID.

   353      *

   354      * @param aCommandId Command ID of the button to change.

   355      * @param aText Text for the button.

   356      * @param aFile  A multi-bitmap file, containing mask and bitmap images.

   357      * @param aBitmapId ID of the bitmap within aFile.

   358      * @param aMaskId ID of the mask within aFile.

   359      */        

   360     inline void SetCommandL(

   361         TInt aCommandId, 

   362         const TDesC& aText,

   363         const TDesC& aFile,

   364         TInt aBitmapId,

   365         TInt aMaskId);

   366 

   367     /**

   368      * Initialises the group of command buttons from a resource.

   369      *

   370      * @param aResourceId ID of the resource structure specifying the command buttons.

   371      */        

   372     IMPORT_C void SetCommandSetL(

   373         TInt aResourceId);   

   374 

   375     /**

   376      * Adds a command button with a text label and command ID.

   377      *

   378      * @param aPosition The position in the button group for the new button.

   379      * @param aCommandId Command ID for the new button.

   380      * @param aText Text for the button.          

   381      */   

   382     inline void AddCommandL(

   383         TInt aPosition, 

   384         TInt aCommandId,

   385         const TDesC& aText);

   386 

   387     /**

   388      * Adds a command button with a bitmap label and command ID.

   389      *

   390      * @param aPosition The position in the button group for the new button.

   391      * @param aCommandId Command ID for the new button.

   392      * @param aBitmap Bitmap for the button.

   393      * @param aMask Mask bitmap for aBitmap.

   394      */        

   395     inline void AddCommandL(

   396         TInt aPosition, 

   397         TInt aCommandId,

   398         const CFbsBitmap& aBitmap,

   399         const CFbsBitmap& aMask);

   400 

   401     /**

   402      * Adds a command button with a command ID and a label containing both 

   403      * a bitmap and text.

   404      *

   405      * @param aPosition The position in the button group for the new button.

   406      * @param aCommandId Command ID for the new button.

   407      * @param aText Text for the button.

   408      * @param aBitmap Bitmap for the button.

   409      * @param aMask Mask bitmap for aBitmap.

   410      */        

   411     inline void AddCommandL(

   412         TInt aPosition, 

   413         TInt aCommandId,

   414         const TDesC& aText,

   415         const CFbsBitmap& aBitmap,

   416         const CFbsBitmap& aMask);

   417 

   418     /**

   419      * Adds a command button with a command ID and a bitmap which is read from a file.

   420      *

   421      * @param aPosition The position in the button group for the new button.

   422      * @param aCommandId Command ID for the new button.

   423      * @param aFile Multi-bitmap file containing the bitmap and mask.

   424      * @param aBitmapId ID of the bitmap within aFile.

   425      * @param aMaskId ID of the mask within aFile.

   426      */        

   427     inline void AddCommandL(

   428         TInt aPosition, 

   429         TInt aCommandId,

   430         const TDesC& aFile,

   431         TInt aBitmapId,

   432         TInt aMaskId);

   433 

   434     /**

   435      * Adds a command button with a command ID and a label containing both a bitmap 

   436      * and text. The bitmap and mask are read from file.

   437      *

   438      * @param aPosition The position in the button group for the new button.

   439      * @param aCommandId Command ID for the new button.

   440      * @param aText Text for the button.

   441      * @param aFile Multi-bitmap file containing the bitmap and mask.

   442      * @param aBitmapId ID of the bitmap within aFile.

   443      * @param aMaskId ID of the mask within aFile.

   444      */        

   445     inline void AddCommandL(

   446         TInt aPosition, 

   447         TInt aCommandId,

   448         const TDesC& aText,

   449         const TDesC& aFile,

   450         TInt aBitmapId,

   451         TInt aMaskId);

   452 

   453     /**

   454      * Pushes a command button with a text label and command ID onto a position's 

   455      * button stack. This function behaves similarly to SetCommandL() but allows 

   456      * the previous command button to be retrieved by calling RemoveCommandFromStack().

   457      *

   458      * @param aPosition The position in the button group at which to add the command button. 

   459      * @param aCommandId Command ID the button will send.

   460      * @param aText Text for the button.

   461      */        

   462     inline void AddCommandToStackL(

   463         TInt aPosition,

   464         TInt aCommandId,

   465         const TDesC& aText);

   466 

   467     /**

   468      * Pushes a command button with a bitmap, mask and command ID onto a position's 

   469      * button stack. This function behaves similarly to SetCommandL() but allows the 

   470      * previous command button to be retrieved by calling RemoveCommandFromStack(). 

   471      *

   472      * @param aPosition The position in the button group at which to add the command button.

   473      * @param aCommandId Command ID the button will send.

   474      * @param aBitmap Bitmap for the button.

   475      * @param aMask Mask bitmap for aBitmap.

   476      */        

   477     inline void AddCommandToStackL(

   478         TInt aPosition,

   479         TInt aCommandId,

   480         const CFbsBitmap& aBitmap,

   481         const CFbsBitmap& aMask);

   482 

   483     /**

   484      * Pushes a command button with text, bitmap, mask and a command ID onto a position's

   485      * button stack. This function behaves similarly to SetCommandL() but allows the 

   486      * previous command button to be retrieved by calling RemoveCommandFromStack().

   487      *

   488      * @param aPosition The position in the button group at which to add the command button.

   489      * @param aCommandId Command ID the button will send.

   490      * @param aText Text for the button.

   491      * @param aBitmap Bitmap for the button.

   492      * @param aMask Mask bitmap for aBitmap.

   493      */        

   494     inline void AddCommandToStackL(

   495         TInt aPosition,

   496         TInt aCommandId,

   497         const TDesC& aText,

   498         const CFbsBitmap& aBitmap,

   499         const CFbsBitmap& aMask);

   500 

   501     /**

   502      * Pushes a command button with a bitmap, mask and command ID onto a position's button 

   503      * stack. The bitmap and mask are read from a file. This function behaves similarly to 

   504      * SetCommandL() but allows the previous command button to be retrieved by calling 

   505      * RemoveCommandFromStack().

   506      *

   507      * @param aPosition The position in the button group at which to add the command button.

   508      * @param aCommandId Command ID the button will send.

   509      * @param aFile A multi-bitmap file containing mask and bitmap.

   510      * @param aBitmapId Index into the file of the bitmap.

   511      * @param aMaskId Index into the file of the bitmap mask.

   512      */        

   513     inline void AddCommandToStackL(

   514         TInt aPosition,

   515         TInt aCommandId,

   516         const TDesC& aFile,

   517         TInt aBitmapId,

   518         TInt aMaskId);

   519 

   520     /**

   521      * Pushes a command button with text, bitmap, mask and command button onto a position's 

   522      * button stack. The bitmap and mask are read from a file. This function behaves similarly

   523      * to SetCommandL() but allows the previous command button to be retrieved by calling 

   524      * RemoveCommandFromStack(). 

   525      *

   526      * @param aPosition The position in the button group at which to push the command button.

   527      * @param aCommandId Command ID the button will send.

   528      * @param aText Text for the button.

   529      * @param aFile A multi-bitmap file containing mask and bitmap.

   530      * @param aBitmapId Index into the file of the bitmap.

   531      * @param aMaskId Index into the file of the bitmap mask.

   532      */        

   533     inline void AddCommandToStackL(

   534         TInt aPosition,

   535         TInt aCommandId,

   536         const TDesC& aText,

   537         const TDesC& aFile,

   538         TInt aBitmapId,

   539         TInt aMaskId);

   540 

   541     /**

   542      * Pushes a command button onto a position's button stack. The text, bitmap, mask and 

   543      * command ID are all read from resource. This function behaves similarly to 

   544      * SetCommandL() but allows the previous command button to be retrieved by calling 

   545      * RemoveCommandFromStack().

   546      *

   547      * @param aPosition The position in the button group at which to push the command button.

   548      * @param aResourceId ID of a resource specifying the text, bitmaps and command ID.

   549      */        

   550     inline void AddCommandToStackL(

   551         TInt aPosition,

   552         TInt aResourceId);

   553 

   554     /**

   555      * As with SetCommandL() but for a set of buttons, also allows the previous command 

   556      * button to be retrieved by calling RemoveCommand().

   557      *

   558      * @param aResourceId Resource describing the set of command buttons.

   559      */        

   560     IMPORT_C void AddCommandSetToStackL(

   561         TInt aResourceId);

   562 

   563     /**

   564      * Removes the command identified by aCommandId, in position aPosition in the group,

   565      * from the command stack. Automatically retrieves the previous command details. 

   566      * Commands are added to the stack by calling AddCommandToStackL.

   567      *

   568      * @param aPosition The position in the button group from which to remove the 

   569      *                  command button.

   570      * @param aCommandId Command ID.

   571      */        

   572     IMPORT_C void RemoveCommandFromStack(TInt aPosition, TInt aCommandId);

   573 

   574     /**

   575      * Sets the default command ID for buttons in this container.

   576      *

   577      * @param aCommandId Command to issue if no other is specified.

   578      */    

   579     IMPORT_C void SetDefaultCommand(TInt aCommandId); 

   580 

   581     /**

   582      * Calculates minimum size required to display the buttons defined in the specified

   583      * resource structure.

   584      *

   585      * @param aResourceId The ID of the resource structure describing the button group.

   586      * @return Minimum size required to display the button group defined in the specified resource structure.

   587      */    

   588     IMPORT_C TSize CalcMinimumSizeL(TInt aResourceId) const;    

   589 

   590     /**

   591      * Places the command in position aPosition in the group on the cleanup stack. Typically 

   592      * used when a control or view changes the contents of two or more buttons on receipt of 

   593      * focus. After altering one command with a call to AddCommandToStackL() the push is made 

   594      * to guarantee the display will be left in a consistent state if the second (and any 

   595      * subsequent) calls to AddCommandToStackL() fail. Only a single command can be pushed 

   596      * for each position.

   597      *

   598      * @param aPosition Position in the container of the button to push.

   599      */    

   600     IMPORT_C void CleanupCommandPushL(TInt aPosition);

   601 

   602     /**

   603      * Removes a command from the cleanup stack without destroying it.

   604      */    

   605     inline void CleanupCommandPop();

   606 

   607     /**

   608      * Removes one or more commands from the cleanup stack without destroying them.

   609      *

   610      * @param aCount Number of commands to pop.

   611      */    

   612     IMPORT_C void CleanupCommandPop(TInt aCount);       

   613 

   614     /**

   615      * Removes a single command which was pushed onto the cleanup stack. It does this by 

   616      * calling CleanupCommandPushL(), rolling back to the previous details. The command

   617      * button popped is destroyed.

   618      */    

   619     inline void CleanupCommandPopAndDestroy();

   620 

   621     /**

   622      * Removes one or more commands which were pushed onto the cleanup stack. It does this 

   623      * by calling CleanupCommandPushL(), rolling back to the previous details. The command 

   624      * buttons popped are destroyed.

   625      *

   626      * @param aCount Number of commands to pop and destroy.

   627      */    

   628     inline void CleanupCommandPopAndDestroy(TInt aCount);   

   629 

   630     /**

   631      * Gets the maximum number of buttons that can be supported by the device.

   632      *

   633      * @return The number of command buttons supported.

   634      */    

   635     IMPORT_C TInt MaxCommands() const;

   636 

   637     /**

   638      * Gets the total number of buttons currently present in the group.

   639      *

   640      * @return The number of buttons.

   641      */    

   642     IMPORT_C TInt ButtonCount() const;

   643     

   644     /**

   645     * Dims (but doesn't draw) the button with id aCommandId if aDimmed is ETrue. If two 

   646     * buttons have the same id, the button to be dimmed is undefined.

   647     *

   648     * @param aCommandId The id for command to be dimmed.

   649     * @param aDimmed ETrue for dimming.

   650     */

   651     IMPORT_C void DimCommand(TInt aCommandId, TBool aDimmed);

   652     

   653     /**

   654     * Returns ETrue if the button with id aCommandId is dimmed. If two buttons have 

   655     * the same id, the results of this check are undefined.

   656     *

   657     * @param aCommandId The id for command to be checked.

   658     * @return The state of the button.    

   659     */

   660     IMPORT_C TBool IsCommandDimmed(TInt aCommandId) const;

   661     

   662     /**

   663     * Sets the the button with id aCommandId to be visible if aVisible is ETrue. If two 

   664     * buttons have the same id, the button to be altered is undefined.

   665     *

   666     * @param aCommandId The id for command to be made visible.

   667     * @param aVisible EFalse for making button invisible.

   668     */

   669     IMPORT_C void MakeCommandVisible(TInt aCommandId, TBool aVisible);

   670 

   671     /**

   672     * Returns ETrue if the button with id aCommandId is visible. If two buttons have 

   673     * the same id, the results are undefined.

   674     *

   675     * @param aCommandId The id for command to be checked.

   676     * @return The state of the button.     

   677     */

   678     IMPORT_C TBool IsCommandVisible(TInt aCommandId) const;

   679 

   680     /**

   681     * Animates the button with id aCommandId. If two buttons have the same id, the 

   682     * button to be animated is undefined.

   683     *

   684     * @since S60 3.1

   685     * @param aCommandId The id for command to be animated.   

   686     */

   687     IMPORT_C void AnimateCommand(TInt aCommandId);

   688     

   689     /**

   690     * Dims (but doesn't draw) the button with position aPosition.

   691     *

   692     * @since S60 3.1

   693     * @param aPosition The position for command to be dimmed.

   694     * @param aDimmed ETrue for dimming.

   695     */

   696     IMPORT_C void DimCommandByPosition(TCommandPosition aPosition, TBool aDimmed);

   697     

   698     /**

   699     * Returns ETrue if the button with position aPosition is dimmed.

   700     *

   701     * @since S60 3.1

   702     * @param aPosition The position for command to be checked.

   703     * @return The state of the button.    

   704     */

   705     IMPORT_C TBool IsCommandDimmedByPosition(TCommandPosition aPosition) const;

   706     

   707     /**

   708     * Sets the the button with position aPosition to be visible if aVisible is ETrue.

   709     *

   710     * @since S60 3.1

   711     * @param aPosition The position for command to be made visible.

   712     * @param aVisible EFalse for making button invisible.

   713     */

   714     IMPORT_C void MakeCommandVisibleByPosition(TCommandPosition aPosition, TBool aVisible);

   715     

   716     /**

   717     * Returns ETrue if the button with position aPosition is visible.

   718     *

   719     * @since S60 3.1

   720     * @param aPosition The position for command to be checked.

   721     * @return The state of the button.     

   722     */

   723     IMPORT_C TBool IsCommandVisibleByPosition(TCommandPosition aPosition) const;

   724     

   725     /**

   726     * Animates the button with position aPosition.

   727     *

   728     * @since S60 3.1

   729     * @param aPosition The position for command to be animated.    

   730     */

   731     IMPORT_C void AnimateCommandByPosition(TCommandPosition aPosition);

   732 

   733     /**

   734      * Gets the button group's location. Typically the button group is external to the 

   735      * view which is using it. In some cases, such as in dialogs with button panels, 

   736      * the button group is internal to the control which is using it.

   737      *

   738      * @return The button group's location.

   739      */  

   740     IMPORT_C TLocation Location() const;

   741     

   742     /**

   743      * Gets a pointer to the command button with the specified command Id.

   744      *

   745      * @param aCommandId Command ID of the button.

   746      * @return Pointer to the command button CEikCommandButton, NULL if there 

   747      *         was no button with Id aCommandId.

   748      */      

   749     IMPORT_C CEikCommandButton* CommandButtonOrNull(TInt aCommandId) const;

   750     

   751     /**

   752      * Sets the boundary rectangle for externally-positioned button groups. 

   753      * For use by EExternal button groups only.

   754      * 

   755      * @param aRect The boundary rectangle to use. The button group attaches 

   756      *              itself to the inside of this rectangle.

   757      */    

   758     IMPORT_C void SetBoundingRect(const TRect& aRect);

   759 

   760     /**

   761      * Subtracts the area occupied by the button group from the specified bounding 

   762      * rectangle. This method should be used in preference to querying the container's 

   763      * area at all times. For use by EExternal button groups only.

   764      * 

   765      * @param aBoundingRect Rectangle to be modified.

   766      */        

   767     IMPORT_C void ReduceRect(TRect& aBoundingRect) const;

   768 

   769     /**

   770      * Gets a pointer to the control (button) with the specified command ID. 

   771      * This method is intended to allow access to standard CCoeControl functionality 

   772      * only. Casting the return value is likely to fail on different devices.

   773      *

   774      * @param aCommandId Command ID of the button to get.

   775      * @return Pointer to a CCoeControl, NULL if there was no button at aCommandId.

   776      */

   777     IMPORT_C CCoeControl* ControlOrNull(TInt aCommandId) const;

   778     

   779     /**

   780      * Gets a pointer to the the button with the specified command Id.

   781      *

   782      * @param aCommandId Command ID of the button to obtain.

   783      * @return The button object.

   784      */    

   785     IMPORT_C CEikCommandButton* ButtonById(TInt aCommandId) const;

   786     

   787     /**

   788      * Gets the position in the group of the button with the specified command Id.

   789      * The return value is undefined if two buttons share the same id.

   790      *

   791      * @param aCommandId Identifies the command.

   792      * @return The command's container position.

   793      */     

   794     IMPORT_C TInt PositionById(TInt aCommandId) const;

   795     

   796     /**

   797      * Updates a command's hotkey and whether the key is displayed. 

   798      * This function is only supported by containers being used for dialog buttons.

   799      *

   800      * @param aCommandId Identifies the command to update.

   801      * @param aFlags Whether to display the hotkey.

   802      * @param aKeyId Hotkey identifier.

   803      */    

   804     IMPORT_C void UpdateHotKey(TInt aCommandId, THotKeyFlags aFlags, TInt aKeyId);

   805     

   806     /**

   807      * Changes the command observer for the button at aPos to aCommandObserver. 

   808      * Panics if an updated observer is already present. This function should be followed 

   809      * by RemoveCommandObserver() when you need to put back the original observer.

   810      *

   811      * @param aPos The button's position.

   812      * @param aCommandObserver The command observer.

   813      */    

   814     IMPORT_C void UpdateCommandObserverL(TInt aPos, MEikCommandObserver& aCommandObserver);

   815     

   816     /**

   817      * Removes the temporary observer for the button at aPos, replacing it with the

   818      * observer that was present when UpdateCommandObserverL() was called.

   819      *

   820      * @param aPos The button's position.

   821      */    

   822     IMPORT_C void RemoveCommandObserver(TInt aPos);

   823     

   824     /**

   825      * Checks for existence of updated command observer for the button at aPosition.

   826      *

   827      * @since S60 3.2

   828      * @param aPosition The position for button to be checked.

   829      * @return ETrue, if updated command observer exists.

   830      */    

   831     IMPORT_C TBool UpdatedCommandObserverExists(TCommandPosition aPosition) const;

   832     

   833     /**

   834      * Tests whether the button group has explicitly been instructed to suppress redraws.

   835      * Some button groups may not activate themselves during construction, in which 

   836      * case, they need to be activated by the client. This method allows the client 

   837      * to enquire whether this is necessary.

   838      *

   839      * @return ETrue if the button group will suppress redraws, otherwise EFalse.

   840      */    

   841     IMPORT_C TBool DelayActivation() const;

   842     

   843     /**

   844      * Returns the container's button group.

   845      *

   846      * @return Pointer to the button group object. Ownership is not transferred.

   847      */    

   848     inline MEikButtonGroup* ButtonGroup();

   849     

   850     /**

   851      * Returns the button group type.

   852      *

   853      * @return The button group type.

   854      */    

   855     inline TUse ButtonGroupType();

   856     

   857     /**

   858     * Internal method for setting markable list's MSK observer.

   859     * This observer is called before default CBA observer if MSK is pressed.

   860     * Observer is removed by passing NULL as parameter.

   861     *

   862     * @since S60 3.1

   863     * @param aMSKObserverOwner

   864     * @param aCommandObserver

   865     */

   866     void UpdateMSKCommandObserver(

   867         CEikListBox* aMSKObserverOwner, 

   868         MEikCommandObserver* aCommandObserver);

   869     

   870 public: // From CCoeControl.

   871     /**

   872      * From CCoeControl.

   873      * Gets the control's minimum required size.

   874      *

   875      * @return The minimum size required by the control.

   876      */ 

   877     IMPORT_C TSize MinimumSize();

   878     

   879     /**

   880      * From CCoeControl.

   881      * Handles key events.

   882      *

   883      * @param aKeyEvent The key event. 

   884      * @param aType The type of key event: EEventKey, EEventKeyUp or EEventKeyDown. 

   885      * @return Indicates whether or not the key event was used by this control. 

   886      */     

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

   888     

   889     /**

   890      * From CCoeControl.

   891      * Sets this control as visible or invisible.

   892      *

   893      * @param aVisible ETrue to make the control visible, EFalse to make it invisible. 

   894      */     

   895     void MakeVisible(TBool aVisible);

   896     

   897     /**

   898      * From CCoeControl.

   899      * Writes the internal state of the control and its components to aStream.

   900      * Does nothing in release mode.

   901      *

   902      * @param aWriteStream The output stream.

   903      */     

   904     IMPORT_C void WriteInternalStateL(RWriteStream& aWriteStream) const;

   905     

   906 public:

   907     /**

   908      * Formerly from MTopSetMember<CEikButtonGroupContainer>, now reserved.

   909      */ 

   910     IMPORT_C virtual void Reserved_MtsmPosition();

   911     

   912     /**

   913      * Formerly from MTopSetMember<CEikButtonGroupContainer>, now reserved.

   914      */     

   915     IMPORT_C virtual void Reserved_MtsmObject();

   916 

   917 public: // New functions for enhanced cba support.

   918     /**

   919      * Used to offer list of commands for softkeys.

   920      *

   921      * @since S60 3.2

   922      * @param aCommandList A list of command ids to be offered for softkeys.

   923      */

   924     IMPORT_C void OfferCommandListL(const RArray<TInt>& aCommandList);

   925     

   926     /**

   927      * Used to offer list of commands for softkeys.

   928      *

   929      * @since S60 3.2

   930      * @param aResourceId Id for CBA resource that defines enhanced cba buttons.

   931      */ 

   932     IMPORT_C void OfferCommandListL(const TInt aResourceId);

   933 

   934     /**

   935      * Used to check if a certain command have been approved to the current command set

   936      *

   937      * @since S60 3.2

   938      * @param aCommandId The id for command which existence should be checked.

   939      * @return ETrue if command is in control group, otherwise EFalse.

   940      */     

   941     IMPORT_C TBool IsCommandInGroup(const TInt aCommandId) const;

   942     

   943     /**

   944      * Replaces command with another.

   945      *

   946      * @since S60 3.2 

   947      * @param aCommandId Id for command that should be replaced.

   948      * @param aResourceId Resource id for new enhanced cba button.

   949      */     

   950     IMPORT_C void ReplaceCommand(const TInt aCommandId, const TInt aResourceId);

   951 

   952 private:

   953     enum TCommandOp {ESet, EAdd, EPush};

   954     

   955 private:

   956     class TCmdPos

   957         {

   958     public:

   959         inline TCmdPos();

   960         inline TCmdPos(TInt aPos, TInt aCmd);

   961     public:

   962         TInt iPos;

   963         TInt iCmd;

   964         };

   965         

   966     class TCmdObserver

   967         {

   968     public:

   969         inline TCmdObserver(TInt aPos, MEikCommandObserver& aObserver);

   970     public:

   971         TInt iPos;

   972         MEikCommandObserver& iObserver;

   973         };

   974         

   975     class CCmdObserverArray : public CArrayFixFlat<TCmdObserver>

   976         {

   977     public:

   978         inline CCmdObserverArray();

   979         TInt FindIndex(TInt aPos);

   980         };

   981         

   982 private:

   983     CEikButtonGroupContainer(TUse aUse);

   984     

   985     void ConstructL(

   986         TOrientation aOrientation,

   987         MEikCommandObserver* aCommandObserver,

   988         TInt aResourceId,

   989         RWindowGroup* aParentWg,

   990         TUint aFlags);

   991         

   992     IMPORT_C void DoSetCommandL(

   993         TInt aPosition,

   994         TInt aCommandId,

   995         const TDesC* aText,

   996         const CFbsBitmap* aBitmap,

   997         const CFbsBitmap* aMask,

   998         TCommandOp aOp);

   999         

  1000     IMPORT_C void DoSetCommandL(

  1001         TInt aPosition,

  1002         TInt aCommandId,

  1003         const TDesC* aText,

  1004         const TDesC& aFile,

  1005         TInt aBitmapId,

  1006         TInt aMaskId,

  1007         TCommandOp aOp);

  1008         

  1009     IMPORT_C void DoSetCommandL(

  1010         TInt aCommandId,

  1011         const TDesC* aText,

  1012         const CFbsBitmap* aBitmap,

  1013         const CFbsBitmap* aMask,

  1014         TCommandOp aOp);

  1015         

  1016     IMPORT_C void DoSetCommandL(

  1017         TInt aCommandId,

  1018         const TDesC* aText,

  1019         const TDesC& aFile,

  1020         TInt aBitmapId,

  1021         TInt aMaskId,

  1022         TCommandOp aOp);

  1023         

  1024     IMPORT_C void DoSetCommandL(

  1025         TInt aPosition,

  1026         TInt aResourceId,

  1027         TCommandOp aOp);

  1028     

  1029     inline CCoeControl* ButtonGroupAsControl() const;

  1030     void UpdateRect();

  1031     static void CleanupCommandDestroy(TAny* aPtr);

  1032     TCmdPos DoCleanupCommandPop();

  1033     void DoCleanupCommandPopAndDestroy();

  1034 

  1035 private: // from CCoeControl

  1036     TInt CountComponentControls() const;

  1037     CCoeControl* ComponentControl(TInt aIndex) const;

  1038     void SizeChanged();

  1039 

  1040 private: // from MEikCommandObserver

  1041     void ProcessCommandL(TInt aCommandId);

  1042     CCoeControl* CreateCustomCommandControlL(TInt aControlType);

  1043 

  1044 private:

  1045     MEikButtonGroup* iButtonGroup;

  1046     TUse iUse;

  1047     CArrayFix<TCmdPos>* iCommandsCleanup;

  1048     MEikCommandObserver* iCommandObserver;

  1049     CCmdObserverArray* iObserverArray;

  1050     TDblQueLink iBtLink;

  1051     CEikListBox* iMSKObserverOwner;

  1052     TInt iSpare;

  1053 

  1054 private:

  1055     friend class CCmdObserverArray;

  1056     friend class CEikButtonGroupStack;

  1057     };

  1058 

  1059 

  1060 // Inline function implementations.

  1061 

  1062 inline void CEikButtonGroupContainer::SetCommandL(

  1063     TInt aPosition,

  1064     TInt aCommandId,

  1065     const TDesC& aText)

  1066     {

  1067     DoSetCommandL(aPosition, aCommandId, &aText, NULL, NULL, ESet);

  1068     }

  1069 

  1070 inline void CEikButtonGroupContainer::SetCommandL(

  1071     TInt aPosition,

  1072     TInt aCommandId,

  1073     const CFbsBitmap& aBitmap,

  1074     const CFbsBitmap& aMask)

  1075     {

  1076     DoSetCommandL(aPosition, aCommandId, NULL, &aBitmap, &aMask, ESet);

  1077     }

  1078 

  1079 inline void CEikButtonGroupContainer::SetCommandL(

  1080     TInt aPosition,

  1081     TInt aCommandId,

  1082     const TDesC& aText,

  1083     const CFbsBitmap& aBitmap,

  1084     const CFbsBitmap& aMask)

  1085     {

  1086     DoSetCommandL(aPosition, aCommandId, &aText, &aBitmap, &aMask, ESet);

  1087     }

  1088 

  1089 inline void CEikButtonGroupContainer::SetCommandL(

  1090     TInt aPosition,

  1091     TInt aCommandId,

  1092     const TDesC& aFile,

  1093     TInt aBitmapId,

  1094     TInt aMaskId)

  1095     {

  1096     DoSetCommandL(aPosition, aCommandId, NULL, aFile, aBitmapId, aMaskId, ESet);

  1097     }

  1098 

  1099 inline void CEikButtonGroupContainer::SetCommandL(

  1100     TInt aPosition,

  1101     TInt aCommandId,

  1102     const TDesC& aText,

  1103     const TDesC& aFile,

  1104     TInt aBitmapId,

  1105     TInt aMaskId)

  1106     {

  1107     DoSetCommandL(aPosition, aCommandId, &aText, aFile, aBitmapId, aMaskId, ESet);

  1108     }

  1109 

  1110 inline void CEikButtonGroupContainer::SetCommandL(

  1111     TInt aPosition,

  1112     TInt aResourceId)

  1113     {

  1114     DoSetCommandL(aPosition, aResourceId, ESet);

  1115     }

  1116 

  1117 inline void CEikButtonGroupContainer::SetCommandL(

  1118     TInt aCommandId,

  1119     const TDesC& aText)

  1120     {

  1121     DoSetCommandL(aCommandId, &aText, NULL, NULL, ESet);

  1122     }

  1123 

  1124 inline void CEikButtonGroupContainer::SetCommandL(

  1125     TInt aCommandId,

  1126     const CFbsBitmap& aBitmap,

  1127     const CFbsBitmap& aMask)

  1128     {

  1129     DoSetCommandL(aCommandId, NULL, &aBitmap, &aMask, ESet);

  1130     }

  1131 

  1132 inline void CEikButtonGroupContainer::SetCommandL(

  1133     TInt aCommandId,

  1134     const TDesC& aText,