Skip to main content
Version: 20 R5

Check Box

A check box is a type of button used to enter or display binary (true-false) data. Basically, it is either checked or unchecked, but a third state can be defined.

Check boxes are controlled by methods or standard actions. The method associated with it executes when the check box is selected. Like all buttons, a check box variable is set to 0 when the form is first opened.

A check box displays text next to a small square. This text is set in the Title property of the check box. You can enter a title in the form of an XLIFF reference in this area (see Appendix B: XLIFF architecture).

Using check boxes

A check box can be associated to a variable or expression of type integer or boolean.

  • integer: if the box is checked, the variable has the value 1. When not checked, it has the value 0. If check box is in third state (see below), it has the value 2.
  • boolean: if the box is checked, the variable has the value True. When not checked, it has the value False.

Any or all check boxes in a form can be checked or unchecked. Multiple check boxes allow the user to select multiple options.

Three-States check box

Check box objects with Regular and Flat button style accept a third state. This third state is an intermediate status, which is generally used for display purposes. For example, it allows indicating that a property is present in a selection of objects, but not in each object of the selection.

To enable this third state, you must select the Three-States property.

This property is only available for regular and flat check boxes associated with numeric variables or expressions — check boxes for Boolean expressions cannot use the Three-States property (a Boolean expression cannot be in an intermediary state).

The variable associated with the check box returns the value 2 when the check box is in the third state.

In entry mode, the Three-States check boxes display each state sequentially, in the following order: unchecked / checked / intermediary / unchecked, etc. The intermediary state is generally not very useful in entry mode; in the code, simply force the value of the variable to 0 when it takes the value of 2 in order to pass directly from the checked state to the unchecked state.

Using a standard action

You can assign a standard action to a check box to handle attributes of text areas. For example, if you assign the fontBold standard action, at runtime the check box will manage the "bold" attribute of the selected text in the current area.

Only actions that can represent a true/false status ("checkable" actions) are supported by this object:

Supported actionsUsage condition (if any)
avoidPageBreakInsideEnabled4D Write Pro areas only
fontItalic
fontBold
fontLinethrough
fontSubscript4D Write Pro areas only
fontSuperscript4D Write Pro areas only
fontUnderline
font/showDialogMac only
htmlWYSIWIGEnabled4D Write Pro areas only
section/differentFirstPage4D Write Pro areas only
section/differentLeftRightPages4D Write Pro areas only
spell/autoCorrectionEnabled
spell/autoDashSubstitutionsEnabledMac only
spell/autoLanguageEnabledMac only
spell/autoQuoteSubstitutionsEnabledMac only
spell/autoSubstitutionsEnabled
spell/enabled
spell/grammarEnabledMac only
spell/showDialogMac only
spell/visibleSubstitutions
visibleBackground4D Write Pro areas only
visibleFooters4D Write Pro areas only
visibleHeaders4D Write Pro areas only
visibleHiddenChars4D Write Pro areas only
visibleHorizontalRuler4D Write Pro areas only
visiblePageFrames4D Write Pro areas only
visibleReferences
widowAndOrphanControlEnabled4D Write Pro areas only

For detailed information on these actions, please refer to the Standard actions section.

Check box button styles

Check boxes use button styles to control a check box's general appearance as well as its available properties. It is possible to apply different predefined styles to check boxes. A great number of variations can be obtained by combining these properties / behaviors.

With the exception of the available properties, many check box objects are structurally identical. The difference is in the processing of their associated variables.

4D provides check boxes in the following predefined button styles:

Regular

The Regular check box button style is a standard system check box (i.e., a rectangle with a descriptive title):

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"regular",
"text": "Cancel",
"action": "Cancel",
"left": 60,
"top": 160,
"width": 100,
"height": 20
"dataSourceTypeHint":"boolean"
}

Flat

The Flat check box button style is a minimalist appearance. The Flat style's graphic nature is particularly useful for forms that will be printed.

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"flat",
"text": "Cancel",
"action": "cancel",
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

Toolbar Button

The Toolbar Button check box button style is primarily intended for integration in a toolbar.

The Toolbar Button check box button style has a transparent background with a title. It is usually associated with a 4-state picture.

Example with states unchecked / checked / highlighted:

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"toolbar",
"text": "Checkbox",
"icon": "/RESOURCES/File.png",
"iconFrames": 4
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

Bevel

The Bevel check box button style combines the appearance of the Regular button style (i.e., a rectangle with a descriptive title) with the Toolbar Button button style's behavior.

The Bevel button style has a light gray background with a title. It is usually associated with a 4-state picture.

