CButton (clase)

Artículo
06/16/2023

Proporciona la funcionalidad de los controles de botón de Windows.

Sintaxis

class CButton : public CWnd

Miembros

Constructores públicos

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

Métodos públicos

Nombre	Descripción
CButton::Create	Crea el control de botón de Windows y lo asocia al objeto `CButton`.
CButton::DrawItem	Se invalida para dibujar un objeto `CButton` dibujado por el propietario.
CButton::GetBitmap	Recupera el identificador del mapa de bits establecido previamente con SetBitmap.
CButton::GetButtonStyle	Recupera información sobre el estilo de control de botón.
CButton::GetCheck	Recupera el estado de comprobación de un control de botón.
CButton::GetCursor	Recupera el identificador de la imagen del cursor establecida previamente con SetCursor.
CButton::GetIcon	Recupera el identificador del icono establecido previamente con SetIcon.
CButton::GetIdealSize	Recupera el tamaño ideal del control de botón.
CButton::GetImageList	Recupera la lista de imágenes del control de botón.
CButton::GetNote	Recupera el componente de nota del control de vínculo de comando actual.
CButton::GetNoteLength	Recupera la longitud del texto de la nota para el control de vínculo de comando actual.
CButton::GetSplitGlyph	Recupera el glifo asociado al control de botón de expansión actual.
CButton::GetSplitImageList	Recupera la lista de imágenes del control de botón de expansión actual.
CButton::GetSplitInfo	Recupera información que define el control de botón de expansión actual.
CButton::GetSplitSize	Recupera el rectángulo delimitador del componente desplegable del control de botón de expansión actual.
CButton::GetSplitStyle	Recupera los estilos del botón de expansión que definen el control de botón de expansión actual.
CButton::GetState	Recupera el estado de comprobación, el estado de resaltado y el estado de foco de un control de botón.
CButton::GetTextMargin	Recupera el margen del texto del control de botón.
CButton::SetBitmap	Especifica un mapa de bits que se va a mostrar en el botón.
CButton::SetButtonStyle	Cambia el estilo de un botón.
CButton::SetCheck	Establece el estado de comprobación de un control de botón.
CButton::SetCursor	Especifica una imagen de cursor que se va a mostrar en el botón.
CButton::SetDropDownState	Establece el estado desplegable del control de botón de expansión actual.
CButton::SetIcon	Especifica un icono que se va a mostrar en el botón.
CButton::SetImageList	Establece la lista de imágenes del control de botón.
CButton::SetNote	Establece la nota en el control de vínculo de comando actual.
CButton::SetSplitGlyph	Asocia un glifo especificado al control de botón de expansión actual.
CButton::SetSplitImageList	Asocia una lista de imágenes con el control de botón de expansión actual.
CButton::SetSplitInfo	Especifica información que define el control de botón de expansión actual.
CButton::SetSplitSize	Establece el rectángulo delimitador del componente desplegable del control de botón de expansión actual.
CButton::SetSplitStyle	Establece el estilo del control de botón de expansión actual.
CButton::SetState	Establece el estado de resaltado de un control de botón.
CButton::SetTextMargin	Establece el margen del texto del control de botón.

Comentarios

Un control de botón es una ventana secundaria pequeña y rectangular que se puede activar y desactivar mediante un clic. Los botones se pueden usar solos o en grupos y pueden etiquetarse o aparecer sin texto. Normalmente, un botón cambia de apariencia cuando el usuario hace clic en él.

Los botones típicos son las casillas, los botones de radio y los botones de inserción. Un objeto CButton puede convertirse en cualquiera de ellos, según el estilo del botón especificado en su inicialización por la función miembro Crear.

Además, la clase CBitmapButton derivada de CButton admite la creación de controles de botón etiquetados con imágenes de mapa de bits en lugar de texto. Un elemento CBitmapButton puede tener mapas de bits independientes para los estados activado, desactivado, enfocado y deshabilitado de un botón.

Puede crear un control de botón a partir de una plantilla de cuadro de diálogo o directamente en el código. En primer lugar, llame al constructor CButton para que construya el objeto CButton y, después, llame a la función miembro Create para que cree el control de botón de Windows y lo asocie al objeto CButton.

La construcción puede ser un proceso de un solo paso en una clase derivada de CButton. Escriba un constructor para la clase derivada y llame a Create desde dentro del constructor.

Si quiere controlar los mensajes de notificación de Windows enviados por un control de botón a su elemento primario (normalmente una clase derivada de CDialog), agregue una entrada de mapa de mensajes y una función miembro del controlador de mensajes a la clase primaria para cada mensaje.

Cada entrada de asignación de mensajes tiene la siguiente forma:

ON_Notification ( id, memberFxn )

donde id. especifica el id. de ventana secundaria del control que envía la notificación y FxnMiembro es el nombre de la función miembro primaria que ha escrito para controlar la notificación.

El prototipo de función principal es el siguiente:

afx_msg void memberFxn();

Las posibles entradas de mapa de mensajes son las siguientes:

Entrada de mapa	Se envía al elemento primario cuando...
ON_BN_CLICKED	El usuario hace clic en un botón.
ON_BN_DOUBLECLICKED	El usuario hace doble clic en un botón.

