The QAction class provides an abstraction for user commands that can be added to different user interface components. 更多...
| 头: | #include <QAction> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Since: | Qt 6.0 |
| 继承: | QObject |
| 继承者: | QWidgetAction |
| enum | ActionEvent { Trigger, Hover } |
| enum | MenuRole { NoRole, TextHeuristicRole, ApplicationSpecificRole, AboutQtRole, AboutRole, …, 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<QObject *> | associatedObjects () 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 |
| QAction::Priority | priority () const |
| void | setActionGroup (QActionGroup * group ) |
| void | setAutoRepeat (bool) |
| void | setCheckable (bool) |
| void | setData (const QVariant & data ) |
| 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 (QObject * object = nullptr) |
| QString | statusTip () const |
| QString | text () const |
| QString | toolTip () const |
| QString | whatsThis () const |
| void | hover () |
| void | resetEnabled () |
| void | setChecked (bool) |
| void | setDisabled (bool b ) |
| void | setEnabled (bool) |
| void | setVisible (bool) |
| void | toggle () |
| void | trigger () |
| void | changed () |
| void | checkableChanged (bool checkable ) |
| void | enabledChanged (bool enabled ) |
| void | hovered () |
| void | toggled (bool checked ) |
| void | triggered (bool checked = false) |
| void | visibleChanged () |
| virtual bool | event (QEvent * e ) override |
在应用程序中,很多常见命令可以凭借菜单、工具栏按钮及键盘快捷方式援引。由于用户期望每个命令都能以相同方式履行,不管所用的用户界面,它是有用的将每个命令表示成 action .
Actions can be added to user interface elements such as menus and toolbars, and will automatically keep the UI in sync. For example, in a word processor, if the user presses a Bold toolbar button, the Bold menu item will automatically be checked.
A QAction may contain an icon, descriptive text, icon text, a keyboard shortcut, status text, "What's This?" text, and a tooltip. All properties can be set independently with setIcon (), setText (), setIconText (), setShortcut (), setStatusTip (), setWhatsThis (),和 setToolTip (). Icon and text, as the two most important properties, can also be set in the constructor. It's possible to set an individual font with setFont (), which e.g. menus respect when displaying the action as a menu item.
推荐把动作创建作为,在其中使用它们的窗口子级。在大多数情况下,动作将是应用程序主窗口的子级。
Once a 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);
把动作添加到 Widget 是使用 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 ).
Actions can be created as independent objects. But they may also be created during the construction of menus. The QMenu 类包含创建适于用作菜单项的动作的方便函数。
另请参阅 QMenu , QToolBar ,和 Qt Widgets - Application Example .
使用此枚举类型当调用 QAction::activate ()
| 常量 | 值 | 描述 |
|---|---|---|
QAction::Trigger
|
0
|
这将导致 QAction::triggered () 信号发射。 |
QAction::Hover
|
1
|
这将导致 QAction::hovered () 信号发射。 |
此枚举描述应该如何把动作移入 macOS 应用程序菜单。
| 常量 | 值 | 描述 |
|---|---|---|
QAction::NoRole
|
0
|
不应将此动作放入应用程序菜单 |
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
|
应按应用程序特定角色,将此动作放入应用程序菜单 |
QAction::AboutQtRole
|
3
|
此动作处理 About Qt 菜单项。 |
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
|
动作应该在用户界面中被优先。 |
另请参阅 priority .
此特性保持动作是否可以自动重复
若为 true,动作会自动重复当按下键盘快捷方式组合时,前提是系统启用了键盘自动重复。默认值为 true。
访问函数:
| bool | autoRepeat () const |
| void | setAutoRepeat (bool) |
通知程序信号:
| void | changed () |
此特性保持动作是否为可复选动作
可复选动作是拥有 On/Off 状态的动作。例如,在单词处理程序中,"粗体" 工具栏按钮可以要么为 On, 要么为 Off。不是触发动作的动作,是命令动作;命令动作 (如:文件保存) 只需执行。默认情况下,此特性为
false
.
在某些情况下,1 个触发操作的状态应该从属其它状态 (例如:左对齐、居中和右对齐触发动作,是相互排斥的)。要达成独占触发,把相关触发动作添加到 QActionGroup 采用把 QActionGroup::exclusive 特性设为 true。
访问函数:
| bool | isCheckable () const |
| void | setCheckable (bool) |
通知程序信号:
| void | checkableChanged (bool checkable ) |
另请参阅 setChecked ().
此特性保持动作是否被复选。
仅可复选动作可以被复选。默认情况下,这为 false (动作未被复选)。
注意: 此特性的通知信号为 toggled ()。作为触发 QAction 改变其状态,它还会发射 changed () 信号。
访问函数:
| bool | isChecked () const |
| void | setChecked (bool) |
通知程序信号:
| void | toggled (bool checked ) |
另请参阅 checkable and toggled ().
此特性保持动作是否被启用
被禁用动作用户无法选取。它们不会从菜单 (或工具栏) 消失,但表明它们不可用的方式是显示它们。例如,可能仅使用灰度着色显示它们。
What's This? 有关被禁用动作的帮助仍然可用,前提是 QAction::whatsThis 特性有设置。
动作将被禁用,当被添加到的所有 Widget (采用 QWidget::addAction ()) 被禁用 (或不可见)。当动作被禁用时,透过其快捷方式触发它是不可能的。
默认情况下,此特性为
true
(动作被启用)。
访问函数:
| bool | isEnabled () const |
| void | setEnabled (bool) |
| void | resetEnabled () |
通知程序信号:
| void | enabledChanged (bool enabled ) |
另请参阅 text .
此特性保持动作的字体
字体特性用于渲染文本设置在 QAction . The font can be considered a hint as it will not be consulted in all cases based upon application and style.
默认情况下,此特性包含应用程序默认字体。
访问函数:
| QFont | font () const |
| void | setFont (const QFont & font ) |
通知程序信号:
| void | changed () |
另请参阅 setText ().
此特性保持动作的图标
在工具栏中,图标被用作工具按钮图标;在菜单中,它显示在菜单文本左侧。不存在默认图标。
若 null 图标 ( QIcon::isNull ()) 被传入此函数,动作图标被清零。
访问函数:
| QIcon | icon () const |
| void | setIcon (const QIcon & icon ) |
通知程序信号:
| void | changed () |
此特性保持动作的描述性图标文本
若 QToolBar::toolButtonStyle 被设为准许显示文本的值,在此特性中保持定义的文本,将作为标签出现在相关工具按钮中。
它还充当菜单和工具提示中的默认文本,若动作没有定义采用 setText () 或 setToolTip (),且也将用于工具栏按钮,若没有定义图标使用 setIcon ().
若未明确设置图标文本,动作的正常文本将用于图标文本。
默认情况下,此特性包含空字符串。
访问函数:
| QString | iconText () const |
| void | setIconText (const QString & text ) |
通知程序信号:
| void | changed () |
另请参阅 setToolTip () 和 setStatusTip ().
此特性保持动作是否应在菜单中展示图标
在某些应用程序,在工具栏中动作带图标可能有意义,但在菜单中不是。若为 true,图标 (若有效) 展示在菜单中,当它为 false,不展示。
默认遵循是否 Qt::AA_DontShowIconsInMenus attribute is set for the application. Explicitly settings this property overrides the presence (or absence) 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.
访问函数:
| bool | isIconVisibleInMenu () const |
| void | setIconVisibleInMenu (bool visible ) |
通知程序信号:
| void | changed () |
另请参阅 icon and QCoreApplication::setAttribute ().
此特性保持动作的菜单角色
这指示在 macOS 应用程序菜单中,动作充当的角色。默认情况下,所有动作都拥有 TextHeuristicRole ,意味着动作是基于其文本添加的 (见 QMenuBar 了解更多信息)。
在 macOS,只可以在将动作放入菜单栏前 (通常在展示第 1 应用程序窗口前) 改变菜单角色。
访问函数:
| QAction::MenuRole | menuRole () const |
| void | setMenuRole (QAction::MenuRole menuRole ) |
通知程序信号:
| void | changed () |
此特性保持在用户界面中动作的优先级。
可以设置此特性以指示动作在用户界面中的优先级应该如何。
对于实例,当工具栏拥有 Qt::ToolButtonTextBesideIcon 模式设置,那么动作具有 LowPriority 被不展示文本标签。
访问函数:
| QAction::Priority | priority () const |
| void | setPriority (QAction::Priority priority ) |
通知程序信号:
| void | changed () |
此特性保持动作的首要快捷键
可以找到此特性的有效键码在 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 () |
此特性保持动作是否应该在上下文菜单中展示快捷方式
在某些应用程序,上下文菜单拥有具有快捷方式的动作可能有意义。若为 true,展示快捷方式 (若有效) 当凭借上下文菜单展示动作时;若为 false,不展示快捷方式。
默认遵循是否 Qt::AA_DontShowShortcutsInContextMenus 属性有设置对于应用程序。明确设置此特性,会覆写属性。
访问函数:
| bool | isShortcutVisibleInContextMenu () const |
| void | setShortcutVisibleInContextMenu (bool show ) |
通知程序信号:
| void | changed () |
另请参阅 shortcut and QCoreApplication::setAttribute ().
此特性保持动作的状态提示
状态提示显示在由动作的顶层父级 Widget 提供的所有状态栏上。
默认情况下,此特性包含空字符串。
访问函数:
| QString | statusTip () const |
| void | setStatusTip (const QString & statusTip ) |
通知程序信号:
| void | changed () |
另请参阅 setToolTip () 和 showStatusText ().
此特性保持动作的描述性文本
若动作被添加到菜单,菜单选项将由图标 (若有 1 个)、文本及快捷方式 (若有 1 个) 组成。若在构造函数中明确设置没有文本,或通过使用 setText(),将把动作的描述图标文本用作文本。不存在默认文本。
Certain UI elements, such as menus or buttons, can use '&' in front of a character to automatically create a mnemonic (a shortcut) for that character. For example, "&File" for a menu will create the shortcut Alt+F , which will open the File menu. "E&xit" will create the shortcut Alt+X for a button, or in a menu allow navigating to the menu item by pressing "x". (use '&&' to display an actual ampersand). The widget might consume and perform an action on a given shortcut.
访问函数:
| QString | text () const |
| void | setText (const QString & text ) |
通知程序信号:
| void | changed () |
另请参阅 iconText .
此特性保持动作的工具提示
此文本用于工具提示。若工具提示未指定,使用动作文本。
默认情况下,此特性包含动作的文本。
访问函数:
| QString | toolTip () const |
| void | setToolTip (const QString & tip ) |
通知程序信号:
| void | changed () |
另请参阅 setStatusTip () 和 setShortcut ().
此特性保持动作是否可见 (如在菜单和工具栏中)
若 visible 为 true,动作可见 (如:在菜单和工具栏) 并由用户选取;若 visible 为 false,动作不可见 (或由用户选取)。
不可见动作 not 变灰;它们根本不出现。
默认情况下,此特性为
true
(动作可见)。
访问函数:
| bool | isVisible () const |
| void | setVisible (bool) |
通知程序信号:
| void | visibleChanged () |
此特性保持动作的 What's This? 帮助文本
What's This? 文本用于提供动作的简要描述。文本可以包含富文本。What's This? 不存在默认文本。
访问函数:
| QString | whatsThis () const |
| void | setWhatsThis (const QString & what ) |
通知程序信号:
| void | changed () |
另请参阅 QWhatsThis .
[explicit]
QAction::
QAction
(
QObject
*
parent
= nullptr)
构造动作采用 parent 。若 parent 是动作组,动作会被自动插入组中。
注意: The parent 自变量是可选的,从 Qt 5.7 起。
[explicit]
QAction::
QAction
(const
QString
&
text
,
QObject
*
parent
= nullptr)
构造动作采用一些 text and parent 。若 parent 是动作组,动作会被自动插入组中。
A stripped version of text (for example, "&Menu Option..." becomes "Menu Option") will be used for tooltips and icon text unless you specify a different text using setToolTip () 或 setIconText () 分别。
另请参阅 text .
[explicit]
QAction::
QAction
(const
QIcon
&
icon
, const
QString
&
text
,
QObject
*
parent
= nullptr)
构造动作采用 icon 和一些 text and parent 。若 parent 是动作组,动作会被自动插入组中。
A stripped version of text (for example, "&Menu Option..." becomes "Menu Option") will be used for tooltips and icon text unless you specify a different text using setToolTip () 或 setIconText () 分别。
[虚拟]
QAction::
~QAction
()
销毁对象并释放分配的资源。
Returns the action group for this action. If no action group manages this action, then
nullptr
将被返回。
另请参阅 QActionGroup and setActionGroup ().
发送相关信号为 ActionEvent event .
Action-based widgets use this API to cause the QAction 发射信号及发射它们自己。
[since 6.0]
QList
<
QObject
*> QAction::
associatedObjects
() const
Returns a list of objects this action has been added to.
该函数在 Qt 6.0 引入。
另请参阅 QWidget::addAction () 和 QGraphicsWidget::addAction ().
[signal]
void
QAction::
changed
()
此信号发射,当动作有改变。若只对给定 Widget 中的动作感兴趣,可以看守 QWidget::actionEvent () 发送采用 QEvent::ActionChanged .
注意: 通知程序信号对于特性 autoRepeat 。通知程序信号对于特性 font 。通知程序信号对于特性 icon 。通知程序信号对于特性 iconText 。通知程序信号对于特性 iconVisibleInMenu 。通知程序信号对于特性 menuRole 。通知程序信号对于特性 priority 。通知程序信号对于特性 shortcut 。通知程序信号对于特性 shortcutContext 。通知程序信号对于特性 shortcutVisibleInContextMenu 。通知程序信号对于特性 statusTip 。通知程序信号对于特性 text 。通知程序信号对于特性 toolTip 。通知程序信号对于特性 whatsThis .
另请参阅 QWidget::actionEvent ().
返回用户设置数据在 QAction::setData .
另请参阅 setData ().
[override virtual protected]
bool
QAction::
event
(
QEvent
*
e
)
重实现: QObject::event (QEvent *e).
[slot]
void
QAction::
hover
()
这是调用 activate(Hover) 的方便槽。
[signal]
void
QAction::
hovered
()
此信号被发射当用户突显动作时;例如:当用户暂停光标在菜单选项、工具栏按钮上或按下动作的快捷键组合时。
另请参阅 activate ().
返回
true
若此动作是分隔符动作;否则它返回
false
.
另请参阅 setSeparator ().
Returns the menu contained by this action.
In widget applications, actions that contain menus can be used to create menu items with submenus, or inserted into toolbars to create buttons with popup menus.
另请参阅 setMenu (), QMenu::addAction (),和 QMenu::menuInAction ().
把此动作组设为 group 。动作会被自动添加到组的动作列表。
组内动作相互排斥。
另请参阅 QActionGroup and actionGroup ().
把动作的内部数据设为给定 data .
另请参阅 data ().
[slot]
void
QAction::
setDisabled
(
bool
b
)
这是方便函数对于 enabled property, that is useful for signals–slots connections. If b 为 true, 动作被禁用;否则,被启用。
把由此动作包含的菜单设为指定 menu .
另请参阅 menu ().
若 b 为 true,则此动作将被认为是分隔符。
如何表示分隔符从属插入其的 Widget。在大多数情况下,文本、子菜单及图标会被分隔符动作忽略。
另请参阅 isSeparator ().
设置 shortcut as the sole shortcut that triggers the action.
注意: setter 函数对于特性 shortcut .
另请参阅 shortcut and setShortcuts ().
设置 shortcuts 作为触发动作的快捷方式列表。列表的第一元素是首要快捷方式。
另请参阅 shortcuts (), shortcut ,和 setShortcut ().
设置从属平台的快捷方式列表基于 key 。调用此函数的结果,从属当前运行平台。注意,此动作可以赋值多个快捷方式。若只要求首要快捷方式,使用 setShortcut 代替。
另请参阅 QKeySequence::keyBindings ().
返回首要快捷键。
注意: getter 函数对于特性 shortcut。
另请参阅 setShortcuts ().
返回快捷键列表,采用首要快捷键作为列表的第一元素。
另请参阅 setShortcuts ().
Updates the relevant status bar for the UI represented by
object
by sending a
QStatusTipEvent
。返回
true
if an event was sent, otherwise returns
false
.
若指定 null 小部件,则事件被发送给动作的父级。
另请参阅 statusTip .
[slot]
void
QAction::
toggle
()
这是方便函数对于 checked 特性。连接到它以将复选状态更改为其的相反状态。
[signal]
void
QAction::
toggled
(
bool
checked
)
此信号发射,每当可复选动作改变其 isChecked () 状态。这可能是用户交互的结果,或因为 setChecked () 被调用。因为 setChecked () 改变 QAction ,它发射 changed () 除 toggled() 外。
checked 为 true 若动作被复选,或 false 若动作被取消复选。
注意: 通知程序信号对于特性 checked .
另请参阅 activate (), triggered (),和 checked .
[slot]
void
QAction::
trigger
()
这是调用 activate(Trigger) 的方便槽。
[signal]
void
QAction::
triggered
(
bool
checked
= false)
此信号被发射当动作被激活由用户;例如:当用户点击菜单选项、工具栏按钮或按下动作的快捷键组合时,或当 trigger () 被调用。显而易见,它是 not 发射当 setChecked () 或 toggle () 被调用。
若动作是可复选的, checked 为 true 若动作被复选,或 false 若动作被取消复选。