Sobre os controles de dica de ferramenta

As dicas de ferramentas aparecem automaticamente ou aparecem quando o usuário pausa o ponteiro do mouse sobre uma ferramenta ou algum outro elemento da interface do usuário. A dica de ferramenta aparece perto do ponteiro e desaparece quando o usuário clica em um botão do mouse, move o ponteiro para longe da ferramenta ou simplesmente espera por alguns segundos.

O controlo tooltip na ilustração a seguir exibe informações sobre um ficheiro na área de trabalho do Windows. Ao passar o mouse sobre a ilustração, você também verá uma dica de ferramenta ao vivo que contém texto descritivo.

Esta seção descreve como funcionam os controles de tooltip e como criá-los.

• Comportamento e aparência da dica de ferramenta
• Criando controlos de dicas de ferramentas
• Ativando controles de tooltips
• Ferramentas de suporte
• Exibindo Texto
• Mensagens e Notificações
• Teste de Colisão
• Processamento de Mensagens Padrão

Comportamento e Aparência da Tooltip

Os controles de tooltip podem exibir uma única linha de texto ou várias linhas. Seus cantos podem ser arredondados ou quadrados. Eles podem ou não ter uma haste que aponta para as ferramentas como um balão de fala de desenho animado. O texto do tooltip pode estar estacionário ou mover-se com o ponteiro do rato, chamado de seguimento. O texto fixo pode ser exibido ao lado de uma ferramenta ou pode ser exibido sobre uma ferramenta, o que é referido como no local. As dicas de ferramentas padrão são estacionárias, exibem uma única linha de texto, têm cantos quadrados e não têm haste apontando para a ferramenta.

As dicas de ferramentas de rastreamento, que são suportadas na versão 4.70 dos controles comuns, mudam de posição na tela dinamicamente. Ao atualizar rapidamente a posição, esses controles de dica de ferramenta parecem se mover suavemente, ou "rastrear". Eles são úteis quando você deseja que o texto da dica de ferramenta siga a posição do ponteiro do mouse enquanto ele se move. Para obter mais informações sobre dicas de ferramentas de acompanhamento e um exemplo com código que mostra como você as cria, consulte Dicas de ferramentas de rastreamento.

As dicas de ferramentas multilineares, que também são suportadas pela versão 4.70 dos controlos comuns, exibem texto em mais de uma linha. Estes são úteis para exibir mensagens longas. Para obter mais informações e um exemplo que mostra como criar dicas de ferramentas de várias linhas, consulte Dicas de ferramentas de várias linhas.

As dicas de ferramentas de balão são exibidas em uma caixa com cantos arredondados e uma haste apontando para a ferramenta. Podem ser de linha única ou multilinha. A ilustração a seguir mostra uma dica de ferramenta de balão com a haste e o retângulo em suas posições padrão. Para obter mais informações sobre dicas de ferramentas de balão e um exemplo que mostra como criá-las, consulte Usando Controles de Dicas de Ferramenta.

Uma tooltip também pode incluir um texto de título e um ícone, tal como mostrado na ilustração a seguir. Observe que a dica de ferramenta deve ter texto; Se tiver apenas texto de título, a dica de ferramenta não será exibida. Além disso, o ícone não aparece a menos que haja um título.

Às vezes, as cadeias de texto são cortadas porque são muito longas para serem exibidas completamente em uma pequena janela. As dicas de ferramentas no local são usadas para exibir textos para objetos que foram cortados, como o nome do arquivo na ilustração a seguir. Para obter um exemplo que mostra como criar dicas de ferramentas embutidas, consulte In-Place Dicas de ferramentas.

O cursor deve passar o mouse sobre uma ferramenta por um período de tempo antes que a dica de ferramenta seja exibida. A duração padrão desse tempo limite é controlada pelo tempo de clique duplo do usuário e normalmente é de cerca de meio segundo. Para especificar um valor de tempo limite não padrão, envie ao controlo de dica de ferramenta uma mensagem TTM_SETDELAYTIME.

Criando controles de dica de ferramenta

Para criar um controle de dica de ferramenta, chame CreateWindowEx e especifique a classe de janela TOOLTIPS_CLASS. Essa classe é registrada quando a DLL de controle comum é carregada. Para garantir que essa DLL seja carregada, inclua a função InitCommonControlsEx em seu aplicativo. Você deve definir explicitamente um controle de dica de ferramenta como estando no topo. Caso contrário, ele pode ser coberto pela janela pai. O fragmento de código a seguir mostra como se cria um controle de tooltip.

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);

