Updated the Qt Quick Canvas learning guide

- Language edits
- Removed the links to qt.nokia.com

Task-number: QTBUG-28831
Change-Id: I2da0bd8a5b99c11277ffca9b0635e9c6614b803c
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

5 files changed, 37 insertions, 41 deletions

diff --git a/canvas_tutorial/about.rst b/canvas_tutorial/about.rst
index 46646fb..e6401b0 100644
--- a/canvas_tutorial/about.rst
+++ b/canvas_tutorial/about.rst
@@ -15,25 +15,23 @@ About this Guide
 Why Would You Want to Read this Guide?
 --------------------------------------
 
-The goal of this guide is to make you familiar with best programming practices using the Canvas Item in Qt Quick 2.0 as part of Qt 5.
-A prerequisite to this guide is to have a solid understanding of the QML language and also use the Qt Quick Application Development Primer as your first guide on how to use Qt Quick for application development. Throughout this guide, we’ll walk you through various aspects and examples of Qt Quick 2.0 Painting API with Canvas. References to other information sources are provided to make it easy for you to deepen your understanding of the used API.
+The goal of this guide is to inform you about the best programming practices using the Canvas type in Qt Quick 2.0.
+A prerequisite to this guide is to have a solid understanding of the QML language, so I recommend reading the Qt Quick Application Development Primer first to understand how to use Qt Quick for application development. Throughout this guide, we’ll walk you through various aspects and examples of Qt Quick 2.0 Painting API with Canvas. References to other information sources are provided to make it easy for you to deepen your understanding of the used API.
 
 .. _get-desktop-source-code:
 
 Get the Source Code and the Guide in Different Formats
 ------------------------------------------------------
 
-.. Todo: Change the download links
+A .zip file that contains the example source code referred in each chapter:
 
-A .zip file that contains the source code of each chapter is provided:
+     `Source code <http://releases.qt-project.org/learning/developerguides/canvastutorial/canvasexample_src.zip>`_
 
-     `Source code <http://get.qt.nokia.com/developerguides/canvastutorial/canvasexample_src.zip>`_
+The guide is available in the following offline formats:
 
-The guide is available in the following formats:
-
-     `PDF <http://get.qt.nokia.com/developerguides/canvastutorial/QtQuickCanvasTutorial.pdf>`_
-     `ePub <http://get.qt.nokia.com/developerguides/canvastutorial/QtQuickCanvasTutorial.epub>`_ for ebook readers. Further details can be found `here <http://en.wikipedia.org/wiki/EPUB#Software_reading_systems>`_.
-     `Qt Help <http://get.qt.nokia.com/developerguides/canvastutorial/QtQuickCanvasTutorial.qch>`_ for Qt Assistant and Qt Creator. In Qt Assistant under the :qt:`Preferences Dialog <assistant-details.html#preferences-dialog>`, in the `Documentation` tab (in a collapsible menu for Mac users), you click on the Add button in order to add this guide in the .qch format. We do the same in Qt Creator, under the `Options` dialog, in the `Help` section you, can add this guide in the `Documentation` tab.
+     `PDF <http://releases.qt-project.org/learning/developerguides/canvastutorial/QtQuickCanvasTutorial.pdf>`_
+     `ePub <http://releases.qt-project.org/learning/developerguides/QtQuickCanvasTutorial.epub>`_ for ebook readers. Further details can be found `here <http://en.wikipedia.org/wiki/EPUB#Software_reading_systems>`_.
+     `Qt Help <http://releases.qt-project.org/learning/developerguides/canvastutorial/QtQuickCanvasTutorial.qch>`_ for Qt Assistant and Qt Creator. In Qt Assistant, go to the :qt:`Preferences Dialog <assistant-details.html#preferences-dialog>`, in the `Documentation` tab (in a collapsible menu for Mac users), click on the `Add` button in order to add this guide in .qch format. Do the same in Qt Creator under the `Options` dialog. In the `Help` section, you can add this guide under the `Documentation` tab.
 
 
 License
diff --git a/canvas_tutorial/conclusion.rst b/canvas_tutorial/conclusion.rst
index c5b38e3..fb54002 100644
--- a/canvas_tutorial/conclusion.rst
+++ b/canvas_tutorial/conclusion.rst
@@ -12,16 +12,14 @@
 Conclusion
 ==========
 
