1 /*

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

    15 *

    16 */

    17 

    18 

    19 #ifndef NPDAPI_H

    20 #define NPDAPI_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 #include <charconv.h>

    25 #include <ConeResLoader.h>

    26 #include <f32file.h>

    27 

    28 // CONSTANTS

    29 const TInt KNotepadPseudoKeyIdForNewNote(-1);

    30 

    31 // FORWARD DECLARATIONS

    32 class CCoeEnv;

    33 class CEikDialog;

    34 class CNotepadModel;

    35 class CNotepadTableModel;

    36 class CPlainText;

    37 

    38 // CLASS DECLARATION

    39 /**

    40 * APIs of Notepad library.

    41 * CNotepadApi provides APIs for other modules.

    42 *

    43 * @lib NpdLib.lib

    44 */

    45 class CNotepadApi : public CBase

    46     {

    47     public:

    48     

    49     	/* Enum for the status of the memos.

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

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

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

    53         enum 

    54             {

    55             ENpdDataEdited = 0,

    56             ENpdDataDeleted,        

    57             ENpdDataErased

    58             };

    59 

    60     public: // Constuctors and destructor

    61 

    62         /**

    63         * Constructor.

    64         * Add a resource file of NpdLib.

    65         *

    66         * @return constructed CNotepadApi object.

    67         */

    68         IMPORT_C static CNotepadApi* NewL();

    69 

    70         /**

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

    72         * Add a resource file of NpdLib.

    73         *

    74         * @return constructed CNotepadApi object.

    75         */

    76         IMPORT_C static CNotepadApi* NewLC();

    77 

    78         /**

    79         * Destructor.

    80         * Remove a resource file of NpdLib.

    81         */

    82         IMPORT_C virtual ~CNotepadApi();

    83 

    84     public: // API functions

    85 

    86         /**

    87         * Fetch a memo.

    88         *

    89         * No need for a pre-allocated buffer.

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

    91         * Caller owns the returned HBufC object.

    92         *

    93         * @param aTitle Optional title text.

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

    95         */

    96         IMPORT_C static HBufC* FetchMemoL(

    97             const TDesC* aTitle = NULL);

    98 

    99         /**

   100         * Fetch a template.

   101         *

   102         * No need for a pre-allocated buffer.

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

   104         * Caller owns the returned HBufC object.

   105         *

   106         * @param aTitle Optional title text.

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

   108         */

   109         IMPORT_C static HBufC* FetchTemplateL(

   110             const TDesC* aTitle = NULL);

   111 

   112         /**

   113         * Execute MCE's "List of templates".

   114         *

   115         * @return CEikDialog's exit status.

   116         */

   117         IMPORT_C static TInt ExecTemplatesL();

   118 

   119         /**

   120         * Execute a file viewer dialog.

   121         *

   122         * @param aFileName text file to view.

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

   124         * @param aDoWait Use wait dialog if ETrue.

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

   126         * @param aEncoding encoding of the File

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

   128         * @return CEikDialog's exit status.

   129         */

   130         IMPORT_C static TInt ExecFileViewerL(

   131             const TDesC& aFileName, 

   132             const TDesC* aTitle = NULL,

   133             const TBool aDoWait = ETrue,

   134             TBool aGuessEncoding = EFalse,

   135             TUint aEncoding = KCharacterSetIdentifierIso88591);

   136 

   137         /**

   138         * Execute a file viewer dialog.

   139         *

   140         * @param aFile file handle.

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

   142         * @param aDoWait Use wait dialog if ETrue.

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

   144         * @param aEncoding encoding of the File

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

   146         * @return CEikDialog's exit status.

   147         */

   148         IMPORT_C static TInt ExecFileViewerL(

   149             RFile& aFile, 

   150             const TDesC* aTitle = NULL,

   151             const TBool aDoWait = ETrue,

   152             TBool aGuessEncoding = EFalse,

   153             TUint aEncoding = KCharacterSetIdentifierIso88591);

   154 

   155         /**

   156         * Save text as a memo.

   157         *

   158         * @param aText    memo text to save.

   159         */

   160         IMPORT_C static void AddContentL(const TDesC& aText);

   161 

   162         /**

   163         * Probe a memo (API for Pinboard).

   164         *

   165         * @param aKey a serial number of memo.

   166         * @return ETrue if exists, EFalse otherwise.

   167         */

   168         IMPORT_C static TBool ExistsMemoL(const TInt aKey);

   169 

   170         /**

   171         * Get number of templates.

   172         *

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

   174         *

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

   176         *     if any trouble.

   177         */

   178         IMPORT_C static TInt NumberOfTemplates();

   179 

   180         /**

   181         * Save contents of a specified file as a memo.

   182         *

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

   184         */

   185         IMPORT_C static void SaveFileAsMemoL(const TDesC& aFileName);

   186 

   187         /**

   188         * Save contents of a specified file as a memo.

   189         *

   190         * @param aFile the file handle.

   191         */

   192         IMPORT_C static void SaveFileAsMemoL(RFile& aFile);

   193 

   194        	/**

   195         * Save contents of a specified file as a memo.

   196         *

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

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

   199        	*/

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

   201 

   202        	/**

   203         * Save contents of a specified file as a memo.

   204         *

   205         * @param aFile the file handle.

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

   207        	*/

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

   209         

   210         /**

   211         * Return internal Dialog object. (Internal to NpdLib)

   212         *

   213         * @internal 

   214         */

   215         IMPORT_C CEikDialog* Dialog();

   216 

   217         /**

   218         * Return internal Model object. (Internal to NpdLib)

   219         *

   220         */

   221         IMPORT_C CNotepadModel* Model();

   222 

   223         /**

   224         * Create CNotepadListDialog.

   225         *

   226         * @param aResId resource id of type NOTEPAD_LIST_DIALOG.

   227         */

   228         IMPORT_C void CreateListDialogL(TInt aResId);

   229 

   230         /**

   231         * Create CNotepadViewerDialog.

   232         *

   233         * @param aFileName filename to view.

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

   235         * @param aDoWait create waiting dialog if ETrue.

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

   237         * @param aEncoding encoding of the File

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

   239         */

   240         IMPORT_C void CreateViewerDialogL(

   241             const TDesC& aFileName, 

   242             const TDesC* aTitle,

   243             const TBool aDoWait,

   244             TBool aGuessEncoding = EFalse,

   245             TUint aEncoding = KCharacterSetIdentifierIso88591);

   246 

   247         /**

   248         * Create CNotepadViewerDialog.

   249         *

   250         * @param aFile file handle.

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

   252         * @param aDoWait create waiting dialog if ETrue.

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

   254         * @param aEncoding encoding of the File

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

   256         */

   257         IMPORT_C void CreateViewerDialogL(

   258             RFile& aFile, 

   259             const TDesC* aTitle,

   260             const TBool aDoWait,

   261             TBool aGuessEncoding = EFalse,

   262             TUint aEncoding = KCharacterSetIdentifierIso88591);

   263 

   264         /**

   265         * Create CNotepadViewerDialog.

   266         *

   267         * @param aDoWait create waiting dialog if ETrue.

   268         */

   269         IMPORT_C void CreateViewerDialogL(const TBool aDoWait);

   270 

   271         /**

   272         * Create CNotepadModel.

   273         *

   274         * @param aResId resource id of type NOTEPAD_MODEL.

   275         */

   276         IMPORT_C void CreateModelL(TInt aResId);

   277 

   278         /**

   279         * Probe a memo (API for Pinboard).

   280         * This method is more efficient than ExistsMemoL

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

   282         *

   283         * @param aKey a serial number of memo.

   284         * @return ETrue if exists, EFalse otherwise.

   285         */

   286         IMPORT_C TBool ProbeMemoL(const TInt aKey);

   287 

   288         /**

   289         * Execute text viewer dialog for read only text

   290         *

   291         * @param aText the text to be viewed. 

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

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

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

   295         */

   296         IMPORT_C static TInt ExecReadOnlyTextViewerL(

   297             const TDesC& aText, 

   298             const TDesC& aTitle = KNullDesC, 

   299             const TDesC& aDeleteConfirmationText = KNullDesC

   300             );

   301 

   302         /**

   303         * Execute text viewer dialog for editable text 

   304         *

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

   306         * @param aText the text to be viewed

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

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

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

   310         */

   311         IMPORT_C static HBufC* ExecTextViewerL(

   312             TInt& aReturnStatus, 

   313             const TDesC& aText, 

   314             const TDesC& aTitle = KNullDesC, 

   315             const TDesC& aDeleteConfirmationText = KNullDesC

   316             );

   317 

   318         /**

   319         * Execute text editor dialog 

   320         *

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

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

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

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

   325         * @return pointer to modified text. 

   326         */

   327         IMPORT_C static HBufC* ExecTextEditorL(

   328             TInt& aReturnStatus,  

   329             const TDesC& aText = KNullDesC, 

   330             const TDesC& aTitle = KNullDesC, 

   331             const TDesC& aDeleteConfirmationText = KNullDesC

   332             );

   333 

   334     private: // Constructor

   335          /**

   336         * private c++ constructor.

   337         */

   338         CNotepadApi();

   339 

   340     private: // New functions

   341 

   342         /**

   343         * Creates text viewer dialog for editable text 

   344         *

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

   346         * @param aReadOnly indicates whether text is readonly or editable 

   347         * @param aText the text to be viewed

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

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

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

   351         */

   352         IMPORT_C void CreateTextViewerDialogL(

   353             HBufC **aContentPointer,

   354             TInt& aReturnStatus,

   355             TBool aReadOnly,

   356             const TDesC& aText, 

   357             const TDesC& aTitle = KNullDesC, 

   358             const TDesC& aDeleteConfirmationText = KNullDesC

   359             );

   360 

   361         /**

   362         * Creates text editor dialog 

   363         *

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

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

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

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

   368         * @return pointer to modified text. 

   369         */

   370         IMPORT_C void CreateTextEditorDialogL(

   371             HBufC **aContentPointer,

   372             TInt& aReturnStatus,

   373             const TDesC& aText = KNullDesC, 

   374             const TDesC& aTitle = KNullDesC, 

   375             const TDesC& aDeleteConfirmationText = KNullDesC

   376             );

   377 

   378         /**

   379         * Show PopupList.

   380         *

   381         * @param aTitle title of popup list.

   382         * @param aModelResId resource id of type NOTEPAD_MODEL.

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

   384         *    aTitle is NULL.

   385         * @param aEmptyTextResId resource id of empty text.

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

   387         */

   388         HBufC* DoPopupListL(

   389             const TDesC* aTitle, 

   390             TInt aModelResId,

   391             TInt aPromptResId, 

   392             TInt aEmptyTextResId = 0 );

   393 

   394     private: // Reserved

   395 

   396         /**

   397         * Reserved API entry.

   398         * @internal

   399         */

   400         IMPORT_C virtual void CNotepadApi_Reserved();

   401 

   402         /**

   403         * Reserved API entry.

   404         * @internal

   405         */

   406         IMPORT_C static void CNotepadApi_Reserved_Static();

   407 

   408     private: // Data

   409 

   410         CCoeEnv* iEnv; // not own

   411         CEikDialog* iDialog; // not own

   412         CNotepadModel* iModel; // own

   413         RConeResourceLoader iResourceLoader;

   414 

   415     };

   416 

   417 #endif // NPDAPI_H

   418 

   419 // End of File

   420