Sobre as Folhas de Propriedades

Uma folha de propriedades é uma janela que permite ao usuário exibir e editar as propriedades de um item. Por exemplo, um aplicativo de planilha pode usar uma folha de propriedades para permitir que o usuário defina as propriedades de fonte e borda de uma célula ou para exibir e definir as propriedades de um dispositivo, como uma unidade de disco, impressora ou mouse.

Esta seção discute os seguintes tópicos.

• Noções básicas da Ficha de Propriedades
• Caixas de Diálogo de Folha de Propriedades
• Páginas
• Criação de Folha de Propriedades
• Adicionar e remover páginas
• Título da folha de propriedades e rótulos de página
• Ativação da Página
• botão Ajuda
  • Remover o botão Ajuda da barra de legendas
• botões OK, Cancelar e Aplicar
• Feiticeiros

Noções básicas da folha de propriedades

Para implementar folhas de propriedades em seu aplicativo, inclua o arquivo de cabeçalho Prsht.h em seu projeto. Prsht.h contém todos os identificadores usados com fichas de propriedades.

Uma folha de propriedades contém uma ou mais janelas filhas sobrepostas chamadas páginas, cada uma contendo janelas de controle para definir um grupo de propriedades relacionadas. Por exemplo, uma página pode conter os controles para definir as propriedades da fonte de um item, incluindo o estilo de tipo, tamanho do ponto, cor e assim por diante. Cada página tem uma guia que o utilizador pode selecionar para trazer a página para o primeiro plano do painel de propriedades. Por exemplo, a aplicação do painel de controlo Date-Time exibe a seguinte ficha de propriedades.

Uma folha de propriedades padrão com várias páginas com guias permite ao usuário acesso aleatório a todas as propriedades. Se for mais apropriado definir propriedades em sequência, pode-se utilizar um assistente de .

Caixas de diálogo da folha de propriedades

Uma folha de propriedades e as páginas que ela contém são, na verdade, caixas de diálogo. A folha de propriedades é uma caixa de diálogo definida pelo sistema que gerencia as páginas e fornece um contêiner comum para elas. Uma caixa de diálogo de folha de propriedades pode ser modal ou não modal. Inclui uma moldura, uma barra de título e quatro botões: OK, Cancelar, Aplicare (opcionalmente) Ajuda. Os procedimentos da caixa de diálogo para as páginas recebem códigos de notificação na forma de mensagens WM_NOTIFY quando o usuário clica nos botões.

Observação

Nem todas as informações nesta seção se aplicam aos assistentes, que apresentam uma aparência e comportamento ligeiramente diferentes. Por exemplo, os assistentes têm um conjunto diferente de botões e nenhuma guia. Para obter mais informações, consulte Criando assistentes.

Cada página numa folha de propriedades é uma caixa de diálogo não modal definida pela aplicação que gere as caixas de controlo usadas para visualizar e editar propriedades de um item. Você fornece o modelo de caixa de diálogo usado para criar cada página, bem como o procedimento de caixa de diálogo que gerencia os controles e define as propriedades do item correspondente.

Uma folha de propriedades envia códigos de notificação para o procedimento da caixa de diálogo de uma página quando a página obtém ou perde ativação e quando o usuário clica no botão OK, Cancelar, Aplicarou Ajuda. As notificações são enviadas sob a forma de mensagens WM_NOTIFY. O parâmetro lParam é o endereço de uma estrutura deNMHDRque inclui o identificador de janela para a caixa de diálogo da folha de propriedades.

Alguns códigos de notificação exigem que uma página devolva TRUE ou FALSE em resposta à mensagem WM_NOTIFY. Para fazer isso, a página deve usar a funçãoSetWindowLongpara definir o valor DWL_MSGRESULT para a caixa de diálogo da página como TRUE ou FALSE.

Páginas

Uma folha de propriedades deve conter pelo menos uma página, mas não pode conter mais do que o valor de MAXPROPPAGES conforme definido nos arquivos de cabeçalho do Windows. Cada página tem um índice baseado em zero que a folha de propriedades atribui de acordo com a ordem em que a página é adicionada à folha de propriedades. Os índices são usados em mensagens que você envia para a folha de propriedades.

Uma página de propriedades pode conter uma caixa de diálogo aninhada. Se isso acontecer, deverá incluir o estilo WS_EX_CONTROLPARENT na caixa de diálogo de nível superior e chamar a função IsDialogMessage com o identificador da caixa de diálogo principal. Isso garante que o usuário possa usar mnemônicos e as teclas de navegação da caixa de diálogo para mover o foco para os controles na caixa de diálogo aninhada.