-In this tutorial, we explored some of the capabilities of the Qt Quick Canvas. We developed a nice looking pie chart visualization and ported HTML5 Canvas code to Qt Quick. If you want to learn more about the canvas API, you may consult some of the various HTML5 tutorials available on the internet.
+In this tutorial, we explored some of the capabilities of the Qt Quick Canvas type. We developed a nice looking pie chart visualization and ported HTML5 Canvas code to Qt Quick. If you want to learn more about the canvas API, you can refer to some of the HTML5 tutorials available on the internet.
 
-This is an incomplete list of tutorials which we consider helpful:
+Here is a small list of such tutorials:
 
      `http://www.html5canvastutorials.com <http://www.html5canvastutorials.com>`_ - A page dedicated to HTML5 Canvas tutorials
      `https://developer.mozilla.org/en/Canvas_tutorial <https://developer.mozilla.org/en/Canvas_tutorial>`_ - An HTML5 Canvas tutorial on the Mozilla Developer Network
      `http://dev.opera.com/articles/view/html-5-canvas-the-basics <http://dev.opera.com/articles/view/html-5-canvas-the-basics>`_ - HTML5 Canvas basics on the Opera developer portal
      `http://www.canvasdemos.com <http://www.canvasdemos.com>`_ - A page presenting HTML5 Canvas demos
 
-`The Qt Webkit Guide about canvas graphics <http://qt-project.org/doc/qt-4.8/qtwebkit-guide-canvas.html>`_ also gives a detailed introduction to the HTML5 Canvas API.
-
-Also note `this very handy cheat sheet <http://blog.nihilogic.dk/2009/02/html5-canvas-cheat-sheet.html>`_.
+`The Qt Webkit Guide about canvas graphics <http://qt-project.org/doc/qt-4.8/qtwebkit-guide-canvas.html>`_ also gives a detailed introduction to the HTML5 Canvas API. Also note `this very handy cheat sheet <http://blog.nihilogic.dk/2009/02/html5-canvas-cheat-sheet.html>`_.
 
diff --git a/canvas_tutorial/html5canvas.rst b/canvas_tutorial/html5canvas.rst
index b71d277..819f956 100644
--- a/canvas_tutorial/html5canvas.rst
+++ b/canvas_tutorial/html5canvas.rst
@@ -15,13 +15,13 @@ Porting HTML5 Canvas Code to Qt Quick
 In this page, we want to show how easy it is to port existing HTML5 Canvas code to Qt Quick using the Canvas element.
 
 .. note::
-    A general list of the necessary changes can be found in `the Qt documentation pages of the Qt Quick Canvas <http://doc.qt.nokia.com/qt5-snapshot/qml-qtquick2-canvas.html>`_.
+    A general list of the necessary changes can be found in `the Qt documentation for :qt5-snapshot: Qt Quick Canvas <qtquick/qml-qtquick2-canvas.html>`_.
 
 
 The HTML5 Canvas Code
 ---------------------
 
-`This link <https://developer.mozilla.org/en/Canvas_tutorial/Transformations>`_ leads to an HTML5 Canvas tutorial, in which one of the examples shows a `spirograph <http://en.wikipedia.org/wiki/Spirograph>`_.
+We are going to port the `spirograph <http://en.wikipedia.org/wiki/Spirograph>`_ example used in this `HTML5 Canvas Tutorial <https://developer.mozilla.org/en/Canvas_tutorial/Transformations>`_.
 
 The HTML5 code looks like this:
 
@@ -32,12 +32,12 @@ The HTML5 code looks like this:
 The Qt Quick Canvas Code
 ------------------------
 
-To use this code in a Qt Quick Canvas, we can almost simply copy the HTML5 code's drawing function into the Canvas element's ``onPaint`` handler. We only need to change the line in which we acquire the drawing context: instead of using a DOM API call (``document.getElementById('canvas')``), we access the canvas element directly. The used JavaScript function can be inserted as a member function of the element.
+To port this code to a Qt Quick application, we can copy the code for drawing function into the ``onPaint`` handler of Qt Quick Canvas. We only need to change the line in which we acquire the drawing context: instead of using a DOM API call (``document.getElementById('canvas')``), we access the canvas directly. The JavaScript function can be inserted as a member function of the canvas.
 
 .. literalinclude:: src/spirograph.qml
     :language: js
 
-This is what the application looks like:
+This is how the ported Qt Quick application looks like:
 
 .. image:: img/spirograph.png
     :scale: 50%
