Inheritance diagram

Collaboration diagram

Description

How to use

The following functions are available in the SFZWebBrowserControl class:

A simple Web Browser can be created easily by only pasting a SFZWebBrowserControl object.

The SFZWebBrowserControl class is implemented base on the IHtmlViewer of BREW API. The limitations of SFZWebBrowserControl class on rendering the HTML data are almost the same as that of IHtmlViewer.

Error Value

Several member functions of SFZWebBrowserControl class record its status internally when an error occurs.

The latest error of member function can be gotten by the static_catch function.

SFERR_NO_ERROR is returned if no error occurs.

The code below is to use the SFZWebBrowserControl class:

SFMTYPEDEFRESPONDER(MyWindow)
class MyWindow : public SFZWindow{
    SFMSEALRESPONDER(MyWindow)
    SFMRESPONDERINSTANTIATEFOUR(MyWindow, SFZWindow, SFYContainer, SFYWidget, SFYResponder)
public:
    static MyWindowSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit MyWindow(Void) static_throws;
    virtual ~MyWindow(Void);

    // define the simple Web Browser as a member function of smart pointer type
    SFZWebBrowserControlSmp _browser;      // simple Web Browser

};

// constructor(error processing is omitted)
MyWindow::MyWindow(Void) static_throws
{
    if (static_try()) {

    // input the browser by string
 SFXAnsiString buffer(
             "BrowserControl<br /><br />"
         "<a href=\"http://www.s-cradle.com/example/tabbrowser/\">Sophia Cradle</a><br /><br />"
        );

    // create a simple Web Browser
        _browser = SFZWebBrowserControl::NewInstance();
        _browser->SetParent(GetThis());
        _browser->SetRealBound(GetLocalBound());
        _browser->SetState(true, true, true, true);

    // start rendering the string as HTML
       _browser->Load(buffer);
   }
}

Reference

SFYControl | SFBHTMLViewer | SFBWeb | BREW API IHtmlViewer

Member

Description

This function terminates communication and rendering of HTML data and releases all the resources internally.

Return value

Description

Return the current history number as 0.

Reference

SFZWebBrowserControl::GetCurrentHistoryIndex

Argument

Description

By default nothing happens when the SFZWebBrowserControl::DoneNotifyHandler function is called.

To do something through this function, it is necessary to override the SFZWebBrowserControl::DoneNotifyHandler function.

The timing when the SFZWebBrowserControl::DoneNotifyHandler function is called is different from that of the SFRBrowserControl::ResponseNotifyHandler function.

Example

The code below is to override this function.

#include <SFZResponder/SFZControl/SFZWebBrowserControl.hpp>

SFMTYPEDEFRESPONDER(MyBrowserControl)
class MyBrowserControl : public SFZWebBrowserControl {
    SFBSEALRESPONDER(MyBrowserControl)
    SFMRESPONDERINSTANTIATEFOUR(MyBrowserControl, SFZWebBrowserControl, SFYControl, SFYWidget, SFYResponder)
public:
    static MyBrowserControlSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit MyBrowserControl(Void) static_throws;
    virtual ~MyBrowserControl(Void);
    virtual Void DoneNotifyHandler(DoneNotifyConstRef notify) {
        if (notify.GetErrorCode() != SFERR_NO_ERROR) {
            // if communication error occored, show the error dialog
            ErrorDialog(notify.GetErrorCode());
        }
        else if (WEB_SUCCEEDED(notify.GetDoneCode())) {
            // if HTTP error occored, show the warning dialog
            WarningDialog(notify.GetResposenCode());
        }
    }
};

Reference

SFZWebBrowserControl::DoneNotify | SFZWebBrowserControl::FocusNotifyHandler | SFZWebBrowserControl::JumpNotifyHandler | SFZWebBrowserControl::ResponseNotifyHandler

Argument

Return value

Return the index of specified element when found. Return a minus value when not found.

Description

The SFZWebBrowserControl::FindElement function is used to search the specified element in the current page. The index of specified element that is found can be used in the SFZWebBrowserControl::GetElementText or SFZWebBrowserControl::GetElementAttribute function.

Reference

SFZWebBrowserControl::GetElementText | SFZWebBrowserControl::GetElementAttribute

Argument

Description

It do nothing in a standard implement.

