タスクメニュー拡張

のカスタムウィジェットプラグインを作成する方法を示します。 Qt Widgets Designerのカスタムウィジェットプラグインを作成する方法と、QDesignerTaskMenuExtension クラスを使用してプラグインに関連付けられたカスタムタスクメニューエントリを提供する方法を示します。

Qt Widgets Designer で使用できるカスタムウィジェットを提供するには、自己完結型の実装を提供する必要があります。この例では、タスクメニュー拡張機能を表示するように設計されたカスタムウィジェットを使用します：TicTacToe ウィジェット。

エクステンションは、Qt Widgets Designer の動作を変更するオブジェクトです。QDesignerTaskMenuExtension は、このエクステンションを持つウィジェットが選択されると、カスタムタスクメニューエントリーを提供できます。

Qt Widgets Designer には、4 種類の拡張機能があります：

• QDesignerContainerExtension Qt Widgets Designer のマルチページコンテナプラグインにページを追加 (および削除) できる拡張機能を提供します。
• QDesignerMemberSheetExtension Qt Widgets Designer のシグナルとスロットの編集モードを使用して接続を設定するときに表示される、ウィジェットのメンバ関数を操作できる拡張機能を提供します。
• QDesignerPropertySheetExtension Qt Widgets Designer のプロパティエディタに表示されるウィジェットのプロパティを操作できる拡張機能を提供します。
• QDesignerTaskMenuExtension Qt Widgets Designer のタスクメニューにカスタムメニューエントリを追加できる拡張機能を提供します。

この例と同じパターンで、それぞれの拡張機能ベースクラスを置き換えるだけで、すべての拡張機能を使用できます。詳細は Qt Widgets Designer C++ Classes.

タスクメニューエクステンションの例は5つのクラスで構成されています：

• TicTacToe は、ユーザーに三目並べゲームをプレイさせるカスタムウィジェットです。
• TicTacToePlugin TicTacToe クラスを に公開しています。Qt Widgets Designer
• TicTacToeTaskMenuFactory TicTacToeTaskMenu オブジェクトを作成します。
• TicTacToeTaskMenu タスクメニューエクステンション、つまりプラグインの関連タスクメニューエントリを提供する。
• TicTacToeDialog Qt Widgets Designer にロードされた Tic-Tac-Toe プラグインの状態を変更できます。

カスタムウィジェットプラグインのプロジェクトファイルには、Qt Widgets Designer 内で確実に動作するための追加情報が必要です。たとえば、カスタムウィジェット・プラグインは、Qt Widgets Designer で提供されるコンポーネントに依存しており、使用するプロジェクト・ファイルでこれを指定する必要があります。まず、プラグインのプロジェクトファイルを見てみましょう。

次に、TicTacToePlugin クラスを確認し、TicTacToeTaskMenuFactory とTicTacToeTaskMenu クラスを確認します。最後に、TicTacToe ウィジェットのクラス定義を簡単に見る前に、TicTacToeDialog クラスを確認します。

プロジェクト・ファイル

CMake

プロジェクト・ファイルには、Qt Widgets Designer ライブラリにリンクするプラグインをビルドすることを記述する必要があります：

find_package(Qt6 REQUIRED COMPONENTS Core Designer Gui Widgets)

qt_add_plugin(taskmenuextension)

target_link_libraries(taskmenuextension PUBLIC
    Qt::Core
    Qt::Designer
    Qt::Gui
    Qt::Widgets
)

次の例は、ウィジェットのヘッダーファイルとソースファイルを追加する方法を示しています：

target_sources(taskmenuextension PRIVATE
    tictactoe.cpp tictactoe.h
    tictactoedialog.cpp tictactoedialog.h
    tictactoeplugin.cpp tictactoeplugin.h
    tictactoetaskmenu.cpp tictactoetaskmenu.h
)

Qt Widgets Designer がカスタムウィジェットを使用できるように、プラグインインターフェースの実装を提供します。この例では、タスクメニュー拡張機能と拡張機能ファクトリ、ダイアログの実装も提供します。

