Symbian^3 Application Developer Library >

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 TBool AcceptInput ()
IMPORT_C void AcquireFocus ()
IMPORT_C void AddConnectionL ( CHuiControl *, TInt )
IMPORT_C void AppendL ( CHuiVisual *)
IMPORT_C void AppendL ( CHuiVisual *, CHuiLayout *)
IMPORT_C CHuiLayout * AppendLayoutL ( THuiLayoutType , CHuiLayout *)
IMPORT_C CHuiVisual * AppendVisualL ( THuiVisualType , CHuiLayout *)
IMPORT_C void BindDisplay (CHuiDisplay &)
IMPORT_C TRect Bounds ()
IMPORT_C void CancelAllCommands ()
void ClearChanged ()
IMPORT_C CHuiControl & Connection ( TInt )
IMPORT_C CHuiControl & ConnectionByOrdinal ( TInt )
IMPORT_C TInt ConnectionCount ()
IMPORT_C TInt ConnectionOrdinal ( TInt )
IMPORT_C TInt ConnectionRole ( TInt )
void ConstructL ()
IMPORT_C CHuiLayout * ContainerLayout (const CHuiControl *)
IMPORT_C CHuiControlGroup * ControlGroup ()
IMPORT_C CHuiDisplay * Display ()
IMPORT_C TRect DisplayArea ()
IMPORT_C THuiRealPoint DisplayCenter ()
IMPORT_C TPoint DisplayToHost (const TPoint &)
IMPORT_C CHuiEnv & Env ()
IMPORT_C MHuiEventHandler * EventHandler ()
IMPORT_C TInt FindConnection (const CHuiControl *)
IMPORT_C CHuiVisual * FindTag (const TDesC8 &)
IMPORT_C TBool Focus ()
IMPORT_C void FocusChanged (CHuiDisplay &, TBool )
void Hide (CHuiDisplay &)
IMPORT_C TBool HitTest (const TPoint &)
IMPORT_C CHuiControl * Host ()
IMPORT_C TInt HostId ()
IMPORT_C TPoint HostToDisplay (const TPoint &)
IMPORT_C TInt Id ()
IMPORT_C TBool IsFocusing ()
IMPORT_C TBool OfferEventL (const THuiEvent &)
IMPORT_C void Remove ( CHuiVisual *)
IMPORT_C void RemoveConnection ( CHuiControl *)
void RemoveVisualsFromHostControl ( CHuiControl &)
IMPORT_C TInt Role ()
void SetControlGroup (CHuiControlGroup &)
void SetFocus (CHuiDisplay &, TBool )
void SetFocusing ( TBool )
IMPORT_C void SetHost ( CHuiControl *)
IMPORT_C void SetHostId ( TInt )
IMPORT_C void SetId ( TInt )
IMPORT_C void SetRole ( TInt )
void ShowL (CHuiDisplay &)
IMPORT_C CHuiTextureManager & TextureManager ()
IMPORT_C CHuiVisual & Visual ( TInt )
IMPORT_C TInt VisualCount ()
IMPORT_C void VisualDestroyed ( CHuiVisual &)
IMPORT_C void VisualLayoutUpdated ( CHuiVisual &)
IMPORT_C void VisualPrepareDrawFailed ( CHuiVisual &, TInt )
Protected Member Functions
IMPORT_C void BaseConstructL ()
IMPORT_C void ConnectionAddedL ( CHuiControl *, TInt )
IMPORT_C void ConnectionRemoved ( CHuiControl *, TInt )
IMPORT_C void ControlExtension (const TUid &, TAny **)
IMPORT_C void HostChangingL ( CHuiControl *)
IMPORT_C void NotifyControlVisibility ( TBool , CHuiDisplay &)
IMPORT_C TInt SessionId ()
IMPORT_C void SetSessionId ( TInt )
IMPORT_C TType Type ()
IMPORT_C void VisualAddedL ( CHuiVisual *)
IMPORT_C void VisualRemoved ( 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_C CHuiControl ( 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 TBool AcceptInput ( ) const

Determines whether the control accepts input events.

AcquireFocus()

IMPORT_C void AcquireFocus ( )

Acquires focus for this control.

AddConnectionL(CHuiControl *, TInt)

IMPORT_C void AddConnectionL ( CHuiControl * aConnectedControl,
TInt aRole = 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 * aConnectedControl Control to connect.
TInt aRole = 0 Role of the control. Interpretation depends on the host.

AppendL(CHuiVisual *)

IMPORT_C void AppendL ( 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 * aVisual Visual to add. Control gets ownership.

AppendL(CHuiVisual *, CHuiLayout *)

IMPORT_C void AppendL ( 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 * aVisual Visual to append.
CHuiLayout * aParentLayout

AppendLayoutL(THuiLayoutType, CHuiLayout *)

IMPORT_C CHuiLayout * AppendLayoutL ( THuiLayoutType aLayoutType,
CHuiLayout * aParentLayout = NULL
)

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

Parameters

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

AppendVisualL(THuiVisualType, CHuiLayout *)

IMPORT_C CHuiVisual * AppendVisualL ( THuiVisualType aVisualType,
CHuiLayout * aParentLayout = NULL
)

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

Parameters

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

BaseConstructL()

IMPORT_C void BaseConstructL ( ) [protected, virtual]

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

BindDisplay(CHuiDisplay &)

IMPORT_C void BindDisplay ( CHuiDisplay & aDisplay )

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

Parameters

CHuiDisplay & aDisplay

Bounds()

IMPORT_C TRect Bounds ( ) const

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

CancelAllCommands()

IMPORT_C void CancelAllCommands ( )

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

ClearChanged()

void ClearChanged ( )

Clears the change flags of the control.

Connection(TInt)

IMPORT_C CHuiControl & Connection ( TInt aIndex ) const

Returns a client control.

Parameters

TInt aIndex Index of the client.

ConnectionAddedL(CHuiControl *, TInt)

IMPORT_C void ConnectionAddedL ( CHuiControl * aConnectedControl,
TInt aRole
) [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 ( TInt aOrdinal ) const

Returns a client control.

Parameters

TInt aOrdinal Role or index.

ConnectionCount()

IMPORT_C TInt ConnectionCount ( ) const

Returns the number of clients.

ConnectionOrdinal(TInt)

IMPORT_C TInt ConnectionOrdinal ( TInt aIndex ) const

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

Parameters

TInt aIndex

ConnectionRemoved(CHuiControl *, TInt)

IMPORT_C void ConnectionRemoved ( CHuiControl * aConnectedControl,
TInt aRole
) [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 TInt ConnectionRole ( TInt aIndex ) 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 aIndex Index of the client.

ConstructL()

void ConstructL ( ) [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 * aConnected Child connection, which is querying for the visual host.

ControlExtension(const TUid &, TAny **)

IMPORT_C void ControlExtension ( 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 TRect DisplayArea ( ) const

Determines the display area.

DisplayCenter()

IMPORT_C THuiRealPoint DisplayCenter ( ) const

Determines the coordinates of the center of the display.

DisplayToHost(const TPoint &)

IMPORT_C TPoint DisplayToHost ( 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 TInt FindConnection ( const CHuiControl * aConnected ) const

Find a client's index number.

Parameters

const CHuiControl * aConnected Connected 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 & aTag Tag descriptor to match against.

Focus()

IMPORT_C TBool Focus ( ) const

Determines whether the control has input focus.

FocusChanged(CHuiDisplay &, TBool)

IMPORT_C void FocusChanged ( CHuiDisplay & aDisplay,
TBool iFocused
) [virtual]

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

Parameters

CHuiDisplay & aDisplay
TBool iFocused

Hide(CHuiDisplay &)

void Hide ( CHuiDisplay & aDisplay )

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

Parameters

CHuiDisplay & aDisplay Display to remove visuals from.

HitTest(const TPoint &)

IMPORT_C TBool HitTest ( const TPoint & aPoint ) const

Tests whether a point is inside the control.

Parameters

const TPoint & aPoint Point in display coordinates.

Host()

IMPORT_C CHuiControl * Host ( ) const

Returns the visual host control.

HostChangingL(CHuiControl *)

IMPORT_C void HostChangingL ( 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 TInt HostId ( ) const

Returns the automatic visual host identification.

HostToDisplay(const TPoint &)

IMPORT_C TPoint HostToDisplay ( const TPoint & aPoint ) const

Coordinate conversion.

Parameters

const TPoint & aPoint

Id()

IMPORT_C TInt Id ( ) const

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

IsFocusing()

IMPORT_C TBool IsFocusing ( ) const [virtual]

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

NotifyControlVisibility(TBool, CHuiDisplay &)

IMPORT_C void NotifyControlVisibility ( TBool aIsVisible,
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 aIsVisible ETrue, if the control is now visible on the display. EFalse, if the control is about to the hidden on the display.
CHuiDisplay & aDisplay The display on which the control's visibility is changing.

OfferEventL(const THuiEvent &)

IMPORT_C TBool OfferEventL ( const THuiEvent & aEvent )

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

Parameters

const THuiEvent & aEvent Event to be handled.

Remove(CHuiVisual *)

IMPORT_C void Remove ( CHuiVisual * aVisual )

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

Parameters

CHuiVisual * aVisual Visual to remove. Caller gets ownership.

RemoveConnection(CHuiControl *)

IMPORT_C void RemoveConnection ( CHuiControl * aConnectedControl )

Removes a client.

Parameters

CHuiControl * aConnectedControl Connected control to remove.

RemoveVisualsFromHostControl(CHuiControl &)

void RemoveVisualsFromHostControl ( CHuiControl & aHostControl )

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

Parameters

CHuiControl & aHostControl Host control.

Role()

IMPORT_C TInt Role ( ) const

Returns the control's role.

AddConnectionL()

SessionId()

IMPORT_C TInt SessionId ( ) const [protected]

! Gets the session id for object.

SetControlGroup(CHuiControlGroup &)

void SetControlGroup ( CHuiControlGroup & aOwnerGroup )

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

Parameters

CHuiControlGroup & aOwnerGroup Owner group.

SetFocus(CHuiDisplay &, TBool)

void SetFocus ( CHuiDisplay & aDisplay,
TBool aHasFocus
)

Changes the control's focus state.

Parameters

CHuiDisplay & aDisplay
TBool aHasFocus

SetFocusing(TBool)

void SetFocusing ( TBool aFocusing )

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

Parameters

TBool aFocusing

SetHost(CHuiControl *)

IMPORT_C void SetHost ( CHuiControl * aHost )

Parameters

CHuiControl * aHost

SetHostId(TInt)

IMPORT_C void SetHostId ( TInt aHostId )

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 void SetId ( TInt aId )

Set an id value for this control.

Parameters

TInt aId

SetRole(TInt)

IMPORT_C void SetRole ( TInt aRole )

Sets the control's role.

AddConnectionL()

Parameters

TInt aRole Connection role.

SetSessionId(TInt)

IMPORT_C void SetSessionId ( TInt aSessionId ) [protected]

! Sets the session id for object.

Parameters

TInt aSessionId

ShowL(CHuiDisplay &)

void ShowL ( 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 & aDisplay Display to add visuals to.

TextureManager()

IMPORT_C CHuiTextureManager & TextureManager ( ) const

Returns the texture manager of the environment of the visual.

Type()

IMPORT_C TType Type ( ) const [protected]

! Gets the object type.

Visual(TInt)

IMPORT_C CHuiVisual & Visual ( TInt aIndex ) const

Returns one of the visuals owned by the control.

Parameters

TInt aIndex Index number of the visual to return.

VisualAddedL(CHuiVisual *)

IMPORT_C void VisualAddedL ( CHuiVisual * aVisual ) [protected, virtual]

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

Parameters

CHuiVisual * aVisual Visual that was added.

VisualCount()

IMPORT_C TInt VisualCount ( ) 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 void VisualDestroyed ( CHuiVisual & aVisual )

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

Parameters

CHuiVisual & aVisual Visual about to the destroyed.

VisualLayoutUpdated(CHuiVisual &)

IMPORT_C void VisualLayoutUpdated ( 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 & aVisual Visual whose layout was updated.

VisualPrepareDrawFailed(CHuiVisual &, TInt)

IMPORT_C void VisualPrepareDrawFailed ( CHuiVisual & aVisual,
TInt aErrorCode
)

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 & aVisual Visual that caused the error.
TInt aErrorCode Symbian KErr error code for the failure.

VisualRemoved(CHuiVisual *)

IMPORT_C void VisualRemoved ( CHuiVisual * aVisual ) [protected, virtual]

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

Parameters

CHuiVisual * aVisual Visual 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.

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.