Classe CButton

Artigo
07/05/2024

Fornece a funcionalidade dos controles de botão Windows.

Sintaxe

class CButton : public CWnd

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
CButton::Create	Cria o controle de botão Windows e o anexa ao objeto `CButton`.
CButton::DrawItem	Substitua para desenhar um objeto desenhado pelo proprietário `CButton`.
CButton::GetBitmap	Recupera o identificador do bitmap definido anteriormente com SetBitmap.
CButton::GetButtonStyle	Recupera informações sobre o estilo de controle de botão.
CButton::GetCheck	Recupera o estado de verificação de um controle de botão.
CButton::GetCursor	Recupera o identificador da imagem do cursor definida anteriormente com SetCursor.
CButton::GetIcon	Recupera o identificador do ícone definido anteriormente com SetIcon.
CButton::GetIdealSize	Recupera o tamanho ideal do controle de botão.
CButton::GetImageList	Recupera a lista de imagens do controle de botão.
CButton::GetNote	Recupera o componente de anotação do controle de link de comando atual.
CButton::GetNoteLength	Recupera o comprimento do texto da anotação para o controle de link de comando atual.
CButton::GetSplitGlyph	Recupera o glifo associado ao controle de botão de divisão atual.
CButton::GetSplitImageList	Recupera a lista de imagens para o controle de botão de divisão atual.
CButton::GetSplitInfo	Recupera informações que definem o controle de botão de divisão atual.
CButton::GetSplitSize	Recupera o retângulo delimitador do componente suspenso do controle de botão de divisão atual.
CButton::GetSplitStyle	Recupera os estilos de botão de divisão que definem o controle de botão de divisão atual.
CButton::GetState	Recupera o estado de verificação, o estado de realce e o estado de foco de um controle de botão.
CButton::GetTextMargin	Recupera a margem de texto do controle de botão.
CButton::SetBitmap	Especifica um bitmap a ser exibido no botão.
CButton::SetButtonStyle	Altera o estilo de um botão.
CButton::SetCheck	Define o estado de verificação de um controle de botão.
CButton::SetCursor	Especifica uma imagem de cursor a ser exibida no botão.
CButton::SetDropDownState	Define o estado suspenso do controle de botão de divisão atual.
CButton::SetIcon	Especifica um ícone a ser exibido no botão.
CButton::SetImageList	Define a lista de imagens do controle de botão.
CButton::SetNote	Define a anotação no controle de link de comando atual.
CButton::SetSplitGlyph	Associa um glifo especificado ao controle de botão de divisão atual.
CButton::SetSplitImageList	Associa uma lista de imagens ao controle de botão de divisão atual.
CButton::SetSplitInfo	Especifica informações que definem o controle de botão de divisão atual.
CButton::SetSplitSize	Define o retângulo delimitador do componente suspenso do controle de botão de divisão atual.
CButton::SetSplitStyle	Define o estilo do controle de botão de divisão atual.
CButton::SetState	Define o estado de realce de um controle de botão.
CButton::SetTextMargin	Define a margem de texto do controle de botão.

Comentários

Um controle de botão é uma janela filho pequena e retangular em que se pode clicar para ativar e desativar. Os botões podem ser usados sozinhos ou em grupos e ser rotulados ou exibidos sem texto. Normalmente, a aparência de um botão muda quando o usuário clica nele.

Os botões típicos são a caixa de seleção, o botão de opção e o botão de pressionar. Um objeto CButton pode se tornar qualquer um deles, de acordo com o estilo de botão especificado em sua inicialização pela função de membro Create.

Além disso, a classe CBitmapButton derivada de CButton dá suporte para a criação de controles de botão rotulados com imagens bitmap, em vez de texto. Um CBitmapButton pode ter bitmaps separados para os estados para cima, para baixo, focado e desabilitado de um botão.

Você pode criar um controle de botão de um modelo de caixa de diálogo ou diretamente em seu código. Em ambos os casos, primeiro chame o construtor CButton para construir o objeto CButton; em seguida, chame a função de membro Create para criar o controle de botão Windows e anexá-lo ao objeto CButton.

A construção pode ser um processo de uma etapa em uma classe derivada de CButton. Escreva um construtor para a classe derivada e chame Create de dentro do construtor.

