elisp: Multiple Terminals
28.2 Multiple Terminals
=======================
Emacs represents each terminal as a “terminal object” data type (
Terminal Type). On GNU and Unix systems, Emacs can use multiple
terminals simultaneously in each session. On other systems, it can only
use a single terminal. Each terminal object has the following
attributes:
• The name of the device used by the terminal (e.g., ‘:0.0’ or
‘/dev/tty’).
• The terminal and keyboard coding systems used on the terminal.
Terminal I/O Encoding.
• The kind of display associated with the terminal. This is the
symbol returned by the function ‘terminal-live-p’ (i.e., ‘x’, ‘t’,
‘w32’, ‘ns’, or ‘pc’). Frames.
• A list of terminal parameters. Terminal Parameters.
There is no primitive for creating terminal objects. Emacs creates
them as needed, such as when you call ‘make-frame-on-display’ (described
below).
-- Function: terminal-name &optional terminal
This function returns the file name of the device used by TERMINAL.
If TERMINAL is omitted or ‘nil’, it defaults to the selected
frame’s terminal. TERMINAL can also be a frame, meaning that
frame’s terminal.
-- Function: terminal-list
This function returns a list of all live terminal objects.
-- Function: get-device-terminal device
This function returns a terminal whose device name is given by
DEVICE. If DEVICE is a string, it can be either the file name of a
terminal device, or the name of an X display of the form
‘HOST:SERVER.SCREEN’. If DEVICE is a frame, this function returns
that frame’s terminal; ‘nil’ means the selected frame. Finally, if
DEVICE is a terminal object that represents a live terminal, that
terminal is returned. The function signals an error if its
argument is none of the above.
-- Function: delete-terminal &optional terminal force
This function deletes all frames on TERMINAL and frees the
resources used by it. It runs the abnormal hook
‘delete-terminal-functions’, passing TERMINAL as the argument to
each function.
If TERMINAL is omitted or ‘nil’, it defaults to the selected
frame’s terminal. TERMINAL can also be a frame, meaning that
frame’s terminal.
Normally, this function signals an error if you attempt to delete
the sole active terminal, but if FORCE is non-‘nil’, you are
allowed to do so. Emacs automatically calls this function when the
last frame on a terminal is deleted (Deleting Frames).
-- Variable: delete-terminal-functions
An abnormal hook run by ‘delete-terminal’. Each function receives
one argument, the TERMINAL argument passed to ‘delete-terminal’.
Due to technical details, the functions may be called either just
before the terminal is deleted, or just afterwards.
A few Lisp variables are “terminal-local”; that is, they have a
separate binding for each terminal. The binding in effect at any time
is the one for the terminal that the currently selected frame belongs
to. These variables include ‘default-minibuffer-frame’,
‘defining-kbd-macro’, ‘last-kbd-macro’, and ‘system-key-alist’. They
are always terminal-local, and can never be buffer-local (
Buffer-Local Variables).
On GNU and Unix systems, each X display is a separate graphical
terminal. When Emacs is started from within the X window system, it
uses the X display specified by the ‘DISPLAY’ environment variable, or
by the ‘--display’ option ((emacs)Initial Options). Emacs can
connect to other X displays via the command ‘make-frame-on-display’.
Each X display has its own selected frame and its own minibuffer
windows; however, only one of those frames is _the_ selected frame at
any given moment (Input Focus). Emacs can even connect to other
text terminals, by interacting with the ‘emacsclient’ program.
(emacs)Emacs Server.
A single X server can handle more than one display. Each X display
has a three-part name, ‘HOSTNAME:DISPLAYNUMBER.SCREENNUMBER’. The first
part, HOSTNAME, specifies the name of the machine to which the display
is physically connected. The second part, DISPLAYNUMBER, is a
zero-based number that identifies one or more monitors connected to that
machine that share a common keyboard and pointing device (mouse, tablet,
etc.). The third part, SCREENNUMBER, identifies a zero-based screen
number (a separate monitor) that is part of a single monitor collection
on that X server. When you use two or more screens belonging to one
server, Emacs knows by the similarity in their names that they share a
single keyboard.
Systems that don’t use the X window system, such as MS-Windows, don’t
support the notion of X displays, and have only one display on each
host. The display name on these systems doesn’t follow the above 3-part
format; for example, the display name on MS-Windows systems is a
constant string ‘w32’, and exists for compatibility, so that you could
pass it to functions that expect a display name.
-- Command: make-frame-on-display display &optional parameters
This function creates and returns a new frame on DISPLAY, taking
the other frame parameters from the alist PARAMETERS. DISPLAY
should be the name of an X display (a string).
Before creating the frame, this function ensures that Emacs is set
up to display graphics. For instance, if Emacs has not processed X
resources (e.g., if it was started on a text terminal), it does so
at this time. In all other respects, this function behaves like
‘make-frame’ (Creating Frames).
-- Function: x-display-list
This function returns a list that indicates which X displays Emacs
has a connection to. The elements of the list are strings, and
each one is a display name.
-- Function: x-open-connection display &optional xrm-string
must-succeed
This function opens a connection to the X display DISPLAY, without
creating a frame on that display. Normally, Emacs Lisp programs
need not call this function, as ‘make-frame-on-display’ calls it
automatically. The only reason for calling it is to check whether
communication can be established with a given X display.
The optional argument XRM-STRING, if not ‘nil’, is a string of
resource names and values, in the same format used in the
‘.Xresources’ file. X Resources (emacs)X Resources. These
values apply to all Emacs frames created on this display,
overriding the resource values recorded in the X server. Here’s an
example of what this string might look like:
"*BorderWidth: 3\n*InternalBorder: 2\n"
If MUST-SUCCEED is non-‘nil’, failure to open the connection
terminates Emacs. Otherwise, it is an ordinary Lisp error.
-- Function: x-close-connection display
This function closes the connection to display DISPLAY. Before you
can do this, you must first delete all the frames that were open on
that display (Deleting Frames).
On some multi-monitor setups, a single X display outputs to more than
one physical monitor. You can use the functions
‘display-monitor-attributes-list’ and ‘frame-monitor-attributes’ to
obtain information about such setups.
-- Function: display-monitor-attributes-list &optional display
This function returns a list of physical monitor attributes on
DISPLAY, which can be a display name (a string), a terminal, or a
frame; if omitted or ‘nil’, it defaults to the selected frame’s
display. Each element of the list is an association list,
representing the attributes of a physical monitor. The first
element corresponds to the primary monitor. The attribute keys and
values are:
‘geometry’
Position of the top-left corner of the monitor’s screen and
its size, in pixels, as ‘(X Y WIDTH HEIGHT)’. Note that, if
the monitor is not the primary monitor, some of the
coordinates might be negative.
‘workarea’
Position of the top-left corner and size of the work area
(usable space) in pixels as ‘(X Y WIDTH HEIGHT)’. This may be
different from ‘geometry’ in that space occupied by various
window manager features (docks, taskbars, etc.) may be
excluded from the work area. Whether or not such features
actually subtract from the work area depends on the platform
and environment. Again, if the monitor is not the primary
monitor, some of the coordinates might be negative.
‘mm-size’
Width and height in millimeters as ‘(WIDTH HEIGHT)’
‘frames’
List of frames that this physical monitor dominates (see
below).
‘name’
Name of the physical monitor as STRING.
‘source’
Source of the multi-monitor information as STRING; e.g.,
‘XRandr’ or ‘Xinerama’.
X, Y, WIDTH, and HEIGHT are integers. ‘name’ and ‘source’ may be
absent.
A frame is “dominated” by a physical monitor when either the
largest area of the frame resides in that monitor, or (if the frame
does not intersect any physical monitors) that monitor is the
closest to the frame. Every (non-tooltip) frame (whether visible
or not) in a graphical display is dominated by exactly one physical
monitor at a time, though the frame can span multiple (or no)
physical monitors.
Here’s an example of the data produced by this function on a
2-monitor display:
(display-monitor-attributes-list)
⇒
(((geometry 0 0 1920 1080) ;; Left-hand, primary monitor
(workarea 0 0 1920 1050) ;; A taskbar occupies some of the height
(mm-size 677 381)
(name . "DISPLAY1")
(frames #<frame emacs@host *Messages* 0x11578c0>
#<frame emacs@host *scratch* 0x114b838>))
((geometry 1920 0 1680 1050) ;; Right-hand monitor
(workarea 1920 0 1680 1050) ;; Whole screen can be used
(mm-size 593 370)
(name . "DISPLAY2")
(frames)))
-- Function: frame-monitor-attributes &optional frame
This function returns the attributes of the physical monitor
dominating (see above) FRAME, which defaults to the selected frame.
Info Catalog
elisp: Creating Frames
elisp: Frames
elisp: Frame Geometry