1 aknindicatorcontainer.h

     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  A default control in the status pane's small indicator pane.

    15 *                Editor indicators uses also same control in the navigation

    16 *                pane and in queries.

    17 *

    18 */

    19 

    20 

    21 #ifndef AKNINDICATORCONTAINER_H

    22 #define AKNINDICATORCONTAINER_H

    23 

    24 //  INCLUDES

    25 #include <akncontrol.h>

    26 #include <eikspane.h>

    27 

    28 class CIncallStatusBubble;

    29 class CAknIndicator;

    30 class CAknIndicatorContainerExtension;

    31 class CAknPictographInterface;

    32 class MAknIndicatorObserver;

    33 

    34 /**

    35  * The default control in the status pane's small indicator pane.

    36  * This container is also used for the status indicators in navi pane and

    37  * for editor indicators in queries.

    38  */

    39 class CAknIndicatorContainer : public CAknControl, public MEikStatusPaneObserver

    40 	{

    41 friend class CAknIndicatorContainerExtension;

    42 friend class CAknIndicatorDataObserver;

    43 public:

    44 

    45     /**

    46     * Layout orientations of the indicator container.

    47     * These are used to specify how the indicators are laid

    48     * out inside the indicator container.

    49     */

    50     enum TLayoutOrientation

    51         {

    52         EVertical,  ///< Indicators are arranged vertically.

    53         EHorizontal ///< Indicators are arranged horizontally.

    54         };

    55 

    56     /** Alignment of the indicators. */

    57     enum TIndicatorAlignment

    58         {

    59         ELeft,   ///< Indicators are aligned on the left side.

    60         ERight   ///< Indicators are aligned on the right side.

    61         };

    62 

    63     /**

    64     * Context of the indicator container.

    65     * These are used to specify what type of status indicators

    66     * the indicator container contains.

    67     */

    68     enum TIndicatorContext

    69         {

    70         EUniversalIndicators = 0,   ///< Universal status indicators.

    71         ENaviPaneEditorIndicators,  ///< Editor indicators shown in navi pane.

    72         EQueryEditorIndicators,     ///< Editor indicators shown in queries.

    73         EFindIndicators             ///< Search field indicators.

    74         };

    75 

    76     /**

    77     * Position of a indicator.

    78     * These are used for invidual indicators to coarsely specify

    79     * where they are positioned inside the indicator container.

    80     */

    81     enum TIndicatorPosition

    82         {

    83         ELeftSide,  ///< Indicator positioned on the left side.

    84         ERightSide, ///< Indicator positioned on the right side.

    85         EMiddle     ///< Indicator positioned in the middle.

    86         };

    87 

    88     /** Additional flags that can be used for custom indicators. */

    89     enum TCustomIndicatorFlags

    90     	{

    91     	EMultiColorIndicator       = 0x1, ///< Indicator is multi-colored.

    92     	EIndicatorPositionInverted = 0x2  ///< Indicator's position is inverted.

    93     	};

    94 

    95     /** Layout modes of indicator container. */

    96     enum TLayoutMode

    97 		{

    98 		ELayoutModeUsual, ///< Used for universal indicators when not in idle.

    99 		ELayoutModeWide   ///< Used for navi pane indicators and universal indicators in idle.

   100 		};

   101 

   102 public:

   103 

   104     /**

   105     * Default constructor.

   106     * Creates an @c EUniversalIndicators object.

   107     */

   108     IMPORT_C CAknIndicatorContainer();

   109 

   110     /**

   111     * Constructor. Creates @c EUniversalIndicators, @c ENaviPaneEditorIndicators

   112     * or @c EQueryEditorIndicators object.

   113     *

   114     * @param  aIndicatorContext  Indicator container context.

   115     */

   116     IMPORT_C CAknIndicatorContainer( TInt aIndicatorContext );

   117 

   118     /**

   119     * Destructor.

   120     */

   121     IMPORT_C ~CAknIndicatorContainer();

   122 

   123     /**

   124     * Second-phase constructor.

   125     */

   126     IMPORT_C void ConstructL();

   127 

   128     /**

   129     * Sets indicator state. The state can be one of the following:

   130     *   - @c EAknIndicatorStateOff

   131     *

   132 	*   - @c EAknIndicatorStateOn

   133 	*

   134 	*   - @c EAknIndicatorStateAnimate

   135 	*

   136 	* Editor indicators do not support animation.

   137     *

   138     * @param  aIndicatorId  ID of the indicator to be modified.

   139     * @param  aState        A state to be set to the indicator.

   140     * @param  aDrawNow      A flag to indicate if the indicator

   141     *                       is redrawn with this call.

   142     */

   143     IMPORT_C void SetIndicatorState( TUid aIndicatorId,

   144                                      TInt aState,

   145                                      TBool aDrawNow = ETrue );

   146 

   147     /**

   148     * Return the current state of an indicator.

   149     *

   150     * @param  aIndicatorId  ID of the indicator.

   151     * @return Current state of the indicator.

   152     */

   153     IMPORT_C TInt IndicatorState( TUid aIndicatorId );

   154 

   155     /**

   156     * Sets value to the message length indicator

   157     * (@c EAknNaviPaneEditorIndicatorMessageLength).

   158     *

   159     * @param  aIndicatorId  ID of the indicator to be modified.

   160     * @param  aString       Value of the indicator.

   161     */

   162     IMPORT_C void SetIndicatorValueL( TUid aIndicatorId, const TDesC& aString );

   163 

   164     /**

   165     * Sets value to the incall status bubble indicator on the

   166     * top of the status pane.

   167     *

   168     * @param  aFlags  Mode of the bubble.

   169     */

   170     IMPORT_C void SetIncallBubbleFlags( const TInt& aFlags );

   171 

   172     /**

   173     * Constructs the object from resource.

   174     *

   175     * @param  aReader  Resource reader.

   176     */

   177     IMPORT_C void ConstructFromResourceL( TResourceReader& aReader );

   178 

   179     /**

   180     * Returns the context of the indicator container.

   181     *

   182     * @return Context of the indicator container.

   183     */

   184     IMPORT_C TInt IndicatorContext() const;

   185 

   186 

   187 public: // From base class @c MEikStatusPaneObserver.

   188 

   189     /**

   190     * The @c MEikStatusPaneObserver interface allows a status pane observer

   191     * to pick up changes in the size or position of the status pane.

   192     * Such events will be as a result of layout changes which

   193     * cause an actual change in the status pane rectangle.

   194     */

   195     IMPORT_C void HandleStatusPaneSizeChange();

   196 

   197 public: // From base class @c CCoeControl.

   198 

   199     /**

   200     * Handles pointer events.

   201     *

   202     * @param  aPointerEvent  The pointer event.

   203     */

   204     IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );

   205 

   206 protected: // From base class @c CCoeControl.

   207 

   208     /**

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

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

   211     * Responds fade events and fades incall status bubble window group.

   212     *

   213 	* @param  aType  Event type.

   214 	*/

   215    	IMPORT_C virtual void HandleResourceChange( TInt aType );

   216 

   217     /**

   218     * Handles size change events.

   219     */

   220     IMPORT_C virtual void SizeChanged();

   221 

   222     /**

   223     * Handles position change events.

   224     */

   225     IMPORT_C virtual void PositionChanged();

   226 

   227     /**

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

   229     *

   230     * @return Amount of component controls.

   231     */

   232     IMPORT_C virtual TInt CountComponentControls() const;

   233 

   234     /**

   235     * Returns a control determined by control index.

   236     *

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

   238     * @return Pointer to control

   239     */

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

   241 

   242 private: // From base class @c CCoeControl.

   243 

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

   245 

   246 private: // From base class @c CAknControl.

   247 

   248     IMPORT_C void* ExtensionInterface( TUid aInterface );

   249 

   250 private:

   251 

   252     virtual void Reserved_1();

   253     void PrioritizeIndicatorsL();

   254 

   255    	static TInt TickerCallback( TAny* aThis );

   256     TInt DoTick();

   257 

   258     void IncallBubbleSizeChanged( TBool aAllowIdleStateBubble );

   259 

   260     void SizeChangedInSmallStatusPane();

   261 

   262     void SizeChangedInNormalStatusPane();

   263 

   264     void SizeChangedInStaconPane();

   265 

   266     void SizeChangedInFlatStatusPane();

   267 

   268     void SizeChangedInExtendedStatusPane();

   269 

   270     void SizeChangedInIdleExtendedStatusPane();

   271 

   272 	void SizeChangedInIdleVertical();

   273 

   274     void SetContainerWindowNonFading( TBool aNonFading );

   275 

   276     void SetupIndicatorLayoutModes();

   277 

   278     TInt SelectIndicatorLayoutMode();

   279 

   280 	void CreateIndicatorFromPaneResourceL( TUid aUid,

   281 	                                       TInt aIndicatorPaneResourceId,

   282 	                                       TInt aCustomIndicatorFlags );

   283 

   284 	TBool IndicatorExists( TUid aUid ) const;

   285 

   286 	void CreateIncallBubbleL();

   287 

   288 	TBool UpdateSmallLayoutL();

   289 

   290 	void SetIncallBubbleDisabled( TBool aDisabled );

   291 

   292 	void ResetAnimTicker( TBool bForeground );

   293 

   294 public:

   295 

   296     /**

   297     * Sets value to the progress bar indicator

   298     * (@c EAknNaviPaneEditorIndicatorProgressBar).

   299     * Panics if the specified indicator is not a progress bar indicator.

   300     *

   301     * @since 2.1

   302     * @param  aIndicatorId  ID of the indicator to be modified.

   303     * @param  aValue        Current progress of the task that bar describes.

   304     * @param  aMaxValue     Progress value when task is finished.

   305     *

   306     */

   307     IMPORT_C void SetIndicatorValue( TUid aIndicatorId,

   308                                      TInt aValue,

   309                                      TInt aMaxValue );

   310 

   311     /**

   312     * Redraws those indicators that are visible and contain pictographs.

   313     */

   314     void DrawPictographArea();

   315 

   316     /**

   317     * Returns the pictograph interface owned by the indicator container,

   318     * or @c NULL if pictographs are not supported.

   319     */

   320     CAknPictographInterface* PictographInterface() const;

   321 

   322 

   323     /**

   324     * Sets whether incall bubble is shown also on the top of the idle

   325     * status pane. Normally it is shown only in usual statuspane layouts,

   326     * but with this method it can be set to shown also in idle.

   327     *

   328     * NOTE: This method works only if indicatorcontainer is used as container

   329     *       for universal indicators.

   330     *

   331     * @param  aAllowed  If true incall bubble is shown also in idle statuspane.

   332     *                   Otherwise bubble is shown only in usual statuspane

   333     *                   layouts.

   334     */

   335     IMPORT_C void SetIncallBubbleAllowedInIdle( TBool aAllowed );

   336 

   337     /**

   338     * Sets whether incall bubble is shown on the top of the usual status pane.

   339     * Normally it is shown in usual statuspane layouts, but with this

   340     * method it can prevent it to be shown.

   341     *

   342     * NOTE: This method works only if indicatorcontainer is used as

   343     *       container for universal indicators.

   344     *

   345     * @param  aAllowed  If true incall bubble is shown in usual statuspane.

   346     */

   347     IMPORT_C void SetIncallBubbleAllowedInUsual( TBool aAllowed );

   348 

   349 

   350     /**

   351     * Sets observer for given indicator.

   352     *

   353     * @param  aIndicatorObserver  Observer of the indicator.

   354     * @param  aIndicatorUid       UID of indicator to be observed.

   355     */

   356     IMPORT_C void SetIndicatorObserver( MAknIndicatorObserver* aIndicatorObserver,

   357                                         TUid aIndicatorUid );

   358 

   359     /**

   360     * Creates a custom indicator.

   361     * Indicators created with this method can be used in addition

   362     * to default indicators.

   363     *

   364     * @since 3.1

   365     *

   366     * @param  aIndicatorResourceId   Resource ID of INDICATOR struct to be used

   367     *                                in costructing indicator.

   368     *        	                     UID in the resource is ignored, a dynamic

   369     *                                UID is given to indicator and returned

   370     *                                to caller.

   371     * @param  aCustomIndicatorFlags  Flags that can be used to set additional

   372     *                                indicator properties.

   373     *                                  - @c EMultiColorIndicator:

   374     *                                       Indicator is shown as multicolor

   375     *                                       (default is 2-color).

   376     *                                  - @c EIndicatorPositionInverted:

   377     *                                       Indicator is aligned to the opposite

   378     *                                       side than default (default is right

   379     *                                       side). Note that this flag does not

   380     *                                       quarantee exact location for the

   381     *                                       indicator, indicators are shown in

   382     *                                       priority order and location may vary

   383     *                                       and look different in different layouts.

   384     *

   385     * @return UID of the new indicator.

   386     *

   387     */

   388 	IMPORT_C TUid CreateIndicatorFromResourceL( TInt aIndicatorResourceId,

   389 	                                            TInt aCustomIndicatorFlags );

   390 

   391 

   392     /**

   393     * Replaces the icon of the given indicator.

   394     *

   395     * @since 3.1

   396     * @param  aIndicator   UID of the indicator.

   397     * @param  aState       State which icon is replaced (@c EAknIndicatorStateOn

   398     *                      or @c EAknIndicatorStateAnimate)

   399     * @param  aLayoutMode  Layout mode of the icon to be replaced

   400     *                      (@c ELayoutModeUsual or @c ELayoutModeWide)

   401     * @param  aIconBitmap  Bitmap of the new icon. Ownership is transferred to

   402     *                      @c CAknIndicatorContainer.

   403     * @param  aIconMask    Mask of the new icon. Ownership is transferred to

   404     *                      @c CAknIndicatorContainer.

   405     * @param  aIconIndex   If parameter aState is @c EAknIndicatorStateAnimate,

   406     *                      then this parameter must contain the index of the

   407     *                      icon to be replaced in the animation sequence.

   408     *                      Old icon must exist for given index so that the

   409     *                      number of animation frames does not change.

   410     */

   411 	IMPORT_C void ReplaceIndicatorIconL( TUid aIndicator,

   412 	                                     TInt aState,

   413 	                                     TInt aLayoutMode,

   414 	                                     CFbsBitmap* aIconBitmap,

   415 	                                     CFbsBitmap* aIconMask,

   416 	                                     TInt aIconIndex = 0 );

   417 

   418 private:

   419 

   420     /** Array of the indicators. */

   421    	typedef CArrayPtrFlat<CAknIndicator> CAknIndicatorQueue;

   422     CAknIndicatorQueue* iIndicators;

   423 

   424     /** Layout orientations. */

   425     TLayoutOrientation iLayoutOrientation;

   426     TLayoutOrientation iPreviousLayoutOrientation;

   427 

   428     /** Alignment of the indicators. */

   429     TIndicatorAlignment iAlignment;

   430 

   431     /** Number of indicators shown. */

   432     TInt iIndicatorsShown;

   433 

   434     /** Number of animated indicators shown. */

   435     TInt iAnimatedIndicatorsShown;

   436 

   437     /** Extension class. */

   438     CAknIndicatorContainerExtension* iExtension;

   439 

   440     /** Context of the indicators. */

   441     TInt iIndicatorContext;

   442 

   443     /** Indicator animation timer. */

   444    	CPeriodic* iTicker;

   445 

   446    	/** Reserved for future use. */

   447     TBool iSpare2;

   448 

   449     /** Synchronization value used in the indicator animations. */

   450     TInt iSynchronizingValue;

   451 

   452     /** Small incall status bubble. */

   453     CIncallStatusBubble* iIncallBubble;

   454     };

   455 

   456 #endif // AKNINDICATORCONTAINER_H

   457 

   458 // End of File