event properties

change

name

shift

Example

rc

source

changeEx

richChange

target

commitKey

richChangeEx

targetName

fieldFull

richValue

type

keyDown

selEnd

value

modifier

selStart

willCommit

change

3.01

 

 

 

A string specifying the change in value that the user has just typed. A JavaScript may replace part or all of this string with different characters. The change may take the form of an individual keystroke or a string of characters (for example, if a paste into the field is performed).

Type

String

Access

R/W

Example

Change all keystrokes to upper case.

   // Custom Keystroke for text field

   event.change = event.change.toUpperCase();

changeEx

5.0

 

 

 

Contains the export value of the change and is available only during a Field/Keystroke event for list boxes and combo boxes.

For the list box, the keystroke script, if any, is entered under the Selection Change tab in the properties dialog box.

For the combo box, changeEx is only available if the pop-up list is used—that is, a selection (with the mouse or the keyboard) is being made from the list. If the combo is editable and the user types in an entry, the Field/Keystroke event behaves as for a text field (that is, there are no changeEx or keyDown event properties).

Beginning with Acrobat 6.0, event.changeEx is defined for text fields. When event.fieldFull is true, changeEx is set to the entire text string the user attempted to enter and event.change is the text string cropped to what fits within the field. Use event.richChangeEx (and event.richChange) to handle rich text fields.

Type

Various

Access

R

Example 1

This example implements a simple HTML online help file system.

Here is a combo box, which is described programmatically.

   var c = this.addField({

      cName: "myHelp",

      cFieldType: "combobox",

      nPageNum: 0,

      oCoords: [72,12+3*72, 3*72, 0+3*72]

   })

Now set the items in the combo box.

   c.setItems([

      ["Online Help", "http://www.example.com/myhelp.html"],

      ["How to Print", "http://www.example.com/myhelp.html#print"],

      ["How to eMail", "http://www.example.com/myhelp.html#email"]

   ]);

Set the action.

   c.setAction("Keystroke", "getHelp()");

This function is defined at the document level.

   function getHelp() {

      if ( !event.willCommit && (event.changeEx != "") )

         app.launchURL(event.changeEx);

   }

Example 2

For an example of the use of changeEx with text fields, see the example following fieldFull.

commitKey

4.0

 

 

 

Determines how a form field will lose focus. Values are:

0 — Value was not committed (for example, escape key was pressed).

1 — Value was committed because of a click outside the field using the mouse.

2 — Value was committed because of pressing the Enter key.

3 — Value was committed by tabbing to a new field.

Type

Number

Access

R

Example

To automatically display an alert dialog box after a field has been committed, add the following to the field’s format script:

   if (event.commitKey != 0)

      app.alert("Thank you for your new field value.");

fieldFull

6.0

 

 

 

Set to true when the user attempts to enter text that does not fit in the field due to either a space limitation (the Field object property doNotScroll is set to true) or the maximum character limit (the Field object property charLimit is set to a positive value). When fieldFull is true, event.changeEx is set to the entire text string the user attempted to enter and event.change is the text string cropped to what fits within the field.

Only available in keystroke events for text fields.

Type

Boolean

Access

R

Events

Keystroke

Example 1

This is a custom keystroke script for a text field that has a character limit. When the field gets filled, or if the user commits the data entered, the focus moves to another field.

   if ( event.fieldFull || event.willCommit )

      this.getField("NextTabField").setFocus();

Example 2

Test whether the user has overfilled the text field. A custom keystroke script for a text field. Initially, the field is set so that text does not scroll.

   if ( event.fieldFull )

   {

      app.alert("You've filled the given space with text,"

      + " and as a result, you've lost some text. I'll set the field to"

      + " scroll horizontally, and paste in the rest of your"

      + " missing text.");

      this.resetForm([event.target.name]);     // Reset field to lose focus

      event.target.doNotScroll = false;        // Make changes

      event.change = event.changeEx;

   }

Field properties generally cannot be changed during a keystroke event, so it is necessary for the field to lose focus as a way to commit the data. The user then has to reset the focus and continue entering data.

keyDown

