Event Control Scripts

Event Control Scripts are among the most advanced features in BarTender and should be used only by technically knowledgeable individuals.

Depending on the purpose of your script, you might need it to execute as infrequently as once per print job or as often as every single printed item. These are respectively the least frequent and most frequent "events" that occur in a print job. In between, however, there is a variety of events that happen more frequently than once per job but less frequently than every single item.

To keep things as simple as possible, BarTender will normally examine your single-line and multi-line scripts and attempt to determine the ideal frequency with which a script should be executed. For most users and most purposes, this will be sufficient. Sometimes, however, you may need more control and need to explicitly state when your scripts will execute.

Event Types

Although it is very unlikely you would ever need to do so, every data source on your template could potentially have a separate script for every event type supported by BarTender. It is more realistic that, if you do need to write an event script, you will need to do so only for one particular event type and probably just for one or a few data sources.

BarTender supports the use of the following Event Control scripts:

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

When using regular multi-line scripts, the application analyzes the design of both your script and templates according to some preset rules and determines the ideal times for the script to get called. The general goal is to evaluate how your document has its serialization opportunities and copies options set and then to call the multiple-line script often enough to supply the document with new data as needed, but no more often than necessary. The OnAutoSelectedEvent lets you write a script that gets called at those "ideal" times, even though you may also be using other scripts tied to specific events.
OnScreenUpdate: Executes any time the string for the associated object is updated on the screen.

OnScreenUpdate: This script is unique because execution is not limited to print time only. Instead, an OnScreenUpdate event script will execute any time an object is updated on the screen. Objects are updated on the screen in response to a number of events, including clicking 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: Executes when the document is closed.
OnPrePrompt: Executes just before displaying the data entry form, if data entry is enabled.
OnPostPrompt: Executes after a user has clicked OK to close the data entry form.
OnNewRecord: Executes when reading from a data source file. An OnNewRecord event script will be executed each time a new record is read from your database or text file at print time. (Input file data only.)
OnSerialize: Executes when serialization might occur. Refer to OnSerialize for more information.

OnIdenticalCopies: Executes during printing for every printed item, even if it is a copy.

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

OnPrintCancel: Executes when a print job is cancelled.
OnPrintEnd: Executes when a print job has just finished.

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, simply click on that item in the Script pane.

You can now insert whatever lines of VBScript you desire into the Editor pane. (Don’t forget that to assign a value to a data source, a line of script beginning with "Value =" needs to appear somewhere in the script.) You can click on as many different items in the Script pane as you want and define a script for each one.

Related Topics