/*
* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Dialog used to select target file or directory
*
*/


#ifndef CAKNFILESELECTIONDIALOG_H
#define CAKNFILESELECTIONDIALOG_H

// INCLUDES
#include <CAknCommonDialogsBase.h>

// FORWARD DECLARATIONS
class CAknFileSelectionModel;
class CAknFileSelectionEventHandler;
class MAknFileSelectionObserver;
class MAknFileFilter;

//  CLASS DEFINITION
/**
*  A class that launches a popup dialog for file selection or directory browsing.
*
*  @lib CommonDialogs.lib
*  @since 1.2
*/
NONSHARABLE_CLASS(CAknFileSelectionDialog) : public CAknCommonDialogsBase
    {
    public:     // Constructors and destructors
        /**
        * Static constructor.
        * @param aDialogType Type of the dialog for reading correct default values.
        * @return Returns a pointer to an instance of itself.
        */
        IMPORT_C static CAknFileSelectionDialog* NewL(
            TCommonDialogType aDialogType );

        /**
        * Static constructor.
        * @param aDialogType Type of the dialog for reading correct default values.
        * @param aResourceId A resource id (FILESELECTIONDIALOG).
        * @return Returns a pointer to an instance of itself.
        */
        IMPORT_C static CAknFileSelectionDialog* NewL(
            TCommonDialogType aDialogType, TInt aResourceId );

        IMPORT_C ~CAknFileSelectionDialog();

    public: // New functions

        /**
        * Sets an observer which is asked if the selected item can be selected.
        * @param aObserver A pointer to an observer.
        */
        IMPORT_C void SetObserver( MAknFileSelectionObserver* aObserver );

        /**
        * Adds a filter to list of filters owned by the engine.
        * Note! The ownership of the filter is transferred to the engine.
        * @param aFilter A pointer to a filter that is derived from MAknFileFilter.
        */
        IMPORT_C void AddFilterL( MAknFileFilter* aFilter );

        /**
        * Sets the default folder that browsing is started from.
        * @param aDefaultFolder A folder that is relative to the root path,
        *        e.g. root path = "C:\" so the default folder could be
        *        "Nokia\Images\".
        */
        IMPORT_C void SetDefaultFolderL( const TDesC& aDefaultFolder );

        /**
        * Sets title to the pop-up dialog.
        * @param aText Title text.
        */
        IMPORT_C void SetTitleL( const TDesC& aText );

        /**
        * Sets the text used for left softkey when a file is focused.
        * @param aText The text for softkey.
        */
        IMPORT_C void SetLeftSoftkeyFileL( const TDesC& aText );

        /**
        * Sets the text used for left softkey when a folder is focused.
        * @param aText The text for softkey.
        */
        IMPORT_C void SetLeftSoftkeyFolderL( const TDesC& aText );

        /**
        * Sets the text used for right softkey when user is in the root folder.
        * @param aText The text used for right softkey when user is in the root folder.
        */
        IMPORT_C void SetRightSoftkeyRootFolderL( const TDesC& aText );

        /**
        * Sets the text used for right softkey when user is in a subfolder.
        * @param aText The text used for right softkey when user is in a subfolder.
        */
        IMPORT_C void SetRightSoftkeySubfolderL( const TDesC& aText );

        /**
        * Executes the file selection dialog.
        * @param aFileName Contains the root path.
        *        If an item is selected, the selected item will be set to the
        *        parameter with full path.
        * @return Returns ETrue if user has selected an item and EFalse
        *         if user hits cancel.
        */
        IMPORT_C TBool ExecuteL( TDes& aFileName );

        /**
        * A static method that launches a file selection dialog.
        * @see RunL()
        */
        IMPORT_C static TBool RunDlgLD( TDes& aFileName,
            const TDesC& aDefaultFolder,
            MAknFileSelectionObserver* aObserver = NULL );

        /**
        * A static method that launches a file selection dialog.
        * @see RunL()
        */
        IMPORT_C static TBool RunDlgLD( TDes& aFileName,
            const TDesC& aDefaultFolder,
            const TDesC& aTitle,
            MAknFileSelectionObserver* aObserver = NULL );

        /**
        * A static method that launches a file selection dialog.
        * @see RunL()
        */
        IMPORT_C static TBool RunDlgLD( TDes& aFileName,
            const TDesC& aDefaultFolder,
            TInt aResourceId,
            MAknFileSelectionObserver* aObserver = NULL );

    private:    // New functions

        /**
        * A static method for launching a file selection dialog.
        * Creates, constructs, runs and deletes a file selection dialog with
        * different parameters.
        * @param aResourceId An id of a resource. If zero, default resource is used.
        * @param aFileName A reference to a filename. Must contain the root path
        *        to start browsing from (if the root path is not defined in
        *        resource). If user accepts a selection, the whole path + current
        *        filename is set to aFileName.
        * @param aDefaultFolder A descriptor that contains one or more folders
        *        that are relative to the root path. Browsing is started from
        *        the default folder and user can browse folders up all the way
        *        to the root folder.
        * @param aTitle A title for file selection dialog.
        * @param aObserver An observer which is asked if the selected item
        *        can be selected. Implemented in application.
        * @return Returns true if user has selected an item and false
        *         if user hits cancel.
        */
        static TBool RunL(
            TInt aResourceId,
            TDes& aFileName,
            const TDesC& aDefaultFolder,
            const TDesC& aTitle,
            MAknFileSelectionObserver* aObserver );

        /**
        * Initialization method that must be called before executing the dialog.
        * Initializes the engine and event handler with correct values.
        * Decides if the dialog should be shown or not.
        * Called in ExecuteL.
        * @param aFileName The root path.
        * @return Returns EFalse if the dialog cannot be executed.
        */
        TBool PrepareL( const TDesC& aFileName );

        /**
        * Sets id to a default CFD resource depending on dialog type.
        * @param aResourceId Resource id variable to be modified.
        * @param aType Dialog type.
        */
        void SetResourceId( TInt& aResourceId, TCommonDialogType aType ) const;

        /**
        * Reads settings from resource.
        * @param aResourceId Resource id.
        */
        void ReadFromResourceL( TInt aResourceId );

    private:    // Constructors and destructors

        CAknFileSelectionDialog( TCommonDialogType aDialogType );

        /**
         * Second phase construct. Constructs itself from a resource.
         * @param aResourceId A resource id (FILESELECTIONDIALOG).
         */
        void ConstructFromResourceL( TInt aResourceId );

    private:    // Data

        // Own: Dialog type
        TCommonDialogType iDialogType;

        // Own: Model
        CAknFileSelectionModel* iModel;

        // Own: Event handler
        CAknFileSelectionEventHandler* iEventHandler;

        // Ref: Observer
        MAknFileSelectionObserver* iObserver;

        // Own: Title
        HBufC* iTitle;

        // Own: Left softkey when file focused
        HBufC* iLeftSoftkeyFile;

        // Own: Left softkey when folder focused
        HBufC* iLeftSoftkeyFolder;

        // Own: Right softkey when in root folder
        HBufC* iRightSoftkeyRootFolder;

        // Own: Right softkey when in subfolder
        HBufC* iRightSoftkeySubfolder;

        // Own: Root path
        HBufC* iRootPath;

        // Own: Default folder
        HBufC* iDefaultFolder;

        // Own: Boolean value that tells if the dialog has been executed already.
        TBool iExecuted;
    };

#endif // CAKNFILESELECTIONDIALOG_H

// End of File