Web Browser Engine

Web Browser Engine
Developer’s Guide
For QNX ® Neutrino® 6.4 or 6.5
© 2010, QNX Software Systems GmbH & Co. KG.

© 2010 QNX Software Systems. All rights reserved.
Published under license by:
QNX Software Systems Co.
175 Terence Matthews Crescent
Kanata, Ontario
K2M 1W8
Canada
Voice: +1 613 591-0931
Fax: +1 613 591-3579
Email: info@qnx.com
Web: http://www.qnx.com/
Publishing history
Electronic edition published 2010.
QNX, Neutrino, Photon, Photon microGUI, Momentics, Aviage, and related marks, names, and logos are trademarks, registered in certain jurisdictions, of QNX Software
Systems GmbH & Co. KG. and are used under license by QNX Software Systems Co. All other trademarks belong to their respective owners.
Contents
About This Guide vii

What’s in this guide? ix
Typographical conventions ix
Note to Windows users x
Technical support x
1 Overview of the Web Browser Engine 1
2 Running the Web Browser Engine Sample

Application 7
Run the sample application 9
Getting a more responsive mouse pointer 9
3 WebView 11
advanceFocus() 15
canShowMIMEType() 16
canShowMIMETypeAsHTML() 17
close() 18
createInstance() 19
goBack() 20
goForward() 21
initWithFrame() 22
mainFrame() 23
onExpose() 24
onKeyDown() 25
onKeyUp() 26
onMouseMotion() 27
onMouseButtonDown() 28
onMouseButtonUp() 29
resetPageZoom() 30
scrollBy() 31
scrollableSubFrameAtPoint() 32
scrollRenderobjectBy() 33
May 10, 2010 Contents iii

scrollableRenderobjectAtPoint() 34
setPageSizeMultiplier() 35
setDownloadDelegate() 36
setMIMETypesShownAsHTML() 37
setMIMETypesShownAsHTML() 38
setWebNotificationDelegate() 39
setViewWindow() 40
zoomPageOut() 41
zoomPageIn() 42
4 WebNotificationDelegate 43
finishedLoadNotification() 46
hoverOverLink() 47
loadError() 48
progressNotification() 49
startLoadNotification() 50
setTitle() 51
showToolTip() 52
showStatus() 53
unknownContentType() 54
createWindow() 55
getInstancePtr() 56
5 GfWindow 57
restoreViewState() 60
saveViewState() 61
setInputMethodState() 62
setInstancePtr() 63
runJavaScriptAlert() 64
runJavaScriptPrompt() 65
runJavaScriptConfirm() 66
textFieldBegin() 67
textFieldEnd() 68
updateScreen() 69
6 WebFrame 71
stopLoading() 74
reload() 75
loadURL() 76
A What’s New 77
iv Contents May 10, 2010

What’s new for the Web Browser Engine for QNX Neutrino 6.5.0 79
May 10, 2010 Contents v

About This Guide
May 10, 2010 About This Guide vii

© 2010, QNX Software Systems GmbH & Co. KG. Typographical conventions
What’s in this guide?

This guide describes how to use the Web Browser Engine for the QNX Neutrino
RTOS.
If you’re familiar with earlier versions of the Web Browser Engine, you should read
the What’s New appendix to find out the Web Browser Engine has changed in this
release.
Typographical conventions
Throughout this manual, we use certain typographical conventions to distinguish
technical terms. In general, the conventions we use conform to those found in IEEE
POSIX publications. The following table summarizes our conventions:
Reference Example
Code examples if( stream == NULL )
Command options -lR
Commands make
Environment variables PATH
File and pathnames /dev/null
Function names exit()
Keyboard chords Ctrl-Alt-Delete
Keyboard input something you type
Keyboard keys Enter
Program output login:
Programming constants NULL
Programming data types unsigned short
Programming literals 0xFF, "message string"
Variable names stdin
User-interface components Cancel
We use an arrow (→) in directions for accessing menu items, like this:
You’ll find the Other... menu item under Perspective→Show View.
We use notes, cautions, and warnings to highlight important messages:
May 10, 2010 About This Guide ix

Technical support © 2010, QNX Software Systems GmbH & Co. KG.
Notes point out something important or useful.
!
CAUTION: Cautions tell you about commands or procedures that may have
unwanted or undesirable side effects.
WARNING: Warnings tell you about commands or procedures that could be

dangerous to your files, your hardware, or even yourself.
Note to Windows users

In our documentation, we use a forward slash (/) as a delimiter in all pathnames,
including those pointing to Windows files.
We also generally follow POSIX/UNIX filesystem conventions.
Technical support
To obtain technical support for any QNX product, visit the Support area on our
website (www.qnx.com). You’ll find a wide range of support options, including
community forums.
x About This Guide May 10, 2010

Chapter 1
Overview of the Web Browser Engine
May 10, 2010 Chapter 1 • Overview of the Web Browser Engine 1

This Overview of the QNX Web Browser Engine describes the following:
• What is the Web Browser Engine?
• Organization of the Web Browser Engine
• Web Browser Engine supported features
• Building Your Own Web Browser Engine-based Browser
• Web Browser Engine Reference Application
What is the Web Browser Engine?

The QNX Web Browser Engine is based on the WebKit open source web browser
engine.
For more information on the Webkit open source web browser project, see:
• http://webkit.org/ — the WebKit open source project home page.
The Web Browser Engine provides a set of core classes that you can use to display
web content in a window. By default, the Web Browser Engine implements the most
basic functionality of a browser, such as the ability to follow links and the ability to
download and display content. You can use the provided functionality of the Web
Browser Engine at the most basic level to display web content in your application, or
you can use the Web Browser Engine API to create your own full-featured,
customized, web-based application.
Downloading and browsing content from the Web can be a fairly daunting task for a
browser, given the wide variety of content and encoding types in use on the Internet.
The Web Browser Engine handles these different content types transparently by
creating and managing the objects necessary to render the incoming content. The Web
Browser Engine provides view classes that are used to display content. Each view
class (called a WebView) contains frames, called WebFrames with each frame
implementing it’s own scrollbar. You do not need to implement custom views or
custom frames in order to display content in your application.
For more information, see the WebView and WebFrame classes.
If you do want to create a custom browser application, you can implement the
provided delegate objects to handle client requests, resource loading, content
downloading, and general user interface look and feel. Delegates are used to intercept
messages and make decisions based on how you want the browser to look or behave in
certain situations. The Web Browser Engine provides a
WebNotificationDelegate class that you can extend to override default
notification behavior. For instance, the WebNotificationDelegate class contains
methods that are called when pages are loaded and when a user hovers over a frame.
For more information, see the WebNotificationDelegate class.