Si crea un objeto CButton en un recurso de cuadro de diálogo, el objeto CButton se destruye automáticamente cuando el usuario cierra el cuadro de diálogo.

Si crea un objeto CButton dentro de una ventana, es posible que tenga que destruirlo. Si crea el objeto CButton en el montón mediante la función new, debe llamar a delete en el objeto para destruirlo cuando el usuario cierre el control de botón de Windows. Si crea el objeto CButton en la pila o se inserta en el objeto de cuadro de diálogo primario, se destruye automáticamente.

Jerarquía de herencia

CObject

CCmdTarget

CWnd

CButton

Requisitos

Encabezado: afxwin.h

CButton::CButton

Construye un objeto CButton.

CButton();

Ejemplo

// Declare a button object.
CButton myButton;

CButton::Create

Crea el control de botón de Windows y lo asocia al objeto CButton.

virtual BOOL Create(
    LPCTSTR lpszCaption,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parámetros

lpszCaption
[in] Especifica el texto del control de botón.

dwStyle
Especifica el estilo del control de botón. Aplique cualquier combinación de estilos de botón al botón.

rect
Especifica el tamaño y la posición del control de botón. Puede ser un objeto CRect o una estructura RECT.

pParentWnd
Especifica la ventana primaria del control de botón, que suele ser un elemento CDialog. No debe ser NULL.

Nid
Especifica el id. del control de botón.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

El objeto CButton se construye en dos pasos. En primer lugar, llame al constructor y, a continuación, llame a Create, que crea el control de botón de Windows y lo asocia al objeto CButton.

Si se especifica el estilo WS_VISIBLE, Windows envía al control de botón todos los mensajes necesarios para activar y mostrar el botón.

Aplique los siguientes estilos de ventana a un control de botón:

WS_CHILD siempre
WS_VISIBLE Normalmente
WS_DISABLED Rarely
WS_GROUP Para agrupar controles
WS_TABSTOP para incluir el botón en el orden de tabulación

Ejemplo

CButton myButton1, myButton2, myButton3, myButton4;

// Create a push button.
myButton1.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON,
                 CRect(10, 10, 100, 30), pParentWnd, 1);

// Create a radio button.
myButton2.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_RADIOBUTTON,
                 CRect(10, 40, 100, 70), pParentWnd, 2);

// Create an auto 3-state button.
myButton3.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_AUTO3STATE,
                 CRect(10, 70, 100, 100), pParentWnd, 3);

// Create an auto check box.
myButton4.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_AUTOCHECKBOX,
                 CRect(10, 100, 100, 130), pParentWnd, 4);

CButton::DrawItem

El marco lo llama cuando ha cambiado un aspecto visual de un botón dibujado por el propietario.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parámetros

lpDrawItemStruct
Puntero largo a una estructura DRAWITEMSTRUCT. La estructura contiene información sobre el elemento que se va a dibujar y el tipo de dibujo necesario.

Comentarios

Un botón dibujado por el propietario tiene establecido el estilo BS_OWNERDRAW. Invalide esta función miembro para implementar el dibujo de un objeto CButton dibujado por el propietario. La aplicación debe restaurar todos los objetos de Interfaz de dispositivo gráfico (GDI) seleccionados para el contexto de presentación proporcionado en lpDrawItemStruct antes de que finalice esta función miembro.

Consulte también los valores de estilo BS_.

Ejemplo

// NOTE: CMyButton is a class derived from CButton. The CMyButton
// object was created as follows:
//
// CMyButton myButton;
// myButton.Create(_T("My button"),
//      WS_CHILD|WS_VISIBLE|BS_PUSHBUTTON|BS_OWNERDRAW,
//      CRect(10,10,100,30), pParentWnd, 1);
//

// This example implements the DrawItem method for a CButton-derived
// class that draws the button's text using the color red.
void CMyButton::DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct)
{
   UINT uStyle = DFCS_BUTTONPUSH;

   // This code only works with buttons.
   ASSERT(lpDrawItemStruct->CtlType == ODT_BUTTON);

   // If drawing selected, add the pushed style to DrawFrameControl.
   if (lpDrawItemStruct->itemState & ODS_SELECTED)
      uStyle |= DFCS_PUSHED;

   // Draw the button frame.
   ::DrawFrameControl(lpDrawItemStruct->hDC, &lpDrawItemStruct->rcItem,
                      DFC_BUTTON, uStyle);

   // Get the button's text.
   CString strText;
   GetWindowText(strText);

   // Draw the button text using the text color red.
   COLORREF crOldColor = ::SetTextColor(lpDrawItemStruct->hDC, RGB(255, 0, 0));
   ::DrawText(lpDrawItemStruct->hDC, strText, strText.GetLength(),
              &lpDrawItemStruct->rcItem, DT_SINGLELINE | DT_VCENTER | DT_CENTER);
   ::SetTextColor(lpDrawItemStruct->hDC, crOldColor);
}

CButton::GetBitmap

Llame a esta función miembro para obtener el identificador de un mapa de bits, establecido previamente con SetBitmap, que está asociado a un botón.

