사용자 정의 위젯 플러그인

이 예제에서 사용되는 사용자 정의 위젯은 아날로그 시계 예제를 기반으로 하며, 사용자 정의 신호나 슬롯을 제공하지 않습니다.

준비

Qt Widgets Designer 에서 사용할 수 있는 사용자 정의 위젯을 제공하려면, 독립적인 구현을 제공하고 플러그인 인터페이스를 정의해야 합니다. 이 예제에서는 편의상 아날로그 시계 예제를 재사용합니다.

프로젝트 파일

CMake

프로젝트 파일에는 Qt Widgets Designer 라이브러리에 링크되는 플러그인을 빌드해야 한다는 내용이 명시되어야 합니다:

find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)

qt_add_plugin(customwidgetplugin)

target_link_libraries(customwidgetplugin PUBLIC
    Qt::Core
    Qt::Gui
    Qt::UiPlugin
    Qt::Widgets
)

링크 라이브러리 목록에는 Qt::UiPlugin 가 지정되어 있습니다. 이는 플러그인이 QDesignerCustomWidgetInterface 및 QDesignerCustomWidgetCollectionInterface 추상 인터페이스만을 사용하며, Qt Widgets Designer 라이브러리와는 링크되지 않음을 나타냅니다. 링크가 설정된 Qt Widgets Designer 의 다른 인터페이스에 접근할 때는 대신 Designer 를 사용해야 합니다. 이렇게 하면 플러그인이 Qt Widgets Designer 라이브러리에 동적으로 링크되고, 해당 라이브러리에 대한 런타임 종속성을 갖게 됩니다.

다음 예제는 위젯의 헤더 파일과 소스 파일을 추가하는 방법을 보여줍니다:

target_sources(customwidgetplugin PRIVATE
    analogclock.cpp analogclock.h
    customwidgetplugin.cpp customwidgetplugin.h
)

Qt Widgets Designer 가 사용자 정의 위젯을 사용할 수 있도록 플러그인 인터페이스의 구현체를 제공합니다.

또한 플러그인이 Qt Widgets Designer 에서 검색하는 위치에 설치되도록 하는 것도 중요합니다. 이를 위해 프로젝트의 대상 경로를 지정하고 설치할 항목 목록에 추가합니다:

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

사용자 정의 위젯은 라이브러리 형태로 생성됩니다. 프로젝트가 설치될 때( ninja install 또는 이에 상응하는 설치 절차를 통해) 다른 Qt Widgets Designer 플러그인과 함께 설치됩니다.

플러그인에 대한 자세한 내용은 'Qt 플러그인 생성 방법' 문서를 참조하십시오.

qmake

다음 예제는 플러그인을 Qt Widgets Designer 라이브러리에 링크하는 방법을 보여줍니다:

CONFIG      += plugin
TEMPLATE    = lib

QT          += widgets uiplugin

QT 변수에는 uiplugin 키워드가 포함되어 있으며, 이는 Qt::UiPlugin 라이브러리와 동일합니다.

다음 예제는 위젯의 헤더 파일과 소스 파일을 추가하는 방법을 보여줍니다:

HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

다음 예제는 Qt Widgets Designer 의 플러그인 경로에 플러그인을 설치하는 방법을 보여줍니다:

TARGET = $$qtLibraryTarget($$TARGET)

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

AnalogClock 클래스 정의 및 구현

AnalogClock 클래스는 아날로그 시계 예제에서 설명한 것과 정확히 동일한 방식으로 정의되고 구현됩니다. 이 클래스는 자체적으로 완비되어 있으며 외부 구성이 필요하지 않으므로, Qt Widgets Designer 에서 수정 없이 사용자 정의 위젯으로 사용할 수 있습니다.

AnalogClockPlugin 클래스 정의

AnalogClock 클래스는 AnalogClockPlugin 클래스를 통해 Qt Widgets Designer 에 노출됩니다. 이 클래스는 QObject 및 QDesignerCustomWidgetInterface 클래스를 모두 상속받으며, QDesignerCustomWidgetInterface 에서 정의된 인터페이스를 구현합니다.

Qt가 해당 위젯을 플러그인으로 인식할 수 있도록 하려면, Q_PLUGIN_METADATA() 매크로를 추가하여 위젯에 대한 관련 정보를 내보내야 합니다:

class AnalogClockPlugin : public QObject, public QDesignerCustomWidgetInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")
    Q_INTERFACES(QDesignerCustomWidgetInterface)
public:
    explicit AnalogClockPlugin(QObject *parent = nullptr);

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

private:
    bool initialized = false;
};

이 함수들은 Qt Widgets Designer 가 위젯 상자에서 사용할 수 있는 위젯에 대한 정보를 제공합니다. initialized 사적 멤버 변수는 플러그인이 Qt Widgets Designer 에 의해 초기화되었는지 여부를 기록하는 데 사용됩니다.

