Acerca de las hojas de propiedades

Una hoja de propiedades es una ventana que permite al usuario ver y editar las propiedades de un elemento. Por ejemplo, una aplicación de hoja de cálculo puede usar una hoja de propiedades para permitir al usuario establecer las propiedades de fuente y borde de una celda o para ver y establecer las propiedades de un dispositivo, como una unidad de disco, una impresora o un mouse.

En esta sección se describen los temas siguientes.

• Conceptos básicos de la hoja de propiedades
• Cuadros de diálogo Hoja de propiedades
• Páginas
• Creación de la hoja de propiedades
• Agregar y quitar páginas
• Título y etiquetas de página de la hoja de propiedades
• Activación de página
• Botón Ayuda
  • Quitar el botón ayuda de la barra de subtítulos
• Botones Aceptar, Cancelar y Aplicar
• Asistentes

Conceptos básicos de la hoja de propiedades

Para implementar hojas de propiedades en la aplicación, incluya el archivo de encabezado Prsht.h en el proyecto. Prsht.h contiene todos los identificadores usados con hojas de propiedades.

Una hoja de propiedades contiene una o varias ventanas secundarias superpuestas denominadas páginas, cada una de las cuales contiene ventanas de control para establecer un grupo de propiedades relacionadas. Por ejemplo, una página puede contener los controles para establecer las propiedades de fuente de un elemento, incluido el estilo de tipo, el tamaño de punto, el color, etc. Cada página tiene una pestaña que el usuario puede seleccionar para llevar la página al primer plano de la hoja de propiedades. Por ejemplo, la aplicación Date-Time panel de control muestra la siguiente hoja de propiedades.

Una hoja de propiedades estándar con varias páginas con pestañas permite al usuario tener acceso aleatorio a todas las propiedades. Si es más adecuado tener propiedades establecidas en secuencia, puede usar un asistente.

Cuadros de diálogo Hoja de propiedades

Una hoja de propiedades y las páginas que contiene son realmente cuadros de diálogo. La hoja de propiedades es un cuadro de diálogo definido por el sistema que administra las páginas y proporciona un contenedor común para ellas. Un cuadro de diálogo de hoja de propiedades puede ser modal o modeless. Incluye un marco, una barra de título y cuatro botones: Aceptar, Cancelar, Aplicar y (opcionalmente) Ayuda. Los procedimientos del cuadro de diálogo para las páginas reciben códigos de notificación en forma de WM_NOTIFY mensajes cuando el usuario hace clic en los botones.

Nota

No toda la información de esta sección se aplica a los asistentes, que tienen un aspecto y un comportamiento algo diferentes. Por ejemplo, los asistentes tienen un conjunto diferente de botones y sin pestañas. Para obtener más información, vea Crear asistentes.

Cada página de una hoja de propiedades es un cuadro de diálogo modelado definido por la aplicación que administra las ventanas de control usadas para ver y editar las propiedades de un elemento. Se proporciona la plantilla de cuadro de diálogo que se usa para crear cada página, así como el procedimiento del cuadro de diálogo que administra los controles y establece las propiedades del elemento correspondiente.

Una hoja de propiedades envía códigos de notificación al procedimiento del cuadro de diálogo para una página cuando la página obtiene o pierde la activación y cuando el usuario hace clic en el botón Aceptar, Cancelar, Aplicar o Ayuda . Las notificaciones se envían en forma de WM_NOTIFY mensajes. El parámetro lParam es la dirección de una estructura NMHDR que incluye el identificador de ventana para el cuadro de diálogo de la hoja de propiedades.

Algunos códigos de notificación requieren que una página devuelva TRUE o FALSE en respuesta al mensaje WM_NOTIFY . Para ello, la página debe usar la función SetWindowLong para establecer el valor de DWL_MSGRESULT para el cuadro de diálogo de página en TRUE o FALSE.

Páginas

Una hoja de propiedades debe contener al menos una página, pero no puede contener más que el valor de MAXPROPPAGES tal como se define en los archivos de encabezado de Windows. Cada página tiene un índice de base cero que la hoja de propiedades asigna según el orden en que se agrega la página a la hoja de propiedades. Los índices se usan en los mensajes que se envían a la hoja de propiedades.

