--- a/epoc32/include/mw/brctldialogsprovider.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/brctldialogsprovider.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,588 @@
-brctldialogsprovider.h
+/*
+* 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