Se você quiser lidar com mensagens de notificação do Windows enviadas por um controle de botão para seu pai (geralmente uma classe derivada de CDialog), adicione uma entrada de mapa de mensagens e uma função de membro do manipulador de mensagens à classe pai para cada mensagem.

Cada entrada de mapa de mensagens usa o seguinte formulário:

ON_Notificação ( id, memberFxn )

em que id especifica a ID da janela filho do controle que envia a notificação e memberFxn é o nome da função de membro pai que você escreveu para lidar com a notificação.

O protótipo de função do pai é o seguinte:

afx_msg void memberFxn();

As entradas potenciais do mapa de mensagens são as seguintes:

Entrada de mapa	Enviado para o pai quando...
ON_BN_CLICKED	O usuário clica em um botão.
ON_BN_DOUBLECLICKED	O usuário clica duas vezes em um botão.

Se você criar um objeto CButton com base em um recurso de caixa de diálogo, o objeto CButton será destruído automaticamente quando o usuário fechar a caixa de diálogo.

Se você criar um objeto CButton dentro de uma janela, talvez seja necessário destruí-lo. Se você criar o objeto CButton no heap usando a função new, deverá chamar o objeto delete para destruí-lo quando o usuário fechar o controle de botão Windows. Se você criar o objeto CButton na pilha ou ele estiver inserido no objeto de diálogo pai, ele será destruído automaticamente.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CButton

Requisitos

Cabeçalho: afxwin.h

CButton::CButton

Constrói um objeto CButton.

CButton();

Exemplo

// Declare a button object.
CButton myButton;

CButton::Create

Cria o controle de botão Windows e o anexa ao objeto CButton.

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

Parâmetros

lpszCaption
Especifica o texto do controle de botão.

dwStyle
Especifica o estilo do controle de botão. Aplique qualquer combinação de estilos de botão ao botão.

rect
Especifica o tamanho e a posição do controle de botão. Pode ser um objeto CRect ou uma estrutura RECT.

pParentWnd
Especifica a janela pai do controle de botão, geralmente um CDialog. Não pode ser NULL.

Nid
Especifica a ID do controle de botão.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Um objeto CButton é construído em duas etapas. Primeiro, chame o construtor, então chame Create, o que cria o controle de botão Windows e o anexa ao objeto CButton.

Se o estilo de WS_VISIBLE for dado, o Windows enviará ao controle de botão todas as mensagens necessárias para ativar e mostrar o botão.

Aplique os seguintes estilos de janela a um controle de botão:

WS_CHILD sempre
WS_VISIBLE Habitualmente
WS_DISABLED Raramente
WS_GROUP Para agrupar controles
WS_TABSTOP Para incluir o botão na ordem de tabulação

Exemplo

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

Chamado pela estrutura quando um aspecto visual de um botão desenhado pelo proprietário foi alterado.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

lpDrawItemStruct
Um ponteiro longo para uma estrutura DRAWITEMSTRUCT. A estrutura contém informações sobre o item a ser desenhado e o tipo de desenho necessário.

Comentários

Um botão desenhado pelo proprietário tem o conjunto de estilos BS_OWNERDRAW. Substitua essa função de membro para implementar o desenho de um objeto desenhado pelo proprietário CButton. O aplicativo deve restaurar todos os objetos GDI (Graphics Device Interface) selecionados para o contexto de exibição fornecido no lpDrawItemStruct antes que a função membro seja encerrada.

Veja também os valores de estilo BS_.

Exemplo

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

Chame essa função de membro para obter o identificador de um bitmap, definido anteriormente com SetBitmap, que está associado a um botão.

HBITMAP GetBitmap() const;

Valor de retorno

Um identificador para um bitmap. NULL se nenhum bitmap for especificado anteriormente.

Exemplo

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 informações sobre o estilo de controle de botão.

UINT GetButtonStyle() const;

Valor de retorno

Retorna os estilos de botão para este objeto CButton. Essa função retorna apenas os valores de estilo BS_, não nenhum um dos outros estilos de janela.

Exemplo

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 o estado de seleção de um botão de opção ou caixa de seleção.

int GetCheck() const;

Valor de retorno

O valor retornado de um controle de botão criado com o estilo BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON, BS_AUTO3STATE, BS_CHECKBOX, BS_RADIOBUTTON ou BS_3STATE é um destes:

