| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Copyright (C) 2016 Rick Stockton <rickstockton@reno-computerhelp.com> |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** 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. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example widgets/mousebuttons |
| \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. Receiving 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 |
| mouse 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 |
| \li \c A QPushButton, "Quit". |
| \li \c ButtonTester. This is derived from Qt's TextArea class, for |
| purpose of customizing/re-implementing the mouse and wheel event |
| member functions. |
| \li \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 mousebutton-buttontester.png |
| */ |