qt5base-lts/examples/widgets/doc/mousebuttons.qdoc

/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Copyright (C) 2012 Rick Stockton <rickstockton@reno-computerhelp.com>
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.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
*/