Long live Qt 4.5!

1 files changed, 232 insertions, 0 deletions

diff --git a/doc/src/examples/menus.qdoc b/doc/src/examples/menus.qdoc
new file mode 100644
index 0000000..0500101
--- /dev/null
+++ b/doc/src/examples/menus.qdoc
@@ -0,0 +1,232 @@
+/****************************************************************************
+**
+** 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$
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.
+*/