Valor	Significado
BST_UNCHECKED	O estado do botão é desmarcado.
BST_CHECKED	O estado do botão é marcado.
BST_INDETERMINATE	O estado do botão é indeterminado (aplica-se somente se o botão tiver o estilo BS_3STATE ou BS_AUTO3STATE).

Se o botão tiver outro estilo, o valor retornado será BST_UNCHECKED.

Exemplo

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

Chame essa função de membro para obter o identificador de um cursor, definido anteriormente com SetCursor, que está associado a um botão.

HCURSOR GetCursor();

Valor de retorno

Um identificador para uma imagem de cursor. NULL se nenhum cursor for especificado anteriormente.

Exemplo

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

Chame essa função de membro para obter o identificador de um ícone, definido anteriormente com SetIcon, que está associado a um botão.

HICON GetIcon() const;

Valor de retorno

Um identificador para um ícone. NULL se nenhum ícone for especificado anteriormente.

Exemplo

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 o tamanho ideal para o controle de botão.

BOOL GetIdealSize(SIZE* psize);

Parâmetros

psize
Um ponteiro para o tamanho atual do botão.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função membro emula a funcionalidade da mensagem BCM_GETIDEALSIZE, conforme descrito na seção Botões do SDK do Windows.

CButton::GetImageList

Chame esse método para obter a lista de imagens do controle de botão.

BOOL GetImageList(PBUTTON_IMAGELIST pbuttonImagelist);

Parâmetros

pbuttonImagelist
Um ponteiro para a lista de imagens do objeto CButton.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função de membro emula a funcionalidade da mensagem BCM_GETIMAGELIST, conforme descrito na seção Botões do SDK do Windows.

CButton::GetNote

Recupera o texto da anotação associado ao controle de link de comando atual.

CString GetNote() const;

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

Parâmetros

lpszNote
[out] Ponteiro para um buffer, que o chamador é responsável por alocar e desalocar. Se o valor retornado for TRUE, o buffer conterá o texto da anotação associado ao controle de link de comando atual; caso contrário, o buffer não será alterado.

cchNote
[in, out] Um ponteiro para uma variável de inteiro sem sinal. Quando esse método é chamado, a variável contém o tamanho do buffer especificado pelo parâmetro lpszNote. Quando esse método retorna, se o valor retornado for TRUE, a variável conterá o tamanho da nota associada ao controle de link de comando atual. Se o valor retornado for FALSE, a variável conterá o tamanho do buffer necessário para conter a anotação.

Valor de retorno

Na primeira sobrecarga, um objeto CString que contém o texto da anotação associado ao controle de link de comando atual.

-ou-

Na segunda sobrecarga, TRUE se esse método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_COMMANDLINK ou BS_DEFCOMMANDLINK.

Esse método envia a mensagem BCM_GETNOTE, que é descrita no SDK do Windows.

CButton::GetNoteLength

Recupera o comprimento do texto da anotação para o controle de link de comando atual.

UINT GetNoteLength() const;

Valor de retorno

O comprimento do texto da anotação, em caracteres Unicode de 16 bits, para o controle de link de comando atual.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_COMMANDLINK ou BS_DEFCOMMANDLINK.

Esse método envia a mensagem BCM_GETNOTELENGTH, que é descrita no SDK do Windows.

CButton::GetSplitGlyph

Recupera o glifo associado ao controle de botão de divisão atual.

TCHAR GetSplitGlyph() const;

Valor de retorno

O caractere de glifo associado ao controle de botão de divisão atual.

Comentários

Um glifo é a representação física de um caractere em uma fonte específica. Por exemplo, um controle de botão de divisão pode ser decorado com o glifo do caractere de marca de seleção Unicode (U+2713).

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Esse método inicializa o membro mask de uma estrutura BUTTON_SPLITINFO com o sinalizador BCSIF_GLYPH e envia essa estrutura na mensagem BCM_GETSPLITINFO descrita no SDK do Windows. Quando a função de mensagem retorna, esse método recupera o glifo do membro himlGlyph da estrutura.

CButton::GetSplitImageList

Recupera a lista de imagens para o controle de botão de divisão atual.

CImageList* GetSplitImageList() const;

Valor de retorno

Um ponteiro para um objeto CImageList.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Esse método inicializa o membro mask de uma estrutura BUTTON_SPLITINFO com o sinalizador BCSIF_IMAGE e envia essa estrutura na mensagem BCM_GETSPLITINFO descrita no SDK do Windows. Quando a função de mensagem retorna, esse método recupera a lista de imagens do membro himlGlyph da estrutura.

