1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/aknnavi.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,605 @@
1.4 +/*
1.5 +* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: A default control in the status pane's navigation pane.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef C_AKNNAVI_H
1.23 +#define C_AKNNAVI_H
1.24 +
1.25 +#include <AknControl.h>
1.26 +#include <coeccntx.h>
1.27 +#include <Aknvolumecontrol.h>
1.28 +
1.29 +// FORWARD DECLARATIONS
1.30 +class CAknNavigationDecorator;
1.31 +class CEikStatusPaneBase;
1.32 +class CFbsBitmap;
1.33 +class MAknTabObserver;
1.34 +class CAknNavigationControlContainerExtension;
1.35 +class MAknsControlContext;
1.36 +
1.37 +class MAknNavigationDecoratorInterface
1.38 + {
1.39 +public:
1.40 + virtual ~MAknNavigationDecoratorInterface() { }
1.41 + virtual CCoeControl* DecoratedControl() = 0;
1.42 + };
1.43 +
1.44 +class MAknNavigationContainerInterface
1.45 + {
1.46 +public:
1.47 + virtual ~MAknNavigationContainerInterface() { }
1.48 + virtual CAknNavigationDecorator* CreateMessageLabelL(const TDesC& aText) = 0;
1.49 + virtual CAknNavigationDecorator* CreateTabGroupL() = 0;
1.50 + virtual void PushL( CAknNavigationDecorator& ) = 0;
1.51 + virtual void Pop() = 0;
1.52 + };
1.53 +
1.54 +/**
1.55 + * A default control in the status pane's navigation pane.
1.56 + */
1.57 +class CAknNavigationControlContainer : public CAknControl,
1.58 + public MCoeControlContext,
1.59 + public MCoeControlObserver,
1.60 + public MAknNavigationContainerInterface
1.61 + {
1.62 +
1.63 +public:
1.64 +
1.65 + DECLARE_TYPE_ID( 0x101F8740 )
1.66 +
1.67 +public:
1.68 +
1.69 + /**
1.70 + * C++ default constructor.
1.71 + *
1.72 + * This object does not own the contents of the navi pane controls stack.
1.73 + */
1.74 + IMPORT_C CAknNavigationControlContainer();
1.75 +
1.76 + /**
1.77 + * Destructor.
1.78 + *
1.79 + * This object does not own the contents of the navi pane controls stack.
1.80 + */
1.81 + IMPORT_C ~CAknNavigationControlContainer();
1.82 +
1.83 + /**
1.84 + * Handles 2nd phase construction.
1.85 + */
1.86 + IMPORT_C void ConstructL();
1.87 +
1.88 + /**
1.89 + * Constructs from a resource. Created object is owned by this object until
1.90 + * @c ResourceDecorator() method is called. If the application does not
1.91 + * fetch the object it is deleted in destructor.
1.92 + *
1.93 + * @param aReader Resource reader.
1.94 + */
1.95 + IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );
1.96 +
1.97 + /**
1.98 + * Resource constructor that returns a new object to the application.
1.99 + *
1.100 + * @param aReader Resource reader.
1.101 + * @return Navigation decorator object that contains navigation pane
1.102 + * control read from resources.
1.103 + */
1.104 + IMPORT_C CAknNavigationDecorator*
1.105 + ConstructNavigationDecoratorFromResourceL(
1.106 + TResourceReader& aReader);
1.107 +
1.108 + /**
1.109 + * Creates and returns a new navigation decorator object containing tab
1.110 + * group.
1.111 + * The ownership of the object is transferred to the application.
1.112 + *
1.113 + * @return Navigation decorator object that contains tab group.
1.114 + */
1.115 + IMPORT_C CAknNavigationDecorator* CreateTabGroupL();
1.116 +
1.117 + /**
1.118 + * Creates and returns a new navigation decorator object containing tab
1.119 + * group. The ownership of the object is transferred to the application.
1.120 + *
1.121 + * @param aObserver Pointer to tab group observer
1.122 + * @return Navigation decorator object that contains tab group.
1.123 + */
1.124 + IMPORT_C CAknNavigationDecorator* CreateTabGroupL(
1.125 + MAknTabObserver* aObserver);
1.126 +
1.127 + /**
1.128 + * Creates from a resource and returns a new navigation decorator object
1.129 + * containing tab group.
1.130 + * The ownership of the object is transferred to the application.
1.131 + *
1.132 + * @param aReader Resource reader.
1.133 + * @return Navigation decorator object that contains tab group.
1.134 + */
1.135 + IMPORT_C CAknNavigationDecorator* CreateTabGroupL(
1.136 + TResourceReader& aReader);
1.137 +
1.138 + /**
1.139 + * Creates from a resource and returns a new navigation decorator object
1.140 + * containing tab group.
1.141 + * The ownership of the object is transferred to the application.
1.142 + *
1.143 + * @param aReader Resource reader.
1.144 + * @param aObserver Pointer to tab group observer.
1.145 + * @return Navigation decorator object that contains tab group.
1.146 + */
1.147 + IMPORT_C CAknNavigationDecorator* CreateTabGroupL(
1.148 + TResourceReader& aReader,
1.149 + MAknTabObserver* aObserver);
1.150 +
1.151 + /**
1.152 + * Creates and returns a new navigation decorator object containing
1.153 + * navigation label.
1.154 + * The ownership of the object is transferred to the application.
1.155 + *
1.156 + * @param aText Label text to the navigation pane.
1.157 + * @return Navigation decorator object that contains navigation label.
1.158 + */
1.159 + IMPORT_C CAknNavigationDecorator* CreateNavigationLabelL(
1.160 + const TDesC& aText = KNullDesC);
1.161 +
1.162 + /**
1.163 + * Creates from a resource and returns a new navigation decorator object
1.164 + * containing navigation label.
1.165 + * The ownership of the object is transferred to the application.
1.166 + *
1.167 + * @param aReader Resource reader.
1.168 + * @return Navigation decorator object that contains navigation label.
1.169 + */
1.170 + IMPORT_C CAknNavigationDecorator* CreateNavigationLabelL(
1.171 + TResourceReader& aReader);
1.172 +
1.173 + /**
1.174 + * Creates and returns a new navigation decorator object containing
1.175 + * navigation image.
1.176 + * The ownership of the returned object is transferred to the application.
1.177 + * Moves ownership of @c aBitmap and @c aMaskBitmap to the navigation
1.178 + * decorator object at the end of the method.
1.179 + *
1.180 + * @param aBitmap Image to be shown in the navigation pane.
1.181 + * @param aMaskBitmap Mask of the image to be shown in the
1.182 + * navigation panel.
1.183 + * @return Navigation decorator object that contains navigation image.
1.184 + */
1.185 + IMPORT_C CAknNavigationDecorator* CreateNavigationImageL(
1.186 + const CFbsBitmap* aBitmap = NULL,
1.187 + const CFbsBitmap* aMaskBitmap = NULL);
1.188 +
1.189 + /**
1.190 + * Creates from a resource and returns a new navigation decorator object
1.191 + * containing navigation image.
1.192 + * The ownership of the returned object is transferred to the application.
1.193 + *
1.194 + * @param aReader Resource reader.
1.195 + * @return Navigation decorator object that
1.196 + * contains navigation image.
1.197 + */
1.198 + IMPORT_C CAknNavigationDecorator* CreateNavigationImageL(
1.199 + TResourceReader& aReader);
1.200 +
1.201 + /**
1.202 + * Creates and returns a new navigation decorator object containing
1.203 + * help text.
1.204 + * The ownership of the object is transferred to the application.
1.205 + *
1.206 + * @param aText Help text label to be shown in the navigation pane.
1.207 + * @return Navigation decorator object that
1.208 + * contains message label (=hint text).
1.209 + */
1.210 + IMPORT_C CAknNavigationDecorator* CreateMessageLabelL(
1.211 + const TDesC& aText = KNullDesC);
1.212 +
1.213 + /**
1.214 + * Creates from a resource and returns a new navigation decorator object
1.215 + * containing help text.
1.216 + * The ownership of the object is transferred to the application.
1.217 + *
1.218 + * @param aReader Resource reader.
1.219 + * @return Navigation decorator object that contains message label
1.220 + * (=hint text).
1.221 + */
1.222 + IMPORT_C CAknNavigationDecorator* CreateMessageLabelL(
1.223 + TResourceReader& aReader);
1.224 +
1.225 + /**
1.226 + * Creates volume control indicator to the navi pane.
1.227 + * The ownership of the object is transferred to the application.
1.228 + *
1.229 + * @param aResourceId Resource file id for the volume control
1.230 + * @return Navigation decorator object that contains volume indicator.
1.231 + *
1.232 + * @deprecated Navi pane volume control is not supported anymore.
1.233 + */
1.234 + IMPORT_C CAknNavigationDecorator* CreateVolumeIndicatorL(TInt aResourceId);
1.235 +
1.236 + /**
1.237 + * Creates editor indicator container control to the navi pane.
1.238 + * The ownership of the object is transferred to the application.
1.239 + *
1.240 + * @return Navigation decorator object that contains editor indicator
1.241 + * container.
1.242 + */
1.243 + IMPORT_C CAknNavigationDecorator* CreateEditorIndicatorContainerL();
1.244 +
1.245 + /**
1.246 + * Pushes default content (empty navigation pane) to the navigation pane's
1.247 + * object stack.
1.248 + * This operation also draws default content to the navigation pane.
1.249 + *
1.250 + * @param aAllowDuplicates If this is @c ETrue, duplicate default
1.251 + * navi pane contents are allowed.
1.252 + */
1.253 + IMPORT_C void PushDefaultL( TBool aAllowDuplicates = EFalse );
1.254 +
1.255 + /**
1.256 + * Pushes a navigation decorator object to the navigation pane's object
1.257 + * stack.
1.258 + * This operation also draws the control to the navigation pane. An object
1.259 + * can be on the stack only once. If the object already exists in the stack
1.260 + * it is moved to topmost object. Ownership is not transfered.
1.261 + * Editor indicator control has priority over others. It is always at the
1.262 + * top if it exists. In this case all other controls are pushed under
1.263 + * the editor indicator object.
1.264 + *
1.265 + * @param aNaviPaneControl Object to be added at the top of the stack.
1.266 + */
1.267 + IMPORT_C void PushL( CAknNavigationDecorator& aNaviPaneControl );
1.268 +
1.269 + /**
1.270 + * Pops topmost object from the navigation pane's object stack. If editor
1.271 + * indicator control is topmost, it is not popped. The next control
1.272 + * is popped instead.
1.273 + * It is not possible to pop editor indicator object with this method.
1.274 + * Use @c Pop(CAknNavigationDecorator* aControl) or @c delete(aControl)
1.275 + * instead if editor indicator control is needed to be popped.
1.276 + */
1.277 + IMPORT_C void Pop();
1.278 +
1.279 + /**
1.280 + * Pops (remove) certain object from the navigation pane's object stack.
1.281 + * The removed object does not need to be topmost.
1.282 + *
1.283 + * @param aControl Object to be removed from the stack.
1.284 + */
1.285 + IMPORT_C void Pop( CAknNavigationDecorator* aControl );
1.286 +
1.287 + /**
1.288 + * Returns topmost object from navigation pane's object stack.
1.289 + * Editor indicator object is transparent for this operation. If editor
1.290 + * indicators exist on the navi pane, next object on the stack is returned.
1.291 + *
1.292 + * @return Navigation decorator object that is topmost in navigation pane's
1.293 + * object stack.
1.294 + */
1.295 + IMPORT_C CAknNavigationDecorator* Top();
1.296 +
1.297 + /**
1.298 + * Return topmost object from navigation pane's object stack.
1.299 + * FEP Editor indicator object is transparent or visible for this operation
1.300 + * depending on the given parameter value. If editor indicator object is to
1.301 + * be ignored and it exist on the navi pane, next object on the stack is
1.302 + * returned. Note that generally FEP does all the needed visibility etc.
1.303 + * handling for FEP editor indicators, so by default applications should
1.304 + * ignore FEP editor indicators.
1.305 + *
1.306 + * @since 3.1
1.307 + * @param aIgnoreFepEditorIndicator Tells if editor indicator
1.308 + * object is ignored.
1.309 + *
1.310 + * @return Navigation decorator object that is topmost in
1.311 + * navigation pane's object stack.
1.312 + */
1.313 + IMPORT_C CAknNavigationDecorator* Top(TBool aIgnoreFepEditorIndicator) const;
1.314 +
1.315 +
1.316 + /**
1.317 + * Replaces existing navigation decorator object in the navigation pane's
1.318 + * object stack. Any object can be on the stack only once. If the
1.319 + * replacement object already exists in the stack, previous copy is
1.320 + * removed from the stack. Ownership is not transfered.
1.321 + * Navi pane is redrawn if top item is changed.
1.322 + *
1.323 + * @param aToBeReplaced An object to be replaced.
1.324 + * @param aReplacement An object that is put to the stack instead.
1.325 + * @return Error number. @c KErrNone if the operation succeeds.
1.326 + * @c KErrNotFound if @c 'aToBeReplaced' object cannot be
1.327 + * found from the stack.
1.328 + */
1.329 + IMPORT_C TInt ReplaceL( CAknNavigationDecorator& aToBeReplaced,
1.330 + CAknNavigationDecorator& aReplacement );
1.331 +
1.332 + /**
1.333 + * Returns the object constructed from resources with
1.334 + * @c ConstrucFromResourcesL() -method to the application.
1.335 + * Ownership of the object is transferred to the application.
1.336 + *
1.337 + * @return Navigation Decorator object that was
1.338 + * created from resources.
1.339 + */
1.340 + IMPORT_C CAknNavigationDecorator* ResourceDecorator();
1.341 +
1.342 + /**
1.343 + * This non-exported method returns reference to navi arrow bitmaps.
1.344 + *
1.345 + * @param aId Id of the bitmap.
1.346 + * @return Reference to the navi arrow bitmap.
1.347 + */
1.348 + CFbsBitmap& NaviArrowBitmap( TInt aId );
1.349 +
1.350 +public:
1.351 +
1.352 + /**
1.353 + * This method can be used to set preferred layout style for navi decorator
1.354 + * objects that are pushed into navistack.
1.355 + * Given layout is applied to objects only if that object supports it and
1.356 + * status pane layout allows that mode to be used.
1.357 + *
1.358 + * @since 3.1
1.359 + *
1.360 + * @param aLayoutStyle CAknNavigationDecorator::ENaviControlLayoutNormal,
1.361 + * CAknNavigationDecorator::ENaviControlLayoutNarrow or
1.362 + * CAknNavigationDecorator::ENaviControlLayoutWide
1.363 + *
1.364 + */
1.365 + IMPORT_C void SetPreferredNaviDecoratorLayoutStyle( TInt aLayoutStyle );
1.366 +
1.367 + /**
1.368 + * Static method to return current color scheme.
1.369 + * @return Current color scheme value.
1.370 + */
1.371 + IMPORT_C static TInt ColorScheme();
1.372 +
1.373 + /**
1.374 + * Used by the UI framework. Notifies context and signal
1.375 + * panes wheter navi wipe graphichs is to be drawn or not.
1.376 + */
1.377 + void NotifyNaviWipeStatusL();
1.378 +
1.379 + /**
1.380 + * Gets current wipe bitmap for navi pane.
1.381 + *
1.382 + * @return Wipe bitmap Id
1.383 + */
1.384 + static TInt CurrentNaviWipeBitmap();
1.385 +
1.386 + /**
1.387 + * From @c CCoeControl.
1.388 + *
1.389 + * Handles pointer events
1.390 + *
1.391 + * @param aPointerEvent The pointer event.
1.392 + */
1.393 + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.394 +
1.395 + /**
1.396 + * Used to notify the navi pane when it goes to background.
1.397 + * @internal Used by the UI framework.
1.398 + */
1.399 + void HandleLosingForeground();
1.400 +
1.401 + /**
1.402 + * Used to notify the navi pane when it gains foreground.
1.403 + * @internal Used by the UI framework.
1.404 + */
1.405 + void HandleGainingForegroundL();
1.406 +
1.407 +protected: // from CCoeControl
1.408 +
1.409 + /**
1.410 + * From @c CCoeControl.
1.411 + *
1.412 + * Handles the size change events.
1.413 + */
1.414 + IMPORT_C virtual void SizeChanged();
1.415 +
1.416 + /**
1.417 + * From @c CCoeControl.
1.418 + *
1.419 + * Handles a change to the control's resources of type @c aType
1.420 + * which are shared across the environment, e.g. color scheme change.
1.421 + *
1.422 + * @param aType Event type.
1.423 + */
1.424 + IMPORT_C virtual void HandleResourceChange(TInt aType);
1.425 +
1.426 + /**
1.427 + * From @c CCoeControl.
1.428 + *
1.429 + * Returns number of controls inside the context pane control.
1.430 + *
1.431 + * @return Number of component controls.
1.432 + */
1.433 + IMPORT_C virtual TInt CountComponentControls() const;
1.434 +
1.435 + /**
1.436 + * From @c CCoeControl.
1.437 + *
1.438 + * Returns a control determined by control id.
1.439 + *
1.440 + * @param aIndex Index of a control to be returned.
1.441 + * @return Pointer to control.
1.442 + */
1.443 + IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const;
1.444 +
1.445 +protected: // from MCoeControlObserver
1.446 +
1.447 + /**
1.448 + * From @c MCoeControlObserver.
1.449 + *
1.450 + * Handles Control event.
1.451 + *
1.452 + * @param aControl Control that caused the event.
1.453 + * @param aEventType Type of the event.
1.454 + */
1.455 + IMPORT_C void HandleControlEventL(CCoeControl* aControl,
1.456 + TCoeEvent aEventType);
1.457 +
1.458 +private: // from CCoeControl
1.459 +
1.460 + IMPORT_C virtual void Draw(const TRect& aRect) const;
1.461 +
1.462 +private:
1.463 +
1.464 + /**
1.465 + * From CAknControl
1.466 + */
1.467 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.468 +
1.469 +public:
1.470 +
1.471 + /**
1.472 + * Not used / implemented
1.473 + *
1.474 + * @deprecated
1.475 + *
1.476 + * @since S60 3.0
1.477 + *
1.478 + * @return @c EFalse
1.479 + */
1.480 + TBool NaviWipeUsed() const;
1.481 +
1.482 + /**
1.483 + * Gets navi bitmap.
1.484 + *
1.485 + * @return Bitmap's colour.
1.486 + */
1.487 + CFbsBitmap* NaviColorBitmap() const;
1.488 +
1.489 + /**
1.490 + * Not used / implemented
1.491 + *
1.492 + * @deprecated
1.493 + *
1.494 + * @since S60 3.0
1.495 + */
1.496 + static void SetBackgroundContextAttributes( CCoeControl* aControl,
1.497 + TBool aNaviWipeUsed );
1.498 +
1.499 +private:
1.500 + TBool IsFepOwnedEditorIndicatorControl(
1.501 + CAknNavigationDecorator* aDecorator ) const;
1.502 +
1.503 + void HandleVisibilityOfNonFepOwnedIndicatorControl(
1.504 + CAknNavigationDecorator* aDecorator, TBool aVisible);
1.505 +
1.506 + /**
1.507 + * Checks wheter default navi wipe bitmap can be drawn to navipane and draws
1.508 + * it if it is possible.
1.509 + *
1.510 + * @since S60 2.6
1.511 + * @param aGc Used graphics context.
1.512 + * @param aRect Rect of the navipane.
1.513 + * @return @c ETrue if draw operation was done, otherwise @c EFalse.
1.514 + *
1.515 + */
1.516 + TBool DrawDefaultNaviWipe(CWindowGc& aGc, const TRect& aRect) const;
1.517 +
1.518 + /**
1.519 + * Checks wheter default navi solid bitmap can be drawn to navipane and draws
1.520 + * it if it is possible.
1.521 + *
1.522 + * @since S60 2.6
1.523 + * @param aGc Used graphics context.
1.524 + * @param aRect Rect of the navipane.
1.525 + * @return ETrue if draw operation was done, otherwise EFalse.
1.526 + *
1.527 + */
1.528 + TBool DrawDefaultNaviSolid(CWindowGc& aGc, const TRect& aRect) const;
1.529 +
1.530 + /**
1.531 + * Checks wheter skinned navi wipe bitmap can be drawn to navipane and draws
1.532 + * it if it is possible. Also skinned background bitmap is drawn.
1.533 + *
1.534 + * @since S60 2.6
1.535 + * @param aGc Used graphics context.
1.536 + * @param aRect Rect of the navipane.
1.537 + * @param aSkin Used skin instance.
1.538 + * @param aCc Used skin control context.
1.539 + * @return ETrue if draw operation was done, otherwise EFalse.
1.540 + */
1.541 + TBool DrawSkinnedNaviWipe( CWindowGc& aGc,
1.542 + const TRect& aRect,
1.543 + MAknsSkinInstance* aSkin,
1.544 + MAknsControlContext* aCc ) const;
1.545 +
1.546 + /**
1.547 + * Checks wheter skinned navi solid bitmap can be drawn to navipane and draws
1.548 + * it if it is possible. Also skinned background bitmap is drawn.
1.549 + *
1.550 + * @since S60 2.6
1.551 + * @param aGc Used graphics context.
1.552 + * @param aRect Rect of the navipane.
1.553 + * @param aSkin Used skin instance.
1.554 + * @param aCc Used skin control context.
1.555 + * @return ETrue if draw operation was done, otherwise EFalse.
1.556 + */
1.557 + TBool DrawSkinnedNaviSolid( CWindowGc& aGc,
1.558 + const TRect& aRect,
1.559 + MAknsSkinInstance* aSkin,
1.560 + MAknsControlContext* aCc ) const;
1.561 +
1.562 + /**
1.563 + * Loads a color bitmap for CAknNavigationDecorator.
1.564 + * @since S60 2.8
1.565 + */
1.566 + void LoadNaviColorBitmapL();
1.567 +
1.568 + void SetContainerWindowNonFading( TBool aNonFading );
1.569 +
1.570 + TRect VolumePopupRect();
1.571 +
1.572 +protected: // from CCoeControl
1.573 +
1.574 + /**
1.575 + * From @c CCoeControl.
1.576 + *
1.577 + * Retrieves an object of the same type as that encapsulated in aId.
1.578 + *
1.579 + * This function is used to allow controls to ask their owners for
1.580 + * access to other objects that they own.
1.581 + *
1.582 + * Other than in the case where NULL is returned, the object returned
1.583 + * must be of the same object type - that is, the @c ETypeId member of
1.584 + * the object pointed to by the pointer returned by this function must
1.585 + * be equal to the @c iUid member of @c aId.
1.586 + *
1.587 + * @param aId An encapsulated object type ID.
1.588 + * @return Encapsulated pointer to the provided object.
1.589 + * Note that the encapsulated pointer may be NULL.
1.590 + */
1.591 + TTypeUid::Ptr MopSupplyObject( TTypeUid aId );
1.592 +
1.593 +private:
1.594 +
1.595 + CEikStatusPaneBase* iStatusPane;
1.596 +
1.597 + CAknNavigationDecorator* iNaviDecoratorFromResource;
1.598 +
1.599 + typedef CArrayPtrFlat<CAknNavigationDecorator> CAknNaviPaneStack;
1.600 + CAknNaviPaneStack* iNaviPaneControls;
1.601 +
1.602 + CFbsBitmap* iNaviArrowBitmap[4];
1.603 +
1.604 + TInt iSpare;
1.605 + CAknNavigationControlContainerExtension* iExtension;
1.606 + };
1.607 +
1.608 +#endif // C_AKNNAVI_H