428
+ − 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
440
+ − 14 heterogeneous types---you can simultaneously have a frame on an
428
+ − 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.
+ − 30
+ − 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.
+ − 36
+ − 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.).
+ − 42
+ − 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).
+ − 49
+ − 50 @defun consolep object
+ − 51 This returns non-@code{nil} if @var{object} is a console.
+ − 52 @end defun
+ − 53
+ − 54 @defun devicep object
+ − 55 This returns non-@code{nil} if @var{object} is a device.
+ − 56 @end defun
+ − 57
+ − 58 @menu
+ − 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.
+ − 66 @end menu
+ − 67
+ − 68 @node Basic Console Functions
+ − 69 @section Basic Console Functions
+ − 70
+ − 71 @defun console-list
+ − 72 This function returns a list of all existing consoles.
+ − 73 @end defun
+ − 74
+ − 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.
+ − 78 @end defun
+ − 79
+ − 80 @node Basic Device Functions
+ − 81 @section Basic Device Functions
+ − 82
+ − 83 @defun device-list
+ − 84 This function returns a list of all existing devices.
+ − 85 @end defun
+ − 86
+ − 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.
+ − 91 @end defun
+ − 92
444
+ − 93 @defun device-frame-list &optional device
428
+ − 94 This function returns a list of all frames on @var{device}.
444
+ − 95 @var{device} defaults to the currently selected device.
428
+ − 96 @end defun
+ − 97
444
+ − 98 @defun frame-device &optional frame
428
+ − 99 This function returns the device that @var{frame} is on.
444
+ − 100 @var{frame} defaults to the currently selected frame.
428
+ − 101 @end defun
+ − 102
+ − 103 @node Console Types and Device Classes
+ − 104 @section Console Types and Device Classes
+ − 105
+ − 106 Every device is of a particular @dfn{type}, which describes how the
+ − 107 connection to that device is made and how the device operates, and
+ − 108 a particular @dfn{class}, which describes other characteristics of
+ − 109 the device (currently, the color capabilities of the device).
+ − 110
+ − 111 The currently-defined device types are
+ − 112
+ − 113 @table @code
+ − 114 @item x
+ − 115 A connection to an X display (such as @samp{willow:0}).
+ − 116
+ − 117 @item tty
+ − 118 A connection to a tty (such as @samp{/dev/ttyp3}).
+ − 119
+ − 120 @item stream
+ − 121 A stdio connection. This describes a device for which input and output
+ − 122 is only possible in a stream-like fashion, such as when XEmacs in running
+ − 123 in batch mode. The very first device created by XEmacs is a terminal
+ − 124 device and is used to print out messages of various sorts (for example,
+ − 125 the help message when you use the @samp{-help} command-line option).
+ − 126 @end table
+ − 127
+ − 128 The currently-defined device classes are
+ − 129 @table @code
+ − 130 @item color
+ − 131 A color device.
+ − 132
+ − 133 @item grayscale
+ − 134 A grayscale device (a device that can display multiple shades of gray,
+ − 135 but no color).
+ − 136
+ − 137 @item mono
+ − 138 A device that can only display two colors (e.g. black and white).
+ − 139 @end table
+ − 140
444
+ − 141 @defun device-type &optional device
428
+ − 142 This function returns the type of @var{device}. This is a symbol whose
444
+ − 143 name is one of the device types mentioned above. @var{device} defaults
+ − 144 to the selected device.
428
+ − 145 @end defun
+ − 146
+ − 147 @defun device-or-frame-type device-or-frame
+ − 148 This function returns the type of @var{device-or-frame}.
+ − 149 @end defun
+ − 150
444
+ − 151 @defun device-class &optional device
428
+ − 152 This function returns the class (color behavior) of @var{device}. This
+ − 153 is a symbol whose name is one of the device classes mentioned above.
+ − 154 @end defun
+ − 155
+ − 156 @defun valid-device-type-p device-type
+ − 157 This function returns whether @var{device-type} (which should be a symbol)
442
+ − 158 specifies a valid device type.
428
+ − 159 @end defun
+ − 160
+ − 161 @defun valid-device-class-p device-class
+ − 162 This function returns whether @var{device-class} (which should be a symbol)
442
+ − 163 specifies a valid device class.
428
+ − 164 @end defun
+ − 165
+ − 166 @defvar terminal-device
+ − 167 This variable holds the initial terminal device object, which
+ − 168 represents XEmacs's stdout.
+ − 169 @end defvar
+ − 170
+ − 171 @node Connecting to a Console or Device
+ − 172 @section Connecting to a Console or Device
+ − 173
444
+ − 174 @defun make-device type connection &optional props
428
+ − 175 This function creates a new device.
+ − 176 @end defun
+ − 177
+ − 178 The following two functions create devices of specific types and are
+ − 179 written in terms of @code{make-device}.
+ − 180
444
+ − 181 @defun make-tty-device &optional tty terminal-type
428
+ − 182 This function creates a new tty device on @var{tty}. This also creates
+ − 183 the tty's first frame. @var{tty} should be a string giving the name of
+ − 184 a tty device file (e.g. @samp{/dev/ttyp3} under SunOS et al.), as
+ − 185 returned by the @samp{tty} command issued from the Unix shell. A value
+ − 186 of @code{nil} means use the stdin and stdout as passed to XEmacs from
+ − 187 the shell. If @var{terminal-type} is non-@code{nil}, it should be a
+ − 188 string specifying the type of the terminal attached to the specified
+ − 189 tty. If it is @code{nil}, the terminal type will be inferred from the
+ − 190 @samp{TERM} environment variable.
+ − 191 @end defun
+ − 192
+ − 193 @defun make-x-device &optional display argv-list
+ − 194 This function creates a new device connected to @var{display}. Optional
+ − 195 argument @var{argv-list} is a list of strings describing command line
+ − 196 options.
+ − 197 @end defun
+ − 198
444
+ − 199 @defun delete-device device &optional force
428
+ − 200 This function deletes @var{device}, permanently eliminating it from use.
+ − 201 This disconnects XEmacs's connection to the device.
+ − 202 @end defun
+ − 203
+ − 204 @defvar create-device-hook
+ − 205 This variable, if non-@code{nil}, should contain a list of functions,
+ − 206 which are called when a device is created.
+ − 207 @end defvar
+ − 208
+ − 209 @defvar delete-device-hook
+ − 210 This variable, if non-@code{nil}, should contain a list of functions,
+ − 211 which are called when a device is deleted.
+ − 212 @end defvar
+ − 213
+ − 214 @defun console-live-p object
+ − 215 This function returns non-@code{nil} if @var{object} is a console that
+ − 216 has not been deleted.
+ − 217 @end defun
+ − 218
+ − 219 @defun device-live-p object
+ − 220 This function returns non-@code{nil} if @var{object} is a device that
+ − 221 has not been deleted.
+ − 222 @end defun
+ − 223
+ − 224 @defun device-x-display device
+ − 225 This function returns the X display which @var{device} is connected to,
+ − 226 if @var{device} is an X device.
+ − 227 @end defun
+ − 228
+ − 229 @node The Selected Console and Device
+ − 230 @section The Selected Console and Device
+ − 231
+ − 232 @defun select-console console
+ − 233 This function selects the console @var{console}. Subsequent editing
+ − 234 commands apply to its selected device, selected frame, and selected
+ − 235 window. The selection of @var{console} lasts until the next time the
+ − 236 user does something to select a different console, or until the next
+ − 237 time this function is called.
+ − 238 @end defun
+ − 239
+ − 240 @defun selected-console
+ − 241 This function returns the console which is currently active.
+ − 242 @end defun
+ − 243
+ − 244 @defun select-device device
+ − 245 This function selects the device @var{device}.
+ − 246 @end defun
+ − 247
+ − 248 @defun selected-device &optional console
+ − 249 This function returns the device which is currently active. If optional
+ − 250 @var{console} is non-@code{nil}, this function returns the device that
+ − 251 would be currently active if @var{console} were the selected console.
+ − 252 @end defun
+ − 253
+ − 254 @node Console and Device I/O
+ − 255 @section Console and Device I/O
+ − 256
+ − 257 @defun console-disable-input console
+ − 258 This function disables input on console @var{console}.
+ − 259 @end defun
+ − 260
+ − 261 @defun console-enable-input console
+ − 262 This function enables input on console @var{console}.
+ − 263 @end defun
+ − 264
+ − 265 Each device has a @dfn{baud rate} value associated with it.
+ − 266 On most systems, changing this value will affect the amount of padding
+ − 267 and other strategic decisions made during redisplay.
+ − 268
+ − 269 @defun device-baud-rate &optional device
+ − 270 This function returns the output baud rate of @var{device}.
+ − 271 @end defun
+ − 272
+ − 273 @defun set-device-baud-rate device rate
+ − 274 This function sets the output baud rate of @var{device} to @var{rate}.
+ − 275 @end defun
