1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Base class for client side controls

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef C_ALFCONTROL_H

    21 #define C_ALFCONTROL_H

    22 

    23 #include <e32base.h>

    24 #include <barsread.h>

    25 #include <alf/alfvisual.h>  

    26 #include <alf/alflayout.h>  

    27 #include <alf/alfeventhandler.h>

    28 #include <alf/alfpropertyowner.h>

    29 

    30 /* Forward declarations. */

    31 class CAlfEnv;

    32 class CAlfDisplay;

    33 class TAlfEvent;

    34 class CAlfControlGroup;

    35 

    36 /**

    37  * CAlfControl provides a base class for gathering logical functionality in

    38  * the UI.

    39  *

    40  * For example a list control could gather and control all visuals that form

    41  * a listbox UI element. A thumbnail view control could be used to control visuals

    42  * that form a thumbnail view in an image gallery application.

    43  *

    44  * Their main use is to handle interaction with the user by catching events through

    45  * overloaded OfferEventL() - method.

    46  *

    47  * Developers should derive their controls from this base class to implement the UI logic

    48  * of their application. Developers should remember to pass a reference to the CAlfEnv - object

    49  * to the CAlfControl - base class when derived class is constructed through the 

    50  * CAlfControl::ConstructL() - method. Failure to do this will result in KERN-EXEC 3 panic

    51  * when CAlfControl - derived object is added to a CAlfControlGroup. Usually you would do this

    52  * when ConstructL() - method of the derived class is called, like this:

    53  *

    54  * Usage: 

    55  * @code

    56  * class CMyControl : public CAlfControl

    57  *    {

    58  *  public:

    59  *     CMyControl( CAlfEnv& aEnv );

    60  *    ~CMyControl();

    61  * 

    62  *    //Handle interaction with the user by catching events

    63  *    virtual TBool OfferEventL(const TAlfEvent& aEvent);

    64  *    

    65  *    //Few other notofication methods, overloaded by this custom

    66  *    //control, to perform required action

    67  *    void NotifyControlVisibility( TBool aIsVisible, CAlfDisplay& aDisplay );

    68  *    void VisualLayoutUpdated( CAlfVisual& aVisual );

    69  *    void FocusChanged( CAlfDisplay& aDisplay, TBool aFocused );

    70  *    void HostChanging( CAlfControl* aNewHost );

    71  *    TBool Focusing()const;

    72  *   };

    73  * 

    74  *  void CMyControl::ConstructL(CAlfEnv& aEnv)

    75  * 	{

    76  *     CAlfControl::ConstructL(aEnv);

    77  * 	}

    78  * 

    79  *  //To show the control on display

    80  *  //Create a new control group

    81  *  CAlfControlGroup& group = iEnv->NewControlGroupL( KControlGroupIdDefault );

    82  * 

    83  *  //Create control instance and append it to group

    84  *  CMyControl* control = CMyControl::ConstructL(&iEnv);

    85  *  group.AppendL( control );

    86  * 

    87  *  //Show control group on display

    88  *  iDisplay->Roster().ShowL( group );

    89  * 

    90  * @endcode 

    91  * Controls are not visible by themselves, but controls create and manipulate

    92  * visuals (CAlfVisual - derived objects). Controls set the target values for visual properties and/or

    93  * schedule animation commands.

    94  *

    95  * Controls are collected in groups represented by CAlfControlGroup - objects (e.g., one group per view). 

    96  * Even though controls are contained within control groups they do not have a hierarchical organization.

    97  * Controls can be, however, connected to each other for collaboration.

    98  * This can be done using AddConnectionL() - method.

    99  */

   100 class CAlfControl : public CAlfPropertyOwner, public MAlfEventHandler 

   101 	{

   102 public:

   103 

   104 	/** @beginAPI */

   105 	

   106 	/* Constructors and destructor. */

   107 

   108 	/**

   109 	 * Constructor.

   110 	 */

   111 	IMPORT_C CAlfControl();

   112 

   113 	/**

   114 	 * Second-phase constructor.

   115 	 */

   116 	IMPORT_C void ConstructL( CAlfEnv& aEnv );

   117 

   118 	/**

   119 	 * Destructor.

   120 	 */

   121 	IMPORT_C ~CAlfControl();

   122 

   123 

   124 	/* Methods. */

   125 	

   126 

   127     IMPORT_C TInt Identifier() const;

   128 

   129 	/**

   130 	 * Set an id value for this control.

   131 	 */

   132 	IMPORT_C void SetId( TInt aId );

   133 

   134 	/**

   135 	 * Returns the id of this control. Zero (0) id the control has no id.

   136 	 */

   137 	IMPORT_C TInt Id() const;

   138 

   139 	/**

   140 	 * Returns the environment of the visual.

   141 	 */

   142 	IMPORT_C CAlfEnv& Env() const;

   143 

   144 	/**

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

   146 	 *

   147 	 * @return  Control group, or <code>NULL</code> if there isn't one.

   148 	 */

   149 	IMPORT_C CAlfControlGroup* ControlGroup() const;

   150 

   151     /**

   152      * Returns the display this control is bound to, or <code>NULL</code>.

   153      */

   154     IMPORT_C CAlfDisplay* Display() const;

   155 

   156     /**

   157      * Binds the control to a display. Called automatically by 

   158      * CAlfControl::ShowL().

   159      */

   160     IMPORT_C void BindDisplay( CAlfDisplay& aDisplay );

   161 

   162 	/**

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

   164 	 *

   165 	 * @see CAlfVisual::Owner()

   166 	 *

   167 	 * @param aVisual        Visual to be appended.

   168 	 * @param aParentLayout  Parent layout visual to which the visual will be appended to.

   169 	 * @return Error code.   KErrNotSupported if some other control already owns the visual

   170 	 *                       KErrAlreadyExists if visual was added to this control already

   171 	 *                       System wide error codes in case of OOM   

   172 	 */

   173 	IMPORT_C TInt Append( CAlfVisual* aVisual,

   174                            CAlfLayout* aParentLayout = NULL);

   175 

   176 	/**

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

   178 	 * of the visual.

   179 	 *

   180 	 * @param aVisual  Visual to remove. Caller gets ownership.

   181 	 */

   182 	IMPORT_C void Remove( CAlfVisual* aVisual );

   183 

   184 	/**

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

   186 	 *

   187 	 * @param aVisualType  Type of the visual to create.

   188 	 *

   189 	 * @return  Pointer to the created visual.

   190 	 */

   191     IMPORT_C CAlfVisual* AppendVisualL( TAlfVisualType aVisualType,

   192                                         CAlfLayout* aParentLayout = 0,

   193                                         TInt aImplementationUid = 0 );

   194 

   195     /**

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

   197      *

   198      * @param aLayoutType  Type of the layout to create.

   199      *

   200      * @return  Pointer to the created layout.

   201      */

   202     IMPORT_C CAlfLayout* AppendLayoutL( TAlfLayoutType aLayoutType,

   203                                         CAlfLayout* aParentLayout = NULL,

   204                                         TInt aImplementationUid = 0 );

   205 

   206     /**

   207      * Returns one of the visuals owned by the control.

   208      *

   209      * @param aIndex  Index number of the visual to return.

   210      *

   211      * @return  Visual.

   212      */

   213     IMPORT_C CAlfVisual& Visual( TInt aIndex ) const;

   214 

   215     /**

   216      * Determines the number of visuals owned by the control. 

   217      *

   218      * Note that in visual hierarchies, child visuals are not owned by 

   219      * their parent visuals, but a control. This means that a control 

   220      * that owns a tree of visuals will return the total number of visuals 

   221      * in the tree, and not just the number of root visuals.

   222      *

   223      * @return  Number of visuals owned by the control.

   224      */

   225     IMPORT_C TInt VisualCount() const;

   226 

   227     /**

   228      * Finds the visual that matches a tag. Only the visuals owned by 

   229      * this control are searched.

   230      *

   231      * @param aTag  Tag descriptor to match against.

   232      *

   233      * @return  The first visual that matches the tag, or <code>NULL</code>

   234      *          if no visual matched the tag.

   235      */

   236     IMPORT_C CAlfVisual* FindTag( const TDesC8& aTag ) const;

   237       

   238 	/**

   239 	 * Returns the visual host control.

   240 	 *

   241 	 * @return  Host control. NULL if not set.

   242 	 */

   243 	IMPORT_C CAlfControl* Host() const;

   244 

   245 	/**

   246 	 * Establishes a manual connection between this host control and another control.

   247 	 * 

   248 	 * If setting manually the connection, do not use the SetHostId() function

   249 	 * from the child control!

   250 	 *

   251 	 * Calls ConnectionAddedL when a connection has been created between the two

   252 	 * controls

   253  	 *

   254 	 * @param aConnectedControl  Control to connect.

   255 	 * @param aRole              Role of the control. Interpretation depends on

   256 	 *                           the host.

   257 	 *

   258 	 * @see ConnectionAddedL

   259 	 */

   260 	IMPORT_C virtual void AddConnectionL( CAlfControl* aConnectedControl, 

   261 	                                      TInt aRole );

   262 

   263 	/**

   264 	 * Removes a client.

   265 	 *

   266 	 * Calls ConnectionRemoved when a connection has been broken between the two

   267 	 * controls

   268 	 *

   269 	 * @param aConnectedControl  Connected control to remove.

   270 	 *

   271 	 * @see ConnectionRemoved

   272 	 */

   273 	IMPORT_C void RemoveConnection( CAlfControl* aConnectedControl );

   274 

   275     /**

   276      * Find a client's index number.

   277      *

   278      * @param aConnected  Connected control to find.

   279      *

   280      * @return  Index number.

   281      */

   282     IMPORT_C TInt FindConnection( const CAlfControl* aConnected ) const;

   283 

   284 	/**

   285 	 * Returns the number of clients.

   286 	 *

   287 	 * @return  Number of client controls.

   288 	 */

   289     IMPORT_C TInt ConnectionCount() const;

   290 

   291 	/**

   292 	 * Returns a client control.

   293 	 *

   294 	 * @param aIndex  Index of the client.

   295 	 *

   296 	 * @return  Reference to the client control.

   297 	 */

   298     IMPORT_C CAlfControl& Connection( TInt aIndex ) const;

   299 

   300     /**

   301      * @deprecated

   302      *  

   303      * Returns a client control.

   304      *

   305      * @param aOrdinal  Role or index.

   306      */

   307     IMPORT_C CAlfControl& ConnectionByOrdinal( TInt aOrdinal ) const;

   308 

   309 	/**

   310 	 * Returns the role of a client control.

   311 	 *

   312 	 * @param aIndex  Index of the client.

   313 	 *

   314 	 * @return  Role of the client control.

   315 	 */

   316     IMPORT_C TInt ConnectionRole( TInt aIndex ) const;

   317 

   318     /**

   319      * @deprecated

   320      *

   321      * Ordinal is the effective index. Role overrides index.

   322      */

   323     IMPORT_C TInt ConnectionOrdinal( TInt aIndex ) const;

   324 

   325     /**

   326      * Returns the controls role.

   327      * 

   328      * @return Role.

   329      */

   330     IMPORT_C TInt Role() const;

   331 

   332     /**

   333      * Sets the controls role.

   334      * 

   335      * @param aRole New role.

   336      */

   337     IMPORT_C void SetRole( TInt aRole );

   338 

   339     /**

   340      * Returns the automatic visual host identification.

   341      * 

   342      * @return Identifier of the host control. Zero if not set,

   343      */

   344     IMPORT_C TInt HostId() const;

   345 

   346     /**

   347      * Sets the automatic visual host identification.

   348      * When the control is shown, the connection is created automatically

   349      * betweem this control and the host determined by the paramter.

   350      * 

   351      * If the automatic ID is set, do not use the manual AddConnectionL function!

   352      * 

   353      * @param aHostId Identifier of the host control. Zero if not set,

   354      */

   355     IMPORT_C void SetHostId( TInt aHostId );

   356 

   357 	/**

   358 	 * @internal

   359 	 *

   360 	 * Do not call this outside the library!

   361 	 *

   362 	 * Sets the host of the control. The AddConnectionL function will

   363 	 * call this after the host side has been set-up for the connection.

   364 	 *

   365 	 * @param aHost  Host control.

   366 	 */

   367     IMPORT_C void SetHost( CAlfControl* aHost );

   368 

   369     /**

   370      * Returns a container layout for the specified child control.

   371      *

   372      * By default this function returns NULL. Override this function

   373      * in your own control to select the container layout. 

   374      *

   375      * @param aConnected Child control, which is querying the layout.

   376      *

   377      * @return Container layout for the child controls' root visuals.

   378      */

   379     IMPORT_C virtual CAlfLayout* ContainerLayout(

   380         const CAlfControl* aConnected ) const;

   381 

   382     /**

   383      * Coordinate conversion.

   384      */

   385     IMPORT_C TPoint HostToDisplay( const TPoint& aPoint ) const;

   386 

   387     /**

   388      * Coordinate conversion.

   389      */

   390     IMPORT_C TPoint DisplayToHost( const TPoint& aPoint ) const;

   391 

   392     /**

   393      * Calculates the region of the screen where the control's visuals are.

   394      *

   395      * @return  Rectangle in display coordinates.

   396      */

   397     IMPORT_C TRect Bounds() const;

   398 

   399     /**

   400      * Tests whether a point is inside the control.

   401      *

   402      * @param aPoint  Point in display coordinates.

   403      *

   404      * @return  <code>ETrue</code>, if the point is inside one of the

   405      *          control's visuals. Otherwise <code>EFalse</code>.

   406      */

   407     IMPORT_C TBool HitTest( const TPoint& aPoint ) const;

   408 

   409     /**

   410      * Attempt to acquire focus for this control.

   411      * 

   412      * Actively attempt to acquire focus on all displays that contain visuals owned by this control.

   413      * This will set the focused control in the rosters of these displays, and then, in most situations, call 

   414      * <code>SetFocus</code> with a value of  <code>ETrue</code> on this control. The callback in 

   415      * <code>CAlfControl::FocusChanged</code> or its virtual override is then called. It is there that the control 

   416      * should perform whatever visual or functional changes that it performs upon change of focus.

   417      * 

   418      * If a display for this control is not currently focused (for example if another application is showing a popup or an element from

   419      * another UI library, for instance an Avkon menu is displayed ) then calling this method will only set a latent focus 

   420      * in that display's roster. That is, the focused control will be changed in the roster, but not in the control itself.

   421      * The control will not receive a <code>FocusChanged</code> callback. The call to this method "fails" only in the sense 

   422      * that there is no immediate setting of focus to the control by the environment.

   423      *

   424      * 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

   425      * control. Alf controls will thus experience loss and gain of focus when displays lose and gain focus, with the record of which 

   426      * control has the latent focus held in the roster.

   427      */

   428     IMPORT_C void AcquireFocus();

   429 

   430     /**

   431      * Attempt to give up focus.

   432      *

   433      * Actively give up focus on all displays containing visuals for this control. Whether the focus is 

   434      * actually changed in the associated roster(s) depends upon the focus state of the related displays.

   435      * @see CAlfControl::AcquireFocus

   436      *

   437      * @note If this control has latent focus in a roster then it is still cleared (i.e. is no longer even latent).

   438      * @note If this control is not the currently focused control in a roster (either active or latent) then calling 

   439      * this method has no effect on the focus state of that roster. 

   440      */

   441     IMPORT_C void RelinquishFocus();

   442     

   443     /**

   444      * Determines whether the control has input focus.

   445      */

   446     IMPORT_C TBool Focus() const;

   447     

   448     /**

   449      * Finds a child connection with focus or recursively one of its child

   450      * connections have focus. Use Focus() to find out if the returned

   451      * control instance has focus.

   452      * 

   453      * @return Child connection on a focus path. NULL if not found.

   454      */

   455     IMPORT_C CAlfControl* FocusedConnection() const;

   456     

   457     /**

   458      * Called when this control is included/excluded from the focus chain.

   459      *

   460      * Example:

   461      * There are controls c1, c2 and c3. The c3 is a child connection of the 

   462      * c2 (i.e. c2 is a host of c3). When the c1 is focused, the c2 is not 

   463      * part of the focus chain. Now, when c3 receives focus, the c2 becomes

   464      * part of the focus chain and this function will be called for c2. When the c3

   465      * loses focus (with RelinquishFocus() or back to c1), this function we be 

   466      * called again for c2 object.

   467      * 

   468      * This function calls PropertyOwnerExtension() with parameters:

   469      * aExtensionUid        KUidAlfPropOwnerExtControlFocusChainChanged

   470      * aExtensionParams     TBool** True if focus chain is gained.

   471      */

   472     void FocusChainChanged( TBool aInFocusChain );

   473 

   474     /**

   475      * Determines whether the control wants to receive focus.

   476      */

   477     IMPORT_C virtual TBool IsFocusing() const;

   478 

   479     /**

   480      * Called when the control's focus state changes.

   481      */

   482     IMPORT_C virtual void FocusChanged( CAlfDisplay& aDisplay, TBool aFocused );

   483 

   484     /**

   485      * Determines whether the control accepts input events.

   486      */

   487     IMPORT_C TBool AcceptInput() const;

   488 

   489     /**

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

   491      *

   492      * @param aEvent  Event to be handled.

   493      *

   494      * @return  <code>ETrue</code>, if the event was handled.

   495      *          Otherwise <code>EFalse</code>.

   496      */

   497     IMPORT_C virtual TBool OfferEventL( const TAlfEvent& aEvent );

   498 

   499     /**

   500      * Determines the display area.

   501      *

   502      * @return  Area of the display on which the control is shown.

   503      */

   504     IMPORT_C TRect DisplayArea() const;

   505 

   506     /**

   507      * Determines the coordinates of the center of the display.

   508      *

   509      * @return  Center of the display on which the control is shown.

   510      */

   511     IMPORT_C TAlfRealPoint DisplayCenter() const;

   512 

   513     /**

   514      * Cancel all scheduled commands related to this control and the control's

   515      * visuals.

   516      */

   517     IMPORT_C void CancelAllCommands();

   518     

   519     /**

   520      * Called when a visual owned by the control is being destroyed.

   521      * Visual is removed from the control.

   522      *

   523      * @param aVisual  Visual about to the destroyed.

   524      */

   525     IMPORT_C virtual void VisualDestroyed(CAlfVisual& aVisual);

   526     

   527     /**

   528      * Notifies the owner that the layout of a visual has been recalculated.

   529      * Called only when the EAlfVisualFlagLayoutUpdateNotification flag has

   530      * been set for the visual.

   531      *

   532      * @param aVisual  Visual that has been laid out.

   533      */

   534      IMPORT_C virtual void VisualLayoutUpdated(CAlfVisual& aVisual);

   535    

   536 	/**

   537 	 * Notifies the visual owner if there was an error (a leave happened)

   538 	 * when preparing the visual for drawing. Typically the resource alloc

   539 	 * errors such as out of memory is escalated through this callback.

   540 	 * 

   541      * @param aVisual    Visual that caused the error.

   542      * @param aErrorCode Symbian KErr error code for the failure.

   543 	 */

   544      IMPORT_C virtual void VisualPrepareDrawFailed(CAlfVisual& aVisual, TInt aErrorCode);

   545 

   546     /**

   547      * Shows all the unshown visuals of the control on the specified display.

   548      * Visuals that are currently shown on another display are not affected.

   549      *

   550      * @param aDisplay  Display to add visuals to.

   551      *

   552      * @see CAlfControl::BindDisplay()

   553      */

   554     IMPORT_C void ShowL( CAlfDisplay& aDisplay );

   555 

   556     /** @endAPI */

   557 

   558     /**

   559      * Sets the group that owns the control. Called by the control group

   560      * when the control is added to the group.

   561      *

   562      * @param aOwnerGroup  Owner group.

   563      */

   564     void SetControlGroup( CAlfControlGroup& aOwnerGroup );

   565 

   566     /**

   567      * Hides those visuals that are displayed on the specified display. Other

   568      * visuals are not affected.

   569      *

   570      * @param aDisplay  Display to remove visuals from.

   571      */

   572     void Hide( CAlfDisplay& aDisplay );

   573 

   574     /**

   575      * Changes the control's focus state.

   576      */

   577     void SetFocus( CAlfDisplay& aDisplay, TBool aHasFocus );

   578 

   579     /**

   580      * Sets the flag that tells whether the control wants to receive focus.

   581      */

   582     void SetFocusing( TBool aFocusing );

   583 

   584     /**

   585      * Clears the change flags of the control.

   586      */

   587     void ClearChanged();

   588 

   589 

   590 protected:

   591 

   592     /** @beginAPI */

   593 

   594     /* Methods. */

   595 

   596     /**

   597      * Notifies the control that its visible has been changed on a display.

   598      * This is the earliest time when the control knows the dimensions of

   599      * the display it is being shown on.

   600      *

   601      * @param aIsVisible  ETrue, if the control is now visible on the display.

   602      *                    EFalse, if the control is about to the hidden on the display.

   603      * @param aDisplay    The display on which the control's visibility is changing.

   604      */

   605     IMPORT_C virtual void NotifyControlVisibility( TBool aIsVisible, 

   606                                                    CAlfDisplay& aDisplay );

   607 

   608 

   609     /* Utility methods. */

   610 

   611     /**

   612      * Called when a visual has been added to the control.

   613      *

   614      * @param aVisual  Visual that was added.

   615      */

   616     IMPORT_C virtual void VisualAddedL( CAlfVisual* aVisual );

   617 

   618     /**

   619      * Called when a visual has been removed from the control.

   620      *

   621      * @param aVisual  Visual that was removed.

   622      */

   623     IMPORT_C virtual void VisualRemoved( CAlfVisual* aVisual );

   624 

   625     /**

   626      * Called when a client control is added to the control.

   627      *

   628      * Override this function to get the notification.

   629      *

   630      * @param aConnectedControl Connected child control

   631      * @parar aRole Role of the child control.

   632      *

   633      * @see AddConnectionL

   634      */

   635     IMPORT_C virtual void ConnectionAddedL( CAlfControl* aConnectedControl, 

   636                                             TInt aRole );

   637 

   638     /**

   639      * Called when a client control is removed from the control.

   640      *

   641      * Override this function to get the notification.

   642      *

   643      * @param aConnectedControl Removed child control

   644      * @parar aRole Role of the child control.

   645      *

   646      * @see RemoveConnection

   647      */

   648     IMPORT_C virtual void ConnectionRemoved( CAlfControl* aConnectedControl, 

   649                                              TInt aRole );

   650 

   651     /**

   652      * The host control is about to be changed. The control needs to

   653      * add its visuals to the container layout provided by the new host.

   654      *

   655      * Override this function to get the notification. Base call is

   656      * mandatory. If this function leaves, the connection will not be

   657      * created.

   658      *

   659      * @param aNewHost New host control. If NULL, the host is removed.

   660      */

   661     IMPORT_C virtual void HostChangingL( CAlfControl* aNewHost );

   662 

   663     /** @endAPI */

   664     

   665     /**

   666      * @internal

   667      *

   668      * Remove this control's visuals from the specified container layout.

   669      *

   670      * @param aHostControl Host control.

   671      */

   672     void RemoveVisualsFromHostControl( CAlfControl& aHostControl );

   673 

   674 protected:

   675 

   676     /** ! future proofing */

   677     IMPORT_C void PropertyOwnerExtension(const TUid& aExtensionUid, TAny** aExtensionParams);

   678 

   679 

   680 private:

   681     

   682     // Private data. Owned.

   683     struct TPrivateData;

   684     TPrivateData* iData;

   685 

   686 	};

   687 

   688 #endif  // C_ALFCONTROL_H