Partilhar via

Classe CCheckListBox

  • Artigo

Fornece a funcionalidade de uma caixa de seleção do Windows.

Sintaxe

class CCheckListBox : public CListBox

Membros

Construtores públicos

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

Métodos públicos

Nome Descrição
CCheckListBox::Create Cria a caixa de lista de verificação do Windows e a anexa ao objeto CCheckListBox.
CCheckListBox::DrawItem Chamado pela estrutura quando um aspecto visual de uma caixa de listagem de desenho do proprietário muda.
CCheckListBox::Enable Habilita ou desabilita um item da caixa de lista de verificação.
CCheckListBox::GetCheck Define o estado da caixa de seleção de um item.
CCheckListBox::GetCheckStyle Obtém o estilo das caixas de seleção do controle.
CCheckListBox::IsEnabled Determina se um item está habilitado.
CCheckListBox::MeasureItem Chamado pela estrutura quando uma caixa de listagem com um estilo desenhado pelo proprietário é criada.
CCheckListBox::OnGetCheckPosition Chamado pela estrutura para obter a posição da caixa de seleção de um item.
CCheckListBox::SetCheck Define o estado da caixa de seleção de um item.
CCheckListBox::SetCheckStyle Define o estilo das caixas de seleção do controle.

Comentários

Uma "caixa de lista de verificação" exibe uma lista de itens, como nomes de arquivo. Cada item na lista tem uma caixa de seleção ao lado dele que o usuário pode marcar ou desmarcar.

CCheckListBox é apenas para controles desenhados pelo proprietário porque a lista contém mais do que cadeias de caracteres de texto. Em sua forma mais simples, uma caixa de lista de verificação contém cadeias de caracteres de texto e caixas de seleção, mas você não precisa ter texto. Por exemplo, você pode ter uma lista de bitmaps pequenos com uma caixa de seleção ao lado de cada item.

Para criar sua própria caixa de lista de verificação, você deve derivar sua própria classe de CCheckListBox. Para derivar sua própria classe, escreva um construtor para a classe derivada e, em seguida, chame Create.

Se você quiser lidar com mensagens de notificação do Windows enviadas por uma caixa de listagem 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 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();

Há apenas uma entrada de mapa de mensagens que pertence especificamente a CCheckListBox (mas veja também as entradas do mapa de mensagens para CListBox):

  • ON_CLBN_CHKCHANGE O usuário alterou o estado da caixa de seleção de um item.

Se a caixa de lista de verificação for uma caixa de lista de verificação padrão (uma lista de cadeias de caracteres com as caixas de seleção de tamanho padrão à esquerda de cada uma), você poderá usar o padrão CCheckListBox::DrawItem para desenhar a caixa de lista de verificação. Caso contrário, você deve substituir a função CListBox::CompareItem e as funções CCheckListBox::DrawItem e CCheckListBox::MeasureItem.

Você pode criar uma caixa de lista de verificação com base em um modelo de caixa de diálogo ou diretamente em seu código.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CListBox

CCheckListBox

Requisitos

Cabeçalho: afxwin.h

CCheckListBox::CCheckListBox

Constrói um objeto CCheckListBox.

CCheckListBox();

Comentários

Um objeto CCheckListBox é construído em duas etapas. Primeiro defina uma classe derivada de CCheckListBox, em seguida chame Create, que inicializa a caixa de lista de verificação do Windows e a anexa ao objeto CCheckListBox.

Exemplo

CCheckListBox myCheckListBox;
myCheckListBox.Create(LBS_HASSTRINGS | LBS_OWNERDRAWFIXED,
                      CRect(10, 10, 100, 100), this, IDC_MYCHECKLISTBOX);

CCheckListBox::Create

Cria a caixa de lista de verificação do Windows e a anexa ao objeto CCheckListBox.

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

Parâmetros

dwStyle
Especifica o estilo da caixa de lista de verificação. O estilo deve ser LBS_HASSTRINGS e LBS_OWNERDRAWFIXED (todos os itens na lista têm a mesma altura) ou LBS_OWNERDRAWVARIABLE (os itens na lista são de alturas variadas). Esse estilo pode ser combinado com outros estilos de caixa de listagem, exceto LBS_USETABSTOPS.

