- C Language Application Interface Stephen A. Uhler Bell Communications Research

nopage Introduction
Copyright (c) 1988 Bellcore All Rights Reserved
Permission is granted to copy or use this program, EXCEPT that it may not be sold for profit, the copyright notice must be reproduced on copies, and credit should be given to Bellcore where it is due. BELLCORE MAKES NO WARRANTY AND ACCEPTS NO LIABILITY FOR THIS PROGRAM. This release of the software and documentation is modified relative to the original Bellcore release, and they are currently maintained by Michael Haardt and Vincent Broman. (manager) is a window system for Unix that currently runs on Sun Workstations with SunOS and on Linux, the free i80386/i80486 PC UN*X. Older versions of also run on Xenix, 386-Minix, Macintosh, DEC 3100, Atari ST MiNT, and the 3b1 Unix-pc. manages asynchronous updates of overlapping windows and provides application support for a heterogeneous network environment, i.e., many different types of computers connected by various communications media. The application interface enables applications (called client programs) to be written in a variety of programming languages, and run on different operating systems. The client program can take full advantage of the windowing capabilities regardless of the type of connection to the workstation running . Client programs communicate with via over a reliable byte stream. Each client program can create and manipulate one or more windows on the display, with commands and data to the various windows multiplexed over the same connection. provides ASCII terminal emulation and takes responsibility for maintaining the integrity of the window contents when parts of windows become obscured and subsequently uncovered. This permits naive applications to work without modification by providing a default environment that appears to be an ordinary terminal. In addition to terminal emulation, provides each client window with: graphics primitives such as line and circle drawing; facilities for manipulating bitmaps, fonts, icons, and pop-up menus; commands to reshape and position windows; and a message passing facility enabling client programs to rendezvous and exchange messages. Client programs may ask to be informed when a change in the window system occurs, such as a reshaped window, a pushed mouse button, or a message sent from another client program. These changes are called events. notifies a client program of an event by sending it an ASCII character string in a format specified by the client program. Existing applications can be integrated into the windowing environment without modification by having imitate keystrokes in response to user defined menus or other events. The user interface provides a simple point-and-select model of interaction using the mouse with pop-up menus and quick access to system functions through meta-keys on the keyboard. also provides a and function that permits a user to sweep out and copy text from any window and paste it into any other. This document describes the low level C interface library for . The C Interface library provides a set of macros and functions which implement the stream protocol and provide clients written in with a function call interface to . This library provides the lowest level access to functions and represents a direct mapping to the underlying protocol. It is expected that a higher level interface will evolve to support application development at a higher level. The library requires only the UNIX for its operation and access to a byte sequential I/O interface from the underlying operating system.

page Model of Interaction
The basic unit within is the window. A window is a rectangular region on the display, surrounded by a border, with a single connection to other processes. All interactions among the client program, the user and are defined entirely in terms of the state of a client's window or windows. has no concept of window types; there are no separate or Every window supports exactly the same set of capabilities as every other window. In addition, all windows act independently. Client programs need not know or care about the existence of other clients or windows that happen to coexist on the same display. The management of overlapping windows is handled entirely by . For example, when a window is partially or totally obscured by another window, then subsequently uncovered, restores the integrity of the window's contents. There are no windows whose size or position are in some way restricted by a parent window. A client may create and manipulate many windows, each of which may be positioned and sized independently on the display. At any given time there is one special window on the display, the window. This is the window that receives keystrokes and mouse data. It is distinguishable to the user from the other windows on the display by its emboldened border. The active window, in addition to receiving all mouse and keyboard data, is also logically in front of the other windows on the display. The active window is, therefore, always completely exposed. Any window can become the active window, but there can only be one active window at a time. A client program may change its window at any time, write text into it, draw lines, anything, so long as the change is that is the change affects just its window. Only the active window may effect changes to the display, such as changing its shape or position. The only global action a window may perform is to become the active window. This window model provides both the user and application developer with a simple, consistent model of interaction.

