Classe `CPropertySheet`

Artigo
06/16/2023

Representa folhas de propriedades, também conhecidas como caixas de diálogo de guia.

Sintaxe

class CPropertySheet : public CWnd

Membros

Construtores públicos

Nome	Descrição
`CPropertySheet::CPropertySheet`	Constrói um objeto `CPropertySheet`.

Métodos públicos

Nome	Descrição
`CPropertySheet::AddPage`	Adiciona uma página à folha de propriedades.
`CPropertySheet::Construct`	Constrói um objeto `CPropertySheet`.
`CPropertySheet::Create`	Exibe uma folha de propriedades sem janela restrita.
`CPropertySheet::DoModal`	Exibe uma folha de propriedades modal.
`CPropertySheet::EnableStackedTabs`	Indica se a folha de propriedades usa guias empilhadas ou de rolagem.
`CPropertySheet::EndDialog`	Encerra a folha de propriedades.
`CPropertySheet::GetActiveIndex`	Recupera o índice da página ativa da folha de propriedades.
`CPropertySheet::GetActivePage`	Retorna o objeto da página ativa.
`CPropertySheet::GetPage`	Recupera um ponteiro para a página especificada.
`CPropertySheet::GetPageCount`	Recupera o número de páginas na folha de propriedades.
`CPropertySheet::GetPageIndex`	Recupera o índice da página especificada da folha de propriedades.
`CPropertySheet::GetTabControl`	Recupera um ponteiro para um controle guia.
`CPropertySheet::MapDialogRect`	Converte as unidades da caixa de diálogo de um retângulo em unidades de tela.
`CPropertySheet::OnInitDialog`	Substitui a inicialização da folha de propriedades aumentada.
`CPropertySheet::PressButton`	Simula a escolha do botão especificado em uma folha de propriedades.
`CPropertySheet::RemovePage`	Remove uma página da folha de propriedades.
`CPropertySheet::SetActivePage`	Define programaticamente o objeto ativo da página.
`CPropertySheet::SetFinishText`	Define o texto para o botão Concluir.
`CPropertySheet::SetTitle`	Define a legenda da folha de propriedades.
`CPropertySheet::SetWizardButtons`	Habilita os botões do assistente.
`CPropertySheet::SetWizardMode`	Habilita o modo assistente.

Membros de Dados Públicos

Nome	Descrição
`CPropertySheet::m_psh`	A estrutura `PROPSHEETHEADER` do Windows. Fornece acesso aos parâmetros básicos da folha de propriedades.

Comentários

Uma folha de propriedades consiste em um objeto CPropertySheet e um ou mais objetos CPropertyPage. A estrutura exibe uma folha de propriedades como uma janela com um conjunto de índices de guia e uma área que contém a página selecionada no momento. O usuário navega até uma página específica usando a guia apropriada.

CPropertySheetfornece suporte para a estrutura PROPSHEETHEADER expandida introduzida no Windows 98 e Windows NT 2000. A estrutura contém sinalizadores e membros adicionais que dão suporte ao uso de um bitmap em segundo plano de "marca d'água".

Para exibir as novas imagens automaticamente em seu objeto da folha de propriedades, passe valores válidos para as imagens de bitmap e paleta na chamada para CPropertySheet::Construct ou CPropertySheet::CPropertySheet.

Embora CPropertySheet não seja derivado de CDialog, o gerenciamento de um objeto CPropertySheet é como o gerenciamento de um objeto CDialog. Por exemplo, a criação de uma folha de propriedades requer construção em duas partes: chamar o construtor e, em seguida, chamar DoModal para uma folha de propriedades modal ou Create para uma folha de propriedades sem modo. CPropertySheet tem dois tipos de construtores: CPropertySheet::Construct e CPropertySheet::CPropertySheet.

Quando você constrói um objeto CPropertySheet, alguns Estilos de janela podem causar uma exceção de primeira chance. Isso resulta do sistema tentando alterar o estilo da folha de propriedades antes da criação da planilha. Para evitar essa exceção, defina os seguintes estilos ao criar seu CPropertySheet:

DS_3DLOOK
DS_CONTROL
WS_CHILD
WS_TABSTOP

Os estilos a seguir são opcionais e não causarão a exceção de primeira chance:

DS_SHELLFONT
DS_LOCALEDIT
WS_CLIPCHILDREN

Outros Window Styles são proibidos e você não deve habilitá-los.

A troca de dados entre um objeto CPropertySheet e um objeto externo é semelhante à troca de dados com um objeto CDialog. A diferença importante é que as configurações de uma folha de propriedades normalmente são variáveis membros dos objetos CPropertyPage em vez do objeto CPropertySheet em si.

É possível criar um tipo de caixa de diálogo de guia chamada assistente, que consiste em uma folha de propriedades com uma sequência de páginas de propriedades que orientam o usuário pelas etapas de uma operação, como a configuração de um dispositivo ou a criação de um boletim informativo. Em uma caixa de diálogo de guia de tipo de assistente, as páginas de propriedade não têm guias, e apenas uma página de propriedade fica visível por vez. Além disso, em vez de ter botões OK e Aplicar agora, uma caixa de diálogo de guia do tipo assistente tem um botão Voltar, um botão Avançar ou Concluir, um botão Cancelar e um botão Ajuda.

