The QAction 類提供可以插入 Widget 的抽象用戶界麵動作。 更多...
| 頭: | #include <QAction> |
| qmake: | QT += widgets |
| 繼承: | QObject |
| 繼承者: | QWidgetAction |
| 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 () |
| void | changed () |
| void | hovered () |
| void | toggled (bool checked ) |
| void | triggered (bool checked = false) |
| const QMetaObject | staticMetaObject |
| virtual bool | event (QEvent * e ) override |
The QAction 類提供可以插入 Widget 的抽象用戶界麵動作。
在應用程序中,很多常見命令可以憑藉菜單、工具欄按鈕及鍵盤快捷方式援引。由於用戶期望每個命令都能以相同方式履行,不管所用的用戶界麵,它是有用的將每個命令錶示成 action .
動作可以被添加到菜單和工具欄,並自動保持同步。例如,在單詞處理程序中,若用戶按下加粗工具欄按鈕,加粗菜單項將被自動選中。
可以將動作創建成獨立對象,但也可以在構造菜單期間創建; QMenu 類包含創建適於用作菜單項的動作的方便函數。
A QAction 可以包含圖標、菜單文本、快捷方式、狀態文本、What's This? 文本及工具提示。這些中的大多數,可以在構造函數中設置。也可以獨立設置它們采用 setIcon (), setText (), setIconText (), setShortcut (), setStatusTip (), setWhatsThis (),和 setToolTip ()。對於菜單項,可以設置單個字體采用 setFont ().
把動作添加到 Widget 是使用 QWidget::addAction () 或 QGraphicsWidget::addAction ()。注意:動作必須被添加到 Widget 在使用它之前;這也為 true 當快捷方式應該全局時 (即 Qt::ApplicationShortcut as Qt::ShortcutContext ).
一旦 QAction 被創建,就應把它添加到相關菜單和工具欄,然後連接到將履行動作的槽。例如:
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);
推薦把動作創建作為,在其中使用它們的窗口子級。在大多數情況下,動作將是應用程序主窗口的子級。
另請參閱 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
|
不應將此動作放入應用程序菜單 |
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
|
動作應該在用戶界麵中被優先。 |
該枚舉在 Qt 4.6 引入或被修改。
另請參閱 priority .
此特性保持動作是否可以自動重復
若為 true,動作會自動重復當按下鍵盤快捷方式組閤時,前提是係統啓用瞭鍵盤自動重復。默認值為 true。
該特性在 Qt 4.2 引入。
訪問函數:
| 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 | changed () |
另請參閱 QAction::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 | changed () |
另請參閱 text .
此特性保持動作的字體
字體特性用於渲染文本設置在 QAction 。字體可以被認為是提示,因為在基於應用程序和風格的所有情況下,都不會諮詢字體。
默認情況下,此特性包含應用程序默認字體。
訪問函數:
| QFont | font () const |
| void | setFont (const QFont & font ) |
通知程序信號:
| void | changed () |
另請參閱 QAction::setText () 和 QStyle .
此特性保持動作的圖標
在工具欄中,圖標被用作工具按鈕圖標;在菜單中,它顯示在菜單文本左側。不存在默認圖標。
若 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 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.
該特性在 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 ,意味著動作是基於其文本添加的 (見 QMenuBar 瞭解更多信息)。
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).
該特性在 Qt 4.2 引入。
訪問函數:
| QAction::MenuRole | menuRole () const |
| void | setMenuRole (QAction::MenuRole menuRole ) |
通知程序信號:
| void | changed () |
此特性保持在用戶界麵中動作的優先級。
可以設置此特性以指示動作在用戶界麵中的優先級應該如何。
對於實例,當工具欄擁有 Qt::ToolButtonTextBesideIcon 模式設置,那麼動作具有 LowPriority 被不展示文本標簽。
該特性在 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 () |
此特性保持動作是否應該在上下文菜單中展示快捷方式
在某些應用程序,上下文菜單擁有具有快捷方式的動作可能有意義。若為 true,展示快捷方式 (若有效) 當憑藉上下文菜單展示動作時;若為 false,不展示快捷方式。
默認遵循是否 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.
該特性在 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 ().
此特性保持動作的描述性文本
若動作被添加到菜單,菜單選項將由圖標 (若有 1 個)、文本及快捷方式 (若有 1 個) 組成。若在構造函數中明確設置沒有文本,或通過使用 setText(),將把動作的描述圖標文本用作文本。不存在默認文本。
訪問函數:
| 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 | changed () |
此特性保持動作的 What's This? 幫助文本
What's This? 文本用於提供動作的簡要描述。文本可以包含富文本。What's This? 不存在默認文本。
訪問函數:
| QString | whatsThis () const |
| void | setWhatsThis (const QString & what ) |
通知程序信號:
| void | changed () |
另請參閱 QWhatsThis .
構造動作采用 parent 。若 parent 是動作組,動作會被自動插入組中。
注意: The parent 自變量是可選的,從 Qt 5.7 起。
構造動作采用一些 text and parent 。若 parent 是動作組,動作會被自動插入組中。
動作使用刪減版的 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 是動作組,動作會被自動插入組中。
動作使用刪減版的 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 ().
[虛擬]
QAction::
~QAction
()
銷毀對象並釋放分配的資源。
返迴此動作的動作組。返迴 0 若沒有動作組管理此動作。
另請參閱 QActionGroup and QAction::setActionGroup ().
發送相關信號為 ActionEvent event .
基於動作的 Widget 使用此 API 以促使 QAction 發射信號及發射它們自己。
返迴已添加此動作的小部件列錶。
該函數在 Qt 4.5 引入。
另請參閱 QWidget::addAction () 和 associatedWidgets ().
返迴已添加此動作的小部件列錶。
該函數在 Qt 4.2 引入。
另請參閱 QWidget::addAction () 和 associatedGraphicsWidgets ().
[signal]
void
QAction::
changed
()
此信號發射,當動作有改變。若隻對給定 Widget 中的動作感興趣,可以看守 QWidget::actionEvent () 發送采用 QEvent::ActionChanged .
注意: 通知程序信號對於特性 autoRepeat 。通知程序信號對於特性 checkable 。通知程序信號對於特性 enabled 。通知程序信號對於特性 font 。通知程序信號對於特性 icon 。通知程序信號對於特性 iconText 。通知程序信號對於特性 iconVisibleInMenu 。通知程序信號對於特性 menuRole 。通知程序信號對於特性 shortcut 。通知程序信號對於特性 shortcutContext 。通知程序信號對於特性 shortcutVisibleInContextMenu 。通知程序信號對於特性 statusTip 。通知程序信號對於特性 text 。通知程序信號對於特性 toolTip 。通知程序信號對於特性 visible 。通知程序信號對於特性 whatsThis .
另請參閱 QWidget::actionEvent ().
返迴用戶設置數據在 QAction::setData .
另請參閱 setData ().
[override virtual protected]
bool
QAction::
event
(
QEvent
*
e
)
重實現自 QObject::event ().
[slot]
void
QAction::
hover
()
這是調用 activate(Hover) 的方便槽。
[signal]
void
QAction::
hovered
()
此信號被發射當用戶突顯動作時;例如:當用戶暫停光標在菜單選項、工具欄按鈕上或按下動作的快捷鍵組閤時。
另請參閱 QAction::activate ().
返迴
true
若此動作是分隔符動作;否則它返迴
false
.
另請參閱 QAction::setSeparator ().
返迴此動作包含的菜單。包含菜單的動作可以用於創建帶子菜單的菜單項,或插入工具欄以創建帶彈齣菜單的按鈕。
另請參閱 setMenu () 和 QMenu::addAction ().
返迴父級 Widget。
把此動作組設為 group 。動作會被自動添加到組的動作列錶。
組內動作相互排斥。
另請參閱 QActionGroup and QAction::actionGroup ().
把動作的內部數據設為給定 userData .
另請參閱 data ().
[slot]
void
QAction::
setDisabled
(
bool
b
)
這是方便函數對於 enabled 特性,這很有用對於信號/槽連接。若 b 為 true, 動作被禁用;否則,被啓用。
把由此動作包含的菜單設為指定 menu .
另請參閱 menu ().
若 b 為 true,則此動作將被認為是分隔符。
如何錶示分隔符從屬插入其的 Widget。在大多數情況下,文本、子菜單及圖標會被分隔符動作忽略。
另請參閱 QAction::isSeparator ().
集 shortcuts 作為觸發動作的快捷方式列錶。列錶的第一元素是首要快捷方式。
該函數在 Qt 4.2 引入。
另請參閱 shortcuts () 和 shortcut .
設置從屬平颱的快捷方式列錶基於 key 。調用此函數的結果,從屬當前運行平颱。注意,此動作可以賦值多個快捷方式。若隻要求首要快捷方式,使用 setShortcut 代替。
該函數在 Qt 4.2 引入。
另請參閱 QKeySequence::keyBindings ().
返迴首要快捷鍵。
注意: getter 函數對於特性 shortcut .
另請參閱 setShortcuts ().
返迴快捷鍵列錶,采用首要快捷鍵作為列錶的第一元素。
該函數在 Qt 4.2 引入。
另請參閱 setShortcuts ().
更新相關狀態欄為
widget
指定通過發送
QStatusTipEvent
到其父級 Widget。返迴
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 .
另請參閱 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 .