Event Control Scripts

Event control scripts are among the most advanced features in BarTender and should be used only by technically knowledgeable users.

Depending on the purpose of your script, you might need it to run as infrequently as one time per print job or as often as every printed item. These are the least frequent and most frequent "events" that occur in a print job, but a variety of events happen more frequently than one time per job and less frequently than every item.

To simplify the process, BarTender typically examines your single-line and multi-line scripts and tries to determine the ideal frequency with which a script should be run. For most users and most purposes, this is sufficient. Sometimes, however, you may need to have more control to explicitly state when your scripts run.

Event Types

It is possible for every data source on your template to have a separate script for every event type that is supported by BarTender. However, this is a very unlikely scenario. More realistically, if you do need to write an event script, you will need to do so only for one particular event type and probably only for one or a few data sources.

BarTender supports the use of the following event control scripts:

OnAutoSelectedEvent: Runs with the same frequency with which scripts are called when the Type is set to Multi-Line Script.

When you use regular multi-line scripts, the application analyzes the design of both your script and your templates according to preset rules and determines the ideal times for the script to be called. The general goal is to evaluate the configuration of your document's serialization opportunities and copies options and then to call the multi-line script often enough to supply the document with new data, but no more often than necessary. Use OnAutoSelectedEvent to write a script that is called at those "ideal" times, even if you are also using other scripts that are associated with specific events.
OnScreenUpdate: Runs any time that the string for the associated object is updated on the screen.

An OnScreenUpdate event script runs whenever an object is updated on the screen, not only at print time. Objects are updated on the screen in response to a number of events, including when a user clicks OK to return to the template. Although other uses may exist, the most important task for this event is to write scripts that give an on-screen value to a non-printing object that is being used to create a print job log file.
OnPrintStart: Runs when the document is closed.
OnPrePrompt: Runs just before the data entry form is displayed if data entry is enabled.
OnPostPrompt: Runs after a user clicks OK to close the data entry form.
OnNewRecord: Runs when a data source file is read from. An OnNewRecord event script is run each time a new record is read from your database or text file at print time. Available for input file data only.
OnSerialize: Runs when serialization might occur. For more information, refer to OnSerialize.

OnIdenticalCopies: Runs during the print job for every printed item, even if it is a copy.

When you set a value that is greater than one in the Copies option on the Print dialog, BarTender can send the template to your printer one time and instruct the printer to print the number of copies that you want. However, if you write a script for the OnIdenticalCopies event, it is run for every item that is printed, even if the items are copies. This process requires that BarTender turns off the previously mentioned printer optimization, which can result in a significant loss in performance.

OnPrintCancel: Runs when a print job is canceled.
OnPrintEnd: Runs when a print job finishes.

Selecting the Events for Which to Write Scripts

Each line item in the Script pane corresponds to a separate script. When you want to write a script for a given event, click that item in the Script pane.

You can now insert whatever lines of VBScript you want into the Editor pane. Remember that to assign a value to a data source, you must add a line of script that starts with "Value =" somewhere in the script. You can click as many different items in the Script pane as you want and define a script for each one.

Related Topics