Acerca de los controles de información sobre herramientas

La información sobre herramientas aparece automáticamente o aparece cuando el usuario pausa el puntero del mouse sobre una herramienta o algún otro elemento de la interfaz de usuario. La información sobre herramientas aparece cerca del puntero y desaparece cuando el usuario hace clic en un botón del mouse, mueve el puntero lejos de la herramienta o simplemente espera unos segundos.

El control de información sobre herramientas de la ilustración siguiente muestra información sobre un archivo en el escritorio de Windows. A medida que mueve el mouse sobre la ilustración, también debería ver una información sobre herramientas en directo que contiene texto descriptivo.

En esta sección se describe cómo funcionan los controles de información sobre herramientas y cómo se crean.

• Comportamiento y apariencia de la información sobre herramientas
• Crear controles de información sobre herramientas
• Activación de controles de información sobre herramientas
• Herramientas auxiliares
• Mostrar texto
• Mensajería y notificación
• Pruebas de posicionamiento
• Procesamiento de mensajes predeterminado

Comportamiento y apariencia de la información sobre herramientas

Los controles de información sobre herramientas pueden mostrar una sola línea de texto o varias líneas. Sus esquinas se pueden redondear o cuadrados. Podrían tener o no un tallo que apunte a las herramientas como un globo de voz de dibujos animados. El texto de información sobre herramientas puede ser estático o puede moverse con el puntero del mouse, denominado seguimiento. El texto estacionario se puede mostrar junto a una herramienta o se puede mostrar sobre una herramienta, lo que se conoce como en contexto. Las informaciones sobre herramientas estándar son fijas, muestran una sola línea de texto, tienen esquinas cuadradas y no tienen ningún tallo que apunte a la herramienta.

La información sobre herramientas de seguimiento, compatible con la versión 4.70 de los controles comunes, cambia la posición en la pantalla dinámicamente. Al actualizar rápidamente la posición, estos controles de información sobre herramientas parecen moverse sin problemas o "seguimiento". Son útiles cuando desea que el texto de información sobre herramientas siga la posición del puntero del mouse a medida que se mueve. Para obtener más información sobre la información sobre herramientas de seguimiento y un ejemplo con código que muestra cómo crearlos, consulte Información sobre herramientas de seguimiento.

La información sobre herramientas de varias líneas, que también es compatible con la versión 4.70 de los controles comunes, muestra texto en más de una línea. Son útiles para mostrar mensajes largos. Para obtener más información y un ejemplo que muestra cómo crear información sobre herramientas de varias líneas, consulte Información sobre herramientas de varias líneas.

La información sobre herramientas de globo se muestra en un cuadro con esquinas redondeadas y un tallo que apunta a la herramienta. Pueden ser de una sola línea o de varias líneas. En la ilustración siguiente se muestra una información sobre herramientas de globo con el tallo y el rectángulo en sus posiciones predeterminadas. Para obtener más información sobre la información sobre herramientas de globo y un ejemplo que muestra cómo crearlos, consulte Uso de controles de información sobre herramientas.

Una información sobre herramientas también puede tener texto de título y un icono, como se muestra en la ilustración siguiente. Tenga en cuenta que la información sobre herramientas debe tener texto; si solo tiene texto de título, la información sobre herramientas no se muestra. Además, el icono no aparece a menos que haya un título.

A veces, las cadenas de texto se recortan porque son demasiado largas para mostrarse completamente en una ventana pequeña. La información sobre herramientas en contexto se usa para mostrar cadenas de texto para objetos que se han recortado, como el nombre de archivo en la ilustración siguiente. Para obtener un ejemplo que muestra cómo crear información sobre herramientas en contexto, consulte Información sobre herramientas en contexto.

El cursor debe mantener el puntero sobre una herramienta durante un período de tiempo antes de que se muestre la información sobre herramientas. La duración predeterminada de este tiempo de espera se controla mediante el tiempo de doble clic del usuario y normalmente es aproximadamente de medio segundo. Para especificar un valor de tiempo de espera no predeterminado, envíe el control de información sobre herramientas a un mensaje de TTM_SETDELAYTIME .

Crear controles de información sobre herramientas

Para crear un control de información sobre herramientas, llame a CreateWindowEx y especifique la clase de ventana TOOLTIPS_CLASS . Esta clase se registra cuando se carga el archivo DLL de control común. Para asegurarse de que se carga este archivo DLL, incluya la función InitCommonControlsEx en la aplicación. Debe definir explícitamente un control de información sobre herramientas como más arriba. De lo contrario, podría estar cubierto por la ventana primaria. En el fragmento de código siguiente se muestra cómo crear un control de información sobre herramientas.

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

El procedimiento de ventana del control de información sobre herramientas establece automáticamente el tamaño, la posición y la visibilidad del control. El alto de la ventana de información sobre herramientas se basa en el alto de la fuente seleccionada actualmente en el contexto del dispositivo para el control de información sobre herramientas. El ancho varía en función de la longitud de la cadena actualmente en la ventana de información sobre herramientas.

Activación de controles de información sobre herramientas