Organization of the Web Browser Engine

The $QNX_TARGET/opt/webkit/ directory contains the Web Browser Engine
library and a simple Graphics Framework-based example browser application. The
directory has the following file structure:
processor/bin Contains the wklauncher application. The wklauncher sample

is included to provide an example of a simple Web Browser
Engine-based application.
processor/lib As wklauncher runs, it loads the Web Browser Engine library,

and various third-party shared libraries that are not shipped with
6.4.1. These are located here.
etc/fonts Contains font configuration files, including fonts.conf. These

are used by the third-party libfontconfig library, which in turn
is used by the libfreetype library. The FONTCONFIG_PATH
environment variable can be used to tell libfontconfig which
directories to search for fonts.conf and other configuration
files. Use a colon to separate multiple path names. By default, the
wklauncher sample browser will look in
/opt/webkit/etc/fonts or
$QNX_TARGET/opt/webkit/etc/fonts. You can override
these locations.
Note that the fonts.conf file contains a font directory list, which currently contains
only /usr/photon/font_repository. You should change this location to the
actual location of your TrueType font files.
ssl Contains a Root certificate bundle used by the Web Browser

Engine to access most secure web sites. You can specify the full
path name of this file by using the CURLOPT_CAINFO
environment variable. By default, wklauncher uses the name
/opt/webkit/ssl/ca-bundle.crt. If this file does not exist it
will use $QNX_TARGET//opt/webkit/ssl/ca-bundle.crt.
You can override this filename by setting the CURLOPT_CAINFO
environment variable yourself.
webkit Contains images used for the buttons displayed by wklauncher.

These PNG files must be located in one of the following two
directories: /opt/webkit/webkit/, or
$QNX_TARGET/opt/webkit/webkit/.
Web Browser Engine supported features

The Web Browser Engine has support for the following features:
• HTML parsing (HTML 4.01)
4 Chapter 1 • Overview of the Web Browser Engine May 10, 2010

• CSS parsing (CSS 2.1 and parts of CSS 3)

