Clase `CPropertySheet`

Artículo
06/16/2023

Representa hojas de propiedades, también conocidas como cuadros de diálogo de pestaña.

Sintaxis

class CPropertySheet : public CWnd

Miembros

Constructores públicos

Nombre	Descripción
`CPropertySheet::CPropertySheet`	Construye un objeto `CPropertySheet`.

Métodos públicos

Nombre	Descripción
`CPropertySheet::AddPage`	Agrega una página a la hoja de propiedades.
`CPropertySheet::Construct`	Construye un objeto `CPropertySheet`.
`CPropertySheet::Create`	Muestra una hoja de propiedades no modal.
`CPropertySheet::DoModal`	Muestra una hoja de propiedades modal.
`CPropertySheet::EnableStackedTabs`	Indica si la hoja de propiedades usa pestañas apiladas o de desplazamiento.
`CPropertySheet::EndDialog`	Finaliza la hoja de propiedades.
`CPropertySheet::GetActiveIndex`	Recupera el índice de la página activa de la hoja de propiedades.
`CPropertySheet::GetActivePage`	Devuelve el objeto de página activo.
`CPropertySheet::GetPage`	Recupera un puntero a la página especificada.
`CPropertySheet::GetPageCount`	Recupera el número de páginas de la hoja de propiedades.
`CPropertySheet::GetPageIndex`	Recupera el índice de la página especificada de la hoja de propiedades.
`CPropertySheet::GetTabControl`	Recupera un puntero a un control de ficha.
`CPropertySheet::MapDialogRect`	Convierte las unidades de cuadro de diálogo de un rectángulo en unidades de pantalla.
`CPropertySheet::OnInitDialog`	Invalidar para aumentar la inicialización de la hoja de propiedades.
`CPropertySheet::PressButton`	Simula la elección del botón especificado en una hoja de propiedades.
`CPropertySheet::RemovePage`	Elimina una página de la hoja de propiedades.
`CPropertySheet::SetActivePage`	Establece mediante programación el objeto de la página activa.
`CPropertySheet::SetFinishText`	Establece el texto del botón Finalizar.
`CPropertySheet::SetTitle`	Establece el título de la hoja de propiedades.
`CPropertySheet::SetWizardButtons`	Habilita los botones del asistente.
`CPropertySheet::SetWizardMode`	Habilita el modo del asistente.

Miembros de datos públicos

Nombre	Descripción
`CPropertySheet::m_psh`	La estructura de Windows `PROPSHEETHEADER`. Proporciona acceso a los parámetros básicos de la hoja de propiedades.

Comentarios

Una hoja de propiedades consta de un objeto CPropertySheet y uno o varios objetos CPropertyPage. El marco muestra una hoja de propiedades como una ventana con un conjunto de índices de pestañas y un área que contiene la página seleccionada actualmente. El usuario navega a una página específica utilizando la pestaña correspondiente.

CPropertySheet proporciona compatibilidad con la estructura expandida PROPSHEETHEADER introducida en Windows 98 y Windows NT 2000. La estructura contiene marcas y miembros adicionales que admiten el uso de un mapa de bits de fondo de "marca de agua".

Para mostrar estas imágenes nuevas automáticamente en el objeto de hoja de propiedades, pase valores válidos para las imágenes de mapa de bits y paleta en la llamada a CPropertySheet::Construct o CPropertySheet::CPropertySheet.

Aunque CPropertySheet no se deriva de CDialog, administrar un objeto CPropertySheet es como administrar un objeto CDialog. Por ejemplo, la creación de una hoja de propiedades requiere una construcción de dos partes: llame al constructor y, a continuación, llame a DoModal para una hoja de propiedades modal o Create para una hoja de propiedades no modal. CPropertySheet tiene dos tipos de constructores: CPropertySheet::Construct y CPropertySheet::CPropertySheet.

Al construir e un objeto CPropertySheet, algunos estilos de ventana pueden provocar que se produzca una excepción de primera oportunidad. Esto se debe a que el sistema intenta cambiar el estilo de la hoja de propiedades antes de que se cree la hoja. Para evitar esta excepción, asegúrese de configurar los siguientes estilos cuando cree: CPropertySheet

