22.7.12 Miscellaneous System Events

A few other event types represent occurrences within the system.

text-conversion

This kind of event is sent after a system-wide input method performs an edit to one or more buffers.

Once the event is sent, the input method may already have made changes to multiple buffers inside many different frames. To determine which buffers have been changed, and what edits have been made to them, use the variable text-conversion-edits, which is set prior to each text-conversion event being sent; it is a list of the form:

((buffer beg end ephemeral) ...)

Where ephemeral is the buffer which was modified, beg and end are markers set to the positions of the edit at the time it was completed, and ephemeral is either a string, containing any text which was inserted (or any text before point which was deleted), t, meaning that the edit is a temporary edit made by the input method, or nil, meaning that some text was deleted after point.

Whether or not this event is sent depends on the value of the buffer-local variable text-conversion-style, which determines how an input method that wishes to make edits to buffer contents will behave.

This variable can have one of four values:

nil

This means that the input method will be disabled entirely, and key events will be sent instead of text conversion events.

action

This means that the input method will be enabled, but RET will be sent whenever the input method wants to insert a new line.

password

This is largely identical to action, but also requests an input method capable of inserting ASCII characters, and instructs it not to save input in locations from which it might be subsequently retrieved by features of the input method that cannot handle sensitive information, such as text suggestions.

t

This, or any other value, means that the input method will be enabled and make edits followed by text-conversion events.

Changes to the value of this variable will only take effect upon the next redisplay after the buffer becomes the selected buffer of a frame. If you need to disable text conversion in a way that takes immediate effect, call the function set-text-conversion-style instead. This has the potential to lock up the input method for a significant amount of time, and should be used with care.

In addition, text conversion is automatically disabled after a prefix key is read by the command loop or read-key-sequence. This can be disabled by setting or binding the variable disable-inhibit-text-conversion to a non-nil value.

(delete-frame (frame))

This kind of event indicates that the user gave the window manager a command to delete a particular window, which happens to be an Emacs frame.

The standard definition of the delete-frame event is to delete frame.

(iconify-frame (frame))

This kind of event indicates that the user iconified frame using the window manager. Its standard definition is ignore; since the frame has already been iconified, Emacs has no work to do. The purpose of this event type is so that you can keep track of such events if you want to.

(make-frame-visible (frame))

This kind of event indicates that the user deiconified frame using the window manager. Its standard definition is ignore; since the frame has already been made visible, Emacs has no work to do.

(touch-end (position))

This kind of event indicates that the user’s finger moved off the mouse wheel or the touchpad. The position element is a mouse position list (see Click Events), specifying the position of the mouse cursor when the finger moved off the mouse wheel.

(wheel-up position clicks lines pixel-delta)

(wheel-down position clicks lines pixel-delta)

These events are generated by moving a mouse wheel. The position element is a mouse position list (see Click Events), specifying the position of the mouse cursor when the event occurred.

clicks, if present, is the number of times that the wheel was moved in quick succession. See Repeat Events. lines, if present and not nil, is the positive number of screen lines that should be scrolled (either up, when the event is wheel-up, or down when the event is wheel-down). pixel-delta, if present, is a cons cell of the form (x . y), where x and y are the numbers of pixels by which to scroll in each axis, a.k.a. pixelwise deltas. Usually, only one of the two will be non-zero, the other will be either zero or very close to zero; the larger number indicates the axis to scroll the window. When the variable mwheel-coalesce-scroll-events is nil, the scroll commands ignore the lines element, even if it’s non-nil, and use the pixel-delta data instead; in that case, the direction of scrolling is determined by the sign of the pixelwise deltas, and the direction (up or down) implied by the event kind is ignored.

You can use these x and y pixelwise deltas to determine how much the mouse wheel has actually moved at pixel resolution. For example, the pixelwise deltas could be used to scroll the display at pixel resolution, exactly according to the user’s turning the mouse wheel. This pixelwise scrolling is possible only when mwheel-coalesce-scroll-events is nil, and in general the pixel-delta data is not generated when that variable is non-nil.

The wheel-up and wheel-down events are generated only on some kinds of systems. On other systems, other events like mouse-4 and mouse-5 are used instead. Portable code should handle both wheel-up and wheel-down events as well as the events specified in the variables mouse-wheel-up-event and mouse-wheel-down-event, defined in mwheel.el. Beware that for historical reasons the mouse-wheel-up-event is the variable that holds an event that should be handled similarly to wheel-down and vice versa.

The same holds for the horizontal wheel movements which are usually represented by wheel-left and wheel-right events, but for which portable code should also obey the variables mouse-wheel-left-event and mouse-wheel-right-event, defined in mwheel.el. However, some mice also generate other events at the same time as they’re generating these scroll events which may get in the way. The way to fix this is generally to unbind these events (for instance, mouse-6 or mouse-7, but this is very hardware and operating system dependent).

(pinch position dx dy scale angle)

