Struktur DEVMODEW (wingdi.h)

Artikel
06/13/2023

Struktur DEVMODEW digunakan untuk menentukan karakteristik perangkat tampilan dan cetak dalam set karakter Unicode (wide).

Sintaks

typedef struct _devicemodeW {
  WCHAR dmDeviceName[CCHDEVICENAME];
  WORD  dmSpecVersion;
  WORD  dmDriverVersion;
  WORD  dmSize;
  WORD  dmDriverExtra;
  DWORD dmFields;
  union {
    struct {
      short dmOrientation;
      short dmPaperSize;
      short dmPaperLength;
      short dmPaperWidth;
      short dmScale;
      short dmCopies;
      short dmDefaultSource;
      short dmPrintQuality;
    } DUMMYSTRUCTNAME;
    POINTL dmPosition;
    struct {
      POINTL dmPosition;
      DWORD  dmDisplayOrientation;
      DWORD  dmDisplayFixedOutput;
    } DUMMYSTRUCTNAME2;
  } DUMMYUNIONNAME;
  short dmColor;
  short dmDuplex;
  short dmYResolution;
  short dmTTOption;
  short dmCollate;
  WCHAR dmFormName[CCHFORMNAME];
  WORD  dmLogPixels;
  DWORD dmBitsPerPel;
  DWORD dmPelsWidth;
  DWORD dmPelsHeight;
  union {
    DWORD dmDisplayFlags;
    DWORD dmNup;
  } DUMMYUNIONNAME2;
  DWORD dmDisplayFrequency;
  DWORD dmICMMethod;
  DWORD dmICMIntent;
  DWORD dmMediaType;
  DWORD dmDitherType;
  DWORD dmReserved1;
  DWORD dmReserved2;
  DWORD dmPanningWidth;
  DWORD dmPanningHeight;
} DEVMODEW, *PDEVMODEW, *NPDEVMODEW, *LPDEVMODEW;

Anggota

dmDeviceName[CCHDEVICENAME]

Untuk tampilan, menentukan nama DLL driver tampilan; misalnya, "perm3dd" untuk driver tampilan 3Dlabs Permedia3.

Untuk printer, menentukan "nama yang mudah diingat"; misalnya, "PCL/HP LaserJet" dalam kasus PCL/HP LaserJet. Jika panjang nama lebih besar dari karakter CCHDEVICENAME, penampung memotongnya agar pas dalam array.

dmSpecVersion

Menentukan nomor versi struktur DEVMODEW ini. Nomor versi saat ini diidentifikasi oleh konstanta DM_SPECVERSION di wingdi.h.

dmDriverVersion

Untuk pencetak, tentukan nomor versi pengandar pencetak yang ditetapkan oleh pengembang pengandar pencetak.

Pengandar tampilan bisa menyetel anggota ini ke DM_SPECVERSION.

dmSize

Menentukan ukuran dalam byte struktur DEVMODEW publik, tidak termasuk anggota privat yang ditentukan driver yang diidentifikasi oleh anggota dmDriverExtra .

dmDriverExtra

Menentukan jumlah byte data driver privat yang mengikuti anggota struktur publik. Jika driver perangkat tidak menyediakan anggota DEVMODEW privat, anggota ini harus diatur ke nol.

dmFields

Menentukan bendera bit yang mengidentifikasi anggota DEVMODEW berikut yang sedang digunakan. Misalnya, bendera DM_ORIENTATION diatur saat anggota dmOrientation berisi data yang valid. Bendera DM_XXX didefinisikan dalam wingdi.h.

DUMMYUNIONNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmOrientation

Untuk pencetak, menentukan orientasi kertas. Anggota ini dapat DMORIENT_PORTRAIT atau DMORIENT_LANDSCAPE.

Anggota ini tidak digunakan untuk tampilan.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperSize

Untuk pencetak, menentukan ukuran kertas yang akan dicetak. Anggota ini harus nol jika panjang dan lebar kertas ditentukan oleh anggota dmPaperLength dan dmPaperWidth . Jika tidak, anggota dmPaperSize harus menjadi salah satu konstanta berawalan DMPAPER yang ditentukan dalam wingdi.h.

Anggota ini tidak digunakan untuk tampilan.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperLength

Untuk printer, menentukan panjang kertas, dalam satuan 1/10 milimeter. Nilai ini mengambil alih panjang kertas yang ditentukan oleh anggota dmPaperSize , dan digunakan jika kertas berukuran kustom, atau jika perangkat adalah printer matriks titik, yang dapat mencetak halaman dengan panjang arbitrer.

