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 do 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 da á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 contém as seguintes seções.
- Sobre as barras de ferramentas da área de trabalho do aplicativo
- Registrando um aplicativo Desktop Toolbar
- Definindo o tamanho e a posição da barra de aplicativos
- Processando 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 às barras de aplicativos para notificá-las sobre eventos que podem afetar seu tamanho, posição e aparência.
Envio de mensagens
Um aplicativo usa um conjunto especial de mensagens, chamadas 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 um estrutura de APPBARDATA. Os membros da estrutura contêm informações de que o sistema precisa para processar a mensagem dada.
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.
Registo
O sistema mantém uma lista interna de appbars e mantém informações sobre cada barra na lista. O sistema usa as informações para gerenciar appbars, executar serviços para eles e enviar-lhes mensagens de notificação.
Um aplicativo deve registrar uma appbar (ou seja, adicioná-la à lista interna) antes de poder receber serviços appbar do sistema. Para registrar uma barra de aplicativos, um aplicativo envia a mensagem ABM_NEW. A estrutura de APPBARDATA que acompanha inclui o handle para a janela da barra de aplicativo e um identificador de mensagem definido pelo aplicativo. O sistema utiliza o identificador de mensagem para enviar mensagens de notificação ao procedimento da janela da barra de ferramentas. 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 da tela usada pela barra de aplicativos. Um aplicativo deve sempre enviar ABM_REMOVE antes de destruir uma appbar.
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 com outras barras de aplicativos ou com a 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 garante 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 este motivo, a aplicação deve utilizar o retângulo ajustado devolvido 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 de duas etapas para definir o tamanho e a posição, o sistema permite que o aplicativo forneça feedback intermediário 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.
Uma aplicação deve definir o tamanho e a posição da sua barra de aplicação depois de a registar e sempre que a barra de aplicação receber a ABN_POSCHANGED mensagem de notificação. Uma barra de aplicativos recebe essa mensagem de notificação sempre que ocorre uma alteração 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 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 todas as appbars de ocultação automática na mesma borda.
Ocultar automaticamente as barras de ferramentas da área de trabalho do aplicativo
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 uma série de appbars diferentes a qualquer momento, ele permite apenas uma appbar de auto-ocultar de cada vez para cada margem do ecrã baseado no princípio de quem chega primeiro. O sistema mantém automaticamente a ordem z de uma barra de aplicativos de ocultação automática (apenas dentro do 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 registrada. 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 de ABM_GETAUTOHIDEBAR.
Uma appbar de ocultação automática não precisa de se registar como uma appbar normal; ou seja, não precisa de estar registada através do envio da mensagem ABM_NEW. Uma barra de aplicativos que não é registrada por ABM_NEW se sobrepõe a todas as 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 de 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 mensagens ABM_QUERYPOS e ABM_SETPOS. Se a posição de uma barra de aplicativos tiver mudado, 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 na parte superior da barra de tarefas é alterado, ou seja, quando o usuário seleciona ou desmarca a caixa de seleção Sempre na parte superior ou ocultação automática 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 cheia é iniciado ou quando o último aplicativo de tela cheia é fechado, uma barra de aplicativos recebe a mensagem de notificação ABN_FULLSCREENAPP. O parâmetro lParam indica se o aplicativo em tela cheia está abrindo ou fechando. Se estiver a abrir, a barra de aplicativos deve descer para a parte inferior do índice z. A barra de aplicativos deve restaurar sua posição de ordem z quando o último aplicativo de tela cheia 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 Mosaico 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 aplicações pode usar ABN_WINDOWARRANGE mensagens para se excluir de uma operação de agrupamento ou mosaico. Para se excluir, a barra de aplicação deve esconder-se quando lParam for TRUE e mostrar-se quando lParam for FALSE. Se uma barra de aplicativos se ocultar em resposta a esta mensagem, não precisará enviar as mensagens de ABM_QUERYPOS e ABM_SETPOS em resposta à operação de cascata ou de blocos.
Registrando 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 para usar 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. Cancelar o 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 appbar, dependendo do valor de um parâmetro de sinalizador booleano.
// 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 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 nenhuma outra barra de aplicações. O sistema ajusta o retângulo puramente por subtração do retângulo; não faz nenhum esforço para preservar o tamanho inicial do retângulo. Por esse motivo, a appbar deve reajustar o retângulo, quando for necessário, após o envio ABM_QUERYPOS.
Em seguida, o aplicativo passa o retângulo delimitador de volta para o sistema usando a mensagem ABM_SETPOS. Em seguida, chama a função MoveWindow para mover a barra de aplicações 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 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 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, 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 acordo.
// 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);
}