• Javascript interpreting (Javascript 1.5, also 1.7 and ECMA-262 3rd edition
• Layout
• Document Object Model (DOM Level 1 and 2
• XML parsing (XHTML 1.1 and XML)
• XSLT and XPath 1.0
• HTML canvas and AJAX
• SMIL 2.2 or 2.3
• Image formats: jpeg, gif, png
• HTTP 1.1, HTTP Cookies
• SSL3/TLS1.0
• SSL Root Certificates Support: VeriSign, Entrust, Thawte, Baltimore.
• Support of externally supplied fonts
The Web Browser Engine supports the following encodings:
• Unicode (UTF 8, UTF 16)

• legacy encodings (e.g. ISO 8859-1, Windows-1251, Shift-JIS, Big 5)
The Web Browser Engine supports the following character sets:
• Traditional
• Japanese
• Chinese
• Korean
Building Your Own Web Browser Engine-based Browser

Source code for the Web Browser Engine library and wklauncher sample browser is
available in the QNX Foundry27 “web-browsers” project. Currently, when you build
your own browser application, you must also build the Web Browser Engine library.
The SVN repository is called “web-browsers”, and is divided into Web Browser
Engine source and third-party support library source. The top-level of the trunk of the
Web Browser Engine respository location contains a README file with further
instructions on how to build the Web Browser Engine using either Linux or Neutrino
SDP 6.4.
Note that the source code for the wklauncher sample browser can be found here:
[web-browsers]/webkit/trunk/WebKitTools/OWBLauncher/Gf/main.cpp

Web Browser Engine Reference Application

The Web Browser Engine comes with a reference application that you can use to build
your own custom browser-based application.
For information on running the Web Browser Engine sample application, see Running
the Web Browser Engine Sample Application.
6 Chapter 1 • Overview of the Web Browser Engine May 10, 2010

Chapter 2
Running the Web Browser Engine Sample
Application
May 10, 2010 Chapter 2 • Running the Web Browser Engine Sample Application 7
The Web Browser Engine comes with a sample GF-based application called
Wklauncher that demonstrates the Web Browser Engine API.
Because the Web Browser Engine library uses GF to render, you must ensure that
io-display is running and properly configured to use the correct display resolution
and color depth.
Wklauncher also requires a devi driver such as devi-hid in order to use keyboard
or mouse input. For example:
devi-hid -P mouse kbd
The following procedure assumes that you are running the sample application from a
self-hosted system.
Run the sample application

To run the Wklauncher sample:
1 At the command-line prompt, set the LD_LIBRARY_PATH so that the required

shared libraries can be found:
export LD_LIBRARY_PATH=$QNX_TARGET/opt/webkit/x86/lib:$LD_LIBRARY_PATH
2 Type the following command to run Wklauncher:

$QNX_TARGET/opt/webkit/x86/bin/wklauncher url
where url is the fully qualified URL of the page that you want to launch in the
browser.
Ensure that you have provided a fully qualified URL. The Wklauncher sample does
not assume the http:// prefix.
The Wklauncher sample application does not provide a field to enter a URL. You can
navigate using your favourite search engine on the Web. Remember that Wklauncher
is only a basic sample application designed to show you how to create a browser-based
application using the Web Browser Engine API. You can add a navigation bar, as well
as other common browser features by using the Web Browser Engine API.
Getting a more responsive mouse pointer

The Wklauncher application uses a hardware cursor to display and move the mouse
pointer. On some websites, you may notice that mouse pointer responsiveness is less
than ideal. In the interest of keeping Wklauncher event-handling simple, this issue
has not been resolved.
One way to solve this issue is to use a separate process to display and move the
hardware cursor. QNX Neutrino 6.4.1 provides an example application called
gfi-demo that you can run as a separate process to display and move the mouse
cursor. You may need to run it at a higher priority to ensure smooth movement when
the Web Browser Engine is busy. In some cases you may also need to run devi-hid
May 10, 2010 Chapter 2 • Running the Web Browser Engine Sample Application 9
and or io-hid at a higher priority. The Wklauncher application has a -C

command-line option to disable it from displaying the cursor.
The following example launches the Wklauncher sample using the gfi-demo
application to render the cursor:
nice --1 gfi-demo &

$QNX_TARGET/opt/webkit/x86/bin/wklauncher -C http://www.qnx.com
The source code for the QNX CAR web browser launcher is now available. You can
download this source to view an example of many of the more advanced techniques
for using the WebKit library, including creation and management of multiple
WebView instances.
You can download the source code from the following repository on Foundry 27:
http://community.qnx.com/svn/repos/web-browsers/qnx/trunk/webkit_kd/
10 Chapter 2 • Running the Web Browser Engine Sample Application May 10, 2010
Chapter 3
WebView
May 10, 2010 Chapter 3 • WebView 11

The WebView class is the main class of the Web Browser Engine API. The WebView
class contains methods that are used to manage the interactions between
WebFrameView and WebFrame instances.
You must create a new WebView instance in order to render a page in the Web
Browser Engine. The following code snippet creates a new WebView instance.
WebView * webView = WebView::createInstance();

Each WebView must be attached to a GFWindow native window. For more Information
about GfWindow see GfWindow.h.
In order to process events and timer messages, you must create a QNX-based
connection on each GfWindow. The main launcher application must determine which
WebView instance each events is destined for. Once a GfWindow is created the
window must be associated with a WebView.
// create the GfWindow

window = new GfWindow();
// associated the main event loops connection ID
window->setCoid(coid);
To set the native window and the size:
webView->setViewWindow(window);
webView->initWithFrame(rect, NULL, NULL);
A WebView instance can also provide page and link-related information. This
information is provided by the WebNotificationDelegate class.
The WebView contains the following methods and types (listed alphabetically):
advanceFocus()
canShowMIMEType()
canShowMIMETypeAsHTML()
close()
createinstance()
goBack()
goForward()
initWithFrame()
mainframe()
onExpose()
onKeyDown()
onKeyUp()
onMouseButtonDown()
onMouseButtonUp()
onMouseMotion()
resetPageZoom()
scrollableSubFrameAtPoint()
scrollableRenderObjectAtPoint()
scrollRenderObjectBy()
setMIMETypesShownAsHTML()

setPageSizeMultiplier()
setViewWindow()
setWebNotificationDelegate()
zoomPageOut()
zoomPageIn()
14 Chapter 3 • WebView May 10, 2010

© 2010, QNX Software Systems GmbH & Co. KG. advanceFocus()
Advances the focus to the next or previous focusable object on the page.
Synopsis:
#include <WebView.h>
virtual bool advanceFocus(bool forward, bool uses_inputmethod);
Description:
These list of objects can be restricted to just those that take keyboard text input.
Arguments:
forward A boolean indicating the direction to send the focus in the list
of objects. A value of true indicates forward, false indicates
back in the list.
uses_inputmethod A boolean indicating whether or not to restrict the list to only

those object that take keyboard input. A value of true
indicates keyboard input, false indicates no keyboard input.
Returns:
True indicates that the focus was advanced successfully.

canShowMIMEType() © 2010, QNX Software Systems GmbH & Co. KG.
Indicates if the Web Browser Engine can display a given MIME type
Synopsis:
virtual bool canShowMIMEType( const char* mimeType );
Description:
Indicates whether or not the browser can display content using the specified MIME
type.
Arguments:
mimeType The MIME type to check.
Returns:
Returns True if the browser will support the specified MIME type, otherwise False.
See also:
canShowMIMETypeAsHTML()

© 2010, QNX Software Systems GmbH & Co. KG. canShowMIMETypeAsHTML()
Indicates if the Web Browser Engine can interpret the given MIME type as HTML
Synopsis:
virtual bool canShowMIMETypeAsHTML( const char* mimeType );
Description:
Indicates whether or not the browser can display the specified MIME type as HTML.
Arguments:
mimeType The MIME type to check.
Returns:
Returns True if the specified MIME type is an HTML type, otherwise False.
See also:
canShowMIMEType()

close() © 2010, QNX Software Systems GmbH & Co. KG.
Closes the current WebView
Synopsis:
void close();
Description:
Closes the current webView instance.
See also:
createInstance()

© 2010, QNX Software Systems GmbH & Co. KG. createInstance()
Create a new WebView instance
Synopsis:
static WebView* createInstance();
Description:
Creates an instance of a WebView class.
Returns:
A pointer to a WebView object.
See also:
close()

goBack() © 2010, QNX Software Systems GmbH & Co. KG.
Go back to the previous URL in the back-forward list
Synopsis:
virtual bool goBack();
Description:
Loads the previous URL in the back-forward list.
Returns:
Returns True if another URL is available in the back-forward list, or False
otherwise.
See also:
goForward()

© 2010, QNX Software Systems GmbH & Co. KG. goForward()
Go forward to the next URL in the back-forward list
Synopsis:
virtual bool goForward();
Description:
Loads the next URL in the back-forward list.
Returns:
Returns True if another URL is available in the back-forward list, or False
otherwise.
See also:
goBack()

initWithFrame() © 2010, QNX Software Systems GmbH & Co. KG.
The designated initializer for WebView
Synopsis:
virtual void initWithFrame( BalRectangle& frame,

const char* frameName,
const char* groupName );
Description:
Initialize a WebView given the specified arguments.
This method creates a main WebFrame instance containing the view. You can pass a
top-level frame name if you handle a targeted frame navigation that would normally
open a window using some other method.
Arguments:
frame The frame that is used to create the view.
frameName The name to give the top level frame. May be an empty string.
groupName The name of the webView group to which this webView instance will
be added. May be an empty string.

© 2010, QNX Software Systems GmbH & Co. KG. mainFrame()
Returns the frame that has the current focus
Synopsis:
virtual WebFrame *mainFrame();
Description:
Returns a WebFrame type representing the main frame, the root of the hierarchy for
this page.

onExpose() © 2010, QNX Software Systems GmbH & Co. KG.
Sends an expose event to the WebView
Synopsis:
void onExpose( BalEventExpose expose );
Description:
Sends an expose event to the current WebView.
Arguments:
expose The expose event to send to the WebView.
See also:
onKeyDown(), onKeyUp(), onMouseButtonUp(), onMouseButtonDown()

© 2010, QNX Software Systems GmbH & Co. KG. onKeyDown()
Sends a key event to the WebView
Synopsis:
void onKeyDown( BalEventKey keyevent );
Description:
Sends a keydown event (indicating that a key has been pressed) to the current
WebView.
Arguments:
keyevent The key event to send to the WebView.
See also:
onExpose(), onKeyUp(), onMouseButtonUp(), onMouseButtonDown()

onKeyUp() © 2010, QNX Software Systems GmbH & Co. KG.
Sends a key up event to the WebView
Synopsis:
void onKeyUp( BalEventKey keyevent );
Description:
Sends a key up event (indicating that a key has been depressed) to the current
WebView.
Arguments:
keyevent The key event to send to the WebView.
See also:
onExpose(), onKeyDown(), onMouseButtonUp(), onMouseButtonDown()

© 2010, QNX Software Systems GmbH & Co. KG. onMouseMotion()
Sends a mouse motion event to the WebView
Synopsis:
void onMouseMotion( BalEventMotion mousemotion );
Description:
Sends a mouse motion event (indicating that the mouse position has moved) to the
current WebView.
Arguments:
mousemotion The mouse motion event to send to the WebView.
See also:
onExpose(), onKeyUp(), onKeyDown(), onMouseButtonUp(), onMouseButtonDown()

onMouseButtonDown() © 2010, QNX Software Systems GmbH & Co. KG.
Sends a mouse button down event to the WebView
Synopsis:
void onMouseButtonDown( BalEventButton buttonevent );
Description:
Sends a mouse motion event (indicating that a mouse button has been pressed) to the
current WebView.
Arguments:
buttonevent The mouse button event to send to the WebView.
See also:
onExpose(), onKeyUp(), onKeyDown(), onMouseButtonUp(), onMouseMotion()

© 2010, QNX Software Systems GmbH & Co. KG. onMouseButtonUp()
Sends a mouse button up event to the WebView
Synopsis:
void onMouseButtonUp( BalEventButton buttonevent );
Description:
Sends a mouse button event (indicating that a mouse button has been depressed) to the
current WebView.
Arguments:
buttonevent The mouse button event to send to the WebView.
See also:
onExpose(), onKeyUp(), onKeyDown(), onMouseButtonDown(), onMouseMotion()

resetPageZoom() © 2010, QNX Software Systems GmbH & Co. KG.
Resets the zoom level of the current page
Synopsis:
virtual void resetPageZoom();
Description:
Resets the zoom level to an arbitrary value.
Examples:
The resetPageZoom() method is often used in conjunction with the mainframe()
method to set the default zoom level for the current page.
case UI_BUTTON_RELOAD:
webView->mainFrame()->reload();
webView->resetPageZoom();
zoom = 1.0;
url_focus = 0;
break;
See also:
zoomPageOut(), zoomPageIn(), setPageSizeMultiplier()

© 2010, QNX Software Systems GmbH & Co. KG. scrollBy()
Scrolls the Webview object by a given offset.
Synopsis:
virtual void scrollBy(BalPoint offset, WebFrame* webFrame = NULL);
Description:
Scrolls the current Webview object by a given offset.
Arguments:
offset A handle to the Balpoint instance representing the offset of the scroll wheel.
This value determines how much the page will scroll.
webFrame = NULL
An optional pointer to a sub frame. This allows the sub frame to be scrolled.
See also:
scrollableSubFrameAtpoint(), scrollRenderObjectBy(),
scrollableRenderobjectAtPoint()

scrollableSubFrameAtPoint() © 2010, QNX Software Systems GmbH & Co. KG.
Returns the scrollable subframe at the given point, if there is one.
Synopsis:
virtual WebFrame* scrollableSubFrameAtPoint(BalPoint point);
Description:
Return the scrollable subframe at the given point, if there is one.
Arguments:
point The point at which to return the subframe.
Returns:
A pointer to a WebFrame instance representing the highest level scrollable subframe.
See also:
scrollBy(), scrollRenderobjectBy(), scrollableRenderobjectAtPoint()

© 2010, QNX Software Systems GmbH & Co. KG. scrollRenderobjectBy()
Scrolls a RenderObject instance by a given offset.
Synopsis:
virtual void scrollRenderObjectBy(BalPoint offset,

WebCore::RenderObject *object);
Description:
Scrolls a RenderObject instance by a given offset.
Arguments:
offset A handle to the Balpoint instance representing the offset of the scroll
wheel. This value determines how much the object will scroll.
object The render object to scroll.
See also:
scrollableSubFrameAtpoint(), scrollBy(), scrollableRenderobjectAtPoint()

scrollableRenderobjectAtPoint() © 2010, QNX Software Systems GmbH & Co. KG.
Returns the scrollable RenderObject at the given point, if there is one.
Synopsis:
virtual WebCore::RenderObject* scrollableRenderObjectAtPoint(

BalPoint point,
int *info);
Description:
Return the scrollable object at the given point, if there is one.
Arguments:
point The point at which to return the subframe.
info A pointer to an integer representing the render object.
Returns:
A pointer to a RenderObject at the specified point.
See also:
scrollableSubFrameAtpoint(), scrollBy(),

© 2010, QNX Software Systems GmbH & Co. KG. setPageSizeMultiplier()
Set a zoom factor for all views managed by this webView
Synopsis:
virtual bool setPageSizeMultiplier( float multiplier );
Description:
Resets the zoom level to an arbitrary value.
Arguments:
multiplier A fractional percentage value where 1.0 is 100%. The multiplier must
be in the range cMinimumZoomMultipler to
cMaximumZoomMultiplier otherwise setting the zoom will be
rounded to stay in the interval.
Returns:
Returns True if the zoom was set as-is or False if the zoom was rounded.
See also:
zoomPageOut(), zoomPageIn(), resetPageZoom()

setDownloadDelegate() © 2010, QNX Software Systems GmbH & Co. KG.
Sets the current WebView’s WebDownloadDelegate
Synopsis:
virtual void setDownloadDelegate( DefaultDownloadDelegate* d );
Description:
The download delegate is retained by WebDownload when any downloads are in
progress. It is up to the application to take care of the correct deletion of the
DefaultDownloadDelegate pointer.
Arguments:
d The WebDownloadDelegate to set.

© 2010, QNX Software Systems GmbH & Co. KG. setMIMETypesShownAsHTML()
Sets the MIME types that the Web Browser Engine will render as HTML
Synopsis:
virtual void setMIMETypesShownAsHTML(const char* mimeTypes,

int cMimeTypes );
Description:
Sets the array of NSString MIME types that Web Browser Engine will attempt to
render as HTML. You can retrieve the built-in array using
MIMETypesShownAsHTML(), then add additional MIME types to that array.
Arguments:
mimeTypes An array of NSString MIME types.
cMimeTypes The index of MIME types in the array.
See also:
canShowMIMEType(), canShowMIMETypeAsHTML()

setMIMETypesShownAsHTML() © 2010, QNX Software Systems GmbH & Co. KG.
Sets the MIME types that the Web Browser Engine will render as HTML
Synopsis:
virtual void setMIMETypesShownAsHTML(const char* mimeTypes,

int cMimeTypes );
Description:
Sets the array of NSString MIME types that Web Browser Engine will attempt to
render as HTML. You can retrieve the built-in array using
MIMETypesShownAsHTML(), then add additional MIME types to that array.
Arguments:
mimeTypes An array of NSString MIME types.
cMimeTypes The index of MIME types in the array.
See also:
canShowMIMEType(), canShowMIMETypeAsHTML()

© 2010, QNX Software Systems GmbH & Co. KG. setWebNotificationDelegate()
Sets the current WebView’s WebDownloadDelegate
Synopsis:
virtual void setWebNotificationDelegate(

WebNotificationDelegate* WebNotificationDelegate );
Description:
The WebNotificationDelegate returns web and link information from the current
WebView.
Arguments:
WebNotificationDelegate
A pointer to a WebNotificationDelegate.
See also:

setViewWindow() © 2010, QNX Software Systems GmbH & Co. KG.
Attaches a native window to this WebView
Synopsis:
virtual void setViewWindow(BalWidget* window );
Description:
Sets the native window for this WebView instance.
Arguments:
window The GF window to attach to this WebView.

© 2010, QNX Software Systems GmbH & Co. KG. zoomPageOut()
Zooms out on the current page
Synopsis:
virtual bool zoomPageOut();
Description:
Zooms out on the current page.
Returns:
See also:
zoomPageIn(), resetPageZoom(), setPageSizeMultiplier()

zoomPageIn() © 2010, QNX Software Systems GmbH & Co. KG.
Zooms in on the current page
Synopsis:
virtual bool zoomPageIn();
Description:
Zooms in on the current page.
Returns:
See also:
zoomPageOut(), resetPageZoom(), setPageSizeMultiplier()

Chapter 4
May 10, 2010 Chapter 4 • WebNotificationDelegate 43

The WebNotificationDelegate class contains methods that describe page and link
information. Moreover, the WebNotificationDelegate class is a delegate class
that you can override to define custom behavior for things like page loading, user
interactions (such as mouse hover info, and tool tips), and general page and link
information.
A WebNotificationDelegate instance must be associated with a WebView
instance in order to return information.
The following code snippet associates a WebNotificationDelegate with a
WebView.
MainWebNotificationDelegate* mainWebNotificationDelegate =
new MainWebNotificationDelegate();
webView->setWebNotificationDelegate(mainWebNotificationDelegate);
In the sample application, the WebNotificationDelegate class is implemented to

define custom browser behavior. In the following example, the hoverOverLink()
method is extended to display a message on the screen whenever the user hovers over
a given WebFrame.
virtual void hoverOverLink(WebFrame*, const char* title, const char* message)

{
sprintf(cur_notification, "NOTIFY: Hover: %s:%s", title ? title :
"NA", message ? message : "NA");
ui_statusbar_draw(layer_surface);
}
The WebNotificationDelegate contains the following methods and types (listed

alphabetically):
finishedLoadNotification()
hoverOverlink()
loadError()
progressNotification()
startLoadNotification()
setTitle()
showToolTip()
showStatus()
unknownContentType()

finishedLoadNotification() © 2010, QNX Software Systems GmbH & Co. KG.
Indicates that the page load has completed
Synopsis:
#include <WebNotificationDelegate.h>
virtual void finishedLoadNotification(WebFrame* frame ) = 0;
Description:
This method is called by the WebView instance each time progress is made in loading
the page.
This is called for each frame and may be called several times for the same WebView
object.
Arguments:
frame A pointer to the WebFrame that has finised loading resources.
See also:
progressNotification(), startLoadNotification()
46 Chapter 4 • WebNotificationDelegate May 10, 2010

© 2010, QNX Software Systems GmbH & Co. KG. hoverOverLink()
Indicates that the mouse is hovering over a link
Synopsis:
virtual void hoverOverLink( WebFrame* frame, const char* title,

const char* message ) = 0;
Description:
Indicates that the mouse is hovering over a link and displays a message given a pointer
to a WebFrame instance, page title, and a message.
Arguments:
frame A pointer to the WebFrame.
title The title of the page.
message The message that appears.
See also:
setTitle(), showToolTip()

loadError() © 2010, QNX Software Systems GmbH & Co. KG.
Indicates that a page load error has occurred
Synopsis:
virtual void loadError( WebFrame* frame,

int code,
const char* url,
const char* description ) = 0;
Description:
Indicates that a page load error has occurred.
Arguments:
code The error code.
url The url that caused the error.
description A description of the error.
See also:
unknownContentType()

© 2010, QNX Software Systems GmbH & Co. KG. progressNotification()
Indicates the progress of a page load
Synopsis:
virtual void progressNotification(WebFrame* frame ) = 0;
Description:
This method is called by the WebView instance each time progress is made in loading
the page.
This can be called (using the estimateProgress() method) several times for the same
WebView instance.
Arguments:
frame A pointer to the WebFrame that is loading resources.
See also:
startLoadNotification(), finishedLoadNotification()

startLoadNotification() © 2010, QNX Software Systems GmbH & Co. KG.
Indicates that a page has started loading.
Synopsis:
virtual void startLoadNotification(WebFrame* webFrame, const char* url)
Description:
This is called for each frame and may be called several times for the same WebView
object.
Arguments:
frame A pointer to the WebFrame that is loading.
url A pointer to the URL of the page.
See also:
progressNotification(), finishedLoadNotification()

© 2010, QNX Software Systems GmbH & Co. KG. setTitle()
Sets a title for a web page
Synopsis:
virtual void setTitle(WebFrame* frame, const char* message ) = 0;
Description:
Sets the title that appears in the given frame.
Arguments:
frame A pointer to the WebFrame to set the title for.
message The title that will appear for the page.
See also:
showToolTip()

showToolTip() © 2010, QNX Software Systems GmbH & Co. KG.
Shows a tooltip for a web page
Synopsis:
virtual void showToolTip(WebFrame* frame, const char* message) = 0;
Description:
Shows a tooltip given a WebFrame and a message.
Arguments:
frame A pointer to the WebFrame for which to add the tooltip.
message The message that will appear in the tooltip.
See also:
setTitle(), showStatus()

© 2010, QNX Software Systems GmbH & Co. KG. showStatus()
Shows a status message for a web page
Synopsis:
virtual void showStatus(WebFrame* frame, const char* message) = 0;
Description:
Shows a status message given a WebFrame instance and a message.
Arguments:
frame A pointer to the WebFrame for which to add the status message.
message The message that will appear in the status.
See also:
setTitle(), showToolTip()

unknownContentType() © 2010, QNX Software Systems GmbH & Co. KG.
Indicates that the content cannot be displayed
Synopsis:
virtual bool unknownContentType( WebFrame* frame,

const char* mimeType,
const char* url ) = 0;
Description:
Indicates that the user has clicked a link which contains content that cannot be
displayed.
Arguments:
mimeType The mimetype of the content that is referenced by the link.
url The url of the link.
Returns:
True to display the content in the link. If False, the link will not be displayed.
See also:
loadError()

© 2010, QNX Software Systems GmbH & Co. KG. createWindow()
Creates a window
Synopsis:
#include <GfWindow.h>
virtual WebView * createWindow(const char* url)
Description:
Creates a window given a URL to load.
Arguments:
url The URL that the window will load. This may be null, allowing the user to
manually set the URL.
Returns:
A WebView instance representing the new window.
See also:
runJavaScriptPrompt(), runJavaScriptAlert()

getInstancePtr() © 2010, QNX Software Systems GmbH & Co. KG.
Returns the instance pointer associated with a GfWindow object.
Synopsis:
#include <GFWindow.h>
void *getInstancePtr();
Description:
This function is used internally by the Web Browser Engine to return the instance
pointer set by the launcher when it creates multiple WebView instances.
The Web Browser Engine exports a global pointer called _webViewInstancePtr.

It performs a similar function to the GfWindow object’s setInstancePtr() function for
WebKit operations, where the GfWindow object is not known. In general, this pointer
must be set whenever the launcher has created multiple WebView instances and the
launcher’s event handler makes calls into WebKit using the WebView API. This is so
that the dispatch and timer pulses received back from WebKit always contain correct
instance information.
Returns:
A WebView instance.
See also:
setInstancePtr()

Chapter 5
GfWindow
May 10, 2010 Chapter 5 • GfWindow 57

Each WebView must be attached to a GFWindow native window. For more Information
about GfWindow see GfWindow.h.
Each GfWindow contains a set of callback methods. These methods allow the
developer to gather information and display this to the user. You must implement a
GfCallbacks class in order to implement this functionality:
// create a callbacks class

MyCallbacks *callbacks = new MyCallbacks();
// set the callbacks class on the window
window->setCallbacks(callbacks);
To set the native window and the size:
webView->setViewWindow(window);
webView->initWithFrame(rect, NULL, NULL);
The following code snippet implements the GFCallbacks class in the sample
application.
class MyCallbacks : public GfCallbacks {
public:
void updateScreen(gf_surface_t surf, int x, int y, int x2, int y2, int dstX, int dstY)
{
if (first_update == 0) {
first_update = perf_snapshot_time();
}
gf_draw_begin(layer_context);
gf_draw_blit2(layer_context, surf, layer_surface, x, y, x2, y2, dstX, dstY);
gf_draw_finish(layer_context);
gf_draw_end(layer_context);
}
void newWindow()
{
}
};
The GfWindow.h header file contains the GFCallbacks class. The implemented
methods of GFCallbacks are described below (listed alphabetically):
createWindow()
getInstancePtr()
restoreViewState()
runJavaScriptAlert()
runJavaScriptConfirm()
runJavaScriptPrompt()
saveViewState()
setInputMethodState()
setInstancePtr()
textFieldBegin()
textFieldEnd()
updateScreen()

restoreViewState() © 2010, QNX Software Systems GmbH & Co. KG.
Allows the launcher application to restore any state information it had previously saved for a page.
Synopsis:
virtual void restoreViewState(void *item)
Description:
This callback is called when the user navigates back to an existing page in the page
history, for example using the back or forward buttons.
Arguments:
item A pointer to a WebView item.
See also:
saveViewState()
60 Chapter 5 • GfWindow May 10, 2010

© 2010, QNX Software Systems GmbH & Co. KG. saveViewState()
Saves the state of the current page after the user navigates away.
Synopsis:
virtual void saveViewState(void *item)
Description:
Saves the current view state for a given control.
Arguments:
item A pointer to a WebView item.
See also:
restoreViewState()

setInputMethodState() © 2010, QNX Software Systems GmbH & Co. KG.
Notifies the launcher application when an input element that requires keyboard support typed text or loses focus.
Synopsis:
virtual void setInputMethodState(int i)
Description:
Notifies the launcher application when an input element that requires keyboard
support typed text or loses focus.
Arguments:
i An integer representing the input element.

© 2010, QNX Software Systems GmbH & Co. KG. setInstancePtr()
Allows the Web Browser Engine to pass the correct WebView instance pointer within certain events.
Synopsis:
void setInstancePtr(void *ptr)
Description:
This function allows the Web Browser Engine to pass the correct WebView instance
pointer within certain events. The events are received by the launcher’s event handler.
The launcher application must use this method if it creates multiple WebView
instances. Currently this is only used by expose pulses but may be expanded in the
future.
Arguments:
*ptr A pointer to a WebView instance.
The Web Browser Engine exports a global pointer called _webViewInstancePtr.

It performs a similar function to the GfWindow object’s setInstancePtr() function for
WebKit operations, where the GfWindow object is not known. In general, this pointer
must be set whenever the launcher has created multiple WebView instances and the
launcher’s event handler makes calls into WebKit using the WebView API. This is so
that the dispatch and timer pulses received back from WebKit always contain correct
instance information.
See also:
getInstancePtr()

runJavaScriptAlert() © 2010, QNX Software Systems GmbH & Co. KG.
Displays a JavaScript prompt on the screen
Synopsis:
virtual void runJavaScriptAlert( const char* message )
Description:
Displays a JavaScript alert on the screen, given a message.
Arguments:
message The alert message to display.
See also:
runJavaScriptPrompt(), runJavaScriptConfirm()

© 2010, QNX Software Systems GmbH & Co. KG. runJavaScriptPrompt()
Displays a JavaScript prompt on the screen.
Synopsis:
virtual bool runJavaScriptPrompt( const char* message,

const char* value,
char **result )
Description:
Displays a JavaScript prompt on the screen, given a message and a value.
Arguments:
message The message to display at the prompt.
value The value to display at the prompt.
result A pointer to the inputted text that the user entered at the prompt.
Returns:
Returns True if the user clicks Yes, otherwise False.
See also:
runJavaScriptAlert(), runJavaScriptConfirm()

runJavaScriptConfirm() © 2010, QNX Software Systems GmbH & Co. KG.
Displays a JavaScript prompt on the screen
Synopsis:
virtual void runJavaScriptAlert( const char* message )
Description:
Displays a JavaScript confirmation on the screen, given a message.
Arguments:
message The confirm message to display.
Returns:
Returns True if the user clicks Yes, otherwise False.
See also:

© 2010, QNX Software Systems GmbH & Co. KG. textFieldBegin()
Indicates that text is being entered in a text field
Synopsis:
virtual void textFieldBegin()
Description:
Indicates that the user is currently entering text in the text field.
See also:
textFieldEnd()

textFieldEnd() © 2010, QNX Software Systems GmbH & Co. KG.
Indicates that the user has stopped entering text
Synopsis:
virtual void textFieldEnd()
Description:
Indicates that the user has stopped entering text in the text field.
See also:
textFieldBegin()

© 2010, QNX Software Systems GmbH & Co. KG. updateScreen()
Update the main display.
Synopsis:
virtual void updateScreen( gf_surface_t surface,

int x,
int y,
int x2,
int y2,
int dstX,
int dstY,
int mode )
Description:
Updates the main display given WebView information.
Arguments:
surface The WebView surface used to update the screen.
x The upper left coordinate of the update area.
y The upper right coordinate of the update area.
x2 The lower left coordinate of the update area.
y2 The lower right coordinate of the update area.
dstX The destination X coordinate.
dstY The destination y coordinate.
mode An integer that enables more efficient output when double-buffering. A

value of 0 indicates normal processing. A value of 1 indicates
intermediate processing meaning that more blits are coming.
Examples:
The updateScreen() method is implemented in the GfCallbacks class. This code
snippet is taken from the sample application.
class MyCallbacks : public GfCallbacks {
public:
void updateScreen(gf_surface_t surf, int x, int y, int x2, int y2, int dstX, int dstY)
{
gf_draw_begin(layer_context);
gf_draw_blit2(layer_context, surf, layer_surface, x, y, x2, y2, dstX, dstY);
gf_draw_finish(layer_context);
gf_draw_end(layer_context);
}
void newWindow()
{
}
};

updateScreen() © 2010, QNX Software Systems GmbH & Co. KG.
See also:

Chapter 6
WebFrame
May 10, 2010 Chapter 6 • WebFrame 71

A WebFrame class encapsulates the data displayed in a WebFrameView object. There

is only ever one WebFrame object per frame displayed in a WebView. An entire
webpage is represented by a hierarchy of WebFrame objects in which the root object is
called the main frame.
Each WebFrame also has a WebDataSource object that manages the loading of frame
content. You use the loadRequest() method to initiate an asynchronous client request
which will create a provisional data source. The provisional data source will transition
to a committed data source once any data has been received.
There are predefined frame names that you can use to refer to a WebFrame. The
following frame names are defined:
• _self
• _current
• _parent
• _top
Frame names may also be specified in the HTML source, or set by clients.
Some of the WebFrame methods are described below (listed alphabetically):
stopLoading()
reload()
loadURL()

stopLoading() © 2010, QNX Software Systems GmbH & Co. KG.
Stops loading the frame content
Synopsis:
#include <WebFrame.h>
virtual void stopLoading();
Description:
Stops the current load operation.
Examples:
The stopLoading() method is often used in conjunction with the mainframe() method
to stop loading content in the current frame.
case UI_BUTTON_STOP:
debug_log("stopLoading\n");
webView->mainFrame()->stopLoading();
url_focus = 0;
break;
See also:
mainframe(), reload()
74 Chapter 6 • WebFrame May 10, 2010

© 2010, QNX Software Systems GmbH & Co. KG. reload()
Reloads the current content
Synopsis:
virtual void reload();
Description:
Reloads the current content in the frame.
Examples:
The reload() method is often used in conjunction with the mainframe() method to
refresh the content in the current frame.
case UI_BUTTON_RELOAD:
webView->mainFrame()->reload();
webView->resetPageZoom();
zoom = 1.0;
url_focus = 0;
break;
See also:
mainframe(), stopLoading()

loadURL() © 2010, QNX Software Systems GmbH & Co. KG.
Requests a given URL to load
Synopsis:
virtual void loadURL( const char* url );
Description:
Loads a given URL.
Arguments:
url The url to load.
Examples:
The loadURL() method is often used in conjunction with the mainframe() method to
load a URL in the current frame.
load_url = perf_snapshot_time();
webView->mainFrame()->loadURL(cur_uri);
See also:
mainframe(), reload()
76 Chapter 6 • WebFrame May 10, 2010

Appendix A
What’s New
In this appendix. . .
What’s new for the Web Browser Engine for QNX Neutrino 6.5.0 79
May 10, 2010 Appendix: A • What’s New 77

© 2010, QNX Software Systems GmbH & Co. KG. What’s new for the Web Browser Engine for QNX Neutrino 6.5.0
This appendix describes what’s new in the Web Browser Engine for 6.5.0:
What’s new for the Web Browser Engine for QNX

Neutrino 6.5.0
The following members were added to the API:
• scrollableSubFrameAtPoint()
• scrollRenderObjectBy()
• scrollableRenderobjectAtPoint()
• advanceFocus()
• setInputMethodState()
• saveViewState()
• restoreViewState()
• setInstancePtr()
• getInstancePtr()
The following members were modified:
scrollBy() Scrolls the Webview object by a given offset.
runJavaScriptPrompt()
Displays a JavaScript prompt on the screen.
updateScreen() Update the main display.
startLoadNotification()
May 10, 2010 Appendix: A • What’s New 79

Web Browser Engine

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Web Browser Engine

Uploaded by

Copyright:

Available Formats

Web Browser Engine

For QNX ® Neutrino® 6.4 or 6.5

© 2010, QNX Software Systems GmbH & Co. KG.

About This Guide vii

1 Overview of the Web Browser Engine 1

2 Running the Web Browser Engine Sample

May 10, 2010 Contents iii

iv Contents May 10, 2010

May 10, 2010 Contents v

May 10, 2010 About This Guide vii

What’s in this guide?

You’ll find the Other... menu item under Perspective→Show View.

We use notes, cautions, and warnings to highlight important messages:

May 10, 2010 About This Guide ix

Notes point out something important or useful.

WARNING: Warnings tell you about commands or procedures that could be

Note to Windows users

x About This Guide May 10, 2010

May 10, 2010 Chapter 1 • Overview of the Web Browser Engine 1

• What is the Web Browser Engine?

• Organization of the Web Browser Engine

• Web Browser Engine supported features

• Building Your Own Web Browser Engine-based Browser

• Web Browser Engine Reference Application

What is the Web Browser Engine?

• http://webkit.org/ — the WebKit open source project home page.

May 10, 2010 Chapter 1 • Overview of the Web Browser Engine 3

Organization of the Web Browser Engine

processor/bin Contains the wklauncher application. The wklauncher sample

processor/lib As wklauncher runs, it loads the Web Browser Engine library,

etc/fonts Contains font configuration files, including fonts.conf. These

ssl Contains a Root certificate bundle used by the Web Browser

webkit Contains images used for the buttons displayed by wklauncher.

Web Browser Engine supported features

• HTML parsing (HTML 4.01)

4 Chapter 1 • Overview of the Web Browser Engine May 10, 2010

• CSS parsing (CSS 2.1 and parts of CSS 3)

The Web Browser Engine supports the following encodings:

• Unicode (UTF 8, UTF 16)

The Web Browser Engine supports the following character sets:

Building Your Own Web Browser Engine-based Browser

May 10, 2010 Chapter 1 • Overview of the Web Browser Engine 5

Web Browser Engine Reference Application

6 Chapter 1 • Overview of the Web Browser Engine May 10, 2010

devi-hid -P mouse kbd

Run the sample application

1 At the command-line prompt, set the LD_LIBRARY_PATH so that the required

2 Type the following command to run Wklauncher:

Getting a more responsive mouse pointer

and or io-hid at a higher priority. The Wklauncher application has a -C

nice --1 gfi-demo &

May 10, 2010 Chapter 3 • WebView 11

WebView * webView = WebView::createInstance();

// create the GfWindow

May 10, 2010 Chapter 3 • WebView 13

14 Chapter 3 • WebView May 10, 2010

virtual bool advanceFocus(bool forward, bool uses_inputmethod);

uses_inputmethod A boolean indicating whether or not to restrict the list to only

May 10, 2010 Chapter 3 • WebView 15

virtual bool canShowMIMEType( const char* mimeType );

16 Chapter 3 • WebView May 10, 2010

virtual bool canShowMIMETypeAsHTML( const char* mimeType );

May 10, 2010 Chapter 3 • WebView 17

virtual void hoverOverLink(WebFrame, const char title, const char* message)