Anggota ini tidak digunakan untuk tampilan.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPaperWidth

Untuk printer, menentukan lebar kertas, dalam satuan 1/10 milimeter. Nilai ini mengambil alih lebar kertas yang ditentukan oleh anggota dmPaperSize . Anggota ini harus digunakan jika dmPaperLength digunakan.

Anggota ini tidak digunakan untuk tampilan.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmScale

Untuk printer, menentukan persentase di mana gambar akan diskalakan untuk pencetakan. Ukuran halaman gambar diskalakan ke halaman fisik dengan faktor dmScale/100. Misalnya, gambar 17 inci berukuran 22 inci dengan nilai skala 100 memerlukan kertas 17x22 inci, sedangkan gambar yang sama dengan nilai skala 50 harus dicetak sebagai ukuran setengah dan pas pada kertas berukuran huruf.

Anggota ini tidak digunakan untuk tampilan.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmCopies

Untuk printer, menentukan jumlah salinan yang akan dicetak, jika perangkat mendukung beberapa salinan.

Anggota ini tidak digunakan untuk tampilan.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmDefaultSource

Untuk printer, tentukan bin input default printer. Ini harus menjadi salah satu konstanta berawalan DMBIN yang ditentukan dalam wingdi.h. Jika konstanta yang ditentukan DMBIN_FORMSOURCE, bin input harus dipilih secara otomatis.

Anggota ini tidak digunakan untuk tampilan.

DUMMYUNIONNAME.DUMMYSTRUCTNAME.dmPrintQuality

Untuk pencetak, tentukan resolusi printer. Nilai konstanta negatif berikut didefinisikan dalam wingdi.h:

DMRES_HIGH
DMRES_MEDIUM
DMRES_LOW
DMRES_DRAFT

Jika nilai positif ditentukan, nilai tersebut menunjukkan jumlah titik per inci (DPI) untuk resolusi x , dan resolusi y ditentukan oleh dmYResolution.

Anggota ini tidak digunakan untuk tampilan.

DUMMYUNIONNAME.dmPosition

DUMMYUNIONNAME.DUMMYSTRUCTNAME2

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmPosition

Untuk tampilan, menentukan struktur POINTL yang berisi koordinat x- dan y sudut kiri atas layar, dalam koordinat desktop. Anggota ini digunakan untuk menentukan posisi relatif monitor di lingkungan beberapa monitor.

Anggota ini tidak digunakan untuk pencetak.

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmDisplayOrientation

Anggota ini didefinisikan hanya untuk Windows XP dan yang lebih baru.

Untuk tampilan, menentukan orientasi di mana gambar harus disajikan. Ketika bit DM_DISPLAYORIENTATION tidak diatur dalam anggota dmFields , anggota ini harus diatur ke nol. Ketika bit DM_DISPLAYORIENTATION diatur dalam anggota dmFields , anggota ini harus diatur ke salah satu nilai berikut:

Nilai	Makna
DMDO_DEFAULT	Orientasi perangkat tampilan mode saat ini adalah orientasi alami perangkat, dan harus digunakan sebagai default.
DMDO_90	Orientasi perangkat tampilan adalah 90 derajat (diukur searah jarang) dari DMDO_DEFAULT.
DMDO_180	Orientasi perangkat tampilan adalah 180 derajat (diukur searah jarang) dari DMDO_DEFAULT.
DMDO_270	Orientasi perangkat tampilan adalah 270 derajat (diukur searah jarang) dari DMDO_DEFAULT.

Anggota ini tidak digunakan untuk pencetak.

Untuk informasi selengkapnya, lihat Mengembalikan Mode Tampilan: DrvGetModes.

DUMMYUNIONNAME.DUMMYSTRUCTNAME2.dmDisplayFixedOutput

Anggota ini didefinisikan hanya untuk Windows XP dan yang lebih baru.

Untuk tampilan resolusi tetap, menentukan bagaimana perangkat dapat menyajikan mode resolusi lebih rendah pada tampilan resolusi yang lebih tinggi. Misalnya, jika resolusi perangkat tampilan diperbaiki pada 1024 X 768, dan modenya diatur ke 640 x 480, perangkat dapat menampilkan gambar 640 X 480 dalam ruang layar 1024 X 768, atau meregangkan gambar 640 X 480 untuk mengisi ruang layar yang lebih besar.

Ketika bit DM_DISPLAYFIXEDOUTPUT tidak diatur dalam anggota dmFields , anggota ini harus diatur ke nol. Ketika bit DM_DISPLAYFIXEDOUTPUT diatur dalam anggota dmFields , anggota ini harus diatur ke salah satu nilai berikut:

