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 若動作被取消復選。