Metode IAccessible::accNavigate (oleacc.h)

Artikel
03/08/2023

Metode IAccessible::accNavigate melintasi elemen UI lain dalam kontainer dan mengambil objek . Metode ini bersifat opsional.

Catatan Metode accNavigate tidak digunakan lagi dan tidak boleh digunakan. Klien harus menggunakan metode dan properti lain seperti AccessibleChildren, get_accChild, get_accParent, dan IEnumVARIANT.

Sintaks

HRESULT accNavigate(
  [in]          long    navDir,
  [in]          VARIANT varStart,
  [out, retval] VARIANT *pvarEndUpAt
);

Parameter

[in] navDir

Jenis: panjang

Menentukan arah untuk menavigasi. Arah ini dalam urutan spasial , seperti kiri atau kanan, atau urutan logis , seperti berikutnya atau sebelumnya. Nilai ini adalah salah satu konstanta navigasi.

[in] varStart

Jenis: VARIAN

Menentukan apakah objek awal navigasi adalah objek itu sendiri atau salah satu anak objek. Parameter ini CHILDID_SELF (untuk memulai dari objek) atau ID anak (untuk memulai dari salah satu elemen turunan objek). Untuk informasi selengkapnya tentang menginisialisasi VARIAN, lihat Cara ID Anak Digunakan dalam Parameter.

[out, retval] pvarEndUpAt

Jenis: VARIAN*

[out, retval] Alamat struktur VARIAN yang menerima informasi tentang objek tujuan. Tabel berikut ini menjelaskan informasi yang dikembalikan dalam pvarEnd.

anggota vt	Anggota nilai
VT_EMPTY	Tidak ada. Tidak ada elemen UI dalam arah yang ditentukan.
VT_I4	lVal berisi ID anak dari elemen UI.
VT_DISPATCH	pdispVal berisi alamat IDispatch elemen UI.

Mengembalikan nilai

Jenis: HRESULT

Jika berhasil, mengembalikan S_OK.

Jika tidak berhasil, mengembalikan salah satu nilai dalam tabel berikut, atau kode kesalahan COM standar lainnya. Server mengembalikan nilai-nilai ini, tetapi klien harus selalu memeriksa parameter output untuk memastikan bahwa nilai tersebut berisi nilai yang valid. Untuk informasi selengkapnya, lihat Memeriksa Nilai Pengembalian IAccessible dan Mengembalikan Nilai.

Kesalahan	Deskripsi
S_FALSE	Tidak ada elemen layar yang ditemukan dalam arah yang ditentukan.
DISP_E_MEMBERNOTFOUND	Objek tidak mendukung metode ini.
E_INVALIDARG	Argumen tidak valid.

Keterangan

Navigasi, baik spasial maupun logis, selalu dibatasi untuk elemen UI dalam kontainer. Dengan navigasi spasial, klien hanya menavigasi ke saudara kandung dari objek awal (varStart). Bergantung pada bendera navigasi yang digunakan dengan navigasi logis, klien menavigasi ke anak atau ke saudara kandung dari objek awal.

Metode accNavigate mengambil elemen UI yang memiliki lokasi layar yang ditentukan, dan objek yang tidak terlihat yang tidak memiliki lokasi layar yang ditentukan.

Metode ini tidak mengubah pilihan atau fokus. Untuk mengubah fokus atau memilih objek, gunakan IAccessible::accSelect.

Untuk mencegah perulangan saat melintasi elemen layar, accNavigate mengembalikan S_FALSE dengan VT_EMPTY saat Anda menentukan NAVDIR_NEXT pada elemen terakhir, atau NAVDIR_PREVIOUS pada elemen pertama.

Seperti metode dan fungsi IAccessible lainnya, klien mungkin menerima kesalahan untuk penunjuk antarmuka IAccessible karena tindakan pengguna. Untuk informasi selengkapnya, lihat Menerima Kesalahan untuk Penunjuk Antarmuka IAccessible.

Beberapa elemen UI yang ditentukan sistem seperti menu, item menu, dan menu pop-up memungkinkan navigasi ke objek yang tidak terlihat. Namun, elemen UI lain yang ditentukan sistem tidak mendukung ini. Server dapat memilih apakah akan mendukung navigasi ke objek yang tidak terlihat dan dapat melewati atau mengeksposnya.

Aplikasi klien harus mengembalikan nilai pengembalian pasca-proses saat menggunakan accNavigate untuk menavigasi antar objek. Tujuan dari langkah-langkah pasca-pemrosesan adalah untuk memberi klien penunjuk antarmuka IAccessible dan ID anak sehingga mereka dapat menggunakan metode dan properti IAccessible untuk elemen UI.