Nilai	Makna
DMDFO_CENTER	Perangkat tampilan menyajikan gambar mode resolusi yang lebih rendah dengan memusatkannya di ruang layar yang lebih besar.
DMDFO_STRETCH	Perangkat tampilan menyajikan gambar mode resolusi lebih rendah dengan meregangkannya untuk mengisi ruang layar yang lebih besar.

Anggota ini tidak digunakan untuk pencetak.

Untuk informasi selengkapnya, lihat Mengembalikan Mode Tampilan: DrvGetModes.

dmColor

Untuk pencetak, tentukan apakah printer warna harus mencetak warna atau monokrom. Anggota ini bisa menjadi salah satu DMCOLOR_COLOR atau DMCOLOR_MONOCHROME.

Anggota ini tidak digunakan untuk tampilan.

dmDuplex

Untuk printer, menentukan pencetakan dupleks (dua sisi) untuk printer berkemampuan dupleks. Anggota ini bisa menjadi salah satu nilai berikut:

DMDUP_HORIZONTAL

Cetak dua sisi, menggunakan pengikatan tepi pendek.

DMDUP_SIMPLEX

Cetak satu sisi.

DMDUP_VERTICAL

Cetak dua sisi, menggunakan pengikatan tepi panjang.

Anggota ini tidak digunakan untuk tampilan.

dmYResolution

Untuk printer, menentukan resolusi y printer, di DPI. Jika anggota ini digunakan, anggota dmPrintQuality menentukan resolusi x .

Anggota ini tidak digunakan untuk tampilan.

dmTTOption

Untuk printer, tentukan bagaimana font TrueType harus dicetak. Anggota ini harus menjadi salah satu konstanta berawalan DMTT yang ditentukan dalam wingdi.h.

Anggota ini tidak digunakan untuk tampilan.

dmCollate

Untuk printer, tentukan apakah beberapa salinan harus disusun. Anggota ini bisa menjadi salah satu nilai berikut:

DMCOLLATE_TRUE

Susun ketika mencetak beberapa salinan.

DMCOLLATE_FALSE

Jangan menyusun ketika mencetak beberapa salinan.

Anggota ini tidak digunakan untuk tampilan.

dmFormName[CCHFORMNAME]

Untuk printer, menentukan nama formulir yang akan digunakan; seperti "Letter" atau "Legal". Ini harus menjadi nama yang dapat diperoleh dengan memanggil fungsi Win32 EnumForms .

Anggota ini tidak digunakan untuk tampilan.

dmLogPixels

Untuk tampilan, menentukan jumlah piksel logis per inci perangkat tampilan dan harus sama dengan anggota ulLogPixels dari struktur GDIINFO .

Anggota ini tidak digunakan untuk pencetak.

dmBitsPerPel

Untuk tampilan, menentukan resolusi warna, dalam bit per piksel, dari perangkat tampilan.

Anggota ini tidak digunakan untuk pencetak.

dmPelsWidth

Untuk tampilan, menentukan lebar, dalam piksel, dari permukaan perangkat yang terlihat.

Anggota ini tidak digunakan untuk pencetak.

dmPelsHeight

Untuk tampilan, menentukan tinggi, dalam piksel, dari permukaan perangkat yang terlihat.

Anggota ini tidak digunakan untuk pencetak.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.dmDisplayFlags

Menentukan mode tampilan perangkat. Anggota ini bisa menjadi kombinasi dari nilai berikut.

Nilai	Makna
DM_GRAYSCALE	Menentukan bahwa tampilan adalah perangkat nonwarna. Jika bendera ini tidak diatur, warna diasumsikan. Bendera ini tidak lagi valid.
DM_INTERLACED	Menentukan bahwa mode tampilan terjalin. Jika bendera tidak diatur, maka tidak terinterlaced akan diasumsikan.

Driver tampilan menggunakan anggota ini; misalnya, dalam fungsi ChangeDisplaySettings . Pengandar pencetak tidak menggunakan anggota ini.

DUMMYUNIONNAME2.dmNup

Untuk printer, menentukan apakah sistem cetak menangani pencetakan "N-up" (memutar beberapa halaman logis EMF ke satu halaman fisik). Nilai anggota ini bisa menjadi salah satu dari berikut ini:

Nilai	Makna
DMNUP_SYSTEM	Sistem cetak menangani pencetakan "N-up".
DMNUP_ONEUP	Sistem cetak tidak menangani pencetakan "N-up". Aplikasi dapat mengatur dmNup ke DMNUP_ONEUP jika berniat untuk melakukan pencetakan "N-up" sendiri.