HBITMAP GetBitmap() const;

Valor devuelto

Identificador de un mapa de bits. NULL si no se ha especificado previamente ningún mapa de bits.

Ejemplo

CButton myBitmapButton;

// Create a bitmap button.
myBitmapButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_BITMAP,
                      CRect(10, 10, 60, 50), pParentWnd, 1);

// If no bitmap is defined for the button, define the bitmap to the
// system close bitmap.
if (myBitmapButton.GetBitmap() == NULL)
   myBitmapButton.SetBitmap(::LoadBitmap(NULL, MAKEINTRESOURCE(OBM_CLOSE)));

CButton::GetButtonStyle

Recupera información sobre el estilo de control de botón.

UINT GetButtonStyle() const;

Valor devuelto

Devuelve los estilos de botón de este objeto CButton. Esta función devuelve solo los valores de estilo BS_, ninguno de los demás estilos de ventana.

Ejemplo

CButton myRadioButton;

// Create a radio button.
myRadioButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_RADIOBUTTON,
                     CRect(10, 10, 100, 30), pParentWnd, 1);

// Change the button style to use one of the "auto" styles; for
// push button, change to def push button.
UINT uStyle = myRadioButton.GetButtonStyle();
if (uStyle == BS_PUSHBUTTON)
   uStyle = BS_DEFPUSHBUTTON;
else if (uStyle == BS_RADIOBUTTON)
   uStyle = BS_AUTORADIOBUTTON;
else if (uStyle == BS_CHECKBOX)
   uStyle = BS_AUTOCHECKBOX;
else if (uStyle == BS_3STATE)
   uStyle = BS_AUTO3STATE;

// Change the button style to the one wanted.
myRadioButton.SetButtonStyle(uStyle);

CButton::GetCheck

Recupera el estado de comprobación de un botón de radio o casilla.

int GetCheck() const;

Valor devuelto

El valor devuelto de un control de botón creado con el estilo BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, BS_RADIOBUTTON o BS_3STATE es uno de los siguientes valores:

Valor	Significado
BST_UNCHECKED	El estado del botón es desactivado.
BST_CHECKED	El estado del botón es activado.
BST_INDETERMINATE	El estado del botón es indeterminado (solo se aplica si el botón tiene el estilo BS_3STATE o BS_AUTO3STATE).

Si el botón tiene cualquier otro estilo, el valor devuelto es BST_UNCHECKED.

Ejemplo

CButton myA3Button;

// Create an auto 3-state button.
myA3Button.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_AUTO3STATE,
                  CRect(10, 10, 100, 30), pParentWnd, 1);

// Set the check state to the next state
// (i.e. BST_UNCHECKED changes to BST_CHECKED
// BST_CHECKED changes to BST_INDETERMINATE
// BST_INDETERMINATE changes to BST_UNCHECKED).
myA3Button.SetCheck(((myA3Button.GetCheck() + 1) % 3));

CButton::GetCursor

Llame a esta función miembro para obtener el identificador de un cursor, establecido previamente con SetCursor, que está asociado a un botón.

HCURSOR GetCursor();

Valor devuelto

Identificador de una imagen de cursor. NULL si no se ha especificado previamente ningún cursor.

Ejemplo

CButton myIconButton;

// Create an icon button.
myIconButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_ICON,
                    CRect(10, 10, 60, 50), pParentWnd, 1);

// If no image is defined for the button, define the image to the
// system arrow and question mark cursor.
if (myIconButton.GetCursor() == NULL)
   myIconButton.SetCursor(::LoadCursor(NULL, IDC_HELP));

CButton::GetIcon

Llame a esta función miembro para obtener el identificador de un icono, establecido previamente con SetIcon, que está asociado a un botón.

HICON GetIcon() const;

Valor devuelto

Identificador de un icono. NULL si no se ha especificado previamente ningún icono.

Ejemplo

CButton myIconButton2;

// Create an icon button.
myIconButton2.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_ICON,
                     CRect(10, 10, 60, 50), pParentWnd, 1);

// If no icon is defined for the button, define the icon to the
// system error icon.
if (myIconButton2.GetIcon() == NULL)
   myIconButton2.SetIcon(::LoadIcon(NULL, IDI_ERROR));

CButton::GetIdealSize

Recupera el tamaño ideal del control de botón.

BOOL GetIdealSize(SIZE* psize);

Parámetros

psize
Puntero al tamaño actual del botón.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Esta función miembro emula la funcionalidad del mensaje BCM_GETIDEALSIZE, como se describe en la sección Botones de Windows SDK.

CButton::GetImageList

Llame a este método para obtener la lista de imágenes del control de botón.

BOOL GetImageList(PBUTTON_IMAGELIST pbuttonImagelist);

Parámetros

pbuttonImagelist
Puntero a la lista de imágenes del objeto CButton.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Esta función miembro emula la funcionalidad del mensaje BCM_GETIMAGELIST, como se describe en la sección Botones de Windows SDK.

CButton::GetNote

Recupera el texto de la nota asociada al control de vínculo de comando actual.

CString GetNote() const;

