@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1995, 1996 Ben Wing.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/consoles-devices.info
@node Consoles and Devices, Positions, Frames, top
@chapter Consoles and Devices
@cindex devices
@cindex consoles

  A @dfn{console} is an object representing a single input connection
to XEmacs, such as an X display or a TTY connection.  It is possible
for XEmacs to have frames on multiple consoles at once (even on
heterogeneous types -- you can simultaneously have a frame on an
X display and a TTY connection).  Normally, there is only one
console in existence.

  A @dfn{device} is an object representing a single output device, such
as a particular screen on an X display. (Usually there is exactly one
device per X console connection, but there may be more than one if you
have a multi-headed X display.  For TTY connections, there is always
exactly one device per console.)

  Each device has one or more @dfn{frames} in which text can be
displayed.  For X displays and the like, a frame corresponds to the
normal window-system concept of a window.  Frames can overlap, be
displayed at various locations within the display, be resized, etc.  For
TTY, only one frame can be displayed at a time, and it occupies the
entire TTY display area.
@ignore @c Not yet implemented
However, you can still define multiple frames
and switch between them.  Their contents are entirely separate from each
other.  These sorts of frames resemble the ``virtual console''
capability provided under Linux or the multiple screens provided by the
multiplexing program @samp{screen} under Unix.
@end ignore

  When you start up XEmacs, an initial console and device are created to
receive input and display frames on.  This will either be an X display
or a TTY connection, depending on what mode you started XEmacs in (this
is determined by the @samp{DISPLAY} environment variable, the
@samp{-nw}, @samp{-t} and @samp{-display} command-line options, etc.).

  You can connect to other X displays and TTY connections by creating
new console objects, and to other X screens on an existing display by
creating new device objects, as described below.  Many functions (for
example the frame-creation functions) take an optional device argument
specifying which device the function pertains to.  If the argument is
omitted, it defaults to the selected device (see below).

@defun consolep object
This returns non-@code{nil} if @var{object} is a console.
@end defun

@defun devicep object
This returns non-@code{nil} if @var{object} is a device.
@end defun

@menu
* Basic Console Functions::     Functions for working with consoles.
* Basic Device Functions::      Functions for working with devices.
* Console Types and Device Classes::
                                I/O and color characteristics.
* Connecting to a Console or Device::
* The Selected Console and Device::
* Console and Device I/O::      Controlling input and output.
@end menu

@node Basic Console Functions
@section Basic Console Functions

@defun console-list
This function returns a list of all existing consoles.
@end defun

@defun console-device-list &optional console
This function returns a list of all devices on @var{console}.  If
@var{console} is @code{nil}, the selected console will be used.
@end defun

@node Basic Device Functions
@section Basic Device Functions

@defun device-list
This function returns a list of all existing devices.
@end defun

@defun device-or-frame-p object
This function returns non-@code{nil} if @var{object} is a device or
frame.  This function is useful because devices and frames are similar
in many respects and many functions can operate on either one.
@end defun

@defun device-frame-list device
This function returns a list of all frames on @var{device}.
@end defun

@defun frame-device frame
This function returns the device that @var{frame} is on.
@end defun

@node Console Types and Device Classes
@section Console Types and Device Classes

Every device is of a particular @dfn{type}, which describes how the
connection to that device is made and how the device operates, and
a particular @dfn{class}, which describes other characteristics of
the device (currently, the color capabilities of the device).

The currently-defined device types are

@table @code
@item x
A connection to an X display (such as @samp{willow:0}).

@item tty
A connection to a tty (such as @samp{/dev/ttyp3}).

@item stream
A stdio connection.  This describes a device for which input and output
is only possible in a stream-like fashion, such as when XEmacs in running
in batch mode.  The very first device created by XEmacs is a terminal
device and is used to print out messages of various sorts (for example,
the help message when you use the @samp{-help} command-line option).
@end table

