2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1995, 1996 Ben Wing.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/consoles-devices.info
8 @node Consoles and Devices, Positions, Frames, top
9 @chapter Consoles and Devices
13 A @dfn{console} is an object representing a single input connection
14 to SXEmacs, such as an X display or a TTY connection. It is possible
15 for SXEmacs to have frames on multiple consoles at once (even on
16 heterogeneous types---you can simultaneously have a frame on an
17 X display and a TTY connection, or two completely different X
18 displays, etc.). Normally, there is only one console in existence.
20 A @dfn{device} is an object representing a single output device, such
21 as a particular screen on an X display. (Usually there is exactly one
22 device per X console connection, but there may be more than one if you
23 have a multi-headed X display. For TTY connections, there is always
24 exactly one device per console.)
26 Each device has one or more @dfn{frames} in which text can be
27 displayed. For X displays and the like, a frame corresponds to the
28 normal window-system concept of a window. Frames can overlap, be
29 displayed at various locations within the display, be resized, etc. For
30 TTY, only one frame can be displayed at a time, and it occupies the
31 entire TTY display area.
33 However, you can still define multiple frames and switch between them.
34 Their contents are entirely separate from each other. These sorts of
35 frames resemble the ``virtual console'' capability provided under Linux
36 or the multiple screens provided by the multiplexing program
37 @samp{screen} under Unix.
39 When you start up SXEmacs, an initial console and device are created to
40 receive input and display frames on. This will either be an X display
41 or a TTY connection, depending on what mode you started SXEmacs in (this
42 is determined by the @samp{DISPLAY} environment variable, the
43 @samp{-nw}, @samp{-t} and @samp{-display} command-line options, etc.).
45 You can connect to other X displays and TTY connections by creating
46 new console objects, and to other X screens on an existing display by
47 creating new device objects, as described below. Many functions (for
48 example the frame-creation functions) take an optional device argument
49 specifying which device the function pertains to. If the argument is
50 omitted, it defaults to the selected device (see below).
52 @defun consolep object
53 This returns non-@code{nil} if @var{object} is a console.
57 This returns non-@code{nil} if @var{object} is a device.
61 * Basic Console Functions:: Functions for working with consoles.
62 * Basic Device Functions:: Functions for working with devices.
63 * Console Types and Device Classes::
64 I/O and color characteristics.
65 * Connecting to a Console or Device::
66 * The Selected Console and Device::
67 * Console and Device I/O:: Controlling input and output.
71 @node Basic Console Functions
72 @section Basic Console Functions
75 This function returns a list of all existing consoles.
78 @defun console-device-list &optional console
79 This function returns a list of all devices on @var{console}. If
80 @var{console} is @code{nil}, the selected console will be used.
83 @node Basic Device Functions
84 @section Basic Device Functions
87 This function returns a list of all existing devices.
90 @defun device-or-frame-p object
91 This function returns non-@code{nil} if @var{object} is a device or
92 frame. This function is useful because devices and frames are similar
93 in many respects and many functions can operate on either one.
96 @defun device-frame-list &optional device
97 This function returns a list of all frames on @var{device}.
98 @var{device} defaults to the currently selected device.
101 @defun frame-device &optional frame
102 This function returns the device that @var{frame} is on.
103 @var{frame} defaults to the currently selected frame.
106 @node Console Types and Device Classes
107 @section Console Types and Device Classes
109 Every device is of a particular @dfn{type}, which describes how the
110 connection to that device is made and how the device operates, and
111 a particular @dfn{class}, which describes other characteristics of
112 the device (currently, the color capabilities of the device).
114 The currently-defined device types are
118 A connection to an X display (such as @samp{willow:0}).
121 A connection to a tty (such as @samp{/dev/ttyp3}).
124 A stdio connection. This describes a device for which input and output
125 is only possible in a stream-like fashion, such as when SXEmacs in running
126 in batch mode. The very first device created by SXEmacs is a terminal
127 device and is used to print out messages of various sorts (for example,
128 the help message when you use the @samp{-help} command-line option).
131 The currently-defined device classes are
137 A grayscale device (a device that can display multiple shades of gray,
141 A device that can only display two colours (e.g. black and white).
144 @defun device-type &optional device
145 This function returns the type of @var{device}. This is a symbol whose
146 name is one of the device types mentioned above. @var{device} defaults
147 to the selected device.
150 @defun device-or-frame-type device-or-frame
151 This function returns the type of @var{device-or-frame}.
154 @defun device-class &optional device
155 This function returns the class (color behavior) of @var{device}. This
156 is a symbol whose name is one of the device classes mentioned above.
159 @defun valid-device-type-p device-type
160 This function returns whether @var{device-type} (which should be a symbol)
161 specifies a valid device type.
164 @defun valid-device-class-p device-class
165 This function returns whether @var{device-class} (which should be a symbol)
166 specifies a valid device class.
169 @defvar terminal-device
170 This variable holds the initial terminal device object, which
171 represents SXEmacs's stdout.
175 @node Connecting to a Console or Device
176 @section Connecting to a Console or Device
178 @defun make-device type connection &optional props
179 This function creates a new device.
182 The following two functions create devices of specific types and are
183 written in terms of @code{make-device}.
185 @defun make-tty-device &optional tty terminal-type
186 This function creates a new tty device on @var{tty}. This also creates
187 the tty's first frame. @var{tty} should be a string giving the name of
188 a tty device file (e.g. @samp{/dev/ttyp3} under SunOS et al.), as
189 returned by the @samp{tty} command issued from the Unix shell. A value
190 of @code{nil} means use the stdin and stdout as passed to SXEmacs from
191 the shell. If @var{terminal-type} is non-@code{nil}, it should be a
192 string specifying the type of the terminal attached to the specified
193 tty. If it is @code{nil}, the terminal type will be inferred from the
194 @samp{TERM} environment variable.
197 @defun make-x-device &optional display argv-list
198 This function creates a new device connected to @var{display}. Optional
199 argument @var{argv-list} is a list of strings describing command line
203 @defun delete-device device &optional force
204 This function deletes @var{device}, permanently eliminating it from use.
205 This disconnects SXEmacs's connection to the device.
208 @defvar create-device-hook
209 This variable, if non-@code{nil}, should contain a list of functions,
210 which are called when a device is created.
213 @defvar delete-device-hook
214 This variable, if non-@code{nil}, should contain a list of functions,
215 which are called when a device is deleted.
218 @defun console-live-p object
219 This function returns non-@code{nil} if @var{object} is a console that
220 has not been deleted.
223 @defun device-live-p object
224 This function returns non-@code{nil} if @var{object} is a device that
225 has not been deleted.
228 @defun device-x-display device
229 This function returns the X display which @var{device} is connected to,
230 if @var{device} is an X device.
233 @node The Selected Console and Device
234 @section The Selected Console and Device
236 @defun select-console console
237 This function selects the console @var{console}. Subsequent editing
238 commands apply to its selected device, selected frame, and selected
239 window. The selection of @var{console} lasts until the next time the
240 user does something to select a different console, or until the next
241 time this function is called.
244 @defun selected-console
245 This function returns the console which is currently active.
248 @defun select-device device
249 This function selects the device @var{device}.
252 @defun selected-device &optional console
253 This function returns the device which is currently active. If optional
254 @var{console} is non-@code{nil}, this function returns the device that
255 would be currently active if @var{console} were the selected console.
259 @node Console and Device I/O
260 @section Console and Device I/O
262 @defun console-disable-input console
263 This function disables input on console @var{console}.
266 @defun console-enable-input console
267 This function enables input on console @var{console}.
270 Each device has a @dfn{baud rate} value associated with it.
271 On most systems, changing this value will affect the amount of padding
272 and other strategic decisions made during redisplay.
274 @defun device-baud-rate &optional device
275 This function returns the output baud rate of @var{device}.
278 @defun set-device-baud-rate device rate
279 This function sets the output baud rate of @var{device} to @var{rate}.