Uso delle barre degli strumenti di Application Desktop
Una barra degli strumenti desktop dell'applicazione (detta anche barra delle app) è una finestra simile alla barra delle applicazioni di Windows. È ancorato a un bordo dello schermo e in genere contiene pulsanti che consentono all'utente di accedere rapidamente ad altre applicazioni e finestre. Il sistema impedisce ad altre applicazioni di usare l'area desktop usata da una barra delle app. Qualsiasi numero di barre delle app può esistere sul desktop in qualsiasi momento.
Questo argomento include le sezioni seguenti.
- Informazioni sulle barre degli strumenti di Application Desktop
- Registrazione di una barra degli strumenti di Application Desktop
- Impostazione delle dimensioni e della posizione della barra delle app
- Elaborazione dei messaggi di notifica della barra delle app
Informazioni sulle barre degli strumenti di Application Desktop
Windows offre un'API che consente di sfruttare i servizi appbar forniti dal sistema. I servizi garantiscono che le barre delle app definite dall'applicazione funzionino senza problemi tra loro e con la barra delle applicazioni. Il sistema mantiene informazioni su ogni barra delle app e invia i messaggi delle barre delle app per notificarli sugli eventi che possono influire sulle dimensioni, la posizione e l'aspetto.
Invio di messaggi
Un'applicazione usa un set speciale di messaggi, denominati messaggi della barra delle app, per aggiungere o rimuovere una barra delle app, impostare le dimensioni e la posizione di una barra delle app e recuperare informazioni sulle dimensioni, la posizione e lo stato della barra delle applicazioni. Per inviare un messaggio della barra delle app, un'applicazione deve usare la funzione SHAppBarMessage. I parametri della funzione includono un identificatore di messaggio, ad esempio ABM_NEW, e l'indirizzo di una struttura APPBARDATA. I membri della struttura contengono informazioni che il sistema deve elaborare il messaggio specificato.
Per qualsiasi messaggio della barra delle app specificato, il sistema usa alcuni membri della struttura APPBARDATA e ignora gli altri. Tuttavia, il sistema usa sempre i membri cbSize e hWnd , quindi un'applicazione deve riempire questi membri per ogni messaggio della barra delle app. Il membro cbSize specifica le dimensioni della struttura e il membro hWnd è l'handle della finestra della barra delle app.
Alcuni messaggi della barra delle app richiedono informazioni dal sistema. Durante l'elaborazione di questi messaggi, il sistema copia le informazioni richieste nella struttura APPBARDATA.
Registrazione
Il sistema mantiene un elenco interno di barre delle app e mantiene le informazioni su ogni barra nell'elenco. Il sistema usa le informazioni per gestire le barre delle app, eseguire servizi per loro e inviarle messaggi di notifica.
Un'applicazione deve registrare una barra delle app , ovvero aggiungerla all'elenco interno, prima di poter ricevere i servizi della barra delle app dal sistema. Per registrare una barra delle app, un'applicazione invia il messaggio di ABM_NEW . La struttura APPBARDATA associata include l'handle per la finestra della barra delle app e un identificatore di messaggio definito dall'applicazione. Il sistema usa l'identificatore del messaggio per inviare messaggi di notifica alla procedura della finestra della barra delle app. Per altre informazioni, vedere Messaggi di notifica della barra delle app.
Un'applicazione annulla la registrazione di una barra delle app inviando il messaggio di ABM_REMOVE . L'annullamento della registrazione di una barra delle app lo rimuove dall'elenco interno delle barre delle app del sistema. Il sistema non invia più messaggi di notifica alla barra delle app o impedisce ad altre applicazioni di usare l'area dello schermo usata dalla barra delle app. Un'applicazione deve sempre inviare ABM_REMOVE prima di eliminare una barra delle app.
Dimensioni e posizione della barra delle app
Un'applicazione deve impostare le dimensioni e la posizione della barra delle app in modo che non interferisca con altre barre delle app o la barra delle applicazioni. Ogni barra delle app deve essere ancorata a un bordo specifico dello schermo e più barre delle app possono essere ancorate a un bordo. Tuttavia, se una barra delle app è ancorata allo stesso bordo della barra delle applicazioni, il sistema garantisce che la barra delle applicazioni sia sempre sul bordo più esterno.
Per impostare le dimensioni e la posizione di una barra delle app, un'applicazione propone innanzitutto un bordo dello schermo e un rettangolo di delimitazione per la barra delle app inviando il messaggio ABM_QUERYPOS. Il sistema determina se qualsiasi parte dell'area dello schermo all'interno del rettangolo proposto viene usata dalla barra delle applicazioni o da un'altra barra delle applicazioni, regola il rettangolo (se necessario) e restituisce il rettangolo regolato all'applicazione.
Successivamente, l'applicazione invia il messaggio ABM_edizione Standard TPOS per impostare il nuovo rettangolo di delimitazione per la barra delle app. Anche in questo caso, il sistema può regolare il rettangolo prima di restituirlo all'applicazione. Per questo motivo, l'applicazione deve usare il rettangolo regolato restituito da ABM_edizione Standard TPOS per impostare le dimensioni finali e la posizione. L'applicazione può usare la funzione MoveWindow per spostare la barra delle app nella posizione.
Usando un processo in due passaggi per impostare le dimensioni e la posizione, il sistema consente all'applicazione di fornire feedback intermedi all'utente durante l'operazione di spostamento. Ad esempio, se l'utente trascina una barra delle app, l'applicazione potrebbe visualizzare un rettangolo ombreggiato che indica la nuova posizione prima che la barra dell'app venga effettivamente spostata.
Un'applicazione deve impostare le dimensioni e la posizione della barra delle app dopo la registrazione e ogni volta che la barra delle app riceve il messaggio di notifica ABN_POSCHANGED . Una barra delle app riceve questo messaggio di notifica ogni volta che si verifica una modifica nelle dimensioni, nella posizione o nello stato di visibilità della barra delle applicazioni e ogni volta che un'altra barra delle app sullo stesso lato dello schermo viene ridimensionata, aggiunta o rimossa.
Ogni volta che una barra delle app riceve il messaggio di WM_ACTIVATE, deve inviare il messaggio di ABM_ACTIVATE . Analogamente, quando una barra delle app riceve un messaggio di WM_WINDOWPOSCHANGED, deve chiamare ABM_WINDOWPOSCHANGED. L'invio di questi messaggi garantisce che il sistema imposti correttamente l'ordine z di tutte le barre delle app dell'ambiente automatico sullo stesso bordo.
Autohide Application Desktop Toolbars
Un'appbar dell'ambiente automatico è una che è normalmente nascosta, ma diventa visibile quando l'utente sposta il cursore del mouse sul bordo dello schermo a cui è associata la barra dell'app. La barra delle app si nasconde di nuovo quando l'utente sposta il cursore del mouse fuori dal rettangolo di delimitazione della barra.
Anche se il sistema consente una serie di barre delle app diverse in qualsiasi momento, consente solo un'appbar dell'app con estensione automatica alla volta per ogni bordo dello schermo in un primo momento, primo servizio. Il sistema mantiene automaticamente l'ordine z di un'appbar dell'ambiente automatico (solo all'interno del relativo gruppo di ordini z).
Un'applicazione usa il messaggio ABM_edizione Standard TAUTOHIDEBAR per registrare o annullare la registrazione di una barra delle app in modalità automatica. Il messaggio specifica il bordo per la barra delle app e un flag che specifica se la barra delle app deve essere registrata o annullata la registrazione. Il messaggio ha esito negativo se è in corso la registrazione di un'appbar dell'ambiente automatico, ma ne è già associato uno al bordo specificato.The message fails if an autohide appbar is being registered but one is already associated with the specified edge. Un'applicazione può recuperare l'handle nella barra delle app dell'ambiente automatico associata a un bordo inviando il messaggio di ABM_GETAUTOHIDEBAR .
Non è necessario registrare un'appbar automatica come barra delle app normale; ovvero, non deve essere registrato inviando il messaggio di ABM_NEW . Una barra delle app non registrata da ABM_NEW si sovrappone a qualsiasi barra delle app ancorata sullo stesso bordo dello schermo.
Messaggi di notifica della barra delle app
Il sistema invia messaggi per notificare a una barra delle app gli eventi che possono influire sulla posizione e sull'aspetto. I messaggi vengono inviati nel contesto di un messaggio definito dall'applicazione. L'applicazione specifica l'identificatore del messaggio quando invia il messaggio ABM_NEW per registrare la barra delle app. Il codice di notifica si trova nel parametro wParam del messaggio definito dall'applicazione.
Una barra delle app riceve il messaggio di notifica ABN_POSCHANGED quando le dimensioni, la posizione o lo stato di visibilità della barra delle applicazioni cambiano, quando un'altra barra delle app viene aggiunta allo stesso bordo dello schermo o quando un'altra barra delle app sullo stesso bordo dello schermo viene ridimensionata o rimossa. Una barra delle app deve rispondere a questo messaggio di notifica inviando messaggi ABM_QUERYPOS e ABM_edizione Standard TPOS. Se la posizione di un'appbar è cambiata, deve chiamare la funzione MoveWindow per spostarsi nella nuova posizione.
Il sistema invia il messaggio di notifica ABN_STATECHANGE ogni volta che lo stato automatico o sempre attivo della barra delle applicazioni è cambiato, ovvero quando l'utente seleziona o deseleziona la casella di controllo Nascondi sempre in alto o Nascondi automaticamente nella finestra delle proprietà della barra delle applicazioni. Una barra delle applicazioni può usare questo messaggio di notifica per impostarne lo stato in modo che sia conforme a quello della barra delle applicazioni, se necessario.
Quando un'applicazione a schermo intero viene avviata o quando l'ultima applicazione a schermo intero viene chiusa, una barra delle app riceve il messaggio di notifica ABN_FULLSCRedizione Enterprise NAPP. Il parametro lParam indica se l'applicazione a schermo intero sta aprendo o chiudendo. Se è in corso l'apertura, la barra dell'app deve essere scritta nella parte inferiore dell'ordine z. La barra delle app deve ripristinare la posizione dell'ordine z quando l'ultima applicazione a schermo intero è stata chiusa.
Una barra delle app riceve il messaggio di notifica ABN_WINDOWARRANGE quando l'utente seleziona il comando Cascade, Tile Horizontally o Tile Vertically dal menu di scelta rapida della barra delle applicazioni. Il sistema invia il messaggio due volte, prima di ridisporre le finestre (lParam è TRUE) e dopo aver organizzato le finestre (lParam è FAL edizione Standard).
Una barra delle app può usare ABN_WINDOWARRANGE messaggi per escludersi dall'operazione a catena o riquadro. Per escludersi, la barra delle app deve nascondersi quando lParam è TRUE e mostrarsi quando lParam è FAL edizione Standard. Se una barra delle app si nasconde in risposta a questo messaggio, non è necessario inviare i messaggi ABM_QUERYPOS e ABM_edizione Standard TPOS in risposta all'operazione a catena o riquadro.
Registrazione di una barra degli strumenti di Application Desktop
Un'applicazione deve registrare una barra delle app inviando il messaggio di ABM_NEW . La registrazione di una barra delle app lo aggiunge all'elenco interno del sistema e fornisce al sistema un identificatore di messaggio da usare per inviare messaggi di notifica alla barra delle app. Prima di uscire, un'applicazione deve annullare la registrazione della barra delle app inviando il messaggio di ABM_REMOVE . L'annullamento della registrazione rimuove la barra delle app dall'elenco interno del sistema e impedisce alla barra di ricevere messaggi di notifica della barra delle app.
La funzione nell'esempio seguente registra o annulla la registrazione di una barra delle app, a seconda del valore di un parametro flag 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;
}
Impostazione delle dimensioni e della posizione della barra delle app
Un'applicazione deve impostare le dimensioni e la posizione della barra delle app dopo la registrazione della barra delle app, dopo che l'utente sposta o ridimensiona la barra delle app e ogni volta che la barra delle app riceve il messaggio di notifica ABN_POSCHANGED . Prima di impostare le dimensioni e la posizione della barra delle app, l'applicazione esegue una query sul sistema per individuare un rettangolo di delimitazione approvato inviando il messaggio di ABM_QUERYPOS . Il sistema restituisce un rettangolo di delimitazione che non interferisce con la barra delle applicazioni o con qualsiasi altra barra delle applicazioni. Il sistema regola il rettangolo esclusivamente in base alla sottrazione rettangolo; non fa alcun sforzo per mantenere le dimensioni iniziali del rettangolo. Per questo motivo, la barra delle app deve riaggiustare il rettangolo, se necessario, dopo l'invio di ABM_QUERYPOS.
Successivamente, l'applicazione passa di nuovo il rettangolo di delimitazione al sistema usando il messaggio ABM_edizione Standard TPOS. Chiama quindi la funzione MoveWindow per spostare la barra delle app nella posizione.
L'esempio seguente mostra come impostare le dimensioni e la posizione di una barra delle app.
// 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);
}
Elaborazione dei messaggi di notifica della barra delle app
Una barra delle app riceve un messaggio di notifica quando cambia lo stato della barra delle applicazioni, all'avvio di un'applicazione a schermo intero (o all'ultima chiusura) o quando si verifica un evento che può influire sulle dimensioni e sulla posizione della barra delle app. Nell'esempio seguente viene illustrato come elaborare i vari messaggi di notifica.
// 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;
}
}
La funzione seguente regola il rettangolo di delimitazione di una barra delle app e quindi chiama la funzione AppBarQuerySetPos definita dall'applicazione (inclusa nella sezione precedente) per impostare di conseguenza le dimensioni e la posizione della barra.
// 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);
}