20002009 Ericsson AB. All Rights Reserved. The contents of this file are subject to the Erlang Public License, Version 1.1, (the "License"); you may not use this file except in compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. Events gs_chapter4.xml
Event Messages

Events are messages which are sent to the owner process of the object when the user interacts with the object in some way. A simple case is the user pressing a button. An event is then delivered to the owner process of the button (the process that created the button). In the following example, the program creates a button object and enables the events click and enter. This example shows that events are enabled in the same way as objects are configured with options.

The process is now ready to receive click and enter events from the button. The events delivered are always five tuples and consist of:

is a tag which says it is an event from the graphics server. contains the object identifier or the name of the object in which the event occurred. contains the type of event which has occurred. In the example shown, it is either or . is a field which the user can set to any Erlang term. It is very useful to have the object store arbitrary data which is delivered with the event. is a list which contains event specific information. In a motion event, the Args argument would contain the x and y coordinates.

There are two categories of events:

generic events object specific events.
Generic Events

Generic events are the same for all types of objects. The following table shows a list of generic event types which the graphics server can send to a process. For generic events, the argument always contains the same data, independent of which object delivers it.

The following sub-sections explains the event types and what they are used for.

Event Args Description buttonpress [ButtonNo,X,Y|_] A mouse button was pressed over the object. buttonrelease [ButtonNo,X,Y|_] A mouse button was released over the object. enter [] Delivered when the mouse pointer enters the objects area. focus [Int|_] Keyboard focus has changed. 0 means lost focus. 1 means gained focus. keypress [KeySym,Keycode, Shift, Control|_] A key has been pressed. leave [] Mouse pointer leaves the object. motion [X,Y|_] The mouse pointer is moving in the object. Used when tracking the mouse in a window. Generic Event Types
The Buttonpress and Buttonrelease Events

These events are generated when a mouse button is pressed or released inside the object frame of a window, or frame object type. The button events are not object specific (compare to click). The format of the buttonpress event is:

The mouse button number which was pressed is the first argument in the field list. This number is either 1, 2 or 3, if you have a three button mouse. The and coordinates are sent along to track in what position the user pressed down the button. These events are useful for programming things like "rubberbanding", which is to draw out an area with the mouse. In detail, this event can be described as pressing the mouse button at a specific coordinate and releasing it at another coordinate in order to define a rectangular area. This action is often used in combination with motion events.

The Enter and Leave Events

These events are generated when the mouse pointer (cursor) enters or leaves an object.

The Focus Event

The focus event tracks which object currently holds the keyboard focus. Only one object at a time can hold the keyboard focus. To have the keyboard focus means that all keypresses from the keyboard will be delivered to that object. The format of a focus event is:

The FocusFlag argument is either 1, which means that the object has gained keyboard focus, or 0, which means that the object has lost keyboard focus.

The Keypress Event

This event is generated by an object which receives text input from the user, like entry objects. It can also be generated by window objects. The format of a keypress event is:

The argument is either the character key which was pressed, or a word which describes which key it was. Examples of are; ,,.., 1,2,3..., , , , , , . The argument is the keycode number for the key that was pressed. Either the or the argument can be used to find out which key was pressed. The argument contains either a 0 or a 1 to indicate if the Shift key was held down when the character key was pressed. The Control argument is similar to the Shift key argument, but applies to the Control key instead of the Shift key.

The Motion Event

The motion event is used to track the mouse position in a window. When the user moves the mouse pointer (cursor) to a new position a motion event is generated. The format of a motion event is:

The current x and y coordinates of the cursor are sent along in the field.

Object Specific Events

The click and doubleclick events are the object specific event types. Only some objects have these events and the field of the events vary for different type of objects. A click on a check button generates a click event where the data field contains the on/off value of the indicator. On the other hand, the click event for a list box contains information on which item was chosen.

Event Args Description click <object specific> Pressing a button or operating on a object in some predefined way. double-click <object specific> Pressing the mouse button twice quickly. Useful with list boxes. Object Specific Events
Matching Events Against Object Identifiers

Events can be matched against the object identifier in the receive statement. The disadvantage of matching against identifiers is that the program must pass the object identifiers as arguments to the event loop.

Matching Events Against Object Names

Another solution is to name the objects using the function. In this way, the program does not have to pass any parameters which contain object identifiers for each function call made.

Matching Events Against the Data Field

A third solution is to set the option to some value and then match against this value. All built-in objects have an option called which can be set to any Erlang term. For example, we could set the data field to a tuple and have the receiving function make an on the contents of the data field whenever certain events arrive.

Experimenting with Events

A good way of learning how events work is to write a short demo program like the one shown below and test how different events work.