QAction 類提供可以被添加到不同用戶界麵組件的用戶命令的抽象。 更多...
| 頭: |
#include <QAction>
|
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
|
| qmake: |
QT += gui
|
| Since: | Qt 6.0 |
| 繼承: | QObject |
| 繼承者: |
| 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 ) |
(從 6.0 起)
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 (QKeySequence::StandardKey key ) |
| void | setShortcuts (const QList<QKeySequence> & shortcuts ) |
| 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 .
可以把動作添加到用戶界麵元素 (譬如:菜單和工具欄),並自動保持 UI 同步。例如,在單詞處理程序中,若用戶按下 "粗體" 工具欄按鈕,將自動復選 "粗體" 菜單項。
QAction 可以包含圖標、描述性文本、圖標文本、鍵盤快捷方式、狀態文本、What's This? 文本、及工具提示。所有特性可以獨立設置采用 setIcon (), setText (), setIconText (), setShortcut (), setStatusTip (), setWhatsThis (),和 setToolTip ()。圖標和文本,作為 2 最重要特性,也可以在構造函數中設置。單獨設置字體是可能的采用 setFont (),如:菜單會遵守,當把動作顯示成菜單項時。
推薦把動作創建作為,在其中使用它們的窗口子級。在大多數情況下,動作將是應用程序主窗口的子級。
QAction 一旦創建,就應把它添加到相關菜單和工具欄,然後連接到將履行動作的槽。
把動作添加到 Widget 是使用 QWidget::addAction () 或 QGraphicsWidget::addAction ()。注意,動作必須被添加到 Widget,在可以使用它之前。這也為 true 當快捷方式應該全局時 (即 Qt::ApplicationShortcut as Qt::ShortcutContext ).
可以把動作創建成獨立對象。但也可以在菜單構造期間創建它們。 QMenu 類包含創建適於用作菜單項的動作的方便函數。
使用此枚舉類型當調用 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 。字體可以被認為是提示,因為在基於應用程序和風格的所有情況下,都不會諮詢字體。
默認情況下,此特性包含應用程序默認字體。
訪問函數:
| QFont | font () const |
| void | setFont (const QFont & font ) |
通知程序信號:
| void | changed () |
另請參閱 setText ().
此特性保持動作的圖標
在工具欄中,圖標被用作工具按鈕圖標;在菜單中,它顯示在菜單文本左側。隻要
QAction::iconVisibleInMenu
返迴
true
.
不存在默認圖標。
若 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 屬性有為應用程序設置。明確設置此特性會覆寫存在 (或缺乏) 的屬性。
例如:
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(),將把動作的描述圖標文本用作文本。不存在默認文本。
某些 UI 元素 (譬如:菜單或按鈕),可以在字符前麵使用 & 以自動為該字符創建助記符 (快捷方式)。例如,用於菜單的 &File 將創建快捷方式 Alt+F ,將打開文件菜單。E&xit 將創建快捷方式 Alt+X 為按鈕,或在菜單中通過按下 x 允許導航到菜單項 (使用 && 能顯示實際 & 和號)。Widget 可能基於給定快捷方式,消耗並履行動作。
訪問函數:
| 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 是動作組,動作會被自動插入組中。
刪減版的 text (例如 &Menu Option... 變為 Menu Option) 將用於工具提示和圖標文本,除非指定不同文本使用 setToolTip () 或 setIconText () 分彆。
另請參閱 text .
[explicit]
QAction::
QAction
(const
QIcon
&
icon
, const
QString
&
text
,
QObject
*
parent
= nullptr)
構造動作采用 icon 和一些 text and parent 。若 parent 是動作組,動作會被自動插入組中。
刪減版的 text (例如 &Menu Option... 變為 Menu Option) 將用於工具提示和圖標文本,除非指定不同文本使用 setToolTip () 或 setIconText () 分彆。
[virtual noexcept]
QAction::
~QAction
()
銷毀對象並釋放分配的資源。
返迴針對此動作的動作組。若沒有動作組管理此動作,那麼
nullptr
將被返迴。
另請參閱 QActionGroup and setActionGroup ().
發送相關信號為 ActionEvent event .
基於動作的 Widget 使用此 API 來導緻 QAction 發射信號及發射它們自己。
[since 6.0]
QList
<
QObject
*> QAction::
associatedObjects
() const
返迴此動作已添加到的對象列錶。
該函數在 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 ().
返迴由此動作包含的菜單。
在 Widget 應用程序中,包含菜單的動作可以用於創建帶有子菜單的菜單項 (或插入工具欄以創建帶有彈齣菜單的按鈕)。
另請參閱 setMenu (), QMenu::addAction (),和 QMenu::menuInAction ().
把此動作組設為 group 。動作會被自動添加到組的動作列錶。
組內動作相互排斥。
另請參閱 QActionGroup and actionGroup ().
把動作的內部數據設為給定 data .
另請參閱 data ().
[slot]
void
QAction::
setDisabled
(
bool
b
)
這是方便函數對於 enabled 特性,這很有用對於信號/槽連接。若 b 為 true, 動作被禁用;否則,被啓用。
把由此動作包含的菜單設為指定 menu .
另請參閱 menu ().
若 b 為 true,則此動作將被認為是分隔符。
如何錶示分隔符從屬插入其的 Widget。在大多數情況下,文本、子菜單及圖標會被分隔符動作忽略。
另請參閱 isSeparator ().
設置 shortcut 作為觸發動作的唯一快捷方式。
注意: setter 函數對於特性 shortcut .
另請參閱 shortcut and setShortcuts ().
設置從屬平颱的快捷方式列錶基於 key 。調用此函數的結果,從屬當前運行平颱。注意,此動作可以賦值多個快捷方式。若隻要求首要快捷方式,使用 setShortcut 代替。
另請參閱 shortcuts () 和 QKeySequence::keyBindings ().
設置 shortcuts 作為觸發動作的快捷方式列錶。列錶的第一元素是首要快捷方式。
另請參閱 shortcut and setShortcut ().
返迴首要快捷鍵。
注意: getter 函數對於特性 shortcut。
另請參閱 setShortcuts ().
返迴快捷鍵列錶,采用首要快捷鍵作為列錶的第一元素。
另請參閱 setShortcuts ().
更新相關 UI 狀態欄, 錶示由
object
通過發送
QStatusTipEvent
。返迴
true
若事件被發送,否則返迴
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 若動作被取消復選。