DS_3DLOOK
DS_CONTROL
WS_CHILD
WS_TABSTOP

Los estilos siguientes son opcionales y no provocarán la excepción de primera oportunidad:

DS_SHELLFONT
DS_LOCALEDIT
WS_CLIPCHILDREN

Cualquier otro Window Styles está prohibido y no debe habilitarlos.

El intercambio de datos entre un objeto CPropertySheet y un objeto externo es similar al intercambio de datos con un objeto CDialog. La diferencia importante es que la configuración de una hoja de propiedades suele ser variables miembro de los objetos CPropertyPage en lugar del propio objeto CPropertySheet.

Puede crear un tipo de cuadro de diálogo de tabulación denominado asistente, que consta de una hoja de propiedades con una secuencia de páginas de propiedades que guían al usuario a través de los pasos de una operación, como configurar un dispositivo o crear un boletín. En un cuadro de diálogo de pestaña de tipo asistente, las páginas de propiedades no tienen pestañas y solo una página de propiedades está visible a la vez. Además, en lugar de tener botones Aceptar y Aplicar ahora, un cuadro de diálogo de pestaña de tipo asistente tiene un botón Atrás, un botón Siguiente o Finalizar, un botón Cancelar y un botón Ayuda.

Para crear un cuadro de diálogo de tipo asistente, siga los mismos pasos que seguiría para crear una hoja de propiedades estándar, pero llame a SetWizardMode antes de llamar a DoModal. Para habilitar los botones del asistente, llame a SetWizardButtons, mediante marcas para personalizar su función y apariencia. Para habilitar el botón Finalizar, llame a SetFinishText después de que el usuario haya realizado la acción en la última página del asistente.

Para obtener más información sobre cómo usar objetos CPropertySheet, vea el artículo Hojas de propiedades y páginas de propiedades.

Jerarquía de herencia

CObject

CCmdTarget

CWnd

CPropertySheet

Requisitos

Encabezado: afxdlgs.h

`CPropertySheet::AddPage`

Agrega la página proporcionada con la pestaña situada más a la derecha en la hoja de propiedades.

void AddPage(CPropertyPage* pPage);

Parámetros

pPage
Apunta a la página que se va a agregar a la hoja de propiedades. El valor no puede ser NULL.

Comentarios

Agregue páginas a la hoja de propiedades en el orden de izquierda a derecha que desea que aparezcan.

AddPage agrega el objeto CPropertyPage a la lista de páginas del objeto CPropertySheet, pero no crea realmente la ventana de la página. El marco pospone la creación de la ventana para la página hasta que el usuario selecciona esa página.

Al agregar una página de propiedades mediante AddPage, eCPropertySheet es el elemento primario del CPropertyPage. Para obtener acceso a la hoja de propiedades desde la página de propiedades, llame a CWnd::GetParent.

No es necesario esperar hasta la creación de la ventana de hoja de propiedades para llamar a AddPage. Normalmente, llamará a AddPage antes de llamar a DoModal o a Create.

Si llama a AddPage después de mostrar la página de propiedades, la fila de pestaña reflejará la página recién agregada.

Ejemplo

// 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`

Construye un 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
Identificador del título que se va a usar para la hoja de propiedades.

pParentWnd
Puntero a la ventana primaria de la hoja de propiedades. Si NULL, la ventana primaria será la ventana principal de la aplicación.

iSelectPage
Índice de la página que inicialmente estará en la parte superior. El valor predeterminado es la primera página agregada a la hoja.

pszCaption
Puntero a una cadena que contiene el título que se va a usar para la hoja de propiedades. El valor no puede ser NULL.

hbmWatermark
Identificador del mapa de bits de marca de agua de la página de propiedades.

hpalWatermark
Controle la paleta del mapa de bits de marca de agua o del mapa de bits de encabezado.

hbmHeader
Identificador del mapa de bits de encabezado de la página de propiedades.

Comentarios

Llame a esta función miembro si aún no se ha llamado a uno de los constructores de clase. Por ejemplo, llame a Construct cuando declare o asigne matrices de objetos CPropertySheet. En el caso de las matrices, debe llamar a Construct para cada miembro de la matriz.

