QAction、QWidgetAction、QActionGroup

QAction

一、描述

在应用程序中，可以通过菜单、工具栏按钮和键盘快捷键调用许多常用命令。由于用户希望每个命令都以相同的方式执行，因此无论使用何种用户界面，将每个命令表示为一个动作是很有用的。

二、类型成员

1、enum QAction::ActionEvent：调用 QAction::activate() 时使用此枚举类型。

• Trigger：发出 QAction::triggered() 信号。
• Hover：发出 QAction::hovered() 信号。

2、enum QAction::MenuRole：此枚举描述了如何将动作移动到 macOS 上的应用程序菜单中。

• NoRole：不应放入应用程序菜单
• TextHeuristicRole：应根据 QMenuBar 文档中描述的动作文本放置在应用程序菜单中。
• ApplicationSpecificRole：应放在具有应用程序特定角色的应用程序菜单中
• AboutQtRole：处理“关于 Qt”菜单项。
• AboutRole：应放置在应用程序菜单中“关于”菜单项的位置。菜单项的文本将设置为“关于<应用程序名称>”。 应用程序名称是从应用程序包中的 Info.plist 文件中获取的。
• PreferencesRole：应放置在应用程序菜单中“Preferences...”菜单项所在的位置。
• QuitRole：应放在应用程序菜单中退出菜单项的位置。

设置此值仅对菜单栏的即时菜单中的项目有效，对这些菜单的子菜单无效。

3、enum QAction::Priority：此枚举定义用户界面中动作的优先级。 

• LowPriority
• NormalPriority
• HighPriority

三、属性成员

1、autoRepeat : bool

动作是否可以自动重复。默认为true。

如果为 true，则当系统启用键盘自动重复时，按住键盘快捷键组合时动作将自动重复。

2、checkable : bool

动作是否为可选中动作。默认为 false。

可选中动作是具有开/关状态的动作。

      checked : bool

是否已选中。

3、enabled : bool

动作是否启用。

用户不能选择禁用的动作，它们不会从菜单或工具栏中消失，但显示方式表明它们不可用。例如，它们可能仅使用灰色阴影显示。

当一个动作被添加到的所有小部件被禁用或不可见时，该动作将被禁用。

当一个动作被禁用时，不可能通过它的快捷方式来触发它。

4、font : QFont

字体。用于呈现 QAction 上设置的文本。

5、icon : QIcon

图标。在工具栏中，图标用作工具按钮图标；在菜单中，它显示在菜单文本的左侧。

6、iconText : QString

描述性图标文本。

如果 QToolBar::toolButtonStyle 设置为允许显示文本的值，则在此属性中定义的文本将在相关工具按钮中显示为标签。

如果未使用 setText() 或 setToolTip() 设置相关属性，它还用作菜单和工具提示中的默认文本，如果尚未使用 setIcon() 设置图标，它也将用于工具栏按钮。

如果未明确设置图标文本，则动作的文本（text）将用于图标文本。

7、iconVisibleInMenu : bool

是否应在菜单中显示图标。

在某些应用程序中，在工具栏中使用带有图标的动作可能很有意义，但在菜单中却没有。

默认是遵循是否为应用程序设置了 Qt::AA_DontShowIconsInMenus 属性。

QApplication app(argc, argv);
app.setAttribute(Qt::AA_DontShowIconsInMenus);  //菜单中不显示图标
// ...
QAction *myAction = new QAction();
// ...
myAction->setIcon(SomeIcon);
myAction->setIconVisibleInMenu(true);   //设置此动作中显示图标

8、menuRole : MenuRole

动作的菜单角色。

菜单角色只能在将动作放入 macOS 的菜单栏之前更改（通常在显示第一个应用程序窗口之前）。

9、priority : Priority

动作在用户界面中的优先级。

例如，当工具栏设置了 Qt::ToolButtonTextBesideIcon 模式时，具有 LowPriority 的动作将不会显示文本标签。

10、shortcut : QKeySequence

此动作的主快捷键。

11、shortcutContext : Qt::ShortcutContext

动作快捷方式的上下文。默认为 Qt::WindowShortcut。

enum Qt::ShortcutContext：对于要发生的 QEvent::Shortcut 事件，用户必须在快捷方式处于活动状态的上下文中输入快捷方式的键序列： 

