--- /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 <e32base.h>
+#include <barsread.h>
+#include <alf/alfvisual.h>
+#include <alf/alflayout.h>
+#include <alf/alfeventhandler.h>
+#include <alf/alfpropertyowner.h>
+
+/* 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 <code>NULL</code> if there isn't one.
+ */
+ IMPORT_C CAlfControlGroup* ControlGroup() const;
+
+ /**
+ * Returns the display this control is bound to, or <code>NULL</code>.
+ */
+ 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 <code>NULL</code>
+ * 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 <code>ETrue</code>, if the point is inside one of the
+ * control's visuals. Otherwise <code>EFalse</code>.
+ */
+ 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
+ * <code>SetFocus</code> with a value of <code>ETrue</code> on this control. The callback in
+ * <code>CAlfControl::FocusChanged</code> 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 <code>FocusChanged</code> 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 <code>ETrue</code>, if the event was handled.
+ * Otherwise <code>EFalse</code>.
+ */
+ 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