이 페이지에서

QWidgetAction Class

QWidgetAction 클래스는 QAction 을 상속받아, 툴바와 같은 액션 기반 컨테이너에 사용자 정의 위젯을 삽입할 수 있는 인터페이스를 제공합니다. 더 보기...

헤더: #include <QWidgetAction>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
상속: QAction

공개 함수

QWidgetAction(QObject *parent)
virtual ~QWidgetAction()
QWidget *defaultWidget() const
void releaseWidget(QWidget *widget)
QWidget *requestWidget(QWidget *parent)
void setDefaultWidget(QWidget *widget)

보호된 함수

virtual QWidget *createWidget(QWidget *parent)
QList<QWidget *> createdWidgets() const
virtual void deleteWidget(QWidget *widget)

재구현된 보호된 함수

virtual bool event(QEvent *event) override
virtual bool eventFilter(QObject *obj, QEvent *event) override

상세 설명

애플리케이션의 대부분의 동작은 메뉴의 항목이나 툴바의 버튼으로 표현됩니다. 그러나 때로는 더 복잡한 위젯이 필요한 경우도 있습니다. 예를 들어, 워드 프로세서의 확대/축소 동작은 QToolBar 내의 QComboBox 을 사용하여 다양한 확대/축소 수준을 표시함으로써 구현할 수 있습니다. QToolBar 는 단일 위젯을 삽입하기 위한 편의 함수인 QToolBar::insertWidget()을 제공합니다. 그러나 여러 컨테이너에서 시각화를 위해 사용자 정의 위젯을 사용하는 동작을 구현하려면 QWidgetAction의 서브클래스를 만들어야 합니다.

예를 들어, QWidgetAction이 QToolBar 에 추가되면 QWidgetAction::createWidget()이 호출됩니다. 이 함수를 재구현할 때는 지정된 부모를 가진 새로운 사용자 정의 위젯을 생성해야 합니다.

QWidgetAction::deleteWidget액션이 컨테이너 위젯에서 제거되면, 이전에 생성된 사용자 정의 위젯을 인수로 받아 QObject::deleteLater()가 호출됩니다. 기본 구현은 위젯을 숨기고 ()를 사용하여 위젯을 삭제합니다.

사용자 정의 위젯이 단 하나뿐인 경우, ` setDefaultWidget()`를 사용하여 이를 기본 위젯으로 설정할 수 있습니다. 그러면 해당 액션이 ` QToolBar`에 추가되거나, 일반적으로 `QWidgetAction`을 지원하는 액션 컨테이너에 추가될 때 해당 위젯이 사용됩니다. 기본 위젯만 포함된 QWidgetAction이 두 개의 툴바에 동시에 추가된 경우, 해당 기본 위젯은 액션이 처음 추가된 첫 번째 툴바에서만 표시됩니다. QWidgetAction은 기본 위젯에 대한 소유권을 인수합니다.

액션을 활성화하는 것은 위젯의 몫이라는 점에 유의하십시오. 예를 들어, 마우스 이벤트 핸들러를 재구현하고 ` QAction::trigger()`를 호출하는 방식이 있습니다.

macOS: macOS에서 애플리케이션 메뉴 바의 메뉴에 위젯을 추가하면, 위젯이 추가되고 작동하지만 몇 가지 제한 사항이 있습니다:

  1. 위젯은 QMenu 에서 분리되어 네이티브 메뉴 뷰로 부모가 변경됩니다. 메뉴를 다른 위치(예: 팝업 메뉴)에 표시할 경우, 해당 위치에는 위젯이 나타나지 않습니다.
  2. 위젯에 대한 포커스/키보드 처리는 불가능합니다.
  3. Apple의 설계상, 현재 위젯에 대한 마우스 트래킹은 작동하지 않습니다.
  4. triggered() 신호를 모달 대화 상자를 여는 슬롯에 연결하면 macOS 10.4에서 크래시가 발생합니다(Apple이 인정한 알려진 버그). 해결 방법으로는 DirectConnection 대신 QueuedConnection을 사용하는 것입니다.

QAction, QActionGroup 및 QWidget도 참조하십시오 .

멤버 함수 문서

[explicit] QWidgetAction::QWidgetAction(QObject *parent)

parent 를 사용하여 액션을 생성합니다.

[virtual noexcept] QWidgetAction::~QWidgetAction()

객체를 삭제하고 할당된 리소스를 해제합니다.

[virtual protected] QWidget *QWidgetAction::createWidget(QWidget *parent)

이 함수는 사용자 정의 위젯을 지원하는 컨테이너 위젯에 액션이 추가될 때마다 호출됩니다. 지정된 parent 위젯에서 해당 액션을 나타내는 데 사용자 정의 위젯이 사용되지 않도록 하려면 0을 반환해야 합니다.

deleteWidget()도 참조하십시오 .

[protected] QList<QWidget *> QWidgetAction::createdWidgets() const

createWidget()를 사용해 왔으며, 해당 액션이 추가된 위젯에서 현재 사용 중인 위젯 목록을 반환합니다.

QWidget *QWidgetAction::defaultWidget() const

기본 위젯을 반환합니다.

setDefaultWidget()도 참조하십시오 .

[virtual protected] void QWidgetAction::deleteWidget(QWidget *widget)

이 함수는 createWidget()를 통해 미리 생성된 사용자 정의 widget 를 사용하여 액션을 표시하는 컨테이너 위젯에서 해당 액션이 제거될 때마다 호출됩니다. 기본 구현은 widget 를 숨기고, QObject::deleteLater()를 사용하여 해당 를 삭제하도록 예약합니다.

createWidget()도 참조하십시오 .

[override virtual protected] bool QWidgetAction::event(QEvent *event)

QAction::event(QEvent *e)를 재구현합니다.

[override virtual protected] bool QWidgetAction::eventFilter(QObject *obj, QEvent *event)

QObject::eventFilter(QObject *watched, QEvent *event)를 재구현합니다.

void QWidgetAction::releaseWidget(QWidget *widget)

지정된 ‘ widget ’를 해제합니다.

액션을 지원하는 컨테이너 위젯은 위젯 액션이 제거될 때 이 함수를 호출합니다.

requestWidget(), deleteWidget(), defaultWidget()도 참조하십시오 .

QWidget *QWidgetAction::requestWidget(QWidget *parent)

지정된 작업( parent)을 나타내는 위젯을 반환합니다.

액션을 지원하는 컨테이너 위젯은 이 함수를 호출하여 해당 액션을 시각적으로 표현할 위젯을 요청할 수 있습니다.

releaseWidget(), createWidget() 및 defaultWidget()도 참조하십시오 .

void QWidgetAction::setDefaultWidget(QWidget *widget)

widget 를 기본 위젯으로 설정합니다. 소유권은 QWidgetAction 로 이전됩니다. 하위 클래스에서 createWidget()을 재구현하여 새로운 위젯을 반환하지 않는 한, 컨테이너 위젯이 requestWidget()를 통해 위젯을 요청할 때 기본 위젯이 사용됩니다.

defaultWidget()도 참조하십시오 .

© 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.