/*

* Copyright (c) 2002 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:  Declaration of Notepad Library APIs.

*

*/

#ifndef NPDAPI_H

#define NPDAPI_H

// INCLUDES

#include <e32base.h>

#include <charconv.h>

#include <ConeResLoader.h>

#include <f32file.h>

// CONSTANTS

const TInt KNotepadPseudoKeyIdForNewNote(-1);

// FORWARD DECLARATIONS

class CCoeEnv;

class CEikDialog;

class CNotepadModel;

class CNotepadTableModel;

class CPlainText;

// CLASS DECLARATION

/**

* APIs of Notepad library.

* CNotepadApi provides APIs for other modules.

*

* @lib NpdLib.lib

*/

class CNotepadApi : public CBase

    {

    public:

    	/* Enum for the status of the memos.

    	*  ENpdDataEdited : Data is edited in the Editor dialog of the opened memo.

    	*  ENpdDataDeleted : Data is deleted in the Editor dialog of the opened memo.

    	*  ENpdDataErased : Data is erased in the Editor dialog of the opened memo.*/

        enum 

            {

            ENpdDataEdited = 0,

            ENpdDataDeleted,        

            ENpdDataErased

            };

    public: // Constuctors and destructor

        /**

        * Constructor.

        * Add a resource file of NpdLib.

        *

        * @return constructed CNotepadApi object.

        */

        IMPORT_C static CNotepadApi* NewL();

        /**

        * Constructor, returned value is also kept on the CleanupStack.

        * Add a resource file of NpdLib.

        *

        * @return constructed CNotepadApi object.

        */

        IMPORT_C static CNotepadApi* NewLC();

        /**

        * Destructor.

        * Remove a resource file of NpdLib.

        */

        IMPORT_C virtual ~CNotepadApi();

    public: // API functions

        /**

        * Fetch a memo.

        *

        * No need for a pre-allocated buffer.

        * Return NULL if the popup list is canceled or there is no memo.

        * Caller owns the returned HBufC object.

        *

        * @param aTitle Optional title text.

        * @return fetched string, (NULL if canceled or no memo).

        */

        IMPORT_C static HBufC* FetchMemoL(

            const TDesC* aTitle = NULL);

        /**

        * Fetch a template.

        *

        * No need for a pre-allocated buffer.

        * Return NULL if the popup list is canceled or there is no template.

        * Caller owns the returned HBufC object.

        *

        * @param aTitle Optional title text.

        * @return fetched string, (NULL if canceled or no templates).

        */

        IMPORT_C static HBufC* FetchTemplateL(

            const TDesC* aTitle = NULL);

        /**

        * Execute MCE's "List of templates".

        *

        * @return CEikDialog's exit status.

        */

        IMPORT_C static TInt ExecTemplatesL();

        /**

        * Execute a file viewer dialog.

        *

        * @param aFileName text file to view.

        * @param aTitle  TitlePane string (if NULL, Title will be FileName).

        * @param aDoWait Use wait dialog if ETrue.

        * @param aGuessEncoding guess encoding if ETrue (ignore aEncoding).

        * @param aEncoding encoding of the File

        *   (default ISO-8859-1. This is ignored if aGuessEncoding is ETrue).

        * @return CEikDialog's exit status.

        */

        IMPORT_C static TInt ExecFileViewerL(

            const TDesC& aFileName, 

            const TDesC* aTitle = NULL,

            const TBool aDoWait = ETrue,

            TBool aGuessEncoding = EFalse,

            TUint aEncoding = KCharacterSetIdentifierIso88591);

        /**

        * Execute a file viewer dialog.

        *

        * @param aFile file handle.

        * @param aTitle  TitlePane string (if NULL, Title will be FileName).

        * @param aDoWait Use wait dialog if ETrue.

        * @param aGuessEncoding guess encoding if ETrue (ignore aEncoding).

        * @param aEncoding encoding of the File

        *   (default ISO-8859-1. This is ignored if aGuessEncoding is ETrue).

        * @return CEikDialog's exit status.

        */

        IMPORT_C static TInt ExecFileViewerL(

            RFile& aFile, 

            const TDesC* aTitle = NULL,

            const TBool aDoWait = ETrue,

            TBool aGuessEncoding = EFalse,

            TUint aEncoding = KCharacterSetIdentifierIso88591);

        /**

        * Save text as a memo.

        *

        * @param aText    memo text to save.

        */

        IMPORT_C static void AddContentL(const TDesC& aText);

        /**

        * Probe a memo (API for Pinboard).

        *

        * @param aKey a serial number of memo.

        * @return ETrue if exists, EFalse otherwise.

        */

        IMPORT_C static TBool ExistsMemoL(const TInt aKey);

        /**

        * Get number of templates.

        *

        * Return an error code (less than zero) if any trouble.

        *

        * @return number of templates. returns error code (less than zero)

        *     if any trouble.

        */

        IMPORT_C static TInt NumberOfTemplates();

        /**

        * Save contents of a specified file as a memo.

        *

        * @param aFileName the name of a file to be saved.

        */

        IMPORT_C static void SaveFileAsMemoL(const TDesC& aFileName);

        /**

        * Save contents of a specified file as a memo.

        *

        * @param aFile the file handle.

        */

        IMPORT_C static void SaveFileAsMemoL(RFile& aFile);

       	/**

        * Save contents of a specified file as a memo.

        *

        * @param aFileName the name of a file to be saved.

        * @param aEncoding The character encoding used in the file.

       	*/

        IMPORT_C static void SaveFileAsMemoL(const TDesC& aFileName, const TUint aEncoding);

       	/**

        * Save contents of a specified file as a memo.

        *

        * @param aFile the file handle.

        * @param aEncoding The character encoding used in the file.

       	*/

        IMPORT_C static void SaveFileAsMemoL(RFile& aFile, const TUint aEncoding);

        /**

        * Return internal Dialog object. (Internal to NpdLib)

        *

        * @internal 

        */

        IMPORT_C CEikDialog* Dialog();

        /**

        * Return internal Model object. (Internal to NpdLib)

        *

        */

        IMPORT_C CNotepadModel* Model();

        /**

        * Create CNotepadListDialog.

        *

        * @param aResId resource id of type NOTEPAD_LIST_DIALOG.

        */

        IMPORT_C void CreateListDialogL(TInt aResId);

        /**

        * Create CNotepadViewerDialog.

        *

        * @param aFileName filename to view.

        * @param aTitle title pane (if NULL, filename is used).

        * @param aDoWait create waiting dialog if ETrue.

        * @param aGuessEncoding guess encoding if ETrue (ignore aEncoding).

        * @param aEncoding encoding of the File

        *     (default ISO-8859-1. This is ignored if aGuessEncoding is ETrue).

        */

        IMPORT_C void CreateViewerDialogL(

            const TDesC& aFileName, 

            const TDesC* aTitle,

            const TBool aDoWait,

            TBool aGuessEncoding = EFalse,

            TUint aEncoding = KCharacterSetIdentifierIso88591);

        /**

        * Create CNotepadViewerDialog.

        *

        * @param aFile file handle.

        * @param aTitle title pane (if NULL, filename is used).

        * @param aDoWait create waiting dialog if ETrue.

        * @param aGuessEncoding guess encoding if ETrue (ignore aEncoding).

        * @param aEncoding encoding of the File

        *     (default ISO-8859-1. This is ignored if aGuessEncoding is ETrue).

        */

        IMPORT_C void CreateViewerDialogL(

            RFile& aFile, 

            const TDesC* aTitle,

            const TBool aDoWait,

            TBool aGuessEncoding = EFalse,

            TUint aEncoding = KCharacterSetIdentifierIso88591);

        /**

        * Create CNotepadViewerDialog.

        *

        * @param aDoWait create waiting dialog if ETrue.

        */

        IMPORT_C void CreateViewerDialogL(const TBool aDoWait);

        /**

        * Create CNotepadModel.

        *

        * @param aResId resource id of type NOTEPAD_MODEL.

        */

        IMPORT_C void CreateModelL(TInt aResId);

        /**

        * Probe a memo (API for Pinboard).

        * This method is more efficient than ExistsMemoL

        * when it is neccessary to probe many memos at a time.

        *

        * @param aKey a serial number of memo.

        * @return ETrue if exists, EFalse otherwise.

        */

        IMPORT_C TBool ProbeMemoL(const TInt aKey);

        /**

        * Execute text viewer dialog for read only text

        *

        * @param aText the text to be viewed. 

        * @param aTitle Title of the viewer dialog. If null, application default is used instead.

        * @param aDeleteConfirmationText Confirmation text shown if user chooses to delete the document

        * @return KErrNone or one of the global error codes. 

        */

        IMPORT_C static TInt ExecReadOnlyTextViewerL(

            const TDesC& aText, 

            const TDesC& aTitle = KNullDesC, 

            const TDesC& aDeleteConfirmationText = KNullDesC

            );

        /**

        * Execute text viewer dialog for editable text 

        *

        * @param aReturnStatus KErrGeneral (-1) if the text was deleted. KErrNone otherwise 

        * @param aText the text to be viewed

        * @param aTitle Title of the viewer dialog. If null, application default is used instead.

        * @param aDeleteConfirmationText Confirmation text shown if user chooses to delete the document

        * @return Pointer to modified text. Returns null if text was not edited.. 

        */

        IMPORT_C static HBufC* ExecTextViewerL(

            TInt& aReturnStatus, 

            const TDesC& aText, 

            const TDesC& aTitle = KNullDesC, 

            const TDesC& aDeleteConfirmationText = KNullDesC

            );

        /**

        * Execute text editor dialog 

        *

        * @param aReturnStatus KErrGeneral (-1) if document was deleted, KErrNone otherwise.

        * @param aText descriptor that holds the initial text. If null, editor starts empty

        * @param aTitle Title of the editor dialog. If null, application default is used instead.

        * @param aDeleteConfirmationText Confirmation text shown if user chooses to delete the document

        * @return pointer to modified text. 

        */

        IMPORT_C static HBufC* ExecTextEditorL(

            TInt& aReturnStatus,  

            const TDesC& aText = KNullDesC, 

            const TDesC& aTitle = KNullDesC, 

            const TDesC& aDeleteConfirmationText = KNullDesC

            );

    private: // Constructor

         /**

        * private c++ constructor.

        */

        CNotepadApi();

    private: // New functions

        /**

        * Creates text viewer dialog for editable text 

        *

        * @param aReturnStatus KErrGeneral (-1) if the text was deleted. KErrNone otherwise 

        * @param aReadOnly indicates whether text is readonly or editable 

        * @param aText the text to be viewed

        * @param aTitle Title of the viewer dialog. If null, application default is used instead.

        * @param aDeleteConfirmationText Confirmation text shown if user chooses to delete the document

        * @return Pointer to modified text. Returns null if text was not edited.. 

        */

        IMPORT_C void CreateTextViewerDialogL(

            HBufC **aContentPointer,

            TInt& aReturnStatus,

            TBool aReadOnly,

            const TDesC& aText, 

            const TDesC& aTitle = KNullDesC, 

            const TDesC& aDeleteConfirmationText = KNullDesC

            );

        /**

        * Creates text editor dialog 

        *

        * @param aReturnStatus KErrGeneral (-1) if document was deleted, KErrNone otherwise.

        * @param aText descriptor that holds the initial text. If null, editor starts empty

        * @param aTitle Title of the editor dialog. If null, application default is used instead.

        * @param aDeleteConfirmationText Confirmation text shown if user chooses to delete the document

        * @return pointer to modified text. 

        */

        IMPORT_C void CreateTextEditorDialogL(

            HBufC **aContentPointer,

            TInt& aReturnStatus,

            const TDesC& aText = KNullDesC, 

            const TDesC& aTitle = KNullDesC, 

            const TDesC& aDeleteConfirmationText = KNullDesC

            );

        /**

        * Show PopupList.

        *

        * @param aTitle title of popup list.

        * @param aModelResId resource id of type NOTEPAD_MODEL.

        * @param aPromptResId resource id of prompt text, which is used when

        *    aTitle is NULL.

        * @param aEmptyTextResId resource id of empty text.

        * @return fetched content, NULL if canceled or no entry.

        */

        HBufC* DoPopupListL(

            const TDesC* aTitle, 

            TInt aModelResId,

            TInt aPromptResId, 

            TInt aEmptyTextResId = 0 );

    private: // Reserved

        /**

        * Reserved API entry.

        * @internal

        */

        IMPORT_C virtual void CNotepadApi_Reserved();

        /**

        * Reserved API entry.

        * @internal

        */

        IMPORT_C static void CNotepadApi_Reserved_Static();

    private: // Data

        CCoeEnv* iEnv; // not own

        CEikDialog* iDialog; // not own

        CNotepadModel* iModel; // own

        RConeResourceLoader iResourceLoader;

    };

#endif // NPDAPI_H

// End of File