ホーム › UI.Accessibility › AccessibleChildren

AccessibleChildren

関数

アクセシブルコンテナの子要素一覧を取得する。

DLLOLEACC.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// OLEACC.dll
#include <windows.h>

HRESULT AccessibleChildren(
    IAccessible* paccContainer,
    INT iChildStart,
    INT cChildren,
    VARIANT* rgvarChildren,
    INT* pcObtained
);

パラメーター

名前	型	方向	説明
paccContainer	IAccessible*	in	コンテナーオブジェクトの IAccessible インターフェイスへのポインター。
iChildStart	INT	in	取得する最初の子の 0 から始まるインデックスを指定します。このパラメーターはインデックスであり、子 ID ではありません。通常は 0 に設定します。
cChildren	INT	in	取得する子の数を指定します。現在の子の数を取得するには、アプリケーションは IAccessible::get_accChildCount を呼び出します。
rgvarChildren	VARIANT*	out	コンテナーの子に関する情報を受け取る VARIANT 構造体の配列へのポインター。配列要素の vt メンバーが VT_I4 の場合、その要素の lVal メンバーが子 ID です。配列要素の vt メンバーが VT_DISPATCH の場合、その要素の pdispVal メンバーは子オブジェクトの IDispatch インターフェイスのアドレスです。
pcObtained	INT*	out	AccessibleChildren 関数によって設定された rgvarChildren 配列の要素数を受け取る変数のアドレス。この値は cChildren パラメーターの値と同じですが、実際に存在する数より多くの子を要求した場合、この値は cChildren の値より小さくなります。

戻り値の型: HRESULT

公式ドキュメント

アクセシブルなコンテナーオブジェクト内にある各子要素の子 ID または IDispatch を取得します。

戻り値

型: STDAPI

成功した場合は S_OK を返します。

失敗した場合は、次のいずれか、またはその他の標準的な COM エラーコードを返します。

戻り値	説明
E_INVALIDARG	引数が有効ではありません。
S_FALSE	関数は成功しましたが、rgvarChildren 配列内の要素数が、cChildren で要求された子の数より少なくなっています。

解説(Remarks)

コンテナー内のすべての子に関する情報を取得するには、iChildStart パラメーターを 0 にし、cChildren に IAccessible::get_accChildCount が返した値を指定する必要があります。

ユーザーインターフェイス要素の子に関する情報を取得するためにこの関数を呼び出す場合、クライアントはすべての子の情報を取得することをお勧めします。つまり、iChildStart を 0 にし、cChildren に IAccessible::get_accChildCount が返した値を指定します。

ある要素に対して子 ID が返された場合、その子要素に関する情報はコンテナーが提供する必要があります。要素の情報を取得するには、クライアントはコンテナーの IAccessible インターフェイスポインターを使用し、取得した子 ID を指定して IAccessible のプロパティを呼び出します。

クライアントは、この関数で取得したすべての IDispatch インターフェイスに対して IUnknown::Release メソッドを呼び出し、配列が不要になった時点で解放する必要があります。

例

次のサンプル関数は、渡された要素の配下にある要素ツリーを表示します。各要素の名前とロールは、ここには示していないユーザー定義関数によって出力されます。


