1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example mainwindows/menus
\title Menus Example
\brief 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.
*/
|
