Metode IViewObject::D raw (oleidl.h)

Artikel
03/15/2023

Menggambar representasi objek ke konteks perangkat yang ditentukan.

Sintaks

HRESULT Draw(
  [in] DWORD                          dwDrawAspect,
  [in] LONG                           lindex,
  [in] void                           *pvAspect,
  [in] DVTARGETDEVICE                 *ptd,
  [in] HDC                            hdcTargetDev,
  [in] HDC                            hdcDraw,
  [in] LPCRECTL                       lprcBounds,
  [in] LPCRECTL                       lprcWBounds,
  [in] BOOL(* )(ULONG_PTR dwContinue) pfnContinue,
  [in] ULONG_PTR                      dwContinue
);

Parameter

[in] dwDrawAspect

Menentukan aspek yang akan digambar, yaitu bagaimana objek akan diwakili. Representasi mencakup konten, ikon, gambar mini, atau dokumen cetak. Nilai yang valid diambil dari enumerasi DVASPECT dan DVASPECT2. Perhatikan bahwa objek dan kontainer yang lebih baru yang mendukung antarmuka gambar yang dioptimalkan mendukung nilai enumerasi DVASPECT2 . Objek dan kontainer lama yang tidak mendukung antarmuka gambar yang dioptimalkan mungkin tidak mendukung DVASPECT2. Objek tanpa jendela hanya mengizinkan DVASPECT_CONTENT, DVASPECT_OPAQUE, dan DVASPECT_TRANSPARENT.

[in] lindex

Bagian dari objek yang menarik untuk operasi gambar. Interpretasinya bervariasi tergantung pada nilai dalam parameter dwAspect. Lihat enumerasi DVASPECT untuk informasi selengkapnya.

[in] pvAspect

Arahkan ke informasi tambahan dalam struktur DVASPECTINFO yang memungkinkan pengoptimalan gambar tergantung pada aspek yang ditentukan. Perhatikan bahwa objek dan kontainer yang lebih baru yang mendukung antarmuka gambar yang dioptimalkan juga mendukung parameter ini. Objek dan kontainer lama yang tidak mendukung antarmuka gambar yang dioptimalkan selalu menentukan NULL untuk parameter ini.

[in] ptd

Arahkan ke struktur DVTARGETDEVICE yang menjelaskan perangkat yang objeknya akan dirender. Jika NULL, tampilan harus dirender untuk perangkat target default (biasanya tampilan). Nilai selain NULL ditafsirkan bersama dengan hdcTargetDev dan hdcDraw. Misalnya, jika hdcDraw menentukan printer sebagai konteks perangkat, parameter ptd menunjuk ke struktur yang menjelaskan perangkat printer tersebut. Data sebenarnya dapat dicetak jika hdcTargetDev adalah nilai yang valid atau mungkin ditampilkan dalam mode pratinjau cetak jika hdcTargetDev adalah NULL.

[in] hdcTargetDev

Konteks informasi untuk perangkat target yang ditunjukkan oleh parameter ptd tempat objek dapat mengekstrak metrik perangkat dan menguji kemampuan perangkat. Jika ptd adalah NULL; objek harus mengabaikan nilai dalam parameter hdcTargetDev .

[in] hdcDraw

Konteks perangkat yang akan digambar. Untuk objek tanpa jendela, parameter hdcDraw harus dalam mode pemetaan MM_TEXT dengan koordinat logisnya yang cocok dengan koordinat klien dari jendela yang berisi. Untuk objek tanpa jendela, konteks perangkat harus dalam keadaan yang sama dengan yang biasanya diteruskan oleh pesan WM_PAINT.

[in] lprcBounds

Penunjuk ke struktur RECTL yang menentukan persegi pada hdcDraw dan di mana objek harus digambar. Parameter ini mengontrol penempatan dan peregangan objek. Parameter ini harus NULL untuk menggambar objek aktif tanpa jendela di tempat. Dalam setiap situasi lain, NULL bukan nilai hukum dan harus menghasilkan kode kesalahan E_INVALIDARG. Jika kontainer meneruskan nilai non-NULL ke objek tanpa jendela, objek harus merender aspek yang diminta ke dalam konteks perangkat dan persegi panjang yang ditentukan. Kontainer dapat meminta ini dari objek tanpa jendela untuk merender tampilan objek kedua yang tidak aktif atau mencetak objek.

[in] lprcWBounds

Jika hdcDraw adalah konteks perangkat metafile, arahkan ke struktur RECTL yang menentukan persegi panjang pembatas dalam metafile yang mendasar. Struktur persegi panjang berisi jangkauan jendela dan asal jendela. Nilai-nilai ini berguna untuk menggambar metafiles. Persegi panjang yang ditunjukkan oleh lprcBounds bersarang di dalam persegi panjang lprcWBounds ini; mereka berada di ruang koordinat yang sama.

Jika hdcDraw bukan konteks perangkat metafile; lprcWBounds akan menjadi NULL.

[in] pfnContinue

Penunjuk ke fungsi panggilan balik yang harus dipanggil objek tampilan secara berkala selama operasi menggambar yang panjang untuk menentukan apakah operasi harus dilanjutkan atau dibatalkan. Fungsi ini mengembalikan TRUE untuk melanjutkan menggambar. Ini mengembalikan FALSE untuk menghentikan gambar dalam hal ini IViewObject::D raw mengembalikan DRAW_E_ABORT.

