Panoramica dell'API di ingrandimento

L'API Ingrandimento consente ai fornitori di assistive technology di sviluppare applicazioni di ingrandimento dello schermo eseguite in Microsoft Windows. Questo argomento descrive l'API Ingrandimento e spiega come usarla in un'applicazione. Contiene le sezioni seguenti:

• Guida Introduttiva
• concetti di base
  • tipi di lente di ingrandimento
  • fattore di ingrandimento
  • effetti colore
  • rettangolo di origine
  • Elenco Filtri
  • trasformazione input
  • cursore di sistema
• Inizializzazione della libreria di runtime della lente di ingrandimento
• Uso del Full-Screen lente di ingrandimento
• Uso del Controllo Lente di Ingrandimento
  • Creazione del controllo Lente di ingrandimento
  • inizializzazione del controllo
  • Impostazione del rettangolo di origine
  • Applicazione di effetti colore
  • Ingrandimento Selettivo
• argomenti correlati

Introduzione

La versione originale dell'API Ingrandimento è supportata in Windows Vista e nei sistemi operativi successivi. In Windows 8 e versioni successive l'API supporta funzionalità aggiuntive, tra cui l'ingrandimento a schermo intero e l'impostazione della visibilità del cursore di sistema con ingrandimento.

Il supporto per l'API ingrandimento viene fornito da Magnification.dll. Per compilare l'applicazione, includere Magnification.h e il collegamento a Magnification.lib.

Nota

L'API Ingrandimento non è supportata in WOW64; ovvero, un'applicazione di ingrandimento a 32 bit non verrà eseguita correttamente in Windows a 64 bit.

Concetti di base

Questa sezione descrive i concetti fondamentali su cui si basa l'API di ingrandimento. Contiene le parti seguenti:

• tipi di lente di ingrandimento
• fattore di ingrandimento
• effetti colore
• rettangolo di origine
• Elenco Filtri
• Trasformazione dell'input
• cursore di sistema

Tipi di lente di ingrandimento

L'API supporta due tipi di lente di ingrandimento, il lente di ingrandimento a schermo intero e il controllo lente di ingrandimento . La lente di ingrandimento a schermo intero consente di ingrandire il contenuto dell'intera schermata, mentre il controllo lente di ingrandimento ingrandire il contenuto di una determinata area dello schermo e visualizzare il contenuto in una finestra. Per entrambe le lenti di ingrandimento, le immagini e il testo sono ingrandite ed entrambe consentono di controllare la quantità di ingrandimento. È anche possibile applicare effetti di colore al contenuto dello schermo con ingrandimento, rendendo più semplice vedere per le persone che hanno carenze di colore o hanno bisogno di colori che hanno più o meno contrasto.

Importante

L'API di controllo lente di ingrandimento è disponibile in Windows Vista e nei sistemi operativi successivi, mentre l'API della lente di ingrandimento a schermo intero è disponibile solo nei sistemi operativi Windows 8 e versioni successive.

Fattore di ingrandimento

Sia la lente di ingrandimento a schermo intero che il controllo lente di ingrandimento applicano una trasformazione di ridimensionamento per ingrandire il contenuto dello schermo. La quantità di ingrandimento applicata dalla trasformazione della scala è detta fattore di ingrandimento . Viene espresso come valore a virgola mobile in cui 1,0 corrisponde a nessun ingrandimento e i valori più grandi generano una quantità corrispondente di ingrandimento. Ad esempio, un valore pari a 1,5 rende il contenuto dello schermo più grande del 50%. Un fattore di ingrandimento minore di 1,0 non è valido.

Effetti colore

Gli effetti colore vengono ottenuti applicando una matrice di trasformazione di colore da 5 a 5 ai colori del contenuto dello schermo con ingrandimento. La matrice determina le intensità dei componenti rosso, blu, verde e alfa del contenuto. Per ulteriori informazioni, vedere Uso di una matrice di colori per trasformare un singolo colore nella documentazione di Windows GDI+.

Rettangolo di origine

La lente di ingrandimento a schermo intero applica la trasformazione della scala e il colore all'intero schermo. Il controllo lente di ingrandimento, d'altra parte, copia un'area dello schermo, denominata rettangolo di origine , in una bitmap fuori schermo. Successivamente, il controllo applica la trasformazione della scala e la trasformazione del colore, se presente, alla bitmap fuori schermo. Infine, il controllo visualizza la bitmap ridimensionata e con trasformazione del colore nella finestra di controllo del lente di ingrandimento.