CButton::GetSplitInfo

Recupera parâmetros que determinam como o Windows desenha o controle de botão de divisão atual.

BOOL GetSplitInfo(PBUTTON_SPLITINFO pInfo) const;

Parâmetros

pInfo
[out] Ponteiro para uma estrutura BUTTON_SPLITINFO que recebe informações sobre o controle de botão de divisão atual. O chamador é responsável por alocar a estrutura .

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Esse método envia a mensagem BCM_GETSPLITINFO, que é descrita no SDK do Windows.

CButton::GetSplitSize

Recupera o retângulo delimitador do componente suspenso do controle de botão de divisão atual.

BOOL GetSplitSize(LPSIZE pSize) const;

Parâmetros

pSize
[out] Ponteiro para uma estrutura SIZE que recebe a descrição de um retângulo.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Quando o controle de botão de divisão é expandido, ele pode exibir um componente suspenso, como um controle de lista ou controle de paginação. Esse método recupera o retângulo delimitador que contém o componente suspenso.

Esse método inicializa o membro mask de uma estrutura BUTTON_SPLITINFO com o sinalizador BCSIF_SIZE e envia essa estrutura na mensagem BCM_GETSPLITINFO descrita no SDK do Windows. Quando a função de mensagem retorna, esse método recupera o retângulo delimitador do membro size da estrutura.

CButton::GetSplitStyle

Recupera os estilos de botão de divisão que definem o controle de botão de divisão atual.

UINT GetSplitStyle() const;

Valor de retorno

Uma combinação bit a bit de estilos de botão de divisão. Para mais informações, confira o membro uSplitStyle da estrutura BUTTON_SPLITINFO.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Os estilos de botão de divisão especificam o alinhamento, a taxa de proporção e o formato gráfico com o qual o Windows desenha um ícone de botão de divisão.

Esse método inicializa o membro mask de uma estrutura BUTTON_SPLITINFO com o sinalizador BCSIF_STYLE e envia essa estrutura na mensagem BCM_GETSPLITINFO descrita no SDK do Windows. Quando a função de mensagem retorna, esse método recupera os estilos de botão de divisão do membro uSplitStyle da estrutura.

CButton::GetState

Recupera o estado de um controle de botão.

UINT GetState() const;

Valor de retorno

Um campo de bits que contém a combinação de valores que indicam o estado atual de um controle de botão. A seguinte tabela lista os possíveis valores.

Estado do botão	Valor	Descrição
BST_UNCHECKED	0x0000	O estado inicial.
BST_CHECKED	0x0001	O controle de botão está marcado.
BST_INDETERMINATE	0x0002	O estado é indeterminado (só é possível quando o controle de botão tem três estados).
BST_PUSHED	0x0004	O controle de botão é pressionado.
BST_FOCUS	0x0008	O controle de botão tem o foco.

Comentários

Um controle de botão com o estilo do botão BS_3STATE ou BS_AUTO3STATE cria uma caixa de seleção que tem um terceiro estado chamado de estado indeterminado. O estado indeterminado indica que a caixa de seleção não está marcada nem desmarcada.

Exemplo

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

Chame esse método para obter a margem de texto do objeto CButton.

BOOL GetTextMargin(RECT* pmargin);

Parâmetros

pmargin
Um ponteiro para a margem de texto do objeto CButton.

Valor de retorno

Retorna a margem de texto. Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Essa função membro emula a funcionalidade da mensagem BCM_GETTEXTMARGIN, conforme descrito na seção Botões do SDK do Windows.

CButton::SetBitmap

Chame essa função de membro para associar um novo bitmap ao botão.

HBITMAP SetBitmap(HBITMAP hBitmap);

Parâmetros

hBitmap
O identificador de um bitmap.

Valor de retorno

O identificador de um bitmap anteriormente associado ao botão.

Comentários

O bitmap será colocado automaticamente na face do botão, centralizado por padrão. Se o bitmap for muito grande para o botão, ele será recortado em ambos os lados. Você pode escolher outras opções de alinhamento, incluindo as seguintes:

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

Ao contrário de CBitmapButton, que usa quatro bitmaps por botão, SetBitmap usa apenas um bitmap por botão. Quando o botão é pressionado, o bitmap parece se deslocar para baixo e para a direita.

