放大 API 概觀

發行項
06/13/2023

放大 API 可讓輔助技術廠商開發在 Microsoft Windows 上執行的螢幕放大應用程式。本主題描述放大 API，並說明如何在應用程式中使用它。它包含下列區段：

快速入門
基本概念
初始化放大鏡執行時間程式庫
使用Full-Screen放大鏡
使用放大鏡控制項
相關主題

開始使用

Windows Vista 和更新版本的作業系統支援原始版本的放大 API。在Windows 8和更新版本上，API 支援其他功能，包括全螢幕放大和設定放大系統游標的可見度。

Magnification.dll提供放大 API 的支援。若要編譯您的應用程式，請包含 Magnification.h，並連結至 Magnification.lib。

注意

WOW64 不支援放大 API;也就是說，32 位放大鏡應用程式無法在 64 位 Windows 上正確執行。

基本概念

本節說明放大 API 所依據的基本概念。其中包含下列部分：

放大鏡的類型
放大因數
色彩效果
來源矩形
篩選清單
輸入轉換
系統資料指標

放大鏡的類型

API 支援兩種類型的放大鏡： 全螢幕放大 鏡和 放大鏡控制項。全螢幕放大鏡會放大整個螢幕的內容，而放大鏡控制項則會放大螢幕的特定區域內容，並在視窗中顯示內容。對於放大鏡，影像和文字都會放大，而且兩者都可讓您控制放大的放大量。您也可以將色彩效果套用至放大的螢幕內容，讓擁有色彩不足或需要更多對比色彩的人員更容易看到。

重要

放大鏡控制項 API 適用于 Windows Vista 和更新版本的作業系統，而全螢幕放大鏡 API 僅適用于Windows 8和更新版本的作業系統。

放大因數

全螢幕放大鏡和放大鏡控制項都會套用縮放轉換來放大螢幕內容。縮放轉換所套用的放大量稱為 放大因數。它會以浮點值表示，其中 1.0 對應至無放大，而較大的值會導致對應的放大量。例如，值為 1.5 會使螢幕內容大於 50%。小於 1.0 的放大因數無效。

色彩效果

色彩效果是藉由將 5 到 5 個色彩轉換矩陣套用至放大畫面內容的色彩來達成。矩陣會決定內容的紅色、藍色、綠色和 Alpha 元件的濃度。如需詳細資訊，請參閱在 Windows GDI+ 檔中使用色彩矩陣轉換單一色彩。

來源矩形

全螢幕放大鏡會將縮放轉換和色彩轉換套用至整個螢幕。另一方面，放大鏡控制項會將稱為 來源矩形的螢幕區域複製到螢幕外點陣圖。接下來，控制項會將尺規轉換和色彩轉換套用至螢幕外點陣圖。最後，控制項會在放大鏡控制項視窗中顯示縮放和色彩轉換的點陣圖。

根據預設，放大鏡控制項會將指定來源矩形中的所有視窗放大。不過，藉由提供視窗控制碼的 篩選清單 ，您可以控制放大內容中包含哪些視窗，以及哪些視窗不是。如需詳細資訊，請參閱選擇性放大。

全螢幕放大鏡不支援篩選清單;它一律會放大螢幕上的所有視窗。

輸入轉換

一般而言，放大的螢幕內容對使用者畫筆或觸控輸入是「不可見」。例如，如果使用者點選控制項的放大影像，系統不一定會將輸入傳遞至控制項。相反地，如果任何) 位於未損毀桌面上點選的螢幕座標，系統會將輸入傳遞給任何專案 (。 MagSetInputTransform函式可讓您指定輸入轉換，將放大畫面內容的座標空間對應至實際 (未損毀) 螢幕座標空間。這可讓系統將放大畫面內容中輸入的畫筆或觸控輸入傳遞至螢幕上的正確 UI 元素。

注意

呼叫進程必須具有 UIAccess 許可權才能設定輸入轉換。如需詳細資訊，請參閱消費者介面自動化安全性考慮和/MANIFESTUAC (在資訊清單中內嵌 UAC 資訊) 。

系統資料指標

MagShowSystemCursor函式可讓您顯示或隱藏系統游標。如果您在全螢幕放大鏡作用中時顯示系統游標，系統游標一律會隨著螢幕內容的其餘部分放大。如果您在全螢幕放大鏡作用中時隱藏系統游標，系統游標完全看不到。

使用放大鏡控制項時， MagShowSystemCursor 函式會顯示或隱藏未放大的系統游標，但不會影響放大系統游標。放大系統游標的可見度取決於放大鏡控制項是否具有 MS_SHOWMAGNIFIEDCURSOR 樣式。如果具有此樣式，每當系統游標進入來源矩形時，放大鏡控制項就會顯示放大的系統游標以及放大畫面內容。

初始化放大鏡執行時間程式庫

您必須先呼叫 MagInitialize 函式來建立和初始化放大鏡執行時間物件，才能呼叫任何其他放大鏡 API 函式。同樣地，當您完成使用放大鏡 API 之後，請呼叫 MagUninitialize 函式來終結放大鏡執行時間物件，並釋放相關聯的系統資源。

使用Full-Screen放大鏡

若要使用全螢幕放大鏡，請呼叫 MagSetFullscreenTransform 函式。 magLevel參數會指定放大因數。 xOffset和yOffset參數會指定放大畫面內容相對於螢幕的位置。

當螢幕內容放大時，它就會變成大於螢幕本身。部分內容會延伸到螢幕邊緣之外，並讓使用者看不見。 MagSetFullscreenTransform函式的xOffset和yOffset參數會決定放大畫面內容的哪個部分出現在畫面上。參數會一起指定未放大螢幕內容中某個點的座標。當內容放大時，它會放在畫面左上角的指定點。

下列範例會設定全螢幕放大鏡的放大因數，並將放大畫面內容的中央放在螢幕中央。

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

使用 MagSetFullscreenColorEffect 函式，藉由設定應用程式定義的色彩轉換矩陣，將色彩效果套用至全螢幕內容。例如，下列範例會設定將色彩轉換成灰階的色彩轉換矩陣。

// 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 ? &amp;g_MagEffectGrayscale : &amp;g_MagEffectIdentity);

    return MagSetFullscreenColorEffect(pEffect);
}

