# Class: Field

## Annotations.Forms. Field

#### new Field(name, options)

  Represents a PDF Form field.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `name` | string |  | The field's full name
  `options` | Annotations.Forms.Field | object | <nullable> | The options with which to construct the field. If options is a Field, the constructor returns the existing object.

  ##### Properties:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `actions` | object.<string, Array.<Actions.Action>> | <optional> | {} | Gets the field's actions.
  `children` | Array.<Annotations.Forms.Field> | <optional> | [] | The field's children
  `defaultValue` | number | string | <optional> <nullable> | null | The field's default value
  `exportValue` | number | string | <optional> <nullable> | null | The field's export value. Defaults to the field's value if not set.
  `flags` | Annotations.WidgetFlags | <optional> | new Annotations.WidgetFlags() | The field's flags object
  `font` | Annotations.Font | <optional> | new Annotations.Font() | Returns the field's associated font object
  `IsModified` | boolean | <optional> | false | Is field is modified?
  `maxLen` | number | <optional> | -1 | The field's maximum length. -1 means infinite.
  `name` | string |  |  | The full name of the field.
  `options` | Array.<object> | null | <optional> | [] | The field's options (or permanently null if the field type does not support options). ###### Properties
  Name | Type | Description
  --- | --- | ---
  `value` | string |
  `displayValue` | string |
  `tooltipName` | string | The text to be displayed when hovering over the field
  `quadding` | string | <optional> | 'Left-justified' | Returns the field's quadding. (One of 'Left-justified', 'Right-justified', 'Centered')
  `type` | string |  |  | Returns the field's type. One of ('Tx', 'Btn', 'Ch' or 'Sig')
  `value` | number | string | <optional> <nullable> | null | The field's value.
  `userName` | string |  |  | A short description string of the field. Displayed as tooltip text when the mouse cursor enters the field.
  `widgets` | Array.<Annotations.WidgetAnnotation> | <optional> | [] | The field's child widgets

  ##### Listens to Events:

  - Annotations.Forms.Field#event:calculate
  - Annotations.Forms.Field#event:commit

### Extends

- Actions.Dispatcher

### Methods

#### addAction(trigger, action)

  Add a single action to a trigger.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `trigger` | string | The name of the trigger to which to add the action.
  `action` | Actions.Action | object | The action to add, or an object representing the desired properties (including a name)

  Inherited From:
    - Actions.Dispatcher#addAction

#### addActions(actions)

  Add the actions to the dispatcher so they run on next trigger, constructing them if necessary

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `actions` | object | The actions to add, as an object with triggers for keys and arrays of action-describing objects for values.

  Inherited From:
    - Actions.Dispatcher#addActions

#### addActionsFromXfdf(widgetElement, pageMatrix)

  Read and instantiate actions from XFDF.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `widgetElement` | Element | The widget element to read from
  `pageMatrix` | XODText.Matrix2D | The widget's page's transormation matrix

  Inherited From:
    - Actions.Dispatcher#addActionsFromXfdf
  Deprecated:
    - Due to PDFInfo

#### commit(event, value, widget)

  Commits the new value to the field (triggers Validate action, and updates all widgets)

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `event` | * |  | Ignored.
  `value` | string | number | <nullable> | The new value.
  `widget` |  |  |

#### getActions()

  Get all the actions associated with this dispatcher.

  Inherited From:
    - Actions.Dispatcher#getActions

  ##### Returns:

  The associated actions (in the same format as addActions)

  Type
    object

#### getDocumentViewer()

  Get the associated DocumentViewer.

  Inherited From:
    - Actions.Dispatcher#getDocumentViewer

  ##### Returns:

  The associated DocumentViewer instance

  Type
    CoreControls.DocumentViewer

#### isTerminal()

  Is this a terminal field? Currently, this checks for field children.

  ##### Returns:

  Whether this field is terminal

  Type
    boolean

#### saveActionsToXfdf(widgetElement, pageMatrix, overrideElement)

  Save the actions associated with this Dispatcher to an XFDF DOM element.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `widgetElement` | Element |  | The element to which to write the actions
  `pageMatrix` | XODText.Matrix2D |  | The widget's page's transformation matrix
  `overrideElement` | Element | <nullable> | An optional other element to write to. If not provided, an OnActivation element will be added to widgetElement

  Inherited From:
    - Actions.Dispatcher#saveActionsToXfdf
  Deprecated:
    - Due to PDFInfo

#### set(options)

  Set all field properties form the given object.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `options` | Annotations.Forms.Field | object | The object to set properties from.

#### setDocumentViewer(documentViewer)

  Set the internal DocumentViewer reference, which is required for some actions to execute correctly.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `documentViewer` | CoreControls.DocumentViewer | The DocumentViewer instance

  Inherited From:
    - Actions.Dispatcher#setDocumentViewer

#### setType(type)

  Sets the field's type. Tries to retain as much type-specific information as possible across type changes.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `type` | string | The new field type, one of Tx, Ch, Btn or Sig.

#### setValue(value, widget)

  Sets the field's value, following any type-specific constraints, and updating all widgets.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `value` | string | number | <nullable> | The value to set.
  `widget` |  |  |

  ##### Fires:

  - Annotations.Forms.Field#event:change

#### setVisible(visible)

  Sets the visibility of all child widgets

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `visible` | boolean | Should the field be visible?

#### triggerAction(trigger, event)

  Trigger all the actions associated with the given trigger, passing the event provided.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `trigger` | string | The trigger to trigger
  `event` | Annotations.Forms.PDFJS.Event | The event to pass to each action

  Inherited From:
    - Actions.Dispatcher#triggerAction

### Events

#### calculate

  A signal that the field should fire its own calculation events.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `source` | Annotations.Forms.Field | The field that caused the calculation event.

  ##### Listeners of This Event:

  - Annotations.Forms.Field

#### change

  An event that represents a field's value having changed.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `field` | Annotations.Forms.Field | The field that has changed.

#### commit

  The field's value has been changed by the user. Sets a new value.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `value` | string | number | <nullable> | The new field value.

  ##### Listeners of This Event:

  - Annotations.Forms.Field

#### Search results