Una página de propiedades puede contener un cuadro de diálogo anidado. Si es así, debe incluir el estilo WS_EX_CONTROLPARENT para el cuadro de diálogo de nivel superior y llamar a la función IsDialogMessage con el identificador al cuadro de diálogo primario. Esto garantiza que el usuario pueda usar mnemonics y las teclas de navegación del cuadro de diálogo para mover el foco a los controles del cuadro de diálogo anidado.

Cada página tiene un icono y una etiqueta correspondientes. La hoja de propiedades crea una pestaña para cada página y muestra el icono y la etiqueta en la pestaña. Se espera que todas las páginas de la hoja de propiedades usen una fuente nobolada. Para asegurarse de que la fuente no está en negrita, especifique el estilo DS_3DLOOK en la plantilla del cuadro de diálogo.

El procedimiento del cuadro de diálogo de una página no debe llamar a la función EndDialog . Si lo hace, destruirá toda la hoja de propiedades, no solo la página.

El tamaño mínimo de una página de hoja de propiedades es de 212 unidades de diálogo horizontalmente y 114 unidades de diálogo verticalmente. Si un cuadro de diálogo de página es menor que este, la página se ampliará hasta que cumpla el tamaño mínimo. El archivo de encabezado Prsht.h contiene tres conjuntos de tamaños recomendados para las páginas de la hoja de propiedades, como se muestra en la tabla siguiente.

Size	Descripción
PROP_SM_CXDLG	Ancho, en unidades de diálogo, de una página de hoja de propiedades pequeña.
PROP_SM_CYDLG	Alto, en unidades de diálogo, de una página de hoja de propiedades pequeña.
PROP_MED_CXDLG	Ancho, en unidades de diálogo, de una página de hoja de propiedades de tamaño mediano.
PROP_MED_CYDLG	Alto, en unidades de diálogo, de una página de hoja de propiedades de tamaño mediano.
PROP_LG_CXDLG	Ancho, en unidades de diálogo, de una página de hoja de propiedades grande.
PROP_LG_CYDLG	Alto, en unidades de diálogo, de una página de hoja de propiedades grande.

El uso de estos tamaños recomendados ayudará a garantizar la coherencia visual entre la aplicación y otras aplicaciones de Microsoft Windows.

En el editor de recursos de Microsoft Visual Studio, puede crear una página con el tamaño adecuado en el cuadro de diálogo Agregar recurso . Expanda el nodo Cuadro de diálogo y seleccione IDD_PROPPAGE_LARGE, IDD_PROPPAGE_MEDIUM o IDD_PROPPAGE_SMALL.

La hoja de propiedades se ajusta automáticamente para dar cabida a la página más grande.

Creación de la hoja de propiedades

Antes de crear una hoja de propiedades, debe definir una o varias páginas. Esto implica rellenar una estructura PROPSHEETPAGE con información sobre la página (su icono, etiqueta, plantilla de cuadro de diálogo, procedimiento de cuadro de diálogo, etc.) y, a continuación, especificar la dirección de la estructura en una llamada a la función CreatePropertySheetPage . La función devuelve un identificador al tipo HPROPSHEETPAGE que identifica de forma única la página.

Para crear una hoja de propiedades, especifique la dirección de una estructura PROPSHEETHEADER en una llamada a la función PropertySheet . La estructura define el icono y el título de la hoja de propiedades e incluye también la dirección de una matriz de identificadores HPROPSHEETPAGE que se obtienen mediante CreatePropertySheetPage. Cuando PropertySheet crea la hoja de propiedades, incluye las páginas identificadas en la matriz. Las páginas aparecen en la hoja de propiedades en el mismo orden en que se encuentran en la matriz.

Otra manera de asignar páginas a una hoja de propiedades es especificar una matriz de estructuras PROPSHEETPAGE en lugar de una matriz de identificadores HPROPSHEETPAGE . En este caso, PropertySheet crea identificadores para las páginas antes de agregarlos a la hoja de propiedades.

Cuando se crea una página, su procedimiento de cuadro de diálogo recibe un mensaje de WM_INITDIALOG . El parámetro lParam del mensaje es un puntero a una copia de la estructura PROPSHEETPAGE que se define cuando se crea la página. En concreto, cuando se crea una página, el miembro lParam de la estructura se puede usar para pasar información definida por la aplicación al procedimiento del cuadro de diálogo. Con la excepción del miembro lParam , esta estructura debe tratarse como de solo lectura. La modificación de cualquier cosa distinta de lParam tendrá consecuencias impredecibles.

