Consoles and Devices
********************

A 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 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 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.

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 screen under Unix.

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 DISPLAY environment variable, the -nw, -t and -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).

 -- Function: consolep object
     This returns non-nil if OBJECT is a console.

 -- Function: devicep object
     This returns non-nil if OBJECT is a device.

Basic Console Functions
=======================

 -- Function: console-list
     This function returns a list of all existing consoles.

 -- Function: console-device-list &optional console
     This function returns a list of all devices on CONSOLE.  If CONSOLE is nil, the selected console will be used.

Basic Device Functions
======================

 -- Function: device-list
     This function returns a list of all existing devices.

 -- Function: device-or-frame-p object
     This function returns non-nil if 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.

 -- Function: device-frame-list device
     This function returns a list of all frames on DEVICE.

 -- Function: frame-device frame
     This function returns the device that FRAME is on.

Console Types and Device Classes
================================

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

The currently-defined device types are

x
     A connection to an X display (such as willow:0).

tty
     A connection to a tty (such as /dev/ttyp3).

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 -help command-line option).

The currently-defined device classes are

color
     A color device.

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

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

 -- Function: device-type device
     This function returns the type of DEVICE.  This is a symbol whose name is one of the device types mentioned above.

 -- Function: device-or-frame-type device-or-frame
     This function returns the type of DEVICE-OR-FRAME.

 -- Function: device-class device
     This function returns the class (color behavior) of DEVICE.  This is a symbol whose name is one of the device classes mentioned above.

 -- Function: valid-device-type-p device-type
     This function returns whether DEVICE-TYPE (which should be a symbol) species a valid device type.

 -- Function: valid-device-class-p device-class
     This function returns whether DEVICE-CLASS (which should be a symbol) species a valid device class.

 -- Variable: terminal-device
     This variable holds the initial terminal device object, which represents XEmacs's stdout.

Connecting to a Console or Device
=================================

 -- Function: make-device &optional type device-data
     This function creates a new device.

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

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

 -- Function: make-x-device &optional display argv-list
     This function creates a new device connected to DISPLAY.  Optional argument ARGV-LIST is a list of strings describing command line options.

 -- Function: delete-device device
     This function deletes DEVICE, permanently eliminating it from use. This disconnects XEmacs's connection to the device.

 -- Variable: create-device-hook
     This variable, if non-nil, should contain a list of functions, which are called when a device is created.

 -- Variable: delete-device-hook
     This variable, if non-nil, should contain a list of functions, which are called when a device is deleted.

 -- Function: console-live-p object
     This function returns non-nil if OBJECT is a console that has not been deleted.

 -- Function: device-live-p object
     This function returns non-nil if OBJECT is a device that has not been deleted.

 -- Function: device-x-display device
     This function returns the X display which DEVICE is connected to, if DEVICE is an X device.

The Selected Console and Device
===============================

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

 -- Function: selected-console
     This function returns the console which is currently active.

 -- Function: select-device device
     This function selects the device DEVICE.

 -- Function: selected-device &optional console
     This function returns the device which is currently active.  If optional CONSOLE is non-nil, this function returns the device that would be currently active if CONSOLE were the selected console.

Console and Device I/O
======================

 -- Function: console-disable-input console
     This function disables input on console CONSOLE.

 -- Function: console-enable-input console
     This function enables input on console CONSOLE.

Each device has a 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.

 -- Function: device-baud-rate &optional device
     This function returns the output baud rate of DEVICE.

 -- Function: set-device-baud-rate device rate
     This function sets the output baud rate of DEVICE to RATE.