Você é responsável por liberar o bitmap quando terminar de usá-lo.

Exemplo

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

Altera o estilo de um botão.

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

Parâmetros

nEstilo
Especifica o estilo do botão.

bRedraw
Especifica se o botão deve ser redesenhado. Um valor não zero redesenha o botão. Um valor de 0 não redesenha o botão. O botão é redesenhado por padrão.

Comentários

Use a função de membro GetButtonStyle para recuperar o estilo do botão. A palavra de ordem baixa do estilo de botão completo é o estilo específico do botão.

Exemplo

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

Define ou redefine o estado de seleção de um botão de opção ou caixa de seleção.

void SetCheck(int nCheck);

Parâmetros

nCheck
Especifica o estado de seleção. Esse parâmetro pode ser um dos seguintes:

Valor	Significado
BST_UNCHECKED	Defina o estado do botão como desmarcado.
BST_CHECKED	Defina o estado do botão como marcado.
BST_INDETERMINATE	Defina o estado do botão como indeterminado. Esse valor só poderá ser usado se o botão tiver o estilo BS_3STATE ou BS_AUTO3STATE.

Comentários

Essa função de membro não tem nenhum efeito sobre um botão de pressionar.

Exemplo

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

Chame essa função de membro para associar um novo cursor ao botão.

HCURSOR SetCursor(HCURSOR hCursor);

Parâmetros

hCursor
O identificador de um cursor.

Valor de retorno

O identificador de um cursor anteriormente associado ao botão.

Comentários

O cursor será colocado automaticamente na face do botão, centralizado por padrão. Se o cursor for muito grande para o botão, ele será recortado em ambos os lados. Você pode escolher outras opções de alinhamento, incluindo as seguintes:

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

Ao contrário de CBitmapButton, que usa quatro bitmaps por botão, SetCursor usa apenas um cursor por botão. Quando o botão é pressionado, o cursor parece se deslocar para baixo e para a direita.

Exemplo

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

Define o estado suspenso do controle de botão de divisão atual.

BOOL SetDropDownState(BOOL fDropDown);

Parâmetros

fDropDown
[in] TRUE para definir BST_DROPDOWNPUSHED estado; caso contrário, FALSE.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Um controle de botão de divisão tem um estilo BS_SPLITBUTTON ou BS_DEFSPLITBUTTON e consiste em um botão e uma seta suspensa para a direita. Para obter mais informações, consulte Estilos de botão. Normalmente, o estado suspenso é definido quando o usuário clica na seta suspensa. Use esse método para definir programaticamente o estado suspenso do controle. A seta suspensa é desenhada sombreada para indicar o estado.

Esse método envia a mensagem BCM_SETDROPDOWNSTATE, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_splitButton, que é usada para acessar programaticamente o controle de botão de divisão. Essa variável é usada no exemplo a seguir.

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

O exemplo de código a seguir define o estado do controle de botão de divisão para indicar que a seta suspensa é enviada por push.

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

Define o estado do controle de botão atual como elevation required, o que é necessário para que o controle exiba um ícone de segurança com privilégios elevados.

BOOL SetElevationRequired(BOOL fElevationRequired);

Parâmetros

fElevationRequired
[in] TRUE para definir o estado elevation required; caso contrário, FALSE.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Se um botão ou controle de link de comando exigir permissão de segurança elevada para executar uma ação, defina o estado elevation required para o controle. Posteriormente, o Windows exibe o ícone de escudo UAC (Controle de Conta de Usuário) no controle. Para obter mais informações, consulte Controle de Conta de Usuário.

Esse método envia a mensagem BCM_SETSHIELD, que é descrita no SDK do Windows.

CButton::SetIcon

Chame essa função de membro para associar um novo ícone ao botão.

HICON SetIcon(HICON hIcon);

Parâmetros

hIcon
O identificador de um ícone.

Valor de retorno

O identificador de um ícone anteriormente associado ao botão.

Comentários

O ícone será colocado automaticamente na face do botão, centralizado por padrão. Se o ícone for muito grande para o botão, ele será recortado em ambos os lados. Você pode escolher outras opções de alinhamento, incluindo as seguintes:

BS_TOP
BS_LEFT
BS_RIGHT
BS_CENTER
BS_BOTTOM
BS_VCENTER

Ao contrário de CBitmapButton, que usa quatro bitmaps por botão, SetIcon usa apenas um ícone por botão. Quando o botão é pressionado, o ícone parece se deslocar para baixo e para a direita.

