summaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorJerome Pasion <jerome.pasion@nokia.com>2011-03-21 09:16:35 (GMT)
committerJerome Pasion <jerome.pasion@nokia.com>2011-03-21 09:16:35 (GMT)
commitfd0906bd56add3cd1f1bda502a905a745f48a73f (patch)
treeaec2ef64b3d3b0a506ae82099cbd520efabca975 /doc/src
parent6a0282d87fde1e827e0c6715162e76f347834062 (diff)
downloadQt-fd0906bd56add3cd1f1bda502a905a745f48a73f.zip
Qt-fd0906bd56add3cd1f1bda502a905a745f48a73f.tar.gz
Qt-fd0906bd56add3cd1f1bda502a905a745f48a73f.tar.bz2
Edited QtWebKit Guide.
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/declarative/qmlwebkit.qdoc4
-rw-r--r--doc/src/webkit/guide/chapter_cache.qdoc338
-rw-r--r--doc/src/webkit/guide/chapter_canvas.qdoc907
-rw-r--r--doc/src/webkit/guide/chapter_css.qdoc6
-rw-r--r--doc/src/webkit/guide/guidelinks.qdoc28
-rw-r--r--doc/src/webkit/webkit.qdoc4
6 files changed, 749 insertions, 538 deletions
diff --git a/doc/src/declarative/qmlwebkit.qdoc b/doc/src/declarative/qmlwebkit.qdoc
index ad2a50c..354e60a 100644
--- a/doc/src/declarative/qmlwebkit.qdoc
+++ b/doc/src/declarative/qmlwebkit.qdoc
@@ -42,9 +42,9 @@ The QtWebKit Module has a QML element, \l{WebView} for displaying web content
from a \c URL.
Import the QtWebKit module before declaring a \c WebView element:
-\code
+\qml
import QtWebKit 1.0
-\endcode
+\endqml
\section1 Simple Usage
\snippet doc/src/snippets/declarative/webview/webview.qml document
diff --git a/doc/src/webkit/guide/chapter_cache.qdoc b/doc/src/webkit/guide/chapter_cache.qdoc
index 4e51c33..b26827e 100644
--- a/doc/src/webkit/guide/chapter_cache.qdoc
+++ b/doc/src/webkit/guide/chapter_cache.qdoc
@@ -41,48 +41,61 @@
/*!
\page qtwebkit-guide-cache.html
-\title QtWebKit Guide - Client Storage
+\title Client Storage (BETA)
\chapter Client Storage
-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.
+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 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 \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
+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.
+\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:
@@ -98,20 +111,23 @@ else {
\endcode
The \c{getItem()} method retrieves the value of a database field named
-\c{key}:
+\bold{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.
+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:
+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 {
@@ -130,19 +146,20 @@ The \c{removeItem()} method deletes database fields:
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}:
+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:
+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 = {};
@@ -151,14 +168,16 @@ for ( var i = 0, l = db.length ; i < l ; 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.
+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.
+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
}
@@ -169,10 +188,10 @@ credit card field is stored only for the duration of the browing session.
\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:
+ 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;
@@ -192,15 +211,17 @@ credit card field is stored only for the duration of the browing session.
}
\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 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:
+ \c{false} boolean values, it converts \c{1} and \c{0} strings to
+ numbers:
\code
var db = window.localStorage;
@@ -210,9 +231,10 @@ credit card field is stored only for the duration of the browing session.
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:
+ 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
@@ -226,9 +248,10 @@ credit card field is stored only for the duration of the browing session.
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:
+ Note that this simple approach may cause problems of its own. For
+ example, perhaps the words \bold{true} and \bold{false} really should
+ be represented as strings. Encapsulating data within objects accounts
+ for such variability:
\code
var db = window.localStorage;
@@ -244,9 +267,9 @@ credit card field is stored only for the duration of the browing session.
\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:
+ 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;
@@ -277,17 +300,17 @@ credit card field is stored only for the duration of the browing session.
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.
+ 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:
+ 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){
@@ -301,21 +324,22 @@ credit card field is stored only for the duration of the browing session.
}, 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.
+ 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.
+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:
@@ -332,9 +356,13 @@ 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
@@ -347,32 +375,34 @@ The three core API methods are:
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 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:
+ 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.
+ 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:
+ 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) {
@@ -383,25 +413,35 @@ The three core API methods are:
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:
+ 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
+ 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
@@ -412,9 +452,10 @@ The three core API methods are:
});
\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:
+ 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]);
@@ -423,7 +464,8 @@ The three core API methods are:
\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:
+ To select values from the table, use a callback to capture the
+ results:
\code
tx.executeSql('SELECT * FROM foo', [], function(tx, results) {
@@ -433,27 +475,28 @@ The three core API methods are:
});
\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.
+ 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.
+ \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}.
+ \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.
+ 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:
@@ -470,39 +513,44 @@ The three core API methods are:
}
\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.
+ \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.
+ \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 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
-*/
+ \l{http://html5doctor.com/introducing-web-sql-databases/}{HTML5
+ Doctor: Introducing Web SQL Databases}
*/
diff --git a/doc/src/webkit/guide/chapter_canvas.qdoc b/doc/src/webkit/guide/chapter_canvas.qdoc
index 996d1ad..f04809a 100644
--- a/doc/src/webkit/guide/chapter_canvas.qdoc
+++ b/doc/src/webkit/guide/chapter_canvas.qdoc
@@ -40,53 +40,55 @@
/*!
\page qtwebkit-guide-canvas.html
-\title QtWebKit Guide - Canvas Graphics
+\title Canvas Graphics (BETA)
\chapter Canvas Graphics
-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.
+HTML5\'s 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:
+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:
+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}.
+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.
+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:
+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.
+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
@@ -94,7 +96,6 @@ the canvas.
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
@@ -112,12 +113,17 @@ you can combine to build complex shapes and graphic images.
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:
@@ -133,7 +139,7 @@ you can combine to build complex shapes and graphic images.
\section2 Drawing Lines
- To draw a line, you first have to \e{"put your pencil down"} on the canvas
+ To draw a line, you first have to "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.
@@ -143,12 +149,12 @@ you can combine to build complex shapes and graphic images.
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)}.
+ at the point (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:
+ coordinates of the line\'s endpoint. For example:
\code
context.beginPath();
@@ -156,24 +162,24 @@ you can combine to build complex shapes and graphic images.
context.lineTo(30,30);
\endcode
- To get the \e{pencil} to actually draw on the canvas, first use the
+ To get the "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}):
+ (#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:
+ (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:
+ 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
@@ -199,43 +205,59 @@ you can combine to build complex shapes and graphic images.
context.fill(); // fill the triangle
\endcode
- The commands, if coded fully, would create the shape below:
+ The above 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.
+ \bold{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:
+ 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}.)
+
+ \o \c{lineWidth} sets the thickness of the current line. The value can
+ be any number greater than 0. For example, \c{context.lineWidth = 10}
+ sets the line thickness to 10 units. The default value is 1 unit,
+ which is not the same as 1 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.)
+
+ \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 miter limit ratio. The value can be any
+ number greater than 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
+ 10.)
+
\endlist
\image webkit-guide/canvas_linecap.png
@@ -246,30 +268,35 @@ you can combine to build complex shapes and graphic images.
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.
+
+ \o Call the \c{context.beginPath()} method to "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}.
+ \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.
+ 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:
+ A complete circle is 360 degrees, or 2\pi radians. A semicircle is 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;
@@ -300,33 +327,42 @@ you can combine to build complex shapes and graphic images.
\endlist
- \note It is not necessary to close the path if you are going to call
+ \bold{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 Call the \c{context.beginPath()} method to "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.
+ \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:
+ 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 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
@@ -336,165 +372,217 @@ you can combine to build complex shapes and graphic images.
\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.
+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 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:
+The first shape drawn on the canvas to which additional shapes are
+added is called the destination shape. The shape drawn on the canvas
+afterwards to create the composite image is called the 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-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-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{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-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-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-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{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{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{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.
-\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:
+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{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
+
+\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:
+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
+\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:
- The default value is \c{10px sans-serif}.
+\code
+context.font = "12pt Arial";
+\endcode
- 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:
+The default value is \c{10px sans-serif}.
- \code
- context.font = "200%";
- \endcode
+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:
-\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
+\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{http://dev.w3.org/html5/canvas-api/canvas-2d-api.html}{the World
+Wide Web Consortium}, 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
-\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.
+
+\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 "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.
+\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,
@@ -563,23 +651,30 @@ 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{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.
+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 dw, height dh, and upper left corner at
+coordinates (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:
+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();
@@ -613,25 +708,30 @@ graphic.onload = function(){
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
+ methods such as \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
+
+ \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
@@ -659,32 +759,40 @@ graphic.onload = function(){
\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:
+To draw the outline of a shape in color,
+set the \c{strokeStyle} attribute to any valid
+\l{http://www.w3schools.com/css/css_colors.asp}{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:
+To fill a shape with color,
+set the \c{fillStyle} attribute to a
+\l{http://www.w3schools.com/css/css_colors.asp}{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:
+The
+\l{http://www.w3.org/TR/2003/CR-css3-color-20030514/#numerical}{CSS3
+Color Module specification} extends both RGB and HSL color models to
+include a color\'s opacity,
+referred to as its \bold{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
@@ -692,41 +800,50 @@ 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.
+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 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:
+ 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.
+ 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:
+ 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
+ Gradients must have two or more \bold{color stops}, representing color
+ shifts positioned from 0 to 1 between to the gradient\'s starting and
end points or circles:
\code
@@ -734,56 +851,77 @@ shapes, until you set a new value.
\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.
+ defined starting and end points or circles, expressed as a number
+ from 0 to 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:
+ 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
+
+ \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
+
+ \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
+
+ \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
+ \bold{NOTE:} A canvas gradient\'s color stops behave slightly
+ differently than those used within non-canvas \l{Gradients}{CSS3
+ Webkit 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
@@ -792,22 +930,25 @@ shapes, until you set a new value.
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{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.
+ 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
@@ -825,45 +966,57 @@ shapes, until you set a new value.
\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.
+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:
+ 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:
+ To increase or decrease the size of each unit in the canvas grid, call
+ the \c{scale} method:
\code
context.scale(x,y);
@@ -880,42 +1033,59 @@ transformation matrix directly.
\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:
+ 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.
+ 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.
+ The transformation matrix is an 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:
+ Each point on the canvas is multiplied by the matrix before anything
+ is drawn. The 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
@@ -926,89 +1096,114 @@ transformation matrix directly.
\image webkit-guide/canvas_math_rotate.png
- where the \c angle of rotation is in radians.
+ where the angle of rotation is in radians.
- \bold{See Also:}
+ \sa
\l{http://www.senocular.com/flash/tutorials/transformmatrix/}{senocular.com}
for a good explanation of how transformation matrices are used
- identically within Adobe Flash.
+ identically within 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.
+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:
+\c{strokeStyle},
+\c{fillStyle},
+\c{globalAlpha},
+\c{lineWidth},
+\c{lineCap},
+\c{lineJoin},
+\c{miterLimit},
+\c{shadowOffsetX},
+\c{shadowOffsetY},
+\c{shadowBlur},
+\c{shadowColor},
+\c{globalCompositeOperation},
+\c{font},
+\c{textAlign},
+and
+\c{textBaseline}.
+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:
-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:
+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{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.
+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.
+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 50
+milliseconds (corresponding to 20 times per second,
+a typical animation frame rate),
+then subsequently halt the animation:
-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.
+\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
index 32c06b5..9dd35bc 100644
--- a/doc/src/webkit/guide/chapter_css.qdoc
+++ b/doc/src/webkit/guide/chapter_css.qdoc
@@ -42,7 +42,7 @@
\page qtwebkit-guide-css.html
-\title QtWebKit Guide - Level 3 CSS
+\title Level 3 CSS (BETA)
\chapter Level 3 CSS
This section of the Qt WebKit Guide serves as an introduction to various Level 3 CSS features
@@ -1504,10 +1504,6 @@ examples provided here illustrate some CSS-only alternatives.
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
*/
/*!
diff --git a/doc/src/webkit/guide/guidelinks.qdoc b/doc/src/webkit/guide/guidelinks.qdoc
index b4f7f98..379b182 100644
--- a/doc/src/webkit/guide/guidelinks.qdoc
+++ b/doc/src/webkit/guide/guidelinks.qdoc
@@ -455,34 +455,6 @@
/*!
\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
index 759a7f7..78d27fa 100644
--- a/doc/src/webkit/webkit.qdoc
+++ b/doc/src/webkit/webkit.qdoc
@@ -94,10 +94,10 @@ technologies to create mobile applications with QtWebKit.
Contents:
\list
-\o \l{QtWebKit Guide - Level 3 CSS}{Level 3 CSS: media queries, selectors, visual
+\o \l{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}
+\o \l{Client Storage}
\endlist
*/