path: root/doc
diff options
authorRick Stockton <>2012-02-06 17:20:08 -0800
committerQt by Nokia <>2012-03-06 08:24:22 +0100
commit4a80a7ced1f643a6794f6550d01c1fe60295a21c (patch)
tree599429a64992918870d97ff05d6ab12783dd4847 /doc
parente3027377f0e7598c00b56962f08cb15b568f2356 (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 <>
Diffstat (limited to 'doc')
-rw-r--r--doc/src/images/widgets/mousebutton-buttontester.pngbin0 -> 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 <>
+** Contact:
+** This file is part of the documentation of the Qt Toolkit.
+** 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.
+ \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
--- /dev/null
+++ b/doc/src/images/widgets/mousebutton-buttontester.png
Binary files differ