FutureBasic Logo

<<    Index    >> FutureBasic

Appendix N - Events   appendix

What are events and why are they important?
The Mac OS and the FB runtime (hereafter referred to as the 'runtime' for simplicity) are constantly processing messages sent to/from your running application. These messages or Events are vital to successful app operation and the programmer (that's you) must decide which events to process. Examples of events are: a window resizing, a window needing an update, key presses on the keyboard, mouse or trackpad clicks on interface items such as buttons, menus and inside text fields and many more. Fortunately most events have a default behavior (meaning what the event will do automatically if the program code doesn't intervene) and the programmer isn't required to intercept them. For example, window resizing will happen automatically and the programmer doesn't have to code anything extra to make this happen.

Which events should my app intercept?
An event's "default behavior", as mentioned above, is an important consideration; many times it provides exactly what the app requires (and what a user expects) and no further code is necessary. Imagine a text field on your app's window and the user typing text into a text field. Every time the user presses a keyboard key, an event is sent to your application (actually two events - one for key down and one for key up when the user releases the key). Most of the time an app wouldn't need to know a user has typed text into a text field, so your app would just ignore the message/event and allow the default behavior to handle it.

Your app will process/intercept (more on event interception later) those events it needs to process. This occurs if the app needs to process an event differently from the default behavior or needs to cache information for later processing. For example, if your app allows the user to draw a rectangle in a window with their mouse/trackpad, the code needs to draw the rectangle and track the start point (x,y coordinates) of the rectangle (and the end point but we won't cover that). In this case our app code should intercept/process the _viewMouseDown event and save the rectangle's start point where the user clicked. If our code doesn't process the _viewMouseDown event it wouldn't know where to start drawing the rectangle because it wouldn't have the coordinates of the user's starting mouse click.

Events related to controls (i.e. user interface widgets such as buttons) in a window are usually intercepted because they indicate the user wants to do something. For example, a user presses a button labeled "Print". The app needs to intercept this and provide a printing interface for the user. When a control, like a button, is created either in code or in a nib (via Xcode's Interface Builder - not covered here) the programmer associates a unique tag (typically a numeric constant) with the button. When a button is pressed, the runtime sends the app a button click event. The app must intercept this button click event and then call code (often a function) to process the user's press of that button.

How to request events from the runtime
Intercepting events is a two-stage process as follows:

  1. First, your app must ask the runtime to send events and also tell the runtime where to send them. Three (3) FB statements request events from the runtime and tell the runtime where to send the events.

  2. Next your app must intercept events within those functions (i.e. the function names sent to the runtime). More on that in the next section.
Use these statements to ask the runtime to deliver events
Event request statement Description and Operation
on appevent Request delivery of all application level events
on dialog Request delivery of all events except those provided by on menu and on appevent.
on menu Request delivery of all menu events
HandleEvents Start Application Events - required for apps that need to intercept events

on appevent fn ask runtime to send application events to my function named DoAppEvent
on dialog fn ask runtime to send non-menu and non-App events to my function named DoDialog
on menu fn DoMenuask runtime to send menu events to my function named DoMenu
HandleEventsstart event handling
How to specify events my app needs to intercept?
All events will be delivered to one of your functions based on the function name supplied by your on appevent, on dialog or on menu statement. The code within the receiving function checks the received event against the event names it wants to intercept. Event names are represented by FB constants. The following discussion uses an FB example file, "ApplicationDemo" located in FB Examples/Application, to illustrate event interception with constants.