1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example mainwindows/menus

    44     \title Menus Example

    45 

    46     The Menus example demonstrates how menus can be used in a main

    47     window application.

    48 

    49     A menu widget can be either a pull-down menu in a menu bar or a

    50     standalone context menu. Pull-down menus are shown by the menu bar

    51     when the user clicks on the respective item or presses the

    52     specified shortcut key. Context menus are usually invoked by some

    53     special keyboard key or by right-clicking.

    54 

    55     \image menus-example.png

    56 

    57     A menu consists of a list of \e action items. In applications,

    58     many common commands can be invoked via menus, toolbar buttons as

    59     well as keyboard shortcuts. Since the user expects the commands to

    60     be performed in the same way, regardless of the user interface

    61     used, it is useful to represent each command as an action.

    62 

    63     The Menus example consists of one single class, \c MainWindow, derived

    64     from the QMainWindow class. When choosing one of the

    65     action items in our application, it will display the item's path

    66     in its central widget.

    67 

    68     \section1 MainWindow Class Definition

    69 

    70     QMainWindow provides a main application window, with a menu bar,

    71     tool bars, dock widgets and a status bar around a large central

    72     widget.

    73 

    74     \snippet examples/mainwindows/menus/mainwindow.h 0

    75 

    76     In this example, we will see how to implement pull-down menus as

    77     well as a context menu. In order to implement a custom context

    78     menu we must reimplement QWidget's \l

    79     {QWidget::}{contextMenuEvent()} function to receive the context

    80     menu events for our main window.

    81 

    82     \snippet examples/mainwindows/menus/mainwindow.h 1

    83 

    84     We must also implement a collection of private slots to respond to

    85     the user activating any of our menu entries.  Note that these

    86     slots are left out of this documentation since they are trivial,

    87     i.e., most of them are only displaying the action's path in the

    88     main window's central widget.

    89 

    90     \snippet examples/mainwindows/menus/mainwindow.h 2

    91 

    92     We have chosen to simplify the constructor by implementing two

    93     private convenience functions to create the various actions, to

    94     add them to menus and to insert the menus into our main window's

    95     menu bar.

    96 

    97     \snippet examples/mainwindows/menus/mainwindow.h 3

    98 

    99     Finally, we declare the various menus and actions as well as a

   100     simple information label in the application wide scope.

   101 

   102     The QMenu class provides a menu widget for use in menu bars,

   103     context menus, and other popup menus while the QAction class

   104     provides an abstract user interface action that can be inserted

   105     into widgets.

   106 

   107     In some situations it is useful to group actions together, e.g.,

   108     we have a \gui {Left Align} action, a \gui {Right Align} action, a

   109     \gui {Justify} action, and a \gui {Center} action, and we want

   110     only one of these actions to be active at any one time. One simple

   111     way of achieving this is to group the actions together in an

   112     action group using the QActionGroup class.

   113 

   114     \section1 MainWindow Class Implementation

   115 

   116     In the constructor, we start off by creating a regular QWidget and

   117     make it our main window's central widget. Note that the main

   118     window takes ownership of the widget pointer and deletes it at the

   119     appropriate time.

   120 

   121     \snippet examples/mainwindows/menus/mainwindow.cpp 0

   122     \codeline

   123     \snippet examples/mainwindows/menus/mainwindow.cpp 1

   124 

   125     Then we create the information label as well as a top and bottom

   126     filler that we add to a layout which we install on the central

   127     widget. QMainWindow objects come with their own customized layout

   128     and setting a layout on a the actual main window, or creating a

   129     layout with a main window as a parent, is considered an error. You

   130     should always set your own layout on the central widget instead.

   131 

   132     \snippet examples/mainwindows/menus/mainwindow.cpp 2

   133 

   134     To create the actions and menus we call our two convenience

   135     functions: \c createActions() and \c createMenus(). We will get

   136     back to these shortly.

   137 

   138     QMainWindow's \l {QMainWindow::statusBar()}{statusBar()} function

   139     returns the status bar for the main window (if the status bar does

   140     not exist, this function will create and return an empty status

   141     bar). We initialize the status bar and window title, resize the

   142     window to an appropriate size as well as ensure that the main

   143     window cannot be resized to a smaller size than the given

   144     one.

   145 

   146     Now, let's take a closer look at the \c createActions() convenience

   147     function that creates the various actions:

   148 

   149     \snippet examples/mainwindows/menus/mainwindow.cpp 4

   150     \dots

   151 

   152     A QAction object may contain an icon, a text, a shortcut, a status

   153     tip, a "What's This?" text, and a tooltip. Most of these can be

   154     set in the constructor, but they can also be set independently

   155     using the provided convenience functions.

   156 

   157     In the \c createActions() function, we first create a \c newAct

   158     action. We make \gui Ctrl+N its shortcut using the

   159     QAction::setShortcut() function, and we set its status tip using the

   160     QAction::setStatusTip() function (the status tip is displayed on all

   161     status bars provided by the action's top-level parent widget). We

   162     also connect its \l {QAction::}{triggered()} signal to the \c

   163     newFile() slot.

   164 

   165     The rest of the actions are created in a similar manner. Please

   166     see the source code for details.

   167 

   168     \snippet examples/mainwindows/menus/mainwindow.cpp 7

   169 

   170 

   171     Once we have created the \gui {Left Align}, \gui {Right Align},

   172     \gui {Justify}, and a \gui {Center} actions, we can also create

   173     the previously mentioned action group.

   174 

   175     Each action is added to the group using QActionGroup's \l

   176     {QActionGroup::}{addAction()} function. Note that an action also

   177     can be added to a group by creating it with the group as its

   178     parent. Since an action group is exclusive by default, only one of

   179     the actions in the group is checked at any one time (this can be

   180     altered using the QActionGroup::setExclusive() function).

   181 

   182     When all the actions are created, we use the \c createMenus()

   183     function to add the actions to the menus and to insert the menus

   184     into the menu bar:

   185 

   186     \snippet examples/mainwindows/menus/mainwindow.cpp 8

   187 

   188     QMenuBar's \l {QMenuBar::addMenu()}{addMenu()} function appends a

   189     new QMenu with the given title, to the menu bar (note that the

   190     menu bar takes ownership of the menu). We use QWidget's \l

   191     {QWidget::addAction()}{addAction()} function to add each action to

   192     the corresponding menu.

   193 

   194     Alternatively, the QMenu class provides several \l

   195     {QMenu::addAction()}{addAction()} convenience functions that create

   196     and add new actions from given texts and/or icons. You can also

   197     provide a member that will automatically connect to the new

   198     action's \l {QAction::triggered()}{triggered()} signal, and a

   199     shortcut represented by a QKeySequence instance.

   200 

   201     The QMenu::addSeparator() function creates and returns a new

   202     separator action, i.e. an action for which QAction::isSeparator()

   203     returns true, and adds the new action to the menu's list of

   204     actions.

   205 

   206     \snippet examples/mainwindows/menus/mainwindow.cpp 12

   207 

   208     Note the \gui Format menu. First of all, it is added as a submenu

   209     to the \gui Edit Menu using QMenu's \l

   210     {QMenu::addMenu()}{addMenu()} function. Secondly, take a look at the

   211     alignment actions: In the \c createActions() function we added the

   212     \c leftAlignAct, \c rightAlignAct, \c justifyAct and \c centerAct

   213     actions to an action group. Nevertheless, we must add each action

   214     to the menu separately while the action group does its magic

   215     behind the scene.

   216 

   217     \snippet examples/mainwindows/menus/mainwindow.cpp 3

   218 

   219     To provide a custom context menu, we must reimplement QWidget's \l

   220     {QWidget::}{contextMenuEvent()} function to receive the widget's

   221     context menu events (note that the default implementation simply

   222     ignores these events).

   223 

   224     Whenever we receive such an event, we create a menu containing the

   225     \gui Cut, \gui Copy and \gui Paste actions. Context menus can be

   226     executed either asynchronously using the \l {QMenu::}{popup()}

   227     function or synchronously using the \l {QMenu::}{exec()}

   228     function. In this example, we have chosen to show the menu using

   229     its \l {QMenu::}{exec()} function. By passing the event's position

   230     as argument we ensure that the context menu appears at the

   231     expected position.

   232 */