Anggota ini tidak digunakan untuk tampilan.

dmDisplayFrequency

Untuk tampilan, menentukan frekuensi, di hertz, dari perangkat tampilan dalam mode saat ini.

Anggota ini tidak digunakan untuk pencetak.

dmICMMethod

Menentukan salah satu konstanta berawalan DMICMMETHOD yang ditentukan dalam wingdi.h.

dmICMIntent

Menentukan salah satu konstanta berawalan DMICM yang ditentukan dalam wingdi.h.

dmMediaType

Menentukan salah satu konstanta berawalan DMMEDIA yang ditentukan dalam wingdi.h.

dmDitherType

Menentukan salah satu konstanta berawalan DMDITHER yang ditentukan dalam wingdi.h.

dmReserved1

Dicadangkan untuk penggunaan sistem dan harus diabaikan oleh driver.

dmReserved2

Dicadangkan untuk penggunaan sistem dan harus diabaikan oleh driver.

dmPanningWidth

Dicadangkan untuk penggunaan sistem dan harus diabaikan oleh driver.

dmPanningHeight

Dicadangkan untuk penggunaan sistem dan harus diabaikan oleh driver.

Keterangan

Struktur DEVMODEW adalah versi Unicode dari struktur DEVMODE (dijelaskan dalam dokumentasi Microsoft Windows SDK). Meskipun aplikasi dapat menggunakan versi ANSI atau Unicode dari struktur, driver diperlukan untuk menggunakan versi Unicode.

Untuk pengandar pencetak, struktur DEVMODEW digunakan untuk menentukan karakteristik printer yang diperlukan oleh dokumen cetak. Ini juga digunakan untuk menentukan karakteristik default printer.

Segera mengikuti anggota yang ditentukan struktur DEVMODEW (sering disebut sebagai anggota publiknya), mungkin ada sekumpulan anggota yang ditentukan pengemudi (sering disebut sebagai anggota DEVMODEW privat). Driver memasok ukuran, dalam byte, dari area privat ini di dmDriverExtra. Anggota privat yang ditentukan driver untuk penggunaan eksklusif oleh driver. Alamat awal untuk anggota privat dapat dirujuk menggunakan anggota dmSize sebagai berikut:

PVOID pvDriverData = (PVOID) (((BYTE *) pdm) + (pdm->dmSize));

Driver dapat mengandalkan penampung untuk melewati buffer DEVMODEW yang tidak lebih kecil dari byte (dmSize + dmDriverExtra). Akibatnya, driver dapat dengan aman membaca jumlah byte tersebut mulai dari awal buffer tanpa menyebabkan pelanggaran akses, dan tanpa perlu memeriksa memori.

Sebelum memainkan EMF, GDI memanggil penampung untuk memvalidasi konten bagian publik buffer DEVMODEW. Jika buffer DEVMODEW tidak lulus tes validasi yang dilakukan di penampung, GDI tidak meneruskan buffer ke driver printer.

Peringatan Windows hanya mengonfirmasi bahwa bagian publik DEVMODEW valid. Namun, data yang rusak di bagian privat struktur dapat menyebabkan kode driver mengalami crash dalam aplikasi atau dalam proses penampung. Akibatnya, sebelum setiap penggunaan data DEVMODEW, driver harus memverifikasi bahwa bagian privat DEVMODEW terbentuk dengan baik.

Di Windows 2000, anggota serikat baru ditambahkan ke struktur DEVMODEW. Anggota serikat ini berisi anggota struktur DEVMODEW yang ada, dmDisplayFlags, bersama dengan anggota baru, dmNup. Anggota ini dijelaskan di bagian Anggota sebelumnya.

Di Windows XP, anggota struct baru ditambahkan. Anggota struktur ini berisi anggota struktur DEVMODEW yang ada, dmPosition, bersama dengan dua anggota baru, dmDisplayOrientation dan dmDisplayFixedOutput. Anggota ini dijelaskan di bagian Anggota sebelumnya.

Juga untuk Windows XP, beberapa anggota struktur DEVMODEW dipindahkan ke lokasi yang berbeda dalam struktur ini. Anggota dmScale, dmCopies, dmDefaultSource, dan dmPrintQuality ditambahkan ke anggota struct yang berisi anggota dmOrientation, dmPaperSize, dmPaperLength, dan dmPaperWidth .

Catatan

Header wingdi.h mendefinisikan DEVMODE sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.