Usar 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 do Windows. É ancorada a 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 aplicativos 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
- Registrar uma barra de ferramentas da área de trabalho do aplicativo
- Definir o tamanho e a posição da barra de aplicativos
- Processar mensagens de notificação da barra de aplicativos
Sobre as barras de ferramentas da área de trabalho do aplicativo
O 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 funcionem sem problemas entre si e com a barra de tarefas. O sistema mantém informações sobre cada barra de aplicativos e envia mensagens de barras de aplicativos para notificar sobre eventos que podem afetar o tamanho, a posição e a aparência.
enviando mensagens
Um aplicativo usa um conjunto especial de mensagens, chamadas como 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 das quais o sistema precisa para processar a mensagem fornecida.
Para qualquer mensagem da barra de aplicativos, o sistema usa alguns membros da estrutura APPBARDATA e ignora os outros. Porém, o sistema sempre usa os membros cbSize e hWnd. Portanto, um aplicativo deve preencher esses membros em 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 as informações sobre cada barra na lista. O sistema usa as informações para gerenciar barras de aplicativos, 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 de barra de aplicativos do sistema. Para registrar uma barra de aplicativos, um aplicativo envia a mensagem ABM_NEW. A estrutura APPBARDATA complementar inclui o identificador para a 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 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. O cancelamento do registro de uma barra de aplicativos remove-a 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 da 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 ela não interfira em nenhuma outra barra de aplicativos ou na barra de tarefas. Cada barra de aplicativos deve ser ancorada a uma borda específica da tela, e várias barras de aplicativos podem ser ancoradas a 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, um aplicativo primeiro 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 da 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, a aplicação deve utilizar o retângulo ajustado retornado por ABM_SETPOS para definir o tamanho e a posição final. O aplicativo pode usar a função MoveWindow para mover a barra de aplicativos para a posição.
Usando um processo de 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 da barra de aplicativos depois de registrá-la 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 ocorre uma alteração no tamanho, na posição ou no 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 receber a mensagem WM_ACTIVATE, ela deverá 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 ocultação automática na mesma borda.
Barras de ferramentas da área de trabalho do aplicativo Ocultar Automaticamente
Uma barra de aplicativos de ocultação automática é aquela que normalmente está oculta, mas se torna visível quando o usuário move o cursor do mouse para a borda da tela à 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 um número de diferentes barras de aplicativos a qualquer momento, ele permite apenas uma barra de aplicativos de ocultação automática por vez para cada borda da tela por ordem de chegada. O sistema mantém automaticamente a ordem z de uma barra de aplicativos de ocultação automática (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 ocultação automática. 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. A mensagem falhará se uma barra de aplicativos de ocultação automática estiver sendo registrada, mas uma já estiver associada à borda especificada. Um aplicativo pode recuperar o identificador para a barra de aplicativos de ocultação automática associada a uma borda enviando a mensagem ABM_GETAUTOHIDEBAR.
Uma barra de aplicativos de ocultação automática não precisa se registrar como uma barra de aplicativos normal; ou seja, ela não precisa ser registrada enviando a mensagem ABM_NEW. Uma barra de aplicativos que não é registrada por ABM_NEW sobrepõe quaisquer barras de aplicativos 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 muda, 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 as mensagens ABM_QUERYPOS e ABM_SETPOS. Se a posição de uma barra de aplicativos mudar, ela deverá chamar a função MoveWindow para se mover para a nova posição.
O sistema envia a mensagem de notificação ABN_STATECHANGE sempre que o estado de ocultação automática ou sempre visível da barra de tarefas é alterado, ou seja, quando o usuário marca ou desmarca a caixa de seleção Sempre visível ou Ocultar automaticamente 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 deverá 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 Cascata, Lado a Lado Horizontalmente ou Lado a Lado 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 mensagens ABN_WINDOWARRANGE para se excluir da operação em cascata ou lado a lado. Para se excluir, a barra de aplicativos deve se ocultar quando lParam é TRUE e mostrar-se quando lParam é 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 em cascata ou lado a lado.
Registrar uma barra de ferramentas da área de trabalho do aplicativo
Um aplicativo deve registrar uma barra de aplicativos enviando a mensagem ABM_NEW. O registro de 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 à 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;
}
Definir o tamanho e a posição da barra de aplicativos
Um aplicativo deverá 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 em busca de 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 simplesmente por 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, após o envio de 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);
}
Processar 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 muda, 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 diversas 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, em seguida, chama a função AppBarQuerySetPos definida pelo aplicativo (incluída na seção anterior) para definir o tamanho e a posição da barra de forma adequada.
// 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);
}
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de