Método IPropertySystem::FormatForDisplay (propsys.h)
Obtém uma representação de cadeia de caracteres Unicode formatada de um valor de propriedade.
Sintaxe
HRESULT FormatForDisplay(
[in] REFPROPERTYKEY key,
[in] REFPROPVARIANT propvar,
[in] PROPDESC_FORMAT_FLAGS pdff,
[out] LPWSTR pszText,
[in] DWORD cchText
);
Parâmetros
[in] key
Tipo: REFPROPERTYKEY
Uma referência à chave de propriedade solicitada.
[in] propvar
Tipo: REFPROPVARIANT
Uma referência a uma estrutura PROPVARIANT que contém o tipo e o valor da propriedade.
[in] pdff
Tipo: PROPDESC_FORMAT_FLAGS
O formato da cadeia de caracteres de propriedade. Consulte PROPDESC_FORMAT_FLAGS para obter valores possíveis.
[out] pszText
Tipo: LPWSTR
Recebe o valor formatado como uma cadeia de caracteres Unicode terminada em nulo. O aplicativo de chamada deve alocar memória para o buffer.
[in] cchText
Tipo: DWORD
O comprimento do buffer em pszText no WCHARs, incluindo o NULL de terminação. O tamanho máximo é 0x8000 (32K).
Retornar valor
Tipo: HRESULT
Retorna um dos valores a seguir.
| Código de retorno | Descrição |
|---|---|
|
A cadeia de caracteres formatada é criada. |
|
A cadeia de caracteres formatada não é criada. S_FALSE indica que a cadeia de caracteres vazia resultou de um VT_EMPTY. |
|
Falha na alocação de memória. |
Comentários
Você deve inicializar o COM (Component Object Model) com CoInitialize ou OleInitialize antes de chamar IPropertySystem::FormatForDisplay.
Quando ele é bem-sucedido, esse método obtém uma representação de cadeia de caracteres Unicode formatada de um valor de propriedade para um PROPERTYKEY especificado e um ou mais PROPDESC_FORMAT_FLAGS. Se PROPERTYKEY não for reconhecido pelo subsistema de esquema, IPropertySystem::FormatForDisplay tentará formatar o valor de acordo com seu VARTYPE.
A finalidade desse método é converter dados em uma cadeia de caracteres adequada para exibição para o usuário. O valor é formatado de acordo com a localidade atual, o idioma do usuário, o PROPDESC_FORMAT_FLAGS e a descrição da propriedade especificada pela chave de propriedade. Para obter informações sobre como o esquema de descrição da propriedade influencia a formatação do valor, consulte displayInfo, stringFormat, booleanFormat, numberFormat, NMDATETIMEFORMAT e enumeratedList. Normalmente, os PROPDESC_FORMAT_FLAGS são usados para modificar o formato prescrito pela descrição da propriedade.
A cadeia de caracteres de saída pode conter caracteres direcionais Unicode. Esses caracteres sem espaçamento influenciam o algoritmo bidirecional Unicode para que os valores apareçam corretamente quando uma linguagem LTR (da esquerda para a direita) é desenhada em uma janela da direita para a esquerda (RTL) e vice-versa. Esses caracteres incluem o seguinte: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".
As propriedades na tabela a seguir usam formatos especiais e não são afetadas pelo PROPDESC_FORMAT_FLAGS (exemplos citados são para cadeias de caracteres com uma localidade atual definida como inglês; normalmente, a saída é localizada, exceto quando indicada).
| Propriedade | Formatar |
|---|---|
| System.FileAttributes | Os atributos de arquivo a seguir são convertidos em letras e acrescentados para criar uma cadeia de caracteres (por exemplo, um valor de 0x1801 (FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_COMPRESSED | FILE_ATTRIBUTE_OFFLINE) é convertido em "RCO"):
|
| System.Photo.ISOSpeed | Por exemplo, "ISO-400". |
| System.Photo.ShutterSpeed |
O valor APEX é convertido em um tempo de exposição usando esta fórmula:
Por exemplo, "2 s". ou "1/125 s". |
| System.Photo.ExposureTime | Por exemplo, "2 s". ou "1/125 s". |
| System.Photo.Aperture |
O valor APEX é convertido em um número F usando esta fórmula:
Por exemplo, "f/5.6". |
| System.Photo.FNumber | Por exemplo, "f/5.6". |
| System.Photo.SubjectDistance | Por exemplo, "15 m" ou "250 mm". |
| System.Photo.FocalLength | Por exemplo, "50 mm". |
| System.Photo.FlashEnergy | Por exemplo, "500 bpcs". |
| System.Photo.ExposureBias | Por exemplo, "-2 etapa", "0 etapa" ou "+3 etapa". |
| System.Computer.DecoratedFreeSpace | Por exemplo, "105 MB livre de 13,2 GB". |
| System.ItemType | Por exemplo, "Application" ou "JPEG Image". |
| System.ControlPanel.Category | Por exemplo, "Aparência e Personalização". |
| System.ComputerName | Por exemplo, "LITWARE05 (este computador)" ou "testbox07". |
Se a chave de propriedade não corresponder a uma descrição de propriedade em nenhum dos esquemas de propriedade registrados, esse método escolherá um formato com base no tipo do valor, conforme descrito na tabela a seguir.
| Tipo do valor | Formato |
|---|---|
| VT_BOOLEAN | Não há suporte. |
| VT_FILETIME | Cadeia de caracteres de data/hora, conforme especificado por PROPDESC_FORMAT_FLAGS e a localidade atual. PDFF_SHORTTIME e PDFF_SHORTDATE são o padrão. Por exemplo, "13/11/2006 15:22". |
| VARTYPE numérico | Cadeia de caracteres decimal na localidade atual. Por exemplo, "42". |
| VT_LPWSTR ou outro | Cadeia de caracteres. Sequências de "\r", "\t" ou "\n" são substituídas por um único espaço. |
| VT_VECTOR | Nada | Valores separados por ponto e vírgula — um ponto e vírgula é usado independentemente da localidade. |
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | propsys.h |
| Redistribuível | Pesquisa da Área de Trabalho do Windows (WDS) 3.0 |