HIT, DO and other action routines

Purpose

These routines are used whenever a tag allows that an action routine be passed as paramater. This is the case, for example, for the OUTLINE_ACTION_DO, OUTLINE_ACTION_INFO etc... tags. For all of these tags, you pass a parameter which is a "routine", which returns to SBasic and tells you what routine was called.

In SBasic, you pass HIT_ROUTINE, DO_ROUTINE or any of the other xxxxx_ROUTINEs as parameter. These are actually functions which return an address (try: "Print HIT_ROUTINE") and it is that address that is passsed on to ProWesS. At that address lies a routine that does the fake return to SBasic. When HIT_ROUTINE comes back , it returns a certain value in the hit_or_do% parameter to the PWactivate keyword, whereas DO_ROUTINE returns another value. EXIT_ROUTINE returns yet another value and so on... This allows you to check which routine was called for a certain object by SELecting on the hit_or_do% parameter which is changed by the PWactivate function.

The different routines

Here is a list of the different routines and the values they return. Please note that all routines are not possible for all of the objects: a loose_item object, for example, has no provision for you to set a redraw routine...:
HIT_ROUTINE
This should be used whenever an action routine for a HIT on an item is required. The value returned (in the hit_or_do% parameter) is 0.
DO_ROUTINE
This should be used whenever an action routine for a DO on an item is required. The value returned (in the hit_or_do% parameter) is 1.
RDRW_ROUTINE
This should be used whenever an action routine redrawing an item is required. The value returned (in the hit_or_do% parameter) is 2.
EXIT_ROUTINE
This should be used whenever an action routine is required for the event that the pointer leaves an object. The value returned (in the hit_or_do% parameter) is 3.
MOVE_ROUTINE
This should be used whenever an action routine is required when a MOVE_EVENT is captured by an object. The value returned (in the hit_or_do% parameter) is 4.
SCALE_ROUTINE
This should be used whenever an action routine is required when a SCALE_EVENT is captured by an object. The value returned (in the hit_or_do% parameter) is 5.
DRAGH_ROUTINE
This should be used whenever an action routine is required when the user starts dragging with a Hit. The value returned (in the hit_or_do% parameter) is 6.
DRAGD_ROUTINE
This should be used whenever an action routine is required when the user starts dragging with a Do. The value returned (in the hit_or_do% parameter) is 7.
DRAGE_ROUTINE
This should be used whenever an action routine is required when the user Ends dragging. The value returned (in the hit_or_do% parameter) is 8.
DRAGA_ROUTINE
This should be used whenever an action routine is required to trap the pointer moving out of the object, and making an Adjustment. The value (in the hit_or_do% parameter) returned is 9.
INFO_ROUTINE
This should be used whenever an action routine is required for an info item. The value returned (in the hit_or_do% parameter) is 10.
WAKE_ROUTINE
This should be used whenever an action routine is required for a wake item. The value returned (in the hit_or_do% parameter) is 11.
QUIT_ROUTINE
This should be used whenever an action routine is required for a quit item. The value returned (in the hit_or_do% parameter) is 12.
HELP_ROUTINE
This should be used whenever an action routine is required for a help item. The value returned (in the hit_or_do% parameter) is 13.
INIT_ROUTINE
This should be used whenever an action routine is required following a PW('SYSTEM_ACTION_INIT') tag. The value returned (in the hit_or_do% parameter) is 14.
EVENT_ROUTINES
There are 8 event routines - EVT1_ROUTINE to EVT8_ROUTINE. They can be used for the system events. The values returned are 21 to 28.
There is, of course, nothing to stop you from using a HIT_ROUTINE for a DO_ROUTINE and visa-versa, if you wish. All of these routines are essentially the same, they only differ in the value they return. So, provided you adjust your SELect, you can use any routine for anything you want. I would suggest, however, to use the routines for their purpose, to avoid confusion...

Example:

     (...)

     object=PWcreate (0,(...),PW('OUTLINE_ACTION_WAKE'),WAKE_ROUTINE,
                              PW('OUTLINE_ACTION_INFO'),INFO_ROUTINE,
                              PW('OUTLINE_ACTION_DO'),DO_ROUTINE,
                        (...)

Here, indicating the wake item will call the WAKE_ROUTINE which returns to SBasic, filling in the hit_or_do% parameter with a 11. The object_hit will be the Wake object (you must previously have queried the Outline object to know what is the object identifier of the wake object, so that you can SELect on it).


PROGS, Professional & Graphical Software
last edited 1996 May 29 (wl)