diff --git a/canvas_tutorial/introduction.rst b/canvas_tutorial/introduction.rst
index 820fb3f..529d391 100644
--- a/canvas_tutorial/introduction.rst
+++ b/canvas_tutorial/introduction.rst
@@ -12,19 +12,19 @@
 Introduction
 ============
 
-If you want to draw custom graphics from within your Qt Quick application, the `Qt Quick Canvas <http://doc.qt.nokia.com/qt5-snapshot/qml-qtquick2-canvas.html>`_ item is your item of choice.
+If you want to draw custom graphics within your Qt Quick application, the :qt5-snapshot:`Qt Quick Canvas <qtquick/qml-qtquick2-canvas.html>`_ item is your choice.
 
-The Canvas element was introduced in Qt Quick 2.0 and provides an area on which you can draw using JavaScript code. It uses a high level command-set based on `the HTML5 Canvas specification <http://www.w3.org/TR/html5/the-canvas-element.html>`_, which allows you to draw basic and complex shapes, add coloring, gradients, shadows, images, text etc, but also grants access to low level pixel data. The employment of JavaScript facilitates the presentation of dynamic content.
+The Canvas type was introduced in Qt Quick 2.0 and provides an area in which you can draw using JavaScript. It uses a high-level command-set based on `the HTML5 Canvas specification <http://www.w3.org/TR/html5/the-canvas-element.html>`_. The Canvas type allows you to draw basic and complex shapes, add color, gradients, shadows, images, text, and access low-level pixel data. Using JavaScript, facilitates the presentation of dynamic content.
 
-After a brief introduction to the Canvas element, we'll develop an interactive pie chart visualization. Later in this guide, we'll see how to port existing HTML5 Canvas code to a Qt Quick 2 application.
+After a brief introduction to the Canvas type, we'll develop an interactive pie chart visualization. Later in this guide, we'll see how to port existing HTML5 Canvas code to a Qt Quick 2 application.
 
-This tutorial introduces you to the Qt Quick Canvas using self contained example programs and is not meant to show each and every aspect of this element. A detailed description of the Canvas and its supported rendering commands can be found in the Qt documentation pages (see: `Canvas <http://doc.qt.nokia.com/qt5-snapshot/qml-qtquick2-canvas.html>`_, `Context2D <http://doc.qt.nokia.com/qt5-snapshot/qml-qtquick2-context2d.html>`_). Also note, that a huge number of very good HTML5 Canvas API tutorials is available on the internet. Since the Qt Quick Canvas element implements this command-set, these tutorials can serve as an excellent starting point to learn drawing. We provide a few links at `the end of this tutorial <conclusion.html>`_. We also assume that you are already familiar with Qt Quick in general, as this tutorial will use non Canvas related features without further notice.
+This tutorial introduces you to the Qt Quick Canvas using example programs and is not meant to show each and every aspect of this type. A detailed description of the Canvas type and its supported rendering commands can be found in the Qt documentation pages (:qt5-snapshot:`Canvas <qtquick/qml-qtquick2-canvas.html>`_, :qt5-snapshot:`Context2D <qtquick/qml-qtquick2-context2d.html>`_). Also note that a large number of good HTML5 Canvas API tutorials are available on the internet. As the Qt Quick Canvas type is based on the HTML5 specification, these tutorials can serve as an excellent starting point to learn drawing. We have listed a few of those tutorials at `the end of this tutorial <conclusion.html>`_. We also assume that you are already familiar with Qt Quick in general, as this tutorial does refer to some the non-Canvas features.
 
 
 A Basic Example
 ---------------
 
-The Qt Quick Canvas element is the element that you place in your application to draw upon. The actual drawing as well as the resource handling is done by its associated `Context2D <http://doc.qt.nokia.com/qt5-snapshot/qml-qtquick2-context2d.html>`_. This element provides the drawing API and manages the transformation stack and style state. It also lets you customize some of its internals such as multithreading, tiling and the usage of hardware acceleration.
+The Qt Quick Canvas type provides a place in your application to draw upon. The actual drawing as well as the resource handling is done by its associated :qt5-snapshot:`Context2D <qtquick/qml-qtquick2-context2d.html>`_ type, which provides the drawing API and manages the transformation stack and style state. It also lets you customize some of its internals such as multithreading, tiling, and the usage of hardware acceleration.
 
 Let's start with a simple example: a small piece of code that displays a colored rectangle:
 
@@ -36,10 +36,10 @@ This is the source code:
 .. literalinclude:: src/canvas.qml
     :language: js
 