Para mostrar la hoja de propiedades, llame a DoModal o a Create. La cadena contenida en el primer parámetro se colocará en la barra de títulos de la hoja de propiedades.

Puede mostrar marcas de agua o imágenes de encabezado automáticamente si usa los prototipos tercero o cuarto de Construct, enumerados anteriormente, y pasa valores válidos para los parámetros hbmWatermark, hpalWatermark o hbmHeader.

Ejemplo

En el ejemplo siguiente se muestra en qué circunstancias llamaría a 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`

Construye un 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
Identificador del título que se va a usar para la hoja de propiedades.

pParentWnd
Apunta a la ventana primaria de la hoja de propiedades. Si NULL, la ventana primaria será la ventana principal de la aplicación.

iSelectPage
Índice de la página que inicialmente estará en la parte superior. El valor predeterminado es la primera página agregada a la hoja.

pszCaption
Apunta a una cadena que contiene el título que se va a usar para la hoja de propiedades. El valor no puede ser NULL.

hbmWatermark
Identificador del mapa de bits de fondo de la hoja de propiedades.

hpalWatermark
Un identificador de la paleta del mapa de bits de marca de agua o mapa de bits de encabezado.

hbmHeader
Un identificador del mapa de bits de encabezado de la página de propiedades.

Comentarios

Para mostrar la hoja de propiedades, llame a DoModal o a Create. La cadena contenida en el primer parámetro se colocará en la barra de títulos de la hoja de propiedades.

Si tiene varios parámetros (por ejemplo, si usa una matriz), use Construct en lugar de CPropertySheet.

Puede mostrar marcas de agua o imágenes de encabezado automáticamente si usa los prototipos tercero o cuarto de CPropertySheet, anteriormente, y pasa valores válidos para los parámetros hbmWatermark, hpalWatermark o hbmHeader.

Ejemplo

// 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`

Muestra una hoja de propiedades no modal.

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

Parámetros

pParentWnd
Apunta a la ventana primaria. Si NULL, primario es el escritorio.

dwStyle
Estilos de ventana para la hoja de propiedades. Para obtener una lista completa de los estilos disponibles, vea Estilos de ventana.

dwExStyle
Estilos de ventana extendidos para la hoja de propiedades. Para obtener una lista completa de los estilos disponibles, vea Estilos de ventana extendidos

Valor devuelto

Distinto de cero si la hoja de propiedades se crea correctamente; de lo contrario, 0.

Comentarios

La llamada a Create puede estar dentro del constructor o puede llamarla después de invocar el constructor.

El estilo predeterminado, expresado pasando -1 como dwStyle, es realmente WS_SYSMENU|WS_POPUP|WS_CAPTION|DS_MODALFRAME|DS_CONTEXTHELP|WS_VISIBLE. El estilo de ventana extendido predeterminado, expresado pasando 0 como dwExStyle, es realmente WS_EX_DLGMODALFRAME.

La función miembro Create devuelve inmediatamente después de crear la hoja de propiedades. Para destruir la hoja de propiedades, llame a CWnd::DestroyWindow.

Las hojas de propiedades sin modelo mostradas con una llamada a Create no tienen botones Aceptar, Cancelar, Aplicar ahora y Ayuda como hojas de propiedades modales. El usuario debe crear los botones que desee.

Para mostrar una hoja de propiedades modal, llame a DoModal en su lugar.

Ejemplo

// 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`

Muestra una hoja de propiedades modal.

virtual INT_PTR DoModal();

Valor devuelto

IDOK o IDCANCEL si la función se realizó correctamente; de lo contrario, 0 o -1. Si la hoja de propiedades se ha establecido como un asistente (vea SetWizardMode), DoModal devuelve ID_WIZFINISH o IDCANCEL.

Comentarios

El valor devuelto corresponde al identificador del control que cerró la hoja de propiedades. Una vez que se devuelve esta función, se destruirán las ventanas correspondientes a la hoja de propiedades y todas las páginas. Los propios objetos seguirán existiendo. Normalmente, recuperará datos de los objetos CPropertyPage después de que DoModal devuelva IDOK.

