Vue d’ensemble de l’API d’agrandissement

L’API d’agrandissement permet aux fournisseurs de technologies d’assistance de développer des applications d’agrandissement d’écran qui s’exécutent sur Microsoft Windows. Cette rubrique décrit l’API d’agrandissement et explique comment l’utiliser dans une application. Il contient les sections suivantes :

• Prise en main
• Concepts de base
  • Types de loupes
  • Facteur d’agrandissement
  • Effets de couleur
  • Source Rectangle
  • Liste de filtres
  • Transformation d’entrée
  • Curseur système
• Initialisation de la bibliothèque d’exécution de la loupe
• Utilisation de la loupe Full-Screen
• Utilisation du contrôle Loupe
  • Création du contrôle Loupe
  • Initialisation du contrôle
  • Définition du rectangle source
  • Application d’effets de couleur
  • Agrandissement sélectif
• Rubriques connexes

Mise en route

La version d’origine de l’API Agrandissement est prise en charge sur Windows Vista et les systèmes d’exploitation ultérieurs. Sur Windows 8 et versions ultérieures, l’API prend en charge des fonctionnalités supplémentaires, notamment l’agrandissement en plein écran et la définition de la visibilité du curseur système agrandi.

La prise en charge de l’API d’agrandissement est assurée par Magnification.dll. Pour compiler votre application, incluez Magnification.h et créez un lien vers Magnification.lib.

Notes

L’API d’agrandissement n’est pas prise en charge sous WOW64 ; autrement dit, une application de loupe 32 bits ne s’exécute pas correctement sur Windows 64 bits.

Concepts de base

Cette section décrit les concepts fondamentaux sur ant l’API d’agrandissement. Il contient les parties suivantes :

• Types de loupes
• Facteur d’agrandissement
• Effets de couleur
• Source Rectangle
• Liste de filtres
• Transformation d’entrée
• Curseur système

Types de loupes

L’API prend en charge deux types de loupes, la loupe plein écran et le contrôle de loupe. La loupe en plein écran agrandit le contenu de l’écran entier, tandis que le contrôle loupe agrandit le contenu d’une zone particulière de l’écran et affiche le contenu dans une fenêtre. Pour les deux loupes, les images et le texte sont agrandis et vous permettent de contrôler la quantité de grossissement. Vous pouvez également appliquer des effets de couleur au contenu de l’écran agrandi, ce qui le rend plus facile à voir pour les personnes qui ont des lacunes de couleur ou qui ont besoin de couleurs qui ont plus ou moins de contraste.

Important

L’API de contrôle de loupe est disponible sur Windows Vista et les systèmes d’exploitation ultérieurs, tandis que l’API de loupe en plein écran est disponible uniquement sur les systèmes d’exploitation Windows 8 et ultérieurs.

Facteur d’agrandissement

La loupe plein écran et le contrôle de loupe appliquent une transformation de mise à l’échelle pour agrandir le contenu de l’écran. La quantité d’agrandissement appliquée par la transformation d’échelle est appelée facteur d’agrandissement. Il est exprimé sous la forme d’une valeur à virgule flottante où 1.0 ne correspond à aucun agrandissement, et les valeurs plus grandes entraînent une quantité correspondante d’agrandissement. Par exemple, une valeur de 1,5 rend le contenu de l’écran 50 % plus grand. Un facteur d’agrandissement inférieur à 1.0 n’est pas valide.

Effets de couleur

Les effets de couleur sont obtenus en appliquant une matrice de transformation de couleur 5 par 5 aux couleurs du contenu de l’écran agrandi. La matrice détermine les intensités des composants rouge, bleu, vert et alpha du contenu. Pour plus d’informations, consultez Utilisation d’une matrice de couleurs pour transformer une couleur unique dans la documentation de Windows GDI+.

Source Rectangle

La loupe en plein écran applique la transformation d’échelle et la transformation de couleur à l’écran entier. Le contrôle de loupe, d’autre part, copie une zone de l’écran, appelée rectangle source, dans une bitmap hors écran. Ensuite, le contrôle applique la transformation de mise à l’échelle et la transformation de couleur, le cas échéant, à l’image bitmap hors écran. Enfin, le contrôle affiche l’image bitmap mise à l’échelle et transformée en couleur dans la fenêtre de contrôle de la loupe.

Liste de filtres