Para criar uma caixa de diálogo do tipo assistente, siga as mesmas etapas que você seguiria para criar uma folha de propriedades padrão, mas chame SetWizardMode antes de chamar DoModal. Para habilitar os botões do assistente, chame SetWizardButtonsusando sinalizadores para personalizar a função e aparência. Para habilitar o botão Concluir, chame SetFinishText depois que o usuário tiver tomado medidas na última página do assistente.

Para obter mais informações sobre como usar objetos CPropertySheet, consulte o artigo Folhas de propriedades e páginas de propriedades.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CPropertySheet

Requisitos

Cabeçalho: afxdlgs.h

`CPropertySheet::AddPage`

Adiciona a página fornecida com a guia mais à direita na folha de propriedades.

void AddPage(CPropertyPage* pPage);

Parâmetros

pPage
Aponta para a página a ser adicionada à folha de propriedades. Não pode ser NULL.

Comentários

Adicione páginas à folha de propriedades da esquerda para a direita na ordem que você deseja que elas apareçam.

AddPage adiciona o objeto CPropertyPage à lista de páginas do objeto CPropertySheet, mas não cria de fato a janela para essa página. A estrutura adia a criação da janela para a página até que o usuário selecione essa página.

Quando você adiciona uma página de propriedade usando AddPage, o CPropertySheet é o pai do CPropertyPage. Para obter acesso à folha de propriedades da página de propriedades, chame CWnd::GetParent.

Não é necessário aguardar a criação da janela da folha de propriedades para chamar AddPage. Normalmente, você chamará AddPage antes de chamar DoModal ou Create.

Se você chamar AddPage depois de exibir a página de propriedades, a linha de tabulação refletirá a página recém-adicionada.

Exemplo

// Add three pages to a CPropertySheet object, then show the 
// CPropertySheet object as a modal dialog.  CStylePage, CShapePage,  
// and CColorPage are CPropertyPage-derived classes created 
// by the Add Class wizard.  

CPropertySheet dlgPropertySheet(_T("Simple PropertySheet"));

CStylePage     stylePage;
CColorPage     colorPage;
CShapePage     shapePage;
dlgPropertySheet.AddPage(&stylePage);
dlgPropertySheet.AddPage(&colorPage);
dlgPropertySheet.AddPage(&shapePage);

dlgPropertySheet.DoModal();

`CPropertySheet::Construct`

Constrói um objeto CPropertySheet.

void Construct(
    UINT nIDCaption,
    CWnd* pParentWnd = NULL,
    UINT iSelectPage = 0);

void Construct(
    LPCTSTR pszCaption,
    CWnd* pParentWnd = NULL,
    UINT iSelectPage = 0);

void Construct(
    UINT nIDCaption,
    CWnd* pParentWnd,
    UINT iSelectPage,
    HBITMAP hbmWatermark,
    HPALETTE hpalWatermark = NULL,
    HBITMAP hbmHeader = NULL);

void Construct(
    LPCTSTR pszCaption,
    CWnd* pParentWnd,
    UINT iSelectPage,
    HBITMAP hbmWatermark,
    HPALETTE hpalWatermark = NULL,
    HBITMAP hbmHeader = NULL);

Parâmetros

nIDCaption
ID da legenda a ser usada para a folha de propriedades.

pParentWnd
Ponteiro para a janela pai da folha de propriedades. Se NULL, a janela pai será a janela principal do aplicativo.

iSelectPage
O índice da página que estará inicialmente na parte superior. O padrão é a primeira página adicionada à planilha.

pszCaption
Ponteiro para uma cadeia de caracteres que contém a legenda a ser usada para a folha de propriedades. Não pode ser NULL.

hbmWatermark
Identificador para o bitmap de marca d'água da página de propriedades.

hpalWatermark
Identificador para a paleta do bitmap de marca d'água e/ou bitmap de cabeçalho.

hbmHeader
Identificador para o bitmap de cabeçalho da página de propriedades.

Comentários

Chame essa função membro se um dos construtores de classe ainda não tiver sido chamado. Por exemplo, chame Construct quando você declarar ou alocar matrizes de objetos CPropertySheet. No caso de matrizes, você deve chamar Construct para cada membro na matriz.

Para exibir a folha de propriedades, chame DoModal ou Create. A cadeia de caracteres contida no primeiro parâmetro será colocada na barra de legenda da folha de propriedades.

Você pode exibir imagens de marca d'água e/ou cabeçalho automaticamente se usar o terceiro ou quarto protótipos de Construct, listados acima, e passar valores válidos para os parâmetros hbmWatermark, hpalWatermark e/ou hbmHeader.

Exemplo

O exemplo a seguir demonstra em quais circunstâncias você chamaria Construct.

const int c_cSheets = 3;
CPropertySheet   grpropsheet[c_cSheets];
// no need to call Construct for this next one
CPropertySheet   someSheet(_T("Some sheet"));

LPTSTR rgszSheets[c_cSheets] = {
   _T("Sheet 1"),
   _T("Sheet 2"),
   _T("Sheet 3")
};

for (int i = 0; i < c_cSheets; i++)
   grpropsheet[i].Construct(rgszSheets[i]);

`CPropertySheet::CPropertySheet`

Constrói um objeto CPropertySheet.

CPropertySheet();

explicit CPropertySheet(
    UINT nIDCaption,
    CWnd* pParentWnd = NULL,
    UINT iSelectPage = 0);