This kind of event is generated by the user performing a “pinch” gesture by placing two fingers on a touchpad and moving them towards or away from each other. position is a mouse position list (see Click Events) that provides the position of the mouse pointer when the event occurred, dx is the change in the horizontal distance between the fingers since the last event in the same sequence, dy is the vertical movement of the fingers since the last event in the same sequence, scale is the ratio of the current distance between the fingers to that distance at the start of the sequence, and angle is the angular difference in degrees between the direction of the line connecting the fingers in this event and the direction of that line in the last event of the same sequence.

As pinch events are only sent at the beginning or during a pinch sequence, they do not report gestures where the user moves two fingers on a touchpad in a rotating fashion without pinching the fingers.

All arguments after position are floating point numbers.

This event is usually sent as part of a sequence, which begins with the user placing two fingers on the touchpad, and ends with the user removing those fingers. dx, dy, and angle will be 0.0 in the first event of a sequence; subsequent events will report non-zero values for these members of the event structure.

dx and dy are reported in imaginary relative units, in which 1.0 is the width and height of the touchpad respectively. They are usually interpreted as being relative to the size of the object beneath the gesture: image, window, etc.

(preedit-text arg)

This event is sent when a system input method tells Emacs to display some text to indicate to the user what will be inserted. The contents of arg are dependent on the window system being used.

On X, arg is a string describing some text to place behind the cursor. It can be nil, which means to remove any text previously displayed.

On PGTK frames (see Frames), arg is a list of strings with information about their color and underline attributes. It has the following form:

   ((string1
     (ul . underline-color)
     (bg . background-color)
     (fg . foreground-color))
    (string2
     (ul . underline-color)
     (bg . background-color)
     (fg . foreground-color))
    …
   )

Color information can be omitted, leaving just the text of the strings. underline-color can be t, meaning underlined text with default underline color, or it can be a string, the name of the color to draw the underline.

This is a special event (see Special Events), which normally should not be bound by the user to any command. Emacs will typically display the text contained in the event in an overlay behind point when it is received.

(drag-n-drop position files)

This kind of event is generated when a group of files is selected in an application outside of Emacs, and then dragged and dropped onto an Emacs frame.

The element position is a list describing the position of the event, in the same format as used in a mouse-click event (see Click Events), and files is the list of file names that were dragged and dropped. The usual way to handle this event is by visiting these files.

This kind of event is generated, at present, only on some kinds of systems.

help-echo

This kind of event is generated when a mouse pointer moves onto a portion of buffer text which has a help-echo text property. The generated event has this form:

(help-echo frame help window object pos)

The precise meaning of the event parameters and the way these parameters are used to display the help-echo text are described in Text help-echo.

sigusr1

sigusr2

These events are generated when the Emacs process receives the signals SIGUSR1 and SIGUSR2. They contain no additional data because signals do not carry additional information. They can be useful for debugging (see Entering the Debugger on an Error).

To catch a user signal, bind the corresponding event to an interactive command in the special-event-map (see Controlling the Active Keymaps). The command is called with no arguments, and the specific signal event is available in last-input-event (see Miscellaneous Event Input Features. For example:

(defun sigusr-handler ()
  (interactive)
  (message "Caught signal %S" last-input-event))

(keymap-set special-event-map "<sigusr1>" 'sigusr-handler)

To test the signal handler, you can make Emacs send a signal to itself:

(signal-process (emacs-pid) 'sigusr1)

language-change

This kind of event is generated on MS-Windows when the input language has changed. This typically means that the keyboard keys will send to Emacs characters from a different language. The generated event has this form:

(language-change frame codepage language-id)

Here frame is the frame which was current when the input language changed; codepage is the new codepage number; and language-id is the numerical ID of the new input language. The coding-system (see Coding Systems) that corresponds to codepage is cpcodepage or windows-codepage. To convert language-id to a string (e.g., to use it for various language-dependent features, such as set-language-environment), use the w32-get-locale-info function, like this:

;; Get the abbreviated language name, such as "ENU" for English
(w32-get-locale-info language-id)
;; Get the full English name of the language,
;; such as "English (United States)"
(w32-get-locale-info language-id 4097)
;; Get the full localized name of the language
(w32-get-locale-info language-id t)

end-session

This event is generated on MS-Windows when the operating system informs Emacs that the user terminated the interactive session, or that the system is shutting down. The standard definition of this event is to invoke the kill-emacs command (see Killing Emacs) so as to shut down Emacs in an orderly fashion; if there are unsaved changes, this will produce auto-save files (see Auto-Saving) that the user can use after restarting the session to restore the unsaved edits.

If one of these events arrives in the middle of a key sequence—that is, after a prefix key—then Emacs reorders the events so that this event comes either before or after the multi-event key sequence, not within it.

Some of these special events, such as delete-frame, invoke Emacs commands by default; others are not bound. If you want to arrange for a special event to invoke a command, you can do that via special-event-map. The command you bind to a function key in that map can then examine the full event which invoked it in last-input-event. See Special Events.