Par défaut, le contrôle loupe agrandit toutes les fenêtres dans le rectangle source spécifié. Toutefois, en fournissant une liste de filtres de poignées de fenêtre, vous pouvez contrôler les fenêtres incluses dans le contenu agrandi et celles qui ne le sont pas. Pour plus d’informations, consultez Agrandissement sélectif.

La loupe en plein écran ne prend pas en charge une liste de filtres ; il agrandit toujours toutes les fenêtres de l’écran.

Transformation d’entrée

Normalement, le contenu de l’écran agrandi est « invisible » pour le stylet utilisateur ou l’entrée tactile. Par exemple, si l’utilisateur appuie sur l’image agrandie d’un contrôle, le système ne passe pas nécessairement l’entrée au contrôle. Au lieu de cela, le système transmet l’entrée à n’importe quel élément (le cas échéant) se trouve aux coordonnées de l’écran appuyé sur le bureau nonmagnifié. La fonction MagSetInputTransform vous permet de spécifier une transformation d’entrée qui mappe l’espace de coordonnées du contenu de l’écran agrandi à l’espace de coordonnées de l’écran réel (nonmagnifié). Cela permet au système de transmettre l’entrée au stylet ou à l’entrée tactile qui est entrée dans le contenu de l’écran agrandi, à l’élément d’interface utilisateur approprié à l’écran.

Notes

Le processus appelant doit disposer de privilèges UIAccess pour définir la transformation d’entrée. Pour plus d’informations, consultez UI Automation Considérations relatives à la sécurité et /MANIFESTUAC (Incorpore les informations UAC dans le manifeste).

Curseur système

La fonction MagShowSystemCursor vous permet d’afficher ou de masquer le curseur système. Si vous affichez le curseur système lorsque la loupe plein écran est active, le curseur système est toujours agrandi avec le reste du contenu de l’écran. Si vous masquez le curseur système lorsque la loupe plein écran est active, le curseur système n’est pas visible du tout.

Avec le contrôle loupe, la fonction MagShowSystemCursor affiche ou masque le curseur système nonmagnifié, mais n’a aucun effet sur le curseur système agrandi. La visibilité du curseur système agrandi varie selon que le contrôle de loupe a le style MS_SHOWMAGNIFIEDCURSOR . S’il a ce style, le contrôle loupe affiche le curseur système agrandi, ainsi que le contenu de l’écran agrandi, chaque fois que le curseur système entre dans le rectangle source.

Initialisation de la bibliothèque d’exécution de la loupe

Avant de pouvoir appeler d’autres fonctions d’API loupe, vous devez créer et initialiser les objets d’exécution de la loupe en appelant la fonction MagInitialize . De même, une fois que vous avez terminé d’utiliser l’API de loupe, appelez la fonction MagUninitialize pour détruire les objets d’exécution de la loupe et libérer les ressources système associées.

Utilisation de la loupe Full-Screen

Pour utiliser la loupe en plein écran, appelez la fonction MagSetFullscreenTransform . Le paramètre magLevel spécifie le facteur d’agrandissement. Les paramètres xOffset et yOffset spécifient la façon dont le contenu de l’écran agrandi est positionné par rapport à l’écran.

Lorsque le contenu de l’écran est agrandi, il devient plus grand que l’écran lui-même. Une partie du contenu s’étend au-delà des bords de l’écran et devient invisible pour l’utilisateur. Les paramètres xOffset et yOffset de la fonction MagSetFullscreenTransform déterminent quelle partie du contenu de l’écran agrandi s’affiche à l’écran. Ensemble, les paramètres spécifient les coordonnées d’un point dans le contenu de l’écran non agrandi. Lorsque le contenu est agrandi, il est positionné avec le point spécifié dans le coin supérieur gauche de l’écran.

L’exemple suivant définit le facteur d’agrandissement de la loupe plein écran et place le centre du contenu de l’écran agrandi au centre de l’écran.

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);
}

Utilisez la fonction MagSetFullscreenColorEffect pour appliquer des effets de couleur au contenu plein écran en définissant une matrice de transformation de couleur définie par l’application. Par exemple, l’exemple suivant définit une matrice de transformation de couleur qui convertit les couleurs en nuances de gris.

// 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);
}

Vous pouvez récupérer le facteur d’agrandissement actuel et les valeurs de décalage en appelant la fonction MagGetFullscreenTransform . Vous pouvez récupérer la matrice de transformation de couleur actuelle en appelant la fonction MagGetFullscreenColorEffect .

