/*

* 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