Example with states unchecked / checked / highlighted:

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"bevel",
"text": "Checkbox",
"icon": "/RESOURCES/File.png",
"iconFrames": 4
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

Rounded Bevel

The Rounded Bevel check box button style is nearly identical to the Bevel button style except, depending on the OS, the corners of the button may be rounded. As with the Bevel button style, the Rounded Bevel button style combines the appearance of the Regular button style with the Toolbar Button button style's behavior.

The Rounded Bevel button style has a light gray background with a title. It is usually associated with a 4-state picture.

Example on macOS:

On Windows, the Rounded Bevel button style is identical to the Bevel button style.

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"roundedBevel",
"text": "Checkbox",
"icon": "/RESOURCES/File.png",
"iconFrames": 4
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

OS X Gradient

The OS X Gradient check box button style is nearly identical to the Bevel button style. As with the Bevel button style, the OS X Gradient button style combines the appearance of the Regular button style with the Toolbar Button button style's behavior.

The OS X Gradient button style has a light gray background with a title and may be displayed as a two-tone system button on macOS. It is usually associated with a 4-state picture.

On Windows, this check box button style is identical to the Bevel button style.

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"gradientBevel",
"text": "Checkbox",
"icon": "/RESOURCES/File.png",
"iconFrames": 4
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

OS X Textured

The OS X Textured button style is similar to the Bevel button style but with a smaller size (maximum size is the size of a standard macOS system button). As with the Bevel button style, the OS X Textured button style combines the appearance of the Regular button style with the Toolbar Button button style's behavior.

By default, the OS X Textured button style appears as:

  • Windows - a standard system button with a light blue background with a title in the center.

  • macOS - a standard system button. Its height is predefined: it is not possible to enlarge or reduce it.

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"texturedBevel",
"text": "Checkbox",
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

Office XP

The Office XP button style combines the appearance of the Regular button style with the Toolbar Button button style's behavior.

The colors (highlight and background) of a check box with the Office XP button style are based on the system colors. The appearance of the check box can be different when the cursor hovers over it, depending on the OS:

  • Windows - its background only appears when the mouse rolls over it. Example with states unchecked / checked / highlighted:

  • macOS - its background is always displayed. Example with states unchecked / checked:

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"office",
"text": "Checkbox",
"action": "fontBold",
"icon": "/RESOURCES/File.png",
"iconFrames": 4
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

Collapse/Expand

This check box button style can be used to add a standard collapse/expand icon. These icons are used natively in hierarchical lists.

  • Windows - the icon looks like a [+] or a [-]

  • macOS - it looks like a triangle pointing right or down.

info

The Collapse/Expand style is named "disclosure" in the button style JSON Grammar.

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"disclosure",
"method": "m_collapse",
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

Disclosure

In macOS and Windows, a check box with the "Disclosure" button style appears as a standard disclosure button, usually used to show/hide additional information. When used as a radio button, the button symbol points downwards with value 0 and upwards with value 1.

  • Windows

  • macOS

info

The Disclosure style is named "roundedDisclosure" in the button style JSON Grammar.

JSON Example:

	"myCheckBox": {
"type": "checkbox",
"style":"roundedDisclosure",
"method": "m_disclose",
"left": 60,
"top": 160,
"width": 100,
"height": 20
}

Custom

The Custom button style accepts a personalized background picture and allows managing specific properties:

It is usually associated with a 4-state picture, that can be used in conjunction with a 4-state background picture.

JSON Example:

	"myCheckbox": {
"type": "checkbox",
"style":"custom",
"text": "OK",
"icon": "/RESOURCES/smiley.jpg",
"iconFrame": 4,
"customBackgroundPicture": "/RESOURCES/paper.jpg",
"iconOffset": 5, //custom icon offset when clicked
"left": 60,
"top": 160,
"width": 100,
"height": 20,
"customBorderX": 20,
"customBorderY": 5
}

Supported Properties

All check boxes share the same set of basic properties:

Bold - Bottom - Button Style - Class - Enterable - Expression Type - Focusable - Font - Font Color - Font Size - Height - Help Tip - Horizontal Alignment(1) - Horizontal Sizing - Image hugs title(2) - Italic - Left - Number of States(2) - Object Name - Picture pathname(2) - Right - Save value - Shortcut - Standard action - Title - Title/Picture Position(2) - Top - Type - Underline - Variable or Expression - Vertical Sizing - Visibility - Width

(1) Not supported by the Regular and Flat styles.
(2) Not supported by the Regular, Flat, Disclosure and Collapse/Expand styles.

Additional specific properties are available, depending on the button style: