summaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorJerome Pasion <jerome.pasion@nokia.com>2011-03-23 12:19:17 (GMT)
committerJerome Pasion <jerome.pasion@nokia.com>2011-03-23 12:19:17 (GMT)
commit8700366079f6346ab0ba8baa624993832127188e (patch)
tree20c1046c755b8226692193fb4508fe6661b87759 /doc/src
parent77631f69a935a9f8e2ca705cc51f27b8c622f302 (diff)
downloadQt-8700366079f6346ab0ba8baa624993832127188e.zip
Qt-8700366079f6346ab0ba8baa624993832127188e.tar.gz
Qt-8700366079f6346ab0ba8baa624993832127188e.tar.bz2
Edited QtWebKit Guide qdoc and added external links.
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/webkit/guide/chapter_cache.qdoc341
-rw-r--r--doc/src/webkit/guide/chapter_canvas.qdoc909
-rw-r--r--doc/src/webkit/guide/chapter_css.qdoc10
-rw-r--r--doc/src/webkit/guide/guidelinks.qdoc34
-rw-r--r--doc/src/webkit/webkit.qdoc4
5 files changed, 546 insertions, 752 deletions
diff --git a/doc/src/webkit/guide/chapter_cache.qdoc b/doc/src/webkit/guide/chapter_cache.qdoc
index bdafe48..fcfd208 100644
--- a/doc/src/webkit/guide/chapter_cache.qdoc
+++ b/doc/src/webkit/guide/chapter_cache.qdoc
@@ -41,61 +41,51 @@
/*!
\page qtwebkit-guide-cache.html
-\title Client Storage
+\title QtWebKit Guide - Client Storage
\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 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.
+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 \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:
@@ -111,23 +101,20 @@ else {
\endcode
The \c{getItem()} method retrieves the value of a database field named
-\bold{key}:
+\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.
+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 {
@@ -146,20 +133,19 @@ 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 = {};
@@ -168,16 +154,14 @@ 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
}
@@ -188,10 +172,10 @@ 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;
@@ -211,17 +195,15 @@ 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;
@@ -231,10 +213,9 @@ 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
@@ -248,10 +229,9 @@ 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 \bold{true} and \bold{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 \c{true} and \c{false} really should be represented
+ as strings. Encapsulating data within objects accounts for such variability:
\code
var db = window.localStorage;
@@ -267,9 +247,9 @@ 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;
@@ -300,17 +280,17 @@ 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){
@@ -324,22 +304,21 @@ 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:
@@ -356,13 +335,9 @@ 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
@@ -375,34 +350,32 @@ 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) {
@@ -413,35 +386,25 @@ 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
@@ -452,10 +415,9 @@ 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]);
@@ -464,8 +426,7 @@ 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) {
@@ -475,28 +436,27 @@ 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:
@@ -513,44 +473,39 @@ 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{http://html5doctor.com/introducing-web-sql-databases/}{HTML5
- Doctor: Introducing Web SQL Databases}
+ \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
index a2688f8..eea2236 100644
--- a/doc/src/webkit/guide/chapter_canvas.qdoc
+++ b/doc/src/webkit/guide/chapter_canvas.qdoc
@@ -40,55 +40,55 @@
/*!
\page qtwebkit-guide-canvas.html
-\title Canvas Graphics
+\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.
-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.
+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:
+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
@@ -96,6 +96,7 @@ the \c{y} axis from top to bottom of 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
@@ -113,17 +114,12 @@ 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:
@@ -139,7 +135,7 @@ you can combine to build complex shapes and graphic images.
\section2 Drawing Lines
- To draw a line, you first have to "put your pencil down" on the canvas
+ 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.
@@ -149,12 +145,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 point (x,y).
+ 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:
+ coordinates of the line's endpoint. For example:
\code
context.beginPath();
@@ -162,24 +158,24 @@ you can combine to build complex shapes and graphic images.
context.lineTo(30,30);
\endcode
- To get the "pencil" to actually draw on the canvas, first use the
+ 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
- (#000):
+ (\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:
+ (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
@@ -205,59 +201,43 @@ you can combine to build complex shapes and graphic images.
context.fill(); // fill the triangle
\endcode
- The above commands, if coded fully, would create the shape below:
+ The commands, if coded fully, would create the shape below:
\image webkit-guide/canvas_closepath.gif
- \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.
+ \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 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}.)
-
+ \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 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.)
-
+ \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
@@ -268,35 +248,30 @@ you can combine to build complex shapes and graphic images.
a line:
\list 1
-
- \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.
+ \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}.
+ \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 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:
+ 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;
@@ -327,42 +302,33 @@ you can combine to build complex shapes and graphic images.
\endlist
- \bold{NOTE:} It is not necessary to close the path if you are going to call
+ \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 "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 \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.
-
+ \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
@@ -372,217 +338,165 @@ 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 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 \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 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:
+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-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-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{xor} displays both the source and the destination shapes except
-the areas of overlap, in which both shapes are completely transparent.
+\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:
+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:
-\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{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
+ \code
+ context.font = "12pt Arial";
+ \endcode
-\o \c{alphabetic} (default) is the anchor point of many alphabetic
-characters
+ The default value is \c{10px sans-serif}.
-\o \c{ideographic} is the anchor point of many ideograms, such as the
-characters used in the writing systems of many Asian languages
+ 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{bottom} is the bottom of the em square
+ \code
+ context.font = "200%";
+ \endcode
-\endlist
+\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 "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 \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.
-\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.
+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,
@@ -651,30 +565,23 @@ 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 dw, height dh, and upper left corner at
-coordinates (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
+\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:
+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();
@@ -708,30 +615,25 @@ 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 \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
-
+ 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
@@ -759,40 +661,32 @@ graphic.onload = function(){
\section1 Applying Colors
-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:
+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{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:
+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{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:
+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
@@ -800,50 +694,41 @@ 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 \bold{color stops}, representing color
- shifts positioned from 0 to 1 between to the gradient\'s starting and
+ 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
@@ -851,77 +736,56 @@ 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 0 to 1.
-
+ 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:
-
+ 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
- \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
+ \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
@@ -930,25 +794,22 @@ 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{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{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
@@ -966,57 +827,45 @@ 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);
@@ -1033,59 +882,42 @@ grid, and modify the 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 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 \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 HTML5 canvas API defines the transformation matrix as:
+ 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
@@ -1096,114 +928,89 @@ grid, and modify the transformation matrix directly.
\image webkit-guide/canvas_math_rotate.png
- where the angle of rotation is in radians.
+ where the \c angle of rotation is in radians.
- \sa
+ \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 Flash.
+ 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:
-\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:
+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:
-
+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.
-
-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:
+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.
+\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 d2cb8a7..71005fc 100644
--- a/doc/src/webkit/guide/chapter_css.qdoc
+++ b/doc/src/webkit/guide/chapter_css.qdoc
@@ -42,11 +42,11 @@
\page qtwebkit-guide-css.html
-\title Level 3 CSS
+\title QtWebKit Guide - Level 3 CSS
\chapter Level 3 CSS
-This section of the Qt WebKit Guide serves as an introduction to various Level 3 CSS features
-supported by QtWebKit:
+This section of the \l{QtWebKit Guide} serves as an introduction to various
+Level 3 CSS features supported by QtWebKit:
\list
@@ -1504,6 +1504,10 @@ 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 1c899d4..b4f7f98 100644
--- a/doc/src/webkit/guide/guidelinks.qdoc
+++ b/doc/src/webkit/guide/guidelinks.qdoc
@@ -218,7 +218,7 @@
*/
/*!
-\externalpage webkit-webkit-guide-js-anim-accord-js.html
+\externalpage wwebkit-webkit-guide-js-anim-accord-js.html
\title anim_accord_js
*/
@@ -343,12 +343,12 @@
*/
/*!
-\externalpage webkit-webkit-guide-css-css3-mask-grad-css.html
+\externalpage webkit-guide/css/webkit-webkit-guide-css-css3-mask-grad-css.html
\title css3_mask-grad_css
*/
/*!
-\externalpage webkit-webkit-guide-js-css3-mask-grad-js.html
+\externalpage webkit-guide/js/webkit-webkit-guide-js-css3-mask-grad-js.html
\title css3_mask-grad_js
*/
@@ -455,6 +455,34 @@
/*!
\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 78d27fa..759a7f7 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{Level 3 CSS}{Level 3 CSS: media queries, selectors, visual
+\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{Client Storage}
+\o \l{QtWebKit Guide - Client Storage}{Client Storage}
\endlist
*/