Inheritance diagram

Collaboration diagram

Description

The following functions are available in the SFRBrowserControl class:

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

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

Error Value

Several member functions of SFRBrowserControl class record its status internally if 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 a simple Web Browser:

SFMTYPEDEFCLASS(MyWindow)
class MyWindow : public SFRTitleWindow {
    SFMSEALCOPY(MyWindow)
public:
    MyWindow(Void) static_throws;
    virtual ~MyWindow(Void) { return; }
    
    // define the simple Web Browser as a member function of pointer type
    SFRBrowserControlPtr     _browser;      // simple Web Browser

};

// constructor(error processing is omitted)
MyWindow::MyWindow(Void) : SFRTitleWindow(SFRApplication::GetInstance(),
    SFXRectangle(20, 20, 200, 250), "my window") static_throws
{
    
    // input the browser by string
    SFXAnsiString buffer(
         "BrowserControl<br /><br />"
         "<a href=\"/example/tabbrowser/\">Sophia Cradle</a><br /><br />"
    );
				
    // create a simple Web Browser
    // the first argument: parent responder
    // the second argument: position and size of the tab
    _browser = ::new SFRBrowserControl(this, rect);
				
    // start rendering the string as HTML
   _browser->Load(buffer);
			
    return;
}

Reference

SFRResponder | SFRApplication | SFRWindow | SFRDialog | SFRControl | SFBHTMLViewer | SFBWeb | Simple Web Browser

Member

Return value

Description

Initialize member variables, and create the IHtmlViewer interface for rendering the web pages.(*)

* The IWeb interface is not created here.

Description

The SFRBrowserControl::~SFRBrowserControl 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

SFRBrowserControl::GetCurrentHistoryIndex

Argument

Description

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

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

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

Example

The code below is to override this function.

#include <SFRResponder/SFRControl/SFRBrowserControl.hpp>

class MyBrowserControl : public SFRBrowserControl {
public:
    MyBrowserControl(SFRResponderPtr director, SFXRectangleConstRef rect)
        : SFRBrowserControl(director, rect) {
    }

protected:
    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

SFRBrowserControl::DoneNotify | SFRBrowserControl::FocusNotifyHandler | SFRBrowserControl::JumpNotifyHandler | SFRBrowserControl::ResponseNotifyHandler

Argument

Return value

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

Description

The SFRBrowserControl::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 SFRBrowserControl::GetElementText or SFRBrowserControl::GetElementAttribute function.

Reference

SFRBrowserControl::GetElementText | SFRBrowserControl::GetElementAttribute

Argument

Description

It do nothing in a standard implement.

If do something outside the standard, users need to override the FocusNotifyHandler() function.

Reference

SFRBrowserControl::FocusNotify | SFRBrowserControl::DoneNotifyHandler | SFRBrowserControl::JumpNotifyHandler | SFRBrowserControl::ResponseNotifyHandler

Return value

It returns the history of the current page.

Reference

SFRBrowserControl::GetCurrentHistoryIndex | SFRBrowserControl::GetHistory

Return value

It returns the 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

SFRBrowserControl::Move | SFRBrowserControl::Previous | SFRBrowserControl::Next | SFRBrowserControl::ClearHistory

Argument

Return value

Return the 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

SFRBrowserControl::FindElement | SFRBrowserControl::GetElementText

Argument

Return values

Return the content of the 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

SFRBrowserControl::FindElement | SFRBrowserControl::GetElementAttribute

Argument

Return value

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

Reference

SFRBrowserControl::HistoryEntry | SFRBrowserControl::GetHistoryList | SFRBrowserControl::GetCurrentHistory

Return value

Return a pointer to the history list: an array of SFRBrowserControl::HistoryEntry structure, which size is the return value by the SFRBrowserControl::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 SFRBrowserControl::HistoryEntry structure is set to an empty string.

	Warning
	The history list returned by the SFRBrowserControl::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

SFRBrowserControl::HistoryEntry | SFRBrowserControl::GetHistorySize

Return value

Return the number of entries in the current history list.

Description

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

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

Reference

SFRBrowserControl::GetHistory | SFRBrowserControl::GetHistoryList | SFRBrowserControl::Move | SFRBrowserControl::SetHistorySize

Return value

Return the width of specified indent in pixels.

Reference

SFRBrowserControl::SetIndent

Return value

Return the color of link text.

Reference

SFRBrowserControl::SetLinkColor | SFRBrowserControl::GetTextColor

Return value

Return the spacing between paragraphs in pixels.

Reference

SFRBrowserControl::SetParagraphSpacing

Return value

Return the width of scroll bar in pixels.

Reference

SFRBrowserControl::SetScrollbarWidth

Return value

Return the text color of HTML.

Reference

SFRBrowserControl::SetTextColor | SFRBrowserControl::GetLinkColor

Return value

If the IWeb instance is not set by the SFRBrowserControl::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 | SFRBrowserControl::UnsetWeb | SFRBrowserControl::SetWeb

Return value

Return value

Reference

SFRBrowserControl::SetInlineEditEnable

Return value

Reference

SFRBrowserControl::SetScrollbarEnable

Argument

Description

Open the linked URL automatically.

The SFRBrowserControl::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 SFRBrowserControl::JumpNotifyHandler function.

Example

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

#include <SFRResponder/SFRControl/SFRBrowserControl.hpp>

class MyBrowserControl : public SFRBrowserControl {
public:
    MyBrowserControl(SFRResponderPtr director, SFXRectangleConstRef rect)
        : SFRBrowserControl(director, rect) {
    }

protected:
    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
     SFRBrowserControl::JumpNotifyHandler(notify);
        }
    }
};

