Usando barras de ferramentas da Área de Trabalho do Aplicativo

Uma barra de ferramentas da área de trabalho do aplicativo (também chamada de barra de aplicativos) é uma janela semelhante à barra de tarefas Windows. Ele é ancorado em uma borda da tela e normalmente contém botões que dão ao usuário acesso rápido a outros aplicativos e janelas. O sistema impede que outros aplicativos usem a área de trabalho usada por uma barra de aplicativos. Qualquer número de barras de aplicativo pode existir na área de trabalho a qualquer momento.

Este tópico inclui as seções a seguir.

Sobre as barras de ferramentas da Área de Trabalho do Aplicativo

Windows fornece uma API que permite que você aproveite os serviços da barra de aplicativos fornecidos pelo sistema. Os serviços ajudam a garantir que as barras de aplicativos definidas pelo aplicativo operem sem problemas entre si e com a barra de tarefas. O sistema mantém informações sobre cada barra de aplicativos e envia as mensagens de barras de aplicativo para notificá-las sobre eventos que podem afetar seu tamanho, posição e aparência.

enviando mensagens

Um aplicativo usa um conjunto especial de mensagens, chamado de mensagens da barra de aplicativos, para adicionar ou remover uma barra de aplicativos, definir o tamanho e a posição de uma barra de aplicativos e recuperar informações sobre o tamanho, a posição e o estado da barra de tarefas. Para enviar uma mensagem da barra de aplicativos, um aplicativo deve usar a função SHAppBarMessage . Os parâmetros da função incluem um identificador de mensagem, como ABM_NEW, e o endereço de uma estrutura APPBARDATA . Os membros da estrutura contêm informações de que o sistema precisa processar a mensagem fornecida.

Para qualquer mensagem da barra de aplicativos, o sistema usa alguns membros da estrutura APPBARDATA e ignora os outros. No entanto, o sistema sempre usa os membros cbSize e hWnd , portanto, um aplicativo deve preencher esses membros para cada mensagem da barra de aplicativos. O membro cbSize especifica o tamanho da estrutura e o membro hWnd é o identificador da janela da barra de aplicativos.

Algumas mensagens da barra de aplicativos solicitam informações do sistema. Ao processar essas mensagens, o sistema copia as informações solicitadas para a estrutura APPBARDATA .

Registro

O sistema mantém uma lista interna de barras de aplicativos e mantém informações sobre cada barra na lista. O sistema usa as informações para gerenciar as barras de aplicativo, executar serviços para elas e enviar mensagens de notificação.

Um aplicativo deve registrar uma barra de aplicativos (ou seja, adicioná-la à lista interna) antes de receber serviços da barra de aplicativos do sistema. Para registrar uma barra de aplicativos, um aplicativo envia a mensagem ABM_NEW . A estrutura APPBARDATA que acompanha inclui o identificador da janela da barra de aplicativos e um identificador de mensagem definido pelo aplicativo. O sistema usa o identificador de mensagem para enviar mensagens de notificação para o procedimento de janela da janela da barra de aplicativos. Para obter mais informações, consulte Mensagens de Notificação da Barra de Aplicativos.

Um aplicativo cancela o registro de uma barra de aplicativos enviando a mensagem ABM_REMOVE . Cancelar o registro de uma barra de aplicativos a remove da lista interna de barras de aplicativos do sistema. O sistema não envia mais mensagens de notificação para a barra de aplicativos ou impede que outros aplicativos usem a área de tela usada pela barra de aplicativos. Um aplicativo deve sempre enviar ABM_REMOVE antes de destruir uma barra de aplicativos.

Tamanho e posição da barra de aplicativos

Um aplicativo deve definir o tamanho e a posição de uma barra de aplicativos para que ele não interfira em nenhuma outra barra de aplicativos ou na barra de tarefas. Cada barra de aplicativos deve ser ancorada em uma borda específica da tela e várias barras de aplicativo podem ser ancoradas em uma borda. No entanto, se uma barra de aplicativos estiver ancorada na mesma borda que a barra de tarefas, o sistema garantirá que a barra de tarefas esteja sempre na borda mais externa.

