diff options
Diffstat (limited to 'doc/src/webkit')
| -rw-r--r-- | doc/src/webkit/guide/chapter_cache.qdoc | 338 | ||||
| -rw-r--r-- | doc/src/webkit/guide/chapter_canvas.qdoc | 907 | ||||
| -rw-r--r-- | doc/src/webkit/guide/chapter_css.qdoc | 6 | ||||
| -rw-r--r-- | doc/src/webkit/guide/guidelinks.qdoc | 28 | ||||
| -rw-r--r-- | doc/src/webkit/webkit.qdoc | 4 |
5 files changed, 536 insertions, 747 deletions
diff --git a/doc/src/webkit/guide/chapter_cache.qdoc b/doc/src/webkit/guide/chapter_cache.qdoc index b26827e..4e51c33 100644 --- a/doc/src/webkit/guide/chapter_cache.qdoc +++ b/doc/src/webkit/guide/chapter_cache.qdoc @@ -41,61 +41,48 @@ /*! \page qtwebkit-guide-cache.html -\title Client Storage (BETA) +\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. +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 +98,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 +130,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 +151,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 +169,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 +192,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 +210,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 +226,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 +244,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 +277,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 +301,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 +332,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 +347,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 +383,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 +412,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 +423,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 +433,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 +470,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 f04809a..996d1ad 100644 --- a/doc/src/webkit/guide/chapter_canvas.qdoc +++ b/doc/src/webkit/guide/chapter_canvas.qdoc @@ -40,55 +40,53 @@ /*! \page qtwebkit-guide-canvas.html -\title Canvas Graphics (BETA) +\title QtWebKit Guide - Canvas Graphics \chapter Canvas Graphics -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 +94,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 +112,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 +133,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 +143,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 +156,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 +199,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 +246,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 +300,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 +336,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 +563,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 +613,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 +659,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 +692,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 +734,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 +792,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 +825,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 +880,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 +926,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 9dd35bc..32c06b5 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 Level 3 CSS (BETA) +\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 @@ -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 379b182..b4f7f98 100644 --- a/doc/src/webkit/guide/guidelinks.qdoc +++ b/doc/src/webkit/guide/guidelinks.qdoc @@ -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 */ |