Condividi tramite


Funzione PSFormatForDisplay (propsys.h)

Ottiene una rappresentazione di stringa Unicode formattata di un valore di proprietà archiviato in una struttura PROPVARIANT . Il chiamante è responsabile dell'allocazione del buffer di output.

Sintassi

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

Parametri

[in] propkey

Tipo: REFPROPERTYKEY

Riferimento a un valore PROPERTYKEY che assegna un nome alla proprietà il cui valore viene recuperato.

[in] propvar

Tipo: REFPROPVARIANT

Riferimento a una struttura PROPVARIANT che contiene il tipo e il valore della proprietà.

[in] pdfFlags

Tipo: PROPDESC_FORMAT_FLAGS

Flag che specifica il formato da applicare alla stringa di proprietà. Per i valori possibili, vedere PROPDESC_FORMAT_FLAGS.

[out] pwszText

Tipo: LPWSTR

Quando la funzione viene restituita, contiene un puntatore al valore formattato come stringa Unicode con terminazione Null. L'applicazione chiamante è responsabile dell'allocazione della memoria per il buffer prima di chiamare PSFormatForDisplay.

[in] cchText

Tipo: DWORD

Specifica la lunghezza del buffer in pwszText in WCHAR, incluso il carattere Null di terminazione.

Valore restituito

Tipo: HRESULT

Restituisce uno dei valori seguenti.

Codice restituito Descrizione
S_OK
La stringa formattata è stata creata correttamente.
S_FALSE
La stringa formattata non è stata creata. S_FALSE indica che una stringa vuota è stata generata da un VT_EMPTY.
E_OUTOFMEMORY
Indica che l'allocazione non è riuscita.

Commenti

Questa funzione chiama l'implementazione del sottosistema dello schema di IPropertySystem::FormatForDisplay. Tale chiamata fornisce una rappresentazione di stringa Unicode di un valore di proprietà, con formattazione aggiuntiva basata su una o più PROPDESC_FORMAT_FLAGS. Se PROPERTYKEY non viene riconosciuto dal sottosistema dello schema, IPropertySystem::FormatForDisplay tenta di formattare il valore in base al valore VARTYPE del valore.

È necessario inizializzare Component Object Model (COM) con CoInitialize o OleInitialize prima di chiamare PSFormatPropertyValue.

Lo scopo di questa funzione è convertire i dati in una stringa adatta per la visualizzazione all'utente. Il valore viene formattato in base alle impostazioni locali correnti, alla lingua dell'utente, al PROPDESC_FORMAT_FLAGS e alla descrizione della proprietà specificata dalla chiave della proprietà. Per informazioni su come lo schema della descrizione della proprietà influisce sulla formattazione del valore, vedere gli argomenti seguenti:

In genere, il PROPDESC_FORMAT_FLAGS viene usato per modificare il formato prescritto dalla descrizione della proprietà.

La stringa di output può contenere caratteri direzionali Unicode. Questi caratteri nonpacing influenzano l'algoritmo bidirezionale Unicode in modo che i valori vengano visualizzati correttamente quando viene disegnato un linguaggio LTR (Left-to-Right) in una finestra RTL (Right-to-Left) o un RTL viene disegnato in una finestra LTR. Questi caratteri includono i seguenti: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

Le proprietà seguenti usano formati speciali e non sono interessate dalla PROPDESC_FORMAT_FLAGS. Si noti che gli esempi citati sono per le stringhe con impostazioni locali correnti impostate su Inglese; in genere, l'output viene localizzato tranne dove indicato.

Proprietà Format
System.FileAttributes Gli attributi di file seguenti vengono convertiti in lettere e aggiunti per creare una stringa (ad esempio, un valore di 0x1801 viene convertito in "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 Ad esempio, "ISO-400".
System.Photo.ShutterSpeed Il valore APEX viene convertito in un tempo di esposizione usando questa formula:

Exposure_time = 2^(-APEX_value)

Ad esempio, "2 sec". o "1/125 sec.".

System.Photo.ExposureTime Ad esempio, "2 sec". o "1/125 sec".
System.Photo.Aperture Il valore APEX viene convertito in un numero F usando questa formula:

F_Number = 2^(APEX_Value / 2)

Ad esempio, "f/5.6".

System.Photo.FNumber Ad esempio, "f/5.6".
System.Photo.SubjectDistance Ad esempio, "15 m"o "250 mm".
System.Photo.FocalLength Ad esempio, "50 mm".
System.Photo.Flash Dottorato Ad esempio, "500 bpcs".
System.Photo.ExposureBias Ad esempio, "-2 step", " 0 step" o "+3 step".
System.Computer.DecoratedFreeSpace Ad esempio, "105 MB gratuito di 13,2 GB".
System.ItemType Ad esempio, "Application" o "JPEG Image".
System.ControlPanel.Category Ad esempio, "Aspetto e personalizzazione".
System.ComputerName Ad esempio, "LITWARE05 (questo computer)" o "testbox07".
 

Se la chiave della proprietà non corrisponde a una descrizione di proprietà in uno degli schemi di proprietà registrati, questa funzione sceglie un formato in base al tipo del valore.

Tipo del valore Formato
VT_BOOLEAN Non supportato.
VT_FILETIME Stringa di data/ora come specificato da PROPDESC_FORMAT_FLAGS e dalle impostazioni locali correnti. PDFF_SHORTTIME e PDFF_SHORTDATE sono l'impostazione predefinita. Ad esempio, "13/11/2006 13:22".
VARTYPE numerico Stringa decimale nelle impostazioni locali correnti. Ad esempio, "42".
VT_LPWSTR o altro Convertito in una stringa. Le sequenze di "\r", "\t" o "\n" vengono sostituite con un singolo spazio.
VT_VECTOR | Nulla Valori separati da punto e virgola. Viene usato un punto e virgola indipendentemente dalle impostazioni locali.
 

Esempio

Nell'esempio seguente, da includere come parte di un programma più ampio, viene illustrato come usare PSFormatForDisplay per formattare un valore di classificazione.

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);
}

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [solo app desktop]
Server minimo supportato Windows Server 2008 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione propsys.h
Libreria Propsys.lib
DLL Propsys.dll (versione 6.0 o successiva)
Componente ridistribuibile Windows Desktop Search (WDS) 3.0

Vedi anche

PSFormatForDisplayAlloc

PSFormatPropertyValue

Schema Descrizione proprietà