Para definir o tamanho e a posição de uma barra de aplicativos, primeiro um aplicativo propõe uma borda de tela e um retângulo delimitador para a barra de aplicativos enviando a mensagem ABM_QUERYPOS . O sistema determina se qualquer parte da área de tela dentro do retângulo proposto é usada pela barra de tarefas ou outra barra de aplicativos, ajusta o retângulo (se necessário) e retorna o retângulo ajustado para o aplicativo.

Em seguida, o aplicativo envia a mensagem ABM_SETPOS para definir o novo retângulo delimitador para a barra de aplicativos. Novamente, o sistema pode ajustar o retângulo antes de devolvê-lo ao aplicativo. Por esse motivo, o aplicativo deve usar o retângulo ajustado retornado por ABM_SETPOS para definir o tamanho e a posição finais. O aplicativo pode usar a função MoveWindow para mover a barra de aplicativos para a posição.

Usando um processo em duas etapas para definir o tamanho e a posição, o sistema permite que o aplicativo forneça comentários intermediários ao usuário durante a operação de movimentação. Por exemplo, se o usuário arrastar uma barra de aplicativos, o aplicativo poderá exibir um retângulo sombreado indicando a nova posição antes que a barra de aplicativos realmente se mova.

Um aplicativo deve definir o tamanho e a posição de sua barra de aplicativos depois de registrá-lo e sempre que a barra de aplicativos receber a mensagem de notificação ABN_POSCHANGED . Uma barra de aplicativos recebe essa mensagem de notificação sempre que uma alteração ocorre no tamanho, posição ou estado de visibilidade da barra de tarefas e sempre que outra barra de aplicativos no mesmo lado da tela é redimensionada, adicionada ou removida.

Sempre que uma barra de aplicativos recebe a mensagem WM_ACTIVATE, ela deve enviar a mensagem ABM_ACTIVATE . Da mesma forma, quando uma barra de aplicativos recebe uma mensagem WM_WINDOWPOSCHANGED, ela deve chamar ABM_WINDOWPOSCHANGED. O envio dessas mensagens garante que o sistema defina corretamente a ordem z de qualquer barra de aplicativos de autoaplicação na mesma borda.

Barras de ferramentas da Área de Trabalho do Aplicativo automaticamente

Uma barra de aplicativos de ressarcimento automático é aquela que normalmente está oculta, mas fica visível quando o usuário move o cursor do mouse para a borda da tela com a qual a barra de aplicativos está associada. A barra de aplicativos se oculta novamente quando o usuário move o cursor do mouse para fora do retângulo delimitador da barra.

Embora o sistema permita várias barras de aplicativo diferentes a qualquer momento, ele permite apenas uma barra de aplicativos de resguardo automático por vez para cada borda de tela por várias etapas. O sistema mantém automaticamente a ordem z de uma barra de aplicativo de auto-deslizamento (somente dentro de seu grupo de ordem z).

Um aplicativo usa a mensagem ABM_SETAUTOHIDEBAR para registrar ou cancelar o registro de uma barra de aplicativos de auto-registro. A mensagem especifica a borda da barra de aplicativos e um sinalizador que especifica se a barra de aplicativos deve ser registrada ou não registrada. A mensagem falhará se uma barra de aplicativo de controle automático estiver sendo registrada, mas uma já estiver associada à borda especificada. Um aplicativo pode recuperar o identificador para a barra de aplicativos de controle automático associado a uma borda enviando a mensagem ABM_GETAUTOHIDEBAR .

Uma barra de aplicativos de auto-deslizamento não precisa se registrar como uma barra de aplicativos normal; ou seja, ele não precisa ser registrado enviando a mensagem ABM_NEW . Uma barra de aplicativos que não é registrada pelo ABM_NEW sobrepõe as barras de aplicativo ancoradas na mesma borda da tela.

Mensagens de notificação da Barra de Aplicativos

