/*

 * 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

     };

 /**

 * 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