explicit CPropertySheet(
    LPCTSTR pszCaption,
    CWnd* pParentWnd = NULL,
    UINT iSelectPage = 0);

CPropertySheet(
    UINT nIDCaption,
    CWnd* pParentWnd,
    UINT iSelectPage,
    HBITMAP hbmWatermark,
    HPALETTE hpalWatermark = NULL,
    HBITMAP hbmHeader = NULL);

CPropertySheet(
    LPCTSTR pszCaption,
    CWnd* pParentWnd,
    UINT iSelectPage,
    HBITMAP hbmWatermark,
    HPALETTE hpalWatermark = NULL,
    HBITMAP hbmHeader = NULL);

Parâmetros

nIDCaption
ID da legenda a ser usada para a folha de propriedades.

pParentWnd
Aponta para a janela pai da folha de propriedades. Se NULL, a janela pai será a janela principal do aplicativo.

iSelectPage
O índice da página que estará inicialmente na parte superior. O padrão é a primeira página adicionada à planilha.

pszCaption
Aponta para uma cadeia de caracteres que contém a legenda a ser usada para a folha de propriedades. Não pode ser NULL.

hbmWatermark
Um identificador para o bitmap em segundo plano da folha de propriedades.

hpalWatermark
Um identificador para a paleta do bitmap de marca d'água e/ou bitmap de cabeçalho.

hbmHeader
Um identificador para o bitmap de cabeçalho da página de propriedades.

Comentários

Para exibir a folha de propriedades, chame DoModal ou Create. A cadeia de caracteres contida no primeiro parâmetro será colocada na barra de legenda da folha de propriedades.

Se você tiver vários parâmetros (por exemplo, se estiver usando uma matriz), use Construct em vez de CPropertySheet.

Você pode exibir imagens de marca d'água e/ou cabeçalho automaticamente se usar o terceiro ou quarto protótipos de CPropertySheet acima, e passar valores válidos para os parâmetros hbmWatermark, hpalWatermark e/ou hbmHeader.

Exemplo

// Declare a CPropertySheet object titled "Simple PropertySheet".
CPropertySheet dlgPropertySheet1(_T("Simple PropertySheet"));

// Declare a CPropertySheet object whose title is specified in the
// IDS_PROPERTYSHEET_TITLE string resource, and the second page is
// initially on top.  
CPropertySheet dlgPropertySheet2(IDS_PROPERTYSHEET_TITLE, this, 1);

`CPropertySheet::Create`

Exibe uma folha de propriedades sem janela restrita.

virtual BOOL Create(CWnd* pParentWnd = NULL,
    DWORD dwStyle = (DWORD)-1,
    DWORD dwExStyle = 0);

Parâmetros

pParentWnd
Aponta para a janela pai. Se NULL, o pai é a área de trabalho.

dwStyle
Estilos de janela para folha de propriedades. Para obter uma lista completa dos estilos disponíveis, consulte Estilos de janela.

dwExStyle
Estilos de janela estendidos para folha de propriedades. Para obter uma lista completa dos estilos disponíveis, consulte Estilos de janela estendida

Valor de retorno

Diferente de zero se a folha de propriedades for criada com êxito; caso contrário, 0.

Comentários

A chamada para Create pode estar dentro do construtor ou você pode chamá-la depois que o construtor for invocado.

O estilo padrão, expresso passando -1 como dwStyle, na verdade é WS_SYSMENU|WS_POPUP|WS_CAPTION|DS_MODALFRAME|DS_CONTEXTHELP|WS_VISIBLE. O estilo de janela estendida padrão, expresso passando 0 como dwExStyle, na verdade é WS_EX_DLGMODALFRAME.

A função membro Create retorna imediatamente após a criação da folha de propriedades. Para destruir a folha de propriedades, chame CWnd::DestroyWindow.

Folhas de propriedades sem modo exibidas com uma chamada para Create não têm botões OK, Cancelar, Aplicar agora e Ajuda, como as folhas de propriedades modais. Os botões desejados devem ser criados pelo usuário.

Para exibir uma folha de propriedades modal, chame DoModal.

Exemplo

// This code fragment shows how to create a modeless property sheet 
// dialog in a command message handler (OnModelessPropertySheet()) 
// of a CView-derived class.
void CPSheetView::OnModelessPropertySheet()
{
   // Declare a CPropertySheet object.  m_pdlgPropertySheet is a data
   // member of type CPropertySheet in CView-derived class.
   m_pdlgPropertySheet = new CPropertySheet(_T("Simple PropertySheet"));
   ASSERT(m_pdlgPropertySheet);

   // Add three pages to the CPropertySheet object.  Both m_pstylePage, 
   // m_pcolorPage, and m_pshapePage are data members of type 
   // CPropertyPage-derived classes in CView-derived class.
   m_pstylePage = new CStylePage;
   m_pcolorPage = new CColorPage;
   m_pshapePage = new CShapePage;
   m_pdlgPropertySheet->AddPage(m_pstylePage);
   m_pdlgPropertySheet->AddPage(m_pcolorPage);
   m_pdlgPropertySheet->AddPage(m_pshapePage);

   // Create a modeless CPropertySheet dialog.
   m_pdlgPropertySheet->Create();
}

