path: root/devdocs/elisp/multiple-terminals.html

 <h3 class="section">Multiple Terminals</h3>     <p>Emacs represents each terminal as a <em>terminal object</em> data type (see <a href="terminal-type">Terminal Type</a>). 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: </p> <ul> <li> The name of the device used by the terminal (e.g., ‘<samp>:0.0</samp>’ or <samp>/dev/tty</samp>). </li>
<li> The terminal and keyboard coding systems used on the terminal. See <a href="terminal-i_002fo-encoding">Terminal I/O Encoding</a>. </li>
<li> The kind of display associated with the terminal. This is the symbol returned by the function <code>terminal-live-p</code> (i.e., <code>x</code>, <code>t</code>, <code>w32</code>, <code>ns</code>, or <code>pc</code>). See <a href="frames">Frames</a>. </li>
<li> A list of terminal parameters. See <a href="terminal-parameters">Terminal Parameters</a>. </li>
</ul> <p>There is no primitive for creating terminal objects. Emacs creates them as needed, such as when you call <code>make-frame-on-display</code> (described below). </p> <dl> <dt id="terminal-name">Function: <strong>terminal-name</strong> <em>&amp;optional terminal</em>
</dt> <dd><p>This function returns the file name of the device used by <var>terminal</var>. If <var>terminal</var> is omitted or <code>nil</code>, it defaults to the selected frame’s terminal. <var>terminal</var> can also be a frame, meaning that frame’s terminal. </p></dd>
</dl> <dl> <dt id="terminal-list">Function: <strong>terminal-list</strong>
</dt> <dd><p>This function returns a list of all live terminal objects. </p></dd>
</dl> <dl> <dt id="get-device-terminal">Function: <strong>get-device-terminal</strong> <em>device</em>
</dt> <dd><p>This function returns a terminal whose device name is given by <var>device</var>. If <var>device</var> is a string, it can be either the file name of a terminal device, or the name of an X display of the form ‘<samp><var>host</var>:<var>server</var>.<var>screen</var></samp>’. If <var>device</var> is a frame, this function returns that frame’s terminal; <code>nil</code> means the selected frame. Finally, if <var>device</var> 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. </p></dd>
</dl> <dl> <dt id="delete-terminal">Function: <strong>delete-terminal</strong> <em>&amp;optional terminal force</em>
</dt> <dd>
<p>This function deletes all frames on <var>terminal</var> and frees the resources used by it. It runs the abnormal hook <code>delete-terminal-functions</code>, passing <var>terminal</var> as the argument to each function. </p> <p>If <var>terminal</var> is omitted or <code>nil</code>, it defaults to the selected frame’s terminal. <var>terminal</var> can also be a frame, meaning that frame’s terminal. </p> <p>Normally, this function signals an error if you attempt to delete the sole active terminal, but if <var>force</var> is non-<code>nil</code>, you are allowed to do so. Emacs automatically calls this function when the last frame on a terminal is deleted (see <a href="deleting-frames">Deleting Frames</a>). </p>
</dd>
</dl> <dl> <dt id="delete-terminal-functions">Variable: <strong>delete-terminal-functions</strong>
</dt> <dd><p>An abnormal hook run by <code>delete-terminal</code>. Each function receives one argument, the <var>terminal</var> argument passed to <code>delete-terminal</code>. Due to technical details, the functions may be called either just before the terminal is deleted, or just afterwards. </p></dd>
</dl>  <p>A few Lisp variables are <em>terminal-local</em>; 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 <code>default-minibuffer-frame</code>, <code>defining-kbd-macro</code>, <code>last-kbd-macro</code>, and <code>system-key-alist</code>. They are always terminal-local, and can never be buffer-local (see <a href="buffer_002dlocal-variables">Buffer-Local Variables</a>). </p> <p>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 <code>DISPLAY</code> environment variable, or by the ‘<samp>--display</samp>’ option (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Initial-Options.html#Initial-Options">Initial Options</a> in <cite>The GNU Emacs Manual</cite>). Emacs can connect to other X displays via the command <code>make-frame-on-display</code>. Each X display has its own selected frame and its own minibuffer windows; however, only one of those frames is <em>the</em> selected frame at any given moment (see <a href="input-focus">Input Focus</a>). Emacs can even connect to other text terminals, by interacting with the <code>emacsclient</code> program. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html#Emacs-Server">Emacs Server</a> in <cite>The GNU Emacs Manual</cite>. </p>   <p>A single X server can handle more than one display. Each X display has a three-part name, ‘<samp><var>hostname</var>:<var>displaynumber</var>.<var>screennumber</var></samp>’. The first part, <var>hostname</var>, specifies the name of the machine to which the display is physically connected. The second part, <var>displaynumber</var>, 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, <var>screennumber</var>, 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. </p> <p>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 ‘<samp>w32</samp>’, and exists for compatibility, so that you could pass it to functions that expect a display name. </p> <dl> <dt id="make-frame-on-display">Command: <strong>make-frame-on-display</strong> <em>display &amp;optional parameters</em>
</dt> <dd>
<p>This function creates and returns a new frame on <var>display</var>, taking the other frame parameters from the alist <var>parameters</var>. <var>display</var> should be the name of an X display (a string). </p> <p>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 <code>make-frame</code> (see <a href="creating-frames">Creating Frames</a>). </p>
</dd>
</dl> <dl> <dt id="x-display-list">Function: <strong>x-display-list</strong>
</dt> <dd><p>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. </p></dd>
</dl> <dl> <dt id="x-open-connection">Function: <strong>x-open-connection</strong> <em>display &amp;optional xrm-string must-succeed</em>
</dt> <dd>
<p>This function opens a connection to the X display <var>display</var>, without creating a frame on that display. Normally, Emacs Lisp programs need not call this function, as <code>make-frame-on-display</code> calls it automatically. The only reason for calling it is to check whether communication can be established with a given X display. </p> <p>The optional argument <var>xrm-string</var>, if not <code>nil</code>, is a string of resource names and values, in the same format used in the <samp>.Xresources</samp> file. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/X-Resources.html#X-Resources">X Resources</a> in <cite>The GNU Emacs Manual</cite>. 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: </p> <div class="example"> <pre class="example">"*BorderWidth: 3\n*InternalBorder: 2\n"
</pre>
</div> <p>If <var>must-succeed</var> is non-<code>nil</code>, failure to open the connection terminates Emacs. Otherwise, it is an ordinary Lisp error. </p>
</dd>
</dl> <dl> <dt id="x-close-connection">Function: <strong>x-close-connection</strong> <em>display</em>
</dt> <dd><p>This function closes the connection to display <var>display</var>. Before you can do this, you must first delete all the frames that were open on that display (see <a href="deleting-frames">Deleting Frames</a>). </p></dd>
</dl>  <p>On some multi-monitor setups, a single X display outputs to more than one physical monitor. You can use the functions <code>display-monitor-attributes-list</code> and <code>frame-monitor-attributes</code> to obtain information about such setups. </p> <dl> <dt id="display-monitor-attributes-list">Function: <strong>display-monitor-attributes-list</strong> <em>&amp;optional display</em>
</dt> <dd>
<p>This function returns a list of physical monitor attributes on <var>display</var>, which can be a display name (a string), a terminal, or a frame; if omitted or <code>nil</code>, 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: </p> <dl compact> <dt>‘<samp>geometry</samp>’</dt> <dd>
<p>Position of the top-left corner of the monitor’s screen and its size, in pixels, as ‘<samp>(<var>x</var> <var>y</var> <var>width</var> <var>height</var>)</samp>’. Note that, if the monitor is not the primary monitor, some of the coordinates might be negative. </p> </dd> <dt>‘<samp>workarea</samp>’</dt> <dd>
<p>Position of the top-left corner and size of the work area (usable space) in pixels as ‘<samp>(<var>x</var> <var>y</var> <var>width</var> <var>height</var>)</samp>’. This may be different from ‘<samp>geometry</samp>’ 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. </p> </dd> <dt>‘<samp>mm-size</samp>’</dt> <dd>
<p>Width and height in millimeters as ‘<samp>(<var>width</var> <var>height</var>)</samp>’ </p> </dd> <dt>‘<samp>frames</samp>’</dt> <dd>
<p>List of frames that this physical monitor dominates (see below). </p> </dd> <dt>‘<samp>name</samp>’</dt> <dd>
<p>Name of the physical monitor as <var>string</var>. </p> </dd> <dt>‘<samp>source</samp>’</dt> <dd><p>Source of the multi-monitor information as <var>string</var>; e.g., ‘<samp>XRandr</samp>’ or ‘<samp>Xinerama</samp>’. </p></dd> </dl> <p><var>x</var>, <var>y</var>, <var>width</var>, and <var>height</var> are integers. ‘<samp>name</samp>’ and ‘<samp>source</samp>’ may be absent. </p> <p>A frame is <em>dominated</em> 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. </p> <p>Here’s an example of the data produced by this function on a 2-monitor display: </p> <div class="lisp"> <pre class="lisp">  (display-monitor-attributes-list)
  ⇒
  (((geometry 0 0 1920 1080) ;; <span class="roman">Left-hand, primary monitor</span>
    (workarea 0 0 1920 1050) ;; <span class="roman">A taskbar occupies some of the height</span>
    (mm-size 677 381)
    (name . "DISPLAY1")
    (frames #&lt;frame emacs@host *Messages* 0x11578c0&gt;
            #&lt;frame emacs@host *scratch* 0x114b838&gt;))
   ((geometry 1920 0 1680 1050) ;; <span class="roman">Right-hand monitor</span>
    (workarea 1920 0 1680 1050) ;; <span class="roman">Whole screen can be used</span>
    (mm-size 593 370)
    (name . "DISPLAY2")
    (frames)))
</pre>
</div> </dd>
</dl> <dl> <dt id="frame-monitor-attributes">Function: <strong>frame-monitor-attributes</strong> <em>&amp;optional frame</em>
</dt> <dd><p>This function returns the attributes of the physical monitor dominating (see above) <var>frame</var>, which defaults to the selected frame. </p></dd>
</dl> <p>On multi-monitor displays it is possible to use the command <code>make-frame-on-monitor</code> to make frames on the specified monitor. </p> <dl> <dt id="make-frame-on-monitor">Command: <strong>make-frame-on-monitor</strong> <em>monitor &amp;optional display parameters</em>
</dt> <dd><p>This function creates and returns a new frame on <var>monitor</var> located on <var>display</var>, taking the other frame parameters from the alist <var>parameters</var>. <var>monitor</var> should be the name of the physical monitor, the same string as returned by the function <code>display-monitor-attributes-list</code> in the attribute <code>name</code>. <var>display</var> should be the name of an X display (a string). </p></dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Multiple-Terminals.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Multiple-Terminals.html</a>
  </p>
</div>