다음 용도로 사용자 정의 위젯 만들기 Qt Widgets Designer

Qt Widgets Designer의 플러그인 기반 아키텍처 덕분에 사용자 정의 및 타사 커스텀 위젯을 표준 Qt Widgets와 마찬가지로 편집할 수 있습니다. 위젯 속성, 시그널 및 슬롯을 포함하여 사용자 정의 위젯의 모든 기능을 Qt Widgets Designer 에서 사용할 수 있습니다. Qt Widgets Designer 는 양식 디자인 과정에서 실제 위젯을 사용하므로, 사용자 정의 위젯은 미리 보기 시와 동일하게 표시됩니다.

QtDesigner 모듈을 사용하면 Qt Widgets Designer 에서 사용자 정의 위젯을 만들 수 있습니다.

시작하기

Qt Widgets Designer 에 사용자 정의 위젯을 통합하려면, 해당 위젯에 대한 적절한 설명과 적합한 프로젝트 파일이 필요합니다.

인터페이스 설명 제공

Qt Widgets Designer 에 제공하려는 위젯의 유형을 알리려면, 위젯이 노출하는 다양한 속성을 설명하는 ` QDesignerCustomWidgetInterface `의 서브클래스를 생성하십시오. 이러한 속성의 대부분은 기본 클래스에서 순수 가상 함수로 제공되는데, 이는 플러그인 작성자만이 이 정보를 제공할 수 있기 때문입니다.

다음 두 가지 가상 함수도 재구현할 수 있습니다:

domXml() 함수에 대한 참고 사항

domXml() 함수는 Qt Widgets Designer 의 위젯 팩토리가 사용자 정의 위젯과 해당 속성을 생성하는 데 사용하는 UI 파일 스니펫을 반환합니다.

Qt 4.4부터 Qt Widgets Designer 의 위젯 상자에서는 하나의 사용자 정의 위젯을 설명하는 완전한 UI 파일을 사용할 수 있습니다. 이 UI 파일은 <ui> 태그를 사용하여 불러올 수 있습니다. <UI> 태그를 지정하면 사용자 정의 위젯에 대한 추가 정보를 포함하는 <CUSTOMWIDGET> 요소를 추가할 수 있습니다. 추가 정보가 필요하지 않은 경우 <widget> 태그만으로도 충분합니다.

사용자 정의 위젯이 적절한 크기 힌트를 제공하지 않는 경우, 서브클래스의 domXml() 함수가 반환하는 문자열에 기본 기하 구조를 지정해야 합니다. 예를 들어, ‘Custom Widget Plugin’ 예제에서 제공하는 AnalogClockPlugin 는 다음과 같은 방식으로 기본 위젯 기하 구조를 정의합니다:

    ...
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
    ...

domXml() 함수의 또 다른 특징은, 이 함수가 빈 문자열을 반환할 경우 위젯이 Qt Widgets Designer 의 위젯 박스에 설치되지 않는다는 점입니다. 하지만 양식 내의 다른 위젯에서는 여전히 이 위젯을 사용할 수 있습니다. 이 기능은 사용자가 명시적으로 생성해서는 안 되지만 다른 위젯에 필요한 위젯을 숨기는 데 사용됩니다.

완전한 사용자 정의 위젯 사양은 다음과 같습니다:

<ui language="c++"> displayname="MyWidget">
    <widget class="widgets::MyWidget" name="mywidget"/>
    <customwidgets>
        <customwidget>
            <class>widgets::MyWidget</class>
            <addpagemethod>addPage</addpagemethod>
            <propertyspecifications>
                <stringpropertyspecification name="fileName" notr="true" type="singleline"/>
                <stringpropertyspecification name="text" type="richtext"/>
                <tooltip name="text">Explanatory text to be shown in Property Editor</tooltip>
            </propertyspecifications>
        </customwidget>
    </customwidgets>
</ui>

<ui> 태그의 속성:

