diff options
author | Rick Stockton <rickstockton@reno-computerhelp.com> | 2012-02-06 17:20:08 -0800 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2012-03-06 08:24:22 +0100 |
commit | 4a80a7ced1f643a6794f6550d01c1fe60295a21c (patch) | |
tree | 599429a64992918870d97ff05d6ab12783dd4847 /doc/src | |
parent | e3027377f0e7598c00b56962f08cb15b568f2356 (diff) |
add widget mousebuttons example 'mousetester'.
This is an xev-like program. A user clicks a mouse button inside the
Window, and the program displays (a) the "raw" button number; (b)
the corresponding Qt::MouseButton name; and (c) the type of mouse Event.
Task-number: QTBUG-24112
Change-Id: I8a76ff37b5b85639f662706072cc4a2ce490754b
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
Diffstat (limited to 'doc/src')
-rw-r--r-- | doc/src/examples/widgets/mousebuttons.qdoc | 94 | ||||
-rw-r--r-- | doc/src/images/widgets/mousebutton-buttontester.png | bin | 0 -> 14492 bytes |
2 files changed, 94 insertions, 0 deletions
diff --git a/doc/src/examples/widgets/mousebuttons.qdoc b/doc/src/examples/widgets/mousebuttons.qdoc new file mode 100644 index 0000000000..bf63cd5076 --- /dev/null +++ b/doc/src/examples/widgets/mousebuttons.qdoc @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Copyright (C) 2012 Rick Stockton <rickstockton@reno-computerhelp.com> +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/mousebuttons/buttontester + \title Mouse Button Tester + + \brief The 'Mouse Button Tester' example demonstrates how to reimplement + mouse events within a custom class. You can also use this program to + verify that Qt is actually receiving mouse events from your mouse. + + Many 'gamer' mouse devices are configured with high-numbered "buttons" + sending text shortcuts for certain games. With such a mouse, no mouse + button events occur: The "mouse" sends keystrokes, and the + 'Mouse Button Tester' Window will not see the event. Receving no event, + it will not repaint the Window with new text describing a \button event. + + And so, in addition to it's use as Qt example code, the program may be + useful s a mouse device tester. Note that there is another example + muouse buttons example which provides the same function, written in QML. + + This program (the Widget-based example) consists of three classes, + in addition to the main() parent program: + + \list + \o \c A QPushButton, "Quit". + \o \c ButtonTester. This is derived from Qt's TextArea class, for + purpose of customizing/re-implementing the mouse and wheel event + member functions. + \o \c A simple QVBoxLayout layout. + \endlist + + First we will review the main program, with it's layout and "Quit" + QPushButton. Then we will take a look at the \c ButtonTester class. + + \section1 The Main Program + + Note that the QPushButton, "Quit", is defined directly within the main() + program, rather than another class. This is a correct way of defining a + "Quit" QPushButton: A "Quit" Button defined inside another + class would result in the destructor of that second class being + called twice. This "Quit" Button uses the traditional Signal/Slot + connection to invoke termination of the QApp, which will properly destroy + its child classes \before terminating itself. + + The remainder of the main() program is concerned with defining the layout, + and applying a minimum size to the customized ButtonTester. + + \section1 ButtonTester Class Definition + + The \c ButtonTester class inherits from QTextEdit, and listens for + mouse events on all possible Qt::MouseButton values. It also listens for + wheel events from the mouse, and indicates the direction of wheel motion + ("up", down", "left", or "right"). It prints short debug messages into + the Window, and also on the console QDebug() stream, when mouse button + and wheel events occur. Our reimplementation of mousePressEvent(), + mouseReleaseEvent(), mouseDoubleClickEvent(), and wheelEvent() "drive" + the program; the other functions simply convert the Qt::MouseButton + values into text strings. + + You should call the ignore() function on any mouse event (or other event) + which your widget-based classes do not use and consume. This function + assures that Qt will propagate the event through each parent widget, + until it is used or propagated to the Window Manager. (Qt attempts to do + this automatically, but it is better programming practice to explicitly + invoke the function.) + + \image widgets/mousebutton-buttontester.png +*/ diff --git a/doc/src/images/widgets/mousebutton-buttontester.png b/doc/src/images/widgets/mousebutton-buttontester.png Binary files differnew file mode 100644 index 0000000000..82fcb7617f --- /dev/null +++ b/doc/src/images/widgets/mousebutton-buttontester.png |