プラグインがQt Widgets Designer によって検索される場所にインストールされるようにすることが重要です。プロジェクトのターゲットパスを指定し、インストールするアイテムのリストに追加することでこれを行います：

   set(INSTALL_EXAMPLEDIR "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_PLUGINS}/designer")
install(TARGETS taskmenuextension
    RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
    BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
    LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
)

タスクメニュー拡張機能はライブラリとして作成されます。タスクメニュー拡張機能はライブラリとして作成され、プロジェクトのインストール時に他のQt Widgets Designer プラグインと一緒にインストールされます (ninja install または同等のインストール手順を使用)。

プラグインの詳細については、Qt プラグインの作成方法を参照してください。

qmake

次の例は、プラグインをQt Widgets Designer ライブラリにリンクする方法を示しています：

TEMPLATE = lib
CONFIG  += plugin

QT      += widgets designer

次の例は、ウィジェットのヘッダーファイルとソースファイルを追加する方法を示しています：

HEADERS += tictactoe.h \
           tictactoedialog.h \
           tictactoeplugin.h \
           tictactoetaskmenu.h
SOURCES += tictactoe.cpp \
           tictactoedialog.cpp \
           tictactoeplugin.cpp \
           tictactoetaskmenu.cpp
OTHER_FILES += tictactoe.json

次の例は、プラグインをQt Widgets Designer のプラグインパスにインストールする方法を示しています：

target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += target

TicTacToePlugin クラスの定義

TicTacToePlugin クラスは、the TicTacToe クラスをQt Widgets Designer に公開します。その定義は、詳細に説明されているカスタムウィジェットプラグイン例のプラグインクラスと同等です。クラス定義のうち、この特定のカスタムウィジェットに固有なのはクラス名だけです。

Qt がウィジェットをプラグインとして認識するように、Q_PLUGIN_METADATA() マクロを追加してウィジェットの関連情報をエクスポートします：

#ifndef TICTACTOEPLUGIN_H
#define TICTACTOEPLUGIN_H

#include <QtUiPlugin/QDesignerCustomWidgetInterface>

class QIcon;
class QWidget;

class TicTacToePlugin : public QObject, public QDesignerCustomWidgetInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")
    Q_INTERFACES(QDesignerCustomWidgetInterface)

public:
    explicit TicTacToePlugin(QObject *parent = nullptr);

    QString name() const override;
    QString group() const override;
    QString toolTip() const override;
    QString whatsThis() const override;
    QString includeFile() const override;
    QIcon icon() const override;
    bool isContainer() const override;
    QWidget *createWidget(QWidget *parent) override;
    bool isInitialized() const override;
    void initialize(QDesignerFormEditorInterface *formEditor) override;
    QString domXml() const override;

private:
    bool initialized = false;
};

#endif

プラグインクラスは、クラス名やインクルードファイルなど、プラグインに関する基本情報をQt Widgets Designer に提供します。さらに、TicTacToe ウィジェットのインスタンスを作成する方法も知っています。TicTacToePlugin はinitialize() 関数も定義しており、プラグインがQt Widgets Designer にロードされた後に呼び出されます。この関数のQDesignerFormEditorInterface パラメータは、Qt Widgets Designer のすべての API へのゲートウェイをプラグインに提供します。

TicTacToePlugin クラスは、QObject とQDesignerCustomWidgetInterface の両方を継承します。多重継承を使用する場合、Q_INTERFACES() マクロを使用して、すべてのインターフェイス（つまり、Q_OBJECT を継承しないクラス）をメタ・オブジェクト・システムに確実に知らせることが重要です。これにより、Qt Widgets Designer は、qobject_cast() を使用して、QObject ポインタだけを使用して、サポートされているインターフェイスを問い合わせることができます。

TicTacToePluginクラスの実装

TicTacToePluginクラスの実装は、ほとんどの部分でCustom Widget Pluginサンプルのプラグインクラスと同等です：

TicTacToePlugin::TicTacToePlugin(QObject *parent)
    : QObject(parent)
{
}

QString TicTacToePlugin::name() const
{
    return u"TicTacToe"_s;
}