// The code fragment below shows how to destroy the C++ objects for
// propertysheet and propertypage in the destructor of CView-derived
// class.
// NOTE:  DestroyWindow() is called in CPropertySheet::OnClose() so
// you do not need to call it here.  Property pages are children
// of the CPropertySheet, they will be destroyed by their parents.
CPSheetView::~CPSheetView()
{
   delete m_pshapePage;
   delete m_pstylePage;
   delete m_pcolorPage;
   delete m_pdlgPropertySheet;
}

`CPropertySheet::DoModal`

Exibe uma folha de propriedades modal.

virtual INT_PTR DoModal();

Valor de retorno

IDOK ou IDCANCEL se a função foi bem-sucedida; caso contrário, 0 ou -1. Se a folha de propriedades tiver sido estabelecida como um assistente (consulteSetWizardMode), DoModal retornará ID_WIZFINISH ou IDCANCEL.

Comentários

O valor retornado corresponde à ID do controle que fechou a folha de propriedades. Depois que essa função retornar, as janelas correspondentes à folha de propriedades e todas as páginas terão sido destruídas. Os próprios objetos ainda existirão. Normalmente, você recuperará dados dos objetos CPropertyPage após DoModal retornar IDOK.

Para exibir uma folha de propriedades sem modo, chame Create.

Quando uma página de propriedades é criada a partir do recurso de diálogo correspondente, ela pode causar uma exceção de primeira chance. Isso resulta da alteração pela página de propriedades do estilo do recurso de diálogo para o estilo necessário antes da página ser criada. Como os recursos geralmente são somente leitura, isso gera uma exceção. O sistema identifica a exceção e faz uma cópia do recurso modificado. Portanto, a exceção de primeira chance pode ser ignorada.

Observação

Essa exceção deve ser tratada pelo sistema operacional se você estiver compilando com o modelo assíncrono de tratamento de exceção. Para mais informações sobre os modelos do tratamento de exceção, confira /EH (Modelo do tratamento de exceção). Nesse caso, não encapsule as chamadas em CPropertySheet::DoModal com um bloco try-catch C++ no qual a captura manipula todas as exceções, por exemplo, catch (...). Esse bloco trataria a exceção destinada ao sistema operacional e causaria um comportamento imprevisível. No entanto, você pode usar com segurança o tratamento de exceções C++ com tipos de exceção específicos ou tratamento de exceção estruturada em que a exceção de Violação de Acesso é passada para o sistema operacional.

Para evitar gerar essa exceção de primeira chance, você pode garantir manualmente que a folha de propriedades tenha os Estilos de janela corretos. Você precisa definir os seguintes estilos para uma folha de propriedades:

DS_3DLOOK
DS_CONTROL
WS_CHILD
WS_TABSTOP

Você pode usar os seguintes estilos opcionais sem causar uma exceção de primeira chance:

DS_SHELLFONT
DS_LOCALEDIT
WS_CLIPCHILDREN

Desabilite todos os outros estilos do Windows porque eles não são compatíveis com as folhas de propriedades. Esse conselho não se aplica aos estilos estendidos. A definição adequada desses estilos padrão garantirá que a folha de propriedades não precise ser modificada e evitará gerar a exceção de primeira chance.

Exemplo

Confira o exemplo de CPropertySheet::AddPage.

`CPropertySheet::EnableStackedTabs`

Indica se é necessário empilhar linhas de guias em uma folha de propriedades.

void EnableStackedTabs(BOOL bStacked);

Parâmetros

bStacked
Indica se as guias empilhadas estão habilitadas na folha de propriedades. Desabilite linhas empilhadas de marcas definindo bStacked como FALSE.

Comentários

Por padrão, se uma folha de propriedades tiver mais guias do que couber em uma única linha na largura da folha de propriedades, as guias serão empilhadas em várias linhas. Para usar guias de rolagem em vez de empilhar guias, chame EnableStackedTabs com bStacked definido como FALSE antes de chamar DoModal ou Create.

Você deve chamar EnableStackedTabs quando cria uma folha de propriedades modal ou sem modo. Para incorporar esse estilo em uma classe derivada de CPropertySheet, grave um manipulador de mensagens para WM_CREATE. Na versão substituída de CWnd::OnCreate, chame EnableStackedTabs( FALSE ) antes de chamar a implementação da classe base.

Exemplo

int CMyPropertySheet::OnCreate(LPCREATESTRUCT lpCreateStruct)
{
   // Set for Scrolling Tabs style
   EnableStackedTabs(FALSE);
   // Call the base class
   if (CPropertySheet::OnCreate(lpCreateStruct) == -1)
      return -1;

   return 0;
}

`CPropertySheet::EndDialog`

Encerra a folha de propriedades.

void EndDialog(int nEndID);

Parâmetros

nEndID
Identificador a ser usado como valor retornado da folha de propriedades.

Comentários

Essa função membro é chamada pela estrutura quando o botão OK, Cancelar ou Fechar é pressionado. Chame essa função membro se ocorrer um evento que deve fechar a folha de propriedades.

Essa função membro é usada apenas com um diálogo modal.

Exemplo

Confira o exemplo de CPropertySheet::PressButton.

`CPropertySheet::GetActiveIndex`

Obtém o número de índice da página ativa da janela da folha de propriedades e, em seguida, usa o número de índice retornado como o parâmetro para GetPage.

int GetActiveIndex() const;

Valor de retorno

O número de índice da página ativa.

Exemplo

Confira o exemplo de CPropertySheet::GetActivePage.

