1 /*

     2 * Copyright (c) 2002-2008 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:  Decorator class for navigation pane controls.

    15 *                The class, for example, decorates navigation pane controls

    16 *                with navi arrows.

    17 *

    18 */

    19 

    20 

    21 #ifndef C_AKNNAVIDE_H

    22 #define C_AKNNAVIDE_H

    23 

    24 #include <AknControl.h>

    25 #include <coeccntx.h>

    26 #include <e32std.h>

    27 

    28 #include <AknNaviObserver.h>

    29 #include <aknnavi.h>

    30 

    31 class CEikScrollButton;

    32 class CAknTabGroup;

    33 class MAknNaviDecoratorObserver;

    34 class CAknNavigationDecoratorExtension;

    35 

    36 /**

    37  * Decorator class for navigation pane controls.

    38  * The class, for example, decorates navigation pane controls with navi arrows.

    39  */

    40 class CAknNavigationDecorator :  public CAknControl,

    41                                  public MCoeControlObserver,

    42                                  public MAknNavigationDecoratorInterface

    43     {

    44 

    45 friend class CAknNavigationControlContainer;

    46 

    47 public:

    48 

    49     /**

    50      * Defines scroll buttons.

    51      */

    52     enum TScrollButton

    53         {

    54         /** Scroll left. */

    55         ELeftButton =  0x0001,

    56 

    57         /** Scroll right. */

    58         ERightButton = 0x0002

    59         };

    60 

    61     /**

    62      * Defines type of the decorated control.

    63      */

    64     enum TControlType

    65         {

    66         /** Type not specified. */

    67         ENotSpecified,

    68 

    69         /** Tab group. */

    70         ETabGroup,

    71 

    72         /** Label. */

    73         ENaviLabel,

    74 

    75         /** Image. */

    76         ENaviImage,

    77 

    78         /** Text. */

    79         EHintText,

    80 

    81         /** Indicator. */

    82         EEditorIndicator,

    83 

    84         /** Volume. */

    85         ENaviVolume

    86         };

    87 

    88 public:

    89 

    90     /**

    91      * Creates a new navigation decorator. The object takes ownership of the

    92      * decorated object at the beginning of the method before any leaving

    93      * functions.

    94      *

    95      * @param aNavigationControlContainer Container control.

    96      * @param aDecoratedControl Control to be decorated.

    97      * @param aType = @c ENotSpecified Control type.

    98      * @return Navigation Decorator object that

    99      *         contains decorated object.

   100      */

   101     IMPORT_C static CAknNavigationDecorator* NewL(

   102         CAknNavigationControlContainer* aNavigationControlContainer,

   103         CCoeControl* aDecoratedControl,

   104         TControlType aType = ENotSpecified);

   105 

   106     /**

   107     * Destructor.

   108     */

   109     IMPORT_C ~CAknNavigationDecorator();

   110 

   111     /**

   112      * Returns the control inside a navigation decorator object. Ownership of

   113      * the control is not changed.

   114      *

   115      * @return Control that is decorated with the decorator.

   116      */

   117     IMPORT_C CCoeControl* DecoratedControl();

   118 

   119     /**

   120      * Shows or hides the navigation arrows at the both ends of the navigation

   121      * pane when current object is shown.

   122      *

   123      * @param aVisible Boolean value if navigation arrows are shown with the

   124      *        decorated control. Visible if @c ETrue.

   125      */

   126     IMPORT_C void MakeScrollButtonVisible(TBool aVisible);

   127 

   128     /**

   129      * Gets the State of the visibility of navigation arrows.

   130      *

   131      * @return @c ETrue if visible.

   132      */

   133     IMPORT_C TBool ScrollButtonVisible() const;

   134 

   135     /**

   136      * Sets the navigation arrow dimmed (and highlighted). Arrows have to be

   137      * visible so that the dimmed arrow is shown on the screen.

   138      *

   139      * @param aButton Navigation arrow to be set (@c ELeftButton or

   140      *        @c ERightButton).

   141      * @param aDimmed @c ETrue is the button is dimmed, @c EFalse if the button

   142      *        is set highlighted.

   143      */

   144     IMPORT_C void SetScrollButtonDimmed(TScrollButton aButton, TBool aDimmed);

   145 

   146     /**

   147     * Is button dimmed or highlighted.

   148     *

   149     * @param aButton Navigation arrow.

   150     * @return @c ETrue If the navigation arrow is dimmed, @c EFalse if

   151     *         it is highlighted.

   152     */

   153     IMPORT_C TBool IsScrollButtonDimmed(TScrollButton aButton) const;

   154 

   155     /**

   156      * Sets the type of the decorated control.

   157      *

   158      * @param aType Type of the control.

   159      */

   160     IMPORT_C void SetControlType(TControlType aType);

   161 

   162     /**

   163      * Returns the type of the decorated control.

   164      *

   165      * @return Control type.

   166      */

   167     IMPORT_C TControlType ControlType() const;

   168 

   169     /**

   170      * Sets observer for navigation decorator events in the decorated control.

   171      *

   172      * @param aObserver Pointer to observer.

   173      */

   174     IMPORT_C virtual void SetNaviDecoratorObserver(

   175                         MAknNaviDecoratorObserver* aObserver);

   176 

   177     /**

   178      * Sets the pointer to the default navigation pane control.

   179      *

   180      * @param aContainer Pointer to default control in navigation pane.

   181      */

   182     void SetNaviStack(CAknNavigationControlContainer* aContainer);

   183 

   184     /**

   185      * From @c CCoeControl.

   186      *

   187      * Handle pointer events.

   188      *

   189      * @param aPointerEvent Pointer event to be handled.

   190      */

   191     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   192 

   193     /**

   194      * Defines the navigation control layout style.

   195      */

   196     enum TAknNaviControlLayoutStyle

   197         {

   198         /** Normal layout style. */

   199         ENaviControlLayoutNormal = 0x1,

   200 

   201         /** Narrow layout style. */

   202         ENaviControlLayoutNarrow = 0x2,

   203 

   204         /**

   205          * Wide layout style, can be used only in portrait mode, in

   206          * usual status pane layout (@c R_AVKON_STATUS_PANE_LAYOUT_USUAL_EXT).

   207          *

   208          * Tabs are not currently supported in wide layout style.

   209          */

   210         ENaviControlLayoutWide   = 0x4

   211         };

   212 

   213     /**

   214      * Defines the navigation control layout mode.

   215      */

   216     enum TAknNaviControlLayoutMode

   217         {

   218         /**

   219          * This is the default layout mode. It lets UI framework to decide the

   220          * proper layout style which is applied to decorated controls in all

   221          * situations.

   222          */

   223         ENaviControlLayoutModeAutomatic = 0x400,

   224 

   225         /**

   226          * @c ENaviControlLayoutModeForced layout mode can be used to lock

   227          * the layout style to the current style.

   228          */

   229         ENaviControlLayoutModeForced = 0x800

   230         };

   231 

   232 

   233     /**

   234      * Sets the layout style for this objects decorated control. The layout

   235      * style can be normal or narrow style.

   236      *

   237      * The style is really applied if the decorated control supports it or if

   238      * the layout mode has been set to forced mode

   239      * (@c ENaviControlLayoutModeForced). Additionally narrow mode may not be

   240      * supported at all in some statuspane configurations (even if forced).

   241      *

   242      * Whether decorated control supports or does not support given style at the

   243      * currently active statuspane layout can be queried using

   244      * @c NaviControlLayoutStyleSupported() method.

   245      *

   246      * @since S60 3.0

   247      * @param aStyle Can be normal (@c ENaviControlLayoutNormal),

   248      *                      narrow (@c ENaviControlLayoutNarrow) or

   249      *                      wide   (@c ENaviControlLayoutWide).

   250      *

   251      */

   252     IMPORT_C void SetNaviControlLayoutStyle(TAknNaviControlLayoutStyle aStyle);

   253 

   254     /**

   255     * Gets the current layout style of this objects decorated control

   256     * (@c ENaviControlLayoutNormalm @c ENaviControlLayoutNarrow or

   257     *  @c ENaviControlLayoutWide).

   258     *

   259     * @since S60 3.0

   260     * @return Current layout style of the navicontrol

   261     */

   262     IMPORT_C TAknNaviControlLayoutStyle NaviControlLayoutStyle();

   263 

   264     /**

   265      * Tells if decorated control supports given layout style at the current

   266      * statuspane layout. For @c ENotSpecified type of controls this always

   267      * returns @c EFalse (just for safety) because their implementation is

   268      * not known.

   269      *

   270      * @since S60 3.0

   271      * @param aStyle The layout style.

   272      * @return @c ETrue if the control supports given layout style

   273      *         otherwise returns @c EFalse.

   274      */

   275     IMPORT_C TBool NaviControlLayoutStyleSupported(TAknNaviControlLayoutStyle

   276                                                    aStyle);

   277 

   278     /**

   279      * Sets the layout mode @c ENaviControlLayoutModeAutomatic or

   280      * @c ENaviControlLayoutModeForced. See @c TAknNaviControlLayoutMode

   281      * for more information.

   282      *

   283      * @since S60 3.0

   284      * @param aMode New layout mode.

   285      *

   286      */

   287     IMPORT_C void SetNaviControlLayoutMode(TAknNaviControlLayoutMode aMode);

   288 

   289     /**

   290      * Gets the current layout mode of decorated control. Can be

   291      * @c ENaviControlLayoutModeAutomatic (default) or

   292      * @c ENaviControlLayoutModeForced (usually set by the application).

   293      *

   294      * @since S60 3.0

   295      * @return Decorated control's current layout

   296      *         mode.

   297      *

   298      */

   299     IMPORT_C TAknNaviControlLayoutMode NaviControlLayoutMode();

   300 

   301 

   302 protected: // from CCoeControl

   303 

   304     /**

   305      * From @c CCoeControl.

   306      *

   307      * Handles the size change events.

   308      */

   309     IMPORT_C virtual void SizeChanged();

   310 

   311     /**

   312      * From @c CCoeControl.

   313      *

   314      * Returns the number of controls inside the context pane control.

   315      *

   316      * @return Number of controls.

   317      */

   318     IMPORT_C virtual TInt CountComponentControls() const;

   319 

   320     /**

   321      * From @c CCoeControl.

   322      *

   323      * Returns a control determined by control id.

   324      *

   325      * @param aIndex Index of a control to be returned.

   326      * @return Pointer to the control.

   327      */

   328     IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const;

   329 

   330 public: // from CCoeControl

   331     /**

   332      * Handles a change to the control's resources of type aType

   333      * which are shared across the environment, e.g. color scheme change.

   334      * @param aType Event type.

   335      */

   336     IMPORT_C virtual void HandleResourceChange(TInt aType);

   337 

   338 protected: // from MCoeControlObserver

   339 

   340     /**

   341      * From @c MCoeControlObserver.

   342      *

   343      * Handles an event from an observed control.

   344      *

   345      * @param aControl Control that caused the event.

   346      * @param aEventType Type of the event.

   347      */

   348     IMPORT_C void HandleControlEventL(CCoeControl* aControl,

   349                                       TCoeEvent aEventType);

   350 

   351 private:

   352 

   353     /**

   354      * From CAknControl

   355      */

   356     IMPORT_C void* ExtensionInterface( TUid aInterface );

   357 

   358 private:

   359 

   360     /**

   361      * Private constructor.

   362      */

   363     IMPORT_C void ConstructL();

   364 

   365 private:

   366 

   367     /**

   368      * From CAknControl

   369      */

   370     IMPORT_C virtual void Draw(const TRect& aRect) const;

   371 

   372     /**

   373      * Gets parent rect of this control. Used for layout calculation purposes.

   374      */

   375     TRect ParentRect();

   376 

   377 public:

   378 

   379     /**

   380     * Gets the default rectangle of the given control type.

   381     *

   382     * @param  aControlType  The control type from which default rectangle is

   383     *                       asked.

   384     * @param  aArrowsUsed   Whether or not the navigation arrows are used

   385     *                       for the control. This is only used for the

   386     *                       tab group control. If arrows are not used with

   387     *                       tab group, then the whole navi pane area

   388     *                       is provided to the tab group control.

   389     * 

   390     * @return Rectangle which tells the default area for given

   391     *         controltype. Coordinates are relative to navi pane.

   392     */

   393     static TRect DecoratedControlRect( TInt aControlType,

   394                                        TBool aArrowsUsed = ETrue );

   395 

   396     /**

   397      * Gets the default rectangle of the navigation pane's default control.

   398      *

   399      * @param aControlType Not used.

   400      * @return Rectangle of the navigation pane's default control.

   401      */

   402     static TRect DecoratedControlNarrowRect( TInt aControlType );

   403 

   404 private:

   405 

   406     /**

   407      * Gets the default rect of default controltype relative to navipane in

   408      * normal layoutstyle (@c ENaviControlLayoutNormal)

   409      *

   410      * @return Rectangle which is tells the default area for a navi control.

   411      *         Coordinates are relative to navipane.

   412      *

   413      */

   414     static TRect DecoratedDefaultControlRect();

   415 

   416 public:

   417 

   418     /**

   419     * Gets the default rect of tab group control type relative to navipane in

   420     * normal (@c ENaviControlLayoutNormal) or wide (@c ENaviControlLayoutWide)

   421     * layout style.

   422     *

   423     * @param  aTopAdjacent  @c ETrue to return a rectangle adjacent to the

   424     *                       top of navi pane, @c EFalse for a rectangle

   425     *                       adjacent to the bottom of navi pane.

   426     * @param  aArrowsUsed   Whether or not the navigation arrows are used

   427     *                       for the tab group. If arrows are not used, then

   428     *                       the whole navi pane area is provided to the tab

   429     *                       group control.

   430     *

   431     * @return Rectangle which tells the default area for a tab group.

   432     */

   433     static TRect DecoratedTabControlRect( TBool aTopAdjacent,

   434                                           TBool aArrowsUsed );

   435 

   436 private:

   437 

   438     /**

   439      * Gets the default rect of volume controltype relative to navipane in

   440      * normal layoutstyle (@c ENaviControlLayoutNormal)

   441      *

   442      * @return Rectangle which is tells the default area for a volume control.

   443      *         Coordinates are relative to navipane.

   444      *

   445      */

   446     static TRect DecoratedVolumeControlRect();

   447 

   448     /**

   449      * This method handles sizechanges in normal layout style.

   450      */

   451     void SizeChangedInNormalLayout();

   452 

   453     /**

   454      * This method handles sizechanges in narrow layout style.

   455      */

   456     void SizeChangedInNarrowLayout();

   457 

   458     /**

   459      * This method handles sizechanges in wide layout style.

   460      */

   461     void SizeChangedInWideLayout();

   462 

   463     /**

   464      * This method initializes timer that is used for times layout style

   465      * changes.

   466      */

   467     void InitLayoutStyleTimer();

   468 

   469     /**

   470      * This method cancels timer that is used for times layout style changes.

   471      */

   472     void CancelLayoutStyleTimer();

   473 

   474     /**

   475      * This method is executed when timer that is used for times layout style

   476      * changes expires.

   477      */

   478     static TInt LayoutStyleEvent(TAny * aPtr);

   479 

   480     /**

   481      * This method is executed when timer that is used for times layout style

   482      * changes expires.

   483      */

   484     void DoLayoutStyleEvent();

   485 

   486     void StartTimerL();

   487 

   488     void SmallDirectionIndicationL();

   489 

   490     static TInt IndicationDrawCallbackL( TAny* aThis );

   491 

   492     /**

   493      * This method cancels the timer that is used in the small direction

   494      * indication animation.

   495      */

   496     void CancelTimer();

   497 

   498     /**

   499      * Gets the rectangle for a navigation arrow.

   500      *

   501      * @param   aScrollButton  @c ELeftButton to return the rectangle

   502      *                         of the left navi arrow,

   503      *                         @c ERightButton for right navi arrow.

   504      *

   505      * @param   aNarrowLayout  @c ETrue to get a navi arrow rectangle

   506      *                         for a narrow decorator layout,

   507      *                         @c EFalse otherwise.

   508      *

   509      * @param   aNaviRect  Navi pane rectangle to be used as parent,

   510      *                     the returned rectangle is relative to this.

   511      *                     If not defined, then relative to the

   512      *                     default navi pane area.

   513      *

   514      * @return  Navigation arrow rectangle.

   515      *          Coordinates are relative to navipane.

   516      *

   517      */

   518     static TRect NaviArrowRect( TScrollButton aScrollButton,

   519                                 TBool aNarrowLayout = EFalse,

   520                                 TRect aNaviRect = TRect( 0,0,0,0 ) );

   521 

   522 protected:

   523 

   524     /**

   525      * Decorated control.

   526      * Own.

   527      */

   528     CCoeControl* iDecoratedControl;

   529 

   530     /**

   531      * Navigation pane default control.

   532      */

   533     CAknNavigationControlContainer* iContainer;

   534 

   535     /**

   536      * Observer for handling decorator events.

   537      */

   538     MAknNaviDecoratorObserver* iNaviDecoratorObserver;

   539 

   540 private:

   541     TBool iNaviArrowsVisible;

   542     TBool iNaviArrowLeftDimmed;

   543     TBool iNaviArrowRightDimmed;

   544     TControlType iControlType;

   545     TPoint iArrowLeftPos;

   546     TSize  iArrowLeftSize;

   547     TPoint iArrowRightPos;

   548     TSize  iArrowRightSize;

   549 

   550     TInt iLayoutFlags;

   551     CPeriodic* iLayoutStyleTimer;

   552 

   553     CAknNavigationDecoratorExtension* iExtension;

   554 

   555     TInt iSpare;

   556     };

   557 

   558 #endif // C_AKNNAVIDE_H