5.0

 

 

 

Available only during a keystroke event for list box and combo box. For a list box or the pop-up part of a combo box, the value is true if the arrow keys were used to make a selection, false otherwise.

For the combo box, keyDown is only available if the pop-up part of it is used, that is, a selection (with the mouse or the keyboard) is being made from the pop-up. If the combo is editable and the user types in an entry, the Field/Keystroke event behaves as for a text field (that is, there are no changeEx or keyDown event properties).

Type

Boolean

Access

R

modifier

3.01

 

 

 

Specifies whether the modifier key is down during a particular event. The modifier key on the Microsoft Windows platform is Control and on the Mac OS platform is Option or Command. This property is not supported on UNIX.

Type

Boolean

Access

R

name

4.05

 

 

 

The name of the current event as a text string. The type and name together uniquely identify the event. Valid names are:

   Keystroke        Mouse Exit

   Validate         WillPrint

   Focus            DidPrint

   Blur             WillSave

   Format           DidSave

   Calculate        Init

   Mouse Up         Exec

   Mouse Down       Open

   Mouse Enter      Close

Type

String

Access

R

Events

All

rc

3.01

 

 

 

Used for validation. Indicates whether a particular event in the event chain should succeed. Set to false to prevent a change from occurring or a value from committing. The default is true.

Type

Boolean

Access

R/W

Events

Keystroke, Validate, Menu

richChange

6.0

 

 

 

Specifies the change in value that the user has just typed. The richChange property is only defined for rich text fields and mirrors the behavior of the event.change property. The value of richChange is an array of Span objects that specify both the text entered into the field and the formatting. Keystrokes are represented as single member arrays, while rich text pasted into a field is represented as an array of arbitrary length.

When event.fieldFull is true, richChangeEx is set to the entire rich formatted text string the user attempted to enter and event.richChange is the rich formatted text string cropped to what fits within the field. Use event.changeEx (and event.change) to handle (plain) text fields.

Related objects and properties are event.richValue, the Span object, the Field object defaultStyle, richText, and richValue properties, and the Annotation object richContents property.

Type

Array of Span objects

Access

R/W

Events

Keystroke

Example

This example changes the keystroke to upper case, alternately colors the text blue and red, and switches underlining off and on.

   // Custom Keystroke event for a rich text field.

   var span = event.richChange;

   for ( var i=0; i<span.length; i++)

   {

      span[i].text = span[i].text.toUpperCase();

      span[i].underline = !span[i].underline;

      span[i].textColor = (span[i].underline) ? color.blue : color.red;

   }

   event.richChange = span;

richChangeEx

6.0

 

 

 

This property is only defined for rich text fields. It mirrors the behavior of the event.changeEx property for text fields. Its value is an array of Span objects that specify both the text entered into the field and the formatting. Keystrokes are represented as single member arrays, while rich text pasted into a field is represented as an array of arbitrary length.

If event.fieldFull is true, richChangeEx is set to the entire rich formatted text string the user attempted to enter and event.richChange is the rich formatted text string cropped to what fits within the field. Use event.changeEx (and event.change) to handle (plain) text fields.

Related objects and properties include event.richChange, event.richValue, the Span object, the Field object defaultStyle, richText, and richValue properties, and the Annotation object richContents property.

Type

Array of Span objects

Access

R/W

Events

Keystroke

Example

If the text field is filled up by the user, allow additional text by setting the field to scroll.

   if ( event.fieldFull )

   {

      app.alert("You've filled the given space with text,"

      + " and as a result, you've lost some text. I'll set the field to"

      + " scroll horizontally, and paste in the rest of your"

      + " missing text.");

      this.resetForm([event.target.name]);    // Reset field to lose focus

      event.target.doNotScroll = false;       // Make changes

      if ( event.target.richText )

         event.richChange = event.richChangeEx

      else

         event.change = event.changeEx;

   }

See also event.fieldFull.

richValue

6.0

 

 

 

This property mirrors the richValue property of the Field object and the event.value property for each event.

Related objects and properties include the Span object, the Field object properties defaultStyle, richText, richValue, event.richChange, event.richChangeEx, and the Annotation object richContents property.