`CPropertySheet::GetActivePage`

Recupera a página ativa da janela da folha de propriedades.

CPropertyPage* GetActivePage() const;

Valor de retorno

O ponteiro para a página ativa.

Comentários

Use essa função membro para executar alguma ação na página ativa.

Exemplo

// The code fragment below sets the last active page (i.e. the 
// active page when the propertysheet was closed) to be the first 
// visible page when the propertysheet is shown. The last active 
// page was saved in m_LastActivePage, (a member variable of 
// CDocument-derived class) when OK was selected from the 
// propertysheet. CMyPropertySheet is a CPropertySheet-derived class.
BOOL CMyPropertySheet::OnInitDialog()
{
   BOOL bResult = CPropertySheet::OnInitDialog();

   CMDIFrameWnd* pframe = (CMDIFrameWnd*)AfxGetMainWnd();
   CMDIChildWnd* pchild = pframe->MDIGetActive();
   CPSheetDoc* doc = (CPSheetDoc*)pchild->GetActiveDocument();
   SetActivePage(doc->m_LastActivePage);

   return bResult;
}

BOOL CMyPropertySheet::OnCommand(WPARAM wParam, LPARAM lParam)
{
   if (LOWORD(wParam) == IDOK)
   {
      CMDIFrameWnd* pframe = (CMDIFrameWnd*)AfxGetMainWnd();
      CMDIChildWnd* pchild = pframe->MDIGetActive();
      CPSheetDoc* doc = (CPSheetDoc*)pchild->GetActiveDocument();
      doc->m_LastActivePage = GetPageIndex(GetActivePage()); // or GetActiveIndex()
   }

   return CPropertySheet::OnCommand(wParam, lParam);
}

`CPropertySheet::GetPage`

Retorna um ponteiro para a página especificada nesta folha de propriedades.

CPropertyPage* GetPage(int nPage) const;

Parâmetros

nPage
Índice da página desejada, começando em 0. Deve ser entre 0 e um, menos que o número de páginas na folha de propriedades, inclusive.

Valor de retorno

O ponteiro para a página correspondente ao parâmetro nPage.

Exemplo

Confira o exemplo de CPropertyPage::OnWizardFinish.

`CPropertySheet::GetPageCount`

Determina o número de páginas atualmente na folha de propriedades.

int GetPageCount() const;

Valor de retorno

O número de páginas na folha de propriedades.

Exemplo

Confira o exemplo de CPropertyPage::OnWizardFinish.

`CPropertySheet::GetPageIndex`

Recupera o número do índice da página especificada na folha de propriedades.

int GetPageIndex(CPropertyPage* pPage);

Parâmetros

pPage
Aponta para a página com o índice a ser encontrado. Não pode ser NULL.

Valor de retorno

O número de índice de uma página.

Comentários

Por exemplo, você usaria GetPageIndex para obter o índice de página para usar SetActivePage ou GetPage.

Exemplo

Confira o exemplo de CPropertySheet::GetActivePage.

`CPropertySheet::GetTabControl`

Recupera um ponteiro para um controle guia para fazer algo específico ao controle guia (ou seja, para usar qualquer uma das APIs em CTabCtrl).

CTabCtrl* GetTabControl() const;

Valor de retorno

Um ponteiro para um controle guia.

Comentários

Por exemplo, chame essa função membro se você quiser adicionar bitmaps a cada uma das guias durante a inicialização.

Exemplo

// Create and associate a tooltip control to the tab control of 
// CMyTTPropertySheet.  CMyTTPropertySheet is a CPropertySheet-derived
// class.
BOOL CMyTTPropertySheet::OnInitDialog()
{
   BOOL bResult = CPropertySheet::OnInitDialog();

   // Create a tooltip control.  m_pToolTipCtrl is a member variable
   // of type CToolTipCtrl* in CMyTTPropertySheet class.  It is 
   // initialized to NULL in the constructor, and destroyed in the 
   // destructor of CMyTTPropertySheet class.
   m_pToolTipCtrl = new CToolTipCtrl;
   if (!m_pToolTipCtrl->Create(this))
   {
      TRACE(_T("Unable To create ToolTip\n"));
      return bResult;
   }

   // Associate the tooltip control to the tab control
   // of CMyPropertySheet.
   CTabCtrl* ptab = GetTabControl();
   ptab->SetToolTips(m_pToolTipCtrl);

   // Get the bounding rectangle of each tab in the tab control of the
   // property sheet. Use this rectangle when registering a tool with 
   // the tool tip control.  IDS_FIRST_TOOLTIP is the first ID string 
   // resource that contains the text for the tool.
   int count = ptab->GetItemCount();
   int id = IDS_FIRST_TOOLTIP;
   for (int i = 0; i < count; i++)
   {
      CRect r;
      ptab->GetItemRect(i, &r);
      VERIFY(m_pToolTipCtrl->AddTool(ptab, id, &r, id));
      id++;
   }

   // Activate the tooltip control.
   m_pToolTipCtrl->Activate(TRUE);

   return bResult;
}

// Override PreTranslateMessage() so RelayEvent() can be 
// called to pass a mouse message to CMyTTPropertySheet's 
// tooltip control for processing.
BOOL CMyTTPropertySheet::PreTranslateMessage(MSG* pMsg)
{
   if (NULL != m_pToolTipCtrl)
      m_pToolTipCtrl->RelayEvent(pMsg);

   return CPropertySheet::PreTranslateMessage(pMsg);
}

