다음에 대한 사용자 정의 위젯 만들기 Qt Widgets Designer

Qt Widgets Designer의 플러그인 기반 아키텍처를 사용하면 사용자 정의 및 타사 사용자 정의 위젯을 표준 Qt 위젯과 마찬가지로 편집할 수 있습니다. 위젯 속성, 신호 및 슬롯을 포함한 모든 사용자 정의 위젯의 기능은 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() 함수가 반환하는 문자열에 기본 지오메트리를 지정해야 합니다. 예를 들어, 사용자 정의 위젯 플러그인 예제에서 제공하는 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 에서 제공하는 컨테이너의 하위 클래스가 아니라 현재 페이지 개념을 기반으로 하는 컨테이너에 해당됩니다. 또한 이러한 컨테이너에 대한 컨테이너 확장을 제공해야 합니다.

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

<tooltip> 태그를 사용하여 속성 위에 마우스를 올려놓으면 속성 편집기에 표시되는 도구 설명을 지정할 수 있습니다. 속성 이름은 name 속성에 지정되며 요소 텍스트는 툴팁입니다. 이 기능은 Qt 5.6에 추가되었습니다.

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

문자열 속성의 type 속성 값입니다:

플러그인 요구 사항

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

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

제대로 작동하는 위젯 만들기

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

Qt Widgets Designer 에서 사용자 정의 위젯에 특별한 동작을 부여하려면 초기화() 함수의 구현을 제공하여 Qt Widgets Designer 특정 동작에 대한 위젯 구성 프로세스를 구성하세요. 이 함수는 createWidget() 호출 전에 처음으로 호출되며, 나중에 Qt Widgets Designer 에서 플러그인의 createWidget() 함수를 호출할 때 테스트할 수 있는 내부 플래그를 설정할 수도 있습니다.

플러그인 빌드 및 설치

간단한 플러그인

사용자 정의 위젯 플러그인에서는 간단한 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 변수에는 Qt::UiPlugin 라이브러리에 해당하는 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 와 호환되지 않는 모드로 빌드된 경우 로드 및 설치되지 않습니다. 플러그인에 대한 자세한 내용은 플러그인 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::createWidget()을 다시 구현하여 서브클래싱하는 것입니다.

그러나 Qt Widgets Designer 사용자 정의 위젯 플러그인을 사용할 수도 있습니다( QUiLoader::pluginPaths() 및 관련 함수 참조). 대상 장치에 Qt Widgets Designer 라이브러리를 배포하지 않으려면 해당 플러그인에 Qt Widgets Designer 라이브러리에 대한 링크가 없어야 합니다(QT = uiplugin, Qt Widgets Designer#빌딩및설치 플러그인용 사용자 정의 위젯 만들기 참조).

관련 예제

Qt Widgets Designer 에서 사용자 정의 위젯 사용에 대한 자세한 내용은 사용자 정의 위젯 플러그인 및 작업 메뉴 확장 예제를 참조하고 Qt Widgets Designer 에서 사용자 정의 위젯 사용에 대한 자세한 내용은 을 참조하세요. 또한 QDesignerCustomWidgetCollectionInterface 클래스를 사용하여 여러 사용자 정의 위젯을 하나의 라이브러리로 결합할 수 있습니다.