Providing event handlers

Understanding automation : How is automation coding structured? : Providing event handlers

Providing event handlers

While running, CorelDRAW raises various events to which macros can respond through the use of event handlers — subroutines with specific, defined names. Each macro project defines its event handlers in one of the following code modules:

•

ThisMacroStorage — for macro projects that are stored in Global Macro Storage (GMS) files

•

ThisDocument — for macro projects that are stored in documents

The GlobalMacroStorage object is a virtual object that represents each and all open documents. The GlobalMacroStorage object has several events that are raised at the time of any event, such as opening, printing, saving, or closing a document (although the range of events is actually greater than this because each one has a “before” and “after” event).

To respond to an event, you must provide an event handler — a subroutine in any ThisMacroStorage module with a specific name for which the application is pre-programmed to search. However, the application does check all ThisMacroStorage modules in all installed projects; for this reason, you can create an event-driven solution and distribute it as a single project file just as you would provide any other solution. Each project can have only one ThisMacroStorage module, and it is automatically created when the project is first created.

In VBA, you can add event handlers to a ThisMacroStorage module by using the Macro Editor. For example, a CorelDRAW macro solution may need to respond to the closing of a document by logging the closure in a file as part of a workflow-management system. To respond to the opening of a document, the solution must respond to the OpenDocument event for the GlobalMacroStorage class. To create this event handler in VBA, do the following:

•

Open a ThisMacroStorage module for editing in the Macro Editor.

•

Next, choose GlobalMacroStorage from the Object list box at the top of the Code window, and then choose DocumentOpen from the Procedure list box.

The Macro Editor creates a new, empty subroutine called GlobalMacroStorage_DocumentOpen()— or, if that subroutine already exists, the Macro Editor places the cursor into it. To then add the name of the opened file to the log, you need only write some code. To reduce the size of the ThisMacroStorage module, you can assign this event-logging task to a public subroutine in another module. This technique lets the run-time interpreter more easily parse all the ThisMacroStorage modules each time an event is raised. The following VBA code illustrates this example for CorelDRAW:

Private Sub GlobalMacroStorage_OpenDocument(ByVal Doc As Document, _

ByVal FileName As String)

Call LogFileOpen(FileName)

End Sub

Here is a small sample of the events available in CorelDRAW:


Event	Description
`Start`	Raised when the user starts the application
`DocumentNew`	Raised when a document is created; passes a reference to the document
`DocumentOpen`	Raised when a document is opened; passes a reference to the document
`DocumentBeforeSave`	Raised before a document is saved; passes the file name of the document as a parameter
`DocumentAfterSave`	Raised after a document is saved; passes the file name of the document as a parameter
`DocumentBeforePrint`	Raised before the Print dialog box is displayed
`DocumentAfterPrint`	Raised after a document is printed
`SelectionChange`	Raised when a selection changes
`DocumentClose`	Raised before a document is closed
`Quit`	Raised when the user quits the application

•

Event handlers for frequent events — such as events related to the Shape class — should be as efficient as possible, to keep the application running as quickly as possible.