BOOL GetNote(
    LPTSTR lpszNote,
    UINT* cchNote) const;

Parámetros

lpszNote
[out] Puntero a un búfer, que el autor de la llamada es responsable de asignar y desasignar. Si el valor devuelto es TRUE, el búfer contiene el texto de la nota asociada al control de vínculo de comando actual; de lo contrario, el búfer no cambia.

cchNote
[in, out] Puntero a una variable de entero sin signo. Cuando se llama a este método, la variable contiene el tamaño del búfer especificado por el parámetro lpszNote. Cuando vuelve este método, si el valor devuelto es TRUE, la variable contiene el tamaño de la nota asociada al control de vínculo de comando actual. Si el valor devuelto es FALSE, la variable contiene el tamaño del búfer necesario para contener la nota.

Valor devuelto

En la primera sobrecarga, un objeto CString que contiene el texto de la nota asociada al control de vínculo de comando actual.

O bien

En la segunda sobrecarga, TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_COMMANDLINK o BS_DEFCOMMANDLINK.

Este método envía el mensaje BCM_GETNOTE, que se describe en Windows SDK.

CButton::GetNoteLength

Recupera la longitud del texto de la nota para el control de vínculo de comando actual.

UINT GetNoteLength() const;

Valor devuelto

Longitud del texto de la nota, en caracteres Unicode de 16 bits, para el control de vínculo de comando actual.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_COMMANDLINK o BS_DEFCOMMANDLINK.

Este método envía el mensaje BCM_GETNOTELENGTH, que se describe en Windows SDK.

CButton::GetSplitGlyph

Recupera el glifo asociado al control de botón de expansión actual.

TCHAR GetSplitGlyph() const;

Valor devuelto

Carácter de glifo asociado al control de botón de expansión actual.

Comentarios

Un glifo es la representación física de un carácter en una fuente determinada. Por ejemplo, un control de botón de expansión puede estar decorado con el glifo del carácter de marca de comprobación Unicode (U+2713).

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Este método inicializa el miembro mask de una estructura BUTTON_SPLITINFO con la marca BCSIF_GLYPH y, a continuación, envía esa estructura en el mensaje BCM_GETSPLITINFO que se describe en Windows SDK. Cuando se devuelve la función de mensaje, este método recupera el glifo del miembro himlGlyph de la estructura.

CButton::GetSplitImageList

Recupera la lista de imágenes del control de botón de expansión actual.

CImageList* GetSplitImageList() const;

Valor devuelto

Puntero a un objeto CImageList.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Este método inicializa el miembro mask de una estructura BUTTON_SPLITINFO con la marca BCSIF_IMAGE y, a continuación, envía esa estructura en el mensaje BCM_GETSPLITINFO que se describe en Windows SDK. Cuando se devuelve la función de mensaje, este método recupera la lista de imágenes del miembro himlGlyph de la estructura.

CButton::GetSplitInfo

Recupera parámetros que determinan cómo Windows dibuja el control de botón de expansión actual.

BOOL GetSplitInfo(PBUTTON_SPLITINFO pInfo) const;

Parámetros

pInfo
[out] Puntero a una estructura BUTTON_SPLITINFO que recibe información sobre el control de botón de expansión actual. El autor de la llamada es responsable de asignar la estructura .

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Este método envía el mensaje BCM_GETSPLITINFO, que se describe en Windows SDK.

CButton::GetSplitSize

Recupera el rectángulo delimitador del componente desplegable del control de botón de expansión actual.

BOOL GetSplitSize(LPSIZE pSize) const;

Parámetros

pSize
[out] Puntero a una estructura SIZE que recibe la descripción de un rectángulo.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Cuando se expande el control de botón de expansión, puede mostrar un componente desplegable, como un control de lista o un control de paginación. Este método recupera el rectángulo delimitador que contiene el componente desplegable.

Este método inicializa el miembro mask de una estructura BUTTON_SPLITINFO con la marca BCSIF_SIZE y, a continuación, envía esa estructura en el mensaje BCM_GETSPLITINFO que se describe en Windows SDK. Cuando se devuelve la función de mensaje, este método recupera el rectángulo delimitador del miembro size de la estructura.

CButton::GetSplitStyle

Recupera los estilos del botón de expansión que definen el control de botón de expansión actual.

UINT GetSplitStyle() const;

Valor devuelto

Combinación bit a bit de estilos de botón de expansión. Para más información, vea el miembro uSplitStyle de la estructura BUTTON_SPLITINFO.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Los estilos de botón de expansión especifican la alineación, la relación de aspecto y el formato gráfico con el que Windows dibuja un icono de botón de expansión.

Este método inicializa el miembro mask de una estructura BUTTON_SPLITINFO con la marca BCSIF_STYLE y, a continuación, envía esa estructura en el mensaje BCM_GETSPLITINFO que se describe en Windows SDK. Cuando se devuelve la función de mensaje, este método recupera los estilos de botón de expansión del miembro uSplitStyle de la estructura.

CButton::GetState

Recupera el estado de un control de botón.

UINT GetState() const;

Valor devuelto

Campo de bits que contiene la combinación de valores que indican el estado actual de un control de botón. En la tabla siguiente, se enumeran los valores posibles.

