ToolTip QML Type

为任何控件提供工具提示。更多...

• 所有成员的列表，包括继承的成员

属性

• delay : int
• text : string
• timeout : int

关联属性

• delay : int
• policy : enumeration (since 6.12)
• text : string
• timeout : int
• toolTip : ToolTip
• visible : bool

方法

• void hide() (since QtQuick.Controls 2.5 (Qt 5.12))
• void show(string text, int timeout) (since QtQuick.Controls 2.5 (Qt 5.12))

附带的方法

• void hide()
• void show(string text, int timeout)

详细说明

工具提示是一段简短的文本，用于向用户说明控件的功能。它通常位于父控件的上方或下方。提示文本可以是任何经过富文本格式化的字符串。

附加工具提示

为控件设置工具提示最直接的方法是通过附加属性指定text 和visibility 。以下示例演示了这种方法：

Button {
    text: qsTr("Save")

    ToolTip.visible: down
    ToolTip.text: qsTr("Save the active project")
}

在正常情况下，同一时间仅显示一个工具提示。为了节省资源，所有使用 ToolTip 附加属性的项目将共享同一个视觉工具提示标签实例。 尽管视觉元素是共享的，但text 、timeout 和delay 会针对使用相应附加属性的每个控件分别存储。不过，多个控件无法同时显示该共享工具提示。共享工具提示仅会显示给最后一个使其可见的控件。共享工具提示的位置由框架决定。

延迟和超时

从某种意义上说，工具提示是短暂的，因为它们是作为特定外部事件或用户交互的结果而显示的，并且通常会在超时后隐藏。可以控制工具提示显示时的延迟以及隐藏时的超时时间。这使得能够实现各种显示和隐藏工具提示的策略。

例如，在触摸屏上，长按按钮后显示工具提示是一种常见模式。以下示例演示了如何延迟显示工具提示，直到达到长按时长阈值。在此示例中，工具提示会在按钮松开后立即隐藏。

Button {
    text: qsTr("Button")

    ToolTip.visible: pressed
    ToolTip.delay: Application.styleHints.mousePressAndHoldInterval
    ToolTip.text: qsTr("This tool tip is shown after pressing and holding the button down.")
}

然而，对于指针设备，可能希望在鼠标悬停在按钮上一段时间后显示工具提示。以下示例演示了如何在鼠标悬停在按钮上 1 秒后显示工具提示，并在 5 秒超时后将其隐藏。

Button {
    text: qsTr("Button")
    hoverEnabled: true

    ToolTip.delay: 1000
    ToolTip.timeout: 5000
    ToolTip.visible: hovered
    ToolTip.text: qsTr("This tool tip is shown after hovering the button for a second.")
}

自定义工具提示

如果需要对工具提示的位置进行更精细的控制，或者需要同时显示多个工具提示实例，也可以创建本地工具提示实例。这样，就可以自定义工具提示，并且可以使用完整的Popup API。以下示例展示了一个工具提示，当拖动滑块手柄时，它会显示滑块的数值。

Slider {
    id: slider
    value: 0.5

    ToolTip {
        parent: slider.handle
        visible: slider.pressed
        text: slider.value.toFixed(1)
    }
}

另请参阅 《自定义工具提示》、《弹出控件》和《closePolicy 》。

属性文档

delay : int

该属性指定显示工具提示前的延迟时间（以毫秒为单位）。延迟时间为负数的工具提示将立即显示。默认值为0 。

另请参阅 Delay and Timeout 。

text : string

此属性存储工具提示中显示的文本。

timeout : int

该属性指定工具提示隐藏前的超时时间（以毫秒为单位）。超时时间为负数的工具提示不会自动隐藏。默认值为-1 。

另请参阅 Delay and Timeout 。

附加属性文档

ToolTip.delay : int [attached]

此附加属性用于存储共享工具提示的延迟时间（以毫秒为单位）。该属性可附加到任何项目上。

如果policy 的值为ToolTip.Manual ，则默认值为0 ；否则，默认值为QStyleHints::toolTipWakeUpDelay()。

另请参阅 Attached Tool Tips 和Delay and Timeout 。

ToolTip.policy : enumeration [attached, since 6.12]

此附加属性用于控制shared tool tip instance 的可见性是否由系统自动处理。它仅对未设置 ToolTip.visible 属性的项目生效。只有设置了ToolTip.text 属性的项目才会显示出来。它仅对以下项目及其派生类型生效：Control 、TextArea 和TextField 。所有其他类型都需要手动设置visible 。

它还决定了共享工具提示实例的 delay 和 timeout 属性的默认值（无论是否已设置ToolTip.visible 或ToolTip.text ）。

该属性会传播到已附加的ToolTip 子对象。

可用值：

默认值为ToolTip.Automatic 。

该属性提供了一种方式，用于放弃 Qt 6.12 中引入的共享工具提示的默认值。这对于在与项目交互之前未显式设置 visible 属性的旧代码尤为重要。 对于那些以声明式方式设置 `visible` 属性，且认为延迟和超时的新默认值可接受的应用程序，则无需使用 `policy `。

该属性在 Qt 6.12 中引入。

另请参阅 Attached Tool Tips 。

ToolTip.text : string [attached]

此附加属性存储共享工具提示的文本内容。该属性可附加到任何项目上。

另请参阅 Attached Tool Tips 。

ToolTip.timeout : int [attached]

此附加属性用于存储共享工具提示的超时时间（以毫秒为单位）。该属性可附加到任何项目上。

默认值基于文本长度确定，且始终不少于 10 秒。

另请参阅 Attached Tool Tips 和Delay and Timeout 。

ToolTip.toolTip : ToolTip [attached]

此附加属性保存了共享工具提示实例。该属性可附加到任何项目上。

另请参阅 Attached Tool Tips 。

ToolTip.visible : bool [attached]

此附加属性用于控制共享工具提示是否可见。该属性可附加到任何项目上。

另请参阅 Attached Tool Tips 。

方法文档

[since QtQuick.Controls 2.5 (Qt 5.12)] void hide()

此方法用于隐藏工具提示。

该方法于 QtQuick.Controls 2.5（Qt 5.12）中引入。

[since QtQuick.Controls 2.5 (Qt 5.12)] void show(string text, int timeout)

该方法将text 作为工具提示显示，其超时时间为timeout （毫秒）。

该方法于 QtQuick.Controls 2.5（Qt 5.12）中引入。

附带的方法文档

[attached] void hide()

此附加方法可隐藏共享工具提示。该方法可附加到任何项目上。

另请参阅 Attached Tool Tips 。

[attached] void show(string text, int timeout = -1)

此附加方法展示了带有text 和timeout （毫秒）的共享工具提示。该方法可附加到任何项目上。

另请参阅 Attached Tool Tips 。