이 특정 사용자 정의 위젯에 고유한 클래스 정의 부분은 클래스 이름뿐이라는 점에 유의하십시오.

AnalogClockPlugin 구현

이 클래스의 생성자는 단순히 QObject 기본 클래스의 생성자를 호출하고, initialized 변수를 false 로 설정합니다.

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

Qt Widgets Designer initialize() 함수를 호출하여 플러그인이 필요할 때 초기화합니다:

void AnalogClockPlugin::initialize(QDesignerFormEditorInterface * /* core */)
{
    if (initialized)
        return;

    initialized = true;
}

이 예제에서는 initialized 비공개 변수를 확인하며, 플러그인이 아직 초기화되지 않은 경우에만 true 으로 설정합니다. 비록 이 플러그인은 초기화 시 실행해야 할 특별한 코드가 필요하지는 않지만, 초기화 확인 후 그러한 코드를 포함시킬 수도 있습니다.

isInitialized() 함수는 Qt Widgets Designer 에 플러그인이 사용 준비가 되었는지 여부를 알립니다:

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

사용자 정의 위젯의 인스턴스는 ` createWidget() ` 함수를 통해 제공됩니다. 아날로그 시계의 구현은 간단합니다:

QWidget *AnalogClockPlugin::createWidget(QWidget *parent)
{
    return new AnalogClock(parent);
}

이 경우 사용자 정의 위젯에는 ` parent `만 지정하면 됩니다. 위젯에 다른 인수를 전달해야 하는 경우, 여기에서 추가할 수 있습니다.

다음 함수들은 ` Qt Widgets Designer `가 위젯 상자에서 위젯을 표현하는 데 사용할 정보를 제공합니다. ` name() ` 함수는 사용자 정의 위젯을 제공하는 클래스의 이름을 반환합니다:

QString AnalogClockPlugin::name() const
{
    return u"AnalogClock"_s;
}

group() 함수는 사용자 정의 위젯이 속한 위젯 유형을 설명하는 데 사용됩니다:

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

위젯 플러그인은 Qt Widgets Designer 의 위젯 상자에서 그룹 이름으로 식별되는 섹션에 배치됩니다. 위젯 상자에서 위젯을 나타내는 데 사용되는 아이콘은 icon() 함수에 의해 반환됩니다:

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

이 경우, 위젯을 나타낼 수 있는 아이콘이 없음을 나타내기 위해 null 아이콘을 반환합니다.

위젯 상자 내 사용자 정의 위젯 항목에 툴팁과 "이게 뭐죠?" 도움말을 제공할 수 있습니다. ` toolTip() ` 함수는 위젯을 설명하는 짧은 메시지를 반환해야 합니다:

QString AnalogClockPlugin::toolTip() const
{
    return {};
}

whatsThis() 함수는 더 긴 설명을 반환할 수 있습니다:

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

isContainer() 함수는 위젯이 다른 위젯을 담는 컨테이너로 사용되어야 하는지 여부를 Qt Widgets Designer 에 알립니다. 그렇지 않은 경우, Qt Widgets Designer 는 사용자가 해당 위젯 내부에 위젯을 배치하는 것을 허용하지 않습니다.

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

Qt의 대부분의 위젯은 자식 위젯을 포함할 수 있지만, Qt Widgets Designer 에서는 이 목적을 위해 전용 컨테이너 위젯을 사용하는 것이 합리적입니다. false 를 반환함으로써, 사용자 정의 위젯이 다른 위젯을 포함할 수 없음을 나타냅니다. 만약 true를 반환했다면, Qt Widgets Designer 은 아날로그 시계 내부에 다른 위젯을 배치하고 레이아웃을 정의하는 것을 허용했을 것입니다.

domXml() 함수는 Qt Widgets Designer 에서 사용하는 표준 XML 형식으로 위젯의 기본 설정을 포함할 수 있는 방법을 제공합니다. 이 경우, 위젯의 기하학적 정보만 지정합니다:

QString AnalogClockPlugin::domXml() const
{
    return uR"(
<ui language="c++">
  <widget class="AnalogClock" name="analogClock">
)"
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
R"(
    <property name="toolTip">
      <string>The current time</string>
    </property>
    <property name="whatsThis">
      <string>The analog clock widget displays the current time.</string>
    </property>
  </widget>
</ui>
)"_s;
}

위젯이 적절한 크기 힌트를 제공하는 경우, 여기에서 이를 정의할 필요는 없습니다. 또한, ` <widget> ` 요소 대신 빈 문자열을 반환하면 Qt Widgets Designer 가 해당 위젯을 위젯 상자에 설치하지 않도록 지시합니다.

애플리케이션에서 아날로그 시계 위젯을 사용할 수 있도록 하려면, 사용자 정의 위젯 클래스 정의가 포함된 헤더 파일의 이름을 반환하도록 includeFile() 함수를 구현합니다:

QString AnalogClockPlugin::includeFile() const
{
    return u"analogclock.h"_s;
}

예제 프로젝트 @ code.qt.io