diff -r 000000000000 -r 15bf7259bb7c uiaccelerator_plat/alf_visual_api/inc/alf/alfcontrol.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/uiaccelerator_plat/alf_visual_api/inc/alf/alfcontrol.h Tue Feb 02 07:56:43 2010 +0200 @@ -0,0 +1,688 @@ +/* +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "Eclipse Public License v1.0" +* which accompanies this distribution, and is available +* at the URL "http://www.eclipse.org/legal/epl-v10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: Base class for client side controls +* +*/ + + + +#ifndef C_ALFCONTROL_H +#define C_ALFCONTROL_H + +#include +#include +#include +#include +#include +#include + +/* Forward declarations. */ +class CAlfEnv; +class CAlfDisplay; +class TAlfEvent; +class CAlfControlGroup; + +/** + * 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: + * @code + * 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 ); + * + * @endcode + * 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. + */ +class CAlfControl : public CAlfPropertyOwner, public MAlfEventHandler + { +public: + + /** @beginAPI */ + + /* Constructors and destructor. */ + + /** + * Constructor. + */ + IMPORT_C CAlfControl(); + + /** + * Second-phase constructor. + */ + IMPORT_C void ConstructL( CAlfEnv& aEnv ); + + /** + * Destructor. + */ + IMPORT_C ~CAlfControl(); + + + /* Methods. */ + + + IMPORT_C TInt Identifier() const; + + /** + * Set an id value for this control. + */ + IMPORT_C void SetId( TInt aId ); + + /** + * Returns the id of this control. Zero (0) id the control has no id. + */ + IMPORT_C TInt Id() const; + + /** + * Returns the environment of the visual. + */ + IMPORT_C CAlfEnv& Env() const; + + /** + * Returns the control group of the visual's owner control. + * + * @return Control group, or NULL if there isn't one. + */ + IMPORT_C CAlfControlGroup* ControlGroup() const; + + /** + * Returns the display this control is bound to, or NULL. + */ + IMPORT_C CAlfDisplay* Display() const; + + /** + * Binds the control to a display. Called automatically by + * CAlfControl::ShowL(). + */ + IMPORT_C void BindDisplay( CAlfDisplay& aDisplay ); + + /** + * Appends a new visual to the list of visuals owned by the control. + * + * @see CAlfVisual::Owner() + * + * @param aVisual Visual to be appended. + * @param aParentLayout Parent layout visual to which the visual will be appended to. + * @return Error code. KErrNotSupported if some other control already owns the visual + * KErrAlreadyExists if visual was added to this control already + * System wide error codes in case of OOM + */ + IMPORT_C TInt Append( CAlfVisual* aVisual, + CAlfLayout* aParentLayout = NULL); + + /** + * Removes a visual from the control. The caller also receives ownership + * of the visual. + * + * @param aVisual Visual to remove. Caller gets ownership. + */ + IMPORT_C void Remove( CAlfVisual* aVisual ); + + /** + * Creates a new visual using the visual factory and appends it. + * + * @param aVisualType Type of the visual to create. + * + * @return Pointer to the created visual. + */ + IMPORT_C CAlfVisual* AppendVisualL( TAlfVisualType aVisualType, + CAlfLayout* aParentLayout = 0, + TInt aImplementationUid = 0 ); + + /** + * Creates a new layout using the visual factory and appends it. + * + * @param aLayoutType Type of the layout to create. + * + * @return Pointer to the created layout. + */ + IMPORT_C CAlfLayout* AppendLayoutL( TAlfLayoutType aLayoutType, + CAlfLayout* aParentLayout = NULL, + TInt aImplementationUid = 0 ); + + /** + * Returns one of the visuals owned by the control. + * + * @param aIndex Index number of the visual to return. + * + * @return Visual. + */ + IMPORT_C CAlfVisual& Visual( TInt aIndex ) 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. + * + * @return Number of visuals owned by the control. + */ + IMPORT_C TInt VisualCount() const; + + /** + * Finds the visual that matches a tag. Only the visuals owned by + * this control are searched. + * + * @param aTag Tag descriptor to match against. + * + * @return The first visual that matches the tag, or NULL + * if no visual matched the tag. + */ + IMPORT_C CAlfVisual* FindTag( const TDesC8& aTag ) const; + + /** + * Returns the visual host control. + * + * @return Host control. NULL if not set. + */ + IMPORT_C CAlfControl* Host() const; + + /** + * 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 + * + * @param aConnectedControl Control to connect. + * @param aRole Role of the control. Interpretation depends on + * the host. + * + * @see ConnectionAddedL + */ + IMPORT_C virtual void AddConnectionL( CAlfControl* aConnectedControl, + TInt aRole ); + + /** + * Removes a client. + * + * Calls ConnectionRemoved when a connection has been broken between the two + * controls + * + * @param aConnectedControl Connected control to remove. + * + * @see ConnectionRemoved + */ + IMPORT_C void RemoveConnection( CAlfControl* aConnectedControl ); + + /** + * Find a client's index number. + * + * @param aConnected Connected control to find. + * + * @return Index number. + */ + IMPORT_C TInt FindConnection( const CAlfControl* aConnected ) const; + + /** + * Returns the number of clients. + * + * @return Number of client controls. + */ + IMPORT_C TInt ConnectionCount() const; + + /** + * Returns a client control. + * + * @param aIndex Index of the client. + * + * @return Reference to the client control. + */ + IMPORT_C CAlfControl& Connection( TInt aIndex ) const; + + /** + * @deprecated + * + * Returns a client control. + * + * @param aOrdinal Role or index. + */ + IMPORT_C CAlfControl& ConnectionByOrdinal( TInt aOrdinal ) const; + + /** + * Returns the role of a client control. + * + * @param aIndex Index of the client. + * + * @return Role of the client control. + */ + IMPORT_C TInt ConnectionRole( TInt aIndex ) const; + + /** + * @deprecated + * + * Ordinal is the effective index. Role overrides index. + */ + IMPORT_C TInt ConnectionOrdinal( TInt aIndex ) const; + + /** + * Returns the controls role. + * + * @return Role. + */ + IMPORT_C TInt Role() const; + + /** + * Sets the controls role. + * + * @param aRole New role. + */ + IMPORT_C void SetRole( TInt aRole ); + + /** + * Returns the automatic visual host identification. + * + * @return Identifier of the host control. Zero if not set, + */ + IMPORT_C TInt HostId() const; + + /** + * 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! + * + * @param aHostId Identifier of the host control. Zero if not set, + */ + IMPORT_C void SetHostId( TInt aHostId ); + + /** + * @internal + * + * Do not call this outside the library! + * + * Sets the host of the control. The AddConnectionL function will + * call this after the host side has been set-up for the connection. + * + * @param aHost Host control. + */ + IMPORT_C void SetHost( CAlfControl* aHost ); + + /** + * 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. + * + * @param aConnected Child control, which is querying the layout. + * + * @return Container layout for the child controls' root visuals. + */ + IMPORT_C virtual CAlfLayout* ContainerLayout( + const CAlfControl* aConnected ) const; + + /** + * Coordinate conversion. + */ + IMPORT_C TPoint HostToDisplay( const TPoint& aPoint ) const; + + /** + * Coordinate conversion. + */ + IMPORT_C TPoint DisplayToHost( const TPoint& aPoint ) const; + + /** + * Calculates the region of the screen where the control's visuals are. + * + * @return Rectangle in display coordinates. + */ + IMPORT_C TRect Bounds() const; + + /** + * Tests whether a point is inside the control. + * + * @param aPoint Point in display coordinates. + * + * @return ETrue, if the point is inside one of the + * control's visuals. Otherwise EFalse. + */ + IMPORT_C TBool HitTest( const TPoint& aPoint ) const; + + /** + * 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 AcquireFocus(); + + /** + * 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. + * @see CAlfControl::AcquireFocus + * + * @note If this control has latent focus in a roster then it is still cleared (i.e. is no longer even latent). + * @note 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 RelinquishFocus(); + + /** + * Determines whether the control has input focus. + */ + IMPORT_C TBool Focus() 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. + * + * @return Child connection on a focus path. NULL if not found. + */ + IMPORT_C CAlfControl* FocusedConnection() const; + + /** + * 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. + */ + void FocusChainChanged( TBool aInFocusChain ); + + /** + * Determines whether the control wants to receive focus. + */ + IMPORT_C virtual TBool IsFocusing() const; + + /** + * Called when the control's focus state changes. + */ + IMPORT_C virtual void FocusChanged( CAlfDisplay& aDisplay, TBool aFocused ); + + /** + * Determines whether the control accepts input events. + */ + IMPORT_C TBool AcceptInput() const; + + /** + * Called when an input event is being offered to the control. + * + * @param aEvent Event to be handled. + * + * @return ETrue, if the event was handled. + * Otherwise EFalse. + */ + IMPORT_C virtual TBool OfferEventL( const TAlfEvent& aEvent ); + + /** + * Determines the display area. + * + * @return Area of the display on which the control is shown. + */ + IMPORT_C TRect DisplayArea() const; + + /** + * Determines the coordinates of the center of the display. + * + * @return Center of the display on which the control is shown. + */ + IMPORT_C TAlfRealPoint DisplayCenter() const; + + /** + * Cancel all scheduled commands related to this control and the control's + * visuals. + */ + IMPORT_C void CancelAllCommands(); + + /** + * Called when a visual owned by the control is being destroyed. + * Visual is removed from the control. + * + * @param aVisual Visual about to the destroyed. + */ + IMPORT_C virtual void VisualDestroyed(CAlfVisual& aVisual); + + /** + * Notifies the owner that the layout of a visual has been recalculated. + * Called only when the EAlfVisualFlagLayoutUpdateNotification flag has + * been set for the visual. + * + * @param aVisual Visual that has been laid out. + */ + IMPORT_C virtual void VisualLayoutUpdated(CAlfVisual& aVisual); + + /** + * 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. + * + * @param aVisual Visual that caused the error. + * @param aErrorCode Symbian KErr error code for the failure. + */ + IMPORT_C virtual void VisualPrepareDrawFailed(CAlfVisual& aVisual, TInt aErrorCode); + + /** + * Shows all the unshown visuals of the control on the specified display. + * Visuals that are currently shown on another display are not affected. + * + * @param aDisplay Display to add visuals to. + * + * @see CAlfControl::BindDisplay() + */ + IMPORT_C void ShowL( CAlfDisplay& aDisplay ); + + /** @endAPI */ + + /** + * Sets the group that owns the control. Called by the control group + * when the control is added to the group. + * + * @param aOwnerGroup Owner group. + */ + void SetControlGroup( CAlfControlGroup& aOwnerGroup ); + + /** + * Hides those visuals that are displayed on the specified display. Other + * visuals are not affected. + * + * @param aDisplay Display to remove visuals from. + */ + void Hide( CAlfDisplay& aDisplay ); + + /** + * Changes the control's focus state. + */ + void SetFocus( CAlfDisplay& aDisplay, TBool aHasFocus ); + + /** + * Sets the flag that tells whether the control wants to receive focus. + */ + void SetFocusing( TBool aFocusing ); + + /** + * Clears the change flags of the control. + */ + void ClearChanged(); + + +protected: + + /** @beginAPI */ + + /* Methods. */ + + /** + * 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. + * + * @param aIsVisible ETrue, if the control is now visible on the display. + * EFalse, if the control is about to the hidden on the display. + * @param aDisplay The display on which the control's visibility is changing. + */ + IMPORT_C virtual void NotifyControlVisibility( TBool aIsVisible, + CAlfDisplay& aDisplay ); + + + /* Utility methods. */ + + /** + * Called when a visual has been added to the control. + * + * @param aVisual Visual that was added. + */ + IMPORT_C virtual void VisualAddedL( CAlfVisual* aVisual ); + + /** + * Called when a visual has been removed from the control. + * + * @param aVisual Visual that was removed. + */ + IMPORT_C virtual void VisualRemoved( CAlfVisual* aVisual ); + + /** + * Called when a client control is added to the control. + * + * Override this function to get the notification. + * + * @param aConnectedControl Connected child control + * @parar aRole Role of the child control. + * + * @see AddConnectionL + */ + IMPORT_C virtual void ConnectionAddedL( CAlfControl* aConnectedControl, + TInt aRole ); + + /** + * Called when a client control is removed from the control. + * + * Override this function to get the notification. + * + * @param aConnectedControl Removed child control + * @parar aRole Role of the child control. + * + * @see RemoveConnection + */ + IMPORT_C virtual void ConnectionRemoved( CAlfControl* aConnectedControl, + TInt aRole ); + + /** + * 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. + * + * @param aNewHost New host control. If NULL, the host is removed. + */ + IMPORT_C virtual void HostChangingL( CAlfControl* aNewHost ); + + /** @endAPI */ + + /** + * @internal + * + * Remove this control's visuals from the specified container layout. + * + * @param aHostControl Host control. + */ + void RemoveVisualsFromHostControl( CAlfControl& aHostControl ); + +protected: + + /** ! future proofing */ + IMPORT_C void PropertyOwnerExtension(const TUid& aExtensionUid, TAny** aExtensionParams); + + +private: + + // Private data. Owned. + struct TPrivateData; + TPrivateData* iData; + + }; + +#endif // C_ALFCONTROL_H