nopage Coordinate Systems
uses four different coordinate systems, coordinates , coordinates, coordinates, and coordinates. The entire display is represented by whereas each window has its own and coordinate systems. are in units of pixels. The coordinate 0 0 is the top left pixel on the display. The coordinate increases to the right, the coordinate increases down. The maximum and coordinate depend upon the particular display in use, for the SUN-3 they are by . Commands that operate on the context of the entire display, such as reshaping a window are specified in coordinates. Windows, when measured in coordinates include their borders. as with are measured in units of pixels. The and values increase to the right and down respectively. The origin, coordinate 0 0 is at the top left corner of the window, just inside the window border. are measured as a fraction of the window's size and shape. As with each window has its origin, 0 0 , at the top left corner of the window just inside the border, however the lower right corner of the window is always at coordinate 999 999 . Graphics commands to a window in are automatically scaled to the size of the window. are measured in rows and columns in the current font, just like an ordinary terminal. The coordinate 0 0 is the top left character position in the window. The maximum and in the window depends on both the window and font size.

nopage Functional Overview
The types of commands a client program may issue are divided into 14 categories: and What follows is a brief description of those command categories, and some examples of specific functions within the category. A detailed description of each command is provided in the following section.
At its most basic level, every window emulates a terminal. It provides functions for and lines and characters, highlighting text, clearing areas and windows, and arbitrary cursor motion capabilities. Sample and descriptions are given in the tables below. No entries are provided for keyboard key values, as they depend upon the particular keyboard in use.
Sample TERMCAP Entry
Px | | terminal:\
:am:bs:im=:ta=^I:\
:AL=\E%da:al=\Ea:\
:cd=\EC:ce=\Ec:cl=^L:\
:cm=\E%r%d,%dM:\
:co#80:li#24:\
:cs=\E%d,%dt:\
:DC=\E%dE:dc=\EE:\
:DL=\E%dd:dl=\Ed:\
:do=\Ef:up=\Eu:nd=\Er:\
:IC=\E%dA:ic=\EA:\
:se=\En:so=\Ei:\
:ve=\Ev:vs=\EV:
Sample TERMINFO Entry
Px | | Terminal,
cols#80, lines#24,
am, msgr, ht=^I,
clear=^L, cr=^M, bel=^G,
cub1=^H, cud1=\Ef, cuf1=\Er,
cuu1=\Eu, ind=^J,
cup=\E%p2%d;%p1%dM,
csr=\E%p1%d;%p2%dt,
wind=\E%p2%d;%p2%p4%+%d;%p1;%p1%p3%+%d;t,
el=\Ec, ed=\EC,
il1=\Ea, dl1=\Ed,
il=\E%p1%da, dl=\E%p1%dd,
smso=\Ei, rmso=\En,
smcup=\E1664P, rmcup=\Et\Ep,
permits the client program to restrict the terminal emulator to an arbitrary subrectangle within the window, called a For example, a text editor wishing to provide scroll bars or banner lines can still let do the terminal emulation by specifying a text region that excludes the top and sides of the window. This text region may be redefined or moved around at will, permitting multiple terminal sub regions in the same window.
In addition to terminal emulation, provides a suite of pen plotter style graphics primitives. A client program may draw lines, circles, ellipses, and elliptical arcs on a window. The graphics objects may either be completely positioned, or located relative to an internal maintained by . The objects may also be drawn into undisplayed or areas, then copied to the window as a single unit. The may be aligned with the character cursor, for locating graphic objects relative to character text. Conversely, the character cursor may be aligned with the graphics cursor, permitting character text to be placed at arbitrary positions on the window. Foreground and background colors for text and graphics operations can be chosen from a color palette, and, at least on some systems, this palette can be manipulated by commands to the server.
provides a complete set of functions for dealing with bitmaps, or rectangular arrays of pixels. Bitmaps may be combined with any of the 16 possible operations. Non-displayed bitmaps of arbitrary size may be created and destroyed, and may be performed on the window, within a scratch-pad bitmap, between two scratch-pad bitmaps, or between a scratch-pad bitmap and the window. Bitmap images may be down-loaded from client programs to , or up-loaded from to the client program. In addition, bitmaps may be saved in files by , or loaded into from files. These last two capabilities permit client programs to manipulate large amounts of bitmap data without the need to send the bits over the communication channel.
Either the user or a client program running in the window may move the .I active window around on the display. Windows may be moved with their size retained, reshaped but remain at the same location, or be both moved and shaped anywhere on the display. If the window is the window, it may be (shoved to the back on the display). If the window is not the window, it can become the active window and then be moved about on the display.
Client programs may change character fonts at any time, even on a character by character basis. comes with hundreds of different fonts, ranging in size from microscopic to viewgraph size. Most fonts contain nearly 256 characters, e.g. the default font supplied by the server conforms to iso8859-1. Client programs are free to create and down-load their own fonts. The fonts supplied by are constant width, that is take up the same amount of room as do. There are commands to aid client programs that wish to use proportional fonts.
A client program may ask about the state of its current window, such as its size and position on the display, the name and size of the current font, the position and extent of the text region, and the state of various mode settings. The client may also inquire about the state of the window system as a whole. That includes the position and state of the mouse, the number and sizes of the available fonts, and the organization of windows on the display. The display organization may include the position, size, name, ownership, and spatial ordering for all windows on the display.
Certain parts of the current window environment may be pushed on a stack, then restored at some later time. Client programs rarely need to know the context in which they are called. They simply push those aspects of the environment they will change, then restore them before exiting. About a dozen different parts of the window environment, such as menus, character fonts, window position, etc. may be stacked independently, or in any combination.
has built in support for pop-up menus. Clients may arrange for menus to pop-up in response to mouse button hits. Up to 50 menus may be down-loaded at once for each window. The client which menu will pop-up when a mouse button is pushed. When an item of a pop-up menu is chosen, returns the string previously put into the menu by the client program. The client program may arrange for different menus to pop up depending upon the current mouse position. Menus may also be linked together as a pop-up menu tree. Sliding off to the right of a menu (called a menu) while an item is selected can cause another menu (called a menu) to pop up. Any item of the menu may be specified as the entry item for a child menu. Upon selecting an item of a menu, the client program may arrange for to return ether the action string associated with just the menu item, or the action strings for the selected items of all the menus. Similar to menus, supports menus as well. Long menus may be broken into several pages by the client program. manages the paging automatically, popping up the next page as the user slides off the bottom of a paged menu.
Client programs may arrange to be informed by when some change, called an event, happens to the state of the window system. As with menus, the message informing the client program of a change is formatted as specified by the client program. Examples of events include mouse buttons being depressed or released, windows changing shape or moving, and the window becoming the window or being covered by another window. Window state information, such as the current cursor position, may be returned as part of an event string.
It is often convenient for client programs to or simple objects, such as lines or boxes, in response to moving the mouse. provides client programs with a mouse activated sweep function. tracks an edge of the line or box with the mouse and reports the coordinates to the client at the conclusion of the sweep operation, when the user releases the mouse. As usual, the client program specifies the format of the data returned by .
A single client program may create and manipulate additional windows, called windows. The data destined for, or to be received from, an window is multiplexed on the same channel as the main window. The client program selects a window to receive output, and all output goes to the selected window until a different window is selected. For input, the client program uses the mechanism to determine from which window input arrived. Alternate windows have the same capabilities as the main window. There is currently no limit to the number of alternate windows a client program may have. Up to 100 windows may exist on the display at one time before performance begins to degrade seriously.
provides a globally accessible buffer shared among all client programs. Any client program may put data into or read data from this buffer. provides a user initiated and function from the command menu. extracts character text from the window and places its ASCII representation into the buffer. copies the contents of the buffer to the input stream of the active window. Client programs, by manipulating the data in the buffer, can interact with the system and functions.
Although the buffer gives client programs a simple asynchronous interprocess communication mechanism, has a more general synchronous interprocess message passing scheme. A client program may send a message to another client program, or broadcast the message to all client programs. As a message recipient, the client program may elect to receive messages as an and encapsulate the message and sender name in the format of its choice. provides the primitives needed to implement clients by permitting to register their names, services and protocols with . Client programs may query for a list of active messages may be associated with windows by the client programs in such a way that the message is automatically received by a client program as part of a event whenever the mouse button is pressed on the window. Using this mechanism, client programs can interact with clients without any advance knowledge of which are available or what services they are providing.
Client programs may select various combinations of window modes. These modes tailor the behavior of the macros described above. Examples of window modes include and that affect the terminal emulation, different coordinate system settings that affect commands, or flags that set a window to automatically upon receiving input, ignore all keyboard input, or suspend output while a window is obscured.

