이 페이지에서

QMenuBar Class

QMenuBar 클래스는 가로 방향 메뉴 바를 제공합니다. 더 보기...

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

속성

공개 함수

QMenuBar(QWidget *parent = nullptr)
virtual ~QMenuBar()
QAction *actionAt(const QPoint &pt) const
QRect actionGeometry(QAction *act) const
QAction *activeAction() const
QAction *addMenu(QMenu *menu)
QMenu *addMenu(const QString &title)
QMenu *addMenu(const QIcon &icon, const QString &title)
QAction *addSeparator()
void clear()
QWidget *cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const
QAction *insertMenu(QAction *before, QMenu *menu)
QAction *insertSeparator(QAction *before)
bool isDefaultUp() const
bool isNativeMenuBar() const
void setActiveAction(QAction *act)
void setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
void setDefaultUp(bool)
void setNativeMenuBar(bool nativeMenuBar)
NSMenu *toNSMenu()

재구현된 공용 함수

virtual int heightForWidth(int) const override
virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

공개 슬롯

virtual void setVisible(bool visible) override

신호

void hovered(QAction *action)
void triggered(QAction *action)

보호된 함수

virtual void initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const

재구현된 보호 함수

virtual void actionEvent(QActionEvent *e) override
virtual void changeEvent(QEvent *e) override
virtual bool event(QEvent *e) override
virtual bool eventFilter(QObject *object, QEvent *event) override
virtual void focusInEvent(QFocusEvent *) override
virtual void focusOutEvent(QFocusEvent *) override
virtual void keyPressEvent(QKeyEvent *e) override
virtual void leaveEvent(QEvent *) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *e) override
virtual void resizeEvent(QResizeEvent *) override
virtual void timerEvent(QTimerEvent *e) override

상세 설명

메뉴 바는 풀다운 메뉴 항목 목록으로 구성됩니다. ` addMenu()`을 사용하여 메뉴 항목을 추가할 수 있습니다. 예를 들어, ` menubar `가 `QMenuBar`에 대한 포인터이고 ` fileMenu `가 ` QMenu`에 대한 포인터라고 가정할 때, 다음 문장은 메뉴를 메뉴 바에 삽입합니다:

menubar->addMenu(fileMenu);

메뉴 항목 텍스트에 포함된 앰퍼샌드(&)는 이 메뉴의 단축키로 Alt+F를 지정합니다. (메뉴 바에 실제 앰퍼샌드 기호를 표시하려면 "&&"를 사용할 수 있습니다.)

메뉴 바의 레이아웃을 직접 설정할 필요는 없습니다. 메뉴 바는 자동으로 자체 지오메트리를 부모 위젯의 최상단에 배치하며, 부모 위젯의 크기가 조정될 때마다 이에 맞게 지오메트리를 변경합니다.

사용법

대부분의 메인 윈도우 스타일 애플리케이션에서는 QMainWindow 에 제공된 menuBar() 함수를 사용하여, 메뉴 바에는 QMenu를, 팝업 메뉴에는 QAction를 추가하게 됩니다.

예제 ( Menus 예제에서 발췌):

    fileMenu = menuBar()->addMenu(tr("&File"));
    fileMenu->addAction(newAct);

removeAction()을 사용하여 메뉴 항목을 제거할 수 있습니다.

QWidgetAction 클래스의 인스턴스를 사용하여 위젯을 메뉴에 추가할 수 있습니다. 이러한 액션은 일반적인 방식으로 메뉴에 삽입할 수 있습니다. 자세한 내용은 QMenu 문서를 참조하십시오.

플랫폼별 모양과 동작

플랫폼마다 메뉴 바의 외관과 사용자가 메뉴 바와 상호작용할 때의 동작에 대한 요구 사항이 다릅니다. 예를 들어, Windows 시스템은 메뉴 바 항목의 키보드 단축키를 나타내는 밑줄이 그어진 문자가 Alt 키를 누를 때만 표시되도록 설정되는 경우가 많습니다.

글로벌 메뉴 바로서의 QMenuBar

macOS 및 Ubuntu Unity와 같은 특정 Linux 데스크톱 환경에서 QMenuBar는 시스템 전체 메뉴 바를 사용하기 위한 래퍼 역할을 합니다. 하나의 대화 상자에 여러 개의 메뉴 바가 있는 경우, 가장 바깥쪽에 위치한 메뉴 바(일반적으로 Qt::Window 위젯 플래그가 설정된 위젯 내부)가 시스템 전체 메뉴 바로 사용됩니다.

macOS용 Qt는 또한 QMenuBar가 macOS의 표준 메뉴 바 레이아웃에 더 가깝게 맞출 수 있도록 메뉴 바 병합 기능을 제공합니다. 항목이 이동되더라도 해당 슬롯은 마치 원래 위치에 있는 것처럼 계속 호출됩니다.

