이 페이지에서

QToolTip Class

QToolTip 클래스는 모든 위젯에 툴팁(풍선 도움말) 기능을 제공합니다. 더 보기...

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

정적 공용 멤버

QFont font()
void hideText()
bool isVisible()
QPalette palette()
void setFont(const QFont &font)
void setPalette(const QPalette &palette)
void showText(const QPoint &pos, const QString &text, QWidget *w = nullptr, const QRect &rect = {}, int msecDisplayTime = -1)
QString text()

상세 설명

팁은 사용자에게 위젯의 기능을 상기시켜 주는 짧은 텍스트입니다. 지정된 위치 바로 아래에 독특한 노란 바탕에 검은색 글씨 조합으로 표시됩니다. 팁은 rich text 형식으로 포맷된 임의의 문자열일 수 있습니다.

<p style='white-space:pre'> 을 사용하여 달리 지정하지 않는 한, 툴팁에 표시되는 서식 있는 텍스트는 암시적으로 줄 바꿈됩니다.

QAction 을 통해 생성된 UI 요소는 QAction 의 tooltip 속성을 사용하므로, 대부분의 대화형 UI 요소의 경우 해당 속성을 설정하는 것이 툴팁을 제공하는 가장 쉬운 방법입니다.

QAction *openAction = new QAction(tr("&Open..."));
openAction->setToolTip(tr("Open an existing file"));

fileMenu = menuBar()->addMenu(tr("&File"));
fileToolBar = addToolBar(tr("&File"));

fileMenu->addAction(openAction);
fileToolBar->addAction(openAction);

다른 위젯의 경우, 위젯의 툴팁을 설정하는 가장 간단하고 일반적인 방법은 QWidget::setToolTip() 함수를 호출하는 것입니다.

searchBar = new SearchBar;
searchBar->setToolTip(tr("Search in the current document"));

또한 ` QEvent::ToolTip` 유형의 ` QHelpEvent `을 사용하여 위젯의 각 영역마다 서로 다른 툴팁을 표시할 수도 있습니다. 위젯의 ` event()` 함수에서 `help` 이벤트를 가로채고, 표시할 텍스트를 인수로 전달하여 ` QToolTip::showText()`를 호출하십시오.

bool Window::event(QEvent *event)
{
    if (event->type() == QEvent::ToolTip) {
        auto *helpEvent = static_cast<QHelpEvent *>(event);
        if (Element *element = elementAt(helpEvent->pos())) {
            QToolTip::showText(helpEvent->globalPos(), element->toolTip(), this);
        } else {
            QToolTip::hideText();
            event->ignore();
        }

        return true;
    }
    return QWidget::event(event);
}

ToolTip-이벤트의 결과로 QToolTip::hideText() 또는 QToolTip::showText()를 빈 문자열로 호출하는 경우, 툴팁 관련 모드를 시작하지 않음을 알리기 위해 해당 이벤트에서 ignore()도 호출해야 합니다.

참고로, 아이템 뷰에서 툴팁을 표시하려는 경우 모델/뷰 아키텍처는 아이템의 툴팁을 설정하는 기능을 제공합니다(예: QTableWidgetItem::setToolTip() 함수). 그러나 아이템 뷰에서 사용자 정의 툴팁을 제공하려면 QAbstractItemView::viewportEvent() 함수 내에서 help 이벤트를 가로채어 직접 처리해야 합니다.

기본 툴팁 색상과 글꼴은 setPalette() 및 setFont()을 사용하여 사용자 정의할 수 있습니다. 툴팁이 현재 표시되어 있을 때, isVisible()은 true 을 반환하고, text()은 현재 표시된 텍스트를 반환합니다.

참고: 툴팁은 활성 창이 아니므로 QPalette 의 비활성 색상 그룹을 사용합니다.

QWidget::toolTip 및 QAction::toolTip도 참조하십시오 .

멤버 함수 문서

[static] QFont QToolTip::font()

툴팁을 표시하는 데 사용되는 글꼴을 반환합니다.

setFont()도 참조하십시오 .

[static] void QToolTip::hideText()

도구 설명창을 숨깁니다. 이는 빈 문자열을 인수로 지정하여 ` showText()`를 호출하는 것과 동일합니다.

showText()도 참조하십시오 .

[static] bool QToolTip::isVisible()

현재 툴팁이 표시되어 있는 경우 true 를 반환합니다.

showText()도 참조하십시오 .

[static] QPalette QToolTip::palette()

툴팁을 표시하는 데 사용되는 팔레트를 반환합니다.

참고: 툴팁은 활성 창이 아니므로 QPalette 의 비활성 색상 그룹을 사용합니다.

setPalette()도 참조하십시오 .

[static] void QToolTip::setFont(const QFont &font)

툴팁을 렌더링하는 데 사용되는 font 를 설정합니다.

font()도 참조하십시오 .

[static] void QToolTip::setPalette(const QPalette &palette)

툴팁을 렌더링하는 데 사용되는 palette 을 설정합니다.

참고: 툴팁은 활성 창이 아니므로, QPalette 의 비활성 색상 그룹을 사용합니다.

palette()도 참조하십시오 .

[static] void QToolTip::showText(const QPoint &pos, const QString &text, QWidget *w = nullptr, const QRect &rect = {}, int msecDisplayTime = -1)

text 를 툴팁으로 표시하며, 전역 위치 pos 를 관심 지점으로 지정합니다. 툴팁은 이 관심 지점을 기준으로 플랫폼별 오프셋을 적용하여 표시됩니다.

비어 있지 않은 사각형을 지정하면, 커서가 이 영역 밖으로 이동하는 즉시 툴팁이 숨겨집니다.

rect 는 w 로 지정한 위젯의 좌표계에 있습니다. rect 가 비어 있지 않은 경우 위젯을 지정해야 합니다. 그렇지 않은 경우 이 인수는 nullptr 일 수 있지만, 멀티헤드 시스템에서 적절한 화면을 결정하는 데 사용됩니다.

msecDisplayTime 매개변수는 툴팁이 표시될 시간을 밀리초 단위로 지정합니다. 기본값인 -1을 사용하면 표시 시간은 텍스트 길이에 따라 결정됩니다.

text 가 비어 있으면 툴팁이 숨겨집니다. 텍스트가 현재 표시된 툴팁과 동일한 경우, 툴팁은 이동하지 않습니다. 먼저 빈 텍스트로 툴팁을 숨긴 다음, 새로운 위치에 새 툴팁을 표시함으로써 강제로 이동시킬 수 있습니다.

[static] QString QToolTip::text()

툴팁이 표시되어 있으면 툴팁 텍스트를 반환하고, 툴팁이 표시되어 있지 않으면 빈 문자열을 반환합니다.

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