Estado del botón	Valor	Descripción
BST_UNCHECKED	0x0000	Estado inicial.
BST_CHECKED	0x0001	El control de botón está activado.
BST_INDETERMINATE	0x0002	El estado es indeterminado (solo es posible cuando el control de botón tiene tres estados).
BST_PUSHED	0x0004	El control de botón está presionado.
BST_FOCUS	0x0008	El control de botón tiene el foco.

Comentarios

Un control de botón con el estilo de botón BS_3STATE o BS_AUTO3STATE crea una casilla que tiene un tercer estado denominado estado indeterminado. El estado indeterminado indica que la casilla no está activada ni desactivada.

Ejemplo

CButton myPushButton;

// Create a push button.
myPushButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON,
                    CRect(10, 10, 100, 30), pParentWnd, 1);

// Invert the highlight state of the button.
myPushButton.SetState(!(myPushButton.GetState() & 0x0004));

CButton::GetTextMargin

Llame a este método para obtener el margen del texto del objeto CButton.

BOOL GetTextMargin(RECT* pmargin);

Parámetros

pmargin
Puntero al margen de texto del CButton objeto.

Valor devuelto

Devuelve el margen del texto. Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Esta función miembro emula la funcionalidad del mensaje BCM_GETTEXTMARGIN, como se describe en la sección Botones de Windows SDK.

CButton::SetBitmap

Llame a esta función miembro para asociar un nuevo mapa de bits al botón.

HBITMAP SetBitmap(HBITMAP hBitmap);

Parámetros

hBitmap
Identificador de un mapa de bits.

Valor devuelto

Identificador de un mapa de bits asociado previamente al botón.

Comentarios

El mapa de bits se colocará automáticamente en la cara del botón, centrado de forma predeterminada. Si el mapa de bits es demasiado grande para el botón, se recortará a ambos lados. Puede elegir otras opciones de alineación, incluidas las siguientes:

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

A diferencia de CBitmapButton, que usa cuatro mapas de bits por botón, SetBitmap usa solo un mapa de bits por botón. Cuando se presiona el botón, el mapa de bits parece desplazarse hacia abajo y hacia la derecha.

Usted es responsable de liberar el mapa de bits cuando haya terminado.

Ejemplo

CButton myBitmapButton;

// Create a bitmap button.
myBitmapButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_BITMAP,
                      CRect(10, 10, 60, 50), pParentWnd, 1);

// If no bitmap is defined for the button, define the bitmap to the
// system close bitmap.
if (myBitmapButton.GetBitmap() == NULL)
   myBitmapButton.SetBitmap(::LoadBitmap(NULL, MAKEINTRESOURCE(OBM_CLOSE)));

CButton::SetButtonStyle

Cambia el estilo de un botón.

void SetButtonStyle(
    UINT nStyle,
    BOOL bRedraw = TRUE);

Parámetros

nStyle
Especifica el estilo del botón.

bRedraw
Especifica si el botón se va a volver a dibujar. Un valor distinto de cero vuelve a dibujar el botón. Un valor 0 no vuelve a dibujar el botón. El botón se vuelve a dibujar de forma predeterminada.

Comentarios

Use la función miembro GetButtonStyle para recuperar el estilo del botón. La palabra de orden inferior del estilo de botón completo es el estilo específico del botón.

Ejemplo

CButton myRadioButton;

// Create a radio button.
myRadioButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_RADIOBUTTON,
                     CRect(10, 10, 100, 30), pParentWnd, 1);

// Change the button style to use one of the "auto" styles; for
// push button, change to def push button.
UINT uStyle = myRadioButton.GetButtonStyle();
if (uStyle == BS_PUSHBUTTON)
   uStyle = BS_DEFPUSHBUTTON;
else if (uStyle == BS_RADIOBUTTON)
   uStyle = BS_AUTORADIOBUTTON;
else if (uStyle == BS_CHECKBOX)
   uStyle = BS_AUTOCHECKBOX;
else if (uStyle == BS_3STATE)
   uStyle = BS_AUTO3STATE;

// Change the button style to the one wanted.
myRadioButton.SetButtonStyle(uStyle);

CButton::SetCheck

Establece o restablece el estado de comprobación de un botón de radio o casilla.

void SetCheck(int nCheck);

Parámetros

nCheck
Especifica el estado de comprobación. Este parámetro puede ser uno de los siguientes:

Valor	Significado
BST_UNCHECKED	Establece el estado del botón en desactivado.
BST_CHECKED	Establece el estado del botón en activado.
BST_INDETERMINATE	Establece el estado del botón en indeterminado. Este valor solo se puede usar si el botón tiene el estilo BS_3STATE o BS_AUTO3STATE.

Comentarios

Esta función miembro no tiene ningún efecto en un botón de inserción.

Ejemplo

CButton myA3Button;

// Create an auto 3-state button.
myA3Button.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_AUTO3STATE,
                  CRect(10, 10, 100, 30), pParentWnd, 1);