If do something outside the standard, users need to override the SFZWebBrowserControl::FocusNotifyHandler function.

Reference

SFZWebBrowserControl::FocusNotify | SFZWebBrowserControl::DoneNotifyHandler | SFZWebBrowserControl::JumpNotifyHandler | SFZWebBrowserControl::ResponseNotifyHandler

Return value

History of the current page.

Reference

SFZWebBrowserControl::GetCurrentHistoryIndex | SFZWebBrowserControl::GetHistory

Return value

Current history index of the current page.

Description

It can be modified by Move function, Previous function, and Next function. And can be initialized to 0 by ClearHistory function.

Reference

SFZWebBrowserControl::Move | SFZWebBrowserControl::Previous | SFZWebBrowserControl::Next | SFZWebBrowserControl::ClearHistory

Argument

Return value

Content of attribute. If the specified attribute is not found, an empty string is returned.

Description

Get the attribute of specified element in the current page. if the specified element is not found, an empty string is returned.

	About the attribute without value.
	As for an element such as <HR NOSHADE> which has an attribute without value, when trying to get its attribute, "NOSHADE" which is the same as the name of attribute is returned.

Reference

SFZWebBrowserControl::FindElement | SFZWebBrowserControl::GetElementText

Argument

Return value

Content of element. If the specified element is empty, an empty string is returned.

Description

Get the text of the specified element in the current page.

Reference

SFZWebBrowserControl::FindElement | SFZWebBrowserControl::GetElementAttribute

Argument

Return value

History content. If there is no history content, or the historyIndex argument is invalid, an empty string is set to the "url" member of SFZWebBrowserControl::HistoryEntry structure.

Reference

SFZWebBrowserControl::GetHistoryList | SFZWebBrowserControl::GetCurrentHistory

Return value

Pointer to the history list: an array of SFZWebBrowserControl::HistoryEntry structure, which size is the return value by the SFZWebBrowserControl::GetHistorySize function.

Description

The top entry of history list is the latest history, and the history number matches the index of entry of history list.

If no information is set to a history entry, its "url" member of SFZWebBrowserControl::HistoryEntry structure is set to an empty string.

	Warning
	The history list returned by the SFZWebBrowserControl::GetHistoryList function must not be modified.

Example

Display all the titles and URLs in the history list for debugging.

void PrintHistoryList(SFBrowserControlConstRef browser)
{
    int i;
    SFBrowserControl::HistoryEntryConstPtr historyList = browser.GetHistoryList();
    for (i=0; i < browser.GetHistorySize(); i++) {
        DBGPRINTF("title '%s' url %s",
                  (ACharConstPtr)historyList[i].title, (ConstACharPtr)historyList[i].url); 
    }
}

Reference

SFZWebBrowserControl::GetHistorySize

Return value

Number of entries in the current history list.

Description

The history number used by the SFZWebBrowserControl::Move or SFZWebBrowserControl::GetHistory function must be less than the number of entries in history list returned by the SFZWebBrowserControl::GetHistorySize function.

* The size of history list returned by the SFZWebBrowserControl::GetHistoryList function equals the return value of SFZWebBrowserControl::GetHistorySize function.

Reference

SFZWebBrowserControl::GetHistory | SFZWebBrowserControl::GetHistoryList | SFZWebBrowserControl::Move | SFZWebBrowserControl::SetHistorySize

Return value

Width of specified indent in pixels.

Reference

SFZWebBrowserControl::SetIndent

Return value

Color of the link text.

Reference

SFZWebBrowserControl::SetLinkColor | SFZWebBrowserControl::GetTextColor

Return value

Space between paragraphs in pixels.

Reference

SFZWebBrowserControl::SetParagraphSpacing

Return value

Width of scroll bar in pixels.

Reference

SFZWebBrowserControl::SetScrollbarWidth

Return value

Text color of HTML.

Reference

SFZWebBrowserControl::SetTextColor | SFZWebBrowserControl::GetLinkColor

Return value

IWeb instance for communication. If the IWeb instance is not set by the SFZWebBrowserControl::SetWeb function and the IWeb instance is not created internally, return null.