rect
Especifica o tamanho e a posição da caixa de lista de verificação. Pode ser um objeto CRect ou uma estrutura RECT.

pParentWnd
Especifica a janela pai da caixa de lista de verificação (geralmente um objeto CDialog). Não pode ser NULL.

nID
Especifica a ID de controle da caixa de lista de verificação.

Valor de retorno

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

Comentários

Um objeto CCheckListBox é construído em duas etapas. Primeiro, defina uma classe derivada de CcheckListBox. Em seguida, chame Create, que inicializa a caixa de lista de verificação do Windows e a anexa à CCheckListBox. Consulte CCheckListBox::CCheckListBox para obter um exemplo.

Quando Create é executado, o Windows envia as mensagens WM_NCCREATE, WM_CREATE, WM_NCCALCSIZE e WM_GETMINMAXINFO para o controle da caixa de lista de verificação.

Essas mensagens são tratadas por padrão pelas funções de membro OnNcCreate, OnCreate, OnNcCalcSize e OnGetMinMaxInfo na classe base CWnd. Para estender o tratamento de mensagens padrão, adicione um mapa de mensagem à classe derivada e substitua as funções membro do manipulador de mensagens anteriores. Substitua OnCreate, por exemplo, para executar a inicialização necessária para uma nova classe.

Aplique os estilos de janela a seguir a um controle de caixa de lista de verificação:

  • WS_CHILD Sempre

  • WS_VISIBLE Geralmente

  • WS_DISABLED Raramente

  • WS_VSCROLL Para adicionar uma barra de rolagem vertical

  • WS_HSCROLL Para adicionar uma barra de rolagem horizontal

  • WS_GROUP Para grupar controles

  • WS_TABSTOP Para permitir o tabbing para esse controle

CCheckListBox::DrawItem

Chamado pela estrutura quando um aspecto visual de uma caixa de lista de verificação desenhada pelo proprietário é alterado.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parâmetros

lpDrawItemStruct
Um ponteiro longo para uma estrutura DRAWITEMSTRUCT que contém informações sobre o tipo de desenho necessário.

Comentários

Os membros itemAction e itemState os membros da estrutura DRAWITEMSTRUCT definem a ação de desenho a ser executada.

Por padrão, essa função desenha uma lista de caixas de seleção padrão, consistindo em uma lista de cadeias de caracteres cada uma com uma caixa de seleção de tamanho padrão à esquerda. O tamanho da lista de caixas de seleção é o especificado em Create.

Substitua essa função membro para implementar o desenho de caixas de lista de verificação desenhadas pelo proprietário que não sejam o padrão, como caixas de lista de verificação com listas que não são cadeias de caracteres, com itens de altura variável ou com caixas de seleção que não estão à esquerda. O aplicativo deverá restaurar todos os objetos GDI (Graphics Device Interface) selecionados para o contexto de exibição fornecido em lpDrawItemStruct antes do encerramento dessa função membro.

Se os itens da caixa de lista de verificação não tiverem a mesma altura, o estilo da caixa de lista de verificação (especificado em Create) deverá ser LBS_OWNERVARIABLE e você deverá substituir a função MeasureItem.

CCheckListBox::Enable

Chame essa função para habilitar ou desabilitar um item da caixa de lista de verificação.

void Enable(
    int nIndex,
    BOOL bEnabled = TRUE);

Parâmetros

nIndex
Índice do item da caixa de lista de verificação a ser habilitado.

bEnabled
Especifica se o item está habilitado ou desabilitado.

CCheckListBox::GetCheck

Recupera o estado da caixa de seleção especificada.

int GetCheck(int nIndex);

Parâmetros

nIndex
Índice baseado em zero de uma caixa de seleção que está contida na caixa de listagem.

Valor de retorno

O estado da caixa de seleção especificada. A seguinte tabela lista os possíveis valores.

