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