Elenco filtri

Per impostazione predefinita, il controllo lente di ingrandimento consente di ingrandire tutte le finestre nel rettangolo di origine specificato. Tuttavia, fornendo un elenco di filtri di handle di finestra, è possibile controllare quali finestre sono incluse nel contenuto ingrandito e quali no. Per altre informazioni, vedere ingrandimento selettivo.

La lente di ingrandimento a schermo intero non supporta un elenco di filtri; ingrandito sempre tutte le finestre sullo schermo.

Trasformazione input

Normalmente, il contenuto dello schermo ingrandito è "invisibile" all'input dell'utente tramite penna o tocco. Ad esempio, se l'utente tocca l'immagine ingrandita di un controllo, il sistema non passa necessariamente l'input al controllo. Invece, il sistema passa l'input a qualsiasi elemento (se presente) si trovi alle coordinate dello schermo toccate sul desktop non ingrandito. La funzione MagSetInputTransform consente di specificare una trasformazione di input che mappa lo spazio di coordinate del contenuto dello schermo ingrandito allo spazio di coordinate effettivo (non ingrandito). Ciò consente al sistema di trasferire l'input penna o tocco immessi nel contenuto dello schermo ingrandito all'elemento corretto dell'interfaccia utente sullo schermo.

Nota

Per impostare la trasformazione di input, il processo chiamante deve disporre dei privilegi UIAccess. Per ulteriori informazioni, vedere Considerazioni sulla Sicurezza dell'Automazione UI e /MANIFESTUAC (incorpora informazioni UAC nel manifesto).

Cursore di sistema

La funzione MagShowSystemCursor consente di visualizzare o nascondere il cursore di sistema. Se si visualizza il cursore di sistema quando l'ingrandimento a schermo intero è attivo, il cursore di sistema viene sempre grandito insieme al resto del contenuto dello schermo. Se si nasconde il cursore di sistema quando l'ingrandimento a schermo intero è attivo, il cursore di sistema non è visibile affatto.

Con il controllo della lente di ingrandimento, la funzione MagShowSystemCursor mostra o nasconde il cursore di sistema non ingrandito, ma non ha alcun effetto sul cursore di sistema ingrandito. La visibilità del cursore di sistema con ingrandimento dipende dal fatto che il controllo lente di ingrandimento abbia lo stile MS_SHOWMAGNIFIEDCURSOR. Se ha questo stile, il controllo lente di ingrandimento visualizza il cursore di sistema ingrandito, insieme al contenuto dello schermo ingrandito, ogni volta che il cursore di sistema entra nel rettangolo di origine.

Inizializzazione della libreria di runtime della lente di ingrandimento

Prima di poter chiamare qualsiasi altra funzione API di ingrandimento, è necessario creare e inizializzare gli oggetti di runtime della lente di ingrandimento chiamando la funzione MagInitialize. Analogamente, al termine dell'uso dell'API lente di ingrandimento, chiamare la funzione MagUninitialize per eliminare definitivamente gli oggetti di runtime del lente di ingrandimento e liberare le risorse di sistema associate.

Uso della lente d'ingrandimento Full-Screen

Per usare la lente di ingrandimento a schermo intero, chiamare la funzione MagSetFullscreenTransform. Il parametro magLevel specifica il fattore di ingrandimento. I parametri xOffset e yOffset specificano il modo in cui il contenuto dello schermo con ingrandimento viene posizionato rispetto allo schermo.

Quando il contenuto dello schermo è ingrandito, diventa più grande dello schermo stesso. Alcune parti del contenuto si estendono oltre i bordi dello schermo e diventano invisibili all'utente. I parametri xOffset e yOffset della funzione MagSetFullscreenTransform determinare quale parte del contenuto dello schermo ingrandito viene visualizzata sullo schermo. Insieme, i parametri specificano le coordinate di un punto nel contenuto dello schermo non immaginificato. Quando il contenuto viene ingrandimentato, viene posizionato con il punto specificato nell'angolo superiore sinistro dello schermo.

L'esempio seguente imposta il fattore di ingrandimento per il lente di ingrandimento a schermo intero e posiziona il centro del contenuto dello schermo ingrandito al centro dello schermo.

