An event is a CLIM object that represents some sort of user gesture (such as moving the pointer or pressing a key on the keyboard) or that corresponds to some sort of notification from the display server. Event objects store such things as the sheet associated with the event, the x and y position of the pointer within that sheet, the key name or character corresponding to a key on the keyboard, and so forth.
The following shows all the event classes, with all classes indented to the right of their superclasses:
event
device-event
keyboard-event
key-press-event
key-release-event
pointer-event
pointer-button-event
pointer-button-press-event
pointer-mouse-wheel-event
pointer-button-release-event
pointer-button-hold-event
pointer-motion-event
pointer-enter-event
pointer-exit-event
window-event
window-configuration-event
window-repaint-event
timer-event
Summary: The protocol class that corresponds to any sort of event. If you want to create a new class that behaves like an event, it should be a subclass of event. Subclasses of event must obey the event protocol.
All of the event classes are immutable.
eventp object
Summary: Returns t if object is an event; otherwise, it returns nil.
Summary: All subclasses of event must take a :timestamp initarg, which is used to specify the timestamp for the event.
event-timestamp Generic Function
event-timestamp event
Summary: Returns an integer that is a monotonically increasing timestamp for the event event. The timestamp must have at least as many bits of precision as a fixnum.
event-type event
Summary: For the event event, returns a keyword with the same name as the class name, except stripped of the "-event" ending. For example, the keyword :key-press is returned by event-type for an event whose class is key-press-event.
All event classes must implement methods for event-type and event-timestamp.
:sheet
:modifier-state Initargs
Summary: The class that corresponds to any sort of device event. This is a subclass of event.
All subclasses of device-event must take the :sheet and :modifier-state initargs, which are used to specify the sheet and modifier state components for the event.
event-sheet device-event
Summary: Returns the sheet associated with the event device-event.
event-modifier-state Generic Function
event-modifier-state device-event
Summary: Returns a value that encodes the state of all the modifier keys on the keyboard. This will be a mask consisting of the logical-or of +shift-key+, +control-key+, +meta-key+, +super-key+, and +hyper-key+.
All device event classes must implement methods for event-sheet and event-modifier-state.
Summary: The class corresponding to any keyboard event; a subclass of device-event.
All subclasses of keyboard-event must take the :key-name initarg, which is used to specify the key name component for the event.
keyboard-event-key-name Generic Function
keyboard-event-key-name keyboard-event
Summary: Returns the name of the key pressed or released in a keyboard event. This will be a symbol whose value is port-specific. Key names corresponding to standard characters such as the alphanumerics will be symbols in the keyword package.
keyboard-event-character Generic Function
keyboard-event-character keyboard-event
Summary: Returns the character associated with the event keyboard-event, if there is any.
All keyboard event classes must implement methods for keyboard-event-key-name and keyboard-event-character.
key-press-event
key-release-event Classes
Summary: The classes corresponding to key press or release events. They are subclasses of keyboard-event.
:pointer
:button
:x
:y Initargs
Summary: The class corresponding to any pointer event. This is a subclass of device-event.
All subclasses of pointer-event must take the :pointer, :button, :x, and :y initargs, which are used to specify the pointer object, pointer button, and native x and y position of the pointer at the time of the event. The sheet's x and y positions are derived from the supplied native x and y positions and the sheet itself.
pointer-event-x Generic Function
pointer-event-x pointer-event
pointer-event-y Generic Function
pointer-event-y pointer-event
Summary: Returns the x and y position of the pointer at the time the event occurred, in the coordinate system of the sheet that received the event. All pointer events must implement a method for these generic functions.
pointer-event-native-x Generic Function
pointer-event-native-x pointer-event
pointer-event-native-y Generic Function
pointer-event-native-y pointer-event
Summary: Returns the x and y position of the pointer at the time the event occurred, in the pointer's native coordinate system. All pointer events must implement a method for these generic functions.
pointer-event-pointer Generic Function
pointer-event-pointer pointer-event
Summary: Returns the pointer object to which this event refers.
pointer-event-button Generic Function
pointer-event-button pointer-event
Summary: Returns an integer, the number of the pointer button that was pressed. Programs should compare this against the constants +pointer-left-button+, +pointer-middle-button+, +pointer-right-button+ and +pointer-wheel+ to see what value was returned.
All pointer event classes must implement methods for pointer-event-x, pointer-event-y, pointer-event-native-x, pointer-event-native-y, pointer-event-pointer, and pointer-event-button.
pointer-event-shift-mask Generic Function
pointer-event-shift-mask pointer-button-event
Summary: Returns the state of the keyboard's shift keys when pointer-button-event occurred.
Summary: The class corresponding to any sort of pointer button event. It is a subclass of pointer-event.
pointer-button-press-event
pointer-button-release-event
pointer-button-hold-event Classes
Summary: The classes that correspond to a pointer button press, button release, and click-and-hold events. These are subclasses of pointer-button-event.
pointer-mouse-wheel-event Class
Summary: The class that corresponds to rotating the wheel on a mouse with modifiers, which can be shift, control or both. This is a subclass of pointer-button-press-event.
When pointer-event-button is called on an instance of pointer-mouse-wheel-event it returns +pointer-wheel+.
pointer-mouse-wheel-event-amount Generic Function
pointer-mouse-wheel-event-amount pointer-mouse-wheel-event
Summary: Returns the number of ticks that the wheel rotated. It is positive when the top of the wheel is pushed away from the user, and negative when it is pulled towards the user.
pointer-button-click-event
pointer-button-double-click-event
pointer-button-click-and-hold-event Classes
Summary: The classes that correspond to a pointer button press followed by (respectively) a button release, another button press, or pointer motion. These are subclasses of pointer-button-event. Ports are not required to generate these events.
Summary: The class that corresponds to any sort of pointer motion event. This is a subclass of pointer-event.
pointer-enter-event
pointer-exit-event Classes
Summary: The classes that correspond to a pointer enter or exit event. This is a subclass of pointer-motion-event.
Summary: The class that corresponds to any sort of windowing event. This is a subclass of device-event.
All subclasses of window-event must take a :region initarg, which is used to specify the damage region associated with the event.
window-event-region Generic Function
window-event-region window-event
Summary: Returns the region of the sheet that is affected by a window event.
window-event-native-region Generic Function
window-event-native-region window-event
Summary: Returns the region of the sheet in native coordinates.
window-event-mirrored-sheet Generic Function
window-event-mirrored-sheet window-event
Summary: Returns the mirrored sheet that is attached to the mirror on which the event occurred.
All window event classes must implement methods for window-event-region, window-event-native-region, and window-event-mirrored-sheet.
window-configuration-event Class
Summary: The class that corresponds to a window changing its size or position. This is a subclass of window-event.
Summary: The class that corresponds to a request to repaint the window. This is a subclass of window-event.
Summary: The class that corresponds to a timeout event. This is a subclass of event.
+pointer-left-button+
+pointer-middle-button+
+pointer-right-button+
+pointer-wheel+ Constants
Summary: Constants that correspond to the left, middle, right button and wheel on a pointing device. pointer-event-button will returns one of these four values.
+shift-key+
+control-key+
+meta-key+
+super-key+
+hyper-key+ Constants
Summary: Constants that correspond to the SHIFT, CONTROL, META, SUPER, and HYPER modifier keys being held down on the keyboard. These constants must be powers of 2 so that they can be combined with logical-or and tested with logtest. event-modifier-state will return some combination of these values.
CLIM does not provide default key mappings for META, HYPER, or SUPER modifier keys, as they are keyboard/X-server specific.
key-modifier-state-match-p Macro
key-modifier-state-match-p button modifier-state &body clauses
Summary: This macro generates code that will check whether the modifier state modifier-state and the pointer button button match all of the clauses. clauses are implicitly grouped by and. Matching a button or a modifier means that the modifier state indicates that the button or modifier is pressed.
A clause may be one of:
:left, :middle, or :right):shift, :control, :meta, :super, or :hyper)(and [clause]+)(or [clause]+)(not clause)
When the mouse wheel is used without a modifier key, it is interpreted as scrolling. The innermost pane that has a scroll bar and contains the mouse is scrolled vertically if it has a vertical scroll bar, otherwise it is scrolled horizontally.
Note: For gadgets, in particular for list-pane, the focus must be on the gadget for it to scroll.
If the mouse wheel is used with a modifier key, which can be shift or control, then an event is generated. The event is of type pointer-mouse-wheel-event, which is a subtype pointer-button-press-event. pointer-event-button returns +pointer-wheel+ for such an event.
In addition to all the information that pointer-button-press-event contains, pointer-mouse-wheel-event also contains the amount of wheel rotation. This can be found by the reader pointer-mouse-wheel-event-amount, which returns a number. The number is positive when the top of the wheel is pushed away from the user, and negative when it is pulled towards the user. The units of the number are ticks of the wheel, and normally it is either 1 or -1.
The function add-gesture-name and macro define-gesture-name, when used with type :pointer-button, can also take :wheel as button-name (in addition to :left, :middle and :right). CLIM adds (by using add-gesture-name) two gestures, :zoom for (:wheel :control), and :rotate for (:wheel :shift). However, it does not make any assumptions about what these gestures actually do. You can define your own gestures as well.
The arglist, tester-arglist and doc-arglist arguments in the translator macros (define-presentation-translator, define-presentation-to-command-translator and define-presentation-action) can also contain amount, in addition to the already documented "canonical" symbols that are listed in the documentation of define-presentation-translator. When the gesture argument specifies a gesture that is mapped to a wheel event (such as :zoom or :rotate above), the variable amount is bound to the amount that pointer-mouse-wheel-event-amount would return for the event. In another cases it is always 0.
For example, assuming you have a frame my-frame, and two functions my-zoom-function-up and my-zoom-function-down that know how to zoom windows in this frame, then the two forms below can be used to invoke these functions when the user moves the mouse wheel while pressing the control button:
(define-frame-command my-frame my-zoom-command ((window window)
(amount t))
(if (> amount 0)
(my-zoom-function-up window)
(my-zoom-function-down window)))
(define-presentation-to-command-translator my-zoom-trans
(t my-zoom-command my-frame
:gesture :zoom)
(window amount)
(list window amount))
CLIM 2.0 User Guide - 01 Dec 2021 19:39:01