Fungsi PSFormatForDisplay (propsys.h)

Artikel
03/15/2023

Mendapatkan representasi string Unicode yang diformat dari nilai properti yang disimpan dalam struktur PROPVARIANT . Pemanggil bertanggung jawab untuk mengalokasikan buffer output.

Sintaks

PSSTDAPI PSFormatForDisplay(
  [in]  REFPROPERTYKEY        propkey,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdfFlags,
  [out] LPWSTR                pwszText,
  [in]  DWORD                 cchText
);

Parameter

[in] propkey

Jenis: REFPROPERTYKEY

Referensi ke PROPERTYKEY yang menamai properti yang nilainya sedang diambil.

[in] propvar

Jenis: REFPROPVARIANT

Referensi ke struktur PROPVARIANT yang berisi jenis dan nilai properti.

[in] pdfFlags

Jenis: PROPDESC_FORMAT_FLAGS

Bendera yang menentukan format yang akan diterapkan ke string properti. Lihat PROPDESC_FORMAT_FLAGS untuk nilai yang mungkin.

[out] pwszText

Jenis: LPWSTR

Saat fungsi kembali, berisi penunjuk ke nilai yang diformat sebagai string Unicode yang dihentikan null. Aplikasi panggilan bertanggung jawab untuk mengalokasikan memori untuk buffer sebelum memanggil PSFormatForDisplay.

[in] cchText

Jenis: DWORD

Menentukan panjang buffer di pwszText di WCHARs, termasuk karakter null yang mengakhiri.

Mengembalikan nilai

Jenis: HRESULT

Mengembalikan salah satu nilai berikut.

Menampilkan kode	Deskripsi
S_OK	String yang diformat berhasil dibuat.
S_FALSE	String yang diformat tidak dibuat. S_FALSE menunjukkan bahwa string kosong dihasilkan dari VT_EMPTY.
E_OUTOFMEMORY	Menunjukkan alokasi gagal.

Keterangan

Fungsi ini memanggil implementasi subsistem skema IPropertySystem::FormatForDisplay. Panggilan tersebut menyediakan representasi string Unicode dari nilai properti, dengan pemformatan tambahan berdasarkan satu atau beberapa PROPDESC_FORMAT_FLAGS. Jika PROPERTYKEY tidak dikenali oleh subsistem skema, IPropertySystem::FormatForDisplay mencoba memformat nilai sesuai dengan VARTYPE nilai.

Anda harus menginisialisasi Model Objek Komponen (COM) dengan CoInitialize atau OleInitialize sebelum Anda memanggil PSFormatPropertyValue.

Tujuan dari fungsi ini adalah untuk mengonversi data menjadi string yang cocok untuk ditampilkan kepada pengguna. Nilai diformat sesuai dengan lokal saat ini, bahasa pengguna, PROPDESC_FORMAT_FLAGS, dan deskripsi properti yang ditentukan oleh kunci properti. Untuk informasi tentang bagaimana skema deskripsi properti memengaruhi pemformatan nilai, lihat topik berikut:

Biasanya, PROPDESC_FORMAT_FLAGS digunakan untuk memodifikasi format yang ditentukan oleh deskripsi properti.

String output dapat berisi karakter arah Unicode. Karakter nonspacing ini memengaruhi algoritma dua arah Unicode sehingga nilai muncul dengan benar saat bahasa kiri-ke-kanan (LTR) digambar pada jendela kanan-ke-kiri (RTL), atau RTL digambar pada jendela LTR. Karakter-karakter ini mencakup yang berikut ini: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

Properti berikut menggunakan format khusus dan tidak terpengaruh oleh PROPDESC_FORMAT_FLAGS. Perhatikan bahwa contoh yang dikutip adalah untuk string dengan lokal saat ini diatur ke Bahasa Inggris; biasanya, output dilokalkan kecuali jika disebutkan.

