사용자 정의 위젯 플러그인

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

준비

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}"
)

사용자 정의 위젯은 라이브러리로 생성됩니다. 프로젝트가 설치될 때 다른 Qt Widgets Designer 플러그인과 함께 설치됩니다( ninja install 또는 이와 유사한 설치 절차 사용).

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

qmake

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

CONFIG      += plugin
TEMPLATE    = lib

QT          += widgets uiplugin

QT 변수에는 Qt::UiPlugin 라이브러리에 해당하는 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 에서 사용자 정의 위젯으로 수정 없이 사용할 수 있습니다.

아날로그 시계 플러그인 클래스 정의

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 에 의해 초기화되었는지 여부를 기록하는 데 사용됩니다.

클래스 정의에서 이 특정 사용자 정의 위젯에 특정한 부분은 클래스 이름뿐입니다.

아날로그 시계 플러그인 구현

클래스 생성자는 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