`CPropertySheet::m_psh`

Uma estrutura cujos membros armazenam as características de PROPSHEETHEADER.

Comentários

Use essa estrutura para inicializar a aparência da folha de propriedades depois que ela for construída, mas antes de ser exibida com a função membro DoModal. Por exemplo, defina o membro dwSize de m_psh no tamanho que você deseja que a folha de propriedades tenha.

Para obter mais informações sobre essa estrutura, incluindo uma listagem de seus membros, consulte PROPSHEETHEADER no SDK do Windows.

Exemplo

// This code fragment shows how to change CPropertySheet's settings 
// before it is shown.  After the changes, CPropertySheet has the 
// caption "Simple Properties", no "Apply" button, and the 
// second page (CColorPage) initially on top.  

CPropertySheet dlgPropertySheet(_T("Simple PropertySheet"));

CStylePage stylePage;
CColorPage colorPage;
CShapePage shapePage;
dlgPropertySheet.AddPage(&stylePage);
dlgPropertySheet.AddPage(&colorPage);
dlgPropertySheet.AddPage(&shapePage);

dlgPropertySheet.m_psh.dwFlags |= PSH_NOAPPLYNOW | PSH_PROPTITLE;
dlgPropertySheet.m_psh.pszCaption = _T("Simple");
dlgPropertySheet.m_psh.nStartPage = 1;

dlgPropertySheet.DoModal();

`CPropertySheet::MapDialogRect`

Converte as unidades da caixa de diálogo de um retângulo em unidades de tela.

void MapDialogRect(LPRECT lpRect) const;

Parâmetros

lpRect
Aponta para uma estrutura RECT ou objeto CRect que contém as coordenadas da caixa de diálogo a serem convertidas.

Comentários

As unidades de caixa de diálogo são declaradas em termos da unidade base da caixa de diálogo atual derivada da largura média e da altura dos caracteres na fonte usada para o texto da caixa de diálogo. Uma unidade horizontal é um quarto da unidade de largura base da caixa de diálogo e uma unidade vertical é um oitavo da unidade de altura base da caixa de diálogo.

A função GetDialogBaseUnits do Windows retorna informações de tamanho para a fonte do sistema, mas você poderá especificar uma fonte diferente para cada folha de propriedades se usar o estilo DS_SETFONT no arquivo de definição de recurso. A função MapDialogRect do Windows, descrita no SDK do Windows, usa a fonte apropriada para essa caixa de diálogo.

A função membro MapDialogRect substitui as unidades de caixa de diálogo em lpRect por unidades de tela (pixels) para que o retângulo possa ser usado para criar uma caixa de diálogo ou posicionar um controle dentro de uma caixa.

`CPropertySheet::OnInitDialog`

Substitui a inicialização da folha de propriedades aumentada.

virtual BOOL OnInitDialog();

Valor de retorno

Especifica se o aplicativo definiu o foco de entrada como um dos controles na folha de propriedades. Se OnInitDialog retornar diferente de zero, o Windows definirá o foco de entrada como o primeiro controle na folha de propriedades. O aplicativo só poderá retornar 0 se tiver definido explicitamente o foco de entrada para um dos controles na folha de propriedades.

Comentários

Essa função de membro é chamada em resposta à mensagem WM_INITDIALOG. Essa mensagem é enviada para a folha de propriedades durante as chamadas a Create ou DoModal, que ocorrem imediatamente antes da exibição da folha de propriedades.

Substitua essa função de membro se você precisar executar o processamento especial quando a folha de propriedades for inicializada. Na versão substituída, primeiro chame a classe base OnInitDialog, mas desconsidere o valor retornado. Normalmente, você retornará TRUE de sua função de membro substituída.

Você não precisa de uma entrada de mapa de mensagens para essa função membro.

`CPropertySheet::PressButton`

Simula a escolha do botão especificado em uma folha de propriedades.

void PressButton(int nButton);

Parâmetros

nButton
nButton : identifica o botão a ser pressionado. Esse parâmetro pode usar um dos valores a seguir:

PSBTN_BACK Escolhe o botão Voltar.
PSBTN_NEXT Escolhe o botão Avançar.
PSBTN_FINISH Escolhe o botão Concluir.
PSBTN_OK Escolhe o botão OK.
PSBTN_APPLYNOW Escolhe o botão Aplicar agora.
PSBTN_CANCEL Escolhe o botão Cancelar.
PSBTN_HELP Escolhe o botão Ajuda.

Comentários

Confira PSM_PRESSBUTTON para mais informações sobre a mensagem Pressbutton do SDK do Windows.

Uma chamada para PressButton não enviar a notificação PSN_APPLY de uma página de propriedade para a estrutura. Para enviar essa notificação, chame CPropertyPage::OnOK.

Exemplo

// Simulate the selection of OK and Cancel buttons when Alt+K and
// Alt+C are pressed.  CMyPropertySheet is a CPropertySheet-derived 
// class.
BOOL CMyPropertySheet::PreTranslateMessage(MSG* pMsg)
{
   if (pMsg->message >= WM_KEYFIRST && pMsg->message <= WM_KEYLAST)
   {
      BOOL altkey = GetKeyState(VK_MENU) < 0;
      if (altkey)
      {
         BOOL handled = TRUE;
         switch (toupper((int)pMsg->wParam))
         {
         case 'C':                     // for Alt+C - Cancel button
            PressButton(PSBTN_CANCEL);   // or EndDialog(IDCANCEL);
            break;

         case 'K':                     // for Alt+K - OK button
            PressButton(PSBTN_OK);      // or EndDialog(IDOK);
            break;

         default:
            handled = FALSE;
         }

         if (handled)
            return TRUE;
      }
   }

   return CPropertySheet::PreTranslateMessage(pMsg);
}

