Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Mit der Vergrößerungs-API können Anbieter von Hilfstechnologien Anwendungen zur Bildschirmvergrößerung entwickeln, die unter Microsoft Windows ausgeführt werden. In diesem Thema wird die Vergrößerungs-API beschrieben und die Verwendung in einer Anwendung erläutert. Sie enthält die folgenden Abschnitte:
- Erste Schritte
- Grundlegende Konzepte
- Initialisieren der Laufzeitbibliothek der Bildschirmlupe
- Verwenden der Full-Screen Bildschirmlupe
- Verwenden des Bildschirmlupensteuerelements
- Zugehörige Themen
Erste Schritte
Die ursprüngliche Version der Vergrößerungs-API wird unter Windows Vista und höheren Betriebssystemen unterstützt. Auf Windows 8 und höher unterstützt die API zusätzliche Features, z. B. die Vollbildvergrößerung und das Festlegen der Sichtbarkeit des vergrößerten Systemcursors.
Unterstützung für die Vergrößerungs-API wird von Magnification.dll bereitgestellt. Um Ihre Anwendung zu kompilieren, fügen Sie Magnification.h ein, und verlinken Sie zu Magnification.lib.
Hinweis
Die Vergrößerungs-API wird unter WOW64 nicht unterstützt. Das heißt, eine 32-Bit-Bildschirmlupenanwendung wird unter 64-Bit-Windows nicht ordnungsgemäß ausgeführt.
Grundlegende Konzepte
In diesem Abschnitt werden die grundlegenden Konzepte beschrieben, auf denen die Vergrößerungs-API basiert. Es enthält die folgenden Teile:
- Arten von Bildschirmlupen
- Vergrößerungsfaktor
- Farbeffekte
- Quellrechteck
- Filterliste
- Eingabetransformation
- Systemcursor
Arten von Bildschirmlupen
Die API unterstützt zwei Arten von Bildschirmlupen, die Vollbildlupe und das Bildschirmlupensteuerelement. Die Vollbildlupe vergrößert den Inhalt des gesamten Bildschirms, während das Bildschirmlupensteuerelement den Inhalt eines bestimmten Bereichs des Bildschirms vergrößert und den Inhalt in einem Fenster anzeigt. Für beide Bildschirmlupen werden Bilder und Text vergrößert, und beide ermöglichen es Ihnen, die Menge der Vergrößerung zu steuern. Sie können auch Farbeffekte auf den vergrößerten Bildschirminhalt anwenden, sodass Personen, die Farbmängel haben oder Farben benötigen, die mehr oder weniger Kontrast haben, leichter zu sehen sind.
Wichtig
Die Bildschirmlupensteuerungs-API ist unter Windows Vista und höheren Betriebssystemen verfügbar, während die Vollbildlupen-API nur unter Windows 8 und höheren Betriebssystemen verfügbar ist.
Vergrößerungsfaktor
Sowohl die Vollbildlupe als auch das Bildschirmlupensteuerelement wenden eine Skalierungstransformation an, um den Bildschirminhalt zu vergrößern. Die Menge der Vergrößerung, die durch die Skalierungstransformation angewendet wird, wird als Vergrößerungsfaktor bezeichnet. Er wird als Gleitkommawert ausgedrückt, wobei 1,0 keiner Vergrößerung entspricht und größere Werte zu einer entsprechenden Vergrößerung führen. Mit einem Wert von 1,5 wird der Bildschirminhalt beispielsweise um 50 Prozent größer. Ein Vergrößerungsfaktor kleiner als 1,0 ist ungültig.
Farbeffekte
Farbeffekte werden erzielt, indem eine 5-mal-5-Farbtransformationsmatrix auf die Farben des vergrößerten Bildschirminhalts angewendet wird. Die Matrix bestimmt die Intensitäten der roten, blauen, grünen und alpha-Komponenten des Inhalts. Weitere Informationen finden Sie unter Verwenden einer Farbmatrix zum Transformieren einer einzelnen Farbe in der Windows GDI+-Dokumentation.
Quellrechteck
Die Vollbildlupe wendet die Skalierungstransformation und Farbtransformation auf den gesamten Bildschirm an. Das Bildschirmlupensteuerelement kopiert hingegen einen Bereich des Bildschirms, der als Quellrechteck bezeichnet wird, in eine Bitmap außerhalb des Bildschirms. Als Nächstes wendet das Steuerelement die Skalierungstransformation und ggf. die Farbtransformation auf die Offscreen-Bitmap an. Schließlich zeigt das Steuerelement die skalierte und farbtransformationierte Bitmap im Fenster der Bildschirmlupe an.
Filterliste
Standardmäßig vergrößert das Bildschirmlupensteuerelement alle Fenster im angegebenen Quellrechteck. Durch Bereitstellen einer Filterliste mit Fensterhandles können Sie jedoch steuern, welche Fenster im vergrößerten Inhalt enthalten sind und welche nicht. Weitere Informationen finden Sie unter Selektive Vergrößerung.
Die Vollbildlupe unterstützt keine Filterliste. Es vergrößert immer alle Fenster auf dem Bildschirm.
Eingabetransformation
Normalerweise ist der vergrößerte Bildschirminhalt für die Stift- oder Toucheingabe des Benutzers "unsichtbar". Wenn der Benutzer beispielsweise auf das vergrößerte Bild eines Steuerelements tippt, übergibt das System die Eingabe nicht unbedingt an das Steuerelement. Stattdessen übergibt das System die Eingabe an jedes Element (falls vorhanden), das sich an den getippten Bildschirmkoordinaten auf dem nicht beschädigten Desktop befindet. Mit der Funktion MagSetInputTransform können Sie eine Eingabetransformation angeben, die den Koordinatenraum des vergrößerten Bildschirminhalts dem tatsächlichen (nichtmagnifizierten) Bildschirmkoordinatenraum zuordnet. Dadurch kann das System Stift- oder Toucheingaben, die in vergrößerten Bildschirminhalten eingegeben werden, an das richtige UI-Element auf dem Bildschirm übergeben.
Hinweis
Der aufrufende Prozess muss über UIAccess-Berechtigungen verfügen, um die Eingabetransformation festzulegen. Weitere Informationen finden Sie unter Benutzeroberflächenautomatisierung Sicherheitsüberlegungen und /MANIFESTUAC (Embeds UAC information in manifest).
Systemcursor
Mit der Funktion MagShowSystemCursor können Sie den Systemcursor ein- oder ausblenden. Wenn Sie den Systemcursor anzeigen, wenn die Vollbildlupe aktiv ist, wird der Systemcursor immer zusammen mit dem restlichen Bildschirminhalt vergrößert. Wenn Sie den Systemcursor ausblenden, wenn die Vollbildlupe aktiv ist, ist der Systemcursor überhaupt nicht sichtbar.
Mit dem Bildschirmlupensteuerelement zeigt die Funktion MagShowSystemCursor den nichtmagnifizierten Systemcursor an, hat jedoch keine Auswirkung auf den vergrößerten Systemcursor. Die Sichtbarkeit des vergrößerten Systemcursors hängt davon ab, ob das Bildschirmlupensteuerelement den MS_SHOWMAGNIFIEDCURSOR Stil aufweist. Wenn es diesen Stil hat, zeigt das Bildschirmlupensteuerelement den vergrößerten Systemcursor zusammen mit dem vergrößerten Bildschirminhalt an, wenn der Systemcursor in das Quellrechteck eintritt.
Initialisieren der Laufzeitbibliothek der Bildschirmlupe
Bevor Sie andere Bildschirmlupen-API-Funktionen aufrufen können, müssen Sie die Laufzeitobjekte der Bildschirmlupe erstellen und initialisieren, indem Sie die MagInitialize-Funktion aufrufen. Rufen Sie nach Abschluss der Verwendung der Bildschirmlupen-API die Funktion MagUninitialize auf, um die Laufzeitobjekte der Bildschirmlupe zu zerstören und die zugeordneten Systemressourcen freizugeben.
Verwenden der Full-Screen Bildschirmlupe
Um die Vollbildlupe zu verwenden, rufen Sie die Funktion MagSetFullscreenTransform auf. Der magLevel-Parameter gibt den Vergrößerungsfaktor an. Die Parameter xOffset und yOffset geben an, wie der vergrößerte Bildschirminhalt relativ zum Bildschirm positioniert wird.
Wenn der Bildschirminhalt vergrößert wird, wird er größer als der Bildschirm selbst. Ein Teil des Inhalts erstreckt sich über die Bildschirmränder hinaus und wird für den Benutzer unsichtbar. Die Parameter xOffset und yOffset der MagSetFullscreenTransform-Funktion bestimmen, welcher Teil des vergrößerten Bildschirminhalts auf dem Bildschirm angezeigt wird. Zusammen geben die Parameter die Koordinaten eines Punkts im unbemerkten Bildschirminhalt an. Wenn der Inhalt vergrößert wird, wird er mit dem angegebenen Punkt in der oberen linken Ecke des Bildschirms positioniert.
Im folgenden Beispiel wird der Vergrößerungsfaktor für die Vollbildlupe festgelegt und die Mitte des vergrößerten Bildschirminhalts in der Mitte des Bildschirms platziert.
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);
}
Verwenden Sie die MagSetFullscreenColorEffect-Funktion , um Farbeffekte auf den Vollbildinhalt anzuwenden, indem Sie eine von der Anwendung definierte Farbtransformationsmatrix festlegen. Im folgenden Beispiel wird beispielsweise eine Farbtransformationsmatrix festgelegt, die Farben in Graustufen konvertiert.
// 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);
}
Sie können den aktuellen Vergrößerungsfaktor und die Offsetwerte abrufen, indem Sie die MagGetFullscreenTransform-Funktion aufrufen. Sie können die aktuelle Farbtransformationsmatrix abrufen, indem Sie die MagGetFullscreenColorEffect-Funktion aufrufen.
Verwenden des Bildschirmlupe-Steuerelements
Das Bildschirmlupe-Steuerelement vergrößert den Inhalt eines bestimmten Bereichs des Bildschirms und zeigt den Inhalt in einem Fenster an. In diesem Abschnitt wird die Verwendung des Bildschirmlupe-Steuerelements beschrieben. Sie enthält die folgenden Teile:
- Erstellen des Bildschirmlupe-Steuerelements
- Initialisieren des Steuerelements
- Festlegen des Quellrechtecks
- Anwenden von Farbeffekten
- Selektive Vergrößerung
Erstellen des Bildschirmlupe-Steuerelements
Das Bildschirmlupensteuerelement muss in einem Fenster gehostet werden, das mit dem erweiterten Stil WS_EX_LAYERED erstellt wurde. Rufen Sie nach dem Erstellen des Hostfensters SetLayeredWindowAttributes auf, um die Deckkraft des Hostfensters festzulegen. Das Hostfenster ist in der Regel auf volle Deckkraft festgelegt, um zu verhindern, dass der zugrunde liegende Bildschirminhalt angezeigt wird. Das folgende Beispiel zeigt, wie Das Hostfenster auf vollständige Deckkraft festgelegt wird:
SetLayeredWindowAttributes(hwndHost, NULL, 255, LWA_ALPHA);
Wenn Sie die WS_EX_TRANSPARENT-Formatvorlage auf das Hostfenster anwenden, werden Mausklicks an das Objekt übergeben, das sich hinter dem Hostfenster an der Position des Mauszeigers befindet. Beachten Sie, dass der Benutzer das Vergrößerungsfenster nicht mithilfe der Maus verschieben oder ändern kann, da das Hostfenster keine Mausklicks verarbeitet.
Die Fensterklasse des Fensters der Bildschirmlupe muss WC_MAGNIFIER sein. Wenn Sie die MS_SHOWMAGNIFIEDCURSOR Formatvorlage anwenden, schließt das Bildschirmlupensteuerelement den Systemcursor in den vergrößerten Bildschirminhalt ein, und der Cursor wird zusammen mit dem Bildschirminhalt vergrößert.
Behalten Sie nach dem Erstellen des Bildschirmlupe-Steuerelements das Fensterhandle bei, damit Sie es an andere Funktionen übergeben können.
Im folgenden Beispiel wird gezeigt, wie Das Bildschirmlupensteuerelement erstellt wird.
// 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;
}
Initialisieren des Steuerelements
Nach dem Erstellen des Bildschirmlupe-Steuerelements müssen Sie die MagSetWindowTransform-Funktion aufrufen, um den Vergrößerungsfaktor anzugeben. Dies ist einfach eine Frage der Angabe einer Matrix von
(n, 0.0, 0.0)
(0.0, n, 0.0)
(0.0, 0.0, 1.0)
wobei n der Vergrößerungsfaktor ist.
Im folgenden Beispiel wird gezeigt, wie der Vergrößerungsfaktor für das Bildschirmlupensteuerelement festgelegt wird.
// 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);
}
Festlegen des Quellrechtecks
Wenn der Benutzer den Mauszeiger um den Bildschirm bewegt, ruft Ihre Anwendung die MagSetWindowSource-Funktion auf, um den Teil des zugrunde liegenden Bildschirms anzugeben, der vergrößert werden soll.
Die folgende Beispielfunktion berechnet die Position und abmessungen des Quellrechtecks (basierend auf der Mausposition und den Dimensionen des Bildschirmlupefensters dividiert durch den Vergrößerungsfaktor) und legt das Quellrechteck entsprechend fest. Die Funktion zentriert auch den Clientbereich des Hostfensters an der Mausposition. Diese Funktion wird in Intervallen aufgerufen, um das Vergrößerungsfenster zu aktualisieren.
// 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;
}
Anwenden von Farbeffekten
Ein Bildschirmlupensteuerelement mit der MS_INVERTCOLORS Formatvorlage wendet eine integrierte Farbtransformationsmatrix an, die die Farben des vergrößerten Bildschirminhalts invertiert. Die folgende Abbildung zeigt den Bildschirminhalt in einem Bildschirmlupe-Steuerelement, das den stil "MS_INVERTCOLORS" aufweist.
Mit der MagSetColorEffect-Funktion können Sie andere Farbeffekte anwenden, indem Sie eine von der Anwendung definierte Farbtransformationsmatrix festlegen. Die folgende Funktion legt beispielsweise eine Farbtransformationsmatrix fest, die Farben in Graustufen konvertiert.
// 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);
}
}
Weitere Informationen zur Funktionsweise von Farbtransformationen finden Sie unter Verwenden einer Farbmatrix zum Transformieren einer einzelnen Farbe in der GDI+-Dokumentation.
Selektive Vergrößerung
Standardmäßig wird die Vergrößerung auf alle Fenster mit Ausnahme des Vergrößerungsfensters selbst angewendet. Rufen Sie die MagSetWindowFilterList-Funktion auf, um anzugeben, welche Fenster vergrößert werden sollen. Diese Methode verwendet entweder eine Liste von Fenstern, die vergrößert werden sollen, oder eine Liste von Fenstern, die von der Vergrößerung ausgeschlossen werden sollen.