BOOL SetZoom(float magnificationFactor)
{
    // A magnification factor less than 1.0 is not valid.
    if (magnificationFactor < 1.0)
    {
        return FALSE;
    }

    // Calculate offsets such that the center of the magnified screen content 
    // is at the center of the screen. The offsets are relative to the 
    // unmagnified screen content.
    int xDlg = (int)((float)GetSystemMetrics(
            SM_CXSCREEN) * (1.0 - (1.0 / magnificationFactor)) / 2.0);
    int yDlg = (int)((float)GetSystemMetrics(
            SM_CYSCREEN) * (1.0 - (1.0 / magnificationFactor)) / 2.0);

    return MagSetFullscreenTransform(magnificationFactor, xDlg, yDlg);
}

Usare la funzioneMagSetFullscreenColorEffect per applicare effetti colore al contenuto a schermo intero impostando una matrice di trasformazione colori definita dall'applicazione. Nell'esempio seguente, ad esempio, viene impostata una matrice di trasformazione dei colori che converte i colori in gradazioni di grigio.

// Initialize color transformation matrices used to apply grayscale and to 
// restore the original screen color.
MAGCOLOREFFECT g_MagEffectGrayscale = {0.3f,  0.3f,  0.3f,  0.0f,  0.0f,
                                       0.6f,  0.6f,  0.6f,  0.0f,  0.0f,
                                       0.1f,  0.1f,  0.1f,  0.0f,  0.0f,
                                       0.0f,  0.0f,  0.0f,  1.0f,  0.0f,
                                       0.0f,  0.0f,  0.0f,  0.0f,  1.0f};

MAGCOLOREFFECT g_MagEffectIdentity = {1.0f,  0.0f,  0.0f,  0.0f,  0.0f,
                                      0.0f,  1.0f,  0.0f,  0.0f,  0.0f,
                                      0.0f,  0.0f,  1.0f,  0.0f,  0.0f,
                                      0.0f,  0.0f,  0.0f,  1.0f,  0.0f,
                                      0.0f,  0.0f,  0.0f,  0.0f,  1.0f};

BOOL SetColorGrayscale(__in BOOL fGrayscaleOn)
{
    // Apply the color matrix required to either apply grayscale to the screen 
    // colors or to show the regular colors.
    PMAGCOLOREFFECT pEffect = 
                (fGrayscaleOn ? &g_MagEffectGrayscale : &g_MagEffectIdentity);

    return MagSetFullscreenColorEffect(pEffect);
}

È possibile recuperare i valori correnti di ingrandimento e offset chiamando la funzione MagGetFullscreenTransform. È possibile recuperare la matrice di trasformazione del colore corrente chiamando la funzione MagGetFullscreenColorEffect.

Uso del Controllo Lente di Ingrandimento

Il controllo lente di ingrandimento consente di ingrandire il contenuto di una determinata area dello schermo e di visualizzare il contenuto in una finestra. In questa sezione viene descritto come utilizzare il controllo lente di ingrandimento. Contiene le parti seguenti:

• Creazione del controllo Ingranditore
• inizializzazione del controllo
• Impostazione del rettangolo di origine
• Applicazione di Effetti Colori
• Ingrandimento selettivo

Creazione del controllo lente d'ingrandimento

Il controllo lente di ingrandimento deve essere ospitato in una finestra creata con lo stile esteso WS_EX_LAYERED. Dopo aver creato la finestra host, chiamare SetLayeredWindowAttributes per impostare l'opacità della finestra host. La finestra host è in genere impostata sull'opacità completa per impedire che il contenuto dello schermo sottostante venga visualizzato. Nell'esempio seguente viene illustrato come impostare l'opacità completa della finestra host:

SetLayeredWindowAttributes(hwndHost, NULL, 255, LWA_ALPHA);

Se si applica lo stile WS_EX_TRANSPARENT alla finestra host, i clic del mouse vengono passati a qualsiasi oggetto dietro la finestra host nella posizione del cursore del mouse. Tenere presente che, poiché la finestra host non elabora i clic del mouse, l'utente non sarà in grado di spostare o ridimensionare la finestra di ingrandimento usando il mouse.

La classe finestra della finestra di controllo lente di ingrandimento deve essere WC_MAGNIFIER. Se si applica lo stile MS_SHOWMAGNIFIEDCURSOR, il controllo lente di ingrandimento include il cursore di sistema nel contenuto dello schermo con ingrandimento e il cursore viene ingrandito insieme al contenuto dello schermo.

