拡大 API の概要

[アーティクル]
06/13/2023

拡大 API を使用すると、支援技術ベンダーは、Microsoft Windows で実行される画面拡大アプリケーションを開発できます。このトピックでは、拡大 API について説明し、アプリケーションで使用する方法について説明します。次のセクションが含まれます。

はじめに
基本的な概念
拡大鏡ランタイムライブラリの初期化
Full-Screen拡大鏡の使用
拡大鏡コントロールの使用
関連トピック

作業の開始

拡大 API の元のリリースは、Windows Vista 以降のオペレーティングシステムでサポートされています。 Windows 8以降では、API では、全画面表示の拡大や拡大されたシステムカーソルの可視性の設定など、追加機能がサポートされています。

拡大 API のサポートは、Magnification.dllによって提供されます。アプリケーションをコンパイルするには、Magnification.h と Magnification.lib へのリンクを含めます。

Note

拡大 API は WOW64 ではサポートされていません。つまり、32 ビット拡大鏡アプリケーションは 64 ビット Windows で正しく実行されません。

基本的な概念

このセクションでは、拡大 API の基礎となる基本的な概念について説明します。これには、次の部分が含まれています。

拡大鏡の種類
倍率
色の効果
ソース四角形
フィルターリスト
入力変換
システムカーソル

拡大鏡の種類

API では、全画面表示拡大鏡と拡大鏡コントロールの 2 種類の拡大鏡がサポートされています。全画面拡大鏡は画面全体のコンテンツを拡大し、拡大鏡コントロールは画面の特定の領域のコンテンツを拡大し、ウィンドウにコンテンツを表示します。拡大鏡では、画像とテキストの両方が拡大され、拡大の量を制御できます。また、拡大画面のコンテンツに色効果を適用して、色の不備がある人や、コントラストが多いか少ない色が必要な人を見やすくすることもできます。

重要

拡大鏡コントロール API は Windows Vista 以降のオペレーティングシステムで使用できます。一方、全画面表示拡大鏡 API はWindows 8以降のオペレーティングシステムでのみ使用できます。

倍率

全画面表示拡大鏡と拡大鏡コントロールの両方で、画面コンテンツを拡大するためにスケール変換が適用されます。スケール変換によって適用される倍率を 倍率と呼びます。 1.0 は倍率に対応せず、値を大きくすると、対応する倍率になる浮動小数点値として表されます。たとえば、値が 1.5 の場合、画面コンテンツは 50% 大きくなります。 1.0 未満の倍率は無効です。

色の効果

色効果は、拡大された画面コンテンツの色に 5 対 5 の色変換マトリックスを適用することによって実現されます。マトリックスは、コンテンツの赤、青、緑、アルファの各成分の強度を決定します。詳細については、Windows GDI+ ドキュメントの「カラーマトリックスを使用して単一色を変換する」を参照してください。

ソース四角形

全画面表示拡大鏡は、スケール変換と色変換を画面全体に適用します。一方、拡大鏡コントロールは、 ソース四角形と呼ばれる画面領域を画面外ビットマップにコピーします。次に、コントロールはスケール変換とカラー変換 (存在する場合) をオフスクリーンビットマップに適用します。最後に、拡大鏡コントロールウィンドウに、拡大縮小および色変換されたビットマップがコントロールに表示されます。

既定では、拡大鏡コントロールは、指定したソース四角形内のすべてのウィンドウを拡大します。ただし、ウィンドウハンドルの フィルターリスト を指定することで、拡大コンテンツに含めるウィンドウと含まれないウィンドウを制御できます。詳細については、「選択的拡大」を参照してください。

全画面表示拡大鏡はフィルターリストをサポートしていません。それは常に画面上のすべてのウィンドウを拡大します。

入力変換

通常、拡大された画面コンテンツは、ユーザーのペンやタッチ入力に対して "非表示" になります。たとえば、ユーザーがコントロールの拡大画像をタップした場合、システムは必ずしも入力をコントロールに渡すとは限りません。代わりに、システムは、(存在する場合)、イメージ化されていないデスクトップ上のタップされた画面座標に存在する任意の項目に入力を渡します。 MagSetInputTransform 関数を使用すると、拡大画面コンテンツの座標空間を実際の (未イメージの) 画面座標空間にマップする入力変換を指定できます。これにより、拡大画面コンテンツに入力されたペンまたはタッチ入力を、画面上の正しい UI 要素に渡すことができます。

Note

呼び出し元のプロセスには、入力変換を設定するための UIAccess 権限が必要です。詳細については、「UI オートメーションセキュリティに関する考慮事項」および「/MANIFESTUAC (マニフェストに UAC 情報を埋め込む)」を参照してください。

システムカーソル

MagShowSystemCursor 関数を使用すると、システムカーソルを表示または非表示にすることができます。全画面表示拡大鏡がアクティブなときにシステムカーソルを表示すると、システムカーソルは常に画面コンテンツの残りの部分と共に拡大されます。全画面表示拡大鏡がアクティブのときにシステムカーソルを非表示にすると、システムカーソルはまったく表示されません。

拡大鏡コントロールを使用すると、 MagShowSystemCursor 関数は、イメージ化されていないシステムカーソルを表示または非表示にしますが、拡大されたシステムカーソルには影響しません。拡大システムカーソルの表示は、拡大鏡コントロールに MS_SHOWMAGNIFIEDCURSOR スタイルがあるかどうかによって異なります。このスタイルの場合、拡大鏡コントロールは、システムカーソルがソース四角形に入るたびに、拡大されたシステムカーソルと拡大画面の内容を表示します。

拡大鏡ランタイムライブラリの初期化

他の拡大鏡 API 関数を呼び出すには、 MagInitialize 関数を呼び出して拡大鏡ランタイムオブジェクトを作成して初期化する必要があります。同様に、拡大鏡 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 スタイルをホストウィンドウに適用すると、マウスカーソルの位置にあるホストウィンドウの背後にあるオブジェクトにマウスクリックが渡されます。ホストウィンドウではマウスのクリックが処理されないため、ユーザーはマウスを使用して拡大ウィンドウを移動またはサイズ変更できないことに注意してください。

拡大鏡コントロールウィンドウの window クラスは 、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 関数を呼び出します。このメソッドは、拡大するウィンドウの一覧、または拡大から除外するウィンドウの一覧を受け取ります。

Magnification API

拡大 API の概要

作業の開始

基本的な概念

拡大鏡の種類

倍率

色の効果

ソース四角形

フィルターリスト

入力変換

システムカーソル

拡大鏡ランタイムライブラリの初期化

Full-Screen拡大鏡の使用

拡大鏡コントロールの使用

拡大鏡コントロールの作成

コントロールの初期化

ソース四角形の設定

色効果の適用

選択倍率

フィードバック

フィードバック

その他のリソース

拡大 API の概要

作業の開始

基本的な概念

拡大鏡の種類

倍率

色の効果

ソース四角形

フィルター リスト

入力変換

システム カーソル

拡大鏡ランタイム ライブラリの初期化

Full-Screen拡大鏡の使用

拡大鏡コントロールの使用

拡大鏡コントロールの作成

コントロールの初期化

ソース四角形の設定

色効果の適用

選択倍率

関連トピック

フィードバック

フィードバック

その他のリソース

フィルターリスト

システムカーソル

拡大鏡ランタイムライブラリの初期化