CEikToolBar Class Reference

API published in: S60 1st Ed

Link against: eikdlg.lib eikcoctl.lib

Capability Information

Required Capabilities

None

#include <eiktbar.h>

Inherits CEikControlGroup, and MEikButtonGroup.

Detailed Description

A vertical group of controls displayed down the right-hand side of the screen in an application.

It contains buttons which are used to issue application commands, and other controls. A toolband may also be created using this class, by setting the EEikToolBarHorizontal flag and initialising from a TOOLBAND resource.


Public Member Functions
IMPORT_C	~CEikToolBar ()
	Destructor.
IMPORT_C	CEikToolBar ()
	Default C++ constructor.
IMPORT_C void	ConstructL (MEikCommandObserver *aCommandObserver, TInt aResourceId, const TRect &aBoundingRect)
	Completes construction of a default-constructed toolbar.
IMPORT_C void	StaticConstructL (MEikCommandObserver *aCommandObserver, TInt aResourceId)
	Creates a toolbar from a resource definition, but does not set its extent or activate it.
IMPORT_C void	SetCommandObserver (MEikCommandObserver *aCommandObserver)
	Sets the toolbar's command observer.
IMPORT_C void	CoordinateButtons (TInt aId, TInt aCount, TEikButtonCoordinator *aCoordinator)
	Sets the button co-ordinator for a group of buttons in a toolbar.
IMPORT_C void	SetButtonStateOn (TInt aId, TBool aState)
	Sets the state of the specified button and draws the button to show the new state.
IMPORT_C TBool	DelayActivation () const
	Delays activation of the toolbar when constructed.
IMPORT_C void	ConstructFromResourceL (TResourceReader &aReader)
	Second-phase construction from a resource.
IMPORT_C void	SetDimmed (TBool aDimmed)
	Sets the toolbar dimmed or not dimmed.
IMPORT_C void	GetColorUseListL (CArrayFix< TCoeColorUse > &aColorUseList) const
	Gets the list of logical colours used to draw the control.
IMPORT_C void	HandleResourceChange (TInt aType)
	Handles a change to the control's resources.
IMPORT_C void	HandlePointerEventL (const TPointerEvent &aPointerEvent)
	Handles pointer events.
IMPORT_C void	AddControlL (CCoeControl *aControl, TInt aId)
	Adds a control to the control group.
IMPORT_C void	AddControlL (TEikGroupControl &aGroupControl)
	Adds a control wrapped with its ID and length to the control group.
void	AddControlTypeL (TInt aType)
	Adds a control type to the control type array.
void	RemoveControlType (TInt aIndex)
	Removes a control type from the control type array.
TBool	ControlIsButton (TInt aIndex) const
	Used to check if a control is a button type control or not.
IMPORT_C void	SetBoundingRect (const TRect &aBoundingRect)
	Sets the toolbar's bounding rectangle.
IMPORT_C void	ReduceRect (TRect &aBoundingRect) const
	Shrinks a rectangle to exclude the toolbar area.
Protected Member Functions
IMPORT_C void	WriteInternalStateL (RWriteStream &aWriteStream) const
	Writes the internal state of the control and its components to `aWriteStream`.

Constructor & Destructor Documentation

IMPORT_C CEikToolBar::~CEikToolBar

(

)

Destructor.

Deletes the toolbar's brush and pen context and control types.

IMPORT_C CEikToolBar::CEikToolBar

(

)

Default C++ constructor.

Creates a new toolbar object, but does not initialise any of its heap-stored members.

Member Function Documentation

IMPORT_C void CEikToolBar::AddControlL ( TEikGroupControl & aGroupControl ) [virtual]

Adds a control wrapped with its ID and length to the control group.

From CEikControlGroup

Parameters:

aGroupControl

The wrapped control to add.

Panic:: EIKCOCTL-26 If the control does not exist.

Reimplemented from CEikControlGroup.

IMPORT_C void CEikToolBar::AddControlL	(	CCoeControl *	aControl,
		TInt	aId
	)	`[virtual]`

Adds a control to the control group.

From CEikControlGroup

Parameters:

	aControl	The control to add to the control group
	aId	The control's ID.

Panic:: EIKCOCTL-26 If the control does not exist.

Reimplemented from CEikControlGroup.

void CEikToolBar::AddControlTypeL

(

TInt

aType

)

Adds a control type to the control type array.

IMPORT_C void CEikToolBar::ConstructFromResourceL

(

TResourceReader &

aReader

)

Second-phase construction from a resource.

This is called by StaticConstructL() with an appropriate reader.

From CCoeControl

Parameters:

aReader A resource reader pointing at a TOOLBAR or TOOLBAND resource defining the toolbar.

Panic:: EIKCOCTL-36 If the control on the toolbar cannot be constructed.

IMPORT_C void CEikToolBar::ConstructL	(	MEikCommandObserver *	aCommandObserver,
		TInt	aResourceId,
		const TRect &	aBoundingRect
	)

Completes construction of a default-constructed toolbar.

The command observer interface defines a method for creating custom controls on the toolbar from user-defined IDs specified in the resource aResourceId.

IDs for controls which cannot be constructed using EikControlFactory::CreateByTypeL() are passed to this object's command observer for construction.

Applications requiring custom controls in their toolbars should override their AppUI's CreateCustomCommandControlL() method, inherited from MEikCommandObserver.

Parameters:

aCommandObserver Sets the command observer for this toolbar. The observer's ProcessCommandL() function is invoked when a toolbar command is invoked by the user.

See also:: MEikCommandObserver::ProcessCommandL(). Typically the observer is the application's AppUI.