QString TicTacToePlugin::group() const
{
    return u"Display Widgets [Examples]"_s;
}

QString TicTacToePlugin::toolTip() const
{
    return u"Tic Tac Toe Example, demonstrating class QDesignerTaskMenuExtension (C++)"_s;
}

QString TicTacToePlugin::whatsThis() const
{
    return {};
}

QString TicTacToePlugin::includeFile() const
{
    return u"tictactoe.h"_s;
}

QIcon TicTacToePlugin::icon() const
{
    return {};
}

bool TicTacToePlugin::isContainer() const
{
    return false;
}

QWidget *TicTacToePlugin::createWidget(QWidget *parent)
{
    auto *ticTacToe = new TicTacToe(parent);
    ticTacToe->setState(u"-X-XO----"_s);
    return ticTacToe;
}

bool TicTacToePlugin::isInitialized() const
{
    return initialized;
}

大きく異なる唯一の関数は、initialize()関数です：

void TicTacToePlugin::initialize(QDesignerFormEditorInterface *formEditor)
{

initialize() 関数は引数としてQDesignerFormEditorInterface オブジェクトを受け取ります。QDesignerFormEditorInterface クラスはQt Widgets Designer のコンポーネントへのアクセスを提供します。

Qt Widgets Designer では、カスタムウィジェットプラグインとツールプラグインの2種類のプラグインを作成できます。QDesignerFormEditorInterface は、通常ツールプラグインを作成するために必要なすべてのQt Widgets Designer コンポーネントへのアクセスを提供します：エクステンションマネージャ、オブジェクトインスペクタ、プロパティエディタ、ウィジェットボックスです。カスタムウィジェットプラグインも同じコンポーネントにアクセスできます。

    if (initialized)
        return;

    auto *manager = formEditor->extensionManager();
    Q_ASSERT(manager != nullptr);

カスタムウィジェットプラグインに関連するエクステンションを作成する場合、QDesignerFormEditorInterface パラメータから取得したQt Widgets Designer'現在のエクステンションマネージャにアクセスする必要があります。

Qt Widgets Designer QDesignerFormEditorInterface は のすべてのコンポーネントに関する情報を保持しています：アクションエディタ、オブジェクトインスペクタ、プロパティエディタ、ウィジェットボックス、拡張機能およびフォームウィンドウマネージャです。Qt Designer

QExtensionManager クラスはQt Widgets Designer の拡張機能管理機能を提供します。Qt Widgets Designer'の現在の拡張機能マネージャを使用すると、与えられたオブジェクトの拡張機能を取得できます。また、与えられたオブジェクトの拡張機能を登録したり解除したりすることもできます。拡張機能とは、Qt Widgets Designer の動作を変更するオブジェクトであることを覚えておいてください。

拡張機能を登録するとき、実際に登録されるのは関連する拡張機能ファクトリです。Qt Widgets Designer では、拡張機能ファクトリーは、必要に応じて名前付き拡張機能を検索し、作成するために使用されます。したがって、この例では、タスクメニューの拡張機能自体は、ユーザーによってタスクメニューが要求されるまで作成されません。

    manager->registerExtensions(new TicTacToeTaskMenuFactory(manager),
                                Q_TYPEID(QDesignerTaskMenuExtension));

    initialized = true;
}

QString TicTacToePlugin::domXml() const
{
    return uR"(
<ui language="c++">
    <widget class="TicTacToe" name="ticTacToe"/>
    <customwidgets>
        <customwidget>
            <class>TicTacToe</class>
            <propertyspecifications>
            <tooltip name="state">Tic Tac Toe state</tooltip>
            <stringpropertyspecification name="state" notr="true" type="singleline"/>
            </propertyspecifications>
        </customwidget>
    </customwidgets>
</ui>
)"_s;
}

QDesignerFormEditorInterface パラメータから取得したQt Widgets Designer の現在のextension manager を使用して登録するTicTacToeTaskMenuFactory オブジェクトを作成します。最初の引数は新しく作成されたファクトリーで、2 番目の引数は文字列である拡張機能識別子です。Q_TYPEID() マクロは単に文字列をQLatin1String に変換します。

