source: trunk/doc/src/examples/context2d.qdoc@ 1168

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example script/context2d
    \title Context2D Example

    This Qt Script example is an implementation of the Context2D API.

    \image context2d-example.png

    Context2D is part of the specification for the HTML \c{<canvas>}
    element. It can be used to draw graphics via scripting. A good
    resource for learning more about the HTML \c{<canvas>} element is
    the \l{http://developer.mozilla.org/en/docs/HTML:Canvas}{Mozilla Developer Center}.

    \section1 Using The HTML Canvas Element in a Web Browser

    First, let's look at how the \c{<canvas>} element is typically
    used in a web browser. The following HTML snippet defines a
    canvas of size 400x400 pixels with id \c{mycanvas}:

    \code
    <canvas width="400" height="400" id="mycanvas">Fallback content goes here.</canvas>
    \endcode

    To draw on the canvas, we must first obtain a reference to the
    DOM element corresponding to the \c{<canvas>} tag and then call
    the element's getContext() function. The resulting object
    implements the Context2D API that we use to draw.

    \code
    <script>
    var canvas = document.getElementById("mycanvas");
    var ctx = canvas.getContext("2d");

    // Draw a face
    ctx.beginPath();
    ctx.arc(75,75,50,0,Math.PI*2,true); // Outer circle
    ctx.moveTo(110,75);
    ctx.arc(75,75,35,0,Math.PI,false);   // Mouth
    ctx.moveTo(65,65);
    ctx.arc(60,65,5,0,Math.PI*2,true);  // Left eye
    ctx.moveTo(95,65);
    ctx.arc(90,65,5,0,Math.PI*2,true);  // Right eye
    ctx.stroke();
    </script>
    \endcode

    When the page is rendered by a browser that supports the
    \c{<canvas>} tag, this would be the result:

    \image context2d-example-smileysmile.png

    \section1 Using Qt Script to script a Canvas

    The goal of this example is to be able to evaluate scripts
    that use the Context2D API, and render the results. Basic
    interaction (mouse, keyboard) should also be supported.
    In other words, we want to present scripts with an execution
    environment that very much resembles that of a web browser. Of
    course, our environment is only a small subset of what a browser
    provides; i.e. we don't provide a full DOM API, only what is
    needed to run "self-contained" Context2D scripts (i.e. scripts
    that don't depend on other parts of the DOM document).

    Our "Context2D-browser" is set up through the following steps:
    \list
    \o Create an Environment.
    \o Create a Context2D, and a QContext2DCanvas widget to render it.
    \o Add the canvas object to the environment; this will enable
       scripts to obtain a reference to it.
    \o Evaluate scripts in the environment.
    \endlist

    Once a script has been evaluated, the application handles any
    timer events and input events that occur subsequently
    (i.e. forwards events to their associated script targets).

    \section1 The Context2D Class

    The "heart" of this example is the Context2D C++ class that implements
    the drawing API. Its interface is defined in terms of properties
    and slots. Note that this class isn't tied to Qt Script in any
    way.

    \snippet examples/script/context2d/context2d.h 0

    The properties define various aspects of the Context2D
    configuration.
    
    \snippet examples/script/context2d/context2d.h 1

    The slots define the operations that can be performed.
    
    \snippet examples/script/context2d/context2d.h 2

    The changed() signal is emitted when the contents of the drawing
    area has changed, so that clients associated with the Context2D
    object (i.e. the canvas widget that renders it) are notified.

    \section2 Implementation

    Conveniently enough, the concepts, data structures and operations
    of the Context2D API map more or less directly to Qt's painting
    API. Conceptually, all we have to do is initialize a QPainter
    according to the Context2D properties, and use functions like
    QPainter::strokePath() to do the painting. Painting is done on a
    QImage.

    \snippet examples/script/context2d/context2d.cpp 0

    The property accessors and most of the slots manipulate the
    internal Context2D state in some way. For the \c{lineCap}
    property, Context2D uses a string representation; we therefore
    have to map it from/to a Qt::PenCapStyle. The \c{lineJoin}
    property is handled in the same fashion. All the property setters
    also set a \e{dirty flag} for the property; this is used to
    decide which aspects of the QPainter that need to be updated
    before doing the next painting operation.

    \snippet examples/script/context2d/context2d.cpp 3

    The implementation of the \c{fillStyle} property is interesting,
    since the value can be either a string or a \c{CanvasGradient}.
    We handle this by having the property be of type QVariant,
    and check the actual type of the value to see how to handle the
    write.

    \snippet examples/script/context2d/context2d.cpp 1

    Context2D does not have a concept of a paint event; painting
    operations can happen at any time. We would like to be efficient,
    and not have to call QPainter::begin() and QPainter::end() for
    every painting operation, since typically many painting operations
    will follow in quick succession. The implementations of the
    painting operations use a helper function, beginPainting(), that
    activates the QPainter if it isn't active already, and updates
    the state of the QPainter (brush, pen, etc.) so that it reflects
    the current Context2D state.

    \snippet examples/script/context2d/context2d.cpp 2

    The implementation of each painting operation ends by calling
    scheduleChange(), which will post a zero-timer event if one is
    not already pending. When the application returns to the event
    loop later (presumably after all the drawing operations have
    finished), the timer will trigger, QPainter::end() will be
    called, and the changed() signal is emitted with the new
    image as argument. The net effect is that there will typically
    be only a single (QPainter::begin(), QPainter::end()) pair
    executed for the full sequence of painting operations.

    \section1 The Canvas Widget

    \snippet examples/script/context2d/qcontext2dcanvas.h 0

    The QContext2DCanvas class provides a widget that renders
    the contents of a Context2D object. It also provides a
    minimal scripting API, most notably the getContext() function.

    \snippet examples/script/context2d/qcontext2dcanvas.cpp 3

    The constructor connects to the changed() signal of the
    Context2D object, so that the widget can update itself