O sistema envia mensagens para notificar uma barra de aplicativos sobre eventos que podem afetar sua posição e aparência. As mensagens são enviadas no contexto de uma mensagem definida pelo aplicativo. O aplicativo especifica o identificador da mensagem quando envia a mensagem ABM_NEW para registrar a barra de aplicativos. O código de notificação está no parâmetro wParam da mensagem definida pelo aplicativo.

Uma barra de aplicativos recebe a mensagem de notificação ABN_POSCHANGED quando o tamanho, a posição ou o estado de visibilidade da barra de tarefas é alterado, quando outra barra de aplicativos é adicionada à mesma borda da tela ou quando outra barra de aplicativos na mesma borda da tela é redimensionada ou removida. Uma barra de aplicativos deve responder a essa mensagem de notificação enviando mensagens ABM_QUERYPOS e ABM_SETPOS . Se a posição de uma barra de aplicativos tiver sido alterada, ela deverá chamar a função MoveWindow para mover-se para a nova posição.

O sistema envia a mensagem de notificação ABN_STATECHANGE sempre que o estado de gerenciamento automático ou sempre no topo da barra de tarefas é alterado, ou seja, quando o usuário seleciona ou limpa a caixa de seleção Always on ouAuto hide na folha de propriedades da barra de tarefas. Uma barra de aplicativos pode usar essa mensagem de notificação para definir seu estado de acordo com o da barra de tarefas, se desejado.

Quando um aplicativo de tela inteira é iniciado ou quando o último aplicativo de tela inteira é fechado, uma barra de aplicativos recebe a mensagem de notificação ABN_FULLSCREENAPP . O parâmetro lParam indica se o aplicativo de tela inteira está abrindo ou fechando. Se estiver abrindo, a barra de aplicativos deverá cair na parte inferior da ordem z. A barra de aplicativos deve restaurar sua posição de ordem z quando o último aplicativo de tela inteira for fechado.

Uma barra de aplicativos recebe a mensagem de notificação ABN_WINDOWARRANGE quando o usuário seleciona o comando Cascade, Tile Horizontal ou Tile Verticalmente no menu de atalho da barra de tarefas. O sistema envia a mensagem duas vezes antes de reorganizar as janelas (lParam é TRUE) e depois de organizar as janelas (lParam é FALSE).

Uma barra de aplicativos pode usar ABN_WINDOWARRANGE mensagens para se excluir da operação de cascata ou bloco. Para se excluir, a barra de aplicativos deve se ocultar quando lParam for TRUE e se mostrar quando lParam for FALSE. Se uma barra de aplicativos se ocultar em resposta a essa mensagem, ela não precisará enviar as mensagens ABM_QUERYPOS e ABM_SETPOS em resposta à operação de cascata ou bloco.

Registrando uma barra de ferramentas da Área de Trabalho do Aplicativo

Um aplicativo deve registrar uma barra de aplicativos enviando a mensagem ABM_NEW . Registrar uma barra de aplicativos a adiciona à lista interna do sistema e fornece ao sistema um identificador de mensagem a ser usado para enviar mensagens de notificação para a barra de aplicativos. Antes de sair, um aplicativo deve cancelar o registro da barra de aplicativos enviando a mensagem ABM_REMOVE . O cancelamento do registro remove a barra de aplicativos da lista interna do sistema e impede que a barra receba mensagens de notificação da barra de aplicativos.

A função no exemplo a seguir registra ou cancela o registro de uma barra de aplicativos, dependendo do valor de um parâmetro de sinalizador booliano.

// RegisterAccessBar - registers or unregisters an appbar. 
// Returns TRUE if successful, or FALSE otherwise. 

// hwndAccessBar - handle to the appbar 
// fRegister - register and unregister flag 

// Global variables 
//     g_uSide - screen edge (defaults to ABE_TOP) 
//     g_fAppRegistered - flag indicating whether the bar is registered 

BOOL RegisterAccessBar(HWND hwndAccessBar, BOOL fRegister) 
{ 
    APPBARDATA abd; 
    
    // An application-defined message identifier
    APPBAR_CALLBACK = (WM_USER + 0x01);
    
    // Specify the structure size and handle to the appbar. 
    abd.cbSize = sizeof(APPBARDATA); 
    abd.hWnd = hwndAccessBar; 

    if (fRegister) 
    { 
        // Provide an identifier for notification messages. 
        abd.uCallbackMessage = APPBAR_CALLBACK; 

        // Register the appbar. 
        if (!SHAppBarMessage(ABM_NEW, &abd)) 
            return FALSE; 

        g_uSide = ABE_TOP;       // default edge 
        g_fAppRegistered = TRUE; 

    } 
    else 
    { 
        // Unregister the appbar. 
        SHAppBarMessage(ABM_REMOVE, &abd); 
        g_fAppRegistered = FALSE; 
    } 

    return TRUE; 
}

Definindo o tamanho e a posição da Barra de Aplicativos

Um aplicativo deve definir o tamanho e a posição de uma barra de aplicativos depois de registrar a barra de aplicativos, depois que o usuário mover ou dimensionar a barra de aplicativos e sempre que a barra de aplicativos receber a mensagem de notificação ABN_POSCHANGED . Antes de definir o tamanho e a posição da barra de aplicativos, o aplicativo consulta o sistema para um retângulo delimitador aprovado enviando a mensagem ABM_QUERYPOS . O sistema retorna um retângulo delimitador que não interfere na barra de tarefas ou em qualquer outra barra de aplicativos. O sistema ajusta o retângulo puramente pela subtração do retângulo; não faz nenhum esforço para preservar o tamanho inicial do retângulo. Por esse motivo, a barra de aplicativos deve reajustar o retângulo, conforme necessário, depois de enviar ABM_QUERYPOS.

Em seguida, o aplicativo passa o retângulo delimitador de volta para o sistema usando a mensagem ABM_SETPOS . Em seguida, ele chama a função MoveWindow para mover a barra de aplicativos para a posição.

O exemplo a seguir mostra como definir o tamanho e a posição de uma barra de aplicativos.

// AppBarQuerySetPos - sets the size and position of an appbar. 

// uEdge - screen edge to which the appbar is to be anchored 
// lprc - current bounding rectangle of the appbar 
// pabd - address of the APPBARDATA structure with the hWnd and cbSize members filled

void PASCAL AppBarQuerySetPos(UINT uEdge, LPRECT lprc, PAPPBARDATA pabd) 
{ 
    int iHeight = 0; 
    int iWidth = 0; 

    pabd->rc = *lprc; 
    pabd->uEdge = uEdge; 

    // Copy the screen coordinates of the appbar's bounding 
    // rectangle into the APPBARDATA structure. 
    if ((uEdge == ABE_LEFT) || (uEdge == ABE_RIGHT)) 
    { 
        iWidth = pabd->rc.right - pabd->rc.left; 
        pabd->rc.top = 0; 
        pabd->rc.bottom = GetSystemMetrics(SM_CYSCREEN); 
    } 
    else 
    { 
        iHeight = pabd->rc.bottom - pabd->rc.top; 
        pabd->rc.left = 0; 
        pabd->rc.right = GetSystemMetrics(SM_CXSCREEN); 
    } 

    // Query the system for an approved size and position. 
    SHAppBarMessage(ABM_QUERYPOS, pabd); 

    // Adjust the rectangle, depending on the edge to which the appbar is anchored.
    switch (uEdge) 
    { 
        case ABE_LEFT: 
            pabd->rc.right = pabd->rc.left + iWidth; 
            break; 

        case ABE_RIGHT: 
            pabd->rc.left = pabd->rc.right - iWidth; 
            break; 

        case ABE_TOP: 
            pabd->rc.bottom = pabd->rc.top + iHeight; 
            break; 

        case ABE_BOTTOM: 
            pabd->rc.top = pabd->rc.bottom - iHeight; 
            break; 
    } 

    // Pass the final bounding rectangle to the system. 
    SHAppBarMessage(ABM_SETPOS, pabd); 

    // Move and size the appbar so that it conforms to the 
    // bounding rectangle passed to the system. 
    MoveWindow(pabd->hWnd, 
               pabd->rc.left, 
               pabd->rc.top, 
               pabd->rc.right - pabd->rc.left, 
               pabd->rc.bottom - pabd->rc.top, 
               TRUE); 

}

