diff options
Diffstat (limited to 'doc/src')
99 files changed, 4723 insertions, 233 deletions
diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 8d8e6c6..93571bd 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -116,6 +116,8 @@ Qt applications. \o \l{QML Modules} \o \l{QML Documents} \o \l{QML Global Object} +\o \l{QML Internationalization} +\o \l{QML Right-to-left User Interfaces} \o \l{QML Security} \o \l{Qt Declarative Module} \endlist diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index 7c10760..90fb715 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -69,12 +69,14 @@ a \l Component object from this URL. Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of the component. This function can take one or two arguments: \list -\o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is - recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to - this function. -\o The second is optional and is a script which assigns values to the item's properties during creation. This avoids warnings - when certain properties have been bound to before they have been set by the code. Additionally, there are small performance - benefits when instantiating objects in this way. +\o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is + recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to + this function. +\o The second is optional and is a map of property-value items that define initial any property values for the item. + Property values specified by this argument are applied to the object before its creation is finalized, avoiding + binding errors that may occur if particular properties must be initialized to enable other property bindings. + when certain properties have been bound to before they have been set by the code. Additionally, there are small + performance benefits when compared to defining property values and bindings after the object is created. \endlist Here is an example. First there is \c Sprite.qml, which defines a simple QML component: diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index 873d0de..8fb64c1 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -77,6 +77,7 @@ To see the QML elements listed by functional area, see the \o \l {FocusScope} - Element that mediate keyboard focus changes \o \l {Flickable} - Provides a surface that can be "flicked" \o \l {Flipable} - Provides a surface that produces "flipping" effects +\o \l {PinchArea} - Enables simple pinch gesture handling \endlist \section1 Positioners and Repeater diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index 06bd819..b7420e0 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -136,8 +136,7 @@ The examples can be found in Qt's \c examples/declarative directory. \section2 Positioners \list -\o \l{declarative/positioners/addandremove}{Adding and Removing Items} -\o \l{declarative/positioners/layoutdirection}{Layout Direction} +\o \l{declarative/positioners}{Example} \endlist \section2 Key Interaction @@ -197,13 +196,20 @@ The examples can be found in Qt's \c examples/declarative directory. \o \l{declarative/i18n}{Example} \endlist +\section2 Right-to-left User Interfaces +\list +\o \l{declarative/righttoleft/layoutmirroring}{Layout mirroring} +\o \l{declarative/righttoleft/layoutdirection}{Layout direction} +\o \l{declarative/righttoleft/textalignment}{Text alignment} +\endlist + \section2 Threading \list \o \l{declarative/threading/threadedlistmodel}{Threaded ListModel} \o \l{declarative/threading/workerscript}{WorkerScript} \endlist -\section2 Screen orientation +\section2 Screen Orientation \list \o \l{declarative/screenorientation}{Example} \endlist diff --git a/doc/src/declarative/pics/layoutmirroring.png b/doc/src/declarative/pics/layoutmirroring.png Binary files differnew file mode 100644 index 0000000..df90ac4 --- /dev/null +++ b/doc/src/declarative/pics/layoutmirroring.png diff --git a/doc/src/declarative/qdeclarativeperformance.qdoc b/doc/src/declarative/qdeclarativeperformance.qdoc index 36b4878..6760869 100644 --- a/doc/src/declarative/qdeclarativeperformance.qdoc +++ b/doc/src/declarative/qdeclarativeperformance.qdoc @@ -136,4 +136,15 @@ The QML Viewer uses the raster graphics system by default for X11 and OS X. It a includes a \c -opengl command line option which sets a QGLWidget as the viewport of the view. On OS X, a QGLWidget is always used. +You can also prevent QDeclarativeView from painting its window background if +you will provide the background of your application using QML, e.g. + +\code +QDeclarativeView window; +window.setAttribute(Qt::WA_OpaquePaintEvent); +window.setAttribute(Qt::WA_NoSystemBackground); +window.viewport()->setAttribute(Qt::WA_OpaquePaintEvent); +window.viewport()->setAttribute(Qt::WA_NoSystemBackground); +\endcode + */ diff --git a/doc/src/declarative/qmlinuse.qdoc b/doc/src/declarative/qmlinuse.qdoc index 7380ef5..131be1b 100644 --- a/doc/src/declarative/qmlinuse.qdoc +++ b/doc/src/declarative/qmlinuse.qdoc @@ -207,7 +207,7 @@ <li><a href="qml-flipable.html">Flipable Element</a> - The Flipable item provides a surface that can be flipped or reflected.</li> <li><a href="qml-focuspanel.html">FocusPanel Element</a> - The FocusPanel item explicitly creates a focus panel.</li> <li><a href="qml-focusscope.html">FocusScope Element</a> - The FocusScope object explicitly creates a focus scope for focus management.</li> - <li><a href="qml-gesturearea.html">GestureArea Element</a> - The GestureArea item enables simple gesture handling.</li> + <li><a href="qml-pincharea.html">PinchArea Element</a> - The PinchArea item enables simple pinch gesture handling.</li> <li><a href="qml-keynavigation.html">KeyNavigation Element</a> - The KeyNavigation attached property supports key navigation by arrow keys.</li> <li><a href="qml-keys.html">Keys Element</a> - The Keys attached property provides key handling to Items.</li> <li><a href="qml-mousearea.html">MouseArea Element</a> - The MouseArea item enables simple mouse handling.</li> diff --git a/doc/src/declarative/righttoleft.qdoc b/doc/src/declarative/righttoleft.qdoc new file mode 100644 index 0000000..7db6136 --- /dev/null +++ b/doc/src/declarative/righttoleft.qdoc @@ -0,0 +1,195 @@ +/**************************************************************************** +** +** 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-righttoleft.html +\title QML Right-to-left User Interfaces + +\section1 Overview + +This chapter discusses different approaches and options available for implementing right-to-left +language support for Qt Quick applications. Some common right-to-left languages include Arabic, Hebrew, +Persian and Urdu. Most changes include making sure that text translated to right-to-left languages +is properly aligned to the right, and horizontally ordered content in views, lists and grids flows +correctly from the right to left. + +In right-to-left language speaking cultures, people naturally scan and read graphic elements and text +from the right to left. The general rule of thumb is that content (like photos, videos and maps) is not +mirrored, but positioning of the content (like application layouts and the flow of visual elements) is +mirrored. For example, photos shown in chronological order should flow from right to left, the +low end range of the horizontal sliders should be located at the right side of the slider, and +text lines should should be aligned to the right side of the available text area. The location of visual +elements should not be mirrored when the position is related to a content; for example, when a +position marker is shown to indicate a location on a map. Also, there are some special cases you may +need to take into account where right-to-left language speakers are used to left-to-right +positioning, for example when using number dialers in phones and media play, pause, rewind and +forward buttons in music players. + +\section1 Text Alignment + +(This applies to the \l Text, \l TextInput and \l TextEdit elements.) + +When the horizontal alignment of a text item is not explicitly set, the text element is +automatically aligned to the natural reading direction of the text. By default left-to-right text +like English is aligned to the left side of the text area, and right-to-left text like Arabic is +aligned to the right side of the text area. The alignment of a text element with empty text takes +its alignment cue from \l QApplication::keyboardInputDirection(), which is based on the active +system locale. + +This default locale-based alignment can be overriden by setting the \c horizontalAlignment +property for the text element, or by enabling layout mirroring using the \l LayoutMirroring attached +property, which causes any explicit left and right horizontal alignments to be mirrored. +Note that when \l LayoutMirroring is set, the \c horizontalAlignment property value remains unchanged; +the effective alignment of the text element that takes the mirroring into account can be read from the +\c effectiveHorizontalAlignment property. + +\snippet doc/src/snippets/declarative/righttoleft.qml 0 + +\section1 Layout direction of positioners and views + +(This applies to the \l Row, \l Grid, \l Flow, \l ListView and \l GridView elements.) + +From Qt Quick 1.1 onwards, elements used for horizontal positioning and model views have gained a \c layoutDirection +property for controlling the horizontal direction of the layouts. Setting \c layoutDirection to +\c Qt.RightToLeft causes items to be laid out from the right to left. By default Qt Quick follows +the left-to-right layout direction. + +The horizontal layout direction can also be reversed through the \l LayoutMirroring attached property. +This causes the effective \c layoutDirection of positioners and views to be mirrored. Note the actual value +of the \c layoutDirection property will remain unchanged; the effective layout direction of positioners and +views that takes the mirroring into account can be read from the \c effectiveLayoutDirection property. + +\snippet doc/src/snippets/declarative/righttoleft.qml 1 + +\section1 Layout mirroring + +The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left +support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout} +{Item anchors}, the layout direction of \l{Using QML Positioner and Repeater Items}{positioners} and +model views, and the explicit text alignment of QML text elements. + +You can enable layout mirroring for a particular \l Item: + +\snippet doc/src/snippets/declarative/righttoleft.qml 2 + +Or set all child elements to also inherit the layout direction: + +\snippet doc/src/snippets/declarative/righttoleft.qml 3 + +Applying mirroring in this manner does not change the actual value of the relevant anchor, +\c layoutDirection or \c horizontalAlignment properties. The separate read-only property +\c effectiveLayoutDirection can be used to query the effective layout +direction of positioners and model views that takes the mirroring into account. Similarly the \l Text, +\l TextInput and \l TextEdit elements have gained the read-only property \c effectiveHorizontalAlignment +for querying the effective visual alignment of text. For anchors, the read only +\l {Item::anchors}{anchors.mirrored} property reflects whether anchors have been mirrored. + +Note that application layouts and animations that are defined using \l {Item::}{x} property values (as +opposed to anchors or positioner elements) are not affected by the \l LayoutMirroring attached property. +Therefore, adding right-to-left support to these types of layouts may require some code changes to your application, +especially in views that rely on both the anchors and x coordinate-based positioning. Here is one way to use +the \l LayoutMirroring attached property to apply mirroring to an item that is positioned using \l {Item::}{x} +coordinates: + +\snippet doc/src/snippets/declarative/righttoleft.qml 4 + +Not all layouts should necessarily be mirrored. There are cases where a visual element is positioned to +the right side of the screen for improved one-handed use, because most people are right-handed, and not +because of the reading direction. In the case that a child element should not be affected by mirroring, +set the \l {LayoutMirroring::enabled}{LayoutMirroring.enabled} property for that element to false. + +Qt Quick is designed for developing animated, fluid user interfaces. When mirroring your application, remember to test that +the animations and transitions continue to work as expected. If you do not have the resources to add +right-to-left support for your application, it may be better to just keep the application layouts left +aligned and just make sure that text is translated and aligned properly. + +\section1 Mirroring icons + +(This applies to \l Image, \l BorderImage and \l AnimatedImage elements.) + +Most images do not need to be mirrored, but some directional icons, such as arrows, may need to be mirrored. +The painting of these icons can be mirrored with a dedicated \c mirror property introduced in Qt Quick 1.1: + +\snippet doc/src/snippets/declarative/righttoleft.qml 5 + +\section1 Default layout direction + +The \l {QML:Qt::application}{Qt.application.layoutDirection} property can be used to query the active layout direction of the +application. It is based on QApplication::layoutDirection(), which most commonly determines the layout +direction from the active language translation file. + +To define the layout direction for a particular locale, declare the dedicated string literal +\c QT_LAYOUT_DIRECTION in context \c QApplication as either "LTR" or "RTL". + +You can do this by first introducing this line + +\code +QT_TRANSLATE_NOOP("QApplication", "QT_LAYOUT_DIRECTION"); +\endcode + +somewhere in your QML source code and calling \c lupdate to generate the translation source file. + +\code +lupdate myapp.qml -ts myapp.ts +\endcode + +This will append the following declaration to the translation file, where you can fill in either "LTR" or +"RTL" as the translation for the locale. + +\code +<context> + <name>QApplication</name> + <message> + <location filename="myapp.qml" line="33"/> + <source>QT_LAYOUT_DIRECTION</source> + <translation type="unfinished">RTL</translation> + </message> +</context> +\endcode + +You can test that the layout direction works as expected by running your Qt Quick application with +the compiled translation file: + +\code +qmlviewer myapp.qml -translation myapp.qm +\endcode + +You can test your application in right-to-left layout direction simply by executing qmlviewer with a +command-line parameter "-reverse": + +\code +qmlviewer myapp.qml -reverse +\endcode + +The layout direction can also be set from C++ by calling the static function \l QApplication::setLayoutDirection(): + +\code +QApplication app(argc, argv); +app.setLayoutDirection(Qt::RightToLeft); +\endcode + +*/ diff --git a/doc/src/declarative/whatsnew.qdoc b/doc/src/declarative/whatsnew.qdoc index f4359f9..6eb1548 100644 --- a/doc/src/declarative/whatsnew.qdoc +++ b/doc/src/declarative/whatsnew.qdoc @@ -29,22 +29,35 @@ \title What's new in Qt Quick \page qtquick-whatsnew.html -\section1 Qt 4.7.3 includes QtQuick 1.1 +\section1 Qt 4.7.4 includes QtQuick 1.1 -QtQuick 1.1 is a minor feature update. +QtQuick 1.1 is a minor feature update. \e {import QtQuick 1.1} to use the new features. \section2 PinchArea PinchArea provides support for the common two finger pinch gesture. +\section2 LayoutMirroring attached property + +\l {LayoutMirroring}{Layout mirroring} is useful when you need to support both left-to-right and right-to-left layout versions of your application that target different language areas. + +\section2 Anchors + +Added the following property: +\list +\o \l {Item::}{anchors.mirrored} +\endlist + \section2 Text Added the following properties: \list -\o lineSpacing -\o lineCount -\o maximumLineCount -\o truncated +\o \l {Text::}{lineHeight} +\o \l {Text::}{lineHeightMode} +\o \l {Text::}{lineCount} +\o \l {Text::}{maximumLineCount} +\o \l {Text::}{truncated} +\o \l {Text::}{effectiveHorizontalAlignment} \endlist horizontalAlignment now accepts Text.AlignJustify alignment mode. @@ -53,85 +66,107 @@ horizontalAlignment now accepts Text.AlignJustify alignment mode. Added the following properties, methods and signal handlers: \list -\o canPaste -\o lineCount -\o deselect() -\o moveCursorSelection(int pos, SelectionMode mode) to enable selection by word -\o onLinkActivated(string link) +\o \l {TextEdit::}{canPaste} +\o \l {TextEdit::}{lineCount} +\o \l {TextEdit::}{inputMethodComposing} +\o \l {TextEdit::}{mouseSelectionMode} +\o \l {TextEdit::}{effectiveHorizontalAlignment} +\o \l {TextEdit::}{deselect()} +\o \l {TextEdit::}{isRightToLeft()} +\o \l {TextEdit::}{moveCursorSelection()} to enable selection by word +\o \l {TextEdit::}{onLinkActivated} \endlist \section2 TextInput Added the following properties and methods: \list -\o canPaste -\o deselect() -\o moveCursorSelection(int pos, SelectionMode mode) to enable selection by word +\o \l {TextInput::}{canPaste} +\o \l {TextInput::}{inputMethodComposing} +\o \l {TextInput::}{mouseSelectionMode} +\o \l {TextInput::}{effectiveHorizontalAlignment} +\o \l {TextInput::}{deselect()} +\o \l {TextInput::}{isRightToLeft()} +\o \l {TextInput::}{moveCursorSelection()} to enable selection by word \endlist \section2 Image, BorderImage and AnimatedImage Added the following properties: \list -\o cache -\o mirror +\o \l{Image::}{cache} +\o \l{Image::}{mirror} \endlist \section2 Item Added the following properties: \list -\o implicitWidth and implicitHeight +\o \l{Item::}{implicitWidth} and \l{Item::}{implicitHeight} \endlist \section2 Flickable Added the following methods: \list -\o resizeContent(qreal w, qreal h, QPointF center) -\o returnToBounds() +\o \l{Flickable::}{resizeContent()} +\o \l{Flickable::}{returnToBounds()} +\endlist + +\section2 MouseArea + +Added the following property: +\list +\o \l{MouseArea::}{preventStealing} \endlist \section2 ListView and GridView -Added the following methods: +Added the following properties and methods: \list -\o positionViewAtBeginning() -\o positionViewAtEnd() +\o \l{ListView::}{layoutDirection} +\o \l{ListView::}{effectiveLayoutDirection} +\o \l{ListView::}{positionViewAtBeginning()} +\o \l{ListView::}{positionViewAtEnd()} \endlist -\section2 Flow, Grid, Row +\section2 Flow, Grid and Row Added the following properties: \list -\o layoutDirection +\o \l{Flow::}{layoutDirection} +\o \l{Flow::}{effectiveLayoutDirection} \endlist \section2 Repeater Added the following methods and signal handlers: \list -\o onItemAdded() -\o onItemRemoved() -\o itemAt(int index) +\o \l{Repeater::}{onItemAdded} +\o \l{Repeater::}{onItemRemoved} +\o \l{Repeater::}{itemAt()} \endlist \section2 Component -The createObject() method now accepts a map of initial property values for the created object. +\list +\o The \l{Component::}{createObject()} method now accepts a map of initial property values for +the created object. +\endlist \section2 Qt -Added the following properties and methods: \list -\o application.layoutDirection -\o application.active +\o Added the \l {QML:Qt::application}{Qt.application} object to hold generic global application +properties. \endlist \section2 Other changes \list -\o Functions can be assigned to properties from JavaScript to create property bindings +\o Functions can be \l{Binding Properties from JavaScript}{assigned to properties from JavaScript} +to create property bindings. +\o QtQuick now supports Right to Left layout in positioners, views, anchors and text elements. \endlist diff --git a/doc/src/demos/guitartuner.qdoc b/doc/src/demos/guitartuner.qdoc new file mode 100644 index 0000000..c669765 --- /dev/null +++ b/doc/src/demos/guitartuner.qdoc @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** 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 + + \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..47241a6 --- /dev/null +++ b/doc/src/demos/mobiledemos.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** 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}. + +*/ + + 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..63ac286 --- /dev/null +++ b/doc/src/demos/qml-qtbubblelevel.qdoc @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** 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 + + \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/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index d4e2a7a..103f474 100644 --- a/doc/src/development/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -1691,8 +1691,7 @@ \section1 INCLUDEPATH This variable specifies the #include directories which should be - searched when compiling the project. Use ';' or a space as the - directory separator. + searched when compiling the project. For example: diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc index dc478b4..68deae7 100644 --- a/doc/src/examples/qml-examples.qdoc +++ b/doc/src/examples/qml-examples.qdoc @@ -271,23 +271,55 @@ */ /*! - \title Positioners: Adding and Removing Items Example - \example declarative/positioners/addandremove + \title Right-to-left User Interfaces: Text Alignment Example + \example declarative/righttoleft/textalignment - This example shows how to use the positioner elements such as \l Row, \l Column, - \l Grid and \l Flow, in particular how to add and remove items with appropriate transitions. + This example shows how the horizontal alignment of \l Text, + \l TextInput and \l TextEdit is affected by the reading direction + of the text and by the layout mirrroring. Click on the gray buttons + shown at the bottom of the example to toggle between different + horizontal alignment options. - \image qml-positioners-example.png + \sa {QML Right-to-left User Interfaces} */ /*! - \title Positioners: Layout Direction Example - \example declarative/positioners/layoutdirection + \title Right-to-left User Interfaces: Layout Direction Example + \example declarative/righttoleft/layoutdirection + + This example shows how to control the horizontal layout direction of + \l Row, \l Grid and \l Flow positioners, and \l ListView and \l GridView + model views. Click on the gray buttons shown at the bottom of the example + to toggle the layout direction of the shown elements. + + \image qml-righttoleft-layoutdirection-example.png + + \sa {QML Right-to-left User Interfaces} +*/ + + +/*! + \title Right-to-left User Interfaces: Layout Mirroring Example + \example declarative/righttoleft/layoutmirroring - This example shows how to control the horizontal layout direction of - \l Row, \l Grid and \l Flow positioners. + This example shows how to mirror the application layouts + using \l LayoutMirroring attached property. Click on the grey button + shown at the bottom of the example to enable or disable the + layout mirroring. - \image qml-positioners-layoutdirection-example.png + \image qml-righttoleft-layoutmirroring-example.png + + \sa {QML Right-to-left User Interfaces} +*/ + +/*! + \title Positioners Example + \example declarative/positioners + + This example shows how to use the positioner elements such as \l Row, \l Column, + \l Grid and \l Flow. + + \image qml-positioners-example.png */ /*! @@ -457,7 +489,7 @@ /*! - \title Screen orientation + \title Screen Orientation \example declarative/screenorientation This example shows how to implement screen orientation support for your application. 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/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/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/qml-righttoleft-layoutdirection-example.png b/doc/src/images/qml-righttoleft-layoutdirection-example.png Binary files differnew file mode 100644 index 0000000..381ecd7 --- /dev/null +++ b/doc/src/images/qml-righttoleft-layoutdirection-example.png diff --git a/doc/src/images/qml-righttoleft-layoutmirroring-example.png b/doc/src/images/qml-righttoleft-layoutmirroring-example.png Binary files differnew file mode 100644 index 0000000..992c876 --- /dev/null +++ b/doc/src/images/qml-righttoleft-layoutmirroring-example.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..90caf06 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,25 +72,39 @@ \div {class="heading"} Develop with Qt \enddiv - \image tools.png \list + \o \l{Getting Started Guides}{Getting Started with Qt} \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} + \o \l{qt-deployment}{Deploying and Publishing Applications to Ovi Store} + \endlist + + \enddiv + \div {class="sectionlist normallist"} + \div {class="heading"} + UI Creation with Qt + \enddiv + + \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 - \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{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} @@ -108,18 +112,6 @@ innovative solutions using Qt. \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 - \endlist - \enddiv \enddiv \enddiv \div {class="indexbox tools"} @@ -137,17 +129,18 @@ 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} \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{external: Qt Mobility Manual}{Qt Mobility APIs} + \o \l{external: Qt Mobility QML Plugins}{Mobility QML Plugins} + \endlist + \list + \o \l{Qt Licenses and Credits} \endlist \enddiv \div {class="sectionlist normallist"} @@ -155,8 +148,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..cafd927 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,25 @@ 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{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 +194,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..d0a5416 100644 --- a/doc/src/qt-webpages.qdoc +++ b/doc/src/qt-webpages.qdoc @@ -24,242 +24,279 @@ ** $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/creator-qml-application.html + \title external: Developing Qt Quick Applications with Creator */ - -/*! - \externalpage http://doc.qt.nokia.com/qtcreator-snapshot/creator-qml-application.html - \title 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 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/snippets/code/doc_src_installation.qdoc b/doc/src/snippets/code/doc_src_installation.qdoc index 1a87566..5aaa2b0 100644 --- a/doc/src/snippets/code/doc_src_installation.qdoc +++ b/doc/src/snippets/code/doc_src_installation.qdoc @@ -250,12 +250,12 @@ export PATH //! [38] cd /home/user/qt/%VERSION% -./configure -platform linux-g++ -xplatform symbian/linux-armcc +./configure -platform linux-g++ -xplatform symbian-armcc //! [38] //! [39] cd /home/user/qt/%VERSION% -./configure -platform linux-g++ -xplatform symbian/linux-gcce -no-webkit +./configure -platform linux-g++ -xplatform symbian-gcce -no-webkit //! [39] //! [40] diff --git a/doc/src/snippets/declarative/arrow.png b/doc/src/snippets/declarative/arrow.png Binary files differnew file mode 100644 index 0000000..f0cae21 --- /dev/null +++ b/doc/src/snippets/declarative/arrow.png diff --git a/doc/src/snippets/declarative/componentCreation.js b/doc/src/snippets/declarative/componentCreation.js index cf59777..7364139 100644 --- a/doc/src/snippets/declarative/componentCreation.js +++ b/doc/src/snippets/declarative/componentCreation.js @@ -32,13 +32,10 @@ function createSpriteObjects() { //![finishCreation] function finishCreation() { if (component.status == Component.Ready) { - sprite = component.createObject(appWindow); + sprite = component.createObject(appWindow, {"x": 100, "y": 100}); if (sprite == null) { // Error Handling - } else { - sprite.x = 100; - sprite.y = 100; - // ... + console.log("Error creating object"); } } else if (component.status == Component.Error) { // Error Handling diff --git a/doc/src/snippets/declarative/layoutmirroring.qml b/doc/src/snippets/declarative/layoutmirroring.qml new file mode 100644 index 0000000..617f39d --- /dev/null +++ b/doc/src/snippets/declarative/layoutmirroring.qml @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ +//![0] +import QtQuick 1.1 + +Rectangle { + LayoutMirroring.enabled: true + LayoutMirroring.childrenInherit: true + + width: 300; height: 50 + color: "yellow" + border.width: 1 + + Row { + anchors { left: parent.left; margins: 5 } + y: 5; spacing: 5 + + Repeater { + model: 5 + + Rectangle { + color: "red" + opacity: (5 - index) / 5 + width: 40; height: 40 + + Text { + text: index + 1 + anchors.centerIn: parent + } + } + } + } +} +//![0] diff --git a/doc/src/snippets/declarative/righttoleft.qml b/doc/src/snippets/declarative/righttoleft.qml new file mode 100644 index 0000000..c2e504a --- /dev/null +++ b/doc/src/snippets/declarative/righttoleft.qml @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 1.1 +import "righttoleft" + +Column { + width: 200 +//![0] +// automatically aligned to the left +Text { + text: "Phone" + width: 200 +} + +// automatically aligned to the right +Text { + text: "خامل" + width: 200 +} + +// aligned to the left +Text { + text: "خامل" + horizontalAlignment: Text.AlignLeft + width: 200 +} + +// aligned to the right +Text { + text: "خامل" + horizontalAlignment: Text.AlignLeft + LayoutMirroring.enabled: true + width: 200 +} +//![0] + +//![1] +// by default child items are positioned from left to right +Row { + Child {} + Child {} +} + +// position child items from right to left +Row { + layoutDirection: Qt.RightToLeft + Child {} + Child {} +} + +// position child items from left to right +Row { + LayoutMirroring.enabled: true + layoutDirection: Qt.RightToLeft + Child {} + Child {} +} +//![1] + +//![2] +Item { + height: 50; width: 150 + + LayoutMirroring.enabled: true + anchors.left: parent.left // anchor left becomes right + + Row { + // items flow from left to right (as per default) + Child {} + Child {} + Child {} + } +} +//![2] + +//![3] +Item { + height: 50; width: 150 + + LayoutMirroring.enabled: true + LayoutMirroring.childrenInherit: true + anchors.left: parent.left // anchor left becomes right + + Row { + // setting childrenInherit in the parent causes these + // items to flow from right to left instead + Child {} + Child {} + Child {} + } +} +//![3] + +//![4] +Rectangle { + color: "black" + height: 50; width: 50 + x: mirror(10) + function mirror(value) { + return LayoutMirroring.enabled ? (parent.width - width - value) : value; + } +} +//![4] + +//![5] +Image { + source: "arrow.png" + mirror: true +} +//![5] +} diff --git a/doc/src/snippets/declarative/righttoleft/Child.qml b/doc/src/snippets/declarative/righttoleft/Child.qml new file mode 100644 index 0000000..48cb295 --- /dev/null +++ b/doc/src/snippets/declarative/righttoleft/Child.qml @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** 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: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$ +** +****************************************************************************/ + +import QtQuick 1.0 + +Rectangle { + width: 50; height: 50 + color: "black" + Text { + color: "white" + text: String.fromCharCode(65 + Math.floor(26*Math.random())) + anchors.centerIn: parent + } +} diff --git a/doc/src/snippets/declarative/states/statechangescript.qml b/doc/src/snippets/declarative/states/statechangescript.qml index b885137..f490a97 100644 --- a/doc/src/snippets/declarative/states/statechangescript.qml +++ b/doc/src/snippets/declarative/states/statechangescript.qml @@ -37,6 +37,7 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ +import QtQuick 1.0 Item { //! [state and transition] 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 +*/ + |
