← Back to branch summary

~ubuntu-branches/ubuntu/raring/qtwebkit-source/raring-proposed

« back to all changes in this revision

Viewing changes to Source/WebKit/qt/docs/qtwebkit.qdoc

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2013-02-18 14:24:18 UTC
  • Revision ID: package-import@ubuntu.com-20130218142418-eon0jmjg3nj438uy
Tags: upstream-2.3
Import upstream version 2.3

Show diffs side-by-side

added added

removed removed

Lines of Context:
Source/WebKit/qt/docs/qtwebkit.qdoc
 
1
/*!
 
2
    \module QtWebKit
 
3
    \title WebKit in Qt
 
4
    \contentspage All Qt Modules
 
5
    \previouspage QtSvg
 
6
    \nextpage QtXml
 
7
    \ingroup modules
 
8
    \ingroup technology-apis
 
9
 
 
10
    \brief The QtWebKit module provides a web browser engine as well as
 
11
    classes to render and interact with web content.
 
12
 
 
13
    QtWebKit provides a Web browser engine that makes it easy to embed content
 
14
    from the World Wide Web into your Qt application. At the same time Web
 
15
    content can be enhanced with native controls.
 
16
 
 
17
    QtWebKit provides facilities for rendering of HyperText Markup Language
 
18
    (HTML), Extensible HyperText Markup Language (XHTML) and Scalable Vector
 
19
    Graphics (SVG) documents, styled using Cascading Style Sheets (CSS) and
 
20
    scripted with JavaScript.
 
21
 
 
22
    A bridge between the JavaScript execution environment and the Qt object
 
23
    model makes it possible for custom QObjects to be scripted. For detailed
 
24
    documentation see \l{The QtWebkit Bridge}.
 
25
    Integration with the Qt networking module enables Web pages to be transparently loaded
 
26
    from Web servers, the local file system or even the Qt resource system.
 
27
 
 
28
    In addition to providing pure rendering features, HTML documents can be
 
29
    made fully editable to the user through the use of the \c{contenteditable}
 
30
    attribute on HTML elements.
 
31
 
 
32
    QtWebKit has been enhanced to become more attractive on the mobile front as well.
 
33
    For more information see \l{QtWebKit Goes Mobile}.
 
34
 
 
35
    QtWebKit is based on the Open Source WebKit engine. More information about
 
36
    WebKit itself can be found on the \l{WebKit Open Source Project} Web site.
 
37
 
 
38
    \section1 Including In Your Project
 
39
 
 
40
    To include the definitions of the module's classes, use the
 
41
    following directive:
 
42
 
 
43
    \snippet webkitsnippets/qtwebkit_build_snippet.qdoc 1
 
44
 
 
45
    To link against the module, add this line to your \l qmake \c
 
46
    .pro file:
 
47
 
 
48
    \snippet webkitsnippets/qtwebkit_build_snippet.qdoc 0
 
49
 
 
50
    \section1 Notes 
 
51
 
 
52
    \note Building the QtWebKit module with debugging symbols is problematic
 
53
    on many platforms due to the size of the WebKit engine. We recommend
 
54
    building the module only in release mode for embedded platforms.
 
55
    Currently QtWebKit will always be compiled without debugging symbols
 
56
    when using gcc. Take a look at the last lines of
 
57
    \c{src/3rdparty/webkit/Source/WebCore/WebCore.pro} if you need to change this.
 
58
 
 
59
    \note Web site icons, also known as "FavIcons", are currently not supported
 
60
    on Windows. We plan to address this in a future release.
 
61
 
 
62
    \note WebKit has certain minimum requirements that must be met on
 
63
    Embedded Linux systems. See the \l{Qt for Embedded Linux Requirements}
 
64
    document for more information.
 
65
 
 
66
    \section1 Architecture
 
67
 
 
68
    The easiest way to render content is through the QWebView class. As a
 
69
    widget it can be embedded into your forms or a graphics view, and it
 
70
    provides convenience functions for downloading and rendering web sites.
 
71
 
 
72
    \snippet webkitsnippets/simple/main.cpp Using QWebView
 
73
 
 
74
    QWebView is used to view Web pages. An instance of QWebView has one
 
75
    QWebPage. QWebPage provides access to the document structure in a page,
 
76
    describing features such as frames, the navigation history, and the
 
77
    undo/redo stack for editable content.
 
78
 
 
79
    HTML documents can be nested using frames in a frameset. An individual
 
80
    frame in HTML is represented using the QWebFrame class. This class includes the
 
81
    bridge to the JavaScript window object and can be painted using QPainter.
 
82
    Each QWebPage has one QWebFrame object as its main frame, and the main frame
 
83
    may contain many child frames.
 
84
 
 
85
    Individual elements of an HTML document can be accessed via DOM JavaScript
 
86
    interfaces from within a web page. The equivalent of this API in QtWebKit
 
87
    is represented by QWebElement. QWebElement objects are obtained using QWebFrame's
 
88
    \l{QWebFrame::}{findAllElements()} and \l{QWebFrame::}{findFirstElement()}
 
89
    functions with CSS selector queries.
 
90
 
 
91
    Common web browser features, defaults and other settings can be configured
 
92
    through the QWebSettings class. It is possible to provide defaults for all
 
93
    QWebPage instances through the default settings. Individual attributes
 
94
    can be overidden by the page specific settings object.
 
95
 
 
96
    \section1 Netscape Plugin Support
 
97
 
 
98
    \note Netscape plugin support is only available on desktop platforms.
 
99
 
 
100
    Since WebKit supports the Netscape Plugin API, Qt applications can display
 
101
    Web pages that embed common plugins on platforms for which those plugins
 
102
    are available. To enable plugin support, the user must have the appropriate
 
103
    binary files for those plugins installed and the \l{QWebSettings::PluginsEnabled}
 
104
    attribute must be enabled for the application.
 
105
 
 
106
    The following locations are searched for plugins:
 
107
 
 
108
    \table
 
109
    \header \li Linux/Unix (X11)
 
110
    \row \li
 
111
    \list
 
112
    \li \c{.mozilla/plugins} in the user's home directory
 
113
    \li \c{.netscape/plugins} in the user's home directory
 
114
    \li System locations, such as
 
115
    \list
 
116
    \li \c{/usr/lib/browser/plugins}
 
117
    \li \c{/usr/local/lib/mozilla/plugins}
 
118
    \li \c{/usr/lib/firefox/plugins}
 
119
    \li \c{/usr/lib64/browser-plugins}
 
120
    \li \c{/usr/lib/browser-plugins}
 
121
    \li \c{/usr/lib/mozilla/plugins}
 
122
    \li \c{/usr/local/netscape/plugins}
 
123
    \li \c{/opt/mozilla/plugins}
 
124
    \li \c{/opt/mozilla/lib/plugins}
 
125
    \li \c{/opt/netscape/plugins}
 
126
    \li \c{/opt/netscape/communicator/plugins}
 
127
    \li \c{/usr/lib/netscape/plugins}
 
128
    \li \c{/usr/lib/netscape/plugins-libc5}
 
129
    \li \c{/usr/lib/netscape/plugins-libc6}
 
130
    \li \c{/usr/lib64/netscape/plugins}
 
131
    \li \c{/usr/lib64/mozilla/plugins}
 
132
    \endlist
 
133
    \li Locations specified by environment variables:
 
134
    \list
 
135
    \li \c{$MOZILLA_HOME/plugins}
 
136
    \li \c{$MOZ_PLUGIN_PATH}
 
137
    \li \c{$QTWEBKIT_PLUGIN_PATH}
 
138
    \endlist
 
139
    \endlist
 
140
    \endtable
 
141
 
 
142
    \table
 
143
    \header  \li Windows
 
144
    \row \li
 
145
    \list
 
146
    \li The user's \c{Application Data\Mozilla\plugins} directory
 
147
    \li Standard system locations of plugins for Quicktime, Flash, etc.
 
148
    \endlist
 
149
    \endtable
 
150
 
 
151
    \table
 
152
    \header \li Mac OS X
 
153
    \row \li
 
154
    \list
 
155
    \li \c{Library/Internet Plug-Ins} in the user's home directory
 
156
    \li The system \c{/Library/Internet Plug-Ins} directory
 
157
    \endlist
 
158
    \endtable
 
159
    
 
160
 
 
161
    \section1 License Information
 
162
 
 
163
    This is a snapshot of the Qt port of WebKit. The exact version information
 
164
    can be found in the \c{src/3rdparty/webkit/VERSION} file supplied with Qt.
 
165
 
 
166
    Qt Commercial Edition licensees that wish to distribute applications that
 
167
    use the QtWebKit module need to be aware of their obligations under the
 
168
    GNU Library General Public License (LGPL).
 
169
 
 
170
    Developers using the Open Source Edition can choose to redistribute
 
171
    the module under the appropriate version of the GNU LGPL.
 
172
 
 
173
    \legalese
 
174
    WebKit is licensed under the GNU Library General Public License.
 
175
    Individual contributor names and copyright dates can be found
 
176
    inline in the code.
 
177
 
 
178
    This library is free software; you can redistribute it and/or
 
179
    modify it under the terms of the GNU Library General Public
 
180
    License as published by the Free Software Foundation; either
 
181
    version 2 of the License, or (at your option) any later version.
 
182
 
 
183
    This library is distributed in the hope that it will be useful,
 
184
    but WITHOUT ANY WARRANTY; without even the implied warranty of
 
185
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
186
    Library General Public License for more details.
 
187
 
 
188
    You should have received a copy of the GNU Library General Public License
 
189
    along with this library; see the file COPYING.LIB.  If not, write to
 
190
    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 
191
    Boston, MA 02110-1301, USA.
 
192
    \endlegalese
 
193
*/
 
194