/usr/share/qt5/doc/qtwebkit/qtwebkit-bridge.html is in qtwebkit5-doc-html 5.1.1-1ubuntu8.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qtwebkit-bridge.qdoc -->
<title>The Qt WebKit Bridge | QtWebKit 5.1</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.1</li>
<li>The Qt WebKit Bridge</li>
<li id="buildversion">
Qt 5.1.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<p class="naviNextPrevious headerNavi">
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level2"><a href="#the-technology">The technology</a></li>
<li class="level2"><a href="#use-cases">Use Cases</a></li>
<li class="level3"><a href="#web-content-in-native-applications">Web Content in Native Applications</a></li>
<li class="level3"><a href="#thin-clients">Thin Clients</a></li>
<li class="level2"><a href="#difference-from-other-bridge-technologies">Difference from Other Bridge Technologies</a></li>
<li class="level2"><a href="#relationship-with-qt-script">Relationship with Qt Script</a></li>
<li class="level1"><a href="#accessing-qobjects">Accessing QObjects</a></li>
<li class="level2"><a href="#making-qobjects-known-to-javascript-via-qwebframe">Making QObjects known to JavaScript via QWebFrame</a></li>
<li class="level2"><a href="#using-signals-and-slots">Using Signals and Slots</a></li>
<li class="level3"><a href="#signal-to-function-connections">Signal to Function Connections</a></li>
<li class="level3"><a href="#signal-to-member-function-connections">Signal to Member Function Connections</a></li>
<li class="level3"><a href="#signal-to-named-member-function-connections">Signal to Named Member Function Connections</a></li>
<li class="level3"><a href="#error-handling">Error Handling</a></li>
<li class="level3"><a href="#emitting-signals-from-scripts">Emitting Signals from Scripts</a></li>
<li class="level3"><a href="#overloaded-signals-and-slots">Overloaded Signals and Slots</a></li>
<li class="level3"><a href="#invokable-methods">Invokable Methods</a></li>
<li class="level2"><a href="#accessing-properties">Accessing Properties</a></li>
<li class="level2"><a href="#accessing-child-qobjects">Accessing Child QObjects</a></li>
<li class="level2"><a href="#data-types">Data types</a></li>
<li class="level3"><a href="#numbers">Numbers</a></li>
<li class="level3"><a href="#strings">Strings</a></li>
<li class="level3"><a href="#date-time">Date & Time</a></li>
<li class="level3"><a href="#regular-expressions">Regular Expressions</a></li>
<li class="level3"><a href="#lists">Lists</a></li>
<li class="level3"><a href="#compound-json-objects">Compound (JSON) objects</a></li>
<li class="level3"><a href="#qvariants">QVariants</a></li>
<li class="level3"><a href="#qobjects">QObjects</a></li>
<li class="level3"><a href="#pixmaps-and-images">Pixmaps and Images</a></li>
<li class="level3"><a href="#qwebelement">QWebElement</a></li>
<li class="level1"><a href="#architecture-issues">Architecture Issues</a></li>
<li class="level2"><a href="#limiting-the-scope-of-the-hybrid-layer">Limiting the Scope of the Hybrid Layer</a></li>
<li class="level2"><a href="#internet-security">Internet Security</a></li>
</ul>
</div>
<h1 class="title">The Qt WebKit Bridge</h1>
<span class="subtitle"></span>
<!-- $$$qtwebkit-bridge.html-description -->
<div class="descr"> <a name="details"></a>
<a name="overview"></a>
<h2>Overview</h2>
<a name="the-technology"></a>
<h3>The technology</h3>
<p>The Qt WebKit bridge is a mechanism that extends WebKit's JavaScript environment to access native objects represented as QObjects. It takes advantage of the QObject introspection, a part of the Object Model, which makes it easy to integrate with the dynamic JavaScript environment. For example QObject properties map directly to JavaScript properties.</p>
<a name="use-cases"></a>
<h3>Use Cases</h3>
<p>There are two main use cases for the Qt WebKit bridge: web content in native applications and thin clients.</p>
<a name="web-content-in-native-applications"></a>
<h4>Web Content in Native Applications</h4>
<p>This is a common use case in classic Qt application, and a design pattern used by several modern applications like an application that contains a media-player, playlist manager, and music store. The playlist manager is usually best authored as a classic desktop application, with the native-looking robust QWidgets as the application's backbone. The media-player control usually has a custom look and feel and is best written using the Graphics View framework or QtDeclarative. The music store, which shows dynamic content from the Internet and gets modified rapidly, is best authored in HTML and maintained on the server.</p>
<p>With the Qt WebKit bridge, the music store component can interact with native parts of the application, for example, when a file needs to be saved to a specific location.</p>
<a name="thin-clients"></a>
<h4>Thin Clients</h4>
<p>The use case uses Qt as a native backend of a full web application, a so-called thin client. In this use case, the entire UI is driven by HTML, JavaScript and CSS. Additionally, it uses Qt-based components to access native features usually not exposed to the web, or to enable helper components that are best written in C++.</p>
<p>An example for such a client is a UI for a video-on-demand service on a TV. The entire content and UI can be kept on the server, served dynamically through HTTP and rendered with WebKit. Additional native components are used to access hardware-specific features like extracting a list of images out of a video stream.</p>
<a name="difference-from-other-bridge-technologies"></a>
<h3>Difference from Other Bridge Technologies</h3>
<p>Of course, Qt WebKit is not the only bridge technology out there. NPAPI, for example, is a long-time standard for web-native bridging. Due to Qt's meta-object system, full applications leveraging web technologies are much easier to develop with the Qt WebKit bridge than with NPAPI. NPAPI, however, is better for cross-browser plugins, due to it being an accepted standard.</p>
<p>When developing a plugin for a browser, NPAPI is recommended. When developing a full application utilizing HTML-rendering, the Qt WebKit bridge is recommended.</p>
<a name="relationship-with-qt-script"></a>
<h3>Relationship with Qt Script</h3>
<p>The Qt WebKit bridge is similar to Qt Script, especially for some of the features described in the Making Applications Scriptable page. However, Qt 4.7 does not provide the full Qt Script API for web applications. Full support is planned for future versions. You might notice that some of the features described here are an exact copy of the ones described in the Making Applications Scriptable page. That is because the Qt WebKit bridge is a subset of that functionality, and this page tries to capture the full capabilities available through the Qt WebKit bridge specifically.</p>
<a name="accessing-qobjects"></a>
<h2>Accessing QObjects</h2>
<a name="making-qobjects-known-to-javascript-via-qwebframe"></a>
<h3>Making QObjects known to JavaScript via QWebFrame</h3>
<p>By default, no <a href="#qobjects">QObjects</a> are accessible through the web environment, for security reasons. When a web application wants to access a native QObject, it must explicitly grant access to this QObject, using the following call:</p>
<pre class="cpp"><span class="comment">// ...</span>
<span class="type"><a href="qwebframe.html">QWebFrame</a></span> <span class="operator">*</span>frame <span class="operator">=</span> myWebPage<span class="operator">-</span><span class="operator">></span>mainFrame();
frame<span class="operator">-</span><span class="operator">></span>addToJavaScriptWindowObject(<span class="string">"someNameForMyObject"</span><span class="operator">,</span> myObject);
<span class="comment">// ...</span></pre>
<p>See <a href="qwebframe.html#addToJavaScriptWindowObject">QWebFrame::addToJavaScriptWindowObject</a>() for more information.</p>
<a name="using-signals-and-slots"></a>
<h3>Using Signals and Slots</h3>
<p>The Qt WebKit bridge adapts Qt's central Signals and Slots feature for scripting. There are three principal ways to use signals and slots with the Qt WebKit bridge:</p>
<ul>
<li><b>Hybrid C++/script</b>: C++ application code connects a signal to a script function. This approach is useful if you have a QObject but don't want to expose the object itself to the scripting environment. You just want to define how the script responds to a signal and leave it up to the C++ side of your application to establish the connection between the C++ signal and the JavaScript slot.</li>
<li><b>Hybrid script/C++</b>: A script can connect signals and slots to establish connections between pre-defined objects that the application exposes to the scripting environment. In this scenario, the slots themselves are still written in C++, but the definition of the connections is fully dynamic (script-defined).</li>
<li><b>Purely script-defined</b>: A script can both define signal handler functions (effectively "slots written in JavaScript"), <i>and</i> set up the connections that utilize those handlers. For example, a script can define a function that will handle the QLineEdit::returnPressed() signal, and then connect that signal to the script function.</li>
</ul>
<p>Note that Qt Script functions such as qScriptConnect are unavilable in the web environment.</p>
<a name="signal-to-function-connections"></a>
<h4>Signal to Function Connections</h4>
<pre class="cpp">function myInterestingScriptFunction() { <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>connect(myInterestingScriptFunction);</pre>
<p>The call to <tt>connect()</tt> establishes a connection between the signal <tt>somethingChanged</tt> and the slot <tt>myInterestingScriptFunction</tt>. Whenever the object <tt>myObject</tt> emits the signal <tt>somethingChanged</tt>, the slot <tt>myInterestingScriptFunction</tt> gets called automatically.</p>
<p>The argument of <tt>connect()</tt> can be any JavaScript function as in the above example or a slot of a QObject as in the following example:</p>
<pre class="cpp">myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>connect(myOtherQObject<span class="operator">.</span>doSomething);</pre>
<p>When the argument is a slot of a QObject, the argument types of the signal and the slot do not have to be compatible. If possible, the Qt WebKit bridge converts the signal arguments such that they match the slot argument.</p>
<p>To disconnect a slot from a signal, you call the signal's <tt>disconnect()</tt> function with the slot as its argument:</p>
<pre class="cpp">myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>disconnect(myInterestingFunction);
myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>disconnect(myOtherQObject<span class="operator">.</span>doSomething);</pre>
<p>When a script function is invoked in response to a signal, the <tt>this</tt> object will be the Global Object.</p>
<a name="signal-to-member-function-connections"></a>
<h4>Signal to Member Function Connections</h4>
<pre class="cpp">myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>connect(thisObject<span class="operator">,</span> function)</pre>
<p>The call to <tt>connect()</tt> establishes a connection between the signal <tt>somethingChanged</tt> and the slot <tt>function</tt>. Whenever the object <tt>myObject</tt> emits the signal <tt>somethingChanged</tt>, the slot <tt>function</tt> of the object <tt>thisObject</tt> gets called automatically. Let's illustrate this with an example.</p>
<p>If you have a push button in a form, you typically want the form to do something in response to the button's <tt>clicked</tt> signal. The call to <tt>connect()</tt> makes sure that the function <tt>onClicked()</tt> is called whenever you click on the push button, that is, whenever the the signal <tt>clicked()</tt> is emitted by <tt>myButton</tt>. The slot <tt>onClicked()</tt> prints the value of <tt>x</tt> as stored in the <tt>form</tt>.</p>
<pre class="cpp">var form <span class="operator">=</span> { x: <span class="number">123</span> };
var onClicked <span class="operator">=</span> function() { print(<span class="keyword">this</span><span class="operator">.</span>x); };
myButton<span class="operator">.</span>clicked<span class="operator">.</span>connect(form<span class="operator">,</span> onClicked);</pre>
<p>To disconnect a slot from a signal, you pass the same arguments to <tt>disconnect()</tt> as you passed to <tt>connect()</tt>. In general, this looks as follows:</p>
<pre class="cpp">myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>disconnect(thisObject<span class="operator">,</span> function);</pre>
<a name="signal-to-named-member-function-connections"></a>
<h4>Signal to Named Member Function Connections</h4>
<pre class="cpp">myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>connect(thisObject<span class="operator">,</span> <span class="string">"functionName"</span>)</pre>
<p>This form of the <tt>connect()</tt> function requires that the first argument <tt>thisObject</tt> is the object that will be bound to <tt>this</tt> when the function <tt>functionName</tt> is invoked in response to the signal <tt>somethingChanged</tt>. The second argument <tt>functionName</tt> specifies the name of a function that is connected to the signal. It refers to a member function of the object <tt>thisObject</tt>.</p>
<p>Note that the function is resolved when the connection is made, not when the signal is emitted.</p>
<pre class="cpp">var obj <span class="operator">=</span> { x: <span class="number">123</span><span class="operator">,</span> fun: function() { print(<span class="keyword">this</span><span class="operator">.</span>x); } };
myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>connect(obj<span class="operator">,</span> <span class="string">"fun"</span>);</pre>
<p>To disconnect from the signal, pass the same arguments to <tt>disconnect()</tt> as you passed to <tt>connect</tt>:</p>
<pre class="cpp">myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>disconnect(thisObject<span class="operator">,</span> <span class="string">"functionName"</span>);</pre>
<a name="error-handling"></a>
<h4>Error Handling</h4>
<p>When <tt>connect()</tt> or <tt>disconnect()</tt> succeeds, the function will return <tt>undefined</tt>; otherwise, it will throw a script exception. You can obtain an error message from the resulting <tt>Error</tt> object. Example:</p>
<pre class="cpp"><span class="keyword">try</span> {
myQObject<span class="operator">.</span>somethingChanged<span class="operator">.</span>connect(myQObject<span class="operator">,</span> <span class="string">"slotThatDoesntExist"</span>);
} <span class="keyword">catch</span> (e) {
print(e);
}</pre>
<a name="emitting-signals-from-scripts"></a>
<h4>Emitting Signals from Scripts</h4>
<p>To emit a signal from script code, you simply invoke the signal function, passing the relevant arguments:</p>
<pre class="cpp">myQObject<span class="operator">.</span>somethingChanged(<span class="string">"hello"</span>);</pre>
<p>It is currently not possible to define a new signal in a script; i.e., all signals must be defined by C++ classes.</p>
<a name="overloaded-signals-and-slots"></a>
<h4>Overloaded Signals and Slots</h4>
<p>When a signal or slot is overloaded, the Qt WebKit bridge will attempt to pick the right overload based on the actual types of the QScriptValue arguments involved in the function invocation. For example, if your class has slots <tt>myOverloadedSlot(int)</tt> and <tt>myOverloadedSlot(QString)</tt>, the following script code will behave reasonably:</p>
<pre class="cpp">myQObject<span class="operator">.</span>myOverloadedSlot(<span class="number">10</span>); <span class="comment">// will call the int overload</span>
myQObject<span class="operator">.</span>myOverloadedSlot(<span class="string">"10"</span>); <span class="comment">// will call the QString overload</span></pre>
<p>You can specify a particular overload by using array-style property access with the normalized signature of the C++ function as the property name:</p>
<pre class="cpp">myQObject<span class="operator">[</span><span class="char">'myOverloadedSlot(int)'</span><span class="operator">]</span>(<span class="string">"10"</span>); <span class="comment">// call int overload; the argument is converted to an int</span>
myQObject<span class="operator">[</span><span class="char">'myOverloadedSlot(QString)'</span><span class="operator">]</span>(<span class="number">10</span>); <span class="comment">// call QString overload; the argument is converted to a string</span></pre>
<p>If the overloads have different number of arguments, the Qt WebKit bridge will pick the overload with the argument count that best matches the actual number of arguments passed to the slot.</p>
<p>For overloaded signals, JavaScript will throw an error if you try to connect to the signal by name; you have to refer to the signal with the full normalized signature of the particular overload you want to connect to.</p>
<a name="invokable-methods"></a>
<h4>Invokable Methods</h4>
<p>Both slots and signals are invokable from scripts by default. In addition, it is also possible to define a method that is invokable from scripts, although the method is neither a signal nor a slot. This is especially useful for functions with return types, as slots normally do not return anything (it would be meaningless to return a value from a slot, as the connected signals cannot handle return values). To make a non-slot method invokable, simply add the Q_INVOKABLE macro before its definition:</p>
<pre class="cpp"><span class="keyword">class</span> MyObject : <span class="keyword">public</span> <span class="type">QObject</span>
{
Q_OBJECT
<span class="keyword">public</span>:
Q_INVOKABLE <span class="type">void</span> thisMethodIsInvokableInJavaScript();
<span class="type">void</span> thisMethodIsNotInvokableInJavaScript();
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
};</pre>
<a name="accessing-properties"></a>
<h3>Accessing Properties</h3>
<p>The properties of a QObject are available as properties of the corresponding JavaScript object. When you manipulate a property in script code, the C++ get/set method for that property will automatically be invoked. For example, if your C++ class has a property declared as follows:</p>
<pre class="cpp"> Q_PROPERTY(bool enabled READ enabled WRITE setEnabled)</pre>
<p>then script code can do things like the following:</p>
<pre class="cpp">myQObject<span class="operator">.</span>enabled <span class="operator">=</span> <span class="keyword">true</span>;
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
myQObject<span class="operator">.</span>enabled <span class="operator">=</span> <span class="operator">!</span>myQObject<span class="operator">.</span>enabled;</pre>
<a name="accessing-child-qobjects"></a>
<h3>Accessing Child QObjects</h3>
<p>Every named child of a QObject (that is, every child for which QObject::objectName() does not return the empty string) is by default available as a property of the JavaScript wrapper object. For example, if you have a QDialog with a child widget whose <tt>objectName</tt> property is <tt>"okButton"</tt>, you can access this object in script code through the expression</p>
<pre class="cpp">myDialog<span class="operator">.</span>okButton</pre>
<p>Because <tt>objectName</tt> is itself a Q_PROPERTY, you can manipulate the name in script code to rename an object. For example:</p>
<pre class="cpp">myDialog<span class="operator">.</span>okButton
myDialog<span class="operator">.</span>okButton<span class="operator">.</span>objectName <span class="operator">=</span> <span class="string">"cancelButton"</span>;
<span class="comment">// from now on, myDialog.cancelButton references the button</span></pre>
<a name="data-types"></a>
<h3>Data types</h3>
<p>When calling slots, receiving signals or accessing properties, usually some payload is involved. For example, a property "text" might return a QString parameter. The Qt WebKit bridge does the job of converting between a given JavaScript data-type, and the expected or given Qt type. Each Qt type has a coresponding set of rules of how JavaScript treats it.</p>
<p>The data type conversions are also applicable for the data returned from non-void invokable methods.</p>
<a name="numbers"></a>
<h4>Numbers</h4>
<p>All Qt numeric data types are converted to or from a JavaScript number. These include int, short, float, double, and the portable Qt types (qreal, qint etc). A special case is QChar. If a slot expects a QChar, the Qt WebKit bridge uses the Unicode value in case of a number and the first character in case of a string.</p>
<p>Note that non-standard (typedef'ed) number types are not automatically converted to or from a JavaScript number - we suggest to use standard number types for signals, slots and properties.</p>
<p>When a non-number is passed as an argument to a method or property that expects a number, the appropriate JavaScript conversion function (parseInt / parseFloat) is used.</p>
<a name="strings"></a>
<h4>Strings</h4>
<p>When JavaScript accesses methods or properties that expect a QString, the Qt WebKit bridge will automatically convert the value to a string (if it is not already a string), using the built-in JavaScript toString method.</p>
<p>When a QString is passed to JavaScript from a signal or a property, the Qt WebKit bridge converts it into a JavaScript string.</p>
<a name="date-time"></a>
<h4>Date & Time</h4>
<p>Both QDate, QTime and QDateTime are automatically translated to or from the JavaScript Date object. If a number is passed as an argument to a method that expects one of the date/time types, the Qt WebKit bridge treats it as a timestamp. If a sting is passed, Qt WebKit tries the different Qt date parsing functions to perform the right translation.</p>
<a name="regular-expressions"></a>
<h4>Regular Expressions</h4>
<p>The Qt WebKit bridge automatically converts a JavaScript RegEx object to a QRegExp. If a string is passed to a method expecting a QRegExp, the string is converted to a QRegExp.</p>
<a name="lists"></a>
<h4>Lists</h4>
<p>The Qt WebKit bridge treats several types of lists in a special way: QVariantList, QStringList, QObjectList and QList<int>. When a slot or property expects one of those list types, the Qt WebKit bridge tries to convert a JavaScript array into that type, converting each of the array's elements to the single-element type of the list.</p>
<p>The most useful type of list is QVariantList, which can be converted to and from any JavaScript array.</p>
<a name="compound-json-objects"></a>
<h4>Compound (JSON) objects</h4>
<p>JavaScript compound objects, also known as JSON objects, are variables that hold a list of key-value pairs, where all the keys are strings and the values can have any type. This translates very well to QVariantMap, which is nothing more than a QMap from QString to QVariant.</p>
<p>The seamless conversion between JSON objects and QVariantMap allows for a very convenient way of passing arbitrary structured data between C++ and the JavaScript environment. If the native QObject makes sure that compound values are converted to QVariantMaps and QVariantLists, JavaScript is guaranteed to receive them in a meaningful way.</p>
<p>Note that types that are not supported by JSON, such as JavaScript functions and getters/setters, are not converted.</p>
<a name="qvariants"></a>
<h4>QVariants</h4>
<p>When a slot or property accepts a QVariant, the Qt WebKit bridge creates a QVariant that best matches the argument passed by JavaScript. A string, for example, becomes a QVariant holding a QString, a normal JSON object becomes a QVariantMap, and a JavaScript array becomes a QVariantList.</p>
<p>Using QVariants generously in C++ in that way makes C++ programming feel a bit more like JavaScript programming, as it adds another level of indirection. Passing QVariants around like this is very flexible. The program can figure out the type of argument at runtime just like JavaScript would do. But doing so also takes away the type safety and robustness of C++. We recommended to use QVariants only for high-level functions, and to keep most of your QObjects type-safe.</p>
<a name="qobjects"></a>
<h4>QObjects</h4>
<p>Pointers to a QObject or a QWidget can be used in signals, slots and properties. This object can then be used like an object that is exposed directly. Its slots can be invoked, its signals connected to, etc. However, this functionality is fairly limited - the type used has to be QObject* or QWidget*. If the type specified is a pointer to a non-QWidget subclass of QObject, the Qt WebKit bridge does not recognize it as a QObject.</p>
<p>In general its advised to use care when passing QObjects as arguments, as those objects don't become owned by the JavaScript engine; That means that the application developer has to be extra careful not to try to access QObjects that have already been deleted by the native environment.</p>
<a name="pixmaps-and-images"></a>
<h4>Pixmaps and Images</h4>
<p>The Qt WebKit bridge handles QPixmaps and QImages in a special way. Since Qt WebKit stores QPixmaps to represent HTML images, QPixmaps coming from the native environment can be used directly inside WebKit. A QImage or a QPixmap coming from Qt is converted to an intermediate JavaScript object, which can be represented like this:</p>
<pre class="cpp">{
width: <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span><span class="operator">,</span>
height: <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span><span class="operator">,</span>
toDataURL: function() { <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }<span class="operator">,</span>
assignToHTMLImageElement: function(element) { <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
toImageData: function() { <span class="operator">.</span><span class="operator">.</span><span class="operator">.</span> }
}</pre>
<p>The JavaScript environment can then use the pixmap from Qt and display it inside the HTML environment, by assigning it to an existing <tt><img></tt> element with <tt>assignToHTMLImageElement()</tt>. It can also use the <tt>toDataURL()</tt> function, which allows using the pixmap as the <tt>src</tt> attribute of an image or as a <tt>background-image</tt> URL. Note that the <tt>toDataURL()</tt> function is costly and should be used with caution. It can also use the <tt>toImageData()</tt> function to convert the pixmap to a JavaScript <tt>ImageData</tt> object.</p>
<p>Example code:</p>
<p>C++:</p>
<pre class="cpp"><span class="keyword">class</span> MyObject : <span class="type">QObject</span> {
Q_OBJECT
Q_PROPERTY(<span class="type">QPixmap</span> myPixmap READ getPixmap)
<span class="keyword">public</span>:
<span class="type">QPixmap</span> getPixmap() <span class="keyword">const</span>;
};
<span class="comment">/* ... */</span>
MyObject myObject;
myWebPage<span class="operator">.</span>mainFrame()<span class="operator">-</span><span class="operator">></span>addToJavaScriptWindowObject(<span class="string">"myObject"</span><span class="operator">,</span> <span class="operator">&</span>myObject);</pre>
<p>HTML:</p>
<pre class="cpp"><span class="operator"><</span>html<span class="operator">></span>
<span class="operator"><</span>head<span class="operator">></span>
<span class="operator"><</span>script<span class="operator">></span>
function loadImage()
{
myObject<span class="operator">.</span>myPixmap<span class="operator">.</span>assignToHTMLImageElement(document<span class="operator">.</span>getElementById(<span class="string">"imageElement"</span>));
var context <span class="operator">=</span> document<span class="operator">.</span>getElementById(<span class="string">"canvasElement"</span>)<span class="operator">.</span>getContext(<span class="string">"2d"</span>);
context<span class="operator">.</span>putImageData(myObject<span class="operator">.</span>myPixmap<span class="operator">.</span>toImageData());
}
<span class="operator"><</span><span class="operator">/</span>script<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>head<span class="operator">></span>
<span class="operator"><</span>body onload<span class="operator">=</span><span class="string">"loadImage()"</span><span class="operator">></span>
<span class="operator"><</span>img id<span class="operator">=</span><span class="string">"imageElement"</span> width<span class="operator">=</span><span class="string">"300"</span> height<span class="operator">=</span><span class="string">"200"</span> <span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>canvas id<span class="operator">=</span><span class="string">"canvasElement"</span> width<span class="operator">=</span><span class="string">"300"</span> height<span class="operator">=</span><span class="string">"200"</span> <span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>body<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>html<span class="operator">></span></pre>
<p>When a Qt object expects a QImage or a QPixmap as input, and the argument passed is an HTML image element, the Qt WebKit bridge would convert the pixmap assigned to that image element into a QPixmap or a QImage.</p>
<a name="qwebelement"></a>
<h4>QWebElement</h4>
<p>A signal, slot or property that expects or returns a <a href="qwebelement.html">QWebElement</a> can work seamlessly with JavaScript references to DOM elements. The JavaScript environment can select DOM elements, keep them in variables, then pass them to Qt as a <a href="qwebelement.html">QWebElement</a>, and receive them back. Example:</p>
<p>C++:</p>
<pre class="cpp"><span class="keyword">class</span> MyObject : <span class="type">QObject</span> {
Q_OBJECT
<span class="keyword">public</span> Q_SLOTS:
<span class="type">void</span> doSomethingWithWebElement(<span class="keyword">const</span> <span class="type"><a href="qwebelement.html">QWebElement</a></span><span class="operator">&</span>);
};
<span class="comment">/* ... */</span>
MyObject myObject;
myWebPage<span class="operator">.</span>mainFrame()<span class="operator">-</span><span class="operator">></span>addToJavaScriptWindowObject(<span class="string">"myObject"</span><span class="operator">,</span> <span class="operator">&</span>myObject);</pre>
<p>HTML:</p>
<pre class="cpp"><span class="operator"><</span>html<span class="operator">></span>
<span class="operator"><</span>head<span class="operator">></span>
<span class="operator"><</span>script<span class="operator">></span>
function runExample() {
myObject<span class="operator">.</span>doSomethingWithWebElement(document<span class="operator">.</span>getElementById(<span class="string">"someElement"</span>));
}
<span class="operator"><</span><span class="operator">/</span>script<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>head<span class="operator">></span>
<span class="operator"><</span>body onload<span class="operator">=</span><span class="string">"runExample()"</span><span class="operator">></span>
<span class="operator"><</span>span id<span class="operator">=</span><span class="string">"someElement"</span><span class="operator">></span>Text<span class="operator"><</span><span class="operator">/</span>span<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>body<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>html<span class="operator">></span></pre>
<p>This is specifically useful to create custom renderers or extensions to the web environment. Instead of forcing Qt to select the element, the web environment selects the element and then sends the selected element directly to Qt.</p>
<p>Note that <a href="qwebelement.html">QWebElement</a>s are not thread safe - an object handling them has to live in the UI thread.</p>
<a name="architecture-issues"></a>
<h2>Architecture Issues</h2>
<a name="limiting-the-scope-of-the-hybrid-layer"></a>
<h3>Limiting the Scope of the Hybrid Layer</h3>
<p>When using Qt WebKit's hybrid features, it is a common pitfall to make the API exposed to JavaScript very rich and use all its features. This, however, leads to complexity and can create bugs that are hard to find. Instead, it is advisable to keep the hybrid layer small and manageable: create a gate only when there's an actual need for it, i.e. there's a new native enabler that requires a direct interface to the application layer. Sometimes new functionality is better handled internally in the native layer or in the web layer; simplicity is your friend.</p>
<p>This usually becomes more apparent when the hybrid layer can create or destroy objects, or uses signals, slots or properties with a QObject* argument. It is advised to be very careful and to treat an exposed QObject as a system - with careful attention to memory management and object ownership.</p>
<a name="internet-security"></a>
<h3>Internet Security</h3>
<p>When exposing native objects to an open web environment, it is important to understand the security implications. Think whether the exposed object enables the web environment access things that shouldn't be open, and whether the web content loaded by that web page comes from a trusted source. In general, when exposing native <a href="#qobjects">QObjects</a> that give the web environment access to private information or to functionality that's potentially harmful to the client, such exposure should be balanced by limiting the web page's access to trusted URLs only with HTTPS, and by utilizing other measures as part of a security strategy.</p>
</div>
<!-- @@@qtwebkit-bridge.html -->
<p class="naviNextPrevious footerNavi">
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|