Collapse all Symbian^3 Product Developer Library

Alf::IAlfWidgetControl Class Reference

class Alf::IAlfWidgetControl : public Alf::IAlfInterfaceBase

The interface for widget controls. Widget controls are derived from Alfred controls. This is the primary interface to access the widget control functionality. Alfred control interface can be queried, but direct access should not be needed. Widget controls are responsible for the widget logic, i.e., storing and controlling the state of the widget. This usually includes input event handling, updating the presentation, and communication with the model, the application, and other controls. Event handlers can be used to implement parts of the widget logic.

alfwidgetmodel.lib

Since: S60 ?S60_version Draft

Inherits from

Alf::IAlfWidgetControl
- Alf::IAlfInterfaceBase

Public Member Functions
	~IAlfWidgetControl()
void	addElement(IAlfElement *)
void	addEventHandler(IAlfWidgetEventHandler *, int)
bool	checkState(uint)
uint	dataIdRange(const IAlfElement &)
uint	dataIdToIndex(const IAlfElement &, uint)
void	destroyPresentation(int)
void	destroyVisualsAndElements(int)
void	disableState(uint)
IAlfElement &	element(int)
IAlfVariantType *	elementData(const IAlfElement &, uint)
uint	elementDataId(const IAlfElement &, uint, uint)
void	enableState(uint)
IAlfWidgetEventHandler &	eventHandler(int)
int	eventHandlerIndex(IAlfWidgetEventHandler &)
IAlfElement *	findElement(const char *)
IAlfWidgetEventHandler *	findEventHandler(const TAlfEvent &)
AlfEventStatus	handleEvent(const TAlfEvent &)
int	numElements()
int	numEventHandlers()
uint	parentElementDataId(const IAlfElement &, uint)
void	removeAndDestroyElement(const IAlfElement &)
void	removeAndDestroyEventHandler(IAlfWidgetEventHandler &)
void	removeAndDestroyEventHandler(const UString &)
void	removeAndDestroyPresentationEventHandlers()
void	removeElement(const IAlfElement &)
void	removeEventHandler(IAlfWidgetEventHandler &)
void	removePresentationEventHandlers()
void	setDataIdRange(const IAlfElement &, uint)
void	setState(uint)
uint	state()
const IfId &	type()
void	updatePresentation()
AlfWidget *	widget()

Public Attributes
const uint	Enabled
const uint	Focusable
const uint	Focused
const uint	Visible

Constructor & Destructor Documentation

~IAlfWidgetControl()

~IAlfWidgetControl

(

)

[inline, virtual]

Virtual destructor.

Since: S60 ?S60_version

Member Functions Documentation

addElement(IAlfElement *)

void

addElement

(

IAlfElement *

aElement

)

[pure virtual]

Add a new element. The control takes the ownership of the element.

Since: S60 ?S60_version

Parameters

IAlfElement * aElement

The element to be added.

addEventHandler(IAlfWidgetEventHandler *, int)

void	addEventHandler	(	IAlfWidgetEventHandler *	aEventHandler,
			int	aIndex = -1
		)	[pure virtual]

Add a new event handler. The control takes the ownership of the event handler.

Since: S60 ?S60_version

Parameters

IAlfWidgetEventHandler * aEventHandler	The event handler to be added.
int aIndex = -1	The index of the new event handler, or -1 to append the event handler after the existing event handlers.

checkState(uint)

bool

checkState

(

uint

aState

)

const [pure virtual]

Checks the current state of the widget control for a single aspect. This is equal to enabled = State() & aState

The parameter passed in should usually be a single bit state aspect e.g. IAlfWidgetControl::Focusable If a pattern with more than one bit set is passed in, the result is not easily usable.

Since: S60 ?S60_version

Parameters

uint aState

a state bit pattern to test

dataIdRange(const IAlfElement &)

uint

dataIdRange

(

const IAlfElement &

aElement

)

[pure virtual]

Get the range of data ids for the given element. The range is used for data mapping in ElementDataId() and ElementData(). SetDataIdRange().

Since: S60 ?S60_version

Parameters

const IAlfElement & aElement

The element.

dataIdToIndex(const IAlfElement &, uint)

uint	dataIdToIndex	(	const IAlfElement &	aElement,
			uint	aDataId
		)	[pure virtual]

Get the index of the given child data id in the parent data container. In the default implementation, the parent data id is calculated as follows: \[ index = aDataId % DataIdRange( aElement ) \] The implementation should match the functionality of ElementDataId().

