/****************************************************************************+
−
**+
−
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).+
−
** All rights reserved.+
−
** Contact: Nokia Corporation (qt-info@nokia.com)+
−
**+
−
** This file is part of the documentation of the Qt Toolkit.+
−
**+
−
** $QT_BEGIN_LICENSE:LGPL$+
−
** No Commercial Usage+
−
** This file contains pre-release code and may not be distributed.+
−
** You may use this file in accordance with the terms and conditions+
−
** contained in the Technology Preview License Agreement accompanying+
−
** this package.+
−
**+
−
** GNU Lesser General Public License Usage+
−
** Alternatively, this file may be used under the terms of the GNU Lesser+
−
** General Public License version 2.1 as published by the Free Software+
−
** Foundation and appearing in the file LICENSE.LGPL included in the+
−
** packaging of this file.  Please review the following information to+
−
** ensure the GNU Lesser General Public License version 2.1 requirements+
−
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.+
−
**+
−
** In addition, as a special exception, Nokia gives you certain additional+
−
** rights.  These rights are described in the Nokia Qt LGPL Exception+
−
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.+
−
**+
−
** If you have questions regarding the use of this file, please contact+
−
** Nokia at qt-info@nokia.com.+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
** $QT_END_LICENSE$+
−
**+
−
****************************************************************************/+
−
+
−
/*!+
−
    \example widgets/tablet+
−
    \title Tablet Example+
−
+
−
    This example shows how to use a Wacom tablet in Qt applications.+
−
+
−
    \image tabletexample.png+
−
+
−
    When you use a tablet with Qt applications, \l{QTabletEvent}s are+
−
    generated. You need to reimplement the+
−
    \l{QWidget::}{tabletEvent()} event handler if you want to handle+
−
    tablet events. Events are generated when the device used for+
−
    drawing enters and leaves the proximity of the tablet (i.e., when+
−
    it is close but not pressed down on it), when a device is pushed+
−
    down and released from it, and when a device is moved on the+
−
    tablet.+
−
  +
−
    The information available in QTabletEvent depends on the device+
−
    used. The tablet in this example has two different devices for+
−
    drawing: a stylus and an airbrush. For both devices the event+
−
    contains the position of the device, pressure on the tablet,+
−
    vertical tilt, and horizontal tilt (i.e, the angle between the+
−
    device and the perpendicular of the tablet). The airbrush has a+
−
    finger wheel; the position of this is also available in the tablet+
−
    event.+
−
+
−
    In this example we implement a drawing program. You can use the+
−
    stylus to draw on the tablet as you use a pencil on paper. When+
−
    you draw with the airbrush you get a spray of paint; the finger+
−
    wheel is used to change the density of the spray. The pressure and+
−
    tilt can change the alpha and saturation values of the QColor and the+
−
    width of the QPen used for drawing.+
−
+
−
    The example consists of the following:+
−
+
−
    \list+
−
        \o The \c MainWindow class inherits QMainWindow and creates+
−
           the examples menus and connect their slots and signals.+
−
	\o The \c TabletCanvas class inherits QWidget and +
−
	   receives tablet events. It uses the events to paint on a+
−
	   QImage, which it draws onto itself.+
−
	\o The \c TabletApplication class inherits QApplication. This+
−
	   class handles tablet events that are not sent to \c tabletEvent(). +
−
	   We will look at this later.+
−
	\o The \c main() function creates a \c MainWindow and shows it+
−
	   as a top level window.+
−
    \endlist+
−
+
−
+
−
    \section1 MainWindow Class Definition+
−
+
−
    The \c MainWindow creates a \c TabletCanvas and sets it as its +
−
    center widget. +
−
+
−
    \snippet examples/widgets/tablet/mainwindow.h 0+
−
+
−
    The QActions let the user select if the tablets pressure and+
−
    tilt should change the pen width, color alpha component and color+
−
    saturation. \c createActions() creates all actions, and \c+
−
    createMenus() sets up the menus with the actions. We have one+
−
    QActionGroup for the actions that alter the alpha channel, color+
−
    saturation and line width respectively. The action groups are+
−
    connected to the \c alphaActionTriggered(), \c+
−
    colorSaturationActiontriggered(), and \c+
−
    lineWidthActionTriggered() slots, which calls functions in \c+
−
    myCanvas.+
−
+
−
+
−
    \section1 MainWindow Class Implementation+
−
+
−
    We start width a look at the constructor \c MainWindow():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 0+
−
+
−
    In the constructor we create the canvas, actions, and menus.+
−
    We set the canvas as the center widget. We also initialize the+
−
    canvas to match the state of our menus and start drawing with a+
−
    red color.+
−
+
−
    Here is the implementation of \c brushColorAct():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 1+
−
+
−
    We let the user pick a color with a QColorDialog. If it is valid,+
−
    we set a new drawing color with \c setColor().+
−
+
−
    Here is the implementation of \c alphaActionTriggered():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 2+
−
+
−
    The \c TabletCanvas class supports two ways by which the alpha +
−
    channel of the drawing color can be changed: tablet pressure and+
−
    tilt. We have one action for each and an action if the alpha+
−
    channel should not be changed. +
−
+
−
    Here is the implementation of \c lineWidthActionTriggered():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 3+
−
+
−
    We check which action is selected in \c lineWidthGroup, and set+
−
    how the canvas should change the drawing line width.+
−
+
−
    Here is the implementation of \c saturationActionTriggered():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 4+
−
+
−
    We check which action is selected in \c colorSaturationGroup, and+
−
    set how the canvas should change the color saturation of the+
−
    drawing color.+
−
+
−
    Here is the implementation of \c saveAct():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 5+
−
+
−
    We use the QFileDialog to let the user select a file to save the+
−
    drawing in. It is the \c TabletCanvas that save the drawing, so we+
−
    call its \c saveImage() function.+
−
+
−
    Here is the implementation of \c loadAct():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 6+
−
+
−
    We let the user select the image file to be opened with+
−
    a QFileDialog; we then ask the canvas to load the image with \c+
−
    loadImage().+
−
+
−
    Here is the implementation of \c aboutAct():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 7+
−
+
−
    We show a message box with a short description of the example. +
−
+
−
    \c createActions() creates all actions and action groups of+
−
    the example. We look at the creation of one action group and its+
−
    actions. See the \l{Application Example}{application example} if+
−
    you want a high-level introduction to QActions. +
−
+
−
    Here is the implementation of \c createActions:+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 8+
−
    \dots+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 9+
−
+
−
    We want the user to be able to choose if the drawing color's+
−
    alpha component should be changed by the tablet pressure or tilt.+
−
    We have one action for each choice and an action if the alpha+
−
    channel is not to be changed, i.e, the color is opaque. We make+
−
    the actions checkable; the \c alphaChannelGroup will then ensure+
−
    that only one of the actions are checked at any time. The \c+
−
    triggered() signal is emitted when an action is checked.+
−
+
−
    \dots+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 10+
−
+
−
    Here is the implementation of \c createMenus():+
−
+
−
    \snippet examples/widgets/tablet/mainwindow.cpp 11+
−
+
−
    We create the menus of the example and add the actions to them.+
−
+
−
+
−
    \section1 TabletCanvas Class Definition+
−
+
−
    The \c TabletCanvas class provides a surface on which the+
−
    user can draw with a tablet. +
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.h 0+
−
+
−
    The canvas can change the alpha channel, color saturation,+
−
    and line width of the drawing. We have one enum for each of+
−
    these; their values decide if it is the tablet pressure or tilt+
−
    that will alter them. We keep a private variable for each, the \c+
−
    alphaChannelType, \c colorSturationType, and \c penWidthType,+
−
    which we provide access functions for. +
−
+
−
    We draw on a QImage with \c myPen and \c myBrush using \c+
−
    myColor. The \c saveImage() and \c loadImage() saves and loads+
−
    the QImage to disk. The image is drawn on the widget in \c+
−
    paintEvent(). The \c pointerType and \c deviceType keeps the type+
−
    of pointer, which is either a pen or an eraser, and device+
−
    currently used on the tablet, which is either a stylus or an+
−
    airbrush.+
−
+
−
    The interpretation of events from the tablet is done in \c+
−
    tabletEvent(); \c paintImage(), \c updateBrush(), and \c+
−
    brushPattern() are helper functions used by \c tabletEvent().+
−
+
−
+
−
    \section1 TabletCanvas Class Implementation+
−
+
−
    We start with a look at the constructor:+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 0+
−
+
−
    In the constructor we initialize our class variables. We need+
−
    to draw the background of our image, as the default is gray.+
−
+
−
    Here is the implementation of \c saveImage():+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 1+
−
+
−
    QImage implements functionality to save itself to disk, so we+
−
    simply call \l{QImage::}{save()}.+
−
+
−
    Here is the implementation of \c loadImage():+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 2+
−
+
−
    We simply call \l{QImage::}{load()}, which loads the image in \a+
−
    file.+
−
+
−
    Here is the implementation of \c tabletEvent():+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 3+
−
+
−
    We get three kind of events to this function: TabletPress,+
−
    TabletRelease, and TabletMove, which is generated when a device+
−
    is pressed down on, leaves, or moves on the tablet. We set the \c+
−
    deviceDown to true when a device is pressed down on the tablet;+
−
    we then know when we should draw when we receive move events. We+
−
    have implemented the \c updateBrush() and \c paintImage() helper+
−
    functions to update \c myBrush and \c myPen after the state of \c+
−
    alphaChannelType, \c colorSaturationType, and \c lineWidthType.+
−
+
−
    Here is the implementation of \c paintEvent():+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 4+
−
+
−
    We simply draw the image to the top left of the widget.+
−
+
−
    Here is the implementation of \c paintImage():+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 5+
−
+
−
    In this function we draw on the image based on the movement of the+
−
    device. If the device used on the tablet is a stylus we want to draw a+
−
    line between the positions of the stylus recorded in \c polyLine. We+
−
    also assume that this is a reasonable handling of any unknown device,+
−
    but update the statusbar with a warning so that the user can see that+
−
    for his tablet he might have to implement special handling.+
−
    If it is an airbrush we want to draw a circle of points with a+
−
    point density based on the tangential pressure, which is the position+
−
    of the finger wheel on the airbrush. We use the Qt::BrushStyle to+
−
    draw the points as it has styles that draw points with different+
−
    density; we select the style based on the tangential pressure in+
−
    \c brushPattern().+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 6+
−
+
−
    We return a brush style with a point density that increases with+
−
    the tangential pressure.+
−
+
−
    In \c updateBrush() we set the pen and brush used for drawing+
−
    to match \c alphaChannelType, \c lineWidthType, \c+
−
    colorSaturationType, and \c myColor. We will examine the code to+
−
    set up \c myBrush and \c myPen for each of these variables:+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 7+
−
+
−
    We fetch the current drawingcolor's hue, saturation, value,+
−
    and alpha values. \c hValue and \c vValue are set to the+
−
    horizontal and vertical tilt as a number from 0 to 255. The+
−
    original values are in degrees from -60 to 60, i.e., 0 equals+
−
    -60, 127 equals 0, and 255 equals 60 degrees. The angle measured+
−
    is between the device and the perpendicular of the tablet (see+
−
    QTabletEvent for an illustration).+
−
         +
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 8+
−
+
−
    The alpha channel of QColor is given as a number between 0+
−
    and 255 where 0 is transparent and 255 is opaque.+
−
    \l{QTabletEvent::}{pressure()} returns the pressure as a qreal+
−
    between 0.0 and 1.0. By subtracting 127 from the tilt values and+
−
    taking the absolute value we get the smallest alpha values (i.e.,+
−
    the color is most transparent) when the pen is perpendicular to+
−
    the tablet. We select the largest of the vertical and horizontal+
−
    tilt value. +
−
 +
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 9+
−
+
−
    The colorsaturation is given as a number between 0 and 255. It is+
−
    set with \l{QColor::}{setHsv()}. We can set the tilt values+
−
    directly, but must multiply the pressure to a number between 0 and+
−
    255.+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 10+
−
+
−
    The width of the pen increases with the pressure. When the pen+
−
    width is controlled with the tilt we let the width increse with+
−
    the angle between the device and the perpendicular of the tablet.+
−
+
−
    \snippet examples/widgets/tablet/tabletcanvas.cpp 11+
−
   +
−
    We finally check wether the pointer is the stylus or the eraser.+
−
    If it is the eraser, we set the color to the background color of+
−
    the image an let the pressure decide the pen width, else we set+
−
    the colors we have set up previously in the function.+
−
+
−
+
−
    \section1 TabletApplication Class Definition+
−
+
−
    We inherit QApplication in this class because we want to+
−
    reimplement the \l{QApplication::}{event()} function. +
−
+
−
    \snippet examples/widgets/tablet/tabletapplication.h 0+
−
+
−
    We keep a \c TabletCanvas we send the device type of the events we+
−
    handle in the \c event() function to. The TabletEnterProximity+
−
    and TabletLeaveProximity events are not sendt to the QApplication+
−
    object, while other tablet events are sendt to the QWidget's+
−
    \c event(), which sends them on to \l{QWidget::}{tabletEvent()}.+
−
    Since we want to handle these events we have implemented \c +
−
    TabletApplication.+
−
+
−
+
−
    \section1 TabletApplication Class Implementation+
−
+
−
    Here is the implementation of \c event():+
−
+
−
    \snippet examples/widgets/tablet/tabletapplication.cpp 0+
−
+
−
    We use this function to handle the TabletEnterProximity and+
−
    TabletLeaveProximity events, which is generated when a device+
−
    enters and leaves the proximity of the tablet. The intended use of these+
−
    events is to do work that is dependent on what kind of device is+
−
    used on the tablet. This way, you don't have to do this work+
−
    when other events are generated, which is more frequently than the+
−
    leave and enter proximity events. We call \c setTabletDevice() in +
−
    \c TabletCanvas.+
−
+
−
    \section1 The \c main() function+
−
+
−
    Here is the examples \c main() function:+
−
+
−
    \snippet examples/widgets/tablet/main.cpp 0+
−
+
−
    In the \c main() function we create a \c MainWinow and display it+
−
    as a top level window. We use the \c TabletApplication class. We+
−
    need to set the canvas after the application is created. We cannot+
−
    use classes that implement event handling before an QApplication+
−
    object is instantiated.+
−
*/+
−