O procedimento de janela para o controle de dica de ferramenta define automaticamente o tamanho, a posição e a visibilidade do controle. A altura da janela de dica de ferramenta é baseada na altura da fonte atualmente selecionada no contexto do dispositivo para o controle de dica de ferramenta. A largura varia com base no comprimento da cadeia de caracteres atualmente na janela de dica de ferramenta.

Ativando controles de dica de ferramenta

Um controle de dica de ferramenta pode estar ativo ou inativo. Quando está ativo, o texto da dica de ferramenta aparece quando o ponteiro do rato está sobre uma ferramenta. Quando está inativo, o texto da dica de ferramenta não aparece, mesmo que o ponteiro esteja em uma ferramenta. A mensagem TTM_ACTIVATE ativa e desativa um controle de dica de ferramenta.

Ferramentas de apoio

Um controle de dica de ferramenta pode suportar qualquer número de ferramentas. Para dar suporte a uma ferramenta específica, você deve registrar a ferramenta com o controle tooltip enviando ao controle a mensagem TTM_ADDTOOL. A mensagem inclui o endereço de uma estrutura TOOLINFO , que fornece as informações necessárias para o controlo de tooltip exibir o texto para a ferramenta. O membro uID da estrutura TOOLINFO é definido pela aplicação. Cada vez que você adiciona uma ferramenta, seu aplicativo fornece um identificador exclusivo. O membro cbSize da estrutura TOOLINFO é necessário e deve especificar o tamanho da estrutura.

Um controlo de dica de ferramenta suporta ferramentas implementadas como janelas (tais como janelas-filhas ou janelas de controlo) e como áreas retangulares dentro da área cliente de uma janela. Quando se adiciona uma ferramenta implementada como uma área retangular, o membro hwnd da estrutura TOOLINFO deve especificar o identificador para a janela que contém a área, e o membro rect deve especificar as coordenadas do cliente do retângulo delimitador da área. Além disso, o membro do uID deve especificar o identificador definido pelo aplicativo para a ferramenta.

Ao adicionar uma ferramenta implementada como uma janela, o membro uID da estruturaTOOLINFO dodeve conter o identificador da janela para a ferramenta. Além disso, o membro do uFlags deve especificar o valor TTF_IDISHWND, que informa ao controle de dica de ferramenta para interpretar o uID membro como um identificador de janela.

Exibindo texto

Quando adiciona uma ferramenta a um controlo de dica de ferramenta, o membro lpszText da estrutura TOOLINFO deve especificar o endereço da cadeia de texto a exibir para a ferramenta. Depois de adicionar uma ferramenta, você pode alterar o texto usando a mensagem TTM_UPDATETIPTEXT.

Se a palavra de ordem alta de lpszText for zero, a palavra de ordem baixa deverá ser o identificador de um recurso de cadeia de caracteres. Quando o controle de dica de ferramenta precisa do texto, o sistema carrega o recurso de cadeia de caracteres especificado da instância do aplicativo identificada pelo membro hinst da estrutura TOOLINFO.

Se você especificar o valor LPSTR_TEXTCALLBACK no membro lpszText da, o controle tooltip notificará a janela especificada no hwnd membro da estrutura TOOLINFOsempre que o controle tooltip precisar exibir texto para a ferramenta. O controle de dica de ferramenta envia o código de notificação TTN_GETDISPINFO para a janela. A mensagem inclui o endereço de um estrutura de NMTTDISPINFO, que contém o identificador de janela, bem como o identificador definido pelo aplicativo para a ferramenta. A janela examina a estrutura para determinar a ferramenta para a qual o texto é necessário e preenche os membros da estrutura apropriados com informações que o controle de tooltip precisa para exibir o texto.

Muitos aplicativos criam barras de ferramentas contendo ferramentas que correspondem a comandos de menu. Para essas ferramentas, é conveniente que o controlo de dica de ferramenta exiba o mesmo texto que o item de menu correspondente. O sistema remove automaticamente os caracteres aceleradores do e comercial (&) de todas as cadeias de caracteres passadas para um controlo de dica de ferramenta e termina a cadeia de caracteres no primeiro tabulador (\t), a menos que o controlo tenha o estilo TTS_NOPREFIX.

Para recuperar o texto de uma ferramenta, use a mensagem TTM_GETTEXT.

Mensagens e notificações

O texto da dica de ferramenta normalmente é exibido quando o ponteiro do mouse passa sobre uma área, normalmente o retângulo definido por uma ferramenta, como um controle de botão. No entanto, o Microsoft Windows só envia mensagens relacionadas ao mouse para a janela que contém o ponteiro, não o controle de dica de ferramenta em si. As informações relacionadas ao mouse devem ser retransmitidas para o controle de dica de ferramenta para que ele exiba o texto da dica de ferramenta no momento e local apropriados.