Utilisation du contrôle Loupe

Le contrôle loupe agrandit le contenu d’une zone particulière de l’écran et affiche le contenu dans une fenêtre. Cette section explique comment utiliser le contrôle de loupe. Il contient les éléments suivants :

• Création du contrôle Loupe
• Initialisation du contrôle
• Définition du rectangle source
• Application d’effets de couleur
• Agrandissement sélectif

Création du contrôle Loupe

Le contrôle loupe doit être hébergé dans une fenêtre créée avec le style étendu WS_EX_LAYERED . Après avoir créé la fenêtre hôte, appelez SetLayeredWindowAttributes pour définir l’opacité de la fenêtre hôte. La fenêtre hôte est généralement définie sur une opacité totale pour empêcher l’affichage du contenu de l’écran sous-jacent. L’exemple suivant montre comment définir la fenêtre hôte sur une opacité totale :

SetLayeredWindowAttributes(hwndHost, NULL, 255, LWA_ALPHA);

Si vous appliquez le style WS_EX_TRANSPARENT à la fenêtre hôte, les clics de souris sont passés à n’importe quel objet se trouve derrière la fenêtre hôte à l’emplacement du curseur de la souris. N’oubliez pas que, étant donné que la fenêtre hôte ne traite pas les clics de souris, l’utilisateur ne peut pas déplacer ou redimensionner la fenêtre d’agrandissement à l’aide de la souris.

La classe de fenêtre de la fenêtre de contrôle de loupe doit être WC_MAGNIFIER. Si vous appliquez le style MS_SHOWMAGNIFIEDCURSOR , le contrôle loupe inclut le curseur système dans le contenu de l’écran agrandi, et le curseur est agrandi avec le contenu de l’écran.

Après avoir créé le contrôle de loupe, conservez le handle de fenêtre pour pouvoir le passer à d’autres fonctions.

L’exemple suivant montre comment créer le contrôle de loupe.

// 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;
}

Initialisation du contrôle

Après avoir créé le contrôle de loupe, vous devez appeler la fonction MagSetWindowTransform pour spécifier le facteur d’agrandissement. Il s’agit simplement de spécifier une matrice de

(n, 0.0, 0.0)

(0.0, n, 0.0)

(0.0, 0.0, 1.0)

où n est le facteur d’agrandissement.

L’exemple suivant montre comment définir le facteur d’agrandissement pour le contrôle de loupe.

// 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);  
}

Définition du rectangle source

Lorsque l’utilisateur déplace le curseur de la souris sur l’écran, votre application appelle la fonction MagSetWindowSource pour spécifier la partie de l’écran sous-jacent qui doit être agrandie.

L’exemple de fonction suivant calcule la position et les dimensions du rectangle source (en fonction de la position de la souris et des dimensions de la fenêtre loupe divisées par le facteur d’agrandissement) et définit le rectangle source en conséquence. La fonction centre également la zone cliente de la fenêtre hôte à la position de la souris. Cette fonction est appelée à intervalles réguliers pour mettre à jour la fenêtre d’agrandissement.

// 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;
}

Application d’effets de couleur

Un contrôle de loupe qui a le style MS_INVERTCOLORS applique une matrice de transformation de couleur intégrée qui inverse les couleurs du contenu de l’écran agrandi. L’illustration suivante montre le contenu de l’écran dans un contrôle de loupe qui a le style MS_INVERTCOLORS .

La fonction MagSetColorEffect vous permet d’appliquer d’autres effets de couleur en définissant une matrice de transformation de couleur définie par l’application. Par exemple, la fonction suivante définit une matrice de transformation de couleur qui convertit les couleurs en nuances de gris.

// 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);
    }
}

Pour plus d’informations sur le fonctionnement des transformations de couleur, consultez Utilisation d’une matrice de couleurs pour transformer une couleur unique dans la documentation GDI+.

Agrandissement sélectif

Par défaut, l’agrandissement est appliqué à toutes les fenêtres autres que la fenêtre d’agrandissement elle-même. Pour spécifier les fenêtres à agrandir, appelez la fonction MagSetWindowFilterList . Cette méthode prend soit une liste de fenêtres à agrandir, soit une liste de fenêtres à exclure de l’agrandissement.

Rubriques connexes

API de grossissement