VBScript Events and Macros
The PDF writer now features VBScript macros and event handlers.
This means that you can now hook into the process of PDF creation by writing your own Visual Basic
event handlers. You can also use Visual Basic Script in your macros for output file name, author, title, subject, and keyword properties.
VBScript events are an extremely powerful tool for customizing the PDF writer for use in your own software.
Writing the right event handlers gives you complete control over the PDF or image output and the
dialogs shown to the user in the process. It enables you to bypass the normal dialogs and insert your
own dialogs written in the programming language of your choice.
Program Life Cycle
In order to use the VBScript feature you must understand the program life cycle.
The life cycle is a description of when an event is triggered and the information
available to the event at that time in the process.
Event handlers often read and write information to a global Context variable.
The global Context variable contains information about the current state of the
document creation. Events can control the process by manipulating values in the Context variable.
The table below shows the order in which Event Handlers are triggered and
Context Variables are set.
Event Handler or
Context Variable | Description |
| PrinterName |
Name of the used PDF printer.
printername = Context("PrinterName")
reads the PDF printer name into the printername variable.
|
| AppPath |
Holds the full path of the program folder where the PDF printer
is installed.
apppath = Context("AppPath")
reads the program path into the apppath variable.
|
| PostscriptFileName |
This context variable holds the name of the raw postscript output from the printer driver.
Using this file path you can get access to the postscript code as it looks before any modifications are made to it.
filename = Context("PostscriptFileName")
reads the file path into the filename variable.
|
| DocumentName |
This is the name of the document as it is listed in the print job queue.
The title in the configuration is often based on this value.
However, the title in the configuration is often change whereas the
Context("DocumentName") stays the same in all event handlers.
|
| DocumentAuthor |
The Context("DocumentAuthor") represents the name of the author
as it is was given in print job queue. Whereas, the Context("Config")("author")
can change with the configuration the Context("DocumentAuthor")
remains unchanged.
|
| DocumentCreationDate |
A creation date string read from the raw postscript created by the printer driver.
|
| Config |
This is the loaded configuration. The configuration is probably the most interesting context variable.
It carries information about the current configuration.
Using this context variable you can read and write to the current configuration and change the
PDF or image creation process. Configuration values must be accessed using lower case names.
If you by accident use mixed or upper case names then you will just get an empty result.
Context("Config")("watermarktext") = "Hello World!"
sets the watermark text of the created document.
|
| OnConfigLoaded |
This event is raised when the configuration is loaded from a file.
The loaded configuration can be manipulated through Context("Config").
Rem -- Simple example that shows the selected output
Rem -- path in a message box
Sub OnConfigLoaded()
MsgBox context("Config")("output")
End Sub
Rem -- Example that creates a sample bookmark at page 1
Sub OnConfigLoaded()
Dim filename, fso, content, file
Rem -- Get the name of the Postscript file
filename = Context("PostscriptFileName")
Rem -- Load the content
fso = CreateObject("Scripting.FileSystemObject")
Set file = fso.OpenTextFile(filename, 1) ' 1 = ForReading
content = file.ReadAll()
file.Close()
Rem -- Insert bookmark
content = Replace(content, _
vbcrlf & "%%Page: 1 1" & vbcrlf, _
vbcrlf & "[ /Title (Sample bookmark) /OUT pdfmark" & _
vbcrlf & "%%Page: 1 1" & vbcrlf)
Rem -- Save the file again
Set file = fso.OpenTextFile(filename, 2) ' 2 = ForWriting
file.Write(content)
file.Close()
End Sub
|
| TextFileName |
The PDF writer can create a text file with all the text found in the print job.
A text extract can be parsed by an event handler and used to modify values
in the configuration. This is useful if you want to use values from the
printer output as properties in the resulting PDF file.
To enable the text extraction you must set the ExtractText configuration value to yes.
textfile = Context("TextFileName")
reads the full path of the extracted text file into the textfile variable.
|
| OnPreprocessText |
Triggered when the extracted text is ready for processing.
REM -- Example that shows the file name of the extracted text file.
Sub OnPreprocessText()
MsgBox(context("TextFileName"))
End Sub
This event is only fired if you have set ExtractText=yes in the configuration.
|
| OnMacrosApplied |
Macros have been applied to the configuration. |
| OnAfterGUI |
Called after the GUI has been shown. It is also called if the GUI is not shown based on the ShowSettings setting.
This is the event where you can make the last adjustments before the PDF or image is created.
You can access and modify information such as document title and author using the context("Config")("title").
REM -- Example that adds the author to the title
Sub OnAfterGUI()
context("Config")("title") = _
context("Config")("title") & _
" (" & context("Config")("author") & ")"
End Sub
|
| PageCount |
Context("PageCount") contains the number of pages in the output.
|
| OutputFileName |
Name of the output file.
|
| FileCount |
Number of files in the output. Multiple files are normally created when the output type is an image.
|
| FileList |
Context("FileList") is a dictionary of file paths. Each entry in this dictionary
represents a single output file. When multiple files are created, this context
variable is very useful to get a complete list of file names.
|
| ErrorNumber |
Context("ErrorNumber") is the error code in case of an error.
|
| ErrorDescription |
Context("ErrorDescription") is the error description in case of an error.
|
| ErrorSource |
Context("ErrorSource") is the error source in case of an error.
|
| OnSuccess |
OnSuccess is triggered if the document creation is completed without errors.
|
| OnError |
OnError is triggered if there were errors during the document creation.
|
| OnAfterPrint |
Regardless of the status this event is triggered when the process is completed.
If you need to know if the operation was a success then you can create an
event handler for the OnSuccess event. In this handler you can
set a global variable indicating success and test this variable in the
OnAfterPrint event handler.
|
Error Handling
If an error is raised during the execution of a macro script then
the document creation will abort and the error is reported.
Errors can be caused by the executed code or raised explicitly
by the programmer.
The example code below shows how you can raise an error.
Sub OnAfterGUI()
Err.raise(9999, "Test macro script", "Fake error to stop execution.")
End Sub
By default the program will show the error message in a message box
and the user will have to press the Ok button to continue.
The message box can be suppressed with the SuppressErrors setting
and errors can be logged in the status file using the StatusFile
setting.
You can add your own code to handle errors in the OnError
event handler. The code below shows how you can retrieve the error
information.
Sub OnError()
MsgBox("Error trapped by OnError eventhandler." & vbcrlf & vbcrlf & _
"Error=" & Context("ErrorNumber") & vbcrlf & _
"Description=" & Context("ErrorDescription") & vbcrlf & _
"Source=" & Context("ErrorSource"))
End Sub
Important Note: All names used to access information in the context object are case sensitive.
When reading and writing information to the Context("Config")("configname") all
configuration names must be written in lower case.
|
