/****************************************************************************

**

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

** All rights reserved.

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

**

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

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

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

** Nokia at qt-info@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.

*/