Qt: キーボードショートカットを実装するための QKeySequence::matches() 関数の使い方

QKeySequence::matches()は、Qt GUIアプリケーションにおいて、押されたキーシーケンスが特定のショートカットキーと一致するかどうかを判定するために使用する関数です。これは、キーボードショートカットを実装する際に重要な役割を果たします。

関数引数

QKeySequence::matches()は、以下の2つの引数を受け取ります。

1. seq: 判定対象となるキーシーケンス。QKeySequenceオブジェクトとして渡されます。
2. type: 判定方法を指定するフラグ。以下のいずれかを指定できます。
   • ExactMatch: 完全一致のみ判定します。
   • PartialMatch: 部分一致も判定します。
   • StandardKey: 標準キーシーケンスのみ判定します。

戻り値

QKeySequence::matches()は、以下のいずれかの値を返します。

• NoMatch: 押されたキーシーケンスが seq と全く一致しない場合。
• PartialMatch: 押されたキーシーケンスが seq の一部と一致する場合。
• ExactMatch: 押されたキーシーケンスが seq と完全に一致する場合。

例

// Ctrl+P キーが押されたかどうかを判定
QKeySequence keySequence(Qt::CTRL + Qt::Key_P);
if (keySequence.matches(QApplication::keyboardModifiers(), QKeySequence::ExactMatch)) {
    // Ctrl+P キーが押された処理を実行
}

この例では、QApplication::keyboardModifiers() を使用して、現在押されている修飾キーを取得しています。そして、QKeySequence::ExactMatch を指定することで、完全一致のみを判定しています。

• キーボードショートカットを実装する際には、QShortcut クラスと併用することもできます。
• QKeySequence::matches()は、ウィジェットレベルとアプリケーションレベルの両方で使用できます。

---

#include <QApplication>
#include <QTextEdit>

class MyTextEdit : public QTextEdit
{
public:
    MyTextEdit(QWidget *parent = nullptr);

protected:
    void keyPressEvent(QKeyEvent *event) override;
};

MyTextEdit::MyTextEdit(QWidget *parent)
    : QTextEdit(parent)
{
}

void MyTextEdit::keyPressEvent(QKeyEvent *event)
{
    if (event->key() == Qt::Key_P && event->modifiers() & Qt::ControlModifier) {
        // Ctrl+P キーが押された処理を実行
        qDebug() << "Ctrl+P キーが押されました!";
    } else {
        QTextEdit::keyPressEvent(event);
    }
}

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

    MyTextEdit editor;
    editor.show();

    return app.exec();
}

例2：カスタムショートカットキーの実装

この例では、QShortcut クラスを使用して、Alt+F キーでアプリケーションを終了するカスタムショートカットキーを実装します。

#include <QApplication>
#include <QMainWindow>
#include <QShortcut>

class MyMainWindow : public QMainWindow
{
public:
    MyMainWindow(QWidget *parent = nullptr);
};

MyMainWindow::MyMainWindow(QWidget *parent)
    : QMainWindow(parent)
{
    // Alt+F キーで close() 関数を呼び出すショートカットキーを作成
    QShortcut *shortcut = new QShortcut(Qt::ALT + Qt::Key_F, this);
    connect(shortcut, &QShortcut::activated, this, &MyMainWindow::close);
}

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

    MyMainWindow window;
    window.show();

    return app.exec();
}

---

代替方法

以下に、QKeySequence::matches() の代替方法として検討すべき選択肢をいくつか紹介します。

QKeyEvent クラスを使用する

QKeyEvent クラスは、キーイベントに関する情報を提供するクラスです。QKeyEvent オブジェクトから、押されたキー、修飾キー、テキスト情報などを取得することができます。これらの情報を組み合わせて、キーシーケンスを判定することができます。

void keyPressEvent(QKeyEvent *event)
{
    if (event->key() == Qt::Key_P && event->modifiers() & Qt::ControlModifier) {
        // Ctrl+P キーが押された処理を実行
        qDebug() << "Ctrl+P キーが押されました!";
    } else {
        // 処理なし
    }
}

QShortcut クラスを使用する

QShortcut クラスは、ショートカットキーを定義および管理するためのクラスです。QShortcut オブジェクトを作成して、ショートカットキーとシグナルを関連付けることができます。シグナルがemitされたら、そのキーシーケンスが押されたことを判定することができます。

QShortcut *shortcut = new QShortcut(Qt::ALT + Qt::Key_F, this);
connect(shortcut, &QShortcut::activated, this, &MyMainWindow::close);

キーボードイベントフィルターを使用する

キーボードイベントフィルターは、アプリケーション全体に渡るキーボードイベントを処理するための仕組みです。キーボードイベントフィルターを実装することで、押されたすべてのキーシーケンスを捕捉し、処理することができます。

bool eventFilter(QObject *obj, QEvent *event)
{
    if (event->type() == QEvent::KeyPress) {
        QKeyEvent *keyEvent = static_cast<QKeyEvent *>(event);
        if (keyEvent->key() == Qt::Key_P && keyEvent->modifiers() & Qt::ControlModifier) {
            // Ctrl+P キーが押された処理を実行
            qDebug() << "Ctrl+P キーが押されました!";
            return true; // イベントを処理済みとする
        }
    }
    return QObject::eventFilter(obj, event);
}

カスタムロジックを実装する

上記の方法で解決できない場合は、独自のロジックを実装する必要があります。これは、複雑なキーシーケンスや、アプリケーション固有の要件を処理する場合に有効です。

方法	利点	欠点
QKeyEvent クラス	シンプルでわかりやすい	すべてのキーイベントを処理する必要があり、煩雑になる可能性がある
QShortcut クラス	ショートカットキー管理に特化	複雑なキーシーケンスには対応しにくい
キーボードイベントフィルター	アプリケーション全体のキーイベントを処理できる	実装が複雑になる可能性がある
カスタムロジック	柔軟性が高い	開発コストが上がる