이 병합 기능은 메뉴 항목의 ` QAction::menuRole()`에 기반합니다. 항목에 ` QAction::TextHeuristicRole`가 설정된 경우, 역할은 다음의 경험적 규칙을 사용하여 제목과 문자열을 일치시켜 결정됩니다:

문자열 일치배치참고
about.*애플리케이션 메뉴 | <애플리케이션 이름> 정보애플리케이션 이름은 Info.plist 파일에서 가져옵니다(아래 참고 사항 참조). 이 항목이 발견되지 않으면 애플리케이션 메뉴에 ‘정보’ 항목이 표시되지 않습니다.
구성, 옵션, 설정 또는 기본 설정애플리케이션 메뉴 | 환경설정이 항목이 발견되지 않으면 ‘설정’ 항목이 비활성화됩니다
종료 또는 나가기응용 프로그램 메뉴 | <응용 프로그램 이름> 종료이 항목이 발견되지 않으면 QCoreApplication::quit()을 호출하는 기본 ‘종료’ 항목이 생성됩니다

QAction::menuRole() 속성을 QAction::NoRole 로 설정하여 이 동작을 재정의할 수 있습니다.

Mac 애플리케이션의 모든 창이 하나의 메뉴 바를 공유하도록 하려면, 부모가 없는 메뉴 바를 생성해야 합니다. 부모가 없는 메뉴 바는 다음과 같이 생성합니다:

QMenuBar *menuBar = new QMenuBar(nullptr);

참고: 공유 메뉴 바를 생성할 때 QMainWindow::menuBar()를 호출하지 마십시오. 해당 메뉴 바는 QMainWindow 를 부모로 갖게 되기 때문입니다. 이 메뉴 바는 부모인 QMainWindow 에 대해서만 표시됩니다.

참고: macOS 메뉴 바에서 애플리케이션 이름으로 사용되는 텍스트는 애플리케이션 번들 내의 Info.plist 파일에 설정된 값에서 가져옵니다. 자세한 내용은 Qt for macOS - 배포를 참조하십시오.

참고: Linux에서 D-Bus 세션 버스에 com.canonical.AppMenu.Registrar 서비스가 사용 가능한 경우, Qt는 앞서 설명한 대로 해당 서비스와 통신하여 애플리케이션의 메뉴를 전역 메뉴 막대에 설치합니다.

예제

Menus 예제는 QMenuBar 및 QMenu 의 사용 방법을 보여줍니다. 다른 메인 윈도우 애플리케이션 예제들도 이러한 클래스를 사용하여 메뉴를 제공합니다.

또한 QMenu, QShortcut, QAction, Apple Human Interface Guidelines 소개 및 메뉴 예제를참조하십시오 .

속성 설명서

defaultUp : bool

이 속성은 팝업의 방향을 지정합니다.

기본 팝업 방향입니다. 기본적으로 메뉴는 화면에서 "아래쪽"으로 나타납니다. 이 속성을 true로 설정하면 메뉴가 "위쪽"으로 나타납니다. 참조하는 문서 아래에 위치한 메뉴의 경우 이 속성을 사용할 수 있습니다.

메뉴가 화면에 다 들어가지 않을 경우, 반대 방향이 자동으로 사용됩니다.

액세스 함수:

bool isDefaultUp() const
void setDefaultUp(bool)

nativeMenuBar : bool

이 속성은 메뉴 막대를 지원하는 플랫폼에서 메뉴 막대를 네이티브 메뉴 막대로 사용할지 여부를 지정합니다.

이 속성은 메뉴바를 지원하는 플랫폼에서 메뉴바를 네이티브 메뉴바로 사용할지 여부를 지정합니다. 현재 지원되는 플랫폼은 macOS와 com.canonical.dbusmenu D-Bus 인터페이스를 사용하는 Linux 데스크톱(예: Ubuntu Unity)입니다. 이 속성이 ` true`인 경우, 메뉴 바는 네이티브 메뉴 바로 사용되며 부모 창의 창 내부에 위치하지 않습니다. ` false `인 경우, 메뉴 바는 창 내에 남아 있습니다. 다른 플랫폼에서는 이 속성을 설정해도 아무런 효과가 없으며, 이 속성을 읽으면 항상 ` false`가 반환됩니다.

기본값은 애플리케이션에 Qt::AA_DontUseNativeMenuBar 속성이 설정되어 있는지 여부에 따릅니다. 이 속성을 명시적으로 설정하면 해당 속성의 유무와 관계없이 이 속성이 우선 적용됩니다.

액세스 함수:

bool isNativeMenuBar() const
void setNativeMenuBar(bool nativeMenuBar)

멤버 함수 문서

[explicit] QMenuBar::QMenuBar(QWidget *parent = nullptr)

