Symbian^3 Application 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

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.

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.