이 페이지에서

QSystemTrayIcon Class

QSystemTrayIcon 클래스는 시스템 트레이에 애플리케이션 아이콘을 표시합니다. 더 보기...

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

공개 유형

enum ActivationReason { Unknown, Context, DoubleClick, Trigger, MiddleClick }
enum MessageIcon { NoIcon, Information, Warning, Critical }

속성

공개 함수

QSystemTrayIcon(QObject *parent = nullptr)
QSystemTrayIcon(const QIcon &icon, QObject *parent = nullptr)
virtual ~QSystemTrayIcon()
QMenu *contextMenu() const
QRect geometry() const
QIcon icon() const
bool isVisible() const
void setContextMenu(QMenu *menu)
void setIcon(const QIcon &icon)
void setToolTip(const QString &tip)
QString toolTip() const

공개 슬롯

void hide()
void setVisible(bool visible)
void show()
void showMessage(const QString &title, const QString &message, QSystemTrayIcon::MessageIcon icon = QSystemTrayIcon::Information, int millisecondsTimeoutHint = 10000)
void showMessage(const QString &title, const QString &message, const QIcon &icon, int millisecondsTimeoutHint = 10000)

신호

void activated(QSystemTrayIcon::ActivationReason reason)
void messageClicked()

정적 공용 멤버

재구현된 보호 함수

virtual bool event(QEvent *e) override

상세 설명

현대 운영 체제는 일반적으로 시스템 트레이 또는 알림 영역이라고 하는 데스크톱의 특수한 영역을 제공하며, 여기에서 장시간 실행되는 애플리케이션이 아이콘과 짧은 메시지를 표시할 수 있습니다.

Windows 10의 시스템 트레이.

QSystemTrayIcon 클래스는 다음 플랫폼에서 사용할 수 있습니다:

사용자의 데스크톱에 시스템 트레이가 있는지 확인하려면 QSystemTrayIcon::isSystemTrayAvailable() 정적 함수를 호출하십시오.

시스템 트레이 항목을 추가하려면 QSystemTrayIcon 객체를 생성하고, setContextMenu()를 호출하여 아이콘에 대한 컨텍스트 메뉴를 제공한 다음, show()를 호출하여 시스템 트레이에 아이콘이 표시되도록 합니다. 상태 알림 메시지("풍선 메시지")는 showMessage()를 사용하여 언제든지 표시할 수 있습니다.

시스템 트레이 아이콘이 생성될 때 시스템 트레이를 사용할 수 없었지만 나중에 사용할 수 있게 되는 경우, 아이콘이 visible 상태라면 QSystemTrayIcon은 시스템 트레이에 해당 애플리케이션에 대한 항목을 자동으로 추가합니다.

activated() 신호는 사용자가 아이콘을 활성화할 때 발생합니다.

X11에서만, 툴팁이 요청되면 QSystemTrayIcon은 QEvent::ToolTip 유형의 QHelpEvent 을 수신합니다. 또한, QSystemTrayIcon은 QEvent::Wheel 유형의 휠 이벤트를 수신합니다. 이러한 이벤트는 다른 플랫폼에서는 지원되지 않습니다. 참고: GNOME Shell 버전 3.26부터, 셸 확장 프로그램이 설치되지 않은 상태에서는 모든 QSystemTrayIcon::ActivationReason 이 시스템에서 지원되지 않습니다.

관련 항목: QDesktopServices, 데스크톱 통합, 시스템 트레이 아이콘 예제.

멤버 유형 문서

enum QSystemTrayIcon::ActivationReason

이 열거형은 시스템 트레이가 활성화된 이유를 설명합니다.

상수값설명
QSystemTrayIcon::Unknown0알 수 없는 이유
QSystemTrayIcon::Context1시스템 트레이 항목에 대한 컨텍스트 메뉴가 요청되었습니다.
QSystemTrayIcon::DoubleClick2시스템 트레이 항목을 더블 클릭했습니다.

참고: macOS에서는 마우스를 클릭하면 컨텍스트 메뉴가 열리기 때문에, 컨텍스트 메뉴가 설정되어 있지 않은 경우에만 더블 클릭 이벤트가 발생합니다.

