1 /*

     2 * Copyright (c) 2002-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:  A default control in the status pane's navigation pane.

    15 *

    16 */

    17 

    18 

    19 #ifndef C_AKNNAVI_H

    20 #define C_AKNNAVI_H

    21 

    22 #include <AknControl.h>

    23 #include <coeccntx.h>

    24 #include <Aknvolumecontrol.h>

    25 

    26 // FORWARD DECLARATIONS

    27 class CAknNavigationDecorator;

    28 class CEikStatusPaneBase;

    29 class CFbsBitmap;

    30 class MAknTabObserver;

    31 class CAknNavigationControlContainerExtension;

    32 class MAknsControlContext;

    33 

    34 class MAknNavigationDecoratorInterface

    35     {

    36 public:

    37     virtual ~MAknNavigationDecoratorInterface() { }

    38     virtual CCoeControl* DecoratedControl() = 0;

    39     };

    40 

    41 class MAknNavigationContainerInterface

    42     {

    43 public:

    44     virtual ~MAknNavigationContainerInterface() { }

    45     virtual CAknNavigationDecorator* CreateMessageLabelL(const TDesC& aText) = 0;

    46     virtual CAknNavigationDecorator* CreateTabGroupL() = 0;

    47     virtual void PushL( CAknNavigationDecorator& ) = 0;

    48     virtual void Pop() = 0;

    49     };

    50 

    51 /**

    52  * A default control in the status pane's navigation pane.

    53  */

    54 class CAknNavigationControlContainer : public CAknControl,

    55                                        public MCoeControlContext,

    56                                        public MCoeControlObserver,

    57                                        public MAknNavigationContainerInterface

    58     {

    59 

    60 public:

    61 

    62     DECLARE_TYPE_ID( 0x101F8740 )

    63 

    64 public:

    65 

    66     /**

    67      * C++ default constructor.

    68      *

    69      * This object does not own the contents of the navi pane controls stack.

    70      */

    71     IMPORT_C CAknNavigationControlContainer();

    72 

    73     /**

    74      * Destructor.

    75      *

    76      * This object does not own the contents of the navi pane controls stack.

    77      */

    78     IMPORT_C ~CAknNavigationControlContainer();

    79 

    80     /**

    81      * Handles 2nd phase construction.

    82      */

    83     IMPORT_C void ConstructL();

    84 

    85     /**

    86      * Constructs from a resource. Created object is owned by this object until

    87      * @c ResourceDecorator() method is called. If the application does not

    88      * fetch the object it is deleted in destructor.

    89      *

    90      * @param aReader Resource reader.

    91      */

    92     IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );

    93 

    94     /**

    95      * Resource constructor that returns a new object to the application.

    96      *

    97      * @param aReader Resource reader.

    98      * @return Navigation decorator object that contains navigation pane

    99      *         control read from resources.

   100      */

   101     IMPORT_C CAknNavigationDecorator*

   102                     ConstructNavigationDecoratorFromResourceL(

   103                                                 TResourceReader& aReader);

   104 

   105     /**

   106      * Creates and returns a new navigation decorator object containing tab

   107      * group.

   108      * The ownership of the object is transferred to the application.

   109      *

   110      * @return Navigation decorator object that contains tab group.

   111      */

   112     IMPORT_C CAknNavigationDecorator* CreateTabGroupL();

   113 

   114     /**

   115      * Creates and returns a new navigation decorator object containing tab

   116      * group. The ownership of the object is transferred to the application.

   117      *

   118      * @param aObserver Pointer to tab group observer

   119      * @return Navigation decorator object that contains tab group.

   120      */

   121     IMPORT_C CAknNavigationDecorator* CreateTabGroupL(

   122                                             MAknTabObserver* aObserver);

   123 

   124     /**

   125      * Creates from a resource and returns a new navigation decorator object

   126      * containing tab group.

   127      * The ownership of the object is transferred to the application.

   128      *

   129      * @param aReader Resource reader.

   130      * @return Navigation decorator object that contains tab group.

   131      */

   132     IMPORT_C CAknNavigationDecorator* CreateTabGroupL(

   133                                                 TResourceReader& aReader);

   134 

   135     /**

   136      * Creates from a resource and returns a new navigation decorator object

   137      * containing tab group.

   138      * The ownership of the object is transferred to the application.

   139      *

   140      * @param aReader Resource reader.

   141      * @param aObserver Pointer to tab group observer.

   142      * @return Navigation decorator object that contains tab group.

   143      */

   144     IMPORT_C CAknNavigationDecorator* CreateTabGroupL(

   145                                             TResourceReader& aReader,

   146                                             MAknTabObserver* aObserver);

   147 

   148     /**

   149      * Creates and returns a new navigation decorator object containing

   150      * navigation label.

   151      * The ownership of the object is transferred to the application.

   152      *

   153      * @param aText Label text to the navigation pane.

   154      * @return Navigation decorator object that contains navigation label.

   155      */

   156     IMPORT_C CAknNavigationDecorator* CreateNavigationLabelL(

   157                                             const TDesC& aText = KNullDesC);

   158 

   159     /**

   160      * Creates from a resource and returns a new navigation decorator object

   161      * containing navigation label.

   162      * The ownership of the object is transferred to the application.

   163      *

   164      * @param aReader Resource reader.

   165      * @return Navigation decorator object that contains navigation label.

   166      */

   167     IMPORT_C CAknNavigationDecorator* CreateNavigationLabelL(

   168                                                     TResourceReader& aReader);

   169 

   170     /**

   171      * Creates and returns a new navigation decorator object containing

   172      * navigation image.

   173      * The ownership of the returned object is transferred to the application.

   174      * Moves ownership of @c aBitmap and @c aMaskBitmap to the navigation

   175      * decorator object at the end of the method.

   176      *

   177      * @param aBitmap Image to be shown in the navigation pane.

   178      * @param aMaskBitmap Mask of the image to be shown in the

   179      *        navigation panel.

   180      * @return Navigation decorator object that contains navigation image.

   181      */

   182     IMPORT_C CAknNavigationDecorator* CreateNavigationImageL(

   183                                         const CFbsBitmap* aBitmap = NULL,

   184                                         const CFbsBitmap* aMaskBitmap = NULL);

   185 

   186     /**

   187      * Creates from a resource and returns a new navigation decorator object

   188      * containing navigation image.

   189      * The ownership of the returned object is transferred to the application.

   190      *

   191      * @param aReader Resource reader.

   192      * @return Navigation decorator object that

   193      *         contains navigation image.

   194      */

   195     IMPORT_C CAknNavigationDecorator* CreateNavigationImageL(

   196                                             TResourceReader& aReader);

   197 

   198     /**

   199      * Creates and returns a new navigation decorator object containing

   200      * help text.

   201      * The ownership of the object is transferred to the application.

   202      *

   203      * @param aText Help text label to be shown in the navigation pane.

   204      * @return Navigation decorator object that

   205      *         contains message label (=hint text).

   206      */

   207     IMPORT_C CAknNavigationDecorator* CreateMessageLabelL(

   208                                         const TDesC& aText = KNullDesC);

   209 

   210     /**

   211      * Creates from a resource and returns a new navigation decorator object

   212      * containing help text.

   213      * The ownership of the object is transferred to the application.

   214      *

   215      * @param aReader Resource reader.

   216      * @return Navigation decorator object that contains message label

   217      *         (=hint text).

   218      */

   219     IMPORT_C CAknNavigationDecorator* CreateMessageLabelL(

   220                                             TResourceReader& aReader);

   221 

   222     /**

   223      * Creates volume control indicator to the navi pane.

   224      * The ownership of the object is transferred to the application.

   225      *

   226      * @param aResourceId Resource file id for the volume control

   227      * @return Navigation decorator object that contains volume indicator.

   228      *

   229      * @deprecated  Navi pane volume control is not supported anymore.

   230      */

   231     IMPORT_C CAknNavigationDecorator* CreateVolumeIndicatorL(TInt aResourceId);

   232 

   233     /**

   234      * Creates editor indicator container control to the navi pane.

   235      * The ownership of the object is transferred to the application.

   236      *

   237      * @return Navigation decorator object that contains editor indicator

   238      *         container.

   239      */

   240     IMPORT_C CAknNavigationDecorator* CreateEditorIndicatorContainerL();

   241 

   242     /**

   243      * Pushes default content (empty navigation pane) to the navigation pane's

   244      * object stack.

   245      * This operation also draws default content to the navigation pane.

   246      *

   247      * @param  aAllowDuplicates  If this is @c ETrue, duplicate default

   248      *                           navi pane contents are allowed.

   249      */

   250     IMPORT_C void PushDefaultL( TBool aAllowDuplicates = EFalse );

   251 

   252     /**

   253      * Pushes a navigation decorator object to the navigation pane's object

   254      * stack.

   255      * This operation also draws the control to the navigation pane. An object

   256      * can be on the stack only once. If the object already exists in the stack

   257      * it is moved to topmost object. Ownership is not transfered.

   258      * Editor indicator control has priority over others. It is always at the

   259      * top if it exists. In this case all other controls are pushed under

   260      * the editor indicator object.

   261      *

   262      * @param aNaviPaneControl Object to be added at the top of the stack.

   263      */

   264     IMPORT_C void PushL( CAknNavigationDecorator& aNaviPaneControl );

   265 

   266     /**

   267      * Pops topmost object from the navigation pane's object stack. If editor

   268      * indicator control is topmost, it is not popped. The next control

   269      * is popped instead.

   270      * It is not possible to pop editor indicator object with this method.

   271      * Use @c Pop(CAknNavigationDecorator* aControl) or @c delete(aControl)

   272      * instead if editor indicator control is needed to be popped.

   273      */

   274     IMPORT_C void Pop();

   275 

   276     /**

   277      * Pops (remove) certain object from the navigation pane's object stack.

   278      * The removed object does not need to be topmost.

   279      *

   280      * @param aControl Object to be removed from the stack.

   281      */

   282     IMPORT_C void Pop( CAknNavigationDecorator* aControl );

   283 

   284     /**

   285      * Returns topmost object from navigation pane's object stack.

   286      * Editor indicator object is transparent for this operation. If editor

   287      * indicators exist on the navi pane, next object on the stack is returned.

   288      *

   289      * @return Navigation decorator object that is topmost in navigation pane's

   290      *         object stack.

   291      */

   292     IMPORT_C CAknNavigationDecorator* Top();

   293 

   294     /**

   295     * Return topmost object from navigation pane's object stack.

   296     * FEP Editor indicator object is transparent or visible for this operation

   297     * depending on the given parameter value. If editor indicator object is to

   298     * be ignored and it exist on the navi pane, next object on the stack is

   299     * returned. Note that generally FEP does all the needed visibility etc.

   300     * handling for FEP editor indicators, so by default applications should

   301     * ignore FEP editor indicators.

   302     *

   303     * @since 3.1

   304     * @param  aIgnoreFepEditorIndicator  Tells if editor indicator

   305     *                                    object is ignored.

   306     *

   307     * @return Navigation decorator object that is topmost in

   308     *         navigation pane's object stack.

   309     */

   310     IMPORT_C CAknNavigationDecorator* Top(TBool aIgnoreFepEditorIndicator) const;

   311 

   312 

   313     /**

   314      * Replaces existing navigation decorator object in the navigation pane's

   315      * object stack. Any object can be on the stack only once. If the

   316      * replacement object already exists in the stack, previous copy is

   317      * removed from the stack. Ownership is not transfered.

   318      * Navi pane is redrawn if top item is changed.

   319      *

   320      * @param aToBeReplaced An object to be replaced.

   321      * @param aReplacement An object that is put to the stack instead.

   322      * @return Error number. @c KErrNone if the operation succeeds.

   323      *         @c KErrNotFound if @c 'aToBeReplaced' object cannot be

   324      *         found from the stack.

   325      */

   326     IMPORT_C TInt ReplaceL( CAknNavigationDecorator& aToBeReplaced,

   327                             CAknNavigationDecorator& aReplacement );

   328 

   329     /**

   330      * Returns the object constructed from resources with

   331      * @c ConstrucFromResourcesL() -method to the application.

   332      * Ownership of the object is transferred to the application.

   333      *

   334      * @return Navigation Decorator object that was

   335      *         created from resources.

   336      */

   337     IMPORT_C CAknNavigationDecorator* ResourceDecorator();

   338 

   339     /**

   340      * This non-exported method returns reference to navi arrow bitmaps.

   341      *

   342      * @param  aId  Id of the bitmap.

   343      * @return Reference to the navi arrow bitmap.

   344      */

   345     CFbsBitmap& NaviArrowBitmap( TInt aId );

   346 

   347 public:

   348 

   349     /**

   350      * This method can be used to set preferred layout style for navi decorator

   351      * objects that are pushed into navistack.

   352      * Given layout is applied to objects only if that object supports it and

   353      * status pane layout allows that mode to be used.

   354      *

   355      * @since 3.1

   356      *

   357      * @param aLayoutStyle CAknNavigationDecorator::ENaviControlLayoutNormal,

   358      *                     CAknNavigationDecorator::ENaviControlLayoutNarrow or

   359      *                     CAknNavigationDecorator::ENaviControlLayoutWide

   360      *

   361      */

   362     IMPORT_C void SetPreferredNaviDecoratorLayoutStyle( TInt aLayoutStyle );

   363 

   364     /**

   365      * Static method to return current color scheme.

   366      * @return Current color scheme value.

   367      */

   368     IMPORT_C static TInt ColorScheme();

   369 

   370     /**

   371      * Used by the UI framework. Notifies context and signal

   372      * panes wheter navi wipe graphichs is to be drawn or not.

   373      */

   374     void NotifyNaviWipeStatusL();

   375 

   376     /**

   377      * Gets current wipe bitmap for navi pane.

   378      *

   379      * @return Wipe bitmap Id

   380      */

   381     static TInt CurrentNaviWipeBitmap();

   382 

   383     /**

   384      * From @c CCoeControl.

   385      *

   386      * Handles pointer events

   387      *

   388      * @param aPointerEvent The pointer event.

   389      */

   390     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   391     

   392     /**

   393      * Used to notify the navi pane when it goes to background.

   394      * @internal Used by the UI framework.

   395      */

   396     void HandleLosingForeground();

   397     

   398     /**

   399      * Used to notify the navi pane when it gains foreground.

   400      * @internal Used by the UI framework.

   401      */

   402     void HandleGainingForegroundL();

   403 

   404 protected: // from CCoeControl

   405 

   406     /**

   407      * From @c CCoeControl.

   408      *

   409      * Handles the size change events.

   410      */

   411     IMPORT_C virtual void SizeChanged();

   412 

   413     /**

   414      * From @c CCoeControl.

   415      *

   416      * Handles a change to the control's resources of type @c aType

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

   418      *

   419      * @param aType Event type.

   420      */

   421     IMPORT_C virtual void HandleResourceChange(TInt aType);

   422 

   423     /**

   424      * From @c CCoeControl.

   425      *

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

   427      *

   428      * @return Number of component controls.

   429      */

   430     IMPORT_C virtual TInt CountComponentControls() const;

   431 

   432     /**

   433      * From @c CCoeControl.

   434      *

   435      * Returns a control determined by control id.

   436      *

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

   438      * @return Pointer to control.

   439      */

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

   441 

   442 protected: // from MCoeControlObserver

   443 

   444     /**

   445      * From @c  MCoeControlObserver.

   446      *

   447      * Handles Control event.

   448      *

   449      * @param aControl Control that caused the event.

   450      * @param aEventType Type of the event.

   451      */

   452     IMPORT_C void HandleControlEventL(CCoeControl* aControl,

   453                                       TCoeEvent aEventType);

   454 

   455 private: // from CCoeControl

   456 

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

   458 

   459 private:

   460 

   461     /**

   462     * From CAknControl

   463     */

   464     IMPORT_C void* ExtensionInterface( TUid aInterface );

   465 

   466 public:

   467 

   468     /**

   469      * Not used / implemented

   470      *

   471      * @deprecated

   472      *

   473      * @since S60 3.0

   474      *

   475      * @return @c EFalse

   476      */

   477     TBool NaviWipeUsed() const;

   478 

   479     /**

   480      * Gets navi bitmap.

   481      *

   482      * @return Bitmap's colour.

   483      */

   484     CFbsBitmap* NaviColorBitmap() const;

   485 

   486     /**

   487      * Not used / implemented

   488      *

   489      * @deprecated

   490      *

   491      * @since S60 3.0

   492      */

   493     static void SetBackgroundContextAttributes( CCoeControl* aControl,

   494                                                 TBool aNaviWipeUsed );

   495 

   496 private:

   497     TBool IsFepOwnedEditorIndicatorControl(

   498         CAknNavigationDecorator* aDecorator ) const;

   499 

   500     void HandleVisibilityOfNonFepOwnedIndicatorControl(

   501         CAknNavigationDecorator* aDecorator, TBool aVisible);

   502 

   503     /**

   504     * Checks wheter default navi wipe bitmap can be drawn to navipane and draws

   505     * it if it is possible.

   506     *

   507     * @since S60 2.6

   508     * @param aGc Used graphics context.

   509     * @param aRect Rect of the navipane.

   510     * @return @c ETrue if draw operation was done, otherwise @c EFalse.

   511     *

   512     */

   513     TBool DrawDefaultNaviWipe(CWindowGc& aGc, const TRect& aRect) const;

   514 

   515     /**

   516     * Checks wheter default navi solid bitmap can be drawn to navipane and draws

   517     * it if it is possible.

   518     *

   519     * @since S60 2.6

   520     * @param aGc Used graphics context.

   521     * @param aRect Rect of the navipane.

   522     * @return ETrue if draw operation was done, otherwise EFalse.

   523     *

   524     */

   525     TBool DrawDefaultNaviSolid(CWindowGc& aGc, const TRect& aRect) const;

   526 

   527     /**

   528     * Checks wheter skinned navi wipe bitmap can be drawn to navipane and draws

   529     * it if it is possible. Also skinned background bitmap is drawn.

   530     *

   531     * @since S60 2.6

   532     * @param aGc Used graphics context.

   533     * @param aRect Rect of the navipane.

   534     * @param aSkin Used skin instance.

   535     * @param aCc Used skin control context.

   536     * @return ETrue if draw operation was done, otherwise EFalse.

   537     */

   538     TBool DrawSkinnedNaviWipe( CWindowGc& aGc,

   539                                const TRect& aRect,

   540                                MAknsSkinInstance* aSkin,

   541                                MAknsControlContext* aCc ) const;

   542 

   543     /**

   544     * Checks wheter skinned navi solid bitmap can be drawn to navipane and draws

   545     * it if it is possible. Also skinned background bitmap is drawn.

   546     *

   547     * @since S60 2.6

   548     * @param aGc Used graphics context.

   549     * @param aRect Rect of the navipane.

   550     * @param aSkin Used skin instance.

   551     * @param aCc Used skin control context.

   552     * @return ETrue if draw operation was done, otherwise EFalse.

   553     */

   554     TBool DrawSkinnedNaviSolid( CWindowGc& aGc,

   555                                 const TRect& aRect,

   556                                 MAknsSkinInstance* aSkin,

   557                                 MAknsControlContext* aCc ) const;

   558 

   559     /**

   560      * Loads a color bitmap for CAknNavigationDecorator.

   561      * @since S60 2.8

   562      */

   563     void LoadNaviColorBitmapL();

   564 

   565     void SetContainerWindowNonFading( TBool aNonFading );

   566     

   567     TRect VolumePopupRect();

   568 

   569 protected: // from CCoeControl

   570 

   571     /**

   572      * From @c CCoeControl.

   573      *

   574      * Retrieves an object of the same type as that encapsulated in aId.

   575      *

   576      * This function is used to allow controls to ask their owners for

   577      * access to other objects that they own.

   578      *

   579      * Other than in the case where NULL is returned, the object returned

   580      * must be of the same object type - that is, the @c ETypeId member of

   581      * the object pointed to by the pointer returned by this function must

   582      * be equal to the @c iUid member of @c aId.

   583      *

   584      * @param aId An encapsulated object type ID.

   585      * @return Encapsulated pointer to the provided object.

   586      *         Note that the encapsulated pointer may be NULL.

   587      */

   588     TTypeUid::Ptr MopSupplyObject( TTypeUid aId );

   589 

   590 private:

   591 

   592     CEikStatusPaneBase* iStatusPane;

   593 

   594     CAknNavigationDecorator* iNaviDecoratorFromResource;

   595 

   596     typedef CArrayPtrFlat<CAknNavigationDecorator> CAknNaviPaneStack;

   597     CAknNaviPaneStack* iNaviPaneControls;

   598 

   599     CFbsBitmap* iNaviArrowBitmap[4];

   600 

   601     TInt  iSpare;

   602     CAknNavigationControlContainerExtension* iExtension;

   603     };

   604 

   605 #endif // C_AKNNAVI_H