ホーム › UI.Shell.PropertiesSystem › PSFormatForDisplay

PSFormatForDisplay

関数

プロパティ値を表示用文字列に整形する。

DLLPROPSYS.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// PROPSYS.dll
#include <windows.h>

HRESULT PSFormatForDisplay(
    const PROPERTYKEY* propkey,
    const PROPVARIANT* propvar,
    PROPDESC_FORMAT_FLAGS pdfFlags,
    LPWSTR pwszText,
    DWORD cchText
);

パラメーター

名前	型	方向	説明
propkey	PROPERTYKEY*	in	値を取得するプロパティを指定する PROPERTYKEY への参照。
propvar	PROPVARIANT*	in	プロパティの型と値を格納する PROPVARIANT 構造体への参照。
pdfFlags	PROPDESC_FORMAT_FLAGS	in	プロパティ文字列に適用する書式を指定するフラグ。指定できる値については PROPDESC_FORMAT_FLAGS を参照してください。
pwszText	LPWSTR	out	この関数が制御を返すときに、書式設定された値を null で終わる Unicode 文字列として指すポインターが格納されます。呼び出し側のアプリケーションは、PSFormatForDisplay を呼び出す前にバッファー用のメモリを割り当てる必要があります。
cchText	DWORD	in	pwszText が指すバッファーの長さを、終端の null 文字を含めた WCHARs 単位で指定します。

戻り値の型: HRESULT

公式ドキュメント

PROPVARIANT 構造体に格納されたプロパティ値について、表示用に書式設定された Unicode 文字列表現を取得します。出力バッファーの割り当ては呼び出し側が行います。

戻り値

型: HRESULT

次のいずれかの値を返します。

戻り値	説明
S_OK	書式設定された文字列が正常に作成されました。
S_FALSE	書式設定された文字列は作成されませんでした。S_FALSE は、VT_EMPTY によって空の文字列になったことを示します。
E_OUTOFMEMORY	割り当てに失敗したことを示します。

解説(Remarks)

この関数は、スキーマサブシステムによる IPropertySystem::FormatForDisplay の実装を呼び出します。この呼び出しにより、1 つ以上の PROPDESC_FORMAT_FLAGS に基づく書式設定を加えた、プロパティ値の Unicode 文字列表現が得られます。PROPERTYKEY がスキーマサブシステムで認識されない場合、IPropertySystem::FormatForDisplay は値の VARTYPE に従って値の書式設定を試みます。

PSFormatPropertyValue を呼び出す前に、CoInitialize または OleInitialize でコンポーネントオブジェクトモデル (COM) を初期化しておく必要があります。

この関数の目的は、データをユーザーへの表示に適した文字列に変換することです。値は、現在のロケール、ユーザーの言語、PROPDESC_FORMAT_FLAGS、およびプロパティキーで指定されるプロパティの説明 (property description) に従って書式設定されます。プロパティの説明のスキーマが値の書式設定にどのように影響するかについては、次のトピックを参照してください。

            通常、<b>PROPDESC_FORMAT_FLAGS</b> は、プロパティの説明で規定された書式を変更するために使用します。

出力文字列には Unicode の方向制御文字が含まれることがあります。これらの非スペーシング文字は Unicode の双方向アルゴリズムに影響を与え、左から右 (LTR) の言語が右から左 (RTL) のウィンドウに描画される場合や、RTL の言語が LTR のウィンドウに描画される場合でも、値が正しく表示されるようにします。これらの文字には次のものが含まれます: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

次のプロパティは特別な書式を使用し、PROPDESC_FORMAT_FLAGS の影響を受けません。挙げている例は、現在のロケールが英語に設定されている場合の文字列です。通常、出力は特に記載がない限りローカライズされます。

プロパティ	書式
System.FileAttributes	次のファイル属性が文字に変換され、連結されて 1 つの文字列になります (たとえば、値 0x1801 は "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	たとえば "ISO-400"。
System.Photo.ShutterSpeed	APEX 値は次の式で露出時間に変換されます。 `Exposure_time = 2^(-APEX_value)` たとえば "2 sec." や "1/125 sec."。
System.Photo.ExposureTime	たとえば "2 sec." や "1/125 sec."。
System.Photo.Aperture	APEX 値は次の式で F 値に変換されます。 `F_Number = 2^(APEX_Value / 2)` たとえば "f/5.6"。
System.Photo.FNumber	たとえば "f/5.6"。
System.Photo.SubjectDistance	たとえば "15 m" や "250 mm"。
System.Photo.FocalLength	たとえば "50 mm"。
System.Photo.FlashEnergy	たとえば "500 bpcs"。
System.Photo.ExposureBias	たとえば "-2 step"、" 0 step"、"+3 step"。
System.Computer.DecoratedFreeSpace	たとえば "105 MB free of 13.2 GB"。
System.ItemType	たとえば "Application" や "JPEG Image"。
System.ControlPanel.Category	たとえば "Appearance and Personalization"。
System.ComputerName	たとえば "LITWARE05 (this computer)" や "testbox07"。

プロパティキーが、登録されているどのプロパティスキーマのプロパティの説明にも対応しない場合、この関数は値の型に基づいて書式を選択します。

値の型	書式
VT_BOOLEAN	サポートされていません。
VT_FILETIME	PROPDESC_FORMAT_FLAGS と現在のロケールで指定される日付/時刻文字列。既定は PDFF_SHORTTIME と PDFF_SHORTDATE です。たとえば "11/13/2006 3:22 PM"。
数値の VARTYPE	現在のロケールでの 10 進数文字列。たとえば "42"。
VT_LPWSTR またはその他	文字列に変換されます。"\r"、"\t"、"\n" の連続は 1 つの空白に置き換えられます。
VT_VECTOR \| 任意の型	セミコロン区切りの値。ロケールに関係なくセミコロンが使用されます。

例

次の例は、より大きなプログラムの一部として使用することを想定したもので、PSFormatForDisplay を使用して評価 (レーティング) の値を書式設定する方法を示しています。

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 には "3 stars" のような書式設定された文字列が格納されます。
    }
    PropVariantClear(&propvar);
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// PROPSYS.dll
#include <windows.h>

