From 4a80a7ced1f643a6794f6550d01c1fe60295a21c Mon Sep 17 00:00:00 2001 From: Rick Stockton Date: Mon, 6 Feb 2012 17:20:08 -0800 Subject: 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 --- doc/src/examples/widgets/mousebuttons.qdoc | 94 +++++++++++++++++++++ .../images/widgets/mousebutton-buttontester.png | Bin 0 -> 14492 bytes 2 files changed, 94 insertions(+) create mode 100644 doc/src/examples/widgets/mousebuttons.qdoc create mode 100644 doc/src/images/widgets/mousebutton-buttontester.png (limited to 'doc') 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 +** 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 new file mode 100644 index 0000000000..82fcb7617f Binary files /dev/null and b/doc/src/images/widgets/mousebutton-buttontester.png differ -- cgit v1.2.3