CHuiControl Class Reference

class CHuiControl : public CBase

CHuiControl provides a base class for gathering logical functionality in the UI.

For example a list control could gather (and _control_) all visuals that form a listbox UI element. A thumbnail view control could be used to control visuals that form a thumbnail view in an image gallery application.

Their main use is to handle interaction with the user - Controls handle input events by overriding OfferEventL().

Controls are not visible by themselves, but controls create and manipulate visuals (CHuiVisual) - set target values for visual properties and/or schedule animation commands.Controls are collected in groups (e.g., one group per view), but do not have a hierarchical organization. However controls can be connected to each other for collaboration between multiple controls. AddConnectionL()

Inherits from

Nested Classes and Structures

Public Member Functions
CHuiControl(CHuiEnv &)
~CHuiControl()
IMPORT_C TBoolAcceptInput()
IMPORT_C voidAcquireFocus()
IMPORT_C voidAddConnectionL(CHuiControl *, TInt)
IMPORT_C voidAppendL(CHuiVisual *)
IMPORT_C voidAppendL(CHuiVisual *, CHuiLayout *)
IMPORT_C CHuiLayout *AppendLayoutL(THuiLayoutType, CHuiLayout *)
IMPORT_C CHuiVisual *AppendVisualL(THuiVisualType, CHuiLayout *)
IMPORT_C voidBindDisplay(CHuiDisplay &)
IMPORT_C TRectBounds()
IMPORT_C voidCancelAllCommands()
voidClearChanged()
IMPORT_C CHuiControl &Connection(TInt)
IMPORT_C CHuiControl &ConnectionByOrdinal(TInt)
IMPORT_C TIntConnectionCount()
IMPORT_C TIntConnectionOrdinal(TInt)
IMPORT_C TIntConnectionRole(TInt)
voidConstructL()
IMPORT_C CHuiLayout *ContainerLayout(const CHuiControl *)
IMPORT_C CHuiControlGroup *ControlGroup()
IMPORT_C CHuiDisplay *Display()
IMPORT_C TRectDisplayArea()
IMPORT_C THuiRealPointDisplayCenter()
IMPORT_C TPointDisplayToHost(const TPoint &)
IMPORT_C CHuiEnv &Env()
IMPORT_C MHuiEventHandler *EventHandler()
IMPORT_C TIntFindConnection(const CHuiControl *)
IMPORT_C CHuiVisual *FindTag(const TDesC8 &)
IMPORT_C TBoolFocus()
IMPORT_C voidFocusChanged(CHuiDisplay &, TBool)
voidHide(CHuiDisplay &)
IMPORT_C TBoolHitTest(const TPoint &)
IMPORT_C CHuiControl *Host()
IMPORT_C TIntHostId()
IMPORT_C TPointHostToDisplay(const TPoint &)
IMPORT_C TIntId()
IMPORT_C TBoolIsFocusing()
IMPORT_C TBoolOfferEventL(const THuiEvent &)
IMPORT_C voidRemove(CHuiVisual *)
IMPORT_C voidRemoveConnection(CHuiControl *)
voidRemoveVisualsFromHostControl(CHuiControl &)
IMPORT_C TIntRole()
voidSetControlGroup(CHuiControlGroup &)
voidSetFocus(CHuiDisplay &, TBool)
voidSetFocusing(TBool)
IMPORT_C voidSetHost(CHuiControl *)
IMPORT_C voidSetHostId(TInt)
IMPORT_C voidSetId(TInt)
IMPORT_C voidSetRole(TInt)
voidShowL(CHuiDisplay &)
IMPORT_C CHuiTextureManager &TextureManager()
IMPORT_C CHuiVisual &Visual(TInt)
IMPORT_C TIntVisualCount()
IMPORT_C voidVisualDestroyed(CHuiVisual &)
IMPORT_C voidVisualLayoutUpdated(CHuiVisual &)
IMPORT_C voidVisualPrepareDrawFailed(CHuiVisual &, TInt)
Protected Member Functions
IMPORT_C voidBaseConstructL()
IMPORT_C voidConnectionAddedL(CHuiControl *, TInt)
IMPORT_C voidConnectionRemoved(CHuiControl *, TInt)
IMPORT_C voidControlExtension(const TUid &, TAny **)
IMPORT_C voidHostChangingL(CHuiControl *)
IMPORT_C voidNotifyControlVisibility(TBool, CHuiDisplay &)
IMPORT_C TIntSessionId()
IMPORT_C voidSetSessionId(TInt)
IMPORT_C TTypeType()
IMPORT_C voidVisualAddedL(CHuiVisual *)
IMPORT_C voidVisualRemoved(CHuiVisual *)
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Private Attributes
CHuiDisplay *iBoundDisplay
RArray< SConnection >iConnections
CHuiEnv &iEnv
TBool iFocusing
TBool iHasFocus
CHuiControl *iHost
TInt iHostId
TInt iId
CHuiControlGroup *iOwnerGroup
TInt iRole
TInt iSessionId
TAny *iSpare
RPointerArray< CHuiVisual >iVisuals