// Set the check state to the next state
// (i.e. BST_UNCHECKED changes to BST_CHECKED
// BST_CHECKED changes to BST_INDETERMINATE
// BST_INDETERMINATE changes to BST_UNCHECKED).
myA3Button.SetCheck(((myA3Button.GetCheck() + 1) % 3));

CButton::SetCursor

Llame a esta función miembro para asociar un nuevo cursor al botón.

HCURSOR SetCursor(HCURSOR hCursor);

Parámetros

hCursor
Identificador de un cursor.

Valor devuelto

Identificador de un cursor asociado previamente al botón.

Comentarios

El cursor se colocará automáticamente en la cara del botón, centrado de forma predeterminada. Si el cursor es demasiado grande para el botón, se recortará a ambos lados. Puede elegir otras opciones de alineación, incluidas las siguientes:

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

A diferencia de CBitmapButton, que usa cuatro mapas de bits por botón, SetCursor usa solo un cursor por botón. Cuando se presiona el botón, el cursor parece desplazarse hacia abajo y hacia la derecha.

Ejemplo

CButton myIconButton;

// Create an icon button.
myIconButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_ICON,
                    CRect(10, 10, 60, 50), pParentWnd, 1);

// If no image is defined for the button, define the image to the
// system arrow and question mark cursor.
if (myIconButton.GetCursor() == NULL)
   myIconButton.SetCursor(::LoadCursor(NULL, IDC_HELP));

CButton::SetDropDownState

Establece el estado desplegable del control de botón de expansión actual.

BOOL SetDropDownState(BOOL fDropDown);

Parámetros

fDropDown
[in] TRUE para establecer el estado BST_DROPDOWNPUSHED; de lo contrario, FALSE.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Un control de botón de expansión tiene un estilo de BS_SPLITBUTTON o BS_DEFSPLITBUTTON, y consta de un botón y una flecha desplegable a su derecha. Para más información, consulte Estilos de botón. Normalmente, el estado de la lista desplegable se establece cuando el usuario hace clic en la flecha desplegable. Use este método para establecer mediante programación el estado desplegable del control. La flecha desplegable se dibuja sombreada para indicar el estado.

Este método envía el mensaje BCM_SETDROPDOWNSTATE, que se describe en Windows SDK.

Ejemplo

En el primer ejemplo de código se define la variable m_splitButton, que se usa para acceder mediante programación al control de botón de expansión. Esta variable se usa en el ejemplo siguiente.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

En el ejemplo de código siguiente se establece el estado del control de botón de expansión para indicar que se inserta la flecha desplegable.

/* Set the state of the split button control to indicate that 
   the drop-down arrow is pushed. The arrow is drawn shaded to 
   indicate the state.
   */
m_splitButton.SetDropDownState(TRUE);

CButton::SetElevationRequired

Establece el estado del control de botón actual en elevation required, que es necesario para que el control muestre un icono de seguridad elevada.

BOOL SetElevationRequired(BOOL fElevationRequired);

Parámetros

fElevationRequired
[in] TRUE para establecer el estado elevation required; en caso contrario, FALSE.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Si un control de vínculo de comando o botón requiere permisos de seguridad elevados para realizar una acción, establezca el control en estado elevation required. Posteriormente, Windows muestra el icono de escudo de Control de cuentas de usuario (UAC) en el control. Para más información, vea User Account Control (Control de cuentas de usuario).

Este método envía el mensaje BCM_SETSHIELD, que se describe en Windows SDK.

CButton::SetIcon

Llame a esta función miembro para asociar un nuevo icono al botón.

HICON SetIcon(HICON hIcon);

Parámetros

hIcon
Identificador de un icono.

Valor devuelto

Identificador de un icono asociado previamente al botón.

Comentarios

El icono se colocará automáticamente en la cara del botón, centrado de forma predeterminada. Si el icono es demasiado grande para el botón, se recortará a ambos lados. Puede elegir otras opciones de alineación, incluidas las siguientes:

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

A diferencia de CBitmapButton, que usa cuatro mapas de bits por botón, SetIcon usa solo un icono por botón. Cuando se presiona el botón, el icono parece desplazarse hacia abajo y hacia la derecha.

Ejemplo

CButton myIconButton2;

// Create an icon button.
myIconButton2.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_ICON,
                     CRect(10, 10, 60, 50), pParentWnd, 1);

// If no icon is defined for the button, define the icon to the
// system error icon.
if (myIconButton2.GetIcon() == NULL)
   myIconButton2.SetIcon(::LoadIcon(NULL, IDI_ERROR));

CButton::SetImageList

Llame a este método para establecer la lista de imágenes del objeto CButton.

BOOL SetImageList(PBUTTON_IMAGELIST pbuttonImagelist);

Parámetros

pbuttonImagelist
Puntero a la nueva lista de imágenes.

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

Esta función miembro emula la funcionalidad del mensaje BCM_SETIMAGELIST, como se describe en la sección Botones de Windows SDK.

CButton::SetNote

Establece el texto de la nota en el control de vínculo de comando actual.

BOOL SetNote(LPCTSTR lpszNote);

Parámetros

lpszNote
[in] Puntero a una cadena Unicode que se establece como texto de la nota para el control de vínculo de comando.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_COMMANDLINK o BS_DEFCOMMANDLINK.

Este método envía el mensaje BCM_SETNOTE, que se describe en Windows SDK.

Ejemplo

En el primer ejemplo de código se define la variable m_cmdLink, que se usa para acceder mediante programación al control de vínculo de comando. Esta variable se usa en el ejemplo siguiente.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

En el ejemplo de código siguiente se establece el texto de la nota para el control de vínculo de comando.

// Set the command link text.
m_cmdLink.SetNote(_T("This is the command link note."));

CButton::SetSplitGlyph

Asocia un glifo especificado al control de botón de expansión actual.

BOOL SetSplitGlyph(TCHAR chGlyph);

Parámetros

chGlyph
[in] Carácter que especifica el glifo que se va a usar como flecha desplegable del botón de expansión.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles que tienen el estilo de botón BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Un glifo es la representación física de un carácter en una fuente determinada. El parámetro chGlyph no se usa como glifo, sino que se usa para seleccionar un glifo de un conjunto de glifos definidos por el sistema. El glifo de flecha desplegable predeterminado se especifica mediante un carácter "6", y se parece al carácter Unicode TRIÁNGULO NEGRO APUNTANDO HACIA ABAJO (U+25BC).

Este método inicializa el miembro mask de una estructura BUTTON_SPLITINFO con la marca BCSIF_GLYPH y el miembro himlGlyph con el parámetro chGlyph y, a continuación, envía esa estructura en el mensaje BCM_GETSPLITINFO que se describe en Windows SDK.

CButton::SetSplitImageList

Asocia una lista de imágenes con el control de botón de expansión actual.

BOOL SetSplitImageList(CImageList* pSplitImageList);

Parámetros

pSplitImageList
[in] Puntero a un objeto CImageList que se va a asignar al control de botón de expansión actual.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Este método inicializa el miembro mask de una estructura BUTTON_SPLITINFO con la marca BCSIF_IMAGE y el miembro himlGlyph con el parámetro pSplitImageList y, a continuación, envía esa estructura en el mensaje BCM_GETSPLITINFO que se describe en Windows SDK.

CButton::SetSplitInfo

Especifica parámetros que determinan cómo Windows dibuja el control de botón de expansión actual.

BOOL SetSplitInfo(PBUTTON_SPLITINFO pInfo);

Parámetros

pInfo
[in] Puntero a una estructura BUTTON_SPLITINFO que define el control de botón de expansión actual.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Este método envía el mensaje BCM_SETSPLITINFO, que se describe en Windows SDK.

Ejemplo

En el primer ejemplo de código se define la variable m_splitButton, que se usa para acceder mediante programación al control de botón de expansión.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

En el ejemplo de código siguiente se cambia el glifo que se usa para la flecha desplegable del botón de expansión. En el ejemplo se sustituye un glifo de triángulo que apunta hacia arriba por el glifo de triángulo hacia abajo predeterminado. El glifo que se muestra depende del carácter que especifique en el miembro himlGlyph de la estructura BUTTON_SPLITINFO. El glifo de triángulo que apunta hacia abajo se especifica mediante un carácter "6" y el glifo de triángulo que apunta hacia arriba se especifica mediante un carácter "5". Para una comparación, consulte el método de conveniencia CButton::SetSplitGlyph.

/* 
   The drop-down arrow glyph is a function of the specified character. 
   The default "down" drop-down arrow glyph is specified by a 
   character '6'. Set the "up" arrow glyph, which is a character '5'.
   See the convenience method, SetSplitGlyph(), for comparison.
   */
BUTTON_SPLITINFO bsInfo = {0};
bsInfo.mask = BCSIF_GLYPH;
TCHAR chGlyph = _T('5'); // "up" arrow glyph
bsInfo.himlGlyph = (HIMAGELIST)chGlyph;
bRC = m_splitButton.SetSplitInfo(&bsInfo);

CButton::SetSplitSize

Establece el rectángulo delimitador del componente desplegable del control de botón de expansión actual.

BOOL SetSplitSize(LPSIZE pSize);

Parámetros

pSize
[in] Puntero a una estructura SIZE que describe un rectángulo delimitador.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Cuando se expande el control de botón de expansión, puede mostrar un componente desplegable, como un control de lista o un control de paginación. Este método especifica el tamaño del rectángulo delimitador que contiene el componente desplegable.

Este método inicializa el miembro mask de una estructura BUTTON_SPLITINFO con la marca BCSIF_SIZE y el miembro size con el parámetro pSize y, a continuación, envía esa estructura en el mensaje BCM_GETSPLITINFO que se describe en Windows SDK.

Ejemplo

En el primer ejemplo de código se define la variable m_splitButton, que se usa para acceder mediante programación al control de botón de expansión. Esta variable se usa en el ejemplo siguiente.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

En el ejemplo de código siguiente se duplica el tamaño de la flecha desplegable del botón de expansión.

// Double the size of the split button drop-down arrow.
SIZE sz;
bRC = m_splitButton.GetSplitSize(&sz); // current size
sz.cx = sz.cx * 2;
sz.cy = sz.cy * 2;
bRC = m_splitButton.SetSplitSize(&sz);