Dopo aver creato il controllo lente di ingrandimento, mantenere l'handle della finestra in modo che sia possibile passarlo ad altre funzioni.

Nell'esempio seguente viene illustrato come creare il controllo lente di ingrandimento.

// Description: 
//   Registers the host window class, creates the host window, sets the layered
//   window attributes, and creates the magnifier control. 
// Parameters:
//   hInstance - Instance handle of the application.
// Variables:
//   HostWndProc - Window procedure of the host window.
//   WindowClassName - Name of the window class.
//   WindowTitle - Title of the host window.
// Constants and global variables:
//   hwndHost - Handle of the host window.
//   hwndMag - Handle of the magnifier window.
//   LENS_WIDTH - Width of the magnifier window.
//   LENS_HEIGHT - Height of the magnifier window.
// 
BOOL CreateMagnifier(HINSTANCE hInstance)
{
   // Register the host window class.
    WNDCLASSEX wcex = {};
    wcex.cbSize = sizeof(WNDCLASSEX); 
    wcex.style          = 0;
    wcex.lpfnWndProc    = HostWndProc;
    wcex.hInstance      = hInstance;
    wcex.hCursor        = LoadCursor(NULL, IDC_ARROW);
    wcex.hbrBackground  = (HBRUSH)(1 + COLOR_BTNFACE);
    wcex.lpszClassName  = WindowClassName;
    
    if (RegisterClassEx(&wcex) == 0)
        return FALSE;

    // Create the host window. 
    hwndHost = CreateWindowEx(WS_EX_TOPMOST | WS_EX_LAYERED | WS_EX_TRANSPARENT, 
        WindowClassName, WindowTitle, 
        WS_CLIPCHILDREN,
        0, 0, 0, 0,
        NULL, NULL, hInstance, NULL);
    if (!hwndHost)
    {
        return FALSE;
    }

    // Make the window opaque.
    SetLayeredWindowAttributes(hwndHost, 0, 255, LWA_ALPHA);

    // Create a magnifier control that fills the client area.
    hwndMag = CreateWindow(WC_MAGNIFIER, TEXT("MagnifierWindow"), 
        WS_CHILD | MS_SHOWMAGNIFIEDCURSOR | WS_VISIBLE,
        0, 0, 
        LENS_WIDTH, 
        LENS_HEIGHT, 
        hwndHost, NULL, hInstance, NULL );
    if (!hwndMag)
    {
        return FALSE;
    }

    return TRUE;
}

Inizializzazione del controllo

Dopo aver creato il controllo lente di ingrandimento, è necessario chiamare la funzioneMagSetWindowTransform per specificare il fattore di ingrandimento. Si tratta semplicemente di specificare una matrice di

(n, 0,0, 0,0)

(0,0, n, 0,0)

(0.0, 0.0, 1.0)

dove n è il fattore di ingrandimento.

Nell'esempio seguente viene illustrato come impostare il fattore di ingrandimento per il controllo lente di ingrandimento.

// Description:
//   Sets the magnification factor for a magnifier control.
// Parameters:
//   hwndMag - Handle of the magnifier control.
//   magFactor - New magnification factor.
//
BOOL SetMagnificationFactor(HWND hwndMag, float magFactor)
{
    MAGTRANSFORM matrix;
    memset(&matrix, 0, sizeof(matrix));
    matrix.v[0][0] = magFactor;
    matrix.v[1][1] = magFactor;
    matrix.v[2][2] = 1.0f;

    return MagSetWindowTransform(hwndMag, &matrix);  
}

Impostazione del rettangolo di origine

Quando l'utente sposta il cursore del mouse sullo schermo, l'applicazione chiama la funzione MagSetWindowSource per specificare la parte dello schermo sottostante da ingrandire.

La funzione di esempio seguente calcola la posizione e le dimensioni del rettangolo di origine (in base alla posizione del mouse e alle dimensioni della finestra di ingrandimento divisa per il fattore di ingrandimento) e imposta di conseguenza il rettangolo di origine. La funzione centra anche l'area client della finestra host in corrispondenza della posizione del mouse. Questa funzione viene chiamata a intervalli per aggiornare la finestra di ingrandimento.