Since: S60 ?S60_version

Parameters

const IAlfElement & aElement	The element associated with the given data id.
uint aDataId	The data id.

destroyPresentation(int)

void

destroyPresentation

(

int

aTimeMilliseconds

)

[pure virtual]

Remove visuals from all elements. The visuals are destroyed after the given delay. This allows executing an animation sequence before the actual destruction of visuals.

Since: S60 ?S60_version

Parameters

int aTimeMilliseconds

The remaining time to destruction of all visuals.

destroyVisualsAndElements(int)

void

destroyVisualsAndElements

(

int

aTimeMilliseconds = 0

)

[pure virtual]

Remove visuals from all elements and destroy all elements. The visuals and elements are destroyed after the given delay. This allows executing an animation sequence before the actual destruction of visuals.

Since: S60 ?S60_version

Parameters

int aTimeMilliseconds = 0

The remaining time to destruction of all visuals.

disableState(uint)

void

disableState

(

uint

aState

)

[pure virtual]

Disable given states.

This method modifies a state by clearing bits. No bits are set. This is equal to SetState( State() & ( 0xFFFFFFFF ^ aState ) ).

The resulting state is tested for the invariants documented with setState() and throws the same exceptions.

Since: S60 ?S60_version

Parameters

uint aState

The states to be disabled.

element(int)

IAlfElement &

element

(

int

aIndex

)

[pure virtual]

Get an element by index.

Since: S60 ?S60_version

Parameters

int aIndex

The index of the element to get.

elementData(const IAlfElement &, uint)

IAlfVariantType *	elementData	(	const IAlfElement &	aElement,
			uint	aDataId
		)	[pure virtual]

Get data for a visual tree created by the given element.

Since: S60 ?S60_version

Parameters

const IAlfElement & aElement	The element containing the visual tree.
uint aDataId	The data id of the visual tree.

elementDataId(const IAlfElement &, uint, uint)

uint	elementDataId	(	const IAlfElement &	aElement,
			uint	aIndex,
			uint	aParentDataId
		)	[pure virtual]

Get an id for mapping data to a visual tree created by an element. The data id is required to be unique withing the scope of the element. The parent data id and data id ranges specified by SetDataIdRange can be used to calculate data ids in hierarchical element structures. In the default implementation, the data id is calculated as follows: \[ data id = aParentDataId * DataIdRange( aElement ) + aIndex \]

Since: S60 ?S60_version

Parameters

const IAlfElement & aElement	The element to associate the data id with.
uint aIndex	The index of the data field.
uint aParentDataId	The parent data id in the data hierarchy.

enableState(uint)

void

enableState

(

uint

aState

)

[pure virtual]

Enable given states.

This method modifies a state by enabling bits. No bits are disabled. This is equal to SetState( State() | aState ).

The resulting state is tested for the invariants documented with setState() and throws the same exceptions.

Since: S60 ?S60_version

Parameters

uint aState

The states to be enabled.

eventHandler(int)

IAlfWidgetEventHandler &

eventHandler

(

int

aIndex

)

[pure virtual]

Get an event handler by index.

Since: S60 ?S60_version

Parameters

int aIndex

The index of the event handler to get.

eventHandlerIndex(IAlfWidgetEventHandler &)

int

eventHandlerIndex

(

IAlfWidgetEventHandler &

aEventHandler

)

const [pure virtual]

Get the index of the given event handler. The index specifies the order in which the event handlers are processed.

Since: S60 ?S60_version

Parameters

IAlfWidgetEventHandler & aEventHandler

The event handler.

findElement(const char *)

IAlfElement *

findElement

(

const char *

aName

)

[pure virtual]

Find an element by name.

Since: S60 ?S60_version

Parameters

const char * aName

The name of the element to find.

findEventHandler(const TAlfEvent &)

IAlfWidgetEventHandler *

findEventHandler

(

const TAlfEvent &

aEvent

)

[pure virtual]

Find an event handler responsible for the given event.

Since: S60 ?S60_version

Parameters

const TAlfEvent & aEvent

The event.

handleEvent(const TAlfEvent &)

AlfEventStatus

handleEvent

(

const TAlfEvent &

aEvent

)

[pure virtual]

Handles events sent to widget control.

Since: S60 ?S60_version

Parameters

const TAlfEvent & aEvent

The event to be handled.

numElements()

int

numElements

(

)

const [pure virtual]

Get the number of elements in the control.

Since: S60 ?S60_version

numEventHandlers()

int

numEventHandlers

