/*
* Copyright (c) 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 "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:  Handle dialogs needed for browser operation
*
*/


#ifndef BRCTLDIALOGSPROVIDER_H
#define BRCTLDIALOGSPROVIDER_H

//  INCLUDES
#include <e32std.h>
#include <e32base.h>

/**
* Type of selection list
*/
enum TBrCtlSelectOptionType
    {
    ESelectTypeMultiple,  ///< Multiple select - Display a checkbox
    ESelectTypeSingle,    ///< Single select - Display a radio button
    ESelectTypeNone,      ///< Single select - Do not display any button
    /**
    * No buttons (single selection only)
    * OK softkey is available
    * Cancel button is not available
    */
    ESelectTypeOkOnly,
    /**
     * Added enumeration ESelectTypeWithFindPane at offset of 0x100 so that
     * the limit of different types of dialog boxes can be upto 256.
     * Any user who wants a list with find pane must "|" with a defined type
     * above like ESelectTypeNone | ESelectTypeWithFindPane to obtain a list
     * box with find pane.
     */
    ESelectTypeWithFindPane = 0x100
    };

/**
* Defines the type of image if it cannot be recognized by the
* Symbian image conversion library.
*/

enum TBrCtlImageType
    {
    EImageTypeAny, ///< Automatically recognized by the image converter
    EImageTypeWbmp, ///< Wireless Bitmap (WBMP) image
    EImageTypeOta ///< Over The Air (OTA) image
    };


// FORWARD DECLARATIONS
class TBrCtlSelectOptionData;
class CBrCtlObjectInfo;
class TBrCtlImageCarrier;

