Class CEikButtonGroupContainer

CEikButtonGroupContainer

Support

Supported from 6.0

Description

Provides a wrapper around the different button arrays used in both pen, and no-pen devices.

Derivation

CBase Base class for all classes to be instantiated on the heap CCoeControl Control base class from which all other controls are derived CEikButtonGroupContainer Provides a wrapper around the different button arrays used in both pen, and no-pen devices MEikCommandObserver Command observers respond to user commands, and have the secondary function of creating custom controls on request for classes such as CEikToolbar, or user-defined classes

Defined in CEikButtonGroupContainer:
AddCommandL(), AddCommandSetToStackL(), AddCommandToStackL(), AnimateCommand(), ButtonById(), ButtonCount(), CalcMinimumSizeL(), CleanupCommandPop(), CleanupCommandPopAndDestroy(), CleanupCommandPushL(), CommandButtonOrNull(), ControlOrNull(), Current(), DelayActivation(), DimCommand(), ECba, EDialog, EDialogButtons, EExternal, EHorizontal, EInternal, EPlainHotKey, EShowHotKey, EToolbar, EVertical, EView, IsCommandDimmed(), IsCommandVisible(), Location(), MakeCommandVisible(), MakeVisible(), MaxCommands(), MinimumSize(), NewL(), OfferKeyEventL(), PositionById(), ReduceRect(), RemoveCommandFromStack(), RemoveCommandObserver(), SetBoundingRect(), SetCommandL(), SetCommandSetL(), SetDefaultCommand(), THotKeyFlags, TLocation, TOrientation, TUse, UpdateCommandObserverL(), UpdateHotKey(), ~CEikButtonGroupContainer()

Inherited from CBase:
operator new()

Inherited from CCoeControl:
ActivateGc(), ActivateL(), BackedUpWindow(), CapturesPointer(), ClaimPointerGrab(), CloseWindow(), ComponentControl(), ConstructFromResourceL(), ControlContext(), ControlEnv(), CopyControlContextFrom(), CountComponentControls(), CreateBackedUpWindowL(), CreateWindowL(), DeactivateGc(), DrawDeferred(), DrawNow(), DrawableWindow(), EnableDragEvents(), FocusChanged(), GetColor(), GetColorUseListL(), GetHelpContext(), GrabbingComponent(), HandleComponentControlsResourceChange(), HandlePointerBufferReadyL(), HandlePointerEventL(), HandleRedrawEvent(), HandleResourceChange(), HasBorder(), IgnoreEventsUntilNextPointerUp(), Index(), InputCapabilities(), IsActivated(), IsBackedUp(), IsBeingDestroyed(), IsBlank(), IsDimmed(), IsFocused(), IsNonFocusing(), IsReadyToDraw(), IsVisible(), Observer(), OverrideColorL(), OwnsWindow(), Position(), PositionChanged(), PositionRelativeToScreen(), PrepareForFocusGainL(), PrepareForFocusLossL(), Rect(), RecursivelyMergedInputCapabilities(), ReportEventL(), ResetGc(), SetAdjacent(), SetAllowStrayPointers(), SetBlank(), SetCanDrawOutsideRect(), SetComponentsToInheritVisibility(), SetContainerWindow(), SetContainerWindowL(), SetControlContext(), SetCornerAndSize(), SetCornerAndSizeL(), SetDimmed(), SetExtent(), SetExtentL(), SetExtentToWholeScreen(), SetExtentToWholeScreenL(), SetFocus(), SetFocusing(), SetGloballyCapturing(), SetNeighbor(), SetNonFocusing(), SetObserver(), SetPointerCapture(), SetPosition(), SetRect(), SetRectL(), SetSize(), SetSizeL(), SetSizeWithoutNotification(), SetSizeWithoutNotificationL(), Size(), SizeChanged(), SizeChangedL(), SystemGc(), Window()

Inherited from MEikCommandObserver:
CreateCustomCommandControlL(), ProcessCommandL()

static CEikButtonGroupContainer* NewL(TUse aUse,TOrientation aOrientation,MEikCommandObserver* aCommandObserver,TInt aResourceId,const CCoeControl& aParent,TUint aFlags);

Description

Creates a button group container in its own window, or if specified, in its parent control's window.

Parameters

TUse aUse The button group's type. Specifying this as either EView or EDialog creates the default button set for the host device; the other options are included primarily for testing. TOrientation aOrientation The button group's orientation. You need specify this only for devices that can layout their buttons either horizontally or vertically. MEikCommandObserver* aCommandObserver A command observer to be notified of commands on the container. TInt aResourceId A resource containing descriptions of buttons in the group. This can be NULL if buttons are to be added dynamically. const CCoeControl aParent The control's parent. TUint aFlags The button group's flags.

Return value

CEikButtonGroupContainer* Button group container object.

~CEikButtonGroupContainer();

Description

Destructor

void SetDefaultCommand(TInt aCommandId);

Description

Sets the default command ID for buttons in this container.

Parameters

TInt aCommandId Command to issue if no other is specified.

void AddCommandL (TInt aPosition, TInt aCommandId, const TDesC& aText);
void AddCommandL (TInt aPosition, TInt aCommandId, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void AddCommandL (TInt aPosition, TInt aCommandId, const TDesC& aText, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void AddCommandL (TInt aPosition, TInt aCommandId, const TDesC& aFile, TInt aBitmapId, TInt aMaskId);
void AddCommandL (TInt aPosition, TInt aCommandId, const TDesC& aText, const TDesC& aFile, TInt aBitmapId, TInt aMaskId);

Description

Adds a command button at the specified position in the container. The button may have an optional text string or a bitmap image; bitmaps may optionally have a mask.

Parameters

TInt aPosition Position for the new button. TInt aCommandId Command ID for the new button. const TDesC& aText Text for the button. const CFbsBitmap& aBitmap Bitmap for the button. const CFbsBitmap& aMask Mask bitmap for aBitmap. const TDesC& aFile File containing the bitmap and any mask for the button. TInt aBitmapId ID of the bitmap, within aFile, for the button. TInt aMaskId ID of the mask, within aFile, for the button.

void SetCommandL (TInt aPosition, TInt aCommandId, const TDesC& aText);
void SetCommandL (TInt aPosition, TInt aCommandId, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void SetCommandL (TInt aPosition, TInt aCommandId, const TDesC& aText, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void SetCommandL (TInt aPosition, TInt aCommandId, const TDesC& aFile, TInt aBitmapId, TInt aMaskId);
void SetCommandL (TInt aPosition, TInt aResourceId);
void SetCommandL (TInt aCommandId, const TDesC& aText);
void SetCommandL (TInt aCommandId, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void SetCommandL (TInt aCommandId, const TDesC& aText, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void SetCommandL (TInt aCommandId, const TDesC& aFile, TInt aBitmapId, TInt aMaskId);
void SetCommandL (TInt aCommandId, const TDesC& aText, const TDesC& aFile, TInt aBitmapId, TInt aMaskId);

Description

Sets a command button's content, overwriting any previous contents at that position.

There are several overloads of this function which allow the command button's image and text to be optionally set. All these functions will raise a panic if the supplied position is out of range.

If an image is set, a mask must also be specified to guarantee compliance with different colour schemes. Ownership of bitmap arguments is transferred at the end of the function.

If a button position is not supplied, CEikButtonGroupContainer attempts to identify which button to overwrite by command ID. If two buttons have the same ID, which will be altered is not defined. The behaviour is also undefined if aCommandId can't be matched to any button.

Parameters

TInt aPosition Position within the button group. TInt aCommandId Command ID the new button will send. const TDesC& aText Text for the button. const CFbsBitmap& aBitmap Bitmap for the button. const CFbsBitmap& aMask Mask bitmap for aBitmap. const TDesC& aFile EPOC multi-bitmap file containing mask and bitmap images. TInt aBitmapId Index within aFile of the image bitmap. TInt aMaskId Index within aFile of a single-plane bitmap to use as the mask. TInt aResourceId ID of a resource specifying the text, bitmaps and command ID.

void SetCommandSetL(TInt aResourceId);

Description

Sets the buttons' text, bitmaps and command ids from a resource.

The type of resource depends on the type of button.

Parameters

TInt aResourceId ID of the resource structure specifying the command buttons.

Description

Each command button slot can contain a stack of controls, the top control of which is visible and active. This allows an application to use different command buttons depending on which of its views is currently visible.

void AddCommandToStackL (TInt aPosition, TInt aCommandId, const TDesC& aText);
void AddCommandToStackL (TInt aPosition, TInt aCommandId, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void AddCommandToStackL (TInt aPosition, TInt aCommandId, const TDesC& aText, const CFbsBitmap& aBitmap,const CFbsBitmap& aMask);
void AddCommandToStackL (TInt aPosition, TInt aCommandId, const TDesC& aFile, TInt aBitmapId, TInt aMaskId);
void AddCommandToStackL (TInt aPosition, TInt aCommandId, const TDesC& aText, const TDesC& aFile, TInt aBitmapId, TInt aMaskId);
void AddCommandToStackL (TInt aPosition, TInt aResourceId);
void AddCommandToStackL (TInt aCommandId, const TDesC& aText);
void AddCommandToStackL (TInt aCommandId, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void AddCommandToStackL (TInt aCommandId, const TDesC& aText, const CFbsBitmap& aBitmap, const CFbsBitmap& aMask);
void AddCommandToStackL (TInt aCommandId, const TDesC& aFile, TInt aBitmapId, TInt aMaskId);
void AddCommandToStackL (TInt aCommandId, const TDesC& aText, const TDesC& aFile,TInt aBitmapId,TInt aMaskId);

Description

Pushes a command button onto a position's button stack.

As with SetCommandL() but allows the previous command to be retrieved at any time by calling RemoveCommand().

There are several overloads of this function which allow the command button's image and text to be optionally set. All these functions will raise a panic if the supplied position is out of range.

If an image is set, a mask must also be specified to guarantee compliance with different colour schemes. Ownership of bitmap arguments is transferred at the end of the function.

If a button position is not supplied, CEikButtonGroupContainer attempts to identify which button to overwrite by command ID. If two buttons have the same ID, which will be altered is not defined. The behaviour is also undefined if aCommandId can't be matched to any button.

Parameters

TInt aPosition The button's position in the group. TInt aCommandId The button's command ID. const TDesC& aText Text for the button. const CFbsBitmap& aBitmap Bitmap for the button. const CFbsBitmap& aMask Mask bitmap for aBitmap. const TDesC& aFile EPOC multi-bitmap file containing mask and bitmap images. TInt aBitmapId Index within aFile of the image bitmap. TInt aMaskId Index within aFile of a single-plane bitmap to use as the mask. TInt aResourceId ID of a resource specifying the text, bitmaps and command ID.

void AddCommandSetToStackL(TInt aResourceId);

Description

As with SetCommandL() but for a set of buttons, also allows the previous command to be retrieved at any time by calling RemoveCommand().

Parameters

TInt aResourceId Resource describing the set of command buttons.

void RemoveCommandFromStack(TInt aPosition,TInt aCommandId);

Description

Removes the command identified by aCommandId, in position aPosition in the group, from the command stack. Automatically retrieves the previous command details.

Commands are added to the stack by calling AddCommandToStackL.

Parameters

TInt aPosition Position in the group. TInt aCommandId Command ID.

Description

The following interface to the thread-local CleanupStack should be used when an application changes the contents of more than one button in the body of one function call.

void CleanupCommandPushL(TInt aPosition);

Description

Places the command in position aPosition in the group on the cleanup stack. Typically used when a control or view changes the contents of two or more buttons on receipt of focus. After altering one command with a call to AddCommandToStackL() the push is made to guarantee the display will be left in a consistent state if the second (and any subsequent) calls to AddCommandToStackL() fail.

Only a single command can be pushed for each position.

Parameters

TInt aPosition Position in the container of the button to push.

void CleanupCommandPop();

Description

Removes a command from the cleanup stack without destroying it.

void CleanupCommandPop(TInt aCount);

Description

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

Parameters

TInt aCount Number of commands to pop.

void CleanupCommandPopAndDestroy();
void CleanupCommandPopAndDestroy(TInt aCount);

Description

Removes one or more commands which were pushed onto the cleanup stack.

It does this by calling CleanupCommandPushL(), rolling back to the previous details. The command buttons popped are destroyed.

Parameters

TInt aCount Number of commands to pop and destroy.

void DimCommand(TInt aCommandId,TBool aDimmed);

Description

Dims or undims a button without drawing it.

If two buttons in the container have the same ID, the behaviour is undefined. Dimming prevents acceptance of user input.

Parameters

TInt aCommandId Command ID of the button to change. TBool aDimmed ETrue to dim the specified command.EFalse to undim the specified command.

TBool IsCommandDimmed(TInt aCommandId) const;

Description

Determines whether the button with the specified command ID is dimmed.

Returns true if the button with the specified command ID is dimmed. If two buttons have the same ID, the results of this check are undefined.

Parameters

TInt aCommandId The command ID.

Return value

TBool ETrue if the specified command is dimmed. EFalse if the specified command is not dimmed.

TBool IsCommandVisible(TInt aCommandId) const;

Description

Tests whether the button with the specified command ID is visible.

If two buttons have the same ID, the results are undefined.

Parameters

TInt aCommandId Specifies the button.

Return value

TBool ETrue if the specified button is visible. EFalse if the specified button is not visible.

void MakeCommandVisible(TInt aCommandId,TBool aVisible);

Description

Makes the button with the specified id either visible, or invisible.

If two buttons have the same ID, the button to be altered is undefined.

Parameters

TInt aCommandId Specifies the button to alter. TBool aVisible ETrue to make the specified button visible.EFalse to make the specified button invisible.

void MakeVisible(TBool aVisible);

Description

Makes the button group either visible, or invisible.

Parameters

TBool aVisible ETrue to make the button group visible. EFalse to make invisible.

CEikCommandButton* ButtonById(TInt aCommandId) const;

Description

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

Parameters

TInt aCommandId Command ID of the button to obtain.

Return value

CEikCommandButton* The button object.

void UpdateCommandObserverL(TInt aPos,MEikCommandObserver& aCommandObserver);

Description

Changes the command observer for the button at aPos to aCommandObserver. Panics if an updated observer is already present. This function should be followed by RemoveCommandObserver() when you need to put back the original observer.

Parameters

TInt aPos The button's position. MEikCommandObserver& aCommandObserver The command observer.

void RemoveCommandObserver(TInt aPos);

Description

Remove temporary observer.

Removes the temporary observer for the button at aPos, replacing it with the observer that was present when UpdateCommandObserverL() was called.

Parameters

TInt aPos The button's position.

TInt MaxCommands() const;

Description

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

Return value

TInt The number of command buttons supported.

CCoeControl* ControlOrNull(TInt aCommandId) const;

Description

Gets a pointer to the control (button) with the specified command Id.

This method is intended to allow access to standard CCoeControl functionality only. Casting the return value is likely to fail on different devices.

Parameters

TInt aCommandId Command ID of the button to get.

Return value

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

CEikCommandButton* CommandButtonOrNull(TInt aCommandId) const;

Support

Supported from 6.1

Description

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

Parameters

TInt aCommandId Command ID of the button.

Return value

CEikCommandButton* Pointer to the command button CEikCommandButton, NULL if there was no button with Id aCommandId.

TInt PositionById(TInt aCommandId) const;

Description

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

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

Parameters

TInt aCommandId Identifies the command.

Return value

TInt The command's container position.

void AnimateCommand(TInt aCommandId);

Description

Animates the button with the specified id.

If two buttons have the same ID, this function's behaviour is undefined.

Parameters

TInt aCommandId The button to animate.

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

Description

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

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

Parameters

TInt aCommandId Identifies the command to update. THotKeyFlags aFlags Whether to display the hotkey. TInt aKeyId Hotkey identifier.

TInt ButtonCount() const;

Description

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

Return value

TInt The number of buttons.

static CEikButtonGroupContainer* Current();

Description

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

Returns NULL if there are no containers active or none suitable for sharing. Ownership of the returned pointer is not transferred.

Return value

CEikButtonGroupContainer* Pointer to the button group container.

TBool DelayActivation() const;

Description

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

Some button groups may not activate themselves during construction, in which case, they need to be activated by the client. This method allows the client to enquire whether this is necessary.

Return value

TBool ETrue if the button group will suppress redraws, otherwise EFalse.

TLocation Location() const;

Description

Gets the button group's location.

Typically the button group is external to the view which is using it. In some cases, such as in dialogs with button panels, the button group is internal to the control which is using it.

Return value

TLocation The button group's location.

void SetBoundingRect(const TRect& aRect);

Description

Sets the boundary rectangle for externally-positioned button groups.

For use by EExternal button groups only.

Parameters

const TRect& aRect The boundary rectangle to use. The button group attaches itself to the inside of this rectangle.

void ReduceRect(TRect& aBoundingRect) const;

Description

Subtracts the area occupied by the button group from the specified bounding rectangle.

This method should be used in preference to querying the container's area at all times.

Parameters

TRect& aBoundingRect Rectangle to be modified.

TSize CalcMinimumSizeL(TInt aResourceId) const;

Description

Calculates minimum size required to display the buttons defined in the specified resource structure.

Parameters

TInt aResourceId The ID of the resource structure describing the button group.

Return value

TSize Minimum size required to display the button group defined in the specified resource structure.

Description

The following member functions implement methods declared virtual in CCoeControl.

TSize MinimumSize();

Description

Gets the minimum size required to display the current button group.

See CCoeControl::MinimumSize().

Return value

TSize The minimum size required to display the button group

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

Description

Offers a key event to the control

Offers the key event aKeyEvent with code aType to the control. See CCoeControl::OfferKeyEventL().

Parameters

const TKeyEvent& aKeyEvent The key event. TEventCode aType The key event type.

Return value

TKeyResponse The key event response.

TUse

Description

Describes how the container is being used.

The enumeration is used by the system to create the appropriate (DFRD specific) button group for the specified type. From 6.1 only two use types can be specified: EView or EDialog.

EView In a view. EDialog In a dialog. EToolbar Deprecated from v6.1.As a toolbar. This should not be used, it is strictly for test purposes only. ECba Deprecated from v6.1.As a CBA. This should not be used, it is strictly for test purposes only. EDialogButtons Deprecated from v6.1.As the buttons in a dialog. This should not be used, it is strictly for test purposes only.

THotKeyFlags

Description

Flags for the display of hotkeys.

EShowHotKey Hotkeys for commands should be shown. EPlainHotKey Hotkeys for commands should not be shown.

TOrientation

Description

Describes the orientation of the container

EVertical Buttons are laid out vertically. EHorizontal Buttons are laid out horizontally.

TLocation

Description

Relative positions of the container and the control which uses it

EInternal The button group is internal to the control which is using it. Dialog buttons for example. EExternal The button group is external to the control which is using it. Toolbar, or command button area, for example.