<addpagemethod> 태그는 Qt Widgets Designer 및 uic에 컨테이너 위젯에 페이지를 추가할 때 어떤 메서드를 사용해야 하는지 알려줍니다. 이는 부모를 전달하여 자식을 추가하는 방식이 아닌, 특정 메서드를 호출하여 자식을 추가해야 하는 컨테이너 위젯에 적용됩니다. 특히, 이는 Qt Widgets Designer 에 제공된 컨테이너의 서브클래스가 아니지만 ‘현재 페이지(Current Page)’ 개념을 기반으로 하는 컨테이너에 해당합니다. 또한, 이러한 컨테이너에 대해서는 별도의 컨테이너 확장 기능을 제공해야 합니다.

<propertyspecifications> 요소에는 속성 메타정보 목록이 포함될 수 있습니다.

<tooltip> 태그는 속성 위에 마우스를 올렸을 때 속성 편집기에 표시될 툴팁을 지정하는 데 사용할 수 있습니다. 속성 이름은 name 속성에 지정되며, 요소의 텍스트가 툴팁이 됩니다. 이 기능은 Qt 5.6에서 추가되었습니다.

문자열(string) 유형의 속성에는 <stringpropertyspecification> 태그를 사용할 수 있습니다. 이 태그에는 다음과 같은 속성이 있습니다:

string 속성의 type 속성 값:

플러그인 요구 사항

플러그인이 모든 플랫폼에서 올바르게 작동하려면, 해당 플러그인이 Qt Widgets Designer 에서 필요로 하는 심볼을 내보내도록 해야 합니다.

우선, Qt Widgets Designer 에서 플러그인을 로드하려면 플러그인 클래스를 내보내야 합니다. 이를 위해 Q_PLUGIN_METADATA() 매크로를 사용하십시오. 또한, Qt Widgets Designer 에서 인스턴스화할 플러그인 내의 각 사용자 정의 위젯 클래스를 정의할 때는 QDESIGNER_WIDGET_EXPORT 매크로를 사용해야 합니다.

올바르게 동작하는 위젯 만들기

일부 사용자 정의 위젯은 Qt Widgets Designer 에 있는 많은 표준 위젯과는 다르게 동작하게 만들 수 있는 특별한 사용자 인터페이스 기능을 가지고 있습니다. 특히, 사용자 정의 위젯이 QWidget::grabKeyboard() 호출의 결과로 키보드를 점유하는 경우, Qt Widgets Designer 의 작동에 영향을 미치게 됩니다.

Qt Widgets Designer 에서 사용자 정의 위젯에 특별한 동작을 부여하려면, Qt Widgets Designer 에 특화된 동작을 위해 위젯 생성 과정을 구성하는 initialize() 함수의 구현을 제공하십시오. 이 함수는 createWidget()이 호출되기 전에 처음 한 번 호출되며, Qt Widgets Designer 가 플러그인의 createWidget() 함수를 호출할 때 나중에 검사할 수 있는 내부 플래그를 설정할 수 있습니다.

플러그인 빌드 및 설치

간단한 플러그인

'Custom Widget' 플러그인은 간단한 Qt Widgets Designer 플러그인의 예시를 보여줍니다.

플러그인의 프로젝트 파일에는 사용자 정의 위젯과 플러그인 인터페이스 모두에 대한 헤더 및 소스 파일을 명시해야 합니다. 일반적으로 이 파일에서는 플러그인 프로젝트가 라이브러리로 빌드되되, Qt Widgets Designer 에 대한 특정 플러그인 지원이 포함되도록 지정하기만 하면 됩니다. CMake 의 경우, 다음 선언을 통해 이를 구현할 수 있습니다:

find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)

qt_add_plugin(customwidgetplugin)
target_sources(customwidgetplugin PRIVATE
    analogclock.cpp analogclock.h
    customwidgetplugin.cpp customwidgetplugin.h
)
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 라이브러리에 동적으로 링크되고, 해당 라이브러리에 대한 런타임 종속성을 갖게 됩니다.

또한 플러그인이 다른 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}"
)

qmake 의 경우:

CONFIG      += plugin
TEMPLATE    = lib
HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

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

또한 이 플러그인이 다른 Qt Widgets Designer 위젯 플러그인들과 함께 설치되어 있는지 확인해야 합니다:

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

$[QT_INSTALL_PLUGINS] 변수는 설치된 Qt 플러그인의 위치를 가리키는 자리 표시자입니다. 애플리케이션을 실행하기 전에 QT_PLUGIN_PATH 환경 변수를 설정하여 Qt Widgets Designer 가 다른 위치에서 플러그인을 찾도록 구성할 수 있습니다.

Qt 애플리케이션에서 라이브러리와 플러그인의 경로를 사용자 정의하는 방법에 대한 자세한 내용은 QCoreApplication::libraryPaths()을 참조하십시오.

플러그인이 Qt Widgets Designer 와 호환되지 않는 모드로 빌드된 경우, 해당 플러그인은 로드되거나 설치되지 않습니다. 플러그인에 대한 자세한 내용은 Plugins HOWTO 문서를 참조하십시오.

플러그인 분할

위에서 설명한 간단한 방식은 특히 Qt Widgets Designer 의 링크가 포함된 다른 인터페이스를 사용할 때 문제를 야기합니다. 사용자 정의 위젯을 사용하는 애플리케이션이 Qt Widgets Designer 헤더와 라이브러리에 의존하게 되기 때문입니다. 실제 상황에서는 이러한 의존성이 바람직하지 않습니다.

다음 섹션에서는 이 문제를 해결하는 방법을 설명합니다.

위젯을 애플리케이션에 링크하기

qmake 를 사용할 때, 포함용 .pri 파일을 생성하여 애플리케이션과 Qt Widgets Designer 간에 사용자 정의 위젯의 소스 파일과 헤더 파일을 공유할 수 있습니다:

INCLUDEPATH += $$PWD
HEADERS += $$PWD/analogclock.h
SOURCES += $$PWD/analogclock.cpp

이 파일은 플러그인과 애플리케이션의 .pro 파일에서 포함됩니다:

include(customwidget.pri)

CMake 를 사용할 때, 위젯의 소스 파일도 마찬가지로 애플리케이션 프로젝트에 추가할 수 있습니다.

라이브러리를 사용하여 위젯 공유하기

또 다른 방법은 위젯을 Qt Widgets Designer 플러그인과 애플리케이션 모두에 링크되는 라이브러리에 포함시키는 것입니다. 런타임 시 라이브러리 위치를 찾는 데 문제가 발생하지 않도록 정적 라이브러리를 사용하는 것이 좋습니다.

공유 라이브러리에 대해서는 ‘공유 라이브러리 생성’을 참조하십시오.

QUiLoader에서 플러그인 사용하기

QUiLoader 에 사용자 정의 위젯을 추가하는 가장 권장되는 방법은 QUiLoader::createWidget() 메서드를 재구현하여 해당 클래스의 서브클래스를 생성하는 것입니다.

그러나 Qt Widgets Designer 사용자 정의 위젯 플러그인을 사용할 수도 있습니다( QUiLoader::pluginPaths() 및 관련 함수 참조). Qt Widgets Designer 라이브러리를 대상 기기에 배포할 필요가 없도록 하려면, 해당 플러그인은 Qt Widgets Designer 라이브러리와 링크되어서는 안 됩니다(QT = uiplugin, Qt Widgets Designer 사용자 정의 위젯 만들기 #플러그인 빌드 및 설치 참조).

관련 예제

Qt Widgets Designer 에서 사용자 정의 위젯을 사용하는 방법에 대한 자세한 내용은 Custom Widget Plugin 예제를, Qt Widgets Designer 에서 사용자 정의 위젯을 사용하는 방법에 대한 자세한 내용은 Task Menu Extension 예제를 참조하십시오. 또한 QDesignerCustomWidgetCollectionInterface 클래스를 사용하여 여러 사용자 정의 위젯을 하나의 라이브러리로 결합할 수 있습니다.