Browser Control API: Using the Web Browser Control API

The Browser Control API creates a basic Browser Control that you embed into an application in order to view Web content from within that application. The host application controls the way the Browser Control displays the Web content, as well as the dialogs, softkeys, and scroll bars. The Developer can specify the size and location (bouncing rectangle) of the Browser Control window as well as the desired capabilities of the Browser Control. These capabilities include:

• Displaying horizontal or vertical scroll bars, or both
• Loading embedded content to the host application
• Loading a URL to the host application
• Enabling and disabling input boxes and Netscape plug-ins
• Allowing network access for HTTP requests
• Employing the Download Manager to download content, such as audio or video files
• Adding page search capability to the Options menu
• Enabling confirmation dialog in the Download Manager

In addition to the creating a basic Browser Control, this API enables the Developer to create Observer interfaces that listen for Browser Control events and perform customized actions based on those events. The Observers can enable you to do the following:

• Customize dialogs
• Display content progressively as it downloads
• Display a progress bar as content downloads
• Customize scroll bars
• Enable the host application to control page navigation
• Enable the host application to change the softkeys based on events observed
• Handle special load requests, such as:
  • Control over network connections
  • Non-markup content
  • Non-HTTP(S) requests

The following sections describe these use cases and provide sample code for each.

Use Case 1: Creating a Basic Browser Control

To create a basic Browser Control within your application to display Web-related content, call the CreateBrowserControlL function of the CBrCtlInterfrace class:

To call this function, supply the following data:

The following code sample creates an instance of a basic Browser Control. In this example, the capabilities are set so that the Browser Control can:

• Make external HTTP requests (ECapabililtyLoadHttpFw)
• Handle scroll bars (ECapabilityDisplayBar)

This relieves the host application of these responsibilities.

//---------------------------------------------------------------

// CBrCtlSampleAppContainer::ConstructL(const TRect& aRect)

// EPOC two phased constructor

// ---------------------------------------------------------

//

void CBrCtlSampleAppContainer::ConstructL(const TRect& aRect)

    {

    CreateWindowL();

    SetRect(aRect);

    ActivateL();

    iCommandBase = TBrCtlDefs::ECommandIdBase;

    iBrCtlCapabilities = TBrCtlDefs::ECapabilityDisplayScrollBar | 

    TBrCtlDefs::ECapabilityLoadHttpFw;

    TRect rect(Position(), Size());

    iBrCtlInterface = CreateBrowserControlL( this, 

        rect, 

        iBrCtlCapabilities,

        iCommandBase, 

        NULL, 

        NULL, 

        NULL,

        NULL,

        NULL);

    }

Notes on the code:

1. The parent control inherits from CCoeControl
2. rect is the client rectangle
3. iBrCtlCapabilities are the capabilities
   • The Browser Control loads the HTTP framework. This is required for the Browser Control to make HTTP requests
   • The Browser Control displays the scroll bar

Use Case 2: Creating a Browser Control with Observer Interfaces

An observer is an interface, implemented by the host application, which listens for Browser Control events and performs customized actions based on those events. The following table lists and describes the observer interfaces.

To create a Browser Control with observer interfaces, follow these steps:

1. Select the observer class you wish to add. The previous table lists the observer interface classes.
2. Implement the functions defined for the observer class you selected in Step 1. The following table lists and describes the functions for each observer interface class.
3. Call the CreateBrowserControlL function of the CBrCtlInterface class with the pointers to the newly created interface class(es).

   The LoadEventObserver class can be added and removed dynamically. The other observers must be created and passed in to the CreateBrowserControlL function.

   Table 8: Observer interface functions

   Observer class	Functions	Description
   MBrCtlDialogsProvider	DialogNotifyErrorL	Notifies the user of an error encountered during a download.
   	DialogNotifyHttpErrorL	Notifies the user of an error from the HTTP server during a download.
   	DialogFileSelectLC	Navigates through your file system and selects a file.
   	DialogSelectOptionL	Displays the selected dialog.
   	DialogUserAuthenticationLC	Returns the user name and password.
   	DialogNoteL	Displays a message to the user.
   	DialogAlertL	Displays a message until the user presses OK.
   	DialogConfirmL	Displays a confirmation message to the user.
   	DialogPromptLC	Prompts the user to input data.
   	DialogDownloadObjectL	Displays information about the Netscape plug-in object and requests confirmation before downloading the object.
   	DialogDisplayPageImagesL	Displays the images contained in the current page.
   	CancelAll	Cancels the displayed dialog due to Browser exit.
   MBrCtlDownloadObserver	HandleDownloadEventL	Informs the host application that one of the following download events is in progress: All events have the prefix EDownload. EventStarted EventCompleted EventProgress EventCanceled EventError EventPaused EventResumed EventPausable
   	NewDownloadL	Informs the host application that the Download Manager has begun a new download.
   	ResumeDownloadL	Tells the host application to resume an incomplete download. After the host application restarts, this method is called for each file whose download was interrupted when the host application closed.
   MBrCtlLayoutObserver	UpdateBrowserHScrollBarL	Updates the position of the horizontal scroll bar.
   	UpdateBrowserVScrollBarL	Updates the position of the vertical scroll bar.
   	NotifyLayoutChange	Determines whether the page is to be read right-to-left or left-to-right.
   MBrCtlLinkResolver	ResolveEmbeddedLinkL	Retrieves the content of embedded objects.
   	ResolveLinkL	Loads new content identified by a link.
   	CancelAll	Cancels all outstanding link resolution operations.
   MBrCtlLoadEventObserver	HandleBrowserLoadEventL	Notifies the Browser Control of a load event and its size.
   MBrCtlSoftkeysObserver	UpdateSoftkeyL	Requests the host application to change a softkey.
   MBrCtlSpecialLoadObserver	HandleDownloadL	Requests the host application to handle a download.
   	HandleRequestL	Requests the host application to handle non-HTTP requests.
   	NetworkConnectionNeededL	Requests a new network connection.
   MBrCtlStateChangeObserver	StateChanged	Notifies the Browser Control of a state-changed event. This means that the image map view is turned on or off.
   MBrCtlWindowObserver	FindWindowL HandleWindowCommandL OpenWindowL	Handles window events such as: Open a URL in a new window Close a window Focus on a particular window Find a window of a specified name

The following example creates and configures an instance of the Browser Control that includes the following observer interfaces:

• Dialog Provider Observer
• Layout Observer
• Link Resolver Observer
• Load Event Observer
• Softkey Observer
• Special Load Observer
• State Change Observer

// ---------------------------------------------------------

//CBrCtlSampleAppContainer::ConstructL(const TRect& aRect)

// EPOC two phased constructor

// ---------------------------------------------------------

void CBrCtlSampleAppContainer::ConstructL(const TRect& aRect)

    {

    CreateWindowL();

    SetRect(aRect);

    ActivateL();

    iCommandBase = TBrCtlDefs::ECommandIdBase;



    // Create the Observers

    iBrCtlSampleAppSpecialLoadObserver = 

    CBrCtlSampleAppSpecialLoadObserver::NewL();



    iBrCtlSampleAppLayoutObserver = 

    CBrCtlSampleAppLayoutObserver::NewL(this);



    iBrCtlSampleAppSoftkeysObserver = 

    CBrCtlSampleAppSoftkeysObserver::NewL(this);



    iBrCtlSampleAppLoadEventObserver = 

    CBrCtlSampleAppLoadEventObserver::NewL(this);



    iBrCtlSampleAppLinkResolver = 

    CBrCtlSampleAppLinkResolver::NewL();



    iBrCtlSampleAppStateChangeObserver = 

    CBrCtlSampleAppStateChangeObserver::NewL(this);



    iBrCtlSampleAppDialogsProvider =    

    CBrCtlSampleAppDialogsProvider::NewL(this);



// Initialize member variables

    iBrCtlCapabilities = 

    TBrCtlDefs::ECapabilityDisplayScrollBar |  

    TBrCtlDefs::ECapabilityLoadHttpFw;



    TRect rect(Position(), Size());

    iBrCtlInterface = CreateBrowserControlL( this, 

        rect, 

        iBrCtlCapabilities,

        iCommandBase, 

        iBrCtlSampleAppSoftkeysObserver, 

        iBrCtlSampleAppLinkResolver, 

        iBrCtlSampleAppSpecialLoadObserver,

        iBrCtlSampleAppLayoutObserver

        iBrCtlSampleAppDialogsProvider);



    // These observers can be added and removed dynamically

    iBrCtlInterface-> 

    AddLoadEventObserverL(iBrCtlSampleAppLoadEventObserver);



    iBrCtlInterface->

    AddStateChangeObserverL(iBrCtlSampleAppStateChangeObserver);

    }

