ON EVENT CALL

The ON EVENT CALL command installs the method, whose name you pass in eventMethod, as the method for catching (trapping) events. This method is called the event-handling method or event-catching method.

Tip: This command requires advanced programming knowledge. Usually, you do not need to use ON EVENT CALL for working with events. While using forms, 4D handles the events and sends them to the appropriate forms and objects.

Tip: Commands such as GET MOUSE, Shift down, etc., can be used for getting information about events. These commands can be called from within object methods to get the information you need about an event involving an object. Using them spares you the writing of an algorithm based on the ON EVENT CALL scheme.

The scope of this command is the current working session. By default, the method is run in a separate local process. You can have only one event-handling method at a time. To stop catching events with a method, call ON EVENT CALL again and pass an empty string in eventMethod.

Since the event-handling method is run in a separate process, it is constantly active, even if no 4D method is running. After installation, 4D calls the event-handling method each time an event occurs. An event can be a mouse click or a keystroke.

The optional processName parameter names the process created by the ON EVENT CALL command. If processName is prefixed with a dollar sign ($), a local process is started, which is usually what you want. If you omit the processName parameter, 4D creates, by default, a local process named $Event Manager.

WARNING: Be very careful in what you do within an event-handling method. Do NOT call commands that generate events, otherwise it will be extremely difficult to get out of the event-handling method execution. The key combination Ctrl+Shift+Backspace (on Windows) or Command-Shift-Control-Backspace (on Macintosh) allows you to kill the Event Manager process. You may want to use this technique to recover an event-handling gone wrong (i.e., one that has bugs triggering events).

In the event-handling method, you can read the following system variables—MouseDown, KeyCode, Modifiers, MouseX, MouseY and MouseProc. Note that these variables are process variables. Their scope is therefore the event-handling process. Copy them into interprocess variables if you want their values available in another process.

• The MouseDown system variable is set to 1 if the event is a mouse click, and to 0 if it is not.
• The KeyCode system variable is set to the code for a keystroke. This variable may return an character code or a function key code. These codes are listed in the sections Unicode Codes and EXPORT TEXT (and its subsections) as well as in the section Function Key Codes. 4D provides predefined constants for the major ASCII Codes and for Function Keys. In the Explorer window, look for the themes of these constants.
• The Modifiers system variable contains the modifier value. It indicates whether a modifier key was down when the event occurred. The following keys can be detected:
  

  Platform	Modifiers
  Windows	Shift key, Caps Lock, Alt key, Ctrl key
  Macintosh	Shift key, Caps Lock, Alt (or Option) key, Command key, Ctrl key

  
  The modifier keys do not generate an event on their own; another key or the mouse button must also be pressed. The Modifiers variable is a Long Integer variable containing a bit field. 4D provides predefined constants specifying the bit position or bit mask for each modifier key. For example, to detect if the Shift key was pressed for the event, you can write either:
  
   If(Modifiers?? Shift key bit) //If the Shift key was down
  
  or:
  
   If((Modifiers & Shift key mask)#0) //If the Shift key was down
  
  You can use one of the following constants, depending on the modifier key to be tested and the platform, which are found in the Events (Modifiers) theme:
  

  Modifier	Constant
  Shift	Shift key bit / Shift key mask
  Caps Lock	Caps lock key bit / Caps lock key mask
  Alt (also called Option under OS X)	Option key bit / Option key mask
  Ctrl under Windows	Command key bit / Command key mask
  Ctrl under OS X	Control key bit / Control key mask
  Command under OS X	Command key bit / Command key mask
  Right click	Control key bit / Control key mask

  
  

• The system variables MouseX and MouseY contain the horizontal and vertical positions of the mouse click, expressed in the local coordinate system of the window where the click occurred. The upper left corner of the window is position 0,0. These are meaningful only when there is a mouse click.
• The MouseProc system variable contains the process reference number of the process in which the event occurred (mouse click).

Important: The system variables MouseDown, KeyCode, Modifiers, MouseX, MouseY, and MouseProc contain significant values only within an event-handling method installed with ON EVENT CALL.

This example will cancel printing if the user presses Ctrl+period. First, the event-handling method is installed. Then a message is displayed, announcing that the user can cancel printing. If the interprocess variable ◊vbWeStop is set to True in the event-handling method, the user is alerted to the number of records that have already been printed. Then the event-handling method is deinstalled:

If Ctrl+period has been pressed, the event-handling method sets ◊vbWeStop to True:

Note that this example uses ON EVENT CALL because it performs a special printing report using the PAGE SETUP, Print form and PAGE BREAK commands with a For...End for loop.

If you print a report using PRINT SELECTION, you do NOT need to handle events that let the user interrupt the printing; this command does that for you.