1.1 --- a/epoc32/include/mw/brctlinterface.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/brctlinterface.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,975 @@
1.4 -brctlinterface.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: Definition of the Browser Control API
1.19 +*
1.20 +*/
1.21 +
1.22 +
1.23 +#ifndef BRCTLINTERFACE_H
1.24 +#define BRCTLINTERFACE_H
1.25 +
1.26 +// INCLUDES
1.27 +#include <../bidi.h>
1.28 +#include <e32std.h>
1.29 +#include <e32base.h>
1.30 +#include <coecntrl.h>
1.31 +#include <eikmenup.h>
1.32 +#include <ssl.h>
1.33 +
1.34 +#include <BrCtlDialogsProvider.h>
1.35 +#include <BrCtlLayoutObserver.h>
1.36 +#include <BrCtlLinkResolver.h>
1.37 +#include <BrCtlSoftkeysObserver.h>
1.38 +#include <BrCtlSpecialLoadObserver.h>
1.39 +#include <BrCtlWindowObserver.h>
1.40 +#include <BrCtlDownloadObserver.h>
1.41 +#include <BrCtlDefs.h>
1.42 +
1.43 +// DATA TYPES
1.44 +
1.45 +// FORWARD DECLARATIONS
1.46 +class MBrCtlDataLoadSupplier;
1.47 +class MBrCtlDataLoadConsumer;
1.48 +class MBrCtlLoadEventObserver;
1.49 +class MBrCtlDialogsProvider;
1.50 +class TBrCtlWmlServiceOption;
1.51 +class TBrCtlSubscribeTo;
1.52 +class MBrCtlStateChangeObserver;
1.53 +class MBrCtlCommandObserver;
1.54 +class MWidgetCallback;
1.55 +class MWidgetExtension;
1.56 +class CBrCtlInterface;
1.57 +class CPluginInfo;
1.58 +class TBrCtlImageCarrier;
1.59 +
1.60 +/**
1.61 +* Creates the browser control.
1.62 +*
1.63 +* @param aParent Parent window of the browser control
1.64 +* @param aRect Bounding rectangle for the browser control
1.65 +* @param aBrCtlCapabilities Desired capabilities of the browser control.
1.66 +* For example, displaying scroll bars, allowing network access for HTTP requests.
1.67 +* @see For a complete list of capability options, see TBrCtlCapabilities
1.68 +* @param aCommandIdBase Base values for Command IDs for Browser Control.
1.69 +* These are added to ensure that each Command ID is unique; Browser Control command IDs must be different from the host application command IDs.
1.70 +* @see For more information, see TBrCtlCommandId
1.71 +* @param aBrCtlSoftkeysObserver Softkeys observer.
1.72 +* Default: the host application does not update the softkeys.
1.73 +* @see For more information, see MBrCtlSoftkeysObserver class
1.74 +* @param aBrCtlLinkResolver Link Resolver. Must be provided if ECapabilityClient
1.75 +* ResolveEmbeddedURL or ECapabilityClientNotifyURL is set.
1.76 +* @see For more information, see MBrCtlLinkResolver class.
1.77 +* @param aBrCtlSpecialLoadObserver Special Load Observer.
1.78 +* @see MBrCtlSpecialLoadObserver class for more details of special load observer.
1.79 +* @param aBrCtlLayoutObserver Layout Observer.
1.80 +* Default:
1.81 +* Non-markup pages are not handled by the browser.
1.82 +* Non-HTTP(S) schemes are not handled by the browser.
1.83 +* Connection is created by the Proxy Filter.
1.84 +* @see For more information, see MBrCtlLayoutObserver class
1.85 +* @param aBrCtlDialogsProvider Dialogs Provider.
1.86 +* @see For more information, see MBrCtlDialogsProvider class
1.87 +* @param aBrCtlWindowObserver Window Observer.
1.88 +* @see For more information, see MBrCtlWindowObserver class
1.89 +* @param aBrCtlDownloadObserver Downlaod observer
1.90 +* @see For more information, MBrCtlDownloadObserver class
1.91 +* @return a pointer to CBrCtlInterface class or NULL if this function fails.
1.92 +*/
1.93 +IMPORT_C CBrCtlInterface* CreateBrowserControlL(CCoeControl* aParent, TRect aRect,
1.94 + TUint aBrCtlCapabilities, TUint aCommandIdBase = TBrCtlDefs::ECommandIdBase,
1.95 + MBrCtlSoftkeysObserver* aBrCtlSoftkeysObserver = NULL,
1.96 + MBrCtlLinkResolver* aBrCtlLinkResolver = NULL,
1.97 + MBrCtlSpecialLoadObserver* aBrCtlSpecialLoadObserver = NULL,
1.98 + MBrCtlLayoutObserver* aBrCtlLayoutObserver = NULL,
1.99 + MBrCtlDialogsProvider* aBrCtlDialogsProvider = NULL,
1.100 + MBrCtlWindowObserver* aBrCtlWindowObserver = NULL,
1.101 + MBrCtlDownloadObserver* aBrCtlDownloadObserver = NULL );
1.102 +
1.103 +/**
1.104 +* The CBrCtlInterface class is the base class of the Browser Control API.
1.105 +* All clients of browser control must use this class. The functions defined
1.106 +* in the CBrCtlInterface class implement basic Browser Control functionality.
1.107 +* You can customize the Browser Control to extend its functionality by
1.108 +* implementing additional interface classes in the host application. Examples
1.109 +* of such classes are MBrCtlDataLoadSupplier, MBrCtlDialogsProvider,
1.110 +* MBrCtlDialogsProvider etc.
1.111 +*
1.112 +* Usage:
1.113 +*
1.114 +* @code
1.115 +* #include <BrCtlInterface.h>
1.116 +* // Interface that provides dialogs used by the Browser Control.
1.117 +* #include <BrCtlDialogsProvider.h>
1.118 +* // Interface used to receive scrolling events.
1.119 +* #include <BrCtlLayoutObserver.h>
1.120 +* //Interface that provides a callback mechanism for receiving the
1.121 +* //content of an embedded link or the content of a user-initiated
1.122 +* //load request.
1.123 +* #include <BrCtlLinkResolver.h>
1.124 +* //Interface that handles requests to change the softkeys.
1.125 +* #include <BrCtlSoftkeysObserver.h>
1.126 +* //Interface that handles special load needs.
1.127 +* #include <BrCtlSpecialLoadObserver.h>
1.128 +* //Reserved for future use.
1.129 +* #include <BrCtlWindowObserver.h>
1.130 +* //Interface that passes download events from the
1.131 +* //Download Manager through the Browser Control to the
1.132 +* //host application.
1.133 +* #include <BrCtlDownloadObserver.h>
1.134 +* Enum Definition of the Browser Control API.
1.135 +* #include <BrCtlDefs.h>
1.136 +*
1.137 +*
1.138 +* The following types of things you can do with the Browser Control API.
1.139 +*
1.140 +* Creating a basic Browser Control
1.141 +* Creating a Browser Control with observer interfaces
1.142 +* Loading content
1.143 +* Passing content incrementally
1.144 +* Receiving load progress events
1.145 +* Handling special load requests
1.146 +* Customizing dialogs
1.147 +* Specifying the softkeys
1.148 +* Resolving links
1.149 +* Customizing scroll bars
1.150 +* Receiving change-of-state events
1.151 +*
1.152 +* @see S60 Platform: Browser Control API Developer's Guide Version 2.0
1.153 +* @lib BrowserEngine.lib
1.154 +* @since 2.8
1.155 +* @file BrCtlInterface.h
1.156 +* @endcode *
1.157 +*/
1.158 +class CBrCtlInterface : public CCoeControl
1.159 + {
1.160 + public: // Constructors and destructor
1.161 +
1.162 + /**
1.163 + * Destructor.
1.164 + */
1.165 + inline virtual ~CBrCtlInterface() {}
1.166 +
1.167 + public: // New functions
1.168 +
1.169 + /**
1.170 + * Passes a command to the Browser Control..
1.171 + * @since 2.8
1.172 + * @param aCommand The command that the Browser Control should process
1.173 + * @return void
1.174 + * @see TBrCtlCommands, For a complete list of commands,
1.175 + */
1.176 + IMPORT_C virtual void HandleCommandL(TInt aCommand) = 0;
1.177 +
1.178 + /**
1.179 + * Return the display size that would be needed to see all the content
1.180 + * @since 2.8
1.181 + * @return The display size that would be needed to see all the content
1.182 + */
1.183 + IMPORT_C virtual TSize ContentSize() = 0;
1.184 +
1.185 + /**
1.186 + * Update a Browser Control setting
1.187 + * @since 2.8
1.188 + * @param aSetting The setting to update
1.189 + * @param aValue The new value of the setting
1.190 + * @leave KErrArgument if the value of aSetting is out of range.
1.191 + * @return void
1.192 + */
1.193 + IMPORT_C virtual void SetBrowserSettingL(TUint aSetting, TUint aValue) = 0;
1.194 +
1.195 + /**
1.196 + * Get a setting from the Browser Control
1.197 + * @since 2.8
1.198 + * @param aSetting The setting to get
1.199 + * @leave KErrArgument if the value of aSetting is out of range.
1.200 + * @return The value of the setting
1.201 + */
1.202 + IMPORT_C virtual TUint BrowserSettingL(TUint aSetting) = 0;
1.203 +
1.204 + /**
1.205 + * Request the Browser Control to display the content of a buffer
1.206 + * @since 2.8
1.207 + * @param aUrl A url that refers to the data. If a url scheme is used, it must be "data:"
1.208 + * @param aData The content to display. Browser Control does not take ownership
1.209 + * @param aDataType The data type of the data
1.210 + * @param aCharsetUid The UID of the character converter of the content's charset 0 assumed Latin-1
1.211 + * @return void
1.212 + * @attention If you use this function, the Browser Control does not keep
1.213 + * track of the history. If the data is not markup, Browser Control uses
1.214 + * the Special Load Observer to pass the content back to the Host Application.
1.215 + * The Special Load Observer uses the Document Handler to send the content
1.216 + * to the proper application.
1.217 + */
1.218 + IMPORT_C virtual void LoadDataL(const TDesC& aUrl,
1.219 + const TDesC8& aData,
1.220 + const TDataType& aDataType,
1.221 + TUid aCharsetUid) = 0;
1.222 +
1.223 + /**
1.224 + * Request the Browser Control to display content incrementaly
1.225 + * @since 2.8
1.226 + * @param aUrl A url that refers to the data. If a url scheme is used, it must be "data:"
1.227 + * @param aDataType The data type of the data
1.228 + * @param aCharsetUid The UID of the character converter of the content's charset 0 assumed Latin-1
1.229 + * @param aContentLength The length of the content.
1.230 + * @param aBrCtlDataLoadSupplier A callback interface to stop passing data if an error occured in the Browser Control
1.231 + * @param aBrCtlDataLoadConsumer A callback interface returned by the browser. Data should be passed to that interface
1.232 + * @return void
1.233 + * @attension If you use this function, the Browser Control does not keep
1.234 + * track of the history.If the content type of the data is not markup, Browser
1.235 + * Control uses the Special Load Observer to pass the content back to the Host
1.236 + * Application. The Special Load Observer uses the Document Handler to send
1.237 + * the content to the proper application.
1.238 + */
1.239 + // The url scheme must be "data:" The url is needed as reference to this load request
1.240 + IMPORT_C virtual void InitLoadDataL(const TDesC& aUrl,
1.241 + const TDataType& aDataType,
1.242 + TUid aCharsetUid,
1.243 + TUint aContentLength,
1.244 + MBrCtlDataLoadSupplier* aBrCtlDataLoadSupplier,
1.245 + MBrCtlDataLoadConsumer** aBrCtlDataLoadConsumer) = 0;
1.246 +
1.247 + /**
1.248 + * Request the Browser Control to load a url
1.249 + * @since 2.8
1.250 + * @param aUrl The url to load
1.251 + * @param aApId The Access Point Id to use
1.252 + * @param aCacheMode The cache mode to use.
1.253 + * Values: One of the following:
1.254 + * ECacheModeNormal
1.255 + * ECacheModeHistory
1.256 + * ECacheModeNoCache
1.257 + * ECacheModeOnlyCache
1.258 + * @see For a description of each of these values, see TBrCtlCacheMode
1.259 + * @return void
1.260 + */
1.261 + IMPORT_C virtual void LoadUrlL( const TDesC& aUrl,
1.262 + TInt aApId = -1,
1.263 + TBrCtlDefs::TBrCtlCacheMode aBrCtlCacheMode = TBrCtlDefs::ECacheModeNormal) = 0;
1.264 +
1.265 + /**
1.266 + * Request the Browser Control to load and display a file from the file system
1.267 + * @since 2.8
1.268 + * @param aFileName The name of the file
1.269 + * @return void
1.270 + */
1.271 + IMPORT_C virtual void LoadFileL(const TDesC& aFileName) = 0;
1.272 +
1.273 + /**
1.274 + * Request the Browser Control to load and display a file from the file system
1.275 + * @since 2.8
1.276 + * @param aFileHandle The handle of the file
1.277 + * @return void
1.278 + */
1.279 + IMPORT_C virtual void LoadFileL(RFile& aFileHandle) = 0;
1.280 +
1.281 + /*
1.282 + * Return the WML Options for the current page
1.283 + * @since 2.8
1.284 + * @param
1.285 + * @return The WML Options for the current page
1.286 + */
1.287 + IMPORT_C virtual RPointerArray<TBrCtlWmlServiceOption>* WMLOptionMenuItemsL() = 0;
1.288 +
1.289 + /**
1.290 + * Request the Browser Control to add its own options to the option menu
1.291 + * @since 2.8
1.292 + * @param aMenuPane Handle of the menu that will contain the options
1.293 + * @param aResourceId The resource ID of the menu
1.294 + * @param aAfter WML options should be added after that index
1.295 + * @return void
1.296 + */
1.297 + IMPORT_C virtual void AddOptionMenuItemsL(CEikMenuPane& aMenuPane, TInt aResourceId, TInt aAfter=-1 ) = 0;
1.298 +
1.299 + /**
1.300 + * Request the Browser Control to clear the cache
1.301 + * @since 2.8
1.302 + * @return The number of bytes that were freed from cache.
1.303 + */
1.304 + IMPORT_C virtual TUint ClearCache() = 0;
1.305 +
1.306 + /**
1.307 + * Ask the Browser Control if a URL is in cache
1.308 + * @since 2.8
1.309 + * @param aUrl The Url
1.310 + * @return ETrue, if a specific Url is in cache
1.311 + * EFalse if the URL is not in the cache
1.312 + */
1.313 + IMPORT_C virtual TBool IsUrlInCache(TDesC& aUrl) = 0;
1.314 +
1.315 + /**
1.316 + * Ask the Browser Control to clear a URL from the cache
1.317 + * @since 2.8
1.318 + * @param aUrl The Url
1.319 + * @return KErrNone if the URL is cleared from the cache
1.320 + * Error message is the URL has not been cleared.
1.321 + */
1.322 + IMPORT_C virtual TInt ClearItemInCache(TDesC& aUrl) = 0;
1.323 +
1.324 + /**
1.325 + * Request the Browser Control to return info about the page. The info is returned on the Cleanup Stack.
1.326 + * @since 2.8
1.327 + * @param aBrCtlPageInfo The type of requested info
1.328 + * @return A descriptor containing the requested page info
1.329 + * @attention The information is returned on the Cleanup stack.
1.330 + */
1.331 + IMPORT_C virtual HBufC* PageInfoLC(TBrCtlDefs::TBrCtlPageInfo aBrCtlPageInfo ) = 0;
1.332 +
1.333 + /**
1.334 + * From CBrCtlInterface Query the Browser Control
1.335 + * if there is a previous or next (depending on aDirection) element in history stack
1.336 + * @param aDirection
1.337 + * ENavigationBack if you wish to query whether there is a previous element
1.338 + * in the history stack.
1.339 + * ENavigationForward if you wish to query whether there is a subsequent
1.340 + * element in the history stack.
1.341 + * @since 2.8
1.342 + * @return ETrue if can go aDirection, EFalse otherwise
1.343 + */
1.344 + IMPORT_C virtual TBool NavigationAvailable( TBrCtlDefs::TBrCtlNavigationDirection aDirection ) = 0;
1.345 +
1.346 + /**
1.347 + * Request the Browser Control to save the current content to a file
1.348 + * @since 2.8
1.349 + * @param aFileName The name of the file to use for saving the content
1.350 + * @return The number of bytes in the saved file
1.351 + */
1.352 + IMPORT_C virtual TUint16 SaveToFileL(const TDesC& aFileName) = 0;
1.353 +
1.354 + /**
1.355 + * Request the Browser Control to pass the server's certificate info for the current page
1.356 + * @since 2.8
1.357 + * @return Certificate info of the server of the current page
1.358 + */
1.359 + IMPORT_C virtual const TCertInfo* CertInfo() = 0;
1.360 +
1.361 + /**
1.362 + * Request the Browser Control to register for load events
1.363 + * @since 2.8
1.364 + * @param aBrCtlLoadEventObserver A load events observer to add
1.365 + * @return void
1.366 + * @attenstion Call this function immediately after creating the Browser Control.
1.367 + * For multiple registrations, the host application may call this function more than once.
1.368 + * Observers must unregister before deleting the Browser Control.
1.369 + */
1.370 + IMPORT_C virtual void AddLoadEventObserverL(MBrCtlLoadEventObserver* aBrCtlLoadEventObserver) = 0;
1.371 +
1.372 + /**
1.373 + * Request the Browser Control to unregister for load events
1.374 + * @since 2.8
1.375 + * @param aBrCtlLoadEventObserver A load events observer to remove
1.376 + * @return void
1.377 + * @attenstion Call this function for each Load Observer that was previously registered.
1.378 +
1.379 +
1.380 + */
1.381 + IMPORT_C virtual void RemoveLoadEventObserver(MBrCtlLoadEventObserver* aBrCtlLoadEventObserver) = 0;
1.382 +
1.383 + /**
1.384 + * Return the number of images in the current page
1.385 + * @since 2.8
1.386 + * @param
1.387 + * @return The number of images in the current page
1.388 + */
1.389 + IMPORT_C virtual TInt ImageCountL() = 0;
1.390 +
1.391 + /**
1.392 + * Returns the focused element
1.393 + * @since 2.8
1.394 + * @return The type of the focused element
1.395 + * @attension The host application may need to perform special processing,
1.396 + * such as updating the softkeys, when a specific element has the focus.
1.397 + */
1.398 + IMPORT_C virtual TBrCtlDefs::TBrCtlElementType FocusedElementType() = 0;
1.399 +
1.400 + /**
1.401 + * Register an observer for state changes
1.402 + * @since 2.8
1.403 + * @param aBrCtlStateChangeObserver The observer to register
1.404 + * @return void
1.405 + * @attenstion The Observer must unregister before deleting the Browser Control.
1.406 + */
1.407 + IMPORT_C virtual void AddStateChangeObserverL(MBrCtlStateChangeObserver* aBrCtlStateChangeObserver) = 0;
1.408 +
1.409 + /**
1.410 + * Unregister an observer for state changes
1.411 + * @since 2.8
1.412 + * @param The observer to unregister
1.413 + * @return void
1.414 + */
1.415 + IMPORT_C virtual void RemoveStateChangeObserver(MBrCtlStateChangeObserver* aBrCtlStateChangeObserver) = 0;
1.416 +
1.417 + /**
1.418 + * Request the Browser Control to return info about the Browser Control version. The info is returned on the Cleanup Stack.
1.419 + * @since 2.8
1.420 + * @param aVersionInfo The type of requested info
1.421 + * @return A descriptor containing the requested page info
1.422 + * @attention The information is returned on the Cleanup Stack.
1.423 + */
1.424 + IMPORT_C virtual HBufC* VersionInfoLC(TBrCtlDefs::TBrCtlVersionInfo aVersionInfo) = 0;
1.425 +
1.426 + /**
1.427 + * Pass a list of content types to the Browser Control.
1.428 + * These content types will not be using the download manager.
1.429 + * The list must be separated by ';' e.g. "text/html;text/wml"
1.430 + * @since 2.8
1.431 + * @param aContentTypes The content types that should not use Download Manager
1.432 + * @return void
1.433 + * @deprecated This function is deprecated. Use the
1.434 + * EParamsSelfDownloadableTypes parameter of the SetParamL function instead.
1.435 + */
1.436 + IMPORT_C virtual void SetSelfDownloadContentTypesL(TDesC& aContentTypes) = 0;
1.437 +
1.438 + /**
1.439 + * Update a Browser Control parameter. consequent calls with the
1.440 + * same aParam will replace the value, and not append to it.
1.441 + * @since 2.8
1.442 + * @param aParam The parameter to update
1.443 + * @param aValue The new value of the parameter
1.444 + * EParamsSelfDownoadableTypes: Pass a list of content types to the
1.445 + * Browser Control. These content types will not be using the
1.446 + * download manager. The list must be separated by ';' e.g.
1.447 + * "text/html;text/wml"
1.448 + *
1.449 + * EParamsRequestHeaders: Pass a list of headers that the
1.450 + * Browser Control. These headers will be added to each request.
1.451 + * The list must be separated by '\r'. The header name and value must be
1.452 + * separated by ':' e.g.
1.453 + * "x-myheader: myvalue\rx-myotherheader: myothervalue"
1.454 + * @return void
1.455 + */
1.456 + IMPORT_C virtual void SetParamL(TBrCtlDefs::TBrCtlParams aParam, const TDesC& aValue) = 0;
1.457 +
1.458 + /**
1.459 + * Request the Browser Control to load a saved page.
1.460 + * @since 3.0
1.461 + * @param aUid a unique identifier for the saved page
1.462 + * @param aSavedPageBuffer buffer which contains the content of the saved page
1.463 + * @return void
1.464 + */
1.465 + IMPORT_C virtual void LoadSavedPageL(const TDesC& aUid, TDesC& aSavedPageBuffer) = 0;
1.466 +
1.467 + /**
1.468 + * Return the zoom levels index
1.469 + * @since 3.0
1.470 + * @return The zoom levels array.
1.471 + */
1.472 + IMPORT_C virtual RArray<TUint>* ZoomLevels() const = 0;
1.473 +
1.474 + /**
1.475 + * Perform the incremental find operation
1.476 + * @param aKeyword String to be find.
1.477 + * @since 3.0
1.478 + * @return TBrCtlFindResponse
1.479 + */
1.480 + IMPORT_C virtual int FindKeyword( const TDesC& aKeyword ) = 0;
1.481 +
1.482 + /**
1.483 + * Continue the incremental find operation
1.484 + * @since 3.0
1.485 + * @param aFowardDirection TRUE if search is in forword direction.
1.486 + * For backword direction, it is FALSE.
1.487 + * @return TBrCtlFindResponse
1.488 + * @attention Method that is called when the user searches for the next
1.489 + * keyword in the doc.
1.490 + *
1.491 + */
1.492 + IMPORT_C virtual TBrCtlDefs::TBrCtlFindResponse FindKeywordAgain( TBool aFowardDirection ) = 0;
1.493 +
1.494 + /**
1.495 + * Return information about the linked feeds in the current page - used to
1.496 + * build a "Subscribe to" submenu.
1.497 + * @since 3.0
1.498 + * @return Information about the linked feeds in the current page. The
1.499 + * caller adopts the result.
1.500 + */
1.501 + IMPORT_C virtual const RPointerArray<TBrCtlSubscribeTo>& SubscribeToMenuItemsL() = 0;
1.502 +
1.503 +
1.504 +
1.505 + public: // Functions from base classes
1.506 +
1.507 + // Functions from CCoeControl
1.508 +
1.509 + /**
1.510 + * From CCoeControl Return the minimum size the Browser Control can use
1.511 + * @since 2.8
1.512 + * @return The minimum size that the Browser Control can use.
1.513 + * @attention This function is inherited from the Symbian CCoeControl class.
1.514 + */
1.515 + IMPORT_C virtual TSize MinimumSize() = 0;
1.516 +
1.517 + /**
1.518 + * From CCoeControl Pass key events to the Browser Control
1.519 + * @since 2.8
1.520 + * @param aKeyEvent The key event
1.521 + * @param aType The key code
1.522 + * @return If the Browser Control consumed the key event or not
1.523 + * @attention This function is inherited from the Symbian CCoeControl class.
1.524 + */
1.525 + IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType) = 0;
1.526 +
1.527 + /**
1.528 + * From CCoeControl Sets that the Browser Control has keyboard focus.
1.529 + * @since 2.8
1.530 + * @param aFocus If the Browser Control gets or loses focus
1.531 + * @param ENoDrawNow If the Browser Control should redraw itself as result of focus change
1.532 + * @return void
1.533 + * @attention This function is inherited from the Symbian CCoeControl class.
1.534 + */
1.535 + IMPORT_C virtual void SetFocus(TBool aFocus, TDrawNow aDrawNow = ENoDrawNow) = 0;
1.536 +
1.537 + /*
1.538 + * This method calls to download manager in order to display query "Cancel
1.539 + * outstanding downloads?" and cancel if it requested by user
1.540 + * @param none
1.541 + * @return ETrue if it is OK to exit; EFalse - if it is not OK to exit
1.542 + */
1.543 + IMPORT_C virtual TBool OkToExit() = 0;
1.544 +
1.545 +
1.546 + /**
1.547 + * This method calls to download manager in order to send the commands (EDownloadCmdPause,DownloadCmdResume,
1.548 + * EDownloadCmdCancel, EDownloadCmdMarkAsProgressive, EDownloadCmdMarkAsNotProgressive )
1.549 + * @param aCommand The command that the Browser Control should process
1.550 + * @param aTransId The transaction Id associated with this command
1.551 + * @return void
1.552 + */
1.553 + IMPORT_C virtual void HandleDownloadCommandL(TUint16 aTransId, TBrCtlDefs::TBrCtlDownloadCmd aCommand) = 0;
1.554 +
1.555 + /**
1.556 + * Request icon for the given url
1.557 + * @since 3.1
1.558 + * @param aUrl url to a favicon or a page
1.559 + * @param aBitmapInfo info on whether to retun a favicon or a page icon
1.560 + * @return favion icon or page icon
1.561 + */
1.562 + IMPORT_C virtual CGulIcon* GetBitmapData(const TDesC& aUrl, TBrCtlDefs::TBrCtlBitmapInfo aBitmapInfo) = 0;
1.563 +
1.564 + /**
1.565 + * Register a client command interface for the browser engine
1.566 + * @since 3.1
1.567 + * @param The observer to register
1.568 + * @return void
1.569 + */
1.570 + IMPORT_C virtual void AddCommandObserverL(MBrCtlCommandObserver* aBrCtlCommandObserver) = 0;
1.571 +
1.572 + /**
1.573 + * Unregister a client command interface for the browser engine
1.574 + * @since 3.1
1.575 + * @param The observer to unregister
1.576 + * @return void
1.577 + */
1.578 + IMPORT_C virtual void RemoveCommandObserver(MBrCtlCommandObserver* aBrCtlCommandObserver) = 0;
1.579 +
1.580 + /**
1.581 + * Unregister a client command interface for the browser engine
1.582 + * @since 3.1
1.583 + * @param The observer to unregister
1.584 + * @return void
1.585 + */
1.586 + IMPORT_C virtual MWidgetExtension* CreateWidgetExtensionL(MWidgetCallback& aWidgetCallback) = 0;
1.587 +
1.588 + /**
1.589 + * Get information about the focused image. The function leaves if the focus is not on an image
1.590 + * @since 3.2
1.591 + * @param
1.592 + * @return The requested information
1.593 + */
1.594 + IMPORT_C virtual TBrCtlImageCarrier* FocusedImageLC() = 0;
1.595 +
1.596 + /**
1.597 + * Requests the Browser Control to POST to a URL
1.598 + * @since 5.0
1.599 + * @param aUrl URL to which the Browser Control sends the POST request
1.600 + * @param aContentType Content type of the data to be posted
1.601 + * @param aPostData Data to be posted
1.602 + * @param aBoundary Boundary for form-data or multi-part content.
1.603 + * @param aReserved For future use only
1.604 + * @return void
1.605 + */
1.606 + IMPORT_C virtual void PostUrlL (const TDesC& aUrl,
1.607 + const TDesC8& aContentType,
1.608 + const TDesC8& aPostData,
1.609 + const TDesC8* aBoundary,
1.610 + TAny* aReserved) = 0;
1.611 + /**
1.612 + * Requests the Browser Control for offscreen bitmap
1.613 + * @since 5.0
1.614 + * @ fills offscreen bitmap.The bitmap memory has to be set and freed by the api calling that function.
1.615 + * @return void.
1.616 + */
1.617 + IMPORT_C virtual void TakeSnapshotL(CFbsBitmap& snapshot) = 0;
1.618 + };
1.619 +
1.620 +
1.621 +/**
1.622 +* The MBrCtlDataLoadSupplier class is a callback interface that
1.623 +* provides the Browser Control with the ability to display content incrementally.
1.624 +* It does this by providing a means for the Browser Control to cancel the load operation
1.625 +* if an error occurs.
1.626 +* For example, if the Browser Control runs out of memory during the
1.627 +* load operation, it can cancel that operation by means of this interface.
1.628 +*
1.629 +* Usage:
1.630 +*
1.631 +* @code
1.632 +* #include <BrCtlInterface.h>
1.633 +* @see S60 Platform: Browser Control API Developer's Guide Version 2.0
1.634 +* @lib BrowserEngine.lib
1.635 +* @since 2.8
1.636 +* @file BrCtlInterface.h
1.637 +* @endcode *
1.638 +*/
1.639 +class MBrCtlDataLoadSupplier
1.640 + {
1.641 + public: // New functions
1.642 + /**
1.643 + * Cancel the load operation
1.644 + * @since 2.8
1.645 + * @return void
1.646 + */
1.647 + virtual void CancelLoad() = 0;
1.648 + };
1.649 +
1.650 +
1.651 +
1.652 +/**
1.653 +* The MBrCtlDataLoadConsumer class is a callback interface that provides
1.654 +* the Browser Control with the ability to receive content incrementally.
1.655 +*
1.656 +* @code
1.657 +* #include <BrCtlInterface.h>
1.658 +* @see S60 Platform: Browser Control API Developer's Guide Version 2.0
1.659 +* @lib BrowserEngine.lib
1.660 +* @since 2.8
1.661 +* @file BrCtlInterface.h
1.662 +* @endcode *
1.663 +*/
1.664 +class MBrCtlDataLoadConsumer
1.665 + {
1.666 + public: // New functions
1.667 + /**
1.668 + * Pass the next data chunk
1.669 + * @since 2.8
1.670 + * @param aData The data chunk to process
1.671 + * @return void
1.672 + */
1.673 + virtual void HandleNextDataChunk(const TDesC8& aData) = 0;
1.674 +
1.675 + /**
1.676 + * Inform the Browser Control about completion of data load
1.677 + * @since 2.8
1.678 + * @return void
1.679 + */
1.680 + virtual void HandleLoadComplete() = 0;
1.681 +
1.682 + /**
1.683 + * Inform the Browser Control that an error occured
1.684 + * if HandleError() is called, then LoadComplete() is infered.
1.685 + * @since 2.8
1.686 + * @param aError The error code
1.687 + * @return void
1.688 + */
1.689 + virtual void HandleError(TInt aError) = 0;
1.690 + };
1.691 +
1.692 +/**
1.693 +* The MBrCtlLoadEventObserver interface receives load progress events.
1.694 +* The host application can implement this interface.
1.695 +*
1.696 +* @code
1.697 +* #include <BrCtlInterface.h>
1.698 +* @see S60 Platform: Browser Control API Developer's Guide Version 2.0
1.699 +* @lib BrowserEngine.lib
1.700 +* @since 2.8
1.701 +* @file BrCtlInterface.h
1.702 +* @endcode *
1.703 +*/
1.704 +class MBrCtlLoadEventObserver
1.705 + {
1.706 + public: // New functions
1.707 + /**
1.708 + * A load events notification
1.709 + * @since 2.8
1.710 + * @param aLoadEvent The load event
1.711 + * @param aSize Size depends on the event
1.712 + * @param aTransactionId The transaction id of the transaction that had this event
1.713 + * @return void
1.714 + */
1.715 + virtual void HandleBrowserLoadEventL(TBrCtlDefs::TBrCtlLoadEvent aLoadEvent, TUint aSize, TUint16 aTransactionId) = 0;
1.716 + };
1.717 +
1.718 +/**
1.719 +* The TBrCtlWmlServiceOption class wraps information about the WML DO elements.
1.720 +* For more information about the DO tag, see http://www.w3schools.com/wap/tag_do.asp.
1.721 +* @code
1.722 +* #include <BrCtlInterface.h>
1.723 +* @lib BrowserEngine.lib
1.724 +* @since 2.8
1.725 +* @file BrCtlInterface.h
1.726 +* @endcode *
1.727 +*/
1.728 +class TBrCtlWmlServiceOption
1.729 + {
1.730 + public:
1.731 + /**
1.732 + * Constructor
1.733 + * @since 2.8
1.734 + * @param aText The text to display in the WML service options
1.735 + * @param aElemID The element Id to use when the user selects this command
1.736 + * @param aActualElemID Internal to the Browser Control. The host
1.737 + * application should not modify this parameter.
1.738 + */
1.739 + TBrCtlWmlServiceOption(HBufC* aText, TUint aElemID, TUint aActualElemID);
1.740 + /**
1.741 + * Displays the text for the WML service options
1.742 + * @since 2.8
1.743 + * @return Text to display for the WML service options
1.744 + */
1.745 + inline const TDesC& Text() {return *iText;}
1.746 + /**
1.747 + * Gets the command ID to use when the user selects this command
1.748 + * @since 2.8
1.749 + * @return Element ID employed when the user selects this command
1.750 + */
1.751 + inline TUint ElemID(){return iElemID;}
1.752 + /**
1.753 + * Gets the actual element ID defined in the WML page.
1.754 + * @since 2.8
1.755 + * @return Actual element ID
1.756 + * @attention This parameter is internal to the Browser Control.
1.757 + * The host application should not modify this parameter.
1.758 + */
1.759 + inline TUint ActualElemID(){return iActualElemID;}
1.760 +
1.761 + /**
1.762 + * Destructor.
1.763 + */
1.764 + ~TBrCtlWmlServiceOption();
1.765 +
1.766 + private: // Data
1.767 + /**
1.768 + * Default constructor
1.769 + * @since 2.8
1.770 + */
1.771 + TBrCtlWmlServiceOption() {};
1.772 +
1.773 + // The text to display in the WML service options
1.774 + HBufC* iText;
1.775 + // The element Id to use when the user selects this command
1.776 + TUint iElemID;
1.777 + // The actual element Id
1.778 + TUint iActualElemID;
1.779 + };
1.780 +
1.781 +/**
1.782 +* The TBrCtlSubscribeTo class provides information of Subscribe to items.
1.783 +* @code
1.784 +* #include <BrCtlInterface.h>
1.785 +* @lib BrowserEngine.lib
1.786 +* @since 2.8
1.787 +* @file BrCtlInterface.h
1.788 +* @endcode *
1.789 +*/
1.790 +class TBrCtlSubscribeTo
1.791 + {
1.792 + public:
1.793 + /**
1.794 + * Constructor
1.795 + * @since 3.0
1.796 + * @param aText The text to display in the subscribe to option. aText
1.797 + * is adopted.
1.798 + * @param aCommandID The menu command Id to use when the user selects it.
1.799 + */
1.800 + TBrCtlSubscribeTo(const TPtrC& aTitle, const TPtrC& aUrl, TUint aCommandID);
1.801 +
1.802 + /**
1.803 + * Returns the title.
1.804 + * @since 3.0
1.805 + * @return The title.
1.806 + */
1.807 + inline const TPtrC& Title() {return iTitle;}
1.808 +
1.809 + /**
1.810 + * Returns the url.
1.811 + * @since 3.0
1.812 + * @return The url.
1.813 + */
1.814 + inline const TPtrC& Url() {return iUrl;}
1.815 +
1.816 + /**
1.817 + * Returns the command.
1.818 + * @since 3.0
1.819 + * @return The command.
1.820 + */
1.821 + inline TUint CommandID() {return iCommandID;}
1.822 +
1.823 + private:
1.824 + /**
1.825 + * Default constructor
1.826 + * @since 3.0
1.827 + */
1.828 + TBrCtlSubscribeTo();
1.829 +
1.830 + private: // Data
1.831 + const TPtrC iTitle;
1.832 + const TPtrC iUrl;
1.833 +
1.834 + TUint iCommandID;
1.835 + };
1.836 +
1.837 +/**
1.838 +* The MBrCtlStateChangeObserver class receives state-changed events.
1.839 +* At the present time, there is only one state-changed event.
1.840 +* This event is generated when the browser switches to and from
1.841 +* the Image Map view. In Image Map view, only an image map is displayed,
1.842 +* which enables the user to navigate. The host application can
1.843 +* implement this interface in order to find out when the view
1.844 +* changes to and from the Image Map view.
1.845 +* @code
1.846 +* #include <BrCtlInterface.h>
1.847 +* @lib BrowserEngine.lib
1.848 +* @since 2.8
1.849 +* @file BrCtlInterface.h
1.850 +* @endcode *
1.851 +*/
1.852 +class MBrCtlStateChangeObserver
1.853 + {
1.854 + public:
1.855 + /**
1.856 + * Notifies the Browser Control of a state-changed event.
1.857 + * @param aState Indicates whether or not the browser is in Image Map view.
1.858 + * Value:EStateImageMapView
1.859 + * @param aValue Indicates the state being changed.
1.860 + * Values:
1.861 + * ETrue indicates entering Image Map view
1.862 + * EFalse indicates exiting Image Map view
1.863 + * @since 2.8
1.864 + * @return void
1.865 + */
1.866 + virtual void StateChanged(TBrCtlDefs::TBrCtlState aState, TInt aValue) = 0;
1.867 + };
1.868 +
1.869 +// CLASS DECLARATION
1.870 +/**
1.871 +* This class provides a mechanism for the browser engine to pass commands to the client
1.872 +*
1.873 +* @lib BrowserEngine.lib
1.874 +* @since 3.1
1.875 +*/
1.876 +class MBrCtlCommandObserver
1.877 + {
1.878 + public: // New functions
1.879 + /**
1.880 + * Method to call client to execute commands
1.881 + * @since 3.1
1.882 + * @param A callback command
1.883 + * @param Array of attribute names
1.884 + * @param Array of attribute values
1.885 + * @return void
1.886 + */
1.887 + virtual void HandleCommandL(TBrCtlDefs::TBrCtlClientCommands aCommand, const CArrayFix<TPtrC>& aAttributesNames,
1.888 + const CArrayFix<TPtrC>& aAttributeValues) = 0;
1.889 + };
1.890 +
1.891 +// CLASS DECLARATION
1.892 +/**
1.893 +* This class provides a mechanism for the browser engine to interact with the widget host application
1.894 +*
1.895 +* @lib BrowserEngine.lib
1.896 +* @since 3.2
1.897 +*/
1.898 +class MWidgetCallback
1.899 + {
1.900 + public:
1.901 + /**
1.902 + * Navigates through your file system and selects a file of specific mime type;
1.903 + * analogous to the Browse command in Windows.
1.904 + * @since 3.2
1.905 + * @param aSelectedFileName The selected file name.
1.906 + * @param aMimeType The accepted mime type.
1.907 + * @return ETrue if the user selected a file
1.908 + * EFalse if the user cancelled the transaction and did not select a file.
1.909 + * @attiontion Returned on cleanup stack. Browser control will free the buffer.
1.910 + */
1.911 + virtual TBool DialogMimeFileSelectLC(HBufC*& aSelectedFileName,
1.912 + const TDesC& aMimeType) = 0;
1.913 +
1.914 + /**
1.915 + * Called to show or hide softkeys
1.916 + * @since 3.1
1.917 + * @param aVisible ETrue to show softkeys, EFalse when full screen is needed
1.918 + */
1.919 + virtual void SetSoftkeysVisible(TBool aVisible) = 0;
1.920 +
1.921 + /**
1.922 + * Called to change the display orientation to landscape
1.923 + * @since 3.1
1.924 + */
1.925 + virtual void SetDisplayMode(TBrCtlDefs::TBrCtlOrientation aOrientation) = 0;
1.926 +
1.927 + //Reserved for future use
1.928 + virtual TInt Reserved_1(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.929 + virtual TInt Reserved_2(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.930 + virtual TInt Reserved_3(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.931 + virtual TInt Reserved_4(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.932 + virtual TInt Reserved_5(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.933 + virtual TInt Reserved_6(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.934 + virtual TInt Reserved_7(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.935 + virtual TInt Reserved_8(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.936 + virtual TInt Reserved_9(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.937 + virtual TInt Reserved_10(TAny*& a0, TAny* a1, TAny* a2) = 0;
1.938 + };
1.939 +
1.940 +// CLASS DECLARATION
1.941 +/**
1.942 +* This class provides an extension mechanism for the widget host app to interact with the browser engine
1.943 +* This class includes the Widget specific extension needed in the browser engine
1.944 +* @lib BrowserEngine.lib
1.945 +* @since 3.2
1.946 +*/
1.947 +class MWidgetExtension
1.948 + {
1.949 + public: // New functions
1.950 + /**
1.951 + * Method to set parameters in the browser engine
1.952 + * @since 3.2
1.953 + * @param The widget identifier
1.954 + * @param The value for the paramater
1.955 + * @return void
1.956 + */
1.957 + virtual void SetParamL(TBrCtlDefs::TBrCtlWidgetParams aParam, const TDesC& aValue) = 0;
1.958 +
1.959 + /**
1.960 + * Method to set parameters in the browser engine
1.961 + * @since 3.2
1.962 + * @param The widget parameter aParam
1.963 + * @param The value for the paramater
1.964 + * @return void
1.965 + */
1.966 + virtual void SetParamL(TBrCtlDefs::TBrCtlWidgetParams aParam, TUint aValue) = 0;
1.967 +
1.968 + /**
1.969 + * Method to invoke callback function for right soft key
1.970 + * @since 3.2
1.971 + * @param none
1.972 + * @return ETrue if there is a rightsoftkey callback, else EFalse
1.973 + */
1.974 + virtual TBool HandleCommandL( TInt aCommandId ) = 0;
1.975 +
1.976 + };
1.977 +#endif // BRCTLINTERFACE_H
1.978 +
1.979 +// End of File