3 \page qtwebkit-bridge.html
4 \title The QtWebKit Bridge
7 \section2 The technology
9 The QtWebKit bridge is a mechanism that extends WebKit's JavaScript environment to access native
10 objects represented as \l{QObject}s. It takes advantage of the \l{QObject} introspection,
11 a part of the \l{Object Model}, which makes it easy to integrate with the dynamic JavaScript environment.
12 For example \l{QObject} properties map directly to JavaScript properties.
16 There are two main use cases for the QtWebKit bridge: web content in native applications and thin clients.
18 \section3 Web Content in Native Applications
20 This is a common use case in classic Qt application, and a design pattern used by several modern
21 applications like an application that contains a media-player, playlist manager, and music store.
22 The playlist manager is usually best authored as a classic desktop application,
23 with the native-looking robust \l{QWidget}s as the application's backbone.
24 The media-player control usually has a custom look and feel and is best written using the \l{Graphics View framework}
25 or \l{QtDeclarative}. The music store, which shows dynamic content
26 from the Internet and gets modified rapidly, is best authored in HTML and maintained on the server.
28 With the QtWebKit bridge, the music store component can interact with native parts of the application,
29 for example, when a file needs to be saved to a specific location.
31 \section3 Thin Clients
33 The use case uses Qt as a native backend of a full web application,
34 a so-called thin client. In this use case, the entire UI is driven by
35 HTML, JavaScript and CSS. Additionally, it uses Qt-based components to
36 access native features usually not exposed to the web, or to enable helper
37 components that are best written in C++.
39 An example for such a client is a UI for a video-on-demand service on a TV. The entire content and
40 UI can be kept on the server, served dynamically through HTTP and rendered with WebKit. Additional
41 native components are used to access hardware-specific features like extracting a list of images
42 out of a video stream.
44 \section2 Difference from Other Bridge Technologies
46 Of course, QtWebKit is not the only bridge technology out there. NPAPI, for example,
47 is a long-time standard for web-native bridging. Due to Qt's meta-object system, full applications
48 leveraging web technologies are much easier to develop with the QtWebKit bridge than with NPAPI. NPAPI, however, is better
49 for cross-browser plugins, due to it being an accepted standard.
51 When developing a plugin for a browser, NPAPI is recommended. When developing a full application
52 utilizing HTML-rendering, the QtWebKit bridge is recommended.
54 \section2 Relationship with QtScript
56 The QtWebKit bridge is similar to \l{QtScript}, especially for some of the features described in the
57 \l{Making Applications Scriptable} page. However, Qt 4.7 does not provide the full QtScript API for web applications.
58 Full support is planned for future versions. You might notice that some of the features
59 described here are an exact copy of the ones described in the \l{Making Applications Scriptable} page. That is because
60 the QtWebKit bridge is a subset of that functionality, and this page tries to capture the full
61 capabilities available through the QtWebKit bridge specifically.
63 \section1 Accessing QObjects
65 \section2 Making QObjects known to JavaScript via QWebFrame
67 By default, no QObjects are accessible through the web environment, for security reasons.
68 When a web application wants to access a native QObject, it must explicitly grant access
69 to this QObject, using the following call:
71 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 0
73 See \l{QWebFrame::addToJavaScriptWindowObject()} for more information.
75 \section2 Using Signals and Slots
77 The QtWebKit bridge adapts Qt's central \l{Signals and Slots} feature for
78 scripting. There are three principal ways to use signals and slots
79 with the QtWebKit bridge:
82 \i \bold{Hybrid C++/script}: C++ application code connects a
83 signal to a script function. This approach is useful if you have
84 a QObject but don't want to expose the object itself to the scripting
85 environment. You just want to define how the script responds to a
86 signal and leave it up to the C++ side of your application to establish
87 the connection between the C++ signal and the JavaScript slot.
89 \i \bold{Hybrid script/C++}: A script can connect signals and slots
90 to establish connections between pre-defined objects that the
91 application exposes to the scripting environment. In this scenario,
92 the slots themselves are still written in C++, but the definition of
93 the connections is fully dynamic (script-defined).
95 \i \bold{Purely script-defined}: A script can both define signal
96 handler functions (effectively "slots written in JavaScript"),
97 \e{and} set up the connections that utilize those handlers. For
98 example, a script can define a function that will handle the
99 QLineEdit::returnPressed() signal, and then connect that signal to the
103 Note that QtScript functions such as qScriptConnect are unavilable in the web environment.
105 \section3 Signal to Function Connections
107 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 7
109 The call to \c{connect()} establishes a connection between the signal
110 \c{somethingChanged} and the slot \c{myInterestingScriptFunction}.
111 Whenever the object \c{myObject} emits the signal \c{somethingChanged},
112 the slot \c{myInterestingScriptFunction} gets called automatically.
114 The argument of \c{connect()} can be any JavaScript function as in the above
115 example or a slot of a QObject as in the following example:
117 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 8
119 When the argument is a slot of a QObject, the argument types of the
120 signal and the slot do not have to be compatible. If possible, the QtWebKit
121 bridge converts the signal arguments such that they match the slot argument.
123 To disconnect a slot from a signal, you call the signal's
124 \c{disconnect()} function with the slot as its argument:
126 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 9
128 When a script function is invoked in response to a signal, the
129 \c this object will be the Global Object.
131 \section3 Signal to Member Function Connections
133 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 10
135 The call to \c{connect() establishes a connection between the signal
136 \c{somethingChanged} and the slot \c{function}. Whenever the object
137 \c{myObject} emits the signal \c{somethingChanged}, the slot \c{function}
138 of the object \c{thisObject} gets called automatically. Let's illustrate
139 this with an example.
141 If you have a push button in a form, you typically want the form
142 to do something in response to the button's \c{clicked} signal. The
143 call to \c{connect()} makes sure that the function \c{onClicked()} is
144 called whenever you click on the push button, that is, whenever the
145 the signal \c{clicked()} is emitted by \c{myButton}. The slot \c{onClicked()}
146 prints the value of \c{x} as stored in the \c{form}.
148 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 11
150 To disconnect a slot from a signal, you pass the same arguments to
151 \c{disconnect()} as you passed to \c{connect()}. In general, this looks
154 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 12
156 \section3 Signal to Named Member Function Connections
158 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 14
160 This form of the \c{connect()} function requires that the first argument \c{thisObject} is
161 the object that will be bound to \c{this} when the function \c{functionName} is
162 invoked in response to the signal \c{somethingChanged}. The second argument \c{functionName} specifies the
163 name of a function that is connected to the signal. It refers to a
164 member function of the object \c{thisObject}.
166 Note that the function is resolved when the connection is made, not
167 when the signal is emitted.
169 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 15
171 To disconnect from the signal, pass the same arguments to \c{disconnect()}
172 as you passed to \c{connect}:
174 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 17
176 \section3 Error Handling
178 When \c{connect()} or \c{disconnect()} succeeds, the function will
179 return \c{undefined}; otherwise, it will throw a script exception.
180 You can obtain an error message from the resulting \c{Error} object.
183 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 18
185 \section3 Emitting Signals from Scripts
187 To emit a signal from script code, you simply invoke the signal
188 function, passing the relevant arguments:
190 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 19
192 It is currently not possible to define a new signal in a script;
193 i.e., all signals must be defined by C++ classes.
195 \section3 Overloaded Signals and Slots
197 When a signal or slot is overloaded, the QtWebKit bridge will attempt to
198 pick the right overload based on the actual types of the QScriptValue arguments
199 involved in the function invocation. For example, if your class has slots
200 \c{myOverloadedSlot(int)} and \c{myOverloadedSlot(QString)}, the following
201 script code will behave reasonably:
203 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 20
205 You can specify a particular overload by using array-style property access
206 with the \l{QMetaObject::normalizedSignature()}{normalized signature} of
207 the C++ function as the property name:
209 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 21
211 If the overloads have different number of arguments, the QtWebKit bridge will
212 pick the overload with the argument count that best matches the
213 actual number of arguments passed to the slot.
215 For overloaded signals, JavaScript will throw an error if you try to connect
216 to the signal by name; you have to refer to the signal with the full
217 normalized signature of the particular overload you want to connect to.
219 \section3 Invokable Methods
221 Both slots and signals are invokable from scripts by default. In addition, it is also
222 possible to define a method that is invokable from scripts, although the method is neither a signal nor a slot.
223 This is especially useful for functions with return types, as slots normally do not return anything
224 (it would be meaningless to return a value from a slot, as the connected signals cannot handle return values).
225 To make a non-slot method invokable, simply add the Q_INVOKABLE macro before its definition:
227 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 22
229 \section2 Accessing Properties
231 The properties of a QObject are available as properties
232 of the corresponding JavaScript object. When you manipulate
233 a property in script code, the C++ get/set method for that
234 property will automatically be invoked. For example, if your
235 C++ class has a property declared as follows:
237 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 23
239 then script code can do things like the following:
241 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 24
243 \section2 Accessing Child QObjects
245 Every named child of a QObject (that is, every child for which
246 QObject::objectName() does not return the empty string) is by default available as
247 a property of the JavaScript wrapper object. For example,
248 if you have a QDialog with a child widget whose \c{objectName} property is
249 \c{"okButton"}, you can access this object in script code through
252 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 25
254 Because \c{objectName} is itself a Q_PROPERTY, you can manipulate
255 the name in script code to rename an object. For example:
257 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 26
261 When calling slots, receiving signals or accessing properties, usually some payload is involved.
262 For example, a property "text" might return a \l{QString} parameter.
263 The QtWebKit bridge does the job of converting between a given JavaScript data-type, and the
264 expected or given Qt type. Each Qt type has a coresponding set of rules of how JavaScript treats it.
266 The data type conversions are also applicable for the data returned from non-void invokable methods.
270 All Qt numeric data types are converted to or from a JavaScript number. These include int, short, float,
271 double, and the portable Qt types (qreal, qint etc). A special case is \l{QChar}.
272 If a slot expects a QChar, the QtWebKit bridge uses the Unicode value in case of a number and the first character in case of a string.
274 Note that non-standard (typedef'ed) number types are not automatically converted to
275 or from a JavaScript number - we suggest to use standard number types for signals, slots
278 When a non-number is passed as an argument to a method or property that expects a number,
279 the appropriate JavaScript conversion function (parseInt / parseFloat) is used.
283 When JavaScript accesses methods or properties that expect a \l{QString}, the QtWebKit bridge
284 will automatically convert the value to a string (if it is not already a string), using the
285 built-in JavaScript toString method.
287 When a QString is passed to JavaScript from a signal or a property, the QtWebKit bridge
288 converts it into a JavaScript string.
290 \section3 Date & Time
292 Both \l{QDate}, \l{QTime} and \l{QDateTime} are automatically translated to or from the JavaScript
293 Date object. If a number is passed as an argument to a method that expects one of the date/time
294 types, the QtWebKit bridge treats it as a timestamp. If a sting is passed, QtWebKit
295 tries the different Qt date parsing functions to perform the right translation.
297 \section3 Regular Expressions
299 The QtWebKit bridge automatically converts a JavaScript RegEx object to a \l{QRegExp}.
300 If a string is passed to a method expecting a \l{QRegExp}, the string is converted
305 The QtWebKit bridge treats several types of lists in a special way: \l{QVariantList}, \l{QStringList},
306 \l{QObjectList} and \l{QList}<int>. When a slot or property expects one of those list types,
307 the QtWebKit bridge tries to convert a JavaScript array into that type, converting each of
308 the array's elements to the single-element type of the list.
310 The most useful type of list is \l{QVariantList}, which can be converted to and from any
313 \section3 Compound (JSON) objects
315 JavaScript compound objects, also known as JSON objects, are variables that hold a list
316 of key-value pairs, where all the keys are strings and the values can have any type.
317 This translates very well to \l{QVariantMap}, which is nothing more than a \l{QMap} from \l{QString}
320 The seamless conversion between JSON objects and \l{QVariantMap} allows for a very convenient
321 way of passing arbitrary structured data between C++ and the JavaScript environment. If the native \l{QObject} makes sure that compound values are converted to \l{QVariantMap}s and \l{QVariantList}s, JavaScript is
322 guaranteed to receive them in a meaningful way.
324 Note that types that are not supported by JSON, such as JavaScript functions and getters/setters,
329 When a slot or property accepts a \l{QVariant}, the QtWebKit bridge creates a \l{QVariant} that best
330 matches the argument passed by JavaScript. A string, for example, becomes a \l{QVariant} holding a \l{QString},
331 a normal JSON object becomes a \l{QVariantMap}, and a JavaScript array becomes a \l{QVariantList}.
333 Using \l{QVariant}s generously in C++ in that way makes C++ programming feel a bit more like JavaScript programming,
334 as it adds another level of indirection. Passing \l{QVariant}s around like this is very flexible. The program can figure out
335 the type of argument at runtime just like JavaScript would do. But doing so also takes away the type safety and robustness of C++.
336 We recommended to use \l{QVariant}s only for high-level functions, and to keep most of your
337 \l{QObject}s type-safe.
341 Pointers to a \l{QObject} or a \l{QWidget} can be used in signals, slots and properties. This object
342 can then be used like an object that is exposed directly. Its slots can be invoked, its signals connected to, etc.
343 However, this functionality is fairly limited - the type used has to be \l{QObject}* or \l{QWidget}*. If the type
344 specified is a pointer to a non-\l{QWidget} subclass of \l{QObject}, the QtWebKit bridge does not recognize it as
347 In general its advised to use care when passing \l{QObject}s as arguments, as those objects don't become owned by
348 the JavaScript engine; That means that the application developer has to be extra careful not to try to access
349 \l{QObject}s that have already been deleted by the native environment.
351 \section3 Pixmaps and Images
355 The QtWebKit bridge handles \l{QPixmap}s and \l{QImage}s in a special way. Since QtWebKit stores \l{QPixmap}s to
356 represent HTML images, \l{QPixmap}s coming from the native environment can be used directly inside WebKit.
357 A \l{QImage} or a \l{QPixmap} coming from Qt is converted to an intermediate JavaScript object,
358 which can be represented like this:
360 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 1
362 The JavaScript environment can then use the pixmap from Qt and display it inside the HTML environment,
363 by assigning it to an existing \c{<img>} element with \c{assignToHTMLImageElement()}. It can also use the \c{toDataURL()} function,
364 which allows using the pixmap as the \c{src} attribute of an image or as a \c{background-image} URL. Note that the \c{toDataURL()}
365 function is costly and should be used with caution.
366 It can also use the \c{toImageData()} function to convert the pixmap to a JavaScript \c{ImageData} object.
371 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 2
374 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 3
376 When a Qt object expects a \l{QImage} or a \l{QPixmap} as input, and the argument passed is an HTML image element,
377 the QtWebKit bridge would convert the pixmap assigned to that image element into a \l{QPixmap} or a \l{QImage}.
381 \section3 QWebElement
383 A signal, slot or property that expects or returns a \l{QWebElement} can work seamlessly with JavaScript references
384 to DOM elements. The JavaScript environment can select DOM elements, keep them in variables, then pass them to Qt as
385 a \l{QWebElement}, and receive them back. Example:
388 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 4
391 \snippet webkitsnippets/qtwebkit_bridge_snippets.cpp 5
393 This is specifically useful to create custom renderers or extensions to the web environment. Instead of forcing Qt
394 to select the element, the web environment selects the element and then sends the selected element directly to Qt.
396 Note that \l{QWebElement}s are not thread safe - an object handling them has to live in the UI thread.
398 \section1 Architecture Issues
400 \section2 Limiting the Scope of the Hybrid Layer
402 When using QtWebKit's hybrid features, it is a common pitfall to make the API exposed to JavaScript very rich and
403 use all its features. This, however, leads to complexity and can create bugs that are hard to find.
404 Instead, it is advisable to keep the hybrid layer small and manageable: create a gate only when
405 there's an actual need for it, i.e. there's a new native enabler that requires a direct interface
406 to the application layer. Sometimes new functionality is better handled internally in the native layer
407 or in the web layer; simplicity is your friend.
409 This usually becomes more apparent when the hybrid layer can create or destroy objects, or uses
410 signals, slots or properties with a \l{QObject}* argument. It is advised to be very careful and to treat
411 an exposed \l{QObject} as a system - with careful attention to memory management and object ownership.
413 \section2 Internet Security
415 When exposing native objects to an open web environment, it is important to understand the security
416 implications. Think whether the exposed object enables the web environment access things that
417 shouldn't be open, and whether the web content loaded by that web page comes from a trusted source. In general, when
418 exposing native QObjects that give the web environment access to private information or to functionality
419 that's potentially harmful to the client, such exposure should be balanced by limiting the web page's
420 access to trusted URLs only with HTTPS, and by utilizing other measures as part of a security strategy.