1 /*

     2 * Copyright (c) 2002-2006 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:  Dialog used to select target file or directory

    15 *

    16 */

    17 

    18 

    19 #ifndef CAKNFILESELECTIONDIALOG_H

    20 #define CAKNFILESELECTIONDIALOG_H

    21 

    22 // INCLUDES

    23 #include <CAknCommonDialogsBase.h>

    24 

    25 // FORWARD DECLARATIONS

    26 class CAknFileSelectionModel;

    27 class CAknFileSelectionEventHandler;

    28 class MAknFileSelectionObserver;

    29 class MAknFileFilter;

    30 

    31 //  CLASS DEFINITION

    32 /**

    33 *  A class that launches a popup dialog for file selection or directory browsing.

    34 *

    35 *  @lib CommonDialogs.lib

    36 *  @since 1.2

    37 */

    38 NONSHARABLE_CLASS(CAknFileSelectionDialog) : public CAknCommonDialogsBase

    39     {

    40     public:     // Constructors and destructors

    41         /**

    42         * Static constructor.

    43         * @param aDialogType Type of the dialog for reading correct default values.

    44         * @return Returns a pointer to an instance of itself.

    45         */

    46         IMPORT_C static CAknFileSelectionDialog* NewL(

    47             TCommonDialogType aDialogType );

    48 

    49         /**

    50         * Static constructor.

    51         * @param aDialogType Type of the dialog for reading correct default values.

    52         * @param aResourceId A resource id (FILESELECTIONDIALOG).

    53         * @return Returns a pointer to an instance of itself.

    54         */

    55         IMPORT_C static CAknFileSelectionDialog* NewL(

    56             TCommonDialogType aDialogType, TInt aResourceId );

    57 

    58         IMPORT_C ~CAknFileSelectionDialog();

    59 

    60     public: // New functions

    61 

    62         /**

    63         * Sets an observer which is asked if the selected item can be selected.

    64         * @param aObserver A pointer to an observer.

    65         */

    66         IMPORT_C void SetObserver( MAknFileSelectionObserver* aObserver );

    67 

    68         /**

    69         * Adds a filter to list of filters owned by the engine.

    70         * Note! The ownership of the filter is transferred to the engine.

    71         * @param aFilter A pointer to a filter that is derived from MAknFileFilter.

    72         */

    73         IMPORT_C void AddFilterL( MAknFileFilter* aFilter );

    74 

    75         /**

    76         * Sets the default folder that browsing is started from.

    77         * @param aDefaultFolder A folder that is relative to the root path,

    78         *        e.g. root path = "C:\" so the default folder could be

    79         *        "Nokia\Images\".

    80         */

    81         IMPORT_C void SetDefaultFolderL( const TDesC& aDefaultFolder );

    82 

    83         /**

    84         * Sets title to the pop-up dialog.

    85         * @param aText Title text.

    86         */

    87         IMPORT_C void SetTitleL( const TDesC& aText );

    88 

    89         /**

    90         * Sets the text used for left softkey when a file is focused.

    91         * @param aText The text for softkey.

    92         */

    93         IMPORT_C void SetLeftSoftkeyFileL( const TDesC& aText );

    94 

    95         /**

    96         * Sets the text used for left softkey when a folder is focused.

    97         * @param aText The text for softkey.

    98         */

    99         IMPORT_C void SetLeftSoftkeyFolderL( const TDesC& aText );

   100 

   101         /**

   102         * Sets the text used for right softkey when user is in the root folder.

   103         * @param aText The text used for right softkey when user is in the root folder.

   104         */

   105         IMPORT_C void SetRightSoftkeyRootFolderL( const TDesC& aText );

   106 

   107         /**

   108         * Sets the text used for right softkey when user is in a subfolder.

   109         * @param aText The text used for right softkey when user is in a subfolder.

   110         */

   111         IMPORT_C void SetRightSoftkeySubfolderL( const TDesC& aText );

   112 

   113         /**

   114         * Executes the file selection dialog.

   115         * @param aFileName Contains the root path.

   116         *        If an item is selected, the selected item will be set to the

   117         *        parameter with full path.

   118         * @return Returns ETrue if user has selected an item and EFalse

   119         *         if user hits cancel.

   120         */

   121         IMPORT_C TBool ExecuteL( TDes& aFileName );

   122 

   123         /**

   124         * A static method that launches a file selection dialog.

   125         * @see RunL()

   126         */

   127         IMPORT_C static TBool RunDlgLD( TDes& aFileName,

   128             const TDesC& aDefaultFolder,

   129             MAknFileSelectionObserver* aObserver = NULL );

   130 

   131         /**

   132         * A static method that launches a file selection dialog.

   133         * @see RunL()

   134         */

   135         IMPORT_C static TBool RunDlgLD( TDes& aFileName,

   136             const TDesC& aDefaultFolder,

   137             const TDesC& aTitle,

   138             MAknFileSelectionObserver* aObserver = NULL );

   139 

   140         /**

   141         * A static method that launches a file selection dialog.

   142         * @see RunL()

   143         */

   144         IMPORT_C static TBool RunDlgLD( TDes& aFileName,

   145             const TDesC& aDefaultFolder,

   146             TInt aResourceId,

   147             MAknFileSelectionObserver* aObserver = NULL );

   148 

   149     private:    // New functions

   150 

   151         /**

   152         * A static method for launching a file selection dialog.

   153         * Creates, constructs, runs and deletes a file selection dialog with

   154         * different parameters.

   155         * @param aResourceId An id of a resource. If zero, default resource is used.

   156         * @param aFileName A reference to a filename. Must contain the root path

   157         *        to start browsing from (if the root path is not defined in

   158         *        resource). If user accepts a selection, the whole path + current

   159         *        filename is set to aFileName.

   160         * @param aDefaultFolder A descriptor that contains one or more folders

   161         *        that are relative to the root path. Browsing is started from

   162         *        the default folder and user can browse folders up all the way

   163         *        to the root folder.

   164         * @param aTitle A title for file selection dialog.

   165         * @param aObserver An observer which is asked if the selected item

   166         *        can be selected. Implemented in application.

   167         * @return Returns true if user has selected an item and false

   168         *         if user hits cancel.

   169         */

   170         static TBool RunL(

   171             TInt aResourceId,

   172             TDes& aFileName,

   173             const TDesC& aDefaultFolder,

   174             const TDesC& aTitle,

   175             MAknFileSelectionObserver* aObserver );

   176 

   177         /**

   178         * Initialization method that must be called before executing the dialog.

   179         * Initializes the engine and event handler with correct values.

   180         * Decides if the dialog should be shown or not.

   181         * Called in ExecuteL.

   182         * @param aFileName The root path.

   183         * @return Returns EFalse if the dialog cannot be executed.

   184         */

   185         TBool PrepareL( const TDesC& aFileName );

   186 

   187         /**

   188         * Sets id to a default CFD resource depending on dialog type.

   189         * @param aResourceId Resource id variable to be modified.

   190         * @param aType Dialog type.

   191         */

   192         void SetResourceId( TInt& aResourceId, TCommonDialogType aType ) const;

   193 

   194         /**

   195         * Reads settings from resource.

   196         * @param aResourceId Resource id.

   197         */

   198         void ReadFromResourceL( TInt aResourceId );

   199 

   200     private:    // Constructors and destructors

   201 

   202         CAknFileSelectionDialog( TCommonDialogType aDialogType );

   203 

   204         /**

   205          * Second phase construct. Constructs itself from a resource.

   206          * @param aResourceId A resource id (FILESELECTIONDIALOG).

   207          */

   208         void ConstructFromResourceL( TInt aResourceId );

   209 

   210     private:    // Data

   211 

   212         // Own: Dialog type

   213         TCommonDialogType iDialogType;

   214 

   215         // Own: Model

   216         CAknFileSelectionModel* iModel;

   217 

   218         // Own: Event handler

   219         CAknFileSelectionEventHandler* iEventHandler;

   220 

   221         // Ref: Observer

   222         MAknFileSelectionObserver* iObserver;

   223 

   224         // Own: Title

   225         HBufC* iTitle;

   226 

   227         // Own: Left softkey when file focused

   228         HBufC* iLeftSoftkeyFile;

   229 

   230         // Own: Left softkey when folder focused

   231         HBufC* iLeftSoftkeyFolder;

   232 

   233         // Own: Right softkey when in root folder

   234         HBufC* iRightSoftkeyRootFolder;

   235 

   236         // Own: Right softkey when in subfolder

   237         HBufC* iRightSoftkeySubfolder;

   238 

   239         // Own: Root path

   240         HBufC* iRootPath;

   241 

   242         // Own: Default folder

   243         HBufC* iDefaultFolder;

   244 

   245         // Own: Boolean value that tells if the dialog has been executed already.

   246         TBool iExecuted;

   247     };

   248 

   249 #endif // CAKNFILESELECTIONDIALOG_H

   250 

   251 // End of File