// Description: 
//   Called by a timer to update the contents of the magnifier window and to set
//   the position of the host window. 
// Constants and global variables:
//   hwndHost - Handle of the host window.
//   hwndMag - Handle of the magnifier window.
//   LENS_WIDTH - Width of the magnifier window.
//   LENS_HEIGHT - Height of the magnifier window.
//   MAGFACTOR - The magnification factor.
//
void CALLBACK UpdateMagWindow(HWND /*hwnd*/, UINT /*uMsg*/, 
        UINT_PTR /*idEvent*/, DWORD /*dwTime*/)
{
    // Get the mouse coordinates.
    POINT mousePoint;
    GetCursorPos(&mousePoint);

    // Calculate a source rectangle that is centered at the mouse coordinates. 
    // Size the rectangle so that it fits into the magnifier window (the lens).
    RECT sourceRect;
    int borderWidth = GetSystemMetrics(SM_CXFIXEDFRAME);
    int captionHeight = GetSystemMetrics(SM_CYCAPTION);
    sourceRect.left = (mousePoint.x - (int)((LENS_WIDTH / 2) / MAGFACTOR)) + 
             (int)(borderWidth / MAGFACTOR);
    sourceRect.top = (mousePoint.y - (int)((LENS_HEIGHT / 2) / MAGFACTOR)) + 
             (int)(captionHeight / MAGFACTOR) + (int)(borderWidth / MAGFACTOR); 
    sourceRect.right = LENS_WIDTH;
    sourceRect.bottom = LENS_HEIGHT;

    // Pass the source rectangle to the magnifier control.
    MagSetWindowSource(hwndMag, sourceRect);

    // Move the host window so that the origin of the client area lines up
    // with the origin of the magnified source rectangle.
    MoveWindow(hwndHost, 
        (mousePoint.x - LENS_WIDTH / 2), 
        (mousePoint.y - LENS_HEIGHT / 2), 
        LENS_WIDTH, 
        LENS_HEIGHT,
        FALSE);

    // Force the magnifier control to redraw itself.
    InvalidateRect(hwndMag, NULL, TRUE);

    return;
}

Applicazione di effetti colore

Un controllo lente di ingrandimento con lo stile MS_INVERTCOLORS applica una matrice di trasformazione dei colori predefinita che inverte i colori del contenuto dello schermo ingrandito. La figura seguente mostra il contenuto dello schermo in un controllo per la lente di ingrandimento con lo stile MS_INVERTCOLORS.

La funzioneMagSetColorEffect consente di applicare altri effetti di colore impostando una matrice di trasformazione colori definita dall'applicazione. Ad esempio, la funzione seguente imposta una matrice di trasformazione colore che converte i colori in gradazioni di grigio.

// Description:
//   Converts the colors displayed in the magnifier window to grayscale, or
//   returns the colors to normal.
// Parameters:
//   hwndMag - Handle of the magnifier control.
//   fInvert - TRUE to convert to grayscale, or FALSE for normal colors.
//
BOOL ConvertToGrayscale(HWND hwndMag, BOOL fConvert)
{
    // Convert the screen colors in the magnifier window.
    if (fConvert)
    {
        MAGCOLOREFFECT magEffectGrayscale = 
            {{ // MagEffectGrayscale
                {  0.3f,  0.3f,  0.3f,  0.0f,  0.0f },
                {  0.6f,  0.6f,  0.6f,  0.0f,  0.0f },
                {  0.1f,  0.1f,  0.1f,  0.0f,  0.0f },
                {  0.0f,  0.0f,  0.0f,  1.0f,  0.0f },
                {  0.0f,  0.0f,  0.0f,  0.0f,  1.0f } 
            }};

        return MagSetColorEffect(hwndMag, &magEffectGrayscale);
    }

    // Return the colors to normal.
    else
    {
        return MagSetColorEffect(hwndMag, NULL);
    }
}

Per altre informazioni sul funzionamento delle trasformazioni dei colori, vedere Uso di una matrice di colori per trasformare un singolo colore nella documentazione di GDI+.

Ingrandimento selettivo

Per impostazione predefinita, l'ingrandimento viene applicato a tutte le finestre diverse dalla finestra di ingrandimento stessa. Per specificare le finestre da ingrandire, chiamare la funzione MagSetWindowFilterList. Questo metodo accetta un elenco di finestre da ingrandire o un elenco di finestre da escludere dall'ingrandimento.

Argomenti correlati

API Ingrandimento