Class CEikButtonBase

CEikButtonBase

Support

Supported from 6.0

Description

This is the base class from which concrete button controls (command buttons, option buttons and checkboxes) are derived. The base class implements knowledge of the button’s logical state, and can respond to user events. It cannot, however, draw itself.

Derived classes should provide an appropriate implementation of CCoeControl::Draw(). It is usual to make the on-screen appearance of the button dependent on its current state. Derived classes may also implement StateChanged() to respond appropriately to changes in the draw state.

Derivation

CBase Base class for all classes to be instantiated on the heap CCoeControl Control base class from which all other controls are derived CEikBorderedControl A control which is drawn surrounded by a rectangular border CEikButtonBase This is the base class from which concrete button controls (command buttons, option buttons and checkboxes) are derived

Defined in CEikButtonBase:
Animate(), CEikButtonBase(), CopyDrawStateTo(), DrawState(), EClear, EDrawClear, EDrawClearPressed, EDrawIndeterminate, EDrawIndeterminatePressed, EDrawSet, EDrawSetPressed, EEikButtonLatches, EEikButtonReportsOnPointerDown, EEikButtonStaysClear, EEikButtonStaysSet, EIndeterminate, ESet, GetColorUseListL(), HandlePointerEventL(), HandleResourceChange(), InputCapabilities(), IsPressed(), OfferKeyEventL(), SetAllowTristate(), SetBehavior(), SetBubbleHelpTextL(), SetCoordinator(), SetIgnoreNextPointerUp(), SetReportOnPointerDown(), SetState(), State(), StateChanged(), TButtonBehavior, TDrawState, TState, iButFlags, ~CEikButtonBase()

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(), GetHelpContext(), GrabbingComponent(), HandleComponentControlsResourceChange(), HandlePointerBufferReadyL(), HandleRedrawEvent(), IgnoreEventsUntilNextPointerUp(), Index(), IsActivated(), IsBackedUp(), IsBeingDestroyed(), IsBlank(), IsDimmed(), IsFocused(), IsNonFocusing(), IsReadyToDraw(), IsVisible(), MakeVisible(), MinimumSize(), Observer(), OverrideColorL(), OwnsWindow(), Position(), PositionChanged(), PositionRelativeToScreen(), PrepareForFocusGainL(), PrepareForFocusLossL(), Rect(), RecursivelyMergedInputCapabilities(), ReportEventL(), ResetGc(), 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 CEikBorderedControl:
Border(), Draw(), HasBorder(), SetAdjacent(), SetBorder(), iBorder

See also:

• State()
• StateChanged()

CEikButtonBase();

Description

Empty default constructor.

~CEikButtonBase();

Description

Destructor.

Destroys a CEikButtonBase object. Button base objects do not own their coordinator, the destructor therefore does not delete it.

void SetCoordinator(TEikButtonCoordinator* aButCoord);

Description

Sets the button’s co-ordinator. This function sets the specified TEikButtonCoordinator object as the button’s co-ordinator. A button co-ordinator manages the interdependence between buttons in a group.

Parameters

TEikButtonCoordinator* aButCoord Button co-ordinator.

void SetBehavior(TButtonBehavior aBehavior);

Description

Sets the button’s behaviour. A button can be made to stay set or stay clear. It can also be made a latching button.

Parameters

TButtonBehavior aBehavior Specifies button behaviour.

protected: void SetReportOnPointerDown();

Description

Sets event reporting on pointer down events. If this flag is set, HandlePointerEvent() will report events to the control observer on incoming pointer down events. Normally events are only sent by the button in response to an incoming pointer down event followed by a pointer up event.

See also:

• CCoeControl::ReportEventL()
• EEikButtonReportsOnPointerDown

void SetIgnoreNextPointerUp();

Description

Sets the button flag so that the next pointer up event is ignored.

void SetBubbleHelpTextL(const TDesC& aText);

Support

Supported from 6.1

Description

Sets the text to appear in a bubble help message for the button.

Parameters

const TDesC& aText The bubble help text.

void Animate();

Description

Animates a button; showing the control as momentarily depressed. This is called by OfferKeyEventL(); it may also be called by an application when the state of a button control is changed from elsewhere to mimic button behaviour and provide more feedback to the user.

Description

A button’s logical state describes whether a button is on, off, or neither on nor off. The three possible TState values are logical values, and are probably what your application wants to know. Contrast this with its draw state, described below.

