Control de notificaciones de personalización

Un control común de la barra de herramientas de Windows tiene características de personalización integradas, incluido un cuadro de diálogo de personalización definido por el sistema, que permite al usuario insertar, eliminar o reorganizar botones de barra de herramientas. La aplicación determina si las características de personalización están disponibles y controla la medida en que el usuario puede personalizar la barra de herramientas.

Puede hacer que estas características de personalización estén disponibles para el usuario proporcionando a la barra de herramientas el estilo CCS_ADJUSTABLE . Las características de personalización permiten al usuario arrastrar un botón a una nueva posición o quitar un botón arrastrándolo fuera de la barra de herramientas. Además, el usuario puede hacer doble clic en la barra de herramientas para mostrar el cuadro de diálogo Personalizar barra de herramientas, lo que permite al usuario agregar, eliminar y reorganizar botones de barra de herramientas. La aplicación puede mostrar el cuadro de diálogo mediante la función de miembro Personalizar .

El control de barra de herramientas envía mensajes de notificación a la ventana primaria en cada paso del proceso de personalización. Si el usuario mantiene presionada la tecla MAYÚS y comienza a arrastrar un botón, la barra de herramientas controla automáticamente la operación de arrastre. La barra de herramientas envía el mensaje de notificación TBN_QUERYDELETE a la ventana primaria para determinar si se puede eliminar el botón. La operación de arrastre finaliza si la ventana primaria devuelve FALSE. De lo contrario, la barra de herramientas captura la entrada del mouse y espera a que el usuario suelte el botón del mouse.

Cuando el usuario suelta el botón del mouse, el control de barra de herramientas determina la ubicación del cursor del mouse. Si el cursor está fuera de la barra de herramientas, se elimina el botón. Si el cursor está en otro botón de barra de herramientas, la barra de herramientas envía el mensaje de notificación TBN_QUERYINSERT a la ventana primaria para determinar si se puede insertar un botón a la izquierda del botón especificado. El botón se inserta si la ventana primaria devuelve TRUE; de lo contrario, no lo es. La barra de herramientas envía el mensaje de notificación TBN_TOOLBARCHANGE para indicar el final de la operación de arrastre.

Si el usuario inicia una operación de arrastre sin mantener presionada la tecla MAYÚS, el control de la barra de herramientas envía el mensaje de notificación TBN_BEGINDRAG a la ventana del propietario. Una aplicación que implementa su propio código de arrastre de botón puede usar este mensaje como señal para iniciar una operación de arrastre. La barra de herramientas envía el mensaje de notificación TBN_ENDDRAG para indicar el final de la operación de arrastre.

Un control de barra de herramientas envía mensajes de notificación cuando el usuario personaliza una barra de herramientas mediante el cuadro de diálogo Personalizar barra de herramientas . La barra de herramientas envía el mensaje de notificación TBN_BEGINADJUST después de que el usuario haga doble clic en la barra de herramientas, pero antes de crear el cuadro de diálogo. A continuación, la barra de herramientas comienza a enviar una serie de mensajes de notificación de TBN_QUERYINSERT para determinar si la barra de herramientas permite insertar botones. Cuando la ventana primaria devuelve TRUE, la barra de herramientas deja de enviar mensajes de notificación TBN_QUERYINSERT . Si la ventana primaria no devuelve TRUE para ningún botón, la barra de herramientas destruye el cuadro de diálogo.

A continuación, el control de barra de herramientas determina si se pueden eliminar botones de la barra de herramientas enviando un mensaje de notificación de TBN_QUERYDELETE para cada botón de la barra de herramientas. La ventana primaria devuelve TRUE para indicar que se puede eliminar un botón; de lo contrario, devuelve FALSE. La barra de herramientas agrega todos los botones de la barra de herramientas al cuadro de diálogo, pero se muestran en gris aquellos que no se pueden eliminar.

Cada vez que el control de la barra de herramientas necesita información sobre un botón en el cuadro de diálogo Personalizar barra de herramientas, envía el mensaje de notificación TBN_GETBUTTONINFO , especificando el índice del botón para el que necesita información y la dirección de una estructura TBNOTIFY . La ventana primaria debe rellenar la estructura con la información pertinente.

El cuadro de diálogo Personalizar barra de herramientas incluye un botón Ayuda y un botón Restablecer. Cuando el usuario elige el botón Ayuda, el control de la barra de herramientas envía el mensaje de notificación TBN_CUSTHELP . La ventana primaria debe responder mostrando información de ayuda. El cuadro de diálogo envía el mensaje de notificación TBN_RESET cuando el usuario selecciona el botón Restablecer. Este mensaje indica que la barra de herramientas está a punto de reinicializar el cuadro de diálogo.

Estos mensajes son todos mensajes WM_NOTIFY, y se pueden controlar en la ventana propietaria agregando entradas al mapa de mensajes de la siguiente forma en el mapa de mensajes de la ventana propietaria:

ON_NOTIFY( wNotifyCode, idControl, memberFxn )

• wNotifyCode

  Código de identificador de mensaje de notificación, como TBN_BEGINADJUST.

• idControl

  Identificador del control que envía la notificación.

• memberFxn

  Función miembro que se llamará cuando se reciba esta notificación.

La función miembro se declararía con el prototipo siguiente:

afx_msg void memberFxn( NMHDR * pNotifyStruct, LRESULT * result );

Si el controlador de mensajes de notificación devuelve un valor, debe colocarlo en el LRESULT al que apunta el resultado.

Para cada mensaje, pNotifyStruct apunta a una estructura NMHDR o a una estructura TBNOTIFY . Estas estructuras se describen a continuación:

