1 /*

     2 * Copyright (c) 2009 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:  Discreet popup

    15 *

    16 */

    17 

    18 #ifndef C_AKNDISCREETPOPUP_H

    19 #define C_AKNDISCREETPOPUP_H

    20 

    21 

    22 #include <coemain.h>

    23 #include <AknsConstants.h>

    24 #include <coecobs.h>

    25 

    26 class CAknDiscreetPopupControl;

    27 class MEikCommandObserver;

    28 class CGulIcon;

    29 class CAknDiscreetPopupServerHandler;

    30 

    31 /**

    32  * Discreet popup is used for notifying user of system generated or user 

    33  * activated events without blocking the flow of usage.

    34  *

    35  * The popup duration can be

    36  * 1) Short (by default). It is used when the user can expect a note to appear,

    37  * like confirmations, and when the nature of the message is positive,

    38  * i.e. the attempted operation was successful. The duration is 1.5 seconds.

    39  * 2) Long (KAknDiscreetPopupDurationLong flag). It is used when the note may 

    40  * appear spontaneously, i.e. without user action, or if the message content 

    41  * is not what the user probably expected (e.g. an error). 

    42  * The duration is 3.0 seconds. 

    43  *

    44  * @lib avkon

    45  * @since S60 v5.2

    46  */

    47 NONSHARABLE_CLASS( CAknDiscreetPopup ) : public CCoeStatic,

    48                                          public MCoeControlObserver

    49     {

    50 

    51 public:

    52 

    53     /**

    54      * Destructor.

    55      */

    56     ~CAknDiscreetPopup();

    57 

    58     /**

    59      * Displays a local discreet popup which is created according 

    60      * to given parameters.Local discreet popup is an application-specific 

    61      * discreet popup that is visible when the parent application is active 

    62      * and visible. 

    63      *

    64      * Title text is the only compulsory parameter.

    65      * Icon can be provided either

    66      * 1) By providing CGulIcon object with aIcon parameter or

    67      * 2) By providing icon skin id and bitmap file information.

    68      * If CGulIcon object is provided, skin and bitmap information is ignored.

    69      * Popup can inform its command observer that it has been tapped 

    70      * through MEikCommandObserver interface.

    71      *

    72      * Possible discreet popup flags are:

    73      * 

    74      * KAknDiscreetPopupDurationLong for long discreet popup duration.

    75      * Default duration is short.

    76      * 

    77      * KAknDiscreetPopupConfirmationTone - popup plays the confirmation tone.

    78      * KAknDiscreetPopupWarningTone - popup plays the warning tone.

    79      * KAknDiscreetPopupErrorTone - popup plays the error tone.

    80      * By default no tone is played.

    81      * 

    82      * @since S60 v5.2

    83      * @param aTitle First line of text. 

    84      * @param aText Second line of text.

    85      * @param aIcon Icon.

    86      * @param aSkinId Icon skin item id.

    87      * @param aBitmapFile Icon bitmap file.

    88      * @param aBitmapId Icon bitmap id.

    89      * @param aMaskId Icon mask id.

    90      * @param aFlags Popup flags.

    91      * @param aCommand Popup command id.

    92      * @param aCommandObserver Popup command observer.

    93      * @return Unique id for popup. 

    94      * @panic EAknPanicNotSupported The method is called from application

    95      * without existing CCoeEnv.

    96      */

    97     IMPORT_C static TInt ShowLocalPopupL( 

    98         const TDesC& aTitle, 

    99         const TDesC& aText = KNullDesC, 

   100         CGulIcon* aIcon = NULL, 

   101         const TAknsItemID& aSkinId = KAknsIIDNone,

   102         const TDesC& aBitmapFile = KNullDesC,

   103         const TInt aBitmapId = 0,

   104         const TInt aMaskId = 0,

   105         const TInt aFlags = 0, 

   106         const TInt aCommand = 0, 

   107         MEikCommandObserver* aCommandObserver = NULL );

   108 

   109     /**

   110      * Displays a local discreet popup which is created according 

   111      * to given resource id.Local discreet popup is an application-specific

   112      * discreet popup that is visible when the parent application is active 

   113      * and visible. 

   114      *

   115      * Popup can inform its command observer that it has been tapped 

   116      * through MEikCommandObserver interface.

   117      * 

   118      * @param aResourceId Discreet popup resource id.

   119      * @param aCommand Popup command id.

   120      * @param aCommandObserver Popup command observer.

   121      * @return Unique id for popup. 

   122      * @panic EAknPanicNotSupported The method is called from application

   123      * without existing CCoeEnv.

   124      */

   125     IMPORT_C static TInt ShowLocalPopupL( 

   126         const TInt aResourceId, 

   127         const TInt aCommand = 0, 

   128         MEikCommandObserver* aCommandObserver = NULL );

   129 

   130     /**

   131      * Displays a global discreet popup which is created according 

   132      * to given parameters. Global discreet notifications remains 

   133      * visible when user navigates from application to another. 

   134      *

   135      * Title text is the only compulsory parameter.

   136      *

   137      * Possible discreet popup flags are:

   138      * 

   139      * KAknDiscreetPopupDurationLong for long discreet popup duration.

   140      * Default duration is short.

   141      * 

   142      * KAknDiscreetPopupConfirmationTone - popup plays the confirmation tone.

   143      * KAknDiscreetPopupWarningTone - popup plays the warning tone.

   144      * KAknDiscreetPopupErrorTone - popup plays the error tone.

   145      * By default no tone is played.

   146      * 

   147      * Note: If caller does not have an existing control environment (CCoeEnv),

   148      * CAknDiscreetPopup::InitL should be called to initialize discreet popup

   149      * before calling this method. In addition, CAknDiscreetPopup::Release

   150      * should be called when there is no need for discreet popup anymore.

   151      * Otherwise all allocated resources will not be freed.

   152      *

   153      * @since S60 v5.2

   154      * @param aTitle First line of text. 

   155      * @param aText Second line of text.

   156      * @param aSkinId Icon skin item id.

   157      * @param aBitmapFile Icon bitmap file.

   158      * @param aBitmapId Icon bitmap id.

   159      * @param aMaskId Icon mask id.

   160      * @param aFlags Popup flags.

   161      * @param aCommand Popup command id.

   162      * @param aCommandObserver Popup command observer.

   163      * @param aAppUid Application uid to be launched.

   164      * @param aViewUid Application view uid to be activated.

   165      * @return Unique id for popup. 

   166      */

   167     IMPORT_C static TInt ShowGlobalPopupL( 

   168         const TDesC& aTitle, 

   169         const TDesC& aText = KNullDesC, 

   170         const TAknsItemID& aSkinId = KAknsIIDNone,

   171         const TDesC& aBitmapFile = KNullDesC,

   172         const TInt aBitmapId = 0,

   173         const TInt aMaskId = 0,

   174         const TInt aFlags = 0,

   175         const TInt aCommandId = 0,

   176         MEikCommandObserver* aCommandObserver = NULL,

   177         const TUid& aAppUid = TUid::Null(),

   178         const TUid& aViewUid = TUid::Null() );

   179 

   180     /**

   181      * Displays a global discreet popup which is created according 

   182      * to given resource id. Global discreet notifications remains 

   183      * visible when user navigates from application to another.

   184      * 

   185      * Note: If caller does not have an existing control environment (CCoeEnv),

   186      * CAknDiscreetPopup::InitL should be called to initialize discreet popup

   187      * before calling this method. In addition, CAknDiscreetPopup::Release

   188      * should be called when there is no need for discreet popup anymore.

   189      * Otherwise all allocated resources will not be freed.

   190      *

   191      * @since S60 v5.2

   192      * @param aResourceId Discreet popup resource id.

   193      * @param aResourceFile Discreet popup resource file path.

   194      * @param aCommand Popup command id.

   195      * @param aCommandObserver Popup command observer.

   196      * @param aAppUid Application uid to be launched.

   197      * @param aViewUid Application view uid to be activated.

   198      * @return Unique id for popup. 

   199      */

   200     IMPORT_C static TInt ShowGlobalPopupL( 

   201         const TInt aResourceId,

   202         const TDesC& aResourceFile,

   203         const TInt aCommandId = 0,

   204         MEikCommandObserver* aCommandObserver = NULL,

   205         const TUid& aAppUid = TUid::Null(),

   206         const TUid& aViewUid = TUid::Null() );

   207 

   208     /**

   209      * Initializes discreet popup when discreet popup

   210      * is launched in application with no existing CCoeEnv.

   211      * Note: This method is intended only for usage of those applications

   212      * that do not have an existing control environment (CCoeEnv) and should

   213 	 * be called only once.

   214      * 

   215      * @panic EAknPanicNotSupported 

   216      * The method is called from application with existing CCoeEnv.

   217      */

   218     IMPORT_C static void InitL();

   219 

   220     /**

   221      * Releases discreet popup resources when discreet popup

   222      * is launched in application with no existing CCoeEnv.

   223      * Note: This method is intended only for usage of those applications

   224      * that do not have an existing control environment (CCoeEnv) and should

   225 	 * be called only once when the application terminates.

   226      * 

   227      * @panic EAknPanicNotSupported 

   228      * The method is called from application with existing CCoeEnv.

   229      */

   230     IMPORT_C static void Release();

   231 

   232 private:

   233 

   234     /**

   235      * C++ constructor.

   236      */

   237     CAknDiscreetPopup();

   238 

   239     /**

   240      * C++ constructor.

   241      */

   242     CAknDiscreetPopup( TBool aUseCoeEnv );

   243 

   244     /**

   245      * Symbian second-phase constructor.

   246      */

   247     void ConstructL();

   248 

   249     /**

   250      * Provides the discreet popup singleton.

   251      *

   252      * @return Discreet popup instance.

   253      */

   254     static CAknDiscreetPopup* InstanceL();

   255 

   256     /**

   257      * Launches the local popup.

   258      *

   259      * @param aTitle First line of text. 

   260      * @param aText Second line of text.

   261      * @param aIcon Icon.

   262      * @param aSkinId Icon skin item id.

   263      * @param aBitmapFile Icon bitmap file.

   264      * @param aBitmapId Icon bitmap id.

   265      * @param aMaskId Icon mask id.

   266      * @param aFlags Popup flags.

   267      * @param aCommand Popup command id.

   268      * @param aCommandObserver Popup command observer.

   269      * @return Unique id for popup. 

   270      */

   271     TInt DoShowLocalL( 

   272         const TDesC& aTitle, 

   273         const TDesC& aText, 

   274         CGulIcon* aIcon, 

   275         const TAknsItemID& aSkinId,

   276         const TDesC& aBitmapFile,

   277         const TInt& aBitmapId,

   278         const TInt& aMaskId,

   279         const TInt& aFlags, 

   280         const TInt& aCommand, 

   281         MEikCommandObserver* aCommandObserver );

   282 

   283     /**

   284      * Launches the local popup, if the queues are empty. 

   285      * If not, the popup is added to a queue.

   286      *

   287      * @param aResourceId Discreet popup resource id.

   288      * @param aCommand Popup command id.

   289      * @param aCommandObserver Popup command observer.

   290      * @return Unique id for popup.

   291      */

   292     TInt DoShowLocalL( 

   293         const TInt& aResourceId, 

   294         const TDesC& aResourceFile,

   295         const TInt& aCommand,

   296         MEikCommandObserver* aCommandObserver );

   297 

   298     /**

   299      * Launches the global popup.

   300      *

   301      * @param aTitle First line of text. 

   302      * @param aText Second line of text.

   303      * @param aSkinId Icon skin item id.

   304      * @param aBitmapFile Icon bitmap file.

   305      * @param aBitmapId Icon bitmap id.

   306      * @param aMaskId Icon mask id.

   307      * @param aFlags Popup flags.

   308      * @param aCommand Popup command id.

   309      * @param aCommandObserver Popup command observer.

   310      * @param aAppUid Application uid to be launched.

   311      * @param aViewUid Application view uid to be activated.

   312      * @return Unique id for popup.

   313      */

   314 

   315     TInt DoShowGlobalL( 

   316         const TDesC& aTitle, 

   317         const TDesC& aText, 

   318         const TAknsItemID& aSkinId,

   319         const TDesC& aBitmapFile,

   320         const TInt& aBitmapId,

   321         const TInt& aMaskId,

   322         const TInt& aFlags,

   323         const TInt& aCommandId,

   324         MEikCommandObserver* aCommandObserver,

   325         const TUid& aAppUid,

   326         const TUid& aViewUid );

   327 

   328     /**

   329      * Launches the global popup.

   330      *

   331      * @param aResourceId Discreet popup resource id.

   332      * @param aResourceFile Discreet popup resource file path.

   333      * @param aCommand Popup command id.

   334      * @param aCommandObserver Popup command observer.

   335      * @param aAppUid Application uid to be launched.

   336      * @param aViewUid Application view uid to be activated.

   337      * @return Unique id for popup.

   338      */

   339 

   340     TInt DoShowGlobalL(

   341         const TInt& aResourceId,

   342         const TDesC& aResourceFile,

   343         const TInt& aCommandId,

   344         MEikCommandObserver* aCommandObserver,

   345         const TUid& aAppUid,

   346         const TUid& aViewUid );

   347 

   348     /**

   349      * This method shows the created popup control.

   350      *

   351      * @param aControl Created popup control.

   352      */

   353     void ShowPopupL( CAknDiscreetPopupControl* aControl );

   354 

   355     /**

   356      * This method deletes the popup and removes it from 

   357      * CAknDiscreetPopup popup list.

   358      *

   359      * @param aControl Closed popup control.

   360      */

   361     void DeletePopup( CAknDiscreetPopupControl* aControl );

   362 

   363     /**

   364      * Returns next available popup id.

   365      * 

   366      * @return Next available popup id.

   367      */

   368     TInt NextPopupId();

   369 

   370     /**

   371      * Checks if popup id is already in use among local popups.

   372      * 

   373      * @return ETrue if popup id is already in use.

   374      */

   375     TBool PopupIdInUse( const TInt& aPopupId );

   376 

   377 // from base class MCoeControlObserver

   378 

   379     /**

   380      * Handles an event from an observed control.

   381      *

   382      * @param aControl The control that sent the event.

   383      * @param aEventType The event type. 

   384      */

   385     void HandleControlEventL( CCoeControl* aControl, TCoeEvent aEventType );

   386 

   387 private: // data

   388 

   389     /**

   390      * Local popup array.

   391      */

   392     RPointerArray<CAknDiscreetPopupControl> iLocalPopups;

   393     

   394     /**

   395      * Ui server handler.

   396      * Own. 

   397      */

   398     CAknDiscreetPopupServerHandler* iServerHandler;

   399 

   400     /**

   401      * ETrue if CoeEnv exists.

   402      */

   403     TBool iUseCoeEnv;

   404     };

   405 

   406 

   407 #endif // C_AKNDISCREETPOPUP_H