Valor Descrição
BST_CHECKED A caixa de seleção está marcada.
BST_UNCHECKED A caixa de seleção não está marcada.
BST_INDETERMINATE O estado da caixa de seleção é indeterminado.

CCheckListBox::GetCheckStyle

Chame essa função para obter o estilo da caixa de lista de verificação.

UINT GetCheckStyle();

Valor de retorno

O estilo das caixas de seleção do controle.

Comentários

Para obter informações sobre estilos possíveis, consulte SetCheckStyle.

CCheckListBox::IsEnabled

Chame essa função para determinar se um item está habilitado.

BOOL IsEnabled(int nIndex);

Parâmetros

nIndex
O índice do item.

Valor de retorno

Diferente de zero se o item estiver habilitado; caso contrário, zero.

CCheckListBox::MeasureItem

Chamado pela estrutura quando uma caixa de lista de verificação com um estilo não padrão é criada.

virtual void MeasureItem(LPMEASUREITEMSTRUCT lpMeasureItemStruct);

Parâmetros

lpMeasureItemStruct
Um ponteiro longo para uma estrutura MEASUREITEMSTRUCT.

Comentários

Por padrão, essa função membro não faz nada. Substitua essa função membro e preencha na estrutura MEASUREITEMSTRUCT para informar o Windows sobre as dimensões dos itens da caixa de lista de verificação. Se a caixa de lista de verificação for criada com o estilo LBS_OWNERDRAWVARIABLE, a estrutura chamará essa função membro para cada item na caixa de listagem. Caso contrário, esse membro será chamado apenas uma vez.

CCheckListBox::OnGetCheckPosition

A estrutura chama essa função para obter a posição e o tamanho da caixa de seleção em um item.

virtual CRect OnGetCheckPosition(
    CRect rectItem,
    CRect rectCheckBox);

Parâmetros

rectItem
A posição e o tamanho do item da lista.

rectCheckBox
A posição padrão e o tamanho da caixa de seleção de um item.

Valor de retorno

A posição e o tamanho da caixa de seleção de um item.

Comentários

A implementação padrão retorna apenas a posição e o tamanho padrão da caixa de seleção (rectCheckBox). Por padrão, uma caixa de seleção é alinhada no canto superior esquerdo de um item e é o tamanho padrão da caixa de seleção. Pode haver casos em que você deseja que as caixas de seleção estejam à direita ou quer uma caixa de seleção maior ou menor. Nesses casos, substitua OnGetCheckPosition para alterar a posição e o tamanho da caixa de seleção dentro do item.

CCheckListBox::SetCheck

Define o estado da caixa de seleção especificada.

void SetCheck(
    int nIndex,
    int nCheck);

Parâmetros

nIndex
Índice baseado em zero de uma caixa de seleção que está contida na caixa de listagem.

nCheck
O estado do botão da caixa de seleção especificada. Confira a seção Comentários para obter valores possíveis.

Comentários

A tabela a seguir lista os possíveis valores do parâmetro nCheck.

Valor Descrição
BST_CHECKED Seleciona a caixa de seleção especificada.
BST_UNCHECKED Desmarca a caixa de seleção especificada.
BST_INDETERMINATE Defina o estado da caixa de seleção especificado como indeterminado.

Esse estado só estará disponível se o estilo da caixa de seleção for BS_AUTO3STATE ou BS_3STATE. Para obter mais informações, consulte Estilos de botão.

CCheckListBox::SetCheckStyle

Chame essa função para definir o estilo das caixas de seleção na caixa de lista de verificação.

void SetCheckStyle(UINT nStyle);

Parâmetros

nStyle
Determina o estilo das caixas de seleção na caixa de lista de verificação.

Comentários

Os estilos válidos são:

  • BS_CHECKBOX

  • BS_AUTOCHECKBOX

  • BS_AUTO3STATE

  • BS_3STATE

Para obter informações sobre esses estilos, consulte Estilos de Botão.

Confira também

Exemplo de MFC TSTCON
Classe CListBox
Gráfico da hierarquia