25.5.6 Working With Events

SXEmacs provides primitives for creating, copying, and destroying event objects. Many functions that return events take an event object as an argument and fill in the fields of this event; or they make accept either an event object or nil, creating the event object first in the latter case.

Function: make-event &optional type plist

This function creates a new event structure. If no arguments are specified, the created event will be empty. To specify the event type, use the type argument. The allowed types are empty, key-press, button-press, button-release, motion, or misc-user.

plist is a property list, the properties being compatible to those returned by event-properties. For events other than empty, it is mandatory to specify certain properties. For empty events, plist must be nil.

The list is canonicalized, which means that if a property keyword is present more than once, only the first instance is taken into account. Specifying an unknown or illegal property signals an error.

The following properties are allowed:

channel

The event channel. This is a frame or a console. For mouse events (of type button-press, button-release and motion), this must be a frame. For key-press events, it must be a console. If channel is unspecified by plist, it will be set to the selected frame or selected console, as appropriate.

key

The event key. This is either a symbol or a character. It is allowed (and required) only for key-press events.

button

The event button. This an integer, either 1, 2 or 3. It is allowed only for button-press and button-release events.

modifiers

The event modifiers. This is a list of modifier symbols. It is allowed for key-press, button-press, button-release and motion events.

x

The event X coordinate. This is an integer. It is relative to the channel’s root window, and is allowed for button-press, button-release and motion events.

y

The event Y coordinate. This is an integer. It is relative to the channel’s root window, and is allowed for button-press, button-release and motion events. This means that, for instance, to access the toolbar, the y property will have to be negative.

timestamp

The event timestamp, a non-negative integer. Allowed for all types of events.

WARNING: the event object returned by this function may be a reused one; see the function deallocate-event.

The events created by make-event can be used as non-interactive arguments to the functions with an (interactive "e") specification.

Here are some basic examples of usage:

;; Create an empty event.
(make-event)
     ⇒ #<empty-event>

;; Try creating a key-press event.
(make-event 'key-press)
     error→ Undefined key for keypress event

;; Creating a key-press event, try 2
(make-event 'key-press '(key home))
     ⇒ #<keypress-event home>

;; Create a key-press event of dubious fame.
(make-event 'key-press '(key escape modifiers (meta alt control shift)))
     ⇒ #<keypress-event control-meta-alt-shift-escape>

;; Create a M-button1 event at coordinates defined by variables
;; x and y.
(make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
     ⇒ #<buttondown-event meta-button1>

;; Create a similar button-release event.
(make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
     ⇒ #<buttonup-event meta-button1up>

;; Create a mouse-motion event.
(make-event 'motion '(x 20 y 30))
     ⇒ #<motion-event 20, 30>

(event-properties (make-event 'motion '(x 20 y 30)))
     ⇒ (channel #<x-frame "emacs" 0x8e2> x 20 y 30
         modifiers nil timestamp 0)

In conjunction with event-properties, you can use make-event to create modified copies of existing events. For instance, the following code will return an equal copy of event:

(make-event (event-type event)
            (event-properties event))

Note, however, that you cannot use make-event as the generic replacement for copy-event, because it does not allow creating all of the event types.

To create a modified copy of an event, you can use the canonicalization feature of plist. The following example creates a copy of event, but with modifiers reset to nil.

(make-event (event-type event)
            (append '(modifiers nil)
                    (event-properties event)))

Function: copy-event event1 &optional event2

This function makes a copy of the event object event1. If a second event argument event2 is given, event1 is copied into event2 and event2 is returned. If event2 is not supplied (or is nil) then a new event will be made, as with make-event.

Function: deallocate-event event

This function allows the given event structure to be reused. You MUST NOT use this event object after calling this function with it. You will lose.

It is not necessary to call this function, as event objects are garbage-collected like all other objects; however, it may be more efficient to explicitly deallocate events when you are sure that it is safe to do so.