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

  A @dfn{device} is an object representing a connection to a particular
display device, such as an X display or a tty.  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's, only one frame can
be displayed at a time, and it occupies the entire tty display area.
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.

When you start up XEmacs, an initial device is created to display
frames on.  This will either be an X device or a tty device, 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 devices by creating 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 devicep object
This returns non-@code{nil} if @var{object} is a device.
@end defun

@menu
* Basic Device Functions::
* Device Types and Classes::
* Connecting to a Device::
* The Selected Device::
* Device Input::
@end menu


@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 Device Types and Classes
@section Device Types and 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 terminal
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 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 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 Device
@section Connecting to a 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 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 Device
@section The Selected Device

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

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


@node Device Input
@section Device Input

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

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

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

@defun device-function-keymap device
This function returns the function key mapping for @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

@defun set-device-function-keymap device keymap
This function sets the function mapping for @var{device} to @var{keymap}.
@end defun