TicTacToeTaskMenuFactory クラスはQExtensionFactory のサブクラスである。ユーザが指定されたタスクメニュー拡張子を持つウィジェット上でマウスの右ボタンをクリックしてタスクメニューを要求すると、Qt Widgets Designer の拡張子マネージャは登録されたすべてのファクトリーを実行し、選択されたウィジェットのタスクメニュー拡張子を作成できる最初のファクトリーを呼び出す。このファクトリーはTicTacToeTaskMenu オブジェクト（拡張機能）を作成します。

デフォルト値は必要ないので、QDesignerCustomWidgetInterface::domXml() 関数 (Qt Widgets Designer で使われる標準 XML フォーマットのウィジェットのデフォルト設定を含む) の再実装は省略する。

    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")

最後に、Q_PLUGIN_METADATA()マクロを使用して、Qtのプラグイン処理クラスで使用するTicTacToePluginクラスをエクスポートします：このマクロは、Qt Widgets Designer がカスタムウィジェットにアクセスして構築できることを保証します。このマクロがないと、Qt Widgets Designer 、ウィジェットを使うことができません。

TicTacToeTaskMenuFactory クラスの定義

TicTacToeTaskMenuFactory クラスはQExtensionFactory を継承し、Qt Widgets Designer の標準拡張ファクトリを提供します。

class TicTacToeTaskMenuFactory : public QExtensionFactory
{
    Q_OBJECT

public:
    explicit TicTacToeTaskMenuFactory(QExtensionManager *parent = nullptr);

protected:
    QObject *createExtension(QObject *object, const QString &iid, QObject *parent) const override;
};

このサブクラスの目的は、QExtensionFactory::createExtension() 関数を再実装し、TicTacToe タスクメニュー拡張機能を作成できるようにすることです。

TicTacToeTaskMenuFactory クラスの実装

クラスのコンストラクタは、QExtensionFactory ベースクラスのコンストラクタを呼び出すだけです：

TicTacToeTaskMenuFactory::TicTacToeTaskMenuFactory(QExtensionManager *parent)
    : QExtensionFactory(parent)
{
}

上述したように、Qt Widgets Designer で指定されたタスクメニュー拡張機能を持つウィジェットの上でマウスの右ボタンをクリックして、ユーザーがタスクメニューを要求すると、ファクトリーが呼び出されます。

Qt Widgets Designerファクトリの動作は、要求された拡張機能がコンテナ、メンバーシート、プロパティシート、タスクメニューのいずれに関連付けられていても同じです：エクステンションマネージャーは登録されたエクステンションファクトリーからcreateExtension() を呼び出します。

QObject *TicTacToeTaskMenuFactory::createExtension(QObject *object,
                                                   const QString &iid,
                                                   QObject *parent) const
{
    if (iid != Q_TYPEID(QDesignerTaskMenuExtension))
        return nullptr;

    if (auto *tic = qobject_cast<TicTacToe*>(object))
        return new TicTacToeTaskMenu(tic, parent);

    return nullptr;
}

したがって、TicTacToeTaskMenuFactory::createExtension() で最初にすることは、要求された拡張機能がタスクメニュー拡張機能かどうかをチェックすることです。もしそうで、要求しているウィジェットがTicTacToe ウィジェットなら、TicTacToeTaskMenu オブジェクトを作成して返します。そうでなければ、単に null ポインタを返し、Qt Widgets Designer の拡張機能マネージャが登録されたファクトリの検索を続けられるようにします。

TicTacToeTaskMenu クラスの定義

TicTacToeTaskMenu クラスはQDesignerTaskMenuExtension を継承し、Qt Widgets Designer のタスク・メニューにカスタム・エントリ（QActions 形式）を追加できるようにします。

class TicTacToeTaskMenu : public QObject, public QDesignerTaskMenuExtension
{
    Q_OBJECT
    Q_INTERFACES(QDesignerTaskMenuExtension)

public:
    explicit TicTacToeTaskMenu(TicTacToe *tic, QObject *parent);

