Como implementar dicas de ferramentas de rastreamento

As dicas de ferramentas de rastreamento permanecem visíveis até que sejam explicitamente fechadas pelo aplicativo e podem mudar de posição na tela dinamicamente. Eles são suportados pela versão 4.70 e posterior dos controles comuns.

Para criar uma dica de ferramenta de controle, inclua o sinalizador TTF_TRACK no membro uFlags da estrutura TOOLINFO ao enviar a mensagem TTM_ADDTOOL.

Seu aplicativo deve ativar manualmente (mostrar) e desativar (ocultar) uma dica de ferramenta de rastreamento enviando uma mensagem TTM_TRACKACTIVATE. Enquanto uma dica de ferramenta de controle estiver ativa, seu aplicativo deve especificar o local da dica de ferramenta enviando mensagens TTM_TRACKPOSITION para o controle de dica de ferramenta. Como o aplicativo lida com tarefas como posicionar a dica de ferramenta, as dicas de ferramentas de controle não usam o sinalizador de TTF_SUBCLASS ou a mensagem TTM_RELAYEVENT.

A mensagem TTM_TRACKPOSITION faz com que o controle de dica de ferramenta exiba a janela usando um dos dois estilos de posicionamento:

• Por padrão, a dica de ferramenta é exibida ao lado da ferramenta correspondente em uma posição escolhida pelo controle. O local escolhido é relativo às coordenadas que você fornece usando essa mensagem.
• Se você incluir o valor TTF_ABSOLUTE no membro da estrutura TOOLINFO, a dica de ferramenta será exibida no local de pixel especificado na mensagem. Nesse caso, o controle não tenta alterar o local da janela de dica de ferramenta a partir das coordenadas fornecidas.

O que você precisa saber

Tecnologias

• Controles do Windows

Pré-requisitos

• C/C++
• Programação da interface do usuário do Windows

Instruções

Implementar dicas de ferramentas in-loco

O membro uFlags da estrutura TOOLINFO usada no exemplo inclui o sinalizador TTF_ABSOLUTE. Sem esse sinalizador, o controle de dica de ferramenta escolhe onde exibir a dica de ferramenta e sua posição em relação à caixa de diálogo pode mudar repentinamente à medida que o ponteiro do mouse se move.

O exemplo a seguir demonstra como criar um controle de dica de ferramenta de controle. O exemplo especifica toda a área do cliente da janela principal como a ferramenta.

HWND CreateTrackingToolTip(int toolID, HWND hDlg, WCHAR* pText)
{
    // Create a tooltip.
    HWND hwndTT = CreateWindowEx(WS_EX_TOPMOST, TOOLTIPS_CLASS, NULL, 
                                 WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP, 
                                 CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, 
                                 hDlg, NULL, g_hInst,NULL);

    if (!hwndTT)
    {
      return NULL;
    }

    // Set up the tool information. In this case, the "tool" is the entire parent window.
    
    g_toolItem.cbSize   = sizeof(TOOLINFO);
    g_toolItem.uFlags   = TTF_IDISHWND | TTF_TRACK | TTF_ABSOLUTE;
    g_toolItem.hwnd     = hDlg;
    g_toolItem.hinst    = g_hInst;
    g_toolItem.lpszText = pText;
    g_toolItem.uId      = (UINT_PTR)hDlg;
    
    GetClientRect (hDlg, &g_toolItem.rect);

    // Associate the tooltip with the tool window.
    
    SendMessage(hwndTT, TTM_ADDTOOL, 0, (LPARAM) (LPTOOLINFO) &g_toolItem); 
    
    return hwndTT;
}
            

Implementação do procedimento de janela

Quando o ponteiro do mouse está dentro da área do cliente, a dica de ferramenta está ativa e exibe as coordenadas do cursor, conforme mostrado na ilustração a seguir.

O código de exemplo a seguir é do procedimento de janela para uma caixa de diálogo que exibe a dica de ferramenta de controle criada no exemplo anterior. A variável booleana global g_TrackingMouse é usada para determinar se é necessário reativar a dica de ferramenta e redefinir o rastreamento do mouse para que o aplicativo seja notificado quando o ponteiro do mouse sair da área do cliente da caixa de diálogo.

//g_hwndTrackingTT is a global HWND variable

case WM_INITDIALOG:

        InitCommonControls();
        g_hwndTrackingTT = CreateTrackingToolTip(IDC_BUTTON1, hDlg, L"");
        return TRUE;

case WM_MOUSELEAVE: // The mouse pointer has left our window. Deactivate the tooltip.
    
    SendMessage(g_hwndTrackingTT, TTM_TRACKACTIVATE, (WPARAM)FALSE, (LPARAM)&g_toolItem);
    g_TrackingMouse = FALSE;
    return FALSE;

case WM_MOUSEMOVE:

    static int oldX, oldY;
    int newX, newY;

    if (!g_TrackingMouse)   // The mouse has just entered the window.
    {                       // Request notification when the mouse leaves.
    
        TRACKMOUSEEVENT tme = { sizeof(TRACKMOUSEEVENT) };
        tme.hwndTrack       = hDlg;
        tme.dwFlags         = TME_LEAVE;
        
        TrackMouseEvent(&tme);

        // Activate the tooltip.
        SendMessage(g_hwndTrackingTT, TTM_TRACKACTIVATE, (WPARAM)TRUE, (LPARAM)&g_toolItem);
        
        g_TrackingMouse = TRUE;
    }

    newX = GET_X_LPARAM(lParam);
    newY = GET_Y_LPARAM(lParam);

    // Make sure the mouse has actually moved. The presence of the tooltip 
    // causes Windows to send the message continuously.
    
    if ((newX != oldX) || (newY != oldY))
    {
        oldX = newX;
        oldY = newY;
            
        // Update the text.
        WCHAR coords[12];
        swprintf_s(coords, ARRAYSIZE(coords), L"%d, %d", newX, newY);
        
        g_toolItem.lpszText = coords;
        SendMessage(g_hwndTrackingTT, TTM_SETTOOLINFO, 0, (LPARAM)&g_toolItem);

        // Position the tooltip. The coordinates are adjusted so that the tooltip does not overlap the mouse pointer.
        
        POINT pt = { newX, newY }; 
        ClientToScreen(hDlg, &pt);
        SendMessage(g_hwndTrackingTT, TTM_TRACKPOSITION, 0, (LPARAM)MAKELONG(pt.x + 10, pt.y - 20));
    }
    return FALSE;

Tópicos relacionados

Usando controles de dica de ferramenta