Cada página tem um ícone e um rótulo correspondentes. A folha de propriedades cria uma guia para cada página e exibe o ícone e o rótulo na guia. Espera-se que todas as páginas da folha de propriedades usem uma fonte sem negrito. Para garantir que a fonte não esteja em negrito, especifique o estilo DS_3DLOOK no modelo de caixa de diálogo.

O procedimento de caixa de diálogo para uma página não deve chamar a função EndDialog. Isso destruirá toda a folha de propriedade, não apenas a página.

O tamanho mínimo para uma página de folha de propriedades é 212 unidades de diálogo horizontalmente e 114 unidades de diálogo verticalmente. Se uma caixa de diálogo de página for menor do que isso, a página será ampliada até atingir o tamanho mínimo. O arquivo de cabeçalho Prsht.h contém três conjuntos de tamanhos recomendados para páginas de folha de propriedades, conforme mostrado na tabela a seguir.

Tamanho	Descrição
PROP_SM_CXDLG	Largura, em unidades de diálogo, de uma pequena página da folha de propriedades.
PROP_SM_CYDLG	Altura, em unidades de diálogo, de uma pequena página da ficha de propriedades.
PROP_MED_CXDLG	Largura, em unidades de diálogo, de uma página de folha de propriedades de tamanho médio.
PROP_MED_CYDLG	Altura, em unidades de diálogo, de uma página de propriedades de tamanho médio.
PROP_LG_CXDLG	Largura, em unidades de diálogo, de uma página grande da folha de propriedades.
PROP_LG_CYDLG	Altura, em unidades de diálogo, de uma grande página de propriedades.

O uso desses tamanhos recomendados ajudará a garantir a consistência visual entre seu aplicativo e outros aplicativos do Microsoft Windows.

No editor de recursos do Microsoft Visual Studio, pode-se criar uma página do tamanho apropriado na caixa de diálogo Adicionar Recursos. Expanda o nó de diálogo e selecione IDD_PROPPAGE_LARGE, IDD_PROPPAGE_MEDIUMou IDD_PROPPAGE_SMALL.

A folha de propriedades é automaticamente dimensionada para acomodar a página maior.

Criação de Folha de Propriedades

Antes de criar uma folha de propriedades, você deve definir uma ou mais páginas. Isso envolve preencher uma estrutura de PROPSHEETPAGE com informações sobre a página — como seu ícone, rótulo, modelo de caixa de diálogo, procedimento de caixa de diálogo, e assim por diante — e, em seguida, especificar o endereço da estrutura em uma chamada à função CreatePropertySheetPage de. A função retorna um identificador para o tipo HPROPSHEETPAGE que identifica exclusivamente a página.

Para criar uma folha de propriedades, especifique o endereço de uma estrutura PROPSHEETHEADER numa chamada da função PropertySheet. A estrutura define o ícone e o título da folha de propriedades e também inclui o endereço de uma matriz de identificadores HPROPSHEETPAGE que você obtém usando CreatePropertySheetPage. Quando PropertySheet cria a folha de propriedades, ela inclui as páginas identificadas na matriz. As páginas aparecem na folha de propriedades na mesma ordem em que estão contidas na matriz.

Outra maneira de atribuir páginas a uma folha de propriedades é especificar uma matriz de estruturas de PROPSHEETPAGE em vez de uma matriz de identificadores de HPROPSHEETPAGE. Nesse caso, PropertySheet cria identificadores para as páginas antes de adicioná-las à folha de propriedades.

Quando uma página é criada, seu procedimento de caixa de diálogo recebe uma mensagem WM_INITDIALOG. O parâmetro lParam da mensagem é um ponteiro para uma cópia da estrutura PROPSHEETPAGE que é definida quando a página é criada. Em particular, quando uma página é criada, o membro lParam da estrutura pode ser usado para passar informações definidas pelo aplicativo para o procedimento da caixa de diálogo. Com exceção do membro lParam, essa estrutura deve ser tratada como somente leitura. Modificar qualquer coisa que não seja lParam terá consequências imprevisíveis.

Quando o sistema passa posteriormente uma cópia da estrutura de PROPSHEETPAGE da página para a sua aplicação, ele usa o mesmo ponteiro. Quaisquer alterações na estrutura serão repassadas. Como o membro lParam é ignorado pelo sistema, ele pode ser modificado para enviar informações para outras partes do seu aplicativo. Você pode, por exemplo, usar lParam para passar informações para a função callback PropSheetPageProc da página.