    QAction *preferredEditAction() const override;
    QList<QAction *> taskActions() const override;

private slots:
    void editState();

private:
    QAction *editStateAction;
    TicTacToe *ticTacToe;
};

preferredEditAction() とtaskActions() 関数を再実装します。親ウィジェットと、タスクメニューが要求されるTicTacToe ウィジェットです。

さらに、editState() のプライベートスロット、editStateAction のカスタムスロット、TicTacToe ウィジェットへのプライベートポインタを宣言します。

TicTacToeTaskMenuクラスの実装

TicTacToeTaskMenu::TicTacToeTaskMenu(TicTacToe *tic, QObject *parent)
    : QObject(parent)
    , editStateAction(new QAction(tr("Edit State..."), this))
    , ticTacToe(tic)
{
    connect(editStateAction, &QAction::triggered, this, &TicTacToeTaskMenu::editState);
}

コンストラクタでは、まずパラメータとして送られたTicTacToe ウィジェットへの参照を保存します。これは後でカスタムアクションが呼び出されるときに必要になります。また、カスタムeditStateAction を作成し、editState() スロットに接続します。

void TicTacToeTaskMenu::editState()
{
    TicTacToeDialog dialog(ticTacToe);
    dialog.exec();
}

editState() スロットは、ユーザがTicTacToe ウィジェットのタスクメニューでEdit State...オプションを選択するたびに呼び出されます。このスロットは、ウィジェットの現在の状態を表示するTicTacToeDialog を作成し、ユーザがゲームをプレイすることで状態を編集できるようにします。

QAction *TicTacToeTaskMenu::preferredEditAction() const
{
    return editStateAction;
}

TicTacToe ウィジェットを選択してF2キーを押したときに呼び出されるアクションとして、カスタムeditStateAction を返すようにpreferredEditAction() 関数を再実装します。

QList<QAction *> TicTacToeTaskMenu::taskActions() const
{
    return QList<QAction *>{editStateAction};
}

taskActions() 関数を再実装して、カスタムアクションのリストを返し、TicTacToe ウィジェットのタスクメニューのデフォルトメニューエントリの上に表示します。

TicTacToeDialogクラスの定義

TicTacToeDialog クラスはQDialog を継承しています。このダイアログによって、ユーザーは現在選択されているTic-Tac-Toeプラグインの状態を修正できます。

class TicTacToeDialog : public QDialog
{
    Q_OBJECT

public:
    explicit TicTacToeDialog(TicTacToe *plugin = nullptr, QWidget *parent = nullptr);

    QSize sizeHint() const override;

private slots:
    void resetState();
    void saveState();

private:
    TicTacToe *editor;
    TicTacToe *ticTacToe;
    QDialogButtonBox *buttonBox;
};

sizeHint() 関数を再実装します。また、resetState() とsaveState() の2つのプライベートスロットを宣言します。ダイアログのボタンとレイアウトに加えて、TicTacToe の2つのポインタを宣言します。1つは、ユーザが対話できるウィジェットへのポインタ、もう1つは、ユーザが状態を編集したい元のカスタムウィジェットプラグインへのポインタです。

TicTacToeDialogクラスの実装

TicTacToeDialog::TicTacToeDialog(TicTacToe *tic, QWidget *parent)
    : QDialog(parent)
    , editor(new TicTacToe)
    , ticTacToe(tic)
    , buttonBox(new QDialogButtonBox(QDialogButtonBox::Ok
                                     | QDialogButtonBox::Cancel
                                     | QDialogButtonBox::Reset))
{
    editor->setState(ticTacToe->state());

    connect(buttonBox->button(QDialogButtonBox::Reset), &QAbstractButton::clicked,
            this, &TicTacToeDialog::resetState);
    connect(buttonBox, &QDialogButtonBox::accepted, this, &TicTacToeDialog::saveState);
    connect(buttonBox, &QDialogButtonBox::rejected, this, &QDialog::reject);

    auto *mainLayout = new QVBoxLayout(this);
    mainLayout->addWidget(editor);
    mainLayout->addWidget(buttonBox);

    setWindowTitle(tr("Edit State"));
}