QSystemTrayIcon::Trigger3시스템 트레이 항목을 클릭했습니다
QSystemTrayIcon::MiddleClick4시스템 트레이 항목을 마우스 가운데 버튼으로 클릭했습니다.

참조: activated().

enum QSystemTrayIcon::MessageIcon

이 열거형은 풍선 메시지가 표시될 때 나타나는 아이콘을 설명합니다.

상수값설명
QSystemTrayIcon::NoIcon0아이콘이 표시되지 않습니다.
QSystemTrayIcon::Information1정보 아이콘이 표시됩니다.
QSystemTrayIcon::Warning2표준 경고 아이콘이 표시됩니다.
QSystemTrayIcon::Critical3중대한 경고 아이콘이 표시됩니다.

QMessageBox도 참조하십시오 .

속성 설명서

icon : QIcon

이 속성은 시스템 트레이 아이콘을 지정합니다.

Windows에서는 시스템 트레이 아이콘 크기가 16x16이며, X11에서는 권장 크기가 22x22입니다. 아이콘은 필요에 따라 적절한 크기로 조정됩니다.

액세스 함수:

QIcon icon() const
void setIcon(const QIcon &icon)

toolTip : QString

이 속성은 시스템 트레이 항목에 대한 툴팁을 저장합니다.

일부 시스템에서는 툴팁의 길이가 제한됩니다. 필요한 경우 툴팁이 잘릴 수 있습니다.

액세스 함수:

QString toolTip() const
void setToolTip(const QString &tip)

visible : bool

이 속성은 시스템 트레이 항목이 표시되는지 여부를 나타냅니다.

이 속성을 true로 설정하거나 ` show()`를 호출하면 시스템 트레이 아이콘이 표시되고, 이 속성을 false로 설정하거나 ` hide()`를 호출하면 아이콘이 숨겨집니다.

액세스 함수:

bool isVisible() const
void setVisible(bool visible)

멤버 함수 설명서

QSystemTrayIcon::QSystemTrayIcon(QObject *parent = nullptr)

지정된 ` parent`를 사용하여 `QSystemTrayIcon` 객체를 생성합니다.

아이콘은 처음에는 보이지 않습니다.

visible도 참조하십시오 .

QSystemTrayIcon::QSystemTrayIcon(const QIcon &icon, QObject *parent = nullptr)

지정된 ` icon ` 및 ` parent`을 사용하여 `QSystemTrayIcon` 객체를 생성합니다.

아이콘은 처음에는 보이지 않습니다.

visible도 참조하십시오 .

[virtual noexcept] QSystemTrayIcon::~QSystemTrayIcon()

시스템 트레이에서 아이콘을 제거하고 할당된 모든 리소스를 해제합니다.

[signal] void QSystemTrayIcon::activated(QSystemTrayIcon::ActivationReason reason)

이 신호는 사용자가 시스템 트레이 아이콘을 활성화할 때 발생합니다. ` reason `는 활성화 사유를 지정합니다. ` QSystemTrayIcon::ActivationReason `는 다양한 활성화 사유를 열거합니다.

QSystemTrayIcon::ActivationReason도 참조하십시오 .

QMenu *QSystemTrayIcon::contextMenu() const

시스템 트레이 항목에 대한 현재 컨텍스트 메뉴를 반환합니다.

setContextMenu()도 참조하십시오 .

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

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

QRect QSystemTrayIcon::geometry() const

시스템 트레이 아이콘의 기하학적 좌표를 화면 좌표계로 반환합니다.

visible도 참조하십시오 .

[slot] void QSystemTrayIcon::hide()

시스템 트레이 항목을 숨깁니다.

show() 및 visible도 참조하십시오 .

[static] bool QSystemTrayIcon::isSystemTrayAvailable()

시스템 트레이를 사용할 수 있는 경우 true 를 반환하고, 그렇지 않은 경우 false 를 반환합니다.

시스템 트레이를 현재 사용할 수 없더라도 나중에 사용할 수 있게 되면, QSystemTrayIcon 는 visible 인 경우 시스템 트레이에 항목을 자동으로 추가합니다.

