diff options
Diffstat (limited to 'doc')
86 files changed, 4567 insertions, 361 deletions
diff --git a/doc/doc.pri b/doc/doc.pri index 3cdac61..68d729b 100644 --- a/doc/doc.pri +++ b/doc/doc.pri @@ -15,6 +15,7 @@ win32:!win32-g++* { $$unixstyle { QDOC = cd $$QT_SOURCE_TREE/tools/qdoc3/test && QT_BUILD_TREE=$$QT_BUILD_TREE QT_SOURCE_TREE=$$QT_SOURCE_TREE $$QT_BUILD_TREE/bin/qdoc3 $$DOCS_GENERATION_DEFINES + COPYWEBKITGUIDE = $$QT_SOURCE_TREE/examples/webkit/webkit-guide } else { QDOC = cd $$QT_SOURCE_TREE/tools/qdoc3/test && set QT_BUILD_TREE=$$QT_BUILD_TREE&& set QT_SOURCE_TREE=$$QT_SOURCE_TREE&& $$QT_BUILD_TREE/bin/qdoc3.exe $$DOCS_GENERATION_DEFINES QDOC = $$replace(QDOC, "/", "\\") @@ -23,6 +24,7 @@ ADP_DOCS_QDOCCONF_FILE = qt-build-docs-online.qdocconf QT_DOCUMENTATION = ($$QDOC qt-api-only.qdocconf assistant.qdocconf designer.qdocconf \ linguist.qdocconf qmake.qdocconf qdeclarative.qdocconf) && \ (cd $$QT_BUILD_TREE && \ + $$QMAKE_COPY_DIR $$COPYWEBKITGUIDE $$QT_BUILD_TREE/doc-build/html-qt && \ $$GENERATOR doc-build/html-qt/qt.qhp -o doc/qch/qt.qch && \ $$GENERATOR doc-build/html-assistant/assistant.qhp -o doc/qch/assistant.qch && \ $$GENERATOR doc-build/html-designer/designer.qhp -o doc/qch/designer.qch && \ @@ -48,7 +50,7 @@ win32-g++*:isEmpty(QMAKE_SH) { } # Build rules: -adp_docs.commands = ($$QDOC $$ADP_DOCS_QDOCCONF_FILE) +adp_docs.commands = ($$QDOC $$ADP_DOCS_QDOCCONF_FILE && $$QMAKE_COPY_DIR $$COPYWEBKITGUIDE $$QT_BUILD_TREE/doc/html) adp_docs.depends += sub-qdoc3 # qdoc3 qch_docs.commands = $$QT_DOCUMENTATION qch_docs.depends += sub-qdoc3 diff --git a/doc/src/declarative/behaviors-and-states.qdoc b/doc/src/declarative/behaviors-and-states.qdoc new file mode 100644 index 0000000..0815b39 --- /dev/null +++ b/doc/src/declarative/behaviors-and-states.qdoc @@ -0,0 +1,206 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-behaviors-and-states.html +\title Using QML Behaviors with States + +\section1 Using Behaviors with States + +In some cases you may choose to use a Behavior to animate a property change caused by a state change. While this works well for some situations, in other situations it may lead to unexpected behavior. + +Here's an example that shows the problem: + +\qml +import QtQuick 1.0 + +Rectangle { + width: 400 + height: 400 + + Rectangle { + id: coloredRect + width: 100 + height: 100 + anchors.centerIn: parent + + color: "red" + Behavior on color { + ColorAnimation {} + } + + MouseArea { + id: mouser + anchors.fill: parent + hoverEnabled: true + } + + states: State { + name: "GreenState" + when: mouser.containsMouse + + PropertyChanges { + target: coloredRect + color: "green" + } + } + } +} +\endqml + +Testing the example by quickly and repeatedly moving the mouse in to and out of the colored rectangle shows that the colored rectangle will settle into a green color over time, never returning to full red. This is not what we wanted! The +problem occurs because we have used a Behavior to animate the change in color, and our state change is trigged by the mouse entering or exiting the MouseArea, which is easily interrupted. + +To state the problem more formally, using States and Behaviors together can cause unexpected behavior when: +\list +\o a Behavior is used to animate a property change, specifically when moving from an explicitly defined state back to the implicit base state; and +\o this Behavior can be interrupted to (re-)enter an explicitly defined state. +\endlist + +The problem occurs because of the way the base state is defined for QML: as the "snapshot" state of the application just prior to entering an explicitly defined state. In this case, if we are in the process of animating from green back +to red, and interrupt the animation to return to "GreenState", the base state will include the color in its intermediate, mid-animation form. + +While future versions of QML should be able to handle this situation more gracefully, there are currently several ways to rework your application to avoid this problem. + +1. Use a transition to animate the change, rather than a Behavior. + +\qml +import QtQuick 1.0 + +Rectangle { + width: 400 + height: 400 + + Rectangle { + id: coloredRect + width: 100 + height: 100 + anchors.centerIn: parent + + color: "red" + + MouseArea { + id: mouser + anchors.fill: parent + hoverEnabled: true + } + + states: State { + name: "GreenState" + when: mouser.containsMouse + + PropertyChanges { + target: coloredRect + color: "green" + } + } + + transitions: Transition { + ColorAnimation {} + } + } +} +\endqml + +2. Use a conditional binding to change the property value, rather than a state + +\qml +import QtQuick 1.0 + +Rectangle { + width: 400 + height: 400 + + Rectangle { + id: coloredRect + width: 100 + height: 100 + anchors.centerIn: parent + + color: mouser.containsMouse ? "green" : "red" + Behavior on color { + ColorAnimation {} + } + + MouseArea { + id: mouser + anchors.fill: parent + hoverEnabled: true + } + } +} +\endqml + +3. Use only explicitly defined states, rather than an implicit base state + +\qml +import QtQuick 1.0 + +Rectangle { + width: 400 + height: 400 + + Rectangle { + id: coloredRect + width: 100 + height: 100 + anchors.centerIn: parent + + Behavior on color { + ColorAnimation {} + } + + MouseArea { + id: mouser + anchors.fill: parent + hoverEnabled: true + } + + states: [ + State { + name: "GreenState" + when: mouser.containsMouse + + PropertyChanges { + target: coloredRect + color: "green" + } + }, + State { + name: "RedState" + when: !mouser.containsMouse + + PropertyChanges { + target: coloredRect + color: "red" + } + }] + } +} +\endqml + +*/ diff --git a/doc/src/demos/guitartuner.qdoc b/doc/src/demos/guitartuner.qdoc new file mode 100644 index 0000000..8678db1 --- /dev/null +++ b/doc/src/demos/guitartuner.qdoc @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page guitartuner_example.html + \title Guitar Tuner Example + \example demos/mobile/guitartuner + +The Guitar Tuner application can be used to tune guitar strings by analyzing the +audio recorded by the device microphone. Guitar Tuner can be also used in the +listening mode. It will then play the audio by the corresponding frequency, and +the user can tune the guitar by ear. The application demonstrates the audio-in +and the audio-out interfaces of +\l{external: Mobility Multimedia}{Qt Mobility Multimedia} and integrating Qt +code to the Qt Quick UI. + + The example is hosted in Projects Forum Nokia: https://projects.forum.nokia.com/guitartuner + +\note This demonstration requires QtMobility libraries. + \image qml-guitartuner-example.png +*/ diff --git a/doc/src/demos/mobiledemos.qdoc b/doc/src/demos/mobiledemos.qdoc new file mode 100644 index 0000000..15fac7e --- /dev/null +++ b/doc/src/demos/mobiledemos.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +/*! + \example demos/mobile/quickhit + \title Quick Hit Demo + + This demo shows how to use Mobility APIs to access device audio + capabilities. Uses the multimedia and systeminfo modules of + \l{external: Qt Mobility Manual}{Qt Mobility}. + + \note This demonstration requires QtMobility libraries. + +*/ + + diff --git a/doc/src/demos/qcamera.qdoc b/doc/src/demos/qcamera.qdoc new file mode 100644 index 0000000..315e82a6 --- /dev/null +++ b/doc/src/demos/qcamera.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qcamera_example.html + \title QCamera Example + \example demos/mobile/qcamera + + This Qt C++ application demonstrates how to use Multimedia, Messaging and Contacts modules from \l{external: Qt Mobility Manual}{Qt Mobility}. + + \image qcameraexample.png + + The application shows the viewfinder picture from the device camera and allows the user to capture images. Captured images are stored into the gallery and can be sent as an MMS message to a friend. Application listens for incoming MMS messages in the Inbox folder. If the MMS message contains a picture, the application asks the user whether he or she wants to add the picture as an avatar of the sender. The person's general contact information has to exist in the device phonebook in order to store the avatar in it. + + The application uses own MyVideoSurface video surface derived from QAbstractVideoSurface for showing camera view finder pictures. A video surface presents a continuous stream of identically formatted frames. + + \snippet demos/mobile/qcamera/cameraexample.cpp 0 + + The application handles Graphics Out Of Memory (GOOM) events in it's QApplication::symbianEventFilter() method. + + \snippet demos/mobile/qcamera/main.cpp 0 + + \section1 Required capabilities + + Application can be self-signed. + + After enabling Qt Mobility Messaging module (MESSAGING_ENABLED flag in .pro file) + from the project file is ReadDeviceData WriteDeviceData capabilities also needed and + application have to be Developer Signed. Enabling Messaging adds MMS sending feature for the application. + + \section1 Compatibility + + Qt SDK 1.1 + + Qt 4.7.2 for Symbian + + QtMobility 1.1.1 + + Tested on: Nokia N8, Nokia E7 + + Developed with: Qt SDK 1.1 + + +*/ diff --git a/doc/src/demos/qml-qtbubblelevel.qdoc b/doc/src/demos/qml-qtbubblelevel.qdoc new file mode 100644 index 0000000..82ea4dc --- /dev/null +++ b/doc/src/demos/qml-qtbubblelevel.qdoc @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtbubblelevel_example.html + \title Qt Bubble Level Example + \example demos/mobile/qtbubblelevel + +Qt Bubble Level is a simple application that uses +\l{external: Qt Mobility Manual}{Qt Mobility's} accelerometer APIs and hardware +sensor information to calculate the inclination of the device and presents this +as atraditional bubble level. The application provides a calibration feature to +handle any possible errors in accelerometer readings. The example is hosted in +Projects Forum Nokia: https://projects.forum.nokia.com/qtbubblelevel + +\note This demonstration requires QtMobility libraries. + + \image qml-qtbubblelevel-demo.png + + \section1 Initialising the application + + All of the initialisations are done in the main function. + + First, QDeclarativeView is created to intepret the QML files. The QML file given is found in the Qt resource. The root QML element is set to resize to the view whenever the view is resized. + + \snippet demos/mobile/qtbubblelevel/main.cpp 0 + + The Settings object will handle the loading or storing of the calibration value. Next, we create instances from QAccelerometer and AccelerometerFilter and attach the filter to the sensor. + + \snippet demos/mobile/qtbubblelevel/main.cpp 1 + + The Qt code is then connected to QML code by using Qt Signals and Slots connections. First, the root object is retrieved from QDeclarativeView. The root object now represents the Qt object of the QML root element. + + The saveCorrectionAngle signal of the QML root element is connected to the Qt slot saveCorrectionAngle. The rotationChanged and correctionAngle Qt signals are connected to the handleRotation and setCorrectionAngle slot of the QML root element. Finally, the quit signal of QDeclarativeEngine is connected to QApplication's quit slot. + + \snippet demos/mobile/qtbubblelevel/main.cpp 2 + + On the Maemo target, the application needs a minimise button, so we connect one additional QML signal to the Qt slot. The minimise button is made visible by setting the value of the QML root element's taskSwitcherVisible property to true. + + \snippet demos/mobile/qtbubblelevel/main.cpp 3 + + The correction factor of the accelerometer is retrieved from persistent storage by using QSettings. The correction factor is signalled to the QML side by using the function setCorrectionAngle. The accelerometer sensor is started and it will eventually begin to signal the changes in accelerometer readings. + + \snippet demos/mobile/qtbubblelevel/main.cpp 4 + + Finally, in the end of the function the view is shown in full screen on mobile devices. On other targets, the application is shown as 800 x 480 resolution in the 100, 100 position from the top-left corner of the desktop. + + \snippet demos/mobile/qtbubblelevel/main.cpp 5 + + \section1 Accessing the accelerometer information + + The inclination of the device is resolved by using the QAccelerometer sensor of QtMobility. We already created the sensor in the main function and attached our self-derived AccelerometerFilter object to it. Here is the definition of the AccelerometerFilter class: + + \snippet demos/mobile/qtbubblelevel/accelerometerfilter.h 0 + + The class is multiderived from QObject and QAccelerometerFilter classes. The QAccelerometerFilter class is derived from QObject because we want to use Qt Signals and Slots to signal changes in accelerometer readings. + + The members x, y, and z store the previous values of the sensor reading in order to implement a low pass filter to the values. + + In the implementation of the AccelerometerFilter class, we first read the value of each axis from the QAccelerometerReading object. The values are then converted from radians to degrees and applied the low pass filter to reduce noise in the sensor readings. Different low pass factors are used depending on the platform (these were determined to be good via experimenting). Finally, the calculated value is emitted. + + Note that the accelerometer sensors are oriented differently in Symbian and Maemo devices, and we must account for this by using platform-specific code. + + \snippet demos/mobile/qtbubblelevel/accelerometerfilter.cpp 0 + + \section1 The Qt Quick UI + + BubbleLevel.qml is the main QML element. It represents the wooden board of the bubble level, and it also acts as a connection point between the QML and the Qt side. In the beginning of the element, there are two signals, two functions, and one property. All of these define the interface between Qt and QML. + + On the Maemo platform, when the application is to be minimised, minimizeApplication is signalled. When a new calibration factor is to be stored in the device's memory, saveCorrectionAngle is signalled. + + The handleRotation function acts as a Qt slot to which the AccelerometerFilters signal rotationChanged is connected. Similarly, the setCorrectionAngle function also acts as a Qt slot to which the Settings object's signal, correctionAngle, is connected. + + The property alias taskSwitcherVisible is provided to allow the Qt model to show or hide the task switcher button which minimises the application. This is only meaningful on Maemo platforms, where every application normally has a task switcher button. + + \snippet demos/mobile/qtbubblelevel/qml/BubbleLevel.qml 0 + + The Tube element represents the the glass tube of the bubble level. It is anchored to the centre of the wooden board. The width and height are calculated with specific factors to make the glass tube scale to different resolutions. + + \snippet demos/mobile/qtbubblelevel/qml/BubbleLevel.qml 1 + + In the implementation of Tube.qml, the property deg represents the current inclination. The x-position of the bubble is bound to the JavaScript function calX which is called every time the property deg, center, or bubblCenter is changed. The function places the bubble in the corresponding place on its parent. + + \snippet demos/mobile/qtbubblelevel/qml/Tube.qml 0 +*/ diff --git a/doc/src/frameworks-technologies/accessible.qdoc b/doc/src/frameworks-technologies/accessible.qdoc index e7bf171..3f63353 100644 --- a/doc/src/frameworks-technologies/accessible.qdoc +++ b/doc/src/frameworks-technologies/accessible.qdoc @@ -52,12 +52,12 @@ An application does not usually communicate directly with assistive tools but through an assistive technology, which is a bridge for exchange of information between the applications and - the tools. Information about user interface elements, such - as buttons and scroll bars, is exposed to the assistive technologies. - Qt supports Microsoft Active Accessibility (MSAA) on Windows and - Mac OS X Accessibility on Mac OS X. - On Unix/X11, support is preliminary. The individual technologies - are abstracted from Qt, and there is only a single interface to + the tools. Information about user interface elements, such as + buttons and scroll bars, is exposed to the assistive technologies. + Qt supports Microsoft Active Accessibility (MSAA) on Windows, Mac + OS X Accessibility on Mac OS X, and AT-SPI on Unix/X11. On + Unix/X11, support is preliminary. The individual technologies are + abstracted from Qt, and there is only a single interface to consider. We will use MSAA throughout this document when we need to address technology related issues. @@ -333,10 +333,16 @@ \section2 QAccessibleWidget Example Instead of creating a custom widget and implementing an interface - for it, we will show how accessibility can be implemented for one of - Qt's standard widgets: QSlider. Making this widget accessible - demonstrates many of the issues that need to be faced when making - a custom widget accessible. + for it, we will show how accessibility is implemented for one of + Qt's standard widgets: QSlider. The accessible interface, + QAccessibleSlider, inherits from QAccessibleAbstractSlider, which + in turn inherits QAccessibleWidget. You do not need to examine the + QAccessibleAbstractSlider class to read this section. If you want + to take a look, the code for all of Qt's accessible interfaces are + found in src/plugins/accessible/widgets. Here is the + QAccessibleSlider's constructor: + + \snippet doc/src/snippets/accessibilityslidersnippet.cpp 0 The slider is a complex control that functions as a \l{QAccessible::}{Controller} for its accessible children. @@ -346,8 +352,6 @@ using a controlling signal, which is a mechanism provided by QAccessibleWidget. We do this in the constructor: - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 0 - The choice of signal shown is not important; the same principles apply to all signals that are declared in this way. Note that we use QLatin1String to ensure that the signal name is correctly @@ -507,10 +511,10 @@ plugin template, and the library containing the plugin must be placed on a path where Qt searches for accessible plugins. - We will go through the implementation of \c SliderPlugin, which is an - accessible plugin that produces interfaces for the - QAccessibleSlider we implemented in the \l{QAccessibleWidget Example}. - We start with the \c key() function: + We will go through the implementation of \c SliderPlugin, which is + an accessible plugin that produces the QAccessibleSlider interface + from the \l{QAccessibleWidget Example}. We start with the \c key() + function: \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 0 @@ -521,13 +525,12 @@ \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 1 - We check whether the interface requested is for the QSlider; if it - is, we create and return an interface for it. Note that \c object - will always be an instance of \c classname. You must return 0 if - you do not support the class. - \l{QAccessible::}{updateAccessibility()} checks with the - available accessibility plugins until it finds one that does not - return 0. + We check whether the interface requested is for QSlider; if it is, + we create and return an interface for it. Note that \c object will + always be an instance of \c classname. You must return 0 if you do + not support the class. \l{QAccessible::}{updateAccessibility()} + checks with the available accessibility plugins until it finds one + that does not return 0. Finally, you need to include macros in the cpp file: @@ -536,9 +539,9 @@ The Q_EXPORT_PLUGIN2 macro exports the plugin in the \c SliderPlugin class into the \c acc_sliderplugin library. The first argument is the name of the plugin library file, excluding the - file suffix, and the second is the class name. For more information - on plugins, consult the plugins \l{How to Create Qt - Plugins}{overview document}. + file suffix, and the second is the class name. For more + information on plugins, you can consult the plugins \l{How to + Create Qt Plugins}{overview document}. You can omit the first macro unless you want the plugin to be statically linked with the application. @@ -555,7 +558,7 @@ \l{QAccessiblePlugin::}{create()} - a QString and a QObject. It also works the same way. You install the factory with the \l{QAccessible::}{installFactory()} function. We give an example - of how to create a factory for the \c SliderPlugin class: + of how to create a factory for the \c QAccessibleSlider interface: \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 0 \dots diff --git a/doc/src/getting-started/demos.qdoc b/doc/src/getting-started/demos.qdoc index 48a5fca..9366259 100644 --- a/doc/src/getting-started/demos.qdoc +++ b/doc/src/getting-started/demos.qdoc @@ -39,7 +39,7 @@ \l{Qt Examples} and are used to highlight certain features of Qt. - \table + \table \header \o {2,1} Getting an Overview \row @@ -54,6 +54,17 @@ If you are new to Qt, and want to start developing applications, you should probably start by going through the \l{Tutorials}. + \keyword qt-mobile-demos + \section1 Mobile Applications + These are demonstrations of some of the capabilities of \l{Qt Quick}Â and + \l{external: Qt Mobility Manual}{Mobility} to create feature rich mobile + applications. + \list + \o \l{Guitar Tuner Example}{Guitar Tuner} - a guitar tuner made with a QML frontend and a Mobility based backend + \o \l{Quick Hit Demo}{Quick Hit} - a game that uses multimedia and Qt Quick + \o \l{Qt Bubble Level Example}{Qt Bubble Level} - a game that utilizes hardware sensors for effects + \o \l{QCamera Example}{QCamera} - a camera application that accesses mobile contacts and networking + \endlist \section1 Painting \list @@ -105,19 +116,19 @@ \list \o \l{demos/mainwindow}{Main Window} shows Qt's extensive support for main window features, such as tool bars, dock windows, and menus. - \o \l{demos/macmainwindow}{Mac Main Window} shows how to create main window applications that has + \o \l{demos/macmainwindow}{Mac Main Window} shows how to create main window applications that has the same appearance as other Mac OS X applications. \endlist \section1 Graphics View \list - \o \l{demos/chip}{40000 Chips} uses the \l{Graphics View Framework} to - efficiently display a large number of individual graphical items on - a scrolling canvas and highlighting features including rotation, + \o \l{demos/chip}{40000 Chips} uses the \l{Graphics View Framework} to + efficiently display a large number of individual graphical items on + a scrolling canvas and highlighting features including rotation, zooming, level of detail control, and item selection. - \o \l{demos/embeddeddialogs}{Embedded Dialogs} showcases Qt 4.4's - \e{Widgets on the Canvas} feature by embedding several + \o \l{demos/embeddeddialogs}{Embedded Dialogs} showcases Qt 4.4's + \e{Widgets on the Canvas} feature by embedding several fully-functional dialogs in a scene. \o \l{demos/boxes}{Boxes} showcases Qt's OpenGL support and the integration with the \l{Graphics View Framework}. diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc index ede8a5b..f988d03 100644 --- a/doc/src/getting-started/examples.qdoc +++ b/doc/src/getting-started/examples.qdoc @@ -36,7 +36,8 @@ You can run the examples from the \l{Examples and Demos Launcher} application (except see \l{QML Examples and Demos} {QML Examples} - for special instructions for running those examples). + for special instructions for running those examples). In addition, + Qt Creator can directly run these examples through the Welcome Page. The examples are listed below by functional area. Each example listed in a particular functional area is meant to illustrate how @@ -56,8 +57,14 @@ These examples are provided under the terms of the \l{New and Modified BSD Licenses}{Modified BSD License}. + \section1 Qt Quick Example Code + The \l{QML Examples and Demos} site has a dedicated page for QML examples. - \section1 Examples by Functional Area + \section1 Qt Mobility Example Code + The \l{external: Qt Mobility Examples}{Qt Mobility Examples} page lists + examples that show how the Qt Mobility APIs might be used. + + \section1 Qt Examples by Module or Technology \generatelist{related} */ diff --git a/doc/src/getting-started/gettingstartedqt.qdoc b/doc/src/getting-started/gettingstartedqt.qdoc index 2800be0..18f85f1 100644 --- a/doc/src/getting-started/gettingstartedqt.qdoc +++ b/doc/src/getting-started/gettingstartedqt.qdoc @@ -105,12 +105,13 @@ This will leave an executable in the \c part1 directory (note that on Windows, you may have to use \c nmake instead of \c make. Also, - the executable will be placed in part1/debug or part1/release). \c - qmake is Qt's build tool, which takes a configuration file. \c - qmake generates this for us when given the \c{-project} argument. - Given the configuration file (suffixed .pro), \c qmake produces a - \c make file that will build the program for you. We will look - into writing our own \c .pro files later. + the executable will be placed in part1\\debug or part1\\release + (these directories are created when you run \c make). \c qmake is + Qt's build tool, which takes a configuration file. \c qmake + generates this for us when given the \c{-project} argument. Given + the configuration file (suffixed .pro), \c qmake produces a \c + make file that will build the program for you. We will look into + writing our own \c .pro files later. \section2 Learn More @@ -245,28 +246,28 @@ parameter types and invoke it. Line 13 declares the slot \c quit(). This is easy using the \c - slots macro. The \c quit() slot can now be connected to signals - with a matching signature (any signal that takes no parameters). + slots macro. The \c quit() slot can now be connected to signals. + We will do that later. Instead of setting up the GUI and connecting the slot in the \c main() function, we now use \c{Notepad}'s constructor. \code - Notepad::Notepad() - { - textEdit = new QTextEdit; - quitButton = new QPushButton(tr("Quit")); - - connect(quitButton, SIGNAL(clicked()), this, SLOT(quit())); - - QVBoxLayout *layout = new QVBoxLayout; - layout->addWidget(textEdit); - layout->addWidget(quitButton); - - setLayout(layout); - - setWindowTitle(tr("Notepad")); - } +20 Notepad::Notepad() +21 { +22 textEdit = new QTextEdit; +23 quitButton = new QPushButton(tr("Quit")); +24 +25 connect(quitButton, SIGNAL(clicked()), this, SLOT(quit())); +26 +27 QVBoxLayout *layout = new QVBoxLayout; +28 layout->addWidget(textEdit); +29 layout->addWidget(quitButton); +30 +31 setLayout(layout); +32 +33 setWindowTitle(tr("Notepad")); +34 } \endcode As you saw in the class definition, we use pointers to our \l @@ -277,7 +278,9 @@ visible strings. This function is necessary when you want to provide your application in more than one language (e.g. English and Chinese). We will not go into details here, but you can follow - the \c {Qt Linguist} link from the learn more table. + the \c {Qt Linguist} link from the learn more table. We will not + look at the implementation of \c quit() slot and the \c main() + function, but you can check out the source code if you want to. \section2 Learn More @@ -305,9 +308,9 @@ using \c qmake's \c -project option. \code - HEADERS = notepad.h - SOURCES = notepad.cpp \ - main.cpp + 1 HEADERS = notepad.h + 2 SOURCES = notepad.cpp \ + 3 main.cpp \endcode The following shell commands build the example. @@ -330,29 +333,29 @@ Let us look at the new \c Notepad class definition. \code - #include <QtGui> - - class Notepad : public QMainWindow - { - Q_OBJECT - - public: - Notepad(); - - private slots: - void open(); - void save(); - void quit(); - - private: - QTextEdit *textEdit; - - QAction *openAction; - QAction *saveAction; - QAction *exitAction; - - QMenu *fileMenu; - }; + 2 #include <QtGui> + 3 + 4 class Notepad : public QMainWindow + 5 { + 6 Q_OBJECT + 7 + 8 public: + 9 Notepad(); +10 +11 private slots: +12 void open(); +13 void save(); +14 void quit(); +15 +16 private: +17 QTextEdit *textEdit; +18 +19 QAction *openAction; +20 QAction *saveAction; +21 QAction *exitAction; +22 +23 QMenu *fileMenu; +24 }; \endcode We include two more slots that can save and open a document. We @@ -369,27 +372,27 @@ GUI. \code - Notepad::Notepad() - { - saveAction = new QAction(tr("&Open"), this); - saveAction = new QAction(tr("&Save"), this); - exitAction = new QAction(tr("E&xit"), this); - - connect(openAction, SIGNAL(triggered()), this, SLOT(open())); - connect(saveAction, SIGNAL(triggered()), this, SLOT(save())); - connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit())); - - fileMenu = menuBar()->addMenu(tr("&File")); - fileMenu->addAction(openAction); - fileMenu->addAction(saveAction); - fileMenu->addSeparator(); - fileMenu->addAction(exitAction); - - textEdit = new QTextEdit; - setCentralWidget(textEdit); - - setWindowTitle(tr("Notepad")); - } +25 Notepad::Notepad() +26 { +27 saveAction = new QAction(tr("&Open"), this); +28 saveAction = new QAction(tr("&Save"), this); +29 exitAction = new QAction(tr("E&xit"), this); +30 +31 connect(openAction, SIGNAL(triggered()), this, SLOT(open())); +32 connect(saveAction, SIGNAL(triggered()), this, SLOT(save())); +33 connect(exitAction, SIGNAL(triggered()), qApp, SLOT(quit())); +34 +35 fileMenu = menuBar()->addMenu(tr("&File")); +36 fileMenu->addAction(openAction); +37 fileMenu->addAction(saveAction); +38 fileMenu->addSeparator(); +39 fileMenu->addAction(exitAction); +40 +41 textEdit = new QTextEdit; +42 setCentralWidget(textEdit); +43 +44 setWindowTitle(tr("Notepad")); +45 } \endcode \l{QAction}s are created with the text that should appear on the @@ -426,28 +429,29 @@ We will start with the \c open() slot: \code - QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), "", - tr("Text Files (*.txt);;C++ Files (*.cpp *.h)")); - - if (fileName != "") { - QFile file(fileName); - if (!file.open(QIODevice::ReadOnly)) { - QMessageBox::critical(this, tr("Error"), - tr("Could not open file")); - return; - } - QString contents = file.readAll().constData(); - textEdit->setPlainText(contents); - file.close(); - } +48 void Notepad::open() +49 { +50 QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), "", +51 tr("Text Files (*.txt);;C++ Files (*.cpp *.h)")); +52 +53 if (fileName != "") { +54 QFile file(fileName); +55 if (!file.open(QIODevice::ReadOnly)) { +56 QMessageBox::critical(this, tr("Error"), tr("Could not open file")); +57 return; +58 } +59 QTextStream in(&file); +60 textEdit->setText(in.readAll()); +61 file.close(); +62 } +63 } \endcode The first step is asking the user for the name of the file to open. Qt comes with QFileDialog, which is a dialog from which the user can select a file. The image above shows the dialog on Kubuntu. The static \l{QFileDialog::}{getOpenFileName()} function - displays a modal file dialog, and does not return until the user - has selected a file. It returns the file path of the file + displays a modal file dialog. It returns the file path of the file selected, or an empty string if the user canceled the dialog. If we have a file name, we try to open the file with @@ -458,38 +462,38 @@ message (see the QMessageBox class description for further details). - Actually reading in the data is trivial using the - \l{QIODevice::}{readAll()} function, which returns all data in the - file in a QByteArray. The \l{QByteArray::}{constData()} returns all - data in the array as a const char*, which QString has a - constructor for. The contents can then be displayed in the text + Actually reading in the data is trivial using the QTextStream + class, which wraps the QFile object. The + \l{QTextStream::}{readAll()} function returns the contents of the + file as a QString. The contents can then be displayed in the text edit. We then \l{QIODevice::}{close()} the file to return the file descriptor back to the operating system. Now, let us move on to the the \c save() slot. \code - QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), "", - tr("Text Files (*.txt);;C++ Files (*.cpp *.h)")); - - if (fileName != "") { - QFile file(fileName); - if (!file.open(QIODevice::WriteOnly)) { - // error message - } else { - QTextStream stream(&file); - stream << textEdit->toPlainText(); - stream.flush(); - file.close(); - } - } +65 void Notepad::save() +66 { +67 QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), "", +68 tr("Text Files (*.txt);;C++ Files (*.cpp *.h)")); +69 +70 if (fileName != "") { +71 QFile file(fileName); +72 if (!file.open(QIODevice::WriteOnly)) { +73 // error message +74 } else { +75 QTextStream stream(&file); +76 stream << textEdit->toPlainText(); +77 stream.flush(); +78 file.close(); +79 } +80 } +81 } \endcode When we write the contents of the text edit to the file, we use - the QTextStream class, which wraps the QFile object. The text - stream can write QStrings directly to the file; QFile only accepts - raw data (char*) with the \l{QIODevice::}{write()} functions of - QIODevice. + the QTextStream class again. QTextStream can also write + \l{QString}s to the file with the << operator. \section2 Learn More diff --git a/doc/src/getting-started/tutorials.qdoc b/doc/src/getting-started/tutorials.qdoc index 9fc6699..2849870 100644 --- a/doc/src/getting-started/tutorials.qdoc +++ b/doc/src/getting-started/tutorials.qdoc @@ -36,79 +36,106 @@ \nextpage Qt Examples - A collection of tutorials and "walkthrough" guides are provided with Qt to + A collection of tutorials and \e walkthrough guides are provided with Qt to help new users get started with Qt development. These documents cover a range of topics, from basic use of widgets to step-by-step tutorials that show how an application is put together. - \table - \row - \o{2,1} \l{Widgets Tutorial}{\bold Widgets} - \o{2,1} \l{Address Book Tutorial}{\bold {Address Book}} - \row - \o \image widget-examples.png Widgets - \o - A beginner's guide to getting started with widgets and layouts to create - GUI applications. - - \o \image addressbook-tutorial.png AddressBook - \o - A seven part guide to creating a fully-functioning address book - application. This tutorial is also available with - \l{Tutoriel "Carnet d'adresses"}{French explanation}. - - \row - \o{2,1} \l{A Quick Start to Qt Designer}{\bold{Qt Designer}} - \o{2,1} \l{Qt Linguist Manual: Programmers#Tutorials}{\bold {Qt Linguist}} - \row - \o \image designer-examples.png - \o - A quick guide through \QD showing the basic steps to create a - form with this interactive tool. - - \o \image linguist-examples.png QtLinguist - \o - A guided tour through the translations process, explaining the - tools provided for developers, translators and release managers. - - -\row - \o{2,1} \l{modelview.html}{\bold{ModelView}} - \o{2,1} \l{thread-basics.html}{\bold {Threads}} - \row - \o \image treeview_sml.png ModelView - \o - This tutorial gives an introduction to ModelView programming using the Qt cross-platform framework - - \o \image threads-examples.png Threads - \o - A short tutorial about thread concepts in general and basic Qt classes to handle threads. - - \row - \o{2,1} \l{QML Tutorial}{\bold QML Tutorial} - \o{2,1} \l{QML Advanced Tutorial}{\bold SameGame} - \row - \o{2,1} - This tutorial provides a very basic introduction to QML. - \o \image qml-samegame-demo-small.png Samegame - \o - This tutorial walks through creating a complete application with QML, - in this case a simple game. It is recommended that you complete the basic QML - tutorial first. - - \row - \o{2,1} \l{QTestLib Tutorial}{\bold QTestLib} - \o{2,1} \l{qmake Tutorial}{\bold qmake} - \row - \o{2,1} - This tutorial gives a short introduction to how to use some of the - features of Qt's unit-testing framework, QTestLib. It is divided into - four chapters. - - \o{2,1} - This tutorial teaches you how to use \c qmake. We recommend that - you read the \l{qmake Manual}{qmake user guide} after completing - this tutorial. - - \endtable + For demonstrations on how to use different Qt technologies, visit the + \l{Qt Examples} page. + + \section1 Qt Creator Tutorial + Qt Creator is the development environment for Qt. + \list + \o \l{external: Qt Creator Manual}{Qt Creator Manual} - The manual contains + information on how to achieve development tasks + These are excerpts from the manual: + \list + \o \l{external: Creating Qt Projects in Creator}{Creating Qt Projects in Creator} + \o \l{external: Developing Qt Quick Applications with Creator}{Developing Qt Quick Applications with Creator} + \o \l{external: Building and Running Applications in Creator}{Building and Running Applications in Creator} + \o \l{external: Debugging Applications in Creator}{Debugging Applications in Creator} + \o \l{external: Publishing Applications to Ovi Store}{Publishing Applications to Ovi Store} + \endlist + \endlist + + \section1 Qt Essentials + The basic concepts and technologies in Qt are introduced in these essential + tutorials. + \list + \o \l{Getting Started Programming with Qt}{Qt Text Editor} - A simple + tutorial detailing the creation of a basic Qt application + Introduces the use of slots and signals, file operations, and widgets. + \o \l{Address Book Tutorial}{Address Book} - A beginner's guide to + widgets, container classes, and layouts. This tutorial is also available + with + \l{Tutoriel "Carnet d'adresses"}{French version}. + \image addressbook-tutorial.png AddressBook + \o \l{modelview.html}{ModelView} - This tutorial gives an introduction to + ModelView programming using the Qt cross-platform framework + \o\l{thread-basics.html}{Threads} - A short tutorial about thread concepts + in general and basic Qt classes to handle threads + \endlist + + \section1 Qt Quick Essentials + Qt Quick and QML features are covered in several tutorials, ranging from + easy introductions to advanced tutorials that mix QML with C++ and + JavaScript. + \list + \o \l{QML Tutorial}{Hello World} - A very simple QML example that + demonstrates the basic QML features + \o \l{Getting Started Programming with QML}{QML Text Editor} - An + intermediate QML tutorial that covers many QML features such as states, + plugins, and C++ development + \o \l{QML Advanced Tutorial}{SameGame} - A walkthrough of creating a + simple game using QML for the interface and JavaScript for the game + logic + \image qml-samegame-demo-small.png Samegame + \endlist + + \section1 QtWebKit + \list + \o \l{QtWebKit Guide} - An introductory guide to the features of QtWebKit + and HTML5. + \list + \o \l{QtWebKit Guide - Level 3 CSS}{CSS Chapter} - Covers what is + possible with CSS3 and QtWebKit. + \o \l{Canvas Graphics}{HTML5 Canvas Chapter} - Covers the basics of + integrating the <canvas> element into web applications. + \o \l{QtWebKit Guide - Client Storage}{Client Storage Chapter} - + Describes the basics of storing information on the client side. + \endlist + \endlist + + \section1 Qt Utilities + \list + \o \l{QTestLib Tutorial}{QTestLib} - This tutorial gives a short + introduction to how to use some of the features of Qt's unit-testing + framework, QTestLib. It is divided into four chapters. + \o \l{qmake Tutorial}{qmake} - This tutorial teaches you how to use \c + qmake. We recommend that you read the \l{qmake Manual}{qmake user guide} + after completing this tutorial. + \o \l{Qt Linguist Manual: Programmers#Tutorials}{Qt Linguist} - A guided + tour through the translations process, explaining the tools provided for + developers, translators and release managers. + \image linguist-examples.png QtLinguist + \endlist + + \section1 Online Learning Materials + These online materials provide further tutorials and developer + presentations. + + \note The videos presented in these sites are not supported by the + Qt Creator browser and must be viewed in a web browser. + + \list + \o \l{Qt eLearning} - The Qt eLearning team provides training and Qt + certification. Many of their learning content are hosted online. + \list + \o \l{Qt eLearning Training Materials} - Additional training material + are available as videos, downloadable code, and PDF files. + \o \l{Qt Developer Days 2010} - The presentation slides and videos from + Qt Developer Days are available for viewing. + \endlist + \endlist */ diff --git a/doc/src/howtos/developmentsteps.qdoc b/doc/src/howtos/developmentsteps.qdoc index e898bf5..078de80 100644 --- a/doc/src/howtos/developmentsteps.qdoc +++ b/doc/src/howtos/developmentsteps.qdoc @@ -94,7 +94,7 @@ great way to do it. Not knowing a better place to start, you begin by taking a cue from web design and plan a wireframe, which helps -\l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-visual-editor.html}{define the application layout}, +\l{external: Developing Qt Quick Applications}{define the application layout}, content and user interaction. You decide on breaking the field of the screen space into three roughly equal size parts. There will be one section across the top, which will span the width of the screen, and two sections in the lower @@ -130,7 +130,7 @@ quickly: Devising a user friendly interface to audio playback is not as intuitive as you first thought. Since there exist a ready made component for -\l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-multimedia.html}{multimedia}, +\l{external: Mobility Multimedia}{multimedia}, you remove the bottom left field and now have the screen split in two. You add textual links for each of the five target languages, and when the user clicks one of them the message text changes and the appropriate audio plays back. It is @@ -164,7 +164,7 @@ for your current and future projects: using \l{Qt WebKit} \o An \l{qt-rendering-painting-system}{OpenGL} based UI for embedded platforms \o \l{Gestures Programming}{Touch} screen support -\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/location-overview.html}{Location} based applications +\o \l{external: Mobility Location}{Location} based applications \o \l{qt-technologies}{Much, much more} \endlist diff --git a/doc/src/howtos/scalabilityintro.qdoc b/doc/src/howtos/scalabilityintro.qdoc index 5b4e58b..b1d9c19 100644 --- a/doc/src/howtos/scalabilityintro.qdoc +++ b/doc/src/howtos/scalabilityintro.qdoc @@ -198,11 +198,11 @@ \list \o \l{Item::anchors.top}{anchors} within an Item \o \l{Row} / \l{Column} / \l{Grid} - \o simple javascript expressions such as width: Math.round(parent.width / 3.0). + \o simple JavaScript expressions such as width: Math.round(parent.width / 3.0). \endlist These basic building blocks, along with the powerful evaluation - capabilities of javascript expressions within every QML binding, + capabilities of JavaScript expressions within every QML binding, are designed to allow the majority of the layout structure definition to be defined in a Device Profile independent way. @@ -214,14 +214,14 @@ container. By combining the features of the layout managers with simple - javascript expressions, a richer variety of designs can be + JavaScript expressions, a richer variety of designs can be expressed, without having to resort to additional layout measurement parameters or measurement values. Here are some things not to do with layouts: \list - \o Don't define complex javascript functions that are regularly + \o Don't define complex JavaScript functions that are regularly evaluated. This will cause poor performance, particularly during animated transitions. \o Don't define all of your layouts using x, y, width and @@ -275,7 +275,7 @@ by the top level orientation change), in the case of anchor layouts, AnchorAnimation elements can be used to control the transitions. In some cases, you can also use a NumberAnimation on - e.g. the width of an item. Remember to avoid complex javascript + e.g. the width of an item. Remember to avoid complex JavaScript calculations during each frame of animation. Using simple anchor definitions and anchor animations can help with this in the majority of cases. diff --git a/doc/src/images/qcameraexample.png b/doc/src/images/qcameraexample.png Binary files differnew file mode 100644 index 0000000..cdf7d4e --- /dev/null +++ b/doc/src/images/qcameraexample.png diff --git a/doc/src/images/qml-guitartuner-example.png b/doc/src/images/qml-guitartuner-example.png Binary files differnew file mode 100644 index 0000000..2f13e8d --- /dev/null +++ b/doc/src/images/qml-guitartuner-example.png diff --git a/doc/src/images/qml-qtbubblelevel-demo.png b/doc/src/images/qml-qtbubblelevel-demo.png Binary files differnew file mode 100644 index 0000000..9d5bc4b --- /dev/null +++ b/doc/src/images/qml-qtbubblelevel-demo.png diff --git a/doc/src/images/webkit-guide/canvas_arcTo.png b/doc/src/images/webkit-guide/canvas_arcTo.png Binary files differnew file mode 100644 index 0000000..6bc1871 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_arcTo.png diff --git a/doc/src/images/webkit-guide/canvas_arcTo2.png b/doc/src/images/webkit-guide/canvas_arcTo2.png Binary files differnew file mode 100644 index 0000000..5f9d32d --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_arcTo2.png diff --git a/doc/src/images/webkit-guide/canvas_clip-complex.png b/doc/src/images/webkit-guide/canvas_clip-complex.png Binary files differnew file mode 100644 index 0000000..cb582ba --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_clip-complex.png diff --git a/doc/src/images/webkit-guide/canvas_clip.png b/doc/src/images/webkit-guide/canvas_clip.png Binary files differnew file mode 100644 index 0000000..c397f5e --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_clip.png diff --git a/doc/src/images/webkit-guide/canvas_clip_aqu.png b/doc/src/images/webkit-guide/canvas_clip_aqu.png Binary files differnew file mode 100644 index 0000000..d0696d6 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_clip_aqu.png diff --git a/doc/src/images/webkit-guide/canvas_closepath.gif b/doc/src/images/webkit-guide/canvas_closepath.gif Binary files differnew file mode 100644 index 0000000..e32024a --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_closepath.gif diff --git a/doc/src/images/webkit-guide/canvas_composite.png b/doc/src/images/webkit-guide/canvas_composite.png Binary files differnew file mode 100644 index 0000000..6e20efa --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_composite.png diff --git a/doc/src/images/webkit-guide/canvas_context.gif b/doc/src/images/webkit-guide/canvas_context.gif Binary files differnew file mode 100644 index 0000000..f18e52ca --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_context.gif diff --git a/doc/src/images/webkit-guide/canvas_lineStrokeTo.gif b/doc/src/images/webkit-guide/canvas_lineStrokeTo.gif Binary files differnew file mode 100644 index 0000000..e05aa00 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_lineStrokeTo.gif diff --git a/doc/src/images/webkit-guide/canvas_linecap.png b/doc/src/images/webkit-guide/canvas_linecap.png Binary files differnew file mode 100644 index 0000000..72ecce5 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_linecap.png diff --git a/doc/src/images/webkit-guide/canvas_math.png b/doc/src/images/webkit-guide/canvas_math.png Binary files differnew file mode 100644 index 0000000..c039a38 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_math.png diff --git a/doc/src/images/webkit-guide/canvas_math_rotate.png b/doc/src/images/webkit-guide/canvas_math_rotate.png Binary files differnew file mode 100644 index 0000000..e80cc09 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_math_rotate.png diff --git a/doc/src/images/webkit-guide/canvas_pattern.png b/doc/src/images/webkit-guide/canvas_pattern.png Binary files differnew file mode 100644 index 0000000..6b593bc --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_pattern.png diff --git a/doc/src/images/webkit-guide/canvas_rectangles.gif b/doc/src/images/webkit-guide/canvas_rectangles.gif Binary files differnew file mode 100644 index 0000000..3b44cc5 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_rectangles.gif diff --git a/doc/src/images/webkit-guide/canvas_rotate.png b/doc/src/images/webkit-guide/canvas_rotate.png Binary files differnew file mode 100644 index 0000000..20947fd --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_rotate.png diff --git a/doc/src/images/webkit-guide/canvas_scale.png b/doc/src/images/webkit-guide/canvas_scale.png Binary files differnew file mode 100644 index 0000000..3b26fde --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_scale.png diff --git a/doc/src/images/webkit-guide/canvas_scalex.png b/doc/src/images/webkit-guide/canvas_scalex.png Binary files differnew file mode 100644 index 0000000..d4e76aa --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_scalex.png diff --git a/doc/src/images/webkit-guide/canvas_scaley.png b/doc/src/images/webkit-guide/canvas_scaley.png Binary files differnew file mode 100644 index 0000000..61462b9 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_scaley.png diff --git a/doc/src/images/webkit-guide/canvas_skewx.png b/doc/src/images/webkit-guide/canvas_skewx.png Binary files differnew file mode 100644 index 0000000..c9bcb67 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_skewx.png diff --git a/doc/src/images/webkit-guide/canvas_skewy.png b/doc/src/images/webkit-guide/canvas_skewy.png Binary files differnew file mode 100644 index 0000000..594ac84 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_skewy.png diff --git a/doc/src/images/webkit-guide/canvas_startAngle.png b/doc/src/images/webkit-guide/canvas_startAngle.png Binary files differnew file mode 100644 index 0000000..f81562e --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_startAngle.png diff --git a/doc/src/images/webkit-guide/canvas_text.png b/doc/src/images/webkit-guide/canvas_text.png Binary files differnew file mode 100644 index 0000000..6983047 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_text.png diff --git a/doc/src/images/webkit-guide/canvas_translate.png b/doc/src/images/webkit-guide/canvas_translate.png Binary files differnew file mode 100644 index 0000000..7bb3ae7 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_translate.png diff --git a/doc/src/images/webkit-guide/canvas_translatey.png b/doc/src/images/webkit-guide/canvas_translatey.png Binary files differnew file mode 100644 index 0000000..9196bf5 --- /dev/null +++ b/doc/src/images/webkit-guide/canvas_translatey.png diff --git a/doc/src/images/webkit-guide/mask0.png b/doc/src/images/webkit-guide/mask0.png Binary files differnew file mode 100644 index 0000000..f9764b5 --- /dev/null +++ b/doc/src/images/webkit-guide/mask0.png diff --git a/doc/src/images/webkit-guide/mask1.png b/doc/src/images/webkit-guide/mask1.png Binary files differnew file mode 100644 index 0000000..5ca7798 --- /dev/null +++ b/doc/src/images/webkit-guide/mask1.png diff --git a/doc/src/images/webkit-guide/scr_anim_accord.png b/doc/src/images/webkit-guide/scr_anim_accord.png Binary files differnew file mode 100644 index 0000000..4295e15 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_accord.png diff --git a/doc/src/images/webkit-guide/scr_anim_demo-rotate.png b/doc/src/images/webkit-guide/scr_anim_demo-rotate.png Binary files differnew file mode 100644 index 0000000..d18bf16 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_demo-rotate.png diff --git a/doc/src/images/webkit-guide/scr_anim_demo-scale.png b/doc/src/images/webkit-guide/scr_anim_demo-scale.png Binary files differnew file mode 100644 index 0000000..8d32d1c --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_demo-scale.png diff --git a/doc/src/images/webkit-guide/scr_anim_demo-skew.png b/doc/src/images/webkit-guide/scr_anim_demo-skew.png Binary files differnew file mode 100644 index 0000000..15fc0fa --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_demo-skew.png diff --git a/doc/src/images/webkit-guide/scr_anim_gallery.png b/doc/src/images/webkit-guide/scr_anim_gallery.png Binary files differnew file mode 100644 index 0000000..aa32583 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_gallery.png diff --git a/doc/src/images/webkit-guide/scr_anim_panel.png b/doc/src/images/webkit-guide/scr_anim_panel.png Binary files differnew file mode 100644 index 0000000..ceff393 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_panel.png diff --git a/doc/src/images/webkit-guide/scr_anim_pulse.png b/doc/src/images/webkit-guide/scr_anim_pulse.png Binary files differnew file mode 100644 index 0000000..afa9ff8 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_pulse.png diff --git a/doc/src/images/webkit-guide/scr_anim_skew.png b/doc/src/images/webkit-guide/scr_anim_skew.png Binary files differnew file mode 100644 index 0000000..819a3a1 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_skew.png diff --git a/doc/src/images/webkit-guide/scr_anim_slide1.png b/doc/src/images/webkit-guide/scr_anim_slide1.png Binary files differnew file mode 100644 index 0000000..8fdf79f --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_slide1.png diff --git a/doc/src/images/webkit-guide/scr_anim_tabbedSkew.png b/doc/src/images/webkit-guide/scr_anim_tabbedSkew.png Binary files differnew file mode 100644 index 0000000..fd07fd7 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_anim_tabbedSkew.png diff --git a/doc/src/images/webkit-guide/scr_css3_backgrounds.png b/doc/src/images/webkit-guide/scr_css3_backgrounds.png Binary files differnew file mode 100644 index 0000000..96fec39 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_backgrounds.png diff --git a/doc/src/images/webkit-guide/scr_css3_border-img.png b/doc/src/images/webkit-guide/scr_css3_border-img.png Binary files differnew file mode 100644 index 0000000..9242b4c --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_border-img.png diff --git a/doc/src/images/webkit-guide/scr_css3_grad-radial.png b/doc/src/images/webkit-guide/scr_css3_grad-radial.png Binary files differnew file mode 100644 index 0000000..e520f8a --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_grad-radial.png diff --git a/doc/src/images/webkit-guide/scr_css3_gradientBack.png b/doc/src/images/webkit-guide/scr_css3_gradientBack.png Binary files differnew file mode 100644 index 0000000..22f80af --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_gradientBack.png diff --git a/doc/src/images/webkit-guide/scr_css3_gradientBackStop.png b/doc/src/images/webkit-guide/scr_css3_gradientBackStop.png Binary files differnew file mode 100644 index 0000000..ff12a11 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_gradientBackStop.png diff --git a/doc/src/images/webkit-guide/scr_css3_gradientButton.png b/doc/src/images/webkit-guide/scr_css3_gradientButton.png Binary files differnew file mode 100644 index 0000000..b3ba62e --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_gradientButton.png diff --git a/doc/src/images/webkit-guide/scr_css3_mask-grad.png b/doc/src/images/webkit-guide/scr_css3_mask-grad.png Binary files differnew file mode 100644 index 0000000..bb539e6 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_mask-grad.png diff --git a/doc/src/images/webkit-guide/scr_css3_mask-img.png b/doc/src/images/webkit-guide/scr_css3_mask-img.png Binary files differnew file mode 100644 index 0000000..6215739 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_mask-img.png diff --git a/doc/src/images/webkit-guide/scr_css3_multicol.png b/doc/src/images/webkit-guide/scr_css3_multicol.png Binary files differnew file mode 100644 index 0000000..775d685 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_multicol.png diff --git a/doc/src/images/webkit-guide/scr_css3_reflect.png b/doc/src/images/webkit-guide/scr_css3_reflect.png Binary files differnew file mode 100644 index 0000000..94e58c3 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_reflect.png diff --git a/doc/src/images/webkit-guide/scr_css3_scroll.png b/doc/src/images/webkit-guide/scr_css3_scroll.png Binary files differnew file mode 100644 index 0000000..d11e05e --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_scroll.png diff --git a/doc/src/images/webkit-guide/scr_css3_sel-nth.png b/doc/src/images/webkit-guide/scr_css3_sel-nth.png Binary files differnew file mode 100644 index 0000000..fe8d26c --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_sel-nth.png diff --git a/doc/src/images/webkit-guide/scr_css3_text-overflow.png b/doc/src/images/webkit-guide/scr_css3_text-overflow.png Binary files differnew file mode 100644 index 0000000..084a52e --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_text-overflow.png diff --git a/doc/src/images/webkit-guide/scr_css3_text-shadow.png b/doc/src/images/webkit-guide/scr_css3_text-shadow.png Binary files differnew file mode 100644 index 0000000..e23e8fa --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_text-shadow.png diff --git a/doc/src/images/webkit-guide/scr_css3_text-stroke.png b/doc/src/images/webkit-guide/scr_css3_text-stroke.png Binary files differnew file mode 100644 index 0000000..5fb3f0d --- /dev/null +++ b/doc/src/images/webkit-guide/scr_css3_text-stroke.png diff --git a/doc/src/images/webkit-guide/scr_form_tapper.png b/doc/src/images/webkit-guide/scr_form_tapper.png Binary files differnew file mode 100644 index 0000000..3a00060 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_form_tapper.png diff --git a/doc/src/images/webkit-guide/scr_form_toggler.png b/doc/src/images/webkit-guide/scr_form_toggler.png Binary files differnew file mode 100644 index 0000000..c03d259 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_form_toggler.png diff --git a/doc/src/images/webkit-guide/scr_layout_link-fmt.png b/doc/src/images/webkit-guide/scr_layout_link-fmt.png Binary files differnew file mode 100644 index 0000000..68e8d72 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_layout_link-fmt.png diff --git a/doc/src/images/webkit-guide/scr_layout_tbl-keyhole.png b/doc/src/images/webkit-guide/scr_layout_tbl-keyhole.png Binary files differnew file mode 100644 index 0000000..d90fcd8 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_layout_tbl-keyhole.png diff --git a/doc/src/images/webkit-guide/scr_mob_condjs.png b/doc/src/images/webkit-guide/scr_mob_condjs.png Binary files differnew file mode 100644 index 0000000..4793f80 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_mob_condjs.png diff --git a/doc/src/images/webkit-guide/scr_mob_layout.png b/doc/src/images/webkit-guide/scr_mob_layout.png Binary files differnew file mode 100644 index 0000000..f3c40ed --- /dev/null +++ b/doc/src/images/webkit-guide/scr_mob_layout.png diff --git a/doc/src/images/webkit-guide/scr_mob_mediaquery.png b/doc/src/images/webkit-guide/scr_mob_mediaquery.png Binary files differnew file mode 100644 index 0000000..c51aec7 --- /dev/null +++ b/doc/src/images/webkit-guide/scr_mob_mediaquery.png diff --git a/doc/src/images/webkit-guide/scr_storage.png b/doc/src/images/webkit-guide/scr_storage.png Binary files differnew file mode 100644 index 0000000..d71156f --- /dev/null +++ b/doc/src/images/webkit-guide/scr_storage.png diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 079a03b..2d40400 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -29,33 +29,24 @@ \page index.html \keyword Qt Reference Documentation -\div {class="indexbox guide"} - \div {class="heading"} - Qt Developer Guide - \enddiv -\enddiv \div {class="indexbox tools"} \div {class="indexboxcont indexboxbar"} \div {class="sectionlist normallist"} - \div {class="heading"} - What is Qt - \enddiv - \image qt-logo_large.png - Qt is a cross-platform application and UI framework. Using Qt, you can - write applications once and deploy them across desktop, mobile, and - embedded operating systems without rewriting the source code. - \enddiv - \div {class="sectionlist normallist"} + \div {class="heading"} + What is Qt + \enddiv \list - \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/index.html}{Qt SDK} - \o \l{http://developer.qt.nokia.com/wiki/QtCreatorWhitepaper}{Qt Creator} - \o \l{http://doc.qt.nokia.com/qtsimulator-1.1/index.html}{Qt Simulator} + \o \l{Qt Whitepaper}{Qt C++ Framework} + \o \l{Intro to Qt Quick}{Qt Quick} + \o \l{external: Qt Mobility Manual}{Qt Mobility} + \o \l{Qt WebKit} \endlist + \enddiv + \div {class="sectionlist normallist"} \list - \o \l{http://developer.qt.nokia.com/wiki/QtWhitepaper}{Qt C++ Framework} - \o \l{Qt Quick} - \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility} - \o \l{Qt WebKit} + \o \l{external: Qt SDK Manual}{Qt SDK} + \o \l{Qt Creator Whitepaper}{Qt Creator} + \o \l{external: Qt Simulator Manual}{Qt Simulator} \endlist \list \o \l{Supported Platforms}{Platform Support} @@ -64,13 +55,12 @@ \enddiv \div {class="sectionlist normallist"} \div {class="heading"} - See Qt + Qt in Action \enddiv - \image mobile.png \list \o \l{Qt Demonstrations}{Application Gallery} - \o \l{Tutorials} - \o \l{Qt Examples}{Examples} + \o \l{Tutorials}{Step-by-Step Tutorials} + \o \l{Qt Examples}{Qt Example Code} \o \l{QML Examples and Demos} \endlist \enddiv @@ -82,42 +72,45 @@ \div {class="heading"} Develop with Qt \enddiv - \image tools.png \list \o \l{Develop with Qt}{Steps to Programming Qt Applications} \o \l{qt-creator-configure-target}{Configure Qt and Creator for Platforms} \o \l{qt-technologies}{Qt Features and Technologies} \o \l{qt-utilities}{Utilities and Testing} - \o \l{qt-deployment}{Deploying Applications and Publish to Ovi Store} - \endlist - \enddiv - \div {class="sectionlist normallist"} - \div {class="heading"} - Featured Articles - \enddiv - \image guide.png - \list - \o \l{Scalability}{How to Create Scalable Applications} - \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-symbian.html}{Setting Up Development Environment for Symbian} - \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-maemo.html}{Setting Up Development Environment for Maemo} - \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-publish-ovi.html}{Publishing Qt Applications to Ovi Store} + \o \l{qt-deployment}{Deploying and Publishing Applications to Ovi Store} \endlist \list - \o \l{Qt Development: The Steps from Challenge to Achievement}{The Steps from Challenge to Achievement} - A case analysis of a business development problem and a search for -innovative solutions using Qt. + \o \l{Getting Started Guides}{Qt and Qt Quick Programming Tutorials} \endlist \enddiv \div {class="sectionlist normallist"} \div {class="heading"} UI Creation with Qt \enddiv - \image qml.png + \list \o \l{qt-ui-creation}{Create UI with Qt} \o \l{qt-rendering-painting-system}{Qt's Rendering and Painting Systems} \o \l{Qt Quick} - develop fluid UIs with QML \o \l{Widgets and Layouts} - elements for C++ interfaces + \o \l{external: Designer in Creator}{Designing UI in Creator} + \endlist + \enddiv + \div {class="sectionlist normallist"} + \div {class="heading"} + Featured Articles + \enddiv + \list + \o \l{Scalability}{How to Create Scalable Applications} + \o \l{external: Setting Up Development Environment for Symbian}{Setting Up Development Environment for Symbian} + \o \l{external: Setting Up Development Environment for Maemo}{Setting Up Development Environment for Maemo} + \o \l{qt-mobile-demos}{Mobile Applications and Demos} + \o \l{QtWebKit Guide}{QtWebKit Developer Guide} + \endlist + \list + \o \l{Qt Development: The Steps from Challenge to Achievement}{The Steps from Challenge to Achievement} + A case analysis of a business development problem and a search for +innovative solutions using Qt. \endlist \enddiv \enddiv @@ -137,17 +130,16 @@ innovative solutions using Qt. \o \l{All Modules}{All Modules} \o \l{All Namespaces}{All Namespaces} \o \l{Global Qt Declarations}{Global Declarations} - \endlist \enddiv \div {class="sectionlist normallist"} \list - \o \l{Qt Quick} \o \l{QML Elements} + \o \l{external: Qt Mobility Manual}{Qt Mobility APIs} + \o \l{external: Qt Mobility QML Plugins}{Mobility QML Plugins} \endlist \list - \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility APIs} - \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} + \o \l{Qt Licenses and Credits} \endlist \enddiv \div {class="sectionlist normallist"} @@ -155,8 +147,8 @@ innovative solutions using Qt. Qt Manuals \enddiv \list - \o \l{http://doc.qt.nokia.com/qtcreator-2.0/index.html}{Qt Creator} - \o \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator} + \o \l{external: Qt Creator Manual}{Qt Creator} + \o \l{external: Qt Simulator Manual}{Qt Simulator} \o \l{linguist-manual.html}{Qt Linguist} \o \l{assistant-manual.html}{Qt Assistant} \endlist diff --git a/doc/src/mainpage.qdoc b/doc/src/mainpage.qdoc index 269dc52..f7f0486 100644 --- a/doc/src/mainpage.qdoc +++ b/doc/src/mainpage.qdoc @@ -30,14 +30,14 @@ \title Develop with Qt \ingroup gettingstarted -\div {class="indexboxcont indexboxbar"} +\div {class = "indexboxcont indexboxbar"} Developing a Qt application involves many different steps and stages. From configuring Creator to distributing binaries to different platforms, Qt provides many options along the way. \image quick_screens.png \enddiv -\div {class="indexboxcont indexboxbar normallist"} +\div {class = "indexboxcont indexboxbar normallist"} \keyword qt-creator-configure-target \section1 Configuring Qt and Creator Targets Qt and Creator are configurable to compile applications on many platform targets @@ -48,15 +48,15 @@ Creator is the integrated development environment for developing Qt applications Creator encompasses every step of application development from interface design to application testing and deployment. \list -\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-project-managing.html}{Creating Qt Projects} -\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-building-running.html}{Building and Running Applications} +\o \l{external: Creating Qt Projects in Creator}{Creating Qt Projects} +\o \l{external: Building and Running Applications in Creator}{Building and Running Applications} \list - \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-running-targets.html}{Targets} - edit and set compiler targets - \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-build-settings.html}{Build Settings} - edit and set build configurations - \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-run-settings.html}{Run Settings} - edit and set application run settings + \o \l{external: Set Compiler Targets in Creator}{Targets} - edit and set compiler targets + \o \l{external: Build Settings in Creator}{Build Settings} - edit and set build configurations + \o \l{external: Run Settings in Creator}{Run Settings} - edit and set application run settings \endlist -\o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-symbian.html}{Setting Up Development Environment for Symbian} -\o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-maemo.html}{Setting Up Development Environment for Maemo} +\o \l{external: Setting Up Development Environment for Symbian}{Setting Up Development Environment for Symbian} +\o \l{external: Setting Up Development Environment for Maemo}{Setting Up Development Environment for Maemo} \endlist \keyword qt-platform-support @@ -77,7 +77,7 @@ and their installation pages, view the \l {Supported Platforms} and the \l {Cross-Platform and Platform-Specific Development} pages. \enddiv -\div {class="indexboxcont indexboxbar normallist"} +\div {class = "indexboxcont indexboxbar normallist"} \keyword qt-technologies \section1 Qt Technologies @@ -109,11 +109,11 @@ applications using layouts and Qt Quick interfaces with QML. \list \o \l{Qt Quick} - create UIs using QML \list - \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-visual-editor.html}{Creator's QML Design Mode} - design Qt Quick interfaces using Creator's design mode + \o \l{external: Developing Qt Quick Applications}{Creator's QML Design Mode} - design Qt Quick interfaces using Creator's design mode \endlist \o \l{Widgets and Layouts} - primary elements for C++ based interfaces \list - \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-using-qt-designer.html}{Creator's Designer} - design interfaces using Qt Designer. + \o \l{external: Designer in Creator}{Creator's Designer} - design interfaces using Qt Designer \endlist \o \l{UI Design with Qt} - covers many Qt features for UI creation \endlist @@ -141,13 +141,13 @@ Qt has various support for different rendering and painting methods. \o \l{QtOpenGL Module} - module for rendering with the OpenGL API \o \l{OpenVG Rendering in Qt}{QtOpenVG Module} - provides support for OpenVG painting \endlist -\o \l{Printing with Qt} - A guide to producing printed output with Qt's paint system and widgets. +\o \l{Printing with Qt} - A guide to producing printed output with Qt's paint system and widgets \endlist \keyword qt-webkit \section2 QtWebKit Module Web applications are increasing in importance and abundance and Qt has -\l{http://www.webkit.org/}{WebKit} support. +\l{WebKit Open Source Project}{WebKit} support. \list \o \l{WebKit in Qt} - WebKit Module \endlist @@ -159,25 +159,26 @@ Qt supports many utilities that work on multiple platforms. \o \l{Container Classes}{Containers} - Qt's implementation of various data structures such as linked lists and hash maps \o \l{Rich Text Processing} - for manipulating structured rich text documents \o \l{XML Processing} - high level manipulation of XML data using different interfaces -\o \l{Making Applications Scriptable} - provides Qt applications with ECMAScript processor. -\o \l{Qt Linguist Manual}{Qt Linguist} - for translating applications into local languages. +\o \l{Making Applications Scriptable} - provides Qt applications with ECMAScript processor +\o \l{Qt Linguist Manual}{Qt Linguist} - for translating applications into local languages \endlist -For more information, visit the \l{Qt's Tools}{Qt Tools} page. +For more information, visit the \l{Qt's Tools}{Qt Tools}Â page. \enddiv -\div {class="indexboxcont indexboxbar normallist"} +\div {class = "indexboxcont indexboxbar normallist"} \keyword qt-testing \section1 Testing Qt Applications Testing and debugging are part of the development process and Qt offers the developer multiple methods of testing their code. \list -\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-debugging.html} {Debugging Applications in Creator} - various debugging options in Creator -\o \l {http://doc.qt.nokia.com/qtsimulator/index.html}{Simulator} - testing mobile applications by simulating a mobile environment -\o \l {QML Viewer} - an executable that is able to run QML files +\o \l{external: Debugging Applications in Creator}{Debugging Applications in Creator} - various debugging options in Creator +\o \l{Debugging Techniques} - essential techniques for debugging Qt code +\o \l{external: Qt Simulator Manual}{Simulator} - testing mobile applications by simulating a mobile environment +\o \l{QML Viewer} - an executable that is able to run QML files \o \l{QTestLib Manual}{QTestLib} - a unit testing framework built into Qt \endlist \enddiv -\div {class="indexboxcont indexboxbar normallist"} +\div {class = "indexboxcont indexboxbar normallist"} \keyword qt-deployment \section1 Deployment Symbian phones, Maemo devices, desktop environments, embedded Linux devices -- Qt applications are deployable to many environments. @@ -194,20 +195,20 @@ considerations that each platform introduce. \o \l{Deploying Qt for Embedded Linux Applications}{Embedded Linux} - deploying Qt applications on embedded Linux \o \l{Deploying an Application on the Symbian Platform}{Symbian} - deploying Qt applications on the Symbian platform \endlist -\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-deployment-symbian.html}{Symbian Deployment in Creator} - Symbian application deployment built into Creator -\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-deployment-maemo.html}{ Deploying Qt Applications on Maemo Devices} +\o \l{external: Symbian Deployment in Creator}{Symbian Deployment in Creator} - Symbian application deployment built into Creator +\o \l{external: Maemo Deployment in Creator}{Deploying Qt Applications on Maemo Devices} \endlist \section1 Ovi Store Publishing Creator can publish applications to Ovi Store directly. \list -\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-publish-ovi.html}{Publishing Qt Applications to Ovi Store} +\o \l{external: Publishing Applications to Ovi Store}{Publishing Qt Applications to Ovi Store} \endlist For additional information, visit the \l{Cross-Platform and Platform-Specific Development} and the \l {Supported Platforms} page. \enddiv -\div {class="indexboxcont indexboxbar normallist"} +\div {class = "indexboxcont indexboxbar normallist"} \section1 Where to Go from Here Qt Demos and Examples diff --git a/doc/src/qt-webpages.qdoc b/doc/src/qt-webpages.qdoc index e915267..9097a38 100644 --- a/doc/src/qt-webpages.qdoc +++ b/doc/src/qt-webpages.qdoc @@ -24,243 +24,297 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! \externalpage http://qt.nokia.com/ \title Qt website */ - /*! \externalpage http://qt.nokia.com/ \title Qt Homepage */ - /*! \externalpage http://bugreports.qt.nokia.com \title Qt Bug Tracker */ - /*! \externalpage http://bugreports.qt.nokia.com \title Bug Report Form */ - /*! \externalpage http://qt.nokia.com/services-partners/partners/partner-directory \title Partner Directory */ - /*! \externalpage http://qt.nokia.com/products/add-on-products \title Qt Solutions */ - /*! \externalpage http://qt.nokia.com/developer/books \title Books about Qt Programming */ - /*! \externalpage http://qt.nokia.com/developer/books/3 \title GUI Programming with Qt 3 */ - /*! \externalpage http://qt.nokia.com/about \title About Qt */ - /*! \externalpage http://qt.nokia.com/products/developer-tools \title Visual Studio Integration */ - /*! \externalpage http://qt.nokia.com/products/add-on-products/catalog/4/Widgets/qtcalendarwidget/ \title Calendar Widget */ - /*! \externalpage http://qt.nokia.com/products/add-on-products/catalog/4/Widgets/qtwizard/ \title QtWizard */ - /*! \externalpage http://qt.nokia.com/products/add-on-products/catalog/4/Utilities/qtcorba/ \title CORBA Framework */ - /*! \externalpage http://qt.nokia.com/products/add-on-products/catalog/4/Widgets/qtwindowlistmenu/ \title Window Menu */ - /*! \externalpage http://qt.nokia.com/qt-in-use \title Customer Success Stories */ - /*! \externalpage http://qt.nokia.com/developer \title Developer Zone */ - /*! \externalpage http://qt.nokia.com/downloads \title Downloads */ - /*! \externalpage http://qt.nokia.com/developer/faqs/ \title FAQs */ - /*! \externalpage http://qt.nokia.com/developer/faqs/licensing/ \title License FAQ */ - /*! \externalpage http://qt.nokia.com/products/licensing/ \title Free Software and Contributions */ - /*! \externalpage http://qt.nokia.com/products/licensing/ \title Qt Licensing Overview */ - /*! \externalpage http://qt.nokia.com/products/pricing/ \title Qt License Pricing */ - /*! \externalpage http://qt.nokia.com/about/contact-us \title How to Order */ - /*! \externalpage http://doc.qt.nokia.com/supported-platforms.html \title Platform Support Policy */ - /*! \externalpage http://qt.nokia.com/products/ \title Product Overview */ - /*! \externalpage http://doc.qt.nokia.com/supported-platforms.html \title Qt 4 Platforms Overview */ - /*! \externalpage http://www.qtextended.org/ \title Qt Extended */ - /*! \externalpage http://doc.qt.nokia.com/qq/ \title Qt Quarterly */ - /*! \externalpage http://bugreports.qt.nokia.com \title Task Tracker */ - /*! \externalpage http://lists.trolltech.com \title Qt Mailing Lists */ - /*! \externalpage http://qt.nokia.com/products/files/pdf/ \title Whitepapers */ - /*! \externalpage http://doc.qt.nokia.com/qtcanvas \title QtCanvas */ - /*! \externalpage http://labs.qt.nokia.com/page/Projects/Itemview/Modeltest \title ModelTest */ - /*! \externalpage http://labs.qt.nokia.com/page/Projects/Accessibility/QDBusBridge \title D-Bus Accessibility Bridge */ - /*! \externalpage http://labs.qt.nokia.com/blogs/2008/12/05/qtestlib-now-with-nice-graphs-pointing-upwards/ \title qtestlib-tools Announcement */ - /*! \externalpage http://qt.nokia.com/products/library/modular-class-library#info_scripting \title Qt Script for Applications (QSA) */ - /*! \externalpage http://qt.nokia.com/products/add-on-products/catalog/4/Utilities/qtsharedmemory/ \title QtSharedMemory */ - /*! \externalpage http://qt.nokia.com/qq/qq21-portingcanvas.html \title Porting to Qt 4.2's Graphics View */ - /*! \externalpage http://qt.nokia.com/products/add-on-products/catalog/4/Windows/qtwinforms/ \title QtWinForms Solution */ - /*! \externalpage http://qt.nokia.com/developer/faqs/qt/installation \title Installation FAQ */ - /*! \externalpage http://qt.gitorious.org \title Public Qt Repository */ - /*! \externalpage http://get.qt.nokia.com/nokiasmartinstaller/ \title Smart Installer */ - /*! \externalpage http://qt.gitorious.org/qt-labs/qtestlib-tools \title qtestlib-tools */ - /*! \externalpage http://labs.qt.nokia.com \title Qt Labs */ /*! - \externalpage http://doc.qt.nokia.com/qtcreator-snapshot/index.html - \title Qt Creator Manual -*/ - -/*! - \externalpage http://doc.qt.nokia.com/qtcreator-snapshot/creator-qml-application.html - \title Developing Qt Quick Applications with Creator + \externalpage http://doc.qt.nokia.com/qtcreator/creator-qml-application.html + \title external: Developing Qt Quick Applications with Creator */ - /*! \externalpage http://qt.gitorious.org/qt/pages/QtCodingStyle \title Qt Coding Style */ - +/*! + \externalpage http://developer.qt.nokia.com/wiki/QtCreatorWhitepaper + \title Qt Creator Whitepaper +*/ +/*! + \externalpage http://developer.qt.nokia.com/wiki/QtWhitepaper + \title Qt Whitepaper +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-visual-editor.html + \title external: Developing Qt Quick Applications +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-publish-ovi.html + \title external: Publishing Applications to Ovi Store +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/index.html + \title external: Qt Creator Manual +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-developing-symbian.html + \title external: Setting Up Development Environment for Symbian +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-developing-maemo.html + \title external: Setting Up Development Environment for Maemo +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtmobility/index.html + \title external: Qt Mobility Manual +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtmobility/qml-plugins.html + \title external: Qt Mobility QML Plugins +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtsimulator/index.html + \title external: Qt Simulator Manual +*/ +/*! + \externalpage http://doc.qt.nokia.com/nokia-qtsdk-latest/index.html + \title external: Qt SDK Manual +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-project-managing.html + \title external: Creating Qt Projects in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-building-running.html + \title external: Building and Running Applications in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-running-targets.html + \title external: Set Compiler Targets in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-build-settings.html + \title external: Build Settings in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-run-settings.html + \title external: Run Settings in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-using-qt-designer.html + \title external: Designer in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-debugging.html + \title external: Debugging Applications in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-deployment-symbian.html + \title external: Symbian Deployment in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtcreator/creator-deployment-maemo.html + \title external: Maemo Deployment in Creator +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtmobility/multimedia.html + \title external: Mobility Multimedia +*/ +/*! + \externalpage http://doc.qt.nokia.com/qtmobility/location-overview.html + \title external: Mobility Location +*/ /*! \externalpage http://qt.nokia.com/developer/learning/online/training/training-day-at-developer-days-2009/ \title Training Day at Qt Developer Days 2009 */ +/*! + \externalpage http://doc.qt.nokia.com/qtmobility/all-examples.html + \title external: Qt Mobility Examples +*/ +/*! + \externalpage http://qt.nokia.com/developer/learning/online/training + \title Qt eLearning +*/ +/*! + \externalpage http://qt.nokia.com/developer/learning/online/training + \title Qt eLearning Training Materials +*/ +/*! + \externalpage http://qt.nokia.com/developer/learning/online/talks/developerdays2010 + \title Qt Developer Days 2010 +*/ + diff --git a/doc/src/snippets/accessibilityfactorysnippet.cpp b/doc/src/snippets/accessibilityfactorysnippet.cpp index a378db7..6dc6b2a 100644 --- a/doc/src/snippets/accessibilityfactorysnippet.cpp +++ b/doc/src/snippets/accessibilityfactorysnippet.cpp @@ -45,9 +45,8 @@ QAccessibleInterface *sliderFactory(const QString &classname, QObject *object) { QAccessibleInterface *interface = 0; - if (classname == "QSlider" && object && object->isWidgetType()) - interface = new SliderInterface(classname, - static_cast<QWidget *>(object)); + if (classname == QLatin1String("QSlider") && object && object->isWidgetType()) + interface = new QAccessibleSlider(static_cast<QWidget *>(object)); return interface; } diff --git a/doc/src/snippets/accessibilitypluginsnippet.cpp b/doc/src/snippets/accessibilitypluginsnippet.cpp index a7e25f0..5c28468 100644 --- a/doc/src/snippets/accessibilitypluginsnippet.cpp +++ b/doc/src/snippets/accessibilitypluginsnippet.cpp @@ -52,7 +52,7 @@ public: //! [0] QStringList SliderPlugin::keys() const { - return QStringList() << "QSlider"; + return QStringList() << QLatin1String("QSlider"); } //! [0] @@ -61,8 +61,8 @@ QAccessibleInterface *SliderPlugin::create(const QString &classname, QObject *ob { QAccessibleInterface *interface = 0; - if (classname == "QSlider" && object && object->isWidgetType()) - interface = new AccessibleSlider(classname, static_cast<QWidget *>(object)); + if (classname == QLatin1String("QSlider") && object && object->isWidgetType()) + interface = new QAccessibleSlider(static_cast<QWidget *>(object)); return interface; } diff --git a/doc/src/tutorials/threads.qdoc b/doc/src/tutorials/threads.qdoc index 1d807a0..2d6a540 100644 --- a/doc/src/tutorials/threads.qdoc +++ b/doc/src/tutorials/threads.qdoc @@ -33,7 +33,7 @@ \title Threading Basics \brief An introduction to threads - \section1 What Are Threads + \section1 What Are Threads? Threads are about doing things in parallel, just like processes. So how do threads differ from processes? While you are making calculations on a diff --git a/doc/src/webkit/guide/chapter_cache.qdoc b/doc/src/webkit/guide/chapter_cache.qdoc new file mode 100644 index 0000000..fcfd208 --- /dev/null +++ b/doc/src/webkit/guide/chapter_cache.qdoc @@ -0,0 +1,511 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the Qt WebKit module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + +\page qtwebkit-guide-cache.html +\title QtWebKit Guide - Client Storage +\chapter Client Storage + +This section of the \l{QtWebKit Guide} serves as an introduction to the +\l{HTML5 Web Storage} features of QtWebKit. + +Traditional mobile web development centered around the limitations of client +handsets, which had very little storage for applications. As handsets become +more powerful, however, this assumption is no longer valid. HTML5's newly +introduced \l{HTML5 Web Storage}{Web Storage} features expand application +storage on the client. + +HTML 5 standardizes access to an application's local data via \c{LocalStorage} +and \c{SessionStorage} APIs. These APIs boost the amount of client storage +available to web applications. They also can effectively replace cookies as a +means to maintain application state and track user preferences. + +Local storage persists indefinitely, while session storage lasts only for the +duration of a window session. Local storage is available from any page or window +from the same site, while session storage is local to each window. Both local +and session storage rely on simple key/value pairs, with keys and values both +stored as strings. + +Local and session storage are not the only client storage available. HTML 5 +WebSQL serves as a more full-featured, client-side database. WebSQL brings +SQLite-based structured database functionality, typically deployed on servers, +to client browser applications. WebSQL is appropriate for data-intensive +applications requiring complex queries rather than simple key/value access. +WebSQL database transaction calls help avoid interfaces from locking up, +facilitate rollback and error handling, and protect against SQL injection. +Database versioning allows you to manage schema changes incrementally. + + +\section1 Simple Data Storage + +The \c{localStorage} and \c{sessionStorage} APIs offer applications up to 5MB of +data storage. They both share the same simple key/value interface, but have +different namespaces and also differ in the extent to which data is available. +Local storage persists indefinitely, while session storage only lasts for the +duration of a window session. Local storage is available from any page or window +from the same site, while session storage is local to each window. + +The following examples demonstrate the API interface. While these use +\c{localStorage} as an example, the same set of API calls work for +\c{sessionStorage}, which is also available within the \c{window} object. + +The following performs an initial check for support of browser-based +storage and assigns the database to a variable: + +\code +if (window.localStorage) { + var db = window.localStorage; + // storage functionality here +} +else { + // store data remotely? +} +\endcode + +The \c{getItem()} method retrieves the value of a database field named +\c{key}: + +\code +var value = db.getItem("key"); +\endcode + +Note that both keys and values are represented as strings. If you specify any +other type of data, it is converted silently to a string representation. (See +\l{Storing Non-String Data} for ways around this limitation.) If \c{getItem()} +returns \c{null} rather than a string value, it means the specified key does not +exist. + +The \c{setItem()} method establishes a new value. When adding data, it is a good +idea to check to make sure you haven't exceeded the allotted storage space: + +\code +try { + db.setItem("key", "string"); +} +catch(err) { + if (err.QUOTA_EXCEEDED_ERR) { + // storage space is exceeded + } +} +\endcode + +The \c{removeItem()} method deletes database fields: + +\code +db.removeItem("key"); +\endcode + +The \c{clear()} method deletes all key/value pairs within the database, either +for an entire site in the case of \c{localStorage}, or for an individual window +session in the case of \c{sessionStorage}: + +\code +db.clear(); +\endcode + +Databases can be accessed as arrays using index notation, useful in cases where +you may not know all the field names. The \c{length} property returns the number +of fields in the database, and the \c{key()} method returns the name of the key +corresponding to a given index. The following reflects the contents of a +database in a JavaScript object: + +\code +var obj = {}; +for ( var i = 0, l = db.length ; i < l ; i++ ) { + obj[ db.key(i) ] = db.getItem( db.key(i) ); +} +\endcode + +Since keys correspond to array indexes, you should not add or remove keys during +any operation that iterates over the full set of key/value pairs. Newly +introduced keys are introduced randomly into the array's sequence. + +The following displays simple storage functionality. The application prompts for +a login and password if they are unavailable. This locally stored data is +available the next time users open the browser. However, the contents of the +credit card field is stored only for the duration of the browing session. + +\l{ex_storage}{\inlineimage webkit-guide/scr_storage.png +} + +\l{storage_css}{(CSS)} +\l{storage_js}{(JavaScript)} + + + \section2 Storing Non-String Data + + Since local and session storage APIs only support string values, you need to + be careful not to allow errors that result from passive conversions from + other data types. The following sample shows how such an error might come + about: + + \code + var db = window.localStorage; + var saveCardInfo; + // user expresses preference NOT to save credit card info: + saveCardInfo = false; + // BUG happens here... + db.setItem("save_card_info", saveCardInfo); + // variable is now a string, not a boolean: + saveCardInfo = db.getItem("save_card_info"); + // both "true" and "false" strings evaluate as true... + if ( saveCardInfo ) { + // ...so this code always executes... + } + else { + // ...and this code never executes. + } + \endcode + + The user's preference to retain credit card information is expressed within + the application as a \c{true} or \c{false} boolean value. When each value is + passed to storage, however, it is passively converted to a string. When + reassigned to a JavaScript variable, it no longer serves as a valid boolean + test. The application falsely assumes users want to save credit card + information, regardless of their expressed preference. + + The following sample fixes the problem. Instead of using \c{true} and + \c{false} boolean values, it converts \c{1} and \c{0} strings to numbers: + + \code + var db = window.localStorage; + var saveCardInfo = 0; + db.setItem("save_card_info", saveCardInfo); + // multiplying forces numeric output: + saveCardInfo = db.getItem("save_card_info") * 1; + \endcode + + For a more reliable alternative, store values as JSON strings and rely on + automatic type conversion when subsequently parsing them. The following + sample shows how parsing JSON preserves both boolean and numeric data: + + \code + var saveCardInfo = true; // boolean + var shipMethod = 2; // number + var db = window.localStorage; + + db.setItem("save_card_info", JSON.stringify(saveCardInfo)); + db.setItem("ship_method", JSON.stringify(shipMethod)); + + saveCardInfo = JSON.parse(db.getItem("save_card_info")); // boolean + shipMethod = JSON.parse(db.getItem("ship_method")); // number + \endcode + + Note that this simple approach may cause problems of its own. For example, + perhaps the words \c{true} and \c{false} really should be represented + as strings. Encapsulating data within objects accounts for such variability: + + \code + var db = window.localStorage; + var obj = { + bool : true, + str : "true", + num : 1 + }; + db.setItem("appState", JSON.stringify(obj)); // to database... + // "appState" is "{'bool':true,'num':1,'str':'true'}" + obj = JSON.parse(db.getItem("appState")); // ...and back + // obj is same as initially defined. + \endcode + + The ability to save objects as JSON strings means that you can save an + application's state within a single database field. For example, you might + use the following approach to save the entire contents of a shopping cart in + a single field for later use: + + \code + var db = window.localStorage; + var cart = { items: [] }; + + cart.message = "From your loving uncle"; + + cart.items.push({ + description : "Floor to Ceiling Shoe Rack", + id : 203174676, + price : 99.95, + quantity : 1, + weight : 20, + }); + + cart.items.push({ + description : "Automatic Laser Toy for Cats", + id : 203345371, + price : 19.95, + quantity : 2, + weight : 0.5, + }); + + // save all cumulative items: + db.setItem("cart", JSON.stringify(cart)); + + // extract items from storage: + cart = JSON.parse(db.getItem("cart")); + \endcode + + JSON allows you to store data types, but functions are ignored. That makes + it more difficult to preserve objects representing fully functional + applications. + + \section2 Storage Events + + The \c{storage} event allows applications to respond indirectly to modified + data resulting from calls to \c{setItem()}, \c{removeItem()}, or + \c{clear()}. This may be useful in providing users with visual feedback + notifying them of data that is modified locally, perhaps rather than being + sent to a remote server: + + \code + window.addEventListener("storage", function(event){ + var icon = document.querySelector("#indicator"); + if (event.storageArea.length) { + icon.className = "writing"; + } + else { + icon.className = "empty"; + } + }, false); + \endcode + + The \c{storage} event's \c{storageArea} attribute returns the + \c{localStorage} or \c{sessionStorage} object being modified. The \c{key} is + the name of the field being modified, and \c{oldValue} and \c{newValue} are + its values before and after the event. The \c{url} is the page that called + the method triggering the change. + + +\section1 WebSQL Databases + +While common local- or session-based databases are capable of storing complex +data structures, QtWebKit-based browsers can also rely upon the WebSQL standard, +which brings SQLite-based structured database functionality, typically deployed +on servers, to client browser applications. Based on SQLite version 3.6.19, +WebSQL is appropriate for data-intensive applications requring complex queries +rather than simple key/value access. + +The following test confirms support for WebSQL: + +\code +if (!!window.openDatabase) { + // supports WebSQL +} +\endcode + +Calls to databases made via the WebSQL API are made asynchronously via +transactions to avoid the user interface from locking up, as database +interaction may occur from several windows at a time. + +The three core API methods are: + +\list +\o \c{openDatabase()} +\o \c{transaction()} +\o \c{executeSql()} +\endlist + + \section2 Creating and Opening a New Database + + To create and open a database, use \c{openDatabase()}on the Window object, + for example: + + \code + var db = openDatabase('mydb', '1.0', 'my first database', 2*1024*1024); + var db = openDatabase('notes', '', 'The Example Notes App!', 1048576); + \endcode + + The four required arguments are the database name, version, display name, + and estimated size in bytes. You can supply a function as an optional fifth + argument to serve as a callback when a database is created. It may be used + to call the \c{changeversion()} method, in which case the callback is + invoked with an empty string for the database version. + + The second example above specifies an empty string for the version. In this + case, the database opens no matter what the database version is. (An + \c{openDatabase()} call specifying the wrong version for an existing + database throws an \c{INVALID_STATE_ERR} exception.) You can then query the + version by examining the database object's version property, for example: + + \code + var version = db.version; + \endcode + + Note that you don't need to close a client-side Web SQL database when + you're done working with it. + + \section2 Transaction Calls and ExecuteSQL Method + + Performing database transactions is superior to running SQL statements + directly because transactions are not committed if they fail and you can + undo them if needed. Transactions also allow you to handle errors using a + callback. To implement a transaction, specify a callback function such as + the following: + + \code + db.transaction(function (tx) { + // SQL details on the tx object go here + } + \endcode + + The \c{transaction()} method takes one to three arguments: + + \list + \o a required transaction callback, in which \c{executeSQL()} calls + belong + \o an optional transaction error object + \o an optional success callback. + \endlist + + Use the \c{executeSQL()} method to specify SQL statements for read and write + operations. The method protects against SQL injection and provides a + callback method to process the results of any SQL queries you specify. The + \c{executeSQL()} method takes from one to four arguments: + + \list + \o a required SQL statement + \o an optional object array of arguments + \o an optional SQL statement callback + \o an optional SQL statement error callback + \endlist + + The example below creates the database if it doesn't exist, adds a + two-column table to the database, and adds a row of data to the table: + + \code + var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024); + db.transaction(function (tx) { + tx.executeSql('CREATE TABLE IF NOT EXISTS foo (id unique, text)'); + tx.executeSql('INSERT INTO foo (id, text) VALUES (1, "synergies")'); + }); + \endcode + + To capture data from the user or an external source, use \c{?} placeholders + to map that data into the SQL query. This ensures the data doesn't + compromise database security, for example from SQL injection: + + \code + tx.executeSql('INSERT INTO foo (id, text) VALUES (?, ?)', [id, value]); + \endcode + + \c{id} and \c{value} are external variables, and \c{executeSql} maps + the items in the array to the \c{?}s. + + To select values from the table, use a callback to capture the results: + + \code + tx.executeSql('SELECT * FROM foo', [], function(tx, results) { + for (var i = 0 , len = results.rows.length; i < len; i++) { + // do something with results.rows.item(i).text + } + }); + \endcode + + No fields are mapped in the above query, but to use the third argument you + need to pass in an empty array as the second argument. + + The SQL statement callback for \c{executeSQL()} is called with the + \c{transaction} object and a SQL statement \c{result} object. The \c{result} + gives access to the ID of the last inserted row, the number of rows + affected, and an indexed list representing the rows returned, in the order + returned. + + The \c{result} object contains an array-like \c{rows} object. It has a + length, but to access individual rows you need to use + \c{results.rows.item(i)}, where \c{i} is the index of the row. This returns + an object representation of each row. For example, if your database has a + \c{name} and an \c{age} field, the \c{row} contains a \c{name} and an + \c{age} property. The value of the \c{age} field can be accessed using + \c{results.rows.item(i).age}. + + \section2 Changing Database Versions + + Each database has one version at a time and multiple versions cannot exist + at one time. Versions allow you to manage schema changes incrementally. + + You can change the version of a client-side Web SQL database using the + \c{changeversion()} method: + + \code + if (db.version == "1.0") { + try { + // comment out for crash recovery. + db.changeVersion("1.0", "2.0", cv_1_0_2_0, oops_1_0_2_0, success_1_0_2_0); + } catch(e) { + alert('changeversion 1.0 -> 2.0 failed'); + alert('DB Version: '+db.version); + } + } + \endcode + + \c{changeversion()} takes the following arguments: required old and new + version numbers, optional SQL transaction callback, optional SQL transaction + error callback, and optional success callback. + + \section2 Errors + + Asynchronous API errors are reported using callbacks that have a + \c{SQLError} object as one of their arguments. \c{SQLError} contains a code + from the table below and a localized message string. + + Error codes are: + + \list + \o 0 \c{UNKNOWN_ERROR} Transaction failed for reasons unrelated to the DB + \o 1 \c{DATABASE_ERROR} Statement failed for DB reasons not covered by other + code + \o 2 \c{VERSION_ERROR} DB version doesn't match expected version + \o 3 \c{TOO_LARGE_ERROR} Data returned from DB was too large. Try the + \c{SQL LIMIT} modifier. + \o 4 \c{QUOTA_ERROR} Insufficient remaining storage + \o 5 \c{SYNTAX_ERROR} Syntax error, argument mismatch, or unallowed + statement + \o 6 \c{CONSTRAINT_ERROR} An \c{INSERT}, \c{UPDATE}, or \c{REPLACE} + statement failed due to a constraint error + \o 7 \c{TIMEOUT_ERROR} Timeout waiting for transaction lock + \endlist + + \bold{See Also:} + \l{HTML5 Doctor: Introducing Web SQL Databases} + +\list +\o \l{QtWebKit Guide} -back to the main page +\endlist +*/ + +*/ diff --git a/doc/src/webkit/guide/chapter_canvas.qdoc b/doc/src/webkit/guide/chapter_canvas.qdoc new file mode 100644 index 0000000..eea2236 --- /dev/null +++ b/doc/src/webkit/guide/chapter_canvas.qdoc @@ -0,0 +1,1016 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the Qt WebKit module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + +\page qtwebkit-guide-canvas.html +\title QtWebKit Guide - Canvas Graphics + +\chapter Canvas Graphics +This section of the \l{QtWebKit Guide} serves as an introduction to the +\l{HTML5 Canvas API} features of QtWebKit. + +The \l{HTML5 Canvas API} enables you to draw within a Web page or Web App using +JavaScript. After you define a rectangle that serves as your drawing canvas, you +can draw straight and curved lines, simple and complex shapes, graphs, and +referenced graphic images. You can add text, color, shadows, gradients, and +patterns. The canvas API also enables you to save or export the canvas as a .png +or .jpeg image file. + +To define the drawing area, set the \c{width} and \c{height} of a \c{<canvas>} +element. For example, the following sets a drawing area with a height of 100 +pixels and width of 200 pixels: + +\code +<canvas id="mycanvas" width="100" height="200"></canvas> +\endcode + +By default, \c{canvas} elements are sized 150 pixels high and 300 pixels wide. +You can also set the size of the canvas using CSS: + +\code +canvas { height : 200px; width : 100px; } +\endcode + +The \c{canvas} element is transparent and has no visible borders until you +\l{Accessing the Rendering Context}{access the 2D rendering context}. + +Resetting the width or height of an existing canvas erases its contents and +resets all the context properties of the canvas to their default values. + +\section1 Accessing the Rendering Context + +The rendering \bold{context} defines the methods and attributes needed to draw +on the canvas. QtWebKit currently supports the two-dimensional rendering +context. The following assigns the canvas rendering context to a \c{context} +variable: + +\code +var context = canvas.getContext("2d") +\endcode + +The 2d context renders the canvas as a coordinate system whose origin (0,0) is +at the top left corner, as shown in the figure below. Coordinates increase along +the \c{x} axis from left to right and along the \c{y} axis from top to bottom of +the canvas. + +\image webkit-guide/canvas_context.gif + +\section1 Drawing Shapes + +The 2D rendering context supports rectangles, lines, and arcs, which +you can combine to build complex shapes and graphic images. + + \section2 Drawing Rectangles + + The rectangle is the only geometric shape that is built in to the + canvas API. You can draw an outline of a rectangle, a filled + rectangle, and a filled rectangle with clear parts. You do not have to + create a path to draw a rectangle. + + To draw an outline of a rectangle, use the \c{strokeRect()} method. + + To draw a filled rectangle, use the \c{fillRect()} method. The default + fill color is black. + + To clear part of a filled rectangle, use the \c{clearRect()} method. + + Each method accepts the following series of arguments: + + \list + \o \c{x} is the position on the canvas to the right of the origin + (0,0) of the top left corner of the rectangle + \o \c{y} is the position on the canvas below the origin of the top + left corner of the rectangle + \o \c{width} is the width of the rectangle to be drawn + \o \c{height} is the height of the rectangle to be drawn + \endlist + + For example, the following code draws concentric rectangles: + + \code + var context = canvas.getContext("2d"); + canvas.strokeRect(50,50,50,50); + canvas.fillRect(60,60,30,30); + canvas.clearRect(70,70,10,10); + \endcode + + \image webkit-guide/canvas_rectangles.gif + + \section2 Drawing Lines + + To draw a line, you first have to \e{"put your pencil down"} on the canvas + by creating a path. The \c{context.beginPath()} method sets a new path + in the canvas. Each line that you draw is stored as a sub-path. + Sub-paths can be closed to form a shape, or they can be left open. + Each time you want to draw a new shape, you have to call the + \c{beginPath()} method to reset the current path. + + After calling \c{beginPath()}, you set your starting position on the + canvas by calling the \c{context.moveTo(x,y)} method. The + \c{moveTo(x,y)} method creates a new subpath on the canvas that begins + at the Cartesian point \c{(x,y)}. + + To draw a straight line, call the \c{context.lineTo(x,y)} method. This + adds the point (x,y) to the current subpath and connects it to the + previous subpath by a straight line. In other words, (x,y) are the + coordinates of the line's endpoint. For example: + + \code + context.beginPath(); + context.moveTo(10,10); + context.lineTo(30,30); + \endcode + + To get the \e{pencil} to actually draw on the canvas, first use the + \c{strokeStyle} property to set the color to a value such as black + (\c{#000}): + + \code + context.strokeStyle(#000); + \endcode + + (The \c{strokeStyle} property can be a CSS color, a pattern, or a gradient.) + Then use the \c{context.stroke()} method to actually draw the line on the + canvas: + + \code + context.stroke(); + \endcode + + This produces the image below. The numeric coordinates are added for clarity + but are not part of the image drawn by the code: + + \image webkit-guide/canvas_lineStrokeTo.gif + + To create a shape, call the \c{context.closePath()} method: + + \code + context.closePath(); + context.moveTo(10,10); // starting point + context.lineTo(30,30); // specify first line + context.moveTo(30,30); // move to end of first line + context.lineTo(60,10); // specify second line + context.moveTo(60,10); // move to end of second line + context.lineTo(10,10); // specify third line to close triangle + context.strokeStyle("#000"); // use black color for lines + context.stroke(); // draws the triangle lines on the canvas + \endcode + + To fill the shape, use the \c{fillstyle} property and the \c{fill()} + method: + + \code + context.fillStyle("#FF0000"); // use red color for fill + context.fill(); // fill the triangle + \endcode + + The commands, if coded fully, would create the shape below: + + \image webkit-guide/canvas_closepath.gif + + \note It is not necessary to close the path when calling the \c{fill()} + method. Calling \c{fill()} closes the path and creates the completed shape. + + You can draw lines of various widths, endcap types, and joining options by + configuring the following attributes: + + \list + \o \c{lineWidth} sets the thickness of the current line. The value can be + any number greater than \c 0. For example, \c{context.lineWidth = 10} sets + the line thickness to \c 10 units. The default value is \c 1 unit, which is + not the same as \c 1 \e pixel. Instead, the line is centered on the current + path, with half its thickness on each side of the path. + \o \c{lineCap} sets the type of endpoint of the current line. The value can + be either \c{butt}, \c{square}, or \c{round}. (The default value is + \c{butt}.) + \list + \o \c{butt}- the ends of the line abutt the line guide. + \o \c{square} adds a box at both ends of the line. + \o \c{round} adds a semicircle at both ends of the line. + \endlist + + \o \c{lineJoin} sets the style with which lines are joined. The value + can be either \c{bevel}, \c{round}, or \c{miter}. (The default value + is \c{miter}.) + \list + \o \c{bevel} flattens the corners at which the lines join + \o \c{round} rounds the corners at which the lines join + \o \c{miter} joins the lines at a single point + \endlist + \o \c{miterLimit} sets the \e{miter limit ratio}. The value can be any + number greater than \c 0. The miter limit ratio determines how far the + connection point of the outside of the lines can be from the connection + point of the inside of the lines. (The default value is \c 10.) + \endlist + + \image webkit-guide/canvas_linecap.png + + \section2 Drawing Arcs + + To draw an arc, you begin with the same steps your followed to create + a line: + + \list 1 + \o Call the \c{context.beginPath()} method to \e{"put your pencil down"} on + the canvas and set a new path. + \o Call the \c{context.moveTo(x,y)} method to set your starting position on + the canvas at the point (x,y). + \o To draw an arc or circle, call the \c{context.arcTo(x1,y1,x2,y2,radius)} + method. This adds an arc with starting point \c{(x1,y1)}, ending point + \c{(x2,y2)}, and radius \c{radius} to the current subpath and connects it to + the previous subpath by a straight line. + + \image webkit-guide/canvas_arcTo.png + + \o An alternative way to draw an arc or circle is to call the + \c{context.arc(x,y,radius,startAngle,endAngle,anticlockwise)} method. This + adds an arc to the current subpath that lies on the circumference of the + circle whose center is at the point (x,y) and whose radius is \c{radius}. + + \image webkit-guide/canvas_arcTo2.png + + Both \c{startAngle} and \c{endAngle} are measured from the x axis in units + of radians. + + A complete circle is \c 360 degrees, or 2\pi radians. A semicircle is \c 180 + degrees, or \pi radians. The number of radians is the number of degrees + multiplied by \pi/180, expressed in JavaScript as: + + \code + var radians = (Math.PI/180)*degrees; + \endcode + + \image webkit-guide/canvas_startAngle.png + + \c{anticlockwise} has the value \c{TRUE} for each arc in the figure + above because they are all drawn in the counterclockwise direction. + + \o To create a shape, call the \c{context.closePath()} method. This + marks the current subpath as closed and draws a straight line from the + current point to the first point in the path. + + \o To draw only the outline of the shape, call the \c{context.stroke()} + method. + + \o To fill in the shape, call the \c{context.fill()} method. + + \o To set the color of the fill, set the \c{strokeStyle}. For example, + the code + + \code + context.strokeStyle = "#FF0000"; + \endcode + + sets the fill color to red. + + \endlist + + \note It is not necessary to close the path if you are going to call + the \c{fill()} method. The fill closes the path and creates the completed + shape. + + To create complex shapes, combine lines and arcs: + + \list 1 + \o Call the \c{context.beginPath()} method to \e{"put your pencil down"} on + the canvas and set a new path. + \o Call the \c{context.moveTo(x,y)} method to set your starting position on + the canvas at the point (x,y). + \o Draw any combination of lines and arcs by calling the \c{lineTo}, + \c{arcTo}, \c{arc}, \c{moveTo}, \c{closePath}, \c{stroke}, and \c{fill} + methods and setting the line attributes and fill colors as described above. + \endlist + + You can also create complex shapes by removing portions of the shapes you + draw. The \c{clip()} method creates a clipping path that defines the area + along which your "scissor" will cut. Any parts of the shape outside the + clipping path are not displayed. To create a complex shape using the + \c{clip()} method: + + \list 1 + \o Call the \c{context.beginPath()} method to set the clipping path. + \o Define the clipping path by calling any combination of the \c{lineTo}, + \c{arcTo}, \c{arc}, \c{moveTo}, and \c{closePath} methods. + \o Call the \c{context.clip()} method. + \endlist + + The new shape displays. The following shows how a clipping path can + modify how an image displays: + + \image webkit-guide/canvas_clip-complex.png + +\section1 Compositing + +You can build complex shapes by drawing shapes on top of each other. It is also +possible to draw shapes behind existing shapes and to mask parts of shapes by +using \e{compositing operations}. The \c{globalCompositeOperation} attribute +sets the way shapes can be combined. + +The first shape drawn on the canvas to which additional shapes are added is +called the \e{destination} shape. The shape drawn on the canvas afterwards to +create the composite image is called the \e{source} shape. The value of the +\c{globalCompositeOperation} attribute must be set to one of the following: + +\list +\o \c{source-over} displays the source (newer) shape over the destination +(older) shape unless the source shape is transparent. (This is the default +value) + +\o \c{source-in} displays only the portion of the source shape that is opaque +and overlaps the destination shape. Everything else is transparent. + +\o \c{source-out} displays only the portion of the source shape that does not +overlap the destination shape. + +\o \c{source-atop} displays only the portion of the opaque source shape that +overlaps the destination shape and the portion of the destination shape that is +not covered by the opaque source shape. + +\o \c{destination-over} displays the destination shape over the source shape. In +areas where both shapes are opaque and overlap, the older shape displays. + +\o \c{destination-in} displays only the portion of the destination shape that is +opaque and overlaps the source shape. Everything else is transparent. The source +(newer) shape is not visible. + +\o \c{destination-out} displays only the portion of the destination shape that +does not overlap the source shape. The source shape is not visible. + +\o \c{destination-atop} displays only the portion of the opaque destination +shape that overlaps the source shape and the portion of the source shape that is +not covered by the opaque destination shape. + +\o \c{lighter} displays both the source and destination shapes. Where the shapes +overlap, the their color values are added, producing a lighter color. + +\o \c{copy} displays only the source shape. The destination shape is ignored. + +\o \c{xor} displays both the source and the destination shapes except the areas +of overlap, in which both shapes are completely transparent. +\endlist + +The following figure shows the various compositing effects: +\image webkit-guide/canvas_composite.png + +\section1 Saving and Exporting Canvas Drawings as Image Files + +You can save or export your canvas drawings as .png or .jpeg image files by +calling the \c{toDataURL()} method: + +\code +canvas.toDataURL([type, ...]) +\endcode +where: +\list +\o \c{type} is the MIME type to which you want to save or export your canvas. +Possible values are: + \list + \o \c{"image\png"} (Default value) + \o \c{"image\jpeg"} + \endlist +\o\c{...} represents additional arguments that depend on the MIME type. + \list + \o If \c{type} is \c{png}, this argument is \c{" "} + \o If \c{type} is \c{jpeg}, this argument is the desired quality level of the + image. The value is a number in the range 0.0 to 1.0, inclusive. + \endlist +\endlist + +\section1 Drawing Text + +You can draw text on your canvas by setting the following font attributes on the +2d drawing context: + +\list +\o \c{font} refers to any font, expressed the same way as in CSS properties. +This attribute's value can include any font style, variant, weight, size, +height, and family. For example: + + \code + context.font = "12pt Arial"; + \endcode + + The default value is \c{10px sans-serif}. + + If you set the \c{font} attribute to a + relative font size, the browser multiplies it by the computed font size of the + \c{<canvas>} element itself. For example: + + \code + context.font = "200%"; + \endcode + +\o \c{textAlign} specifies the alignment of the text. The values can be one of +the following: + \list + \o \c{left} for left-aligned text + \o \c{right} for right-aligned text + \o \c{center} for text that is centered within each line + \o \c{start} (default) - the text is aligned at the beginning of the line. Text + is left- or right-justified based on locale-specific writing method: left when + text is left-to-right, right when text is right-to-left. + \o \c{end} - the text is aligned at the end of the line, either left or right + depending on locale-specific writing method. + \endlist + +\o \c{textBaseline} specifies the position at which text is drawn relative to a +baseline. The figure below, from \l{HTML5 Canvas API}, illustrates the possible +values for the \c{textBaseline} attribute: + \list + \o \c{top} is the top of the em square, which approximates the top of the glyphs + in a font + \o \c{hanging} specifies a hanging baseline, where the tops of some glyphs are + anchored. + \o \c{middle} is the mid-point of the em square + \o \c{alphabetic} (default) is the anchor point of many alphabetic characters + \o \c{ideographic} is the anchor point of many ideograms, such as the characters + used in the writing systems of many Asian languages + \o \c{bottom} is the bottom of the em square + \endlist +\endlist + +\image webkit-guide/canvas_text.png + +To draw text on a canvas: +\list 1 +\o Set the \c{font} attribute on the drawing context. For example: + \code + context.font = "bold 11px arial" + \endcode +\o Measure the text that you want to draw by calling the \c{measureText} method: + \code + TextMetrics measureText("Text to draw"); + \endcode +where \c{TextMetrics} is the object returned. Its \c{width} attribute is the +width, in pixels, that the \c{"Text to draw"} would be when drawn with the font +specified by the \c{font} attribute. +\o Call either of the following methods: + \list + \o \c{fillText} draws the text with the font style specified by the \c{font} + attribute, the alignment specified by the \c{textAlign} attribute, and the + baseline specified by the \c{textBaseline} attribute. For example: + \code + context.fillText("Text to draw",x,y,maximumWidth); + \endcode +where \c{x} and \c{y} are the coordinates at which the drawing begins (the +anchor point), and \c{maximumWidth} is the maximum width of the text string +(optional). If the \c{width} returned in step 2 is larger than the +\c{maximumWidth}, the font is scaled down until the width of the text string is +less than the \c{maximumWidth} specified. + +If you don't specify the \c{font} attribute, the text inherits the font size and +style of the \c{<canvas>} element itself. + +\o \c{strokeText} is the same as the \c{fillText} method, except that +a stroke style is applied to the text instead of a fill style, +creating outlines of glyphs. For example: + +\code +context.fillText("Text to stroke",x,y,maximumWidth); +\endcode + +\endlist + +\endlist + +\section1 Working with Images + +You can insert existing images onto your canvas, you can scale or crop +them, and you can combine them to create composite images. You can +also draw new images by creating an \c{Image()} object with JavaScript. + +To insert an existing image onto a canvas, call the \c{drawImage} method: + +\code +context.drawImage(image, dx, dy, dw, dh) +\endcode + +where: + +\list + +\o \c{image} is a reference to an HTML \c{<image>} or \c{<canvas>} +element. The image must be fully loaded before you can draw it on the +canvas. The reference cannot be a URL. Instead, it should be +referenced using standard DOM methods such as \c{document.images()} or +\c{document.getElementById()}. For example: + +\code +<canvas id="demo1" width="100" height="150"></canvas> + +var canvas = document.getElementById("demo1"); +var context = canvas.getContext("2d"); +\endcode + + +\o \c{dx} is the x coordinate of the upper left corner of the image to be +drawn on the canvas (the destination image) + +\o \c{dy} is the y coordinate of the upper left corner of the destination +image + +\o \c{dw} is the width of the destination image (optional) + +\o \c{dh} is the height of the destination image (optional) + +\endlist + +If \c{dw} and \c{dh} are not specified, the image retains its source +dimensions when drawn on the canvas. When \c{dw} and \c{dh} are +specified, the image is scaled to width \c{dw} and height \c{dh} when +drawn on the canvas. + +If you want to crop the source image, the \c{drawImage} method can be +overloaded with the following arguments: + +\code +context.drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh) +\endcode + +where: +\list +\o \c{sx} is the x coordinate of the upper left corner of the cropped source +image +\o \c{sy} is the y coordinate of the upper left corner of the cropped source +image +\o \c{sw} is the width of the cropped source image +\o \c{sh} is the height of the cropped source image +\endlist + +Use this method if you want to crop the source image to the rectangle (sx, sy, +sw, sh) before drawing it on the canvas. The destination image will have width +\c dw, height \c dh, and upper left corner at coordinates \c{(dx,dy)} on the +canvas. + +To create a new image using JavaScript, create an \c{Image} object and define +its source. Use an \c{onload} event handler to ensure that the \c{drawImage} +method is not called until the image has finished loading. For example: + +\code +var graphic = new Image(); +graphic.src = "clipart/graphic.png"; +\endcode + +The image begins to load. + +\code +graphic.onload = function(){ + context.drawImage(graphic,x,y); +}; +\endcode + + \section2 Creating Patterns with Images + + You can create patterns with an image by repeating it horizontally, + vertically, or both. The top left corner of the first image must be + anchored at the origin of the coordinate space. To repeat an image, + call the \c{createPattern} method: + + \code + context.createPattern(image, repetition); + \endcode + + where: + + \list + + \o \c{image} is a reference to an HTML \c{<image>} or \c{<canvas>}element + that is repeated to form a pattern. The image must + be fully loaded before you can draw it on the canvas. The reference + cannot be a URL. Instead, it should be referenced via standard DOM + methods such as + \list + \o \c{document.images} and + \o \c{document.getElementById}. For example: + + \code + <canvas id="demo1" width="100" height="150"></canvas> + + var canvas = document.getElementById("demo1"); + var context = canvas.getContext("2d"); + \endcode + \endlist + \o \c{repetition} is the direction in which the image repeats to form the + pattern. Possible values are: + \list + \o \c{repeat} (default) the image repeats both horizontally and vertically + \o \c{repeat-x} the image repeats horizontally + \o \c{repeat-y} the image repeats vertically + \endlist + \endlist + + The repeated images are the same size as the source image. The + \c{createPattern} method does not scale the images. + + For example, to create a horizontal pattern of roses, create an + \c{Image} object to use as a pattern and define its source. Use an + \c{onload} event handler to ensure that the \c{createPattern} method + is not called until the image has finished loading. For example: + + \code + var roses = new Image(); + roses.src = "clipart/roses.jpg"; + \endcode + + The image begins to load. + + \code + roses.onload = function(){ + var pattern = context.createPattern(roses,repeat-x); + }; + \endcode + + \image webkit-guide/canvas_pattern.png + +\section1 Applying Colors + +To draw the outline of a shape in color, set the \c{strokeStyle} attribute to +any valid \l{CSS Color Value}{CSS color value}. The color value can be in +hexadecimal notation or in RGB/HSL notation, as described in \l{Specifying Color +and Opacity}. For example, either of the following sets a shape's outline to +red: + +\code +context.strokeStyle = "#FF0000" +context.strokeStyle = "rgb(255,0,0)" +\endcode + +To fill a shape with color, set the \c{fillStyle} attribute to a l{CSS Color +Value}{CSS color value}. The color value can be in hexadecimal notation or in +RGB/HSL notation. For example, either of the following colors a shape's interior +as blue: + +\code +context.fillStyle = "#0000FF" +context.fillStyle = "rgb(0,0,255)" +\endcode + +The \l{CSS3 Color Module specification} extends both RGB and HSL color models to +include a color's opacity, referred to as its \e{alpha}. These extended +models are known as RGBA and HSLA. There are no hexadecimal notations for RGBA +and HSLA values. The following specifies varying levels of opacity for a blue +shape: + +\code +context.fillStyle = rgba(0, 0, 255, 0) // transparent +context.fillStyle = rgba(0, 0, 255, 0.5) // semi-transparent +context.fillStyle = rgba(0, 0, 255, 1) // opaque +\endcode + +When you set the \c{context.strokeStyle} or \c{context.fillStyle} attributes, +whatever value you set becomes the default value for all subsequently drawn +shapes, until you set a new value. + + \section2 Applying Gradients + + A gradient is a smooth transition between colors. There are two types of + gradients: linear and radial. + + A linear gradient transitions the color along a line between two points. To + create a linear gradient, call the \c{createLinearGradient} method: + + \code + createLinearGradient(x0, y0, x1, y1) + \endcode + + where \c{(x0, y0)} is the starting point and \c{(x1, y1)} is the ending + point for the linear gradient. + + A radial gradient transitions the color along a cone between two circles. To + create a radial gradient, call the \c{createRadialGradient} method: + + \code + createRadialGradient(x0, y0, r0, x1, y1, r1) + \endcode + where: + \list + \o \c{(x0, y0, r0)} represents the starting circle, whose origin is \c{(x0, + y0)} and whose radius is \c{r0}. + \o \c{(x1, y1, r1)} represents the ending circle, whose origin is \c{(x1, y1)} + and whose radius is \c{r1}. + \endlist + + Gradients must have two or more \e{color stops}, representing color + shifts positioned from \c 0 to \c 1 between to the gradient's starting and + end points or circles: + + \code + addColorStop(position,color) + \endcode + + where: + \list + \o \c{position} specifies the position of the color within the already + defined starting and end points or circles, expressed as a number from \c 0 + to \c 1. + \o \c{color} specifies the CSS color at that position. + \endlist + + For example, to define a gradient that varies from red to blue horizontally + along a rectangular area: + \list 1 + \o Create a gradient object: + \code + var redbluegradient = context.createLinearGradient(0,0,100,0); + \endcode + \o Define the color stops: + \code + redbluegradient.addColorStop(0, "rgb(255,0,0)"); // red at the left side of the rectangle + redbluegradient.addColorStop(1, "rgb(0,0,255)"); // blue at the right side of the rectangle + \endcode + \o Draw the shape and set a \c{fillStyle} or \c{strokeStyle}: + \code + context.fillStyle = redbluegradient; + context.fillRect(0,0,100,150); + \endcode + \endlist + + To define a gradient that varies from red to blue vertically along a + rectangle: + \list 1 + \o Create a gradient object: + \code + var redbluegradient = context.createLinearGradient(0,0,0,150); + \endcode + \o Define the color stops: + \code + redbluegradient.addColorStop(0, "rgb(255,0,0)"); // red at the top of the rectangle + redbluegradient.addColorStop(1, "rgb(0,0,255)"); // blue at the bottom of the rectangle + \endcode + \o Draw the shape and set a \c{fillStyle} or \c{strokeStyle}: + \code + context.fillStyle = redbluegradient; + context.fillRect(0,0,100,150); + \endcode + \endlist + + \note A canvas gradient's color stops behave slightly differently than those + used within non-canvas \l{Gradients}{gradients}. Webkit gradients specify + mandatory \c{from} and \c{to} colors, with optional \c{color-stop} values + for additional color shifts within the overall range of the gradient. For + canvas gradients, even the initial and final colors are defined as color + stops. + + \section2 Applying Shadows + + To add a shadow effect to a drawing on a canvas, set the following + attributes: + + \list + \o \c{shadowColor} sets the color of the shadow. The value can be any CSS + color value. The default value is transparent black (\c{"rgba(0,0,0,0)"}). + + \o \c{shadowBlur} sets the amount of blur in the shadow, in pixels. The + value can be any positive number or 0. A value of 0 produces a sharp shadow + with no blur. + + \o \c{shadowOffsetX} sets the number of pixels the shadow extends + horizontally from the object drawn. If this value is a positive number, the + shadow extends to the right of the object. If negative, the shadow extends + to the left of the object. The default value is 0 pixels. + + \o \c{shadowOffsetY} sets the number of pixels the shadow extends vertically + from the object drawn. If this value is a positive number, the shadow + extends below the object. If negative, the shadow extends above the object. + The default value is 0 pixels. + \endlist + + The following example code adds a semi-transparent black shadow to the + bottom right of a blue rectangle: + + \code + var context = canvas.getContext("2d"); + context.shadowOffsetX = 5; + context.shadowOffsetY = 5; + context.shadowBlur = 10; + context.shadowColor = "rgba(0,0,0,0.5)"; + context.fillStyle = "#0000FF"; + context.fillRect = (0,0,100,50) + \endcode + +\section1 Transforming Graphics + +When drawing shapes and paths, you can translate the canvas's origin, rotate the +canvas around the origin, scale the units in the canvas grid, and modify the +transformation matrix directly. + + \section2 Translating the Canvas Origin + + Translating the origin enables you to draw patterns of different objects on + the canvas without having to measure the coordinates manually for each + shape. To translate the origin of the canvas, use the \c{translate} method: + \code + context.translate(x,y); + \endcode + where: + \list + \o \c{x} is the horizontal distance that the origin is translated, in + coordinate space units + \o \c{y} is the vertical distance that the origin is translated, in + coordinate space units + \endlist + + \section2 Rotating the Canvas + + To rotate the canvas around the current origin, call the \c{rotate()} + method: + \code + context.rotate(angle); + \endcode + where \c{angle} is the clockwise rotation angle in radians. + The number of radians is the number of degrees multiplied by \pi/180, + expressed in JavaScript as: + \code + var radians = (Math.PI/180)*degrees; + \endcode + \image webkit-guide/canvas_rotate.png + + \section2 Scaling the Canvas Grid + + To increase or decrease the size of each unit in the canvas grid, call the + \c{scale} method: + + \code + context.scale(x,y); + \endcode + + where: + + \list + + \o \c{x} is the scale factor in the horizontal direction + + \o \c{y} is the scale factor in the vertical direction + + \endlist + + The scale factors are in multiples. For example, \c{scale(2.0, 0.5)} would + double the horizontal size of an object drawn on the canvas and half its + vertical size, as shown below: + + \image webkit-guide/canvas_scale.png + + \section2 Manipulating the Transformation Matrix + + Modifying the transformation matrix directly enables you to perform scaling, + rotating, and translating transformations in a single step. + + The transformation matrix is an \e{affine transformation} matrix from linear + algebra. Affine transformations preserve colinearity and relative distance + in the transformed coordinate space. This means that points in a line remain + in a line, parallel lines remain parallel, and the distance between lines + and objects maintains the same ratio, even if a scale factor is applied. + Repositioning by translation, rotation, or skewing is also possible. + + Each point on the canvas is multiplied by the matrix before anything is + drawn. The \l{HTML5 Canvas API} defines the transformation matrix as: + + \image webkit-guide/canvas_math.png + where: + \list + \o \c{a} is the scale factor in the horizontal (x) direction + \image webkit-guide/canvas_scalex.png + \o \c{c} is the skew factor in the x direction + \image webkit-guide/canvas_skewx.png + \o \c{e} is the translation in the x direction + \image webkit-guide/canvas_translate.png + \o \c{b} is the skew factor in the y (vertical) direction + \image webkit-guide/canvas_skewy.png + \o \c{d} is the scale factor in the y direction + \image webkit-guide/canvas_scaley.png + \o \c{f} is the translation in the y direction + \image webkit-guide/canvas_translatey.png + \o the last row remains constant + \endlist + + The scale factors and skew factors are multiples; \c{e} and \c{f} are + coordinate space units, just like the units in the \c{translate(x,y)} + method. + + The rotation transformation matrix is as follows: + + \image webkit-guide/canvas_math_rotate.png + + where the \c angle of rotation is in radians. + + \bold{See Also:} + \l{http://www.senocular.com/flash/tutorials/transformmatrix/}{senocular.com} + for a good explanation of how transformation matrices are used + identically within Adobe Flash. + +\section1 Canvas Animations + +You can animate a canvas drawing by repeatedly redrawing the canvas for each +frame and translating, rotating, skewing, and scaling the drawn objects. + +To draw each frame by employing the HTML5 canvas API, you should define the +original canvas state and save it for future reference. The drawing context +maintains a stack of drawing states. Each state consists of the current +transformation matrix, current clipping region, and current values of the +following attributes: +\list +\o\c{strokeStyle} +\o\c{fillStyle} +\o\c{globalAlpha} +\o\c{lineWidth} +\o\c{lineCap} +\o\c{lineJoin} +\o\c{miterLimit} +\o\c{shadowOffsetX} +\o\c{shadowOffsetY} +\o\c{shadowBlur} +\o\c{shadowColor} +\o\c{globalCompositeOperation} +\o\c{font} +\o\c{textAlign} +\o\c{textBaseline} +\endlist +The current path and the current bitmap are NOT part of the drawing state. +The path can be reset only by invoking the \c{beginPath()} method. The current +bitmap is a property of the canvas, not of the context. + +To save the original canvas state, call the \c{save()} method: +\code +context.save(); +\endcode + +Before drawing each new frame, you must clear the canvas: +\code +canvas.clearRect(x,y,width,height); +\endcode +where: +\list +\o \c{x} is the position of the top left corner of the canvas on the horizontal +axis +\o \c{y} is the position of the top left corner of the canvas on the vertical +axis +\o \c{width} is the width of the canvas +\o \c{height} is the height of the canvas +\endlist + +Draw the new frame using any of the methods provided by the canvas API. Then +save it by calling the \c{save()} method. + +If you wish to return to the state of the original frame as the basis for each +new frame that you draw, call the \c{context.restore()} method. + +To execute the drawing methods repeatedly, use the standard JavaScript-based +animation technique, calling the \c{setInterval()} and \c{clearInterval()} +methods. The following shows how to execute an animation function every \c 50 +milliseconds (corresponding to 20 times per second, a typical animation frame +rate), then subsequently halt the animation: +\code +var id = setInterval(functionName, 50); +clearInterval(id); +\endcode + +\bold{See Also:} +\list +\o +\l{http://www.canvasdemos.com/2009/10/09/html-5-canvas-animation/}{CanvasDemos.com: animated cartoon}, which discusses how to use Canvas as an animation framework. + +\o +\l{http://blog.nihilogic.dk/2009/02/html5-canvas-cheat-sheet.html}{nihilogic.dk: +HTML5 Canvas Cheat Sheet} + +\o \l{QtWebKit Guide} -back to the main page +\endlist + +*/ diff --git a/doc/src/webkit/guide/chapter_css.qdoc b/doc/src/webkit/guide/chapter_css.qdoc new file mode 100644 index 0000000..71005fc --- /dev/null +++ b/doc/src/webkit/guide/chapter_css.qdoc @@ -0,0 +1,1519 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the Qt WebKit module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + +\page qtwebkit-guide-css.html + +\title QtWebKit Guide - Level 3 CSS + +\chapter Level 3 CSS +This section of the \l{QtWebKit Guide} serves as an introduction to various +Level 3 CSS features supported by QtWebKit: + +\list + +\o The \l{Media Queries} section discusses a simple client-based technique to +present different interfaces and functionality from a single source of content +to different classes of mobile device. + +\o The \l{Selectors} section concentrates on recently introduced syntax elements +that make applying formatting and gathering DOM elements more flexible. + +\o The \l{Visual Effects} section surveys numerous formatting properties, +including new color models and advanced WebKit effects. + +\o Finally, the \l{Dynamic CSS} section discusses 2D transforms, transitions, +and keyframe animations. + +\endlist + +This section features links to numerous sample pages that demonstrate how +various CSS3 features may be applied within a mobile interface. For best +results, view these samples with a modern Webkit-based browser such as Apple +Safari or Google Chrome. Resize the window in which the sample appears to +roughly match the dimensions of a touch-screen mobile device. + +\section1 Media Queries + +CSS \e{media queries} extend \e{media types} with more detailed capabilities. +Media queries offer a simple client-side mechanism to customize interfaces +comprehensively via CSS. + +Media queries are especially useful when extending a body of content for +presentation on mobile browsers. Prior to support for this feature, there were +two basic approaches to provisioning mobile web content, both server-based: + +\list +\o \e{Mobile-specific domains}. Content providers might provide a separate +access points for default content at \c{www.website.com}, with mobile content +available at \c{m.website.com} or \c{website.mobi}. There might also be an +additional \c{touch.website.com} access point targeted for higher-end +touch-screen browsers. + +\o \e{Dynamic Server-based Adaptation}. In this case, there is a single access +point, but the server sends different content, typically depending on the +\e{User-Agent} header included in all browsers' HTTP requests. +This approach may leverage databases of device characteristics such as +\l{WURFL} or \l{DeviceAtlas}. +\endlist + +This section describes how to provision CSS entirely on the mobile +client. + + \section2 Media Types and Media Queries + + If you only want to serve interfaces for desktop browsers and low-end mobile + browsers, specify external CSS files within your HTML's \c{head} region + using media types: + + \code + <link media="screen" href="/path/to/desktop.css" type="text/css" rel="stylesheet"/> + <link media="handheld" href="/path/to/mobile.css" type="text/css" rel="stylesheet"/> + \endcode + + The \c{media} attribute specifies different \e{types} of browser: \c{screen} + for large-screen desktop browsers, and \c{handheld} for mobile browsers. + Browsers identifying themselves as \c{handheld} are served the + \c{mobile.css} file, which should specify a dramatically simplified + mobile interface. + + A problem arises, however, when the majority of higher-end touch browsers + identify themselves as the \c{screen} media type, to avoid being served + overly simplified content that is beneath their capabilities. The example + above serves a desktop-oriented design to later-generation mobile browsers. + To target a higher-end mobile design to these browsers, you need to specify + additional media \c{queries}: + + \code + <link media="only screen and (min-device-width: 481px)" href="/path/to/desktop.css" type="text/css" rel="stylesheet"/> + <link media="only screen and (max-device-width: 480px)" href="/path/to/touch.css" type="text/css" rel="stylesheet"/> + <link media="handheld" href="/path/to/mobile.css" type="text/css" rel="stylesheet"/> + \endcode + + The first two lines specify any \c{screen}-typed browser whose window + is wider or narrower than 480 pixels. + + Regions of content that are inappropriate for presentation within + either the touch-based or lower-end mobile design can then be easily + removed within the corresponding CSS files: + + \code + .widget, .nested_nav, .sidebar, .video_ad, .related_items { + display: none; + } + \endcode + + The following example demonstrates a simple message identifying your class + of browser, which appears dynamically based on CSS that is linked using + media types and media query syntax: + + \l{mob_mediaquery}{\inlineimage webkit-guide/scr_mob_mediaquery.png + } + + \e{Click on the image to view the example live in a browser or click on the + following links to view the CSS files.} + + \l{mq_desktop_css}{(Desktop CSS)} + \l{mq_touch_css}{(Touch-Screen CSS)} + \l{mq_mobile_css}{(Low-end Mobile CSS)} + + The following example shows a skeletal interface that appears differently + based on the type of browser viewing it. The image below shows how it + appears when viewed on a touch-based browser, but a desktop browser renders + a more elaborate three-column layout: + + \l{mob_layout}{\inlineimage webkit-guide/scr_mob_layout.png + } + + \l{mqlayout_desktop_css}{(Desktop CSS)} + \l{mqlayout_touch_css}{(Touch-Screen CSS)} + \l{mqlayout_mobile_css}{(Low-end Mobile CSS)} + + When viewed with a desktop browser, + the page displays a typical desktop-style layout: + a main content column surrounded by navigation and sidebar columns, + with banner headers and footers that straddle the top and bottom of + the screen. + When viewed with a touch-based browser, + the sidebar element does not appear. + The main content extends to the full width of the screen, + while header and navigation elements share the top of the screen. + When viewed with other mobile browsers, + even the top of the screen is simplified to replace header information + with a simple icon. + + Note that you can also use media queries to customize interfaces for + tablet devices such as the Apple iPad: + + \code + <link rel="stylesheet" media="all and (min-device-width: 481px) + and (max-device-width: 1024px)" href="/path/to/ipad.css"/> + \endcode + + \section2 In-line Media Queries + + While it's generally good practice to keep CSS for different designs within + separate files, you can also consolidate them. The following example + provides a default san-serif font styling for \c{h1} elements, then + different sets of style sheets for three browser categories: + + \code + h1 { font-family : Arial, sans-serif } + @media screen { + h1 { color: #00008B; } + } + @media only screen and (max-device-width: 480px) { + h1 { color: #00008B; font-size: medium; } + } + @media handheld { + h1 { font-size: medium; font-weight: bold } + } + \endcode + + Consolidating style sheets in this manner may reduce the number of separate + HTTP requests, help web designers to keep track of variations among designs, + and reduce style sheet properties defined redundantly in more than one file. + + \section2 Media Queries via JavaScript + + Browsers that support media queries also support APIs to test them from + within JavaScript. Browsers based on QtWebKit use the \c{matchMedia} API. + Some other browsers use a slightly different (and older) \c{styleMedia} API, + which itself used to be called the \c{media} API. Each can be called from + the \c{window} object. The following function accounts for all three cases: + + \code + function matchesMediaQuery(query) { + if (!!window.matchMedia) + return window.matchMedia(query).matches; + if (!!window.styleMedia && !!window.styleMedia.matchMedium) + return window.styleMedia.matchMedium(query); + if (!!window.media && window.media.matchMedium) + return window.media.matchMedium(query); + return false; + } + \endcode + + The \c{query} argument corresponds to the media query string used to + activate the CSS. For example, the following higher-level function tests + whether the browser matches design categories provided simple labels such as + \c{desktop}, \c{touch}, or \c{mobile}: + + \code + function isDesign(str) { + var design; + if (matchesMediaQuery('only screen and (min-device-width: 481px)')) { + design = 'desktop'; + } + else if (matchesMediaQuery('only screen and (max-device-width: 480px)')) { + design = 'touch'; + } + else if (matchesMediaQuery('handheld')) { + design = 'mobile'; + } + return str == design; + } + \endcode + + You can then use the test whenever there is a need to assign functionality + for a specific design. The following gathers a series of images and assigns + different panel-viewing functions for \c{desktop} and \c{touch} designs, + with no functionality assigned to the lower-end \c{mobile} design: + + \code + var imgs = document.querySelectorAll("img.panel"); + for ( var i = 0, len = imgs.length ; i < len ; i++ ) { + el = imgs[i]; + if ( isDesign("desktop") ) { + imgs[i].addEventListener("mouseover", showHoverPanel); + imgs[i].addEventListener("mouseout", hideHoverPanel); + } + else if ( isDesign("touch") ) { + imgs[i].addEventListener("click", showTouchPanel); + } + } + \endcode + + The following example uses this technique to produce a simple message, + dynamically generated by JavaScript, + that corresponds to the message generated by CSS: + + \l{mob_condjs}{\inlineimage webkit-guide/scr_mob_condjs.png + } + + \l{mob_condjs_css}{(CSS)} + \l{mob_condjs_js}{(JavaScript)} + +\section1 Selectors + +Level 3 CSS provides many useful new \e{selectors} that make it easier to apply +formatting to page elements. In addition, the \l{Selectors API} makes DOM +elements accessible using the same CSS expressions you use to apply formatting +to them. The following show alternate ways to access elements: + +\code +var element = document.getElementById('map'); +var element = document.querySelector('#map'); + +var elements = document.getElementByClassName('active'); +var elements = document.querySelectorAll('ul > li.active'); +\endcode + +This section provides examples of how different kinds of Level 3 +selectors might be applied when formatting mobile interfaces. + + \section2 Attribute Matching + + It is often useful to offer visual hints marking different kinds of link. + Users might want to know the difference between a link to a page on the same + website and one on an external site. Links to non-HTML file types might pose + special challenges to mobile users. Alternately, mobile users might get + special benefit from telephone links. + + You can automate this by using the CSS attribute prefix and suffix matching + selectors. The following uses \c{^=} to mark external HTTP links, email, + SMS, and telephone links, by inserting an icon after the text of the link: + + \code + a[href^="http://"]:after, a[href^="https://"]:after + { content : url(icon/external.png); } + a[href^="mailto:"]:after { content : url(icon/email.png); } + a[href^="sms:"]:after { content : url(icon/sms.png); } + a[href^="tel:"]:after { content : url(icon/tel.gif); } + \endcode + + The following uses \c{$=} to identify various file types by common suffixes: + + \code + a[href$=".doc"]:after { content : url(icon/ms_word.gif) } + a[href$=".ppt"]:after { content : url(icon/powerpoint.gif) } + a[href$=".rss"]:after, a[href$=".xml"]:after + { content : url(icon/feed.gif) } + a[href$=".pdf"]:after { content : url(icon/pdf.jpg) } + a[href$=".xls"]:after { content : url(icon/excel.jpg) } + \endcode + + You can also use \c{*=} to freely match substrings within any attribute + value. The following might distinguish links to a site's blog area based on + how the URL is organized: + + \code + a[href*="/blog/"]:after { content : url(icon/blog.jpg )} + \endcode + + The following example demonstrates links identified by dynamically generated + icons: + + \l{layout_link-fmt}{\inlineimage webkit-guide/scr_layout_link-fmt.png + } + + \l{layout_link-fmt_css}{(CSS)} + + \section2 Form Input State + + The \c{:checked} dynamic class allows you to style radio and checkbox inputs + based on their selection state: + + \code + input[type=radio], + input[type=checkbox] + { text-align : right } + + input[type=radio]:checked, + input[type=checkbox]:checked + { text-align : left } + \endcode + + This enables the following mobile-friendly interface, which converts small + radio and check boxes to much more accessible toggle buttons: + + \l{form_toggler}{\inlineimage webkit-guide/scr_form_toggler.png + } + + \l{form_toggler_css}{(CSS)} + + Using the dynamic \c{:checked} CSS class, the \c{text-align} property + toggles from \c{left} to \c{right} depending on whether the \c{input} is + checked or not. Note that to display button text, dynamic classes can be + chained together to form complex expressions: + \c{input[type=radio]:checked:before}. + + The example also relies on the \c{-webkit-appearance} property, which allows + you to override the default visual presentation of specialized interface + elements such as radio and checkbox inputs. + + The following example provides alternate styling for radio and checkbox + inputs, presenting them as tappable buttons: + + \l{form_tapper}{\inlineimage webkit-guide/scr_form_tapper.png + } + + \l{form_tapper_css}{(CSS)} + + Form elements may also be re-styled based on whether they are \c{:enabled} + or \c{:disabled}. In addition, the \c{:focus} dynamic class allows you to + style text form inputs or other editable content regions that users have + currently selected for editing. + + \section2 Navigational Selectors + + Elements within a page that are the target of navigation can receive + distinct styling using the \c{:target} dynamic class. The act of navigating + to an element can alter its appearance, or even determine if it is to appear + at all. + + The following example relies on anchor navigation to display successive rows + of a table within a mobile interface: + + \l{layout_tbl-keyhole}{\inlineimage webkit-guide/scr_layout_tbl-keyhole.png + } + + \l{layout_tbl-keyhole_css}{(CSS)} + + While the example relies on table-related tags, they are re-styled with + block formatting to confine each row of information within the screen. Each + row features links to other rows, triggering their display. Other links + navigate away from the table, which suppresses its display altogether. This + is the main CSS driving the interface: + + \code + .mobile > tbody > tr { display : none } + .mobile > tbody > tr:target { display : block } + \endcode + + The same technique may be used to display or dismiss optional interface + elements such as panels, simply by providing navigation links to them within + the page. + + \section2 Indirect Sibling Selector + + The Level 2 \c{+} selector allows you to style elements that immediately + follow other specified elements. For example, the following refers to a + paragraph that immediately follows a heading at the same level of markup: + + \code + h1 + p { font-weight: bold } + \endcode + + In contrast, the Level 3 \c{~} indirect sibling selector allows you to style + any subsequent element at the same level within the markup. The following + example styles any element that follows an \c{h2} that is classed + \c{pullquote}: + + \code + h2 ~ .pullquote { font-size: 90% } + \endcode + + \note Webkit-based browsers do not yet allow you to style + elements dynamically via indirect sibling selectors. + + \section2 Positional Selectors + + Various dynamic classes allow you to style elements depending on their + position with a series of elements: either elements of the same type, or + other child elements of the same parent. The following example aligns a + series of icons to a grid: + + \l{css3_sel-nth}{\inlineimage webkit-guide/scr_css3_sel-nth.png + } + + \l{css3_sel-nth_css}{(CSS)} + + Columns are specified with the \c{:nth-of-type()} selector, which accepts + numeric expressions as arguments. The following selectors refer to every + fourth \c{img} element, but offset by a specified number: + + \code + img { position: absolute } + img:nth-of-type(4n-3) { left: 2% } + img:nth-of-type(4n-2) { left: 27% } + img:nth-of-type(4n-1) { left: 52% } + img:nth-of-type(4n-0) { left: 77% } + \endcode + + Alternately, keywords \c{odd} and \c{even} correspond to \c{2n-1} and \c{2n} + expressions. These are useful, for example, when styling table rows with + alternating background colors. + + Rows are represented as the number of the element within the series, plus a + fixed number. Each selector redefines the previous selector's upper range + of values: + + \code + img:nth-of-type(n) { top: 5% } + img:nth-of-type(n+5) { top: 20% } + img:nth-of-type(n+9) { top: 35% } + img:nth-of-type(n+13) { top: 50% } + img:nth-of-type(n+17) { top: 65% } + img:nth-of-type(n+21) { top: 80% } + \endcode + + Level 3 CSS defines the following positional selectors: + + \list + \o \c{:first-child}, \c{:last-child}, and \c{:only-child} refer to the first + or last child element within a series, or when it is the only one. + + \o \c{:first-of-type}, \c{:last-of-type}, and \c{:only-of-type} refer to the + first or last specified element within a series, or when it is the only one. + + \o \c{:nth-first-child()} and \c{:nth-last-child()} refer to the specified + child element positioned from the start or end of the series. + + \o \c{:nth-first-of-type()} and \c{:nth-last-of-type()} refer to the + specified element positioned from the start or end of the series. + + \o \c{:nth-of-type()} refers to any series of specified elements. + + \o \c{:nth-child()} refers to any series of child elements. + + \endlist + + \section2 Other Selectors + + Level 3 CSS specifies several other potentially useful dynamic + classes that can be added to selectors: + + \list + + \o \c{:empty} refers to an element that contains no child elements, + including text nodes. + + \o \c{:root} is a markup-independent way to refer to elements that are + postioned at the root of the document, + in most cases the \c{html} tag. + + \o The \c{:not()} dynamic class allows you to narrow a range of + selectors. + This may be more useful when gathering elements via the Selectors API. + For example, + the following JavaScript gathers form inputs, + but not including submit buttons: + + \code + var inputs = document.querySelectorAll("input:not([type=submit])"); + \endcode + + \endlist + +\section1 Visual Effects + +QtWebKit supports numerous Level 3 CSS visual features. This section briefly +demonstrates how many of these recently available visual features may be used to +refine mobile web designs. + +These more advanced CSS3 effects tend to be available only on the latest +generation of mobile browsers. Still, it is safe to use them, even if the design +degrades somewhat for devices that don't support them. When a browser +encounters CSS properties or values it can't interpret, it simply ignores them. +Designers can respond by providing fallback options to allow for \e{graceful +degradation}. For example, the following CSS specifies a plain gray background +in case the browser does not support gradients: + +\code +background: #aaaaaa; +background: -webkit-gradient(linear, center top, center bottom, + from(#777777), color-stop(50%,#dddddd), to(#777777) ); +\endcode + +Note that many of the CSS properties discussed in this section were implemented +relatively recently, and vendors of browser rendering engines (such as WebKit) +may still be in the process of testing and standardizing their behavior. These +property names feature \e{vendor prefixes} such as \c{-webkit-} for WebKit, +\c{-moz-} for Mozilla, and \c{-o-} for Opera. + +It may be possible to extend CSS properties to these various browsers by +providing vendor-specific syntax. The following example shows how to extend the +\c{border-image} property to the Opera browser or Mozilla-based Fennec or the +Maemo Browser for Nokia N900. It also shows the property's final name following +the process of standardization: + +\code +-webkit-border-image : url(img/border-frame.gif) 10 stretch stretch; +-moz-border-image : url(img/border-frame.gif) 10 stretch stretch; +-o-border-image : url(img/border-frame.gif) 10 stretch stretch; +border-image : url(img/border-frame.gif) 10 stretch stretch; +\endcode + +In some cases, there are slight variations in the syntax each vendor expects as +property values. + + \section2 Specifying Color and Opacity + + Prior to CSS3, there were three options when specifying color values: named + colors, hexadecimal color values, or RGB values. CSS3 provides additional + ways to specify colors: + + \list + \o \e{HSL}. Colors defined with the HSL model specify the \e{hue} as a + radial or degree coordinate, then its \e{saturation} and \e{luminence} + as percentages. The following example specifies red and green values: + + \code + background: hsl(0 , 100%, 60%); + background: hsl(128, 75% , 33%); + \endcode + + \o \e{HSLA}. + Same as HSL, + but specifying an additional decimal \e{alpha} value that + corresponds to opacity. + The following specifies a fully opaque red, + followed by a partial transparency: + + \code + background: hsla(0, 100%, 60%, 1.0); + background: hsla(0, 100%, 60%, 0.5); + \endcode + + \o \e{RGBA}. + Same as RGB, + but specifying an additional decimal \e{alpha} value that + corresponds to opacity. + The following the same transition from opaque to transparent as shown + above: + + \code + background: rgba(100%, 0%, 0%, 1.0); + background: rgba(100%, 0%, 0%, 0.5); + \endcode + \endlist + + With the addition of opacity to color definitions, you can now also specify + \c{transparent} as a color name. Note that while RGBA and HSLA options are + now available, you can still use the familiar \c{opacity} property + independently of color definitions. + + \section2 Rounded Corners + + In addition to removing harsh edges, rounded corners often help distinguish + active items from static background elements. Rounded corners are + implemented using the \c{border-radius} property. The following rounds off + an edge to the same extent that interior elements are offset: + + \code + .rounded { + border-radius : 1em; + padding : 1em; + } + \endcode + + The following example demonstrates how rounded corners can enhance a mobile + design, by marking the start and end of large regions of content, such as a + list of links: + + \l{layout_link-fmt}{\inlineimage webkit-guide/scr_layout_link-fmt.png + } + + \l{layout_link-fmt_css}{(CSS)} + + The greater the measurement applied to an element's \c{border-radius}, the + more dramatically rounded are its corners. For example, applying a + \c{border-radius} that is half an element's overall dimensions results in a + circle: + + \code + .circle { + width : 4em; + height : 4em; + border-radius : 2em; + } + \endcode + + You can also set each corner individually, and specify a pair of values to + achieve oval-shaped borders: + + \code + border-top-left-radius : 2em/1em; + \endcode + + \section2 Border Images + + Border images allow you to apply customized marquee effects, as in the + following example: + + \l{css3_border-img}{\inlineimage webkit-guide/scr_css3_border-img.png + } + + \l{css3_border-img_css}{(CSS)} + + In this case, the image stretches to fit an element's dimensions: + + \code + -webkit-border-image : url(img/border-frame.gif) 10 stretch stretch; + \endcode + + As is true of the \c{border} property, a single numeric argument specifies + the width of the border as a whole, or up to four values to modify the width + of each side. + + Any border image you specify substitutes some or all of an element's normal + border. The \c{border-image} and \c{border-corner-image} each collectively + represent four more specific properties. + + For \c{border-image}, these properties are: + + \list + \o \c{border-top-image} + \o \c{border-right-image} + \o \c{border-bottom-image} + \o \c{border-left-image} + \endlist + + For \c{border-corner-image}, these properties are: + \list + \o \c{border-top-left-image} + \o \c{border-top-right-image} + \o \c{border-bottom-right-image} + \o \c{border-bottom-left-image} + \endlist + + The \c{border-image} property specifies a single image for all four edge + borders. The \c{border-corner-image} property specifies an image for all + four corner borders. To specify images individually for any of the edge or + corner borders, use any of the eight individual properties. + + When specifying any border edge or corner image values: + + \list + \o A \c{stretch} value stretches one image to fill the element border area, + as shown in the example above. + + \o A \c{repeat} value repeats one image until it fills the element border + area and clips any overflow, for example: + + \code + -webkit-border-image : url(img/border-frame.gif) 10 repeat repeat; + \endcode + + In this case the first \c{repeat} applies to top and bottom edge borders, + and the second applies to left and right edge borders. + \endlist + + \section2 Backgrounds + + CSS3 allows you to specify more than one background image at a time. + The following example shows an accordion-style tabbed interface: + + \l{css3_backgrounds}{\inlineimage webkit-guide/scr_css3_backgrounds.png + } + + \l{css3_backgrounds_css}{(CSS)} + \l{css3_backgrounds_js}{(JavaScript)} + + By default, tabs display a single icon image, but when selected feature an + additional gradient background image. The following CSS shows how both icon + and background can receive their own series of specifications, affecting + their offset or whether each image repeats: + + \code + background-image : url(img/select.png) , url(img/gradient.jpg); + background-repeat : no-repeat , repeat-x; + background-position : 12px 12px , 0 0; + \endcode + + In addition, you may set the \c{background-size} property to \c{contain} to + scale images to the size of the containing element. (Level 2 CSS allowed + only specific measurements or percentages of the image's size.) + + \section2 Text Shadow and Stroke + + Shadows can be applied to text. As the following example shows, text shadows + may interfere with the legibility of text, and are seldom appropriate unless + they're used for large, sans-serif display headings: + + \l{css3_text-shadow}{\inlineimage webkit-guide/scr_css3_text-shadow.png + } + + \l{css3_text-shadow_css}{(CSS)} + + In addition to the shadow's color, the property accepts two measurements to + represent its offset from the text, while the third specifies the extent to + which the shadow is blurred: + + \code + h1,h2,h3,h4 { text-shadow : 0.25em 0.25em 0.25em #aaaaaa; } + \endcode + + CSS3 also allows you to apply a different colored fill to characters, + suitable mainly for larger display type or subtle animations: + + \l{css3_text-stroke}{\inlineimage webkit-guide/scr_css3_text-stroke.png + } + + \l{css3_text-stroke_css}{(CSS)} + + In the following CSS, \c{-webkit-text-fill-color} is synonymous with the + standard \c{color} property: + + \code + -webkit-text-stroke-color : #000000; + -webkit-text-stroke-width : 1px; + -webkit-text-fill-color : purple; + \endcode + + \section2 Text Overflow + + Web developers are familiar with the \c{overflow} property, which can be + used to hide content that exceeds an element's dimensions, or else to make + it accessible via scrolling. CSS3 specifies an additional \c{text-overflow} + property that allows you to add ellipses as a suffix to any text that + overflows the element, to indicate the presence of additional text. + + The following example shows how the \c{text-overflow} property allows you to + present user-selectable links to expanded regions of text within a page: + + \l{css3_text-overflow}{\inlineimage webkit-guide/scr_css3_text-overflow.png + } + + \l{css3_text-overflow_css}{(CSS)} + \l{css3_text-overflow_js}{(JavaScript)} + + Use the \c{text-overflow} property in conjunction with \c{overflow} and + \c{white-space}: + + \code + text-overflow : ellipsis; + overflow : hidden; + white-space : nowrap; + \endcode + + For \c{text-overflow} to work, the element's \c{white-space} must be set to + \c{nowrap}, overriding the default \c{normal} value. This prevents words + from wrapping onto another line as is standard behavior outside the \c{pre} + tag, and forces text past the right edge of the element. + + (The element's \c{text-overflow} may specify both \c{ellipsis} and + \c{ellipsis-word}, the latter of which is not as widely implemented.) + + \section2 Custom Scrollbars + + In general, scrollable elements should be avoided wherever possible within + mobile interfaces. Drag gestures already allow users to scroll windows + vertically, and narrow mobile screens are not suitable for overly wide + content. + + In cases where content can only be viewed within a scrolling window, + scrollbars can be reformatted to make them more accessible to mobile users. + The following example presents a block of code within a touch-enabled mobile + interface: + + \l{css3_scroll}{\inlineimage webkit-guide/scr_css3_scroll.png + } + + \l{css3_scroll_css}{(CSS)} + + This interface uses standard scrollbars, but their appearance is enhanced + using low-level \e{pseudo-element} CSS classes that refer to individual + components within the scrollbar. + + Simply by invoking the following CSS selector, you disable scrollbars' + default appearance: + + \code + pre::-webkit-scrollbar { height : 3em } + \endcode + + In this case, the specified property increases the scrollbar's default + \c{height} to make it easier for mobile users to tap it with their fingers. + + Each additional scrollbar component must then be explicitly defined, + otherwise it does not render. The following CSS provides custom styling for + the horizontal panning buttons: + + \code + ::-webkit-scrollbar-button:increment { + background-image : url(img/arrow_right.png); + background-size : contain; + background-repeat : no-repeat; + width : 3em; + height : 3em; + } + ::-webkit-scrollbar-button:decrement { + background-image : url(img/arrow_left.png); + background-size : contain; + background-repeat : no-repeat; + width : 3em; + height : 3em; + } + \endcode + + In this case, the scrollbar region between the two navigation icons is still + active, but not obviously so since its visual formatting has been + overridden. The simpler set of controls is far more suitable for a mobile + interface. + + Webkit provides pseudo-elements for the following components: + + \list + \o \c{scrollbar} refers to scrollbar as a whole. Additional dynamic classes + can be appended to specify \c{:vertical} and \c{:horizontal} scrollbars. The + \c{:corner-present} dynamic class activates when both scrollbars are + present. + + \o \c{scrollbar-button} refers to incremental navigation buttons. Each + button can be styled separately with \c{:increment} and \c{:decrement} + dynamic classes. + + \o \c{scrollbar-thumb} refers to the scrollbar's slider control. + + \o \c{scrollbar-track} refers to the active navigation region between + buttons. + + \o \c{scrollbar-track-piece} refers to each portion of the track on either + side of the thumb control. These can be styled separately using \c{:start} + and \c{:end} dynamic classes. + + \o \c{scrollbar-corner} refers to the corner where scrollbar tracks meet. + The \c{resizer} pseudo-element also refers to this corner, but for resizable + elements such as \c{textarea}. + + \o The \c{:double-button} and \c{:single-button} dynamic classes refer to + whether incrementor and decrementors are paired together redundantly at each + end of the track, while \c{:no-button} refers to whether they display at + all. + \endlist + + \bold{See Also:} + \l{http://webkit.org/blog/363/styling-scrollbars/}{Surfin' Safari: + Styling Scrollbars} + + \section2 Gradients + + Gradients provide a graduated shading effect that can add subtle texture to + background elements, and can provide buttons a three-dimensional, beveled + appearance. Explicit support for gradients means there's no longer a need to + implement them as repeating background images. + + Specify gradients using CSS properties such as the following: + + \code + background: #aaaaaa; + background: -webkit-gradient(linear, center top, center bottom, + from(#dddddd), to(#777777) ); + \endcode + + Note the pair of \c{background} statements. The first specifies a monochrome + fallback color for browsers that do not support gradients. + + The function specifies a simple \c{linear} gradient from the top to the + bottom of the element, shifting from a light to a darker gray. + + The following example shows how this gradient can be applied to a background + element: + + \l{css3_gradientBack}{\inlineimage webkit-guide/scr_css3_gradientBack.png + } + + \l{css3_gradientBack_css}{(CSS)} + + Gradients cannot be applied to the \c{body} element. Instead, they are here + applied to an element that covers the background. + + You can specify more than one gradient for the same element. The following + shifts from a dark to a light gray halfway down the element, then back to + dark: + + \code + background: -webkit-gradient(linear, center top, center bottom, + from(#777777), color-stop(50%, #dddddd), to(#777777) ); + \endcode + + Here is how the additional \c{color-stop} appears when applied to the same + background element: + + \l{css3_gradientBackStop}{\inlineimage webkit-guide/scr_css3_gradientBackStop.png + } + + \l{css3_gradientBackStop_css}{(CSS)} + + Gradients can also provide a textured, three-dimensional appearance for + buttons. In the following example, the gradient is inverted and darkened + when each button is pressed: + + \l{css3_gradientButton}{\inlineimage webkit-guide/scr_css3_gradientButton.png + } + + \l{css3_gradientButton_css}{(CSS)} + + In addition to linear gradients, CSS3 also specifies \bold{radial} gradients + that emanate from a single point. The following example demonstrates a + colorful radial gradient used to mark where users touch the screen: + + \l{css3_grad-radial}{\inlineimage webkit-guide/scr_css3_grad-radial.png + } + + \l{css3_grad-radial_css}{(CSS)} + \l{css3_grad-radial_js}{(JavaScript)} + + The syntax is slightly different than for linear gradients. The first two + comma-separated arguments after the \c{radial} statement specify the + coordinates of the inner circle, and its radius. The next two arguments + specify the coordinates and radius of the outer circle: + + \code + background: -webkit-gradient(radial, 90 120, 5, 100 130, 48, + from(#777777), color-stop(50%, #dddddd), to(#777777) ); + \endcode + + The use of \c{from}, \c{to} values and \c{color-stop} in radial gradients + are the same as for linear gradients. + + \section2 Reflections + + Reflections offer a mirror-like effect which, in the following example, adds + a sense of weight to headings and images: + + \l{css3_reflect}{\inlineimage webkit-guide/scr_css3_reflect.png + } + + \l{css3_reflect_css}{(CSS)} + + The property's syntax specifies the edge of the element at which to reflect, + the offset, and an overlay color. In this case, the color is a gradient, + which causes the reflection to gradually fade: + + \code + -webkit-box-reflect : below -0.25em -webkit-gradient(linear, center + top, center bottom, from(transparent), color-stop(0.25, + transparent), to(black)); + \endcode + + \section2 Masks + + Masks offer a way to modify an image by overlaying either another image, or + a gradient. The following example shows a series of thumbnail images that + appear faded at their bottom edge until selected: + + \l{css3_mask-grad}{\inlineimage webkit-guide/scr_css3_mask-grad.png + } + + \l{css3_mask-grad_css}{(CSS)} + \l{css3_mask-grad_js}{(JavaScript)} + + The gradient's opacity shifts from \c 1 to \c 0, an effect that translates + to the image: + + \code + -webkit-mask-box-image : -webkit-gradient(linear, left top, left + bottom, from(rgba(0, 0, 0, 1)), to(rgba(0, 0, 0, 0))); + \endcode + + The following example demonstrates an image used as a mask to frame another + image: + + \l{css3_mask-img}{\inlineimage webkit-guide/scr_css3_mask-img.png + } + + \l{css3_mask-img_css}{(CSS)} + + Separately, the component images look like these: + + \inlineimage webkit-guide/mask0.png + \inlineimage webkit-guide/mask1.png + + + The syntax is the same for border images, and allows you to stretch one + image over the other: + + \code + -webkit-mask-box-image : url(img/mask.png) 5% stretch; + \endcode + +\section1 Dynamic CSS + +Animations help enhance touch-based mobile interfaces in many ways. They help +ease transitions from one display state to another that might otherwise appear +jarring. They help provide a sense of navigational orientation. They also often +simulate tactile feedback as users' touches result in a tangible visual effect. +Overall, they add a sense of vibrancy that increases users' engagement with the +content on display. + +Support by QtWebKit for HTML5 allows you to choose from among several flavors of +web-based animation: Canvas, SVG, and Level 3 CSS. Web developers may also be +familiar with lower-level JavaScript-based animation techniques, which form the +basis of many popular JavaScript libraries such as jQuery and Prototype. This +section focuses on CSS-based animations, since they are more appropriate to +integrate throughout a web design, without the additional overhead JavaScript +libraries require. Like Adobe Flash, SVG and Canvas offer more specialized, +low-level graphics frameworks whose animation features are more appropriate for +generating standalone effects. + +This section demonstrates animation techniques by offering a series of examples +that apply to common mobile design tasks. While some of these tasks are +addressed by existing JavaScript frameworks such as jQuery and Prototype, the +examples provided here illustrate some CSS-only alternatives. + + \section2 CSS Animation Concepts + + Level 3 CSS introduces three distinct concepts that are relevant when + crafting dynamic effects, which are discussed in the following sections: + + \list + \o \e{Transforms} offer a series of manipulations to screen elements. By + themselves, transforms present only static visual effects, but they become + especially useful as part of dynamic transitions and animations. Simple + transforms are two-dimensional, with three-dimensional transforms gaining + gradual support. + + \o \e{Transitions} entail a graduated shift from one explicit display + state to another. Transitional shifts apply to any CSS property that + specifies numeric or color values. + + \o \e{Animations} offer more complex sequences of transitions that can + specify many intermediate display states. Unlike simple transitions, + animations can also be initiated more freely. + \endlist + + \section2 2D Transforms + + Transforms allow you to freely displace box elements from where they would + ordinarily appear. Several transform functions are available, allowing you + to \e{scale}, \e{rotate}, \e{skew}, or \e{translate} (move) objects. + + The \c{translate} function moves an element from its default location, and + accepts \c{x} and \c{y} measurements as arguments. The following moves an + element off the right edge of the screen: + + \code + -webkit-transform: translate(120%, 0); + \endcode + + Alternately, \c{translateX} and \c{translateY} functions allow you to + specify each axis independently. This moves the element off the top of the + screen: + + \code + -webkit-transform: translateX(0.0) translateY(-120%); + \endcode + + Scale transforms allow you enlarge or shrink an element, with the scale + expressed as a decimal. By itself, \c{scale} modifies height and width + proportionately, but the alternative \c{scaleX} and \c{scaleY} functions + allow you to constrain scaling to a single axis. + + The following animation demonstrates a \c{translate} function, which moves + the element from off the screen, followed by series of \c{scale}, + \c{scaleX}, and \c{scaleY} functions: + + \l{anim_demo-scale}{\inlineimage webkit-guide/scr_anim_demo-scale.png + } + + \l{anim_demo-scale_css}{(CSS)} + + By default, transforms originate from the center of the element, but you can + specify any edge using the \c{-webkit-transform-origin} property. The + following reduces an element to 75% of its original size, while keeping it + at its original bottom edge: + + \code + -webkit-transform : scale(0.75); + -webkit-transform-origin : bottom; + \endcode + + The following example uses this scale transform to shrink icons that are + assigned to in-line links, with icons aligning to the text's baseline: + + \l{layout_link-fmt}{\inlineimage webkit-guide/scr_layout_link-fmt.png + } + + \l{layout_link-fmt_css}{(CSS)} + + The \c{rotate} function accepts degree or radian arguments, with negative + arguments specifying counter-clockwise motion. The following animation + demonstrates two rotations: the first clockwise around the element's center + point, and the second counter-clockwise around the top left corner: + + \l{anim_demo-rotate}{\inlineimage webkit-guide/scr_anim_demo-rotate.png + } + + \l{anim_demo-rotate_css}{(CSS)} + + The \c{skew} function also accepts positive or negative degree arguments, + specifying the extent to which to modify the bottom left corner's 90-degree + angle. The \c{skew} and \c{skewX} functions shift the element horizontally, + but the alternative \c{skewY} function shifts the element vertically. The + following animation demonstrates a \c{skewX} followed by a \c{skewY}: + + \l{anim_demo-skew}{\inlineimage webkit-guide/scr_anim_demo-skew.png + } + + \l{anim_demo-skew_css}{(CSS)} + + In the following example, a variety of transforms make a set of three + navigational tab icons appear to be part of a cube: + + \l{anim_tabbedSkew}{\inlineimage webkit-guide/scr_anim_tabbedSkew.png + } + + \l{anim_tabbedSkew_css}{(CSS)} + + The example also implements the tab icons as internal links that activate + display of content using the \c{:target} dynamic class. See the + \l{Navigational Selectors} section for more information. + + Note that transforms can include any combination of the functions described + above: + + \code + nav > a:nth-of-type(3) { + background-image : url(img/S_google.jpg); + -webkit-transform : rotate(-60deg) skew(-30deg) translate(1.7em, 0em); + } + \endcode + + \section2 Transitions + + Transitions allow you to gradually shift from one defined CSS state to + another. Any CSS property expressed as a numeric or color value (including a + color name or hex value) can be transitioned between two style sheets. + Properties such as \c{display} that have discrete sets of named values, such + as the \c{display} property's \c{block} or \c{none} values, cannot be + transitioned. In cases where named values translate internally to numeric + values, such as the \c{border-width} property's \c{thin} and \c{thick} + values, they can be transitioned. + + The following example shows a series of transitions from a collapsed icon + state to an expanded panel: + + \l{anim_panel}{\inlineimage webkit-guide/scr_anim_panel.png + } + + \l{anim_panel_css}{(CSS)} + \l{anim_panel_js}{(JavaScript)} + + Each style sheet specifies a different \c{max-width} value, and each + accompanying transition, defined separately for each state, allows the value + to shift over the course of half of a second: + + \code + nav.expanded { + max-width : 95%; + -webkit-transition : max-width 0.5s ease-in-out; + } + nav.collapsed { + max-width : 10%; + -webkit-transition : max-width 0.5s ease-in-out; + } + \endcode + + That shorthand syntax can be expanded to several different properties: + + \code + nav.expanded { + max-width : 95%; + -webkit-transition-property : max-width; + -webkit-transition-duration : 0.5s; + -webkit-transition-timing-function : ease-in-out; + } + nav.collapsed { + max-width : 10%; + -webkit-transition-property : max-width; + -webkit-transition-duration : 0.5s; + -webkit-transition-timing-function : ease-in-out; + } + \endcode + + Available transition functions include \c{linear}, \c{ease-in}, + \c{ease-out}, \c{ease-in-out} and \c{cubic-bezier}. + + Note that the \c{max-width} properties in both style sheets both use + percentages to specify measurements. Transitions may not work properly if + you shift from one unit to another. + + The example above specifies an additional set of transitions affecting the + icons nested within the navigation panel: + + \code + nav.expanded > .option { + opacity : 1; + -webkit-transform : scale(1.0); + -webkit-transition : all 0.5s linear; + } + nav.collapsed > .option { + opacity : 0; + -webkit-transform : scale(0.0); + -webkit-transition : all 0.5s linear; + } + \endcode + + The shifting \c{scale} transform makes icons appear to zoom in to fill the + space, while \c{opacity} makes them fade in. Specifying \c{all} as the + transition property applies to any valid property that differs between the + two states. + + These nested transitions execute at the same time as those assigned to the + parent \c{nav} element. The combined effect appears to be a single + transition. + + \section2 Transitional Sequences + + The prior example showed a single transition, but transitions can also be + run in sequence to form more complex animations. The following example + demonstrates an embedded navigation panel that, when pressed, expands + horizontally, then vertically to reveal numerous navigation options: + + \l{anim_accord}{\inlineimage webkit-guide/scr_anim_accord.png + } + + \l{anim_accord_css}{(CSS)} + \l{anim_accord_js}{(JavaScript)} + + The style sheets specify separate, comma-separated transitions for \c{width} + and \c{height} properties: + + \code + #accordion.expanded { + width: 80%; + height: 90%; + -webkit-transition: + width 0.5s ease-in-out 0.0s, + height 0.5s ease-in-out 0.5s + ; + } + #accordion.collapsed { + width: 10%; + height: 7%; + -webkit-transition: + height 0.5s ease-in-out 0.0s, + width 0.5s ease-in-out 0.5s + ; + } + \endcode + + Each transition's additional time measurement specifies a delay. The + long-form syntax may make this clearer: + + \code + #accordion.expanded { + width: 80%; + height: 90%; + -webkit-transition-property : width , height; + -webkit-transition-duration : 0.5s , 0.5s; + -webkit-transition-timing-function : ease-in-out , ease-in-out; + -webkit-transition-delay : 0.0s , 0.5s; + } + #accordion.collapsed { + width : 10%; + height : 7%; + -webkit-transition-property : height , width; + -webkit-transition-duration : 0.5s , 0.5s; + -webkit-transition-timing-function : ease-in-out , ease-in-out; + -webkit-transition-delay : 0.0s , 0.5s; + } + \endcode + + The shift to the \c{expanded} state involves two transitions, each of which + lasts half a second and relies on the same \c{ease-in-out} function. The + first takes place immediately and affects the \c{width} property. The + second, affecting the \c{height} property, takes place after a delay that + matches the first transition's duration. The reverse transition is much the + same, only the \c{height} property transitions before the \c{width} to + reverse the effect. + + In addition to the navigation element's sequence of transitions, nested + accordion-style animations activate when users expand top-level headings. + Subheadings are revealed using a \c{scaleY} transform, which makes them + appear as if they are flipping upwards. + + The following example shows a photo gallery interface that uses the same + techniques. (Size the window to emulate a smaller mobile screen.) + + \l{anim_gallery}{\inlineimage webkit-guide/scr_anim_gallery.png + } + + \l{anim_gallery_css}{(CSS)} + \l{anim_gallery_js}{(JavaScript)} + + The main interface uses simple transitions affecting \c{opacity}, along with + \c{scale} and \c{translate} transforms, which combined make queued images + appear dimmer, smaller, and horizontally offset from the main image. + + A separate sequence of transitions activates when users tap selected images. + The first transition uses a \c{scaleX} transform to flip the image towards + the center. The second then flips out a panel featuring details on the + photo. When users navigate away to adjacent photos, the panel automatically + flips back to its original state as it is moved to the side. + + Another example shows an interface featuring a simple list of items: + + \l{anim_skew}{\inlineimage webkit-guide/scr_anim_skew.png + } + + \l{anim_skew_css}{(CSS)} + \l{anim_skew_js}{(JavaScript)} + + When dismissed, items are wiped off the screen using a \c{skew} transform + that provides the illusion of speed. Remaining items move upwards to fill + the space vacated by items that have been removed. + + This example uses the same technique of sequential transitions. The first + transition applies to the combined \c{translate}/\c{skew} transform. The + second, delayed transition modifies the \c{top} property to align remaining + items to a grid. + + Note that for items to reposition themselves in this example, a vertical + grid must be explicitly specified. You can only apply transitions between + properties you explicitly define and activate, not between values the + browser assigns internally to automatically position elements relative to + each other. + + \section2 Keyframe Animations + + The previous section showed how you can chain sequences of transitions to + produce complex effects. Animations also allow you to define many + intermediary interface states, but using a far simpler syntax, and not + assigned to transitions between CSS states. + + The following example shows a simple animation of icons that pulse when + selected: + + \l{anim_pulse}{\inlineimage webkit-guide/scr_anim_pulse.png + } + + \l{anim_pulse_css}{(CSS)} + + It uses the following CSS, shown here in both abbreviated and long form: + + \code + nav > a:target { -webkit-animation : pulse 1s infinite; } + + nav > a:target { + -webkit-animation-name : pulse; + -webkit-animation-duration : 1s; + -webkit-animation-iteration-count : infinite; + } + \endcode + + You supply a \c{name} for the animation that corresponds to a + \c{keyframes} rule defined separately within your CSS: + + \code + @-webkit-keyframes pulse { + 0% { opacity : 1.0 } + 50% { opacity : 0.7 } + } + \endcode + + Percentages mark new animation states within the course of the animation, + and behave much like CSS selectors. In this case, the animation shifts + between two separate states over the course of a second: opaque and slightly + dimmed. With its \c{iteration-count} set to \c{infinite} rather than a set + number, the animation only stops when the link is no longer selected. + + The following example demonstrates a popular mobile design pattern + implemented with CSS. Navigation to nested subheads appears to wipe to the + right, while navigating upwards in the hierarchy appears to wipe to the + left: + + \l{anim_slide1}{\inlineimage webkit-guide/scr_anim_slide1.png + } + + \l{anim_slide_css}{(CSS)} + + It relies on keyframes rules such as the following, which define a simple + start and end state: + + \code + @-webkit-keyframes slide_in { + from { + left : 80%; + right : -80%; + } + to { + left : 0em; + right : 0em; + } + } + \endcode + + Unlike a transition, the animation is triggered immediately when the page + loads, but only if the target of navigation is an anchor whose ID is + \c{in} or \c{out}. If you navigate to the page itself, no animation + occurs. + + The following example uses a keyframe animation to scroll through banner + options at the top of the screen: + + \l{css3_multicol}{\inlineimage webkit-guide/scr_css3_multicol.png + } + + \l{css3_multicol_css}{(CSS)} + + The animation defines a set of rapid shifts alternating with long static + phases. It modifies the left offset of an element that is five times the + width of the window. + + \code + @-webkit-keyframes banner_scroll { + 0% { left : 0%; } + 18% { left : 0%; } + 20% { left : -100%; } + 38% { left : -100%; } + 40% { left : -200%; } + 58% { left : -200%; } + 60% { left : -300%; } + 78% { left : -300%; } + 80% { left : -400%; } + 95% { left : -400%; } + 100% { left : 0%; } + } + \endcode + + Finally, the demonstrations of \l{anim_demo-rotate}{rotate}, + \l{anim_demo-scale}{scale}, and \l{anim_demo-skew}{skew} 2D transforms that + opened this section all rely on separate keyframe animations to slide in and + manipulate a series of panels. Separate \c{-webkit-animation-delay} settings + for each panel control the sequence of each presentation. + + +\list +\o \l{QtWebKit Guide} -back to the main page +\endlist +*/ + +/*! +\example webkit/webkit-guide +\title QtWebKit Guide Files +This is a listing of \l{QtWebKit Guide} code. +\note The links to the HTML5 code is found within the guide. +*/ + diff --git a/doc/src/webkit/guide/guidelinks.qdoc b/doc/src/webkit/guide/guidelinks.qdoc new file mode 100644 index 0000000..b4f7f98 --- /dev/null +++ b/doc/src/webkit/guide/guidelinks.qdoc @@ -0,0 +1,488 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the Qt WebKit module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\externalpage webkit-guide/storage.htm +\title ex_storage +*/ + +/*! +\externalpage webkit-webkit-guide-css-storage-css.html +\title storage_css +*/ + +/*! +\externalpage webkit-webkit-guide-js-storage-js.html +\title storage_js +*/ + +/*! +\externalpage webkit-guide/anim_accord.htm +\title anim_accord +*/ + +/*! +\externalpage webkit-guide/anim_demo-rotate.htm +\title anim_demo-rotate +*/ + +/*! +\externalpage webkit-guide/anim_demo-scale.htm +\title anim_demo-scale +*/ + +/*! +\externalpage webkit-guide/anim_demo-skew.htm +\title anim_demo-skew +*/ + +/*! +\externalpage webkit-guide/anim_gallery.htm +\title anim_gallery +*/ + +/*! +\externalpage webkit-guide/anim_panel.htm +\title anim_panel +*/ + +/*! +\externalpage webkit-guide/anim_pulse.htm +\title anim_pulse +*/ + +/*! +\externalpage webkit-guide/anim_skew.htm +\title anim_skew +*/ + +/*! +\externalpage webkit-guide/anim_slide1.htm +\title anim_slide1 +*/ + +/*! +\externalpage webkit-guide/anim_tabbedSkew.htm +\title anim_tabbedSkew +*/ + +/*! +\externalpage webkit-guide/css3_backgrounds.htm +\title css3_backgrounds +*/ + +/*! +\externalpage webkit-guide/css3_border-img.htm +\title css3_border-img +*/ + +/*! +\externalpage webkit-guide/css3_grad-radial.htm +\title css3_grad-radial +*/ + +/*! +\externalpage webkit-guide/css3_gradientBack.htm +\title css3_gradientBack +*/ + +/*! +\externalpage webkit-guide/css3_gradientBackStop.htm +\title css3_gradientBackStop +*/ + +/*! +\externalpage webkit-guide/css3_gradientButton.htm +\title css3_gradientButton +*/ + +/*! +\externalpage webkit-guide/css3_mask-grad.htm +\title css3_mask-grad +*/ + +/*! +\externalpage webkit-guide/css3_mask-img.htm +\title css3_mask-img +*/ + +/*! +\externalpage webkit-guide/css3_multicol.htm +\title css3_multicol +*/ + +/*! +\externalpage webkit-guide/css3_reflect.htm +\title css3_reflect +*/ + +/*! +\externalpage webkit-guide/css3_scroll.htm +\title css3_scroll +*/ + +/*! +\externalpage webkit-guide/css3_sel-nth.htm +\title css3_sel-nth +*/ + +/*! +\externalpage webkit-guide/css3_text-overflow.htm +\title css3_text-overflow +*/ + +/*! +\externalpage webkit-guide/css3_text-shadow.htm +\title css3_text-shadow +*/ + +/*! +\externalpage webkit-guide/css3_text-stroke.htm +\title css3_text-stroke +*/ + +/*! +\externalpage webkit-guide/form_tapper.htm +\title form_tapper +*/ + +/*! +\externalpage webkit-guide/form_toggler.htm +\title form_toggler +*/ + +/*! +\externalpage webkit-guide/layout_link-fmt.htm +\title layout_link-fmt +*/ + +/*! +\externalpage webkit-guide/layout_tbl-keyhole.htm +\title layout_tbl-keyhole +*/ + +/*! +\externalpage webkit-guide/mob_condjs.htm +\title mob_condjs +*/ + +/*! +\externalpage webkit-guide/mob_layout.htm +\title mob_layout +*/ + +/*! +\externalpage webkit-guide/mob_mediaquery.htm +\title mob_mediaquery +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-accord-css.html +\title anim_accord_css +*/ + +/*! +\externalpage wwebkit-webkit-guide-js-anim-accord-js.html +\title anim_accord_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-demo-rotate-css.html +\title anim_demo-rotate_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-demo-scale-css.html +\title anim_demo-scale_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-demo-skew-css.html +\title anim_demo-skew_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-gallery-css.html +\title anim_gallery_css +*/ + +/*! +\externalpage webkit-webkit-guide-js-anim-gallery-js.html +\title anim_gallery_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-panel-css.html +\title anim_panel_css +*/ + +/*! +\externalpage webkit-webkit-guide-js-anim-panel-js.html +\title anim_panel_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-pulse-css.html +\title anim_pulse_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-skew-css.html +\title anim_skew_css +*/ + +/*! +\externalpage webkit-webkit-guide-js-anim-skew-js.html +\title anim_skew_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-slide-css.html +\title anim_slide_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-anim-tabbedskew-css.html +\title anim_tabbedSkew_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-form-tapper-css.html +\title form_tapper_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-form-toggler-css.html +\title form_toggler_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-layout-link-fmt-css.html +\title layout_link-fmt_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-layout-tbl-keyhole-css.html +\title layout_tbl-keyhole_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-backgrounds-css.html +\title css3_backgrounds_css +*/ + +/*! +\externalpage webkit-webkit-guide-js-css3-backgrounds-js.html +\title css3_backgrounds_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-border-img-css.html +\title css3_border-img_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-grad-radial-css.html +\title css3_grad-radial_css +*/ + +/*! +\externalpage webkit-webkit-guide-js-css3-grad-radial-js.html +\title css3_grad-radial_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-gradientback-css.html +\title css3_gradientBack_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-gradientbackstop-css.html +\title css3_gradientBackStop_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-gradientbutton-css.html +\title css3_gradientButton_css +*/ + +/*! +\externalpage webkit-guide/css/webkit-webkit-guide-css-css3-mask-grad-css.html +\title css3_mask-grad_css +*/ + +/*! +\externalpage webkit-guide/js/webkit-webkit-guide-js-css3-mask-grad-js.html +\title css3_mask-grad_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-mask-img-css.html +\title css3_mask-img_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-multicol-css.html +\title css3_multicol_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-reflect-css.html +\title css3_reflect_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-scroll-css.html +\title css3_scroll_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-sel-nth-css.html +\title css3_sel-nth_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-text-overflow-css.html +\title css3_text-overflow_css +*/ + +/*! +\externalpage webkit-webkit-guide-js-css3-text-overflow-js.html +\title css3_text-overflow_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-text-shadow-css.html +\title css3_text-shadow_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-css3-text-stroke-css.html +\title css3_text-stroke_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-mob-condjs-css.html +\title mob_condjs_css +*/ + +/*! +\externalpage webkit-webkit-guide-js-mob-condjs-js.html +\title mob_condjs_js +*/ + +/*! +\externalpage webkit-webkit-guide-css-mqlayout-desktop-css.html +\title mqlayout_desktop_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-mqlayout-touch-css.html +\title mqlayout_touch_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-mqlayout-mobile-css.html +\title mqlayout_mobile_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-mq-desktop-css.html +\title mq_desktop_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-mq-touch-css.html +\title mq_touch_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-mq-mobile-css.html +\title mq_mobile_css +*/ + +/*! +\externalpage webkit-webkit-guide-css-mob-mediaquery-css.html +\title mob_mediaquery_css +*/ + +/*! +\externalpage http://deviceatlas.com/ +\title DeviceAtlas +*/ + +/*! +\externalpage http://wurfl.sourceforge.net/ +\title WURFL +*/ + +/*! +\externalpage http://www.w3.org/TR/selectors-api/ +\title Selectors API +*/ + +/*! +\externalpage http://dev.w3.org/html5/webstorage/ +\title HTML5 Web Storage +*/ + +/*! +\externalpage http://html5doctor.com/introducing-web-sql-databases +\title HTML5 Doctor: Introducing Web SQL Databases +*/ + +/*! +\externalpage http://dev.w3.org/html5/canvas-api/canvas-2d-api.html +\title HTML5 Canvas API +*/ + +/*! +\externalpage http://www.w3schools.com/css/css_colors.asp +\title CSS Color Value +*/ + +/*! +\externalpage http://www.w3.org/TR/2003/CR-css3-color-20030514/#numerical +\title CSS3 Color Module specification +*/ + +/*! +\externalpage http://www.canvasdemos.com/2009/10/09/html-5-canvas-animation +\title CanvasDemos.com: animated cartoon +*/ diff --git a/doc/src/webkit/webkit.qdoc b/doc/src/webkit/webkit.qdoc new file mode 100644 index 0000000..759a7f7 --- /dev/null +++ b/doc/src/webkit/webkit.qdoc @@ -0,0 +1,103 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the Qt WebKit module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! +\page qtwebkit-guide.html + +\title QtWebKit Guide + +\section1 Introduction to QtWebKit + +Qt WebKit is a web content rendering engine based on the open source +WebKit project, featuring broad support for standard web technologies. +QtWebKit is developed as a part of the WebKit community, +which enables every new release of Qt WebKit +to include the latest developments from the WebKit project. + +Qt SDK 1.1 supports the following Qt WebKit releases: + +\list +\o QtWebKit 2.1 for Symbian^3 when using Qt 4.7. +\o QtWebKit 2.0, as a standard part of Qt 4.7, +for all other platforms when using Qt 4.7. +\o When using Qt 4.6, +the QtWebKit version of Qt 4.6 is used on all platforms. +\endlist + +\section1 QtWebKit 2.1 for Web Developers + +The highlights of the QtWebKit 2.1 release for web developers +are listed below. +Please note that HTML5 and CSS3 features are based on draft +specifications that are subject to change. + +\list +\o HTML5 progress and meter elements +\o HTML5 canvas element +\o Web SQL Database +\o Web Storage +\o CSS Animations +\o CSS Transitions +\o CSS 2D Transforms +\o CSS Text +\o CSS Masks +\o CSS Scrollbar Styles +\o Native JSON parser +\endlist + +\section1 Qt WebKit Module + +Information regarding the classes and API introduced in the Qt WebKit module +are found in the \l{WebKit in Qt} page. + +\section1 Mobile HTML5 Developer's Guide for QtWebKit (BETA) + +This is a beta release of a guide for mobile web development with +QtWebKit 2.1. It discusses how to use several standard web +technologies to create mobile applications with QtWebKit. + +Contents: +\list +\o \l{QtWebKit Guide - Level 3 CSS}{Level 3 CSS: media queries, selectors, visual +effects, transforms, transitions, and animations} +\o \l{Canvas Graphics}{HTML5 canvas element} +\o \l{QtWebKit Guide - Client Storage}{Client Storage} +\endlist +*/ + |
