/*

* 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 CHANGE   *

 *                                                      *

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

#ifndef C_SIFUI_H

#define C_SIFUI_H

#include <e32base.h>                            // CBase

class CSifUiPrivate;

class CApaMaskedBitmap;

class CSifUiCertificateInfo;

class CSifUiAppInfo;

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

        /**

         * Displays main installation confirmation query and waits for user response.

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

         * changes the dialog to installation progress note. And finally, ShowFailedL()

         * or ShowCompleteL() changes the dialog to the final error or complete note.

         * 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().

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

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

         */

        IMPORT_C TBool ShowConfirmationL( const CSifUiAppInfo& aAppInfo );

        /**

         * Defines memory selection alternatives for the main installation

         * confirmation query displayed with ShowConfirmationL() function.

         * @param aDriveNumbers - options for memory selection

         */

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

        /**

         * 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 );

        /**

         * Defines certificate details for the main installation confirmation

         * query displayed with ShowConfirmationL() function.

         * @param aCertificates - certificate details

         */

        IMPORT_C void SetCertificateInfoL(

                const RPointerArray<CSifUiCertificateInfo>& aCertificates );

        /**

         * Displays main installation progress note. If the progress note or main

         * confirmation query is already displayed, then updates the dialog content.

         * Use IncreaseProgressBarValueL() to increase the progress bar value.

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

         * Use ShowFailedL() or ShowCompleteL() to replace the dialog content

         * with the final error or complete note.

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

         * @param aProgressBarFinalValue - final value of the progress bar

         */

        /**

         * 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();

        /**

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

         */

        enum TOptionalButton

            {

            EHideProgressButton,

            ECancelProgressButton,

            EShowInAppLibButton,

            EErrorDetailsButton

            };

        /**

         * 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 );

        /**

         * Displays main installation complete note. Installation complete note contains

         * button to launch the application libaray to show the recently installed apps.

         */

        IMPORT_C void ShowCompleteL();

        /**

         * Displays main installation error note. Installation error note contains button

         * to see detailed error message when available.

         * @param aErrorCode - error code

         * @param aErrorMessage - localized error message to be displayed

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

         */

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

            const TDesC& aErrorDetails = KNullDesC );

    private:    // new functions

        CSifUi();

        void ConstructL();

    private:    // data

        CSifUiPrivate* iPrivate;

    };

#endif  // C_SIFUI_H