nopage Underlying Protocol
The purpose of this library package is both to provide a function call interface to the stream protocol, and to document each command understood by . There are two types of commands, as summarized in the table below.
command protocol
In both cases, is the ASCII escape character or '\033', whereas the word represents a single character command identifier. The are optional integers, there can be as few as zero, as in the command
ESCa
which inserts a blank line in the window, or as many as eight, as would be used by the command
ESC0,0,50,100,10,20,3,2b
which is an example of a command to copy images between bitmaps. No spaces may be included between the character and the command identifier character, but the argument separators may be either commas (,) or semicolons (;). The function of the command is determined both by the command identifier character and the number of numeric arguments preceding the command identifier character. All of the commands with the same command identifier character are closely related in function. For example, all the commands in the following table have the same command character, and all draw ellipses, but have different effects based upon the number of arguments.
Commands that draw ellipses
1 | ESC100,200o
2 | ESC100,200,300,400o
3 | ESC100,200,300,400,2o
All of the ellipses have major and minor axis lengths of and units respectively. Command 1 draws the ellipse at the current graphics location. Command 2 draws the ellipse at the location specified by the third and forth arguments, at 300 400 . Command 3 draws the ellipse into scratchpad bitmap number The second form of command, which is a special case of the first form, is used for downloading data from the client program to . The integer specifies the number of bytes of data to be downloaded, and are the number of data values downloaded. An example of the second type of command is
ESC11,7bI-moved
which instructs to send the client program the string any time the client's window is moved to a different location on the display. The refers to the number of the event and the is the number of characters in the event string, which in this case is All of the command identifier characters are listed in The command actions, determined by the command identifier and number of command arguments, are described by the macros in this document.

