Metode IAccessible::accHitTest (oleacc.h)

Artikel
03/05/2024

Metode IAccessible::accHitTest mengambil elemen turunan atau objek turunan yang ditampilkan pada titik tertentu di layar. Semua objek visual mendukung metode ini, tetapi objek suara tidak. Aplikasi klien jarang memanggil metode ini secara langsung; untuk mendapatkan objek yang dapat diakses yang ditampilkan pada suatu titik, gunakan fungsi AccessibleObjectFromPoint , yang memanggil metode ini secara internal.

Sintaks

HRESULT accHitTest(
  [in]          long    xLeft,
  [in]          long    yTop,
  [out, retval] VARIANT *pvarChild
);

Parameter

[in] xLeft

Jenis: panjang

Menentukan koordinat layar titik yang diuji. Koordinat x meningkat dari kiri ke kanan. Perhatikan bahwa ketika koordinat layar digunakan, asalnya adalah sudut kiri atas layar.

[in] yTop

Jenis: panjang

Menentukan koordinat layar titik yang diuji. Koordinat y meningkat dari atas ke bawah. Perhatikan bahwa ketika koordinat layar digunakan, asalnya adalah sudut kiri atas layar.

[out, retval] pvarChild

Jenis: VARIAN*

[out, retval] Alamat VARIAN yang mengidentifikasi objek yang ditampilkan pada titik yang ditentukan oleh xLeft dan yTop. Informasi yang dikembalikan dalam pvarID tergantung pada lokasi titik yang ditentukan sehubungan dengan objek yang metode accHitTest-nya sedang dipanggil.

Lokasi titik	anggota vt	Anggota nilai
Di luar batas objek, dan baik di dalam atau di luar persegi panjang pembatas objek.	VT_EMPTY	Tidak ada.
Di dalam objek tetapi tidak dalam elemen turunan atau objek anak.	VT_I4	lVal CHILDID_SELF.
Dalam elemen turunan.	VT_I4	lVal berisi ID anak.
Dalam objek anak.	VT_DISPATCH	pdispVal diatur ke penunjuk antarmuka IDispatch objek anak

Nilai kembali

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.

Kesalahan	Deskripsi
S_FALSE	Titik berada di luar batas objek. Anggota vtpvarID VT_EMPTY.
DISP_E_MEMBERNOTFOUND	Objek tidak mendukung metode ini.
E_INVALIDARG	Argumen tidak valid.

Catatan untuk pengembang klien: Meskipun server mengembalikan S_FALSE jika anggota vt pvarID VT_EMPTY, klien juga harus menangani kasus di mana pvarID-vt> VT_EMPTY dan nilai yang dikembalikan S_OK.

Keterangan

Jika titik yang diuji ada pada salah satu anak objek, dan anak ini mendukung antarmuka IAccessible itu sendiri, metode ini harus mengembalikan penunjuk antarmuka IAccessible . Namun, klien harus siap untuk menangani penunjuk antarmuka IAccessible atau ID anak. Untuk informasi selengkapnya, lihat Cara ID Anak Digunakan dalam Parameter.

Karena accLocation mengembalikan persegi panjang pembatas, tidak semua titik dalam persegi panjang tersebut akan berada dalam batas objek yang sebenarnya. Beberapa titik dalam persegi panjang pembatas mungkin tidak ada pada objek . Untuk objek non-persegi panjang, seperti item tampilan daftar dalam mode ikon besar di mana satu item memiliki persegi panjang untuk ikon dan persegi panjang lain untuk teks ikon, koordinat persegi panjang pembatas objek yang diambil oleh IAccessible::accLocation bisa gagal jika diuji dengan accHitTest .

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.

Ketika metode ini digunakan dalam situasi tertentu, catatan penggunaan tambahan berlaku. Untuk informasi selengkapnya, lihat Navigasi Melalui Pengujian Hit dan Lokasi Layar.

Contoh Server

Contoh kode berikut menunjukkan kemungkinan implementasi untuk kotak daftar kustom.


// m_pControl is the control that returns this accessible object. 
// m_hwnd is the HWND of the control window. 
//  
HRESULT STDMETHODCALLTYPE AccServer::accHitTest( 
    long xLeft,
    long yTop,
    VARIANT *pvarChild) 

{
    POINT pt;
    pt.x = xLeft;
    pt.y = yTop;

    // Not in our window. 
    if (WindowFromPoint(pt) != m_hwnd)
    {
        pvarChild->vt = VT_EMPTY;
        return S_FALSE;
    }

    else  // In our window; return list item, or self if in blank space. 
    {
        pvarChild->vt = VT_I4;
        ScreenToClient(m_hwnd, &pt);
        // IndexFromY returns the 0-based index of the item at that point, 
        // or -1 if the point is not on any item.
        int index = m_pControl->IndexFromY(pt.y);
        if (index >= 0)
        {
            // Increment, because the child array is 1-based. 
            pvarChild->lVal = index + 1;
        }
        else
        {
            pvarChild->lVal = CHILDID_SELF;

        }
        return S_OK;
    }
};

Contoh Klien

Contoh fungsi berikut memilih item pada titik tertentu pada layar dalam daftar yang diwakili oleh pAcc. Diasumsikan bahwa satu pilihan diinginkan.


HRESULT SelectItemAtPoint(IAccessible* pAcc, POINT point)
{
    if (pAcc == NULL)
    {
        return E_INVALIDARG;
    }
    VARIANT varChild;

    HRESULT hr = pAcc->accHitTest(point.x, point.y, &varChild);        
    if ((hr == S_OK) && (varChild.lVal != CHILDID_SELF))
    {
        return pAcc->accSelect((SELFLAG_TAKEFOCUS | SELFLAG_TAKESELECTION), varChild);
    }
    return S_FALSE;
}

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