TCustomCheckBox.State

The check, unchecked, or grayed state for the control.

Declaration

Source position: stdctrls.pp line 1359

Description

State is a TCheckBoxState property which indicates whether the check box is checked, unchecked or grayed (disabled). The default value for the property is cbUnchecked. State allows the control to be set to the indeterminate (grayed) state when AllowGrayed is set to True. Otherwise, it has the same behavior as using the Checked property.

See TCheckBoxState for the available enumeration values and their meanings in the State property.

Reading the property value calls RetrieveState to get the value from the widgetset class when its handle has been allocated. Otherwise, the existing value for the member is used.

Changing the value for the property causes the Checked property in an assigned Action to be updated if the property value is not cbGrayed and the ClicksDisabled property is False. The value is applied to the Action without updating the value in the control. This prevents recursion when the value is changed in the linked action.

Otherwise, ApplyChanges is called to update the visual appearance for the control. DoClickOnChange is called to post the control message for the updated control, and to emulate the OnChange and OnClick behavior in the Delphi VCL. When ClicksDisabled is True, only the OnChange event handler is signalled. When set to False, the Click method is called to signal both the OnChange and OnClick event handlers (when assigned).

The Grayed property in Action is set to False when the new property value is cbChecked or cbUnchecked.

Version info

Modified in LCL version 3.0 to prevent recursive updates (and event notifications) when the action is changed.

See also

Example

{ This example uses a check box on a form. When the application runs, 
  the check box is initially checked. When the user clicks it,
  the check box is unchecked. Clicking it again grays the check box. }
procedure TForm1.FormCreate(Sender: TObject);
begin
  Checkbox1.AllowGrayed := True;
  Checkbox1.State := cbChecked;
end;