source: trunk/doc/src/examples/menus.qdoc@ 550

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at qt-sales@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \example mainwindows/menus
    \title Menus Example

    The Menus example demonstrates how menus can be used in a main
    window application.

    A menu widget can be either a pull-down menu in a menu bar or a
    standalone context menu. Pull-down menus are shown by the menu bar
    when the user clicks on the respective item or presses the
    specified shortcut key. Context menus are usually invoked by some
    special keyboard key or by right-clicking.

    \image menus-example.png

    A menu consists of a list of \e action items. In applications,
    many common commands can be invoked via menus, toolbar buttons as
    well as keyboard shortcuts. Since the user expects the commands to
    be performed in the same way, regardless of the user interface
    used, it is useful to represent each command as an action.

    The Menus example consists of one single class, \c MainWindow, derived
    from the QMainWindow class. When choosing one of the
    action items in our application, it will display the item's path
    in its central widget.

    \section1 MainWindow Class Definition

    QMainWindow provides a main application window, with a menu bar,
    tool bars, dock widgets and a status bar around a large central
    widget.

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

    In this example, we will see how to implement pull-down menus as
    well as a context menu. In order to implement a custom context
    menu we must reimplement QWidget's \l
    {QWidget::}{contextMenuEvent()} function to receive the context
    menu events for our main window.

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

    We must also implement a collection of private slots to respond to
    the user activating any of our menu entries.  Note that these
    slots are left out of this documentation since they are trivial,
    i.e., most of them are only displaying the action's path in the
    main window's central widget.

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

    We have chosen to simplify the constructor by implementing two
    private convenience functions to create the various actions, to
    add them to menus and to insert the menus into our main window's
    menu bar.

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

    Finally, we declare the various menus and actions as well as a
    simple information label in the application wide scope.

    The QMenu class provides a menu widget for use in menu bars,
    context menus, and other popup menus while the QAction class
    provides an abstract user interface action that can be inserted
    into widgets.

    In some situations it is useful to group actions together, e.g.,
    we have a \gui {Left Align} action, a \gui {Right Align} action, a
    \gui {Justify} action, and a \gui {Center} action, and we want
    only one of these actions to be active at any one time. One simple
    way of achieving this is to group the actions together in an
    action group using the QActionGroup class.

    \section1 MainWindow Class Implementation

    In the constructor, we start off by creating a regular QWidget and
    make it our main window's central widget. Note that the main
    window takes ownership of the widget pointer and deletes it at the
    appropriate time.

    \snippet examples/mainwindows/menus/mainwindow.cpp 0
    \codeline
    \snippet examples/mainwindows/menus/mainwindow.cpp 1

    Then we create the information label as well as a top and bottom
    filler that we add to a layout which we install on the central
    widget. QMainWindow objects come with their own customized layout
    and setting a layout on a the actual main window, or creating a
    layout with a main window as a parent, is considered an error. You
    should always set your own layout on the central widget instead.

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

    To create the actions and menus we call our two convenience
    functions: \c createActions() and \c createMenus(). We will get
    back to these shortly.

    QMainWindow's \l {QMainWindow::statusBar()}{statusBar()} function
    returns the status bar for the main window (if the status bar does
    not exist, this function will create and return an empty status
    bar). We initialize the status bar and window title, resize the
    window to an appropriate size as well as ensure that the main
    window cannot be resized to a smaller size than the given
    one.

    Now, let's take a closer look at the \c createActions() convenience
    function that creates the various actions:

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

    A QAction object may contain an icon, a text, a shortcut, a status
    tip, a "What's This?" text, and a tooltip. Most of these can be
    set in the constructor, but they can also be set independently
    using the provided convenience functions.

    In the \c createActions() function, we first create a \c newAct
    action. We make \gui Ctrl+N its shortcut using the
    QAction::setShortcut() function, and we set its status tip using the
    QAction::setStatusTip() function (the status tip is displayed on all
    status bars provided by the action's top-level parent widget). We
    also connect its \l {QAction::}{triggered()} signal to the \c
    newFile() slot.

    The rest of the actions are created in a similar manner. Please
    see the source code for details.

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


    Once we have created the \gui {Left Align}, \gui {Right Align},
    \gui {Justify}, and a \gui {Center} actions, we can also create
    the previously mentioned action group.

    Each action is added to the group using QActionGroup's \l
    {QActionGroup::}{addAction()} function. Note that an action also
    can be added to a group by creating it with the group as its
    parent. Since an action group is exclusive by default, only one of
    the actions in the group is checked at any one time (this can be
    altered using the QActionGroup::setExclusive() function).

    When all the actions are created, we use the \c createMenus()
    function to add the actions to the menus and to insert the menus
    into the menu bar:

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

    QMenuBar's \l {QMenuBar::addMenu()}{addMenu()} function appends a
    new QMenu with the given title, to the menu bar (note that the
    menu bar takes ownership of the menu). We use QWidget's \l
    {QWidget::addAction()}{addAction()} function to add each action to
    the corresponding menu.

    Alternatively, the QMenu class provides several \l
    {QMenu::addAction()}{addAction()} convenience functions that create
    and add new actions from given texts and/or icons. You can also
    provide a member that will automatically connect to the new
    action's \l {QAction::triggered()}{triggered()} signal, and a
    shortcut represented by a QKeySequence instance.

    The QMenu::addSeparator() function creates and returns a new
    separator action, i.e. an action for which QAction::isSeparator()
    returns true, and adds the new action to the menu's list of
    actions.

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

    Note the \gui Format menu. First of all, it is added as a submenu
    to the \gui Edit Menu using QMenu's \l
    {QMenu::addMenu()}{addMenu()} function. Secondly, take a look at the
    alignment actions: In the \c createActions() function we added the
    \c leftAlignAct, \c rightAlignAct, \c justifyAct and \c centerAct
    actions to an action group. Nevertheless, we must add each action
    to the menu separately while the action group does its magic
    behind the scene.

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

    To provide a custom context menu, we must reimplement QWidget's \l
    {QWidget::}{contextMenuEvent()} function to receive the widget's
    context menu events (note that the default implementation simply
    ignores these events).

    Whenever we receive such an event, we create a menu containing the
    \gui Cut, \gui Copy and \gui Paste actions. Context menus can be
    executed either asynchronously using the \l {QMenu::}{popup()}
    function or synchronously using the \l {QMenu::}{exec()}
    function. In this example, we have chosen to show the menu using
    its \l {QMenu::}{exec()} function. By passing the event's position
    as argument we ensure that the context menu appears at the
    expected position.
*/