Para mostrar una hoja de propiedades sin modelos, llame a Create en su lugar.

Cuando se crea una página de propiedades a partir de su recurso de diálogo correspondiente, puede provocar una excepción de primera oportunidad. Esto resulta de la página de propiedades que cambia el estilo del recurso de diálogo al estilo necesario antes de crear la página. Dado que los recursos suelen ser de solo lectura, esto provoca una excepción. El sistema controla la excepción y realiza una copia del recurso modificado. Por lo tanto, se puede omitir la excepción de primera oportunidad.

Nota:

El sistema operativo debe controlar esta excepción si está compilando con el modelo de control de excepciones asincrónico. Para obtener más información sobre los modelos de gestión de excepciones, consulte /EH (Modelo de gestión de excepciones). En este caso, no encapsula las llamadas a CPropertySheet::DoModal con un bloque try-catch de C++ en el que catch controla todas las excepciones, por ejemplo, catch (...). Este bloque controlaría la excepción prevista para el sistema operativo y provocaría un comportamiento imprevisible. Sin embargo, puede usar de forma segura el control de excepciones de C++ con tipos de excepciones específicos o control de excepciones estructurados en los que se pasa la excepción de infracción de acceso al sistema operativo.

Para evitar generar esta excepción de primera oportunidad, puede garantizar manualmente que la hoja de propiedades tenga los Estilos de ventana correctos. Debe establecer los siguientes estilos para una hoja de propiedades:

DS_3DLOOK
DS_CONTROL
WS_CHILD
WS_TABSTOP

Puede usar los siguientes estilos opcionales sin provocar una excepción de primera oportunidad:

DS_SHELLFONT
DS_LOCALEDIT
WS_CLIPCHILDREN

Deshabilite todos los demás estilos de Windows porque no son compatibles con las hojas de propiedades. Este consejo no se aplica a los estilos extendidos. Establecer estos estilos estándar correctamente garantizará que la hoja de propiedades no tenga que modificarse y evitará generar la excepción de primera oportunidad.

Ejemplo

Vea el ejemplo de CPropertySheet::AddPage.

`CPropertySheet::EnableStackedTabs`

Indica si se van a apilar filas de pestañas en una hoja de propiedades.

void EnableStackedTabs(BOOL bStacked);

Parámetros

bStacked
Indica si las pestañas apiladas están habilitadas en la hoja de propiedades. Deshabilite las filas apiladas de etiquetas estableciendobStacked en FALSE.

Comentarios

De forma predeterminada, si una hoja de propiedades tiene más pestañas de las que caben en una sola fila en el ancho de la hoja de propiedades, las pestañas se apilan en varias filas. Para usar pestañas de desplazamiento en lugar de apilar pestañas, llame a EnableStackedTabs con la configuración de bStacked en FALSE antes de llamar a DoModal o a Create.

Debe llamar a EnableStackedTabs cuando cree un modal o una hoja de propiedades sin modelos. Para incorporar este estilo en una clase derivada de CPropertySheet, escriba un controlador de mensajes para WM_CREATE. En la versión invalidada deCWnd::OnCreate, llame a EnableStackedTabs( FALSE ) antes de llamar a la implementación de la clase base.

Ejemplo

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`

Finaliza la hoja de propiedades.

void EndDialog(int nEndID);

Parámetros

nEndID
Identificador que se va a usar como valor devuelto de la hoja de propiedades.

Comentarios

El marco llama a esta función miembro cuando se presiona el botón Aceptar, Cancelar o Cerrar. Llame a esta función miembro si se produce un evento que debe cerrar la hoja de propiedades.

Esta función miembro solo se usa con un cuadro de diálogo modal.

Ejemplo

Vea el ejemplo de CPropertySheet::PressButton.

`CPropertySheet::GetActiveIndex`

Obtiene el número de índice de la página activa de la ventana de hoja de propiedades y, a continuación, usa el número de índice devuelto como parámetro para GetPage.

int GetActiveIndex() const;

Valor devuelto

Número de índice de la página activa.

Ejemplo

Vea el ejemplo de CPropertySheet::GetActivePage.

`CPropertySheet::GetActivePage`

Recupera la página activa de la ventana de hoja de propiedades.

CPropertyPage* GetActivePage() const;

Valor devuelto

Puntero a la página activa.

Comentarios

Use esta función miembro para realizar alguna acción en la página activa.

Ejemplo

// 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`