parent 를 상위 요소로 하는 메뉴 바를 생성합니다.

[virtual noexcept] QMenuBar::~QMenuBar()

메뉴 막대를 제거합니다.

QAction *QMenuBar::actionAt(const QPoint &pt) const

pt 에 있는 ‘ QAction ’을 반환합니다. pt 에 액션이 없거나 위치에 구분 기호가 포함된 경우 nullptr 을 반환합니다.

QWidget::addAction() 및 addSeparator()도 참조하십시오 .

[override virtual protected] void QMenuBar::actionEvent(QActionEvent *e)

QWidget::actionEvent(QActionEvent *event)를 재구현합니다.

QRect QMenuBar::actionGeometry(QAction *act) const

act 액션의 지오메트리를 QRect 형식으로 반환합니다.

actionAt()도 참조하십시오 .

QAction *QMenuBar::activeAction() const

현재 강조 표시된 QAction 가 있으면 이를 반환하고, 없으면 nullptr 를 반환합니다.

setActiveAction()도 참조하십시오 .

QAction *QMenuBar::addMenu(QMenu *menu)

메뉴 바에 ‘ menu ’를 추가합니다. 메뉴의 menuAction()을 반환합니다. 메뉴 바는 해당 메뉴에 대한 소유권을 가지지 않습니다.

참고: 반환된 QAction 객체를 사용하여 해당 메뉴를 숨길 수 있습니다.

참조: QWidget::addAction() 및 QMenu::menuAction().

QMenu *QMenuBar::addMenu(const QString &title)

title 를 포함한 새로운 ‘ QMenu ’를 메뉴 바에 추가합니다. 메뉴 바가 해당 메뉴의 소유권을 가져갑니다. 새로운 메뉴를 반환합니다.

QWidget::addAction() 및 QMenu::menuAction()도 참조하십시오 .

QMenu *QMenuBar::addMenu(const QIcon &icon, const QString &title)

메뉴 바에 icon 및 title 이 포함된 새로운 ‘ QMenu ’를 추가합니다. 메뉴 바가 해당 메뉴의 소유권을 가져갑니다. 새로운 메뉴를 반환합니다.

QWidget::addAction() 및 QMenu::menuAction()도 참조하십시오 .

QAction *QMenuBar::addSeparator()

메뉴에 구분 기호를 추가합니다.

[override virtual protected] void QMenuBar::changeEvent(QEvent *e)

QWidget::changeEvent(QEvent *event)를 재구현합니다.

void QMenuBar::clear()

메뉴 막대에서 모든 동작을 제거합니다.

참고: macOS에서 시스템 메뉴 막대에 병합된 메뉴 항목은 이 함수로 제거되지 않습니다. 이를 처리하는 한 가지 방법은 불필요한 항목을 직접 제거하는 것입니다. 각 메뉴에 ` menu role ` 속성을 설정하여, 어떤 메뉴 항목이 병합되고 어떤 항목이 병합되지 않는지 미리 파악할 수 있습니다. 그런 다음 어떤 항목을 다시 생성하거나 직접 제거할지 결정하면 됩니다.

removeAction()도 참조하십시오 .

QWidget *QMenuBar::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const

corner 에 따라 첫 번째 메뉴 항목의 왼쪽 또는 마지막 메뉴 항목의 오른쪽에 위치한 위젯을 반환합니다.

참고: ` Qt::TopRightCorner ` 또는 ` Qt::TopLeftCorner ` 이외의 모서리를사용하면 경고가 표시됩니다.

setCornerWidget()도 참조하십시오 .

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

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

[override virtual protected] bool QMenuBar::eventFilter(QObject *object, QEvent *event)

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

[override virtual protected] void QMenuBar::focusInEvent(QFocusEvent *)

QWidget::focusInEvent(QFocusEvent *event)를 재구현합니다.

[override virtual protected] void QMenuBar::focusOutEvent(QFocusEvent *)

QWidget::focusOutEvent(QFocusEvent *event)를 재구현합니다.

[override virtual] int QMenuBar::heightForWidth(int) const

QWidget::heightForWidth(int w) const를 재구현합니다.

[signal] void QMenuBar::hovered(QAction *action)

이 신호는 메뉴 작업이 강조 표시될 때 발생하며, ` action `는 이벤트가 전송되도록 한 작업을 나타냅니다.

대개 이 신호는 상태 정보를 업데이트하는 데 사용됩니다.

triggered() 및 QAction::hovered()도 참조하십시오 .

[virtual protected] void QMenuBar::initStyleOption(QStyleOptionMenuItem *option, const QAction *action) const

메뉴 바의 값과 action 에 있는 정보를 사용하여 option 를 초기화합니다. 이 방법은 하위 클래스에서 QStyleOptionMenuItem 가 필요하지만, 모든 정보를 직접 입력하고 싶지 않을 때 유용합니다.

