doc/src/examples/menus.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \example mainwindows/menus
  30     \title Menus Example
  31
  32     \brief The Menus example demonstrates how menus can be used in a main
  33     window application.
  34
  35     A menu widget can be either a pull-down menu in a menu bar or a
  36     standalone context menu. Pull-down menus are shown by the menu bar
  37     when the user clicks on the respective item or presses the
  38     specified shortcut key. Context menus are usually invoked by some
  39     special keyboard key or by right-clicking.
  40
  41     \image menus-example.png
  42
  43     A menu consists of a list of \e action items. In applications,
  44     many common commands can be invoked via menus, toolbar buttons as
  45     well as keyboard shortcuts. Since the user expects the commands to
  46     be performed in the same way, regardless of the user interface
  47     used, it is useful to represent each command as an action.
  48
  49     The Menus example consists of one single class, \c MainWindow, derived
  50     from the QMainWindow class. When choosing one of the
  51     action items in our application, it will display the item's path
  52     in its central widget.
  53
  54     \section1 MainWindow Class Definition
  55
  56     QMainWindow provides a main application window, with a menu bar,
  57     tool bars, dock widgets and a status bar around a large central
  58     widget.
  59
  60     \snippet examples/mainwindows/menus/mainwindow.h 0
  61
  62     In this example, we will see how to implement pull-down menus as
  63     well as a context menu. In order to implement a custom context
  64     menu we must reimplement QWidget's \l
  65     {QWidget::}{contextMenuEvent()} function to receive the context
  66     menu events for our main window.
  67
  68     \snippet examples/mainwindows/menus/mainwindow.h 1
  69
  70     We must also implement a collection of private slots to respond to
  71     the user activating any of our menu entries.  Note that these
  72     slots are left out of this documentation since they are trivial,
  73     i.e., most of them are only displaying the action's path in the
  74     main window's central widget.
  75
  76     \snippet examples/mainwindows/menus/mainwindow.h 2
  77
  78     We have chosen to simplify the constructor by implementing two
  79     private convenience functions to create the various actions, to
  80     add them to menus and to insert the menus into our main window's
  81     menu bar.
  82
  83     \snippet examples/mainwindows/menus/mainwindow.h 3
  84
  85     Finally, we declare the various menus and actions as well as a
  86     simple information label in the application wide scope.
  87
  88     The QMenu class provides a menu widget for use in menu bars,
  89     context menus, and other popup menus while the QAction class
  90     provides an abstract user interface action that can be inserted
  91     into widgets.
  92
  93     In some situations it is useful to group actions together, e.g.,
  94     we have a \gui {Left Align} action, a \gui {Right Align} action, a
  95     \gui {Justify} action, and a \gui {Center} action, and we want
  96     only one of these actions to be active at any one time. One simple
  97     way of achieving this is to group the actions together in an
  98     action group using the QActionGroup class.
  99
 100     \section1 MainWindow Class Implementation
 101
 102     In the constructor, we start off by creating a regular QWidget and
 103     make it our main window's central widget. Note that the main
 104     window takes ownership of the widget pointer and deletes it at the
 105     appropriate time.
 106
 107     \snippet examples/mainwindows/menus/mainwindow.cpp 0
 108     \codeline
 109     \snippet examples/mainwindows/menus/mainwindow.cpp 1
 110
 111     Then we create the information label as well as a top and bottom
 112     filler that we add to a layout which we install on the central
 113     widget. QMainWindow objects come with their own customized layout
 114     and setting a layout on a the actual main window, or creating a
 115     layout with a main window as a parent, is considered an error. You
 116     should always set your own layout on the central widget instead.
 117
 118     \snippet examples/mainwindows/menus/mainwindow.cpp 2
 119
 120     To create the actions and menus we call our two convenience
 121     functions: \c createActions() and \c createMenus(). We will get
 122     back to these shortly.
 123
 124     QMainWindow's \l {QMainWindow::statusBar()}{statusBar()} function
 125     returns the status bar for the main window (if the status bar does
 126     not exist, this function will create and return an empty status
 127     bar). We initialize the status bar and window title, resize the
 128     window to an appropriate size as well as ensure that the main
 129     window cannot be resized to a smaller size than the given
 130     one.
 131
 132     Now, let's take a closer look at the \c createActions() convenience
 133     function that creates the various actions:
 134
 135     \snippet examples/mainwindows/menus/mainwindow.cpp 4
 136     \dots
 137
 138     A QAction object may contain an icon, a text, a shortcut, a status
 139     tip, a "What's This?" text, and a tooltip. Most of these can be
 140     set in the constructor, but they can also be set independently
 141     using the provided convenience functions.
 142
 143     In the \c createActions() function, we first create a \c newAct
 144     action. We make \gui Ctrl+N its shortcut using the
 145     QAction::setShortcut() function, and we set its status tip using the
 146     QAction::setStatusTip() function (the status tip is displayed on all
 147     status bars provided by the action's top-level parent widget). We
 148     also connect its \l {QAction::}{triggered()} signal to the \c
 149     newFile() slot.
 150
 151     The rest of the actions are created in a similar manner. Please
 152     see the source code for details.
 153
 154     \snippet examples/mainwindows/menus/mainwindow.cpp 7
 155
 156
 157     Once we have created the \gui {Left Align}, \gui {Right Align},
 158     \gui {Justify}, and a \gui {Center} actions, we can also create
 159     the previously mentioned action group.
 160
 161     Each action is added to the group using QActionGroup's \l
 162     {QActionGroup::}{addAction()} function. Note that an action also
 163     can be added to a group by creating it with the group as its
 164     parent. Since an action group is exclusive by default, only one of
 165     the actions in the group is checked at any one time (this can be
 166     altered using the QActionGroup::setExclusive() function).
 167
 168     When all the actions are created, we use the \c createMenus()
 169     function to add the actions to the menus and to insert the menus
 170     into the menu bar:
 171
 172     \snippet examples/mainwindows/menus/mainwindow.cpp 8
 173
 174     QMenuBar's \l {QMenuBar::addMenu()}{addMenu()} function appends a
 175     new QMenu with the given title, to the menu bar (note that the
 176     menu bar takes ownership of the menu). We use QWidget's \l
 177     {QWidget::addAction()}{addAction()} function to add each action to
 178     the corresponding menu.
 179
 180     Alternatively, the QMenu class provides several \l
 181     {QMenu::addAction()}{addAction()} convenience functions that create
 182     and add new actions from given texts and/or icons. You can also
 183     provide a member that will automatically connect to the new
 184     action's \l {QAction::triggered()}{triggered()} signal, and a
 185     shortcut represented by a QKeySequence instance.
 186
 187     The QMenu::addSeparator() function creates and returns a new
 188     separator action, i.e. an action for which QAction::isSeparator()
 189     returns true, and adds the new action to the menu's list of
 190     actions.
 191
 192     \snippet examples/mainwindows/menus/mainwindow.cpp 12
 193
 194     Note the \gui Format menu. First of all, it is added as a submenu
 195     to the \gui Edit Menu using QMenu's \l
 196     {QMenu::addMenu()}{addMenu()} function. Secondly, take a look at the
 197     alignment actions: In the \c createActions() function we added the
 198     \c leftAlignAct, \c rightAlignAct, \c justifyAct and \c centerAct
 199     actions to an action group. Nevertheless, we must add each action
 200     to the menu separately while the action group does its magic
 201     behind the scene.
 202
 203     \snippet examples/mainwindows/menus/mainwindow.cpp 3
 204
 205     To provide a custom context menu, we must reimplement QWidget's \l
 206     {QWidget::}{contextMenuEvent()} function to receive the widget's
 207     context menu events (note that the default implementation simply
 208     ignores these events).
 209
 210     Whenever we receive such an event, we create a menu containing the
 211     \gui Cut, \gui Copy and \gui Paste actions. Context menus can be
 212     executed either asynchronously using the \l {QMenu::}{popup()}
 213     function or synchronously using the \l {QMenu::}{exec()}
 214     function. In this example, we have chosen to show the menu using
 215     its \l {QMenu::}{exec()} function. By passing the event's position
 216     as argument we ensure that the context menu appears at the
 217     expected position.
 218 */