Cuando el sistema pasa posteriormente una copia de la estructura PROPSHEETPAGE de la página a la aplicación, usa el mismo puntero. Los cambios realizados en la estructura se pasarán. Dado que el sistema omite el miembro lParam , se puede modificar para enviar información a otras partes de la aplicación. Por ejemplo, puede usar lParam para pasar información a la función de devolución de llamada PropSheetPageProc de la página.

PropertySheet establece automáticamente el tamaño y la posición inicial de una hoja de propiedades. La posición se basa en la posición de la ventana del propietario y el tamaño se basa en la página más grande especificada en la matriz de páginas cuando se creó la hoja de propiedades. Si desea que las páginas coincidan con el ancho de los cuatro botones situados en la parte inferior de la hoja de propiedades, establezca el ancho de la página más ancha en 190 unidades de diálogo.

El tamaño de una hoja de propiedades se calcula a partir de las propiedades de ancho y alto de la plantilla de diálogo en el archivo de recursos. Consulte DIALOG Resource (Recurso DIALOG ) o DIALOGEX Resource (Recurso DIALOGEX ) para obtener más información. Sin embargo, tenga en cuenta que, por motivos de compatibilidad, las dimensiones se calculan en relación con la fuente Dlg de MS Shell en lugar de la fuente usada por la página. Si diseña una página que usa otra fuente, se puede usar una de las siguientes sugerencias.

• Ajuste las dimensiones de la plantilla de diálogo para compensar la diferencia de tamaño entre la fuente Dlg de MS Shell y la fuente que realmente usa la página. Por ejemplo, si elige una fuente que sea el doble de ancho que MS Shell Dlg, establezca la propiedad width de la plantilla de diálogo en dos veces el uso normal.
• Use una plantilla DIALOGEX y establezca el estilo de diálogo DS_SHELLFONT . En ese caso, el administrador de hojas de propiedades interpreta las dimensiones de la plantilla de diálogo en relación con la fuente usada por la plantilla de diálogo.

Agregar y quitar páginas

Después de crear una hoja de propiedades, una aplicación puede agregar una página al final del conjunto de páginas existente enviando un mensaje de PSM_ADDPAGE . Para insertar una página entre las páginas existentes, envíe un mensaje de PropSheet_InsertPage . Tenga en cuenta que el tamaño de la hoja de propiedades no puede cambiar una vez creado. Las páginas agregadas o insertadas no deben ser mayores que la página más grande actualmente en la hoja de propiedades. Para quitar una página, envíe un mensaje de PSM_REMOVEPAGE .

Al definir una página, puede especificar la dirección de una función de devolución de llamada PropSheetPageProc a la que llama la hoja de propiedades al crear o quitar la página. El uso de PropSheetPageProc le ofrece la oportunidad de realizar operaciones de inicialización y limpieza para páginas individuales.

Nota:

Se producen varios mensajes y una llamada de función mientras la hoja de propiedades manipula la lista de páginas. Mientras se realiza esta acción, intentar modificar la lista de páginas tendrá resultados impredecibles. No agregue, inserte ni quite páginas en la implementación de PropSheetPageProc ni controle las siguientes notificaciones y mensajes de Windows.

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

Si surge la necesidad de modificar una página de hoja de propiedades mientras controla uno de estos mensajes o mientras PropSheetPageProc está en funcionamiento, publique un mensaje privado de Windows. La aplicación no recibirá ese mensaje hasta después de que el administrador de hojas de propiedades haya terminado sus tareas, en cuyo momento será seguro modificar la lista de páginas.

Cuando se destruye una hoja de propiedades, destruye automáticamente todas las páginas que se han agregado a ella. Las páginas se destruyen en orden inverso de la especificada en la matriz utilizada para crear las páginas. Para destruir una página creada por la función CreatePropertySheetPage , pero que no se agregó a la hoja de propiedades, use la función DestroyPropertySheetPage .

Título y etiquetas de página de la hoja de propiedades

Especifique el título de una hoja de propiedades en la estructura PROPSHEETHEADER utilizada para crear la hoja de propiedades. Si el miembro dwFlags incluye el valor de PSH_PROPTITLE , la hoja de propiedades agrega el sufijo "Properties" o el prefijo "Properties for", dependiendo de la versión. Puede cambiar el título después de crear una hoja de propiedades mediante el mensaje PSM_SETTITLE . En un Asistente aero, este mensaje se puede usar para cambiar el título de una página interior dinámicamente.