Parameters:

	aResourceId	The ID of a `TOOLBAR` or `TOOLBAND` resource structure.
	aBoundingRect	Defines the rectangle to which the toolbar's extent must be limited. This is typically given by `CEikAppUi::ClientRect()`, which returns the extent of the whole application window, less the extent of any toolbars that already exist and are owned by the AppUI.

Panic:: EIKCOCTL-36 If the control on the toolbar cannot be constructed.

TBool CEikToolBar::ControlIsButton

(

TInt

aIndex

)

const

Used to check if a control is a button type control or not.

IMPORT_C void CEikToolBar::CoordinateButtons	(	TInt	aId,
		TInt	aCount,
		TEikButtonCoordinator *	aCoordinator
	)

Sets the button co-ordinator for a group of buttons in a toolbar.

Parameters:

	aId	Command identifying a toolbar button.
	aCount	The number of buttons in the group.
	aCoordinator	The button coordinator.

IMPORT_C TBool CEikToolBar::DelayActivation

(

)

const

Delays activation of the toolbar when constructed.

This function sets the toolbar flag EEikToolBarDelayActivation. If this flag is set when ConstructL() is called on the toolbar, the toolbar will be constructed but not activated.

The application can subsequently activate the toolbar by calling CCoeControl::ActivateL().

Returns:: ETrue to delay activation of the toolbar.

IMPORT_C void CEikToolBar::GetColorUseListL ( CArrayFix< TCoeColorUse > & aColorUseList ) const [virtual]

Gets the list of logical colours used to draw the control.

Appends the list to aColorUseList paired with an explanation of how the colours are used.

From CCoeControl

Parameters:

[in,out] aColorUseList The list of logical colours.

Reimplemented from CEikControlGroup.

IMPORT_C void CEikToolBar::HandlePointerEventL

(

const TPointerEvent &

aPointerEvent

)

Handles pointer events.

This function gets called whenever a pointer event occurs in the control, i.e. when the pointer is within the control's extent, or when the control has grabbed the pointer.

If overriding this method, the implementation must include a base call to this method.

From CCoeControl.

Parameters:

aPointerEvent

The pointer event.

Reimplemented from CEikControlGroup.

IMPORT_C void CEikToolBar::HandleResourceChange ( TInt aType ) [virtual]

Handles a change to the control's resources.

The types of resources handled are those which are shared across the environment, e.g. colours or fonts. For colour scheme changes, DrawDeferred() is called in order to redraw the control.

If overriding this method, the implementation must include a base call to this method.

From CCoeControl.

Parameters:

aType

The type of resource that has changed.

Reimplemented from CEikControlGroup.

IMPORT_C void CEikToolBar::ReduceRect ( TRect & aBoundingRect ) const [virtual]

Shrinks a rectangle to exclude the toolbar area.

This function reduces the size of the rectangle passed into the function so that on return, the area occupied by the toolbar or toolband is removed from the rectangle. It is provided to prevent drawing over an existing toolbar or toolband.

From MEikButtonGroup

Parameters:

[in,out] aBoundingRect Specifies a rectangle which, on return, is shrunk to exclude the toolbar’s extent.

Implements MEikButtonGroup.

void CEikToolBar::RemoveControlType

(

TInt

aIndex

)

Removes a control type from the control type array.

IMPORT_C void CEikToolBar::SetBoundingRect ( const TRect & aBoundingRect ) [virtual]

Sets the toolbar's bounding rectangle.

This function has a different effect on the toolbar's extent, depending on whether the toolbar is vertical or horizontal.

For a vertical toolbar, sets the toolbar height to equal the height of the bounding rectangle.

For a horizontal toolbar (toolband), sets the toolband width to equal the width of the bounding rectangle.

From MEikButtonGroup

Parameters:

aBoundingRect

The toolbar's bounding rectangle.

Implements MEikButtonGroup.

IMPORT_C void CEikToolBar::SetButtonStateOn	(	TInt	aId,
		TBool	aState
	)

Sets the state of the specified button and draws the button to show the new state.

Parameters:

	aId	The command that identifies the button.
	aState	`ETrue` to set the button, `EFalse` to clear the button.

IMPORT_C void CEikToolBar::SetCommandObserver

(

MEikCommandObserver *

aCommandObserver

)

Sets the toolbar's command observer.

Applications will not typically need to use this function.

Parameters:

aCommandObserver The command observer for this toolbar. When a command is invoked in the toolbar, HandleCommandL() is called in the observer.

IMPORT_C void CEikToolBar::SetDimmed

(

TBool

aDimmed

)

Sets the toolbar dimmed or not dimmed.

Dimming usually indicates that user input is not accepted.

From CCoeControl

Parameters:

aDimmed ETrue to set as dimmed , EFalse to set as not dimmed.

IMPORT_C void CEikToolBar::StaticConstructL	(	MEikCommandObserver *	aCommandObserver,
		TInt	aResourceId
	)

Creates a toolbar from a resource definition, but does not set its extent or activate it.

This function is used by ConstructL(), applications will not typically need to use it.

Parameters:

	aCommandObserver	Specifies the object in which `HandleCommandL()` is called when a toolbar command is invoked, typically the application's AppUI.
	aResourceId	The resource that defines the toolbar.

Panic:: EIKCOCTL-36 If the control on the toolbar cannot be constructed.

IMPORT_C void CEikToolBar::WriteInternalStateL ( RWriteStream & aWriteStream ) const [protected]

Writes the internal state of the control and its components to aWriteStream.

Does nothing in release mode.

Designed to be overridden and base called from subclasses.

From CCoeControl

Parameters:

[in,out] aWriteStream A connected write stream.

Reimplemented from CEikControlGroup.

The documentation for this class was generated from the following file:

eiktbar.h

CEikToolBar Class Reference

Capability Information

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation