/*
* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Defines a common global note API meant to be
*               customised by each SW platform.
*
*/


#ifndef GLOBALNOTE_H
#define GLOBALNOTE_H

// INCLUDES
#include <e32base.h>

// CONSTANTS

// Available note types
enum TGlobalNoteType
    {
    EGlobalInformationNote  = 1,
    EGlobalWarningNote      = 2,
    EGlobalConfirmationNote = 3,
    EGlobalErrorNote        = 4,
    EGlobalWaitNote         = 5
    };

// Available note softkeys
enum TGlobalNoteSoftkey
    {
    // No sofkeys
    EGlobalNoteSoftkeyNone = 0,

    // Single button notes
    EGlobalNoteSoftkeyOk      = 1,
    EGlobalNoteSoftkeyExit    = 2,
    EGlobalNoteSoftkeyCancel  = 3,
    EGlobalNoteSoftkeyBack    = 4,
    EGlobalNoteSoftKeyClose   = 5,
    EGlobalNoteSoftKeyQuit    = 6,

    // Double button notes.
    EGlobalNoteSoftkeyOkCancel   = 1000,
    EGlobalNoteSoftkeyYesNo      = 1001,
    EGlobalNoteSoftkeyAnswerExit = 1002
    };


// Return values for asynchronous notes
enum TGlobalNoteResult
    {
    EGlobalNoteResultOk      = 1,
    EGlobalNoteResultExit    = 2,
    EGlobalNoteResultCancel  = 3,
    EGlobalNoteResultBack    = 4,
    EGlobalNoteResultClose   = 5,
    EGlobalNoteResultQuit    = 6,
    EGlobalNoteResultYes     = 7,
    EGlobalNoteResultNo      = 8,
    EGlobalNoteResultAnswer  = 9
    };

// FORWARD DECLARATIONS
class CGlobalNoteImpl;

// CLASS DECLARATION

/**
* Common global note adapter.
*
* Example usage of the API:
*
* Link your module against library commonadapter.lib
* Include header globalnote.h
*
* @code
*
*   _LIT( KNoteText, "Haaha..\nDoes this thing work at all" );
*   _LIT( KCancelText, "Cancelled" );
*
*   CGlobalNote* globalNote = CGlobalNote::NewLC();
*   globalNote->SetSoftkeys( EGlobalNoteSoftkeyOkCancel );
*   TRequestStatus status;
*   globalNote->ShowNoteL( status, EGlobalErrorNote, KNoteText );
*   User::WaitForRequest( status );
*   if ( status != KErrCancel )
*       {
*       TBuf<12> buf;
*       buf.AppendNum( status.Int() );
*       User::InfoPrint( buf );
*       }
*   else
*       {
*       User::InfoPrint( KCancelText );
*       }
*
*   CleanupStack::PopAndDestroy( globalNote );
*
* @endcode
*
* @lib commonadapter.lib
* @since 2.0
*/
NONSHARABLE_CLASS( CGlobalNote ) : public CBase
    {
public:

    /**
    *Two-phased constructors.
    */
    IMPORT_C static CGlobalNote* NewL();
    IMPORT_C static CGlobalNote* NewLC();

    /**
    * Destructor.
    */
    IMPORT_C ~CGlobalNote();

public: // New functions

    /**
    * Sets note softkeys.
    *
    * @since 2.0
    *
    * @param  aSoftKey  Softkey ID
    */
    IMPORT_C void SetSoftkeys( TGlobalNoteSoftkey aSoftkey );

    /**
    * Shows a global note. This call returns immediately.
    * Deleting @c CGlobalNote instance does not remove the
    * note after this call.
    *
    * @since 2.0
    *
    * @param  aType      Note type.
    * @param  aNoteText  Note text.
    *
    * @return  Note ID.
    */
    IMPORT_C TInt ShowNoteL( TGlobalNoteType aType, const TDesC& aNoteText );

    /**
    * Shows a global note. This call returns immediately.
    * Deleting @c CGlobalNote instance cancels the note after
    * this call. In this case, @c KErrCancel is returned in @c aStatus.
    *
    * @since 2.0
    *
    * @param  aStatus    After user has pressed a softkey, this returns the
    *                    corresponding @c TGlobalNoteResult code of
    *                    the pressed softkey.
    * @param  aType      Note type.
    * @param  aNoteText  Note text.
    *
    * @return  Note ID.
    */
    IMPORT_C TInt ShowNoteL( TRequestStatus& aStatus,
                             TGlobalNoteType aType,
                             const TDesC& aNoteText );

    /**
    * Cancels a started note by ID.
    *
    * @since 2.0
    *
    * @param  aNoteId  ID of the note to be canceled.
    */
    IMPORT_C void CancelNoteL( TInt aNoteId );

private:

    /**
    * C++ default constructor.
    */
    CGlobalNote();

    /**
    * Symbian 2nd-phase constructor.
    */
    void ConstructL();

private:

    /**
    * Pointer to separate implementation class.
    * Own.
    */
    CGlobalNoteImpl* iImpl;
    };

#endif // GLOBALNOTE_H