IPropertySystem::FormatForDisplay method

Gets a formatted, Unicode string representation of a property value.

Syntax


HRESULT FormatForDisplay(
  [in]  REFPROPERTYKEY        key,
  [in]  REFPROPVARIANT        propvar,
  [in]  PROPDESC_FORMAT_FLAGS pdff,
  [out] LPWSTR                pszText,
  [in]  DWORD                 cchText
);

Parameters

key [in]

Type: REFPROPERTYKEY

A reference to the requested property key.

propvar [in]

Type: REFPROPVARIANT

A reference to a PROPVARIANT structure containing the type and value of the property.

pdff [in]

Type: PROPDESC_FORMAT_FLAGS

The format of the property string. See PROPDESC_FORMAT_FLAGS for possible values.

pszText [out]

Type: LPWSTR

Receives the formatted value as a null-terminated, Unicode string. The calling application must allocate memory for the buffer.

cchText [in]

Type: DWORD

The length of the buffer at pszText in WCHARs, including the terminating NULL. The maximum size is 0x8000 (32K).

Return value

Type: HRESULT

Returns one of the following values.

Return codeDescription
S_OK

Formatted string is created.

S_FALSE

Formatted string is not created. S_FALSE indicates that the empty string resulted from a VT_EMPTY.

E_OUTOFMEMORY

Memory allocation failed.

 

Remarks

You must initialize Component Object Model (COM) with CoInitialize or OleInitialize before calling IPropertySystem::FormatForDisplay.

When it succeeds, this method gets a formatted Unicode string representation of a property value for a specified PROPERTYKEY, and one or more PROPDESC_FORMAT_FLAGS. If the PROPERTYKEY is not recognized by the schema subsystem, IPropertySystem::FormatForDisplay attempts to format the value according to its VARTYPE.

The purpose of this method is to convert data into a string suitable for display to the user. The value is formatted according to the current locale, the language of the user, the PROPDESC_FORMAT_FLAGS, and the property description specified by the property key. For information about how the property description schema influences the formatting of the value, see displayInfo, stringFormat, booleanFormat, numberFormat, NMDATETIMEFORMAT, and enumeratedList. Typically, the PROPDESC_FORMAT_FLAGS are used to modify the format prescribed by the property description.

The output string may contain Unicode directional characters. These nonspacing characters influence the Unicode bidirectional algorithm so that the values appear correctly when a left-to-right (LTR) language is drawn on a right-to-left (RTL) window, and vice versa. These characters include the following: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

The properties in the following table use special formats and are unaffected by the PROPDESC_FORMAT_FLAGS (examples cited are for strings with a current locale set to English; typically, output is localized except where noted).

PropertyFormat
System.FileAttributesThe following file attributes are converted to letters and appended to create a string (for example, a value of 0x1801 (FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_COMPRESSED | FILE_ATTRIBUTE_OFFLINE) is converted to "RCO"):
  • FILE_ATTRIBUTE_READONLY (0x00000001) - 'R'
  • FILE_ATTRIBUTE_SYSTEM (0x00000004) - 'S'
  • FILE_ATTRIBUTE_ARCHIVE (0x00000020) -'A'
  • FILE_ATTRIBUTE_COMPRESSED (0x00000800) - 'C'
  • FILE_ATTRIBUTE_ENCRYPTED (0x00004000) - 'E'
  • FILE_ATTRIBUTE_OFFLINE (0x00001000) - 'O'
  • FILE_ATTRIBUTE_NOT_CONTENT_INDEXED (0x00002000) - 'I'
System.Photo.ISOSpeedFor example, "ISO-400".
System.Photo.ShutterSpeed

The APEX value is converted to an exposure time using this formula:

Exposure_time = 2^(-APEX_value)

For example, "2 sec."or "1/125 sec.".

System.Photo.ExposureTimeFor example, "2 sec."or "1/125 sec."
System.Photo.Aperture

The APEX value is converted to an F number using this formula:

F_Number = 2^(APEX_Value / 2)

For example, "f/5.6".

System.Photo.FNumberFor example, "f/5.6".
System.Photo.SubjectDistanceFor example, "15 m"or "250 mm".
System.Photo.FocalLengthFor example, "50 mm".
System.Photo.FlashEnergyFor example, "500 bpcs".
System.Photo.ExposureBiasFor example, "-2 step", " 0 step", or "+3 step".
System.Computer.DecoratedFreeSpaceFor example, "105 MB free of 13.2 GB".
System.ItemTypeFor example, "Application" or "JPEG Image".
System.ControlPanel.CategoryFor example, "Appearance and Personalization".
System.ComputerNameFor example, "LITWARE05 (this computer)" or "testbox07".

 

If the property key does not correspond to a property description in any of the registered property schemas, this method chooses a format based on the type of the value, as described in the following table.

Type of the valueFormat
VT_BOOLEANNot supported.
VT_FILETIMEDate/time string as specified by PROPDESC_FORMAT_FLAGS and the current locale. PDFF_SHORTTIME and PDFF_SHORTDATE are the default. For example, "11/13/2006 3:22 PM".
Numeric VARTYPEDecimal string in the current locale. For example, "42".
VT_LPWSTR or otherString. Sequences of "\r", "\t", or "\n" are replaced with a single space.
VT_VECTOR | anythingSemicolon separated values—a semicolon is used regardless of locale.

 

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Redistributable

Windows Desktop Search (WDS) 3.0

Header

Propsys.h

IDL

Propsys.idl

 

 

Show: