nRow, nColNuméricoObrigatório
Linha e coluna em que o componente será posicionado. Com PIXEL, as coordenadas partem do canto superior esquerdo do componente pai.
COMANDOPublicado
@ ... CHECKBOX
@ <nRow>, <nCol> CHECKBOX [<oCheckBox> VAR] <lVar> [PROMPT <cCaption>] [OF <oWnd>] [SIZE <nWidth>, <nHeight>] [PIXEL]Cria uma caixa de seleção ligada a uma variável lógica e, opcionalmente, disponibiliza seu objeto TCheckBox.
Visão geral
O comando @ ... CHECKBOX permite editar visualmente um valor lógico: marcado representa verdadeiro (.T.) e desmarcado representa falso (.F.). Durante a compilação, o comando é convertido no construtor New() da classe TCheckBox. A cláusula VAR é usada quando o objeto precisa ser armazenado para configuração ou manipulação posterior.
Sintaxe
@ <nRow>, <nCol> CHECKBOX [<oCheckBox> VAR] <lVar> [PROMPT <cCaption>] [OF <oWnd>] [SIZE <nWidth>, <nHeight>] [PIXEL]Parâmetros
oCheckBox VARObjetoOpcional
Variável que receberá o objeto TCheckBox. Ao informar o objeto, a cláusula VAR é obrigatória antes da variável lógica.
lVarLógicoObrigatório
Variável lógica editada pelo componente: .T. quando marcado e .F. quando desmarcado.
PROMPT cCaptionCaractereOpcional
Texto apresentado ao lado da caixa de seleção.
OF oWndObjetoOpcional
Diálogo, painel, folder ou outro contêiner visual proprietário do componente. OF é a forma recomendada.
SIZE nWidth, nHeightNuméricoOpcional
Largura e altura reservadas para o componente.
ON CHANGE / ON CLICKEventoOpcional
Ação executada quando o usuário altera o estado da caixa.
VALIDValidaçãoOpcional
Expressão lógica executada na perda do foco; deve retornar .T. para permitir a saída.
WHENHabilitaçãoOpcional
Expressão lógica que determina se o componente pode receber foco.
FONT · COLOR · MESSAGE · PIXELCláusulasOpcional
Personalizam fonte, cores, dica contextual e sistema de coordenadas.
Caixa de seleção simples
#Include "TOTVS.ch"
User Function ExCheckBox()
Local oDlg
Local oCheckBox
Local lAtivo := .F.
Define Dialog oDlg Title "Preferências" ;
From 100, 100 To 300, 440 Pixel
@ 15, 20 CheckBox oCheckBox Var lAtivo ;
Prompt "Cadastro ativo" Size 100, 15 ;
Of oDlg Pixel
@ 50, 20 Button "Confirmar" Size 55, 14 ;
Action MsgInfo(IIf(lAtivo, "Ativo", "Inativo")) ;
Of oDlg Pixel
Activate Dialog oDlg Centered
ReturnResultado esperado
A variável lAtivo começa falsa, é atualizada pelo controle e consultada quando o usuário confirma.
Reação à alteração do estado
#Include "TOTVS.ch"
User Function ExCheckEvento()
Local oDlg
Local lEnviarEmail := .T.
Define Dialog oDlg Title "Notificações" ;
From 0, 0 To 160, 360 Pixel
@ 20, 20 CheckBox lEnviarEmail ;
Prompt "Enviar confirmação por e-mail" ;
On Change AtualizarPreferencia(lEnviarEmail) ;
Size 150, 15 Of oDlg Pixel
Activate Dialog oDlg Centered
Return
Static Function AtualizarPreferencia(lEnviarEmail)
ConOut("Enviar e-mail: " + IIf(lEnviarEmail, "Sim", "Não"))
ReturnResultado esperado
ON CHANGE encaminha o novo valor lógico para uma função curta e específica.
- Inclua TOTVS.ch para disponibilizar o comando ao compilador.
- Inicialize a variável lógica antes de criar o componente para definir seu estado inicial.
- Use oCheckBox VAR somente quando precisar acessar propriedades ou métodos do objeto depois da criação.
- Use ON CHANGE para reagir imediatamente à marcação ou desmarcação.
- Use VALID para decidir se o foco pode sair e WHEN para decidir se o controle pode receber foco.
- Prefira OF para explicitar o contêiner proprietário do componente.
- A variável editada deve ser lógica; usar outro tipo pode causar comportamento incorreto ou erro.
- Quando o objeto é informado, esquecer VAR torna a declaração inválida.
- VALID e WHEN precisam retornar valores lógicos.
- Sem OF, o componente será associado à janela ou ao diálogo ativo no momento.
- Misturar coordenadas PIXEL com outra unidade pode posicionar ou dimensionar o controle incorretamente.
- Não concentre regras de negócio extensas no evento; encaminhe o processamento para uma função dedicada.