Você pode ter mensagens retransmitidas automaticamente se:

• A ferramenta é um controle ou é definida como um retângulo na estrutura de TOOLINFO da ferramenta.
• A janela associada à ferramenta está no mesmo thread que o controle tooltip.

Se essas duas condições forem atendidas, defina a bandeira TTF_SUBCLASS no membro uFlags da estrutura TOOLINFO da ferramenta quando adicionar o ferramenta no controlo de dicas com TTM_ADDTOOL. As mensagens necessárias do mouse serão retransmitidas automaticamente para o controle de dica de ferramenta.

Definir TTF_SUBCLASS para que as mensagens do mouse sejam retransmitidas para o controle é suficiente para a maioria das finalidades. No entanto, não funcionará em casos onde não exista uma conexão direta entre o controle de tooltip e a janela da ferramenta. Por exemplo, se uma ferramenta é implementada como uma área retangular em uma janela definida pelo aplicativo, o procedimento da janela recebe as mensagens do mouse. Definir TTF_SUBCLASS é suficiente para garantir que eles sejam passados para o controle. No entanto, se uma ferramenta for implementada como uma janela definida pelo sistema, as mensagens do mouse serão enviadas para essa janela e não estarão diretamente disponíveis para o aplicativo. Nesse caso, você deve subclassificar a janela ou usar um gancho de mensagem para acessar as mensagens do mouse. Em seguida, você deve retransmitir explicitamente mensagens do mouse para o controle de dica de ferramenta com TTM_RELAYEVENT. Para obter um exemplo de como usar TTM_RELAYEVENT, consulte Dicas de ferramentas de rastreamento.

Quando um controle de dica de ferramenta recebe uma mensagem WM_MOUSEMOVE, ele determina se o ponteiro do mouse está no retângulo delimitador de uma ferramenta. Se for, o controlador de dica de ferramenta define um temporizador. No final do intervalo de tempo limite, o controle de dica de ferramenta verifica a posição do ponteiro para ver se ele se moveu. Se não tiver, o controlo de tooltip recupera o texto da ferramenta e exibe o tooltip. O controle de dica de ferramenta continua a mostrar a janela até receber uma mensagem retransmitida de botão para cima ou botão para baixo ou até que uma mensagem de WM_MOUSEMOVE indique que o ponteiro se moveu para fora do retângulo delimitador da ferramenta.

Na verdade, um controle de dica de ferramenta tem três durações de tempo limite associadas a ele. A duração inicial é o tempo que o ponteiro do mouse deve permanecer estacionário na área do retângulo delimitador de uma ferramenta antes que a janela do tooltip seja exibida. A duração da reexibição é o tempo de atraso antes que as janelas de dica de ferramenta subsequentes sejam exibidas quando o ponteiro se move de uma ferramenta para outra. A duração do pop-up é o tempo durante o qual a janela da dica de ferramenta permanece exibida antes de ser oculta. Ou seja, se o ponteiro permanecer estacionário dentro do retângulo delimitador depois que a janela de dica de ferramenta for exibida, a janela de dica de ferramenta será automaticamente ocultada no final da duração do pop-up. Você pode ajustar todas as durações de tempo limite usando a mensagem TTM_SETDELAYTIME.

Se uma aplicação inclui uma ferramenta implementada como uma área retangular e o tamanho ou a posição do controlo muda, a aplicação pode usar a mensagem TTM_NEWTOOLRECT para relatar a alteração ao tooltip. Um aplicativo não precisa relatar alterações de tamanho e posição para uma ferramenta implementada como uma janela porque o controle de dica de ferramenta usa a alça de janela da ferramenta para determinar se o ponteiro do mouse está na ferramenta, não o retângulo delimitador da ferramenta.

Quando uma dica de ferramenta está prestes a ser exibida, o controle de dica de ferramenta envia à janela do proprietário um código de notificação TTN_SHOW. A janela do proprietário recebe um código de notificação TTN_POP quando uma dica de ferramenta está prestes a ser ocultada. Cada código de notificação é enviado no contexto de uma mensagem WM_NOTIFY.

Teste de Colisão

A mensagem TTM_HITTEST permite recuperar informações que um controle de dica de ferramenta mantém sobre a ferramenta que ocupa um ponto específico. A mensagem inclui uma estrutura TTHITTESTINFO que contém um identificador de janela, as coordenadas de um ponto, e o endereço de uma estrutura TOOLINFO . O controlo da dica de ferramenta determina se uma ferramenta ocupa o ponto e, se sim, preenche TOOLINFO com informações sobre a ferramenta.

Processamento de mensagens padrão

A tabela a seguir descreve as mensagens tratadas pelo procedimento de janela para o controlo de tooltip.