The currently-defined device classes are
@table @code
@item color
A color device.

@item grayscale
A grayscale device (a device that can display multiple shades of gray,
but no color).

@item mono
A device that can only display two colors (e.g. black and white).
@end table

@defun device-type device
This function returns the type of @var{device}.  This is a symbol whose
name is one of the device types mentioned above.
@end defun

@defun device-or-frame-type device-or-frame
This function returns the type of @var{device-or-frame}.
@end defun

@defun device-class device
This function returns the class (color behavior) of @var{device}.  This
is a symbol whose name is one of the device classes mentioned above.
@end defun

@defun valid-device-type-p device-type
This function returns whether @var{device-type} (which should be a symbol)
species a valid device type.
@end defun

@defun valid-device-class-p device-class
This function returns whether @var{device-class} (which should be a symbol)
species a valid device class.
@end defun

@defvar terminal-device
This variable holds the initial terminal device object, which
represents XEmacs's stdout.
@end defvar

@node Connecting to a Console or Device
@section Connecting to a Console or Device

@defun make-device &optional type device-data
This function creates a new device.
@end defun

The following two functions create devices of specific types and are
written in terms of @code{make-device}.

@defun make-tty-device &optional tty terminal-type 
This function creates a new tty device on @var{tty}.  This also creates
the tty's first frame.  @var{tty} should be a string giving the name of
a tty device file (e.g. @samp{/dev/ttyp3} under SunOS et al.), as
returned by the @samp{tty} command issued from the Unix shell.  A value
of @code{nil} means use the stdin and stdout as passed to XEmacs from
the shell.  If @var{terminal-type} is non-@code{nil}, it should be a
string specifying the type of the terminal attached to the specified
tty.  If it is @code{nil}, the terminal type will be inferred from the
@samp{TERM} environment variable.
@end defun

@defun make-x-device &optional display argv-list
This function creates a new device connected to @var{display}.  Optional
argument @var{argv-list} is a list of strings describing command line
options.
@end defun

@defun delete-device device
This function deletes @var{device}, permanently eliminating it from use.
This disconnects XEmacs's connection to the device.
@end defun

@defvar create-device-hook
This variable, if non-@code{nil}, should contain a list of functions,
which are called when a device is created.
@end defvar

@defvar delete-device-hook
This variable, if non-@code{nil}, should contain a list of functions,
which are called when a device is deleted.
@end defvar

@defun console-live-p object
This function returns non-@code{nil} if @var{object} is a console that
has not been deleted.
@end defun

@defun device-live-p object
This function returns non-@code{nil} if @var{object} is a device that
has not been deleted.
@end defun

@defun device-x-display device
This function returns the X display which @var{device} is connected to,
if @var{device} is an X device.
@end defun

@node The Selected Console and Device
@section The Selected Console and Device

@defun select-console console
This function selects the console @var{console}.  Subsequent editing
commands apply to its selected device, selected frame, and selected
window.  The selection of @var{console} lasts until the next time the
user does something to select a different console, or until the next
time this function is called.
@end defun

@defun selected-console
This function returns the console which is currently active.
@end defun

@defun select-device device
This function selects the device @var{device}.
@end defun

@defun selected-device &optional console
This function returns the device which is currently active.  If optional
@var{console} is non-@code{nil}, this function returns the device that
would be currently active if @var{console} were the selected console.
@end defun

@node Console and Device I/O
@section Console and Device I/O

@defun console-disable-input console
This function disables input on console @var{console}.
@end defun

@defun console-enable-input console
This function enables input on console @var{console}.
@end defun

Each device has a @dfn{baud rate} value associated with it.
On most systems, changing this value will affect the amount of padding
and other strategic decisions made during redisplay.

@defun device-baud-rate &optional device
This function returns the output baud rate of @var{device}.
@end defun

@defun set-device-baud-rate device rate
This function sets the output baud rate of @var{device} to @var{rate}.
@end defun