COMMANDPublished

@ ... CHECKBOX

@ <nRow>, <nCol> CHECKBOX [<oCheckBox> VAR] <lVar> [PROMPT <cCaption>] [OF <oWnd>] [SIZE <nWidth>, <nHeight>] [PIXEL]

Creates a checkbox bound to a logical variable and optionally exposes its TCheckBox object.

Visual interfaceCheckBoxTCheckBoxLogicalCommands

01 · OVERVIEW

Overview

The @ ... CHECKBOX command visually edits a logical value: checked represents true (.T.) and unchecked represents false (.F.). During compilation it is translated into the TCheckBox class New() constructor. Use VAR when the object must be retained for later configuration or manipulation.

02 · SYNTAX

Syntax

@ <nRow>, <nCol> CHECKBOX [<oCheckBox> VAR] <lVar> [PROMPT <cCaption>] [OF <oWnd>] [SIZE <nWidth>, <nHeight>] [PIXEL]

Parameters

nRow, nCol

NuméricoRequired

Row and column where the component is placed. With PIXEL, coordinates start at the upper-left corner of the parent.

oCheckBox VAR

ObjetoOptional

Variable receiving the TCheckBox object. When the object is supplied, VAR is required before the logical variable.

lVar

LógicoRequired

Logical variable edited by the component: .T. when checked and .F. when unchecked.

PROMPT cCaption

CaractereOptional

Text displayed beside the checkbox.

OF oWnd

ObjetoOptional

Dialog, panel, folder or other visual container that owns the component. OF is recommended.

SIZE nWidth, nHeight

NuméricoOptional

Width and height reserved for the component.

ON CHANGE / ON CLICK

EventoOptional

Action executed when the user changes the checkbox state.

VALID

ValidaçãoOptional

Logical expression run when focus is lost; it must return .T. to allow leaving.

WHEN

HabilitaçãoOptional

Logical expression determining whether the component may receive focus.

FONT · COLOR · MESSAGE · PIXEL

CláusulasOptional

Customize font, colors, contextual hint and coordinate system.

03 · PRACTICAL EXAMPLE

Simple checkbox

#Include "TOTVS.ch"

User Function ExCheckBox()
    Local oDlg
    Local oCheckBox
    Local lActive := .F.

    Define Dialog oDlg Title "Preferences" ;
        From 100, 100 To 300, 440 Pixel

    @ 15, 20 CheckBox oCheckBox Var lActive ;
        Prompt "Active record" Size 100, 15 ;
        Of oDlg Pixel

    @ 50, 20 Button "Confirm" Size 55, 14 ;
        Action MsgInfo(IIf(lActive, "Active", "Inactive")) ;
        Of oDlg Pixel

    Activate Dialog oDlg Centered
Return

Expected result

lActive starts false, is updated by the control, and is read when the user confirms.

04 · PRACTICAL EXAMPLE

Reacting to a state change

#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"))
Return

Expected result

ON CHANGE forwards the new logical value to a short, focused function.

BEST PRACTICES

Include TOTVS.ch to make the command available to the compiler.
Initialize the logical variable before creating the component to define its initial state.
Use oCheckBox VAR only when properties or methods are needed after creation.
Use ON CHANGE to react immediately to checking or unchecking.
Use VALID to control leaving the field and WHEN to control entering it.
Prefer OF to explicitly identify the owner container.

COMMON PITFALLS

The edited variable must be logical; another type may cause incorrect behavior or an error.
When an object is supplied, omitting VAR makes the declaration invalid.
VALID and WHEN must return logical values.
Without OF, the component is bound to the active window or dialog.
Mixing PIXEL coordinates with another unit may position or size the control incorrectly.
Do not place lengthy business rules in the event; delegate to a dedicated function.