Un control de información sobre herramientas puede estar activo o inactivo. Cuando está activo, el texto de información sobre herramientas aparece cuando el puntero del mouse está en una herramienta. Cuando está inactivo, el texto de la información sobre herramientas no aparece, incluso si el puntero está en una herramienta. El mensaje TTM_ACTIVATE activa y desactiva un control de información sobre herramientas.

Herramientas auxiliares

Un control de información sobre herramientas puede admitir cualquier número de herramientas. Para admitir una herramienta determinada, debe registrar la herramienta con el control de información sobre herramientas enviando el control el mensaje TTM_ADDTOOL . El mensaje incluye la dirección de una estructura TOOLINFO , que proporciona información que el control de información sobre herramientas debe mostrar texto para la herramienta. La aplicación define el miembro uID de la estructura TOOLINFO . Cada vez que agrega una herramienta, la aplicación proporciona un identificador único. Se requiere el miembro cbSize de la estructura TOOLINFO y debe especificar el tamaño de la estructura.

Un control de información sobre herramientas admite herramientas implementadas como ventanas (como ventanas secundarias o ventanas de control) y como áreas rectangulares dentro del área cliente de una ventana. Al agregar una herramienta implementada como un área rectangular, el miembro hwnd de la estructura TOOLINFO debe especificar el identificador para la ventana que contiene el área y el miembro rect debe especificar las coordenadas de cliente del rectángulo delimitador del área. Además, el miembro uID debe especificar el identificador definido por la aplicación para la herramienta.

Al agregar una herramienta implementada como una ventana, el miembro uID de la estructura TOOLINFO debe contener el identificador de ventana para la herramienta. Además, el miembro uFlags debe especificar el valor de TTF_IDISHWND , que indica al control de información sobre herramientas que interprete el miembro uID como identificador de ventana.

Mostrar texto

Al agregar una herramienta a un control de información sobre herramientas, el miembro lpszText de la estructura TOOLINFO debe especificar la dirección de la cadena que se va a mostrar para la herramienta. Después de agregar una herramienta, puede cambiar el texto mediante el mensaje TTM_UPDATETIPTEXT .

Si la palabra de orden alto de lpszText es cero, la palabra de orden bajo debe ser el identificador de un recurso de cadena. Cuando el control de información sobre herramientas necesita el texto, el sistema carga el recurso de cadena especificado desde la instancia de aplicación identificada por el miembro trasero de la estructura TOOLINFO .

Si especifica el valor de LPSTR_TEXTCALLBACK en el miembro lpszText , el control de información sobre herramientas notifica a la ventana especificada en el miembro hwnd de la estructura TOOLINFOsiempre que el control de información sobre herramientas necesite mostrar texto para la herramienta. El control de información sobre herramientas envía el código de notificación TTN_GETDISPINFO a la ventana. El mensaje incluye la dirección de una estructura NMTTDISPINFO , que contiene el identificador de ventana, así como el identificador definido por la aplicación para la herramienta. La ventana examina la estructura para determinar la herramienta para la que se necesita texto y rellena los miembros de estructura adecuados con información que necesita el control de información sobre herramientas para mostrar la cadena.

Nota

La longitud máxima del texto de información sobre herramientas estándar es de 80 caracteres. Para obtener más información, vea la estructura NMTTDISPINFO . El texto de información sobre herramientas de varias líneas puede ser más largo.

 

Muchas aplicaciones crean barras de herramientas que contienen herramientas que corresponden a comandos de menú. Para estas herramientas, es conveniente que el control de información sobre herramientas muestre el mismo texto que el elemento de menú correspondiente. El sistema quita automáticamente los caracteres de acelerador de la y comercial (&) de todas las cadenas que se pasan a un control de información sobre herramientas y finaliza la cadena en el primer carácter de tabulación (\t), a menos que el control tenga el estilo TTS_NOPREFIX .

Para recuperar el texto de una herramienta, use el mensaje TTM_GETTEXT .

Mensajería y notificación

Normalmente, el texto de información sobre herramientas se muestra cuando el puntero del mouse mantiene el puntero sobre un área, normalmente el rectángulo definido por una herramienta como un control de botón. Sin embargo, Microsoft Windows solo envía mensajes relacionados con el mouse a la ventana que contiene el puntero, no al propio control de información sobre herramientas. La información relacionada con el mouse se debe retransmitir al control de información sobre herramientas para que muestre el texto de la información sobre herramientas en el momento y lugar adecuados.

Puede hacer que los mensajes se retransmitan automáticamente si:

• La herramienta es un control o se define como un rectángulo en la estructura TOOLINFO de la herramienta.
• La ventana asociada a la herramienta está en el mismo subproceso que el control de información sobre herramientas.

Si se cumplen estas dos condiciones, establezca la marca TTF_SUBCLASS en el miembro uFlags de la estructura TOOLINFO de la herramienta al agregar la herramienta al control de información sobre herramientas con TTM_ADDTOOL. Los mensajes del mouse necesarios se retransmitirán automáticamente al control de información sobre herramientas.

Establecer TTF_SUBCLASS para que los mensajes del mouse se retransmitan al control son suficientes para la mayoría de los propósitos. Sin embargo, no funcionará en los casos en los que no haya ninguna conexión directa entre el control de información sobre herramientas y la ventana de la herramienta. Por ejemplo, si una herramienta se implementa como un área rectangular en una ventana definida por la aplicación, el procedimiento de ventana recibe los mensajes del mouse. Establecer TTF_SUBCLASS es suficiente para asegurarse de que se pasan al control. Sin embargo, si una herramienta se implementa como una ventana definida por el sistema, los mensajes del mouse se envían a esa ventana y no están directamente disponibles para la aplicación. En este caso, debe subclase la ventana o usar un enlace de mensajes para acceder a los mensajes del mouse. A continuación, debe retransmitir explícitamente los mensajes del mouse al control de información sobre herramientas con TTM_RELAYEVENT. Para obtener un ejemplo de cómo usar TTM_RELAYEVENT, vea Información sobre herramientas de seguimiento.

Cuando un control de información sobre herramientas recibe un mensaje de WM_MOUSEMOVE , determina si el puntero del mouse está en el rectángulo delimitador de una herramienta. Si es así, el control de información sobre herramientas establece un temporizador. Al final del intervalo de tiempo de espera, el control de información sobre herramientas comprueba la posición del puntero para ver si se ha movido. Si no lo tiene, el control de información sobre herramientas recupera el texto de la herramienta y muestra la información sobre herramientas. El control de información sobre herramientas continúa mostrando la ventana hasta que recibe un mensaje de botón o botón hacia arriba o hacia abajo retransmitido o hasta que un mensaje de WM_MOUSEMOVE indica que el puntero se ha movido fuera del rectángulo delimitador de la herramienta.

Un control de información sobre herramientas tiene realmente tres duraciones de tiempo de espera asociadas. La duración inicial es el tiempo que el puntero del mouse debe permanecer estático dentro del rectángulo delimitador de una herramienta antes de que se muestre la ventana de información sobre herramientas. La duración de la repetición es la longitud del retraso antes de que se muestren las ventanas de información sobre herramientas posteriores cuando el puntero se mueve de una herramienta a otra. La duración emergente es el tiempo que permanece la ventana de información sobre herramientas antes de que se oculte. Es decir, si el puntero permanece estacionario dentro del rectángulo delimitador después de que se muestre la ventana de información sobre herramientas, la ventana de información sobre herramientas se oculta automáticamente al final de la duración emergente. Puede ajustar todas las duraciones de tiempo de espera mediante el mensaje TTM_SETDELAYTIME .

Si una aplicación incluye una herramienta implementada como un área rectangular y el tamaño o la posición del control cambia, la aplicación puede usar el mensaje TTM_NEWTOOLRECT para notificar el cambio al control de información sobre herramientas. Una aplicación no necesita notificar los cambios de tamaño y posición de una herramienta implementada como una ventana porque el control de información sobre herramientas usa el identificador de ventana de la herramienta para determinar si el puntero del mouse está en la herramienta, no en el rectángulo delimitador de la herramienta.

Cuando se va a mostrar una información sobre herramientas, el control de información sobre herramientas envía a la ventana del propietario un código de notificación TTN_SHOW . La ventana del propietario recibe un código de notificación TTN_POP cuando una información sobre herramientas está a punto de ocultarse. Cada código de notificación se envía en el contexto de un mensaje de WM_NOTIFY .

Pruebas de posicionamiento

El mensaje TTM_HITTEST permite recuperar información que mantiene un control de información sobre herramientas sobre la herramienta que ocupa un punto determinado. El mensaje incluye una estructura TTHITTESTINFO que contiene un identificador de ventana, las coordenadas de un punto y la dirección de una estructura TOOLINFO . El control de información sobre herramientas determina si una herramienta ocupa el punto y, si es así, rellena TOOLINFO con información sobre la herramienta.

Procesamiento de mensajes predeterminado

En la tabla siguiente se describen los mensajes que controla el procedimiento de ventana para el control de información sobre herramientas.

Message	Descripción
WM_CREATE	Garantiza que el control de información sobre herramientas tenga los estilos de ventana WS_EX_TOOLWINDOW y WS_POPUP . También asigna memoria e inicializa variables internas.
WM_DESTROY	Libera los recursos asignados para el control de información sobre herramientas.
WM_GETFONT	Devuelve el identificador de la fuente que usará el control de información sobre herramientas para dibujar texto.
WM_MOUSEMOVE	Oculta la ventana de información sobre herramientas.
WM_PAINT	Dibuja la ventana de información sobre herramientas.
WM_SETFONT	Establece el identificador de la fuente que usará el control de información sobre herramientas para dibujar texto.
WM_TIMER	Oculta la ventana de información sobre herramientas si la herramienta ha cambiado de posición o si el puntero del mouse se ha movido fuera de la herramienta. De lo contrario, muestra la ventana de información sobre herramientas.
WM_WININICHANGE	Restablece las variables internas que se basan en las métricas del sistema.