epoc32/include/mw/eikbtgpc.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100 (2010-03-31)
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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 "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:  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         EIsEmbedded      = 0x08, ///< Embedded in a dialog or popup.
   105         EParentIsControl = 0x10  ///< Parent window group is treated as CCoeControl.
   106         };
   107         
   108     /**
   109      * Defines the positions for each command.   
   110      */   
   111     enum TCommandPosition
   112         {
   113         ELeftSoftkeyPosition    = 0, ///< Position for left softkey.
   114         ERightSoftkeyPosition   = 2, ///< Position for right softkey.
   115         EMiddleSoftkeyPosition  = 3  ///< Position for middle softkey.
   116         };
   117         
   118 public:
   119     /**
   120      * Creates a button group container in its own window.
   121      *
   122      * @param aUse The button group's type. 
   123      * @param aOrientation The button group's orientation. You need specify this 
   124      *                     only for devices that can layout their buttons either 
   125      *                     horizontally or vertically.
   126      * @param aCommandObserver A command observer to be notified of commands on 
   127      *                         the container.
   128      * @param aResourceId A resource containing descriptions of buttons in the group. 
   129      *                    This can be NULL if buttons are to be added dynamically.
   130      * @param aFlags The button group's flags.
   131      * @return Button group container object.
   132      */ 
   133     IMPORT_C static CEikButtonGroupContainer* NewL(
   134         TUse aUse,
   135         TOrientation aOrientation,
   136         MEikCommandObserver* aCommandObserver,
   137         TInt aResourceId,
   138         TUint aFlags = EAddToStack);
   139 
   140     /**
   141      * Creates a button group container in its parent control's window.
   142      *
   143      * @param aUse The button group's type.
   144      * @param aOrientation The button group's orientation. You need specify this 
   145      *                     only for devices that can layout their buttons either 
   146      *                     horizontally or vertically.
   147      * @param aCommandObserver A command observer to be notified of commands on 
   148      *                         the container.
   149      * @param aResourceId A resource containing descriptions of buttons in the group. 
   150      *                    This can be NULL if buttons are to be added dynamically.
   151      * @param aParent The control's parent.
   152      * @param aFlags The button group's flags.
   153      * @return Button group container object.
   154      */         
   155     IMPORT_C static CEikButtonGroupContainer* NewL(
   156         TUse aUse,
   157         TOrientation aOrientation,
   158         MEikCommandObserver* aCommandObserver,
   159         TInt aResourceId,
   160         const CCoeControl& aParent,
   161         TUint aFlags = EAddToStack);
   162 
   163     /**
   164      * Creates a button group container in given window group.
   165      *
   166      * @param aUse The button group's type.
   167      * @param aOrientation The button group's orientation. You need specify this 
   168      *                     only for devices that can layout their buttons either 
   169      *                     horizontally or vertically.
   170      * @param aCommandObserver A command observer to be notified of commands on 
   171      *                         the container.
   172      * @param aResourceId A resource containing descriptions of buttons in the group. 
   173      *                    This can be NULL if buttons are to be added dynamically.
   174      * @param aParentWg The parent window group.
   175      * @param aFlags The button group's flags.
   176      * @return Button group container object.
   177      */        
   178     IMPORT_C static CEikButtonGroupContainer* NewL(
   179         TUse aUse,
   180         TOrientation aOrientation,
   181         MEikCommandObserver* aCommandObserver,
   182         TInt aResourceId,
   183         RWindowGroup& aParentWg,
   184         TUint aFlags = EAddToStack);
   185 
   186     /**
   187      * Destructor.
   188      */        
   189     IMPORT_C ~CEikButtonGroupContainer();
   190 
   191     /**
   192      * Gets a pointer to an application's currently active CEikButtonGroupContainer (if any).
   193      *
   194      * Returns NULL if there are no containers active or none suitable for sharing. 
   195      * Ownership of the returned pointer is not transferred.
   196      *
   197      * @return Pointer to the button group container.
   198      */    
   199     IMPORT_C static CEikButtonGroupContainer* Current();
   200     
   201 public:
   202     /**
   203      * Sets a command button's text label and command ID.
   204      *
   205      * @param aPosition The position within the button group of the button to change.
   206      *                  If the position is out of range this function raises a panic.
   207      * @param aCommandId Command ID the button will send.
   208      * @param aText Text for the button.
   209      */
   210     inline void SetCommandL(
   211         TInt aPosition, 
   212         TInt aCommandId, 
   213         const TDesC& aText);
   214 
   215     /**
   216      * Sets a command button's bitmap and command ID.
   217      *
   218      * @param aPosition The position within the button group of the button to change. 
   219      *                  If the position is out of range this function raises a panic.
   220      * @param aCommandId Command ID the button will send.
   221      * @param aBitmap The bitmap for the button.
   222      * @param aMask The mask bitmap for aBitmap.
   223      */    
   224     inline void SetCommandL(
   225         TInt aPosition, 
   226         TInt aCommandId, 
   227         const CFbsBitmap& aBitmap,
   228         const CFbsBitmap& aMask);
   229 
   230     /**
   231      * Sets a command button's bitmap, text and command ID.
   232      *
   233      * @param aPosition The position within the button group of the button to change. 
   234      *                  If the position is out of range, the function raises a panic.
   235      * @param aCommandId Command ID the button will send.
   236      * @param aText The text for the button.
   237      * @param aBitmap The bitmap for the button.
   238      * @param aMask The mask bitmap for aBitmap.
   239      */        
   240     inline void SetCommandL(
   241         TInt aPosition, 
   242         TInt aCommandId, 
   243         const TDesC& aText,
   244         const CFbsBitmap& aBitmap,
   245         const CFbsBitmap& aMask);
   246 
   247     /**
   248      * Sets a command button's bitmap and command ID. The bitmap and its mask are read
   249      * from a file.
   250      *
   251      * @param aPosition The position within the button group of the button to change.
   252      *                  If the position is out of range, the function raises a panic.
   253      * @param aCommandId Command ID the button will send.
   254      * @param aFile A multi-bitmap file, containing mask and bitmap images.
   255      * @param aBitmapId ID of the bitmap within aFile.
   256      * @param aMaskId ID of the mask within aFile.
   257      */        
   258     inline void SetCommandL(
   259         TInt aPosition, 
   260         TInt aCommandId, 
   261         const TDesC& aFile,
   262         TInt aBitmapId,
   263         TInt aMaskId);
   264 
   265     /**
   266      * Sets a command button's bitmap, text label and command ID. The bitmap and its 
   267      * mask are read from a file.
   268      *
   269      * @param aPosition The position within the button group of the button to change.
   270      *                  If the position is out of range, the function raises a panic.
   271      * @param aCommandId Command ID the button will send.
   272      * @param aText The text for the button.
   273      * @param aFile A multi-bitmap file, containing mask and bitmap images.
   274      * @param aBitmapId ID of the bitmap within aFile.
   275      * @param aMaskId ID of the mask within aFile.
   276      */        
   277     inline void SetCommandL(
   278         TInt aPosition, 
   279         TInt aCommandId, 
   280         const TDesC& aText,
   281         const TDesC& aFile,
   282         TInt aBitmapId,
   283         TInt aMaskId);
   284 
   285     /**
   286      * Sets a command button's bitmap, text label and command ID. The bitmap, mask,
   287      * text and command ID are all read from resource.
   288      *
   289      * @param aPosition The position within the button group of the button to change.
   290      *                  If the position is out of range, the function raises a panic.
   291      * @param aResourceId Resource ID specifying the text, bitmaps and command ID.
   292      */        
   293     inline void SetCommandL(
   294         TInt aPosition, 
   295         TInt aResourceId);
   296 
   297     /**
   298      * Sets a command button's text. The button to change is identified by its command ID.
   299      *
   300      * @param aCommandId Command ID of the button to change.
   301      * @param aText The text for the button.
   302      * @leave KErrNotFound The ID cannot be matched to any button.
   303      */        
   304     inline void SetCommandL(
   305         TInt aCommandId, 
   306         const TDesC& aText);
   307 
   308     /**
   309      * Sets a command button's bitmap and mask. The button to change is identified 
   310      * by its command ID.
   311      *
   312      * @param aCommandId Command ID of the button to change.
   313      * @param aBitmap Bitmap for the button.
   314      * @param aMask Mask bitmap for aBitmap.
   315      * @leave KErrNotFound The ID cannot be matched to any button.
   316      */        
   317     inline void SetCommandL(
   318         TInt aCommandId, 
   319         const CFbsBitmap& aBitmap,
   320         const CFbsBitmap& aMask);
   321 
   322     /**
   323      * Sets a command button's bitmap, mask and text. The button to change is 
   324      * identified by its command ID.
   325      *
   326      * @param aCommandId Command ID of the button to change.
   327      * @param aText Text for the button.
   328      * @param aBitmap Bitmap for the button.
   329      * @param aMask Mask bitmap for aBitmap.
   330      */        
   331     inline void SetCommandL(
   332         TInt aCommandId, 
   333         const TDesC& aText,
   334         const CFbsBitmap& aBitmap,
   335         const CFbsBitmap& aMask);
   336 
   337     /**
   338      * Sets a command button's bitmap and mask. The bitmap and mask are read from 
   339      * a multi bitmap file. The button to change is identified by its command ID.
   340      *
   341      * @param aCommandId Command ID of the button to change.
   342      * @param aFile A multi-bitmap file, containing mask and bitmap images.
   343      * @param aBitmapId ID of the bitmap within aFile.
   344      * @param aMaskId ID of the mask within aFile.
   345      */        
   346     inline void SetCommandL(
   347         TInt aCommandId, 
   348         const TDesC& aFile,
   349         TInt aBitmapId,
   350         TInt aMaskId);
   351 
   352     /**
   353      * Sets a command button's bitmap, mask and text. The bitmap and its mask are read 
   354      * from a multi bitmap file. The button to change is identified by its command ID.
   355      *
   356      * @param aCommandId Command ID of the button to change.
   357      * @param aText Text for the button.
   358      * @param aFile  A multi-bitmap file, containing mask and bitmap images.
   359      * @param aBitmapId ID of the bitmap within aFile.
   360      * @param aMaskId ID of the mask within aFile.
   361      */        
   362     inline void SetCommandL(
   363         TInt aCommandId, 
   364         const TDesC& aText,
   365         const TDesC& aFile,
   366         TInt aBitmapId,
   367         TInt aMaskId);
   368 
   369     /**
   370      * Initialises the group of command buttons from a resource.
   371      *
   372      * @param aResourceId ID of the resource structure specifying the command buttons.
   373      */        
   374     IMPORT_C void SetCommandSetL(
   375         TInt aResourceId);   
   376 
   377     /**
   378      * Adds a command button with a text label and command ID.
   379      *
   380      * @param aPosition The position in the button group for the new button.
   381      * @param aCommandId Command ID for the new button.
   382      * @param aText Text for the button.          
   383      */   
   384     inline void AddCommandL(
   385         TInt aPosition, 
   386         TInt aCommandId,
   387         const TDesC& aText);
   388 
   389     /**
   390      * Adds a command button with a bitmap label and command ID.
   391      *
   392      * @param aPosition The position in the button group for the new button.
   393      * @param aCommandId Command ID for the new button.
   394      * @param aBitmap Bitmap for the button.
   395      * @param aMask Mask bitmap for aBitmap.
   396      */        
   397     inline void AddCommandL(
   398         TInt aPosition, 
   399         TInt aCommandId,
   400         const CFbsBitmap& aBitmap,
   401         const CFbsBitmap& aMask);
   402 
   403     /**
   404      * Adds a command button with a command ID and a label containing both 
   405      * a bitmap and text.
   406      *
   407      * @param aPosition The position in the button group for the new button.
   408      * @param aCommandId Command ID for the new button.
   409      * @param aText Text for the button.
   410      * @param aBitmap Bitmap for the button.
   411      * @param aMask Mask bitmap for aBitmap.
   412      */        
   413     inline void AddCommandL(
   414         TInt aPosition, 
   415         TInt aCommandId,
   416         const TDesC& aText,
   417         const CFbsBitmap& aBitmap,
   418         const CFbsBitmap& aMask);
   419 
   420     /**
   421      * Adds a command button with a command ID and a bitmap which is read from a file.
   422      *
   423      * @param aPosition The position in the button group for the new button.
   424      * @param aCommandId Command ID for the new button.
   425      * @param aFile Multi-bitmap file containing the bitmap and mask.
   426      * @param aBitmapId ID of the bitmap within aFile.
   427      * @param aMaskId ID of the mask within aFile.
   428      */        
   429     inline void AddCommandL(
   430         TInt aPosition, 
   431         TInt aCommandId,
   432         const TDesC& aFile,
   433         TInt aBitmapId,
   434         TInt aMaskId);
   435 
   436     /**
   437      * Adds a command button with a command ID and a label containing both a bitmap 
   438      * and text. The bitmap and mask are read from file.
   439      *
   440      * @param aPosition The position in the button group for the new button.
   441      * @param aCommandId Command ID for the new button.
   442      * @param aText Text for the button.
   443      * @param aFile Multi-bitmap file containing the bitmap and mask.
   444      * @param aBitmapId ID of the bitmap within aFile.
   445      * @param aMaskId ID of the mask within aFile.
   446      */        
   447     inline void AddCommandL(
   448         TInt aPosition, 
   449         TInt aCommandId,
   450         const TDesC& aText,
   451         const TDesC& aFile,
   452         TInt aBitmapId,
   453         TInt aMaskId);
   454 
   455     /**
   456      * Pushes a command button with a text label and command ID onto a position's 
   457      * button stack. This function behaves similarly to SetCommandL() but allows 
   458      * the previous command button to be retrieved by calling RemoveCommandFromStack().
   459      *
   460      * @param aPosition The position in the button group at which to add the command button. 
   461      * @param aCommandId Command ID the button will send.
   462      * @param aText Text for the button.
   463      */        
   464     inline void AddCommandToStackL(
   465         TInt aPosition,
   466         TInt aCommandId,
   467         const TDesC& aText);
   468 
   469     /**
   470      * Pushes a command button with a bitmap, mask and command ID onto a position's 
   471      * button stack. This function behaves similarly to SetCommandL() but allows the 
   472      * previous command button to be retrieved by calling RemoveCommandFromStack(). 
   473      *
   474      * @param aPosition The position in the button group at which to add the command button.
   475      * @param aCommandId Command ID the button will send.
   476      * @param aBitmap Bitmap for the button.
   477      * @param aMask Mask bitmap for aBitmap.
   478      */        
   479     inline void AddCommandToStackL(
   480         TInt aPosition,
   481         TInt aCommandId,
   482         const CFbsBitmap& aBitmap,
   483         const CFbsBitmap& aMask);
   484 
   485     /**
   486      * Pushes a command button with text, bitmap, mask and a command ID onto a position's
   487      * button stack. This function behaves similarly to SetCommandL() but allows the 
   488      * previous command button to be retrieved by calling RemoveCommandFromStack().
   489      *
   490      * @param aPosition The position in the button group at which to add the command button.
   491      * @param aCommandId Command ID the button will send.
   492      * @param aText Text for the button.
   493      * @param aBitmap Bitmap for the button.
   494      * @param aMask Mask bitmap for aBitmap.
   495      */        
   496     inline void AddCommandToStackL(
   497         TInt aPosition,
   498         TInt aCommandId,
   499         const TDesC& aText,
   500         const CFbsBitmap& aBitmap,
   501         const CFbsBitmap& aMask);
   502 
   503     /**
   504      * Pushes a command button with a bitmap, mask and command ID onto a position's button 
   505      * stack. The bitmap and mask are read from a file. This function behaves similarly to 
   506      * SetCommandL() but allows the previous command button to be retrieved by calling 
   507      * RemoveCommandFromStack().
   508      *
   509      * @param aPosition The position in the button group at which to add the command button.
   510      * @param aCommandId Command ID the button will send.
   511      * @param aFile A multi-bitmap file containing mask and bitmap.
   512      * @param aBitmapId Index into the file of the bitmap.
   513      * @param aMaskId Index into the file of the bitmap mask.
   514      */        
   515     inline void AddCommandToStackL(
   516         TInt aPosition,
   517         TInt aCommandId,
   518         const TDesC& aFile,
   519         TInt aBitmapId,
   520         TInt aMaskId);
   521 
   522     /**
   523      * Pushes a command button with text, bitmap, mask and command button onto a position's 
   524      * button stack. The bitmap and mask are read from a file. This function behaves similarly
   525      * to SetCommandL() but allows the previous command button to be retrieved by calling 
   526      * RemoveCommandFromStack(). 
   527      *
   528      * @param aPosition The position in the button group at which to push the command button.
   529      * @param aCommandId Command ID the button will send.
   530      * @param aText Text for the button.
   531      * @param aFile A multi-bitmap file containing mask and bitmap.
   532      * @param aBitmapId Index into the file of the bitmap.
   533      * @param aMaskId Index into the file of the bitmap mask.
   534      */        
   535     inline void AddCommandToStackL(
   536         TInt aPosition,
   537         TInt aCommandId,
   538         const TDesC& aText,
   539         const TDesC& aFile,
   540         TInt aBitmapId,
   541         TInt aMaskId);
   542 
   543     /**
   544      * Pushes a command button onto a position's button stack. The text, bitmap, mask and 
   545      * command ID are all read from resource. This function behaves similarly to 
   546      * SetCommandL() but allows the previous command button to be retrieved by calling 
   547      * RemoveCommandFromStack().
   548      *
   549      * @param aPosition The position in the button group at which to push the command button.
   550      * @param aResourceId ID of a resource specifying the text, bitmaps and command ID.
   551      */        
   552     inline void AddCommandToStackL(
   553         TInt aPosition,
   554         TInt aResourceId);
   555 
   556     /**
   557      * As with SetCommandL() but for a set of buttons, also allows the previous command 
   558      * button to be retrieved by calling RemoveCommand().
   559      *
   560      * @param aResourceId Resource describing the set of command buttons.
   561      */        
   562     IMPORT_C void AddCommandSetToStackL(
   563         TInt aResourceId);
   564 
   565     /**
   566      * Removes the command identified by aCommandId, in position aPosition in the group,
   567      * from the command stack. Automatically retrieves the previous command details. 
   568      * Commands are added to the stack by calling AddCommandToStackL.
   569      *
   570      * @param aPosition The position in the button group from which to remove the 
   571      *                  command button.
   572      * @param aCommandId Command ID.
   573      */        
   574     IMPORT_C void RemoveCommandFromStack(TInt aPosition, TInt aCommandId);
   575 
   576     /**
   577      * Sets the default command ID for buttons in this container.
   578      *
   579      * @param aCommandId Command to issue if no other is specified.
   580      */    
   581     IMPORT_C void SetDefaultCommand(TInt aCommandId); 
   582 
   583     /**
   584      * Calculates minimum size required to display the buttons defined in the specified
   585      * resource structure.
   586      *
   587      * @param aResourceId The ID of the resource structure describing the button group.
   588      * @return Minimum size required to display the button group defined in the specified resource structure.
   589      */    
   590     IMPORT_C TSize CalcMinimumSizeL(TInt aResourceId) const;    
   591 
   592     /**
   593      * Places the command in position aPosition in the group on the cleanup stack. Typically 
   594      * used when a control or view changes the contents of two or more buttons on receipt of 
   595      * focus. After altering one command with a call to AddCommandToStackL() the push is made 
   596      * to guarantee the display will be left in a consistent state if the second (and any 
   597      * subsequent) calls to AddCommandToStackL() fail. Only a single command can be pushed 
   598      * for each position.
   599      *
   600      * @param aPosition Position in the container of the button to push.
   601      */    
   602     IMPORT_C void CleanupCommandPushL(TInt aPosition);
   603 
   604     /**
   605      * Removes a command from the cleanup stack without destroying it.
   606      */    
   607     inline void CleanupCommandPop();
   608 
   609     /**
   610      * Removes one or more commands from the cleanup stack without destroying them.
   611      *
   612      * @param aCount Number of commands to pop.
   613      */    
   614     IMPORT_C void CleanupCommandPop(TInt aCount);       
   615 
   616     /**
   617      * Removes a single command which was pushed onto the cleanup stack. It does this by 
   618      * calling CleanupCommandPushL(), rolling back to the previous details. The command
   619      * button popped is destroyed.
   620      */    
   621     inline void CleanupCommandPopAndDestroy();
   622 
   623     /**
   624      * Removes one or more commands which were pushed onto the cleanup stack. It does this 
   625      * by calling CleanupCommandPushL(), rolling back to the previous details. The command 
   626      * buttons popped are destroyed.
   627      *
   628      * @param aCount Number of commands to pop and destroy.
   629      */    
   630     inline void CleanupCommandPopAndDestroy(TInt aCount);   
   631 
   632     /**
   633      * Gets the maximum number of buttons that can be supported by the device.
   634      *
   635      * @return The number of command buttons supported.
   636      */    
   637     IMPORT_C TInt MaxCommands() const;
   638 
   639     /**
   640      * Gets the total number of buttons currently present in the group.
   641      *
   642      * @return The number of buttons.
   643      */    
   644     IMPORT_C TInt ButtonCount() const;
   645     
   646     /**
   647     * Dims (but doesn't draw) the button with id aCommandId if aDimmed is ETrue. If two 
   648     * buttons have the same id, the button to be dimmed is undefined.
   649     *
   650     * @param aCommandId The id for command to be dimmed.
   651     * @param aDimmed ETrue for dimming.
   652     */
   653     IMPORT_C void DimCommand(TInt aCommandId, TBool aDimmed);
   654     
   655     /**
   656     * Returns ETrue if the button with id aCommandId is dimmed. If two buttons have 
   657     * the same id, the results of this check are undefined.
   658     *
   659     * @param aCommandId The id for command to be checked.
   660     * @return The state of the button.    
   661     */
   662     IMPORT_C TBool IsCommandDimmed(TInt aCommandId) const;
   663     
   664     /**
   665     * Sets the the button with id aCommandId to be visible if aVisible is ETrue. If two 
   666     * buttons have the same id, the button to be altered is undefined.
   667     *
   668     * @param aCommandId The id for command to be made visible.
   669     * @param aVisible EFalse for making button invisible.
   670     */
   671     IMPORT_C void MakeCommandVisible(TInt aCommandId, TBool aVisible);
   672 
   673     /**
   674     * Returns ETrue if the button with id aCommandId is visible. If two buttons have 
   675     * the same id, the results are undefined.
   676     *
   677     * @param aCommandId The id for command to be checked.
   678     * @return The state of the button.     
   679     */
   680     IMPORT_C TBool IsCommandVisible(TInt aCommandId) const;
   681 
   682     /**
   683     * Animates the button with id aCommandId. If two buttons have the same id, the 
   684     * button to be animated is undefined.
   685     *
   686     * @since S60 3.1
   687     * @param aCommandId The id for command to be animated.   
   688     */
   689     IMPORT_C void AnimateCommand(TInt aCommandId);
   690     
   691     /**
   692     * Dims (but doesn't draw) the button with position aPosition.
   693     *
   694     * @since S60 3.1
   695     * @param aPosition The position for command to be dimmed.
   696     * @param aDimmed ETrue for dimming.
   697     */
   698     IMPORT_C void DimCommandByPosition(TCommandPosition aPosition, TBool aDimmed);
   699     
   700     /**
   701     * Returns ETrue if the button with position aPosition is dimmed.
   702     *
   703     * @since S60 3.1
   704     * @param aPosition The position for command to be checked.
   705     * @return The state of the button.    
   706     */
   707     IMPORT_C TBool IsCommandDimmedByPosition(TCommandPosition aPosition) const;
   708     
   709     /**
   710     * Sets the the button with position aPosition to be visible if aVisible is ETrue.
   711     *
   712     * @since S60 3.1
   713     * @param aPosition The position for command to be made visible.
   714     * @param aVisible EFalse for making button invisible.
   715     */
   716     IMPORT_C void MakeCommandVisibleByPosition(TCommandPosition aPosition, TBool aVisible);
   717     
   718     /**
   719     * Returns ETrue if the button with position aPosition is visible.
   720     *
   721     * @since S60 3.1
   722     * @param aPosition The position for command to be checked.
   723     * @return The state of the button.     
   724     */
   725     IMPORT_C TBool IsCommandVisibleByPosition(TCommandPosition aPosition) const;
   726     
   727     /**
   728     * Animates the button with position aPosition.
   729     *
   730     * @since S60 3.1
   731     * @param aPosition The position for command to be animated.    
   732     */
   733     IMPORT_C void AnimateCommandByPosition(TCommandPosition aPosition);
   734 
   735     /**
   736      * Gets the button group's location. Typically the button group is external to the 
   737      * view which is using it. In some cases, such as in dialogs with button panels, 
   738      * the button group is internal to the control which is using it.
   739      *
   740      * @return The button group's location.
   741      */  
   742     IMPORT_C TLocation Location() const;
   743     
   744     /**
   745      * Gets a pointer to the command button with the specified command Id.
   746      *
   747      * @param aCommandId Command ID of the button.
   748      * @return Pointer to the command button CEikCommandButton, NULL if there 
   749      *         was no button with Id aCommandId.
   750      */      
   751     IMPORT_C CEikCommandButton* CommandButtonOrNull(TInt aCommandId) const;
   752     
   753     /**
   754      * Sets the boundary rectangle for externally-positioned button groups. 
   755      * For use by EExternal button groups only.
   756      * 
   757      * @param aRect The boundary rectangle to use. The button group attaches 
   758      *              itself to the inside of this rectangle.
   759      */    
   760     IMPORT_C void SetBoundingRect(const TRect& aRect);
   761 
   762     /**
   763      * Subtracts the area occupied by the button group from the specified bounding 
   764      * rectangle. This method should be used in preference to querying the container's 
   765      * area at all times. For use by EExternal button groups only.
   766      * 
   767      * @param aBoundingRect Rectangle to be modified.
   768      */        
   769     IMPORT_C void ReduceRect(TRect& aBoundingRect) const;
   770 
   771     /**
   772      * Gets a pointer to the control (button) with the specified command ID. 
   773      * This method is intended to allow access to standard CCoeControl functionality 
   774      * only. Casting the return value is likely to fail on different devices.
   775      *
   776      * @param aCommandId Command ID of the button to get.
   777      * @return Pointer to a CCoeControl, NULL if there was no button at aCommandId.
   778      */
   779     IMPORT_C CCoeControl* ControlOrNull(TInt aCommandId) const;
   780     
   781     /**
   782      * Gets a pointer to the the button with the specified command Id.
   783      *
   784      * @param aCommandId Command ID of the button to obtain.
   785      * @return The button object.
   786      */    
   787     IMPORT_C CEikCommandButton* ButtonById(TInt aCommandId) const;
   788     
   789     /**
   790      * Gets the position in the group of the button with the specified command Id.
   791      * The return value is undefined if two buttons share the same id.
   792      *
   793      * @param aCommandId Identifies the command.
   794      * @return The command's container position.
   795      */     
   796     IMPORT_C TInt PositionById(TInt aCommandId) const;
   797     
   798     /**
   799      * Updates a command's hotkey and whether the key is displayed. 
   800      * This function is only supported by containers being used for dialog buttons.
   801      *
   802      * @param aCommandId Identifies the command to update.
   803      * @param aFlags Whether to display the hotkey.
   804      * @param aKeyId Hotkey identifier.
   805      */    
   806     IMPORT_C void UpdateHotKey(TInt aCommandId, THotKeyFlags aFlags, TInt aKeyId);
   807     
   808     /**
   809      * Changes the command observer for the button at aPos to aCommandObserver. 
   810      * Panics if an updated observer is already present. This function should be followed 
   811      * by RemoveCommandObserver() when you need to put back the original observer.
   812      *
   813      * @param aPos The button's position.
   814      * @param aCommandObserver The command observer.
   815      */    
   816     IMPORT_C void UpdateCommandObserverL(TInt aPos, MEikCommandObserver& aCommandObserver);
   817     
   818     /**
   819      * Removes the temporary observer for the button at aPos, replacing it with the
   820      * observer that was present when UpdateCommandObserverL() was called.
   821      *
   822      * @param aPos The button's position.
   823      */    
   824     IMPORT_C void RemoveCommandObserver(TInt aPos);
   825     
   826     /**
   827      * Checks for existence of updated command observer for the button at aPosition.
   828      *
   829      * @since S60 3.2
   830      * @param aPosition The position for button to be checked.
   831      * @return ETrue, if updated command observer exists.
   832      */    
   833     IMPORT_C TBool UpdatedCommandObserverExists(TCommandPosition aPosition) const;
   834     
   835     /**
   836      * Tests whether the button group has explicitly been instructed to suppress redraws.
   837      * Some button groups may not activate themselves during construction, in which 
   838      * case, they need to be activated by the client. This method allows the client 
   839      * to enquire whether this is necessary.
   840      *
   841      * @return ETrue if the button group will suppress redraws, otherwise EFalse.
   842      */    
   843     IMPORT_C TBool DelayActivation() const;
   844     
   845     /**
   846      * Returns the container's button group.
   847      *
   848      * @return Pointer to the button group object. Ownership is not transferred.
   849      */    
   850     inline MEikButtonGroup* ButtonGroup();
   851     
   852     /**
   853      * Returns the button group type.
   854      *
   855      * @return The button group type.
   856      */    
   857     inline TUse ButtonGroupType();
   858     
   859     /**
   860     * Internal method for setting markable list's MSK observer.
   861     * This observer is called before default CBA observer if MSK is pressed.
   862     * Observer is removed by passing NULL as parameter.
   863     *
   864     * @since S60 3.1
   865     * @param aMSKObserverOwner
   866     * @param aCommandObserver
   867     */
   868     void UpdateMSKCommandObserver(
   869         CEikListBox* aMSKObserverOwner, 
   870         MEikCommandObserver* aCommandObserver);
   871     
   872 public: // From CCoeControl.
   873     /**
   874      * From CCoeControl.
   875      * Gets the control's minimum required size.
   876      *
   877      * @return The minimum size required by the control.
   878      */ 
   879     IMPORT_C TSize MinimumSize();
   880     
   881     /**
   882      * From CCoeControl.
   883      * Handles key events.
   884      *
   885      * @param aKeyEvent The key event. 
   886      * @param aType The type of key event: EEventKey, EEventKeyUp or EEventKeyDown. 
   887      * @return Indicates whether or not the key event was used by this control. 
   888      */     
   889     IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType);
   890     
   891     /**
   892      * From CCoeControl.
   893      * Sets this control as visible or invisible.
   894      *
   895      * @param aVisible ETrue to make the control visible, EFalse to make it invisible. 
   896      */     
   897     void MakeVisible(TBool aVisible);
   898     
   899     /**
   900      * From CCoeControl.
   901      * Writes the internal state of the control and its components to aStream.
   902      * Does nothing in release mode.
   903      *
   904      * @param aWriteStream The output stream.
   905      */     
   906     IMPORT_C void WriteInternalStateL(RWriteStream& aWriteStream) const;
   907     
   908 public:
   909     /**
   910      * Formerly from MTopSetMember<CEikButtonGroupContainer>, now reserved.
   911      */ 
   912     IMPORT_C virtual void Reserved_MtsmPosition();
   913     
   914     /**
   915      * Formerly from MTopSetMember<CEikButtonGroupContainer>, now reserved.
   916      */     
   917     IMPORT_C virtual void Reserved_MtsmObject();
   918 
   919 public: // New functions for enhanced cba support.
   920     /**
   921      * Used to offer list of commands for softkeys.
   922      *
   923      * @since S60 3.2
   924      * @param aCommandList A list of command ids to be offered for softkeys.
   925      */
   926     IMPORT_C void OfferCommandListL(const RArray<TInt>& aCommandList);
   927     
   928     /**
   929      * Used to offer list of commands for softkeys.
   930      *
   931      * @since S60 3.2
   932      * @param aResourceId Id for CBA resource that defines enhanced cba buttons.
   933      */ 
   934     IMPORT_C void OfferCommandListL(const TInt aResourceId);
   935 
   936     /**
   937      * Used to check if a certain command have been approved to the current command set
   938      *
   939      * @since S60 3.2
   940      * @param aCommandId The id for command which existence should be checked.
   941      * @return ETrue if command is in control group, otherwise EFalse.
   942      */     
   943     IMPORT_C TBool IsCommandInGroup(const TInt aCommandId) const;
   944     
   945     /**
   946      * Replaces command with another.
   947      *
   948      * @since S60 3.2 
   949      * @param aCommandId Id for command that should be replaced.
   950      * @param aResourceId Resource id for new enhanced cba button.
   951      */     
   952     IMPORT_C void ReplaceCommand(const TInt aCommandId, const TInt aResourceId);
   953 
   954 private:
   955     enum TCommandOp {ESet, EAdd, EPush};
   956     
   957 private:
   958     class TCmdPos
   959         {
   960     public:
   961         inline TCmdPos();
   962         inline TCmdPos(TInt aPos, TInt aCmd);
   963     public:
   964         TInt iPos;
   965         TInt iCmd;
   966         };
   967         
   968     class TCmdObserver
   969         {
   970     public:
   971         inline TCmdObserver(TInt aPos, MEikCommandObserver& aObserver);
   972     public:
   973         TInt iPos;
   974         MEikCommandObserver& iObserver;
   975         };
   976         
   977     class CCmdObserverArray : public CArrayFixFlat<TCmdObserver>
   978         {
   979     public:
   980         inline CCmdObserverArray();
   981         TInt FindIndex(TInt aPos);
   982         };
   983         
   984 private:
   985     CEikButtonGroupContainer(TUse aUse);
   986     
   987     void ConstructL(
   988         TOrientation aOrientation,
   989         MEikCommandObserver* aCommandObserver,
   990         TInt aResourceId,
   991         RWindowGroup* aParentWg,
   992         TUint aFlags);
   993         
   994     IMPORT_C void DoSetCommandL(
   995         TInt aPosition,
   996         TInt aCommandId,
   997         const TDesC* aText,
   998         const CFbsBitmap* aBitmap,
   999         const CFbsBitmap* aMask,
  1000         TCommandOp aOp);
  1001         
  1002     IMPORT_C void DoSetCommandL(
  1003         TInt aPosition,
  1004         TInt aCommandId,
  1005         const TDesC* aText,
  1006         const TDesC& aFile,
  1007         TInt aBitmapId,
  1008         TInt aMaskId,
  1009         TCommandOp aOp);
  1010         
  1011     IMPORT_C void DoSetCommandL(
  1012         TInt aCommandId,
  1013         const TDesC* aText,
  1014         const CFbsBitmap* aBitmap,
  1015         const CFbsBitmap* aMask,
  1016         TCommandOp aOp);
  1017         
  1018     IMPORT_C void DoSetCommandL(
  1019         TInt aCommandId,
  1020         const TDesC* aText,
  1021         const TDesC& aFile,
  1022         TInt aBitmapId,
  1023         TInt aMaskId,
  1024         TCommandOp aOp);
  1025         
  1026     IMPORT_C void DoSetCommandL(
  1027         TInt aPosition,
  1028         TInt aResourceId,
  1029         TCommandOp aOp);
  1030     
  1031     inline CCoeControl* ButtonGroupAsControl() const;
  1032     void UpdateRect();
  1033     static void CleanupCommandDestroy(TAny* aPtr);
  1034     TCmdPos DoCleanupCommandPop();
  1035     void DoCleanupCommandPopAndDestroy();
  1036 
  1037 private: // from CCoeControl
  1038     TInt CountComponentControls() const;
  1039     CCoeControl* ComponentControl(TInt aIndex) const;
  1040     void SizeChanged();
  1041 
  1042 private: // from MEikCommandObserver
  1043     void ProcessCommandL(TInt aCommandId);
  1044     CCoeControl* CreateCustomCommandControlL(TInt aControlType);
  1045 
  1046 private:
  1047     MEikButtonGroup* iButtonGroup;
  1048     TUse iUse;
  1049     CArrayFix<TCmdPos>* iCommandsCleanup;
  1050     MEikCommandObserver* iCommandObserver;
  1051     CCmdObserverArray* iObserverArray;
  1052     TDblQueLink iBtLink;
  1053     CEikListBox* iMSKObserverOwner;
  1054     TInt iSpare;
  1055     TInt iValid;
  1056 private:
  1057     friend class CCmdObserverArray;
  1058     friend class CEikButtonGroupStack;
  1059     };
  1060 
  1061 
  1062 // Inline function implementations.
  1063 
  1064 inline void CEikButtonGroupContainer::SetCommandL(
  1065     TInt aPosition,
  1066     TInt aCommandId,
  1067     const TDesC& aText)
  1068     {
  1069     DoSetCommandL(aPosition, aCommandId, &aText, NULL, NULL, ESet);
  1070     }
  1071 
  1072 inline void CEikButtonGroupContainer::SetCommandL(
  1073     TInt aPosition,
  1074     TInt aCommandId,
  1075     const CFbsBitmap& aBitmap,
  1076     const CFbsBitmap& aMask)
  1077     {
  1078     DoSetCommandL(aPosition, aCommandId, NULL, &aBitmap, &aMask, ESet);
  1079     }
  1080 
  1081 inline void CEikButtonGroupContainer::SetCommandL(
  1082     TInt aPosition,
  1083     TInt aCommandId,
  1084     const TDesC& aText,
  1085     const CFbsBitmap& aBitmap,
  1086     const CFbsBitmap& aMask)
  1087     {
  1088     DoSetCommandL(aPosition, aCommandId, &aText, &aBitmap, &aMask, ESet);
  1089     }
  1090 
  1091 inline void CEikButtonGroupContainer::SetCommandL(
  1092     TInt aPosition,
  1093     TInt aCommandId,
  1094     const TDesC& aFile,
  1095     TInt aBitmapId,
  1096     TInt aMaskId)
  1097     {
  1098     DoSetCommandL(aPosition, aCommandId, NULL, aFile, aBitmapId, aMaskId, ESet);
  1099     }
  1100 
  1101 inline void CEikButtonGroupContainer::SetCommandL(
  1102     TInt aPosition,
  1103     TInt aCommandId,
  1104     const TDesC& aText,
  1105     const TDesC& aFile,
  1106     TInt aBitmapId,
  1107     TInt aMaskId)
  1108     {
  1109     DoSetCommandL(aPosition, aCommandId, &aText, aFile, aBitmapId, aMaskId, ESet);
  1110     }
  1111 
  1112 inline void CEikButtonGroupContainer::SetCommandL(
  1113     TInt aPosition,
  1114     TInt aResourceId)
  1115     {
  1116     DoSetCommandL(aPosition, aResourceId, ESet);
  1117     }
  1118 
  1119 inline void CEikButtonGroupContainer::SetCommandL(
  1120     TInt aCommandId,
  1121     const TDesC& aText)
  1122     {
  1123     DoSetCommandL(aCommandId, &aText, NULL, NULL, ESet);
  1124     }
  1125 
  1126 inline void CEikButtonGroupContainer::SetCommandL(
  1127     TInt aCommandId,
  1128     const CFbsBitmap& aBitmap,
  1129     const CFbsBitmap& aMask)
  1130     {
  1131     DoSetCommandL(aCommandId, NULL, &aBitmap, &aMask, ESet);
  1132     }
  1133 
  1134 inline void CEikButtonGroupContainer::SetCommandL(
  1135     TInt aCommandId,
  1136     const TDesC& aText,
  1137     const CFbsBitmap& aBitmap,
  1138     const CFbsBitmap& aMask)
  1139     {
  1140     DoSetCommandL(aCommandId, &aText, &aBitmap, &aMask, ESet);
  1141     }
  1142 
  1143 inline void CEikButtonGroupContainer::SetCommandL(
  1144     TInt aCommandId,
  1145     const TDesC& aFile,
  1146     TInt aBitmapId,
  1147     TInt aMaskId)
  1148     {
  1149     DoSetCommandL(aCommandId, NULL, aFile, aBitmapId, aMaskId, ESet);
  1150     }
  1151 
  1152 inline void CEikButtonGroupContainer::SetCommandL(
  1153     TInt aCommandId,
  1154     const TDesC& aText,
  1155     const TDesC& aFile,
  1156     TInt aBitmapId,
  1157     TInt aMaskId)
  1158     {
  1159     DoSetCommandL(aCommandId, &aText, aFile, aBitmapId, aMaskId, ESet);
  1160     }
  1161 
  1162 inline void CEikButtonGroupContainer::AddCommandL(
  1163     TInt aPosition,
  1164     TInt aCommandId,
  1165     const TDesC& aText)
  1166     {
  1167     DoSetCommandL(aPosition, aCommandId, &aText, NULL, NULL, EAdd);
  1168     }
  1169 
  1170 inline void CEikButtonGroupContainer::AddCommandL(
  1171     TInt aPosition,
  1172     TInt aCommandId,
  1173     const CFbsBitmap& aBitmap,
  1174     const CFbsBitmap& aMask)
  1175     {
  1176     DoSetCommandL(aPosition, aCommandId, NULL, &aBitmap, &aMask, EAdd);
  1177     }
  1178 
  1179 inline void CEikButtonGroupContainer::AddCommandL(
  1180     TInt aPosition,
  1181     TInt aCommandId,
  1182     const TDesC& aText,
  1183     const CFbsBitmap& aBitmap,
  1184     const CFbsBitmap& aMask)
  1185     {
  1186     DoSetCommandL(aPosition, aCommandId, &aText, &aBitmap, &aMask, EAdd);
  1187     }
  1188 
  1189 inline void CEikButtonGroupContainer::AddCommandL(
  1190     TInt aPosition,
  1191     TInt aCommandId,
  1192     const TDesC& aFile,
  1193     TInt aBitmapId,
  1194     TInt aMaskId)
  1195     {
  1196     DoSetCommandL(aPosition, aCommandId, NULL, aFile, aBitmapId, aMaskId, EAdd);
  1197     }
  1198 
  1199 inline void CEikButtonGroupContainer::AddCommandL(
  1200     TInt aPosition,
  1201     TInt aCommandId,
  1202     const TDesC& aText,
  1203     const TDesC& aFile,
  1204     TInt aBitmapId,
  1205     TInt aMaskId)
  1206     {
  1207     DoSetCommandL(aPosition, aCommandId, &aText, aFile, aBitmapId, aMaskId, EAdd);
  1208     }
  1209 
  1210 inline void CEikButtonGroupContainer::AddCommandToStackL(
  1211     TInt aPosition,
  1212     TInt aCommandId,
  1213     const TDesC& aText)
  1214     {
  1215     DoSetCommandL(aPosition, aCommandId, &aText, NULL, NULL, EPush);
  1216     }
  1217 
  1218 inline void CEikButtonGroupContainer::AddCommandToStackL(
  1219     TInt aPosition,
  1220     TInt aCommandId,
  1221     const CFbsBitmap& aBitmap,
  1222     const CFbsBitmap& aMask)
  1223     {
  1224     DoSetCommandL(aPosition, aCommandId, NULL, &aBitmap, &aMask, EPush);
  1225     }
  1226 
  1227 inline void CEikButtonGroupContainer::AddCommandToStackL(
  1228     TInt aPosition,
  1229     TInt aCommandId,
  1230     const TDesC& aText,
  1231     const CFbsBitmap& aBitmap,
  1232     const CFbsBitmap& aMask)
  1233     {
  1234     DoSetCommandL(aPosition, aCommandId, &aText, &aBitmap, &aMask, EPush);
  1235     }
  1236 
  1237 inline void CEikButtonGroupContainer::AddCommandToStackL(
  1238     TInt aPosition,
  1239     TInt aCommandId,
  1240     const TDesC& aFile,
  1241     TInt aBitmapId,
  1242     TInt aMaskId)
  1243     {
  1244     DoSetCommandL(aPosition, aCommandId, NULL, aFile, aBitmapId, aMaskId, EPush);
  1245     }
  1246 
  1247 inline void CEikButtonGroupContainer::AddCommandToStackL(
  1248     TInt aPosition,
  1249     TInt aCommandId,
  1250     const TDesC& aText,
  1251     const TDesC& aFile,
  1252     TInt aBitmapId,
  1253     TInt aMaskId)
  1254     {
  1255     DoSetCommandL(aPosition, aCommandId, &aText, aFile, aBitmapId, aMaskId, EPush);
  1256     }
  1257 
  1258 inline void CEikButtonGroupContainer::AddCommandToStackL(
  1259     TInt aPosition,
  1260     TInt aResourceId)
  1261     {
  1262     DoSetCommandL(aPosition, aResourceId, EPush);
  1263     }
  1264 
  1265 inline void CEikButtonGroupContainer::CleanupCommandPop()
  1266     {
  1267     CleanupCommandPop(1);
  1268     }
  1269 
  1270 inline void CEikButtonGroupContainer::CleanupCommandPopAndDestroy()
  1271     {
  1272     CleanupStack::PopAndDestroy();
  1273     }
  1274 
  1275 inline void CEikButtonGroupContainer::CleanupCommandPopAndDestroy(TInt aCount)
  1276     {
  1277     CleanupStack::PopAndDestroy(aCount);
  1278     }
  1279 
  1280 inline MEikButtonGroup* CEikButtonGroupContainer::ButtonGroup()
  1281     {
  1282     return iButtonGroup;
  1283     }
  1284 
  1285 inline CEikButtonGroupContainer::TUse CEikButtonGroupContainer::ButtonGroupType()
  1286     {
  1287     return iUse;
  1288     }
  1289 
  1290 #endif // __EIKBTGPC_H__