Reference

SFRBrowserControl::JumpNotify | SFRBrowserControl::Open | SFRBrowserControl::DoneNotifyHandler | SFRBrowserControl::FocusNotifyHandler | SFRBrowserControl::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 SFRBrowserControl::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 SFRBrowserControl class with overrided SFRBrowserControl::DoneNotifyHandler function.

Reference

SFRBrowserControl::Open | SFRBrowserControl::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 SFRBrowserControl::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 SFRBrowserControl class with overrided SFRBrowserControl::DoneNotifyHandler function.

Reference

SFRBrowserControl::DoneNotifyHandler | SFRBrowserControl::Open | SFRBrowserControl::Previous | SFRBrowserControl::Next | SFRBrowserControl::Reload

Argument

Return value

Instruction

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 SFRBrowserControl::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 SFRBrowserControl class with overrided SFRBrowserControl::DoneNotifyHandler function.

Reference

SFRBrowserControl::DoneNotifyHandler | SFRBrowserControl::Open | SFRBrowserControl::Move | SFRBrowserControl::Previous | SFRBrowserControl::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 SFRBrowserControl class, create a new class with overrided DoneNotifyHandler function.

Reference

SFRBrowserControl::Load | SFRBrowserControl::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 SFRBrowserControl::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 SFRBrowserControl class with overrided SFRBrowserControl::DoneNotifyHandler function.

Reference

SFRBrowserControl::DoneNotifyHandler | SFRBrowserControl::Open | SFRBrowserControl::Move | SFRBrowserControl::Next | SFRBrowserControl::Reload

Description

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

Reference

SFRBrowserControl::Load | SFRBrowserControl::Open

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 SFRBrowserControl::DoneNotifyHandler in the timing being called.

Example

The code below is to override this function.

#include <SFRResponder/SFRControl/SFRBrowserControl.hpp>

class MyBrowserControl : public SFRBrowserContorl {
public:
    MyBrowserControl(SFRResponderPtr director, SFXRectangleConstRef rect)
        : SFRBrowserControl(director, rect) {
    }

protected:
    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

SFRBrowserControl::ResponseNotify | SFRBrowserControl::DoneNotifyHandler | SFRBrowserControl::FocusNotifyHandler | SFRBrowserControl::JumpNotifyHandler

Argument

Return value

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

Instruction

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

SFRBrowserControl::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 SFRBrowserControl::GetCurrentHistoryIndex function cannot be set.

Reference

SFRBrowserControl::GetCurrentHistoryIndex | SFRBrowserControl::GetHistory | SFRBrowserControl::GetHistoryList | SFRBrowserControl::Move | SFRBrowserControl::SetHistorySize

Argument

Return value

Reference

SFRBrowserControl::GetIndent

Argument

Return value

Reference

SFRBrowserControl::IsInlineEditEnable

Argument

Return value

Reference

SFRBrowserControl::GetLinkColor | SFRBrowserControl::SetTextColor

Argument

Return value

Reference

SFRBrowserControl::GetParagraphSpacing

Argument

Return value

Description

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

Reference

SFRBrowserControl::IsScrollbarEnable

Argument

Return value

Reference

SFRBrowserControl::GetScrollbarWidth

Argument

Return value

Reference

SFRBrowserControl::GetTextColor | SFRBrowserControl::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(SFRBrowserControlRef 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 | SFRBrowserControl::UnsetWeb | SFRBrowserControl::GetWeb

Description

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

Return value

Description

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

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

Reference

SFRBrowserControl::SetAuthorizeData

Description

The SFRBrowserControl::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 | SFRBrowserControl::SetWeb | SFRBrowserControl::GetWeb

Description

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

Reference

SFRBrowserControl::GetHistorySize | SFRBrowserControl::SetHistorySize

Description

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

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

The member functions of DoneNotify class are as below:

Reference

SFRBrowserControl::DoneNotifyHandler

Description

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

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

The member functions of FocusNotify class are as below:

Reference

SFRBrowserControl::FocusNotifyHandler

Reference

SFRBrowserControl::GetHistory | SFRBrowserControl::GetHistoryList

Description

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

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

The member functions of JumpNotify class are as below:

Reference

SFRBrowserControl::JumpNotifyHandler

Description

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

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

The member functions of ResponseNotify class are as below:

Reference

SFRBrowserControl::ResponseNotifyHandler