CButton::SetSplitStyle

Establece el estilo del control de botón de expansión actual.

BOOL SetSplitStyle(UINT uSplitStyle);

Parámetros

uSplitStyle
[in] Combinación bit a bit de estilos de botón de expansión. Para más información, vea el miembro uSplitStyle de la estructura BUTTON_SPLITINFO.

Valor devuelto

TRUE si este método se ejecuta correctamente; de lo contrario, FALSE.

Comentarios

Use este método solo con controles cuyo estilo de botón sea BS_SPLITBUTTON o BS_DEFSPLITBUTTON.

Los estilos de botón de expansión especifican la alineación, la relación de aspecto y el formato gráfico con el que Windows dibuja un icono de botón de expansión. Para más información, vea el miembro uSplitStyle de la estructura BUTTON_SPLITINFO.

Este método inicializa el miembro mask de una estructura BUTTON_SPLITINFO con la marca BCSIF_STYLE y el miembro uSplitStyle con el parámetro uSplitStyle y, a continuación, envía esa estructura en el mensaje BCM_GETSPLITINFO que se describe en Windows SDK.

Ejemplo

En el primer ejemplo de código se define la variable m_splitButton, que se usa para acceder mediante programación al control de botón de expansión.

public:
// Variable to access programatically defined command link control.
CButton m_cmdLink;
// Variable to access programatically defined split button control.
CButton m_splitButton;

En el ejemplo de código siguiente se establece el estilo de la flecha desplegable del botón de expansión. El estilo BCSS_ALIGNLEFT muestra la flecha en el lado izquierdo del botón y el estilo BCSS_STRETCH conserva las proporciones de la flecha desplegable al cambiar el tamaño del botón.

/* 
    Set the style of the split button drop-down arrow: Display the 
    arrow on the left and retain the arrow's proportions when resizing 
    the control.
    */
bRC = m_splitButton.SetSplitStyle(BCSS_ALIGNLEFT | BCSS_STRETCH);

CButton::SetState

Establece si un control de botón se resalta o no.

void SetState(BOOL bHighlight);

Parámetros

bHighlight
Especifica si el botón se debe resaltar. Un valor distinto de cero resalta el botón; un valor 0 quita cualquier resaltado.

Comentarios

El resaltado afecta al exterior de un control de botón. No tiene ningún efecto en el estado de comprobación de un botón de radio o casilla.

Un control de botón se resalta automáticamente cuando el usuario hace clic con el botón izquierdo del mouse y lo mantiene pulsado. El resaltado se quita cuando el usuario suelta el botón del mouse.

Ejemplo

CButton myPushButton;

// Create a push button.
myPushButton.Create(_T("My button"), WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON,
                    CRect(10, 10, 100, 30), pParentWnd, 1);

// Invert the highlight state of the button.
myPushButton.SetState(!(myPushButton.GetState() & 0x0004));

CButton::SetTextMargin

Llame a este método para establecer el margen del texto del objeto CButton.

BOOL SetTextMargin(RECT* pmargin);

Parámetros

pmargin
Puntero al nuevo margen de texto.

Valor devuelto

Devuelve TRUE si la operación se realiza correctamente; de lo contrario, devuelve FALSE.

Comentarios

Esta función miembro emula la funcionalidad del mensaje BCM_SETTEXTMARGIN, como se describe en la sección Botones de Windows SDK.

Consulte también

CWnd (clase)
Gráfico de jerarquías
CWnd (clase)
CComboBox (clase)
CEdit (clase)
CListBox (clase)
CScrollBar (clase)
CStatic (clase)
CBitmapButton (clase)
CDialog (clase)

Compartir vía

CButton (clase)

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Comentarios

Jerarquía de herencia

Requisitos

CButton::CButton

Ejemplo

CButton::Create

Parámetros

Valor devuelto

Comentarios

Ejemplo

CButton::DrawItem

Parámetros

Comentarios

Ejemplo

CButton::GetBitmap

Valor devuelto

Ejemplo

CButton::GetButtonStyle

Valor devuelto

Ejemplo

CButton::GetCheck

Valor devuelto

Ejemplo

CButton::GetCursor

Valor devuelto

Ejemplo

CButton::GetIcon

Valor devuelto

Ejemplo

CButton::GetIdealSize

Parámetros

Valor devuelto

Comentarios

CButton::GetImageList

Parámetros

Valor devuelto

Comentarios

CButton::GetNote

Parámetros

Valor devuelto

Comentarios

CButton::GetNoteLength

Valor devuelto

Comentarios

CButton::GetSplitGlyph

Valor devuelto

Comentarios

CButton::GetSplitImageList

Valor devuelto

Comentarios

CButton::GetSplitInfo

Parámetros

Valor devuelto

Comentarios

CButton::GetSplitSize

Parámetros

Valor devuelto

Comentarios

CButton::GetSplitStyle

Valor devuelto

Comentarios

CButton::GetState

Valor devuelto

Comentarios

Ejemplo

CButton::GetTextMargin

Parámetros

Valor devuelto

Comentarios

CButton::SetBitmap

Parámetros

Valor devuelto

Comentarios

Ejemplo