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
new file mode 100644
index 0000000000..82fcb7617f
--- /dev/null
+++ b/doc/src/images/widgets/mousebutton-buttontester.png