Constructor & Destructor Documentation

CHuiControl(CHuiEnv &)

IMPORT_CCHuiControl(CHuiEnv &aEnv)

Constructs this control. An unique ID for this control is generated for this control using CHuiStatic::GenerateId(); Id()TodoThis constructor is public, explain rationale.

Parameters

CHuiEnv & aEnv

~CHuiControl()

IMPORT_C~CHuiControl()

Destructs this control. Cancels all scheduled commands for this control. Removes the host and any other connections (if any) and destroys the visuals owned by this control.

Member Functions Documentation

AcceptInput()

IMPORT_C TBoolAcceptInput()const

Determines whether the control accepts input events.

AcquireFocus()

IMPORT_C voidAcquireFocus()

Acquires focus for this control.

AddConnectionL(CHuiControl *, TInt)

IMPORT_C voidAddConnectionL(CHuiControl *aConnectedControl,
TIntaRole = 0
)[virtual]

New virtual method. Establishes a connection between this control and another control. Instead of supporting a treelike parent-child control hierarchy, Hitchcock allows defining a set of links between any controls. These links are called connections. Connections can be used to construct a parent-child based hierarchy of controls, if that is considered necessary from the point of view of input event handling or some other data passing scenario. They can be utilized for observation purposes or keeping track of associated controls.

HUITK Programmer's Guide for examples of how to connect controls.

Parameters

CHuiControl * aConnectedControlControl to connect.
TInt aRole = 0Role of the control. Interpretation depends on the host.

AppendL(CHuiVisual *)

IMPORT_C voidAppendL(CHuiVisual *aVisual)

From MHuiVisualOwner. Appends a visual to the control. The control also receives ownership of the visual. This method is specifically intended to be used when adding previously created visuals to the control.

Parameters

CHuiVisual * aVisualVisual to add. Control gets ownership.

AppendL(CHuiVisual *, CHuiLayout *)

IMPORT_C voidAppendL(CHuiVisual *aVisual,
CHuiLayout *aParentLayout
)

Appends a new visual to the list of visuals owned by the control. This method is specifically intended to be used during construction of visual trees.

Parameters

CHuiVisual * aVisualVisual to append.
CHuiLayout * aParentLayout

AppendLayoutL(THuiLayoutType, CHuiLayout *)

IMPORT_C CHuiLayout *AppendLayoutL(THuiLayoutTypeaLayoutType,
CHuiLayout *aParentLayout = NULL
)

Creates a new layout using the visual factory and appends it.

Parameters

THuiLayoutType aLayoutTypeType of the layout to create.
CHuiLayout * aParentLayout = NULL

AppendVisualL(THuiVisualType, CHuiLayout *)

IMPORT_C CHuiVisual *AppendVisualL(THuiVisualTypeaVisualType,
CHuiLayout *aParentLayout = NULL
)

Creates a new visual using the visual factory and appends it.

Parameters

THuiVisualType aVisualTypeType of the visual to create.
CHuiLayout * aParentLayout = NULL

BaseConstructL()

IMPORT_C voidBaseConstructL()[protected, virtual]

Virtual second phase constructor. Must be base called in deriving class.

BindDisplay(CHuiDisplay &)

IMPORT_C voidBindDisplay(CHuiDisplay &aDisplay)

Binds the control to a display. Called automatically by CHuiControl::ShowL().

Parameters

CHuiDisplay & aDisplay

Bounds()

IMPORT_C TRectBounds()const

Calculates the region of the screen where the control's visuals are.

CancelAllCommands()

IMPORT_C voidCancelAllCommands()