Exemplo

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

Chame esse método para definir a lista de imagens do objeto CButton.

BOOL SetImageList(PBUTTON_IMAGELIST pbuttonImagelist);

Parâmetros

pbuttonImagelist
Um ponteiro para a nova lista de imagens.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Essa função de membro emula a funcionalidade da mensagem BCM_SETIMAGELIST, conforme descrito na seção Botões do SDK do Windows.

CButton::SetNote

Define o texto da anotação no controle de link de comando atual.

BOOL SetNote(LPCTSTR lpszNote);

Parâmetros

lpszNote
[in] Ponteiro para uma cadeia de caracteres Unicode definida como o texto de anotação para o controle de link de comando.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_COMMANDLINK ou BS_DEFCOMMANDLINK.

Esse método envia a mensagem BCM_SETNOTE, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_cmdLink, que é usada para acessar programaticamente o controle de link de comando. Essa variável é usada no exemplo a seguir.

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

O próximo exemplo de código define o texto da anotação para o controle de link de comando.

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

CButton::SetSplitGlyph

Associa um glifo especificado ao controle de botão de divisão atual.

BOOL SetSplitGlyph(TCHAR chGlyph);

Parâmetros

chGlyph
[in] Um caractere que especifica o glifo a ser usado como a seta suspensa do botão de divisão.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles que têm o estilo de botão BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Um glifo é a representação física de um caractere em uma fonte específica. O parâmetro chGlyph não é usado como glifo, mas é usado para selecionar um glifo de um conjunto de glifos definidos pelo sistema. O glifo de seta suspensa padrão é especificado por um caractere '6' e se assemelha ao caractere Unicode BLACK DOWN-POINTING TRIANGLE (U+25BC).

Esse método inicializa o membro mask de uma estrutura BUTTON_SPLITINFO com o sinalizador BCSIF_GLYPH e o himlGlyph membro com o parâmetro chGlyph e envia essa estrutura na mensagem BCM_GETSPLITINFO descrita no SDK do Windows.

CButton::SetSplitImageList

Associa uma lista de imagens ao controle de botão de divisão atual.

BOOL SetSplitImageList(CImageList* pSplitImageList);

Parâmetros

pSplitImageList
[in] Ponteiro para um objeto CImageList a ser atribuído ao controle de botão de divisão atual.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Esse método inicializa o membro mask de uma estrutura BUTTON_SPLITINFO com o sinalizador BCSIF_IMAGE e o membro himlGlyph com o parâmetro pSplitImageList, então envia essa estrutura na mensagem BCM_GETSPLITINFO descrita no SDK do Windows.

CButton::SetSplitInfo

Especifica parâmetros que determinam como o Windows desenha o controle de botão de divisão atual.

BOOL SetSplitInfo(PBUTTON_SPLITINFO pInfo);

Parâmetros

pInfo
[in] Ponteiro para uma estrutura BUTTON_SPLITINFO que define o controle de botão de divisão atual.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Esse método envia a mensagem BCM_SETSPLITINFO, que é descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_splitButton, que é usada para acessar programaticamente o controle de botão de divisão.

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

O próximo exemplo de código altera o glifo usado para a seta suspensa do botão de divisão. O exemplo substitui um glifo de triângulo apontando para cima para o glifo de triângulo apontando para baixo padrão. O glifo exibido depende do caractere especificado no membro himlGlyph da estrutura BUTTON_SPLITINFO. O glifo de triângulo apontando para baixo é especificado por um caractere '6' e o glifo triângulo apontando para cima é especificado por um caractere '5'. Para comparação, confira o método de conveniência, 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

Define o retângulo delimitador do componente suspenso do controle de botão de divisão atual.

BOOL SetSplitSize(LPSIZE pSize);

Parâmetros

pSize
[in] Ponteiro para uma estrutura SIZE que descreve um retângulo delimitador.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Quando o controle de botão de divisão é expandido, ele pode exibir um componente suspenso, como um controle de lista ou controle de paginação. Esse método especifica o tamanho do retângulo delimitador que contém o componente suspenso.

Esse método inicializa o membro mask de uma estrutura BUTTON_SPLITINFO com o sinalizador BCSIF_SIZE e o membro size com o parâmetro pSize, então envia essa estrutura na mensagem BCM_GETSPLITINFO descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_splitButton, que é usada para acessar programaticamente o controle de botão de divisão. Essa variável é usada no exemplo a seguir.

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