Devuelve un puntero a la página especificada de esta hoja de propiedades.

CPropertyPage* GetPage(int nPage) const;

Parámetros

nPage
Índice de la página deseada, a partir de 0. Debe estar comprendido entre 0 y uno menor que el número de páginas de la hoja de propiedades, ambos incluidos.

Valor devuelto

Puntero a la página correspondiente al parámetro nPage.

Ejemplo

Vea el ejemplo de CPropertyPage::OnWizardFinish.

`CPropertySheet::GetPageCount`

Determina el número de páginas que se encuentran actualmente en la hoja de propiedades.

int GetPageCount() const;

Valor devuelto

Número de páginas de la hoja de propiedades.

Ejemplo

Vea el ejemplo de CPropertyPage::OnWizardFinish.

`CPropertySheet::GetPageIndex`

Recupera el número de índice de la página especificada en la hoja de propiedades.

int GetPageIndex(CPropertyPage* pPage);

Parámetros

pPage
Apunta a la página con el índice que se va a encontrar. El valor no puede ser NULL.

Valor devuelto

Número de índice de una página.

Comentarios

Por ejemplo, usaría GetPageIndex para obtener el índice de página con el fin de usar SetActivePage o GetPage.

Ejemplo

Vea el ejemplo de CPropertySheet::GetActivePage.

`CPropertySheet::GetTabControl`

Recupera un puntero a un control de pestaña para hacer algo específico del control de pestaña (es decir, para usar cualquiera de las API de CTabCtrl).

CTabCtrl* GetTabControl() const;

Valor devuelto

Recupera un puntero a un control de ficha.

Comentarios

Por ejemplo, llame a esta función miembro si desea agregar mapas de bits a cada una de las pestañas durante la inicialización.

Ejemplo

// 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`

Estructura cuyos miembros almacenan las características de PROPSHEETHEADER.

Comentarios

Utilice esta estructura para inicializar la apariencia de la hoja de propiedades después de su construcción, pero antes de que se muestre con la función miembro DoModal. Por ejemplo, establezca el miembro dwSize de m_psh en el tamaño que desea que tenga la hoja de propiedades.

Para obtener más información sobre esta estructura, incluida una lista de sus miembros, vea PROPSHEETHEADER en Windows SDK.

Ejemplo

// 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`

Convierte las unidades de cuadro de diálogo de un rectángulo en unidades de pantalla.

void MapDialogRect(LPRECT lpRect) const;

Parámetros

lpRect
Apunta a una estructura RECT u objeto CRect que contiene las coordenadas del cuadro de diálogo que se va a convertir.

Comentarios

Las unidades de cuadro de diálogo se indican en términos de la unidad base actual del cuadro de diálogo derivada del ancho medio y alto de caracteres en la fuente utilizada para el texto del cuadro de diálogo. Una unidad horizontal es una cuarta parte de la unidad de ancho base del cuadro de diálogo y una unidad vertical es una octava de la unidad de alto base del cuadro de diálogo.

La función de Windows GetDialogBaseUnits devuelve información de tamaño para la fuente del sistema, pero puede especificar una fuente diferente para cada hoja de propiedades si usa el estilo DS_SETFONT en el archivo de definición de recursos. La función de Windows MapDialogRect, descrita en Windows SDK, usa la fuente adecuada para este cuadro de diálogo.

La función miembro MapDialogRect reemplaza las unidades de cuadro de diálogo en lpRect con unidades de pantalla (píxeles) para que el rectángulo se pueda usar para crear un cuadro de diálogo o colocar un control dentro de un cuadro.

`CPropertySheet::OnInitDialog`

Invalida para aumentar la inicialización de la hoja de propiedades.

virtual BOOL OnInitDialog();

Valor devuelto

