Função PropertySheetA (prsht.h)

Artigo
11/20/2024

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.

Valor de retorno

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 modeless, 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.

Observações

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.

Observação As observações a seguir referem-se apenas aos 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 dwFlags membro 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 PropertySheet valor retornado é 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 PropertySheet valor retornado 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 de 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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

Compartilhar via