Cancel all scheduled commands related to this control and the control's visuals.

ClearChanged()

voidClearChanged()

Clears the change flags of the control.

Connection(TInt)

IMPORT_C CHuiControl &Connection(TIntaIndex)const

Returns a client control.

Parameters

TInt aIndexIndex of the client.

ConnectionAddedL(CHuiControl *, TInt)

IMPORT_C voidConnectionAddedL(CHuiControl *aConnectedControl,
TIntaRole
)[protected, virtual]

New virtual method. Called when a client control is added to the control.

AddConnectionL()

Parameters

CHuiControl * aConnectedControl
TInt aRole

ConnectionByOrdinal(TInt)

IMPORT_C CHuiControl &ConnectionByOrdinal(TIntaOrdinal)const

Returns a client control.

Parameters

TInt aOrdinalRole or index.

ConnectionCount()

IMPORT_C TIntConnectionCount()const

Returns the number of clients.

ConnectionOrdinal(TInt)

IMPORT_C TIntConnectionOrdinal(TIntaIndex)const

Ordinal is the effective index. Role overrides index. AddConnectionL()

Parameters

TInt aIndex

ConnectionRemoved(CHuiControl *, TInt)

IMPORT_C voidConnectionRemoved(CHuiControl *aConnectedControl,
TIntaRole
)[protected, virtual]

New virtual method. Called when a client control is removed from the control.

RemoveConnection()

Parameters

CHuiControl * aConnectedControl
TInt aRole

ConnectionRole(TInt)

IMPORT_C TIntConnectionRole(TIntaIndex)const

Returns the role of a client control.

Roles are defined by the application developer - a user interface framework built on top of Hitchcock can define a suitable set of roles for the controls implemented in the framework.

AddConnectionL()

Parameters

TInt aIndexIndex of the client.

ConstructL()

voidConstructL()[inline]

ContainerLayout(const CHuiControl *)

IMPORT_C CHuiLayout *ContainerLayout(const CHuiControl *aConnected)const [virtual]

Returns a container layout for the specified child control. A container layout contains all the visuals of a child control.

Parameters

const CHuiControl * aConnectedChild connection, which is querying for the visual host.

ControlExtension(const TUid &, TAny **)

IMPORT_C voidControlExtension(const TUid &aExtensionUid,
TAny **aExtensionParams
)[protected, virtual]

Parameters

const TUid & aExtensionUid
TAny ** aExtensionParams

ControlGroup()

IMPORT_C CHuiControlGroup *ControlGroup()const

From MHuiVisualOwner. Returns the control group of the visual's owner control.

Display()

IMPORT_C CHuiDisplay *Display()const

Returns the display this control is bound to, or NULL.

DisplayArea()

IMPORT_C TRectDisplayArea()const

Determines the display area.

DisplayCenter()

IMPORT_C THuiRealPointDisplayCenter()const

Determines the coordinates of the center of the display.

DisplayToHost(const TPoint &)

IMPORT_C TPointDisplayToHost(const TPoint &aPoint)const

Coordinate conversion.

Parameters

const TPoint & aPoint

Env()

IMPORT_C CHuiEnv &Env()const

From MHuiVisualOwner. Returns the environment of the visual.

EventHandler()

IMPORT_C MHuiEventHandler *EventHandler()

From MHuiVisualOwner. Returns a pointer to the event handler responsible for handling events related this control's visuals (i.e. the handler is this control).

FindConnection(const CHuiControl *)

IMPORT_C TIntFindConnection(const CHuiControl *aConnected)const

Find a client's index number.

Parameters

const CHuiControl * aConnectedConnected control to find.

FindTag(const TDesC8 &)

IMPORT_C CHuiVisual *FindTag(const TDesC8 &aTag)const

Finds the visual that matches a tag. Only the visuals owned by this control are searched.

Parameters

const TDesC8 & aTagTag descriptor to match against.

Focus()

IMPORT_C TBoolFocus()const

Determines whether the control has input focus.

FocusChanged(CHuiDisplay &, TBool)

IMPORT_C voidFocusChanged(CHuiDisplay &aDisplay,
TBooliFocused
)[virtual]

New virtual method. Called when the control's focus state changes.

Parameters

CHuiDisplay & aDisplay
TBool iFocused

Hide(CHuiDisplay &)