PropertySheet define automaticamente o tamanho e a posição inicial de uma folha de propriedades. A posição é baseada na posição da janela do proprietário e o tamanho é baseado na maior página especificada na matriz de páginas quando a folha de propriedades foi criada. Se desejar que as páginas correspondam à largura dos quatro botões na parte inferior da folha de propriedades, defina a largura da página mais larga como 190 unidades de diálogo.

O tamanho de uma folha de propriedades é calculado a partir das propriedades de largura e altura do modelo de diálogo no ficheiro de recurso. Consulte de recursos DIALOG ou de recursos DIALOGEX para obter mais detalhes. Note, no entanto, que, por razões de compatibilidade, as dimensões são calculadas em relação à fonte MS Shell Dlg em vez da fonte usada pela página. Se você criar uma página que usa outra fonte, uma das sugestões a seguir pode ser usada.

• Ajuste as dimensões do modelo de diálogo para compensar a diferença de tamanho entre a fonte MS Shell Dlg e a fonte que a página realmente usa. Por exemplo, se você escolher uma fonte que seja duas vezes maior que o MS Shell Dlg, defina a propriedade width do modelo de diálogo para o dobro do uso normal.
• Use um modelo de DIALOGEX e defina o estilo de diálogo DS_SHELLFONT. Nesse caso, o gerenciador de folhas de propriedades interpreta as dimensões do modelo de diálogo em relação à fonte usada pelo modelo de diálogo.

Adicionar e remover páginas

Depois de criar uma folha de propriedades, um aplicativo pode adicionar uma página ao final do conjunto de páginas existente enviando uma mensagem de PSM_ADDPAGE. Para inserir uma página entre páginas existentes, envie uma mensagem PropSheet_InsertPage. Observe que o tamanho da folha de propriedades não pode ser alterado após sua criação. As páginas adicionadas ou inseridas não devem ser maiores do que a maior página atualmente na folha de propriedades. Para remover uma página, envie uma mensagem PSM_REMOVEPAGE.

Ao definir uma página, pode-se especificar o endereço de uma função de retorno de chamada PropSheetPageProc que a folha de propriedades chama quando está criando ou removendo a página. Ao utilizar PropSheetPageProc, tem a oportunidade de realizar operações de inicialização e limpeza para páginas individuais.

Observação

Um número de mensagens e uma chamada de função ocorrem enquanto a folha de propriedades está manipulando a lista de páginas. Enquanto esta ação está ocorrendo, tentar modificar a lista de páginas terá resultados imprevisíveis. Não adicione, insira ou remova páginas em sua implementação de PropSheetPageProc ou ao manipular as seguintes notificações e mensagens do Windows.

• PSN_APPLY
• PSN_KILLACTIVE
• PSN_RESET
• PSN_SETACTIVE
• PSN_WIZBACK
• PSN_WIZNEXT
• WM_INITDIALOG
• WM_DESTROY

Se surgir a necessidade de modificar uma página da folha de propriedades enquanto você estiver manipulando uma dessas mensagens ou enquanto PropSheetPageProc estiver em operação, publique uma mensagem privada do Windows. Seu aplicativo não receberá essa mensagem até que o gerente de folha de propriedades tenha concluído suas tarefas, momento em que será seguro modificar a lista de páginas.

Quando uma folha de propriedades é destruída, ela destrói automaticamente todas as páginas que foram adicionadas a ela. As páginas são destruídas na ordem inversa da especificada na matriz usada para criar as páginas. Para destruir uma página que foi criada pela função CreatePropertySheetPage, mas não foi adicionada à folha de propriedades, use a função DestroyPropertySheetPage.

Título da folha de propriedades e rótulos de página

Você especifica o título de uma folha de propriedades na estrutura PROPSHEETHEADER que se usa para criar a folha de propriedades. Se o membro dwFlags incluir o valor PSH_PROPTITLE, a folha de propriedades irá adicionar o sufixo "Properties" ou o prefixo "Properties for", dependendo da versão. Você pode alterar o título depois que uma folha de propriedades é criada usando a mensagem PSM_SETTITLE. Num Aero Wizard, esta mensagem pode ser usada para alterar dinamicamente o título de uma página interior.

Por padrão, uma folha de propriedades usa a cadeia de caracteres de nome especificada no modelo de caixa de diálogo como o rótulo de uma página. Você pode substituir a cadeia de caracteres de nome incluindo o valor PSP_USETITLE no membro dwFlags da estrutura PROPSHEETPAGE que define a página. Quando PSP_USETITLE é especificado, o membro pszTitle deve conter o endereço da cadeia de caracteres de etiqueta da página.

Ativação da página