`CPropertySheet::RemovePage`

Remove uma página da folha de propriedades e destrói a janela associada.

void RemovePage(CPropertyPage* pPage);
void RemovePage(int nPage);

Parâmetros

pPage
Aponta para a página a ser removida da folha de propriedades. Não pode ser NULL.

nPage
Índice da página a ser removida. Deve ser entre 0 e um, menos que o número de páginas na folha de propriedades, inclusive.

Comentários

O objeto CPropertyPage em si não será destruído até que o proprietário da janela CPropertySheet seja fechado.

`CPropertySheet::SetActivePage`

Altera a página ativa.

BOOL SetActivePage(int nPage);
BOOL SetActivePage(CPropertyPage* pPage);

Parâmetros

nPage
Índice da página a ser definida. Deve estar entre 0 e um, menos que o número de páginas na folha de propriedades, inclusive.

pPage
Aponta para a página a ser definida na folha de propriedades. Não pode ser NULL.

Valor de retorno

Diferente de zero se a folha de propriedades for ativada com êxito; caso contrário, 0.

Comentários

Por exemplo, use SetActivePage se a ação de um usuário em uma página deve fazer com que outra página se torne a página ativa.

Exemplo

Confira o exemplo de CPropertySheet::GetActivePage.

`CPropertySheet::SetFinishText`

Define o texto no botão de comando Concluir.

void SetFinishText(LPCTSTR lpszText);

Parâmetros

lpszText
Aponta para o texto a ser exibido no botão de comando Concluir.

Comentários

Chame SetFinishText para exibir o texto no botão do comando Concluir e oculte os botões Avançar e Voltar depois que o usuário concluir a ação na última página do assistente.

Exemplo

// CShapePage is the last wizard property page. Enable the Back 
// button and change the Next button to Finish. The "Finish" button 
// will have "Done" as its caption.
BOOL CShapePage::OnSetActive()
{
   CPropertySheet* psheet = (CPropertySheet*)GetParent();
   psheet->SetWizardButtons(PSWIZB_BACK | PSWIZB_FINISH);
   psheet->SetFinishText(_T("Done"));

   return CPropertyPage::OnSetActive();
}

`CPropertySheet::SetTitle`

Especifica a legenda da folha de propriedades (o texto exibido na barra de título de uma janela de quadro).

void SetTitle(
    LPCTSTR lpszText,
    UINT nStyle = 0);

Parâmetros

nStyle
Especifica o estilo do título da folha de propriedades. O estilo deve ser especificado em 0 ou como PSH_PROPTITLE. Se o estilo for definido como PSH_PROPTITLE, a palavra "Propriedades" será exibida após o texto especificado como a legenda. Por exemplo, chamar SetTitle("Simples" PSH_PROPTITLE) resultará em uma legenda de folha de propriedades de "Propriedades simples".

lpszText
Aponta para o texto a ser usado como a legenda na barra de título da folha de propriedades.

Comentários

Por padrão, uma folha de propriedades usa o parâmetro de legenda no construtor da folha de propriedades.

Exemplo

// Declare a CPropertySheet object with a caption "Simple PropertySheet".
CPropertySheet dlgPropertySheet(_T("Simple PropertySheet"));

// Add three pages to the CPropertySheet object. CStylePage, CColorPage,
// and CShapePage are CPropertyPage-derived classes created
// by the Add Class wizard.
CStylePage     stylePage;
CColorPage     colorPage;
CShapePage     shapePage;
dlgPropertySheet.AddPage(&stylePage);
dlgPropertySheet.AddPage(&colorPage);
dlgPropertySheet.AddPage(&shapePage);

// Change the caption of the CPropertySheet object 
// from "Simple PropertySheet" to "Simple Properties".
dlgPropertySheet.SetTitle(_T("Simple"), PSH_PROPTITLE);

// Show the CPropertySheet object as MODAL.
dlgPropertySheet.DoModal();

`CPropertySheet::SetWizardButtons`

Habilita ou desabilita o botão Voltar, Avançar ou Concluir em uma folha de propriedades do assistente.

void SetWizardButtons(DWORD dwFlags);

Parâmetros

dwFlags
Um conjunto de sinalizadores que personalizam a função e a aparência dos botões do assistente. Esse parâmetro pode ser uma combinação dos seguintes valores:

PSWIZB_BACKBotão Voltar
PSWIZB_NEXT Botão Avançar
PSWIZB_FINISHBotão Concluir
PSWIZB_DISABLEDFINISH Botão Concluir desabilitado

Comentários

Chame SetWizardButtons somente depois que a caixa de diálogo estiver aberta; você não poderá chamar SetWizardButtons antes de chamar DoModal. Normalmente, você deve chamar SetWizardButtons de CPropertyPage::OnSetActive.

Se você quiser alterar o texto no botão Concluir ou ocultar os botões Avançar e Voltar depois que o usuário tiver concluído o assistente, chame SetFinishText. Observe que o mesmo botão é compartilhado para Concluir e Avançar. Você pode exibir um botão Concluir ou Avançar de uma só vez, mas não ambos.

Exemplo

CPropertySheet tem três páginas de propriedades do assistente: CStylePage, CColorPage e CShapePage. O fragmento de código abaixo mostra como habilitar e desabilitar os botões Voltar e Avançar na página de propriedades do assistente.

// CStylePage is the first wizard property page.  Disable the Back 
// button but enable the Next button.
BOOL CStylePage::OnSetActive() 
{
   CPropertySheet* psheet = (CPropertySheet*) GetParent();   
   psheet->SetWizardButtons(PSWIZB_NEXT);
   
   return CPropertyPage::OnSetActive();
}

// CColorPage is the second wizard property page. Enable both the 
// Back button and the Next button.
BOOL CColorPage::OnSetActive()
{
   CPropertySheet* psheet = (CPropertySheet*)GetParent();
   psheet->SetWizardButtons(PSWIZB_BACK | PSWIZB_NEXT);

   return CPropertyPage::OnSetActive();
}

// CShapePage is the last wizard property page. Enable the Back 
// button and change the Next button to Finish. The "Finish" button 
// will have "Done" as its caption.
BOOL CShapePage::OnSetActive()
{
   CPropertySheet* psheet = (CPropertySheet*)GetParent();
   psheet->SetWizardButtons(PSWIZB_BACK | PSWIZB_FINISH);
   psheet->SetFinishText(_T("Done"));

   return CPropertyPage::OnSetActive();
}

`CPropertySheet::SetWizardMode`

Estabelece uma página de propriedades como assistente.

void SetWizardMode();

Comentários

Uma característica fundamental de uma página de propriedades de assistente é que o usuário navega usando Avançar ou Concluir, Voltar e Cancelar em vez de guias.

Chame SetWizardMode antes de chamar DoModal. Depois que você chamar SetWizardMode, DoModal retornará ID_WIZFINISH (se o usuário fechar com o botão Concluir) ou IDCANCEL.

SetWizardMode define o sinalizador PSH_WIZARD.

Exemplo

CPropertySheet sheet(_T("Simple PropertySheet"));

CStylePage pageStyle;
CColorPage pageColor;
CShapePage pageShape;

sheet.AddPage(&pageStyle);
sheet.AddPage(&pageColor);
sheet.AddPage(&pageShape);

sheet.SetWizardMode();

sheet.DoModal();

Confira também

Exemplo de MFC CMNCTRL1
Exemplo de MFC CMNCTRL2
Exemplo de MFC PROPDLG
Exemplo de MFC SNAPVW
Classe CWnd
Gráfico da hierarquia

Compartilhar via

Classe CPropertySheet

Sintaxe

Membros

Construtores públicos

Métodos públicos

Membros de Dados Públicos

Comentários

Hierarquia de herança

Requisitos

CPropertySheet::AddPage

Parâmetros

Comentários

Exemplo

CPropertySheet::Construct

Parâmetros

Comentários

Exemplo

CPropertySheet::CPropertySheet

Parâmetros

Comentários

Exemplo

CPropertySheet::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CPropertySheet::DoModal

Valor de retorno

Comentários

Exemplo

CPropertySheet::EnableStackedTabs

Parâmetros

Comentários

Exemplo

CPropertySheet::EndDialog

Parâmetros

Comentários

Exemplo

CPropertySheet::GetActiveIndex

Valor de retorno

Exemplo

CPropertySheet::GetActivePage

Valor de retorno

Comentários

Exemplo

CPropertySheet::GetPage

Parâmetros

Valor de retorno

Exemplo

CPropertySheet::GetPageCount

Valor de retorno

Exemplo

CPropertySheet::GetPageIndex

Parâmetros

Valor de retorno

Comentários

Exemplo

CPropertySheet::GetTabControl

Valor de retorno

Comentários

Exemplo

CPropertySheet::m_psh

Comentários

Exemplo

CPropertySheet::MapDialogRect

Parâmetros

Comentários

CPropertySheet::OnInitDialog

Valor de retorno

Comentários

CPropertySheet::PressButton

Parâmetros

Comentários

Exemplo

CPropertySheet::RemovePage

Parâmetros

Comentários

CPropertySheet::SetActivePage

Parâmetros

Classe `CPropertySheet`

`CPropertySheet::AddPage`

`CPropertySheet::Construct`

`CPropertySheet::CPropertySheet`

`CPropertySheet::Create`

`CPropertySheet::DoModal`

`CPropertySheet::EnableStackedTabs`

`CPropertySheet::EndDialog`

`CPropertySheet::GetActiveIndex`

`CPropertySheet::GetActivePage`

`CPropertySheet::GetPage`

`CPropertySheet::GetPageCount`

`CPropertySheet::GetPageIndex`

`CPropertySheet::GetTabControl`

`CPropertySheet::m_psh`

`CPropertySheet::MapDialogRect`

`CPropertySheet::OnInitDialog`

`CPropertySheet::PressButton`

`CPropertySheet::RemovePage`

`CPropertySheet::SetActivePage`

`CPropertySheet::SetFinishText`

`CPropertySheet::SetTitle`

`CPropertySheet::SetWizardButtons`

`CPropertySheet::SetWizardMode`