Função PropertySheetA (prsht.h)

  • Artigo

Cria uma folha de propriedades e adiciona as páginas definidas na estrutura de cabeçalho da folha de propriedades especificada.

Sintaxe

INT_PTR PropertySheetA(
  LPCPROPSHEETHEADERA unnamedParam1
);

Parâmetros

unnamedParam1

Tipo: LPCPROPSHEETHEADER

Ponteiro para uma estrutura PROPSHEETHEADER que define o quadro e as páginas de uma folha de propriedades.

Retornar valor

Tipo: INT_PTR

Para folhas de propriedades modais, o valor retornado é o seguinte:

>=1 As alterações foram salvas pelo usuário.
0 Nenhuma alteração foi salva pelo usuário.
-1 Ocorreu um erro.
 

Para folhas de propriedades de modelagem, o valor retornado é o identificador de janela da folha de propriedades.

Os valores retornados a seguir têm um significado especial.

Código de retorno Descrição
ID_PSREBOOTSYSTEM
 Uma página enviou a mensagem PSM_REBOOTSYSTEM para a folha de propriedades. O computador deve ser reiniciado para que as alterações do usuário entrem em vigor.
ID_PSRESTARTWINDOWS
 Uma página enviou a mensagem PSM_RESTARTWINDOWS para a folha de propriedades. O Windows deve ser reiniciado para que as alterações do usuário entrem em vigor.

Comentários

Para recuperar informações de erro estendidas, chame GetLastError.

Se você tentar adicionar mais de 99 páginas a uma folha de propriedades, essa função falhará, mas sem nenhuma indicação da causa do erro: PropertySheet retornará um valor de -1, mas GetLastError retornará 0.

Nota As observações a seguir referem-se apenas a assistentes que não usam o estilo do assistente aero (PSH_AEROWIZARD) ou folhas de propriedades não assistente.
 
Por padrão, a função PropertySheet cria uma caixa de diálogo modal. Se o membro dwFlags da estrutura PROPSHEETHEADER especificar o sinalizador PSH_MODELESS, PropertySheet criará uma caixa de diálogo de modelagem e retornará imediatamente após sua criação. Nesse caso, o valor retornado propertysheet é o identificador de janela para a caixa de diálogo modeless.

Para uma folha de propriedades de modelagem, o loop de mensagem deve usar PSM_ISDIALOGMESSAGE para passar mensagens para a caixa de diálogo da folha de propriedades. O loop de mensagem deve usar PSM_GETCURRENTPAGEHWND para determinar quando destruir a caixa de diálogo. Quando o usuário clica no botão OK ou Cancelar , PSM_GETCURRENTPAGEHWND retorna NULL. Em seguida, você pode usar a função DestroyWindow para destruir a caixa de diálogo.

Versão 5.80. O valor retornado propertysheet contém informações diferentes para folhas de propriedades modais e modeless. Em alguns casos, as folhas de propriedades de modelagem podem precisar das informações que teriam recebido do PropertySheet se tivessem sido modais. Em particular, eles podem precisar saber se ID_PSREBOOTSYSTEM ou ID_PSRESTARTWINDOWS teriam sido retornados. Uma folha de propriedades de modelagem pode recuperar o valor que uma folha de propriedades modal teria recebido de PropertySheet aguardando até PSM_GETCURRENTPAGEHWND retornar NULL e, em seguida, enviar uma mensagem PSM_GETRESULT .

Observação

O cabeçalho prsht.h define PropertySheet como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho prsht.h
Biblioteca Comctl32.lib
DLL Comctl32.dll
Conjunto de APIs ext-ms-win-shell-comctl32-window-l1-1-0 (introduzido no Windows 10, versão 10.0.14393)