2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1995, 1996 Ben Wing.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/consoles-devices.info
6 @node Consoles and Devices, Positions, Frames, top
7 @chapter Consoles and Devices
11 A @dfn{console} is an object representing a single input connection
12 to XEmacs, such as an X display or a TTY connection. It is possible
13 for XEmacs to have frames on multiple consoles at once (even on
14 heterogeneous types -- you can simultaneously have a frame on an
15 X display and a TTY connection). Normally, there is only one
18 A @dfn{device} is an object representing a single output device, such
19 as a particular screen on an X display. (Usually there is exactly one
20 device per X console connection, but there may be more than one if you
21 have a multi-headed X display. For TTY connections, there is always
22 exactly one device per console.)
24 Each device has one or more @dfn{frames} in which text can be
25 displayed. For X displays and the like, a frame corresponds to the
26 normal window-system concept of a window. Frames can overlap, be
27 displayed at various locations within the display, be resized, etc. For
28 TTY, only one frame can be displayed at a time, and it occupies the
29 entire TTY display area.
31 However, you can still define multiple frames and switch between them.
32 Their contents are entirely separate from each other. These sorts of
33 frames resemble the ``virtual console'' capability provided under Linux
34 or the multiple screens provided by the multiplexing program
35 @samp{screen} under Unix.
37 When you start up XEmacs, an initial console and device are created to
38 receive input and display frames on. This will either be an X display
39 or a TTY connection, depending on what mode you started XEmacs in (this
40 is determined by the @samp{DISPLAY} environment variable, the
41 @samp{-nw}, @samp{-t} and @samp{-display} command-line options, etc.).
43 You can connect to other X displays and TTY connections by creating
44 new console objects, and to other X screens on an existing display by
45 creating new device objects, as described below. Many functions (for
46 example the frame-creation functions) take an optional device argument
47 specifying which device the function pertains to. If the argument is
48 omitted, it defaults to the selected device (see below).
50 @defun consolep object
51 This returns non-@code{nil} if @var{object} is a console.
55 This returns non-@code{nil} if @var{object} is a device.
59 * Basic Console Functions:: Functions for working with consoles.
60 * Basic Device Functions:: Functions for working with devices.
61 * Console Types and Device Classes::
62 I/O and color characteristics.
63 * Connecting to a Console or Device::
64 * The Selected Console and Device::
65 * Console and Device I/O:: Controlling input and output.
68 @node Basic Console Functions
69 @section Basic Console Functions
72 This function returns a list of all existing consoles.
75 @defun console-device-list &optional console
76 This function returns a list of all devices on @var{console}. If
77 @var{console} is @code{nil}, the selected console will be used.
80 @node Basic Device Functions
81 @section Basic Device Functions
84 This function returns a list of all existing devices.
87 @defun device-or-frame-p object
88 This function returns non-@code{nil} if @var{object} is a device or
89 frame. This function is useful because devices and frames are similar
90 in many respects and many functions can operate on either one.
93 @defun device-frame-list device
94 This function returns a list of all frames on @var{device}.
97 @defun frame-device frame
98 This function returns the device that @var{frame} is on.
101 @node Console Types and Device Classes
102 @section Console Types and Device Classes
104 Every device is of a particular @dfn{type}, which describes how the
105 connection to that device is made and how the device operates, and
106 a particular @dfn{class}, which describes other characteristics of
107 the device (currently, the color capabilities of the device).
109 The currently-defined device types are
113 A connection to an X display (such as @samp{willow:0}).
116 A connection to a tty (such as @samp{/dev/ttyp3}).
119 A stdio connection. This describes a device for which input and output
120 is only possible in a stream-like fashion, such as when XEmacs in running
121 in batch mode. The very first device created by XEmacs is a terminal
122 device and is used to print out messages of various sorts (for example,
123 the help message when you use the @samp{-help} command-line option).
126 The currently-defined device classes are
132 A grayscale device (a device that can display multiple shades of gray,
136 A device that can only display two colors (e.g. black and white).
139 @defun device-type device
140 This function returns the type of @var{device}. This is a symbol whose
141 name is one of the device types mentioned above.
144 @defun device-or-frame-type device-or-frame
145 This function returns the type of @var{device-or-frame}.
148 @defun device-class device
149 This function returns the class (color behavior) of @var{device}. This
150 is a symbol whose name is one of the device classes mentioned above.
153 @defun valid-device-type-p device-type
154 This function returns whether @var{device-type} (which should be a symbol)
155 species a valid device type.
158 @defun valid-device-class-p device-class
159 This function returns whether @var{device-class} (which should be a symbol)
160 species a valid device class.
163 @defvar terminal-device
164 This variable holds the initial terminal device object, which
165 represents XEmacs's stdout.
168 @node Connecting to a Console or Device
169 @section Connecting to a Console or Device
171 @defun make-device &optional type device-data
172 This function creates a new device.
175 The following two functions create devices of specific types and are
176 written in terms of @code{make-device}.
178 @defun make-tty-device &optional tty terminal-type
179 This function creates a new tty device on @var{tty}. This also creates
180 the tty's first frame. @var{tty} should be a string giving the name of
181 a tty device file (e.g. @samp{/dev/ttyp3} under SunOS et al.), as
182 returned by the @samp{tty} command issued from the Unix shell. A value
183 of @code{nil} means use the stdin and stdout as passed to XEmacs from
184 the shell. If @var{terminal-type} is non-@code{nil}, it should be a
185 string specifying the type of the terminal attached to the specified
186 tty. If it is @code{nil}, the terminal type will be inferred from the
187 @samp{TERM} environment variable.
190 @defun make-x-device &optional display argv-list
191 This function creates a new device connected to @var{display}. Optional
192 argument @var{argv-list} is a list of strings describing command line
196 @defun delete-device device
197 This function deletes @var{device}, permanently eliminating it from use.
198 This disconnects XEmacs's connection to the device.
201 @defvar create-device-hook
202 This variable, if non-@code{nil}, should contain a list of functions,
203 which are called when a device is created.
206 @defvar delete-device-hook
207 This variable, if non-@code{nil}, should contain a list of functions,
208 which are called when a device is deleted.
211 @defun console-live-p object
212 This function returns non-@code{nil} if @var{object} is a console that
213 has not been deleted.
216 @defun device-live-p object
217 This function returns non-@code{nil} if @var{object} is a device that
218 has not been deleted.
221 @defun device-x-display device
222 This function returns the X display which @var{device} is connected to,
223 if @var{device} is an X device.
226 @node The Selected Console and Device
227 @section The Selected Console and Device
229 @defun select-console console
230 This function selects the console @var{console}. Subsequent editing
231 commands apply to its selected device, selected frame, and selected
232 window. The selection of @var{console} lasts until the next time the
233 user does something to select a different console, or until the next
234 time this function is called.
237 @defun selected-console
238 This function returns the console which is currently active.
241 @defun select-device device
242 This function selects the device @var{device}.
245 @defun selected-device &optional console
246 This function returns the device which is currently active. If optional
247 @var{console} is non-@code{nil}, this function returns the device that
248 would be currently active if @var{console} were the selected console.
251 @node Console and Device I/O
252 @section Console and Device I/O
254 @defun console-disable-input console
255 This function disables input on console @var{console}.
258 @defun console-enable-input console
259 This function enables input on console @var{console}.
262 Each device has a @dfn{baud rate} value associated with it.
263 On most systems, changing this value will affect the amount of padding
264 and other strategic decisions made during redisplay.
266 @defun device-baud-rate &optional device
267 This function returns the output baud rate of @var{device}.
270 @defun set-device-baud-rate device rate
271 This function sets the output baud rate of @var{device} to @var{rate}.