Description

	Caution when specifying the WebOpt.
	Though any WebOpt can be set to the IWeb instance, the user setting of WebOpt must be preserved until another IWeb instance is used. Please see the "Instructions about the life-time of WEBOPT" in the BREW API Reference.

	The behavior when suspended.
	When suspended, the IWeb instance is set to be created internally by default settings. At this time, the information on WebOpt settings is also reset. To continue to use your own IWeb instance, set it by the resume handler again.

Reference

SFBWeb | SFZWebBrowserControl::UnsetWeb | SFZWebBrowserControl::SetWeb

Return value

Return value

Reference

SFZWebBrowserControl::SetInlineEditEnable

Return value

Reference

SFZWebBrowserControl::SetScrollbarEnable

Argument

Description

Open the linked URL automatically.

The SFZWebBrowserControl::JumpNotifyHandler function do nothing except the http://, https://, file://, and res:// streams.

To do something other than default settings, it is necessary to override the SFZWebBrowserControl::JumpNotifyHandler function.

Example

The code below is to override the SFZWebBrowserControl::JumpNotifyHandler function.

#include <SFZResponder/SFZControl/SFZWebBrowserControl.hpp>

SFMTYPEDEFRESPONDER(MyBrowserControl)
class MyBrowserControl : public SFZWebBrowserControl {
    SFBSEALRESPONDER(MyBrowserControl)
    SFMRESPONDERINSTANTIATEFOUR(MyBrowserControl, SFZWebBrowserControl, SFYControl, SFYWidget, SFYResponder)
public:
    static MyBrowserControlSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit MyBrowserControl(Void) static_throws;
    virtual ~MyBrowserControl(Void);
    virtual Void JumpNotifyHandler(JumpNotifyConstRef notify) {
        if (notify.GetUrl().StartWith("mailto:")) {
            // if it's "mailto:", call the mailer
            Mailer(notify.GetUrl());
        }
        else {
            // or just call the standard handler
     SFZWebBrowserControl::JumpNotifyHandler(notify);
        }
    }
};

Reference

SFZWebBrowserControl::JumpNotify | SFZWebBrowserControl::Navigate | SFZWebBrowserControl::DoneNotifyHandler | SFZWebBrowserControl::FocusNotifyHandler | SFZWebBrowserControl::ResponseNotifyHandler

Argument

Return value

Description

Immediately after the inline image is received, it is displayed.

	About communication error:
	The communication errors cannot be gotten from the return value of SFZWebBrowserControl::Load function. To get the communication errors or the event that rendering is finished, it is necessary to create a new class inheriting from the SFZWebBrowserControl class with overrided SFZWebBrowserControl::DoneNotifyHandler function.

Reference

SFZWebBrowserControl::Navigate | SFZWebBrowserControl::DoneNotifyHandler

Argument

Return value

Description

If the specified index is greater than the size of history list, or there is no history entry of specified index, SFERR_INVALID_PARAM is returned as an error.

	About communication error:
	The communication errors cannot be gotten from the return value of SFZWebBrowserControl::Move function. To get the communication errors or the event that rendering is finished, it is necessary to create a new class inheriting from the SFZWebBrowserControl class with overrided SFZWebBrowserControl::DoneNotifyHandler function.

Reference

SFZWebBrowserControl::DoneNotifyHandler | SFZWebBrowserControl::Navigate | SFZWebBrowserControl::Previous | SFZWebBrowserControl::Next | SFZWebBrowserControl::Reload

Argument

Return value

Description

Immediately after the inline image is received, it is displayed.

	The Errors about communication.
	The Errors about communication cannot be gotten by return values. While finishing rendering and getting the errors about communication, It is necessary to inherit from the SFZWebBrowserControl class, create a new class with overrided DoneNotifyHandler function.

Reference

SFZWebBrowserControl::Load | SFZWebBrowserControl::DoneNotifyHandler

Argument

Return value

Description

If the specified index number is negative, the history entry go back by its absolute value is displayed. If it is out of the history list, SFERR_INVALID_PARAM is returned as an error.

	About communication error:
	The communication errors cannot be gotten from the return value of SFZWebBrowserControl::Next function. To get the communication errors or the event that rendering is finished, it is necessary to create a new class inheriting from the SFZWebBrowserControl class with overrided SFZWebBrowserControl::DoneNotifyHandler function.

Reference

