epoc32/include/mw/aknnavide.h
branchSymbian2
changeset 2 2fe1408b6811
parent 1 666f914201fb
child 4 837f303aceeb
     1.1 --- a/epoc32/include/mw/aknnavide.h	Tue Nov 24 13:55:44 2009 +0000
     1.2 +++ b/epoc32/include/mw/aknnavide.h	Tue Mar 16 16:12:26 2010 +0000
     1.3 @@ -1,1 +1,558 @@
     1.4 -aknnavide.h
     1.5 +/*
     1.6 +* Copyright (c) 2002-2008 Nokia Corporation and/or its subsidiary(-ies).
     1.7 +* All rights reserved.
     1.8 +* This component and the accompanying materials are made available
     1.9 +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
    1.10 +* which accompanies this distribution, and is available
    1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
    1.12 +*
    1.13 +* Initial Contributors:
    1.14 +* Nokia Corporation - initial contribution.
    1.15 +*
    1.16 +* Contributors:
    1.17 +*
    1.18 +* Description:  Decorator class for navigation pane controls.
    1.19 +*                The class, for example, decorates navigation pane controls
    1.20 +*                with navi arrows.
    1.21 +*
    1.22 +*/
    1.23 +
    1.24 +
    1.25 +#ifndef C_AKNNAVIDE_H
    1.26 +#define C_AKNNAVIDE_H
    1.27 +
    1.28 +#include <akncontrol.h>
    1.29 +#include <coeccntx.h>
    1.30 +#include <e32std.h>
    1.31 +
    1.32 +#include <aknnaviobserver.h>
    1.33 +#include <aknnavi.h>
    1.34 +
    1.35 +class CEikScrollButton;
    1.36 +class CAknTabGroup;
    1.37 +class MAknNaviDecoratorObserver;
    1.38 +class CAknNavigationDecoratorExtension;
    1.39 +
    1.40 +/**
    1.41 + * Decorator class for navigation pane controls.
    1.42 + * The class, for example, decorates navigation pane controls with navi arrows.
    1.43 + */
    1.44 +class CAknNavigationDecorator :  public CAknControl,
    1.45 +                                 public MCoeControlObserver,
    1.46 +                                 public MAknNavigationDecoratorInterface
    1.47 +    {
    1.48 +
    1.49 +friend class CAknNavigationControlContainer;
    1.50 +
    1.51 +public:
    1.52 +
    1.53 +    /**
    1.54 +     * Defines scroll buttons.
    1.55 +     */
    1.56 +    enum TScrollButton
    1.57 +        {
    1.58 +        /** Scroll left. */
    1.59 +        ELeftButton =  0x0001,
    1.60 +
    1.61 +        /** Scroll right. */
    1.62 +        ERightButton = 0x0002
    1.63 +        };
    1.64 +
    1.65 +    /**
    1.66 +     * Defines type of the decorated control.
    1.67 +     */
    1.68 +    enum TControlType
    1.69 +        {
    1.70 +        /** Type not specified. */
    1.71 +        ENotSpecified,
    1.72 +
    1.73 +        /** Tab group. */
    1.74 +        ETabGroup,
    1.75 +
    1.76 +        /** Label. */
    1.77 +        ENaviLabel,
    1.78 +
    1.79 +        /** Image. */
    1.80 +        ENaviImage,
    1.81 +
    1.82 +        /** Text. */
    1.83 +        EHintText,
    1.84 +
    1.85 +        /** Indicator. */
    1.86 +        EEditorIndicator,
    1.87 +
    1.88 +        /** Volume. */
    1.89 +        ENaviVolume
    1.90 +        };
    1.91 +
    1.92 +public:
    1.93 +
    1.94 +    /**
    1.95 +     * Creates a new navigation decorator. The object takes ownership of the
    1.96 +     * decorated object at the beginning of the method before any leaving
    1.97 +     * functions.
    1.98 +     *
    1.99 +     * @param aNavigationControlContainer Container control.
   1.100 +     * @param aDecoratedControl Control to be decorated.
   1.101 +     * @param aType = @c ENotSpecified Control type.
   1.102 +     * @return Navigation Decorator object that
   1.103 +     *         contains decorated object.
   1.104 +     */
   1.105 +    IMPORT_C static CAknNavigationDecorator* NewL(
   1.106 +        CAknNavigationControlContainer* aNavigationControlContainer,
   1.107 +        CCoeControl* aDecoratedControl,
   1.108 +        TControlType aType = ENotSpecified);
   1.109 +
   1.110 +    /**
   1.111 +    * Destructor.
   1.112 +    */
   1.113 +    IMPORT_C ~CAknNavigationDecorator();
   1.114 +
   1.115 +    /**
   1.116 +     * Returns the control inside a navigation decorator object. Ownership of
   1.117 +     * the control is not changed.
   1.118 +     *
   1.119 +     * @return Control that is decorated with the decorator.
   1.120 +     */
   1.121 +    IMPORT_C CCoeControl* DecoratedControl();
   1.122 +
   1.123 +    /**
   1.124 +     * Shows or hides the navigation arrows at the both ends of the navigation
   1.125 +     * pane when current object is shown.
   1.126 +     *
   1.127 +     * @param aVisible Boolean value if navigation arrows are shown with the
   1.128 +     *        decorated control. Visible if @c ETrue.
   1.129 +     */
   1.130 +    IMPORT_C void MakeScrollButtonVisible(TBool aVisible);
   1.131 +
   1.132 +    /**
   1.133 +     * Gets the State of the visibility of navigation arrows.
   1.134 +     *
   1.135 +     * @return @c ETrue if visible.
   1.136 +     */
   1.137 +    IMPORT_C TBool ScrollButtonVisible() const;
   1.138 +
   1.139 +    /**
   1.140 +     * Sets the navigation arrow dimmed (and highlighted). Arrows have to be
   1.141 +     * visible so that the dimmed arrow is shown on the screen.
   1.142 +     *
   1.143 +     * @param aButton Navigation arrow to be set (@c ELeftButton or
   1.144 +     *        @c ERightButton).
   1.145 +     * @param aDimmed @c ETrue is the button is dimmed, @c EFalse if the button
   1.146 +     *        is set highlighted.
   1.147 +     */
   1.148 +    IMPORT_C void SetScrollButtonDimmed(TScrollButton aButton, TBool aDimmed);
   1.149 +
   1.150 +    /**
   1.151 +    * Is button dimmed or highlighted.
   1.152 +    *
   1.153 +    * @param aButton Navigation arrow.
   1.154 +    * @return @c ETrue If the navigation arrow is dimmed, @c EFalse if
   1.155 +    *         it is highlighted.
   1.156 +    */
   1.157 +    IMPORT_C TBool IsScrollButtonDimmed(TScrollButton aButton) const;
   1.158 +
   1.159 +    /**
   1.160 +     * Sets the type of the decorated control.
   1.161 +     *
   1.162 +     * @param aType Type of the control.
   1.163 +     */
   1.164 +    IMPORT_C void SetControlType(TControlType aType);
   1.165 +
   1.166 +    /**
   1.167 +     * Returns the type of the decorated control.
   1.168 +     *
   1.169 +     * @return Control type.
   1.170 +     */
   1.171 +    IMPORT_C TControlType ControlType() const;
   1.172 +
   1.173 +    /**
   1.174 +     * Sets observer for navigation decorator events in the decorated control.
   1.175 +     *
   1.176 +     * @param aObserver Pointer to observer.
   1.177 +     */
   1.178 +    IMPORT_C virtual void SetNaviDecoratorObserver(
   1.179 +                        MAknNaviDecoratorObserver* aObserver);
   1.180 +
   1.181 +    /**
   1.182 +     * Sets the pointer to the default navigation pane control.
   1.183 +     *
   1.184 +     * @param aContainer Pointer to default control in navigation pane.
   1.185 +     */
   1.186 +    void SetNaviStack(CAknNavigationControlContainer* aContainer);
   1.187 +
   1.188 +    /**
   1.189 +     * From @c CCoeControl.
   1.190 +     *
   1.191 +     * Handle pointer events.
   1.192 +     *
   1.193 +     * @param aPointerEvent Pointer event to be handled.
   1.194 +     */
   1.195 +    IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
   1.196 +
   1.197 +    /**
   1.198 +     * Defines the navigation control layout style.
   1.199 +     */
   1.200 +    enum TAknNaviControlLayoutStyle
   1.201 +        {
   1.202 +        /** Normal layout style. */
   1.203 +        ENaviControlLayoutNormal = 0x1,
   1.204 +
   1.205 +        /** Narrow layout style. */
   1.206 +        ENaviControlLayoutNarrow = 0x2,
   1.207 +
   1.208 +        /**
   1.209 +         * Wide layout style, can be used only in portrait mode, in
   1.210 +         * usual status pane layout (@c R_AVKON_STATUS_PANE_LAYOUT_USUAL_EXT).
   1.211 +         *
   1.212 +         * Tabs are not currently supported in wide layout style.
   1.213 +         */
   1.214 +        ENaviControlLayoutWide   = 0x4
   1.215 +        };
   1.216 +
   1.217 +    /**
   1.218 +     * Defines the navigation control layout mode.
   1.219 +     */
   1.220 +    enum TAknNaviControlLayoutMode
   1.221 +        {
   1.222 +        /**
   1.223 +         * This is the default layout mode. It lets UI framework to decide the
   1.224 +         * proper layout style which is applied to decorated controls in all
   1.225 +         * situations.
   1.226 +         */
   1.227 +        ENaviControlLayoutModeAutomatic = 0x400,
   1.228 +
   1.229 +        /**
   1.230 +         * @c ENaviControlLayoutModeForced layout mode can be used to lock
   1.231 +         * the layout style to the current style.
   1.232 +         */
   1.233 +        ENaviControlLayoutModeForced = 0x800
   1.234 +        };
   1.235 +
   1.236 +
   1.237 +    /**
   1.238 +     * Sets the layout style for this objects decorated control. The layout
   1.239 +     * style can be normal or narrow style.
   1.240 +     *
   1.241 +     * The style is really applied if the decorated control supports it or if
   1.242 +     * the layout mode has been set to forced mode
   1.243 +     * (@c ENaviControlLayoutModeForced). Additionally narrow mode may not be
   1.244 +     * supported at all in some statuspane configurations (even if forced).
   1.245 +     *
   1.246 +     * Whether decorated control supports or does not support given style at the
   1.247 +     * currently active statuspane layout can be queried using
   1.248 +     * @c NaviControlLayoutStyleSupported() method.
   1.249 +     *
   1.250 +     * @since S60 3.0
   1.251 +     * @param aStyle Can be normal (@c ENaviControlLayoutNormal),
   1.252 +     *                      narrow (@c ENaviControlLayoutNarrow) or
   1.253 +     *                      wide   (@c ENaviControlLayoutWide).
   1.254 +     *
   1.255 +     */
   1.256 +    IMPORT_C void SetNaviControlLayoutStyle(TAknNaviControlLayoutStyle aStyle);
   1.257 +
   1.258 +    /**
   1.259 +    * Gets the current layout style of this objects decorated control
   1.260 +    * (@c ENaviControlLayoutNormalm @c ENaviControlLayoutNarrow or
   1.261 +    *  @c ENaviControlLayoutWide).
   1.262 +    *
   1.263 +    * @since S60 3.0
   1.264 +    * @return Current layout style of the navicontrol
   1.265 +    */
   1.266 +    IMPORT_C TAknNaviControlLayoutStyle NaviControlLayoutStyle();
   1.267 +
   1.268 +    /**
   1.269 +     * Tells if decorated control supports given layout style at the current
   1.270 +     * statuspane layout. For @c ENotSpecified type of controls this always
   1.271 +     * returns @c EFalse (just for safety) because their implementation is
   1.272 +     * not known.
   1.273 +     *
   1.274 +     * @since S60 3.0
   1.275 +     * @param aStyle The layout style.
   1.276 +     * @return @c ETrue if the control supports given layout style
   1.277 +     *         otherwise returns @c EFalse.
   1.278 +     */
   1.279 +    IMPORT_C TBool NaviControlLayoutStyleSupported(TAknNaviControlLayoutStyle
   1.280 +                                                   aStyle);
   1.281 +
   1.282 +    /**
   1.283 +     * Sets the layout mode @c ENaviControlLayoutModeAutomatic or
   1.284 +     * @c ENaviControlLayoutModeForced. See @c TAknNaviControlLayoutMode
   1.285 +     * for more information.
   1.286 +     *
   1.287 +     * @since S60 3.0
   1.288 +     * @param aMode New layout mode.
   1.289 +     *
   1.290 +     */
   1.291 +    IMPORT_C void SetNaviControlLayoutMode(TAknNaviControlLayoutMode aMode);
   1.292 +
   1.293 +    /**
   1.294 +     * Gets the current layout mode of decorated control. Can be
   1.295 +     * @c ENaviControlLayoutModeAutomatic (default) or
   1.296 +     * @c ENaviControlLayoutModeForced (usually set by the application).
   1.297 +     *
   1.298 +     * @since S60 3.0
   1.299 +     * @return Decorated control's current layout
   1.300 +     *         mode.
   1.301 +     *
   1.302 +     */
   1.303 +    IMPORT_C TAknNaviControlLayoutMode NaviControlLayoutMode();
   1.304 +
   1.305 +
   1.306 +protected: // from CCoeControl
   1.307 +
   1.308 +    /**
   1.309 +     * From @c CCoeControl.
   1.310 +     *
   1.311 +     * Handles the size change events.
   1.312 +     */
   1.313 +    IMPORT_C virtual void SizeChanged();
   1.314 +
   1.315 +    /**
   1.316 +     * From @c CCoeControl.
   1.317 +     *
   1.318 +     * Returns the number of controls inside the context pane control.
   1.319 +     *
   1.320 +     * @return Number of controls.
   1.321 +     */
   1.322 +    IMPORT_C virtual TInt CountComponentControls() const;
   1.323 +
   1.324 +    /**
   1.325 +     * From @c CCoeControl.
   1.326 +     *
   1.327 +     * Returns a control determined by control id.
   1.328 +     *
   1.329 +     * @param aIndex Index of a control to be returned.
   1.330 +     * @return Pointer to the control.
   1.331 +     */
   1.332 +    IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const;
   1.333 +
   1.334 +public: // from CCoeControl
   1.335 +    /**
   1.336 +     * Handles a change to the control's resources of type aType
   1.337 +     * which are shared across the environment, e.g. color scheme change.
   1.338 +     * @param aType Event type.
   1.339 +     */
   1.340 +    IMPORT_C virtual void HandleResourceChange(TInt aType);
   1.341 +
   1.342 +protected: // from MCoeControlObserver
   1.343 +
   1.344 +    /**
   1.345 +     * From @c MCoeControlObserver.
   1.346 +     *
   1.347 +     * Handles an event from an observed control.
   1.348 +     *
   1.349 +     * @param aControl Control that caused the event.
   1.350 +     * @param aEventType Type of the event.
   1.351 +     */
   1.352 +    IMPORT_C void HandleControlEventL(CCoeControl* aControl,
   1.353 +                                      TCoeEvent aEventType);
   1.354 +
   1.355 +private:
   1.356 +
   1.357 +    /**
   1.358 +     * From CAknControl
   1.359 +     */
   1.360 +    IMPORT_C void* ExtensionInterface( TUid aInterface );
   1.361 +
   1.362 +private:
   1.363 +
   1.364 +    /**
   1.365 +     * Private constructor.
   1.366 +     */
   1.367 +    IMPORT_C void ConstructL();
   1.368 +
   1.369 +private:
   1.370 +
   1.371 +    /**
   1.372 +     * From CAknControl
   1.373 +     */
   1.374 +    IMPORT_C virtual void Draw(const TRect& aRect) const;
   1.375 +
   1.376 +    /**
   1.377 +     * Gets parent rect of this control. Used for layout calculation purposes.
   1.378 +     */
   1.379 +    TRect ParentRect();
   1.380 +
   1.381 +public:
   1.382 +
   1.383 +    /**
   1.384 +    * Gets the default rectangle of the given control type.
   1.385 +    *
   1.386 +    * @param  aControlType  The control type from which default rectangle is
   1.387 +    *                       asked.
   1.388 +    * @param  aArrowsUsed   Whether or not the navigation arrows are used
   1.389 +    *                       for the control. This is only used for the
   1.390 +    *                       tab group control. If arrows are not used with
   1.391 +    *                       tab group, then the whole navi pane area
   1.392 +    *                       is provided to the tab group control.
   1.393 +    * 
   1.394 +    * @return Rectangle which tells the default area for given
   1.395 +    *         controltype. Coordinates are relative to navi pane.
   1.396 +    */
   1.397 +    static TRect DecoratedControlRect( TInt aControlType,
   1.398 +                                       TBool aArrowsUsed = ETrue );
   1.399 +
   1.400 +    /**
   1.401 +     * Gets the default rectangle of the navigation pane's default control.
   1.402 +     *
   1.403 +     * @param aControlType Not used.
   1.404 +     * @return Rectangle of the navigation pane's default control.
   1.405 +     */
   1.406 +    static TRect DecoratedControlNarrowRect( TInt aControlType );
   1.407 +
   1.408 +private:
   1.409 +
   1.410 +    /**
   1.411 +     * Gets the default rect of default controltype relative to navipane in
   1.412 +     * normal layoutstyle (@c ENaviControlLayoutNormal)
   1.413 +     *
   1.414 +     * @return Rectangle which is tells the default area for a navi control.
   1.415 +     *         Coordinates are relative to navipane.
   1.416 +     *
   1.417 +     */
   1.418 +    static TRect DecoratedDefaultControlRect();
   1.419 +
   1.420 +public:
   1.421 +
   1.422 +    /**
   1.423 +    * Gets the default rect of tab group control type relative to navipane in
   1.424 +    * normal (@c ENaviControlLayoutNormal) or wide (@c ENaviControlLayoutWide)
   1.425 +    * layout style.
   1.426 +    *
   1.427 +    * @param  aTopAdjacent  @c ETrue to return a rectangle adjacent to the
   1.428 +    *                       top of navi pane, @c EFalse for a rectangle
   1.429 +    *                       adjacent to the bottom of navi pane.
   1.430 +    * @param  aArrowsUsed   Whether or not the navigation arrows are used
   1.431 +    *                       for the tab group. If arrows are not used, then
   1.432 +    *                       the whole navi pane area is provided to the tab
   1.433 +    *                       group control.
   1.434 +    *
   1.435 +    * @return Rectangle which tells the default area for a tab group.
   1.436 +    */
   1.437 +    static TRect DecoratedTabControlRect( TBool aTopAdjacent,
   1.438 +                                          TBool aArrowsUsed );
   1.439 +
   1.440 +private:
   1.441 +
   1.442 +    /**
   1.443 +     * Gets the default rect of volume controltype relative to navipane in
   1.444 +     * normal layoutstyle (@c ENaviControlLayoutNormal)
   1.445 +     *
   1.446 +     * @return Rectangle which is tells the default area for a volume control.
   1.447 +     *         Coordinates are relative to navipane.
   1.448 +     *
   1.449 +     */
   1.450 +    static TRect DecoratedVolumeControlRect();
   1.451 +
   1.452 +    /**
   1.453 +     * This method handles sizechanges in normal layout style.
   1.454 +     */
   1.455 +    void SizeChangedInNormalLayout();
   1.456 +
   1.457 +    /**
   1.458 +     * This method handles sizechanges in narrow layout style.
   1.459 +     */
   1.460 +    void SizeChangedInNarrowLayout();
   1.461 +
   1.462 +    /**
   1.463 +     * This method handles sizechanges in wide layout style.
   1.464 +     */
   1.465 +    void SizeChangedInWideLayout();
   1.466 +
   1.467 +    /**
   1.468 +     * This method initializes timer that is used for times layout style
   1.469 +     * changes.
   1.470 +     */
   1.471 +    void InitLayoutStyleTimer();
   1.472 +
   1.473 +    /**
   1.474 +     * This method cancels timer that is used for times layout style changes.
   1.475 +     */
   1.476 +    void CancelLayoutStyleTimer();
   1.477 +
   1.478 +    /**
   1.479 +     * This method is executed when timer that is used for times layout style
   1.480 +     * changes expires.
   1.481 +     */
   1.482 +    static TInt LayoutStyleEvent(TAny * aPtr);
   1.483 +
   1.484 +    /**
   1.485 +     * This method is executed when timer that is used for times layout style
   1.486 +     * changes expires.
   1.487 +     */
   1.488 +    void DoLayoutStyleEvent();
   1.489 +
   1.490 +    void StartTimerL();
   1.491 +
   1.492 +    void SmallDirectionIndicationL();
   1.493 +
   1.494 +    static TInt IndicationDrawCallbackL( TAny* aThis );
   1.495 +
   1.496 +    /**
   1.497 +     * This method cancels the timer that is used in the small direction
   1.498 +     * indication animation.
   1.499 +     */
   1.500 +    void CancelTimer();
   1.501 +
   1.502 +    /**
   1.503 +     * Gets the rectangle for a navigation arrow.
   1.504 +     *
   1.505 +     * @param   aScrollButton  @c ELeftButton to return the rectangle
   1.506 +     *                         of the left navi arrow,
   1.507 +     *                         @c ERightButton for right navi arrow.
   1.508 +     *
   1.509 +     * @param   aNarrowLayout  @c ETrue to get a navi arrow rectangle
   1.510 +     *                         for a narrow decorator layout,
   1.511 +     *                         @c EFalse otherwise.
   1.512 +     *
   1.513 +     * @param   aNaviRect  Navi pane rectangle to be used as parent,
   1.514 +     *                     the returned rectangle is relative to this.
   1.515 +     *                     If not defined, then relative to the
   1.516 +     *                     default navi pane area.
   1.517 +     *
   1.518 +     * @return  Navigation arrow rectangle.
   1.519 +     *          Coordinates are relative to navipane.
   1.520 +     *
   1.521 +     */
   1.522 +    static TRect NaviArrowRect( TScrollButton aScrollButton,
   1.523 +                                TBool aNarrowLayout = EFalse,
   1.524 +                                TRect aNaviRect = TRect( 0,0,0,0 ) );
   1.525 +
   1.526 +protected:
   1.527 +
   1.528 +    /**
   1.529 +     * Decorated control.
   1.530 +     * Own.
   1.531 +     */
   1.532 +    CCoeControl* iDecoratedControl;
   1.533 +
   1.534 +    /**
   1.535 +     * Navigation pane default control.
   1.536 +     */
   1.537 +    CAknNavigationControlContainer* iContainer;
   1.538 +
   1.539 +    /**
   1.540 +     * Observer for handling decorator events.
   1.541 +     */
   1.542 +    MAknNaviDecoratorObserver* iNaviDecoratorObserver;
   1.543 +
   1.544 +private:
   1.545 +    TBool iNaviArrowsVisible;
   1.546 +    TBool iNaviArrowLeftDimmed;
   1.547 +    TBool iNaviArrowRightDimmed;
   1.548 +    TControlType iControlType;
   1.549 +    TPoint iArrowLeftPos;
   1.550 +    TSize  iArrowLeftSize;
   1.551 +    TPoint iArrowRightPos;
   1.552 +    TSize  iArrowRightSize;
   1.553 +
   1.554 +    TInt iLayoutFlags;
   1.555 +    CPeriodic* iLayoutStyleTimer;
   1.556 +
   1.557 +    CAknNavigationDecoratorExtension* iExtension;
   1.558 +
   1.559 +    TInt iSpare;
   1.560 +    };
   1.561 +
   1.562 +#endif // C_AKNNAVIDE_H