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()
Nested Classes and Structures
Constructor & Destructor Documentation
CHuiControl(CHuiEnv &)
IMPORT_C | CHuiControl | ( | CHuiEnv & | aEnv | ) | |
~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 *)
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 *)
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.
AppendLayoutL(THuiLayoutType, CHuiLayout *)
Creates a new layout using the visual factory and appends it.
AppendVisualL(THuiVisualType, CHuiLayout *)
Creates a new visual using the visual factory and appends it.
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 | ) | |
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()
Clears the change flags of the control.
Connection(TInt)
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()
ConnectionByOrdinal(TInt)
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 |
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()
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. |
ContainerLayout(const CHuiControl *)
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()
Determines the coordinates of the center of the display.
DisplayToHost(const TPoint &)
Env()
IMPORT_C CHuiEnv & | Env | ( | ) | const |
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 *)
Find a client's index number.
Parameters
const CHuiControl * aConnected | Connected control to find. |
FindTag(const TDesC8 &)
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 &)
Tests whether a point is inside the control.
Parameters
const TPoint & aPoint | Point in display coordinates. |
Host()
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()
HostId()
IMPORT_C TInt | HostId | ( | ) | const |
Returns the automatic visual host identification.
HostToDisplay(const TPoint &)
Id()
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 *)
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 | ) | |
Parameters
CHuiControl * aConnectedControl | Connected control to remove. |
RemoveVisualsFromHostControl(CHuiControl &)
void | RemoveVisualsFromHostControl | ( | CHuiControl & | aHostControl | ) | |
Remove this control's visuals from the specified container layout.
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.
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.
SetId(TInt)
IMPORT_C void | SetId | ( | TInt | aId | ) | |
Set an id value for this control.
SetRole(TInt)
IMPORT_C void | SetRole | ( | TInt | aRole | ) | |
Parameters
TInt aRole | Connection role. |
SetSessionId(TInt)
IMPORT_C void | SetSessionId | ( | TInt | aSessionId | ) | [protected] |
! Sets the session id for object.
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()
Returns the texture manager of the environment of the visual.
Type()
IMPORT_C TType | Type | ( | ) | const [protected] |
Visual(TInt)
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.
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 &)
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 | ) | |
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.
Member Data Documentation
CHuiDisplay * iBoundDisplay
CHuiDisplay * | iBoundDisplay | [private] |
The display this control is currently bound to.
RArray< SConnection > iConnections
Connected controls and their roles.
CHuiEnv & iEnv
The environment where this visual belong to.
TBool
iFocusing
ETrue, if the control wants to receive input focus.
CHuiControl * iHost
Host control. The host provides a container visual for this control's visuals.
TInt
iHostId
Identifier of the host control.
TInt
iId
Identifier of the control.
CHuiControlGroup * iOwnerGroup
CHuiControlGroup * | iOwnerGroup | [private] |
The group into which this control belongs to.
RPointerArray< CHuiVisual > iVisuals
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.