【保存版】Qt Widgets - キーシーケンス編集の基本から応用まで、QKeySequenceEditを使いこなす

QKeySequenceEditクラスは、Qt Widgetsライブラリで提供される、ユーザー入力を介してキーシーケンスを選択できるウィジェットです。キーシーケンスとは、修飾キー（Ctrl、Shift、Altなど）と通常キーの組み合わせを表すもので、ショートカットキーなどに利用されます。

主な機能

ショートカットキーとして使用可能なキーシーケンスのリスト表示
キーシーケンスの有効性チェック
現在選択されているキーシーケンスの取得
ユーザーによるキーシーケンスの入力と編集

プロパティ

autoRepeat: キーが押されたままの状態が続いた場合に、キーシーケンスが自動的に繰り返されるかどうかを制御するブール値
keySequence: 現在選択されているキーシーケンスを表すQKeySequenceオブジェクト

シグナル

editingFinished(): ユーザーがキーシーケンスの入力を完了したときに発行されるシグナル

スロット

setKeySequence(const QKeySequence &): 選択されているキーシーケンスを設定するスロット

詳細解説

QKeySequenceEditウィジェットは、主にショートカットキーの設定画面などで利用されます。ユーザーは、ウィジェットにフォーカスを当ててキーを押すことで、キーシーケンスを入力することができます。修飾キーと通常キーの組み合わせを入力することで、複雑なキーシーケンスも設定可能です。

入力されたキーシーケンスは、keySequenceプロパティによって取得することができます。また、setKeySequenceスロットを使用して、プログラム側からもキーシーケンスを設定することができます。

QKeySequenceEditウィジェットは、editingFinishedシグナルを発行することで、ユーザーがキーシーケンスの入力を完了したことを通知します。このシグナルを接続することで、入力されたキーシーケンスを処理するコードを実行することができます。

例

#include <QtWidgets/QApplication>
#include <QtWidgets/QKeySequenceEdit>

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

  // ウィジェットを作成
  QKeySequenceEdit keySequenceEdit;

  // キーシーケンスが入力完了したら処理を実行
  QObject::connect(&keySequenceEdit, &QKeySequenceEdit::editingFinished,
                   []() {
                     // 入力されたキーシーケンスを取得
                     QKeySequence keySequence = keySequenceEdit.keySequence();

                     // キーシーケンスを処理
                     if (keySequence == Qt::Key_Ctrl + Qt::Key_Z) {
                       // Ctrl + Zが押されたら処理を実行
                     }
                   });

  // ウィジェットを表示
  keySequenceEdit.show();

  return app.exec();
}

この例では、QKeySequenceEditウィジェットを作成し、editingFinishedシグナルに接続しています。シグナルハンドラ内では、入力されたキーシーケンスを取得し、Ctrl + Zキーが押されたかどうかをチェックしています。押された場合は、処理を実行しています。

QKeySequenceEditウィジェットは、Qt DesignerなどのGUIデザイナーツールを使用して、フォームエディタにドラッグアンドドロップで配置することができます。
ショートカットキーとして使用できないキーシーケンスを入力した場合は、ユーザーに警告を表示することができます。
QKeySequenceEditウィジェットは、入力されたキーシーケンスの有効性をチェックしません。無効なキーシーケンスを入力しても、エラーは発生しません。

ショートカットキーの設定

この例では、QKeySequenceEdit ウィジェットを使用して、ショートカットキーを設定する方法を示します。

#include <QtWidgets/QApplication>
#include <QtWidgets/QKeySequenceEdit>
#include <QtWidgets/QLabel>

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

  // ラベルを作成
  QLabel label("ショートカットキーを設定するには、キーを押してください。");

  // キーシーケンス編集ウィジェットを作成
  QKeySequenceEdit keySequenceEdit;

  // キーシーケンスが入力完了したら処理を実行
  QObject::connect(&keySequenceEdit, &QKeySequenceEdit::editingFinished,
                   [&label, &keySequenceEdit]() {
                     // 入力されたキーシーケンスを取得
                     QKeySequence keySequence = keySequenceEdit.keySequence();

                     // キーシーケンスをラベルに設定
                     label.setText(QString("現在のショートカットキー: ") + keySequence.toString());
                   });

  // レイアウトを設定
  QVBoxLayout layout;
  layout.addWidget(&label);
  layout.addWidget(&keySequenceEdit);

  // ウィジェットを表示
  QWidget window;
  window.setLayout(&layout);
  window.show();

  return app.exec();
}

このコードを実行すると、ウィンドウが表示されます。ウィンドウ内にラベルとキーシーケンス編集ウィジェットが表示されます。ユーザーがキーシーケンス編集ウィジェットにフォーカスを当ててキーを押すと、入力されたキーシーケンスがラベルに表示されます。

