From 20cb6c9b3298942cf769c5aab9db1f978db5f464 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 17 Jan 2009 16:31:21 +0000 Subject: [PATCH] (Frames): Document `frame-terminal' and `terminal-live-p'. (Multiple Displays): Document `make-frame-on-tty'. (Multiple Terminals): Document `terminal-list', `delete-terminal', `terminal-name', and `get-device-terminal'. --- doc/lispref/frames.texi | 230 ++++++++++++++++++++++------------------ 1 file changed, 126 insertions(+), 104 deletions(-) diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index dd4e987a2d..ae2eac87e5 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -13,12 +13,20 @@ or more Emacs windows, see @ref{Windows}. It's the kind of object that is called a ``window'' in the terminology of graphical environments; but we can't call it a ``window'' here, because Emacs uses that word in a different way. In Emacs Lisp, a @dfn{frame object} is a Lisp object -that represents a frame on the screen. +that represents a frame on the screen. @xref{Frame Type}. A frame initially contains a single main window and/or a minibuffer window; you can subdivide the main window vertically or horizontally into smaller windows. @xref{Splitting Windows}. + A @dfn{terminal} is a display device capable of displaying one or +more Emacs frames. On GNU and Unix systems, Emacs supports any number +of different terminals in one session, and can mix GUI and text-only +frames in the same session. + + Emacs represents each terminal on which it displays frames as a +special @dfn{terminal object} data type, see @ref{Terminal Type}. + @cindex terminal frame When Emacs runs on a text-only terminal, it starts with one @dfn{terminal frame}. If you create additional frames on the same @@ -51,10 +59,26 @@ The frame is displayed on an MS-DOS terminal. @end table @end defun +@defun frame-terminal &optional frame +This function returns the terminal object (@pxref{Terminal Type}) that +displays @var{frame}. If @var{frame} is @code{nil} or unspecified, it +defaults to the selected frame. +@end defun + +@defun terminal-live-p object +This predicate returns a non-@code{nil} value if @var{object} is a +terminal that is alive (i.e.@: was not deleted), and @code{nil} +otherwise. For live terminals, the return value indicates what kind +of frames are displayed on that terminal; the list of possible values +is the same as for @code{framep} above. +@end defun + @menu * Creating Frames:: Creating additional frames. * Multiple Displays:: Creating frames on other displays. +* Multiple Terminals:: Displaying on several different devices. * Frame Parameters:: Controlling frame size, position, font, etc. +* Terminal Parameters:: Parameters common for all frames on terminal. * Frame Titles:: Automatic updating of frame titles. * Deleting Frames:: Frames last until explicitly deleted. * Finding All Frames:: How to examine all existing frames. @@ -77,7 +101,6 @@ The frame is displayed on an MS-DOS terminal. * Text Terminal Colors:: Defining colors for text-only terminals. * Resources:: Getting resource values from the server. * Display Feature Testing:: Determining the features of a terminal. -* Multiple Terminals:: Displaying on several different devices. @end menu @xref{Display}, for information about the related topic of @@ -182,6 +205,16 @@ the other frame parameters from @var{parameters}. Aside from the Frames}). @end deffn +@deffn Command make-frame-on-tty tty type &optional parameters +This command creates a text-only frame on another text terminal. The +argument @var{tty} identifies the terminal device by its file name, +e.g., @file{/dev/ttys2}, and @var{type} gives the device type as a +string, e.g., @code{"vt100"}, to use for searching the +termcap/terminfo database for the entry describing capabilities of the +device. Optional argument @var{parameters} specifies additional +parameters for the frame. +@end deffn + @defun x-display-list This returns a list that indicates which X displays Emacs has a connection to. The elements of the list are strings, and each one is @@ -216,6 +249,71 @@ you can do this, you must first delete all the frames that were open on that display (@pxref{Deleting Frames}). @end defun +@node Multiple Terminals +@section Multiple Terminals +@cindex multiple terminals +@cindex multi-tty + + Emacs represents each terminal on which it displays frames as a +special @dfn{terminal object} data type, see @ref{Terminal Type}. The +terminal object has the following attributes: + +@itemize @bullet +@item +The name of the device used by the terminal (e.g., @file{/dev/tty}). + +@item +The terminal and keyboard coding systems (@pxref{Terminal I/O +Encoding}) used on the terminal. + +@item +The kind of frames (@pxref{Frames}) the terminal is displaying. + +@item +A list of the terminal parameters (@pxref{Terminal Parameters}). +@end itemize + + There's no primitive for creating terminal objects; Emacs creates +them as needed when you call one of the primitives, such as +@code{make-frame-on-tty} (@pxref{Multiple Displays}), that start +displaying on a new terminal. + +@defun terminal-list +This function return the list of all the terminal objects used by +Emacs to display frames in this session. +@end defun + +@defun delete-terminal &optional terminal force +This function deletes all frames on @var{terminal} and frees the +resources used by it. @var{terminal} can be a terminal object, a +frame (meaning that frame's terminal), or @code{nil} (meaning the +selected frame's terminal). Normally, the function signals an error +if you attempt to delete the sole active terminal, but if @var{force} +is non-@code{nil}, you are allowed to do so. This function runs the +hook @code{delete-terminal-functions}, passing each function a single +argument, @var{terminal}. +@end defun + +@defun terminal-name &optional terminal +This function returns the file name of the device used by +@var{terminal}. If @var{terminal} is omitted or @code{nil}, it +defaults to the selected frame's terminal. @var{terminal} can also be +a frame, meaning that frame's terminal. +@end defun + +@defun get-device-terminal device +This function is in a sense the opposite of @code{terminal-name}: it +returns a terminal whose device name is given by @var{device}. If +@var{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 +@samp{@var{host}:@var{server}.@var{screen}} (@pxref{Multiple +Displays}). If @var{device} is a frame, this function returns that +frame's terminal; @code{nil} means the selected frame. Finally, if +@var{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. +@end defun + @node Frame Parameters @section Frame Parameters @cindex frame parameters @@ -951,6 +1049,22 @@ Here is an example: @end example @end defun +@node Terminal Parameters +@section Terminal Parameters +@cindex terminal parameters + + This subsection describes how to read and change the parameter +values of a terminal. + +@defun terminal-parameters &optional terminal +@end defun + +@defun terminal-parameter terminal parameter +@end defun + +@defun set-terminal-parameter terminal parameter value +@end defun + @node Frame Titles @section Frame Titles @cindex frame title @@ -1326,6 +1440,16 @@ This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. @xref{Misc Events}. +@defun suspend-frame +@end defun + +@c FIXME: xref to suspend-emacs, and xref there. +@defun suspend-tty &optional tty +@end defun + +@defun resume-tty &optional tty +@end defun + @node Raising and Lowering @section Raising and Lowering Frames @@ -2242,108 +2366,6 @@ The functions @code{x-pixel-width} and @code{x-pixel-height} return the width and height of an X Window frame, measured in pixels. @end ignore -@node Multiple Terminals -@section Multiple Terminals -@cindex multiple terminals -@cindex multi-tty - - A @dfn{terminal} is a display device capable of displaying one or -more Emacs frames. On GNU and Unix systems, Emacs supports any number -of different terminals in one session, and can mix GUI and text-only -frames in the same session. - - Emacs represents each terminal on which it displays frames as a -special @dfn{terminal object} data type, see @ref{Terminal Type}. The -terminal object has a unique integer identifier and the following -attributes: - -@itemize @bullet -@item -The name of the device used by the terminal (e.g., @file{/dev/tty}). - -@item -The terminal and keyboard coding systems (@pxref{Terminal I/O -Encoding}) used on the terminal. - -@item -The type of frames (@pxref{Frames}) the terminal is displaying. - -@item -A list of the terminal parameters (@pxref{Terminal Parameters}). -@end itemize - -@c This is still under construction. - -@defun frame-terminal -@end defun - -@defun get-device-terminal device -@end defun - -@defun terminal-list -@end defun - -@menu -* Low-level Terminal:: Low-level manipulation of terminal objects. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frames on Other TTY devices:: Creating frames on other terminal devices. -@end menu - -@node Low-level Terminal -@subsection Low-level Access to Terminals - - This subsection describes low-level primitives for accessing and -manipulating Emacs terminal objects. There's no primitive for -creating terminal objects; Emacs creates them as needed when you call -one of the primitives, such as @code{make-frame-on-tty} (@pxref{Frames -on Other TTY devices}), that start displaying on a new terminal. - -@defun suspend-tty &optional tty -@end defun - -@defun resume-tty &optional tty -@end defun - -@defun terminal-live-p object -@end defun - -@defun terminal-name &optional terminal -@end defun - -@defun delete-terminal &optional terminal force -@end defun - -@node Terminal Parameters -@subsection Terminal Parameters -@cindex terminal parameters - - This subsection describes how to read and change the parameter -values of a terminal. - -@defun terminal-parameters &optional terminal -@end defun - -@defun terminal-parameter terminal parameter -@end defun - -@defun set-terminal-parameter terminal parameter value -@end defun - -@defun environment &optional frame -@end defun - -@defvar initial-environment -@end defvar - -@node Frames on Other TTY devices -@subsection Frames on Other TTY devices - - This subsection documents functions related to displaying Emacs -frames on a terminal device other than the current one. - -@defun make-frame-on-tty tty type &optional parameters -@end defun - @ignore arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba -- 2.20.1