Compartilhar via

Função PSFormatForDisplay (propsys.h)

  • Artigo

Obtém uma representação de cadeia de caracteres Unicode formatada de um valor de propriedade armazenado em uma estrutura PROPVARIANT . O chamador é responsável por alocar o buffer de saída.

Sintaxe

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

Parâmetros

[in] propkey

Tipo: REFPROPERTYKEY

Referência a um PROPERTYKEY que nomeia a propriedade cujo valor está sendo recuperado.

[in] propvar

Tipo: REFPROPVARIANT

Referência a uma estrutura PROPVARIANT que contém o tipo e o valor da propriedade.

[in] pdfFlags

Tipo: PROPDESC_FORMAT_FLAGS

Um sinalizador que especifica o formato a ser aplicado à cadeia de caracteres de propriedade. Consulte PROPDESC_FORMAT_FLAGS para obter valores possíveis.

[out] pwszText

Tipo: LPWSTR

Quando a função retorna, contém um ponteiro para o valor formatado como uma cadeia de caracteres Unicode terminada em nulo. O aplicativo de chamada é responsável por alocar memória para o buffer antes de chamar PSFormatForDisplay.

[in] cchText

Tipo: DWORD

Especifica o comprimento do buffer em pwszText no WCHARs, incluindo o caractere nulo de terminação.

Retornar valor

Tipo: HRESULT

Retorna um dos valores a seguir.

Código de retorno Descrição
S_OK
 A cadeia de caracteres formatada foi criada com êxito.
S_FALSE
 A cadeia de caracteres formatada não foi criada. S_FALSE indica que uma cadeia de caracteres vazia resultou de um VT_EMPTY.
E_OUTOFMEMORY
 Indica que a alocação falhou.

Comentários

Essa função chama a implementação do subsistema de esquema de IPropertySystem::FormatForDisplay. Essa chamada fornece uma representação de cadeia de caracteres Unicode de um valor de propriedade, com formatação adicional com base em 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 VARTYPE do valor.

Você deve inicializar o COM (Component Object Model) com CoInitialize ou OleInitialize antes de chamar PSFormatPropertyValue.

A finalidade dessa função é 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 os seguintes tópicos:

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 não espaçados influenciam o algoritmo bidirecional Unicode para que os valores apareçam corretamente quando um idioma da esquerda para a direita (LTR) é desenhado em uma janela da direita para a esquerda (RTL) ou um RTL é desenhado em uma janela LTR. Esses caracteres incluem o seguinte: "\x200e", "\x200f", "\x202a", "\x202b", "\x202c", "\x202d", "\x202e".

As propriedades a seguir usam formatos especiais e não são afetadas pelo PROPDESC_FORMAT_FLAGS. Observe que os exemplos citados são para cadeias de caracteres com uma localidade atual definida como inglês; normalmente, a saída é localizada, exceto quando anotado.

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 é convertido em "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 Por exemplo, "ISO-400".
System.Photo.ShutterSpeed O valor APEX é convertido em um tempo de exposição usando esta fórmula:

Exposure_time = 2^(-APEX_value)

Por exemplo, "2 segundos". ou "1/125 s".
System.Photo.ExposureTime Por exemplo, "2 segundos". ou "1/125 s".
System.Photo.Aperture O valor APEX é convertido em um número F usando esta fórmula:

F_Number = 2^(APEX_Value / 2)

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 livres 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, essa função escolherá um formato com base no tipo do valor.

Tipo do valor Formatar
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 Convertido em uma 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.
 

Exemplos

O exemplo a seguir, a ser incluído como parte de um programa maior, demonstra como usar PSFormatForDisplay para formatar um valor de classificação.

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

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
Biblioteca Propsys.lib
DLL Propsys.dll (versão 6.0 ou posterior)
Redistribuível Pesquisa da Área de Trabalho do Windows (WDS) 3.0

Confira também

PSFormatForDisplayAlloc

PSFormatPropertyValue

Esquema de descrição da propriedade