• Qt::WidgetShortcut：快捷方式在其父部件获得焦点时处于活动状态。
• Qt::WidgetWithChildrenShortcut：快捷方式在其父窗口小部件或其任何子窗口具有焦点时处于活动状态。作为顶级小部件的子小部件（弹出窗口除外）不受此快捷方式上下文的影响。
• Qt::WindowShortcut：当其父窗口小部件是活动顶层窗口的逻辑子窗口小部件时，快捷方式处于活动状态。
• Qt::ApplicationShortcut：当应用程序窗口之一处于活动状态时，快捷方式处于活动状态。

12、shortcutVisibleInContextMenu : bool

动作是否应在上下文菜单中显示快捷方式。

默认遵循是否为应用程序设置了 Qt::AA_DontShowShortcutsInContextMenus 属性。显式设置此属性会覆盖该属性。

• Qt::AA_DontShowIconsInMenus：具有 Icon 属性的动作不会显示在任何菜单中，除非由 QAction::iconVisibleInMenu 属性特别设置。
• Qt::AA_DontShowShortcutsInContextMenus：具有 Shortcut 属性的动作不会显示在任何快捷菜单中，除非由 QAction::shortcutVisibleInContextMenu 属性特别设置。要覆盖平台集成的设置，请在实例化 QCoreApplication 后设置此属性。

13、statusTip : QString

动作的状态提示。状态提示显示在动作的顶级父窗口小部件提供的所有状态栏上。

14、text : QString

动作的描述性文本。

若将动作添加到菜单，则菜单选项将由图标（如果有）、文本和快捷方式（如果有）组成。

15、toolTip : QString

动作的工具提示。如果未指定工具提示，则使用动作的的 text。

16、visible : bool

是否可见。

17、whatsThis : QString

“这是什么？” 帮助文本。用于提供动作的简要说明。可能包含富文本。

四、函数成员

1、【信号】void changed()

以下属性变化时会发出此信号：

• font
• icon
• iconText
• iconVisibleInMenu
• menuRole
• shortcut
• shortcutContext.
• shortcutVisibleInContextMenu.
• statusTip.
• text.
• toolTip
• whatsThis

2、void hover()

调用activate(Hover)的便利函数。

     void trigger()

3、【信号】void hovered()

当用户突出显示一个动作时发出此信号。例如，当用户将光标悬停在菜单选项、工具栏按钮上或按下动作的快捷键组合时。

4、void setDisabled(bool b)

 是否禁用。

5、void toggle()

这是设置选中属性的便利函数。

6、【信号】void toggled(bool checked)

每当可选中动作更改其 isChecked() 状态时，都会发出此信号。

这可能是用户交互的结果，也可能是因为调用了 setChecked()。当 setChecked() 更改 动作时，它会发出 changed() 和 toggled()。

checked 为是否已经选中了该动作。

7、【信号】void triggered(bool checked = false)

当用户激活动作时发出此信号。

例如，当用户单击菜单选项、工具栏按钮或按下动作的快捷键组合时，或调用 trigger() 时。值得注意的是，调用 setChecked() 或 toggle() 时不会发出它。

如果动作是可选中的，checked 为是否被选中。

8、void setActionGroup(QActionGroup *group) / QActionGroup * actionGroup() 

设置组。组内的动作将是互斥的。

9、QList<QObject *> associatedObjects()

返回已添加此动作的对象列表。

10、QVariant data() / void setData(const QVariant &data)

动作用户数据。

11、void setSeparator(bool b) / bool isSeparator()

如果 b 为true，则此动作将被视为分隔符。

分隔符的表示方式取决于插入它的小部件。在大多数情况下，分隔符动作将忽略文本、子菜单和图标。

12、void setShortcut(const QKeySequence &shortcut)

设置触发动作的唯一快捷方式。

      void setShortcuts(const QList<QKeySequence> &shortcuts)

设置触发动作的快捷方式列表。列表的第一个元素是主要快捷方式。

13、void setShortcuts(QKeySequence::StandardKey key)

根据键设置依赖于平台的快捷键列表。调用此函数的结果将取决于当前运行的平台。

此动作可以分配多个快捷方式。如果只需要主快捷键，请改用 setShortcut()。

14、bool showStatusText(QObject *object = nullptr)

通过发送 QStatusTipEvent 更新由 object 表示的 UI 的相关状态栏。如果发送了事件，则返回 true，否则返回 false。

如果 object 为 nullptr，则将事件发送到QAction的父级。

---

QWidgetAction

一、描述

QWidgetAction 类继承自 QAction，用于将自定义小部件插入到基于QAction的容器中，例如工具栏。