page Conventions and Notation
All functions and macros and programming examples are shown in a typewriter font to distinguish them from ordinary text. Similarly, function and macro arguments are shown in a bold typewriter font. The names of often-used arguments passed to macros indicate their function, and are defined below. column, row The integers column and row refer to a character position in coordinates even though characters may be placed at arbitrary pixel locations within a window and need not fall on column or row boundaries. Dwidth, Dheight The integers Dwidth and Dheight represent a width and height in coordinates. mode The positive integer mode, represents the bit combination of window modes. Mode is usually an list of constants in A typical use of mode is the argument to m_push mode as in m_push P_FLAGS | P_EVENT | P_MENU . n The small non-negative integer represents a resource descriptor when describing objects such as windows, fonts, or menus. name Name is the file name of a bitmap image on the machine. File names given with no directory prefix are referenced relative to the subdirectory of 's home directory. The home directory is installation dependent, and may be determined with the command parent, child The small positive integers parent and child represent menus. A menu is linked to a menu forming a tree of menus. radius The positive integer radius along with radius1 and radius2 signifies a radius when referring to circles or major and minor axis when referring to ellipses. They are only referenced in respect to coordinates. string An array of characters, is a null terminated ASCII character string. Except where noted, several ASCII control characters can be included in strings by escaping them with \X, where is one of the characters shown in the following table.
Character string control characters
escape | octal | Meaning
character | value |
\b | 010 | Back space
\E | 033 | Escape
\e | 033 | Escape
\f | 014 | Form feed
\g | 007 | Bell
\M | * | Turn on
 |  | 8'th (parity) bit
\n | 012 | New line
\r | 015 | Return
\s | 040 | Space
\\ | 134 | Back-slash (\)
* (the next character has its 8'th bit turned on) to, from The small positive integers to and from identify the destination and source bitmaps for operations. The value 0 (zero) represents the current window bitmap; positive integers name scratch-pad bitmap storage. width, height The integers width and height represent a width and height in coordinates. X, Y The integer pair X Y represents a point in coordinates. The suffixes and as in X_src Y_src or X_dst Y_dst are used to indicate and coordinates respectively. Similarly, the suffixes and as in X1 Y1 refer generically to the first or second coordinate. x, y The integers x y represent a point in coordinates. Whether that is (i.e. 0-999) or depends upon the current coordinate setting of the window. As with X Y above, the modifiers and refer respectively to the and coordinates.