Uma folha de propriedades pode ter apenas uma página ativa de cada vez. A página que tem a ativação está em primeiro plano da pilha sobreposta de páginas. O usuário ativa uma página selecionando sua guia; Um aplicativo ativa uma página usando a mensagem PSM_SETCURSEL.

A folha de propriedades envia o código de notificação PSN_KILLACTIVE para a página que está prestes a ser desativada. Em resposta, a página deve validar quaisquer alterações que o usuário tenha feito na página. Se a página exigir entrada adicional do usuário antes de perder a ativação, use a função SetWindowLong para definir o valor de DWL_MSGRESULT da página como TRUE. Além disso, a página deve exibir uma caixa de mensagem que descreve o problema e fornece a ação recomendada. Defina DWL_MSGRESULT para FALSE quando não houver problema em perder a ativação.

Antes que a página que está ganhando a ativação esteja visível, a folha de propriedades envia o código de notificação PSN_SETACTIVE para a página. A página deve responder inicializando suas janelas de controle.

Botão Ajuda

As folhas de propriedades podem exibir dois botões de Ajuda: um botão de Ajuda da folha de propriedades que é exibido na parte inferior do quadro, ao lado dos botões OK/Cancelar/Aplicar, e um botão padrão na barra de título que fornece Ajuda contextual.

O botão Ajuda da folha de propriedades é opcional e pode ser ativado página a página. Para exibir o botão Ajuda da folha de propriedades para uma ou mais páginas:

• Defina o sinalizador PSH_HASHELP no membro dwFlags da estrutura PROPSHEETHEADER da folha de propriedades.
• Para cada página que exibirá um botão Ajuda, defina o sinalizador PSP_HASHELP no membro dwFlags da estruturaPROPSHEETPAGEda página.

Quando o usuário clica no botão Ajuda, a página ativa recebe um código de notificação PSN_HELP. A página deve responder exibindo informações de Ajuda, normalmente chamando a função WinHelp.

Remover o botão Ajuda da barra de legendas

O botão Ajuda da barra de legendas é exibido por padrão, para que a Ajuda contextual esteja sempre disponível para os botões OK/Cancelar/Aplicar. No entanto, este botão pode ser removido, se necessário. Para remover o botão Ajuda da barra de título de uma folha de propriedades:

• Para versões dos controlos comuns anteriores à versão 5.80, deve-se implementar uma função de retorno da folha de propriedades .
• Para versão 5.80 e posteriores dos controlos comuns, pode simplesmente definir o sinalizador PSH_NOCONTEXTHELP no membro dwFlags da estrutura PROPSHEETHEADER da folha de propriedades. No entanto, se precisares de compatibilidade com versões anteriores de controlos comuns, deves implementar a função de chamada de retorno.

Para implementar uma função de callback da folha de propriedades que remove o botão Ajuda da barra de título:

• Defina o sinalizador PSH_USECALLBACK no dwFlags membro da estruturaPROPSHEETHEADER da folha de propriedades.
• Defina o membro pfnCallBack da estrutura PROPSHEETHEADER para apontar para a função de retorno de chamada.
• Implemente a função de retorno de chamada. Quando essa função receber a mensagem PSCB_PRECREATE, ela também receberá um ponteiro para o modelo de caixa de diálogo da folha de propriedades. Remova o estilo DS_CONTEXTHELP deste modelo.

O exemplo a seguir ilustra como implementar essa função de retorno de chamada:

int CALLBACK RemoveContextHelpProc(HWND hwnd, UINT message, LPARAM lParam)
{
    switch (message) 
    {
    case PSCB_PRECREATE:
        // Remove the DS_CONTEXTHELP style from the
        // dialog box template
        if (((LPDLGTEMPLATEEX)lParam)->signature ==    
           0xFFFF)
           {
            ((LPDLGTEMPLATEEX)lParam)->style 
            &= ~DS_CONTEXTHELP;
        }
        else {
            ((LPDLGTEMPLATE)lParam)->style 
            &= ~DS_CONTEXTHELP;
        }
        return TRUE;
    }
    return TRUE;
}

Se a estrutura DLGTEMPLATEEX não estiver definida, inclua a seguinte declaração:

#include <pshpack1.h>

typedef struct DLGTEMPLATEEX
{
    WORD dlgVer;
    WORD signature;
    DWORD helpID;
    DWORD exStyle;
    DWORD style;
    WORD cDlgItems;
    short x;
    short y;
    short cx;
    short cy;
} DLGTEMPLATEEX, *LPDLGTEMPLATEEX;

#include <poppack.h>