TState State() const;

Description

Gets the button’s logical state.

Return value

TState The button’s logical state. This can be one of three possible TState values.

void SetState(TState aState);

Description

Sets the button’s state.

Parameters

TState aState The logical state to which the button will be set.

protected: void SetAllowTristate();

Description

Specifies the button can have an indeterminate state that is neither on, nor off.

void GetColorUseListL(CArrayFix<TCoeColorUse>& aColorUseList) const;

Description

Gets a list of logical colours employed in the drawing of the control, paired with an explanation of how they are used. Appends the list to aColorUseList.

Parameters

CArrayFix<TCoeColorUse>& aColorUseList List of logical colours with an explanation of how they are used.

Description

The draw state of a button describes how it should be drawn at any given instant.

protected: TDrawState DrawState() const;

Description

Gets the current draw state.

Return value

TDrawState The current draw state.

protected: void CopyDrawStateTo(CEikButtonBase* aTargetButton) const;

Description

Copies the current draw state to the specified button.

Parameters

CEikButtonBase* aTargetButton The button to which the draw state is copied.

protected: TBool IsPressed() const;

Description

Tests whether the button is currently being pressed by the user.

Return value

TBool ETrue if the button is currently being pressed by the user.

private: virtual void StateChanged();

Description

Notifies the button that its draw state has changed. This function is called by CEikButtonBase when the button’s draw state changes, and may be overriden by derived classes in order to respond appropriately. For example, certain standard Uikon classes change their border type ready for drawing.

Subclasses should call their own StateChanged() function whenever they update the draw state.

Description

The following member functions provide appropriate implementations of methods declared virtual in CCoeControl.

void HandlePointerEventL
    (const TPointerEvent& aPointerEvent);

Description

Handles pointer events occurring on the control. This function provides an appropriate implementation of CCoeControl::HandlePointerEventL().

Parameters

const TPointerEvent& aPointerEvent The pointer event.

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

Description

Handles key events offered to the control by the control environment. This function provides an appropriate implementation of CCoeControl::OfferKeyEventL().

Parameters

const TKeyEvent& aKeyEvent The key event to respond to. TEventCode aType The event code.

Return value

TKeyResponse Whether or not the key event was consumed.

void HandleResourceChange(TInt aType);

Description

Handles a change to the control's resources which are shared across the environment. For example, colours or fonts.

Parameters

TInt aType The type of resource that has changed.

TCoeInputCapabilities InputCapabilities() const;

Description

Returns the control’s input capabilities.

Return value

TCoeInputCapabilities The control’s input capabilities.

TInt iButFlags

Description

Flags that encode the button’s draw state, behaviour, logical state and whether the button has been pressed. This is expressed as a bitwise OR of the flags defined in TDrawState, TButtonBehavior and TState.

The states may be read with DrawState(), State() and IsPressed(). Derived classes may modify this datum directly.

See also: SetBehaviour()and SetReportOnPointerDown()

enum TDrawState;

Description

Possible states for the draw state

The TDrawState values affecting a button are stored in iButFlags. All draw state flag bits must be maskable by 0x001f; the ones which describe a pressed button must be maskable by 0x0010.

EDrawClear Button is clear. EDrawSet Button is set. EDrawIndeterminate Button is between set and clear. EDrawClearPressed Button is clear, and the user is pressing it. EDrawSetPressed Button is set, and the user is pressing it. EDrawIndeterminatePressed Button is between set and clear, and the user is pressing it.

TState

Description

Possible logical states for a button. TState values represent the logical state of a button. Derived button classes may draw themselves differently to indicate different states. See also State() and SetState().

The state of a non-latching button is, in general, of no interest to applications. What is of interest is the fact that it has been pressed.

EClear The clear state; often drawn as button-up. ESet The set state; often drawn as button-down. EIndeterminate An indeterminate state; often used for an animation stage between the two other buttons, and may be used for derived tri-state buttons.

TButtonBehavior

Description

Specifies button behaviour. TButtonBehaviour values may be bitwise-ORed.

EEikButtonStaysClear Button is always clear. EEikButtonStaysSet Button is always set. EEikButtonLatches Button latches. EEikButtonReportsOnPointerDown Button reports a control event to its observer on just a pointer down rather than on a down followed by an up.