Application Events
Enabling Event Handlers
You must enable event handlers before using them. For security reasons, they are disabled by default. To enable event handlers, select Options > Preferences and click the General tab. Then, check the box that says
"Enable event handlers". Once you enable event handlers, that option is saved so you don't have to do it again.
There is also a user-level command named Enable Event Handlers that can be assigned to a menu, or a keystroke.
Note:
For security reasons, you cannot run the
Enable Event Handlers
command from a macro.
Editing Event Handler Files
Source Insight will ignore event handlers in any file that is modified and unsaved. Therefore, if you are editing an event handler source file, Source Insight will not try to execute the handler while you are editing it! Once you are done with the editing, save the file. Source Insight will once again execute the handlers when the file is saved.
Errors in Event Handlers
If an event handler causes a syntax error or runtime error, then all event handlers are disabled for the rest of the Source Insight session. You will see a "Macro Error" warning message. To enable event handlers again, you must restart Source Insight.
Synchronous Vs. Asynchronous Events
Some event handlers are called immediately when the event occurs. These are called "synchronous' events.
An example is
DocumentNew
. It gets called as soon as the user creates a new document (file buffer).
However, some events are called shortly after the event occurs, usually after a short amount of idle time.
These are called "asynchronous' events. They are asynchronous because it would destabilize Source Insight if a user-written macro were to be called at the exact time the event occurred.
Helpful Tips for Event Handlers
It is best to put all event handlers in one file, or a small number of files with names like "event-something.em". That way, you can easily remove those files from the project to effectively turn off the handlers.
Global variables are useful for adding counters, and maintaining state between events. See “Global Variables” on page 371.
Application Events
Application events apply to the Source Insight application as a whole.
event AppStart()
Called after the Source Insight application loads and initializes. The current project and workspace session is already loaded.
Source Insight 4 User Guide 413