CommonAdapter/inc/GlobalNote.h
changeset 0 2f259fa3e83a
equal deleted inserted replaced
-1:000000000000 0:2f259fa3e83a
       
     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