QAction encapsulates a user command as an object, which can be linked to various UI elements like menu items, toolbar buttons, and keyboard shortcuts. This abstraction centralizes command properties, behavior, and state management, promoting UI consistency and simplified event handling.

Core Attributes and Capabilities

1. Properties:

• Text (text): The label displayed on menu entries or toolbar buttons.
• Icon (icon): A graphical symbol associated with the command, typically for toolbar use.
• Keyboard Shortcut (shortcut): A key combination to invoke the command directly.
• Status Bar Hint (statusTip): Informational text shown on the status bar when the pointer hovers over the command's UI representation.
• Tooltip (toolTip): A brief descriptive message displayed during prolonged hovering.
• Toggle Capability (checkable): Determines if the command supports an on/off state, behaving like a checkbox or toggle button.

2. Behavior and Interaction:

• Command Execution: Emits the triggered() signal when activated via UI interaction or its shortcut, which can be connected to a handling function.
• State Change: For toggle-capable commands, the toggled(bool) signal emits the current checked status.
• Custom Data: Allows attaching arbitrary user data for passing context to handler functions.

3. Integration and Management:

• UI Attachment: Added to QMenu, QToolBar, or other action-aware widgets using their addAction() methods.
• Signal-Slot Connections: Use QObject::connect() to link QAction signals to custom slots implementing the command's logic.

C++ Implementation Example

Below is a self-contained example demonstrating QAction usage within a main window. It uses Qt's built-in icon resources and consolidates code for brevity in a single file.

#include <QApplication>
#include <QMainWindow>
#include <QMenuBar>
#include <QToolBar>
#include <QAction>
#include <QKeySequence>
#include <QStatusBar>
#include <QDebug>

class AppWindow : public QMainWindow {
    Q_OBJECT

public:
    AppWindow(QWidget *parent = nullptr) : QMainWindow(parent) {
        // Instantiate command actions
        QAction *cmdCreate = new QAction(QIcon(":/qt-project.org/styles/commonstyle/images/fileicon.png"),
                                          "&Create", this);
        cmdCreate->setShortcut(QKeySequence::New);
        cmdCreate->setStatusTip("Initialize a new document");
        connect(cmdCreate, &QAction::triggered, this, &AppWindow::handleCreate);

        QAction *cmdLoad = new QAction("&Load...", this);
        cmdLoad->setShortcut(QKeySequence::Open);
        cmdLoad->setStatusTip("Load an existing document");
        connect(cmdLoad, &QAction::triggered, this, &AppWindow::handleLoad);

        QAction *cmdStore = new QAction("&Store", this);
        cmdStore->setShortcut(QKeySequence::Save);
        cmdStore->setStatusTip("Store the current document");
        connect(cmdStore, &QAction::triggered, this, &AppWindow::handleStore);

        // Add commands to a menu
        QMenu *docMenu = menuBar()->addMenu("&Document");
        docMenu->addAction(cmdCreate);
        docMenu->addAction(cmdLoad);
        docMenu->addAction(cmdStore);

        // Add commands to a toolbar
        QToolBar *primaryToolbar = addToolBar("Primary Commands");
        primaryToolbar->addAction(cmdCreate);
        primaryToolbar->addAction(cmdLoad);
        primaryToolbar->addAction(cmdStore);

        // Show initial status message
        statusBar()->showMessage(cmdCreate->statusTip());
    }

private slots:
    void handleCreate() {
        qDebug() << "Create command activated";
    }

    void handleLoad() {
        qDebug() << "Load command activated";
    }

    void handleStore() {
        qDebug() << "Store command activated";
    }
};

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    AppWindow window;
    window.show();

    return app.exec();
}

#include "main.moc"

The code defines an AppWindow class with three actions for document operations. Each action is configured with text, a shortcut, and a status tip before being added to both a menu and a toolbar. Their triggered() signals are connected to private slots that print debug messages. The main.moc enclusion is required for the meta-object compiler when using Q_OBJECT in a single source file. A corresponding project file is needed for compilation:

DemoProject.pro

QT       += core gui

greaterThan(QT_MAJOR_VERSION, 4): QT += widgets

CONFIG += c++11

SOURCES += \
    main.cpp