voidHide(CHuiDisplay &aDisplay)

Hides those visuals that are displayed on the specified display. Other visuals are not affected.

Parameters

CHuiDisplay & aDisplayDisplay to remove visuals from.

HitTest(const TPoint &)

IMPORT_C TBoolHitTest(const TPoint &aPoint)const

Tests whether a point is inside the control.

Parameters

const TPoint & aPointPoint in display coordinates.

Host()

IMPORT_C CHuiControl *Host()const

Returns the visual host control.

HostChangingL(CHuiControl *)

IMPORT_C voidHostChangingL(CHuiControl *aNewHost)[protected, virtual]

New virtual method. The host control is about to be changed. The control needs to add its visuals to the container layout provided by the new host.

SetHost()

Parameters

CHuiControl * aNewHost

HostId()

IMPORT_C TIntHostId()const

Returns the automatic visual host identification.

HostToDisplay(const TPoint &)

IMPORT_C TPointHostToDisplay(const TPoint &aPoint)const

Coordinate conversion.

Parameters

const TPoint & aPoint

Id()

IMPORT_C TIntId()const

Returns the id of this control. Zero (0) id the control has no id.

IsFocusing()

IMPORT_C TBoolIsFocusing()const [virtual]

New virtual method. Determines whether the control wants to receive focus.

NotifyControlVisibility(TBool, CHuiDisplay &)

IMPORT_C voidNotifyControlVisibility(TBoolaIsVisible,
CHuiDisplay &aDisplay
)[protected, virtual]

New virtual method. Notifies the control that its visible has been changed on a display. This is the earliest time when the control knows the dimensions of the display it is being shown on.

Parameters

TBool aIsVisibleETrue, if the control is now visible on the display. EFalse, if the control is about to the hidden on the display.
CHuiDisplay & aDisplayThe display on which the control's visibility is changing.

OfferEventL(const THuiEvent &)

IMPORT_C TBoolOfferEventL(const THuiEvent &aEvent)

From MHuiEventHandler. Called when an input event is being offered to the control.

Parameters

const THuiEvent & aEventEvent to be handled.

Remove(CHuiVisual *)

IMPORT_C voidRemove(CHuiVisual *aVisual)

From MHuiVisualOwner. Removes a visual from the control. The caller also receives ownership of the visual.

Parameters

CHuiVisual * aVisualVisual to remove. Caller gets ownership.

RemoveConnection(CHuiControl *)

IMPORT_C voidRemoveConnection(CHuiControl *aConnectedControl)

Removes a client.

Parameters

CHuiControl * aConnectedControlConnected control to remove.

RemoveVisualsFromHostControl(CHuiControl &)

voidRemoveVisualsFromHostControl(CHuiControl &aHostControl)

Remove this control's visuals from the specified container layout.

Parameters

CHuiControl & aHostControlHost control.

Role()

IMPORT_C TIntRole()const

Returns the control's role.

AddConnectionL()

SessionId()

IMPORT_C TIntSessionId()const [protected]

! Gets the session id for object.

SetControlGroup(CHuiControlGroup &)

voidSetControlGroup(CHuiControlGroup &aOwnerGroup)

Sets the group that owns the control. Called by the control group when the control is added to the group.

Parameters

CHuiControlGroup & aOwnerGroupOwner group.

SetFocus(CHuiDisplay &, TBool)

voidSetFocus(CHuiDisplay &aDisplay,
TBoolaHasFocus
)

Changes the control's focus state.

Parameters

CHuiDisplay & aDisplay
TBool aHasFocus

SetFocusing(TBool)

voidSetFocusing(TBoolaFocusing)

Sets the flag that tells whether the control wants to receive focus.

Parameters

TBool aFocusing

SetHost(CHuiControl *)

IMPORT_C voidSetHost(CHuiControl *aHost)

Parameters

CHuiControl * aHost

SetHostId(TInt)

IMPORT_C voidSetHostId(TIntaHostId)

Sets the automatic visual host identification (non zero). Needs to be unique in the CHuiEnv. If using this automatic mechanism, do not use the AddConnectionL() function - it will be automatically called when this control is shown.

Parameters

TInt aHostId

SetId(TInt)

IMPORT_C voidSetId(TIntaId)

Set an id value for this control.

Parameters

TInt aId

SetRole(TInt)

IMPORT_C voidSetRole(TIntaRole)