Botões OK, Cancelar e Aplicar

Os botões OK e Aplicar são semelhantes; Ambos direcionam as páginas de uma folha de propriedades para validar e aplicar as alterações de propriedade feitas pelo usuário. A única diferença é que clicar no botão OK faz com que a folha de propriedades seja destruída após a aplicação das alterações.

Quando o utilizador clica no botão OK ou Aplicar, a folha de propriedades envia uma notificação PSN_KILLACTIVE para a página ativa, para que ela tenha a oportunidade de validar as alterações do utilizador. Se as alterações forem válidas, a página deverá chamar a função SetWindowLong com o valor DWL_MSGRESULT definido como FALSE. Se as alterações do usuário não forem válidas, a página deverá definir DWL_MSGRESULT como TRUE e exibir uma caixa de diálogo informando o usuário sobre o problema. A página permanece ativa até definir DWL_MSGRESULT para FALSE em resposta a uma mensagem PSN_KILLACTIVE.

Assim que uma página responder a uma notificação de PSN_KILLACTIVE ao definir DWL_MSGRESULT para FALSE, a folha de propriedades enviará uma notificação de PSN_APPLY a cada página. Quando uma página recebe essa notificação, ela deve aplicar as novas propriedades ao item correspondente. Para indicar à folha de propriedades que as alterações são válidas para a página, chame SetWindowLong com DWL_MSGRESULT definido como PSNRET_NOERROR. Se as alterações forem inválidas para a página, retorne um erro. Isso evita que a ficha de propriedades seja destruída e devolve o foco para a página que recebeu a notificação de PSN_APPLY ou para a página que tinha foco quando o botão Aplicar foi pressionado. Para retornar um erro e indicar qual página receberá foco, defina DWL_MSGRESULT para um dos seguintes valores.

• PSNRET_INVALID. A folha de propriedades não será destruída e o foco será devolvido a esta página.
• PSNRET_INVALID_NOCHANGEPAGE. A folha de propriedades não será destruída e o foco será retornado para a página que tinha foco quando o botão foi pressionado.

Um aplicativo pode usar a mensagem PSM_APPLY para simular a seleção do botão Aplicar.

O botão Aplicar é inicialmente desativado quando uma página se torna ativa, indicando que ainda não há alterações de propriedade a serem aplicadas. Quando a página recebe entrada por meio de um de seus controles indicando que o usuário editou uma propriedade, a página deve enviar a mensagem PSM_CHANGED para a folha de propriedades. A mensagem faz com que a folha de propriedades habilite o botão Aplicar. Se, posteriormente, o usuário clicar no botão Aplicar ou Cancelar, a página deverá reinicializar seus controles e, em seguida, enviar a mensagem PSM_UNCHANGED para desativar novamente o botão Aplicar.

Às vezes, o botão Aplicar faz com que uma página faça uma alteração em uma folha de propriedades e a alteração não pode ser desfeita. Quando isso acontece, a página deve enviar a mensagem de PSM_CANCELTOCLOSE para a folha de propriedades. A mensagem faz com que a folha de propriedades altere o texto do botão OK para "Fechar", indicando que as alterações aplicadas não podem ser canceladas.

Às vezes, uma página faz uma alteração na configuração do sistema que requer que o Windows seja reiniciado ou o sistema reinicializado antes que a alteração possa entrar em vigor. Depois de fazer essa alteração, uma página deve enviar a mensagem PSM_RESTARTWINDOWS ou PSM_REBOOTSYSTEM para a folha de propriedades. Essas mensagens fazem com que a função PropertySheet retorne o valor ID_PSRESTARTWINDOWS ou ID_PSREBOOTSYSTEM depois que a folha de propriedades for destruída.

Quando um usuário clica no botão Cancelar, a folha de propriedades envia o código de notificação PSN_RESET para todas as páginas, indicando que a folha de propriedades está prestes a ser destruída. Uma página deve usar a notificação para executar operações de limpeza.

Feiticeiros

Um assistente é um tipo especial de folha de propriedades. Os assistentes são projetados para apresentar páginas uma de cada vez em uma sequência controlada pelo aplicativo. Em vez de selecionar a partir de um grupo de páginas clicando em uma guia, os usuários navegam para frente e para trás através da sequência, uma página de cada vez, clicando em botões. Por exemplo, a imagem de ecrã abaixo mostra a página de boas-vindas do assistente Adicionar Hardware:

A captura de tela a seguir mostra a primeira página de um Aero Wizard, o novo estilo introduzido no Windows Vista.

Consulte Criando assistentes para obter uma discussão completa sobre assistentes.