[signal] void QSystemTrayIcon::messageClicked()

이 신호는 showMessage()를 사용하여 표시된 메시지를 사용자가 클릭했을 때 발생합니다.

참고: Microsoft Windows의 동작 방식을따르므로 , 풍선 메시지가 표시된 트레이 아이콘을 사용자가 클릭할 때도 이 신호가 발생합니다.

activated()항목도 참조하십시오 .

void QSystemTrayIcon::setContextMenu(QMenu *menu)

지정된 ‘ menu ’를 시스템 트레이 아이콘의 컨텍스트 메뉴로 설정합니다.

사용자가 마우스 버튼을 클릭하여 시스템 트레이 아이콘의 컨텍스트 메뉴를 요청하면 해당 메뉴가 표시됩니다.

참고: 시스템 트레이아이콘은 메뉴에 대한 소유권을 가지지 않습니다. 예를 들어, 적절한 상위 객체를 사용하여 메뉴를 생성하는 등의 방법으로, 적절한 시점에 메뉴가 삭제되도록 해야 합니다.

contextMenu()도 참조하십시오 .

[slot] void QSystemTrayIcon::show()

시스템 트레이에 아이콘을 표시합니다.

hide() 및 visible도 참조하십시오 .

[slot] void QSystemTrayIcon::showMessage(const QString &title, const QString &message, QSystemTrayIcon::MessageIcon icon = QSystemTrayIcon::Information, int millisecondsTimeoutHint = 10000)

지정된 title, message 및 icon 값을 가진 항목에 대해, millisecondsTimeoutHint 에 명시된 시간 동안 풍선 메시지를 표시합니다. title 및 message 는 일반 텍스트 문자열이어야 합니다.

사용자가 메시지를 클릭할 수 있으며, 이 경우 messageClicked() 신호가 발생합니다.

메시지 표시는 시스템 구성 및 사용자 기본 설정에 따라 달라지며, 메시지가 전혀 표시되지 않을 수도 있습니다. 따라서 중요한 정보를 전달하는 유일한 수단으로 의존해서는 안 됩니다.

Windows에서 애플리케이션이 포커스를 가지고 있을 때 millisecondsTimeoutHint 은 일반적으로 시스템에 의해 무시됩니다.

Qt 5.2에서 슬롯으로 변경되었습니다.

참고: 이 슬롯은 오버로드되어 있습니다. 이 슬롯에 연결하려면:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        systemTrayIcon, qOverload(&QSystemTrayIcon::showMessage));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        systemTrayIcon, [receiver = systemTrayIcon](const QString &title, const QString &message, QSystemTrayIcon::MessageIcon icon, int millisecondsTimeoutHint) { receiver->showMessage(title, message, icon, millisecondsTimeoutHint); });
더 많은 예제와 접근 방식은 오버로드된 슬롯에 연결하기를 참조하십시오.

show() 및 supportsMessages()도 참조하십시오 .

[slot] void QSystemTrayIcon::showMessage(const QString &title, const QString &message, const QIcon &icon, int millisecondsTimeoutHint = 10000)

지정된 title, message 및 사용자 정의 아이콘 icon 을 가진 항목에 대해, millisecondsTimeoutHint 에 명시된 시간 동안 풍선 메시지를 표시합니다.

참고: 이 슬롯은 오버로드되어 있습니다. 이 슬롯에 연결하려면:

// Connect using qOverload:
connect(sender, &SenderClass::signal,
        systemTrayIcon, qOverload(&QSystemTrayIcon::showMessage));

// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
        systemTrayIcon, [receiver = systemTrayIcon](const QString &title, const QString &message, const QIcon &icon, int millisecondsTimeoutHint) { receiver->showMessage(title, message, icon, millisecondsTimeoutHint); });
더 많은 예제와 방법에 대해서는 오버로드된 슬롯에 연결하기를 참조하십시오.

[static] bool QSystemTrayIcon::supportsMessages()

시스템 트레이가 풍선 메시지를 지원하는 경우 true 를 반환하고, 그렇지 않은 경우 false 를 반환합니다.

showMessage()도 참조하십시오 .

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