QDesignerCustomWidgetInterface Class
QDesignerCustomWidgetInterface 클래스는 Qt Widgets Designer 가 사용자 정의 위젯에 접근하고 이를 생성할 수 있도록 해줍니다. 더 보기...
| 헤더: | #include <QDesignerCustomWidgetInterface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Designer) target_link_libraries(mytarget PRIVATE Qt6::Designer) |
| qmake: | QT += designer |
공개 함수
| virtual | ~QDesignerCustomWidgetInterface() |
| virtual QString | codeTemplate() const |
| virtual QWidget * | createWidget(QWidget *parent) = 0 |
| virtual QString | domXml() const |
| virtual QString | group() const = 0 |
| virtual QIcon | icon() const = 0 |
| virtual QString | includeFile() const = 0 |
| virtual void | initialize(QDesignerFormEditorInterface *formEditor) |
| virtual bool | isContainer() const = 0 |
| virtual bool | isInitialized() const |
| virtual QString | name() const = 0 |
| virtual QString | toolTip() const = 0 |
| virtual QString | whatsThis() const = 0 |
매크로
상세 설명
QDesignerCustomWidgetInterface는 사용자 정의 위젯에 인터페이스를 제공합니다. 이 클래스에는 위젯의 클래스 이름이나 헤더 파일 이름과 같은 기본 정보를 반환하기 위해 서브클래스에서 반드시 구현해야 하는 일련의 함수가 포함되어 있습니다. 그 외의 함수들은 플러그인이 로드될 때 초기화하고, Qt Widgets Designer 에서 사용할 사용자 정의 위젯의 인스턴스를 생성하기 위해 구현되어야 합니다.
사용자 정의 위젯을 구현할 때는 Qt Widgets Designer 에서 해당 위젯을 사용할 수 있도록 QDesignerCustomWidgetInterface를 상속받은 서브클래스를 만들어야 합니다. 예를 들어, 다음은 Qt Widgets Designer 에서 아날로그 시계 사용자 정의 위젯을 사용할 수 있게 해주는 ‘사용자 정의 위젯 플러그인 ( Custom Widget Plugin )’ 예제에서 사용되는 플러그인의 선언입니다:
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;
};이 특정 사용자 정의 위젯에 고유한 클래스 정의 부분은 클래스 이름뿐이라는 점에 유의하십시오. 또한, 인터페이스를 구현하고 있으므로 Q_INTERFACES() 매크로를 사용하여 메타 객체 시스템에 이를 알리도록 해야 합니다. 이를 통해 Qt Widgets Designer 는 QObject 포인터만 사용하여 qobject_cast() 함수를 호출함으로써 지원되는 인터페이스를 조회할 수 있습니다.
Qt Widgets Designer 가 사용자 정의 위젯 플러그인을 로드한 후에는, 해당 인터페이스의 initialize() 함수를 호출하여 필요한 리소스를 설정할 수 있도록 합니다. 이 함수는 QDesignerFormEditorInterface 매개변수와 함께 호출되며, 이 매개변수를 통해 플러그인은 Qt Widgets Designer 의 모든 API에 접근할 수 있습니다.
Qt Widgets Designer 적절한 부모 위젯을 인수로 전달하여 플러그인의 createWidget() 함수를 호출함으로써 사용자 정의 위젯 인스턴스를 생성합니다. 플러그인은 지정된 부모 위젯을 사용하여 사용자 정의 위젯 인스턴스를 생성하고 반환해야 합니다.
Q_PLUGIN_METADATA() 매크로를 사용하여 사용자 정의 위젯 플러그인을 Qt Widgets Designer 로 내보냅니다. 예를 들어, libcustomwidgetplugin.so (유닉스) 또는 libcustomwidget.dll (윈도우)라는 라이브러리에 MyCustomWidget 라는 위젯 클래스가 포함되어 있다면, 플러그인 헤더 파일에 다음 줄을 추가하여 이를 내보낼 수 있습니다:
Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")이 매크로는 Qt Widgets Designer 가 사용자 정의 위젯에 접근하고 생성할 수 있도록 보장합니다. 이 매크로가 없으면 Qt Widgets Designer 에서 이를 사용할 방법이 없습니다.
사용자 정의 위젯 플러그인을 구현할 때는 이를 별도의 라이브러리로 빌드합니다. 동일한 라이브러리에 여러 사용자 정의 위젯 플러그인을 포함하려면, 추가로 ` QDesignerCustomWidgetCollectionInterface`을 서브클래스화해야 합니다.
- QVariant::ByteArray
- QVariant::Bool
- QVariant::Color
- QVariant::Cursor
- QVariant::Date
- QVariant::DateTime
- QVariant::Double
- QVariant::Int
- QVariant::Point
- QVariant::Rect
- QVariant::Size
- QVariant::SizePolicy
- QVariant::String
- QVariant::Time
- QVariant::UInt
QDesignerCustomWidgetInterface 클래스를 사용한 전체 예제는 사용자 정의 위젯 예제를 참조하십시오. 이 예제는 Qt Widgets Designer 용 사용자 정의 위젯 플러그인을 만드는 방법을 보여줍니다.
QDesignerCustomWidgetCollectionInterface 및 Qt Widgets Designer 용 사용자 정의 위젯 만들기도참조하십시오 .
멤버 함수 문서
[virtual constexpr noexcept default] QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface()
사용자 정의 위젯 인터페이스를 제거합니다.
[virtual] QString QDesignerCustomWidgetInterface::codeTemplate() const
이 함수는 Qt Widgets Designer 에서 향후 사용할 목적으로 예약되어 있습니다.
[pure virtual] QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent)
지정된 ` parent`을 가진 사용자 정의 위젯의 새 인스턴스를 반환합니다.
[virtual] QString QDesignerCustomWidgetInterface::domXml() const
Qt Widgets Designer 에 사용자 정의 위젯의 속성을 설명하는 데 사용되는 XML을 반환합니다.
[pure virtual] QString QDesignerCustomWidgetInterface::group() const
사용자 정의 위젯이 속한 그룹의 이름을 반환합니다.
[pure virtual] QIcon QDesignerCustomWidgetInterface::icon() const
Qt Widgets Designer 의 위젯 상자에서 사용자 정의 위젯을 나타내는 데 사용되는 아이콘을 반환합니다.
[pure virtual] QString QDesignerCustomWidgetInterface::includeFile() const
uic가 사용자 정의 위젯용 코드를 생성할 때 사용하는 포함 파일의 경로를 반환합니다.
C++에서 사용되는 사용자 정의 위젯의 경우, Qt for Python, 아래와 같이 접두사를 사용하여 반환된 문자열에 언어별 정보를 지정하십시오:
"C++:myheader.h,Python:MyModule"[virtual] void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor)
지정된 formEditor 인터페이스와 함께 사용할 위젯을 초기화합니다.
isInitialized()도 참조하십시오 .
[pure virtual] bool QDesignerCustomWidgetInterface::isContainer() const
사용자 정의 위젯이 컨테이너로 사용되도록 설계된 경우 true를 반환하고, 그렇지 않은 경우 false를 반환합니다.
대부분의 사용자 정의 위젯은 다른 위젯을 담는 용도로 사용되지 않으므로, 이 함수의 구현은 false를 반환하지만, 사용자 정의 컨테이너는 ` Qt Widgets Designer`에서 올바르게 동작하도록 보장하기 위해 true를 반환합니다.
[virtual] bool QDesignerCustomWidgetInterface::isInitialized() const
위젯이 초기화된 경우 true를 반환하고, 그렇지 않은 경우 false를 반환합니다.
initialize()도 참조하십시오 .
[pure virtual] QString QDesignerCustomWidgetInterface::name() const
인터페이스에서 제공된 사용자 정의 위젯의 클래스 이름을 반환합니다.
반환된 이름은 사용자 정의 위젯에 사용된 클래스 이름과 정확히 일치 해야 합니다.
[pure virtual] QString QDesignerCustomWidgetInterface::toolTip() const
Qt Widgets Designer 에서 툴팁에 사용할 수 있는 위젯에 대한 간략한 설명을 반환합니다.
[pure virtual] QString QDesignerCustomWidgetInterface::whatsThis() const
Qt Widgets Designer 에서 해당 위젯에 대한 “이 기능은 무엇인가요?” 도움말에 사용할 수 있는 위젯 설명을 반환합니다.
매크로 설명서
QDESIGNER_WIDGET_EXPORT
이 매크로는 사용자 정의 위젯을 정의할 때, 해당 위젯이 Qt Widgets Designer 와 함께 사용하기 위해 플러그인에서 올바르게 내보내지도록 보장하기 위해 사용됩니다.
일부 플랫폼에서는 빌드 시스템에 의해 Qt Widgets Designer 가 새 위젯을 생성하는 데 필요한 심볼이 플러그인에서 제거되어 사용할 수 없게 되는 경우가 있습니다. 이 매크로를 사용하면 해당 플랫폼에서 해당 심볼이 유지되도록 보장할 수 있으며, 다른 플랫폼에는 어떠한 부작용도 없습니다.
예를 들어, ‘Custom Widget Plugin’ 예제에서는 다음과 같은 선언을 사용하여 사용자 정의 위젯 클래스를 내보냅니다.
class QDESIGNER_WIDGET_EXPORT AnalogClock : public QWidget
{
Q_OBJECT
...
};© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