您可以藉由呼叫 MagGetFullscreenTransform 函式來擷取目前的放大因數和位移值。您可以藉由呼叫 MagGetFullscreenColorEffect 函式來擷取目前的色彩轉換矩陣。

使用放大鏡控制項

放大鏡控制項會放大螢幕特定區域的內容，並在視窗中顯示內容。本節說明如何使用放大鏡控制項。它包含下列部分：

建立放大鏡控制項
初始化控制項
設定來源矩形
套用色彩效果
選擇性放大

建立放大鏡控制項

放大鏡控制項必須裝載在以WS_EX_LAYERED延伸樣式建立的視窗中。建立主機視窗之後，請呼叫 SetLayeredWindowAttributes 來設定主機視窗的不透明度。主機視窗通常會設定為完全不透明度，以防止基礎螢幕內容顯示。下列範例示範如何將主機視窗設定為完整不透明度：

SetLayeredWindowAttributes(hwndHost, NULL, 255, LWA_ALPHA);

如果您將 WS_EX_TRANSPARENT 樣式套用至主視窗，滑鼠按一下會傳遞至滑鼠游標位置上主視窗後方的任何物件。請注意，因為主視窗不會處理滑鼠點選，所以使用者將無法使用滑鼠移動或調整縮放視窗的大小。

放大鏡控制項視窗的視窗類別必須 WC_MAGNIFIER。如果您套用 MS_SHOWMAGNIFIEDCURSOR 樣式，放大鏡控制項會在放大畫面內容中包含系統游標，而游標會隨著螢幕內容一起放大。

建立放大鏡控制項之後，請保留視窗控制碼，以便將它傳遞至其他函式。

下列範例示範如何建立放大鏡控制項。

// 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(&amp;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;
}

初始化控制項

建立放大鏡控制項之後，您必須呼叫 MagSetWindowTransform 函式來指定放大因數。這只是指定矩陣的事項

(n、0.0、0.0)

(0.0、 n、0.0)

(0.0、0.0、1.0)

其中 n 是放大因數。

下列範例示範如何設定放大鏡控制項的放大因數。

// 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(&amp;matrix, 0, sizeof(matrix));
    matrix.v[0][0] = magFactor;
    matrix.v[1][1] = magFactor;
    matrix.v[2][2] = 1.0f;

    return MagSetWindowTransform(hwndMag, &amp;matrix);  
}

設定來源矩形

當使用者在螢幕周圍移動滑鼠游標時，您的應用程式會呼叫 MagSetWindowSource 函式，以指定要放大的基礎畫面部分。

下列範例函式會根據滑鼠位置和放大鏡視窗的維度除以放大因數) ，計算來源 (矩形的位置和維度，並據以設定來源矩形。函式也會將主視窗的工作區置中于滑鼠位置。此函式會依間隔呼叫，以更新放大視窗。

// 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(&amp;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;
}

套用色彩效果

具有 MS_INVERTCOLORS 樣式的放大鏡控制項會套用內建色彩轉換矩陣，以反轉放大螢幕內容的色彩。下圖顯示具有 MS_INVERTCOLORS 樣式的放大鏡控制項中的螢幕內容。

反轉色彩之放大內容的螢幕擷取畫面

MagSetColorEffect函式可讓您藉由設定應用程式定義的色彩轉換矩陣來套用其他色彩效果。例如，下列函式會設定將色彩轉換成灰階的色彩轉換矩陣。

// 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, &amp;magEffectGrayscale);
    }

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

如需色彩轉換運作方式的詳細資訊，請參閱 GDI+ 檔中使用色彩矩陣轉換單一色彩。

選擇性放大

根據預設，放大會套用至放大視窗本身以外的所有視窗。若要指定要放大的視窗，請呼叫 MagSetWindowFilterList 函式。這個方法會採用視窗清單來放大，或是要從放大中排除的視窗清單。

放大 API

放大 API 概觀

開始使用

基本概念

放大鏡的類型

放大因數

色彩效果

來源矩形

篩選清單

輸入轉換

系統資料指標

初始化放大鏡執行時間程式庫

使用Full-Screen放大鏡

使用放大鏡控制項

建立放大鏡控制項

初始化控制項

設定來源矩形

套用色彩效果

選擇性放大

意見反應

意見反應

其他資源

放大 API 概觀

開始使用

基本概念

放大鏡的類型

放大因數

色彩效果

來源矩形

篩選清單

輸入轉換

系統資料指標

初始化放大鏡執行時間程式庫

使用Full-Screen放大鏡

使用放大鏡控制項

建立放大鏡控制項

初始化控制項

設定來源矩形

套用色彩效果

選擇性放大

相關主題

意見反應

意見反應

其他資源