comparison man/lispref/consoles-devices.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children ac2d302a0011
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1 @c -*-texinfo-*-
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
8 @cindex devices
9 @cindex consoles
10
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
16 console in existence.
17
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.)
23
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. However, you can still define multiple frames
30 and switch between them. Their contents are entirely separate from each
31 other. These sorts of frames resemble the ``virtual console''
32 capability provided under Linux or the multiple screens provided by the
33 multiplexing program @samp{screen} under Unix.
34
35 When you start up XEmacs, an initial console and device are created to
36 receive input and display frames on. This will either be an X display
37 or a TTY connection, depending on what mode you started XEmacs in (this
38 is determined by the @samp{DISPLAY} environment variable, the
39 @samp{-nw}, @samp{-t} and @samp{-display} command-line options, etc.).
40
41 You can connect to other X displays and TTY connections by creating
42 new console objects, and to other X screens on an existing display by
43 creating new device objects, as described below. Many functions (for
44 example the frame-creation functions) take an optional device argument
45 specifying which device the function pertains to. If the argument is
46 omitted, it defaults to the selected device (see below).
47
48 @defun consolep object
49 This returns non-@code{nil} if @var{object} is a console.
50 @end defun
51
52 @defun devicep object
53 This returns non-@code{nil} if @var{object} is a device.
54 @end defun
55
56 @menu
57 * Basic Console Functions:: Functions for working with consoles.
58 * Basic Device Functions:: Functions for working with devices.
59 * Console Types and Device Classes::
60 I/O and color characteristics.
61 * Connecting to a Console or Device::
62 * The Selected Console and Device::
63 * Console and Device I/O:: Controlling input and output.
64 @end menu
65
66 @node Basic Console Functions
67 @section Basic Console Functions
68
69 @defun console-list
70 This function returns a list of all existing consoles.
71 @end defun
72
73 @defun console-device-list &optional console
74 This function returns a list of all devices on @var{console}. If
75 @var{console} is @code{nil}, the selected console will be used.
76 @end defun
77
78 @node Basic Device Functions
79 @section Basic Device Functions
80
81 @defun device-list
82 This function returns a list of all existing devices.
83 @end defun
84
85 @defun device-or-frame-p object
86 This function returns non-@code{nil} if @var{object} is a device or
87 frame. This function is useful because devices and frames are similar
88 in many respects and many functions can operate on either one.
89 @end defun
90
91 @defun device-frame-list device
92 This function returns a list of all frames on @var{device}.
93 @end defun
94
95 @defun frame-device frame
96 This function returns the device that @var{frame} is on.
97 @end defun
98
99 @node Console Types and Device Classes
100 @section Console Types and Device Classes
101
102 Every device is of a particular @dfn{type}, which describes how the
103 connection to that device is made and how the device operates, and
104 a particular @dfn{class}, which describes other characteristics of
105 the device (currently, the color capabilities of the device).
106
107 The currently-defined device types are
108
109 @table @code
110 @item x
111 A connection to an X display (such as @samp{willow:0}).
112
113 @item tty
114 A connection to a tty (such as @samp{/dev/ttyp3}).
115
116 @item stream
117 A stdio connection. This describes a device for which input and output
118 is only possible in a stream-like fashion, such as when XEmacs in running
119 in batch mode. The very first device created by XEmacs is a terminal
120 device and is used to print out messages of various sorts (for example,
121 the help message when you use the @samp{-help} command-line option).
122 @end table
123
124 The currently-defined device classes are
125 @table @code
126 @item color
127 A color device.
128
129 @item grayscale
130 A grayscale device (a device that can display multiple shades of gray,
131 but no color).
132
133 @item mono
134 A device that can only display two colors (e.g. black and white).
135 @end table
136
137 @defun device-type device
138 This function returns the type of @var{device}. This is a symbol whose
139 name is one of the device types mentioned above.
140 @end defun
141
142 @defun device-or-frame-type device-or-frame
143 This function returns the type of @var{device-or-frame}.
144 @end defun
145
146 @defun device-class device
147 This function returns the class (color behavior) of @var{device}. This
148 is a symbol whose name is one of the device classes mentioned above.
149 @end defun
150
151 @defun valid-device-type-p device-type
152 This function returns whether @var{device-type} (which should be a symbol)
153 species a valid device type.
154 @end defun
155
156 @defun valid-device-class-p device-class
157 This function returns whether @var{device-class} (which should be a symbol)
158 species a valid device class.
159 @end defun
160
161 @defvar terminal-device
162 This variable holds the initial terminal device object, which
163 represents XEmacs's stdout.
164 @end defvar
165
166 @node Connecting to a Console or Device
167 @section Connecting to a Console or Device
168
169 @defun make-device &optional type device-data
170 This function creates a new device.
171 @end defun
172
173 The following two functions create devices of specific types and are
174 written in terms of @code{make-device}.
175
176 @defun make-tty-device &optional tty terminal-type
177 This function creates a new tty device on @var{tty}. This also creates
178 the tty's first frame. @var{tty} should be a string giving the name of
179 a tty device file (e.g. @samp{/dev/ttyp3} under SunOS et al.), as
180 returned by the @samp{tty} command issued from the Unix shell. A value
181 of @code{nil} means use the stdin and stdout as passed to XEmacs from
182 the shell. If @var{terminal-type} is non-@code{nil}, it should be a
183 string specifying the type of the terminal attached to the specified
184 tty. If it is @code{nil}, the terminal type will be inferred from the
185 @samp{TERM} environment variable.
186 @end defun
187
188 @defun make-x-device &optional display argv-list
189 This function creates a new device connected to @var{display}. Optional
190 argument @var{argv-list} is a list of strings describing command line
191 options.
192 @end defun
193
194 @defun delete-device device
195 This function deletes @var{device}, permanently eliminating it from use.
196 This disconnects XEmacs's connection to the device.
197 @end defun
198
199 @defvar create-device-hook
200 This variable, if non-@code{nil}, should contain a list of functions,
201 which are called when a device is created.
202 @end defvar
203
204 @defvar delete-device-hook
205 This variable, if non-@code{nil}, should contain a list of functions,
206 which are called when a device is deleted.
207 @end defvar
208
209 @defun console-live-p object
210 This function returns non-@code{nil} if @var{object} is a console that
211 has not been deleted.
212 @end defun
213
214 @defun device-live-p object
215 This function returns non-@code{nil} if @var{object} is a device that
216 has not been deleted.
217 @end defun
218
219 @defun device-x-display device
220 This function returns the X display which @var{device} is connected to,
221 if @var{device} is an X device.
222 @end defun
223
224 @node The Selected Console and Device
225 @section The Selected Console and Device
226
227 @defun select-console console
228 This function selects the console @var{console}. Subsequent editing
229 commands apply to its selected device, selected frame, and selected
230 window. The selection of @var{console} lasts until the next time the
231 user does something to select a different console, or until the next
232 time this function is called.
233 @end defun
234
235 @defun selected-console
236 This function returns the console which is currently active.
237 @end defun
238
239 @defun select-device device
240 This function selects the device @var{device}.
241 @end defun
242
243 @defun selected-device &optional console
244 This function returns the device which is currently active. If optional
245 @var{console} is non-@code{nil}, this function returns the device that
246 would be currently active if @var{console} were the selected console.
247 @end defun
248
249 @node Console and Device I/O
250 @section Console and Device I/O
251
252 @defun console-disable-input console
253 This function disables input on console @var{console}.
254 @end defun
255
256 @defun console-enable-input console
257 This function enables input on console @var{console}.
258 @end defun
259
260 Each device has a @dfn{baud rate} value associated with it.
261 On most systems, changing this value will affect the amount of padding
262 and other strategic decisions made during redisplay.
263
264 @defun device-baud-rate &optional device
265 This function returns the output baud rate of @var{device}.
266 @end defun
267
268 @defun set-device-baud-rate device rate
269 This function sets the output baud rate of @var{device} to @var{rate}.
270 @end defun