Qt: QWhatsThisClickedEvent を使って「What's This?」ヘルプシステムを拡張する

QWhatsThisClickedEvent::href() は、Qt GUIにおける "What's This?" ヘルプシステムで使用されるイベントクラス QWhatsThisClickedEvent のメソッドです。このメソッドは、ユーザーが "What's This?" テキスト内のハイパーリンクをクリックした際に、クリックされたURLを取得するために使用されます。

機能

QWhatsThisClickedEvent::href() メソッドは、QString 型の値を返します。この値は、クリックされたハイパーリンクのURLを表します。

使用方法

このメソッドは、QWhatsThisClickedEvent オブジェクトに対して呼び出されます。このオブジェクトは、"What's This?" テキスト内のハイパーリンクがクリックされたときに発行されるイベントを表します。

例

以下のコード例は、QWhatsThisClickedEvent::href() メソッドを使用して、クリックされたURLを取得する方法を示しています。

void myWidget::whatsThisClicked(QWhatsThisClickedEvent *event)
{
    QString url = event->href();
    // クリックされたURLを使用して処理を行う
}

このメソッドは、静的メソッドではありません。
このメソッドは、QWhatsThisClickedEvent オブジェクトに対してのみ呼び出すことができます。
QWhatsThisClickedEvent::href() メソッドは、"What's This?" ヘルプシステムが有効になっている場合にのみ使用できます。

#include <QApplication>
#include <QLabel>
#include <QWhatsThis>

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

protected:
    void whatsThisClicked(QWhatsThisClickedEvent *event) override;
};

MyWidget::MyWidget(QWidget *parent) : QWidget(parent)
{
    QLabel *label = new QLabel(this);
    label->setText("Click the link to see the URL.");

    QWhatsThis::enableText(label, "This is a link to https://www-example-com.cdn.ampproject.org/c/s/www.example.com");
}

void MyWidget::whatsThisClicked(QWhatsThisClickedEvent *event)
{
    QString url = event->href();
    QMessageBox::information(this, "URL", url);
}

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    MyWidget widget;
    widget.show();
    return app.exec();
}

例2: クリックされたハイパーリンクに基づいて処理を行う

この例では、QWhatsThisClickedEvent::href() メソッドを使用して、クリックされたハイパーリンクのURLを取得し、そのURLに基づいて処理を行う方法を示します。

#include <QApplication>
#include <QDesktopServices>
#include <QLabel>
#include <QWhatsThis>

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

protected:
    void whatsThisClicked(QWhatsThisClickedEvent *event) override;
};

MyWidget::MyWidget(QWidget *parent) : QWidget(parent)
{
    QLabel *label = new QLabel(this);
    label->setText("Click the link to open the URL.");

    QWhatsThis::enableText(label, "This is a link to https://www-example-com.cdn.ampproject.org/c/s/www.example.com");
}

void MyWidget::whatsThisClicked(QWhatsThisClickedEvent *event)
{
    QString url = event->href();
    QDesktopServices::openUrl(QUrl(url));
}

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    MyWidget widget;
    widget.show();
    return app.exec();
}

これらの例は、QWhatsThisClickedEvent::href() メソッドを使用して、クリックされたハイパーリンクに基づいてさまざまな処理を行う方法を示しています。
例2では、クリックされたハイパーリンクのURLを取得し、そのURLに基づいて QDesktopServices::openUrl() 関数を使用してURLを開いています。
例1では、クリックされたハイパーリンクのURLを取得し、ラベルに表示しています。
上記のコード例は、Qt GUIにおける QWhatsThisClickedEvent::href() メソッドの使用方法を示しています。

コード例はあくまでも例であり、必要に応じて変更することができます。
上記のコード例は、Qt CreatorなどのIDEを使用してコンパイルして実行できます。

しかし、QWhatsThisClickedEvent::href() メソッドにはいくつかの制限があります。

静的メソッドではありません。
QWhatsThisClickedEvent オブジェクトに対してのみ呼び出すことができます。
"What's This?" ヘルプシステムが有効になっている場合にのみ使用できます。

これらの制限を回避するために、QWhatsThisClickedEvent::href() メソッドの代替方法がいくつかあります。

代替方法

QTextCursor::posAtEvent() を使用する

QTextCursor::posAtEvent() メソッドを使用して、クリックされた位置を取得し、その位置に対応するURLを抽出することができます。

void myWidget::whatsThisClicked(QWhatsThisClickedEvent *event)
{
    QTextCursor cursor = event->widget()->cursorForPosition(event->pos());
    QString url = cursor.currentChar().data()[0]; // URLを抽出
    // クリックされたURLを使用して処理を行う
}

QWhatsThis::registerWhatsThisHandler() を使用する

QWhatsThis::registerWhatsThisHandler() 関数を使用して、QWhatsThisClickedEvent イベントハンドラを登録することができます。このハンドラは、クリックされた位置とURLを取得し、その情報を使用して処理を行うことができます。

void myWidget::whatsThisClicked(QWhatsThisClickedEvent *event)
{
    QString url = QWhatsThis::registerWhatsThisHandler(event, this);
    // クリックされたURLを使用して処理を行う
}

独自のヘルプシステムを実装する

独自のヘルプシステムを実装することで、QWhatsThisClickedEvent::href() メソッドの制限を回避することができます。

使用する代替方法は、要件に応じて選択する必要があります。
上記の代替方法は、それぞれ異なる利点と欠点があります。