Symbian^3 Application Developer Library >

CAlfControl Class Reference

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:

Usage: 
        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.

Inherits from

Nested Classes and Structures

Public Member Functions
CAlfControl ()
~CAlfControl ()
IMPORT_C TBool AcceptInput ()
IMPORT_C void AcquireFocus ()
IMPORT_C void AddConnectionL ( CAlfControl *, TInt )
IMPORT_C TInt Append ( CAlfVisual *, CAlfLayout *)
IMPORT_C CAlfLayout * AppendLayoutL ( TAlfLayoutType , CAlfLayout *, TInt )
IMPORT_C CAlfVisual * AppendVisualL ( TAlfVisualType , CAlfLayout *, TInt )
IMPORT_C void BindDisplay (CAlfDisplay &)
IMPORT_C TRect Bounds ()
IMPORT_C void CancelAllCommands ()
void ClearChanged ()
IMPORT_C CAlfControl & Connection ( TInt )
IMPORT_C CAlfControl & ConnectionByOrdinal ( TInt )
IMPORT_C TInt ConnectionCount ()
IMPORT_C TInt ConnectionOrdinal ( TInt )
IMPORT_C TInt ConnectionRole ( TInt )
IMPORT_C void ConstructL (CAlfEnv &)
IMPORT_C CAlfLayout * ContainerLayout (const CAlfControl *)
IMPORT_C CAlfControlGroup * ControlGroup ()
IMPORT_C CAlfDisplay * Display ()
IMPORT_C TRect DisplayArea ()
IMPORT_C TAlfRealPoint DisplayCenter ()
IMPORT_C TPoint DisplayToHost (const TPoint &)
IMPORT_C CAlfEnv & Env ()
IMPORT_C TInt FindConnection (const CAlfControl *)
IMPORT_C CAlfVisual * FindTag (const TDesC8 &)
IMPORT_C TBool Focus ()
void FocusChainChanged ( TBool )
IMPORT_C void FocusChanged (CAlfDisplay &, TBool )
IMPORT_C CAlfControl * FocusedConnection ()
void Hide (CAlfDisplay &)
IMPORT_C TBool HitTest (const TPoint &)
IMPORT_C CAlfControl * Host ()
IMPORT_C TInt HostId ()
IMPORT_C TPoint HostToDisplay (const TPoint &)
IMPORT_C TInt Id ()
IMPORT_C TInt Identifier ()
IMPORT_C TBool IsFocusing ()
IMPORT_C TBool OfferEventL (const TAlfEvent &)
IMPORT_C void RelinquishFocus ()
IMPORT_C void Remove ( CAlfVisual *)
IMPORT_C void RemoveConnection ( CAlfControl *)
IMPORT_C TInt Role ()
void SetControlGroup (CAlfControlGroup &)
void SetFocus (CAlfDisplay &, TBool )
void SetFocusing ( TBool )
IMPORT_C void SetHost ( CAlfControl *)
IMPORT_C void SetHostId ( TInt )
IMPORT_C void SetId ( TInt )
IMPORT_C void SetRole ( TInt )
IMPORT_C void ShowL (CAlfDisplay &)
IMPORT_C CAlfVisual & Visual ( TInt )
IMPORT_C TInt VisualCount ()
IMPORT_C void VisualDestroyed ( CAlfVisual &)
IMPORT_C void VisualLayoutUpdated ( CAlfVisual &)
IMPORT_C void VisualPrepareDrawFailed ( CAlfVisual &, TInt )
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 *)
Inherited Functions
CAlfPropertyOwner::CAlfPropertyOwner()
CAlfPropertyOwner::CopyProperty(const CAlfPropertyOwner &,const TDesC8 &)
CAlfPropertyOwner::PropertyClear()
CAlfPropertyOwner::PropertyFindInteger(const TDesC8 &,TInt *)const
CAlfPropertyOwner::PropertyFindString(const TDesC8 &,TDesC **)const
CAlfPropertyOwner::PropertyRemove(const TDesC8 &)
CAlfPropertyOwner::PropertySetIntegerL(const TDesC8 &,TInt,TInt,TInt)
CAlfPropertyOwner::PropertySetStringL(const TDesC8 &,const TDesC &)
CAlfPropertyOwner::~CAlfPropertyOwner()
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
TPrivateData * iData

