An event is PCE's notion of representing some activity from the user. Such an activity may be the user pressing a key on the keyboard, a button of the mouse, changing the mouse's location, etc.
Events are typed and their types are organised in a hierarchy. See Class event_tree. Note that event-types have no relation to PCE data-types as described by class type.
Events are trapped from the X-window environment by class window. This class deals internally with low-level events such as repaint requests. All events that may be of interest to the user are transformed into PCE event objects, which are then dispatched by a graphical device object.
There are several ways to program event handling. The most common way
is to use gesture
objects. A gesture
object parses one or a sequence of events into meaningful actions such
as click, move, resize, connect, etc. Gestures may be attached to
graphical objects
using graphical->recogniser.
When using user-defined classes, events may be parsed by redefining the
graphical->event
method. Gestures are normally used to realise the event-parsing in the
redefined method.
Bugs:
The single inheritance hierarchy for event type specification is not very satisfactory. A multiple inheritance hierarchy would be better. A common problem arrising is that you may wish to have all left-button events, regardless of whether it is an up, down or drag or all button-down events, regardless of the exact button.
ASCII events are defined very ungracefully. Be aware that consistency
with class editor will
probably be implemented some day, changing --for example-- type 3
into _\C-c_.
The status of the modifier keys is normally tested using event->has_modifier.
The type of click (single, double, triple) is requested using
event<-multiclick
and the button for button-related events using event<-button.
Current definition of the mask-values
control-key 0x1 shift-key 0x2 meta-key 0x4 left-button 0x8 middle-button 0x10 right-button 0x20 single-click 0x40 double-click 0x80 triple-click 0xC0
<-key.
Whether or not an event is of specified type is normally tested using
event->is_a.
Other useful classifications are realised using
event->is_up, event->is_down, event->is_drag, event->has_modifier, event<-click_time
and
event<-click_displacement.
One event requires special treatment. This is the event related to wheel-mice,
mice normally having two buttons and a scroll-wheel. Rotations of the
scroll-wheel are mapped to an
event object with event<-id:
wheel. Conform the Microsoft windows conventions, this event is has a rotation
attribute, associate using object->attribute.
The rotation has the value 120 if the wheel is rotated from the user and
-120 when rotated towards the user.
In the X11 version, wheel-events are normally mapped to the virtual
mouse-buttons 4 and 5. If the class-variable
event.x11_wheel_mouse = @on
(default in the X11 version), the low-level event handling will map the
button 4 and button 5 events to wheel events.
The wheel event is handled by class window, class editor, class list_browser and class scroll_bar.
<-position
or event<-area_position.
Subsequent calls to one of these methods will update the point<-x
and point<-y
values and return the same point
object.
|frame->post.
Note that this graphical is not necessarily the object that initialy
received the event. See also event<-window.
<-multiclick.|frame->event.
<-window.
Note that this position is not in the window's coordinate system,
but relative to the top-left corner of the X-widget realising the
window.
<-window.
See event<-x
for details.
A modifier may be created by conversion from a name consisting of the
letters’s’(shift),’c’(control) and’m’(meta).
The empty name demands all modifier keys to be up. See modifier<-convert
for details.
The following tests whether the shift key of the current event is depressed (and the control- and meta-keys are not depressed).
send(@event, has_modifier, s).
|frame], x=[int], y=[int], button_mask=[int],
time=[int]->generate_event.
->in_event_area).
If the argument is a window it checks whether the event is in the client area of the window.
Defaults: The default graphical is the event<-receiver.
<-id
is at or below the specified node in @event_hierarchy.
This test is the common way to test the identity of events. It is used by handler objects. Note that class gesture provides a more advanced mechanism to deal with mouse events.
ASCII events (event<-id
is an integer) are organised as follows:
ascii
control
0..31|127
printable
32..126
meta
128..255
The demo tool Events displays @event-hierarchy.
loc_move event with one of the pointer-buttons depressed.->is_down.
It may also be used to forward events to other graphicals. It performs the following steps:
<-receiver
to the argument graphical
->event
to the argument graphical. Otherwise invoke recogniser->event
on the argument recogniser. The latter mechanism is used when a device->event
posts an event to its focus and
window<-focus_recogniser
is not @nil.
<-window
has no window<-focus
and
->is_down
event and
<-window
invoke `window ->focus: graphical, @nil, @default, <-button`
<-x
and area<-y
of the argument graphical.
Note that both event<-position
and event<-area_position
reuse the point object
in the slot -position.
Defaults: The default graphical is the event<-receiver
of the event.
<-click_time, event->is_up, event<-multiclick
and class click_gesture.down event. See also event<-click_displacement,
event<-multiclick, event->is_up
and class click_gesture.<-display
on the associated event<-window.<-window.|frame|window] -> frame|window<-window
refers to the window in which the event occurred. If a window has the
event focus however,
event<-window
returns the window that has the focus rather than the window where the
pointer is.
get(Event, inside_sub_window, Frame)
will return the XPCE frame in which the event occurred.
get(Event, inside_sub_window, Frame, Window)
will return the window in which the event occurred, where Frame is the return value of the previous call. This call returns the actual window (not the window_decorator object) if the event occurred in a normal window. If the event occurred in a decoration (scroll_bar object, window-label) the window_decorator is returned.
This method is used by the Prolog defined class drag_and_drop_gesture
to locate the target for the drop operation which may be in another
window. See
$PCEHOME/prolog/lib/pce_drag_and_drop.pl.
<-id.
Otherwise it is a symbolic description of the depressed key. The
key-description is described with key_binding->function.master of an event is the master of its event<-receiver.
See‘visual
event<-master’for
details.Clicking is normally handled using a click_gesture object.
NOTE: When there are both recognisers for single- and double-click,
next step in a
multiclick sequence if it the down event is within 400 milliseconds of
previous down event and within 4 pixels displaced.
Bugs: These methods should read the corresponding X-resources.
<-id.
Backwards compatibility only.|frame|display] -> int|frame|display] -> int|frame|display] -> pointFor device objects
(and windows), the returned position is relative to the origin (device<-offset)
of the device. For other graphicals it is relative to the area<-x
and area<-y
of the graphical's area. For a display
object it is relative to the top-left corner of the display. See also event<-area_position.
The returned value is also stored in the -position slot.