/*

* Copyright (c) 2010 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:  CSifUi API can be used to implement UI dialogs for

*               SIF (Software Install Framework) plugins.

*/

/**************************************************************

 *                                                            *

 *   WARNING - WORK-IN-PROGRESS - THIS API MAY STILL CHANGE   *

 *                                                            *

 **************************************************************/

#ifndef C_SIFUI_H

#define C_SIFUI_H

#include <e32base.h>                            // CBase

#include <bamdesca.h>                           // MDesCArray

class CSifUiPrivate;

class CApaMaskedBitmap;

class CSifUiCertificateInfo;

class CSifUiAppInfo;

class CSifUiErrorInfo;

namespace Swi {

    class CAppInfo;

    class CCertificateInfo;

}

/**

 * CSifUi provides UI dialogs for SW installation. UI dialogs are

 * global and they can be used in a non-UI code (like SIF plugins).

 * SW install device dialog plugin implements the UI dialogs.

 *

 * @lib sifui.lib

 * @since 10.1

 */

class CSifUi : public CBase

    {

    public:     // constructor and destructor

        /**

         * Creates new CSifUi object and pushes it into cleanup stack.

         * @returns CSifUi* -- new CSifUi object

         */

        IMPORT_C static CSifUi* NewLC();

        /**

         * Creates new CSifUi object.

         * @returns CSifUi* -- new CSifUi object

         */

        IMPORT_C static CSifUi* NewL();

        /**

         * Destructor.

         */

        ~CSifUi();

    public:     // new functions

        //=================================================

        // Preparing note method

        //=================================================

        /**

         * Displays installation dialog with "Preparing" text and indefinite progress bar.

         * No buttons are available. Use ShowConfirmationL() method to update the dialog

         * content to the installation confirmation query.

         */

        IMPORT_C void ShowPreparingL();

        //=================================================

        // Install confirmation query methods

        //=================================================

        /**

         * Defines memory selection alternatives for the ShowConfirmationL() installation

         * confirmation query. Use SelectedDrive() method to get the selected drive number

         * after ShowConfirmationL() call.

         * @param aDriveNumbers - options for memory selection

         */

        IMPORT_C void SetMemorySelectionL( const RArray<TInt>& aDriveNumbers );

        /**

         * Defines certificate details for the ShowConfirmationL() installation

         * confirmation query. If certificates are not set, then application is

         * untrusted.

         * @param aCertificates - certificate details

         */

        IMPORT_C void SetCertificateInfoL(

                const RPointerArray<CSifUiCertificateInfo>& aCertificates );

        /**

         * Displays installation confirmation query and waits for user response.

         * Returns ETrue if the user accepted the query. The next ShowProgressL() call

         * changes the dialog content to installation progress note. And finally,

         * ShowCompleteL() or ShowFailedL() call changes the dialog content to the

         * complete or error note.

         * If preparing installation note needs to be displayed before confirmation query,

         * then call ShowPreparingL() before any other functions.

         * If the installation confirmation query should contain memory selection option,

         * then set the selectable drives with SetMemorySelectionL() first. User selected

         * drive can be retrieved with SelectedDrive() after ShowConfirmationL() returns.

         * If the installation confirmation query should contain certificate details, then

         * set the certificate details using SetCertificateInfoL() first.

         * @param aAppInfo - application information (name, size, version, vendor, icon)

         * @return TBools - ETrue if the user accepted the query, EFalse otherwise

         */

        IMPORT_C TBool ShowConfirmationL( const CSifUiAppInfo& aAppInfo );

        /**

         * Gets the selected drive where new component should be installed.

         * Use RFs::DriveToChar() to convert the drive number to drive letter.

         * @param aDriveNumber - selected drive number

         * @return TInt - KErrNone if successful, otherwise Symbian error code

         */

        IMPORT_C TInt SelectedDrive( TInt& aDriveNumber );

        //=================================================

        // Progress note methods

        //=================================================

        /**

         * Installing phases in progress notes. Indicated in progress note title text.

         */

        enum TInstallingPhase {

            EInstalling,

            EDownloading,

            ECheckingCerts

        };

        /**

         * Displays installation progress note. Changes confirmation query content

         * to progress note. If the progress note is already displayed, then updates

         * the dialog content. Use IncreaseProgressBarValueL() method to increase the

         * progress bar value.

         * Dialog remains on the screen after progress bar shows full 100% value.

         * Use ShowCompleteL() or ShowFailedL() methods to show the result.

         * @param aAppInfo - application information (name, size, version, vendor, icon)

         * @param aProgressBarFinalValue - final value of the progress bar

         * @param aPhase - defines new title text for the progress note dialog

         */

        IMPORT_C void ShowProgressL( const CSifUiAppInfo& aAppInfo, TInt aProgressBarFinalValue,

                TInstallingPhase aPhase = EInstalling );

        /**

         * Updates the progress bar value displayed in progress note. Initially progress bar

         * shows 0%. Each aIncrement increases the value displayed in progress bar. When all

         * increments reach the final value defined in ShowProgressNoteL() method, then the

         * progress bar shows full 100%. Caller should check using IsCancelled() method if

         * the user has cancelled the progress note before updating the progress bar value.

         * @param aIncrement - progress bar value increment

         */

        IMPORT_C void IncreaseProgressBarValueL( TInt aIncrement );

        /**

         * Returns ETrue if the user has cancelled the progress dialog.

         * @return TBool - ETrue if the progress dialog has been cancelled

         */

        IMPORT_C TBool IsCancelled();

        //=================================================

        // Final complete and error notes

        //=================================================

        /**

         * Displays installation complete note and waits for the user to close it.

         * Installation complete note contains "Show" button to show installed

         * applications in application library. Use SetButtonVisible() method to

         * hide the "Show" button when necessary.

         */

        IMPORT_C void ShowCompleteL();

        /**

         * Displays installation error note and waits for user to close it.

         * Installation error note contains "Details" button to show the detailed

         * error message (when available). Also SetButtonVisible() method can be

         * used to hide the "Details" button if necessary.

         * @param aErrorCategory - error category

         * @param aErrorMessage - localized error message to be displayed

         * @param aErrorDetails - localized error message details (if any)

         * @param aErrorCode - error code

         * @param aErrorCode - error code

         */

        IMPORT_C void ShowFailedL( const CSifUiErrorInfo& aErrorInfo );

        //=================================================

        // Buttons in progress/complete/error notes

        //=================================================

        /**

         * Toolbar buttons in progress and complete notes that can be disabled/hidden.

         */

        enum TOptionalButton

            {

            EHideProgressButton,        // "Hide" button in progress note

            ECancelProgressButton,      // "Cancel" button in progress note

            EShowInAppLibButton,        // "Show" button in complete note

            EErrorDetailsButton         // "Details" button in error note

            };

        /**

         * Hides or shows optional toolbar buttons from installation progress note

         * or installation complete note. All optional buttos are visible by default.

         * Buttons visibility becomes effective in the next ShowProgressL(),

         * ShowCompleteL(), or IncreseProgressBarValueL() method calls.

         * @param aButton - button which visibility is changed

         * @param aIsVisible - EFalse if button needs to be hidden

         */

        IMPORT_C void SetButtonVisible( TOptionalButton aButton, TBool aIsVisible );

        //=================================================

        // Other query dialogs

        //=================================================

        /**

         * Displays dialog requesting capabilities for the application being installed

         * and waits for user response. Returns ETrue if the user granted the capabilities.

         * Other dialogs (like progress note) are not affected.

         * @param aCapabilities - requested user capabilities

         * @return TBool - ETrue if the user granted the capabilities, EFalse otherwise

         */

        IMPORT_C TBool ShowGrantCapabilitiesL( const TCapabilitySet& aCapabilities );

        /**

         * Displays pop-up language selection dialog with radio-buttons, and

         * waits for user response. Other displayed installation dialogs (like

         * progress note) are not affected. Returns integer that is the index

         * of the selected language in given langauge array, or error code.

         * Return value is KErrCancel if the user cancelled the query.

         * @param aLanguages - array of selectable languages

         * @return The selected item index to aLangauges array, or error code.

         */

        IMPORT_C TInt ShowSelectLanguageL( const RArray<TLanguage>& aLanguages );

        /**

         * Displays multi-selection pop-up dialog with checkboxes, and waits

         * for user response. Other displayed installation dialogs (like progress

         * note) are not affected. Returns ETrue if the user made the selection,

         * EFalse if the user cancelled the query. Selected indices are returned

         * in aSelectedIndexes array.

         * @param aSelectableItems - array of selectable items displayed

         * @param aSelectedIndexes - returns the selected item indices

         * @return TBool - ETrue if the user accepted the query, EFalse otherwise

         */

        IMPORT_C TBool ShowSelectOptionsL( const MDesCArray& aSelectableItems,

                RArray<TInt>& aSelectedIndexes );

        //=================================================

        // DEPRECATED METHODS

        //=================================================

        // DEPRECATED, WILL BE REMOVED, DO NOT USE

        IMPORT_C void ShowFailedL( TInt aErrorCode, const TDesC& aErrorMessage,

            const TDesC& aErrorDetails = KNullDesC );

        IMPORT_C TBool ShowSingleSelectionL( const TDesC& aTitle,

            const MDesCArray& aSelectableItems, TInt& aSelectedIndex );

        IMPORT_C TBool ShowMultiSelectionL( const TDesC& aTitle,

            const MDesCArray& aSelectableItems, RArray<TInt>& aSelectedIndexes );

    private:    // new functions

        CSifUi();

        void ConstructL();

    private:    // data

        CSifUiPrivate* iPrivate;

    };

#endif  // C_SIFUI_H