ON EVENT CALL

version 3

ON EVENT CALL (eventMethod{; processName})

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, 4th Dimension handles the events and sends them to the appropriate forms and objects.

Tip: Version 6 introduces new commands, such as GET MOUSE, Shift down, etc., 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 4th Dimension method is running. After installation, 4th Dimension 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-Option-Control-Backspace (on Macintosh) converts the Event Manager process into a normal process. This means that the method will no longer be automatically passed all the events that occur. 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 ASCII code for a keystroke. This variable may return an ASCII code or a function key code. These codes are listed in the sections ASCII Codes (and its subsections) and Function Key Codes. 4D provides predefined constants for the major ASCII Codes and for Function Key Codes. In the Explorer window, look for the themes of these constants.

• The Modifiers system variable contains the modifier value. It indicates whether any of the following modifier keys were down when the event occurred:

- The Windows ALT key is equivalent to the Macintosh Option key.

- The Windows Ctrl key is equivalent to the Macintosh Command key.

- The Macintosh Control key has no equivalent on Windows. However, a right mouse button click on Windows is equivalent to a Control-Click on Macintosh.

The modifier keys do not generate an event; another key or the mouse button must also be pressed. The Modifiers variable is a 4-byte Long Integer variable that should be seen as an array of 32 bits. 4D provides predefined constants expressing bit positions or bit masks for testing the bit corresponding to each modifier key. For example, to detect if the Shift key was pressed for the event, you can write:

   If (Modifiers ?? Shift key bit ) ` If the Shift key was down

or:

   If ((Modifiers & Shift key mask)#0)` If the Shift key was down

Note: Under Windows, the value 128 is added to the Modifiers variable if the (left) button of the mouse is released at the time of the event.

• 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:

   PAGE SETUP
   If (OK=1)
      <>vbWeStop:=False
      ON EVENT CALL("EVENT HANDLER") ` Installs the event-handling method
      ALL RECORDS([People]) 
      MESSAGE("To interrupt printing press Ctrl+Period") 
      $vlNbRecords:=Records in selection([People])
      For ($vlRecord;1;$vlNbRecords)
         If (<>vbWeStop) 
            ALERT("Printing cancelled at record "+String($vlRecord)+" of "+String($vlNbRecords)) 
            $vlRecord:=$vlNbRecords+1
         Else 
            Print form([People];"Special Report") 
         End if 
      End for 
      PAGE BREAK 
      ON EVENT CALL("") ` Deinstalls the event-handling method
   End if

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

      ` EVENT HANDLER project method
   If ((Modifiers ?? Command key bit) & (KeyCode = Period))
      CONFIRM("Are you sure?") 
      If (OK=1) 
         <>vbWeStop:=True
         FILTER EVENT ` Do NOT forget this call; otherwise 4D will also get this event 
      End if 
   End if

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; PRINT SELECTION does that for you.

FILTER EVENT, GET MOUSE, Method called on event, Shift down.