Sets the control's role.

AddConnectionL()

Parameters

TInt aRoleConnection role.

SetSessionId(TInt)

IMPORT_C voidSetSessionId(TIntaSessionId)[protected]

! Sets the session id for object.

Parameters

TInt aSessionId

ShowL(CHuiDisplay &)

voidShowL(CHuiDisplay &aDisplay)

Shows all the unshown visuals of the control on the specified display. Visuals that are currently shown on another display are not affected.

CHuiControl::BindDisplay()

Parameters

CHuiDisplay & aDisplayDisplay to add visuals to.

TextureManager()

IMPORT_C CHuiTextureManager &TextureManager()const

Returns the texture manager of the environment of the visual.

Type()

IMPORT_C TTypeType()const [protected]

! Gets the object type.

Visual(TInt)

IMPORT_C CHuiVisual &Visual(TIntaIndex)const

Returns one of the visuals owned by the control.

Parameters

TInt aIndexIndex number of the visual to return.

VisualAddedL(CHuiVisual *)

IMPORT_C voidVisualAddedL(CHuiVisual *aVisual)[protected, virtual]

New virtual method. Called when a visual has been added to the control.

Parameters

CHuiVisual * aVisualVisual that was added.

VisualCount()

IMPORT_C TIntVisualCount()const

Determines the number of visuals owned by the control.

Note that in visual hierarchies, child visuals are not owned by their parent visuals, but a control. This means that a control that owns a tree of visuals will return the total number of visuals in the tree, and not just the number of root visuals.

VisualDestroyed(CHuiVisual &)

IMPORT_C voidVisualDestroyed(CHuiVisual &aVisual)

From MHuiVisualOwner. Called when a visual owned by the control is being destroyed. Visual is removed from the control.

Parameters

CHuiVisual & aVisualVisual about to the destroyed.

VisualLayoutUpdated(CHuiVisual &)

IMPORT_C voidVisualLayoutUpdated(CHuiVisual &aVisual)

From MHuiVisualOwner. Notifies the control that one of the visuals it ows has been laid out. Called automatically from CHuiVisual::UpdateChildrenLayout(). For example, occurs when a parent layout is resized.

Parameters

CHuiVisual & aVisualVisual whose layout was updated.

VisualPrepareDrawFailed(CHuiVisual &, TInt)

IMPORT_C voidVisualPrepareDrawFailed(CHuiVisual &aVisual,
TIntaErrorCode
)

From MHuiVisualOwner. Called when there was an error (a leave happened) while preparing one of the controls visual for drawing. Typically the resource alloc errors such as out of memory is escalated through this callback.

By default this callback causes a panic with the error code, so you should override this if you want different behavior.

Parameters

CHuiVisual & aVisualVisual that caused the error.
TInt aErrorCodeSymbian KErr error code for the failure.

VisualRemoved(CHuiVisual *)

IMPORT_C voidVisualRemoved(CHuiVisual *aVisual)[protected, virtual]

New virtual method. Called when a visual has been removed from the control.

Parameters

CHuiVisual * aVisualVisual that was removed.

Member Data Documentation

CHuiDisplay * iBoundDisplay

CHuiDisplay *iBoundDisplay[private]

The display this control is currently bound to.

RArray< SConnection > iConnections

RArray< SConnection >iConnections[private]

Connected controls and their roles.

CHuiEnv & iEnv

CHuiEnv &iEnv[private]

The environment where this visual belong to.

TBool iFocusing

TBool iFocusing[private]

ETrue, if the control wants to receive input focus.

TBool iHasFocus

TBool iHasFocus[private]

Control has input focus.

CHuiControl * iHost

CHuiControl *iHost[private]

Host control. The host provides a container visual for this control's visuals.

TInt iHostId

TInt iHostId[private]

Identifier of the host control.

TInt iId

TInt iId[private]

Identifier of the control.

CHuiControlGroup * iOwnerGroup

CHuiControlGroup *iOwnerGroup[private]

The group into which this control belongs to.

TInt iRole

TInt iRole[private]

Control's role.

TInt iSessionId

TInt iSessionId[private]

Session id

TAny * iSpare

TAny *iSpare[private]

RPointerArray< CHuiVisual > iVisuals

RPointerArray< CHuiVisual >iVisuals[private]

Visuals owned by the control.