En esta página

ToolTip QML Type

Muestra información sobre herramientas para cualquier control. Más...

Import Statement: import QtQuick.Controls
Inherits:

Popup

Propiedades

Propiedades adjuntas

Métodos

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

Métodos adjuntos

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

Descripción detallada

Una información sobre herramientas es un breve texto que informa al usuario sobre la función de un control. Normalmente se sitúa encima o debajo del control principal. El texto de la información sobre herramientas puede ser cualquier cadena con formato de texto enriquecido.

Información sobre herramientas que muestra un texto útil

Informaciones sobre herramientas adjuntas

La forma más sencilla de configurar las descripciones emergentes para los controles es especificar las propiedades asociadas ` text ` y ` visibility `. El siguiente ejemplo ilustra este enfoque:

Button {
    text: qsTr("Save")

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

En circunstancias normales, solo hay una sugerencia visible a la vez. Para ahorrar recursos, todos los elementos que utilizan la propiedad asociada `ToolTip` comparten la misma instancia visual de etiqueta de sugerencia. Aunque los elementos visuales se comparten, text, timeout y delay se almacenan individualmente para cada elemento que utilice la propiedad adjunta correspondiente. Sin embargo, no es posible que varios elementos hagan visible la información sobre herramientas compartida al mismo tiempo. La información sobre herramientas compartida solo se muestra para el último elemento que la haya hecho visible. La posición de la información sobre herramientas compartida la determina el marco de trabajo.

Nota: para personalizar la propiedad ` attached ToolTip`, debe proporcionarse como parte de su propio estilo. Para realizar una personalización puntual de una propiedad ` ToolTip`, consulte Custom Tool Tips.

Retardo y tiempo de espera

Las descripciones emergentes suelen ser transitorias, en el sentido de que se muestran como resultado de un determinado evento externo o de la interacción del usuario, y normalmente se ocultan tras un tiempo de espera determinado. Es posible controlar el retraso con el que se muestra una descripción emergente y el tiempo de espera hasta que se oculta. Esto permite implementar diversas estrategias para mostrar y ocultar descripciones emergentes.

Por ejemplo, en las pantallas táctiles, es habitual mostrar una información sobre herramientas al mantener pulsado un botón. El siguiente ejemplo muestra cómo retrasar la aparición de una información sobre herramientas hasta que se alcance el intervalo de pulsación prolongada. En este ejemplo, la información sobre herramientas se oculta en cuanto se suelta el botón.

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.")
}

Sin embargo, con dispositivos de puntero, puede ser conveniente mostrar una información sobre herramientas al pasar el cursor por encima de un botón durante un tiempo. El siguiente ejemplo muestra cómo mostrar una información sobre herramientas tras pasar el cursor por encima de un botón durante un segundo y ocultarla tras un tiempo de espera de cinco segundos.

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.")
}

Informaciones sobre herramientas personalizadas

Si se necesita un control más preciso sobre la posición de la información sobre herramientas, o si se requieren varias instancias simultáneas de información sobre herramientas, también es posible crear instancias locales de información sobre herramientas. De esta forma, es posible personalizar la información sobre herramientas, y se dispone de toda la API de Popup. El siguiente ejemplo muestra una información sobre herramientas que presenta el valor de un control deslizante cuando se arrastra el controlador.

Texto de ayuda asociado al control deslizante que muestra el valor actual