Type

Array of Span objects

Access

R/W

Events

Keystroke

Example

Turn all bold text into red underlined text.

   // Custom format event for a rich text field.

   var spans = event.richValue;

   for ( var i = 0; i < spans.length; i++ )

   {

      if( spans[i].fontWeight >= 700 )

      {

         spans[i].textColor = color.red;

         spans[i].fontWeight = 400;     // change to default weight

         spans[i].underline = true;

      }

   }

   event.richValue = spans;

selEnd

3.01

 

 

 

The ending position of the current text selection during a keystroke event.

Type

Integer

Access

R/W

Example

Merge the last change (of a text field) with the uncommitted change. The function uses both selEnd and selStart.

   function AFMergeChange(event)

   {

      var prefix, postfix;

      var value = event.value;

   

      if(event.willCommit) return event.value;

      if(event.selStart >= 0)

         prefix = value.substring(0, event.selStart);

      else prefix = "";

      if(event.selEnd >= 0 && event.selEnd <= value.length)

         postfix = value.substring(event.selEnd, value.length);

      else postfix = "";

      return prefix + event.change + postfix;

   }

selStart

3.01

 

 

 

The starting position of the current text selection during a keystroke event.

Type

Integer

Access

R/W

Example

See the example following selEnd.

shift

3.01

 

 

 

true if the shift key is down during a particular event, false otherwise.

Type

Boolean

Access

R

Example

The following is a mouse-up button action:

   if (event.shift)

      this.gotoNamedDest("dest2");

   else

      this.gotoNamedDest("dest1");

source

5.0

 

 

 

The Field object that triggered the calculation event. This object is usually different from the target of the event, which is the field that is being calculated. For dynamic stamp calculation, event.source corresponds to the Doc object that triggered the event.

Type

Object

Access

R

target

3.01

 

 

 

The target object that triggered the event. In all mouse, focus, blur, calculate, validate, and format events, it is the Field object that triggered the event. In other events, such as page open and close, it is the Doc or this object.

Type

Object

Access

R

targetName

5.0

 

 

 

Tries to return the name of the JavaScript being executed. Can be used for debugging purposes to help identify the code causing exceptions to be thrown. Common values of targetName include:

When an exception is thrown, targetName is reported if there is an identifiable name.

Type

String

Access

R

Example

The first line of the folder-level JavaScript file conserve.js has an error in it. When the viewer starts, an exception is thrown and the message reveals the source of the problem.

   MissingArgError: Missing required argument.

   App.alert:1:Folder-Level:App:conserve.js

    ===> Parameter cMsg.

type

5.0

 

 

 

The type of the current event. The type and name together uniquely identify the event. Valid types are:

   Batch            External

   Console          Bookmark

   App              Link

   Doc              Field

   Page             Menu

Type

String

Access

R

value

3.01

 

 

 

This property has different meanings for different field events:

For example, the following JavaScript verifies that the field value is between zero and 100:

      if (event.value < 0 || event.value > 100) {

         app.beep(0);

         app.alert("Invalid value for field " + event.target.name);

         event.rc = false;

      }

For example, the following JavaScript sets the calculated value of the field to the value of the SubTotal field plus tax.

      var f = this.getField("SubTotal");

      event.value = f.value * 1.0725;

For example, the following JavaScript formats the field as a currency type of field.

      event.value = util.printf("$%.2f", event.value);

Beginning with Acrobat 5.0, for a list box that allows multiple selections (see field.multipleSelection), the following behavior occurs. If the field value is an array (that is, multiple items are selected), event.value returns an empty string when getting, and does not accept setting.

Type

Various

Access

R/W

willCommit

3.01

 

 

 

Verifies the current keystroke event before the data is committed. It can be used to check target form field values to verify, for example, whether character data was entered instead of numeric data. JavaScript sets this property to true after the last keystroke event and before the field is validated.

Type

Boolean

Access

R

Example

This example shows the structure of a keystroke event.

   var value = event.value

   if (event.willCommit)

      // Final value checking.

   else

      // Keystroke-level checking.