/*

* Copyright (c) 2006-2007 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:   ?Description

*

*/

#ifndef __HUIROSTER_H__

#define __HUIROSTER_H__

#include <e32base.h>

#include <uiacceltk/HuiObserverArray.h>

#include <uiacceltk/huieventhandler.h>

/* Forward declarations. */

class MHuiFrameBuffer;

class CHuiControlGroup;

class CHuiControl;

class CHuiVisual;

class CHuiGc;

class THuiEvent;

class CHuiRosterEntry;

struct THuiXYMetric;

class MHuiEffectable;

class CHuiRenderBuffer;

/** Predefined positions for showing groups. */

const TInt KHuiRosterShowAtTop = -2;

const TInt KHuiRosterShowAtBottom = -1;

/** Input event types for observing. */

enum THuiInputType

    {

    EHuiInputPointerDrag,

    EHuiInputPointerLongTap,

    EHuiInputPointerUnhandled

    };

/**

 * Roster defines a priority order of control groups shown an a display.

 * The roster also offers input events to the groups, and handles the

 * drawing of the groups' root visuals.

 *

 * The roster is responsible for managing the logical state of the UI: which

 * controls are active, who has input focus, and which controls receive input

 * events. In the roster, the logical structure and state of

 * the user interface is represented by control groups and controls.

 *

 * This is an abstract base class. The methods here are accessible from

 * the outside.

 *

 * There is a roster owned by the environment (a shared roster), if this is not

 * passed to a display's ConstructL, it will create its own private roster automatically.

 *

 * @see HUITK Programmer's Guide for more information on using rosters.

 */

NONSHARABLE_CLASS(CHuiRoster) : public CBase

	{

public:

	/* Destructor. */

	virtual ~CHuiRoster();

	/* Methods. */

	/**

	 * Shows a control group.

	 *

	 * @param aGroup  Control group.

	 * @param aWhere  Where to show the group. Index, <code>KHuiRosterShowAtTop</code>,

	 *                or <code>KHuiRosterShowAtBottom</code>.

	 */

	virtual void ShowL(CHuiControlGroup& aGroup, TInt aWhere = KHuiRosterShowAtTop) = 0;

	/**

	 * Hides a control group.

	 * Hides all the controls within a control group. Also disconnects the

	 * control from its host.

	 *

	 * @param aGroup  Control group to be hidden.

	 *

	 * @see CHuiControl::Hide()

	 */

    virtual void Hide(CHuiControlGroup& aGroup) = 0;

    /**

     * Finds the index of a control group in the roster.

     *

     * @param aGroup  Control group. Should return KErrNotFound if not found.

     */

    virtual TInt Find(CHuiControlGroup* aGroup) const = 0;

    /**

     * Returns the number of control groups.

     */

    virtual TInt Count() const = 0;

    /**

     * Returns a control group.

     *

     * @see Count()

     */

    virtual CHuiControlGroup& ControlGroup(TInt aIndex) const = 0;

    /**

     * Finds a control inside the roster.

     *

     * @param aControlId  Identifier of the control to find.

     *

     * @return  Pointer to the control.  <code>NULL</code>, if not found.

     */

    virtual CHuiControl* FindControl(TInt aControlId) const = 0;

    /**

     * Gives input focus to a control.

     */

    virtual void SetFocus(CHuiControl& aControl) = 0;

    /**

     * Clears the input focus so that no control has focus.

     */

    virtual void ClearFocus() = 0;

    /**

     * Called when a key event occurs. The input event is offered to the 

     * controls in the order defined by the groups.

     */    

    virtual TBool HandleEventL(const THuiEvent& aEvent) = 0;

    /**

     * Show an individual visual in the roster. The visual is appended to the

     * root level visuals of its group, at the end of the list of root visuals.

     *

     * @param aVisual  Visual to show.

     */

    IMPORT_C virtual void ShowVisualL(CHuiVisual* aVisual) = 0;

    /**

     * Hide an individual visual in the roster.

     *

     * @param aVisual  Visual to hide.

     */

    virtual void HideVisual(CHuiVisual* aVisual) = 0;

    /**

     * Moves a root visual to the front. Causes layout recalculation.

     */

    virtual void MoveVisualToFront(CHuiVisual* aRootVisual) = 0;

    /**

     * Returns the array of input observers for a specific type of input 

     * event.

     *

     * @param aInputType  Type of input being observed.

     */

    virtual RHuiObserverArray<MHuiEventHandler>& Observers(THuiInputType aInputType) = 0;

    /**

     * Sets treshold which pointer needs to be moved before starting to send 

     * drag events.Default treshold is 4 pixels in both X and Y direction.

     * Event handler must be added to some pointer event observer array, before

     * calling this function. Also removing event handler from observer will 

     * reset this treshold.

     *

     * NOTE: Not every unit type is feasible. Only these types are supported:

     * EHuiUnitPixel, EHuiUnitRelativeToDisplay, EHuiUnitS60

     *

     * \code

     *  Display()->Roster().Observers(EHuiInputPointerDrag).AppendL(*this);

     *  Display()->Roster().SetPointerDragThresholdL(*this,THuiXYMetric(THuiMetric(0.2,EHuiUnitRelativeToDisplay),THuiMetric(0.1,EHuiUnitRelativeToDisplay)));

     * \endcode

     *

     * @param aEventHandler  Event handler to which treshold affects.

     * @param aXYMetric  Treshold in metric units.

     */

    virtual void SetPointerDragThresholdL(const MHuiEventHandler& aEventHandler, const THuiXYMetric& aXYMetric) = 0;

    /**

     * Disables long tap events when dragging is going on. Default 

     * functionality is that long tap event will be delivered simultaneously

     * with drag events. Event handler must be added to some pointer event 

     * observer array, before calling this function. Also removing event 

     * handler from observer will reset this feature.

     *

     * \code

     *  Display()->Roster().Observers(EHuiInputPointerDrag).AppendL(*this);

     *  Display()->Roster().DisableLongTapEventsWhenDraggingL(*this);

     * \endcode

     *

     * @param aEventHandler  Event handler to which disabling affects.

     * @param aDisable  Boolean to indicate whether feature is disabled or not.

     */

    virtual void  DisableLongTapEventsWhenDraggingL(const MHuiEventHandler& aEventHandler, TBool aDisable = ETrue) = 0;

    /**

     * Moves a root visual to the given position.

     *

     * @param aRootVisual  Visual to move.

     */

    virtual void Move(CHuiVisual* aVisual, TInt aPos) = 0;

    /**

     * Returns effectable-interface if it is supported by the implementation.

     *

     */

    virtual MHuiEffectable* Effectable() = 0;

    /**

     * Takes screenshot from the roster content and keeps drawing that until

     * this method is called again to unfreeze content.

     * 

     * @param aFreeze if ETrue, further frames are drawn from cached image of the

     * roster content. If EFalse, normal drawing is used.

     *

     */

    virtual void FreezeVisibleContentL(TBool aFreeze = ETrue) = 0;

    virtual TBool IsVisibleContentFrozen() const = 0;

protected:

    /* Constructors. */

	/**

	 * Constructor.

	 */

	CHuiRoster();

	};

#endif  // __HUIROSTER_H__