HRESULT PSFormatForDisplay(
    const PROPERTYKEY* propkey,
    const PROPVARIANT* propvar,
    PROPDESC_FORMAT_FLAGS pdfFlags,
    LPWSTR pwszText,
    DWORD cchText
);

[DllImport("PROPSYS.dll", ExactSpelling = true)]
static extern int PSFormatForDisplay(
    IntPtr propkey,   // PROPERTYKEY*
    IntPtr propvar,   // PROPVARIANT*
    int pdfFlags,   // PROPDESC_FORMAT_FLAGS
    [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pwszText,   // LPWSTR out
    uint cchText   // DWORD
);

<DllImport("PROPSYS.dll", ExactSpelling:=True)>
Public Shared Function PSFormatForDisplay(
    propkey As IntPtr,   ' PROPERTYKEY*
    propvar As IntPtr,   ' PROPVARIANT*
    pdfFlags As Integer,   ' PROPDESC_FORMAT_FLAGS
    <MarshalAs(UnmanagedType.LPWStr)> pwszText As System.Text.StringBuilder,   ' LPWSTR out
    cchText As UInteger   ' DWORD
) As Integer
End Function

' propkey : PROPERTYKEY*
' propvar : PROPVARIANT*
' pdfFlags : PROPDESC_FORMAT_FLAGS
' pwszText : LPWSTR out
' cchText : DWORD
Declare PtrSafe Function PSFormatForDisplay Lib "propsys" ( _
    ByVal propkey As LongPtr, _
    ByVal propvar As LongPtr, _
    ByVal pdfFlags As Long, _
    ByVal pwszText As LongPtr, _
    ByVal cchText As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

PSFormatForDisplay = ctypes.windll.propsys.PSFormatForDisplay
PSFormatForDisplay.restype = ctypes.c_int
PSFormatForDisplay.argtypes = [
    ctypes.c_void_p,  # propkey : PROPERTYKEY*
    ctypes.c_void_p,  # propvar : PROPVARIANT*
    ctypes.c_int,  # pdfFlags : PROPDESC_FORMAT_FLAGS
    wintypes.LPWSTR,  # pwszText : LPWSTR out
    wintypes.DWORD,  # cchText : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('PROPSYS.dll')
PSFormatForDisplay = Fiddle::Function.new(
  lib['PSFormatForDisplay'],
  [
    Fiddle::TYPE_VOIDP,  # propkey : PROPERTYKEY*
    Fiddle::TYPE_VOIDP,  # propvar : PROPVARIANT*
    Fiddle::TYPE_INT,  # pdfFlags : PROPDESC_FORMAT_FLAGS
    Fiddle::TYPE_VOIDP,  # pwszText : LPWSTR out
    -Fiddle::TYPE_INT,  # cchText : DWORD
  ],
  Fiddle::TYPE_INT)

#[link(name = "propsys")]
extern "system" {
    fn PSFormatForDisplay(
        propkey: *const PROPERTYKEY,  // PROPERTYKEY*
        propvar: *const PROPVARIANT,  // PROPVARIANT*
        pdfFlags: i32,  // PROPDESC_FORMAT_FLAGS
        pwszText: *mut u16,  // LPWSTR out
        cchText: u32  // DWORD
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("PROPSYS.dll")]
public static extern int PSFormatForDisplay(IntPtr propkey, IntPtr propvar, int pdfFlags, [MarshalAs(UnmanagedType.LPWStr)] System.Text.StringBuilder pwszText, uint cchText);
"@
$api = Add-Type -MemberDefinition $sig -Name 'PROPSYS_PSFormatForDisplay' -Namespace Win32 -PassThru
# $api::PSFormatForDisplay(propkey, propvar, pdfFlags, pwszText, cchText)

#uselib "PROPSYS.dll"
#func global PSFormatForDisplay "PSFormatForDisplay" sptr, sptr, sptr, sptr, sptr
; PSFormatForDisplay varptr(propkey), varptr(propvar), pdfFlags, varptr(pwszText), cchText   ; 戻り値は stat
; propkey : PROPERTYKEY* -> "sptr"
; propvar : PROPVARIANT* -> "sptr"
; pdfFlags : PROPDESC_FORMAT_FLAGS -> "sptr"
; pwszText : LPWSTR out -> "sptr"
; cchText : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "PROPSYS.dll"
#cfunc global PSFormatForDisplay "PSFormatForDisplay" var, var, int, var, int
; res = PSFormatForDisplay(propkey, propvar, pdfFlags, pwszText, cchText)
; propkey : PROPERTYKEY* -> "var"
; propvar : PROPVARIANT* -> "var"
; pdfFlags : PROPDESC_FORMAT_FLAGS -> "int"
; pwszText : LPWSTR out -> "var"
; cchText : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "PROPSYS.dll"
#cfunc global PSFormatForDisplay "PSFormatForDisplay" sptr, sptr, int, sptr, int
; res = PSFormatForDisplay(varptr(propkey), varptr(propvar), pdfFlags, varptr(pwszText), cchText)
; propkey : PROPERTYKEY* -> "sptr"
; propvar : PROPVARIANT* -> "sptr"
; pdfFlags : PROPDESC_FORMAT_FLAGS -> "int"
; pwszText : LPWSTR out -> "sptr"
; cchText : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。