Sobre controles de dica de ferramenta

As dicas de ferramentas aparecem automaticamente, ou pop-up, 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 controle de dica de ferramenta na ilustração a seguir exibe informações sobre um arquivo na área de trabalho do Windows. Ao mover 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 os controles de dica de ferramenta funcionam e como você os cria.

• Comportamento e aparência da dica de ferramenta
• Criando controles de dica de ferramenta
• Ativando controles de dica de ferramenta
• Ferramentas de Suporte
• Exibindo texto
• Mensagens e notificações
• Teste de acerto
• Processamento de mensagens padrão

Comportamento e aparência da dica de ferramenta

Os controles de dica de ferramenta 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 da dica de ferramenta pode ser estacionário ou pode ser movido com o ponteiro do mouse, chamado rastreamento. O texto estacionário pode ser exibido ao lado de uma ferramenta ou pode ser exibido sobre uma ferramenta, que é conhecida como in-loco. 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 pela 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 à medida que ele se move. Para obter mais informações sobre dicas de ferramentas de controle e um exemplo com código que mostra como criá-las, consulte Dicas de ferramentas de controle.

Dicas de ferramentas de várias linhas, que também são suportadas pela versão 4.70 dos controles comuns, exibem texto em mais de uma linha. Eles 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. Eles 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 dica de ferramenta.

Uma dica de ferramenta também pode ter texto de título e um ícone, conforme mostrado na ilustração a seguir. Observe que a dica de ferramenta deve ter texto; Se tiver apenas o texto do 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 in-loco são usadas para exibir cadeias de caracteres de texto para objetos que foram recortados, como o nome do arquivo na ilustração a seguir. Para obter um exemplo que mostra como criar dicas de ferramentas in-loco, consulte Dicas de ferramentas in-loco.

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 uma mensagem de TTM_SETDELAYTIME ao controle de dica de ferramenta.

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 topmost. Caso contrário, ele pode ser coberto pela janela pai. O fragmento de código a seguir mostra como criar um controle de dica de ferramenta.

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 ponta 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 mouse está em uma ferramenta. Quando está inativo, o texto da dica de ferramenta não aparece, mesmo se o ponteiro estiver em uma ferramenta. A mensagem TTM_ACTIVATE ativa e desativa um controle de dica de ferramenta.

Ferramentas de Suporte

Um controle de dica de ferramenta pode oferecer suporte a qualquer número de ferramentas. Para oferecer suporte a uma ferramenta específica, você deve registrar a ferramenta com o controle de dica de ferramenta enviando ao controle a mensagem TTM_ADDTOOL. A mensagem inclui o endereço de uma estrutura TOOLINFO , que fornece informações que o controle de dica de ferramenta precisa para exibir texto para a ferramenta. O membro uID da estrutura TOOLINFO é definido pelo aplicativo. 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 controle de dica de ferramenta oferece suporte a ferramentas implementadas como janelas (como janelas filhas ou janelas de controle) e como áreas retangulares dentro da área do cliente de uma janela. Quando você 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 uID deve especificar o identificador definido pelo aplicativo para a ferramenta.

Quando você adiciona uma ferramenta implementada como uma janela, o membro uID da estrutura TOOLINFO deve conter o identificador de janela para a ferramenta. Além disso, o membro uFlags deve especificar o valor TTF_IDISHWND, que informa ao controle de dica de ferramenta para interpretar o membro uID como um identificador de janela.

Exibindo texto

Quando você adiciona uma ferramenta a um controle de dica de ferramenta, o membro lpszText da estrutura TOOLINFO deve especificar o endereço da cadeia de caracteres a ser exibida 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, o controle de dica de ferramenta notificará a janela especificada no membro hwnd da estrutura TOOLINFOsempre que o controle de dica de ferramenta 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 uma estrutura 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 apropriada com informações que o controle de dica de ferramenta precisa para exibir a cadeia de caracteres.

Muitos aplicativos criam barras de ferramentas contendo ferramentas que correspondem a comandos de menu. Para essas ferramentas, é conveniente que o controle de dica de ferramenta exiba o mesmo texto que o item de menu correspondente. O sistema remove automaticamente os caracteres do acelerador e comercial (&) de todas as cadeias de caracteres passadas para um controle de dica de ferramenta e termina a cadeia de caracteres no primeiro caractere de tabulação (\t), a menos que o controle 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 o mouse 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 ao controle da 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 TOOLINFO da ferramenta.
• A janela associada à ferramenta está no mesmo thread que o controle de dica de ferramenta.

Se essas duas condições forem atendidas, defina o sinalizador TTF_SUBCLASS no membro uFlags da estrutura TOOLINFO da ferramenta quando você adicionar a ferramenta ao controle de dica de ferramenta 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, ele não funcionará nos casos em que não houver conexão direta entre o controle de dica de ferramenta e a janela da ferramenta. Por exemplo, se uma ferramenta for implementada como uma área retangular em uma janela definida pelo aplicativo, o procedimento de janela receberá as mensagens do mouse. A definição de TTF_SUBCLASS é suficiente para garantir que elas sejam passadas 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 de WM_MOUSEMOVE, ele determina se o ponteiro do mouse está no retângulo delimitador de uma ferramenta. Se estiver, o controle 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 controle de dica de ferramenta recupera o texto da ferramenta e exibe a dica de ferramenta. 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.

Um controle de dica de ferramenta na verdade 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 dentro do retângulo delimitador de uma ferramenta antes que a janela de dica de ferramenta seja exibida. A duração da reapresentação é o comprimento do 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 que a janela da dica de ferramenta permanece exibida antes de ficar oculta. Ou seja, se o ponteiro permanecer parado dentro do retângulo delimitador depois que a janela da dica de ferramenta for exibida, a janela da dica de ferramenta ficará automaticamente oculta no final da duração do pop-up. Você pode ajustar todas as durações de tempo limite usando a mensagem TTM_SETDELAYTIME.

Se um aplicativo incluir uma ferramenta implementada como uma área retangular e o tamanho ou a posição das alterações de controle, o aplicativo poderá usar a mensagem TTM_NEWTOOLRECT para relatar a alteração ao controle de dica de ferramenta. 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 no 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 .

Testes de clique

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 controle de dica de ferramenta determina se uma ferramenta ocupa o ponto e, se ocupar, preenche TOOLINFO com informações sobre a ferramenta.

Processamento de mensagens padrão

A tabela a seguir descreve as mensagens manipuladas pelo procedimento de janela para o controle de dica de ferramenta.