QAction class provides an abstract user interface action that can be inserted into widgets. 更多...
Header: | #include <QAction> |
qmake: | QT += widgets |
继承: | QObject |
继承者: |
enum | ActionEvent { Trigger, Hover } |
enum | MenuRole { NoRole, TextHeuristicRole, ApplicationSpecificRole, AboutQtRole, ..., QuitRole } |
enum | Priority { LowPriority, NormalPriority, HighPriority } |
|
|
QAction (QObject * parent = nullptr) | |
QAction (const QString & text , QObject * parent = nullptr) | |
QAction (const QIcon & icon , const QString & text , QObject * parent = nullptr) | |
virtual | ~QAction () |
QActionGroup * | actionGroup () const |
void | activate (QAction::ActionEvent event ) |
QList<QGraphicsWidget *> | associatedGraphicsWidgets () const |
QList<QWidget *> | associatedWidgets () const |
bool | autoRepeat () const |
QVariant | data () const |
QFont | font () const |
QIcon | icon () const |
QString | iconText () const |
bool | isCheckable () const |
bool | isChecked () const |
bool | isEnabled () const |
bool | isIconVisibleInMenu () const |
bool | isSeparator () const |
bool | isShortcutVisibleInContextMenu () const |
bool | isVisible () const |
QMenu * | menu () const |
QAction::MenuRole | menuRole () const |
QWidget * | parentWidget () const |
QAction::Priority | priority () const |
void | setActionGroup (QActionGroup * group ) |
void | setAutoRepeat ( bool ) |
void | setCheckable ( bool ) |
void | setData (const QVariant & userData ) |
void | setFont (const QFont & font ) |
void | setIcon (const QIcon & icon ) |
void | setIconText (const QString & text ) |
void | setIconVisibleInMenu (bool visible ) |
void | setMenu (QMenu * menu ) |
void | setMenuRole (QAction::MenuRole menuRole ) |
void | setPriority (QAction::Priority priority ) |
void | setSeparator (bool b ) |
void | setShortcut (const QKeySequence & shortcut ) |
void | setShortcutContext (Qt::ShortcutContext context ) |
void | setShortcutVisibleInContextMenu (bool show ) |
void | setShortcuts (const QList<QKeySequence> & shortcuts ) |
void | setShortcuts (QKeySequence::StandardKey key ) |
void | setStatusTip (const QString & statusTip ) |
void | setText (const QString & text ) |
void | setToolTip (const QString & tip ) |
void | setWhatsThis (const QString & what ) |
QKeySequence | shortcut () const |
Qt::ShortcutContext | shortcutContext () const |
QList<QKeySequence> | shortcuts () const |
bool | showStatusText (QWidget * widget = nullptr) |
QString | statusTip () const |
QString | text () const |
QString | toolTip () const |
QString | whatsThis () const |
void | hover () |
void | setChecked ( bool ) |
void | setDisabled (bool b ) |
void | setEnabled ( bool ) |
void | setVisible ( bool ) |
void | toggle () |
void | trigger () |
const QMetaObject | staticMetaObject |
virtual bool | event (QEvent * e ) override |
QAction class provides an abstract user interface action that can be inserted into widgets.
In applications many common commands can be invoked via menus, toolbar buttons, and keyboard shortcuts. Since the user expects each command to be performed in the same way, regardless of the user interface used, it is useful to represent each command as an action .
Actions can be added to menus and toolbars, and will automatically keep them in sync. For example, in a word processor, if the user presses a Bold toolbar button, the Bold menu item will automatically be checked.
Actions can be created as independent objects, but they may also be created during the construction of menus; the QMenu class contains convenience functions for creating actions suitable for use as menu items.
A QAction may contain an icon, menu text, a shortcut, status text, "What's This?" text, and a tooltip. Most of these can be set in the constructor. They can also be set independently with setIcon (), setText (), setIconText (), setShortcut (), setStatusTip (), setWhatsThis (),和 setToolTip (). For menu items, it is possible to set an individual font with setFont ().
Actions are added to widgets using QWidget::addAction () 或 QGraphicsWidget::addAction (). Note that an action must be added to a widget before it can be used; this is also true when the shortcut should be global (i.e., Qt::ApplicationShortcut as Qt::ShortcutContext ).
一旦 QAction has been created it should be added to the relevant menu and toolbar, then connected to the slot which will perform the action. For example:
const QIcon openIcon = QIcon::fromTheme("document-open", QIcon(":/images/open.png")); QAction *openAct = new QAction(openIcon, tr("&Open..."), this); openAct->setShortcuts(QKeySequence::Open); openAct->setStatusTip(tr("Open an existing file")); connect(openAct, &QAction::triggered, this, &MainWindow::open); fileMenu->addAction(openAct); fileToolBar->addAction(openAct);
We recommend that actions are created as children of the window they are used in. In most cases actions will be children of the application's main window.
另请参阅 QMenu , QToolBar ,和 应用程序范例 .
此枚举类型会被使用,当调用 QAction::activate ()
常量 | 值 | 描述 |
---|---|---|
QAction::Trigger
|
0
|
这将导致 QAction::triggered () 信号被发射。 |
QAction::Hover
|
1
|
这将导致 QAction::hovered () 信号被发射。 |
This enum describes how an action should be moved into the application menu on macOS .
常量 | 值 | 描述 |
---|---|---|
QAction::NoRole
|
0
|
This action should not be put into the application menu |
QAction::TextHeuristicRole
|
1
|
This action should be put in the application menu based on the action's text as described in the QMenuBar 文档编制。 |
QAction::ApplicationSpecificRole
|
2
|
This action should be put in the application menu with an application specific role |
QAction::AboutQtRole
|
3
|
This action handles the "About Qt" menu item. |
QAction::AboutRole
|
4
|
This action should be placed where the "About" menu item is in the application menu. The text of the menu item will be set to "About <application name>". The application name is fetched from the
Info.plist
file in the application's bundle (See
Qt for macOS - 部署
).
|
QAction::PreferencesRole
|
5
|
This action should be placed where the "Preferences..." menu item is in the application menu. |
QAction::QuitRole
|
6
|
This action should be placed where the Quit menu item is in the application menu. |
Setting this value only has effect on items that are in the immediate menus of the menubar, not the submenus of those menus. For example, if you have File menu in your menubar and the File menu has a submenu, setting the MenuRole for the actions in that submenu have no effect. They will never be moved.
此枚举定义用户界面中动作的优先级。
常量 | 值 | 描述 |
---|---|---|
QAction::LowPriority
|
0
|
动作不应该在用户界面中被优先。 |
QAction::NormalPriority
|
128
|
|
QAction::HighPriority
|
256
|
动作应该在用户界面中被优先。 |
This enum was introduced or modified in Qt 4.6.
另请参阅 priority .
此特性保持动作是否可以自动重复
若为 true,动作会自动重复当按下键盘快捷方式组合时,前提是系统启用了键盘自动重复。默认值为 true。
This property was introduced in Qt 4.2.
访问函数:
bool | autoRepeat () const |
void | setAutoRepeat ( bool ) |
通知信号:
void | changed () |
此特性保持动作是否为可复选动作
A checkable action is one which has an on/off state. For example, in a word processor, a Bold toolbar button may be either on or off. An action which is not a toggle action is a command action; a command action is simply executed, e.g. file save. By default, this property is
false
.
In some situations, the state of one toggle action should depend on the state of others. For example, "Left Align", "Center" and "Right Align" toggle actions are mutually exclusive. To achieve exclusive toggling, add the relevant toggle actions to a QActionGroup with the QActionGroup::exclusive property set to true.
访问函数:
bool | isCheckable () const |
void | setCheckable ( bool ) |
通知信号:
void | changed () |
另请参阅 QAction::setChecked ().
此特性保持动作是否被复选。
仅可复选动作可以被复选。默认情况下,这为 false (动作未被复选)。
注意: 此特性的通知信号为 toggled ()。作为触发 QAction 改变其状态,它还会发射 changed () 信号。
访问函数:
bool | isChecked () const |
void | setChecked ( bool ) |
通知信号:
void | toggled (bool checked ) |
另请参阅 checkable and toggled ().
此特性保持动作是否被启用
Disabled actions cannot be chosen by the user. They do not disappear from menus or toolbars, but they are displayed in a way which indicates that they are unavailable. For example, they might be displayed using only shades of gray.
What's This? help on disabled actions is still available, provided that the QAction::whatsThis property is set.
An action will be disabled when all widgets to which it is added (with QWidget::addAction ()) are disabled or not visible. When an action is disabled, it is not possible to trigger it through its shortcut.
默认情况下,此特性为
true
(动作被启用)。
访问函数:
bool | isEnabled () const |
void | setEnabled ( bool ) |
通知信号:
void | changed () |
另请参阅 text .
此特性保持动作的字体
字体特性用于渲染文本设置在 QAction 。字体被认为是提示,因为在所有情况下都不会基于应用程序和样式咨询字体。
默认情况下,此特性包含应用程序默认字体。
访问函数:
QFont | font () const |
void | setFont (const QFont & font ) |
通知信号:
void | changed () |
另请参阅 QAction::setText () 和 QStyle .
此特性保持动作的图标
In toolbars, the icon is used as the tool button icon; in menus, it is displayed to the left of the menu text. There is no default icon.
若 null 图标 ( QIcon::isNull ()) 被传入此函数,动作图标被清零。
访问函数:
QIcon | icon () const |
void | setIcon (const QIcon & icon ) |
通知信号:
void | changed () |
此特性保持动作的描述性图标文本
若 QToolBar::toolButtonStyle is set to a value that permits text to be displayed, the text defined held in this property appears as a label in the relevant tool button.
It also serves as the default text in menus and tooltips if the action has not been defined with setText () 或 setToolTip (), and will also be used in toolbar buttons if no icon has been defined using setIcon ().
If the icon text is not explicitly set, the action's normal text will be used for the icon text.
默认情况下,此特性包含空字符串。
访问函数:
QString | iconText () const |
void | setIconText (const QString & text ) |
通知信号:
void | changed () |
另请参阅 setToolTip () 和 setStatusTip ().
This property holds whether or not an action should show an icon in a menu
In some applications, it may make sense to have actions with icons in the toolbar, but not in menus. If true, the icon (if valid) is shown in the menu, when it is false, it is not shown.
The default is to follow whether the Qt::AA_DontShowIconsInMenus attribute is set for the application. Explicitly settings this property overrides the presence (or abscence) of the attribute.
例如:
QApplication app(argc, argv); app.setAttribute(Qt::AA_DontShowIconsInMenus); // Icons are *no longer shown* in menus // ... QAction *myAction = new QAction(); // ... myAction->setIcon(SomeIcon); myAction->setIconVisibleInMenu(true); // Icon *will* be shown in menus for *this* action.
This property was introduced in Qt 4.4.
访问函数:
bool | isIconVisibleInMenu () const |
void | setIconVisibleInMenu (bool visible ) |
通知信号:
void | changed () |
另请参阅 QAction::icon and QCoreApplication::setAttribute ().
此特性保持动作的菜单角色
This indicates what role the action serves in the application menu on macOS . By default all actions have the TextHeuristicRole , which means that the action is added based on its text (see QMenuBar for more information).
The menu role can only be changed before the actions are put into the menu bar in macOS (usually just before the first application window is shown).
This property was introduced in Qt 4.2.
访问函数:
QAction::MenuRole | menuRole () const |
void | setMenuRole (QAction::MenuRole menuRole ) |
通知信号:
void | changed () |
此特性保持在用户界面中动作的优先级。
This property can be set to indicate how the action should be prioritized in the user interface.
For instance, when toolbars have the Qt::ToolButtonTextBesideIcon mode set, then actions with LowPriority will not show the text labels.
This property was introduced in Qt 4.6.
访问函数:
QAction::Priority | priority () const |
void | setPriority (QAction::Priority priority ) |
此特性保持动作的首要快捷键
此特性的有效键码可以找到,在 Qt::Key and Qt::Modifier 。没有默认的快捷键。
访问函数:
QKeySequence | shortcut () const |
void | setShortcut (const QKeySequence & shortcut ) |
通知信号:
void | changed () |
此特性保持动作快捷方式的上下文
可以找到此特性的有效值在 Qt::ShortcutContext 。默认值为 Qt::WindowShortcut .
访问函数:
Qt::ShortcutContext | shortcutContext () const |
void | setShortcutContext (Qt::ShortcutContext context ) |
通知信号:
void | changed () |
This property holds whether or not an action should show a shortcut in a context menu
In some applications, it may make sense to have actions with shortcuts in context menus. If true, the shortcut (if valid) is shown when the action is shown via a context menu, when it is false, it is not shown.
The default is to follow whether the Qt::AA_DontShowShortcutsInContextMenus attribute is set for the application, falling back to the widget style hint. Explicitly setting this property overrides the presence (or abscence) of the attribute.
This property was introduced in Qt 5.10.
访问函数:
bool | isShortcutVisibleInContextMenu () const |
void | setShortcutVisibleInContextMenu (bool show ) |
通知信号:
void | changed () |
另请参阅 QAction::shortcut and QCoreApplication::setAttribute ().
此特性保持动作的状态提示
状态提示显示在由动作的顶层父级 Widget 提供的所有状态栏上。
默认情况下,此特性包含空字符串。
访问函数:
QString | statusTip () const |
void | setStatusTip (const QString & statusTip ) |
通知信号:
void | changed () |
另请参阅 setToolTip () 和 showStatusText ().
此特性保持动作的描述性文本
If the action is added to a menu, the menu option will consist of the icon (if there is one), the text, and the shortcut (if there is one). If the text is not explicitly set in the constructor, or by using setText(), the action's description icon text will be used as text. There is no default text.
访问函数:
QString | text () const |
void | setText (const QString & text ) |
通知信号:
void | changed () |
另请参阅 iconText .
此特性保持动作的工具提示
此文本用于工具提示。若工具提示未指定,使用动作文本。
默认情况下,此特性包含动作的文本。
访问函数:
QString | toolTip () const |
void | setToolTip (const QString & tip ) |
通知信号:
void | changed () |
另请参阅 setStatusTip () 和 setShortcut ().
This property holds whether the action can be seen (e.g. in menus and toolbars)
若 visible is true the action can be seen (e.g. in menus and toolbars) and chosen by the user; if visible is false the action cannot be seen or chosen by the user.
Actions which are not visible are not grayed out; they do not appear at all.
默认情况下,此特性为
true
(动作可见)。
访问函数:
bool | isVisible () const |
void | setVisible ( bool ) |
通知信号:
void | changed () |
此特性保持动作的 What's This? 帮助文本
The "What's This?" text is used to provide a brief description of the action. The text may contain rich text. There is no default "What's This?" text.
访问函数:
QString | whatsThis () const |
void | setWhatsThis (const QString & what ) |
通知信号:
void | changed () |
另请参阅 QWhatsThis .
构造动作采用 parent 。若 parent 是动作组,动作会被自动插入组中。
注意: parent 自变量是可选的,从 Qt 5.7 起。
构造动作采用一些 text and parent 。若 parent 是动作组,动作会被自动插入组中。
The action uses a stripped version of text (e.g. "&Menu Option..." becomes "Menu Option") as descriptive text for tool buttons. You can override this by setting a specific description with setText (). The same text will be used for tooltips unless you specify a different text using setToolTip ().
构造动作采用 icon 和一些 text and parent 。若 parent 是动作组,动作会被自动插入组中。
The action uses a stripped version of text (e.g. "&Menu Option..." becomes "Menu Option") as descriptive text for tool buttons. You can override this by setting a specific description with setText (). The same text will be used for tooltips unless you specify a different text using setToolTip ().
[virtual]
QAction::
~QAction
()
销毁对象并释放分配的资源。
Returns the action group for this action. If no action group manages this action then 0 will be returned.
另请参阅 QActionGroup and QAction::setActionGroup ().
发送相关信号为 ActionEvent event .
基于动作的 Widget 使用此 API 以促使 QAction 去发射信号及发射它们自己。
返回已添加此动作的小部件列表。
This function was introduced in Qt 4.5.
另请参阅 QWidget::addAction () 和 associatedWidgets ().
返回已添加此动作的小部件列表。
This function was introduced in Qt 4.2.
另请参阅 QWidget::addAction () 和 associatedGraphicsWidgets ().
[signal]
void
QAction::
changed
()
This signal is emitted when an action has changed. If you are only interested in actions in a given widget, you can watch for QWidget::actionEvent () sent with an QEvent::ActionChanged .
注意: 通知信号为特性 autoRepeat . Notifier signal for property checkable . Notifier signal for property enabled . Notifier signal for property font . Notifier signal for property icon . Notifier signal for property iconText . Notifier signal for property iconVisibleInMenu . Notifier signal for property menuRole . Notifier signal for property shortcut . Notifier signal for property shortcutContext . Notifier signal for property shortcutVisibleInContextMenu . Notifier signal for property statusTip . Notifier signal for property text . Notifier signal for property toolTip . Notifier signal for property visible . Notifier signal for property whatsThis .
另请参阅 QWidget::actionEvent ().
返回用户设置数据在 QAction::setData .
另请参阅 setData ().
[override virtual protected]
bool
QAction::
event
(
QEvent
*
e
)
Reimplemented from QObject::event ().
[slot]
void
QAction::
hover
()
这是调用 activate(Hover) 的方便槽。
[signal]
void
QAction::
hovered
()
This signal is emitted when an action is highlighted by the user; for example, when the user pauses with the cursor over a menu option, toolbar button, or presses an action's shortcut key combination.
另请参阅 QAction::activate ().
返回
true
若此动作是分隔符动作;否则它返回
false
.
另请参阅 QAction::setSeparator ().
返回由此动作包含的菜单。包含菜单的动作可以被用于创建带子菜单的菜单项,或被插入工具栏中以创建带弹出菜单的按钮。
另请参阅 setMenu () 和 QMenu::addAction ().
返回父级 Widget。
把此动作组设为 group 。动作会被自动添加到组的动作列表。
组内动作将是相互排斥的。
另请参阅 QActionGroup and QAction::actionGroup ().
把动作的内部数据设为给定 userData .
另请参阅 data ().
[slot]
void
QAction::
setDisabled
(
bool
b
)
这是方便函数,为 enabled property, that is useful for signals--slots connections. If b is true the action is disabled; otherwise it is enabled.
把由此动作包含的菜单设为指定 menu .
另请参阅 menu ().
若 b 为 true,则此动作将被认为是分隔符。
How a separator is represented depends on the widget it is inserted into. Under most circumstances the text, submenu, and icon will be ignored for separator actions.
另请参阅 QAction::isSeparator ().
集 shortcuts 作为触发动作的快捷方式列表。列表的第一元素是首要快捷方式。
This function was introduced in Qt 4.2.
另请参阅 shortcuts () 和 shortcut .
设置从属平台的快捷方式列表基于 key . The result of calling this function will depend on the currently running platform. Note that more than one shortcut can assigned by this action. If only the primary shortcut is required, use setShortcut 代替。
This function was introduced in Qt 4.2.
另请参阅 QKeySequence::keyBindings ().
返回首要快捷键。
注意: Getter 函数为特性 shortcut .
另请参阅 setShortcuts ().
返回快捷键列表,采用首要快捷键作为列表的第一元素。
This function was introduced in Qt 4.2.
另请参阅 setShortcuts ().
更新相关状态栏为
widget
指定通过发送
QStatusTipEvent
到其父级 Widget。返回
true
若事件被发送;否则返回
false
.
若指定 null 小部件,则事件被发送给动作的父级。
另请参阅 statusTip .
[slot]
void
QAction::
toggle
()
这是方便函数,为 checked property. Connect to it to change the checked state to its opposite state.
[signal]
void
QAction::
toggled
(
bool
checked
)
此信号被发射每当可复选动作改变其 isChecked () status. This can be the result of a user interaction, or because setChecked () was called. As setChecked () changes the QAction , it emits changed () in addition to toggled().
checked 为 true 若动作被复选,或 false 若动作被取消复选。
注意: 通知信号为特性 checked .
另请参阅 QAction::activate (), QAction::triggered (),和 checked .
[slot]
void
QAction::
trigger
()
这是调用 activate(Trigger) 的方便槽。
[signal]
void
QAction::
triggered
(
bool
checked
= false)
此信号被发射当动作被激活由用户;例如:当用户点击菜单选项、工具栏按钮或按下动作的快捷键组合时,或当 trigger () 被调用。显而易见,它是 not 被发射当 setChecked () 或 toggle () 被调用。
若动作是可复选的, checked 为 true 若动作被复选,或 false 若动作被取消复选。
另请参阅 QAction::activate (), QAction::toggled (),和 checked .