Appendix N - Events

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

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.

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

Examples:

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 `DoMenu`	ask runtime to send menu events to my function named DoMenu
HandleEvents	start 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.

on appevent event constants are in the Application.incl header (headers can be opened via the View menu + Show Headers Folder). Two useful ones (for more - please see the header) are _appDidFinishLaunching and _appShouldTerminateAfterLastWindowClosed.

_appDidFinishLaunching this event comes from the OS and says "your app was launched" This is a good time to build windows and menus programmatically (or to load windows and menus from a nib created in Xcode's Interface Builder). The "ApplicationDemo" example file and its fn DoAppEvent function shows how to intercept those events with those constants.

on dialog event constants are stored in many headers because, unlike on menu and on appevent, they can arrive from many objects such as windows, buttons and other views/objects. For example, the window event constants are in the Windows.incl header (headers can be opened via the View menu + Show Headers Folder). A useful one (there are many - please see the header) is _windowWillClose. The "ApplicationDemo" example file and its fn DoDialog function shows how to intercept this event (the event means a window is about to close) with that constant. Notice the demo code has only one window, so if a _windowWillClose event arrives it must be that window. Challenge: how to handle a window close if there are multiple windows open?

on menu events are limited to what menu and menu item the user selected. Since an app usually establishes its own constants corresponding to the menus and menu items, it is often just a matter of matching what fn DoMenu receives against your own app's menu/menu item constants to see what the user selected. The "ApplicationDemo" example file and its fn DoMenu function shows how to intercept menu and menu item events with the app's own constants.