コンストラクタでは、まずパラメータとして送られたTicTacToeウィジェットへの参照を保存します。次に、新しいTicTacToe ウィジェットを作成し、その状態をパラメータ・ウィジェットの状態と同じに設定します。

最後に、ダイアログのボタンとレイアウトを作成します。

QSize TicTacToeDialog::sizeHint() const
{
    return {250, 250};
}

sizeHint() 関数を再実装して、ダイアログが適切なサイズになるようにします。

void TicTacToeDialog::resetState()
{
    editor->clearBoard();
}

resetState() スロットは、ユーザーがリセットボタンを押すたびに呼び出されます。エディタウィジェット、つまりダイアログのコンストラクタで作成したTicTacToe ウィジェットに対してclearBoard() 関数を呼び出すだけです。

void TicTacToeDialog::saveState()
{

saveState() スロットは、ユーザがOKボタンを押すたびに呼び出され、エディタ・ウィジェットの状態を変更したいウィジェットに転送します。状態の変更をQt Widgets Designer に見えるようにするには、QDesignerFormWindowInterface クラスを使って、後者のウィジェットの state プロパティを設定する必要があります。

QDesignerFormWindowInterface は、関連するフォーム・ウィンドウに関する情報を提供し、そのプロパティを変更できるようにします。このインターフェースは直接インスタンス化されることを意図しておらず、Qt Widgets Designer のフォーム・ウィンドウ・マネージャーによって制御されるQt Widgets Designer の現在のフォーム・ウィンドウへのアクセスを提供するものです。

特定のウィジェットを含むフォーム・ウィンドウを探す場合は、静的関数QDesignerFormWindowInterface::findFormWindow() を使用します：

    if (auto *formWindow = QDesignerFormWindowInterface::findFormWindow(ticTacToe))
        formWindow->cursor()->setProperty("state", editor->state());

変更したいウィジェットのフォーム・ウィンドウを取得した後、QDesignerFormWindowInterface::cursor() 関数を使用してフォーム・ウィンドウのカーソルを取得します。

QDesignerFormWindowCursorInterface クラスは、フォーム・ウィンドウのテキスト・カーソルへのインタフェースを提供します。カーソルを取得したら、最後にQDesignerFormWindowCursorInterface::setProperty （）関数を使ってstateプロパティを設定します。

    accept();
}

最後に、イベント・オブジェクトのacceptフラグを設定するQEvent::accept （）関数を呼び出します。accept パラメータを設定することは、イベント受信者がイベントを望んでいることを示す。不要なイベントは、親ウィジェットに伝搬される可能性があります。

TicTacToe クラスの定義

TicTacToe クラスは、ユーザが三目並べゲームをプレイできるカスタムウィジェットです。

class TicTacToe : public QWidget
{
    Q_OBJECT
    Q_PROPERTY(QString state READ state WRITE setState)

public:
    explicit TicTacToe(QWidget *parent = nullptr);

    QSize minimumSizeHint() const override;
    QSize sizeHint() const override;
    void setState(const QString &newState);
    QString state() const;
    void clearBoard();

protected:
    void mousePressEvent(QMouseEvent *event) override;
    void paintEvent(QPaintEvent *event) override;

private:
    static constexpr char16_t Empty = '-';
    static constexpr char16_t Cross = 'X';
    static constexpr char16_t Nought = 'O';

    QRect cellRect(int position) const;
    int cellWidth() const { return width() / 3; }
    int cellHeight() const { return height() / 3; }

    QString myState;
    int turnNumber = 0;
};

TicTacToe クラス定義の主な内容は、state プロパティの宣言と、state() 関数およびsetState() 関数です。

TicTacToe ウィジェットの状態をプロパティとして宣言して、Qt Widgets Designer から見えるようにする必要があります。Qt Widgets Designer は、TicTacToe ウィジェットがQWidget とQObject から継承したプロパティと同じ方法で管理できます。

プロジェクト例 @ code.qt.io