/**
* The MBrDialogsProvider class provides functions implemented by
* the Browser Control to display dialogs, such as error notifications,
* authentication requests, and selection lists.
*
* Usage:
*
* @code
*  #include <brctldialogsprovider.h>
*
*
* @see S60 Platform: Browser Control API Developer's Guide Version 2.0
* @lib BrowserEngine.lib
* @file brctldialogsprovider.h
* @endcode     *
*/
class MBrCtlDialogsProvider
    {
    public: // New functions

        /**
        * Notifies the user of an error encountered during a download.
        * Some examples are: insufficient memory, unrecognized URL, and DNS not found.
        * @since 2.8
        * @param aErrCode The error that occured
        * @return void
        */
        virtual void DialogNotifyErrorL(TInt aErrCode) = 0;

        /**
        * Notifies the user of an error from the HTTP server
        * during a download. Some examples are: file not found, redirect error.
        * @since 2.8
        * @param aErrCode The error that occured
        * @param aUri The uri of the request that failed
        * @return void
        */
        virtual void DialogNotifyHttpErrorL(TInt aErrCode, const TDesC& aUri) = 0;

        /**
        * Navigates through your file system and selects a file;
        * analogous to the Browse command in Windows.
        * @since 2.8
        * @param aStartPath The initial displayed directory
        * @param aRootPath The top most directory that the user can go up to
        * @param aSelectedFileName The selected file name.
        * @return ETrue if the user selected a file
        * EFalse if the user cancelled the transaction and did not select a file.
        * @attiontion Returned on cleanup stack. Browser control will free the buffer.
        */
        virtual TBool DialogFileSelectLC(const TDesC& aStartPath,
                                         const TDesC& aRootPath,
                                         HBufC*& aSelectedFileName) = 0;

        /**
        * List selection dialog
        * @since 2.8
        * @param Title of the selection dialog. This is optional.
        * @param aBrCtlSelectOptionType The type of the list box.
        * Values: One of the following:
        * Check boxes (multiple selections allowed)
        * Radio buttons (single selection only). For example, highlight a URL listed
        *   in the session History.
        *   No buttons (single selection only)
        * No buttons (single selection only), OK softkey available
        * For example, if you are about to download a plug-in, you can choose
        * to display the content in the Web page or in a viewer application.
        * @param aOptions A list of options to display
        * @return EFalse if the user canceled the dialog selection
        * ETrue if the user selected an option.
        */
        virtual TBool DialogSelectOptionL(const TDesC& aTitle,
                                          TBrCtlSelectOptionType aBrCtlSelectOptionType,
                                          CArrayFix<TBrCtlSelectOptionData>& aOptions) = 0;

        /**
        * User Authentication dialog.
        * @since 2.8
        * @param aUrl The url requiring authentication
        * @param aRealm The realm requiring authentication
        * @param aDefaultUserName The user name that was used before for this realm and path, if any
        * @param aReturnedUserName The user name entered by the user
        * @param aReturnedPasswd The password entered by the user
        * @param aBasicAuthentication ETrue if basic authentication is required.
        * EFalse if another type of authentication is required; for example, Digest.
        * Default: EFalse
        * @return EFalse if the user cancelled the selection
        * ETrue if the user selected an option.
        @ attiontion User name and password are returned on cleanup stack.
        */
        virtual TBool DialogUserAuthenticationLC(const TDesC& aUrl,
                                                 const TDesC& aRealm,
                                                 const TDesC& aDefaultUserName,
                                                 HBufC*& aReturnedUserName,
                                                 HBufC*& aReturnedPasswd,
                                                 TBool aBasicAuthentication = EFalse) = 0;

        /**
        * Displays a message to the user.
        * For example, the message may inform the user
        * about an error encountered while processing a request.
        * @since 2.8
        * @param aMessage The message to display
        * @return void
        * @attention Softkeys are not supported.
        * The message disappears after a time out.
        */
        virtual void DialogNoteL(const TDesC& aMessage) = 0;

        /**
        * Display a note to the user with ok softkey only
        * @since 2.8
        * @param aTitle The title, could be empty
        * @param aMessage The message to display
        * @return void
        * @attention The OK softkey is supported.
        * The message displays until the user presses OK.
        */
        virtual void DialogAlertL(const TDesC& aTitle, const TDesC& aMessage) = 0;

        /**
        * Display confirmation message to the user.
        * For example, Are you sure you want to delete this?
        * @since 2.8
        * @param aTitle The title, could be empty
        * @param aMessage The message to display
        * @param aYesMessage The text to display on left softkey
        * @param aNoMessage The text to display on right softkey
        * @return EFalse if the user cancelled the selection
        * ETrue if the user selected an option.
        */
        virtual TBool DialogConfirmL(const TDesC& aTitle,
                                     const TDesC& aMessage,
                                     const TDesC& aYesMessage,
                                     const TDesC& aNoMessage) = 0;

        /**
        * Displays an input dialog to the user. Asks the user to input data.
        * @since 2.8
        * @param aTitle The title, could be empty
        * @param aMessage The message to display
        * @param aDefaultInput The default input if available
        * @param aReturnedInput The input entered by the user.
        * @return EFalse if the user cancelled the selection
        * ETrue if the user selected an option.
        * @attention Returned on the cleanup stack.
        */
        virtual TBool DialogPromptLC(const TDesC& aTitle,
                                     const TDesC& aMessage,
                                     const TDesC& aDefaultInput,
                                     HBufC*& aReturnedInput) = 0;

        /**
        * Displays information about the Netscape plug-in object and
        * requests confirmation before downloading the object.
        * @since 2.8
        * @param aBrCtlObjectInfo Information about the object to be downloaded.
        * The following information is passes as part of this object:
        * Content type
        * Size
        * Flag to indicate whether a viewer application exists for this content
        * Flag to indicate whether a Netscape plug-in exists that supports this content
        * Name of the application or Netscape plug-in with which the content can
        * be viewed on the mobile phone
        * @return EFalse if the user cancelled the selection
        * ETrue if the user selected an option.
        */
        virtual TBool DialogDownloadObjectL(CBrCtlObjectInfo* aBrCtlObjectInfo) = 0;

        /**
        * Display the images that appear in the current page
        * @since 2.8
        * @param aPageImages Array describing the images that appear in the current page.
        * The array contains the following elements for each image:
        * Image data
        * URL of the image
        * Title for the image
        * Image type
        * If the image type is WBMP or OTA, it must be specified.
        * Symbian can detect any other image type.
        * @return void
        */
        virtual void DialogDisplayPageImagesL(CArrayFixFlat<TBrCtlImageCarrier>& aPageImages) = 0;

        /**
        * Cancels the dialog displayed due to browser exit or destroyed pages.
        * @since 2.8
        * @return void
        */
        virtual void CancelAll() = 0;

        /**
        * Displays a dialog for searching on the page.
        * @since 3.0
        * @return void
        */
       virtual void DialogFindL() = 0;

    };


/**
* The TBrCtlSelectOptionData class represents a list of elements
* to display in the list box. This class is used for the List Selection Dialog.
* @code
*  #include <brctldialogsprovider.h>
* @lib BrowserEngine.lib
* @since 2.8
* @file brctldialogsprovider.h
* @endcode     *
*/
class TBrCtlSelectOptionData
    {
    public:
        /**
        * Default Constructor
        * @return TbrCtlSelectOptionData object
        * @since 2.8
        */
        inline TBrCtlSelectOptionData()
                {
                iText.Set(NULL, 0);
                iIsSelected = EFalse;
                iIsOptGroup = EFalse;
                iHasOnPick = EFalse;
                }

        /**
        * Constructor
        * @since 2.8
        * @param aText The text to display with this element
        * @param aIsSelected If the element is selected
        * @param aIsOptGroup If a title of option group or an element
        * @param aHasOnPick If has onPick, The dialog should close when the element is selected
        * @return TbrCtlSelectOptionData object
        */
        inline TBrCtlSelectOptionData( const TDesC& aText,
                                        TBool aIsSelected,
                                        TBool aIsOptGroup,
                                        TBool aHasOnPick )
                                                            {
                                                            iText.Set(aText);
                                                            iIsSelected = aIsSelected;
                                                            iIsOptGroup = aIsOptGroup;
                                                            iHasOnPick = aHasOnPick;
                                                            }
        /**
        * Gets the display text associated with a specified option.
        * @since 2.8
        * @return A reference to a Symbian TDesC object that
        * contains the text associated with this option.
        */
        inline const TDesC& Text() const {return iText;}
        /**
        * Indicates whether or not an option is selected.
        * @since 2.8
        * @return ETrue if the option is selected
        * EFalse if the option is not selected
        */
        inline TBool IsSelected() const {return iIsSelected;}
        /**
        * Indicates whether an option group member
        * variable is a group title or a selectable option.
        * @since 2.8
        * @return ETrue if the listed item is the title of an option group
        * EFalse if the listed item is one of the options from which to select
        */
        inline TBool IsOptGroup() const {return iIsOptGroup;}
        /**
        * Indicates whether or not the dialog closes when an option is selected.
        * @since 2.8
        * @return ETrue if the dialog closes when the element is selected.
        * This is known as having OnPick capability.
        * EFalse if the dialog does not close when the element is selected
        */
        inline TBool HasOnPick() const {return iHasOnPick;}
        /**
        * Sets the text of the option object.
        * @since 2.8
        * @param aText A reference to a TDesC object that contains the
        * text to associate with a particular option.
        * @return None
        */

        inline void SetText( TDesC& aText )             { iText.Set( aText ); }
        /**
        * Sets the selection state of an option.
        * @since 2.8
        * @param aIsSelected The state of the IsSelected member variable.
        * Value:
        * ETrue if the option is selected
        * EFalse if the option is not selected
        * @return None
        */
        inline void SetIsSelected( TBool aIsSelected )  { iIsSelected = aIsSelected; }
        /**
        * Sets the state of the option group member variable.
        * Indicates whether an option group member variable is a group title
        * or a selectable option.
        * @since 2.8
        * @param aIsOptGroup The state of the option group.
        * Value:
        * ETrue if the listed item is the title of an option group.
        * EFalse if the listed item is one of the options from which to select.
        * @return None
        */
        inline void SetIsOptGroup( TBool aIsOptGroup )  { iIsOptGroup = aIsOptGroup; }
        /**
        * Sets the state of the hasOnPick member variable.
        * Indicates whether or not the dialog closes when an option is selected.
        * @since 2.8
        * @param aHasOnPick
        * ETrue if the dialog closes when the element is selected. This
        * is known as having OnPick capability.
        * EFalse if the dialog does not close when the element is selected
        * @return None
        */
        inline void SetHasOnPick( TBool aHasOnPick )    { iHasOnPick = aHasOnPick; }

    private:    // Data
        // The text associated with the element
        TPtrC iText;
        // Flag if the element is selected
        TBool iIsSelected;
        // Flag if an element or oprion group title
        TBool iIsOptGroup;
        // Flag if the element has onPick
        TBool iHasOnPick;
    };