SFZWebBrowserControl::DoneNotifyHandler | SFZWebBrowserControl::Navigate | SFZWebBrowserControl::Move | SFZWebBrowserControl::Previous | SFZWebBrowserControl::Reload

Argument

Return value

Description

If the specified index number is negative, the history entry go back by its absolute value is displayed. If it is out of the history list, SFERR_INVALID_PARAM is returned as an error.

	About communication error:
	The communication errors cannot be gotten from the return value of SFZWebBrowserControl::Previous function. To get the communication errors or the event that rendering is finished, it is necessary to create a new class inheriting from the SFZWebBrowserControl class with overrided SFZWebBrowserControl::DoneNotifyHandler function.

Reference

SFZWebBrowserControl::DoneNotifyHandler | SFZWebBrowserControl::Navigate | SFZWebBrowserControl::Move | SFZWebBrowserControl::Next | SFZWebBrowserControl::Reload

Description

When the current page is displayed by the SFZWebBrowserControl::Load function or by the SFZWebBrowserControl::Navigate function with the argument of IAStream or ISource, the redrawing fails if its "url" is not set validlly.

Reference

SFZWebBrowserControl::Load | SFZWebBrowserControl::Navigate

Argument

Return value

Description

This function is called before rendering.

The standard implement is to do nathing and return a false. To do any other process, it is necessary to overrice the ResponseNotifyHandler() function.

This function is different with SFZWebBrowserControl::DoneNotifyHandler in the timing being called.

Example

The code below is to override this function.

#include <SFZResponder/SFZControl/SFZWebBrowserControl.hpp>

SFMTYPEDEFRESPONDER(MyBrowserControl)
class MyBrowserControl : public SFZWebBrowserControl {
    SFBSEALRESPONDER(MyBrowserControl)
    SFMRESPONDERINSTANTIATEFOUR(MyBrowserControl, SFZWebBrowserControl, SFYControl, SFYWidget, SFYResponder)
public:
    static MyBrowserControlSmp NewInstance(SFCErrorPtr exception = null);
protected:
    explicit MyBrowserControl(Void) static_throws;
    virtual ~MyBrowserControl(Void);
    virtual Void ResponseNotifyHandler(ResponseNotifyConstRef notify) {
        if (notify.GetErrorCode() != SFERR_NO_ERROR) {
            // if there is a communication error, show the error dialog, stop rendering
            ErrorDialog(notify.GetErrorCode());
            return true;
        }
        else if (WEB_SUCCEEDED(notify.GetDoneCode())) {
            // if there is a HTTP error, show the warning dialog
            WarningDialog(notify.GetResposenCode());
        }
        return false;  // if there is normal or warning, render the HTML page
    }
};

Reference

SFZWebBrowserControl::ResponseNotify | SFZWebBrowserControl::DoneNotifyHandler | SFZWebBrowserControl::FocusNotifyHandler | SFZWebBrowserControl::JumpNotifyHandler

Argument

Return value

The Basic HTTP authorization is not processed when an error code other than SFERR_NO_ERROR is returned.

Description

After this setting, all the http request headers are included with this authorization information when accessing the web pages .

When accessing the web pages not reachable from the specified URL link, this authorization settings are canceled.

To cancel the authorization settings, use the UnsetAuthorizeData function.

Reference

SFZWebBrowserControl::UnsetAuthorizeData

Argument

Return value

The size of history list is not modified when an error code other than SFERR_NO_ERROR is returned.

Description

If the value less than the size of current history list is set, old history entries outside the specified size are removed.

The value less than the size returned by SFZWebBrowserControl::GetCurrentHistoryIndex function cannot be set.

Reference

SFZWebBrowserControl::GetCurrentHistoryIndex | SFZWebBrowserControl::GetHistory | SFZWebBrowserControl::GetHistoryList | SFZWebBrowserControl::Move | SFZWebBrowserControl::SetHistorySize

Argument

Return value

Reference

SFZWebBrowserControl::GetIndent

Argument

Return value

Return SFERR_NO_ERROR.

Reference

SFZWebBrowserControl::IsInlineEditEnable

Argument

Return value

Reference

SFZWebBrowserControl::GetLinkColor | SFZWebBrowserControl::SetTextColor

Argument

Return value

Reference

SFZWebBrowserControl::GetParagraphSpacing

Argument