La estructura NMHDR contiene los siguientes miembros:

typedef struct tagNMHDR {
    HWND hwndFrom;  // handle of control sending message
    UINT idFrom;// identifier of control sending message
    UINT code;  // notification code; see below
} NMHDR;

• hwndFrom

  Identificador de ventana del control que envía la notificación. Para convertir este identificador en un puntero CWnd , use CWnd::FromHandle.

• idFrom

  Identificador del control que envía la notificación.

• código

  Código de notificación. Este miembro puede ser un valor específico de un tipo de control, como TBN_BEGINADJUST o TTN_NEEDTEXT, o puede ser uno de los valores de notificación comunes que se enumeran a continuación:

  • NM_CLICK El usuario ha realizado clic en el botón izquierdo del mouse dentro del control.

  • NM_DBLCLK El usuario ha realizado doble clic en el botón izquierdo del mouse dentro del control.

  • NM_KILLFOCUS El control ha perdido el foco de entrada.

  • NM_OUTOFMEMORY El control no pudo completar una operación porque no hay suficiente memoria disponible.

  • NM_RCLICK El usuario ha realizado clic en el botón derecho del mouse dentro del control.

  • NM_RDBLCLK El usuario ha realizado doble clic en el botón derecho del mouse dentro del control.

  • NM_RETURN El control tiene el foco de entrada y el usuario presionó la tecla ENTRAR.

  • NM_SETFOCUS El control recibió el foco de entrada.

La estructura TBNOTIFY contiene los siguientes miembros:

typedef struct {
    NMHDR hdr; // information common to all WM_NOTIFY messages
    int iItem; // index of button associated with notification
    TBBUTTON tbButton; // info about button associated withnotification
    int cchText;   // count of characters in button text
    LPSTR lpszText;// address of button text
} TBNOTIFY, FAR* LPTBNOTIFY;

• Hdr

  Información común a todos los mensajes de WM_NOTIFY .

• iItem

  Índice del botón asociado a la notificación.

• tbButton

  Estructura TBBUTTON que contiene información sobre el botón de la barra de herramientas asociado a la notificación.

• cchText

  Recuento de caracteres en el texto del botón.

• lpszText

  Puntero al texto del botón.

Las notificaciones que envía la barra de herramientas son las siguientes:

• TBN_BEGINADJUST

  Se envía cuando el usuario comienza a personalizar un control de barra de herramientas. El puntero apunta a una estructura NMHDR que contiene información sobre la notificación. El controlador no necesita devolver ningún valor específico.

• TBN_BEGINDRAG

  Se envía cuando el usuario comienza a arrastrar un botón en un control de barra de herramientas. El puntero apunta a una estructura TBNOTIFY . El miembro iItem contiene el índice de base cero del botón que se está arrastrando. El controlador no necesita devolver ningún valor específico.

• TBN_CUSTHELP

  Se envía cuando el usuario elige el botón Ayuda en el cuadro de diálogo Personalizar barra de herramientas. No devuelve ningún valor. El puntero apunta a una estructura NMHDR que contiene información sobre el mensaje de notificación. El controlador no necesita devolver ningún valor específico.

• TBN_ENDADJUST

  Se envía cuando el usuario deja de personalizar un control de barra de herramientas. El puntero apunta a una estructura NMHDR que contiene información sobre el mensaje de notificación. El controlador no necesita devolver ningún valor específico.

• TBN_ENDDRAG

  Se envía cuando el usuario deja de arrastrar un botón en un control de barra de herramientas. El puntero apunta a una estructura TBNOTIFY . El miembro iItem contiene el índice de base cero del botón que se está arrastrando. El controlador no necesita devolver ningún valor específico.

• TBN_GETBUTTONINFO

  Se envía cuando el usuario personaliza un control de barra de herramientas. La barra de herramientas usa este mensaje de notificación para recuperar la información necesaria en el cuadro de diálogo Personalizar barra de herramientas. El puntero apunta a una estructura TBNOTIFY . El miembro iItem especifica el índice de base cero de un botón. Los miembros pszText y cchText especifican la dirección y la longitud, en caracteres, del texto del botón actual. Una aplicación debe rellenar la estructura con información sobre el botón. Devuelve TRUE si la información del botón se copió en la estructura o FALSE en caso contrario.

• TBN_QUERYDELETE

  Se envía mientras el usuario personaliza una barra de herramientas para determinar si se puede eliminar un botón de un control de barra de herramientas. El puntero apunta a una estructura TBNOTIFY . El miembro iItem contiene el índice de base cero del botón que se va a eliminar. Devuelve TRUE para permitir que el botón se elimine o FALSE para evitar que se elimine el botón.

• TBN_QUERYINSERT

  Se envía mientras el usuario personaliza un control de barra de herramientas para determinar si se puede insertar un botón a la izquierda del botón especificado. El puntero apunta a una estructura TBNOTIFY . El miembro iItem contiene el índice de base cero del botón que se va a insertar. Devuelve TRUE para permitir que se inserte un botón delante del botón especificado o FALSE para evitar que se inserte el botón.

• TBN_RESET

  Se envía cuando el usuario restablece el contenido del cuadro de diálogo Personalizar barra de herramientas. El puntero apunta a una estructura NMHDR que contiene información sobre el mensaje de notificación. El controlador no necesita devolver ningún valor específico.

• TBN_TOOLBARCHANGE

  Se envía después de que el usuario haya personalizado un control de barra de herramientas. El puntero apunta a una estructura NMHDR que contiene información sobre el mensaje de notificación. El controlador no necesita devolver ningún valor específico.

Consulte también

Uso de CToolBarCtrl
Mandos