/**
* The CBrCtlObjectInfo class used to represent the information about the
* plugin object.
* @code
*  #include <brctldialogsprovider.h>
* @lib BrowserEngine.lib
* @since 3.0
* @file brctldialogsprovider.h
* @endcode     *
*/
class CBrCtlObjectInfo : public CBase
  {
  public:
        /**
        * Default Constructor
        * @since 2.8
        */
        CBrCtlObjectInfo();

        /**
        * Constructor
        * @since 3.0
        * @param aAppSupported A flag if there is a viewer app for this object
        * @param aPluginSupported A flag if there is a netscape plugin for this object
        * @param aSize The size of the object
        * @param aAppName The name of the viewer app or netscape plugin that supports this object
        * @param aFileType The content type of the object
        * @return CBrCtlObjectInfo object
        */
    CBrCtlObjectInfo(TBool aAppSupported, TBool aPluginSupported,
                         const TDesC& aSize, const TDesC& aAppName,
                         const TDesC& aFileType);
  public:
        /**
        * Sets the flag if there is a viewer app for this object
        * @since 3.0
        * @param aAppSupported ETrue if there is a viewer app for this object
        * EFalse if there is not a viewer app for this object.
        * @return None
        */
        inline void SetAppSupported(TBool aAppSupported) {iAppSupported = aAppSupported;}
        /**
        * Sets the flag if there is a netscape plugin for this object
        * @since 3.0
        * @param aPluginSupported ETrue if there is a netscape plugin for this object
        * EFalse if there is not a netscape plugin for this object.
        * @return None
        */
        inline void SetPluginSupported(TBool aPluginSupported) {iPluginSupported = aPluginSupported;}
        /**
        * Sets the size of the object
        * @since 3.0
        * @param aSize Symbian descriptor containing the size of the object
        * @return None
        */
        inline void SetSize(const TDesC& aSize) {iSize.Set(aSize);}
        /**
        * Sets the name of the viewer app or netscape plugin that supports this object
        * @since 3.0
        * @param aAppName  Symbian descriptor containing the name of
        * the viewer app or netscape plugin that supports this object.
        * @return None
        */
    inline void SetAppName(const TDesC& aAppName) {iAppName.Set(aAppName);}
        /**
        * Sets the content type of the object
        * @since 3.0
        * @param aFileType Symbian descriptor holding content type of the object
        * @return None
        */
    inline void SetFileType(const TDesC& aFileType) {iFileType.Set(aFileType);}
        /**
        * Tells if there is a viewer app for this object
        * @since 3.0
        * @param None
        * @return  ETrue if there is a viewer app for this object
        * EFalse if there is not a viewer app for this object.
        */
        inline TBool AppSupported() {return iAppSupported;}
        /**
        * Tells if there is a netscape plugin for this object
        * @since 3.0
        * @param None
        * @return ETrue if there is a netscape plugin for this object
        * EFalse if there is not a netscape plugin for this object.
        */
        inline TBool PluginSupported() {return iPluginSupported;}
        /**
        * Gets the size of the object
        * @since 3.0
        * @param None
        * @return Symbian descriptor containing the size of the object
        */
        inline const TDesC& Size() const {return iSize;}
        /**
        * Gets the name of the viewer app or netscape plugin that supports this object
        * @since 3.0
        * @param None
        * @return Symbian descriptor containing the name of
        * the viewer app or netscape plugin that supports this object.
        */
    inline const TDesC& AppName() const {return iAppName;}
        /**
        * Gets the content type of the object
        * @since 3.0
        * @param None
        * @return Symbian descriptor holding content type of the object
        */
    inline const TDesC& FileType() const {return iFileType;}
  private:
    // A flag if there is a viewer app for this object
        TBool iAppSupported;
        // A flag if there is a Netscape plugin for this object
    TBool iPluginSupported;
        // The size of the object
    TPtrC iSize;
        // The name of the viewer app or Netscape plugin
    TPtrC iAppName;
        // The content type of the object
    TPtrC iFileType;
  };

/**
* TheTBrCtlImageCarrier class used to give the information about the
* image.
* @code
*  #include <brctldialogsprovider.h>
* @lib BrowserEngine.lib
* @since 2.8
* @file brctldialogsprovider.h
* @endcode     *
*/
class TBrCtlImageCarrier
    {
    public:
        /**
        * Constructor
        * @since 2.8
        * @param aRawData The image data
        * @param aUrl The url of the image
        * @param aAltText The alt text of the image
        * @param aImageType The type of the image
        */
        TBrCtlImageCarrier(const TDesC8& aRawData, const TDesC& aUrl,
            const TDesC& aAltText, TBrCtlImageType aImageType, const TDesC& aContentType ) :
            iRawData( aRawData ),
            iUrl( aUrl ),
            iAltText( aAltText ),
            iImageType(aImageType),
      iContentType(aContentType)
            {
            }
        /**
        * Provides the image data
        * @since 3.0
        * @param None
        * @return Symbian descriptor containing image data
        */
        inline const TDesC8& RawData() const {return iRawData;}
        /**
        * Provides the url of the image
        * @since 3.0
        * @param None
        * @return Symbian descriptor containing url of the image
        */
        inline const TDesC& Url() const {return iUrl;}
        /**
        * Provides the alt text of the image
        * @since 3.0
        * @param None
        * @return Symbian descriptor containing alt text of the image
        */
        inline const TDesC& AltText() const {return iAltText;}
        /**
        * Provides the type of the image
        * @since 3.0
        * @param None
        * @return Symbian descriptor containing the type of the image
        */
        inline TBrCtlImageType ImageType() const {return iImageType;}
        /**
        * Provides the content type of the image
        * @since 3.1
        * @param None
        * @return Symbian descriptor containing content type of the image
        */
        inline const TDesC& ContentType() const {return iContentType;}
    private:
        TPtrC8 iRawData;
        TPtrC iUrl;
        TPtrC iAltText;
        TBrCtlImageType iImageType;
    TPtrC iContentType;
    };


#endif      // BRCTLDIALOGSPROVIDER_H

// End of File