Use Case 3: Loading Content

A host application can load content by calling any of the functions described in the following table. These functions are all in the CBrCtlInterface.

The following example shows how to download a Web page with a specified URL using the LoadUrlL function:

// ----------------------------------------------------

// CBrCtlSampleAppContainer::LoadingContentFromUrlL()

// ----------------------------------------------------

//

void 

CBrCtlSampleAppContainer::LoadingContentFromUrlL()

    {

     _LIT(Kurl, “http://www.nokia.com/page.htm”);

     iBrCtlInterface->LoadL(KUrl);

    }

The following example shows how to load content from a file using an RFile handle:

// ----------------------------------------------------

// CBrCtlSampleAppContainer::LoadingContentWithFileHandleL()

// ----------------------------------------------------

//

void 

CBrCtlSampleAppContainer::LoadingContentWithFileHandleL()

    {

    _LIT(KUrl, "c:\\BrCtlSampleApp\\sample3.htm");

    RFs rfs;

    RFile file;

    User::LeaveIfError(rfs.Connect());

    CleanupClosePushL(rfs);



    User::LeaveIfError(file.Open(rfs, KUrl(),

    EFileShareReadersOnly));



    CleanupClosePushL(file);



    iBrCtlInterface->LoadFileL(file);



    CleanupStack::PopAndDestroy(2); // file, rfs

    }

The following example shows how to load content from a buffer:

// ----------------------------------------------------

// CBrCtlSampleAppContainer::LoadingContentWithBufferL()

// ----------------------------------------------------

//

void 

CBrCtlSampleAppContainer::LoadingContentWithBufferL()

    {

    _LIT(KUrl, "c:\\BrCtlSampleApp\\sample4.htm");

    _LIT8(KDataType, "text/html");

    HBufC8* data = ReadFileLC(KUrl);

    TDataType dataType(KDataType());

    TUid uid;

    uid.iUid = KCharacterSetIdentifierIso88591;

    iBrCtlInterface->LoadDataL(KUrl, *data, dataType, uid);

    CleanupStack::PopAndDestroy(); // data

    }

Use Case 4: Passing Content Incrementally

The host application can pass content to the Browser Control in small chunks, if desired. The Browser Control displays this content incrementally.

To pass content from the host application to the Browser Control incrementally, follow these steps:

1. Inherit from the MBrCtlDataLoadSupplier class and implement the CancelLoad function to stop the load operation.
2. Call the InitLoadDataL function of the CBrCtlInterface class to request the Browser Control to display content incrementally.
3. Call the HandleNextDataChunk function of the MBrCtlDataLoadConsumer class to pass the data chunks to the Browser Control.
4. Call the HandleLoadComplete function when the data chunk has finished loading.
5. If an error occurs, call the HandleError function.

The following table lists the functions that provide the Browser Control with the ability to display content incrementally.

The following example illustrates how to load content in small chunks:

Inherit from the MBrCtlDataLoadSupplier interface

To pass content from the host application to the Browser Control incrementally, inherit from the MBrCtlDataLoadSupplier class.

class CBrCtlSampleAppContainer : public CCoeControl, MCoeControlObserver, MBrCtlDataLoadSupplier

    {

    .

    .

    .

    }

Implement the CancelLoad function to stop the load operation.

/ ----------------------------------------------------

// CBrCtlSampleAppContainer::CancelLoad()

// ----------------------------------------------------

//

void CBrCtlSampleAppContainer::CancelLoad()

    {

    iCancelInitDataLoad = ETrue;

} 

Call the InitLoadDataL function

Call the InitLoadDataL function of the CBrCtlInterface class to request the Browser Control to display the content incrementally.

// ----------------------------------------------------

// CBrCtlSampleAppContainer::IncrementalLoadingL()

// ----------------------------------------------------

//

void 

CBrCtlSampleAppContainer::IncrementalLoadingL()

    {

    _LIT(KUrl, "c:\\BrCtlSampleApp\\sample5.htm");



    HBufC8* data = ReadFileLC(KUrl);

    _LIT8(KDataType, "text/html");

    TDataType dataType(KDataType());

    MBrCtlDataLoadConsumer* brCtlDataLoadConsumer = NULL;

    TUid uid;

    uid.iUid = KCharacterSetIdentifierIso88591;





    // Call the InitLoadDataL function of the

    // CBrCtlInterface

    // class to request the Browser Control to display the 

    // content incrementally.

    iBrCtlInterface->InitLoadDataL(KUrl, dataType, uid,

    data->Length(), this, &brCtlDataLoadConsumer);

    // Call the HandleNextDataChunk function to pass the

    // data chunks to the Browser Control.



    if (brCtlDataLoadConsumer)

        {

        brCtlDataLoadConsumer->HandleNextDataChunk(*data);

        // Call the HandleLoadComplete function when the    

        // data chunk has finished loading.

        if (!iCancelInitDataLoad)

            {

            brCtlDataLoadConsumer->HandleLoadComplete();

            }

        }

    iCancelInitDataLoad = EFalse;

    CleanupStack::PopAndDestroy(); // data

}

Use Case 5: Receiving Load Progress Events

The host application can display a progress bar as the Browser Control loads content. This gives the user a visual indication that the page is loading.

To receive load progress events, follow these steps:

1. Create an object that inherits from the MBrCtlLoadEventObserver interface. This interface is used to receive load progress events.
2. Implement the HandleBrowserLoadEventL function to update the progress bar display as the loading operation progresses.
3. Call the AddLoadEventObserverL function on the Browser Control interface to register the object with the Browser Control.
4. Call the RemoveLoadEventObserver function on the Browser Control interface before deleting the Browser Control.

The following functions handle load progress events:

The following example illustrates how to receive load progress events in order to create a progress bar. If a progress bar is desired, the host application must create and display it using the load progress information received from the Browser Control.

Inherit from the MBrCtlLoadEventObserver interface

Create an object that inherits from the MBrCtlLoadEventObserver interface, which is used to receive load progress events.

class CBrCtlSampleAppLoadEventObserver : public CBase,

 public MBrCtlLoadEventObserver

{

.

.

.

} 

Implement the HandleBrowserLoadEventL function

Implement the HandleBrowserLoadEventL function to update the progress bar display as the loading operation progresses.

// ---------------------------------------------------------

// CBrCtlSampleAppLoadEventObserver::HandleBrowserLoadEventL

// ---------------------------------------------------------

//

void 

CBrCtlSampleAppLoadEventObserver::HandleBrowserLoadEventL

(TBrCtlDefs::TBrCtlLoadEvent aLoadEvent,

TUint aSize, 

 TUint16 aTransactionId) 

    

    {

    // Here we are creating a text string to be displayed on

    // the screen. If you were implementing this method,

    // you would most likely be displaying a

    // progress bar.



    TBuf16<256> tgt; 



    _LIT(KHandleBrowserLoadEvent, "Load event = %d, size = 

    %d, trId = %d");

     

    tgt.AppendFormat(KHandleBrowserLoadEvent, aLoadEvent, 

    aSize, aTransactionId);



    iContainer->SetText(tgt);



    iContainer->DrawNow();

 

    }

Register the LoadEventObserver object with the Browser Control

Call the AddLoadEventObserverL function on the Browser Control interface to register the object with the Browser Control.

iBrCtlInterface-> 

AddLoadEventObserverL(iBrCtlSampleAppLoadEventObserver);

Use Case 6: Handling Special Load Requests

Special load requests consist of the following:

• Non-HTTP(S) load requests
• Non-HTML content
• Control over network connections

In these cases, the host application can handle the requests instead of the Browser Control.

The following functions of the BrCtlSpecialLoadObserver class handle special load events.

The following example handles a request to load non-HTML content.

Call the LoadUrlL function

The following code calls the LoadURL function on the Browser Control interface with a URL that contains non-HTML content.

// ----------------------------------------------------

// CBrCtlSampleAppContainer::SpecialLoadRequestsL()

// ----------------------------------------------------

//

void 

CBrCtlSampleAppContainer::SpecialLoadRequestsL()

    {

    _LIT(KUrl, "file://BrCtlSampleApp/sample6.htm");

    iBrCtlInterface->LoadUrlL( KUrl );

    }

Inherit from the MBrCtlSpecialLoadObserver interface

Inherit from the MBrCtlSpecialLoadObserver interface if the host application requires control over network connections or needs to handle non-markup content or non-HTTP(S) requests.

class CBrCtlSampleAppSpecialLoadObserver : public CBase, 

public MBrCtlSpecialLoadObserver

    {

    .

    .

    .

    }

Implement the HandleDownloadL function

The host application implements the HandleDownloadL function to handle non-HTML content.

// ---------------------------------------------------------

// CBrCtlSampleAppSpecialLoadObserver::HandleDownloadL

// ---------------------------------------------------------

//

TBool 

CBrCtlSampleAppSpecialLoadObserver::HandleDownloadL

(RArray<TUint>* aTypeArray, CDesCArrayFlat* aDesArray)

    {

    TInt i = 0;

    TInt count = aTypeArray->Count();

    for (i = 0; i < count; i++)

        {

        if ((*aTypeArray)[i] == EParamLocalFileName &&

        aDesArray[i].Length() > 0)

            {

            TInt j = 0;

            for (j = 0; j < count; j++)

                {

                if ((*aTypeArray)[j] == EParamReceivedContentType)

                    {

                    HBufC8* dataType8 =

                    HBufC8::NewLC((*aDesArray)[j].Length());

                    dataType8->Des().Copy((*aDesArray)[j]);

                    TDataType dataType(*dataType8);

                    iHandler->OpenFileEmbeddedL((*aDesArray)[i],

dataType);

                    CleanupStack::PopAndDestroy();

                    break;

                    }

                }

            break;

            }

        }

    return EFalse;

    }   	         

Use Case 7: Customizing Dialogs

The Browser Control provides dialogs to communicate with the user of the host application. You can customize these dialogs by implementing the MBrCtlDialogsProvider interface to:

• Remove one or more dialogs
• Change the format or content of dialogs
• Selectively implement some of the default dialogs

The following functions provide dialogs used by the Browser Control, such as authentication requests, selection lists, download confirmations, and error notifications. The Browser Control implements this interface for the default dialogs. If you wish to customize the dialogs, the host application must implement this interface.

The following example illustrates how to customize the alert dialog.

Inherit from the MBrCtlDialogsProvider Interface

Create an object that inherits from the MBrCtlDialogsProvider interface:

class CBrCtlSampleAppDialogsProvider : public CBase, public 

MBrCtlDialogsProvider

{

.

.

.

}

Implement the DialogAlertL function

// -------------------------------------------------------

// CBrCtlSampleAppDialogsProvider:: DialogAlertL

// -------------------------------------------------------

//

void 

CBrCtlSampleAppDialogsProvider::DialogAlertL(const TDesC& 

    /*aTitle*/, const TDesC& /*aMessage*/)



    {

    _LIT(KTitle,"");



    _LIT(KPrompt, "Enter URL");





    _LIT(KDefText, "http://");



    HBufC* returnedInput = NULL;

	

    TBool ret;



	  // defInput is not modified by the dialog.

    TBuf<256>defInput = ( (TUint16*) KDefText().Ptr());



    CBrCtlSampleAppQueryDialog* dialog = new (ELeave)

        CBrCtlSampleAppQueryDialog( defInput, returnedInput );



    CleanupStack::PushL(dialog);



    dialog->PrepareLC( R_DATA_QUERY_WITH_HEADING );



	  dialog->SetHeaderTextL( KTitle );



    dialog->SetPromptL( KPrompt );



    CleanupStack::Pop(); // dialog



    ret = dialog->RunLD();



    if (ret)

        {

        iContainer->BrCtlInterface()->LoadUrlL

            ( *returnedInput  );



        delete returnedInput;

        }

    }

Use Case 8: Specifying the Softkeys

The host application can change the labels of the softkeys as a response to softkey events received from the Browser Control. The Browser Control transmits one or more softkey events under the following conditions:

• A document is displayed
• A plug-in control is activated or deactivated
• An input box is activated or deactivated
• The Browser view changes to and from the Image Map view.

To specify the softkeys, follow these steps:

1. Implement the UpdateSoftkeyL function to change the softkeys
2. Use the event to query the FocusedElementType function to learn what the focused element is. All events are issued the EChangeReasonIdle reason code.
3. Change the softkeys based on the focused element

The following function handles requests to change the softkeys.

The following sample code illustrates how to change the labels of the softkeys in response to softkey events received from the Browser Control.

Inherit from the MBrCtlSoftkeysObserver interface

Create an object that inherits from the MBrCtlSoftkeysObserver class.

class CBrCtlSampleAppSoftkeysObserver : public CBase, public

MBrCtlSoftkeysObserver

{

.

.

.

}

Implement the UpdateSoftkeyL function

Implement the UpdateSoftkeyL function to change the softkeys:

/ ---------------------------------------------------------

// CBrCtlSampleAppSoftkeysObserver::UpdateSoftkeyL

// ---------------------------------------------------------

//

void 

CBrCtlSampleAppSoftkeysObserver::UpdateSoftkeyL

(BrCtlKeySoftkey /*aKeySoftkey*/,

 const TDesC& /*aLabel*/,

 TUint32 /*aCommandId*/,                TBrCtlSoftkeyChangeReason /*aBrCtlSoftkeyChangeReason*/)

 	

    {

 CBrCtlInterface* brCtl = iContainer->BrCtlInterface();



    TBrCtlDefs::TBrCtlElementType type = brCtl-> 

    FocusedElementType();



CEikButtonGroupContainer* current = 

    CEikButtonGroupContainer::Current();



    switch (type)

        {

        case TBrCtlDefs::EElementActivatedInputBox:

            current->SetCommandSetL(R_INPUT_ELEMENT_BUTTONS );

            break;

        

        default:

           current->SetCommandSetL( R_BROWSER_DEFAULT_BUTTONS);

            break;

        }

    current->DrawNow();

    }

Use Case 9: Resolving Links

This section explains how to resolve two different types of links:

• Embedded links
• User-selected links

It also describes the functions called by the host application after the link is resolved, or if an error occurs.

Resolving Embedded Links

If the content of an embedded link is to be loaded from the private store of a host application, such as an email application, then the developer should implement the MBrCtlLinkResolver class. This interface provides a callback mechanism to the host application to transmit the content of an embedded link or the content of a user-initiated load request to the Browser Control.

To enable this callback mechanism, the host application must set the ECapabilityClientResolveEmbeddedURL capability or the ECapabilityClientNotifyURL capability.

If the host application is unable to resolve the embedded link, then the Browser Control tries to handle the request through the HTTP framework.

The following functions of the MBrCtlLinkResolver interface provide the content of an embedded link.

The following examples show how to resolve an embedded link. The ResolveEmbeddedLinkL function retrieves the content of embedded objects. The ResolveLinkL function loads new content identified by a link.

Inherit from the MBrCtlLinkResolver interface

Create an object that inherits from the MBrCtlLinkResolver class:

class CBrCtlSampleAppLinkResolver : public CBase, 

public MBrCtlLinkResolver

    {

    .

    .

    .

    }

Retrieve the content of an embedded object

Implement the ResolveEmbeddedLinkL function to retrieve an image embedded within an HTML-formatted email.

// ---------------------------------------------------------

// CBrCtlSampleAppLinkResolver::ResolveEmbeddedLinkL

// ---------------------------------------------------------

//

TBool 

CBrCtlSampleAppLinkResolver::ResolveEmbeddedLinkL

(const TDesC& aEmbeddedUrl,  

const TDesC& /*aCurrentUrl*/, 

TBrCtlLoadContentType /*aLoadContentType*/, 

MBrCtlLinkContent& aEmbeddedLinkContent) 

    {        

    if (IsFileScheme(aEmbeddedUrl))

        {

        GetFileNameL(aEmbeddedUrl);

        HBufC8* buf = ReadFileLC(*iFileName);

        HBufC* contentType = NULL;

        TPtrC p(NULL, 0);

        contentType = RecognizeLC(*iFileName, *buf);

                             

aEmbeddedLinkContent.HandleResolveComplete(*contentType, 

        p,buf);        

        CleanupStack::PopAndDestroy(2); // contentType, buf

        return ETrue;

        }

    return EFalse;

    } 

Load new content identified by an embedded link

Implement the ResolveLinkL function to load new content identified by a hyperlink within an HTML-formatted email.

// ---------------------------------------------------------

// CBrCtlSampleAppLinkResolver::ResolveLinkL

// ---------------------------------------------------------

//

TBool 

CBrCtlSampleAppLinkResolver::ResolveLinkL

(const TDesC& aUrl, 

 const TDesC& /*aCurrentUrl*/,

 MBrCtlLinkContent& aBrCtlLinkContent) 

    {        

    if (IsFileScheme(aUrl))

        {

        GetFileNameL(aUrl);

        HBufC8* buf = ReadFileLC(*iFileName);

        HBufC* contentType = NULL;

        TPtrC p(NULL, 0);

        contentType = RecognizeLC(*iFileName, *buf);

        aBrCtlLinkContent.HandleResolveComplete(*contentType,

        p, buf);        

        CleanupStack::PopAndDestroy(2); // contentType, buf

        return ETrue;

        }

    return EFalse;

    } 

Resolving user-selected links

If the host application wishes to handle events when the user clicks on a link, it should implement the MBrCtlLinkResolver class. This interface provides a callback mechanism to the host application to handle the events by doing one of the following:

• Providing the content
• Telling the Browser Control to get the content by itself
• Launching a stand-alone Browser. For example, Outlook may launch an instance of Internet Explorer when a user clicks on a hyperlink within an email message.

To enable this callback mechanism, the host application must set the ECapabilityClientNorifyURL capability.

If the host application is unable to resolve the user-initiated load request, then the Browser Control tries to handle the request through the HTTP framework.

The following functions of the MBrCtlLinkResolver interface class provide the content of a load request that was initiated by the user.

MBrCtlLinkContentInterface functions

The Browser Control implements this interface after a link is resolved or an error occurs. The following table lists the functions called by the host application after a link is resolved or after an error occurs in resolving the link.

Use Case 10: Customizing Scroll Bars

To customize a scroll bar based upon one or more layout (scrolling) events, follow these steps:

1. When you create the Browser Control, do not specify the EcapabilityDisplayScrollBar flag.
2. Implement the MBrCtlLayoutObserver interface.

This enables the host application to display and update the scroll bars.

If you wish to have no scroll bars at all, follow Step 1 but do not implement Step 2.

The following functions of the MBrCtlLayoutObserver interface receive scrolling events when the host application draws the scrollbar.

The following sample code illustrates how to customize a scroll bar.

Inherit from the MBrCtlLayoutObserver interface

Create an object that inherits from the MBrCtlLayoutObserver class.

class CBrCtlSampleAppLayoutObserver : public CBase, public MBrCtlLayoutObserver

{

 .

 .

 .

}

Implement the UpdateBrowserScrollBarL functions

Implement the UpdateBrowserHScrollBarL function to update the position of the horizontal scroll bar. Implement the UpdateBrowserVScrollBarL to update the position of the vertical scroll bar.

/ ---------------------------------------------------------

// CBrCtlSampleAppObserver::UpdateBrowserVScrollBarL

// ---------------------------------------------------------

//

void CBrCtlSampleAppLayoutObserver::UpdateBrowserVScrollBarL

(TInt aDocumentHeight,

 TInt aDisplayHeight,

 TInt aDisplayPosY ) 

    

    {

    // Here we are creating a text string that will be

    // displayed on the screen

    // But if you were implementing this method, you most

    // likely would be implementing

    // your own scroll bars here.



    TBuf16<256> tgt;



    TPoint point(0, 100);



    _LIT(KUpdateScrollbar, "Doc Height=%d, Dis Height=%d, 

    Dis Pos=%d");

	

    tgt.AppendFormat(KUpdateScrollbar, aDocumentHeight, 

    aDisplayHeight, aDisplayPosY);



    iContainer->SetPoint(point);



    iContainer->SetText(tgt);



    iContainer->DrawNow();

    }



// ---------------------------------------------------------

// CBrCtlSampleAppObserver::UpdateBrowserHScrollBarL

// ---------------------------------------------------------

//

void CBrCtlSampleAppLayoutObserver::UpdateBrowserHScrollBarL

(TInt aDocumentWidth,

 TInt aDisplayWidth,

 TInt aDisplayPosX ) 



    {

    // Here we are creating a text string that will be

    // displayed on the screen

    // But if you were implementing this method, you most

    // likely would be implementing

    // your own scroll bars here.



    TBuf16<256> tgt;



    TPoint point(0, 130);



    _LIT(KUpdateScrollbar, "Doc Width=%d, Dis Width=%d, 

    Dis Pos=%d");

        

    tgt.AppendFormat(KUpdateScrollbar, aDocumentWidth, 

    aDisplayWidth, aDisplayPosX);



    iContainer->SetPoint(point);



    iContainer->SetText(tgt);



    iContainer->DrawNow();

    }



// ---------------------------------------------------------

// CBrCtlSampleAppObserver::NotifyLayoutChange

// ---------------------------------------------------------

//

void CBrCtlSampleAppLayoutObserver::NotifyLayoutChange

( TBrCtlLayout aNewLayout ) 



    {

    TBuf16<256> tgt;



    TPoint point(0, 120);



    _LIT(KUpdateLayout, "New layout is  %d");



    tgt.AppendFormat(KUpdateLayout, aNewLayout);



    iContainer->SetPoint(point);



    iContainer->SetText(tgt);



    iContainer->DrawNow();

    }

Use Case 11: Receiving Change-of-State Events

A change-of-state event indicates that the state of the Browser has changed. For example, the Browser may switch to or from the Image Map view.

To receive change-of-state events, inherit from the MBrCtlStateChangeObserver interface and implement the StateChanged function.

The following function indicates that the Browser has changed its state.

The following example illustrates how to receive an event that indicates that the state of the Browser has changed.

Inherit from the MBrCtlStateChangeObserver interface

Create an object that inherits from the MBrCtlStateChangeObserver class.

// The StateChangeObserver class inherits from the

//  MBrCtlStateChangeObserver interface



class CBrCtlSampleAppStateChangeObserver : public CBase, 

public MBrCtlStateChangeObserver



{

.

.

.

}

Implement the StateChanged function

The Browser calls the StateChanged function when its state changes to and from the Image Map view.

// ---------------------------------------------------------

// CBrCtlSampleAppStateChangeObserver::StateChanged

// ---------------------------------------------------------

//

void 

CBrCtlSampleAppStateChangeObserver::StateChanged(TBrCtlDefs::

TBrCtlState aState,                                             TInt aValue)

    {

    // Here we are creating a string to be displayed on the

    // screen, but you would implement this method to have

    // code that would be executed when the observer

    // receives state changed events.

    TBuf16<256> tgt; 

    TPoint point(0, 120);

    _LIT(KHandleBrowserStateChange, "State Change event = %d,

    value = %d");

    tgt.AppendFormat(KHandleBrowserStateChange, aState, 

    aValue);

    iContainer->SetPoint(point);

    iContainer->SetText(tgt);

    iContainer->DrawNow();

    }

Use Case 13: Subscribing to Web Feeds

Web feeds provide Web content or summaries of Web content, such as news headlines or the latest blog posting, together with links to the full content. The user can subscribe to XML Web feeds in Really Simple Syndication (RSS) or Atom format. These feeds can be updated and accessed similarly to bookmarks. To create a menu that lists up to 10 Web feed subscription items, follow these steps:

1. Go to the Web page to which you would like to subscribe.
2. Call the SubscribeToMenuItemsL method in the BrCtlInterface.h file.

   This method returns an array of theBrCtlSubscribeTo class, which is in the BrCtlInterface.h file. Each array element contains a URL and associated title and command ID.

3. Build your subscription menu using the information returned.

The following function builds a Subscribe To menu of URLs and their associated page titles.

The following example illustrates how to build a Subscribe To menu:

Error handling

The Browser Control API uses standard Symbian error reporting mechanisms. It does not define any error codes of its own.

Memory overhead

The RAM consumption of the Browser Control is directly related to the size of the content being rendered. For example, loading embedded images and objects increases RAM consumption considerably.

Extensions to the API

The Browser Control API does not explicitly support any extensions.