QAction 類

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.

推薦把動作創建作為,在其中使用它們的窗口子級。在大多數情況下,動作將是應用程序主窗口的子級。

QAction in widget applications

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 .

成員類型文檔編製

enum QAction:: ActionEvent

使用此枚舉類型當調用 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.

enum QAction:: Priority

此枚舉定義用戶界麵中動作的優先級。

常量 描述
QAction::LowPriority 0 動作不應該在用戶界麵中被優先。
QAction::NormalPriority 128
QAction::HighPriority 256 動作應該在用戶界麵中被優先。

另請參閱 priority .

特性文檔編製

autoRepeat : bool

此特性保持動作是否可以自動重復

若為 true,動作會自動重復當按下鍵盤快捷方式組閤時,前提是係統啓用瞭鍵盤自動重復。默認值為 true。

訪問函數:

bool autoRepeat () const
void setAutoRepeat (bool)

通知程序信號:

void changed ()

checkable : bool

此特性保持動作是否為可復選動作

可復選動作是擁有 On/Off 狀態的動作。例如,在單詞處理程序中,"粗體" 工具欄按鈕可以要麼為 On, 要麼為 Off。不是觸發動作的動作,是命令動作;命令動作 (如:文件保存) 隻需執行。默認情況下,此特性為 false .

在某些情況下,1 個觸發操作的狀態應該從屬其它狀態 (例如:左對齊、居中和右對齊觸發動作,是相互排斥的)。要達成獨占觸發,把相關觸發動作添加到 QActionGroup 采用把 QActionGroup::exclusive 特性設為 true。

訪問函數:

bool isCheckable () const
void setCheckable (bool)

通知程序信號:

void checkableChanged (bool checkable )

另請參閱 setChecked ().

checked : bool

此特性保持動作是否被復選。

僅可復選動作可以被復選。默認情況下,這為 false (動作未被復選)。

注意: 此特性的通知信號為 toggled ()。作為觸發 QAction 改變其狀態,它還會發射 changed () 信號。

訪問函數:

bool isChecked () const
void setChecked (bool)

通知程序信號:

void toggled (bool checked )

另請參閱 checkable and toggled ().

enabled : bool

此特性保持動作是否被啓用

被禁用動作用戶無法選取。它們不會從菜單 (或工具欄) 消失,但錶明它們不可用的方式是顯示它們。例如,可能僅使用灰度著色顯示它們。

What's This? 有關被禁用動作的幫助仍然可用,前提是 QAction::whatsThis 特性有設置。

動作將被禁用,當被添加到的所有 Widget (采用 QWidget::addAction ()) 被禁用 (或不可見)。當動作被禁用時,透過其快捷方式觸發它是不可能的。

默認情況下,此特性為 true (動作被啓用)。

訪問函數:

bool isEnabled () const
void setEnabled (bool)
void resetEnabled ()

通知程序信號:

void enabledChanged (bool enabled )

另請參閱 text .

font : QFont

此特性保持動作的字體

字體特性用於渲染文本設置在 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 ().

icon : QIcon

此特性保持動作的圖標

在工具欄中,圖標被用作工具按鈕圖標;在菜單中,它顯示在菜單文本左側。不存在默認圖標。

若 null 圖標 ( QIcon::isNull ()) 被傳入此函數,動作圖標被清零。

訪問函數:

QIcon icon () const
void setIcon (const QIcon & icon )

通知程序信號:

void changed ()

iconText : QString

此特性保持動作的描述性圖標文本

QToolBar::toolButtonStyle 被設為準許顯示文本的值,在此特性中保持定義的文本,將作為標簽齣現在相關工具按鈕中。

它還充當菜單和工具提示中的默認文本,若動作沒有定義采用 setText () 或 setToolTip (),且也將用於工具欄按鈕,若沒有定義圖標使用 setIcon ().

若未明確設置圖標文本,動作的正常文本將用於圖標文本。

默認情況下,此特性包含空字符串。

訪問函數:

QString iconText () const
void setIconText (const QString & text )

通知程序信號:

void changed ()

另請參閱 setToolTip () 和 setStatusTip ().

iconVisibleInMenu : bool

此特性保持動作是否應在菜單中展示圖標

在某些應用程序,在工具欄中動作帶圖標可能有意義,但在菜單中不是。若為 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 ()

priority : Priority

此特性保持在用戶界麵中動作的優先級。

可以設置此特性以指示動作在用戶界麵中的優先級應該如何。

對於實例,當工具欄擁有 Qt::ToolButtonTextBesideIcon 模式設置,那麼動作具有 LowPriority 被不展示文本標簽。

訪問函數:

QAction::Priority priority () const
void setPriority (QAction::Priority priority )

通知程序信號:

void changed ()

shortcut : QKeySequence

此特性保持動作的首要快捷鍵

可以找到此特性的有效鍵碼在 Qt::Key and Qt::Modifier 。沒有默認的快捷鍵。

訪問函數:

QKeySequence shortcut () const
void setShortcut (const QKeySequence & shortcut )

通知程序信號:

void changed ()

shortcutContext : Qt::ShortcutContext