应用程序中的大多数动作都表示为菜单中的项目或工具栏中的按钮。但是，有时需要更复杂的小部件。QToolBar 提供 QToolBar::insertWidget() 作为插入单个小部件的便利功能。但是，如果想实现一个使用自定义小部件在多个容器中进行可视化的动作，那么必须继承 QWidgetAction。

int main(int argc, char *argv[])
{
    QApplication a(argc,argv);
    QMenu popupMenu;
    QAction *action1 = new QAction("&New1",&popupMenu);
    QAction *action2 = new QAction("&New2",&popupMenu);
    QAction *action3 = new QAction("&New3",&popupMenu);
    popupMenu.addAction(action1);
    popupMenu.addAction(action2);
    popupMenu.addAction(action3);

    QWidgetAction * waction1 = new QWidgetAction(&popupMenu);
    waction1->setDefaultWidget(new QPushButton("确定"));
    popupMenu.addAction(waction1);

    popupMenu.exec(QCursor::pos());
}

二、成员函数

1、[virtual protected] QWidget * createWidget(QWidget *parent)

每当将动作添加到支持自定义小部件的容器小部件时，都会调用此函数。

       [virtual protected] void deleteWidget(QWidget *widget)

每当从使用先前使用 createWidget() 创建的自定义小部件显示动作的容器小部件中删除动作时，都会调用此函数。

默认实现隐藏小部件并使用 QObject::deleteLater() 将其删除。 

2、 [protected] QList<QWidget *> createdWidgets()

返回已使用 createWidget() 且当前由已添加动作的小部件使用的小部件列表。

3、void releaseWidget(QWidget *widget)

释放指定的小部件。支持动作的容器小部件在删除小部件动作时调用此函数。

4、QWidget * requestWidget(QWidget *parent)

返回一个代表动作的小部件，具有给定的父级。

支持动作的容器小部件可以调用此函数来请求小部件作为动作的可视化表示。

5、void setDefaultWidget(QWidget *widget) / QWidget * defaultWidget()

将小部件设置为默认小部件。所有权转移给 QWidgetAction。

除非子类重新实现 createWidget() 以返回新的小部件，否则当容器小部件通过 requestWidget() 请求小部件时，将使用默认小部件。 

---

QActionGroup

一、描述

QActionGroup 用于将 QAction 对象分组在一起。

在某些情况下，将 QAction 对象组合在一起很有用。 例如，如果有一个左对齐动作、一个右对齐动作、一个对齐动作和一个居中动作，那么任何时候都应该只有其中一个动作处于活动状态。实现此目的的一种简单方法是将动作分组到一个动作组中。

二、类型成员

1、enum class QActionGroup::ExclusionPolicy：此枚举指定可用于控制组如何对可选中动作执行互斥选中的不同策略。

• None：可以独立选中组中的动作。
• Exclusive：任何时候都可以选中一个动作。这是默认策略。
• ExclusiveOptional：任何时候最多可以选中一个动作。这些动作也可以全部取消选中。

三、属性成员

1、enabled : bool

动作组是否启用。设置时除非已明确禁用，否则组中的每个动作都将启用或禁用。

2、exclusionPolicy : QActionGroup::ExclusionPolicy

选中策略。

3、visible : bool

动作组是否可见。除非已被显式隐藏，否则动作组中的每个动作都将匹配该组的可见状态。

四、成员函数

1、void setDisabled(bool b)

设置是否禁用组。

2、void setExclusive(bool b)

启用或禁用组互斥选中。

这是一个便捷方法，当 b 为true时调用 setExclusionPolicy(ExclusionPolicy::Exclusive)，否则调用 setExclusionPolicy(ExclusionPolicy::None)。

      bool isExclusive()

组是否是互斥的。exclusionPolicy 是 Exclusive 或 ExclusionOptional，则该组是互斥的。

3、QList<QAction *> actions()

返回此组的动作列表。

4、QAction * addAction(QAction *action)

将动作添加到组，并将其返回。

通常，通过将组作为其父项来创建动作，将动作添加到组中，因此通常不使用此功能。

      QAction * addAction(const QString &text)

      QAction * addAction(const QIcon &icon, const QString &text)

创建并返回带有文本、图标的动作。新创建的动作是此组的子项。

通常，通过以组为父项来创建动作，将动作添加到组中，因此通常不使用此功能。

      void removeAction(QAction *action)

从此组中删除动作。action 将没有父级。 

5、QAction * checkedAction()

返回组中当前选中的动作。