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:  Defines a common global note API meant to be

    15 *               customised by each SW platform.

    16 *

    17 */

    18 

    19 

    20 #ifndef GLOBALNOTE_H

    21 #define GLOBALNOTE_H

    22 

    23 // INCLUDES

    24 #include <e32base.h>

    25 

    26 // CONSTANTS

    27 

    28 // Available note types

    29 enum TGlobalNoteType

    30     {

    31     EGlobalInformationNote  = 1,

    32     EGlobalWarningNote      = 2,

    33     EGlobalConfirmationNote = 3,

    34     EGlobalErrorNote        = 4,

    35     EGlobalWaitNote         = 5

    36     };

    37 

    38 // Available note softkeys

    39 enum TGlobalNoteSoftkey

    40     {

    41     // No sofkeys

    42     EGlobalNoteSoftkeyNone = 0,

    43 

    44     // Single button notes

    45     EGlobalNoteSoftkeyOk      = 1,

    46     EGlobalNoteSoftkeyExit    = 2,

    47     EGlobalNoteSoftkeyCancel  = 3,

    48     EGlobalNoteSoftkeyBack    = 4,

    49     EGlobalNoteSoftKeyClose   = 5,

    50     EGlobalNoteSoftKeyQuit    = 6,

    51 

    52     // Double button notes.

    53     EGlobalNoteSoftkeyOkCancel   = 1000,

    54     EGlobalNoteSoftkeyYesNo      = 1001,

    55     EGlobalNoteSoftkeyAnswerExit = 1002

    56     };

    57 

    58 

    59 // Return values for asynchronous notes

    60 enum TGlobalNoteResult

    61     {

    62     EGlobalNoteResultOk      = 1,

    63     EGlobalNoteResultExit    = 2,

    64     EGlobalNoteResultCancel  = 3,

    65     EGlobalNoteResultBack    = 4,

    66     EGlobalNoteResultClose   = 5,

    67     EGlobalNoteResultQuit    = 6,

    68     EGlobalNoteResultYes     = 7,

    69     EGlobalNoteResultNo      = 8,

    70     EGlobalNoteResultAnswer  = 9

    71     };

    72 

    73 // FORWARD DECLARATIONS

    74 class CGlobalNoteImpl;

    75 

    76 // CLASS DECLARATION

    77 

    78 /**

    79 * Common global note adapter.

    80 *

    81 * Example usage of the API:

    82 *

    83 * Link your module against library commonadapter.lib

    84 * Include header globalnote.h

    85 *

    86 * @code

    87 *

    88 *   _LIT( KNoteText, "Haaha..\nDoes this thing work at all" );

    89 *   _LIT( KCancelText, "Cancelled" );

    90 *

    91 *   CGlobalNote* globalNote = CGlobalNote::NewLC();

    92 *   globalNote->SetSoftkeys( EGlobalNoteSoftkeyOkCancel );

    93 *   TRequestStatus status;

    94 *   globalNote->ShowNoteL( status, EGlobalErrorNote, KNoteText );

    95 *   User::WaitForRequest( status );

    96 *   if ( status != KErrCancel )

    97 *       {

    98 *       TBuf<12> buf;

    99 *       buf.AppendNum( status.Int() );

   100 *       User::InfoPrint( buf );

   101 *       }

   102 *   else

   103 *       {

   104 *       User::InfoPrint( KCancelText );

   105 *       }

   106 *

   107 *   CleanupStack::PopAndDestroy( globalNote );

   108 *

   109 * @endcode

   110 *

   111 * @lib commonadapter.lib

   112 * @since 2.0

   113 */

   114 NONSHARABLE_CLASS( CGlobalNote ) : public CBase

   115     {

   116 public:

   117 

   118     /**

   119     *Two-phased constructors.

   120     */

   121     IMPORT_C static CGlobalNote* NewL();

   122     IMPORT_C static CGlobalNote* NewLC();

   123 

   124     /**

   125     * Destructor.

   126     */

   127     IMPORT_C ~CGlobalNote();

   128 

   129 public: // New functions

   130 

   131     /**

   132     * Sets note softkeys.

   133     *

   134     * @since 2.0

   135     *

   136     * @param  aSoftKey  Softkey ID

   137     */

   138     IMPORT_C void SetSoftkeys( TGlobalNoteSoftkey aSoftkey );

   139 

   140     /**

   141     * Shows a global note. This call returns immediately.

   142     * Deleting @c CGlobalNote instance does not remove the

   143     * note after this call.

   144     *

   145     * @since 2.0

   146     *

   147     * @param  aType      Note type.

   148     * @param  aNoteText  Note text.

   149     *

   150     * @return  Note ID.

   151     */

   152     IMPORT_C TInt ShowNoteL( TGlobalNoteType aType, const TDesC& aNoteText );

   153 

   154     /**

   155     * Shows a global note. This call returns immediately.

   156     * Deleting @c CGlobalNote instance cancels the note after

   157     * this call. In this case, @c KErrCancel is returned in @c aStatus.

   158     *

   159     * @since 2.0

   160     *

   161     * @param  aStatus    After user has pressed a softkey, this returns the

   162     *                    corresponding @c TGlobalNoteResult code of

   163     *                    the pressed softkey.

   164     * @param  aType      Note type.

   165     * @param  aNoteText  Note text.

   166     *

   167     * @return  Note ID.

   168     */

   169     IMPORT_C TInt ShowNoteL( TRequestStatus& aStatus,

   170                              TGlobalNoteType aType,

   171                              const TDesC& aNoteText );

   172 

   173     /**

   174     * Cancels a started note by ID.

   175     *

   176     * @since 2.0

   177     *

   178     * @param  aNoteId  ID of the note to be canceled.

   179     */

   180     IMPORT_C void CancelNoteL( TInt aNoteId );

   181 

   182 private:

   183 

   184     /**

   185     * C++ default constructor.

   186     */

   187     CGlobalNote();

   188 

   189     /**

   190     * Symbian 2nd-phase constructor.

   191     */

   192     void ConstructL();

   193 

   194 private:

   195 

   196     /**

   197     * Pointer to separate implementation class.

   198     * Own.

   199     */

   200     CGlobalNoteImpl* iImpl;

   201     };

   202 

   203 #endif // GLOBALNOTE_H