1 /*

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

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef __HUIROSTER_H__

    21 #define __HUIROSTER_H__

    22 

    23 

    24 #include <e32base.h>

    25 #include <uiacceltk/HuiObserverArray.h>

    26 #include <uiacceltk/huieventhandler.h>

    27 

    28 

    29 /* Forward declarations. */

    30 class MHuiFrameBuffer;

    31 class CHuiControlGroup;

    32 class CHuiControl;

    33 class CHuiVisual;

    34 class CHuiGc;

    35 class THuiEvent;

    36 class CHuiRosterEntry;

    37 struct THuiXYMetric;

    38 class MHuiEffectable;

    39 class CHuiRenderBuffer;

    40 

    41 /** Predefined positions for showing groups. */

    42 const TInt KHuiRosterShowAtTop = -2;

    43 const TInt KHuiRosterShowAtBottom = -1;

    44 

    45 

    46 /** Input event types for observing. */

    47 enum THuiInputType

    48     {

    49     EHuiInputPointerDrag,

    50     EHuiInputPointerLongTap,

    51     EHuiInputPointerUnhandled

    52     };

    53 

    54 

    55 /**

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

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

    58  * drawing of the groups' root visuals.

    59  *

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

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

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

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

    64  *

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

    66  * the outside.

    67  *

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

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

    70  *

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

    72  */

    73 NONSHARABLE_CLASS(CHuiRoster) : public CBase

    74 	{

    75 public:

    76 

    77 	/* Destructor. */

    78 	virtual ~CHuiRoster();

    79 	

    80 

    81 	/* Methods. */

    82 	

    83 	/**

    84 	 * Shows a control group.

    85 	 *

    86 	 * @param aGroup  Control group.

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

    88 	 *                or <code>KHuiRosterShowAtBottom</code>.

    89 	 */

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

    91 		

    92 	/**

    93 	 * Hides a control group.

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

    95 	 * control from its host.

    96 	 *

    97 	 * @param aGroup  Control group to be hidden.

    98 	 *

    99 	 * @see CHuiControl::Hide()

   100 	 */

   101     virtual void Hide(CHuiControlGroup& aGroup) = 0;

   102 

   103     /**

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

   105      *

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

   107      */

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

   109     

   110     /**

   111      * Returns the number of control groups.

   112      */

   113     virtual TInt Count() const = 0;

   114     

   115     /**

   116      * Returns a control group.

   117      *

   118      * @see Count()

   119      */

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

   121     

   122     /**

   123      * Finds a control inside the roster.

   124      *

   125      * @param aControlId  Identifier of the control to find.

   126      *

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

   128      */

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

   130    

   131     /**

   132      * Gives input focus to a control.

   133      */

   134     virtual void SetFocus(CHuiControl& aControl) = 0;

   135     

   136     /**

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

   138      */

   139     virtual void ClearFocus() = 0;

   140                 

   141     /**

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

   143      * controls in the order defined by the groups.

   144      */    

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

   146     

   147     /**

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

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

   150      *

   151      * @param aVisual  Visual to show.

   152      */

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

   154 

   155     /**

   156      * Hide an individual visual in the roster.

   157      *

   158      * @param aVisual  Visual to hide.

   159      */

   160     virtual void HideVisual(CHuiVisual* aVisual) = 0;

   161 

   162     /**

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

   164      */

   165     virtual void MoveVisualToFront(CHuiVisual* aRootVisual) = 0;

   166     

   167     /**

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

   169      * event.

   170      *

   171      * @param aInputType  Type of input being observed.

   172      */

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

   174 

   175     /**

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

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

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

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

   180      * reset this treshold.

   181      *

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

   183      * EHuiUnitPixel, EHuiUnitRelativeToDisplay, EHuiUnitS60

   184      *

   185      * \code

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

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

   188      * \endcode

   189      *

   190      * @param aEventHandler  Event handler to which treshold affects.

   191      * @param aXYMetric  Treshold in metric units.

   192      */

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

   194 

   195     /**

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

   197      * functionality is that long tap event will be delivered simultaneously

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

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

   200      * handler from observer will reset this feature.

   201      *

   202      * \code

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

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

   205      * \endcode

   206      *

   207      * @param aEventHandler  Event handler to which disabling affects.

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

   209      */

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

   211     

   212     /**

   213      * Moves a root visual to the given position.

   214      *

   215      * @param aRootVisual  Visual to move.

   216      */

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

   218 

   219     /**

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

   221      *

   222      */

   223     virtual MHuiEffectable* Effectable() = 0;

   224         

   225     /**

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

   227      * this method is called again to unfreeze content.

   228      * 

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

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

   231      *

   232      */

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

   234     

   235     virtual TBool IsVisibleContentFrozen() const = 0;

   236     

   237 protected:

   238 

   239     /* Constructors. */

   240 

   241 	/**

   242 	 * Constructor.

   243 	 */

   244 	CHuiRoster();

   245     

   246 	};

   247 

   248 #endif  // __HUIROSTER_H__