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 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.

In questo argomento sono contenute le sezioni seguenti.

Informazioni sulle barre degli strumenti di Application Desktop

Windows fornisce un'API che consente di sfruttare i servizi della barra delle app forniti dal sistema. I servizi consentono di garantire che le barre delle app definite dall'applicazione funzionino senza problemi tra loro e con la barra delle applicazioni. Il sistema mantiene le informazioni su ogni barra delle app e invia i messaggi appbars per notificare agli eventi che possono influire sulle dimensioni, la posizione e l'aspetto.

sending messages

Un'applicazione usa un set speciale di messaggi, detti messaggi della barra delle app, per aggiungere o rimuovere una barra delle app, impostare le dimensioni e la posizione di un'appbar e recuperare informazioni sulle dimensioni, la posizione e lo stato della barra delle applicazioni. Per inviare un messaggio appbar, 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 dell'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 delle barre delle app e mantiene le informazioni su ogni barra nell'elenco. Il sistema usa le informazioni per gestire le barre delle app, eseguire i servizi e inviarli 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 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 routine 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 distruggere una barra delle app.

Dimensioni e posizione della barra delle app

Un'applicazione deve impostare le dimensioni e la posizione di un'appbar 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 applicazioni è 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_SETPOS 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_SETPOS per impostare le dimensioni e la posizione finali. L'applicazione può usare la funzione MoveWindow per spostare la barra delle app in posizione.

Usando un processo in due passaggi per impostare le dimensioni e la posizione, il sistema consente all'applicazione di fornire feedback intermedio 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 relativa 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 nello stato di dimensione, posizione o visibilità della barra delle applicazioni e ogni volta che un'altra barra dell'app sullo stesso lato dello schermo viene ridimensionata, aggiunta o rimossa.

Ogni volta che un'appbar 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 arco.

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 delle app. La barra delle app si nasconde di nuovo quando l'utente sposta il cursore del mouse all'esterno del 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'ambiente automatico alla volta per ogni bordo dello schermo in base al primo avvio. Il sistema mantiene automaticamente l'ordine z di una barra delle app dell'ide automatico (solo all'interno del gruppo z-order).

Un'applicazione usa il messaggio di ABM_SETAUTOHIDEBAR per registrare o annullare la registrazione di una barra delle app per l'accesso automatico. 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. Un'applicazione può recuperare l'handle sulla barra delle app dell'ambiente automatico associata a un bordo inviando il messaggio di ABM_GETAUTOHIDEBAR .

Non è necessario registrare una barra delle app in modalità 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 tutte le barre delle app ancorate 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 l'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 cambiano le dimensioni, la posizione o lo stato di visibilità della barra delle applicazioni, quando un'altra barra delle app viene aggiunta allo stesso bordo dello schermo o quando un'altra barra delle applicazioni sullo stesso bordo dello schermo viene ridimensionata o rimossa. Una barra delle app deve rispondere a questo messaggio di notifica inviando ABM_QUERYPOS e ABM_SETPOS messaggi. 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 viene chiusa l'ultima applicazione a schermo intero, una barra delle app riceve il messaggio di notifica ABN_FULLSCREENAPP . Il parametro lParam indica se l'applicazione a schermo intero è aperta o chiusa. Se è aperto, la barra dell'app deve essere visualizzata 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 è FALSE).

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 viene visualizzata quando lParam è FALSE. Se una barra delle app si nasconde in risposta a questo messaggio, non è necessario inviare il ABM_QUERYPOS e ABM_SETPOS messaggi 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 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 di 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 di un'appbar dopo la registrazione della barra delle app, dopo che l'utente ha spostato o ridimensionato 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 alcuno 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_SETPOS . Chiama quindi la funzione MoveWindow per spostare la barra delle app in 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 lo stato della barra delle applicazioni cambia, quando un'applicazione a schermo intero viene avviata (o l'ultima chiude) o quando si verifica un evento che può influire sulle dimensioni e sulla posizione della barra delle applicazioni. 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 un'appbar 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); 
}