-The usual way is to declare a ``Canvas`` element and place the drawing commands inside its ``onPaint`` handler. After acquiring the drawing context, we prepare a rectangular path using ``rect(real x, real y, real w, real h)``. Then we setup the fill color state to a yellow color using ``fillStyle`` and fill the rectangle by calling ``fill()``. The green border of the rectangle is drawn by setting ``strokeStyle`` and calling ``stroke()`` respectively. ``lineWidth`` sets the width of the stroke.
+The usual way is to declare a ``Canvas`` type and place the drawing commands inside its ``onPaint`` handler. After acquiring the drawing context, we prepare a rectangular path using ``rect(real x, real y, real w, real h)``. Then we set up the fill color state to yellow using ``fillStyle`` and fill the rectangle by calling ``fill()``. The green border of the rectangle is drawn by setting ``strokeStyle`` and calling ``stroke()`` respectively. The ``lineWidth`` property sets the width of the stroke.
 
 .. note::
-    The order of ``stroke()`` and ``fill()`` matters: The stroke pattern is drawn centered along the path (in this example with a 2 px width pattern to the left side and a 2 px width pattern to the right side). If we used ``stroke()`` before calling ``fill()``, the fill would over paint the inner part of the border resulting in a 2 px wide border.
+    The order of ``stroke()`` and ``fill()`` matters: The stroke pattern is drawn centered along the path (in this example with a 2 px width pattern to the left side and a 2 px width pattern to the right side). If we call ``stroke()`` before ``fill()``, ``fill()`` would over paint the inner part of the border resulting in a 2 px wide border.
 
 
 Essential Context2D Properties / Methods
@@ -63,9 +63,9 @@ Transformation     translate(x, y)                    Move coordinate system
 Transformation     rotate(angle)                      Rotate coordinate system
 Transformation     scale(x, y)                        Scale coordinate system
 Transformation     shear(sh, sv)                      Shear coordinate system
-Style              strokeStyle                        Setup line style
-Style              lineWidth                          Setup line width
-Style              fillStyle                          Setup fill style
+Style              strokeStyle                        Set up line style
+Style              lineWidth                          Set up line width
+Style              fillStyle                          Set up fill style
 Drawing            stroke()                           Draw path using style
 Drawing            fill()                             Fill path using style
 ================== ================================== =========================
diff --git a/canvas_tutorial/piechart.rst b/canvas_tutorial/piechart.rst
index 4c9ccdc..3d6e6fb 100644
--- a/canvas_tutorial/piechart.rst
+++ b/canvas_tutorial/piechart.rst
@@ -12,9 +12,9 @@
 A Pie Chart
 ===========
 
-In this chapter, we'll present a more elaborate example: we'll create a pie chart item that visualizes the data of a Qt Quick ListModel similar to `this Qt Widget example <http://qt-project.org/doc/qt-4.8/itemviews-chart.html>`_. The ListModel's values will also be shown in a ListView next to the chart. If one of its entries is selected, the according sector of the pie chart shall be highlighted.
+In this chapter, we'll present a more elaborate example: we'll create a pie chart item that visualizes the data of a Qt Quick ListModel similar to `the Qt Widget example <http://qt-project.org/doc/qt-4.8/itemviews-chart.html>`_. The ListModel's values are shown in a ListView next to the chart. If one of its entries is selected, the according sector of the pie chart gets highlighted.
 
-The final application will look like this:
+The final application looks like this:
 
 .. image:: img/piechart-3.png
     :scale: 50%
@@ -23,7 +23,7 @@ The final application will look like this:
 The Layout & the Conceptual Context of the Pie Chart
 ----------------------------------------------------
 
-Let's start with the layout of the application and the context in which the pie chart lives. This means setting up the ListModel, placing the Canvas element and creating the ListView.
+Let's start with the layout of the application and the context in which the pie chart lives. This means setting up the ListModel, placing the Canvas and creating the ListView.
 
 .. image:: img/piechart-1.png
     :scale: 50%
@@ -45,7 +45,7 @@ The canvas that shows the pie chart is placed in the left half of the applicatio
     :end-before: // [1]
     :append: ...
 
-On the right side, we display the model's data in a list view which shows the item's labels and values in colored rows. It represents the legend of the chart so to say:
+On the right side, we display the model's data in a list view, which shows the item's labels and values in colored rows. It represents the legend of the chart so to say:
 
 .. literalinclude:: src/piechart-1.qml
     :language: js