Constructor & Destructor Documentation

CAlfControl()

IMPORT_C CAlfControl ( )

Constructor.

~CAlfControl()

IMPORT_C ~CAlfControl ( )

Destructor.

Member Functions Documentation

AcceptInput()

IMPORT_C TBool AcceptInput ( ) const

Determines whether the control accepts input events.

AcquireFocus()

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.

AddConnectionL(CAlfControl *, TInt)

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

ConnectionAddedL

Parameters

CAlfControl * aConnectedControl Control to connect.
TInt aRole Role of the control. Interpretation depends on the host.

Append(CAlfVisual *, CAlfLayout *)

IMPORT_C TInt Append ( CAlfVisual * aVisual,
CAlfLayout * aParentLayout = NULL
)

Appends a new visual to the list of visuals owned by the control.

CAlfVisual::Owner()

Parameters

CAlfVisual * aVisual Visual to be appended.
CAlfLayout * aParentLayout = NULL Parent layout visual to which the visual will be appended to.

AppendLayoutL(TAlfLayoutType, CAlfLayout *, TInt)

IMPORT_C CAlfLayout * AppendLayoutL ( TAlfLayoutType aLayoutType,
CAlfLayout * aParentLayout = NULL,
TInt aImplementationUid = 0
)

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

Parameters

TAlfLayoutType aLayoutType Type of the layout to create.
CAlfLayout * aParentLayout = NULL
TInt aImplementationUid = 0

AppendVisualL(TAlfVisualType, CAlfLayout *, TInt)

IMPORT_C CAlfVisual * AppendVisualL ( TAlfVisualType aVisualType,
CAlfLayout * aParentLayout = 0,
TInt aImplementationUid = 0
)

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

Parameters

TAlfVisualType aVisualType Type of the visual to create.
CAlfLayout * aParentLayout = 0
TInt aImplementationUid = 0

BindDisplay(CAlfDisplay &)

IMPORT_C void BindDisplay ( CAlfDisplay & aDisplay )

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

Parameters

CAlfDisplay & 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 CAlfControl & Connection ( TInt aIndex ) const

Returns a client control.

Parameters

TInt aIndex Index of the client.

ConnectionAddedL(CAlfControl *, TInt)

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.

AddConnectionL

Parameters

CAlfControl * aConnectedControl Connected child control aRole Role of the child control.
TInt aRole

ConnectionByOrdinal(TInt)

IMPORT_C CAlfControl & 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.

Parameters

TInt aIndex

ConnectionRemoved(CAlfControl *, TInt)

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.

RemoveConnection

Parameters

CAlfControl * aConnectedControl Removed child control aRole Role of the child control.
TInt aRole

ConnectionRole(TInt)

IMPORT_C TInt ConnectionRole ( TInt aIndex ) const

Returns the role of a client control.

Parameters

TInt aIndex Index of the client.

ConstructL(CAlfEnv &)

IMPORT_C void ConstructL ( CAlfEnv & aEnv )

Second-phase constructor.

Parameters

CAlfEnv & aEnv

ContainerLayout(const CAlfControl *)

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.

Parameters

const CAlfControl * aConnected Child control, which is querying the layout.

ControlGroup()

IMPORT_C CAlfControlGroup * ControlGroup ( ) const

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

Display()

IMPORT_C CAlfDisplay * 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 TAlfRealPoint 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 CAlfEnv & Env ( ) const

Returns the environment of the visual.

FindConnection(const CAlfControl *)

IMPORT_C TInt FindConnection ( const CAlfControl * aConnected ) const

Find a client's index number.

Parameters

const CAlfControl * aConnected Connected control to find.

FindTag(const TDesC8 &)

IMPORT_C CAlfVisual * 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.

FocusChainChanged(TBool)

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.

Parameters

TBool aInFocusChain

FocusChanged(CAlfDisplay &, TBool)

IMPORT_C void FocusChanged ( CAlfDisplay & aDisplay,
TBool aFocused
) [virtual]

Called when the control's focus state changes.

Parameters

