# CheckBoxField

## Content

# Class: CheckBoxField

Represents CheckBox AcroForm field.

## Extends

- [`Field`](Field)

## Constructors

### Constructor

```ts
new CheckBoxField(om): CheckBoxField;
```

Creates a new CheckBoxField.

#### Parameters

##### om

[`ObjectManager`](ObjectManager)

[ObjectManager](ObjectManager) that controls the lifetime of the CheckBoxField.

#### Returns

`CheckBoxField`

#### Overrides

```ts
Field.constructor
```

### Constructor

```ts
new CheckBoxField(): CheckBoxField;
```

Creates a new CheckBoxField.

#### Returns

`CheckBoxField`

#### Overrides

```ts
Field.constructor
```

## Accessors

### alternateName

#### Get Signature

```ts
get alternateName(): string;
```

Gets or sets an alternate field name to be used in place of the actual field name wherever
the field must be identified in the user interface (such as in error or status messages referring to the field).
This text is also useful when extracting the document's contents in support of accessibility
to users with disabilities or for other purposes.

##### Returns

`string`

#### Set Signature

```ts
set alternateName(value): void;
```

Gets or sets an alternate field name to be used in place of the actual field name wherever
the field must be identified in the user interface (such as in error or status messages referring to the field).
This text is also useful when extracting the document's contents in support of accessibility
to users with disabilities or for other purposes.

##### Parameters

###### value

