Metode IViewObjectEx::QueryHitPoint (ocidl.h)

Artikel
03/05/2024

Menunjukkan apakah titik berada dalam aspek tertentu dari objek.

Sintaks

HRESULT QueryHitPoint(
  [in]  DWORD   dwAspect,
  [in]  LPCRECT pRectBounds,
  [in]  POINT   ptlLoc,
  [in]  LONG    lCloseHint,
  [out] DWORD   *pHitResult
);

Parameter

[in] dwAspect

Aspek gambar yang diminta.

[in] pRectBounds

Persegi panjang pembatas objek dalam koordinat klien dari jendela yang berisi. Persegi panjang ini dihitung dan diteruskan oleh kontainer sehingga objek dapat secara bermakna menafsirkan lokasi hit.

[in] ptlLoc

Lokasi hit dalam koordinat klien dari jendela yang berisi.

[in] lCloseHint

Jarak yang disarankan dalam unit HIMETRIC yang dianggap dekat oleh kontainer. Nilai ini adalah petunjuk, dan objek dapat menafsirkannya dengan cara mereka sendiri. Objek juga dapat menggunakan petunjuk ini untuk menyimpulkan resolusi output secara kasar untuk memilih ekspansi implementasi uji hit.

[out] pHitResult

Pointer untuk mengembalikan informasi tentang hit yang dinyatakan sebagai nilai enumerasi HITRESULT .

Nilai kembali

Metode ini mengembalikan S_OK pada keberhasilan. Kemungkinan nilai pengembalian lainnya termasuk yang berikut ini.

Menampilkan kode	Deskripsi
E_FAIL	Metode ini tidak diimplementasikan untuk aspek yang diminta. Gunakan DVASPECT_CONTENT sebagai gantinya.

Keterangan

Untuk mendukung deteksi hit pada objek non-persegi panjang, kontainer membutuhkan cara yang dapat diandalkan untuk menanyakan objek apakah lokasi tertentu berada di dalam salah satu aspek gambarnya. Fungsi ini disediakan oleh IViewObjectEx::QueryHitPoint.

Catatan Karena metode ini adalah bagian dari antarmuka IViewObjectEx , kontainer dapat mengetahui apakah tetikus mengenai objek tanpa harus meluncurkan server. Jika hit terjadi di dalam objek, maka kemungkinan objek akan diaktifkan di tempat dan server dimulai.

Biasanya, kontainer terlebih dahulu dengan cepat menentukan apakah lokasi tertentu berada dalam jangkauan persegi panjang objek. Jika lokasi berada dalam jangkauan persegi panjang objek, kontainer memanggil IViewObjectEx::QueryHitPoint untuk mendapatkan konfirmasi bahwa lokasi sebenarnya berada di dalam objek. Lokasi hit diteruskan dalam koordinat klien jendela kontainer. Karena objek mungkin tidak aktif ketika metode ini dipanggil, persegi panjang pembatas objek dalam sistem koordinat yang sama juga diteruskan ke metode ini, mirip dengan apa yang terjadi di IPointerInactive::OnInactiveSetCursor.

Kemungkinan nilai yang dikembalikan meliputi:

Di luar, pada wilayah transparan
Cukup dekat untuk dianggap sebagai hit (dapat digunakan oleh objek kecil atau tipis)
Memukul

IViewObjectEx::QueryHitPoint tidak khawatir dengan sub-objek objek yang dipanggilnya. Ini hanya menunjukkan apakah tetikus mengenai berada di dalam objek atau tidak.

IViewObjectEx::QueryHitPoint dapat dipanggil untuk salah satu aspek gambar yang didukung objek. Ini harus gagal jika tidak didukung untuk aspek gambar yang diminta.

Objek transparan mungkin ingin menerapkan mekanisme deteksi hit kompleks di mana pengguna dapat memilih objek transparan atau objek di belakangnya, tergantung di mana tepatnya klik terjadi di dalam objek. Misalnya, kotak teks transparan yang menunjukkan teks yang cukup besar dapat memungkinkan pengguna memilih objek di belakang, misalnya, bitmap, saat pengguna mengklik di antara karakter. Untuk alasan ini, informasi yang dikembalikan oleh IViewObjectEx::QueryHitPoint menyertakan indikasi tentang apakah temuan terjadi pada wilayah buram atau transparan.

Contoh deteksi hit non-persegi panjang dan transparan adalah kontrol lingkaran transparan dengan objek di belakangnya (garis dalam contoh di bawah):

Diagram lingkaran dengan garis diagonal melaluinya, memperlihatkan nilai deteksi hit untuk area di dalam dan di luar lingkaran dan di dekat garis.

Nilai yang ditampilkan adalah untuk pengujian hit terhadap lingkaran; wilayah abu-abu bukan bagian dari kontrol, tetapi ditunjukkan di sini untuk menunjukkan area di sekitar gambar yang dianggap dekat. Setiap objek menerapkan definisinya sendiri dari dekat tetapi dibantu oleh petunjuk yang disediakan oleh kontainer sehingga kedekatan dapat disesuaikan saat gambar zoom lebih besar atau lebih kecil.

Pada gambar di atas, titik yang ditandai Hit, Close, dan Transparent semuanya akan menjadi hit dengan berbagai kekuatan pada lingkaran, dengan pengecualian yang ditandai Transparan, (tetapi untuk garis, tutup). Ini menggambarkan efek dari berbagai kekuatan hit. Karena lingkaran merespons transparan saat klaim garis ditutup, dan transparan lebih lemah dari dekat, garis mengambil hit.

Catatan untuk Pelaksana

Objek yang mendukung IViewObjectEx diperlukan untuk menerapkan metode ini setidaknya untuk aspek DVASPECT_CONTENT . Objek tidak boleh mengambil tindakan lain sebagai respons terhadap metode ini selain mengembalikan informasi; seharusnya tidak ada efek samping.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	ocidl.h

Lihat juga

HITRESULT

IPointerInactive::OnInactiveSetCursor

IViewObjectEx

Bagikan melalui