Return value

Return SFERR_NO_ERROR.

Description

The scroll bar here is not of SophiaFramework UNIVERSE, but of the standard BREW.

Reference

SFZWebBrowserControl::IsScrollbarEnable

Argument

Return value

Reference

SFZWebBrowserControl::GetScrollbarWidth

Argument

Return value

Reference

SFZWebBrowserControl::GetTextColor | SFZWebBrowserControl::SetLinkColor

Argument

Description

Use the specified IWeb interface for HTTP accessing.

If it is under rendering, or communicating, interrupt it.

	Caution when specify the WebOpt.
	Though any WebOpt can be set for gotten IWeb instance, the user-set data of WebOpt should be kept by user till it is useable by another IWeb instance. Please see the "Instructions about the life-time of WEBOPT" in BREW API Reference.

	The behavior when suspend.
	When suspend, the IWeb instance is set to be created internally as default. At this time, the information of specified WebOpt will be reset, too. When continue to use user-original IWeb instance, Please reset it by resume handler.

The specified value can be gotten by GetWeb function.

Example

Set the user agent name.

The setting will be abandoned if the device suspends. It is necessary to set in the resume handler again.

SCError SetUserAgent(SFZWebBrowserControlRef browser) {
    SFBWebSmp web;
    web = browser.GetWeb();
    if (web == null) {
        web = SFBWeb::Instance();
    }
    
    WebOpt opts[2];
    opts[0].nId = WEB_HEADER;
    // do not release the setting string if it is in effective until you secure the heap of it
    opts[0].pVal = "User-Agent: ibROWSE/0.1 (SophiaFramework; I; BREW 3.1)\r\n";
    opts[1].nId = WEBOPT_END;
    opts[1].pVal = null;

    int s = web->AddOpt(opts);
    if (s != SFERR_NO_ERROR) {
        return s;
    }
    browser.SetWeb(web);
    return SFERR_NO_ERROR;
}

Reference

SFBWeb | SFZWebBrowserControl::UnsetWeb | SFZWebBrowserControl::GetWeb

Description

Nothing happens except under accessing the network or rendering. The content that has already been displayed takes no influence by calling the SFZWebBrowserControl::Stop function.

Return value

Description

The SFZWebBrowserControl::UnsetAuthorizeData function used to cancel the settings for Basic HTTP authorization set by the SFZWebBrowserControl::SetAuthorizeData function.

After calling this function, information on the Basic HTTP authorization is not included with the http request header.

Reference

SFZWebBrowserControl::SetAuthorizeData

Description

The SFZWebBrowserControl::UnsetWeb function is used to have the IWeb interface for communication to be created inside the control.

In case of rendering or communicating, its process is interrupted.

Reference

SFBWeb | SFZWebBrowserControl::SetWeb | SFZWebBrowserControl::GetWeb

Description

Only HISTORY_SIZE is defined to represent the size of history list.

Reference

SFZWebBrowserControl::GetHistorySize | SFZWebBrowserControl::SetHistorySize

Description

The DoneNotify class is derived from the HVNotify of BREW API.

The DoneNotify class is mainly used as the argument of SFZWebBrowserControl::DoneNotifyHandler function.

The member functions of DoneNotify class are as below:

Reference

SFZWebBrowserControl::DoneNotifyHandler

Description

The FocusNotify class is derived from the HVNotify of BREW API.

The FocusNotify class is mainly used as the argument of SFZWebBrowserControl::FocusNotifyHandler function.

The member functions of FocusNotify class are as below:

Reference

SFZWebBrowserControl::FocusNotifyHandler

Reference

SFZWebBrowserControl::GetHistory | SFZWebBrowserControl::GetHistoryList

Description

The JumpNotify class is derived from the HVNotify of BREW API.

The JumpNotify class is mainly used as the argument of SFZWebBrowserControl::JumpNotifyHandler function.

The member functions of JumpNotify class are as below:

Reference

SFZWebBrowserControl::JumpNotifyHandler

Description

The ResponseNotify class is derived from the HVNotify of BREW API.

The ResponseNotify class is mainly used as the argument of SFZWebBrowserControl::ResponseNotifyHandler function.

The member functions of ResponseNotify class are as below:

Reference

SFZWebBrowserControl::ResponseNotifyHandler