`string`

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`alternateName`](Field#alternatename)

***

### calculationIndex

#### Get Signature

```ts
get calculationIndex(): number;
```

Gets or sets an index that is used to determine the field's calculation order.
Fields with lower indices are calculated before fields with higher indices.

If several fields have the same CalculationIndex, the calculation order is determined
by the order of fields in the collection.

[recalculateValue](Field#recalculatevalue) can be used to specify JavaScript that is used to calculate the field's value.

##### Returns

`number`

#### Set Signature

```ts
set calculationIndex(value): void;
```

Gets or sets an index that is used to determine the field's calculation order.
Fields with lower indices are calculated before fields with higher indices.

If several fields have the same CalculationIndex, the calculation order is determined
by the order of fields in the collection.

[recalculateValue](Field#recalculatevalue) can be used to specify JavaScript that is used to calculate the field's value.

##### Parameters

###### value

`number`

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`calculationIndex`](Field#calculationindex)

***

### checked

#### Get Signature

```ts
get checked(): boolean;
```

Gets or sets the value of this CheckBoxField as a Boolean value.
See [CheckBoxField#value](#value) for details.

##### See

 - [defaultChecked](#defaultchecked)
 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)

##### Returns

`boolean`

#### Set Signature

```ts
set checked(value): void;
```

Gets or sets the value of this CheckBoxField as a Boolean value.
See [CheckBoxField#value](#value) for details.

##### See

 - [defaultChecked](#defaultchecked)
 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### checkStyle

#### Get Signature

```ts
get checkStyle(): CheckStyle;
```

Gets or sets the style of check mark that is used by this CheckBoxField.
This property wraps the [WidgetAnnotation#checkStyle](WidgetAnnotation#checkstyle) property
and functions identically to:
this.widget.checkStyle = value;

Note that a field may have multiple associated annotations across different pages.
These can be added and configured using the [@widgets](Field) property.

##### See

[WidgetAnnotation#checkStyle](WidgetAnnotation#checkstyle)

##### Returns

[`CheckStyle`](../enumerations/CheckStyle)

#### Set Signature

```ts
set checkStyle(value): void;
```

Gets or sets the style of check mark that is used by this CheckBoxField.
This property wraps the [WidgetAnnotation#checkStyle](WidgetAnnotation#checkstyle) property
and functions identically to:
this.widget.checkStyle = value;

Note that a field may have multiple associated annotations across different pages.
These can be added and configured using the [@widgets](Field) property.

##### See

[WidgetAnnotation#checkStyle](WidgetAnnotation#checkstyle)

##### Parameters

###### value

[`CheckStyle`](../enumerations/CheckStyle)

##### Returns

`void`

***

### children

#### Get Signature

```ts
get children(): FieldCollection;
```

Gets the list of child fields.

##### Returns

[`FieldCollection`](FieldCollection)

#### Inherited from

[`Field`](Field).[`children`](Field#children)

***

### defaultChecked

#### Get Signature

```ts
get defaultChecked(): boolean;
```

Gets or sets the default value of this CheckBoxField as a Boolean value.
See [CheckBoxField#value](#value) for details.

##### See

 - [checked](#checked)
 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)

##### Returns

`boolean`

#### Set Signature

```ts
set defaultChecked(value): void;
```

Gets or sets the default value of this CheckBoxField as a Boolean value.
See [CheckBoxField#value](#value) for details.

##### See

 - [checked](#checked)
 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)

##### Parameters

###### value

`boolean`

##### Returns

`void`

***

### defaultValue

#### Get Signature

```ts
get defaultValue(): string | number | boolean | number[];
```

Gets or sets the default value of this CheckBoxField.
See [CheckBoxField#value](#value) for details.

##### See

[hasRadioButtonBehavior](#hasradiobuttonbehavior)

##### Returns

`string` \| `number` \| `boolean` \| `number`[]

#### Set Signature

```ts
set defaultValue(value): void;
```

Gets or sets the default value of this CheckBoxField.
See [CheckBoxField#value](#value) for details.

##### See

[hasRadioButtonBehavior](#hasradiobuttonbehavior)

##### Parameters

###### value

`string` \| `number` \| `boolean` \| `number`[]

##### Returns

`void`

#### Overrides

[`Field`](Field).[`defaultValue`](Field#defaultvalue)

***

### doc

#### Get Signature

```ts
get doc(): PdfDocument;
```

Gets the [PdfDocument](PdfDocument) owning this field.

##### Returns

[`PdfDocument`](PdfDocument)

#### Inherited from

[`Field`](Field).[`doc`](Field#doc)

***

### export

#### Get Signature

```ts
get export(): boolean;
```

Gets or sets a value indicating whether the field must not be exported by a [ActionSubmitForm](ActionSubmitForm) action.

##### Returns

`boolean`

#### Set Signature

```ts
set export(value): void;
```

Gets or sets a value indicating whether the field must not be exported by a [ActionSubmitForm](ActionSubmitForm) action.

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`export`](Field#export)

***

### formatValue

#### Get Signature

```ts
get formatValue(): ActionJavaScript;
```

Gets or sets a JavaScript action to be performed before the field is formatted to display its current value.
This action can modify the field's value before formatting.

##### Returns

[`ActionJavaScript`](ActionJavaScript)

#### Set Signature

```ts
set formatValue(value): void;
```

Gets or sets a JavaScript action to be performed before the field is formatted to display its current value.
This action can modify the field's value before formatting.

##### Parameters

###### value

  \| [`ActionJavaScriptProperties`](../type-aliases/ActionJavaScriptProperties)
  \| [`ActionJavaScript`](ActionJavaScript)

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`formatValue`](Field#formatvalue)

***

### hasRadioButtonBehavior

#### Get Signature

```ts
get hasRadioButtonBehavior(): boolean;
```

Checks whether this CheckBoxField actually behaves as a [RadioButtonField](RadioButtonField).
This situation takes place if the checkbox field owns more than one [WidgetAnnotation](WidgetAnnotation)s,
and the widgets' appearance streams used to show checked state have different names.

##### Returns

`boolean`

- "true" if this checkbox behaves as a radio button, "false" otherwise.

***

### id

#### Get Signature

```ts
get id(): number;
```

Gets the reference to the object.

##### Returns

`number`

#### Inherited from

[`Field`](Field).[`id`](Field#id)

***

### justification

#### Get Signature

```ts
get justification(): VariableTextJustification;
```

Gets or sets the justification to be used in displaying the field's text.
Note that this field is used only if [WidgetAnnotation#justification](WidgetAnnotation#justification) is not specified.

##### Returns

[`VariableTextJustification`](../enumerations/VariableTextJustification)

#### Set Signature

```ts
set justification(value): void;
```

Gets or sets the justification to be used in displaying the field's text.
Note that this field is used only if [WidgetAnnotation#justification](WidgetAnnotation#justification) is not specified.

##### Parameters

###### value

[`VariableTextJustification`](../enumerations/VariableTextJustification)

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`justification`](Field#justification)

***

### keyPress

#### Get Signature

```ts
get keyPress(): ActionJavaScript;
```

Gets or sets a JavaScript action to be performed when the user types a keystroke into a
text field or combo box or modifies the selection in a scrollable list box.
This action can check the keystroke for validity and reject or modify it.

##### Returns

[`ActionJavaScript`](ActionJavaScript)

#### Set Signature

```ts
set keyPress(value): void;
```

Gets or sets a JavaScript action to be performed when the user types a keystroke into a
text field or combo box or modifies the selection in a scrollable list box.
This action can check the keystroke for validity and reject or modify it.

##### Parameters

###### value

  \| [`ActionJavaScriptProperties`](../type-aliases/ActionJavaScriptProperties)
  \| [`ActionJavaScript`](ActionJavaScript)

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`keyPress`](Field#keypress)

***

### mappingName

#### Get Signature

```ts
get mappingName(): string;
```

Gets or sets the mapping name to be used when exporting interactive form field data from the document.

##### Returns

`string`

#### Set Signature

```ts
set mappingName(value): void;
```

Gets or sets the mapping name to be used when exporting interactive form field data from the document.

##### Parameters

###### value

`string`

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`mappingName`](Field#mappingname)

***

### name

#### Get Signature

```ts
get name(): string;
```

Gets or sets the field's name.

##### Returns

`string`

#### Set Signature

```ts
set name(value): void;
```

Gets or sets the field's name.

##### Parameters

###### value

`string`

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`name`](Field#name)

***

### om

#### Get Signature

```ts
get om(): ObjectManager;
```

Gets the owner [ObjectManager](ObjectManager) instance.

##### Returns

[`ObjectManager`](ObjectManager)

#### Inherited from

[`Field`](Field).[`om`](Field#om)

***

### opt

#### Get Signature

```ts
get opt(): string[];
```

Gets an array of strings containing one entry for each widget annotation,
defining export values for its constituent radio buttons.
See the PDF spec for details.

##### Returns

`string`[]

#### Set Signature

```ts
set opt(value): void;
```

Sets an array of strings containing one entry for each widget annotation,
defining export values for its constituent radio buttons.
See the PDF spec for details.

##### Parameters

###### value

`string`[]

##### Returns

`void`

***

### owner

#### Get Signature

```ts
get owner(): FieldCollection;
```

Gets the [FieldCollection](FieldCollection) containing this field.

##### Returns

[`FieldCollection`](FieldCollection)

#### Inherited from

[`Field`](Field).[`owner`](Field#owner)

***

### page

#### Get Signature

```ts
get page(): PdfPage;
```

Gets or sets the [PdfPage](PdfPage) containing this field.
This property wraps the [WidgetAnnotation#page](WidgetAnnotation#page) property
and functions identically to:
this.widget.page = value;

Note that a field may have multiple associated annotations across different pages.
These can be added and configured using the [@widgets](Field) property.

##### See

[WidgetAnnotation#page](WidgetAnnotation#page)

##### Returns

[`PdfPage`](PdfPage)

#### Set Signature

```ts
set page(value): void;
```

Gets or sets the [PdfPage](PdfPage) containing this field.
This property wraps the [WidgetAnnotation#page](WidgetAnnotation#page) property
and functions identically to:
this.widget.page = value;

Note that a field may have multiple associated annotations across different pages.
These can be added and configured using the [@widgets](Field) property.

##### See

[WidgetAnnotation#page](WidgetAnnotation#page)

##### Parameters

###### value

[`PdfPage`](PdfPage)

##### Returns

`void`

***

### parent

#### Get Signature

```ts
get parent(): Field;
```

Gets the parent field.

##### Returns

[`Field`](Field)

#### Inherited from

[`Field`](Field).[`parent`](Field#parent)

***

### readOnly

#### Get Signature

```ts
get readOnly(): boolean;
```

Gets or sets a value indicating whether the user may not change the value of the field.
Any associated widget annotations will not interact with the user; that is,
they will not respond to mouse clicks or change their appearance in response to mouse motions.
This flag is useful for fields whose values are computed or imported from a database.

##### Returns

`boolean`

#### Set Signature

```ts
set readOnly(value): void;
```

Gets or sets a value indicating whether the user may not change the value of the field.
Any associated widget annotations will not interact with the user; that is,
they will not respond to mouse clicks or change their appearance in response to mouse motions.
This flag is useful for fields whose values are computed or imported from a database.

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`readOnly`](Field#readonly)

***

### recalculateValue

#### Get Signature

```ts
get recalculateValue(): ActionJavaScript;
```

Gets or sets a JavaScript action to be performed to recalculate the value of this field when
that of another field changes.

##### Returns

[`ActionJavaScript`](ActionJavaScript)

#### Set Signature

```ts
set recalculateValue(value): void;
```

Gets or sets a JavaScript action to be performed to recalculate the value of this field when
that of another field changes.

##### Parameters

###### value

  \| [`ActionJavaScriptProperties`](../type-aliases/ActionJavaScriptProperties)
  \| [`ActionJavaScript`](ActionJavaScript)

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`recalculateValue`](Field#recalculatevalue)

***

### rect

#### Get Signature

```ts
get rect(): Rect;
```

Gets or sets the rectangle that defines the location and size of the field on a page.
This property wraps the [WidgetAnnotation#rect](WidgetAnnotation#rect) property
and functions identically to:
this.widget.rect = value;

Note that a field may have multiple associated annotations across different pages.
These can be added and configured using the [@widgets](Field) property.

##### See

[WidgetAnnotation#rect](WidgetAnnotation#rect)

##### Returns

[`Rect`](../type-aliases/Rect)

#### Set Signature

```ts
set rect(value): void;
```

Gets or sets the rectangle that defines the location and size of the field on a page.
This property wraps the [WidgetAnnotation#rect](WidgetAnnotation#rect) property
and functions identically to:
this.widget.rect = value;

Note that a field may have multiple associated annotations across different pages.
These can be added and configured using the [@widgets](Field) property.

##### See

[WidgetAnnotation#rect](WidgetAnnotation#rect)

##### Parameters

###### value

[`Rect`](../type-aliases/Rect)

##### Returns

`void`

***

### required

#### Get Signature

```ts
get required(): boolean;
```

Gets or sets a value indicating whether the field must have a value at the time it is
exported by a [ActionSubmitForm](ActionSubmitForm) action.

##### Returns

`boolean`

#### Set Signature

```ts
set required(value): void;
```

Gets or sets a value indicating whether the field must have a value at the time it is
exported by a [ActionSubmitForm](ActionSubmitForm) action.

##### Parameters

###### value

`boolean`

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`required`](Field#required)

***

### value

#### Get Signature

```ts
get value(): string | number | boolean | number[];
```

Gets or sets the object value of this checkbox field.

Gets "false" if none of the associated widgets is checked.
Otherwise gets "true" if all widgets use the same name for the checked appearance stream,
or the name of the appearance stream that is used to display the checked state.

When set, if a Boolean value is specified, it is assigned as is to the checked state.
If the assigned value is not a Boolean, it is converted to string and is interpreted
as the name of the widget's appearance stream used to show the widget's checked state.
If no such stream exists, the checkbox will show as unchecked.

##### See

 - [checked](#checked)
 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)

##### Returns

`string` \| `number` \| `boolean` \| `number`[]

#### Set Signature

```ts
set value(value): void;
```

Gets or sets the object value of this checkbox field.

Gets "false" if none of the associated widgets is checked.
Otherwise gets "true" if all widgets use the same name for the checked appearance stream,
or the name of the appearance stream that is used to display the checked state.

When set, if a Boolean value is specified, it is assigned as is to the checked state.
If the assigned value is not a Boolean, it is converted to string and is interpreted
as the name of the widget's appearance stream used to show the widget's checked state.
If no such stream exists, the checkbox will show as unchecked.

##### See

 - [checked](#checked)
 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)

##### Parameters

###### value

`string` \| `number` \| `boolean` \| `number`[]

##### Returns

`void`

#### Overrides

[`Field`](Field).[`value`](Field#value)

***

### valueChanged

#### Get Signature

```ts
get valueChanged(): ActionJavaScript;
```

Gets or sets a JavaScript action to be performed when the field's value is changed.
This action can check the new value for validity.

##### Returns

[`ActionJavaScript`](ActionJavaScript)

#### Set Signature

```ts
set valueChanged(value): void;
```

Gets or sets a JavaScript action to be performed when the field's value is changed.
This action can check the new value for validity.

##### Parameters

###### value

  \| [`ActionJavaScriptProperties`](../type-aliases/ActionJavaScriptProperties)
  \| [`ActionJavaScript`](ActionJavaScript)

##### Returns

`void`

#### Inherited from

[`Field`](Field).[`valueChanged`](Field#valuechanged)

***

### widget

#### Get Signature

```ts
get widget(): WidgetAnnotation;
```

Gets the [WidgetAnnotation](WidgetAnnotation) defining view properties of the CheckBoxField.

##### Returns

[`WidgetAnnotation`](WidgetAnnotation)

***

### widgets

#### Get Signature

```ts
get widgets(): FieldWidgetCollection;
```

Gets the list of widget annotations associated with this field.

##### Returns

[`FieldWidgetCollection`](FieldWidgetCollection)

#### Inherited from

[`Field`](Field).[`widgets`](Field#widgets)

## Methods

### free()

```ts
free(): void;
```

Detaches the object from the [ObjectManager](ObjectManager) and deallocates its memory, if possible.

#### Returns

`void`

#### Inherited from

[`Field`](Field).[`free`](Field#free)

***

### getCheckedAppearanceStreamName()

```ts
getCheckedAppearanceStreamName(widgetIndex): string;
```

Gets the name of the checked appearance stream for the widget annotation
at the specified index.

#### Parameters

##### widgetIndex

`number`

The zero-based index of the widget annotation.

#### Returns

`string`

The appearance stream name, or null if not defined.

#### See

 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)
 - [getCheckedAppearanceStreamNames](#getcheckedappearancestreamnames)
 - [setCheckedAppearanceStreamName](#setcheckedappearancestreamname)

***

### getCheckedAppearanceStreamNames()

```ts
getCheckedAppearanceStreamNames(): string[];
```

Gets the names of the checked appearance streams for all widget annotations
associated with this CheckBoxField.

Each entry corresponds to a widget annotation (in the same order as [Field#widgets](Field#widgets))
and contains the name of the appearance stream used to display the widget's checked state.

#### Returns

`string`[]

An array of appearance stream names, or null if not defined.

#### See

 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)
 - [getCheckedAppearanceStreamName](#getcheckedappearancestreamname)
 - [setCheckedAppearanceStreamNames](#setcheckedappearancestreamnames)

***

### rebind()

```ts
rebind(omTo): void;
```

Rebinds the object from the current [ObjectManager](ObjectManager) to the specified one.

#### Parameters

##### omTo

[`ObjectManager`](ObjectManager)

The new [ObjectManager](ObjectManager) for the object.

#### Returns

`void`

#### Inherited from

[`Field`](Field).[`rebind`](Field#rebind)

***

### setCheckedAppearanceStreamName()

```ts
setCheckedAppearanceStreamName(widgetIndex, value): void;
```

Sets the name of the checked appearance stream for the widget annotation
at the specified index.

#### Parameters

##### widgetIndex

`number`

The zero-based index of the widget annotation.

##### value

`string`

The appearance stream name to assign.

#### Returns

`void`

#### See

 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)
 - [setCheckedAppearanceStreamNames](#setcheckedappearancestreamnames)
 - [getCheckedAppearanceStreamName](#getcheckedappearancestreamname)

***

### setCheckedAppearanceStreamNames()

```ts
setCheckedAppearanceStreamNames(value): void;
```

Sets the names of the checked appearance streams for all widget annotations
associated with this CheckBoxField.

Each entry corresponds to a widget annotation (in the same order as [Field#widgets](Field#widgets))
and specifies the name of the appearance stream used to display the widget's checked state.

#### Parameters

##### value

`string`

The appearance stream name to assign.

#### Returns

`void`

#### See

 - [hasRadioButtonBehavior](#hasradiobuttonbehavior)
 - [getCheckedAppearanceStreamNames](#getcheckedappearancestreamnames)
 - [setCheckedAppearanceStreamName](#setcheckedappearancestreamname)