Tabel berikut ini menjelaskan kemungkinan skenario untuk IAccessible::accNavigate, berdasarkan kriteria berikut:

Titik awal yang ditentukan (baik Anda memulai dengan objek penuh atau elemen sederhana)
Hasilnya dikembalikan ( IDispatch atau ID anak VT_I4)
Pasca-pemrosesan yang perlu dilakukan aplikasi klien untuk memiliki penunjuk antarmuka IAccessible dan ID anak

Untuk tabel ini, asumsikan bahwa startID dan endID adalah ID anak VT_I4 (elemen sederhana), dan pStartAcc dan pEndAcc VT_I4 dengan CHILDID_SELF (objek lengkap).

Tabel ini menjelaskan bendera NAVDIR_ berikut: NEXT, PREVIOUS, LEFT, RIGHT, UP, dan DOWN. Untuk informasi selengkapnya tentang bendera navigasi, lihat Konstanta Navigasi.

Titik awal	Hasil dikembalikan	Pasca-pemrosesan untuk nilai yang dikembalikan
pStartAcc, startID	VT_I4 endID	Panggil get_accChild di pStartAcc passing endID. Ikuti prosedur normal yang diuraikan dalam get_accChild.
pStartAcc, startID	VT_DISPATCH pEndAcc	Gunakan prosedur standar untuk mengonversi penunjuk antarmuka IDispatch ke penunjuk antarmuka IAccessible untuk pEndAcc.
pStartAcc, CHILDID_SELF	VT_I4 endID	Panggil get_accParent di pStartAcc, melewati CHILDID_SELF untuk mendapatkan penunjuk antarmuka IAccessible induk untuk endID. Kemudian, panggil get_accChild pada penunjuk antarmuka IAccessible , melewati endID. Ikuti prosedur normal yang diuraikan dalam get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Gunakan prosedur standar untuk mengonversi penunjuk antarmuka IDispatch ke penunjuk antarmuka IAccessible untuk pEndAcc.

Tabel berikut ini menjelaskan bendera navigasi NAVDIR_FIRSTCHILD dan NAVDIR_LASTCHILD. Ini tidak termasuk entri untuk menavigasi ke anak pertama atau terakhir ketika titik awal adalah elemen sederhana karena elemen sederhana tidak dapat memiliki anak.

Titik awal	Hasil dikembalikan	Pasca-pemrosesan untuk nilai yang dikembalikan
pStartAcc, CHILDID_SELF	VT_I4 endID	Panggil get_accChild di pStartAcc, melewati endID. Ikuti prosedur normal yang diuraikan dalam get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Gunakan prosedur standar untuk mengonversi penunjuk antarmuka IDispatch ke penunjuk antarmuka IAccessible untuk pEndAcc.

Untuk informasi selengkapnya, lihat Properti dan Metode Navigasi Objek.

Contoh Server

Contoh berikut menunjukkan kemungkinan implementasi metode untuk kotak daftar kustom yang item daftarnya adalah elemen anak.


// m_pControl is the control that returns this accessible object. 
// m_pStdAccessibleObject is the standard accessible object for the window 
//    that contains the control. 

HRESULT STDMETHODCALLTYPE AccServer::accNavigate( 
    long navDir,
    VARIANT varStart,
    VARIANT *pvarEndUpAt)
{
    // Default value. 
    pvarEndUpAt->vt = VT_EMPTY;

    if (varStart.vt != VT_I4)
    {
        return E_INVALIDARG;
    }

    switch (navDir)
    {
    case NAVDIR_FIRSTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = 1;
        }
        else  // Starting with child. 
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_LASTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = m_pControl->GetCount();
        }
        else  // Starting with child.           
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_NEXT:   
    case NAVDIR_DOWN:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal + 1;
            // Out of range. 
            if (pvarEndUpAt->lVal > m_pControl->GetCount())
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

    case NAVDIR_PREVIOUS:
    case NAVDIR_UP:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal - 1;
            // Out of range. 
            if (pvarEndUpAt->lVal <1)
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

     // Unsupported directions. 
    case NAVDIR_LEFT:
    case NAVDIR_RIGHT:
        if (varStart.lVal == CHILDID_SELF)
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        else 
        {
            pvarEndUpAt->vt = VT_EMPTY;
            return S_FALSE;
        }
        break;
    }
    return S_OK;
};

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	oleacc.h
Pustaka	Oleacc.lib
DLL	Oleacc.dll
Redistribusi	Aksesibilitas Aktif 1.3 RDK pada Windows NT 4.0 dengan SP6 dan yang lebih baru dan Windows 95