此特性保持動作快捷方式的上下文

可以找到此特性的有效值在 Qt::ShortcutContext 。默認值為 Qt::WindowShortcut .

訪問函數:

Qt::ShortcutContext shortcutContext () const
void setShortcutContext (Qt::ShortcutContext context )

通知程序信號:

void changed ()

shortcutVisibleInContextMenu : bool

此特性保持動作是否應該在上下文菜單中展示快捷方式

在某些應用程序,上下文菜單擁有具有快捷方式的動作可能有意義。若為 true,展示快捷方式 (若有效) 當憑藉上下文菜單展示動作時;若為 false,不展示快捷方式。

默認遵循是否 Qt::AA_DontShowShortcutsInContextMenus 屬性有設置對於應用程序。明確設置此特性,會覆寫屬性。

訪問函數:

bool isShortcutVisibleInContextMenu () const
void setShortcutVisibleInContextMenu (bool show )

通知程序信號:

void changed ()

另請參閱 shortcut and QCoreApplication::setAttribute ().

statusTip : QString

此特性保持動作的狀態提示

狀態提示顯示在由動作的頂層父級 Widget 提供的所有狀態欄上。

默認情況下,此特性包含空字符串。

訪問函數:

QString statusTip () const
void setStatusTip (const QString & statusTip )

通知程序信號:

void changed ()

另請參閱 setToolTip () 和 showStatusText ().

text : QString

此特性保持動作的描述性文本

若動作被添加到菜單,菜單選項將由圖標 (若有 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 .

toolTip : QString

此特性保持動作的工具提示

此文本用於工具提示。若工具提示未指定,使用動作文本。

默認情況下,此特性包含動作的文本。

訪問函數:

QString toolTip () const
void setToolTip (const QString & tip )

通知程序信號:

void changed ()

另請參閱 setStatusTip () 和 setShortcut ().

visible : bool

此特性保持動作是否可見 (如在菜單和工具欄中)

visible 為 true,動作可見 (如:在菜單和工具欄) 並由用戶選取;若 visible 為 false,動作不可見 (或由用戶選取)。

不可見動作 not 變灰;它們根本不齣現。

默認情況下,此特性為 true (動作可見)。

訪問函數:

bool isVisible () const
void setVisible (bool)

通知程序信號:

void visibleChanged ()

whatsThis : QString

此特性保持動作的 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 () 分彆。

另請參閱 text and icon .

[虛擬] QAction:: ~QAction ()

銷毀對象並釋放分配的資源。

QActionGroup *QAction:: actionGroup () const

Returns the action group for this action. If no action group manages this action, then nullptr 將被返迴。

另請參閱 QActionGroup and setActionGroup ().

void QAction:: activate ( QAction::ActionEvent event )

發送相關信號為 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 ().

QVariant QAction:: data () const

返迴用戶設置數據在 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 ().

bool QAction:: isSeparator () const

返迴 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 ().

void QAction:: setActionGroup ( QActionGroup * group )

把此動作組設為 group 。動作會被自動添加到組的動作列錶。

組內動作相互排斥。

另請參閱 QActionGroup and actionGroup ().

void QAction:: setData (const QVariant & data )

把動作的內部數據設為給定 data .

另請參閱 data ().

[slot] void QAction:: setDisabled ( bool b )

這是方便函數對於 enabled property, that is useful for signals–slots connections. If b 為 true, 動作被禁用;否則,被啓用。

void QAction:: setMenu ( QMenu * menu )

把由此動作包含的菜單設為指定 menu .

另請參閱 menu ().

void QAction:: setSeparator ( bool b )

b 為 true,則此動作將被認為是分隔符。

如何錶示分隔符從屬插入其的 Widget。在大多數情況下,文本、子菜單及圖標會被分隔符動作忽略。

另請參閱 isSeparator ().

void QAction:: setShortcut (const QKeySequence & shortcut )

設置 shortcut as the sole shortcut that triggers the action.

注意: setter 函數對於特性 shortcut .

另請參閱 shortcut and setShortcuts ().

void QAction:: setShortcuts (const QList < QKeySequence > & shortcuts )

設置 shortcuts 作為觸發動作的快捷方式列錶。列錶的第一元素是首要快捷方式。

另請參閱 shortcuts (), shortcut ,和 setShortcut ().

void QAction:: setShortcuts ( QKeySequence::StandardKey key )

設置從屬平颱的快捷方式列錶基於 key 。調用此函數的結果,從屬當前運行平颱。注意,此動作可以賦值多個快捷方式。若隻要求首要快捷方式,使用 setShortcut 代替。

另請參閱 QKeySequence::keyBindings ().

QKeySequence QAction:: shortcut () const

返迴首要快捷鍵。

注意: getter 函數對於特性 shortcut。

另請參閱 setShortcuts ().

QList < QKeySequence > QAction:: shortcuts () const

返迴快捷鍵列錶,采用首要快捷鍵作為列錶的第一元素。

另請參閱 setShortcuts ().

bool QAction:: showStatusText ( QObject * object = nullptr)

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

另請參閱 activate (), toggled (),和 checked .