De forma predeterminada, una hoja de propiedades usa la cadena de nombre especificada en la plantilla del cuadro de diálogo como etiqueta de una página. Puede invalidar la cadena de nombre incluyendo el valor PSP_USETITLE en el miembro dwFlags de la estructura PROPSHEETPAGE que define la página. Cuando se especifica PSP_USETITLE , el miembro pszTitle debe contener la dirección de la cadena de etiqueta de la página.

Activación de página

Una hoja de propiedades solo puede tener una página activa a la vez. La página que tiene la activación está en primer plano de la pila superpuesta de páginas. El usuario activa una página seleccionando su pestaña; una aplicación activa una página mediante el mensaje PSM_SETCURSEL .

La hoja de propiedades envía el código de notificación PSN_KILLACTIVE a la página que está a punto de perder la activación. En respuesta, la página debe validar los cambios realizados por el usuario en la página. Si la página requiere una entrada de usuario adicional antes de perder la activación, use la función SetWindowLong para establecer el valor DWL_MSGRESULT de la página en TRUE. Además, la página debe mostrar un cuadro de mensaje que describa el problema y proporcione la acción recomendada. Establezca DWL_MSGRESULT en FALSE cuando esté bien perder la activación.

Antes de que la página que obtenga la activación sea visible, la hoja de propiedades envía el código de notificación PSN_SETACTIVE a la página. La página debe responder inicializando sus ventanas de control.

Botón Ayuda

Las hojas de propiedades pueden mostrar dos botones de Ayuda: un botón ayuda de hoja de propiedades que se muestra en la parte inferior del marco, junto a los botones Aceptar/aplicar/y un botón de barra de subtítulo estándar que proporciona ayuda contextual.

El botón Ayuda de la hoja de propiedades es opcional y se puede habilitar en una página por página. Para mostrar el botón Ayuda de la hoja de propiedades para una o varias páginas:

• Establezca la marca PSH_HASHELP en el miembro dwFlags de la estructura PROPSHEETHEADER de la hoja de propiedades.
• Para cada página que mostrará un botón Ayuda, establezca la marca PSP_HASHELP en el miembro dwFlags de la estructura PROPSHEETPAGE de la página.

Cuando el usuario hace clic en el botón Ayuda, la página activa recibe un código de notificación de PSN_HELP . La página debe responder mostrando información de Ayuda, normalmente llamando a la función WinHelp .

Quitar el botón ayuda de la barra de subtítulos

El botón Ayuda de la barra de subtítulo se muestra de forma predeterminada, de modo que la Ayuda contextual esté siempre disponible para los botones Aceptar, Cancelar o Aplicar. Sin embargo, este botón se puede quitar, si es necesario. Para quitar el botón Ayuda de la barra de subtítulo de una hoja de propiedades:

• Para las versiones de los controles comunes anteriores a la versión 5.80, debe implementar una función de devolución de llamada de hoja de propiedades.
• Para la versión 5.80 y posteriores de los controles comunes, simplemente puede establecer la marca de PSH_NOCONTEXTHELP en el miembro dwFlags de la estructura PROPSHEETHEADER de la hoja de propiedades. Sin embargo, si necesita compatibilidad con versiones anteriores de control comunes, debe implementar la función de devolución de llamada.

Para implementar una función de devolución de llamada de hoja de propiedades que quita el botón ayuda de la barra de subtítulo:

• Establezca la marca PSH_USECALLBACK en el miembro dwFlags de la estructura PROPSHEETHEADER de la hoja de propiedades.
• Establezca el miembro pfnCallBack de la estructura PROPSHEETHEADER para que apunte a la función de devolución de llamada.
• Implemente la función de devolución de llamada. Cuando esta función recibe el mensaje PSCB_PRECREATE , también recibirá un puntero a la plantilla del cuadro de diálogo de la hoja de propiedades. Quite el estilo DS_CONTEXTHELP de esta plantilla.

En el ejemplo siguiente se muestra cómo implementar esta función de devolución de llamada:

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;
}

Si la estructura DLGTEMPLATEEX no está definida, incluya la siguiente declaración:

#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>

Botones Aceptar, Cancelar y Aplicar

Los botones Aceptar y Aplicar son similares; ambos dirigen las páginas de una hoja de propiedades para validar y aplicar los cambios de propiedad realizados por el usuario. La única diferencia es que hacer clic en el botón Aceptar hace que la hoja de propiedades se destruya después de aplicar los cambios.