Properti	Format
System.FileAttributes	Atribut file berikut dikonversi menjadi huruf dan ditambahkan untuk membuat string (misalnya, nilai 0x1801 dikonversi ke "RCO"):
	FILE_ATTRIBUTE_READONLY- 'R'
	FILE_ATTRIBUTE_SYSTEM - 'S'
	FILE_ATTRIBUTE_ARCHIVE -'A'
	FILE_ATTRIBUTE_COMPRESSED - 'C'
	FILE_ATTRIBUTE_ENCRYPTED - 'E'
	FILE_ATTRIBUTE_OFFLINE - 'O'
	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED - 'I'
System.Photo.ISOSpeed	Misalnya, "ISO-400".
System.Photo.ShutterSpeed	Nilai APEX dikonversi ke waktu pencahayaan menggunakan rumus ini: `Exposure_time = 2^(-APEX_value)` Misalnya, "2 detik." atau "1/125 detik.".
System.Photo.ExposureTime	Misalnya, "2 detik." atau "1/125 detik."
System.Photo.Aperture	Nilai APEX dikonversi ke angka F menggunakan rumus ini: `F_Number = 2^(APEX_Value / 2)` Misalnya, "f/5.6".
System.Photo.FNumber	Misalnya, "f/5.6".
System.Photo.SubjectDistance	Misalnya, "15 m"atau "250 mm".
System.Photo.FocalLength	Misalnya, "50 mm".
System.Photo.FlashEnergy	Misalnya, "500 bpcs".
System.Photo.ExposureBias	Misalnya, "-2 langkah", " 0 langkah", atau "+3 langkah".
System.Computer.DecoratedFreeSpace	Misalnya, "105 MB gratis 13,2 GB".
System.ItemType	Misalnya, "Aplikasi" atau "Gambar JPEG".
System.ControlPanel.Category	Misalnya, "Penampilan dan Personalisasi".
System.ComputerName	Misalnya, "LITWARE05 (komputer ini)" atau "testbox07".

Jika kunci properti tidak sesuai dengan deskripsi properti di salah satu skema properti terdaftar, maka fungsi ini memilih format berdasarkan jenis nilai.

Jenis nilai	Format
VT_BOOLEAN	Tidak didukung.
VT_FILETIME	String tanggal/waktu seperti yang ditentukan oleh PROPDESC_FORMAT_FLAGS dan lokal saat ini. PDFF_SHORTTIME dan PDFF_SHORTDATE adalah defaultnya. Misalnya, "13/11/2006 15:22".
VARTYPE Numerik	String desimal di lokal saat ini. Misalnya, "42".
VT_LPWSTR atau lainnya	Dikonversi menjadi string. Urutan "\r", "\t", atau "\n" diganti dengan satu spasi.
VT_VECTOR \| Apa pun	Nilai yang dipisahkan titik koma. Titik koma digunakan terlepas dari lokal.

Contoh

Contoh berikut, untuk disertakan sebagai bagian dari program yang lebih besar, menunjukkan cara menggunakan PSFormatForDisplay untuk memformat nilai peringkat.

PROPVARIANT propvar;

HRESULT hr = InitPropVariantFromUInt32(RATING_THREE_STARS_SET, &propvar);

if (SUCCEEDED(hr))
{
    WCHAR szValue[100];

    hr = PSFormatForDisplay(PKEY_Rating, propvar, PDFF_DEFAULT, szValue, ARRAYSIZE(szValue));

    if (SUCCEEDED(hr))
    {
        // szValue contains a formatted string similar to "3 stars".
    }
    PropVariantClear(&propvar);
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	propsys.h
Pustaka	Propsys.lib
DLL	Propsys.dll (versi 6.0 atau yang lebih baru)
Redistribusi	Windows Desktop Search (WDS) 3.0

Lihat juga

PSFormatForDisplayAlloc

PSFormatPropertyValue

Skema Deskripsi Properti

Share via