Processando mensagens de notificação da Barra de Aplicativos

Uma barra de aplicativos recebe uma mensagem de notificação quando o estado da barra de tarefas é alterado, quando um aplicativo de tela inteira é iniciado (ou o último é fechado) ou quando ocorre um evento que pode afetar o tamanho e a posição da barra de aplicativos. O exemplo a seguir mostra como processar as várias mensagens de notificação.

// AppBarCallback - processes notification messages sent by the system. 

// hwndAccessBar - handle to the appbar 
// uNotifyMsg - identifier of the notification message 
// lParam - message parameter 

void AppBarCallback(HWND hwndAccessBar, UINT uNotifyMsg, 
    LPARAM lParam) 
{ 
    APPBARDATA abd; 
    UINT uState; 

    abd.cbSize = sizeof(abd); 
    abd.hWnd = hwndAccessBar; 

    switch (uNotifyMsg) 
    { 
        case ABN_STATECHANGE: 

            // Check to see if the taskbar's always-on-top state has changed
            // and, if it has, change the appbar's state accordingly.
            uState = SHAppBarMessage(ABM_GETSTATE, &abd); 

            SetWindowPos(hwndAccessBar, 
                         (ABS_ALWAYSONTOP & uState) ? HWND_TOPMOST : HWND_BOTTOM, 
                         0, 0, 0, 0, 
                         SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE); 

            break; 

        case ABN_FULLSCREENAPP: 

            // A full-screen application has started, or the last full-screen
            // application has closed. Set the appbar's z-order appropriately.
            if (lParam) 
            { 
                SetWindowPos(hwndAccessBar, 
                             (ABS_ALWAYSONTOP & uState) ? HWND_TOPMOST : HWND_BOTTOM, 
                             0, 0, 0, 0, 
                             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE); 
            } 
            else 
            { 
                uState = SHAppBarMessage(ABM_GETSTATE, &abd); 

                if (uState & ABS_ALWAYSONTOP) 
                    SetWindowPos(hwndAccessBar, 
                                 HWND_TOPMOST, 
                                 0, 0, 0, 0, 
                                 SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE); 
            } 

        case ABN_POSCHANGED: 

            // The taskbar or another appbar has changed its size or position.
            AppBarPosChanged(&abd); 
            break; 
    } 
}

A função a seguir ajusta o retângulo delimitador de uma barra de aplicativos e chama a função AppBarQuerySetPos definida pelo aplicativo (incluída na seção anterior) para definir o tamanho e a posição da barra adequadamente.

// AppBarPosChanged - adjusts the appbar's size and position. 

// pabd - address of an APPBARDATA structure that contains information 
//        used to adjust the size and position. 

void PASCAL AppBarPosChanged(PAPPBARDATA pabd) 
{ 
    RECT rc; 
    RECT rcWindow; 
    int iHeight; 
    int iWidth; 

    rc.top = 0; 
    rc.left = 0; 
    rc.right = GetSystemMetrics(SM_CXSCREEN); 
    rc.bottom = GetSystemMetrics(SM_CYSCREEN); 

    GetWindowRect(pabd->hWnd, &rcWindow); 

    iHeight = rcWindow.bottom - rcWindow.top; 
    iWidth = rcWindow.right - rcWindow.left; 

    switch (g_uSide) 
    { 
        case ABE_TOP: 
            rc.bottom = rc.top + iHeight; 
            break; 

        case ABE_BOTTOM: 
            rc.top = rc.bottom - iHeight; 
            break; 

        case ABE_LEFT: 
            rc.right = rc.left + iWidth; 
            break; 

        case ABE_RIGHT: 
            rc.left = rc.right - iWidth; 
            break; 
    } 

    AppBarQuerySetPos(g_uSide, &rc, pabd); 
}