CAlfDisplay & aDisplay
TBool aFocused

FocusedConnection()

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.

Hide(CAlfDisplay &)

void Hide ( CAlfDisplay & aDisplay )

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

Parameters

CAlfDisplay & 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 CAlfControl * Host ( ) const

Returns the visual host control.

HostChangingL(CAlfControl *)

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.

Parameters

CAlfControl * aNewHost New host control. If NULL, the host is removed.

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.

Identifier()

IMPORT_C TInt Identifier ( ) const

IsFocusing()

IMPORT_C TBool IsFocusing ( ) const [virtual]

Determines whether the control wants to receive focus.

NotifyControlVisibility(TBool, CAlfDisplay &)

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.

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.
CAlfDisplay & aDisplay The display on which the control's visibility is changing.

OfferEventL(const TAlfEvent &)

IMPORT_C TBool OfferEventL ( const TAlfEvent & aEvent ) [virtual]

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

Parameters

const TAlfEvent & aEvent Event to be handled.

PropertyOwnerExtension(const TUid &, TAny **)

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

! future proofing

Parameters

const TUid & aExtensionUid
TAny ** aExtensionParams

RelinquishFocus()

IMPORT_C void RelinquishFocus ( )

Attempt to give up focus.

Actively give up focus on all displays containing visuals for this control. Whether the focus is actually changed in the associated roster(s) depends upon the focus state of the related displays. CAlfControl::AcquireFocus
Note:

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.

Remove(CAlfVisual *)

IMPORT_C void Remove ( CAlfVisual * aVisual )

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

Parameters

CAlfVisual * aVisual Visual to remove. Caller gets ownership.

RemoveConnection(CAlfControl *)

IMPORT_C void RemoveConnection ( CAlfControl * aConnectedControl )

Removes a client.

Calls ConnectionRemoved when a connection has been broken between the two controls

ConnectionRemoved

Parameters

CAlfControl * aConnectedControl Connected control to remove.

RemoveVisualsFromHostControl(CAlfControl &)

void RemoveVisualsFromHostControl ( CAlfControl & aHostControl ) [protected]

Parameters

CAlfControl & aHostControl

Role()

IMPORT_C TInt Role ( ) const

Returns the controls role.

SetControlGroup(CAlfControlGroup &)

void SetControlGroup ( CAlfControlGroup & aOwnerGroup )

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

Parameters

CAlfControlGroup & aOwnerGroup Owner group.

SetFocus(CAlfDisplay &, TBool)

void SetFocus ( CAlfDisplay & aDisplay,
TBool aHasFocus
)

Changes the control's focus state.

Parameters

CAlfDisplay & 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(CAlfControl *)

IMPORT_C void SetHost ( CAlfControl * aHost )

Parameters

CAlfControl * aHost

SetHostId(TInt)

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!

Parameters

TInt aHostId Identifier of the host control. Zero if not set,

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 controls role.

Parameters

TInt aRole New role.

ShowL(CAlfDisplay &)

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.

CAlfControl::BindDisplay()

Parameters

CAlfDisplay & aDisplay Display to add visuals to.

Visual(TInt)

IMPORT_C CAlfVisual & Visual ( TInt aIndex ) const

Returns one of the visuals owned by the control.

Parameters

TInt aIndex Index number of the visual to return.

VisualAddedL(CAlfVisual *)

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

Called when a visual has been added to the control.

Parameters

CAlfVisual * 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(CAlfVisual &)

IMPORT_C void VisualDestroyed ( CAlfVisual & aVisual ) [virtual]

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

Parameters

CAlfVisual & aVisual Visual about to the destroyed.

VisualLayoutUpdated(CAlfVisual &)

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.

Parameters

CAlfVisual & aVisual Visual that has been laid out.

VisualPrepareDrawFailed(CAlfVisual &, TInt)

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.

Parameters

CAlfVisual & aVisual Visual that caused the error.
TInt aErrorCode Symbian KErr error code for the failure.

VisualRemoved(CAlfVisual *)

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

Called when a visual has been removed from the control.

Parameters

CAlfVisual * aVisual Visual that was removed.

Member Data Documentation

TPrivateData * iData

TPrivateData * iData [private]

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.