man/lispref/consoles-devices.texi

   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.
  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
  93 @defun device-frame-list &optional device
  94 This function returns a list of all frames on @var{device}.
  95 @var{device} defaults to the currently selected device.
  96 @end defun
  97
  98 @defun frame-device &optional frame
  99 This function returns the device that @var{frame} is on.
 100 @var{frame} defaults to the currently selected frame.
 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
 141 @defun device-type &optional device
 142 This function returns the type of @var{device}.  This is a symbol whose
 143 name is one of the device types mentioned above.  @var{device} defaults
 144 to the selected device.
 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
 151 @defun device-class &optional device
 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)
 158 specifies a valid device type.
 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)
 163 specifies a valid device class.
 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
 174 @defun make-device type connection &optional props
 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
 181 @defun make-tty-device &optional tty terminal-type
 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
 199 @defun delete-device device &optional force
 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