HRESULT WalkTreeWithAccessibleChildren(IAccessible* pAcc, int depth)
{
    HRESULT hr;
    long childCount;
    long returnCount;

    if (!pAcc)
    {
        return E_INVALIDARG;
    }
    hr = pAcc->get_accChildCount(&childCount);
    if (FAILED(hr))
    {
        return hr;
    };
    if (childCount == 0)
    {
        return S_FALSE;
    }
    VARIANT* pArray = new VARIANT[childCount];
    hr = AccessibleChildren(pAcc, 0L, childCount, pArray, &returnCount);
    if (FAILED(hr))
    {
        return hr;
    };

    // 子を順に処理する。
    for (int x = 0; x < returnCount; x++)
    {
        VARIANT vtChild = pArray[x];
        // アクセシブルオブジェクトであれば IAccessible を取得し、再帰する。
        if (vtChild.vt == VT_DISPATCH)
        {
            IDispatch* pDisp = vtChild.pdispVal;
            IAccessible* pChild = NULL;
            hr = pDisp->QueryInterface(IID_IAccessible, (void**) &pChild);
            if (hr == S_OK)
            {
                for (int y = 0; y < depth; y++)
                {
                    printf("  ");
                }
                PrintName(pChild, CHILDID_SELF);
                printf("(Object) ");
                PrintRole(pChild, CHILDID_SELF);
                WalkTreeWithAccessibleChildren(pChild, depth + 1);
                pChild->Release();
            }
            pDisp->Release();
        }
        // そうでない場合は子要素なので、親に対して accNavigate を呼び出す必要がある。
        //   また、子要素はさらに子を持てないため再帰しない。
        else
        {
            for (int y = 0; y < depth; y++)
            {
                printf("  ");
            }
            PrintName(pAcc, vtChild.lVal);
            printf("(Child element) ");
            PrintRole(pAcc, vtChild.lVal);
        }
    }
    delete[] pArray;
    return S_OK;
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// OLEACC.dll
#include <windows.h>

HRESULT AccessibleChildren(
    IAccessible* paccContainer,
    INT iChildStart,
    INT cChildren,
    VARIANT* rgvarChildren,
    INT* pcObtained
);

[DllImport("OLEACC.dll", ExactSpelling = true)]
static extern int AccessibleChildren(
    IntPtr paccContainer,   // IAccessible*
    int iChildStart,   // INT
    int cChildren,   // INT
    IntPtr rgvarChildren,   // VARIANT* out
    out int pcObtained   // INT* out
);

<DllImport("OLEACC.dll", ExactSpelling:=True)>
Public Shared Function AccessibleChildren(
    paccContainer As IntPtr,   ' IAccessible*
    iChildStart As Integer,   ' INT
    cChildren As Integer,   ' INT
    rgvarChildren As IntPtr,   ' VARIANT* out
    <Out> ByRef pcObtained As Integer   ' INT* out
) As Integer
End Function

' paccContainer : IAccessible*
' iChildStart : INT
' cChildren : INT
' rgvarChildren : VARIANT* out
' pcObtained : INT* out
Declare PtrSafe Function AccessibleChildren Lib "oleacc" ( _
    ByVal paccContainer As LongPtr, _
    ByVal iChildStart As Long, _
    ByVal cChildren As Long, _
    ByVal rgvarChildren As LongPtr, _
    ByRef pcObtained As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

AccessibleChildren = ctypes.windll.oleacc.AccessibleChildren
AccessibleChildren.restype = ctypes.c_int
AccessibleChildren.argtypes = [
    ctypes.c_void_p,  # paccContainer : IAccessible*
    ctypes.c_int,  # iChildStart : INT
    ctypes.c_int,  # cChildren : INT
    ctypes.c_void_p,  # rgvarChildren : VARIANT* out
    ctypes.POINTER(ctypes.c_int),  # pcObtained : INT* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLEACC.dll')
AccessibleChildren = Fiddle::Function.new(
  lib['AccessibleChildren'],
  [
    Fiddle::TYPE_VOIDP,  # paccContainer : IAccessible*
    Fiddle::TYPE_INT,  # iChildStart : INT
    Fiddle::TYPE_INT,  # cChildren : INT
    Fiddle::TYPE_VOIDP,  # rgvarChildren : VARIANT* out
    Fiddle::TYPE_VOIDP,  # pcObtained : INT* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "oleacc")]
extern "system" {
    fn AccessibleChildren(
        paccContainer: *mut core::ffi::c_void,  // IAccessible*
        iChildStart: i32,  // INT
        cChildren: i32,  // INT
        rgvarChildren: *mut VARIANT,  // VARIANT* out
        pcObtained: *mut i32  // INT* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLEACC.dll")]
public static extern int AccessibleChildren(IntPtr paccContainer, int iChildStart, int cChildren, IntPtr rgvarChildren, out int pcObtained);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLEACC_AccessibleChildren' -Namespace Win32 -PassThru
# $api::AccessibleChildren(paccContainer, iChildStart, cChildren, rgvarChildren, pcObtained)

#uselib "OLEACC.dll"
#func global AccessibleChildren "AccessibleChildren" sptr, sptr, sptr, sptr, sptr
; AccessibleChildren paccContainer, iChildStart, cChildren, varptr(rgvarChildren), varptr(pcObtained)   ; 戻り値は stat
; paccContainer : IAccessible* -> "sptr"
; iChildStart : INT -> "sptr"
; cChildren : INT -> "sptr"
; rgvarChildren : VARIANT* out -> "sptr"
; pcObtained : INT* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLEACC.dll"
#cfunc global AccessibleChildren "AccessibleChildren" sptr, int, int, var, var
; res = AccessibleChildren(paccContainer, iChildStart, cChildren, rgvarChildren, pcObtained)
; paccContainer : IAccessible* -> "sptr"
; iChildStart : INT -> "int"
; cChildren : INT -> "int"
; rgvarChildren : VARIANT* out -> "var"
; pcObtained : INT* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLEACC.dll"
#cfunc global AccessibleChildren "AccessibleChildren" sptr, int, int, sptr, sptr
; res = AccessibleChildren(paccContainer, iChildStart, cChildren, varptr(rgvarChildren), varptr(pcObtained))
; paccContainer : IAccessible* -> "sptr"
; iChildStart : INT -> "int"
; cChildren : INT -> "int"
; rgvarChildren : VARIANT* out -> "sptr"
; pcObtained : INT* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。