1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Handle dialogs needed for browser operation

    15 *

    16 */

    17 

    18 

    19 #ifndef BRCTLDIALOGSPROVIDER_H

    20 #define BRCTLDIALOGSPROVIDER_H

    21 

    22 //  INCLUDES

    23 #include <e32std.h>

    24 #include <e32base.h>

    25 

    26 /**

    27 * Type of selection list

    28 */

    29 enum TBrCtlSelectOptionType

    30     {

    31     ESelectTypeMultiple,  ///< Multiple select - Display a checkbox

    32     ESelectTypeSingle,    ///< Single select - Display a radio button

    33     ESelectTypeNone,      ///< Single select - Do not display any button

    34     /**

    35     * No buttons (single selection only)

    36     * OK softkey is available

    37     * Cancel button is not available

    38     */

    39     ESelectTypeOkOnly

    40     };

    41 

    42 /**

    43 * Defines the type of image if it cannot be recognized by the

    44 * Symbian image conversion library.

    45 */

    46 

    47 enum TBrCtlImageType

    48     {

    49     EImageTypeAny, ///< Automatically recognized by the image converter

    50     EImageTypeWbmp, ///< Wireless Bitmap (WBMP) image

    51     EImageTypeOta ///< Over The Air (OTA) image

    52     };

    53 

    54 

    55 // FORWARD DECLARATIONS

    56 class TBrCtlSelectOptionData;

    57 class CBrCtlObjectInfo;

    58 class TBrCtlImageCarrier;

    59 

    60 /**

    61 * The MBrDialogsProvider class provides functions implemented by

    62 * the Browser Control to display dialogs, such as error notifications,

    63 * authentication requests, and selection lists.

    64 *

    65 * Usage:

    66 *

    67 * @code

    68 *  #include <BrCtlDialogsProvider.h>

    69 *

    70 *

    71 * @see S60 Platform: Browser Control API Developer's Guide Version 2.0

    72 * @lib BrowserEngine.lib

    73 * @file BrCtlDialogsProvider.h

    74 * @endcode     *

    75 */

    76 class MBrCtlDialogsProvider

    77     {

    78     public: // New functions

    79 

    80         /**

    81         * Notifies the user of an error encountered during a download.

    82         * Some examples are: insufficient memory, unrecognized URL, and DNS not found.

    83         * @since 2.8

    84         * @param aErrCode The error that occured

    85         * @return void

    86         */

    87         virtual void DialogNotifyErrorL(TInt aErrCode) = 0;

    88 

    89         /**

    90         * Notifies the user of an error from the HTTP server

    91         * during a download. Some examples are: file not found, redirect error.

    92         * @since 2.8

    93         * @param aErrCode The error that occured

    94         * @param aUri The uri of the request that failed

    95         * @return void

    96         */

    97         virtual void DialogNotifyHttpErrorL(TInt aErrCode, const TDesC& aUri) = 0;

    98 

    99         /**

   100         * Navigates through your file system and selects a file;

   101         * analogous to the Browse command in Windows.

   102         * @since 2.8

   103         * @param aStartPath The initial displayed directory

   104         * @param aRootPath The top most directory that the user can go up to

   105         * @param aSelectedFileName The selected file name.

   106         * @return ETrue if the user selected a file

   107         * EFalse if the user cancelled the transaction and did not select a file.

   108         * @attiontion Returned on cleanup stack. Browser control will free the buffer.

   109         */

   110         virtual TBool DialogFileSelectLC(const TDesC& aStartPath,

   111                                          const TDesC& aRootPath,

   112                                          HBufC*& aSelectedFileName) = 0;

   113 

   114         /**

   115         * List selection dialog

   116         * @since 2.8

   117         * @param Title of the selection dialog. This is optional.

   118         * @param aBrCtlSelectOptionType The type of the list box.

   119         * Values: One of the following:

   120         * Check boxes (multiple selections allowed)

   121         * Radio buttons (single selection only). For example, highlight a URL listed

   122         *   in the session History.

   123         *   No buttons (single selection only)

   124         * No buttons (single selection only), OK softkey available

   125         * For example, if you are about to download a plug-in, you can choose

   126         * to display the content in the Web page or in a viewer application.

   127         * @param aOptions A list of options to display

   128         * @return EFalse if the user canceled the dialog selection

   129         * ETrue if the user selected an option.

   130         */

   131         virtual TBool DialogSelectOptionL(const TDesC& aTitle,

   132                                           TBrCtlSelectOptionType aBrCtlSelectOptionType,

   133                                           CArrayFix<TBrCtlSelectOptionData>& aOptions) = 0;

   134 

   135         /**

   136         * User Authentication dialog.

   137         * @since 2.8

   138         * @param aUrl The url requiring authentication

   139         * @param aRealm The realm requiring authentication

   140         * @param aDefaultUserName The user name that was used before for this realm and path, if any

   141         * @param aReturnedUserName The user name entered by the user

   142         * @param aReturnedPasswd The password entered by the user

   143         * @param aBasicAuthentication ETrue if basic authentication is required.

   144         * EFalse if another type of authentication is required; for example, Digest.

   145         * Default: EFalse

   146         * @return EFalse if the user cancelled the selection

   147         * ETrue if the user selected an option.

   148         @ attiontion User name and password are returned on cleanup stack.

   149         */

   150         virtual TBool DialogUserAuthenticationLC(const TDesC& aUrl,

   151                                                  const TDesC& aRealm,

   152                                                  const TDesC& aDefaultUserName,

   153                                                  HBufC*& aReturnedUserName,

   154                                                  HBufC*& aReturnedPasswd,

   155                                                  TBool aBasicAuthentication = EFalse) = 0;

   156 

   157         /**

   158         * Displays a message to the user.

   159         * For example, the message may inform the user

   160         * about an error encountered while processing a request.

   161         * @since 2.8

   162         * @param aMessage The message to display

   163         * @return void

   164         * @attention Softkeys are not supported.

   165         * The message disappears after a time out.

   166         */

   167         virtual void DialogNoteL(const TDesC& aMessage) = 0;

   168 

   169         /**

   170         * Display a note to the user with ok softkey only

   171         * @since 2.8

   172         * @param aTitle The title, could be empty

   173         * @param aMessage The message to display

   174         * @return void

   175         * @attention The OK softkey is supported.

   176         * The message displays until the user presses OK.

   177         */

   178         virtual void DialogAlertL(const TDesC& aTitle, const TDesC& aMessage) = 0;

   179 

   180         /**

   181         * Display confirmation message to the user.

   182         * For example, Are you sure you want to delete this?

   183         * @since 2.8

   184         * @param aTitle The title, could be empty

   185         * @param aMessage The message to display

   186         * @param aYesMessage The text to display on left softkey

   187         * @param aNoMessage The text to display on right softkey

   188         * @return EFalse if the user cancelled the selection

   189         * ETrue if the user selected an option.

   190         */

   191         virtual TBool DialogConfirmL(const TDesC& aTitle,

   192                                      const TDesC& aMessage,

   193                                      const TDesC& aYesMessage,

   194                                      const TDesC& aNoMessage) = 0;

   195 

   196         /**

   197         * Displays an input dialog to the user. Asks the user to input data.

   198         * @since 2.8

   199         * @param aTitle The title, could be empty

   200         * @param aMessage The message to display

   201         * @param aDefaultInput The default input if available

   202         * @param aReturnedInput The input entered by the user.

   203         * @return EFalse if the user cancelled the selection

   204         * ETrue if the user selected an option.

   205         * @attention Returned on the cleanup stack.

   206         */

   207         virtual TBool DialogPromptLC(const TDesC& aTitle,

   208                                      const TDesC& aMessage,

   209                                      const TDesC& aDefaultInput,

   210                                      HBufC*& aReturnedInput) = 0;

   211 

   212         /**

   213         * Displays information about the Netscape plug-in object and

   214         * requests confirmation before downloading the object.

   215         * @since 2.8

   216         * @param aBrCtlObjectInfo Information about the object to be downloaded.

   217         * The following information is passes as part of this object:

   218         * Content type

   219         * Size

   220         * Flag to indicate whether a viewer application exists for this content

   221         * Flag to indicate whether a Netscape plug-in exists that supports this content

   222         * Name of the application or Netscape plug-in with which the content can

   223         * be viewed on the mobile phone

   224         * @return EFalse if the user cancelled the selection

   225         * ETrue if the user selected an option.

   226         */

   227         virtual TBool DialogDownloadObjectL(CBrCtlObjectInfo* aBrCtlObjectInfo) = 0;

   228 

   229         /**

   230         * Display the images that appear in the current page

   231         * @since 2.8

   232         * @param aPageImages Array describing the images that appear in the current page.

   233         * The array contains the following elements for each image:

   234         * Image data

   235         * URL of the image

   236         * Title for the image

   237         * Image type

   238         * If the image type is WBMP or OTA, it must be specified.

   239         * Symbian can detect any other image type.

   240         * @return void

   241         */

   242         virtual void DialogDisplayPageImagesL(CArrayFixFlat<TBrCtlImageCarrier>& aPageImages) = 0;

   243 

   244         /**

   245         * Cancels the dialog displayed due to browser exit or destroyed pages.

   246         * @since 2.8

   247         * @return void

   248         */

   249         virtual void CancelAll() = 0;

   250 

   251         /**

   252         * Displays a dialog for searching on the page.

   253         * @since 3.0

   254         * @return void

   255         */

   256        virtual void DialogFindL() = 0;

   257 

   258     };

   259 

   260 

   261 /**

   262 * The TBrCtlSelectOptionData class represents a list of elements

   263 * to display in the list box. This class is used for the List Selection Dialog.

   264 * @code

   265 *  #include <BrCtlDialogsProvider.h>

   266 * @lib BrowserEngine.lib

   267 * @since 2.8

   268 * @file BrCtlDialogsProvider.h

   269 * @endcode     *

   270 */

   271 class TBrCtlSelectOptionData

   272     {

   273     public:

   274         /**

   275         * Default Constructor

   276         * @return TbrCtlSelectOptionData object

   277         * @since 2.8

   278         */

   279         inline TBrCtlSelectOptionData()

   280                 {

   281                 iText.Set(NULL, 0);

   282                 iIsSelected = EFalse;

   283                 iIsOptGroup = EFalse;

   284                 iHasOnPick = EFalse;

   285                 }

   286 

   287         /**

   288         * Constructor

   289         * @since 2.8

   290         * @param aText The text to display with this element

   291         * @param aIsSelected If the element is selected

   292         * @param aIsOptGroup If a title of option group or an element

   293         * @param aHasOnPick If has onPick, The dialog should close when the element is selected

   294         * @return TbrCtlSelectOptionData object

   295         */

   296         inline TBrCtlSelectOptionData( const TDesC& aText,

   297                                         TBool aIsSelected,

   298                                         TBool aIsOptGroup,

   299                                         TBool aHasOnPick )

   300                                                             {

   301                                                             iText.Set(aText);

   302                                                             iIsSelected = aIsSelected;

   303                                                             iIsOptGroup = aIsOptGroup;

   304                                                             iHasOnPick = aHasOnPick;

   305                                                             }

   306         /**

   307         * Gets the display text associated with a specified option.

   308         * @since 2.8

   309         * @return A reference to a Symbian TDesC object that

   310         * contains the text associated with this option.

   311         */

   312         inline const TDesC& Text() const {return iText;}

   313         /**

   314         * Indicates whether or not an option is selected.

   315         * @since 2.8

   316         * @return ETrue if the option is selected

   317         * EFalse if the option is not selected

   318         */

   319         inline TBool IsSelected() const {return iIsSelected;}

   320         /**

   321         * Indicates whether an option group member

   322         * variable is a group title or a selectable option.

   323         * @since 2.8

   324         * @return ETrue if the listed item is the title of an option group

   325         * EFalse if the listed item is one of the options from which to select

   326         */

   327         inline TBool IsOptGroup() const {return iIsOptGroup;}

   328         /**

   329         * Indicates whether or not the dialog closes when an option is selected.

   330         * @since 2.8

   331         * @return ETrue if the dialog closes when the element is selected.

   332         * This is known as having OnPick capability.

   333         * EFalse if the dialog does not close when the element is selected

   334         */

   335         inline TBool HasOnPick() const {return iHasOnPick;}

   336         /**

   337         * Sets the text of the option object.

   338         * @since 2.8

   339         * @param aText A reference to a TDesC object that contains the

   340         * text to associate with a particular option.

   341         * @return None

   342         */

   343 

   344         inline void SetText( TDesC& aText )             { iText.Set( aText ); }

   345         /**

   346         * Sets the selection state of an option.

   347         * @since 2.8

   348         * @param aIsSelected The state of the IsSelected member variable.

   349         * Value:

   350         * ETrue if the option is selected

   351         * EFalse if the option is not selected

   352         * @return None

   353         */

   354         inline void SetIsSelected( TBool aIsSelected )  { iIsSelected = aIsSelected; }

   355         /**

   356         * Sets the state of the option group member variable.

   357         * Indicates whether an option group member variable is a group title

   358         * or a selectable option.

   359         * @since 2.8

   360         * @param aIsOptGroup The state of the option group.

   361         * Value:

   362         * ETrue if the listed item is the title of an option group.

   363         * EFalse if the listed item is one of the options from which to select.

   364         * @return None

   365         */

   366         inline void SetIsOptGroup( TBool aIsOptGroup )  { iIsOptGroup = aIsOptGroup; }

   367         /**

   368         * Sets the state of the hasOnPick member variable.

   369         * Indicates whether or not the dialog closes when an option is selected.

   370         * @since 2.8

   371         * @param aHasOnPick

   372         * ETrue if the dialog closes when the element is selected. This

   373         * is known as having OnPick capability.

   374         * EFalse if the dialog does not close when the element is selected

   375         * @return None

   376         */

   377         inline void SetHasOnPick( TBool aHasOnPick )    { iHasOnPick = aHasOnPick; }

   378 

   379     private:    // Data

   380         // The text associated with the element

   381         TPtrC iText;

   382         // Flag if the element is selected

   383         TBool iIsSelected;

   384         // Flag if an element or oprion group title

   385         TBool iIsOptGroup;

   386         // Flag if the element has onPick

   387         TBool iHasOnPick;

   388     };

   389 

   390 /**

   391 * The CBrCtlObjectInfo class used to represent the information about the

   392 * plugin object.

   393 * @code

   394 *  #include <BrCtlDialogsProvider.h>

   395 * @lib BrowserEngine.lib

   396 * @since 3.0

   397 * @file BrCtlDialogsProvider.h

   398 * @endcode     *

   399 */

   400 class CBrCtlObjectInfo : public CBase

   401   {

   402   public:

   403         /**

   404         * Default Constructor

   405         * @since 2.8

   406         */

   407         CBrCtlObjectInfo();

   408 

   409         /**

   410         * Constructor

   411         * @since 3.0

   412         * @param aAppSupported A flag if there is a viewer app for this object

   413         * @param aPluginSupported A flag if there is a netscape plugin for this object

   414         * @param aSize The size of the object

   415         * @param aAppName The name of the viewer app or netscape plugin that supports this object

   416         * @param aFileType The content type of the object

   417         * @return CBrCtlObjectInfo object

   418         */

   419     CBrCtlObjectInfo(TBool aAppSupported, TBool aPluginSupported,

   420                          const TDesC& aSize, const TDesC& aAppName,

   421                          const TDesC& aFileType);

   422   public:

   423         /**

   424         * Sets the flag if there is a viewer app for this object

   425         * @since 3.0

   426         * @param aAppSupported ETrue if there is a viewer app for this object

   427         * EFalse if there is not a viewer app for this object.

   428         * @return None

   429         */

   430         inline void SetAppSupported(TBool aAppSupported) {iAppSupported = aAppSupported;}

   431         /**

   432         * Sets the flag if there is a netscape plugin for this object

   433         * @since 3.0

   434         * @param aPluginSupported ETrue if there is a netscape plugin for this object

   435         * EFalse if there is not a netscape plugin for this object.

   436         * @return None

   437         */

   438         inline void SetPluginSupported(TBool aPluginSupported) {iPluginSupported = aPluginSupported;}

   439         /**

   440         * Sets the size of the object

   441         * @since 3.0

   442         * @param aSize Symbian descriptor containing the size of the object

   443         * @return None

   444         */

   445         inline void SetSize(const TDesC& aSize) {iSize.Set(aSize);}

   446         /**

   447         * Sets the name of the viewer app or netscape plugin that supports this object

   448         * @since 3.0

   449         * @param aAppName  Symbian descriptor containing the name of

   450         * the viewer app or netscape plugin that supports this object.

   451         * @return None

   452         */

   453     inline void SetAppName(const TDesC& aAppName) {iAppName.Set(aAppName);}

   454         /**

   455         * Sets the content type of the object

   456         * @since 3.0

   457         * @param aFileType Symbian descriptor holding content type of the object

   458         * @return None

   459         */

   460     inline void SetFileType(const TDesC& aFileType) {iFileType.Set(aFileType);}

   461         /**

   462         * Tells if there is a viewer app for this object

   463         * @since 3.0

   464         * @param None

   465         * @return  ETrue if there is a viewer app for this object

   466         * EFalse if there is not a viewer app for this object.

   467         */

   468         inline TBool AppSupported() {return iAppSupported;}

   469         /**

   470         * Tells if there is a netscape plugin for this object

   471         * @since 3.0

   472         * @param None

   473         * @return ETrue if there is a netscape plugin for this object

   474         * EFalse if there is not a netscape plugin for this object.

   475         */

   476         inline TBool PluginSupported() {return iPluginSupported;}

   477         /**

   478         * Gets the size of the object

   479         * @since 3.0

   480         * @param None

   481         * @return Symbian descriptor containing the size of the object

   482         */

   483         inline const TDesC& Size() const {return iSize;}

   484         /**

   485         * Gets the name of the viewer app or netscape plugin that supports this object

   486         * @since 3.0

   487         * @param None

   488         * @return Symbian descriptor containing the name of

   489         * the viewer app or netscape plugin that supports this object.

   490         */

   491     inline const TDesC& AppName() const {return iAppName;}

   492         /**

   493         * Gets the content type of the object

   494         * @since 3.0

   495         * @param None

   496         * @return Symbian descriptor holding content type of the object

   497         */

   498     inline const TDesC& FileType() const {return iFileType;}

   499   private:

   500     // A flag if there is a viewer app for this object

   501         TBool iAppSupported;

   502         // A flag if there is a Netscape plugin for this object

   503     TBool iPluginSupported;

   504         // The size of the object

   505     TPtrC iSize;

   506         // The name of the viewer app or Netscape plugin

   507     TPtrC iAppName;

   508         // The content type of the object

   509     TPtrC iFileType;

   510   };

   511 

   512 /**

   513 * TheTBrCtlImageCarrier class used to give the information about the

   514 * image.

   515 * @code

   516 *  #include <BrCtlDialogsProvider.h>

   517 * @lib BrowserEngine.lib

   518 * @since 2.8

   519 * @file BrCtlDialogsProvider.h

   520 * @endcode     *

   521 */

   522 class TBrCtlImageCarrier

   523     {

   524     public:

   525         /**

   526         * Constructor

   527         * @since 2.8

   528         * @param aRawData The image data

   529         * @param aUrl The url of the image

   530         * @param aAltText The alt text of the image

   531         * @param aImageType The type of the image

   532         */

   533         TBrCtlImageCarrier(const TDesC8& aRawData, const TDesC& aUrl,

   534             const TDesC& aAltText, TBrCtlImageType aImageType, const TDesC& aContentType ) :

   535             iRawData( aRawData ),

   536             iUrl( aUrl ),

   537             iAltText( aAltText ),

   538             iImageType(aImageType),

   539       iContentType(aContentType)

   540             {

   541             }

   542         /**

   543         * Provides the image data

   544         * @since 3.0

   545         * @param None

   546         * @return Symbian descriptor containing image data

   547         */

   548         inline const TDesC8& RawData() const {return iRawData;}

   549         /**

   550         * Provides the url of the image

   551         * @since 3.0

   552         * @param None

   553         * @return Symbian descriptor containing url of the image

   554         */

   555         inline const TDesC& Url() const {return iUrl;}

   556         /**

   557         * Provides the alt text of the image

   558         * @since 3.0

   559         * @param None

   560         * @return Symbian descriptor containing alt text of the image

   561         */

   562         inline const TDesC& AltText() const {return iAltText;}

   563         /**

   564         * Provides the type of the image

   565         * @since 3.0

   566         * @param None

   567         * @return Symbian descriptor containing the type of the image

   568         */

   569         inline TBrCtlImageType ImageType() const {return iImageType;}

   570         /**

   571         * Provides the content type of the image

   572         * @since 3.1

   573         * @param None

   574         * @return Symbian descriptor containing content type of the image

   575         */

   576         inline const TDesC& ContentType() const {return iContentType;}

   577     private:

   578         TPtrC8 iRawData;

   579         TPtrC iUrl;

   580         TPtrC iAltText;

   581         TBrCtlImageType iImageType;

   582     TPtrC iContentType;

   583     };

   584 

   585 

   586 #endif      // BRCTLDIALOGSPROVIDER_H

   587 

   588 // End of File