Especifica si la aplicación ha establecido el foco de entrada en uno de los controles de la hoja de propiedades. Si OnInitDialog devuelve un valor distinto de cero, Windows establece el foco de entrada en el primer control de la hoja de propiedades. La aplicación solo puede devolver 0 si ha establecido explícitamente el foco de entrada en uno de los controles de la hoja de propiedades.

Comentarios

Se llama a esta función miembro en respuesta al mensaje WM_INITDIALOG. Este mensaje se envía a la hoja de propiedades durante las llamadas Create o DoModal, que se producen inmediatamente antes de que se muestre la hoja de propiedades.

Invalide esta función miembro si necesita realizar un procesamiento especial cuando se inicializa la hoja de propiedades. En la versión invalidada, primero llama a la clase base OnInitDialog, pero ignora su valor devuelto. Normalmente, devolverá TRUE de la función miembro reemplazada.

No necesita una entrada de mapa de mensajes para esta función miembro.

`CPropertySheet::PressButton`

Simula la elección del botón especificado en una hoja de propiedades.

void PressButton(int nButton);

Parámetros

nButton
nButton : identifica el botón que se va a presionar. Este parámetro puede establecerse con uno de los siguientes valores:

PSBTN_BACK Elige el botón Atrás.
PSBTN_NEXT Elige el botón Siguiente.
PSBTN_FINISH Elige el botón Finalizar.
PSBTN_OK Elige el botón Aceptar.
PSBTN_APPLYNOW Elige el botón Aplicar ahora.
PSBTN_CANCEL Elige el botón Cancelar.
PSBTN_HELP Elige el botón Ayuda.

Comentarios

Vea PSM_PRESSBUTTON para obtener más información sobre el mensaje Pressbutton de Windows SDK.

Una llamada a PressButton no enviará la notificación PSN_APPLY desde una página de propiedades al marco de trabajo. Para enviar esta notificación, llame a CPropertyPage::OnOK.

Ejemplo

// 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`

Quita una página de la hoja de propiedades y destruye la ventana asociada.

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

Parámetros

pPage
Apunta a la página que se va a quitar de la hoja de propiedades. El valor no puede ser NULL.

nPage
Índice de la página que se va a quitar. Debe estar comprendido entre 0 y uno menor que el número de páginas de la hoja de propiedades, ambos incluidos.

Comentarios

El propio objeto CPropertyPage no se destruye hasta que se cierra el propietario de la ventana CPropertySheet.

`CPropertySheet::SetActivePage`

Cambia la página activa.

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

Parámetros

nPage
Índice de la página que se va a establecer. Debe estar comprendido entre 0 y uno menor que el número de páginas de la hoja de propiedades, ambos incluidos.

pPage
Apunta a la página que se va a establecer en la hoja de propiedades. No puede ser NULL.

Valor devuelto

Distinto de cero si la hoja de propiedades se activa correctamente; de lo contrario, 0.

Comentarios

Por ejemplo, use SetActivePage si la acción de un usuario en una página debe hacer que otra página se convierta en la página activa.

Ejemplo

Vea el ejemplo de CPropertySheet::GetActivePage.

`CPropertySheet::SetFinishText`

Establece el texto del botón de comando Finalizar.

void SetFinishText(LPCTSTR lpszText);

Parámetros

lpszText
Apunta al texto que se va a mostrar en el botón de comando Finalizar.

Comentarios

Llame a SetFinishText para mostrar el texto en el botón de comando Finalizar y ocultar los botones Siguiente y Atrás después de que el usuario complete la acción en la última página del asistente.

Ejemplo

// 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 el título de la hoja de propiedades (el texto que se muestra en la barra de título de una ventana de marco).

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

Parámetros

nStyle
Especifica el estilo del título de la hoja de propiedades. El estilo debe especificarse en 0 o como PSH_PROPTITLE. Si el estilo se establece como PSH_PROPTITLE, la palabra "Propiedades" aparece después del texto especificado como título. Por ejemplo, llamar a SetTitle("Simple", PSH_PROPTITLE) dará como resultado un título de hoja de propiedades de "Propiedades simples".

lpszText
Apunta al texto que se va a usar como título en la barra de título de la hoja de propiedades.

Comentarios