QStyleOption::initFrom() 및 QMenu::initStyleOption()도 참조하십시오 .

QAction *QMenuBar::insertMenu(QAction *before, QMenu *menu)

이 편의 함수는 before 액션 앞에 menu 를 삽입하고, menuAction()을 반환합니다.

QWidget::insertAction() 및 addMenu()도 참조하십시오 .

QAction *QMenuBar::insertSeparator(QAction *before)

이 편의 함수는 새로운 분리자 동작, 즉 ` QAction::isSeparator()`가 true를 반환하는 동작을 생성합니다. 이 함수는 새로 생성된 동작을 이 메뉴 바의 동작 목록에서 ` before ` 동작 바로 앞에 삽입한 후, 해당 목록을 반환합니다.

QWidget::insertAction() 및 addSeparator()도 참조하십시오 .

[override virtual protected] void QMenuBar::keyPressEvent(QKeyEvent *e)

QWidget::keyPressEvent(QKeyEvent *event)를 재구현합니다.

[override virtual protected] void QMenuBar::leaveEvent(QEvent *)

QWidget::leaveEvent(QEvent *event)를 재구현합니다.

[override virtual] QSize QMenuBar::minimumSizeHint() const

QWidget::minimumSizeHint 속성에 대한 액세스 함수를 재구현합니다.

[override virtual protected] void QMenuBar::mouseMoveEvent(QMouseEvent *e)

QWidget::mouseMoveEvent(QMouseEvent *event)를 재구현합니다.

[override virtual protected] void QMenuBar::mousePressEvent(QMouseEvent *e)

QWidget::mousePressEvent(QMouseEvent *event)를 재구현합니다.

[override virtual protected] void QMenuBar::mouseReleaseEvent(QMouseEvent *e)

QWidget::mouseReleaseEvent(QMouseEvent *event)를 재구현합니다.

[override virtual protected] void QMenuBar::paintEvent(QPaintEvent *e)

QWidget::paintEvent(QPaintEvent *event)를 재구현합니다.

[override virtual protected] void QMenuBar::resizeEvent(QResizeEvent *)

QWidget::resizeEvent(QResizeEvent *event)를 재구현합니다.

void QMenuBar::setActiveAction(QAction *act)

현재 선택된 동작을 ‘ act ’로 설정합니다.

activeAction()도 참조하십시오 .

void QMenuBar::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)

이 설정은 지정된 ‘ widget ’을 ‘ corner ’에 따라 첫 번째 메뉴 항목의 바로 왼쪽이나 마지막 메뉴 항목의 오른쪽에 표시되도록 합니다.

메뉴 바는 ` widget`에 대한 소유권을 가져와 이를 메뉴 바로 다시 부모 지정합니다. 그러나 ` corner `에 이미 위젯이 포함되어 있는 경우, 이 기존 위젯은 더 이상 관리되지 않으며 여전히 메뉴 바의 보이는 자식 요소로 남아 있습니다.

참고: ` Qt::TopRightCorner ` 또는 ` Qt::TopLeftCorner ` 이외의 모서리를사용하면 경고가 발생합니다.

참조: cornerWidget().

[override virtual slot] void QMenuBar::setVisible(bool visible)

QWidget::visible 속성에 대한 액세스 함수를 재구현합니다.

[override virtual] QSize QMenuBar::sizeHint() const

QWidget::sizeHint 속성에 대한 액세스 함수를 재구현합니다.

[override virtual protected] void QMenuBar::timerEvent(QTimerEvent *e)

QObject::timerEvent(QTimerEvent *event)를 재구현합니다.

NSMenu *QMenuBar::toNSMenu()

이 메뉴 바에 대한 네이티브 NSMenu를 반환합니다. macOS에서만 사용할 수 있습니다.

참고: Qt는 네이티브 메뉴 바에 델리게이트를 설정할 수 있습니다. 사용자 정의 델리게이트를 설정해야 하는 경우, 원래의 델리게이트를 저장하고 해당 델리게이트로 전달되는 모든 호출을 전달해야 합니다.

[signal] void QMenuBar::triggered(QAction *action)

이 신호는 마우스 클릭으로 인해 이 메뉴바에 속한 메뉴의 액션이 실행될 때 발생하며, ` action `는 이 신호의 발생 원인이 된 액션입니다.

참고: 이 신호가 정상적으로 작동하려면` QMenuBar `가 ` QMenu `의 소유권을 가져야 합니다.

일반적으로 QAction::triggered()를 사용하여 각 메뉴 액션을 단일 슬롯에 연결하지만, 때로는 여러 항목을 단일 슬롯에 연결하고 싶을 때가 있습니다(대부분 사용자가 배열에서 선택할 때). 이 신호는 이러한 경우에 유용합니다.

hovered() 및 QAction::triggered()도 참조하십시오 .

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