Cuando el usuario hace clic en el botón Aceptar o Aplicar , la hoja de propiedades envía una notificación PSN_KILLACTIVE a la página activa, lo que le da la oportunidad de validar los cambios del usuario. Si los cambios son válidos, la página debe llamar a la función SetWindowLong con el valor DWL_MSGRESULT establecido en FALSE. Si los cambios del usuario no son válidos, la página debe establecer DWL_MSGRESULT enTRUE y mostrar un cuadro de diálogo que informe al usuario del problema. La página permanece activa hasta que establece DWL_MSGRESULT en FALSE en respuesta a un mensaje de PSN_KILLACTIVE.

Después de que una página responda a una notificación de PSN_KILLACTIVE estableciendo DWL_MSGRESULT en FALSE, la hoja de propiedades enviará una notificación PSN_APPLY a cada página. Cuando una página recibe esta notificación, debe aplicar las nuevas propiedades al elemento correspondiente. Para indicar a la hoja de propiedades que los cambios son válidos para la página, llame a SetWindowLong con DWL_MSGRESULT establecido en PSNRET_NOERROR. Si los cambios no son válidos para la página, devuelva un error. Al hacerlo, se impide que la hoja de propiedades se destruya y devuelva el foco a la página que recibió la notificación de PSN_APPLY o la página que tenía el foco cuando se presionaba el botón Aplicar . Para devolver un error e indicar qué página recibirá el foco, establezca DWL_MSGRESULT en uno de los valores siguientes.

• PSNRET_INVALID. La hoja de propiedades no se destruirá y el foco se devolverá a esta página.
• PSNRET_INVALID_NOCHANGEPAGE. La hoja de propiedades no se destruirá y el foco se devolverá a la página que tenía el foco cuando se presionaba el botón.

Una aplicación puede usar el mensaje PSM_APPLY para simular la selección del botón Aplicar .

El botón Aplicar se deshabilita inicialmente cuando una página se activa, lo que indica que aún no hay cambios de propiedad que se apliquen. Cuando la página recibe la entrada a través de uno de sus controles que indica que el usuario ha editado una propiedad, la página debe enviar el mensaje PSM_CHANGED a la hoja de propiedades. El mensaje hace que la hoja de propiedades habilite el botón Aplicar . Si el usuario hace clic posteriormente en el botón Aplicar o Cancelar , la página debe reinicializar sus controles y, a continuación, enviar el mensaje de PSM_UNCHANGED para volver a deshabilitar el botón Aplicar .

A veces, el botón Aplicar hace que una página realice un cambio en una hoja de propiedades y el cambio no se pueda deshacer. Cuando esto sucede, la página debe enviar el mensaje PSM_CANCELTOCLOSE a la hoja de propiedades. El mensaje hace que la hoja de propiedades cambie el texto del botón Aceptar a "Cerrar", lo que indica que no se pueden cancelar los cambios aplicados.

A veces, una página realiza un cambio en la configuración del sistema que requiere que Windows se reinicie o que el sistema se reinicie antes de que el cambio pueda surtir efecto. Después de realizar este cambio, una página debe enviar el PSM_RESTARTWINDOWS o PSM_REBOOTSYSTEM mensaje a la hoja de propiedades. Estos mensajes hacen que la función PropertySheet devuelva el valor de ID_PSRESTARTWINDOWS o ID_PSREBOOTSYSTEM después de destruir la hoja de propiedades.

Cuando un usuario hace clic en el botón Cancelar , la hoja de propiedades envía el código de notificación PSN_RESET a todas las páginas, lo que indica que la hoja de propiedades está a punto de destruirse. Una página debe usar la notificación para realizar operaciones de limpieza.

Asistentes

Un asistente es un tipo especial de hoja de propiedades. Los asistentes están diseñados para presentar páginas de una en una secuencia controlada por la aplicación. En lugar de seleccionar en un grupo de páginas haciendo clic en una pestaña, los usuarios navegan hacia delante y hacia atrás por la secuencia, una página a la vez, haciendo clic en botones. Por ejemplo, la siguiente captura de pantalla muestra la página principal del Asistente para agregar hardware:

En la captura de pantalla siguiente se muestra la primera página de un Asistente aerográfico, el nuevo estilo introducido en Windows Vista.

Consulte Creación de asistentes para obtener una explicación completa de los asistentes.