@@ -57,18 +57,18 @@ On the right side, we display the model's data in a list view which shows the it
 How to Draw a Sector
 --------------------
 
-A pie chart is a circular chart consisting of several sectors - one for each data set. The area of each sector is proportional to the value it represents. So let's first take a look at how to draw one of the pie chart's sectors.
+A pie chart is a circular chart consisting of several sectors - one for each data set. The area of each sector is proportional to the value it represents. So let's first take a look at how to draw one of the pie chart sectors.
 
-The size of a sector is defined by the length of its arc or the arc's subtending angle. If you think of the whole pie having an angle of ``2      PI`` then each sector should cover an angle of ``value * (2 * PI) / SUM_OF_VALUES``.
+The size of a sector is defined by the length of its arc or the arc's subtending angle. If you think of the whole pie having an angle of ``2 PI``, each sector should cover an angle of ``value * (2 * PI) / SUM_OF_VALUES``.
 
 .. image:: img/piechart-sector-graphic.png
 
-To draw the arc, we use the ``arc(real x, real y, real radius, real startAngle, real endAngle, bool anticlockwise)`` function, which creates a circular path on the circumference of a circle which is centered around ``(x, y)`` and has the given radius. To complete the pie segment, we also need to draw the lines which go from the circle's center to the arc's edges. Therefore we move the cursor's position to the center point, draw the arc, and then draw a line back to the center. The ``arc()`` function will automatically generate a line from the cursor's initial position at the center to the starting point of the arc in addition to the arc itself.
+To draw the arc, we use the ``arc(real x, real y, real radius, real startAngle, real endAngle, bool anticlockwise)`` function. This function creates a circular path on the circumference of a circle, which is centered around ``(x, y)`` and has the given radius. To complete the pie segment, we also need to draw the lines that go from the circle's center to the arc's edges. Therefore we move the cursor's position to the center point, draw the arc, and then draw a line back to the center. The ``arc()`` function automatically generates a line from the cursor's initial position at the center to the starting point of the arc in addition to the arc itself.
 
 .. literalinclude:: src/piechart-sector.js
     :language: js
 
-This is how the output of an application using the code snippet above might look:
+This is how the output of an application using the code described above looks:
 
 .. image:: img/piechart-sector.png
     :scale: 50%
@@ -77,7 +77,7 @@ This is how the output of an application using the code snippet above might look
 Drawing the Chart
 -----------------
 
-Next we will draw the complete pie chart. After this step the application will look like this:
+Next, we will draw the complete pie chart. After this step, the application looks like this:
 
 .. image:: img/piechart-2.png
     :scale: 50%
@@ -95,7 +95,7 @@ In the ``onPaint`` handler, we iterate over the model's elements and draw one pi
 Finalizing the Chart
 --------------------
 
-In this chapter we'll visually enhance the pie chart's appearance and also provide interactivity. This is a screenshot of the application after this stage:
+In this chapter we'll enhance the pie chart's appearance and also provide interactivity. This is how the application looks after the enhancement:
 
 .. image:: img/piechart-3.png
     :scale: 50%
@@ -109,7 +109,7 @@ In order to make the application more alive, we change the chart's appearance ac
     :end-before: // [0]
     :append: ...
 
-The selected entry shall also be indicated in the pie chart. Therefore we increase the associated sector's radius by 2%. We also want this chart sector to always be located on the right side of the chart. For this, we to rotate the canvas element based on the list view's ``currentItem`` property. To smooth this change, we apply a behavior to the rotation using a spring animation. Additionally, we overlay a radial gradient from transparent white to a darker gray to further brush up the pie chart's appearance.
+The pie chart sector representing the selected entry is also highlighted by increasing the sector's radius by 2%. We also want the highlighted sector to be on the right side of the chart, so we rotate the canvas based on the list view's ``currentItem`` property. To smooth this change, we apply a behavior to the rotation using a spring animation. Finally, we overlay a radial gradient from transparent white to a darker gray to further brush up the pie chart's appearance.
 
 .. literalinclude:: src/piechart-3.qml
     :language: js
@@ -122,5 +122,5 @@ Now we're done! We've successfully created a nice looking pie chart.
 
 .. rubric:: What's Next?
 
-The next chapter will demonstrate how to port HTML5 Canvas code into the Canvas Item of Qt Quick.
+The next chapter demonstrates how to port HTML5 Canvas code into the Canvas Item of Qt Quick.