キーシーケンスの有効性チェック

この例では、QKeySequenceEdit を使用して、入力されたキーシーケンスの有効性をチェックする方法を示します。

#include <QtWidgets/QApplication>
#include <QtWidgets/QKeySequenceEdit>
#include <QtWidgets/QMessageBox>

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

  // キーシーケンス編集ウィジェットを作成
  QKeySequenceEdit keySequenceEdit;

  // キーシーケンスが入力完了したら処理を実行
  QObject::connect(&keySequenceEdit, &QKeySequenceEdit::editingFinished,
                   [&keySequenceEdit]() {
                     // 入力されたキーシーケンスを取得
                     QKeySequence keySequence = keySequenceEdit.keySequence();

                     // キーシーケンスが有効かどうかをチェック
                     if (!keySequence.isValid()) {
                       // 無効なキーシーケンスの場合は、エラーメッセージを表示
                       QMessageBox::warning(nullptr, "エラー", "無効なキーシーケンスです。");
                     } else {
                       // 有効なキーシーケンスの場合は、キーシーケンスを処理
                       // ...
                     }
                   });

  // ウィジェットを表示
  keySequenceEdit.show();

  return app.exec();
}

このコードを実行すると、ウィンドウが表示されます。ウィンドウ内にキーシーケンス編集ウィジェットが表示されます。ユーザーがキーシーケンス編集ウィジェットにフォーカスを当ててキーを押すと、入力されたキーシーケンスの有効性がチェックされます。無効なキーシーケンスを入力した場合には、エラーメッセージが表示されます。

この例では、QKeySequenceEdit を使用して、ショートカットキーとして使用できないキーシーケンスの警告を表示する方法を示します。

#include <QtWidgets/QApplication>
#include <QtWidgets/QKeySequenceEdit>
#include <QtWidgets/QMessageBox>
#include <QRegularExpression>

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

  // キーシーケンス編集ウィジェットを作成
  QKeySequenceEdit keySequenceEdit;

  // キーシーケンスが入力完了したら処理を実行
  QObject::connect(&keySequenceEdit, &QKeySequenceEdit::editingFinished,
                   [&keySequenceEdit]() {
                     // 入力されたキーシーケンスを取得
                     QKeySequence keySequence = keySequenceEdit.keySequence();

                     // ショートカットキーとして使用できないキーシーケンスかどうかをチェック
                     QRegularExpression regex("[A-Za-z0-9+\\-\\^/!@#\$%&\\*'\\(\\)\\-_=\\{\\}\\|\\:\\;\\<\\>\\?\\,\\./\\?\\<\\>\\?\\,\\./\\[\\]\\^~`]");
                     if (!regex.match(keySequence.toString()).

代替方法

QShortcut: 特定のキーシーケンスにアクションを関連付ける場合、QShortcut クラスがより適している場合があります。QShortcut は、キーシーケンスとスロットを直接結びつけることができ、より簡潔なコードで実現できます。

QShortcut *shortcut = new QShortcut(QKeySequence(Qt::CTRL + Qt::Key_Z), this);
connect(shortcut, &QShortcut::activated, this, &MyClass::mySlot);

キーイベントハンドラ: より高度な制御が必要な場合は、キーイベントハンドラを使用することができます。キーイベントハンドラを使用すると、押されたキー、修飾キー、イベント発生ウィジェットなどの情報を取得することができます。

void MyClass::keyPressEvent(QKeyEvent *event) {
  if (event->key() == Qt::Key_Z && event->modifiers() & Qt::ControlModifier) {
    // Ctrl + Zが押されたら処理を実行
  }
}

カスタムウィジェット: より複雑な要件の場合は、カスタムウィジェットを作成することができます。カスタムウィジェットを使用すると、外観や動作を完全に制御することができます。

各方法の比較

方法	利点	欠点	適した状況
QKeySequenceEdit	使いやすい	カスタマイズ性に欠ける	シンプルなショートカットキーの設定
QShortcut	簡潔なコード	キーイベントの詳細情報にアクセスできない	特定のキーシーケンスにアクションを関連付ける
キーイベントハンドラ	高度な制御が可能	コードが複雑になる	複雑なキーシーケンス処理
カスタムウィジェット	完全な制御が可能	開発コストが高い	複雑な要件

QKeySequenceEdit は、使いやすいキーシーケンス選択ウィジェットですが、状況に応じて代替方法を検討することで、より柔軟な開発を実現することができます。

キーシーケンスの文字列表現を取得するには、QKeySequence::toString() メソッドを使用することができます。
上記以外にも、キーシーケンスの入力を取得する方法として、QInputDialog::keySequence() 関数を使用する方法もあります。