Slider {
    id: slider
    value: 0.5

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

Véase también Personalización de la información sobre herramientas, controles emergentes y closePolicy.

Documentación de propiedades

delay : int

Esta propiedad establece el retraso (en milisegundos) tras el cual se muestra la información sobre herramientas. Una información sobre herramientas con un retraso negativo se muestra de inmediato. El valor por defecto es 0.

Véase también Delay and Timeout.

text : string

Esta propiedad contiene el texto que aparece en la información sobre herramientas.

timeout : int

Esta propiedad establece el tiempo de espera (en milisegundos) tras el cual se oculta la información sobre herramientas. Una información sobre herramientas con un tiempo de espera negativo no se oculta automáticamente. El valor por defecto es -1.

Véase también Delay and Timeout.

Documentación de la propiedad adjunta

ToolTip.delay : int [attached]

Esta propiedad adjunta contiene el retraso (en milisegundos) de la información sobre herramientas compartida. La propiedad se puede adjuntar a cualquier elemento.

El valor por defecto es 0 si policy es ToolTip.Manual; en caso contrario, es QStyleHints::toolTipWakeUpDelay().

Véase también « Attached Tool Tips » y « Delay and Timeout ».

ToolTip.policy : enumeration [attached, since 6.12]

Esta propiedad adjunta controla si la visibilidad de la información sobre herramientas ( shared tool tip instance ) se gestiona automáticamente. Solo surte efecto en los elementos en los que no se haya establecido « ToolTip.visible ». Solo se mostrarán los elementos que tengan establecido « ToolTip.text ». Solo surte efecto en los siguientes elementos y sus tipos derivados: « Control », « TextArea » y « TextField ». Todos los demás tipos requieren que se establezca manualmente « visible ».

También determina los valores por defecto de las propiedades «delay» y «timeout» de la instancia compartida de la información sobre herramientas (independientemente de si se han establecido « ToolTip.visible » o « ToolTip.text »).

Esta propiedad se propaga a los elementos secundarios de tipo « ToolTip » asociados.

Valores disponibles:

ConstanteDescripción
ToolTip.AutomaticLa información sobre herramientas compartida se mostrará al pasar el cursor por encima del elemento adjunto o al mantenerlo pulsado (si se activa mediante un toque y el elemento adjunto es un ` AbstractButton ` o uno de sus tipos derivados). Si se ha establecido explícitamente la propiedad «visible» o no se ha establecido la propiedad «text», este valor no tendrá ningún efecto y el comportamiento será equivalente al de « ToolTip.Manual ». La información sobre herramientas compartida también adoptará por defecto los valores específicos de la plataforma para sus propiedades «delay» y «timeout».
ToolTip.ManualLa información sobre herramientas compartida no se mostrará automáticamente, y el desarrollador es responsable de establecer la propiedad «visible». La información sobre herramientas compartida no adoptará por defecto valores específicos de la plataforma para sus propiedades «delay» y «timeout».

El valor por defecto es ` ToolTip.Automatic`.

La propiedad permite inhabilitar los valores por defecto de las descripciones emergentes compartidas introducidas en Qt 6.12. Esto resulta especialmente relevante para el código heredado que no establece explícitamente la propiedad «visible» antes de interactuar con un elemento. Para las aplicaciones que establecen de forma declarativa la propiedad «visible» y consideran aceptables los nuevos valores por defecto de «delay» y «timeout», no es necesario utilizar « policy ».

Esta propiedad se introdujo en Qt 6.12.

Véase también Attached Tool Tips.

ToolTip.text : string [attached]

Esta propiedad adjunta contiene el texto de la información sobre herramientas compartida. La propiedad se puede adjuntar a cualquier elemento.

Véase también Attached Tool Tips.

ToolTip.timeout : int [attached]

Esta propiedad adjunta contiene el tiempo de espera (en milisegundos) de la información sobre herramientas compartida. La propiedad se puede adjuntar a cualquier elemento.

El valor por defecto se basa en la longitud del texto y siempre será de al menos 10 segundos.

Véase también Attached Tool Tips y Delay and Timeout.

ToolTip.toolTip : ToolTip [attached]

Esta propiedad adjunta contiene la instancia de la información sobre herramientas compartida. La propiedad se puede adjuntar a cualquier elemento.

Véase también Attached Tool Tips.

ToolTip.visible : bool [attached]

Esta propiedad asociada indica si la descripción emergente compartida está visible. La propiedad se puede asociar a cualquier elemento.

Véase también Attached Tool Tips.

Documentación del método

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

Este método oculta la información sobre herramientas.

Este método se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

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

Este método muestra el « text » como una información sobre herramientas, que desaparece tras un tiempo de espera de timeout (milisegundos).

Este método se introdujo en QtQuick.Controls 2.5 (Qt 5.12).

Documentación adjunta del método

[attached] void hide()

Este método adjunto oculta la información sobre herramientas compartida. El método se puede adjuntar a cualquier elemento.

Véase también Attached Tool Tips.

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

Este método adjunto muestra la información sobre herramientas compartida con text y timeout (milisegundos). El método se puede adjuntar a cualquier elemento.

Véase también Attached Tool Tips.

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