O próximo exemplo de código dobra o tamanho da seta suspensa do botão de divisão.

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

Define o estilo do controle de botão de divisão atual.

BOOL SetSplitStyle(UINT uSplitStyle);

Parâmetros

uSplitStyle
[in] Uma combinação bit a bit de estilos de botão de divisão. Para mais informações, confira o membro uSplitStyle da estrutura BUTTON_SPLITINFO.

Valor de retorno

TRUE se o método for bem-sucedido; caso contrário, FALSE.

Comentários

Use esse método somente com controles cujo estilo de botão é BS_SPLITBUTTON ou BS_DEFSPLITBUTTON.

Os estilos de botão de divisão especificam o alinhamento, a taxa de proporção e o formato gráfico com o qual o Windows desenha um ícone de botão de divisão. Para mais informações, confira o membro uSplitStyle da estrutura BUTTON_SPLITINFO.

Esse método inicializa o membro mask de uma estrutura BUTTON_SPLITINFO com o sinalizador BCSIF_STYLE e o uSplitStyle membro com o parâmetro uSplitStyle e envia essa estrutura na mensagem BCM_GETSPLITINFO descrita no SDK do Windows.

Exemplo

O primeiro exemplo de código define a variável, m_splitButton, que é usada para acessar programaticamente o controle de botão de divisão.

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

O próximo exemplo de código define o estilo da seta suspensa do botão de divisão. O estilo BCSS_ALIGNLEFT exibe a seta no lado esquerdo do botão e o estilo BCSS_STRETCH mantém as proporções da seta suspensa quando você redimensiona o botão.

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

Define se um controle de botão está realçado ou não.

void SetState(BOOL bHighlight);

Parâmetros

bHighlight
Especifica se o botão deve ser realçado. Um valor não zero realça o botão; um valor 0 remove qualquer realce.

Comentários

Realçar afeta o exterior de um controle de botão. Ele não tem nenhum efeito no estado de verificação de um botão de opção ou caixa de seleção.

Um controle de botão é realçado automaticamente quando o usuário clica e segura o botão esquerdo do mouse. O realce é removido quando o usuário libera o botão do mouse.

Exemplo

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

Chame esse método para definir a margem de texto do objeto CButton.

BOOL SetTextMargin(RECT* pmargin);

Parâmetros

pmargin
Um ponteiro para a nova margem de texto.

Valor de retorno

Retorna TRUE em caso de êxito. FALSE, em caso de falha.

Comentários

Essa função membro emula a funcionalidade da mensagem BCM_SETTEXTMARGIN, conforme descrito na seção Botões do SDK do Windows.

Confira também

Classe CWnd
Gráfico da hierarquia
Classe CWnd
Classe CComboBox
Classe CEdit
Classe CListBox
Classe CScrollBar
Classe CStatic
Classe CBitmapButton
Classe CDialog

Partilhar via

Classe CButton

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CButton::CButton

Exemplo

CButton::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CButton::DrawItem

Parâmetros

Comentários

Exemplo

CButton::GetBitmap

Valor de retorno

Exemplo

CButton::GetButtonStyle

Valor de retorno

Exemplo

CButton::GetCheck

Valor de retorno

Exemplo

CButton::GetCursor

Valor de retorno

Exemplo

CButton::GetIcon

Valor de retorno

Exemplo

CButton::GetIdealSize

Parâmetros

Valor de retorno

Comentários

CButton::GetImageList

Parâmetros

Valor de retorno

Comentários

CButton::GetNote

Parâmetros

Valor de retorno

Comentários

CButton::GetNoteLength

Valor de retorno

Comentários

CButton::GetSplitGlyph

Valor de retorno

Comentários

CButton::GetSplitImageList

Valor de retorno

Comentários

CButton::GetSplitInfo

Parâmetros

Valor de retorno

Comentários

CButton::GetSplitSize

Parâmetros

Valor de retorno

Comentários

CButton::GetSplitStyle

Valor de retorno

Comentários

CButton::GetState

Valor de retorno

Comentários

Exemplo

CButton::GetTextMargin

Parâmetros

Valor de retorno

Comentários

CButton::SetBitmap

Parâmetros

Valor de retorno

Comentários

Exemplo