(

)

const [pure virtual]

Get the number of event handlers in the control.

Since: S60 ?S60_version

parentElementDataId(const IAlfElement &, uint)

uint	parentElementDataId	(	const IAlfElement &	aElement,
			uint	aDataId
		)	[pure virtual]

Get the parent data id from the given data id. In the default implementation, the parent data id is calculated as follows: \[ parent data id = aDataId / DataIdRange( aElement ) \] The implementation should match the functionality of ElementDataId().

Since: S60 ?S60_version

Parameters

const IAlfElement & aElement	The element associated with the given data id.
uint aDataId	The data id.

removeAndDestroyElement(const IAlfElement &)

void

removeAndDestroyElement

(

const IAlfElement &

aElement

)

[pure virtual]

Remove and destroy an element. All visuals created by the element are destroyed.

Since: S60 ?S60_version

Parameters

const IAlfElement & aElement

The element to be removed and destroyed.

removeAndDestroyEventHandler(IAlfWidgetEventHandler &)

void

removeAndDestroyEventHandler

(

IAlfWidgetEventHandler &

aEventHandler

)

[pure virtual]

Remove and destroy an event handler.

Since: S60 ?S60_version

Parameters

IAlfWidgetEventHandler & aEventHandler

The event handler to be removed and destroyed.

removeAndDestroyEventHandler(const UString &)

void

removeAndDestroyEventHandler

(

const UString &

aHandlerId

)

[pure virtual]

Remove and destroy an event handler from the control bases on its name.

Since: S60 ?S60_version

Parameters

const UString & aHandlerId

The name/Id of the event handler to be removed and destroyed.

removeAndDestroyPresentationEventHandlers()

void

removeAndDestroyPresentationEventHandlers

(

)

[pure virtual]

Remove and destroy all event handlers associated with presentation.

Since: S60 ?S60_version

removeElement(const IAlfElement &)

void

removeElement

(

const IAlfElement &

aElement

)

[pure virtual]

Remove an element.

Since: S60 ?S60_version

Parameters

const IAlfElement & aElement

The element to be removed.

removeEventHandler(IAlfWidgetEventHandler &)

void

removeEventHandler

(

IAlfWidgetEventHandler &

aEventHandler

)

[pure virtual]

Remove and destroy an event handler.

Since: S60 ?S60_version

Parameters

IAlfWidgetEventHandler & aEventHandler

The event handler to be removed and destroyed.

removePresentationEventHandlers()

void

removePresentationEventHandlers

(

)

[pure virtual]

Removes all event handlers associated with presentation from this control.

Since: S60 ?S60_version

setDataIdRange(const IAlfElement &, uint)

void	setDataIdRange	(	const IAlfElement &	aElement,
			uint	aRange
		)	[pure virtual]

Set the range of data ids for an element. The range is used for data mapping in ElementDataId() and ElementData(). The default range for all elements is 0xFFFFFFFF. The ranges need to be adjusted for child elements in hierarchical element structures. Otherwise,the data ids will overflow and not remain unique. ElementDataId().

Since: S60 ?S60_version

Parameters

const IAlfElement & aElement	The element.
uint aRange	The range of data ids.

setState(uint)

void

setState

(

uint

aState

)

[pure virtual]

Sets the widget control's state.

The entire state of the widget is set to the passed-in value.

The new state must conform to the following invariants:

If IAlfWidgetControl::Focus is set, then IAlfWidgetControl::Focusable must also be set If IAlfWidgetControl::Focusable is set, then IAlfWidgetControl::Enabled must also be set

If these invariants are violated, then this method will throw AlfException::EInvalidArgument

Since: S60 ?S60_version

Parameters

uint aState

The new state of the control.

state()

uint

state

(

)

const [pure virtual]

Get the state of the control. The state is a combination of binary state flags.

The individual aspects of the state can be queried by testing for the bits in the return value.

Since: S60 ?S60_version

type()

const IfId &

type

(

)

[static, inline]

updatePresentation()

void

updatePresentation

(

)

[pure virtual]

Create or update the presentation for the widget.

Since: S60 ?S60_version

widget()

AlfWidget *

widget

(

)

[pure virtual]

Get the owner widget of this control.

Since: S60 ?S60_version

Member Data Documentation

const uint Enabled

const uint

Enabled

[static]

const uint Focusable

const uint

Focusable

[static]

const uint Focused

const uint

Focused

[static]

const uint Visible

const uint

Visible

[static]

Defines the bitflags used with the state interfaces.