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(