dwLanjutkan

[in] dwContinue

Nilai yang akan diteruskan sebagai parameter ke fungsi yang diarahkan oleh parameter pfnContinue . Biasanya, dwContinue adalah penunjuk ke struktur yang ditentukan aplikasi yang diperlukan di dalam fungsi panggilan balik.

Nilai kembali

Metode ini mengembalikan S_OK pada keberhasilan. Nilai pengembalian lain yang mungkin termasuk yang berikut ini.

Menampilkan kode	Deskripsi
OLE_E_BLANK	Tidak ada data untuk digambar.
DRAW_E_ABORT	Operasi gambar dibatalkan.
VIEW_E_DRAW	Kesalahan dalam menggambar.
DV_E_LINDEX	Nilai tidak valid untuk lindex; saat ini hanya -1 yang didukung.
DV_E_DVASPECT	Nilai tidak valid untuk dwAspect.
OLE_E_INVALIDRECT	Persegi panjang tidak valid.

Keterangan

Aplikasi kontainer mengeluarkan panggilan ke IViewObject::D raw untuk membuat representasi objek yang terkandung. Metode ini menggambar bagian yang ditentukan (lindex) dari tampilan yang ditentukan (dwAspect dan pvAspect) pada konteks perangkat yang ditentukan (hdcDraw). Pemformatan, font, dan keputusan penyajian lainnya dibuat berdasarkan perangkat target yang ditentukan oleh parameter ptd.

Ada hubungan antara nilai dwDrawAspect dan nilai lprcbounds . Nilai lprcbounds menentukan persegi panjang pada hdcDraw tempat gambar akan dipetakan. Untuk DVASPECT_THUMBNAIL, DVASPECT_ICON, dan DVASPECT_SMALLICON, objek menarik apa pun yang ingin digambarnya, dan memetakannya ke ruang yang diberikan dengan cara terbaik. Beberapa objek mungkin menskalakan agar pas sementara beberapa mungkin menskalakan agar pas tetapi mempertahankan rasio aspek. Selain itu, beberapa mungkin menskalakan sehingga gambar muncul dengan lebar penuh, tetapi bagian bawah dipotong. Kontainer dapat menyarankan ukuran melalui IOleObject::SetExtent, tetapi tidak memiliki kontrol atas ukuran penyajian. Dalam kasus DVASPECT_CONTENT, implementasi IViewObject::D raw harus menggunakan jangkauan yang diberikan oleh IOleObject::SetExtent atau menggunakan persegi panjang pembatas yang diberikan dalam parameter lprcBounds .

Untuk objek yang lebih baru yang mendukung teknik menggambar yang dioptimalkan dan untuk objek tanpa jendela, metode ini harus digunakan sebagai berikut:

Aspek gambar baru didukung dalam dwAspect seperti yang didefinisikan dalam DVASPECT2.
Parameter pvAspect dapat digunakan untuk meneruskan informasi tambahan yang memungkinkan pengoptimalan gambar melalui struktur DVASPECTINFO .
Metode IViewObject::D raw dapat dipanggil untuk menggambar ulang objek aktif tanpa jendela di tempat dengan mengatur parameter lrpcBounds ke NULL. Dalam setiap situasi lainnya, NULL adalah nilai ilegal dan harus menghasilkan kode kesalahan E_INVALIDARG. Objek tanpa jendela menggunakan persegi panjang yang diteruskan oleh kata kerja aktivasi atau memanggil IOleInPlaceObject::SetObjectRects alih-alih menggunakan parameter ini. Jika kontainer meneruskan nilai non-NULL ke objek tanpa jendela, objek harus merender aspek yang diminta ke dalam konteks perangkat dan persegi panjang yang ditentukan. Kontainer dapat meminta ini dari objek tanpa jendela untuk merender tampilan objek kedua yang tidak aktif atau mencetak objek. Lihat antarmuka IOleInPlaceSiteWindowless untuk informasi selengkapnya tentang menggambar objek tanpa jendela.
Untuk objek tanpa jendela, parameter dwAspect hanya memungkinkan aspek DVASPECT_CONTENT, DVASPECT_OPAQUE, dan DVASPECT_TRANSPARENT.
Untuk objek tanpa jendela, parameter hdcDraw harus dalam mode pemetaan MM_TEXT dengan koordinat logisnya yang cocok dengan koordinat klien dari jendela yang berisi. Untuk objek tanpa jendela, konteks perangkat harus dalam keadaan yang sama dengan yang biasanya diteruskan oleh pesan WM_PAINT.

Untuk mempertahankan kompatibilitas dengan objek dan kontainer lama yang tidak mendukung pengoptimalan gambar, semua objek, persegi panjang atau tidak, diperlukan untuk mempertahankan asal dan luas persegi panjang. Ini memungkinkan kontainer untuk tetap menganggap semua objek yang disematkan sebagai persegi panjang dan meneruskannya persegi panjang penyajian yang sesuai di Gambar.

Tingkat objek tergantung pada aspek gambar. Untuk objek non-persegi panjang, luasnya harus ukuran persegi panjang yang mencakup seluruh aspek. Menurut konvensi, asal objek adalah sudut kiri atas persegi panjang dari aspek DVASPECT_CONTENT. Dengan kata lain, asal selalu bertepatan dengan sudut kiri atas persegi panjang yang dikelola oleh situs objek, bahkan untuk objek non-persegi panjang.

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	oleidl.h