|
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).
String
R/W
Change all keystrokes to upper case.
// Custom Keystroke for text field
event.change = event.change.toUpperCase();
|
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
Various
R
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);
}
For an example of the use of changeEx with text fields, see the example following fieldFull.
|
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.
Number
R
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.");
|
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.
Boolean
R
Keystroke
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();
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.
|
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).
Boolean
R
|
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.
Boolean
R
|
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
String
R
All
|
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.
Boolean
R/W
Keystroke, Validate, Menu
|
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.
Array of Span objects
R/W
Keystroke
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;
|
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.
Array of Span objects
R/W
Keystroke
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.
|
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.
Array of Span objects
R/W
Keystroke
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;
|
3.01 |
|
|
|
The ending position of the current text selection during a keystroke event.
Integer
R/W
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;
}
|
3.01 |
|
|
|
The starting position of the current text selection during a keystroke event.
Integer
R/W
See the example following selEnd.
|
3.01 |
|
|
|
true if the shift key is down during a particular event, false otherwise.
Boolean
R
The following is a mouse-up button action:
if (event.shift)
this.gotoNamedDest("dest2");
else
this.gotoNamedDest("dest1");
|
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.
Object
R
|
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.
Object
R
|
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:
The folder-level script file name for App/Init events
The document-level script name forDoc/Open events
The PDF file name being processed for Batch/Exec events
The field name for Field events
The menu item name for Menu/Exec events
The screen annotation name for Screen events (multimedia events)
When an exception is thrown, targetName is reported if there is an identifiable name.
String
R
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.
|
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
String
R
|
3.01 |
|
|
|
This property has different meanings for different field events:
For the Field/Validate event, it is the value that the field contains when it is committed. For a combo box, it is the face value, not the export value (see changeEx).
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 a Field/Calculate event, JavaScript should set this property. It is the value that the field should take upon completion of the event.
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 a Field/Format event, JavaScript should set this property. It is the value used when generating the appearance for the field. By default, it contains the value that the user has committed. For a combo box, this is the face value, not the export value (see changeEx for the export value).
For example, the following JavaScript formats the field as a currency type of field.
event.value = util.printf("$%.2f", event.value);
For a Field/Keystroke event, it is the current value of the field. If modifying a text field, for example, this is the text in the text field before the keystroke is applied.
For Field/Blur and Field/Focus events, it is the current value of the field. During these two events, event.value is read only. That is, the field value cannot be changed by setting event.value.
Beginning with
Various
R/W
|
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.
Boolean
R
This example shows the structure of a keystroke event.
var value = event.value
if (event.willCommit)
// Final value checking.
else
// Keystroke-level checking.