De forma predeterminada, una hoja de propiedades utiliza el parámetro de título en el constructor de la hoja de propiedades.

Ejemplo

// 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 o deshabilita el botón Atrás, Siguiente o Finalizar en una hoja de propiedades del asistente.

void SetWizardButtons(DWORD dwFlags);

Parámetros

dwFlags
Conjunto de marcas que personalizan la función y la apariencia de los botones del asistente. Este parámetro puede ser una combinación de los siguientes valores:

PSWIZB_BACK Botón Atrás
PSWIZB_NEXT Botón Siguiente
PSWIZB_FINISH Botón Finalizar
PSWIZB_DISABLEDFINISH Botón Finalizar deshabilitado

Comentarios

Llame a SetWizardButtons solo después de abrir el cuadro de diálogo; no puede llamar a SetWizardButtons antes de llamar a DoModal. Normalmente, debe llamar a SetWizardButtons desde CPropertyPage::OnSetActive.

Si desea cambiar el texto del botón Finalizar u ocultar los botones Siguiente y Atrás una vez que el usuario haya completado el asistente, llame a SetFinishText. Tenga en cuenta que el mismo botón se comparte para Finalizar y Siguiente. Puede mostrar un botón Finalizar o Siguiente a la vez, pero no ambos.

Ejemplo

Un CPropertySheet tiene tres páginas de propiedades del asistente: CStylePage, CColorPage y CShapePage. El fragmento de código siguiente muestra cómo habilitar y deshabilitar los botones Atrás y Siguiente en la página de propiedades del asistente.

// 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`

Establece una página de propiedades como asistente.

void SetWizardMode();

Comentarios

Una característica clave de una página de propiedades del asistente es que el usuario navega mediante los botones Siguiente o Finalizar, Atrás y Cancelar en lugar de pestañas.

Llame a SetWizardMode antes de llamar a DoModal. Después de llamar a SetWizardMode, DoModal devolverá ID_WIZFINISH (si el usuario cierra con el botón Finalizar) o IDCANCEL.

SetWizardMode establece la marca PSH_WIZARD.

Ejemplo

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

CStylePage pageStyle;
CColorPage pageColor;
CShapePage pageShape;

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

sheet.SetWizardMode();

sheet.DoModal();

Vea también

Ejemplo de MFCCMNCTRL1
Ejemplo de MFCCMNCTRL2
Ejemplo de MFCPROPDLG
Ejemplo de MFCSNAPVW
CWnd (clase)
Gráfico de jerarquías

Compartir a través de

Clase CPropertySheet

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Miembros de datos públicos

Comentarios

Jerarquía de herencia

Requisitos

CPropertySheet::AddPage

Parámetros

Comentarios

Ejemplo

CPropertySheet::Construct

Parámetros

Comentarios

Ejemplo

CPropertySheet::CPropertySheet

Parámetros

Comentarios

Ejemplo

CPropertySheet::Create

Parámetros

Valor devuelto

Comentarios

Ejemplo

CPropertySheet::DoModal

Valor devuelto

Comentarios

Ejemplo

CPropertySheet::EnableStackedTabs

Parámetros

Comentarios

Ejemplo

CPropertySheet::EndDialog

Parámetros

Comentarios

Ejemplo

CPropertySheet::GetActiveIndex

Valor devuelto

Ejemplo

CPropertySheet::GetActivePage

Valor devuelto

Comentarios

Ejemplo

CPropertySheet::GetPage

Parámetros

Valor devuelto

Ejemplo

CPropertySheet::GetPageCount

Valor devuelto

Ejemplo

CPropertySheet::GetPageIndex

Parámetros

Valor devuelto

Comentarios

Ejemplo

CPropertySheet::GetTabControl

Valor devuelto

Comentarios

Ejemplo

CPropertySheet::m_psh

Comentarios

Ejemplo

CPropertySheet::MapDialogRect

Parámetros

Comentarios

CPropertySheet::OnInitDialog

Valor devuelto

Comentarios

CPropertySheet::PressButton

Parámetros

Comentarios

Ejemplo

CPropertySheet::RemovePage

Parámetros

Comentarios

CPropertySheet::SetActivePage

Parámetros

Clase `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`