| class CAlfControl : public CAlfPropertyOwner |
CAlfControl 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 by catching events through overloaded OfferEventL() - method.
Developers should derive their controls from this base class to implement the UI logic of their application. Developers should remember to pass a reference to the CAlfEnv - object to the CAlfControl - base class when derived class is constructed through the CAlfControl::ConstructL() - method. Failure to do this will result in KERN-EXEC 3 panic when CAlfControl - derived object is added to a CAlfControlGroup. Usually you would do this when ConstructL() - method of the derived class is called, like this:
class CMyControl : public CAlfControl
{
public:
CMyControl( CAlfEnv& aEnv );
~CMyControl();
//Handle interaction with the user by catching events
virtual TBool OfferEventL(const TAlfEvent& aEvent);
//Few other notofication methods, overloaded by this custom
//control, to perform required action
void NotifyControlVisibility( TBool aIsVisible, CAlfDisplay& aDisplay );
void VisualLayoutUpdated( CAlfVisual& aVisual );
void FocusChanged( CAlfDisplay& aDisplay, TBool aFocused );
void HostChanging( CAlfControl* aNewHost );
TBool Focusing()const;
};
void CMyControl::ConstructL(CAlfEnv& aEnv)
{
CAlfControl::ConstructL(aEnv);
}
//To show the control on display
//Create a new control group
CAlfControlGroup& group = iEnv->NewControlGroupL( KControlGroupIdDefault );
//Create control instance and append it to group
CMyControl* control = CMyControl::ConstructL(&iEnv);
group.AppendL( control );
//Show control group on display
iDisplay->Roster().ShowL( group );
Controls are not visible by themselves, but controls create and manipulate visuals (CAlfVisual - derived objects). Controls set the target values for visual properties and/or schedule animation commands.Controls are collected in groups represented by CAlfControlGroup - objects (e.g., one group per view). Even though controls are contained within control groups they do not have a hierarchical organization. Controls can be, however, connected to each other for collaboration. This can be done using AddConnectionL() - method.
| Protected Member Functions | |
|---|---|
| IMPORT_C void | ConnectionAddedL(CAlfControl *, TInt) |
| IMPORT_C void | ConnectionRemoved(CAlfControl *, TInt) |
| IMPORT_C void | HostChangingL(CAlfControl *) |
| IMPORT_C void | NotifyControlVisibility(TBool, CAlfDisplay &) |
| IMPORT_C void | PropertyOwnerExtension(const TUid &, TAny **) |
| void | RemoveVisualsFromHostControl(CAlfControl &) |
| IMPORT_C void | VisualAddedL(CAlfVisual *) |
| IMPORT_C void | VisualRemoved(CAlfVisual *) |
| Private Attributes | |
|---|---|
| TPrivateData * | iData |
| IMPORT_C void | AcquireFocus | ( | ) |
Attempt to acquire focus for this control.
Actively attempt to acquire focus on all displays that contain visuals owned by this control. This will set the focused control in the rosters of these displays, and then, in most situations, call SetFocus with a value of ETrue on this control. The callback in CAlfControl::FocusChanged or its virtual override is then called. It is there that the control should perform whatever visual or functional changes that it performs upon change of focus.
If a display for this control is not currently focused (for example if another application is showing a popup or an element from another UI library, for instance an Avkon menu is displayed ) then calling this method will only set a latent focus in that display's roster. That is, the focused control will be changed in the roster, but not in the control itself. The control will not receive a FocusChanged callback. The call to this method "fails" only in the sense that there is no immediate setting of focus to the control by the environment.
When focus is restored to the display, then the latent focus held in the roster will then be used to set focus again to the control. Alf controls will thus experience loss and gain of focus when displays lose and gain focus, with the record of which control has the latent focus held in the roster.
| IMPORT_C void | AddConnectionL | ( | CAlfControl * | aConnectedControl, |
| TInt | aRole | |||
| ) | [virtual] | |||
Establishes a manual connection between this host control and another control.
If setting manually the connection, do not use the SetHostId() function from the child control!
Calls ConnectionAddedL when a connection has been created between the two controls
| CAlfControl * aConnectedControl | Control to connect. |
| TInt aRole | Role of the control. Interpretation depends on the host. |
| IMPORT_C TInt | Append | ( | CAlfVisual * | aVisual, |
| CAlfLayout * | aParentLayout = NULL | |||
| ) | ||||
Appends a new visual to the list of visuals owned by the control.
| CAlfVisual * aVisual | Visual to be appended. |
| CAlfLayout * aParentLayout = NULL | Parent layout visual to which the visual will be appended to. |
| IMPORT_C CAlfLayout * | AppendLayoutL | ( | TAlfLayoutType | aLayoutType, |
| CAlfLayout * | aParentLayout = NULL, | |||
| TInt | aImplementationUid = 0 | |||
| ) | ||||
Creates a new layout using the visual factory and appends it.
| TAlfLayoutType aLayoutType | Type of the layout to create. |
| CAlfLayout * aParentLayout = NULL | |
| TInt aImplementationUid = 0 |
| IMPORT_C CAlfVisual * | AppendVisualL | ( | TAlfVisualType | aVisualType, |
| CAlfLayout * | aParentLayout = 0, | |||
| TInt | aImplementationUid = 0 | |||
| ) | ||||
Creates a new visual using the visual factory and appends it.
| TAlfVisualType aVisualType | Type of the visual to create. |
| CAlfLayout * aParentLayout = 0 | |
| TInt aImplementationUid = 0 |
| IMPORT_C void | BindDisplay | ( | CAlfDisplay & | aDisplay | ) |
Binds the control to a display. Called automatically by CAlfControl::ShowL().
| CAlfDisplay & aDisplay |
| IMPORT_C TRect | Bounds | ( | ) | const |
Calculates the region of the screen where the control's visuals are.
| IMPORT_C void | CancelAllCommands | ( | ) |
Cancel all scheduled commands related to this control and the control's visuals.
| IMPORT_C CAlfControl & | Connection | ( | TInt | aIndex | ) | const |
Returns a client control.
| TInt aIndex | Index of the client. |
| IMPORT_C void | ConnectionAddedL | ( | CAlfControl * | aConnectedControl, |
| TInt | aRole | |||
| ) | [protected, virtual] | |||
Called when a client control is added to the control.
Override this function to get the notification.
| CAlfControl * aConnectedControl | Connected child control aRole Role of the child control. |
| TInt aRole |
| IMPORT_C CAlfControl & | ConnectionByOrdinal | ( | TInt | aOrdinal | ) | const |
Returns a client control.
| TInt aOrdinal | Role or index. |
| IMPORT_C TInt | ConnectionOrdinal | ( | TInt | aIndex | ) | const |
Ordinal is the effective index. Role overrides index.
| TInt aIndex |
| IMPORT_C void | ConnectionRemoved | ( | CAlfControl * | aConnectedControl, |
| TInt | aRole | |||
| ) | [protected, virtual] | |||
Called when a client control is removed from the control.
Override this function to get the notification.
| CAlfControl * aConnectedControl | Removed child control aRole Role of the child control. |
| TInt aRole |
| IMPORT_C TInt | ConnectionRole | ( | TInt | aIndex | ) | const |
Returns the role of a client control.
| TInt aIndex | Index of the client. |
| IMPORT_C void | ConstructL | ( | CAlfEnv & | aEnv | ) |
Second-phase constructor.
| CAlfEnv & aEnv |
| IMPORT_C CAlfLayout * | ContainerLayout | ( | const CAlfControl * | aConnected | ) | const [virtual] |
Returns a container layout for the specified child control.
By default this function returns NULL. Override this function in your own control to select the container layout.
| const CAlfControl * aConnected | Child control, which is querying the layout. |
| IMPORT_C CAlfControlGroup * | ControlGroup | ( | ) | const |
Returns the control group of the visual's owner control.
| IMPORT_C CAlfDisplay * | Display | ( | ) | const |
Returns the display this control is bound to, or NULL.
| IMPORT_C TAlfRealPoint | DisplayCenter | ( | ) | const |
Determines the coordinates of the center of the display.
| IMPORT_C TPoint | DisplayToHost | ( | const TPoint & | aPoint | ) | const |
Coordinate conversion.
| const TPoint & aPoint |
| IMPORT_C TInt | FindConnection | ( | const CAlfControl * | aConnected | ) | const |
Find a client's index number.
| const CAlfControl * aConnected | Connected control to find. |
| IMPORT_C CAlfVisual * | FindTag | ( | const TDesC8 & | aTag | ) | const |
Finds the visual that matches a tag. Only the visuals owned by this control are searched.
| const TDesC8 & aTag | Tag descriptor to match against. |
| void | FocusChainChanged | ( | TBool | aInFocusChain | ) |
Called when this control is included/excluded from the focus chain.
Example: There are controls c1, c2 and c3. The c3 is a child connection of the c2 (i.e. c2 is a host of c3). When the c1 is focused, the c2 is not part of the focus chain. Now, when c3 receives focus, the c2 becomes part of the focus chain and this function will be called for c2. When the c3 loses focus (with RelinquishFocus() or back to c1), this function we be called again for c2 object.
This function calls PropertyOwnerExtension() with parameters: aExtensionUid KUidAlfPropOwnerExtControlFocusChainChanged aExtensionParams TBool** True if focus chain is gained.
| TBool aInFocusChain |
| IMPORT_C void | FocusChanged | ( | CAlfDisplay & | aDisplay, |
| TBool | aFocused | |||
| ) | [virtual] | |||
Called when the control's focus state changes.
| CAlfDisplay & aDisplay | |
| TBool aFocused |
| IMPORT_C CAlfControl * | FocusedConnection | ( | ) | const |
Finds a child connection with focus or recursively one of its child connections have focus. Use Focus() to find out if the returned control instance has focus.
| void | Hide | ( | CAlfDisplay & | aDisplay | ) |
Hides those visuals that are displayed on the specified display. Other visuals are not affected.
| CAlfDisplay & aDisplay | Display to remove visuals from. |
| IMPORT_C TBool | HitTest | ( | const TPoint & | aPoint | ) | const |
Tests whether a point is inside the control.
| const TPoint & aPoint | Point in display coordinates. |
| IMPORT_C void | HostChangingL | ( | CAlfControl * | aNewHost | ) | [protected, virtual] |
The host control is about to be changed. The control needs to add its visuals to the container layout provided by the new host.
Override this function to get the notification. Base call is mandatory. If this function leaves, the connection will not be created.
| CAlfControl * aNewHost | New host control. If NULL, the host is removed. |
| IMPORT_C TPoint | HostToDisplay | ( | const TPoint & | aPoint | ) | const |
Coordinate conversion.
| const TPoint & aPoint |
| IMPORT_C TBool | IsFocusing | ( | ) | const [virtual] |
Determines whether the control wants to receive focus.
| IMPORT_C void | NotifyControlVisibility | ( | TBool | aIsVisible, |
| CAlfDisplay & | aDisplay | |||
| ) | [protected, virtual] | |||
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.
| TBool aIsVisible | ETrue, if the control is now visible on the display. EFalse, if the control is about to the hidden on the display. |
| CAlfDisplay & aDisplay | The display on which the control's visibility is changing. |
| IMPORT_C TBool | OfferEventL | ( | const TAlfEvent & | aEvent | ) | [virtual] |
Called when an input event is being offered to the control.
| const TAlfEvent & aEvent | Event to be handled. |
| IMPORT_C void | PropertyOwnerExtension | ( | const TUid & | aExtensionUid, |
| TAny ** | aExtensionParams | |||
| ) | [protected, virtual] | |||
! future proofing
| IMPORT_C void | RelinquishFocus | ( | ) |
Attempt to give up focus.
If this control has latent focus in a roster then it is still cleared (i.e. is no longer even latent).
If this control is not the currently focused control in a roster (either active or latent) then calling this method has no effect on the focus state of that roster.
| IMPORT_C void | Remove | ( | CAlfVisual * | aVisual | ) |
Removes a visual from the control. The caller also receives ownership of the visual.
| CAlfVisual * aVisual | Visual to remove. Caller gets ownership. |
| IMPORT_C void | RemoveConnection | ( | CAlfControl * | aConnectedControl | ) |
Removes a client.
Calls ConnectionRemoved when a connection has been broken between the two controls
| CAlfControl * aConnectedControl | Connected control to remove. |
| void | RemoveVisualsFromHostControl | ( | CAlfControl & | aHostControl | ) | [protected] |
| CAlfControl & aHostControl |
| void | SetControlGroup | ( | CAlfControlGroup & | aOwnerGroup | ) |
Sets the group that owns the control. Called by the control group when the control is added to the group.
| CAlfControlGroup & aOwnerGroup | Owner group. |
| void | SetFocus | ( | CAlfDisplay & | aDisplay, |
| TBool | aHasFocus | |||
| ) | ||||
Changes the control's focus state.
| CAlfDisplay & aDisplay | |
| TBool aHasFocus |
| void | SetFocusing | ( | TBool | aFocusing | ) |
Sets the flag that tells whether the control wants to receive focus.
| TBool aFocusing |
| IMPORT_C void | SetHostId | ( | TInt | aHostId | ) |
Sets the automatic visual host identification. When the control is shown, the connection is created automatically betweem this control and the host determined by the paramter.
If the automatic ID is set, do not use the manual AddConnectionL function!
| TInt aHostId | Identifier of the host control. Zero if not set, |
| IMPORT_C void | ShowL | ( | CAlfDisplay & | aDisplay | ) |
Shows all the unshown visuals of the control on the specified display. Visuals that are currently shown on another display are not affected.
| CAlfDisplay & aDisplay | Display to add visuals to. |
| IMPORT_C CAlfVisual & | Visual | ( | TInt | aIndex | ) | const |
Returns one of the visuals owned by the control.
| TInt aIndex | Index number of the visual to return. |
| IMPORT_C void | VisualAddedL | ( | CAlfVisual * | aVisual | ) | [protected, virtual] |
Called when a visual has been added to the control.
| CAlfVisual * aVisual | Visual that was added. |
| 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.
| IMPORT_C void | VisualDestroyed | ( | CAlfVisual & | aVisual | ) | [virtual] |
Called when a visual owned by the control is being destroyed. Visual is removed from the control.
| CAlfVisual & aVisual | Visual about to the destroyed. |
| IMPORT_C void | VisualLayoutUpdated | ( | CAlfVisual & | aVisual | ) | [virtual] |
Notifies the owner that the layout of a visual has been recalculated. Called only when the EAlfVisualFlagLayoutUpdateNotification flag has been set for the visual.
| CAlfVisual & aVisual | Visual that has been laid out. |
| IMPORT_C void | VisualPrepareDrawFailed | ( | CAlfVisual & | aVisual, |
| TInt | aErrorCode | |||
| ) | [virtual] | |||
Notifies the visual owner if there was an error (a leave happened) when preparing the visual for drawing. Typically the resource alloc errors such as out of memory is escalated through this callback.
| CAlfVisual & aVisual | Visual that caused the error. |
| TInt aErrorCode | Symbian KErr error code for the failure. |
| IMPORT_C void | VisualRemoved | ( | CAlfVisual * | aVisual | ) | [protected, virtual] |
Called when a visual has been removed from the control.
| CAlfVisual * aVisual | Visual that was removed. |
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.