1.1 --- a/epoc32/include/mw/brctldialogsprovider.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/brctldialogsprovider.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,588 @@
1.4 -brctldialogsprovider.h
1.5 +/*
1.6 +* Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* under the terms of the License "Eclipse Public License v1.0"
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Handle dialogs needed for browser operation
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef BRCTLDIALOGSPROVIDER_H
1.24 +#define BRCTLDIALOGSPROVIDER_H
1.25 +
1.26 +// INCLUDES
1.27 +#include <e32std.h>
1.28 +#include <e32base.h>
1.29 +
1.30 +/**
1.31 +* Type of selection list
1.32 +*/
1.33 +enum TBrCtlSelectOptionType
1.34 + {
1.35 + ESelectTypeMultiple, ///< Multiple select - Display a checkbox
1.36 + ESelectTypeSingle, ///< Single select - Display a radio button
1.37 + ESelectTypeNone, ///< Single select - Do not display any button
1.38 + /**
1.39 + * No buttons (single selection only)
1.40 + * OK softkey is available
1.41 + * Cancel button is not available
1.42 + */
1.43 + ESelectTypeOkOnly
1.44 + };
1.45 +
1.46 +/**
1.47 +* Defines the type of image if it cannot be recognized by the
1.48 +* Symbian image conversion library.
1.49 +*/
1.50 +
1.51 +enum TBrCtlImageType
1.52 + {
1.53 + EImageTypeAny, ///< Automatically recognized by the image converter
1.54 + EImageTypeWbmp, ///< Wireless Bitmap (WBMP) image
1.55 + EImageTypeOta ///< Over The Air (OTA) image
1.56 + };
1.57 +
1.58 +
1.59 +// FORWARD DECLARATIONS
1.60 +class TBrCtlSelectOptionData;
1.61 +class CBrCtlObjectInfo;
1.62 +class TBrCtlImageCarrier;
1.63 +
1.64 +/**
1.65 +* The MBrDialogsProvider class provides functions implemented by
1.66 +* the Browser Control to display dialogs, such as error notifications,
1.67 +* authentication requests, and selection lists.
1.68 +*
1.69 +* Usage:
1.70 +*
1.71 +* @code
1.72 +* #include <BrCtlDialogsProvider.h>
1.73 +*
1.74 +*
1.75 +* @see S60 Platform: Browser Control API Developer's Guide Version 2.0
1.76 +* @lib BrowserEngine.lib
1.77 +* @file BrCtlDialogsProvider.h
1.78 +* @endcode *
1.79 +*/
1.80 +class MBrCtlDialogsProvider
1.81 + {
1.82 + public: // New functions
1.83 +
1.84 + /**
1.85 + * Notifies the user of an error encountered during a download.
1.86 + * Some examples are: insufficient memory, unrecognized URL, and DNS not found.
1.87 + * @since 2.8
1.88 + * @param aErrCode The error that occured
1.89 + * @return void
1.90 + */
1.91 + virtual void DialogNotifyErrorL(TInt aErrCode) = 0;
1.92 +
1.93 + /**
1.94 + * Notifies the user of an error from the HTTP server
1.95 + * during a download. Some examples are: file not found, redirect error.
1.96 + * @since 2.8
1.97 + * @param aErrCode The error that occured
1.98 + * @param aUri The uri of the request that failed
1.99 + * @return void
1.100 + */
1.101 + virtual void DialogNotifyHttpErrorL(TInt aErrCode, const TDesC& aUri) = 0;
1.102 +
1.103 + /**
1.104 + * Navigates through your file system and selects a file;
1.105 + * analogous to the Browse command in Windows.
1.106 + * @since 2.8
1.107 + * @param aStartPath The initial displayed directory
1.108 + * @param aRootPath The top most directory that the user can go up to
1.109 + * @param aSelectedFileName The selected file name.
1.110 + * @return ETrue if the user selected a file
1.111 + * EFalse if the user cancelled the transaction and did not select a file.
1.112 + * @attiontion Returned on cleanup stack. Browser control will free the buffer.
1.113 + */
1.114 + virtual TBool DialogFileSelectLC(const TDesC& aStartPath,
1.115 + const TDesC& aRootPath,
1.116 + HBufC*& aSelectedFileName) = 0;
1.117 +
1.118 + /**
1.119 + * List selection dialog
1.120 + * @since 2.8
1.121 + * @param Title of the selection dialog. This is optional.
1.122 + * @param aBrCtlSelectOptionType The type of the list box.
1.123 + * Values: One of the following:
1.124 + * Check boxes (multiple selections allowed)
1.125 + * Radio buttons (single selection only). For example, highlight a URL listed
1.126 + * in the session History.
1.127 + * No buttons (single selection only)
1.128 + * No buttons (single selection only), OK softkey available
1.129 + * For example, if you are about to download a plug-in, you can choose
1.130 + * to display the content in the Web page or in a viewer application.
1.131 + * @param aOptions A list of options to display
1.132 + * @return EFalse if the user canceled the dialog selection
1.133 + * ETrue if the user selected an option.
1.134 + */
1.135 + virtual TBool DialogSelectOptionL(const TDesC& aTitle,
1.136 + TBrCtlSelectOptionType aBrCtlSelectOptionType,
1.137 + CArrayFix<TBrCtlSelectOptionData>& aOptions) = 0;
1.138 +
1.139 + /**
1.140 + * User Authentication dialog.
1.141 + * @since 2.8
1.142 + * @param aUrl The url requiring authentication
1.143 + * @param aRealm The realm requiring authentication
1.144 + * @param aDefaultUserName The user name that was used before for this realm and path, if any
1.145 + * @param aReturnedUserName The user name entered by the user
1.146 + * @param aReturnedPasswd The password entered by the user
1.147 + * @param aBasicAuthentication ETrue if basic authentication is required.
1.148 + * EFalse if another type of authentication is required; for example, Digest.
1.149 + * Default: EFalse
1.150 + * @return EFalse if the user cancelled the selection
1.151 + * ETrue if the user selected an option.
1.152 + @ attiontion User name and password are returned on cleanup stack.
1.153 + */
1.154 + virtual TBool DialogUserAuthenticationLC(const TDesC& aUrl,
1.155 + const TDesC& aRealm,
1.156 + const TDesC& aDefaultUserName,
1.157 + HBufC*& aReturnedUserName,
1.158 + HBufC*& aReturnedPasswd,
1.159 + TBool aBasicAuthentication = EFalse) = 0;
1.160 +
1.161 + /**
1.162 + * Displays a message to the user.
1.163 + * For example, the message may inform the user
1.164 + * about an error encountered while processing a request.
1.165 + * @since 2.8
1.166 + * @param aMessage The message to display
1.167 + * @return void
1.168 + * @attention Softkeys are not supported.
1.169 + * The message disappears after a time out.
1.170 + */
1.171 + virtual void DialogNoteL(const TDesC& aMessage) = 0;
1.172 +
1.173 + /**
1.174 + * Display a note to the user with ok softkey only
1.175 + * @since 2.8
1.176 + * @param aTitle The title, could be empty
1.177 + * @param aMessage The message to display
1.178 + * @return void
1.179 + * @attention The OK softkey is supported.
1.180 + * The message displays until the user presses OK.
1.181 + */
1.182 + virtual void DialogAlertL(const TDesC& aTitle, const TDesC& aMessage) = 0;
1.183 +
1.184 + /**
1.185 + * Display confirmation message to the user.
1.186 + * For example, Are you sure you want to delete this?
1.187 + * @since 2.8
1.188 + * @param aTitle The title, could be empty
1.189 + * @param aMessage The message to display
1.190 + * @param aYesMessage The text to display on left softkey
1.191 + * @param aNoMessage The text to display on right softkey
1.192 + * @return EFalse if the user cancelled the selection
1.193 + * ETrue if the user selected an option.
1.194 + */
1.195 + virtual TBool DialogConfirmL(const TDesC& aTitle,
1.196 + const TDesC& aMessage,
1.197 + const TDesC& aYesMessage,
1.198 + const TDesC& aNoMessage) = 0;
1.199 +
1.200 + /**
1.201 + * Displays an input dialog to the user. Asks the user to input data.
1.202 + * @since 2.8
1.203 + * @param aTitle The title, could be empty
1.204 + * @param aMessage The message to display
1.205 + * @param aDefaultInput The default input if available
1.206 + * @param aReturnedInput The input entered by the user.
1.207 + * @return EFalse if the user cancelled the selection
1.208 + * ETrue if the user selected an option.
1.209 + * @attention Returned on the cleanup stack.
1.210 + */
1.211 + virtual TBool DialogPromptLC(const TDesC& aTitle,
1.212 + const TDesC& aMessage,
1.213 + const TDesC& aDefaultInput,
1.214 + HBufC*& aReturnedInput) = 0;
1.215 +
1.216 + /**
1.217 + * Displays information about the Netscape plug-in object and
1.218 + * requests confirmation before downloading the object.
1.219 + * @since 2.8
1.220 + * @param aBrCtlObjectInfo Information about the object to be downloaded.
1.221 + * The following information is passes as part of this object:
1.222 + * Content type
1.223 + * Size
1.224 + * Flag to indicate whether a viewer application exists for this content
1.225 + * Flag to indicate whether a Netscape plug-in exists that supports this content
1.226 + * Name of the application or Netscape plug-in with which the content can
1.227 + * be viewed on the mobile phone
1.228 + * @return EFalse if the user cancelled the selection
1.229 + * ETrue if the user selected an option.
1.230 + */
1.231 + virtual TBool DialogDownloadObjectL(CBrCtlObjectInfo* aBrCtlObjectInfo) = 0;
1.232 +
1.233 + /**
1.234 + * Display the images that appear in the current page
1.235 + * @since 2.8
1.236 + * @param aPageImages Array describing the images that appear in the current page.
1.237 + * The array contains the following elements for each image:
1.238 + * Image data
1.239 + * URL of the image
1.240 + * Title for the image
1.241 + * Image type
1.242 + * If the image type is WBMP or OTA, it must be specified.
1.243 + * Symbian can detect any other image type.
1.244 + * @return void
1.245 + */
1.246 + virtual void DialogDisplayPageImagesL(CArrayFixFlat<TBrCtlImageCarrier>& aPageImages) = 0;
1.247 +
1.248 + /**
1.249 + * Cancels the dialog displayed due to browser exit or destroyed pages.
1.250 + * @since 2.8
1.251 + * @return void
1.252 + */
1.253 + virtual void CancelAll() = 0;
1.254 +
1.255 + /**
1.256 + * Displays a dialog for searching on the page.
1.257 + * @since 3.0
1.258 + * @return void
1.259 + */
1.260 + virtual void DialogFindL() = 0;
1.261 +
1.262 + };
1.263 +
1.264 +
1.265 +/**
1.266 +* The TBrCtlSelectOptionData class represents a list of elements
1.267 +* to display in the list box. This class is used for the List Selection Dialog.
1.268 +* @code
1.269 +* #include <BrCtlDialogsProvider.h>
1.270 +* @lib BrowserEngine.lib
1.271 +* @since 2.8
1.272 +* @file BrCtlDialogsProvider.h
1.273 +* @endcode *
1.274 +*/
1.275 +class TBrCtlSelectOptionData
1.276 + {
1.277 + public:
1.278 + /**
1.279 + * Default Constructor
1.280 + * @return TbrCtlSelectOptionData object
1.281 + * @since 2.8
1.282 + */
1.283 + inline TBrCtlSelectOptionData()
1.284 + {
1.285 + iText.Set(NULL, 0);
1.286 + iIsSelected = EFalse;
1.287 + iIsOptGroup = EFalse;
1.288 + iHasOnPick = EFalse;
1.289 + }
1.290 +
1.291 + /**
1.292 + * Constructor
1.293 + * @since 2.8
1.294 + * @param aText The text to display with this element
1.295 + * @param aIsSelected If the element is selected
1.296 + * @param aIsOptGroup If a title of option group or an element
1.297 + * @param aHasOnPick If has onPick, The dialog should close when the element is selected
1.298 + * @return TbrCtlSelectOptionData object
1.299 + */
1.300 + inline TBrCtlSelectOptionData( const TDesC& aText,
1.301 + TBool aIsSelected,
1.302 + TBool aIsOptGroup,
1.303 + TBool aHasOnPick )
1.304 + {
1.305 + iText.Set(aText);
1.306 + iIsSelected = aIsSelected;
1.307 + iIsOptGroup = aIsOptGroup;
1.308 + iHasOnPick = aHasOnPick;
1.309 + }
1.310 + /**
1.311 + * Gets the display text associated with a specified option.
1.312 + * @since 2.8
1.313 + * @return A reference to a Symbian TDesC object that
1.314 + * contains the text associated with this option.
1.315 + */
1.316 + inline const TDesC& Text() const {return iText;}
1.317 + /**
1.318 + * Indicates whether or not an option is selected.
1.319 + * @since 2.8
1.320 + * @return ETrue if the option is selected
1.321 + * EFalse if the option is not selected
1.322 + */
1.323 + inline TBool IsSelected() const {return iIsSelected;}
1.324 + /**
1.325 + * Indicates whether an option group member
1.326 + * variable is a group title or a selectable option.
1.327 + * @since 2.8
1.328 + * @return ETrue if the listed item is the title of an option group
1.329 + * EFalse if the listed item is one of the options from which to select
1.330 + */
1.331 + inline TBool IsOptGroup() const {return iIsOptGroup;}
1.332 + /**
1.333 + * Indicates whether or not the dialog closes when an option is selected.
1.334 + * @since 2.8
1.335 + * @return ETrue if the dialog closes when the element is selected.
1.336 + * This is known as having OnPick capability.
1.337 + * EFalse if the dialog does not close when the element is selected
1.338 + */
1.339 + inline TBool HasOnPick() const {return iHasOnPick;}
1.340 + /**
1.341 + * Sets the text of the option object.
1.342 + * @since 2.8
1.343 + * @param aText A reference to a TDesC object that contains the
1.344 + * text to associate with a particular option.
1.345 + * @return None
1.346 + */
1.347 +
1.348 + inline void SetText( TDesC& aText ) { iText.Set( aText ); }
1.349 + /**
1.350 + * Sets the selection state of an option.
1.351 + * @since 2.8
1.352 + * @param aIsSelected The state of the IsSelected member variable.
1.353 + * Value:
1.354 + * ETrue if the option is selected
1.355 + * EFalse if the option is not selected
1.356 + * @return None
1.357 + */
1.358 + inline void SetIsSelected( TBool aIsSelected ) { iIsSelected = aIsSelected; }
1.359 + /**
1.360 + * Sets the state of the option group member variable.
1.361 + * Indicates whether an option group member variable is a group title
1.362 + * or a selectable option.
1.363 + * @since 2.8
1.364 + * @param aIsOptGroup The state of the option group.
1.365 + * Value:
1.366 + * ETrue if the listed item is the title of an option group.
1.367 + * EFalse if the listed item is one of the options from which to select.
1.368 + * @return None
1.369 + */
1.370 + inline void SetIsOptGroup( TBool aIsOptGroup ) { iIsOptGroup = aIsOptGroup; }
1.371 + /**
1.372 + * Sets the state of the hasOnPick member variable.
1.373 + * Indicates whether or not the dialog closes when an option is selected.
1.374 + * @since 2.8
1.375 + * @param aHasOnPick
1.376 + * ETrue if the dialog closes when the element is selected. This
1.377 + * is known as having OnPick capability.
1.378 + * EFalse if the dialog does not close when the element is selected
1.379 + * @return None
1.380 + */
1.381 + inline void SetHasOnPick( TBool aHasOnPick ) { iHasOnPick = aHasOnPick; }
1.382 +
1.383 + private: // Data
1.384 + // The text associated with the element
1.385 + TPtrC iText;
1.386 + // Flag if the element is selected
1.387 + TBool iIsSelected;
1.388 + // Flag if an element or oprion group title
1.389 + TBool iIsOptGroup;
1.390 + // Flag if the element has onPick
1.391 + TBool iHasOnPick;
1.392 + };
1.393 +
1.394 +/**
1.395 +* The CBrCtlObjectInfo class used to represent the information about the
1.396 +* plugin object.
1.397 +* @code
1.398 +* #include <BrCtlDialogsProvider.h>
1.399 +* @lib BrowserEngine.lib
1.400 +* @since 3.0
1.401 +* @file BrCtlDialogsProvider.h
1.402 +* @endcode *
1.403 +*/
1.404 +class CBrCtlObjectInfo : public CBase
1.405 + {
1.406 + public:
1.407 + /**
1.408 + * Default Constructor
1.409 + * @since 2.8
1.410 + */
1.411 + CBrCtlObjectInfo();
1.412 +
1.413 + /**
1.414 + * Constructor
1.415 + * @since 3.0
1.416 + * @param aAppSupported A flag if there is a viewer app for this object
1.417 + * @param aPluginSupported A flag if there is a netscape plugin for this object
1.418 + * @param aSize The size of the object
1.419 + * @param aAppName The name of the viewer app or netscape plugin that supports this object
1.420 + * @param aFileType The content type of the object
1.421 + * @return CBrCtlObjectInfo object
1.422 + */
1.423 + CBrCtlObjectInfo(TBool aAppSupported, TBool aPluginSupported,
1.424 + const TDesC& aSize, const TDesC& aAppName,
1.425 + const TDesC& aFileType);
1.426 + public:
1.427 + /**
1.428 + * Sets the flag if there is a viewer app for this object
1.429 + * @since 3.0
1.430 + * @param aAppSupported ETrue if there is a viewer app for this object
1.431 + * EFalse if there is not a viewer app for this object.
1.432 + * @return None
1.433 + */
1.434 + inline void SetAppSupported(TBool aAppSupported) {iAppSupported = aAppSupported;}
1.435 + /**
1.436 + * Sets the flag if there is a netscape plugin for this object
1.437 + * @since 3.0
1.438 + * @param aPluginSupported ETrue if there is a netscape plugin for this object
1.439 + * EFalse if there is not a netscape plugin for this object.
1.440 + * @return None
1.441 + */
1.442 + inline void SetPluginSupported(TBool aPluginSupported) {iPluginSupported = aPluginSupported;}
1.443 + /**
1.444 + * Sets the size of the object
1.445 + * @since 3.0
1.446 + * @param aSize Symbian descriptor containing the size of the object
1.447 + * @return None
1.448 + */
1.449 + inline void SetSize(const TDesC& aSize) {iSize.Set(aSize);}
1.450 + /**
1.451 + * Sets the name of the viewer app or netscape plugin that supports this object
1.452 + * @since 3.0
1.453 + * @param aAppName Symbian descriptor containing the name of
1.454 + * the viewer app or netscape plugin that supports this object.
1.455 + * @return None
1.456 + */
1.457 + inline void SetAppName(const TDesC& aAppName) {iAppName.Set(aAppName);}
1.458 + /**
1.459 + * Sets the content type of the object
1.460 + * @since 3.0
1.461 + * @param aFileType Symbian descriptor holding content type of the object
1.462 + * @return None
1.463 + */
1.464 + inline void SetFileType(const TDesC& aFileType) {iFileType.Set(aFileType);}
1.465 + /**
1.466 + * Tells if there is a viewer app for this object
1.467 + * @since 3.0
1.468 + * @param None
1.469 + * @return ETrue if there is a viewer app for this object
1.470 + * EFalse if there is not a viewer app for this object.
1.471 + */
1.472 + inline TBool AppSupported() {return iAppSupported;}
1.473 + /**
1.474 + * Tells if there is a netscape plugin for this object
1.475 + * @since 3.0
1.476 + * @param None
1.477 + * @return ETrue if there is a netscape plugin for this object
1.478 + * EFalse if there is not a netscape plugin for this object.
1.479 + */
1.480 + inline TBool PluginSupported() {return iPluginSupported;}
1.481 + /**
1.482 + * Gets the size of the object
1.483 + * @since 3.0
1.484 + * @param None
1.485 + * @return Symbian descriptor containing the size of the object
1.486 + */
1.487 + inline const TDesC& Size() const {return iSize;}
1.488 + /**
1.489 + * Gets the name of the viewer app or netscape plugin that supports this object
1.490 + * @since 3.0
1.491 + * @param None
1.492 + * @return Symbian descriptor containing the name of
1.493 + * the viewer app or netscape plugin that supports this object.
1.494 + */
1.495 + inline const TDesC& AppName() const {return iAppName;}
1.496 + /**
1.497 + * Gets the content type of the object
1.498 + * @since 3.0
1.499 + * @param None
1.500 + * @return Symbian descriptor holding content type of the object
1.501 + */
1.502 + inline const TDesC& FileType() const {return iFileType;}
1.503 + private:
1.504 + // A flag if there is a viewer app for this object
1.505 + TBool iAppSupported;
1.506 + // A flag if there is a Netscape plugin for this object
1.507 + TBool iPluginSupported;
1.508 + // The size of the object
1.509 + TPtrC iSize;
1.510 + // The name of the viewer app or Netscape plugin
1.511 + TPtrC iAppName;
1.512 + // The content type of the object
1.513 + TPtrC iFileType;
1.514 + };
1.515 +
1.516 +/**
1.517 +* TheTBrCtlImageCarrier class used to give the information about the
1.518 +* image.
1.519 +* @code
1.520 +* #include <BrCtlDialogsProvider.h>
1.521 +* @lib BrowserEngine.lib
1.522 +* @since 2.8
1.523 +* @file BrCtlDialogsProvider.h
1.524 +* @endcode *
1.525 +*/
1.526 +class TBrCtlImageCarrier
1.527 + {
1.528 + public:
1.529 + /**
1.530 + * Constructor
1.531 + * @since 2.8
1.532 + * @param aRawData The image data
1.533 + * @param aUrl The url of the image
1.534 + * @param aAltText The alt text of the image
1.535 + * @param aImageType The type of the image
1.536 + */
1.537 + TBrCtlImageCarrier(const TDesC8& aRawData, const TDesC& aUrl,
1.538 + const TDesC& aAltText, TBrCtlImageType aImageType, const TDesC& aContentType ) :
1.539 + iRawData( aRawData ),
1.540 + iUrl( aUrl ),
1.541 + iAltText( aAltText ),
1.542 + iImageType(aImageType),
1.543 + iContentType(aContentType)
1.544 + {
1.545 + }
1.546 + /**
1.547 + * Provides the image data
1.548 + * @since 3.0
1.549 + * @param None
1.550 + * @return Symbian descriptor containing image data
1.551 + */
1.552 + inline const TDesC8& RawData() const {return iRawData;}
1.553 + /**
1.554 + * Provides the url of the image
1.555 + * @since 3.0
1.556 + * @param None
1.557 + * @return Symbian descriptor containing url of the image
1.558 + */
1.559 + inline const TDesC& Url() const {return iUrl;}
1.560 + /**
1.561 + * Provides the alt text of the image
1.562 + * @since 3.0
1.563 + * @param None
1.564 + * @return Symbian descriptor containing alt text of the image
1.565 + */
1.566 + inline const TDesC& AltText() const {return iAltText;}
1.567 + /**
1.568 + * Provides the type of the image
1.569 + * @since 3.0
1.570 + * @param None
1.571 + * @return Symbian descriptor containing the type of the image
1.572 + */
1.573 + inline TBrCtlImageType ImageType() const {return iImageType;}
1.574 + /**
1.575 + * Provides the content type of the image
1.576 + * @since 3.1
1.577 + * @param None
1.578 + * @return Symbian descriptor containing content type of the image
1.579 + */
1.580 + inline const TDesC& ContentType() const {return iContentType;}
1.581 + private:
1.582 + TPtrC8 iRawData;
1.583 + TPtrC iUrl;
1.584 + TPtrC iAltText;
1.585 + TBrCtlImageType iImageType;
1.586 + TPtrC iContentType;
1.587 + };
1.588 +
1.589 +
1.590 +#endif // BRCTLDIALOGSPROVIDER_H
1.591 +
1.592 +// End of File