rsalz@uunet.uu.net (Rich Salz) (01/27/89)
Submitted-by: Stephen A. Uhler <sau@bellcore.com> Posting-number: Volume 17, Issue 45 Archive-name: mgr/part44 #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh <file", e.g.. If this archive is complete, you # will see the following message at the end: # "End of archive 44 (of 61)." # Contents: doc/usrman/doc.1 doc/usrman/doc.3 # Wrapped by rsalz@papaya.bbn.com on Thu Nov 17 21:05:53 1988 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'doc/usrman/doc.1' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/usrman/doc.1'\" else echo shar: Extracting \"'doc/usrman/doc.1'\" \(26023 characters\) sed "s/^X//" >'doc/usrman/doc.1' <<'END_OF_FILE' X'\" Copyright (c) 1988 Bellcore X'\" All Rights Reserved X'\" Permission is granted to copy or use this program, EXCEPT that it X'\" may not be sold for profit, the copyright notice must be reproduced X'\" on copies, and credit should be given to Bellcore where it is due. X'\" BELLCORE MAKES NO WARRANTY AND ACCEPTS NO LIABILITY FOR THIS PROGRAM. X'\" X'\" $Header: doc.1,v 4.2 88/06/30 12:44:53 bianchi Exp $ X'\" $Source: /tmp/mgrsrc/doc/usrman/RCS/doc.1,v $ X.TL X\*M - C Language Application Interface X.AU XStephen A. Uhler X.AI XBell Communications Research X.Sh nopage Introduction X.FS X.ce 2 XCopyright (c) 1988 Bellcore XAll Rights Reserved X.br XPermission is granted to copy or use this program, EXCEPT that it Xmay not be sold for profit, the copyright notice must be reproduced Xon copies, and credit should be given to Bellcore where it is due. XBELLCORE MAKES NO WARRANTY AND ACCEPTS NO LIABILITY FOR THIS PROGRAM. X.FE X\*M X(\fBm\fPana\fBg\fPe\fBr\fP) Xis a window system for Unix that currently runs on Sun Workstations. X\*M manages asynchronous updates of overlapping windows Xand provides application support for a heterogeneous network Xenvironment, i.e., Xmany different types of computers connected by various Xcommunications media. XThe application interface enables applications (called client programs) to be Xwritten in a variety of programming languages, and run on different Xoperating systems. XThe client program can take full Xadvantage of the windowing capabilities Xregardless of the Xtype of connection to the workstation running \*M. X.LP XClient programs communicate with \*M via X.I pseudo-terminals Xover a reliable byte stream. XEach client program can create and manipulate one or more windows Xon the display, with commands and data to the various windows multiplexed over Xthe same connection. X\*M provides X.SM XASCII X.LG Xterminal emulation and takes responsibility for Xmaintaining the integrity of the window contents when parts of windows become Xobscured and subsequently uncovered. XThis permits naive applications to work without modification Xby providing a default environment that appears to be an ordinary terminal. X.LP XIn addition to terminal emulation, \*M provides each client window with: Xgraphics primitives such as line and circle drawing; facilities for Xmanipulating bitmaps, fonts, icons, and pop-up menus; Xcommands to reshape Xand position windows; and a message passing Xfacility enabling client programs Xto rendezvous and exchange messages. XClient programs may ask to be informed when a change in the window system Xoccurs, such as a reshaped window, a pushed mouse button, Xor a message sent from another client program. XThese changes are called events. X\*M notifies a client program of an event by sending Xit an X.SM XASCII X.LG Xcharacter string in a format specified by the client program. XExisting applications can be integrated into the Xwindowing environment without modification by having \*M Ximitate keystrokes in response to user defined menus or Xother events. X.LP XThe user interface provides a simple point-and-select model of Xinteraction using the mouse with pop-up menus and Xquick access to system functions through meta-keys on the keyboard. X\*M also provides a X.I cut Xand X.I paste X.R Xfunction that permits a user to sweep out and copy text from any window Xand paste it into any other. X.LP XThis document describes the low level XC interface library for \*M. XThe X.I XC Interface library X.R Xprovides a set of macros and functions which implement the stream protocol Xand provide clients written in X.B C Xwith a function call interface to \*M. XThis library provides the lowest level access to \*M functions Xand represents a direct mapping to the underlying protocol. XIt is expected that a higher level interface will evolve to support Xapplication development at a higher level. XThe library requires only the X.SM XUNIX X.LG X.I "Standard I/O Library" Xfor its operation and access to a byte sequential I/O Xinterface from the underlying operating system. X.Sh page Model of Interaction XThe basic unit within \*M is the window. XA window is a rectangular region on the display, surrounded by a Xborder, with a single connection to other processes. XAll interactions among the client program, the user and \*M are Xdefined entirely in terms of the state Xof a client's window or windows. X\*M has no concept of window types; there are no separate X.I "graphics windows" , X.I "text windows" , Xor X.I "edit windows" . XEvery window supports exactly the same set of capabilities as Xevery other window. XIn addition, all windows act independently. XClient programs need not know or care about the existence of other Xclients or windows that happen to coexist on the same display. XThe management of overlapping windows is handled entirely by \*M. XFor example, Xwhen a window is partially or totally obscured by another window, Xthen subsequently uncovered, \*M restores the integrity of the Xwindow's contents. XThere are no X.I sub-windows , Xwindows whose size or position are in some Xway restricted by a parent window. XA client may create and manipulate many windows, each of which Xmay be positioned and sized independently on the display. X.LP XAt any given time there is one special window on the display, Xthe X.I active Xwindow. XThis is the window that receives keystrokes and mouse data. XIt is distinguishable to the user from the other windows on the Xdisplay by its emboldened border. XThe active window, in addition to receiving all mouse and keyboard Xdata, is also logically in front of the other windows Xon the display. XThe active window is, therefore, always completely exposed. XAny window can become the active window, but there can only be one Xactive window at a time. X.LP XA client program may change its window at any time, write text into it, Xdraw lines, anything, so long as the change is X.I local , Xthat is the change affects just its window. XOnly the active window may effect X.I global Xchanges Xto the display, Xsuch as changing its shape or position. XThe only global action a X.I non-active Xwindow may perform is to become the active window. XThis window model provides both the user and Xapplication developer with a simple, Xconsistent model of interaction. X.Sh nopage Coordinate Systems X\*M uses four different coordinate systems, X.I display Xcoordinates , X.I "absolute window" Xcoordinates, X.I "relative window" Xcoordinates, Xand X.I character Xcoordinates. XThe entire display is represented by X.I "display coordinates" Xwhereas each window has its own X.I "absolute window" , X.I "relative window" , Xand X.I character Xcoordinate systems. X.LP X.I "Display coordinates" Xare in units of pixels. XThe coordinate X.Fr "" 0 0 Xis the top left Xpixel on the display. The X.B X Xcoordinate increases to the right, the X.B Y Xcoordinate Xincreases down. XThe maximum X.B X Xand X.B Y Xcoordinate depend upon the particular display in use, Xfor the SUN-3 they are X.Fi 1152 Xby X.Fi 900 . XCommands that operate on the context of the entire display, such as Xreshaping a window are specified in X.I display Xcoordinates. XWindows, when measured Xin X.I display Xcoordinates include their borders. X.LP X.I "Absolute window coordinates" , Xas with X.I "display coordinates" , Xare measured in units of pixels. XThe X.Fi X Xand X.Fi Y Xvalues increase to the right and down respectively. XThe origin, coordinate X.Fr "" 0 0 Xis at the top left corner of the window, just inside the window border. X.LP X.I "Relative window coordinates" Xare measured as a fraction of the window's size and shape. XAs with X.I "absolute window coordinates" , Xeach window has its origin, X.Fr "" 0 0 X, at the top left corner of the window just inside the border, Xhowever the lower right corner of the window is always at Xcoordinate X.Fr "" 999 999 X\&. XGraphics commands to a window in X.I "relative window coordinates" Xare automatically scaled to the size of the window. X.LP X.I "Character coordinates" Xare measured in rows and columns in the current Xfont, just like an ordinary terminal. XThe coordinate X.Fr "" 0 0 Xis the top left character Xposition in the window. XThe maximum X.I row Xand X.I column Xin the window Xdepends on both the window and font size. X.Sh nopage Functional Overview XThe types of commands a client program may issue \*M Xare divided into 14 Xcategories: X.I "terminal emulation" , X.I graphics , X.I bit-blts , X.I "window positioning" , X.I "font changes" , X.I "state inquiry" , X.I "saved contexts" , X.I menus , X.I events , X.I "sweep functions" , X.I "multiple window manipulation" , X.I "cut and paste" , X.I messages , Xand X.I "window modes" . XWhat follows is a brief description of those command categories, Xand some examples of specific functions within the category. XA detailed description of each command is provided in the following Xsection. X.LP X.B XTerminal Emulation X.R X.br XAt its basic level, every \*M window emulates a X.I \s-2CRT\s+2 Xterminal. XIt provides functions for X.I inserting Xand X.I deleting Xlines and characters, highlighting text, clearing areas and windows, and Xarbitrary cursor motion capabilities. XSample \*M X.I \s-2TERMCAP\s+2 Xand X.I \s-2TERMINFO\s+2 Xdescriptions are given in the tables below. XNo entries are provided for keyboard key values, Xas they depend upon the particular keyboard in use. X.Mk \" mark vertical baseline or later return X.TS Xbox; Xc s Xl s Xl lflrp-2. XSample \*M \fIT\s-2ERMCAP\fP\s+2 Entry X_ XPx \(vr \*M \(vr \*M terminal:\e X :am:bs:im=:ta=^I:\e X :AL=\eE%da:al=\eEa:\e X :cd=\eEC:ce=\eEc:cl=^L:\e X :cm=\eE%r%d,%dM:\e X :co#80:li#24:\e X :cs=\eE%d,%dt:\e X :DC=\eE%dE:dc=\eEE:\e X :DL=\eE%dd:dl=\eEd:\e X :do=\eEf:up=\eEu:nd=\eEr:\e X :IC=\eE%dA:ic=\eEA:\e X :se=\eEn:so=\eEi:\e X :ve=\eEv:vs=\eEV: X.TE X.Go 3.1i \" return to baseline shifted right X.TS Xbox; Xc s Xl s Xl lflrp-2. XSample \*M \fIT\s-2ERMINFO\s+2\fP Entry X_ XPx \(br \*M \(br \*M Terminal, X cols#80, lines#24, X am, msgr, ht=^I, X clear=^L, cr=^M, bel=^G, X cub1=^H, cud1=\eEf, cuf1=\eEr, X cuu1=\eEu, ind=^J, X cup=\eE%p2%d;%p1%dM, X csr=\eE%p1%d;%p2%dt, X wind=\eE%p2%d;%p2%p4%+%d;%p1;%p1%p3%+%d;t, X el=\eEc, ed=\eEC, X il1=\eEa, dl1=\eEd, X il=\eE%p1%da, dl=\eE%p1%dd, X smso=\eEi, rmso=\eEn, X smcup=\eE1664P, rmcup=\eEt\eEp, X.TE X.Rs \" restore baseline stuff X.LP X\*M permits the client program to restrict the terminal emulator Xto an arbitrary subrectangle within the window, Xcalled a X.I "text region" . XFor example, a text editor wishing to provide scroll bars or banner lines Xcan still let \*M do the terminal emulation by specifying a text Xregion that excludes the top and sides of the window. XThis text region may be redefined or moved around at will, permitting Xmultiple terminal sub regions in the same window. X.LP X.B Graphics X.br XIn addition to terminal emulation, \*M provides a suite of pen plotter style Xgraphics primitives. XA client program may draw lines, circles, ellipses, and elliptical arcs Xon a window. XThe graphics objects may either be completely positioned, or located Xrelative to an internal X.I "graphics point" , Xmaintained by \*M. XThe objects may also be drawn into undisplayed or X.I scratchpad Xareas, then copied to the window as a single unit. XThe X.I "graphics point" Xmay be aligned with the character cursor, Xfor locating graphic objects relative to character text. XConversely, the character cursor may be aligned with the graphics cursor, Xpermitting character text to be placed at arbitrary positions on the window. X.LP X.B Bit-blts X.br X\*M provides a complete set of functions for dealing with bitmaps, or Xrectangular arrays of pixels. XBitmaps may be combined with any of the 16 possible X.I bit-blt Xoperations. XNon-displayed Xbitmaps of arbitrary size may be created and destroyed, and X.I bit-blts Xmay be performed on the window, within a scratch-pad bitmap, Xbetween two scratch-pad bitmaps, Xor between a scratch-pad bitmap and the window. XBitmap images may be down-loaded from client programs to \*M, Xor up-loaded from \*M to the client program. XIn addition, bitmaps may be saved in files by \*M, or loaded Xinto \*M from files. XThese last two capabilities permit client programs to manipulate large Xamounts of bitmap data without the need to send the bits Xover the communication channel. X.LP X.B "Window Positioning" X.br XEither the user or client program may move the X.I active Xwindow Xaround on the display. XWindows may be moved with their size retained, reshaped but remain at the Xsame location, or be both moved and shaped anywhere on the display. XIf the window is the X.I active Xwindow, Xit may be X.I buried X(shoved to the back on the display). XIf the window is not the X.I active Xwindow, Xit can become the active window and then moved about on the display. X.LP X.B "Font Changes" X.br XClient programs may change character fonts at any time, even on a Xcharacter by character basis. X\*M comes with scores of different fonts, Xranging in size from microscopic to viewgraph size. XClient programs are Xfree to create and down-load their own fonts. XThe fonts supplied by \*M are constant width, that is X.I i 's Xtake up the same amount of room as X.I m 's Xdo. There are commands to aid client programs that wish to use Xproportional fonts. X.LP X.B "State Inquiry" X.br XA client program may ask \*M about the state of its current window, Xsuch as its size and position on the display, Xthe name and size of the current font, Xthe position and extent of the text region, and the state of Xvarious mode settings. XThe client may also inquire about the state of the window system as a whole. XThat includes the position and state of the mouse, the number and sizes Xof the available fonts, and Xthe organization of windows on the display. XThe display organization may include the position, size, name, Xownership, and spatial ordering for all windows on the display. X.LP X.B "Saved Contexts" X.br XCertain parts of the current window environment may be pushed on a stack, Xthen restored at some later time. XClient programs rarely need to know the context in which they are called. XThey simply push those aspects of the environment they will change, then Xrestore them before exiting. XAbout a dozen different parts of the window environment, such as menus, Xcharacter fonts, window position, etc. may be stacked independently, or in Xany combination. X.LP X.B Menus X.br X\*M has built in support for pop-up menus. XClients may arrange for menus to pop-up in response to mouse button Xhits. XUp to 50 menus may be down-loaded at once for each window. XThe client X.I selects Xwhich menu will pop-up when a mouse button is pushed. XWhen an item of a pop-up menu is chosen, \*M returns the string Xpreviously put into the menu by the client program. XThe client program may arrange Xfor different menus to pop up depending upon the Xcurrent mouse position. XMenus may also be linked together as a pop-up menu tree. XSliding off to the right of a menu (called a X.I parent Xmenu) while an item is selected Xcan cause another menu (called a X.I child Xmenu) Xto pop up. XAny item of the X.I parent Xmenu may be specified as the entry item for a child menu. XUpon selecting an item of a X.I child Xmenu, Xthe client program may arrange for \*M to return Xether the action string associated with just the X.I child Xmenu item, Xor the action strings for the selected items of all the menus. XSimilar to X.I sliding Xmenus, X\*M supports X.I paging Xmenus as well. XLong menus may be broken into several pages by the client program. X\*M manages the paging automatically, popping up the next page as Xthe user slides off the bottom of a paged menu. X.LP X.B Events X.br XClient programs may arrange to be informed by \*M when some change, Xcalled an event, Xhappens to the state of the window system. XAs with menus, the message informing the client program of a change Xis formated as specified by the client program. XExamples of events include mouse buttons being depressed or released, Xwindows changing shape or moving, and the window becoming the X.I active Xwindow or being covered by another window. XWindow state information, such as the current cursor position, Xmay be returned as part of an event string. X.LP X.B "Sweep Functions" X.br XIt is often convenient for client programs to X.I sweep , Xor X.I rubber-band Xsimple objects, such as lines or boxes, in response to moving the mouse. X\*M provides client programs with a mouse activated sweep function. X\*M tracks an edge of the line or box with the mouse and reports Xthe coordinates to the client at the conclusion of the sweep Xoperation, when the user releases the mouse. XAs usual, the client program specifies the format of the data returned by X\*M. X.LP X.B "Multiple Window Manipulation" X.br XA single client program may create and manipulate additional windows, called X.I alternate Xwindows. XThe data destined for, or to be received from, an X.I alternate Xwindow is multiplexed on the same channel as the main window. XThe client program selects a window to receive output, and all output Xgoes to the selected window until a different window is selected. XFor input, the client program uses the X.I event Xmechanism to determine from which window input arrived. XAlternate windows have the same capabilities as the main window. XThere is currently no limit to the number of alternate windows a Xclient program may have. XUp to 100 windows may exist on the display at one time Xbefore performance begins to degrade seriously. X.LP X.B "Cut and Paste" X.br X\*M provides a globally accessible X.I snarf Xbuffer shared among all client programs. XAny client program Xmay put data into or read data from this buffer. X\*M provides a user initiated X.I cut Xand X.I paste Xfunction from the command menu. X\*M extracts character text from the window and places its X\s-2ASCII\s+2 Xrepresentation into the X.I snarf Xbuffer. X.I Paste Xcopies the contents of the X.I snarf Xbuffer to the input stream of the active Xwindow. XClient programs, by manipulating the data in the X.I snarf Xbuffer, Xcan interact with the system X.I cut Xand X.I paste Xfunctions. X.LP X.B Messages X.br XAlthough the X.I snarf Xbuffer gives client programs a simple asynchronous interprocess Xcommunication mechanism, \*M has a more general synchronous interprocess Xmessage passing scheme. XA client program may send a message Xto another client program, or broadcast the message to all client programs. XAs a message recipient, the client program may elect to receive messages Xas an X.I event Xand encapsulate the message and sender name in the format of its choice. X\*M provides the primitives needed to implement X.I server Xclients Xby permitting X.I servers Xto register their names, services and protocols with \*M. XClient Xprograms may query \*M for a list of active X.I servers . X.I Server Xmessages may be associated with windows by the X.I server Xclient programs in such a way that the message is automatically Xreceived by a client Xprogram as part of a X.I "mouse button" Xevent whenever the mouse button is Xpressed on the X.I server 's Xwindow. XUsing this mechanism, client programs can interact with X.I server Xclients without any advance knowledge of which X.I server s Xare available or what services they are providing. X.br X.LP X.B "Window Modes" X.br XClient programs may select various combinations of window modes. XThese modes tailor the behavior of the macros described above. XExamples of window modes include X.I "auto line wrap" Xand X.I "character overstrike" Xthat affect the terminal emulation, Xdifferent coordinate system settings that affect X.I graphics Xcommands, or Xflags that set a window to X.I activate Xautomatically upon receiving input, Xignore all keyboard input, Xor suspend output while a window is obscured. X.Sh nopage Underlying Protocol XThe purpose of this library package is both to provide a function call Xinterface to the stream protocol, and to document each command understood Xby \*M. XThere are two types of \*M commands, as summarized in the table below. X.TS Xcenter box; Xc Xl. X\*M command protocol X_ XT{ X.B ESC X.Sb X 1 , X.Sb X 2 , ... , X.Sb X n X.B command XT} XT{ X.B ESC X.Sb X 1 , X.Sb X 2 , ... , X.Sb X n X.I length X.B command X.I data XT} X.sp 0.5v X.TE XIn both cases, X.SM X.B ESC X.LG Xis the X.SM XASCII X.LG Xescape character or '\e033', Xwhereas the word X.B command Xrepresents a single character command identifier. XThe X.I X 's Xare optional integers, there can be as few as zero, as in the command X.TS Xcenter box; Xc. X\fBESC\fP\fIa\fP X.TE Xwhich inserts a blank line in the window, or Xas many as eight, as would be used by the command X.TS Xcenter box; Xc. X\fBESC\fP0,0,50,100,10,20,3,2\fIb\fP X.TE Xwhich is an example of a command to copy images between bitmaps. XNo spaces may be included between the X.B ESC Xcharacter and the command identifier character, but the argument Xseparators may be either commas (,) or semicolons (;). X.LP XThe function of the command is determined both Xby the command identifier character Xand X.I n , Xthe number of numeric arguments preceding the command identifier character. XAll of the commands with the same command identifier character are closely Xrelated in function. XFor example, all the commands Xin the following table have the same command character, X.B 'o' , Xand all draw ellipses, but have different effects based upon the Xnumber of arguments. X.TS Xcenter box; Xc s Xl|l. XCommands that draw \fIellipses\fP X_ X1 \fBESC\fP100,200\fBo\fP X2 \fBESC\fP100,200,300,400\fBo\fP X3 \fBESC\fP100,200,300,400,2\fBo\fP X.TE XAll of the ellipses have major and minor axis lengths of X.I 100 Xand X.I 200 Xunits respectively. XCommand 1 draws the ellipse at the current graphics location. XCommand 2 draws the ellipse at the location specified by the Xthird and forth arguments, at X.Fr "" 300 400 X\&. XCommand 3 draws the ellipse into scratchpad bitmap number X.I 2 . X.LP XThe second form of \*M commands, Xwhich is a special case of the first form, Xis used for downloading data from the Xclient program to \*M. XThe integer X.I length Xspecifies the number of bytes of data to be downloaded, and X.I data Xare the X.I length Xnumber of data values downloaded. XAn example of the second type of \*M command is X.TS Xcenter box; Xc. X\fBESC\fP11,7\fBb\fP\fII-moved\fP X.TE Xwhich instructs \*M to send the client program the string X.I "I-moved" Xany time the client's window is moved to a different location Xon the display. XThe X.I 11 Xrefers to the number of the X.I move Xevent and the X.I 7 Xis the number of characters in the event string, which in this case is X.I "I-moved" . X.LP XAll of the command identifier characters are listed in X.I "window.h" . XThe command actions, determined by the command identifier and number Xof command arguments, are described by the macros in this document. X.Sh page Conventions and Notation XAll functions and macros and programming examples are shown X.ft \*(Ff Xin a typewriter font X.ft Xto distinguish them from ordinary text. XSimilarly, function and macro arguments are shown in a X.ft \*(Fn Xbold typewriter font. X.ft X.LP XThe names of often used Xarguments passed to macros indicate their function, Xand are defined below. X.Ad column , row XThe integers X.Fa column Xand X.Fa row Xrefer to a character position in X.I character Xcoordinates even though characters may be placed at arbitrary pixel Xlocations within a window Xand need not fall on X.Fa column Xor X.Fa row Xboundaries. X.Ad Dwidth , Dheight XThe integers X.Fa Dwidth Xand X.Fa Dheight Xrepresent a width and height in X.B display Xcoordinates. X.Ad mode XThe positive integer X.Fa mode , Xrepresents the bit combination Xof window modes. X.Fa Mode Xis usually an X.I or ed Xlist of constants in X.I term.h . XA typical use of X.Fa mode Xis the argument to X.Fr m_push mode X as in X.Fr m_push "P_FLAGS \(br P_EVENT \(br P_MENU" X\&. X.Ad n XThe small non-negative integer X.Fi n Xrepresents a resource descriptor Xwhen describing objects such as windows, fonts, or menus. X.Ad name X.Fa Name Xis the file name of a bitmap image on the X.I \*M-host Xmachine. XFile names given with no directory prefix are referenced relative to Xthe X.I icon Xsubdirectory of X\*M's Xhome directory. XThe home directory is installation dependent, and may be determined with Xthe command X.I "\*M -V" . X.Ad parent , child XThe small positive integers X.Fa parent Xand X.Fa child Xrepresent menus. XA X.I child Xmenu is linked Xto a X.I parent Xmenu forming a tree of menus. X.Ad radius XThe positive integer X.Fa radius Xalong with X.Fa radius1 Xand X.Fa radius2 Xsignifies a radius when referring to circles or Xmajor and minor axis when referring to ellipses. XThey are only referenced in respect to X.I window Xcoordinates. X.Ad string XAn array of characters, X.Fi string Xis a null terminated X.SM XASCII X.LG Xcharacter string. XExcept where noted, several X.SM XASCII X.LG Xcontrol characters can be included in Xstrings by escaping them with \e\fIX\fP, where X.I X Xis one of the characters shown in the following table. X.TS Xcenter box; Xc s s Xc | c | c Xc | c | c Xr | l | l. XCharacter string control characters X_ Xescape octal Meaning Xcharacter value X= X\eb 010 Back space X\eE 033 Escape X\ee 033 Escape X\ef 014 Form feed X\eg 007 Bell X\eM * Turn on X 8'th (parity) bit X\en 012 New line X\er 015 Return X\es 040 Space X\e\e 134 Back-slash (\e) X X.TE X.ce X* \s-2(the next character has its 8'th bit turned on)\s+2 X.Ad to , from XThe small positive integers X.Fa to Xand X.Fa from Xidentify the destination and source bitmaps for X.I bit-blt Xoperations. XThe value 0 (zero) represents the current window bitmap; Xpositive integers name scratch-pad bitmap storage. X.Ad width , height XThe integers X.Fa width Xand X.Fa height Xrepresent a width and height in X.B window Xcoordinates. X.Ad X , Y XThe integer pair X.Fr "" X Y X represents a point in X.I display Xcoordinates. XThe suffixes X.Fi src Xand X.Fi dst Xas in X.Fr "" X_src Y_src X or X.Fr "" X_dst Y_dst X are used to indicate X.I source Xand X.I destination Xcoordinates respectively. XSimilarly, the suffixes X.Fi 1 Xand X.Fi 2 Xas in X.Fr "" X1 Y1 X refer generically to the first or second coordinate. X.Ad x , y XThe integers X.Fr "" x y X represent a point in X.I window Xcoordinates. Whether that is X.I relative X(i.e. 0-999) or X.I absolute Xdepends upon the current coordinate setting of the window. XAs with X.Fr "" X Y X above, the modifiers X.Fi src , dst , 1 , Xand X.Fi 2 Xrefer respectively to the X.I source , X.I destination , X.I first , Xand X.I second Xcoordinates. END_OF_FILE # end of 'doc/usrman/doc.1' fi if test -f 'doc/usrman/doc.3' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'doc/usrman/doc.3'\" else echo shar: Extracting \"'doc/usrman/doc.3'\" \(19981 characters\) sed "s/^X//" >'doc/usrman/doc.3' <<'END_OF_FILE' X'\" Copyright (c) 1988 Bellcore X'\" All Rights Reserved X'\" Permission is granted to copy or use this program, EXCEPT that it X'\" may not be sold for profit, the copyright notice must be reproduced X'\" on copies, and credit should be given to Bellcore where it is due. X'\" BELLCORE MAKES NO WARRANTY AND ACCEPTS NO LIABILITY FOR THIS PROGRAM. X'\" X'\" $Header: doc.3,v 4.2 88/06/30 12:44:57 bianchi Exp $ X'\" $Source: /tmp/mgrsrc/doc/usrman/RCS/doc.3,v $ X.Fh m_font n X.Fs m_font 6 "Change to a new font" XChange to font X.Fi n . XThe line positioning is adjusted to keep Xthe baseline of the new and old fonts the same. XFont numbers are small integers X(currently no more than 15). XFont 0 (zero) always refers to the built-in or X.I default Xfont. XThe actual fonts associated with the font numbers may be set in the \*M X.I startup Xfile, or changed by clients on the fly X(see X.Fr m_loadfont X). X.Fe X.Fh m_func mode X.Fs m_func 4 "Set the bit-blt and graphics drawing mode" X.Fs m_func 5 "Set the bit-blt function" XSet the drawing mode. XThis specifies the drawing mode for all X.I graphics Xand X.I bit-blt Xoperations. XThe integer X.Fi mode Xis one of 16 possible boolean combinations of Xthe X.I source Xand X.I destination Xbit patterns. XCombinations of bit patterns for which Xthere is no X.I source Xbitmap, such as X.Fr m_bitwrite X or X.Fr m_line X use the modes shown in the middle column of the following table. XSeveral common X.Fi mode s Xare specified for the bit patterns in which the source Xbitmap is relevent. X.TS Xcenter box; Xc s s Xc | c | c Xl | l | l. XNames for \fBbit-blt\fP modes X_ Xsource no source comments X= XB_OR B_SET default XB_COPY B_CLEAR XB_COPYINVERTED B_INVERT XB_XOR XB_AND X X.TE XAlternately, X.Fi mode Xmay be derived with a boolean combination of X.Fi B_SRC Xand X.Fi B_DST, Xthus X.Fi B_OR Xis equivalent to X.Fi ( B_SRC " \(br " B_DST ). X.Fe X.Fh m_getchar X.Fs m_getchar 2 "Read a character from \*M" XThe macro X.Fr m_getchar Xis equivalent to the X.I stdio Xroutine X.I getchar() , Xexcept the character is retrieved from \*M via the file pointer X.I m_termin Xinstead of X.I stdin. X.Fe X.Fh m_gets buff X.Fs m_gets 2 "Read a line from \*M" XA line of characters is read from \*M and placed into X.Fi buff . XThe macro X.Fr m_gets Xreturns X.SM X.I NULL X.LG Xif the connection to \*M is severed. XThe macro X.Fr m_gets Xis equivalent to the stdio X.I fgets() Xcall Xexcept input is retrieved from \*M. X.Fe X.Fh m_getinfo mode X.Fs m_getinfo 7 "Ask \*M for information" XThis function requests \*M to return information back to the client program. X.Fi Mode Xspecifies one of (currently) 16 different requests. XResponses are always terminated with a X.I "new line" Xfor single line responses, and with a pair of X.I "new lines" Xfor multi-line Xresponses. XConsequently, clients can request and process information requests Xusing normal line mode processing. XThe following list of information requests is understood. X.RS X'\" .IP \fBG_ALLFONT\fP 0.5i Size information for all fonts. X'\" .br X'\" The X'\" .I width X'\" and X'\" .I height X'\" in pixels for a character in each font is listed in a space X'\" separated list. X'\" The first pair of numbers is the character size of font X'\" .B 0 , X'\" the next pair for font X'\" .B 1 , X'\" and so on. X'\" The first request for X'\" .Fi G_ALLFONT X'\" can be expensive, as it requires reading each font X'\" from the disk that has not yet been used. X.IP \fBG_ALLMINE\fP 0.5i Window status for alternate windows. X.br XInformation about each window that may be written to by the client program Xis returned, one line of information per window, as a Xlist of space separated items. XThe first two items give the location of the top left Xcorner of the window in X.I display Xcoordinates. XThe second two items give the X.I height Xand X.I width Xof the window, Xalso in X.I display Xcoordinates. XThe next field contains the last two characters of the X.I pseudo tty Xassociated with each window. XNormally the X.I pseudo tty Xis the same for each window reported. XThe next field contains the X.I "window id" , Xwhich is 0 (zero) Xfor the primary window, Xand the value returned by the call to X.Fr m_makewindow Xfor the other windows (if any). XThe final field contains the visual status of the window, Xwhich is either X.SM X.I C_EXPOSED X.LG X('e') Xif the window is completely visible, Xor X.SM X.I C_OBSCURED X.LG X('o') Xif the window is partly or completely obscured. XThe window information is printed in order from X.I front Xto X.I back . XA sample line might look something like: X.TS Xcenter box; Xc. X492 2 652 570 p6 2 o X.TE Xwhich indicates that the window at X.Fr "" 492 2 X is X.Fi 652 Xpixels X.I wide Xand X.Fi 570 Xpixels X.I high , Xhas a controlling X.I pseudo tty Xof X.I /dev/tty\fBp6\fP, Xis alternate window number X.Fi 2, Xand is at least partially obscured. X.IP \fBG_ALL\fP 0.5i Status of all windows. X.br XInformation about all windows Xis returned, one line of information per window, as a Xlist of space separated items. XThe first two items give the location of the top left Xcorner of the window in X.I display Xcoordinates. XThe second two items give the X.I height Xand X.I width Xof the window, Xalso in X.I display Xcoordinates. XThe next field contains the last two characters of the X.I pseudo tty Xassociated with each window. XNormally the X.I pseudo tty Xis the same for each window controlled by the same client. XThe next field contains the X.I "window id" , Xwhich is 0 (zero) Xfor a primary window, Xand the value returned by the call to X.Fr m_makewindow Xfor alternate windows. XThe final field contains the visual status of the window, Xwhich is either X.SM X.I C_EXPOSED X.LG X('e') Xif the window is completely visible, Xor X.SM X.I C_OBSCURED X.LG X('o') Xif the window is partly or completely obscured. XThe window information for each window is printed in order from X.I front Xto X.I back. XThus the first line returned is currently the X.I active Xwindow. XA sample line might look something like: X.TS Xcenter box; Xc. X492 2 652 570 p6 0 o X.TE XWhich indicates that the window at X.Fr "" 492 2 X is X.Fi 652 Xpixels X.I wide Xand X.Fi 570 Xpixels X.I high, Xhas a controlling X.I pseudo tty Xof X.I /dev/tty\fBp6\fP, Xis a main window, Xand is at least partially obscured. X.IP \fBG_COORDS\fP 0.5i Window coordinates. X.br XA single line is returned containing the location and size of the Xwindow in X.I display Xcoordinates. XThe first pair of numbers is the position of the top left Xcorner of the window, Xthe second pair of numbers is the window's X.I width Xand X.I height Xin pixels. X.IP \fBG_CURSOR\fP 0.5i X.br XA single line is returned containing the position of the X.I character Xand the X.I graphics Xcursor. XThe first pair of numbers is the current X.I column Xand X.I row Xin character coordinates Xand the second pair of numbers is the Xcurrent X.I graphics location Xin window coordinates. XThe graphics cursor location is reported in either X.I absolute Xor X.I relative Xwindow coordinates, Xdepending upon the window coordinate mode setting. X.IP \fBG_FONT\fP 0.5i Current font information. X.br XA single line is returned which contains current font information. XThe first pair of numbers is the character X.I width Xand X.I height, Xin pixels. XThe next number is the X.I "font number" Xas would be used in a call to X.Fi m_font , Xand the final field is the ascii name of the font. X.IP \fBG_ID\fP 0.5i Alternate window number. X.br XA single line is returned containing the window's alternate window Xid ( 0 for the main window), Xfollowed by the number of windows controlled by the client Xprogram. X.IP \fBG_MOUSE\fP 0.5i Mouse coordinates. X.br XThe mouse position, in X.I display Xcoordinates are returned, followed by the most recent button transition, Xwhich is one of X.Fi 1 , -1 , 2 , -2 . XThe numbers X.Fi 1 Xand X.Fi 2 Xrepresent buttons X.I one Xand X.I two Xon the mouse respectively. XThe third mouse button is reserved for system use and is not accessible to Xclient programs. XA negative value means the button was released; Xa positive value indicates the button is still depressed. X.IP \fBG_MOUSE2\fP 0.5i Scaled mouse coordinates . X.br XThe mouse coordinates, in X.I window Xcoordinates are returned, followed by the most recent button transition, Xwhich is one of X.Fi 1 , -1 , 2 , -2 . XThe numbers X.Fi 1 Xand X.Fi 2 Xrepresent buttons X.I one Xand X.I two Xrespectively. XA negative value means the button was last released; Xa positive value indicates the button is still depressed. XIf the Xmouse is above Xor to the left of the window, Xa negative coordinate value is returned. XIn addition if the window is in X.I relative Xcoordinate mode, coordinate values between X0 and 999 will be reported only if the mouse is within the window. X.IP \fBG_STATUS\fP 0.5i Window status. X.br XA line is returned containing a single character, Xeither X.SM X.I C_EXPOSED X.LG X('e'), X.SM X.I C_OBSCURED X.LG X('o'), Xor X.SM X.I C_ACTIVE X('a') X.LG Xdepending upon whether the window is Xexposed but not the X.I active Xwindow, Xpartially or totally obscured, Xor exposed and the X.I active Xwindow. X.IP \fBG_SYSTEM\fP 0.5i System global information. X.br XA single line containing constant global information is returned. XThere are currently four fields: X.RS X.IP 1) 3 XThe X.I hostname Xof the machine \*M is running on, Xas returned by X.I gethostname() . X.IP 2) 3 XThe width of the display in pixels. X.IP 3) 3 XThe height of the display Xin pixels. X.IP 4) 3 XThe size of the window borders in pixels. X.RE X.IP \fBG_TERMCAP\fP 0.5i X.br XA single line is returned which contains a X.I \s-2TERMCAP\s+2 Xentry for \*M. XThe X.I \s-2TERMCAP\s+2 Xentry is always the same, except for X.I lines Xand X.I columns Xentries (li# and co#), Xwhich vary to reflect the current window size. X.IP \fBG_TEXT\fP 0.5i X.br XA single line containing four integers is returned Xwith the current text region size. XThe first pair of numbers is the top left corner of the text region, Xin X.I window Xcoordinates, the second pair of numbers is the X.I width Xand X.I height Xof the text region. XIf no text region is defined, implying the entire window is the text Xregion, all four numbers are returned as 0 (zero). X.IP \fBG_WINSIZE\fP 0.5i X.br XA single line is returned containing the current number of X.I columns Xand X.I rows Xin the X.I "text region" . XIf no text region is defined, Xthe number of X.I lines Xand X.I columns Xfor the entire window is returned. X.IP \fBG_FLAGS\fP 0.5i Window flags. X.br XA single line is returned containing a hexadecimal number representing Xthe current window mode bits. XEach mode is represented by a bit in the word. XMany of the modes may be X.I set Xor X.I cleared Xwith X.Fr m_setmode X or X.Fr m_clearmode X\&. XSee the discussion of X.Fr m_setmode X for a detailed discussion of these flags. XThe meaningful mode bits are: X.RS X.IP 0x000001 10 XThe window is completely exposed. X.IP 0x000004 10 XIt is possible to use the system X.I cut Xfunction in this window. XThis mode is restored by clearing the window. XSee X.Fr m_clear X\&. X.IP 0x000008 10 XThe window is X.I white Xtext on a X.I black Xbackground. X.IP 0x000010 10 XThe window is in standout mode. XIndividual characters are printed in reverse. X.IP 0x000020 10 XThe window has died. XIf a client sees this flag, the window is about to go away. X.IP 0x000040 10 XExpose the window upon shell output. XThe window will be automatically activated Xwhen the next character arrives for output on the window. X.IP 0x000080 10 XPermit a partially or totally obscured window to update. X.IP 0x000100 10 XDo not kill the window when the original process started in it dies. XThis flag may only be set from the startup file. X.IP 0x000200 10 X.I Vi Xmode is turned on. XPushing the right mouse button sends the characters: X.TS Xcenter box; Xc. X\fBrow\fP H \fBcolumn\fP \(br X.TE Xwhere X.Fi row Xand X.Fi column Xspecifies the character location the mouse is sitting on. XThis has the effect of aligning X.I vi 's Xnotion of the current character position with the mouse. X.IP 0x000800 10 XKeyboard input is refused when the window is active. X.IP 0x001000 10 XAuto wrap mode is turned on. XThe character cursor automatically wraps to the Xbeginning of the next row when it reaches the right margin of the text region. X.IP 0x002000 10 XOverstrike mode is turned on. XCharacters are written to the window using the the current drawing mode, Xas set by X.Fr m_func X\&. X.IP 0x004000 10 XThe window is in X.I absolute Xwindow coordinate mode. X.IP 0x010000 10 XThe system X.I cut Xfunction snarfs complete lines only. X.IP 0x020000 10 XThe system X.I cut Xfunction changes spaces to tabs whenever possible. XTabs are assumed to be every 8 spaces. X.IP 0x040000 10 XThe system X.I cut Xfunction will attempt to snarf text even if errors occur. X.RE X.RE X.Fe X.Fh m_go x y X.Fs m_go 4 "Move the graphics point" XMove the X.I "graphics point" Xto the window position X.Fr "" x y X in the current window coordinates. X.Fe X.Fh m_gotext X.Fs m_gotext 4 "Align the graphics point with the character cursor" XThe graphics point is moved to the bottom left corner of the Xcurrent character cursor location. X.Fe X.Fh m_halfwin X Y Dwidth Dheight X.Fs m_halfwin 11 "Create a window with no process connected to it" XA window is created at X.Fi X , Y Xof size X.Fi Dwidth Xby X.Fi Dheight Xwith no process connected to it. X\*M returns the name of the file, a X.I pseudo-tty , Xthat must be opened in order to Xtalk to the new window. XA process which opens that X.I pseudo-tty Xbecomes a client program, communicating with \*M and the new Xwindow in the usual fashion. XFor a single process managing multiple windows, use X.Fr m_newwin X\&. X.Fe X.Fh m_highlight X Y Dwidth Dheight X.Fs m_highlight 13 "Highlight a portion of the display" X\*M flashes the rectagular portion of the display starting at X.Fi X , Y Xof size X.Fi Dwidth Xby X.Fi Dheight . XThis is an experimental capability and may be removed in the future. X.Fe X.Fh m_incr n X.Fs m_incr 13 "Adjust the character cursor position" XThe current character position is adjusted to the left or Xright X.Fi n Xunits Xin X.I window Xcoordinates. XThe argument X.Fi n Xmay be signed to indicate movement to the left (if negative) or to the Xright (if positive or unsigned). XThis is useful for client programs dealing with proportionally Xspaced text. X.Fe X.Fh m_left n X.Fs m_left 13 "Move character cursor left by tenths of a character width" XMove the character cursor left X.Fi n Xtenths of a character width. XSee also X.Fr m_down X.Fr m_right Xand X.Fr m_up X\&. X.Fe X.Fh m_line x1 y1 x2 y2 X.Fs m_line 4 "Draw a line" XDraw a line in the current window from the coordinate X.Fr "" x1 y1 X to the coordinate X.Fr "" x2 y2 X\&. XThe line is either set, Xcleared or inverted as determined by the last call to X.Fr m_func X\&. X.Fe X.Fh m_linecolor mode color X.Fs m_linecolor 14 "Set the graphics mode and color" XThe drawing mode and color is set for all graphics and bit-blt operations. XThe integer X.Fi mode Xsets the drawing mode, in the manner of X.Fr m_func X\&. XThe integer X.Fi color Xis the index into the color lookup table for the drawing color. XThis command is equivalent to X.Fr m_func Xon a monochrome display. XSee also X.Fr m_fcolor Xand X.Fr m_linecolor X\&. X.Fe X.Fh m_lineto to x1 y1 x2 y2 X.Fs m_lineto 4 "Draw a line on a scratchpad bitmap" XDraw a line Xon the scratchpad bitmap X.Fi to Xfrom the coordinate X.Fr "" x1 y1 X to the coordinate X.Fr "" x2 y2 X\&. XThe line is either set, Xcleared or inverted as determined by the last call to X.Fr m_func X\&. X.Fe X.Fh m_linkmenu parent item child mode X.Fs m_linkmenu 8 "Link two menus together" XThe menus X.Fi parent Xand X.Fi child Xare linked together. XWhen menu X.Fi parent Xis popped up and item number X.Fi item X(starting from zero) Xis highlighted, sliding off to the right of the X.Fi parent Xmenu causes the X.Fi child Xmenu to pop up. XWhen an item is chosen, \*M sends the Xconcatenation of the action strings associated with each of the Xpopped-up menus, Xfrom left to right (i.e. X.Fi parent Xto X.Fi child ). XAn arbitrary tree of menus Xmay be created by linking successive menus together in this Xmanner. XIt is up to the application to indicate on the parent Xmenu item that sliding to the right will pop up a child menu. XTypically "\fB\(->\fP" is used. X.sp XThe X.Fi mode Xargument, Xif not zero, Xchanges the menu options Xfor the X.Fi parent Xmenu. XThe flag settings, Xwhich may be X.I or -ed Xtogether (except for X.SM X.Fi MF_CLEAR X.LG X) are: X.RS X.IP \fBMF_SNIP\fP 0.5i X.br XBy default, when an item in a X.I child Xmenu is selected, Xthe values associated with the highlighted items for all of the ancestor menus Xare concatenated to the X.I child 's Xitem value. XWhen X.SM X.Fi MF_SNIP X.LG Xis enabled, only the string associated with the child menu is returned. X.IP \fBMF_PAGE\fP 0.5i X.br XNormally, whenever a menu is popped-up, the previously Xchosen item is initially highlighted. XIf X.SM X.Fi MF_PAGE X.LG Xis enabled, this behavior is extended to paged menus. X\*M automatically pages through a set of paged Xmenus to highlight the currently selected item. X.IP \fBMF_AUTO\fP 0.5i X.br X\*M will automatically slide to the right and pop up Xa child menu Xto highlight the previously selected item. X.IP \fBMF_CLEAR\fP 0.5i X.br XClears the mode X.SM X.Fi MF_SNIP , X.Fi MF_PAGE , X.LG Xand X.SM X.Fi MF_AUTO . X.LG X.RE XSee also X.Fr m_loadmenu X, X.Fr m_selectmenu X, and X.Fr m_unlinkmenu X\&. X.Fe X.Fh m_loadfont n name X.Fs m_loadfont 6 "Download a font" XThe \*M font whose pathname is X.Fi name Xis downloaded into X\*M, replacing the font currently located at position X.Fi n . XAny subsequent calls to X.Fr m_font Xwill select the newly downloaded font. XThe font that used to be at position X.Fi n Xremains available to windows that are already using it, Xbut is unavailable for future use. XThe format of \*M font files is described in X.I font.h . X.Fe X.Fh m_loadmenu n string X.Fs m_loadmenu 8 "Down load a menu" XThe text X.Fi string Xis downloaded into menu position X.Fi n . XThe first character of X.Fi string Xis the X.I "menu delimiter" Xcharacter. XAll of the menu item strings are concatenated, Xfollowed by all of their action strings. XThe X.I "menu delimiter" Xcharacter separates all of the items and actions Xand terminates the list. XMenus are downloaded at once, as a single entity. XThe macro X.Fr m_selectmenu X is used to have the menu pop-up when a mouse button is pushed. X.Fe X.Fh m_move column row X.Fs m_move 3 "Move the character cursor" XThe character cursor is moved to character location X.Fi column , row X, where X.Fr "" 0 0 X is the top left character position on the window, or on Xthe current text region if one is specified X(see X.Fr m_textregion X). X.Fe X.Fh m_movecursor x y X.Fs m_movecursor 13 "Move the character cursor to an arbitrary coordinate location" XMove the character cursor to the position X.Fr "" x y X in window coordinates. XThis permits characters to be placed at arbitrary pixel locations, Xnot just on character boundaries. XUse X.Fr m_move Xto move to a X.Fi row Xand X.Fi column Xposition. X.Fe X.Fh m_movemouse X Y X.Fs m_movemouse 6 "Move the mouse position" XMove the mouse to position X.Fr "" X Y X in X.I display Xcoordinates. XExcessive use of this macro is anti-social. X.Fe X.Fh m_moveprint x y string X.Fs m_moveprint 13 "Print a string at a given location" XPrint X.Fi string Xat the window coordinate X.Fr "" x y X\&. XThis macro is equivalent to calling X.Fr m_movecursor X followed by X.Fr m_printstr X\&. X.Fe X.Fh m_movewindow X Y X.Fs m_movewindow 6 "Move a window" XMove the window to the display location X.Fr "" X Y X in X.I display Xcoordinates. XIf the new position is too close to the edge of the display for the window Xto fit entirely at the requested location, Xthe right edge or bottom of the window is truncated at the boundary of the Xdisplay. X.Fe X.Fs m_newwin 11 "Make a new window" XAn alternate window is created with the size and location indicated. XThe arguments X.Fi X Xand X.Fi Y Xspecify the upper left corner of the window, X.Fi Dwide Xand X.Fi Dhigh Xthe size. XIf the window is to be to fit at the requested location, Xits size is truncated appropriately. X\*M will return a window number if the creation is successful, or Xa X.I newline Xif the window could not be created. XThe newly created window is made the X.I active Xwindow. XThe macro X.Fr m_selectwin Xis used to enable writing on the newly created window. X.Fe END_OF_FILE # end of 'doc/usrman/doc.3' fi echo shar: End of archive 44 \(of 61\). cp /dev/null ark44isdone MISSING="" for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 \ 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 \ 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 \ 55 56 57 58 59 60 61 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 61 archives. rm -f ark[1-9]isdone ark[1-9][0-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 -- Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.