Qt GUI で QHelpEvent クラスを使ってツールチップや "この機能とは何ですか?" ヘルプを実装する

QHelpEvent クラスは、ウィジェット内の特定のポイントに関するヘルプ情報を要求するために使用されるイベントを提供します。これは、ツールチップや "この機能とは何ですか?" などのヘルプ機能を実装するためにアプリケーションで傍受することができます。

詳細

QHelpEvent クラスは、以下の情報を提供します。

• グローバル座標: globalPos() メソッドで取得
• マウスポインタの位置: pos() メソッドで取得
• イベントの種類: QEvent::ToolTip または QEvent::WhatsThis

使用方法

QHelpEvent を処理するには、以下の手順に従います。

1. ウィジェットの helpEvent() シグナルに接続します。
2. シグナルハンドラ内で、type() メソッドを使用してイベントの種類を調べます。
3. pos() または globalPos() メソッドを使用して、マウスポインタの位置を取得します。
4. 適切なヘルプ情報を表示します。

void MyWidget::helpEvent(QHelpEvent *event)
{
    if (event->type() == QEvent::ToolTip) {
        // ツールチップを表示
        QString tip = "このウィジェットは ...";
        QToolTip::showText(event->globalPos(), tip);
    } else if (event->type() == QEvent::WhatsThis) {
        // "この機能とは何ですか?" ヘルプを表示
        QString helpText = "この機能は ...";
        QMessageBox::information(this, "この機能とは何ですか?", helpText);
    }
}

• カスタムウィジェットで QHelpEvent を処理するには、virtual bool helpEvent(QHelpEvent *event) メソッドをオーバーライドする必要があります。
• QHelpEvent は、ウィジェットがフォーカスを持っている場合にのみ送信されます。

• ヘルプシステムの実装方法については、Qt チュートリアルを参照してください。
• Qt GUI には、ヘルプ情報を提供するための他にも、さまざまな機能が用意されています。詳細については、Qt ドキュメントを参照してください。

---

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

protected:
    void helpEvent(QHelpEvent *event) override;
};

MyWidget::MyWidget(QWidget *parent) : QWidget(parent)
{
    // ...
}

void MyWidget::helpEvent(QHelpEvent *event)
{
    if (event->type() == QEvent::ToolTip) {
        QString tip = "このウィジェットは ...";
        QToolTip::showText(event->globalPos(), tip);
    }
}

例 2: "この機能とは何ですか?" ヘルプの表示

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

protected:
    void helpEvent(QHelpEvent *event) override;
};

MyWidget::MyWidget(QWidget *parent) : QWidget(parent)
{
    // ...
}

void MyWidget::helpEvent(QHelpEvent *event)
{
    if (event->type() == QEvent::WhatsThis) {
        QString helpText = "この機能は ...";
        QMessageBox::information(this, "この機能とは何ですか?", helpText);
    }
}

例 3: カスタムヘルプウィジェットの表示

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

protected:
    void helpEvent(QHelpEvent *event) override;
};

MyWidget::MyWidget(QWidget *parent) : QWidget(parent)
{
    // ...
}

void MyWidget::helpEvent(QHelpEvent *event)
{
    if (event->type() == QEvent::HelpRequest) {
        MyHelpWidget helpWidget(this);
        helpWidget.setHelpText("このウィジェットは ...");
        helpWidget.show(event->globalPos());
    }
}

MyHelpWidget クラス

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

    void setHelpText(const QString &text);

private:
    QLabel *textLabel;
};

MyHelpWidget::MyHelpWidget(QWidget *parent) : QWidget(parent)
{
    textLabel = new QLabel(this);
    textLabel->setTextInteractionFlags(Qt::TextInteractionFlag::NoTextInteraction);
    QVBoxLayout *layout = new QVBoxLayout(this);
    layout->addWidget(textLabel);
    layout->setAlignment(Qt::AlignCenter);
}

void MyHelpWidget::setHelpText(const QString &text)
{
    textLabel->setText(text);
}

• カスタムヘルプウィジェットを使用すると、より複雑なヘルプ情報を表示することができます。
• 上記のコードは、3 つの例を示しています。
  • 最初の例では、単純なツールチップを表示します。
  • 2 番目の例では、"この機能とは何ですか?" ヘルプダイアログを表示します。
  • 3 番目の例では、カスタムヘルプウィジェットを表示します。

• 具体的なアプリケーションでは、必要に応じてコードをカスタマイズする必要があります。
• これらの例は、基本的な使用方法を示すものです。

---

Qt GUI には、QHelpEvent クラス以外にも、ヘルプ情報を提供するためのさまざまな方法があります。状況に応じて、以下の代替方法を検討することができます。

ツールチップ

• QToolTip::showText() メソッドを使用して表示できます。
• ウィジェットにマウスポインタを合わせると、簡単な説明が表示されます。
• 最もシンプルな方法です。

"この機能とは何ですか?" ヘルプ

• QWhatsThis::showText() メソッドを使用して表示できます。
• ユーザーが Shift キーを押しながらマウスポインタをウィジェットの上に置くと、詳細な説明が表示されます。

カスタムヘルプウィジェット

• QWidget クラスを継承して作成する必要があります。
• より複雑なヘルプ情報を表示することができます。

コンテキストメニュー

• QMenu クラスを使用して作成する必要があります。
• ヘルプオプションを含むコンテキストメニューを表示することができます。

ステータスバー

• QStatusBar クラスを使用して表示できます。
• ヘルプメッセージをステータスバーに表示することができます。

ドキュメント

• QHelpViewer クラスを使用して表示できます。
• アプリケーション全体のヘルプを提供するために、HTML ドキュメントを作成することができます。

オンラインヘルプ

• QDesktopServices::openUrl() メソッドを使用してリンクを開くことができます。
• オンラインヘルプシステムにリンクを提供することができます。

最適な方法を選択

最適な方法は、アプリケーションの要件によって異なります。

• アプリケーション全体のヘルプを提供する必要がある場合は、ドキュメントやオンラインヘルプシステムを使用するのが良いでしょう。
• より詳細なヘルプが必要な場合は、"この機能とは何ですか?" ヘルプ、カスタムヘルプウィジェット、コンテキストメニューなどの方法を検討することができます。
• シンプルなツールチップで十分な場合は、QToolTip::showText() メソッドを使用するのが最も簡単です。