








                     MGR - C Language Application Interface


                                Stephen A. Uhler

                          Bell Communications Research





9 _I_n_t_r_o_d_u_c_t_i_o_n

 MGR (manager) is a window system for Unix that currently runs on Sun  Worksta-
 tions with SunOS and on Linux, the free i80386/i80486 PC UN*X.  Older versions
 of MGR also run on Xenix, 386-Minix, Macintosh, DEC 3100, Atari ST  MiNT,  and
 the  3b1 Unix-pc.  MGR 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 capabil-
 ities regardless of the type of connection to the workstation running MGR.

 Client programs communicate with MGR via _p_s_e_u_d_o-_t_e_r_m_i_n_a_l_s 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.  MGR provides ASCII terminal emulation and takes respon-
 sibility for maintaining the integrity of the window contents  when  parts  of
 windows become obscured and subsequently uncovered.  This permits naive appli-
 cations to work without modification by providing a default  environment  that
 appears to be an ordinary terminal.

 In addition to terminal emulation,  MGR  provides  each  client  window  with:
 graphics primitives such as line and circle drawing; facilities for manipulat-
 ing 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
 _________________________
               Copyright (c) 1988 Bellcore
                   All Rights Reserved
 Permission is granted to copy or use this program,  EX-
 CEPT  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 modi-
 fied relative to the  original  Bellcore  release,  and
 they  are  currently  maintained  by Michael Haardt and
 Vincent Broman.
9


                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 2 -                     Introduction


 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.  MGR notifies a client program of an event  by  sending  it  an  ASCII
 character string in a format specified by the client program.  Existing appli-
 cations can be integrated into the windowing environment without  modification
 by  having  MGR  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.  MGR also provides a _c_u_t and  _p_a_s_t_e  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  MGR.   The  _C
 _I_n_t_e_r_f_a_c_e  _l_i_b_r_a_r_y  provides a set of macros and functions which implement the
 stream protocol and provide clients written in _C with a function  call  inter-
 face  to  MGR.  This library provides the lowest level access to MGR 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  _S_t_a_n_d_a_r_d  _I/_O  _L_i_b_r_a_r_y
 for  its  operation  and  access  to  a byte sequential I/O interface from the
 underlying operating system.


































                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 3 -               Model of Interaction


 _M_o_d_e_l _o_f _I_n_t_e_r_a_c_t_i_o_n

 The basic unit within MGR 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  MGR  are
 defined  entirely  in terms of the state of a client's window or windows.  MGR
 has no concept of window types; there are no separate _g_r_a_p_h_i_c_s  _w_i_n_d_o_w_s,  _t_e_x_t
 _w_i_n_d_o_w_s, or _e_d_i_t _w_i_n_d_o_w_s.  Every window supports exactly the same set of capa-
 bilities 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  over-
 lapping  windows  is  handled  entirely by MGR.  For example, when a window is
 partially or totally obscured by another window, then subsequently  uncovered,
 MGR  restores  the  integrity  of  the  window's  contents.  There are no _s_u_b-
 _w_i_n_d_o_w_s, 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 _a_c_t_i_v_e  win-
 dow.   This is the window that receives keystrokes and mouse data.  It is dis-
 tinguishable to the user from the other windows on the display by  its  embol-
 dened  border.  The active window, in addition to receiving all mouse and key-
 board 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 _l_o_c_a_l, that is the change affects
 just its window.  Only the active window may  effect  _g_l_o_b_a_l  changes  to  the
 display,  such  as  changing  its shape or position.  The only global action a
 _n_o_n-_a_c_t_i_v_e window may perform is to become the  active  window.   This  window
 model  provides  both  the  user and application developer with a simple, con-
 sistent model of interaction.

9 _C_o_o_r_d_i_n_a_t_e _S_y_s_t_e_m_s

 MGR uses four different coordinate systems,  _d_i_s_p_l_a_y  coordinates  ,  _a_b_s_o_l_u_t_e
 _w_i_n_d_o_w  coordinates,  _r_e_l_a_t_i_v_e  _w_i_n_d_o_w coordinates, and _c_h_a_r_a_c_t_e_r coordinates.
 The entire display is represented by _d_i_s_p_l_a_y _c_o_o_r_d_i_n_a_t_e_s whereas  each  window
 has  its  own  _a_b_s_o_l_u_t_e _w_i_n_d_o_w, _r_e_l_a_t_i_v_e _w_i_n_d_o_w, and _c_h_a_r_a_c_t_e_r coordinate sys-
 tems.

 _D_i_s_p_l_a_y _c_o_o_r_d_i_n_a_t_e_s are in units of pixels.  The coordinate ( 0,0)is  the  top
 left  pixel  on  the  display.  The _X coordinate increases to the right, the _Y
 coordinate increases down.  The maximum _X and _Y  coordinate  depend  upon  the
 particular display in use, for the SUN-3 they are 1152 by 900 .  Commands that
 operate on the context of the entire display, such as reshaping a  window  are
 specified  in  _d_i_s_p_l_a_y coordinates.  Windows, when measured in _d_i_s_p_l_a_y coordi-
 nates include their borders.

 _A_b_s_o_l_u_t_e _w_i_n_d_o_w _c_o_o_r_d_i_n_a_t_e_s, as with  _d_i_s_p_l_a_y  _c_o_o_r_d_i_n_a_t_e_s,  are  measured  in
 units  of  pixels.   The X and Y values increase to the right and down respec-
 tively.  The origin, coordinate ( 0,0)is at the top left corner of the window,
 just inside the window border.


9                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 4 -                Coordinate Systems


 _R_e_l_a_t_i_v_e _w_i_n_d_o_w _c_o_o_r_d_i_n_a_t_e_s are measured as a fraction of  the  window's  size
 and shape.  As with _a_b_s_o_l_u_t_e _w_i_n_d_o_w _c_o_o_r_d_i_n_a_t_e_s, 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 _r_e_l_a_t_i_v_e _w_i_n_d_o_w _c_o_o_r_d_i_n_a_t_e_s are  automatically  scaled
 to the size of the window.

 _C_h_a_r_a_c_t_e_r _c_o_o_r_d_i_n_a_t_e_s are measured in rows and columns in  the  current  font,
 just  like an ordinary terminal.  The coordinate ( 0,0)is the top left charac-
 ter position in the window.  The maximum _r_o_w and _c_o_l_u_m_n in the window  depends
 on both the window and font size.

9 _F_u_n_c_t_i_o_n_a_l _O_v_e_r_v_i_e_w

 The types of commands a client program may  issue  MGR  are  divided  into  14
 categories:  _t_e_r_m_i_n_a_l _e_m_u_l_a_t_i_o_n, _g_r_a_p_h_i_c_s, _b_i_t-_b_l_i_t_s, _w_i_n_d_o_w _p_o_s_i_t_i_o_n_i_n_g, _f_o_n_t
 _c_h_a_n_g_e_s, _s_t_a_t_e _i_n_q_u_i_r_y, _s_a_v_e_d _c_o_n_t_e_x_t_s, _m_e_n_u_s, _e_v_e_n_t_s, _s_w_e_e_p _f_u_n_c_t_i_o_n_s, _m_u_l_t_i_-
 _p_l_e _w_i_n_d_o_w _m_a_n_i_p_u_l_a_t_i_o_n, _c_u_t _a_n_d _p_a_s_t_e, _m_e_s_s_a_g_e_s, and _w_i_n_d_o_w _m_o_d_e_s.  What fol-
 lows is a brief description of those command categories, and some examples  of
 specific  functions  within the category.  A detailed description of each com-
 mand is provided in the following section.

 _T_e_r_m_i_n_a_l _E_m_u_l_a_t_i_o_n
 At its most basic level, every MGR window emulates a _C_R_T  terminal.   It  pro-
 vides  functions for _i_n_s_e_r_t_i_n_g and _d_e_l_e_t_i_n_g lines and characters, highlighting
 text, clearing areas and windows, and arbitrary  cursor  motion  capabilities.
 Sample  MGR  _T_E_R_M_C_A_P  and _T_E_R_M_I_N_F_O descriptions are given in the tables below.
 No entries are provided for keyboard key values, as they depend upon the  par-
 ticular keyboard in use.

8 ______________________________
    Sample MGR _T_E_R_M_C_A_P Entry
8 ______________________________
  Px | MGR | MGR 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:
8 ______________________________
7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|













                              |7|7|7|7|7|7|7|7|7|7|7|7|7|7|















7777777777777777778

8                               ________________________________________________
                                          Sample MGR _T_E_R_M_I_N_F_O Entry
8                               ________________________________________________
                                Px | MGR | MGR 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,
8                               ________________________________________________
7                              |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|














                                                                              |7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|

















 MGR permits the client program to restrict the terminal emulator to  an  arbi-
 trary  subrectangle  within  the window, called a _t_e_x_t _r_e_g_i_o_n.  For example, a
 text editor wishing to provide scroll bars or banner lines can still  let  MGR
 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



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 5 -               Functional Overview


 will, permitting multiple terminal sub regions in the same window.

 _G_r_a_p_h_i_c_s
 In addition to terminal emulation, MGR 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 _g_r_a_p_h_i_c_s _p_o_i_n_t, maintained by
 MGR.  The objects may also be drawn into undisplayed or _s_c_r_a_t_c_h_p_a_d areas, then
 copied to the window as a single unit.  The _g_r_a_p_h_i_c_s _p_o_i_n_t 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, per-
 mitting 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.

 _B_i_t-_b_l_t_s
 MGR provides a complete set of functions for dealing  with  bitmaps,  or  rec-
 tangular  arrays of pixels.  Bitmaps may be combined with any of the 16 possi-
 ble _b_i_t-_b_l_t operations.   Non-displayed  bitmaps  of  arbitrary  size  may  be
 created  and  destroyed, and _b_i_t-_b_l_t_s 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 MGR,  or up-loaded from MGR to the client program.   In  addition,  bitmaps
 may  be  saved in files by MGR, or loaded into MGR 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.

 _W_i_n_d_o_w _P_o_s_i_t_i_o_n_i_n_g
 Either the user or a client program running in the _a_c_t_i_v_e 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 _a_c_t_i_v_e window, it may be
 _b_u_r_i_e_d (shoved to the back on the display).  If the window is not  the  _a_c_t_i_v_e
 window,  it  can  become  the  active  window  and  then be moved about on the
 display.

 _F_o_n_t _C_h_a_n_g_e_s
 Client programs may change character fonts at any time, even on a character by
 character  basis.  MGR 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  MGR are constant width, that is _i's take up the same amount of room as _m's
 do.  There are commands to aid client programs that wish to  use  proportional
 fonts.

 _S_t_a_t_e _I_n_q_u_i_r_y
 A client program may ask MGR 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 set-
 tings.   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.



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 6 -               Functional Overview


 The display organization may include the position, size, name, ownership,  and
 spatial ordering for all windows on the display.

 _S_a_v_e_d _C_o_n_t_e_x_t_s
 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  posi-
 tion, etc. may be stacked independently, or in any combination.

 _M_e_n_u_s
 MGR 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 _s_e_l_e_c_t_s which menu will pop-up when a  mouse
 button  is  pushed.   When an item of a pop-up menu is chosen, MGR 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 _p_a_r_e_n_t menu) while an item is selected
 can cause another menu (called a _c_h_i_l_d menu) to  pop  up.   Any  item  of  the
 _p_a_r_e_n_t menu may be specified as the entry item for a child menu.  Upon select-
 ing an item of a _c_h_i_l_d menu, the client program may arrange for MGR to  return
 ether  the  action  string  associated  with  just the _c_h_i_l_d menu item, or the
 action strings for the selected items of all the menus.   Similar  to  _s_l_i_d_i_n_g
 menus,  MGR  supports  _p_a_g_i_n_g  menus  as  well.  Long menus may be broken into
 several pages by the client program.  MGR manages  the  paging  automatically,
 popping up the next page as the user slides off the bottom of a paged menu.

 _E_v_e_n_t_s
 Client programs may arrange to be informed by MGR 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 _a_c_t_i_v_e
 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.

 _S_w_e_e_p _F_u_n_c_t_i_o_n_s
 It is often convenient for client programs to  _s_w_e_e_p,  or  _r_u_b_b_e_r-_b_a_n_d  simple
 objects,  such  as  lines or boxes, in response to moving the mouse.  MGR pro-
 vides client programs with a mouse activated sweep function.   MGR  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 MGR.

 _M_u_l_t_i_p_l_e _W_i_n_d_o_w _M_a_n_i_p_u_l_a_t_i_o_n
 A single client program may create and manipulate additional  windows,  called
 _a_l_t_e_r_n_a_t_e  windows.   The data destined for, or to be received from, an _a_l_t_e_r_-
 _n_a_t_e 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 _e_v_e_n_t mechanism to determine from which window input arrived.



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 7 -               Functional Overview


 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  perfor-
 mance begins to degrade seriously.

 _C_u_t _a_n_d _P_a_s_t_e
 MGR provides a globally accessible _s_n_a_r_f buffer shared among all  client  pro-
 grams.   Any  client  program may put data into or read data from this buffer.
 MGR provides a user initiated _c_u_t and _p_a_s_t_e function from  the  command  menu.
 MGR  extracts  character text from the window and places its ASCII representa-
 tion into the _s_n_a_r_f buffer.  _P_a_s_t_e copies the contents of the _s_n_a_r_f buffer  to
 the  input  stream of the active window.  Client programs, by manipulating the
 data in the _s_n_a_r_f buffer, can interact with the system  _c_u_t  and  _p_a_s_t_e  func-
 tions.

 _M_e_s_s_a_g_e_s
 Although the _s_n_a_r_f buffer gives client programs a simple  asynchronous  inter-
 process  communication mechanism, MGR has a more general synchronous interpro-
 cess 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  _e_v_e_n_t  and
 encapsulate the message and sender name in the format of its choice.  MGR pro-
 vides the primitives needed to implement _s_e_r_v_e_r clients by permitting  _s_e_r_v_e_r_s
 to register their names, services and protocols with MGR.  Client programs may
 query MGR for a list of active _s_e_r_v_e_r_s.  _S_e_r_v_e_r  messages  may  be  associated
 with  windows  by the _s_e_r_v_e_r client programs in such a way that the message is
 automatically received by a client program as part of  a  _m_o_u_s_e  _b_u_t_t_o_n  event
 whenever  the  mouse  button  is  pressed  on the _s_e_r_v_e_r's window.  Using this
 mechanism, client programs  can  interact  with  _s_e_r_v_e_r  clients  without  any
 advance  knowledge  of  which  _s_e_r_v_e_rs are available or what services they are
 providing.

 _W_i_n_d_o_w _M_o_d_e_s
 Client programs may select various combinations of window modes.  These  modes
 tailor  the  behavior of the macros described above.  Examples of window modes
 include _a_u_t_o _l_i_n_e _w_r_a_p and _c_h_a_r_a_c_t_e_r _o_v_e_r_s_t_r_i_k_e that affect the terminal  emu-
 lation, different coordinate system settings that affect _g_r_a_p_h_i_c_s commands, or
 flags that set a window to _a_c_t_i_v_a_t_e automatically upon receiving input, ignore
 all keyboard input, or suspend output while a window is obscured.

9 _U_n_d_e_r_l_y_i_n_g _P_r_o_t_o_c_o_l

 The purpose of this library package is both to provide a function call  inter-
 face  to  the stream protocol, and to document each command understood by MGR.
 There are two types of MGR commands, as summarized in the table below.

8                    ________________________________________
                              MGR command protocol
8                    ________________________________________

7                     _E_S_C X918, X928,..., X9n8 _c_o_m_m_a_n_d

7                     _E_S_C X918, X928,..., X9n8 _l_e_n_g_t_h _c_o_m_m_a_n_d _d_a_t_a
98                    ________________________________________
7                   |8|7|7|7|


9                                                           |8|7|7|7|




9 In both cases, _E_S_C is the ASCII escape character or '\033', whereas  the  word
 _c_o_m_m_a_n_d  represents  a  single  character  command  identifier.   The  _X's are


9                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 8 -               Underlying Protocol


 optional integers,  there can be as few as zero, as in the command

8                                     ______
                                      ESC_a
8                                     ______
7                                    |8|
8                                          |8|

9 which inserts a blank line in the window, or as many as  eight,  as  would  be
 used by the command

8                           __________________________
                            ESC0,0,50,100,10,20,3,2_b
8                           __________________________
7                          |8|
8                                                    |8|

9 which is an example of a command to copy images between  bitmaps.   No  spaces
 may  be  included between the _E_S_C character and the command identifier charac-
 ter, but the argument separators may be either commas (,) or semicolons (;).

 The function of the command is determined both by the command identifier char-
 acter  and _n, 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, '_o', and all draw  ellipses,  but  have
 different effects based upon the number of arguments.

8                         _____________________________
                          Commands that draw _e_l_l_i_p_s_e_s
8                         _____________________________
                          1     ESC100,200o
                          2     ESC100,200,300,400o
                          3     ESC100,200,300,400,2o
8                         _____________________________
7                        |7|7|7|7|



                             |8|7|7|

9                                                     |7|7|7|7|





 All of the ellipses have major and minor axis lengths of  _1_0_0  and  _2_0_0  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 _2.

 The second form of MGR command, which is a special case of the first form,  is
 used  for downloading data from the client program to MGR.  The integer _l_e_n_g_t_h
 specifies the number of bytes of data to  be  downloaded,  and  _d_a_t_a  are  the
 _l_e_n_g_t_h number of data values downloaded.  An example of the second type of MGR
 command is

8                               _________________
                                ESC11,7b_I-_m_o_v_e_d
8                               _________________
7                              |8|
8                                               |8|

9 which instructs MGR to send the client program the string _I-_m_o_v_e_d any time the
 client's  window  is  moved  to  a  different location on the display.  The _1_1
 refers to the number of the _m_o_v_e event and the _7 is the number  of  characters
 in the event string, which in this case is _I-_m_o_v_e_d.

 All of the command identifier characters are listed  in  _i_n_c_l_u_d_e/_m_g_r/_w_i_n_d_o_w._h.
 The  command  actions, determined by the command identifier and number of com-
 mand arguments, are described by the macros in this document.


9


                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 9 -           Conventions and Notation


 _C_o_n_v_e_n_t_i_o_n_s _a_n_d _N_o_t_a_t_i_o_n

 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  _c_h_a_r_a_c_t_e_r
      coordinates even though characters may be placed at arbitrary pixel loca-
      tions 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  _d_i_s_p_l_a_y
      coordinates.

 mode
      The positive integer mode,  represents  the  bit  combination  of  window
      modes.     Mode    is    usually   an   _o_red   list   of   constants   in
      _i_n_c_l_u_d_e/_m_g_r/_w_i_n_d_o_w._h.  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 n 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  _M_G_R-_h_o_s_t  machine.   File
      names  given with no directory prefix are referenced relative to the _i_c_o_n
      subdirectory of MGR's home directory.  The home directory is installation
      dependent, and may be determined with the command _M_G_R -_V.

 parent,child
      The small positive integers parent and child represent  menus.   A  _c_h_i_l_d
      menu is linked to a _p_a_r_e_n_t 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 _w_i_n_d_o_w coordinates.

 string
      An array of characters, string  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  _X  is  one  of  the
      characters shown in the following table.









                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 10 -          Conventions and Notation



8                       _______________________________________
                         Character string control characters
8                       _______________________________________
                         escape     octal        Meaning
                        character   value
8                       ______________________________________________________________________________
                               \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 (\)

8                       _______________________________________
7                      |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|














9                                 |7|7|7|7|7|7|7|7|7|7|7|7|7|7|













                                         |7|7|7|7|7|7|7|7|7|7|7|7|7|7|













                                                             |8|7|7|7|7|7|7|7|7|7|7|7|7|7|7|7|
















9                  * (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 _b_i_t-_b_l_t 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  _w_i_n_d_o_w
      coordinates.

 X,Y
      The integer pair ( X,Y) represents a point in _d_i_s_p_l_a_y  coordinates.   The
      suffixes  src  and dst as in ( X_src,Y_src) or ( X_dst,Y_dst) are used to
      indicate _s_o_u_r_c_e and _d_e_s_t_i_n_a_t_i_o_n coordinates respectively.  Similarly, the
      suffixes  1 and 2 as in ( X1,Y1) refer generically to the first or second
      coordinate.

 x,y
      The integers ( x,y) represent a point  in  _w_i_n_d_o_w  coordinates.   Whether
      that  is _r_e_l_a_t_i_v_e (i.e. 0-999) or _a_b_s_o_l_u_t_e depends upon the current coor-
      dinate setting of the window.  As with ( X,Y) above, the  modifiers  src,
      dst,  1,  and 2 refer respectively to the _s_o_u_r_c_e, _d_e_s_t_i_n_a_t_i_o_n, _f_i_r_s_t, and
      _s_e_c_o_n_d coordinates.














                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 11 -                          Macros


 _M_a_c_r_o_s

 The C library interface macros expand into  _p_r_i_n_t_f  expressions  that  convert
 their  command  specification  into the MGR stream protocol.  Compile time and
 run time options are available that globally alter the behavior of these  mac-
 ros  to the specific needs of the client program.  The options are detailed in
 the _U_s_i_n_g _t_h_e _L_i_b_r_a_r_y section of this document.  The macros should be regarded
 as  statements,  not  as expressions returning values.  The macro descriptions
 here attempt to reflect the actual state of the system, and may  include  some
 inconsistencies  that should be cleaned up in future releases of the software.
 Every MGR command (a command identifier - argument count combination) that  is
 accepted by MGR has a macro which invokes that function.


 m_addchar()
      Inserts a space character at the current character cursor position.   The
      remaining characters on the line, if any, are shifted to the right.

 m_addchars( n)
      Inserts n space characters at the current character cursor position.  The
      remaining characters on the line, if any, are shifted to the right.

 m_addline()
      Inserts a blank line at current row. The current row, and any  below  it,
      are  shifted  down one line.  The bottom line of text is scrolled off the
      window.

 m_addlines( n)
      Inserts n blank lines at current row. The current row, and any below  it,
      are  shifted  down.  The bottom n lines of text are scrolled off the win-
      dow.  It is much more efficient to call m_addlines( n) once, than  it  is
      to call m_addline()n times.

 m_aligntext()
      Moves the current character cursor coincident with the  current  graphics
      point.   The current graphics point is set with m_go( x,y).  This permits
      client programs to position characters at arbitrary  pixel  locations  on
      the window.

 m_arc( x,y,x1,y1,x2,y2)
      An arc centered at ( x,y) is drawn counter clockwise from ( x1,y1)  to  (
      x2,y2) using the current drawing function (see m_func()).

 m_bell()
      The window flashes and the bell, if there is one,  rings.   Even  if  the
      window is totally obscured, its flashing is made visible to the user.

 m_bcolor( color)
      The background color for text operations is set to  color,  which  is  an
      index into the color lookup table.  This command has no effect on a mono-
      chrome display.  See also m_fcolor() and m_fgbgcolor().

 m_bitccreate( n,wide,high,deep)
      Create the scratchpad bitmap n of size wide by high with bit  depth  deep



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 12 -                          Macros


      having   undefined   initial   contents.   This  macro  is  identical  to
      m_bitcreate()except that if deep is specified to be other than one,  then
      the  bitmap  is given the same bit depth as that of the window or screen,
      generally eight on a color system.

 m_bitcld( wide,high,x,y,deep,size)
      Prepare MGR to download a color or monochrome bitmap to the window.  This
      macro instructs MGR that the next size bytes received will be interpreted
      as a bitmap image to be displayed on the window starting  at  location  (
      x,y),  and  of  size  wide  by high by deep in bits.  Downloading bitmaps
      requires an eight bit channel between MGR and the client program.   Large
      bitmaps  are  best  sent  in  several  pieces.  The macro m_bitfromfile()
      should be used instead, where possible, as it only requires a  seven  bit
      data channel and avoids the movement of large amounts of data through the
      channel.  If more bytes are specified than required by the  size  of  the
      bitmap,  they are discarded.  If the number specified by size is insuffi-
      cient to fill the entire bitmap, the remainder of the  bits  are  set  to
      undetermined values.  The bitmap data is sent in external format.

 m_bitcldto( wide,high,x_dst,y_dst,deep,to,size)
      Prepare to download a bitmap to the scratchpad bitmap to.  If to does not
      already exist, (see m_bitcreate()), it is created automatically with size
      wide by high by deep in bits.  This function instructs MGR that the  next
      size bytes received will be interpreted as a bitmap image to be copied to
      scratchpad bitmap to at location x_dst,y_dst.  This function requires  an
      eight  bit channel between MGR and the client program.  If more bytes are
      specified than required by the size of the bitmap,  they  are  discarded.
      If  the  number specified by size is insufficient to fill the entire bit-
      map, the remainder of the bits are set to undetermined values.  The  bit-
      map data is sent in external format.

 m_bitcopy( x_dst,y_dst,wide,high,x_src,y_src)
      Copy a rectangle from one place on the window to another  with  the  copy
      function  set  by m_func( n). The rectangular area at x_src,y_src of size
      wide by high is combined with the rectangle at x_dst,y_dst  according  to
      the  last function set by m_func().  The resultant rectangle is placed at
      x_dst,y_dst.

 m_bitcopyto( x_dst,y_dst,wide,high,x_src,y_src,to,from)
      Combine the rectangle at position x_src,y_src of size  wide  by  high  of
      bitmap from with the rectangle of the same size at x_dst, y_dst of bitmap
      to.  The bit-blt function used to combine the two rectangles  is  set  by
      m_func().   From  and  to are scratch-pad bitmap descriptors.  Scratchpad
      bitmap 0 (zero) represents the current window contents and  may  be  used
      for  the  source, destination, or both.  If the scratchpad bitmap to does
      not already exist, it is created with a size of wide+x_src by high+y_src.

 m_bitcreate( n,wide,high)
      Create the scratchpad bitmap n of size wide by high with bit  depth  one,
      i.e.  monochrome.   The  contents of the bitmap are undefined.  The macro
      m_bitwriteto() can be used to initialize the scratchpad bitmap.   If  the
      bitmap  already  exists, the old one is first discarded.  Scratchpad bit-
      maps may also be created implicitly by specifying a  non-existent  bitmap
      as  the  destination  of  m_bitwriteto(),  m_bitcopyto(),  m_bitld(),  or



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 13 -                          Macros


      m_stringto().

 m_bitdestroy( n)
      Destroys scratchpad bitmap n and frees all the resources associated  with
      it.  If n does not exist, this macro has no effect.

 m_bitfromfile( to,name)
      Copy the file name on the _M_G_R-_h_o_s_t machine into the scratchpad bitmap to.
      The  scratchpad  bitmap  to is created if it does not already exist.  _M_G_R
      returns  a single line containing the _w_i_d_t_h and _h_e_i_g_h_t of the bitmap,  or
      a _b_l_a_n_k if the file could not be found or loaded.  If name does not start
      with / or ./, The file name is prefixed with  MGR's  home  directory  and
      /_i_c_o_n/.   Names  starting with ./ are evaluated relative to the directory
      current when _M_G_R was invoked.  The formats of bitmap files are  described
      in the _i_n_c_l_u_d_e/_m_g_r/_m_g_r._h header file.

 m_bitget( from,size,offset)
      Upload part of a _s_c_r_a_t_c_h_p_a_d bitmap.   Size  bytes  of  _s_c_r_a_t_c_h_p_a_d  bitmap
      from,  starting offset bytes from the beginning of the bitmap are sent to
      the client program from _M_G_R.  After this call, the client is expected  to
      read  size bytes from the input stream.  The image data is sent in exter-
      nal bitmap format, i.e., raster scan order, 8 pixels to a bigendian byte,
      padded  at  the right of every line to 8 bits.  Size should be kept small
      (about 80 bytes), to avoid potential flow control problems, with  bitmaps
      uploaded  in  multiple  passes.   The  data  sent  by  MGR for this macro
      requires an eight bit data channel, so its use is discouraged.  The macro
      m_bitsave() should be used instead when possible.

 m_bitld( wide,high,x,y,size)
      Prepare MGR to download a monochrome  bitmap  to  the  window.   This  is
      identical to a call to m_bitcld with the parameter deep set to one.

 m_bitldto( wide,high,x_dst,y_dst,to,size)
      Prepare to download a monochrome bitmap  to  the  scratchpad  bitmap  to.
      This  is identical to a call to m_bitcldto with the parameter deep set to
      one.

 m_bitsave( from,name)
      Save a scratchpad bitmap from on the file name on the _M_G_R-_h_o_s_t file  sys-
      tem.   If  name  does not start with / or ./, name is prefixed with MGR's
      home directory and /_i_c_o_n/.  Names starting with ./ are evaluated relative
      to  the  directory current when _M_G_R was invoked.  Specifying from to be 0
      (zero) saves the entire display contents  to  the  file.   The  functions
      m_windowsave() and m_othersave() are used to save contents of entire win-
      dows.

 m_bitset( map,x,y,v)
      Set the value of the pixel _x, on the bitmap _m_a_p to the value given in  _v.
      In  a  monochrome version of the MGR server you can only set or clear the
      particular pixel. Use 1 to set, 0 to clear; any other value will have all
      but the low order bit masked out.  A color server will accept values from
      0 to 255.

 m_bitvalue( map,x,y)



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 14 -                          Macros


      Get the current value of the pixel x, y in the bitmap _b_i_t_m_a_p.  The  value
      can  be  read using the m_gets macro.  The string is a newline-terminated
      decimal integer.  A mono server only returns 1 for set, and 0 for  clear.
      A color server may return values from 0 to 255.

 m_bitwrite( x_dst,y_dst,wide,high)
      The rectangular region of the window, starting at x_dst,y_dst  of  extent
      wide  by  high, is set, cleared or inverted as determined by the previous
      call to m_func().

 m_bitwriteto( x_dst,y_dst,wide,high,to)
      The rectangular region of _s_c_r_a_t_c_h_p_a_d bitmap to, starting  at  x_dst,y_dst
      of  extent wide by high, is set, cleared or inverted as determined by the
      previous call to m_func().  If the destination to does not exist,  it  is
      created with the dimensions wide by high.

 m_broadcast( string)
      The message string is  broadcast  to  all  windows  that  are  _l_i_s_t_e_ning.
      _L_i_s_t_e_ning  is  turned  on by setting the ACCEPT event for a window.  (See
      m_setevent()).  Messages can only be sent to  windows  whose  controlling
      terminals  have  general  write permission disabled (i.e. mode 0400) as a
      security measure to prevent  malicious  foreign  processes  from  sending
      _s_h_e_l_ls messages that get interpreted and executed as commands.

 m_circle( x_dst,y_dst,radius)
      A circle of radius radius is drawn, centered at x_dst,y_dst.  The  points
      at the edge of the circle are set, cleared or inverted depending upon the
      last call to m_func().  Circles are never scaled, they always  appear  as
      circles  on  the  display, regardless of the window shape.  The radius is
      scaled based upon the average  width  and  height  of  the  window.   Use
      m_ellipse() to obtain a scaled circle.

 m_clear()
      The current _t_e_x_t _r_e_g_i_o_n is cleared, and the character cursor is moved  to
      position  (  0,0).  If no _t_e_x_t _r_e_g_i_o_n is set, m_clear() clears the entire
      window.

 m_cleareol()
      All of the characters on the current  line,  starting  with  the  current
      character  to the end of the _t_e_x_t _r_e_g_i_o_n, are cleared.  If no _t_e_x_t _r_e_g_i_o_n
      is set, m_cleareol() clears to the edge of the window.

 m_cleareos()
      All of the characters in the current _t_e_x_t _r_e_g_i_o_n, from the current  char-
      acter  to  the end of the _t_e_x_t _r_e_g_i_o_n, are cleared.  If no _t_e_x_t _r_e_g_i_o_n is
      set, m_clear() clears to the end of the window.

 m_clearevent( n)
      Event n is cleared.  The integer n is one of: ACCEPT, ACTIVATE, BUTTON_1,
      BUTTON_1U,  BUTTON_2,  BUTTON_2U,  COVERED,  DEACTIVATE,  DESTROY,  MOVE,
      NOTIFY, PASTE, REDRAW, RESHAPE, SNARFED, or UNCOVERED.  See  m_setevent()
      for a description of the events.

 m_clearmenu( n)



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 15 -                          Macros


      If menu n exists, it is cleared.

 m_clearmode( mode)
      Clear one of the following window modes.  Except where noted,  these  are
      the  default  settings.   The  mode  settings are more fully explained in
      m_setmode().

      M_ABS
           _A_b_s_o_l_u_t_e window coordinate mode is turned off.  The window is now in
           _r_e_l_a_t_i_v_e  window  coordinates.  All  window coordinates range from (
           0,0) in the upper left corner to ( 999,999) at the lower right.

      M_ACTIVATE
           Bury the window. Unlike the other window modes, _b_u_r_y  has  no  state
           associated  with  it, just a one time action.  A window is buried by
           visually pushing it to the bottom of the display; any window  inter-
           secting it will appear in front of it.

      M_AUTOEXPOSE
           Do not automatically activate the window the next time  it  receives
           output.

      M_BACKGROUND
           MGR does not permit the window to  update  if  it  is  partially  or
           totally  obscured.   Data  destined for the window is held until the
           window is uncovered, or _M__B_A_C_K_G_R_O_U_N_D is turned on.

      M_CONSOLE
           This  window  is  not  the   destination   of   stuff   written   to
           "/dev/console".

      M_NOBUCKEY
           Buckey keys, those with value from 128-255, can cause  server  func-
           tions to be executed when typed at the keyboard, if the BUCKEY capa-
           bility was configured into the server at compile time.

      M_NOINPUT
           Accept keyboard input if the window is active.

      M_NOREPORT
           Report changes in window sizes to the OS, if the OS  wants  to  know
           the sizes of terminals attached to ttys.

      M_NOWRAP
           Wrap the character cursor to the next line when it reaches the right
           margin of the _t_e_x_t _r_e_g_i_o_n.

      M_OVERSTRIKE
           Do not overstrike characters.  Text is copied to the  window  as  if
           m_func( BIT_SRC) is set.

      M_SNARFHARD
           The system _c_u_t function fails if any errors are found. This is indi-
           cated  by  flashing  the window.  The contents of the _c_u_t buffer are



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 16 -                          Macros


           left undisturbed.  Normally this only happens if some  process  unk-
           nown to MGR scribbles into the region being cut.

      M_SNARFLINES
           Sets the system _c_u_t function to cut individual  characters,  instead
           of entire lines only.

      M_SNARFTABS
           The system _c_u_t function cuts text exactly as it appears on the  win-
           dow.   All interior white space is converted to _s_p_a_c_es, all trailing
           white space is treated as a _n_e_w _l_i_n_e.

      M_STACK
           Event stacking is turned off.  Event strings are only  returned  for
           the  current  window  context  and not for any contexts stacked with
           m_push().

      M_STANDOUT
           Characters are drawn in black with a white background.

      M_WOB
           The window foreground color is set to _b_l_a_c_k, and  the  window  back-
           ground color is set to _w_h_i_t_e.

      M_DUPKEY
           The keyboard escape character is turned off.  This mode is turned on
           by   calling   m_dupkey().    There  is  no  corresponding  call  to
           m_setmode().

 m_deletechar()
      The character at the cursor position is deleted.  Any characters  on  the
      line  to the right of the cursor are shifted left one character position.
      The last character on the line is set to a _s_p_a_c_e.

 m_deletechars( n)
      The next n characters are deleted, starting at the character cursor posi-
      tion.   Any characters on the line to the right of the cursor are shifted
      left n character positions.  The last n characters on the line are set to
      _s_p_a_c_e.

 m_deleteline()
      The line at the cursor position is deleted.  Any lines below  the  cursor
      are shifted up one line.  The last line is cleared.

 m_deletelines( n)
      The next n lines starting at the cursor position and toward the bottom of
      the  window are deleted.  Any lines below the deleted ones are shifted up
      n lines.  The last n lines are cleared.  It is more efficient to make one
      call to m_deletelines() than to call m_deleteline()n times.

 m_destroywin( n)
      Destroy alternate window n, created by calling m_newwin().  If output  is
      currently directed to this window, it is automatically re-directed to the
      _m_a_i_n window.  See also m_selectwin().



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 17 -                          Macros


 m_down( n)
      Move the character cursor down n tenths of a character height.  This  may
      cause the window to scroll.  See also m_left(), m_right(), and m_up().

 m_draw( x,y)
      Draw a line from current _g_r_a_p_h_i_c_s _p_o_i_n_t to ( x,y).  The macro  m_go()  is
      used  to  move the _g_r_a_p_h_i_c_s _p_o_i_n_t.  The _g_r_a_p_h_i_c_s _p_o_i_n_t is left at ( x,y),
      the end point of the line.

 m_dupkey( char)
      Every time the character char is typed at the keyboard for  this  window,
      it is sent to the client program twice.  This enables clients to reliably
      distinguish keyboard input from that  generated  by  menu  selections  or
      events.  The client begins every _e_v_e_n_t and _m_e_n_u string with a two charac-
      ter code whose first character is char and whose second character is any-
      thing  but  char  or  space.   When  this mode is set, all replies to MGR
      queries, as with m_getinfo()are prepended by the two  character  sequence
      char  followed  by  space.   For  multiline  requests, such as M_getinfo(
      G_ALL)only the first line of the reply is affected.  These two characters
      are  also  prepended  to  all  other MGR commands that return a character
      string to the client program, such as m_newwin() or m_bitfromfile().

 m_ellipse( x,y,radius1,radius2)
      Draw an ellipse centered at ( x,y).  The values for radius1  and  radius2
      are  the  major and minor axis radii.  The ellipse is either set, cleared
      or inverted determined by the last call  to  m_func().   The  values  for
      radius1 and radius2 are scaled based upon the average width and height of
      the window.

 m_ellipseto( to,x,y,radius1,radius2)
      Draw an ellipse  on  scratchpad  bitmap  to  centered  at  (  x,y)  where
      radius1,radius2  are  the  major  and  minor  axis radii.  The ellipse is
      either set, cleared or inverted determined by the last call to  m_func().
      The  values  for  radius1  and  radius2 are scaled based upon the average
      width and height of the window.  If the  offscreen  bitmap  to  does  not
      exist, this call has no effect.

 m_fastdraw( x,y,count,data)
      The next count bytes of data are sent to MGR are  to  be  interpreted  as
      lines  drawn  in _f_a_s_t _d_r_a_w mode, starting at ( x,y).  _F_a_s_t _d_r_a_w mode per-
      mits the rapid drawing of short vectors by encoding an  _x,_y  displacement
      location  in  a  single  byte.  The _x coordinate is contained in the most
      significant 4 bits, the _y coordinate in the  least  significant  4  bits.
      Values  for  _x  and _y represent displacements from the previous location,
      and range from +7 to -8.  A 7 is coded as _0_x_f_f, a -8 as _0_x_0_0.  If both  _x
      and _y are zero (i.e.  _0_x_8_0_8_0).  The next coordinate is taken to be a _m_o_v_e
      instead of a _d_r_a_w.  An eight bit channel between MGR and the client  pro-
      gram is required for _f_a_s_t _d_r_a_w mode.  See also m_rfastdraw().

 m_fcolor( color)
      The foreground color for text operations is set to color ,  which  is  an
      index into the color lookup table.  This command has no effect on a mono-
      chrome display.  See also m_bcolor() and m_fgbgcolor().




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 18 -                          Macros


 m_fgbgcolor( fg_color,bg_color)
      The foreground and background colors for graphics operations are  set  to
      fg_color  , and bg_color , which are indices into the color lookup table.
      This command has no effect on a monochrome display.  If  either  argument
      has  a  negative value, then the corresponding color (foreground or back-
      ground) remains unchanged.  See also m_bcolor() and m_fcolor().

 m_flush()
      Flush the MGR output buffer.  This is equivalent to  the  stdio  function
      _f_f_l_u_s_h() and is needed only when the M_FLUSH flag is _n_o_t specified in the
      call to m_setup().

 m_font( n)
      Change to font n.  The line positioning is adjusted to keep the  baseline
      of  the  new  and  old  fonts  the same.  Font numbers are small integers
      (currently no more than 15).  Font 0 (zero) always refers to the built-in
      or  _d_e_f_a_u_l_t  font.  The actual fonts associated with the font numbers may
      be set in the MGR _s_t_a_r_t_u_p file, or changed by clients  on  the  fly  (see
      m_loadfont()).

 m_fracdown( numer,denom)
      Move the character cursor down a distance of numer/denom times the height
      of  characters  in the current font, rounded to a whole number of pixels.
      The function m_down() is a special case of m_fracdown()  where  denom  is
      ten.

 m_fracleft( numer,denom)
      Move the character cursor left a distance of numer/denom times the  width
      of  characters  in the current font, rounded to a whole number of pixels.
      The function m_left() is a special case of m_fracleft()  where  denom  is
      ten.

 m_fracright( numer,denom)
      Move the character cursor right a distance of numer/denom times the width
      of  characters  in the current font, rounded to a whole number of pixels.
      The function m_right() is a special case of m_fracright() where denom  is
      ten.

 m_fracup( numer,denom)
      Move the character cursor up a distance of numer/denom times  the  height
      of  characters  in the current font, rounded to a whole number of pixels.
      The function m_up() is a special case of m_fracup() where denom is ten.

 m_func( mode)
      Set the drawing mode.  This specifies the drawing mode in force  for  all
      _g_r_a_p_h_i_c_s  and _b_i_t-_b_l_t operations.  The integer mode is one of 16 possible
      boolean combinations of the _s_o_u_r_c_e and _d_e_s_t_i_n_a_t_i_o_n bit patterns.   Combi-
      nations  of  bit  patterns  for  which there is no _s_o_u_r_c_e bitmap, such as
      m_bitwrite() or m_line() use the modes shown in the middle column of  the
      following table.  Several common modes are specified for the bit patterns
      in which the source bitmap is relevant.






                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 19 -                          Macros



8                          _________________________________
                               Names for bit-blt modes
8                          _________________________________
                            source    no source   comments
8                          __________________________________________________________________
                           BIT_SRC    BIT_INV
                           BIT_OR     BIT_SET     default
                           BIT_NOR    BIT_DST
                           BIT_XOR    BIT_CLR
                           BIT_AND
                           BIT_NAND
8                          _________________________________
7                         |8|7|7|7|7|7|7|7|7|







9                                   |7|7|7|7|7|7|7|






                                               |7|7|7|7|7|7|7|






                                                          |8|7|7|7|7|7|7|7|7|









9      Alternately, mode may be derived with a boolean  combination  of  BIT_SRC
      and   BIT_DST,   thus   BIT_OR   is   equivalent   to  BUILDOP(BIT_SRC  |
      BIT_DST,BLACK,WHITE).  The default graphics mode in newly created windows
      is BIT_OR .

 m_getchar()
      The macro m_getchar() is  equivalent  to  the  _s_t_d_i_o  routine  _g_e_t_c_h_a_r(),
      except  the character is retrieved from MGR via the file pointer _m__t_e_r_m_i_n
      instead of _s_t_d_i_n.

 m_getinfo( mode)
      This function requests MGR to return information back to the client  pro-
      gram.    Mode   specifies  one  of  (currently)  15  different  requests.
      Responses  are  always  terminated  with  a  _n_e_w  _l_i_n_e  for  single  line
      responses, and with a pair of _n_e_w _l_i_n_e_s for multi-line responses.  Conse-
      quently, clients can request and process information requests using  nor-
      mal  line  mode  processing.   If  the mode requested is unsupported, the
      response is empty except for the terminating newline.  The following list
      of information requests is understood.

      G_ALLMINE
           Window status for own windows only.
           Information about each window that may be written to by  the  client
           program  is  returned, one line of information per window, as a list
           of space separated items.  The format of the information is the same
           as  that obtained from the G_ALL request below, but only a subset of
           the windows is described.

      G_ALL
           Status of all windows.
           Information about all windows is returned, one line  of  information
           per window, as a list of space separated items.  The first two items
           give the location of the top left corner of the  window  in  _d_i_s_p_l_a_y
           coordinates.   The second two items give the _h_e_i_g_h_t and _w_i_d_t_h of the
           window, also in _d_i_s_p_l_a_y coordinates.  The next  field  contains  the
           last  two  characters  of the _p_s_e_u_d_otty associated with each window.
           Normally the _p_s_e_u_d_otty is the same for each window controlled by the
           same  client.   The  next  field  contains the _w_i_n_d_o_w _i_d, which is 0
           (zero) for a primary window, and the value returned by the  call  to
           m_makewindow()  for  alternate  windows.  The seventh field contains
           the visual status of the window, which is either _C__E_X_P_O_S_E_D ('e')  if
           the  window is completely visible, or _C__O_B_S_C_U_R_E_D ('o') if the window



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 20 -                          Macros


           is partly or completely obscured.  The final  field  is  the  window
           setid.   Windows  can  be uniquely identified by a pair of window id
           and window setids.   The  window  information  for  each  window  is
           printed  in  order from _f_r_o_n_t to _b_a_c_k.  Thus the first line returned
           is currently the _a_c_t_i_v_e window.  A sample line might look  something
           like:

8                                 ________________________
                                  492 2 652 570 p6 0 o 9
8                                 ________________________
7                                |8|
8                                                        |8|

9           Which indicates that the window at ( 492,2)is 652  pixels  _w_i_d_e  and
           570  pixels  _h_i_g_h,  has  a controlling _p_s_e_u_d_otty of /_d_e_v/_t_t_yp6, is a
           main window with a setid number of 9,  and  is  at  least  partially
           obscured.

      G_NOTIFY
           List windows with notify strings.
           Information about each window which  has  a  NOTIFY  string  set  is
           returned as four fields terminated by a newline.  Each window report
           is formed by concatenating the window  process  id,  a  period,  the
           alternate window number, a space, the length of the NOTIFY string, a
           space, and the NOTIFY string itself.  Line processing can be compli-
           cated by NOTIFY strings which contain newlines.

      G_COORDS
           Window coordinates.
           A single line is returned containing the location and  size  of  the
           window  in  _d_i_s_p_l_a_y  coordinates.   The first pair of numbers is the
           position of the top left corner of the window, the  second  pair  of
           numbers is the window's _w_i_d_t_h and _h_e_i_g_h_t in pixels.

      G_CURSOR
           A single line is returned containing the position of  the  _c_h_a_r_a_c_t_e_r
           and  the _g_r_a_p_h_i_c_s cursors and the type of the character cursor.  The
           first pair of numbers is the current _c_o_l_u_m_n  and  _r_o_w  in  character
           coordinates   and   the  second  pair  of  numbers  is  the  current
           _g_r_a_p_h_i_c_slocation in window coordinates.  The graphics  cursor  loca-
           tion  is reported in either _a_b_s_o_l_u_t_e or _r_e_l_a_t_i_v_e window coordinates,
           depending upon the window coordinate mode setting.  The fifth number
           encodes the cursor type.

      G_FONT
           A single line is returned which contains current  font  information.
           The first pair of numbers is the character _w_i_d_t_h and _h_e_i_g_h_t, in pix-
           els.  The next number is the _f_o_n_t _n_u_m_b_e_r as would be used in a  call
           to  m_font,  and  the  final field is the ascii name of the font, or
           _d_e_f_a_u_l_t if there is no name.

      G_ID
           Alternate window number.
           A single line is returned containing the window's  alternate  window
           id  ( 0 for the main window), followed by the number of windows con-
           trolled by the client program.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 21 -                          Macros


      G_MOUSE
           Mouse coordinates.
           The mouse position, in _d_i_s_p_l_a_y coordinates are returned, followed by
           the  most  recent button transition, which is one of 1,-1,2,-2.  The
           numbers 1 and 2 represent buttons _o_n_e and _t_w_o on the mouse,  respec-
           tively,  counting  from  right  to  left.  The third mouse button is
           reserved for system use and is not accessible to client programs.  A
           negative value means the button was released; a positive value indi-
           cates the button is still depressed.

      G_MOUSE2
           Scaled mouse coordinates.
           The mouse coordinates, in _w_i_n_d_o_w coordinates are returned,  followed
           by  the  most  recent  button transition, which is one of 1,-1,2,-2.
           The numbers 1 and 2 represent buttons _o_n_e and _t_w_o  respectively.   A
           negative  value means the button was last released; a positive value
           indicates the button is still depressed.  If the mouse is  above  or
           to  the left of the window, a negative coordinate value is returned.
           In addition if the window is in _r_e_l_a_t_i_v_e coordinate mode, coordinate
           values  between  0  and  999  will  be reported only if the mouse is
           within the window.

      G_STATUS
           A line is returned containing a single character,  either  _C__E_X_P_O_S_E_D
           ('e'),  _C__O_B_S_C_U_R_E_D  ('o'),  or _C__A_C_T_I_V_E ('a') depending upon whether
           the window is exposed  but  not  the  _a_c_t_i_v_e  window,  partially  or
           totally obscured, or exposed and the _a_c_t_i_v_e window.

      G_SYSTEM
           A single line  containing  constant  global  system  information  is
           returned.  There are currently five fields:

           1) The _h_o_s_t_n_a_m_e of the machine MGR is running  on,  as  returned  by
              _g_e_t_h_o_s_t_n_a_m_e().

           2) The width of the display in pixels.

           3) The height of the display in pixels.

           4) The size of the window borders in pixels.

           5) The depth of the display in bits.  Currently, the depth  must  be
              one or eight.

      G_TERMCAP
           A single line is returned which contains a _T_E_R_M_C_A_P  entry  for  MGR.
           The  _T_E_R_M_C_A_P  entry is always the same, except for _l_i_n_e_s and _c_o_l_u_m_n_s
           entries (li# and co#), which vary  to  reflect  the  current  window
           size, and the am entry reflecting the state of the M_NOWRAP flag.

      G_TEXT
           A single line containing four integers is returned with the  current
           text  region size.  The first pair of numbers is the top left corner
           of the text region,  in  _w_i_n_d_o_w  coordinates,  the  second  pair  of



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 22 -                          Macros


           numbers  is  the  _w_i_d_t_h  and  _h_e_i_g_h_t of the text region.  If no text
           region is defined, implying the entire window is  the  text  region,
           all four numbers are returned as 0 (zero).

      G_WINSIZE
           A single line is returned containing the current number  of  _c_o_l_u_m_n_s
           and  _r_o_w_s  in  the  _t_e_x_t  _r_e_g_i_o_n.  If no text region is defined, the
           number of _c_o_l_u_m_n_s and _r_o_w_s for the entire window is returned.

      G_FLAGS
           A single line is returned containing a hexadecimal number represent-
           ing  the  current  window  mode bits.  For color MGR four additional
           fields are returned which indicate the current text  foreground  and
           background  color, and the graphics foreground and background color.
           For the first, or mode field, each mode is represented by a  bit  in
           the  word.  Many of the modes may be _s_e_t or _c_l_e_a_r_e_d with m_setmode()
           or m_clearmode().  See the discussion of m_setmode() for a  detailed
           discussion of these flags.  The meaningful mode bits are:

           0x000001  The window is completely exposed.

           0x000004  It is possible to use the system _c_u_t function in this win-
                     dow.   This  mode is restored by clearing the window.  See
                     m_clear().

           0x000008  The window is _w_h_i_t_e text on a _b_l_a_c_k background.

           0x000010  The window is in standout mode.  Individual characters are
                     printed in reverse.

           0x000020  The window has died.  If a client sees this flag, the win-
                     dow is about to go away.

           0x000040  Expose the window upon shell output.  The window  will  be
                     automatically  activated  when  the next character arrives
                     for output on the window.

           0x000080  Permit a partially or totally obscured window to update.

           0x000100  Do not kill the window when the original  process  started
                     in  it  dies.   This flag may only be set from the startup
                     file.

           0x000200  _V_i mode is turned on.   Pushing  the  right  mouse  button
                     sends the characters:

8                                          ________________
                                           row H column |
8                                          ________________
7                                         |8|
8                                                         |8|

9                     where row and column specifies the character location  the
                     mouse is sitting on.  This has the effect of aligning _v_i's
                     notion of the current character position with  the  mouse,
                     if  no  wrapped  lines  appear  above this position on the
                     screen.



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 23 -                          Macros


           0x000800  Keyboard input is refused when the window is active.

           0x001000  Auto wrap mode is turned off with the bit equal to one, on
                     when  zero.   When  on, the character cursor automatically
                     wraps to the beginning of the next row when it reaches the
                     right margin of the text region.

           0x002000  Overstrike mode is turned on.  Characters are  written  to
                     the  window  using the the current drawing mode, as set by
                     m_func().

           0x004000  The window is in _a_b_s_o_l_u_t_e window coordinate mode.

           0x010000  The system _c_u_t function snarfs complete lines only.

           0x020000  The system _c_u_t function changes spaces  to  tabs  whenever
                     possible.  Tabs are assumed to be every 8 spaces.

           0x040000  The system _c_u_t function will attempt to snarf text even if
                     errors occur.

 m_gets( buff)
      A line of characters is read from MGR and placed into the  array  buff  .
      The macro m_gets() returns _N_U_L_L if the connection to MGR is severed.  The
      macro m_gets() is equivalent to the stdio _f_g_e_t_s() call  except  input  is
      retrieved from MGR .  The buffersize is obtained from _s_i_z_e_o_f(_b_u_f_f) , con-
      sequently, buff must be the name of an array.

 m_go( x,y)
      Move the _g_r_a_p_h_i_c_s _p_o_i_n_t to the window position ( x,y) in the current win-
      dow coordinates.

 m_gotext()
      The graphics point is moved to the bottom  left  corner  of  the  current
      character cursor location.

 m_halfwin( X,Y,Dwidth,Dheight)
      A window is created at X,Y of size Dwidth by Dheight with no process con-
      nected  to it.  MGR returns the name of the file, a _p_s_e_u_d_o-_t_t_y, that must
      be opened in order to talk to the new window.  A process which opens that
      _p_s_e_u_d_o-_t_t_y  becomes  a client program, communicating with MGR and the new
      window in the usual fashion.  For a single process managing multiple win-
      dows,  use  m_newwin().   The  advantage  of this way is that MGR can not
      detect the death of the process and automatically destroy the window.

 m_halfwinft( X,Y,Dwidth,Dheight,font)
      A window is created just as with m_halfwin(),  except  that  font  number
      font is the initial font used in the new window.

 m_highlight( X,Y,Dwidth,Dheight)
      MGR flashes the rectangular portion of the display  starting  at  X,Y  of
      size  Dwidth  by  Dheight.  This is an experimental capability and may be
      removed in the future.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 24 -                          Macros


 m_incr( n)
      The current character position is adjusted to the left or right  n  units
      in _w_i_n_d_o_w coordinates.  The argument n may be signed to indicate movement
      to the left (if negative) or to the  right  (if  positive  or  unsigned).
      This  is  useful  for  client programs dealing with proportionally spaced
      text.

 m_left( n)
      Move the character cursor left n tenths of a character width.   See  also
      m_down(), m_right(), and m_up().

 m_line( x1,y1,x2,y2)
      Draw a line in the current window from the coordinate  (  x1,y1)  to  the
      coordinate  (  x2,y2).   The  line  is either set, cleared or inverted as
      determined by the last call to m_func().

 m_linecolor( mode,color)
      The drawing mode and color is set for all  graphics  and  bit-blt  opera-
      tions.   The  integer  mode  sets  the  drawing  mode,  in  the manner of
      m_func().  The integer color is the index into the color lookup table for
      the  drawing  color.   This  command is equivalent to m_func() on a mono-
      chrome display.  See also m_bcolor() and m_fcolor()for the colors used in
      text  operations.  The m_linecolor() call is deprecated in favor of using
      m_func() and m_fgbgcolor().

 m_lineto( to,x1,y1,x2,y2)
      Draw a line on the scratchpad bitmap to from the coordinate (  x1,y1)  to
      the  coordinate ( x2,y2).  The line is either set, cleared or inverted as
      determined by the last call to m_func().

 m_linkmenu( parent,item,child,mode)
      The menus parent and child are linked  together.   When  menu  parent  is
      popped up and item number item (starting from zero) is highlighted, slid-
      ing off to the right of the parent menu causes the child menu to pop  up.
      When an item is chosen, MGR sends the concatenation of the action strings
      associated with each of the popped-up menus, from  left  to  right  (i.e.
      parent  to  child).  An arbitrary tree of menus may be created by linking
      successive menus together in this manner.  It is up to the application to
      indicate  on the parent menu item that sliding to the right will pop up a
      child menu.  Typically "->" is used.

      The mode argument, if not zero, changes the menu options for  the  parent
      menu.   The  flag  settings,  which  may  be  _o_r-ed  together (except for
      MF_CLEAR ) are:

      MF_SNIP
           By default, when an item in a _c_h_i_l_d menu  is  selected,  the  values
           associated  with the highlighted items for all of the ancestor menus
           are concatenated  to  the  _c_h_i_l_d's  item  value.   When  MF_SNIP  is
           enabled, only the string associated with the child menu is returned.

      MF_PAGE
           Normally, whenever a menu is popped-up, the previously  chosen  item
           is  initially  highlighted.  If MF_PAGE is enabled, this behavior is



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 25 -                          Macros


           extended to paged menus.  MGR automatically pages through a  set  of
           paged menus to highlight the currently selected item.

      MF_AUTO
           MGR will automatically slide to the right and pop up a child menu to
           highlight the previously selected item.

      MF_CLEAR
           Clears the mode MF_SNIP, MF_PAGE, and MF_AUTO.
      See also m_loadmenu(), m_selectmenu(), and m_unlinkmenu().

 m_loadfont( n,name)
      The MGR font whose pathname is name is downloaded into MGR, replacing the
      font   currently   located  at  position  n.   Any  subsequent  calls  to
      m_font()will select the newly downloaded font.  The font that used to  be
      at position n remains available to windows that are already using it, but
      is unavailable for future use.  The format of MGR font files is described
      in _i_n_c_l_u_d_e/_m_g_r/_f_o_n_t._h.

 m_menubar( x,y,menu,item)

 m_menuerase( menu)

 m_menuitem( menu,item)

 m_menushow( x,y,menu)

 m_loadmenu( n,string)
      The text string is downloaded into menu position n.  The first  character
      of  string is the _m_e_n_u _d_e_l_i_m_i_t_e_r character.  All of the menu item strings
      are concatenated, followed by all of their action strings.  The _m_e_n_u _d_e_l_-
      _i_m_i_t_e_r  character  separates  all of the items and actions and terminates
      the list.  Menus are downloaded at once, as a single entity.   The  macro
      m_selectmenu()  is  used  to  have the menu pop-up when a mouse button is
      pushed.

 m_move( column,row)
      The character cursor is moved to character location column,row , where  (
      0,0)  is the top left character position on the window, or on the current
      text region if one is specified (see m_textregion()).

 m_movecursor( x,y)
      Move the character cursor to the position ( x,y) in  window  coordinates.
      This  permits  characters  to be placed at arbitrary pixel locations, not
      just on character boundaries.  Use m_move()to move to a  row  and  column
      position.

 m_movemouse( X,Y)
      Move the mouse to position ( X,Y) in _d_i_s_p_l_a_y coordinates.  Excessive  use
      of this macro is anti-social.

 m_moveprint( x,y,string)
      Print string at the window coordinate ( x,y).  This macro  is  equivalent
      to calling m_movecursor() followed by m_printstr().



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 26 -                          Macros


 m_movewindow( X,Y)
      Move the window to the display location ( X,Y)  in  _d_i_s_p_l_a_y  coordinates.
      If  the new position is too close to the edge of the display for the win-
      dow to fit entirely at the requested location, the right edge  or  bottom
      of the window is truncated at the boundary of the display.

 m_newwin( X,Y,Dwide,Dhigh)
      An alternate window is created with the size and location indicated.  The
      arguments  X and Y specify the upper left corner of the window, Dwide and
      Dhigh the size.  If the window is to be to fit at the requested location,
      its  size is truncated appropriately.  MGR will return a window number if
      the creation is successful, or a _n_e_w_l_i_n_e  if  the  window  could  not  be
      created.   The newly created window is made the _a_c_t_i_v_e window.  The macro
      m_selectwin() is used to enable writing on the newly created window.

 m_nomenu()
      Deselect all menus.  No menu will pop-up when the middle mouse button  is
      pressed.   This call does not delete the menu, it simply disassociates it
      from the button.

 m_nomenu2()
      Deselect all menus.  No menu will pop-up when the right mouse  button  is
      pressed.   This call does not delete the menu, it simply disassociates it
      from the button.  This macro should be combined with  m_nomenu()  but  is
      separate for historical reasons.

 m_othersave( id,sub,name)
      The bitmap contents of the window identified as id.sub is  saved  in  the
      file name in bitmap format (see _b_i_t_m_a_p(5) for a description of the bitmap
      format).  The _w_i_n_d_o_w _i_d can be determined either  by  calling  m_getinfo(
      G_ALL)   or  from  the  event  _M__A_C_C_E_P_T  (see  m_setevent()).   See  also
      m_windowsave() and m_bitsave().

 m_pagemenu( parent,child)
      Connect menu child to the bottom of menu parent to permit a long menu  to
      be  paged.  Mousing off the bottom of the parent menu automatically pops-
      up the _c_h_i_l_d menu, which in turn may be the parent of another menu.   See
      also m_unpagemenu(), m_linkmenu() and m_unlinkmenu().

 m_pop()
      Pop the window  context.   The  last  window  context  saved  by  calling
      m_push()  or  m_pushsave()  is  restored.   If  no environments have been
      pushed, m_pop()has no effect.

 m_popall()
      Like m_pop() above, except all environments pushed since the  first  call
      to  m_setup() are popped.  The macro m_popall() is typically used as part
      of the clean up before client program termination.

 m_printstr( string)
      Print string on the window at  the  current  character  cursor  location.
      This  is  equivalent to the _s_t_d_i_o function _p_r_i_n_t_f with a %_s format speci-
      fied and the output directed toward the file pointer _m__t_e_r_m_o_u_t instead of
      _s_t_d_o_u_t.



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 27 -                          Macros


 m_push( mode)
      Certain parts (stack modes) of the  current  window  environment  may  be
      moved  to  a  stack,  to  be  restored  at  a  later time with m_pop() or
      m_popall().  Any combination  of  the  following  pieces  of  the  window
      environment, called a window context, may be placed on the window stack.

      P_BITMAP
           All currently defined _s_c_r_a_t_c_h_p_a_d bitmaps are moved to the stack  and
           become undefined in the current window context.

      P_BITOP
           The default bitblit functions used for graphics and text  operations
           are  both  moved  to  the  stack  and replaced by _B_I_T__O_R and _B_I_T__S_R_C
           respectively.

      P_COLOR
           The foreground and background colors  used  for  graphics  and  text
           operations  are  all  moved to the stack and replaced by the default
           black-on-white and black-on-white.

      P_CURSOR
           The current _c_h_a_r_a_c_t_e_r cursor and _g_r_a_p_h_i_c_s _p_o_i_n_t positions are  saved
           on the stack.

      P_EVENT
           All currently defined events are moved to the stack and become unde-
           fined in the current window context.

      P_FLAGS
           The window modes, as set with m_setmode() are moved  to  the  stack.
           The  modes  revert  to  their default settings in the current window
           context.

      P_FONT
           The current font setting is copied to the stack.  If  this  font  is
           subsequently  deleted, by writing over it with a different font, the
           original font setting is retained, even  if  it  can  no  longer  be
           accessed using m_font().

      P_MENU
           All downloaded menus and menu links are moved to the the stack along
           with the currently selected menu number.  The menus become undefined
           in the current context.

      P_MOUSE
           The mouse cursor location is saved on the stack.  Its current  loca-
           tion remains the same.

      P_POSITION
           The window size and location is saved on  the  stack.   The  current
           size and location are maintained.

      P_TEXT
           The text region location and size are saved on the stack.  The  text



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 28 -                          Macros


           region in the current context is reset to the entire window.

      P_WINDOW
           The current image contents of the window is  copied  to  the  stack.
           This is done without altering the current contents of the window.
      Stack modes are combined by _o_r-ing them together to form a  saved  window
      context,  such  as:          m_push(  P_MENU|P_EVENT) which will save all
      events, and menus but leave everything else alone.  All stack modes  that
      require  client  download data revert to their default settings when they
      are  _p_u_s_h_e_d.   For  example,  after  m_push(  P_MENU|P_EVENT|P_MOUSE)  is
      called,  no  events or menus are currently defined, but the mouse remains
      where it is.  The defined constant _P__A_L_L refers to all of the modes.

 m_pushsave( mode)
      Certain parts (stack modes) of the  current  window  environment  may  be
      copied  to  a  stack,  to  be  restored  at  a later time with m_pop() or
      m_popall().  The macro m_pushsave() differs from m_push() in  that  down-
      loaded data, such as _m_e_n_u_s _e_v_e_n_t_s or _s_c_r_a_t_c_h_p_a_d bitmaps are copied to the
      stack instead of moved, and thus remain  in  effect  after  the  call  to
      m_pushsave().  The current window context is thus unaffected.  Any combi-
      nation of the following pieces of the window environment may be copied to
      the window stack.

      P_BITMAP
           All currently defined _s_c_r_a_t_c_h_p_a_d bitmaps are copied to the stack.

      P_BITOP
           The bitblit operations currently used for graphics  and  text  func-
           tions are both copied to the stack.

      P_COLOR
           The current foreground and background colors used for  graphics  and
           text functions are all copied to the stack.

      P_CURSOR
           The current _c_h_a_r_a_c_t_e_r and _g_r_a_p_h_i_c_s cursor positions are saved on the
           stack.

      P_EVENT
           All currently defined events are copied to the stack.

      P_FLAGS
           The window modes, as set with m_setmode(), are copied to the stack.

      P_FONT
           The current font setting is copied to the stack.  If  this  font  is
           subsequently  deleted, by writing over it with a different font, the
           original font setting is retained, even  if  it  can  no  longer  be
           accessed using m_font().

      P_MENU
           All downloaded menus and menu links are  copied  to  the  the  stack
           along with the currently selected menu number.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 29 -                          Macros


      P_MOUSE
           The mouse cursor location is saved on the stack.

      P_POSITION
           The window size and location are saved on the stack.

      P_TEXT
           The text region location and size are saved on the stack.

      P_WINDOW
           The current image contents of the window is copied to the stack.
      Stack modes are combined by _o_r-ing them together to form a  saved  window
      context,  such  as:          m_push(  P_MENU|P_EVENT) which will save all
      events, and menus but leave everything else alone.

 m_put( string)
      String is put into the global _s_n_a_r_f buffer.  There is one  common  buffer
      for  all  clients  programs.   The macro m_snarf()is used to retrieve the
      contents of the buffer.  The MGR system _c_u_t function places text in  this
      buffer, whereas the system _p_a_s_t_e function pastes text from this buffer.

 m_putchar( c)
      The character c is written in the window at the current character  cursor
      location.   This  function  is  like  the _s_t_d_i_o _p_u_t_c_h_a_r(_c), only directed
      toward the client's window.

 m_rcircle( radius)
      A circle of radius radius is drawn,  centered  at  the  current  _g_r_a_p_h_i_c_s
      _p_o_i_n_t.  The points at the edge of the circle are set, cleared or inverted
      depending upon the last call to m_func().  Circles are  always  drawn  as
      circles, both in _a_b_s_o_l_u_t_e and in _r_e_l_a_t_i_v_e window coordinates.  The radius
      is scaled based upon the average width and height of the window.

 m_rellipse( radius1,radius2)
      Draw an ellipse centered at the _g_r_a_p_h_i_c_s _p_o_i_n_t with foci on  the  coordi-
      nate axes.  The two radii, radius1 and radius2 specify the horizontal and
      vertical (major or minor) axis  lengths.   The  ellipse  is  either  set,
      cleared, or inverted, as determined by the last call to m_func().  If the
      window is in _r_e_l_a_t_i_v_e coordinate mode, radius1  and  radius2  are  scaled
      based upon the average width and height of the window.

 m_resetesc()
      The MGR _e_s_c_a_p_e character is reset to its to default value ('\033').  This
      turns off the debugging mode turned on by m_setesc().

 m_rfastdraw( count,data)
      The next count bytes of data are sent to MGR are  to  be  interpreted  as
      lines  drawn  in  _f_a_s_t _d_r_a_w mode, starting at the current graphics point.
      _F_a_s_t _d_r_a_w mode permits the rapid drawing of short vectors by encoding  an
      _x,_y  displacement in a single byte.  The _x coordinate is contained in the
      most significant 4 bits, the _y coordinate  in  the  least  significant  4
      bits.  Values for _x and _y represent displacements from the previous loca-
      tion, and range from +7 to -8.  A 7 is coded as _0_x_f_f, a -8 as  _0_x_0_0.   If
      both _x and _y are zero (i.e.  _0_x_8_0_8_0).  The next coordinate is taken to be



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 30 -                          Macros


      a _m_o_v_e instead of a _d_r_a_w.  An eight  bit  channel  between  MGR  and  the
      client program is required for _f_a_s_t _d_r_a_w mode.  See also m_fastdraw().

 m_right( n)
      Move the character cursor right n tenths of a character width.  See  also
      m_left(), m_down(), and m_up().

 m_scrollregion( first_row,last_row)
      This sets up a _t_e_x_t _r_e_g_i_o_n as a _V_T_1_0_0-_l_i_k_e scrolling region.  The  entire
      width  of  the  window from lines first_row to last_row inclusive becomes
      the _t_e_x_t _r_e_g_i_o_n.  MGR does not change the kernel's notion of  the  window
      size in response to this call, because the scrolling region is thought of
      as only a part of the window, that part which should  scroll.   See  also
      m_textregion() and m_textreset().

 m_selectmenu( n)
      This macro is used to indicate menu n pops-up in response to pressing the
      _m_i_d_d_l_e  mouse  button.   Menus  are downloaded (with m_loadmenu()) first,
      then selected.  Only one menu may be selected at a time on  each  button.
      If  the  button  is already down when this call is made, and there is not
      currently a menu associated with the button, then the menu just  selected
      pops-up  immediately.   This last feature may be used to pop up different
      menus in a context sensitive way.

 m_selectmenu2( n)
      This macro is used to indicate menu n pops-up in response to pressing the
      _r_i_g_h_t mouse button.  Menus are downloaded (with m_loadmenu()) first, then
      selected.  This macro functions the same as, and should be combined  with
      m_selectmenu() above, but exists separately for historical reasons.

 m_selectwin( n)
      Select alternate window  n  for  output.   Alternate  windows  are  first
      created  by  m_newwin().   All  output  goes to the selected window until
      either m_selectwin()is called to change windows, or the  selected  window
      is  destroyed.  If n is 0 (zero) or the currently selected window is des-
      troyed, the main, or original window is selected.  Input from all windows
      is  send  to  the  client  program  on the same input channel.  The macro
      m_setevent( ACTIVATE) may be used to help decide  what  window  generated
      the  input  by  associating  a  unique string with each window's _A_C_T_I_V_A_T_E
      event.  The _s_e_l_e_c_t_e_d window and the _a_c_t_i_v_e window are specified  indepen-
      dently.   Selecting  a  window  does  not  make it the _a_c_t_i_v_e window, and
      creating a new window, although it is created as the  _a_c_t_i_v_e  window,  is
      not automatically selected.

 m_sendme( string)
      The argument string is sent back to the client process as if it was typed
      in  at the keyboard.  Strings may contain substitutable parameters in the
      manner of _p_r_i_n_t_f format specifiers (i.e. %X).  The %X, where X is one  of
      p,  P,  M, n, or w is replaced by the value of the parameters, as defined
      above under the button-up section of m_setevent(). It  is  intended  that
      this  mechanism  of  obtaining  state  information from MGR eventually be
      extended to include any information that might be relevant to an applica-
      tion program, thus rendering m_getinfo()obsolete.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 31 -                          Macros


 m_sendto( n,string)
      The message string is sent to window n.  A unique window identifier, n is
      determined  with  either  m_setevent()  using  the  %_w  option,  or  with
      m_getinfo().  In general, the window id n is the process id (_p_i_d) of  the
      client program started by MGR when the window was created.  If the target
      window has turned on _A_C_C_E_P_T with m_setevent(), string is received by  the
      client  program  associated  with the target window as part of the _A_C_C_E_P_T
      event.  General write permissions must be disabled on the target client's
      _p_s_e_u_d_otty  in order for the message to be received, to prevent unsuspect-
      ing _s_h_e_l_ls from interpreting messages sent by unscrupulous  processes  as
      commands.  See also m_broadcast().

 m_setcursor( i)
      The character cursor may be set to one of  CS_BLOCK,  CS_LEFT,  CS_RIGHT,
      CS_BOX,  CS_UNDER,  or CS_INVIS which sets the cursor representation to a
      solid block (the default), a vertical bar at the left edge of the charac-
      ter  cell, a vertical bar at the right edge, an outline box, or an under-
      score respectively.  CS_INVIS, or any other invalid code causes the char-
      acter cursor to be invisible.  This macro currently only effects the cur-
      sor representation for the active window.

 m_setecho()
      Turn on character echoing, if possible.  Character  echoing  is  normally
      disabled  by  clients  to  inhibit information from MGR, as from calls to
      m_getinfo(), from echoing on the window.

 m_setesc( c)
      This macro call causes the character c to be used as the MGR escape char-
      acter  by  the library package (instead of '_\_0_3_3').  This permits viewing
      the output stream to MGR without causing the commands to be executed.

 m_setevent( n,string)
      An event string, string is sent to the client program  by  MGR  upon  the
      occurrence  of the specified event n.  The event string is typically read
      by the client program using m_gets().  Event strings are  never  sent  in
      response to an event unless specifically requested by the client program.
      Events are one of the following types.

      ACTIVATE
           The window became the _a_c_t_i_v_e window.  It is  at  the  front  of  the
           display, and is currently receiving both mouse and keyboard input.

      BUTTON_1
           The right mouse button was depressed.  This event is  sent  only  to
           the _a_c_t_i_v_e window.

      BUTTON_1U
           The right mouse button was released.  This event is sent only to the
           _a_c_t_i_v_e window.

      BUTTON_2
           The middle mouse button was depressed.  This event is sent  only  to
           the _a_c_t_i_v_e window.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 32 -                          Macros


      BUTTON_2U
           The middle mouse button was released.  This event is  sent  only  to
           the _a_c_t_i_v_e window.

      COVERED
           The window was partially or completely obscured by another window.

      DEACTIVATE
           The window was deactivated, it is no longer the _a_c_t_i_v_e window.

      REDRAW
           The display was redrawn, either by selecting the _r_e_d_r_a_w option  from
           the  system  menu, or by keying _L_E_F_T-_r from the keyboard.  Only win-
           dows that are exposed receive  the  _R_E_D_R_A_W  event.   The  images  of
           obscured windows are restored automatically by MGR.  The client pro-
           gram is expected  to  regenerate  the  contents  of  its  window  in
           response to the _R_E_D_R_A_W event.

      RESHAPE
           The window was reshaped.  If the user  selects  the  system  _r_e_s_h_a_p_e
           option, the _R_E_S_H_A_P_E event is sent, even if the window stays the same
           shape.

      UNCOVERED
           The window, previously obscured, was uncovered.  If the window  also
           became  the  _a_c_t_i_v_e  window,  the _U_N_C_O_V_E_R_E_D event is sent before the
           _A_C_T_I_V_A_T_E event.

      MOVE
           The window was moved.

      DESTROY
           The window was destroyed.  Only _a_l_t_e_r_n_a_t_e  windows  (as  created  by
           m_newwin())  cause _D_E_S_T_R_O_Y events to be sent.  If the _m_a_i_n window is
           destroyed, the client program is sent a _h_a_n_g_u_p signal, and its  con-
           nection to MGR is severed.

      ACCEPT
           Messages are accepted from client programs running in other  windows
           (see  m_sendto()).  The content of the message is obtained by speci-
           fying the %m parameter as part of the  event  string,  as  is  fully
           described below.

      NOTIFY
           Register a name with MGR, and make this  name  available  to  client
           programs.  This name is available to other clients, either by a call
           to m_getinfo( G_NOTIFY) or with the %n  parameter  described  below.
           Unlike the other events, the _n_o_t_i_f_y string is never sent back to the
           client program by MGR, but is used to register a name for  the  win-
           dow.

      SNARFED
           Text was put into the snarf buffer either by a client  program  with
           m_put() or by use of the system _c_u_t function.



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 33 -                          Macros


      PASTE
           Text is about to arrive as a result of the system _p_a_s_t_efunction.

      Some _e_v_e_n_t strings may contain substitutable parameters in the manner  of
      _p_r_i_n_t_f format specifiers (i.e. %X).  These parameters are applicable only
      to certain types of events.  In any case, the % character may  be  forced
      by  doubling  it,  as  in %%.  Where more than one data item replaces the
      format specifier, the items are separated by a _s_p_a_c_e character.  For  the
      event  strings  BUTTON_1  and  BUTTON_2,  several parameters cause MGR to
      sweep out some object in response to mouse movement, and report back  the
      size  of the swept object when the button is released.  Any one of lines,
      boxes, text, or rectangles may be swept out with this mechanism.  Initial
      parameters  may be associated with a sweep event by listing them as comma
      separated integers following the % and preceding the sweep command  char-
      acter.   The parameters (if any) set the initial size of the object to be
      swept, in the same  coordinate  system  in  which  the  sweep  extend  is
      reported.

      %r   Depressing the button  causes  MGR  to  sweep  out  a  rectangle  in
           response  to  moving  the  mouse,  in a manner similar to the system
           _r_e_s_h_a_p_e function.  The initial parameters set the initial width  and
           height  of  the rectangle.  When the button is released, the coordi-
           nates of the _s_t_a_r_t_i_n_g and _e_n_d_i_n_g points of the rectangle in response
           to  moving the mouse, in _w_i_n_d_o_w coordinates, are substituted for the
           %_r.

      %R   Depressing the button causes MGR to sweep out a rectangle, as in  %_r
           above, only the result is reported in _d_i_s_p_l_a_ycoordinates.

      %b   Depressing the button causes MGR to move a rectangle in response  to
           moving  the  mouse, in a manner similar to the system _m_o_v_e function.
           The initial parameters set the initial width and height of the  rec-
           tangle  to be moved.  When the button is released, the current coor-
           dinates of the box's corner is returned in _w_i_n_d_o_w coordinates,  sub-
           stituted for the %_b.

      %B   Depressing the button causes MGR to move a rectangle in response  to
           moving  the  mouse, in a manner similar to the system _m_o_v_e function.
           The initial parameters set the initial width and height of the  rec-
           tangle  to be moved.  When the button is released, the current coor-
           dinates of the box's corner is returned in _d_i_s_p_l_a_y coordinates, sub-
           stituted for the %_b.

      %l   Depressing the button causes MGR to sweep out a line.   One  end  of
           the  line remains fixed at the _g_r_a_p_h_i_c_s _p_o_i_n_t while the other end of
           the line tracks the mouse position.  The initial end  point  of  the
           line  may  be specified as a displacement from the graphics point as
           part of the initial parameters.  When the button  is  released,  the
           coordinates of the _s_t_a_r_t_i_n_g and _e_n_d_i_n_g points of the line, in _w_i_n_d_o_w
           coordinates, are substituted for the %_l.

      %t   Depressing the button causes MGR to sweep  out  text,  in  a  manner
           equivalent to the system _c_u_t function.  Upon the release of the but-
           ton, the %_t is replaced by the starting character coordinate of  the



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 34 -                          Macros


           _c_u_t  region,  followed  by character distance to the ending point in
           columns and lines  respectively.   For  example,  The  event  string
           _s_w_e_e_p[%t]  might  return  _s_w_e_e_p[17 5 6 0], indicating the user swept
           out a six character word on a single line, starting  on  column  17,
           row  5.   An  initial  size  may  be specified in number of rows and
           number of columns.
      The remaining format specifiers are replaced by the information described
      below.   No  sweep  action is performed.  The first five, %p, %P, %M, %n,
      and %w also apply to the button release events.

      %p   The %_p is replaced by the current mouse coordinates, in _w_i_n_d_o_w coor-
           dinates.

      %P   The %_P is replaced by the current mouse  coordinates,  in  _c_h_a_r_a_c_t_e_r
           coordinates.

      %M   The %_M is replaced by the time in hundredths of  seconds  that  have
           elapsed since MGR was started.

      %n   If the mouse cursor is over a window whose NOTIFY event is set,  the
           text of that message is substituted for the %_n.

      %w   If the mouse cursor is over a window whose NOTIFY event is set,  the
           window_id  of the clicked on window is substituted for the %_w.  This
           window_id may be used by m_sendto() to send the clicked-on window  a
           message.

      %S   If the mouse cursor is over a window whose NOTIFY event is set,  the
           length of that message is substituted for the %_S.

      The ACCEPT event is used to receive messages from other client  programs.
      The  following  substitutable parameters may be used as part of the event
      string.

      %f   The window_id of message sender, as used in m_sendto(), replaces the
           %_f.

      %m   The text of message sent by the other client program replaces the %_m

      %s   The length of the message, in  characters,  replaces  the  %_s.   For
           example, a call to

8                __________________________________________________________
                 m_setevent(ACCEPT,"Message from (%f), (%s) long is: %m")
8                __________________________________________________________
7               |8|
8                                                                         |8|

9           might cause MGR to return

8                          ______________________________________
                           Message from (3214), (2) long is: HI
8                          ______________________________________
7                         |8|
8                                                               |8|

9           after the client program whose _w_i_n_d_o_w _i_d is _3_2_1_4  uses  m_sendto()to
           send the message "_H_I".

      %p   As with the BUTTON events above, %_p is replaced by the current mouse



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 35 -                          Macros


           position in _w_i_n_d_o_w coordinates.

      %P   As with the BUTTON events above, %_P is replaced by the current mouse
           position in _c_h_a_r_a_c_t_e_r coordinates.
      For the SNARFED event string, the following substitution  parameters  are
      recognized.

      %f   The _w_i_n_d_o_w _i_d of the window filling the _s_n_a_r_f  buffer  replaces  the
           %_f.

      %c   The current length of the _s_n_a_r_f buffer, in characters, replaces  the
           %_c.

      %C   The contents of the _s_n_a_r_f buffer replaces the %_C.  At present,  only
           the first 250 characters of the _s_n_a_r_f buffer may be returned via the
           %_C parameter.  Use m_snarf()to read the entire buffer.

      The PASTE event string, recognizes the %_c specifier  as  described  under
      _S_N_A_R_F_E_D above.

 m_setmode( mode)
      Various window modes may be _s_e_t or _c_l_e_a_r_e_d (see  m_clearmode())  indepen-
      dently.  These modes are:

      M_ABS
           The window is set to _a_b_s_o_l_u_t_e coordinate mode.  The upper left  edge
           of  the  window,  just inside the border is at position ( 0,0).  All
           other locations are measured relative to that corner in pixels.

      M_ACTIVATE
           The window is made the _a_c_t_i_v_e window,  pops  to  the  front  of  the
           display, and obtains all keyboard and mouse input.

      M_AUTOEXPOSE
           The next character to be typed on the window causes it to  automati-
           cally become the _a_c_t_i_v_e window.

      M_BACKGROUND
           Output goes to the  window  even  if  it  is  partially  or  totally
           obscured.   The  data  in  exposed  portions  of  the window is seen
           immediately.  Data in covered portions of the window is saved by MGR
           and restored when the covered portions are exposed.

      M_CONSOLE
           This window is the destination of data written to "/dev/console"  if
           the  OS supports this kind of redirection.  When one window turns on
           this flag, the same flag is turned off in all other windows.

      M_NOBUCKEY
           Buckey characters, those with values from 128-255, typed on the key-
           board  do  not magically cause server functions to be executed.  All
           eight bits of keyboard input are passed on to the client.

      M_NOINPUT



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 36 -                          Macros


           Keyboard input is prohibited.  All input from the keyboard  is  held
           buffered  by  MGR  until either _M__N_O_I_N_P_U_T is cleared, or a different
           window is made the _a_c_t_i_v_e window.  In the latter case the input goes
           to  the  newly  activated window.  This flag is automatically turned
           off when the user activates the window.  This feature is for  client
           programs  that  want  one of their windows to come to the front just
           long enough to notify the user of some event, but  do  not  want  to
           accidentally intercept keyboard input while the user is merrily typ-
           ing to some other client.

      M_NOREPORT
           When a window changes size, the OS is not specially notified of  the
           change,  even  if that OS tries to keep track of the screen sizes of
           terminals attached to ttys.

      M_NOWRAP
           The character cursor does not automatically jump to the left edge of
           the  next  line  as  it  reaches  the right edge of its text region.
           After the right margin is passed, the cursor and any subsequent text
           disappear past the right edge of the window.

      M_OVERSTRIKE
           Text is written to the window with the mode  specified  by  m_func()
           instead  of  the  normal copy mode.  This mode is _B_I_T__O_R by default.
           In copy mode, the characters completely obliterate their destination
           instead of combining with it.

      M_SNARFHARD
           The system _c_u_t function attempts to cut text even if the window con-
           tents  have  been corrupted.  Unidentifyable characters are returned
           as _C__N_O_C_H_A_R ('?').

      M_SNARFLINES
           The system _c_u_t function only cuts entire lines.  If any  text  on  a
           line is swept out, the entire line of text is included.

      M_SNARFTABS
           The system _c_u_t function attempts to turn white space into a  minimal
           combination of spaces and tabs.  Tab are set at every 8 columns.

      M_STACK
           Any events pushed on the window stack when this flag is set will  be
           sent  in  addition  to  any currently active events. This setting is
           useful for filters which need to receive events,  yet  still  permit
           clients running under them to receive events as well.

      M_STANDOUT
           The window is put in standout mode.  All characters are written with
           their foreground and background colors reversed.

      M_WOB
           The sense of _w_h_i_t_e and _b_l_a_c_k is reversed for the entire window,  not
           just for characters as is _M__S_T_A_N_D_O_U_T.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 37 -                          Macros


 m_setnoecho()
      Character echoing to the window is disabled if possible.  Character echo-
      ing  is  normally disabled by clients to inhibit information from MGR, as
      from calls to m_getinfo() from echoing on the window.

 m_setnoraw()
      Normal terminal input processing is in  effect.   Input  is  buffered  by
      lines,  and  all normal line editing and keyboard interrupt generation is
      in effect.

 m_setraw()
      Every character is available as entered, no  input  processing  is  done.
      This  is typically called _r_a_w mode.  Raw mode is not always available, in
      which case the macro call has no effect.

 m_shapewindow( X,Y,Dwidth,Dheight)
      The window is reshaped to  position  (  X,Y)  and  with  size  Dwidth  by
      Dheight.   As  only  the  _a_c_t_i_v_e  window may be reshaped, m_shapewindow()
      activates the window if it is not already active.  The new  size  of  the
      window  is  not  guaranteed;  the _w_i_d_t_h or _h_e_i_g_h_t may be truncated to the
      right or bottom edges of the display.  The macro m_getinfo() can be  used
      to determine the actual window size.

 m_size( columns,rows)
      The size of the window is changed so that it fits exactly columns by rows
      of  characters  in  the current font.  The window may be truncated at the
      right or bottom edge of the display if it is too  large  to  fit  on  the
      display at its current position.

 m_sizeall( X,Y,columns,rows)
      The window is reshaped to position ( X,Y) on the display, and resized  to
      fit columns and rows of text.  As only the _a_c_t_i_v_e window may be reshaped,
      m_shapewindow() activates the window if it is not  already  active.   The
      new  size  of  the  window  is not guaranteed; the _w_i_d_t_h or _h_e_i_g_h_t may be
      truncated to the right  or  bottom  edges  of  the  display.   The  macro
      m_getinfo() can be used to determine the actual window size.

 m_sleep()
      This call causes MGR to suspend the processing of characters to the  win-
      dow.   After  a chunk of output for all other windows has been processed,
      output processing resumes.  This does not normally take very long, making
      m_sleep() almost a _n_o-_o_p.

 m_snarf()
      The application is sent the contents of the global snarf buffer, if  any,
      as  specified by the last call by a client programs call to m_put() or by
      use of the system _c_u_t function.

 m_standend()
      Inverse video mode as set by m_standout() is turned off.  This is exactly
      equivalent to m_clearmode( M_STANDOUT).

 m_standout()
      Inverse  video  mode  is  turned  on.   This  is  exactly  equivalent  to



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 38 -                          Macros


      m_setmode(  M_STANDOUT).   The  color  of  the characters and their back-
      grounds are interchanged.

 m_stringto( to,x_dst,y_dst,string)
      The text string is printed starting at the  location  (  x_dst,y_dst)  on
      _s_c_r_a_t_c_h_p_a_d  bitmap  to.  The text is clipped to fit in the bitmap, and no
      special command processing is done on string.  If to  is  0  (zero),  The
      text  is  printed  on the window, but _t_e_x_t _r_e_g_i_o_n boundaries are ignored.
      This is the only way to get text  into  a  window  outside  of  the  _t_e_x_t
      _r_e_g_i_o_n.

 m_textregion( x,y,wide,high)
      A subregion within the current window starting at ( x,y) and of size wide
      by  high  is  defined within which all text is restricted.  All functions
      and information that deals in _c_h_a_r_a_c_t_e_r coordinates views the text region
      as  if  it was the entire window.  As soon as the text region is defined,
      the character cursor is moved to row and column  (  0,0),  which  is  now
      located  at  the  point  ( x,y).  Graphics output is not affected by text
      regions.  MGR may (if the server is compiled with  -DREGION_HACK)  change
      the kernel's notion of the window size in response to this call, possibly
      generating a SIGWINCH signal.

 m_textreset()
      The _t_e_x_t _r_e_g_i_o_n (defined by a call to m_textregion()or  m_scrollregion())
      is reset to be the entire window.  This is the default setting.  MGR does
      not change the kernel's notion of the window size  in  response  to  this
      call, because this may be a scrolling region, only.  If you want the ker-
      nel to know of the change, set the textregion to be the entire window.

 m_unlinkmenu( parent,item)
      The menu link associating a child menu  with  the  menu  parent  at  item
      (counting  from  zero) is removed (see also m_linkmenu()).  This function
      does not change the menus, only their connections.

 m_unpagemenu( parent)
      The link associating the menu parent with a _c_h_i_l_d menu is  removed.   See
      also m_pagemenu().

 m_up( n)
      Move the character cursor up n tenths of a character  height.   This  may
      cause  the  window  to  scroll  down.   See also m_left(), m_right(), and
      m_down().

 m_whatsat( X,Y)
      MGR returns to the client program  a  line  indicating  what  is  at  the
      _d_i_s_p_l_a_ycoordinates  (  X,Y).  If that location is occupied by a window, a
      line containing the name of the controlling terminal of the client,  then
      that of the window at that location, then its alternate window number and
      process id, all written as a space separated list.  The names  of  termi-
      nals  are  abbreviated  to their final two characters.  If the location (
      X,Y)is not in a window, MGR returns a newline.

 m_windowsave( name)
      The current image contents of the window is saved in the file name on the



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 39 -                          Macros


      MGR-host  machine  in  MGR bitmap format.  File names beginning with "./"
      are evaluated relative to the current directory  when  MGR  was  started.
      See also m_othersave() and m_bitsave().






















































                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 40 -                       Functions


 _F_u_n_c_t_i_o_n_s

 The functions listed below have  packaged  common  sequences  of  _m_a_c_r_o  calls
 together  to  provide  a  slightly  higher  level of interface than the macros
 alone.  They are still low  level,  and  have  no  pretense  of  completeness.
 Except  where  noted, all of the functions return a value greater than zero on
 success, and a value less than zero upon failure.  The functions fail only  if
 they  read  an unexpected value from MGR, for example if an event notification
 arrives just before the response to the query.  Client programs  may  use  the
 function  m_lastline()  in  an  attempt  to  determine  what  input caused the
 failure.  If such race conditions become a problem, one can either change  the
 approach  to  one  which uses m_dupkey() or to one which integrates queries to
 the server with the event dispatching mechanism.  Those functions which expect
 data  from  MGR  automatically  flush  any  pending output before reading, and
 unless the _M__M_O_D_E_O_K flag is set, attempt to  turn  off  character  echoing  to
 prevent data returned by MGR from echoing back on the window.  The three func-
 tions get_param(), get_size(), and get_font()are deprecated in favor of alter-
 natives  listed  below  which  return  the same information in more manageably
 sized parameter lists.


 int
 get_all( list)
 struct window_data *list;
9      The current position size and status of all windows  on  the  display  is
      returned  in  list.  The number of in windows on the display is returned.
      List should be large enough to hold a status entry for each window.   The
      _w_i_n_d_o_w__d_a_t_a structure is defined in _i_n_c_l_u_d_e/_m_g_r/_m_g_r._h.

 int
 get_client( list)
 struct window_data *list;
9      The current position size and status of  the  client  programs  _m_a_i_n  and
      _a_l_t_e_r_n_a_t_e  windows  is  returned in list.  The number of windows owned by
      the client program is returned.  List should be large enough  to  hold  a
      status  entry  for  each window.  The _w_i_n_d_o_w__d_a_t_a structure is defined in
      _i_n_c_l_u_d_e/_m_g_r/_m_g_r._h.

 int
 get_colrow( columns,rows)
 int *columns, *rows;
9      The number of _c_o_l_u_m_n_s and _r_o_w_s in the current _t_e_x_t _r_e_g_i_o_n is returned  in
      columns  and  rows  respectively.   For  any  _N_U_L_L  argument, no value is
      returned.

 int
 get_cursor( column,row)
 int *column, *row;
9      The current _c_h_a_r_a_c_t_e_r cursor position is placed in column and  row.   For
      any _N_U_L_L argument, no value is returned.

 int



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 41 -                       Functions


 get_eachclientwin( windatap)
 struct window_data *windatap;
9      Get the window parameters for each window in the current window set,  one
      window  at  a time.  This function returns 1 if window_data structure has
      been filled, 0 otherwise.  It is important to call get_eachclientwin() in
      a  tight  loop that doesn't exit until it returns 0, so that all the data
      is picked up.  This function is preferred  to  get_client()  because  you
      don't need to know the maximum number of windows you are likely to see.

 int
 get_eachwin( windatap)
 struct window_data *windatap;
9      Get the window parameters for all the windows,  one  window  at  a  time.
      This  function returns 1 if window_data structure has been filled, 0 oth-
      erwise.  It is important to call  get_eachwin()  in  a  tight  loop  that
      doesn't exit until it returns 0, so that all the data is picked up.  This
      function is preferred to get_all() because you don't  need  to  know  the
      maximum number of windows you are likely to see.

 int
 get_font( wide,high)
 int  *wide, *high;
9      The character size of the current font, in pixels is placed in  wide  and
      high.  For any _N_U_L_L argument, no value is returned.  The function returns
      the current font number, as would be used in a call to m_font().

 int
 get_mouse( x,y)
 int *x, *y;
9      The current mouse position, in _w_i_n_d_o_w coordinates, is placed in x and  y.
      For  any  _N_U_L_L  argument, no value is returned.  The function returns the
      current mouse button state, which is in the range of -2 to +2  upon  suc-
      cess,  a  value less than -2 upon failure.  See m_getinfo( G_MOUSE) for a
      discussion of the return values.

 int
 get_param( host,xmax,ymax,border)
 char *host;
 int *xmax, *ymax, *border;
9      The _M_G_R-_h_o_s_t, display size (in pixels) and window border size (in pixels)
      is  placed  in  the  arguments  host,xmax,ymax, and border.  For any _N_U_L_L
      argument, no value is returned.  This function exists only  for  backward
      compatibility and should not be used any longer.

 int
 get_size( X,Y,Dwidth,Dheight)
 int *X, *Y, *Dwidth, *Dheight;
9      The position of the window on the  display,  in  _d_i_s_p_l_a_y  coordinates  is
      placed  into  X,Y,Dwidth and Dheight.  For any _N_U_L_L argument, no value is
      returned.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 42 -                       Functions


 char *
 get_termcap()
9      A string containing a  _T_E_R_M_C_A_P  entry,  suitable  for  placing  into  the
      _T_E_R_M_C_A_P  environment  variable  is  returned.  The function get_termcap()
      returns _N_U_L_L upon failure.

 void
 ckmgrterm( text)
 char *text;
9      This function checks the environment variable TERM.  If it is present and
      does  not  contain  the  substring "mgr", then a message beginning with (
      text) is written to _s_t_d_e_r_r and _e_x_i_t is called.

 BITMAP *
 bitmapread( file_pointer)
 FILE* file_pointer;
9      The file pointed to by file_pointer is read and  converted  into  an  MGR
      bitmap.  The return value of NULL indicates failure.  This is the identi-
      cal routine MGR uses to read bitmap  files,  so  use  it.   The  external
      integer bm_compressed is set if the bitmap was compressed.

 int
 bitmapwrite( file_pointer,bitmap,flag)
 FILE* file_pointer;
 BITMAP* bitmap;
9      This function is used by MGR to write the MGR bitmap pointed to  by  bit-
      map() into the file pointed to by file_pointer().

 int
 is_active()
9      The function is_active() returns _T_R_U_E if the window is the _a_c_t_i_v_e window.

 void
 menu_load( n,count,text)
 int n, count;
 struct menu_entry *text;
9      A menu is downloaded to MGR at position n.   The  integer  count  is  the
      number  of  menu  items  to  be down-loaded, and text is an array of menu
      item/value   pairs.    The   structure   _m_e_n_u__e_n_t_r_y   is    defined    in
      _i_n_c_l_u_d_e/_m_g_r/_m_g_r._h.

 int
 m_bitfile( to,name,widep,highp,depthp)
 int to;
 char *name;
 int *widep, *highp, *depthp;
9      Given a bitmap id, to and an icon name, have MGR load that icon into that
      scratchpad bitmap, returning the icon width, height and depth, in pixels,
      via the given integer pointers.  Return a positive number if  successful.
      If  the  icon  is not loaded, set the width, height and depth values to 0
      and return 0.  This function  is  identical  to  m_bitfromfile()plus  the


9                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 43 -                       Functions


      needed interception of the line returned from MGR.

 int
 m_getbordersize( void)
9      This function returns the width of the border of each window in pixels.

 int
 m_getdepth( void)
9      This function returns the depth of the screen bitmap in bits, usually one
      for monochrome, eight for color.

 int
 m_getfontid( void)
9      The function returns as an int the current font number, or -1 to indicate
      a protocol error.

 char*
 m_getfontname()
9      The function returns a pointer to a static array containing the  name  of
      the current font or NULL to indicate a protocol error.

 int
 m_getfontsize( width,height)
 int *width, *height;
9      The size of the current font is stored  in  *width  and  height.   Return
      value is -1 for a protocol error or 0 otherwise.

 int
 m_gethostname( name,len)
 char *name;
 int len;
9      The hostname of the host machine running the MGR server, with a terminat-
      ing  NUL,  is returned in name[0] through name[len-1], possibly truncated
      if len is too small.  Return value is -1 for a protocol error or 0 other-
      wise.

 int
 m_getscreensize( width,height,depth)
 int *width, *height, *depth;
9      The display size (in pixels) and depth (in bit) is placed  in  the  argu-
      ments  width, height, and depth.  Return value is -1 for a protocol error
      or 0 otherwise.

 int
 m_getwindowposition( x,y)
 int *x, *y;
9      The position of the upper left corder of the window border is  placed  in
      the arguments x and y.  Return value is -1 for a protocol error or 0 oth-
      erwise.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 44 -                       Functions


 int
 m_getwindowsize( width,height)
 int *width, *height;
9      The window size is placed in the  arguments  width  and  height.   Return
      value is -1 for a protocol error or 0 otherwise.

 char *
 m_lastline()
9      The last input from MGR to a library function is returned.  The  data  is
      kept in a static buffer which is overwritten at each request.

 int
 m_makewindow( X,Y,Dwidth,Dheight)
 int  X, Y, Dwidth, Dheight;
9      An alternate window is created as the _a_c_t_i_v_e window, at  display  coordi-
      nates  (  X,Y)and of size Dwidth by Dheight pixels.  If the window is too
      big to fit on the display, its  width  and  height  are  truncated.   The
      alternate  window's  _w_i_n_d_o_w-_i_d is returned if the window was created suc-
      cessfully.  The macro m_selectwin() is used to write on the newly created
      window.

 int
 m_setup( mode)
 int mode;
9      This function initializes the library.  It  must  be  called  before  any
      other  function  or macro.  The argument mode is one or more of the flags
      _M__F_L_U_S_H, _M__D_E_B_U_G, or _M__M_O_D_E_O_K _o_r-ed together.  If _M__F_L_U_S_H is present, all
      macros  and  function flush output to MGR after each macro call.  This is
      slightly less efficient than letting the client program  flush  the  data
      (see  m_flush()) but prevent inadvertent buffering problems.  The _M__D_E_B_U_G
      flag forces the macro package to read and write  from  _s_t_d_i_n  and  _s_t_d_o_u_t
      respectively.   Normally  /_d_e_v/_t_t_y  is  opened for reading and writing to
      permit standard input or output redirection  while  still  maintaining  a
      connection  to  MGR.  If /_d_e_v/_t_t_y can not be opened, as would be the case
      for clients invoked through _r_s_h, the _M__D_E_B_U_G flag is turned on, and _s_t_d_i_n
      and _s_t_d_o_u_t are used instead.  The _M__M_O_D_E_O_K flag instructs those functions
      which expect data from MGR to assume the terminal modes are set appropri-
      ately.   Otherwise,  the  functions attempt to turn off character echoing
      and turn on line mode before  fetching  data  from  MGR.   The  functions
      m_ttyset()  and  m_ttyreset()  can  be used to set and reset the terminal
      modes.  The function m_setup() returns its  argument,  with  the  _M__D_E_B_U_G
      flag _o_r-ed in if /_d_e_v/_t_t_y can not be opened.

 void
 m_ttyreset()
9      The terminal modes are restored to their state just  prior  to  the  last
      call  to m_ttyset().  Calls to m_ttyset() and m_ttyreset() may be stacked
      up to ten levels.

 int
 m_ttyset()
9


                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 45 -                       Functions


      The terminal is set in a state suitable for data exchange with MGR.   All
      automatic  conversions  are  switched off to get a completely transparent
      line.  The function returns 0 if it successfully retrieves  the  terminal
      modes, -1 otherwise.





















































                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 46 -                 Using the Library


 _U_s_i_n_g _t_h_e _L_i_b_r_a_r_y

 Clients using _T_h_e _C _I_n_t_e_r_f_a_c_e _L_i_b_r_a_r_y should specify:

         #include <mgr/mgr.h>

 which also includes

         <stdio.h>

 if it has not already been included.  Programs are compiled either with

         cc -o foo -I$(inc) foo.c libmgr.a

 where $(inc) is the MGR include directory or simply

         cc -o foo foo.c -lmgr

 if the library is installed in a standard location.  The  file  _l_i_b_m_g_r._a  con-
 tains  the functions listed in the last section.  Several compile time options
 are available to the client program using the library.  Normally, the  library
 setup  routine,  m_setup()  attempts to open /_d_e_v/_t_t_y to communicate with MGR.
 Client  programs  may  define  the  C  preprocessor  symbols   _M__D_E_V_I_C_E_I_N   or
 _M__D_E_V_I_C_E_O_U_T  to override the selection of /_d_e_v/_t_t_y for input or output respec-
 tively.  After each macro call, the flush flag _M__F_L_U_S_H is  tested  to  see  if
 output  should  be  flushed to MGR.  If the C preprocessor symbol _M__N_O_F_L_U_S_H is
 defined, before the client program includes _m_g_r._h, the  flush  flag  is  never
 tested, and it becomes the responsibility of the client program to insure out-
 put is flushed at the appropriate times.

 Several external variables maintained by the library are accessible to  client
 programs.  The _s_t_d_i_o _F_I_L_E pointers _m__t_e_r_m_i_n and _m__t_e_r_m_o_u_t are used for direct-
 ing output to, and receiving input from MGR.  These file pointers are initial-
 ized  in  m_setup(),  and may be changed by client programs after m_setup() is
 called.  The integer _m__f_l_a_g_s contains the current library  mode  settings,  as
 returned  by  m_setup().  The _M__M_O_D_E_O_K and _M__F_L_U_S_H bits of _m__f_l_a_g_s may also be
 changed at any time after m_setup() is called.  The  integer  _m__e_n_v_c_o_u_n_t  con-
 tains  the  current window context depth, and is used by m_popall() to pop the
 appropriate number of contexts.  _M__e_n_v_c_o_u_n_t should not be  changed  by  client
 programs.   Finally, the character _m__m_e_n_u_c_h_a_r defines the menu separator char-
 acter used by menu_load().  This character, set to '\005' by the library pack-
 age,  can  be  changed to any character that will not appear as part of a menu
 item or action.














                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 47 -                        Glossary


 _G_l_o_s_s_a_r_y


 absolute coordinates
      _A_b_s_o_l_u_t_e _c_o_o_r_d_i_n_a_t_e_s is a coordinate system used in _w_i_n_d_o_w_s  measured  in
      units of pixels.

 active window
      The _a_c_t_i_v_e window is the window logically in the front  of  the  display,
      which is receiving keyboard and mouse input and has a bold border.

 alternate window
      An _a_l_t_e_r_n_a_t_e _w_i_n_d_o_w is an additional window created by a  client  program
      that shares the communication channel with the main window.

 bitmap
      A _b_i_t_m_a_p represents a rectangular  array  of  pixels,  either  stored  in
      server memory or displayed on-screen.

 channel
      The _c_h_a_n_n_e_l is the bidirectional byte  stream  connecting  MGR  with  the
      client  program.  The _c_h_a_n_n_e_l is usually the program's standard input and
      output.

 character coordinates
      _C_h_a_r_a_c_t_e_r _c_o_o_r_d_i_n_a_t_e_s is the coordinate system used in windows for count-
      ing  characters  in _c_o_l_u_m_n_s and _r_o_w_s .  The top left character coordinate
      is (0,0).

 character cursor
      The _c_h_a_r_a_c_t_e_r _c_u_r_s_o_r points to the location in the window where the  next
      character  will  be placed.  The cursor location is always highlighted on
      the active window.

 child menu
      A _c_h_i_l_d _m_e_n_u is a menu that will pop up when the user  slides  the  mouse
      off to the right of a popped up _p_a_r_e_n_t _m_e_n_u.

 client program
      A _c_l_i_e_n_t _p_r_o_g_r_a_m is any Unix command that is running in  an  MGR  window.
      Client  programs  may  be existing programs, as might be found in /_b_i_n or
      new MGR-aware applications written specifically to take advantage of  the
      windowing environment.

 client-host
      The _c_l_i_e_n_t-_h_o_s_t is the computer that the client program  is  running  on.
      It is often the same as the _M_G_R-_h_o_s_t machine, but it does not need to be.

 display coordinates
      _D_i_s_p_l_a_y _c_o_o_r_d_i_n_a_t_e_s is a coordinate system used to measure pixels on  the
      display.  The top left corner of the display is at (0,0), with _x increas-
      ing to the right, and _y increasing down.

 exposed



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 48 -                        Glossary


      A window is _e_x_p_o_s_e_d if it is entirely visible.

 graphics point
      The _g_r_a_p_h_i_c_s _p_o_i_n_t is a location on the window, measured in the  prevail-
      ing  window  coordinate system, that may serve as a reference location or
      origin for many of the graphics operations.

 listener
      A _l_i_s_t_e_n_e_r is a window that has turned on the ACCEPT event and is willing
      to receive messages from other client programs.

 main window
      A client program's _m_a_i_n _w_i_n_d_o_w is the window the program was started  in.
      The  client program may create and destroy alternate windows, but not its
      _m_a_i_n _w_i_n_d_o_w.  If the user destroys a client program's  _m_a_i_n  _w_i_n_d_o_w,  the
      connection  to  MGR  is severed, and the client program receives a _h_a_n_g_u_p
      signal.

 MGR-host
      The MGR-host is the computer that MGR is running on.

 mouse cursor
      The _m_o_u_s_e _c_u_r_s_o_r is a small bitmap or _i_c_o_n that tracks  the  movement  of
      the  mouse  on  the  display.  Normally the _m_o_u_s_e _c_u_r_s_o_r is a small arrow
      pointing north west.

 obscured
      A window is _o_b_s_c_u_r_e_d when it is partially or totally covered  by  another
      window.

 parent menu
      A menu is called a _p_a_r_e_n_t _m_e_n_u  when  sliding  off  to  the  right  of  a
      selected item causes another menu or _c_h_i_l_d _m_e_n_u to pop up.

 relative coordinates
      _R_e_l_a_t_i_v_e _c_o_o_r_d_i_n_a_t_e_s is a coordinate system for windows  where  a  single
      unit represents one thousandth of the way across (or down) the window.

 scratchpad bitmap
      A _s_c_r_a_t_c_h_p_a_d _b_i_t_m_a_p is a chunk of memory, allocated by MGR for use  by  a
      client program, that may hold a bitmap image that is not on the display.

 snarf buffer
      The _s_n_a_r_f _b_u_f_f_e_r is a buffer maintained by MGR of arbitrary size that  is
      accessible by all client programs.

 target window
      A _t_a_r_g_e_t _w_i_n_d_o_w is a window that is to receive  a  message  from  another
      window.

 text region
      A _t_e_x_t _r_e_g_i_o_n is the part of the window in which character text  and  the
      functions  that  operate  on characters work.  The _t_e_x_t _r_e_g_i_o_n may be the
      entire window (the default) or a rectangular subregion within the window.



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 49 -                        Glossary


 window border
      The _w_i_n_d_o_w _b_o_r_d_e_r is  a  thin  black  border  around  every  window  that
      separates  the  window  from  the  rest  of  the  display.  The border is
      included in the size of the window in display coordinates, but the window
      coordinate systems exclude the border.

 window context
      A _w_i_n_d_o_w _c_o_n_t_e_x_t contains the values for  one  or  more  aspects  of  the
      window's  state.   A  _W_i_n_d_o_w  _c_o_n_t_e_x_t  may  be saved on a stack, and then
      restored at some later time.

 window id
      A _w_i_n_d_o_w _i_d is a unique number assigned to every window that may be  used
      as  an  identifier when sending a message to the window.  _W_i_n_d_o_w _i_ds have
      two parts, the first part is the process number  of  the  client  program
      that  was  started  when  the  window was created, the second part is the
      window's _a_l_t_e_r_n_a_t_e window number, or zero for a main window.








































                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 50 -             Sample Client Program


 _S_a_m_p_l_e _C_l_i_e_n_t _P_r_o_g_r_a_m


 This program, called _c_l_o_s_e, closes, or iconifies a window. Its not a  terribly
 useful  application  in  its  own  right,  but it does exercise several of the
 library calls.  When _c_l_o_s_e starts up, it makes the window  smaller,  moves  it
 toward  the  top  of the display, then writes the word "closed" in it.  If the
 window is covered by another window, it changes the word "closed" to "hidden",
 then flashes its window every 15 seconds as long as the window is covered.  If
 the window is then uncovered, the word "hidden" gets changed back to "closed".
 Activating  the window causes _c_l_o_s_e to restore the window's original shape and
 contents, then exit.

 /* _i_c_o_n_i_f_y _a _M_G_R _w_i_n_d_o_w */

 #include <mgr/mgr.h>
 #include <signal.h>

 #define TIME    15                /* _t_i_m_e _i_n_t_e_r_v_a_l _f_o_r _r_e_m_i_n_d_e_r */
 #define CONTEXT P_POSITION | P_WINDOW | P_FLAGS | P_EVENT | P_CURSOR

 static char line[80];             /* _e_v_e_n_t _i_n_p_u_t _b_u_f_f_e_r */

 int main()
     {
     int clean(), timer();         /* _i_n_t_e_r_r_u_p_t _r_o_u_t_i_n_e_s */
     int x,y;                      /* _w_i_n_d_o_w _p_o_s_i_t_i_o_n _o_n _d_i_s_p_l_a_y */
     char *msg = "closed";         /* _c_l_o_s_e_d _w_i_n_d_o_w "_i_c_o_n" */

     /* _s_e_t_u_p _t_h_e _w_i_n_d_o_w _e_n_v_i_r_o_n_m_e_n_t */

     m_setup(M_FLUSH);             /* _s_e_t_u_p _i/_o, _t_u_r_n _o_n _f_l_u_s_h_i_n_g */
     m_push(CONTEXT);              /* _s_a_v_e _c_u_r_r_e_n_t _w_i_n_d_o_w _c_o_n_t_e_x_t */
     m_setmode(M_NOWRAP);          /* _d_o_n'_t _a_u_t_o-_w_r_a_p _a_t _r_i_g_h_t _m_a_r_g_i_n */
     m_ttyset();                   /* _s_e_t _u_p _t_t_y _m_o_d_e_s */

     /* _c_a_t_c_h _t_h_e _a_p_p_r_o_p_r_i_a_t_e _s_i_g_n_a_l_s */

     signal(SIGTERM,clean);        /* _i_n _c_a_s_e _w_e _g_e_t _t_e_r_m_i_n_a_t_e_d */
     signal(SIGALRM,timer);        /* _f_o_r _t_h_e _r_e_m_i_n_d_e_r _s_e_r_v_i_c_e */

     /* _i_c_o_n_i_f_y _t_h_e _w_i_n_d_o_w */

     get_size(&x,&y,0,0);          /* _f_e_t_c_h _w_i_n_d_o_w _c_o_o_r_d_i_n_a_t_e_s */
     m_sizeall(x,10,strlen(msg),1);/* _m_o_v_e _a_n_d _r_e_s_i_z_e _w_i_n_d_o_w */
     m_clear();                    /* _c_l_e_a_r _t_h_e _w_i_n_d_o_w */
     m_printstr(msg);              /* _p_r_i_n_t _m_e_s_s_a_g_e _i_n _t_h_e _w_i_n_d_o_w */

     /* _c_a_t_c_h _e_v_e_n_t_s */

     m_setevent(ACTIVATE, "A\n"); /* _w_i_n_d_o_w _i_s _n_o_w _t_h_e _a_c_t_i_v_e _w_i_n_d_o_w */
     m_setevent(COVERED,  "C\n"); /* _c_o_v_e_r_e_d _b_y _a_n_o_t_h_e_r _w_i_n_d_o_w */
     m_setevent(UNCOVERED,"U\n"); /* _c_o_m_p_l_e_t_e_l_y _v_i_s_i_b_l_e */
     m_setevent(REDRAW,   "R\n"); /* _r_e_d_r_a_w _r_e_q_u_e_s_t_e_d */



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 51 -             Sample Client Program


     m_clearmode(M_ACTIVATE);      /* _b_u_r_y _t_h_e _w_i_n_d_o_w */

     /* _w_a_i_t _f_o_r _a_n _e_v_e_n_t */

     while(m_gets(line) != NULL)   /* _r_e_a_d _a _l_i_n_e _f_r_o_m _M_G_R */
         switch (*line) {
         case 'A':                 /* _w_i_n_d_o_w _i_s _a_c_t_i_v_a_t_e_d */
             clean();              /* _c_l_e_a_n _u_p _a_n_d _e_x_i_t */
             break;
         case 'C':                 /* _w_i_n_d_o_w _i_s _c_o_v_e_r_e_d */
             m_clear();
             m_printstr("hidden");
             alarm(TIME);          /* _t_u_r_n _o_n _r_e_m_i_n_d_e_r */
             break;
         case 'R':                 /* _s_y_s_t_e_m '_r_e_d_r_a_w' */
         case 'U':                 /* _w_i_n_d_o_w _i_s _u_n_c_o_v_e_r_e_d */
             m_clear();
             m_printstr(msg);
             alarm(0);             /* _t_u_r_n _o_f_f _r_e_m_i_n_d_e_r */
             break;
         case 'T':                 /* _s_e_n_d _r_e_m_i_n_d_e_r */
             m_setmode(M_WOB);     /* _h_i_g_h_l_i_g_h_t _w_i_n_d_o_w */
             m_bell();             /* _r_i_n_g _t_h_e _b_e_l_l */
             sleep(1);
             alarm(TIME);          /* _r_e_s_e_t _r_e_m_i_n_d_e_r _t_i_m_e_r */
             m_clearmode(M_WOB);   /* _r_e_s_e_t _w_i_n_d_o_w _h_i_g_h_l_i_g_h_t_i_n_g */
             break;
         }
     }

 clean()                           /* _c_l_e_a_n _u_p _a_n_d _e_x_i_t */
     {
     m_ttyreset();                 /* _r_e_s_e_t _t_t_y _m_o_d_e_s */
     m_popall();                   /* _r_e_s_t_o_r_e _w_i_n_d_o_w _c_o_n_t_e_x_t */
     exit(0);
     }

 timer()                           /* _c_a_l_l_e_d _a_t _r_e_m_i_n_d_e_r _t_i_m_e_o_u_t */
     {
     m_sendme("T\n");             /* _s_e_n_d _t_i_m_e_o_u_t _m_e_s_s_a_g_e */
     }
















                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 52 -    Macros and Functions by Category


 _M_a_c_r_o_s _a_n_d _F_u_n_c_t_i_o_n_s _b_y _C_a_t_e_g_o_r_y




 _L_i_b_r_a_r_y _P_a_c_k_a_g_e _C_o_n_t_r_o_l*



 m_bell 11...........Flash the window and ring the bell.

 m_flush 18..........Flush any outpout pending for the window.

 m_lastline|- 44......Retrieve the last line send from MGR for a  library  func-
                     tion.

 m_resetesc 29.......Restore the MGR escape character to '033'.

 m_setecho 31........Turn on terminal character echo.

 m_setesc 31.........Change the MGR escape character (for debugging).

 m_setnoecho 37......Turn off character echo.

 m_setnoraw 37.......Enable normal character input processing (line mode).

 m_setraw 37.........Disable all character input processing (raw mode).

 m_setup|- 44.........Initialize the library package.

 m_ttyreset|- 44......Reset the tty modes.

 m_ttyset|- 44........Set the tty modes for proper MGR interaction.


 _S_t_a_n_d_a_r_d _I/_O _F_u_n_c_t_i_o_n_s



 m_getchar 19........Read a character from MGR.

 m_gets 23...........Read a line from MGR.

 m_printstr 26.......Print a string on the window.

 m_putchar 29........Put a character on the window.

9 _________________________
9   * The routines marked with a  dagger  (|-)  are  func-
 tions,  the other routines are macros.  The page number
 on which the macro or function is defined is printed in
 bold face after the name.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 53 -    Macros and Functions by Category


 _T_e_r_m_i_n_a_l _F_u_n_c_t_i_o_n_s



 m_addchar 11........Insert a space character.

 m_addchars 11.......Insert some space characters.

 m_addline 11........Insert a blank line.

 m_addlines 11.......Insert some blank lines.

 m_aligntext 11......Align character cursor with the graphics point.

 m_clear 14..........Clear the window.

 m_cleareol 14.......Clear to the end of the line.

 m_cleareos 14.......Clear to the end of the window.

 m_deletechar 16.....Delete a character.

 m_deletechars 16....Delete characters.

 m_deleteline 16.....Delete a line.

 m_deletelines 16....Delete lines.

 m_down 17...........Move character  cursor  down  by  tenths  of  a  character
                     height.

 m_fracdown 18.......Cursor down a fraction of a char height.

 m_fracleft 18.......Cursor left a fraction of a char width.

 m_fracright 18......Cursor right a fraction of a char width.

 m_fracup 18.........Cursor up a fraction of a char height.

 m_incr 24...........Adjust the character cursor position.

 m_left 24...........Move character cursor left by tenths of a character width.

 m_move 25...........Move the character cursor.

 m_movecursor 25.....Move the character cursor to an arbitrary coordinate loca-
                     tion.

 m_moveprint 25......Print a string at a given location.

 m_right 30..........Move character cursor  right  by  tenths  of  a  character
                     width.

 m_scrollregion 30...Set up a VT00 like scrolling region.



                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 54 -    Macros and Functions by Category


 m_setesc 31.........Change the character cursor representation.

 m_standend 37.......Turn off reverse video characters.

 m_standout 37.......Turn on reverse video characters.

 m_textregion 38.....create a text region.

 m_textreset 38......Reset the text region to the entire window.

 m_up 38.............Move character cursor up by tenths of a character height.


 _G_r_a_p_h_i_c_s _P_r_i_m_i_t_i_v_e_s



 m_arc 11............Draw an arc.

 m_circle 14.........Draw a circle.

 m_draw 17...........Draw a line from the graphics point.

 m_ellipse 17........Draw an ellipse.

 m_ellipseto 17......Draw an ellipse on a scratchpad bitmap.

 m_fastdraw 17.......Draw a group of fast vectors.

 m_func 18...........Set the bit-blt and graphics drawing mode.

 m_go 23.............Move the graphics point.

 m_gotext 23.........Align the graphics point with the character cursor.

 m_line 24...........Draw a line.

 m_lineto 24.........Draw a line on a scratchpad bitmap.

 m_rcircle 29........Draw a circle at the graphics point.

 m_rellipse 29.......Draw an ellipse at the graphics point.

 m_rfastdraw 29......Draw a group of fast vectors at the graphics point.

 m_stringto 38.......Print a string to an scratchpad bitmap.


 _B_i_t-_b_l_t_s _a_n_d _R_e_l_a_t_e_d _F_u_n_c_t_i_o_n_s



 bitmapread|- 42......Read an MGR bitmap from a file.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 55 -    Macros and Functions by Category


 bitmapwrite|- 42.....Write an MGR bitmap to a file.

 m_bitccreate 11.....Create a color scratchpad bitmap.

 m_bitcld 12.........Download an image to the window.

 m_bitcldto 12.......Down load an image to a scratchpad bitmap.

 m_bitcopy 12........Bit-blt a rectangle within the window.

 m_bitcopyto 12......Bit-blt a rectangle between two bitmaps.

 m_bitcreate 12......Create a scratchpad bitmap.

 m_bitdestroy 13.....Destroy a scratchpad bitmap.

 m_bitfile|- 42.......Read a bitmap file into a scratchpad bitmap.

 m_bitfromfile 13....Read a bitmap file into a scratchpad bitmap.

 m_bitget 13.........Upload a bitmap to the client program.

 m_bitld 13..........Download a monochrome image to the window.

 m_bitldto 13........Down load a monochrome image to a scratchpad bitmap.

 m_bitsave 13........Copy a scratchpad bitmap to a file.

 m_bitset 13.........set a pixel on a bitmap to a given value.

 m_bitvalue 14.......Get value of pixel in bitmap.

 m_bitwrite 14.......Set, Clear or Invert a rectangular portion of the window.

 m_bitwriteto 14.....Set, Clear or Invert a rectangular portion of a scratchpad
                     bitmap.

 m_func 18...........Set the bit-blt function.

 m_getbordersize|- 43.Inquire the pixel width of window borders.

 m_getdepth|- 43......Inquire the depth of the screen in bits.

 m_othersave 26......Save another client's window image in a file.

 m_windowsave 38.....Save the window image on a file.


 _W_i_n_d_o_w _E_n_v_i_r_o_n_m_e_n_t _C_h_a_n_g_e_s



 m_clearmode 15......Reset a window mode.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 56 -    Macros and Functions by Category


 m_dupkey 17.........Turn on keyboard escape mechanism.

 m_font 18...........Change to a new font.

 m_loadfont 25.......Download a font.

 m_movemouse 25......Move the mouse position.

 m_movewindow 26.....Move a window.

 m_setmode 35........Set a window mode.

 m_shapewindow 37....Reposition a window.

 m_size 37...........Resize a window to a specified number of rows and columns.

 m_sizeall 37........Reposition a window  with  a  given  number  of  rows  and
                     columns.


 _W_i_n_d_o_w _S_t_a_t_e _I_n_q_u_i_r_y



 ckmgrterm|- 42.......Check $TERM for an MGR terminal.

 get_all|- 40.........Get all window status.

 get_client|- 40......Get alternate window status.

 get_colrow|- 40......Get window size, in columns and rows.

 get_cursor|- 40......Get cursor position.

 get_eachclientwin|- 41Get window parameters for each window.

 get_eachwin|- 41.....Get window parameters for each window.

 get_font|- 41........Get character font size.

 get_mouse|- 41.......Get mouse position.

 get_param|- 41.......Get MGR system parameters.

 get_size|- 41........Get the window size and position on the display.

 get_termcap|- 42.....Get a TERMCAP entry.

 is_active|- 42.......See if the window is the active window.

 m_getfontid|- 43.....Get id number of current font.

 m_getfontname|- 43...Get name of current font.




                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 57 -    Macros and Functions by Category


 m_getfontsize|- 43...Get size of current font.

 m_gethostname|- 43...Get name of MGR server host.

 m_getinfo 19........Ask MGR for information.

 m_getscreensize|- 43.Get MGR screen size parameters.

 m_getwindowposition|- 43
                     Get window position.

 m_getwindowsize|- 44.Get window size.

 m_whatsat 38........Find out what is at a particular display location.


 _P_o_p-_u_p _M_e_n_u _M_a_n_a_g_e_m_e_n_t



 m_clearmenu 15......Clear a menu.

 m_linkmenu 24.......Link two menus together.

 m_loadmenu 25.......Down load a menu.

 m_menubar 25........Highlight a menu item (extended menu operation).

 m_menuerase 25......Remove a menu (extended menu operation).

 m_menuitem 25.......Pre-select a menu item.

 m_menushow 25.......Display a menu (extended menu operation).

 m_nomenu 26.........Unselect a pop-up menu from the middle mouse button.

 m_nomenu2 26........Unselect a pop-up menu from the end mouse button.

 m_pagemenu 26.......Break a large menu into pages.

 m_selectmenu 30.....Select a pop-up menu for the middle mouse button.

 m_selectmenu2 30....Select a pop-up menu for the right mouse button.

 m_unlinkmenu 38.....Unlink a menu.

 m_unpagemenu 38.....Disconnect two pages of a paged menu.

 menu_load|- 42.......Down load a pop-up menu.


 _E_v_e_n_t _H_a_n_d_l_i_n_g





                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 58 -    Macros and Functions by Category


 m_clearevent 14.....Clear an event.

 m_setevent 31.......Set an event.


 _W_i_n_d_o_w _C_o_n_t_e_x_t _M_a_n_i_p_u_l_a_t_i_o_n



 m_pop 26............Pop the window context.

 m_popall 26.........Pop all stacked window contexts.

 m_push 27...........Stack the window context.

 m_pushsave 28.......Stack and save the window context.


 _M_u_l_t_i_p_l_e _W_i_n_d_o_w_s



 m_destroywin 16.....Destroy an alternate window.

 m_halfwin 23........Create a window with no process connected to it.

 m_halfwinft 23......Create a window with no process connected to it.

 m_makewindow|- 44....Make an alternate window.

 m_newwin 26.........Make a new window.

 m_selectwin 30......Select an alternate window for output.


 _M_e_s_s_a_g_e _P_a_s_s_i_n_g



 m_broadcast 14......Broadcast a message to all listeners.

 m_put 29............Save characters in the global snarf buffer.

 m_sendme 30.........Send string back to self.

 m_sendto 31.........Send a message to another window.

 m_snarf 37..........Retrieve the contents of the global snarf buffer.


 _M_i_s_c_e_l_l_a_n_e_o_u_s _F_u_n_c_t_i_o_n_s






                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





 MGR-C Language Application Interface- 59 -    Macros and Functions by Category


 m_highlight 23......Highlight a portion of the display.

 m_sleep 37..........Do nothing.


 _C_o_l_o_r _M_a_n_i_p_u_l_a_t_i_o_n



 m_bcolor 11.........Set the text background color.

 m_fcolor 17.........Set the text foreground color.

 m_fgbgcolor 18......Set the graphics foreground and background colors.

 m_linecolor 24......Set the graphics mode and color.









































                                     March 28, 1996       MGR 0.59  8c9 1988 Bellcore





     MGR-C Language Application Interface- 60 -           Macro and Function Index


     _M_a_c_r_o _a_n_d _F_u_n_c_t_i_o_n _I_n_d_e_x

     These are the pages where macros and functions are referenced.  The bold
     page numbers are the defining references.

     bitmap 42
     bitmapread 42
     bitmapwrite 42
     ckmgrterm 42
     file_pointer 42
     get_all 40, 41
     get_client 40, 41
     get_colrow 40
     get_cursor 40
     get_eachclientwin 41
     get_eachwin 41
     get_font 40, 41
     get_mouse 41
     get_param 40, 41
     get_size 40, 41
     get_termcap 42
     is_active 42
     m_addchar 11
     m_addchars 11
     m_addline 11
     m_addlines 11
     m_aligntext 11
     m_arc 11
     m_bcolor 11, 17, 18,
     24
     m_bell 11
     m_bitccreate 11
     m_bitcld 12
     m_bitcldto 12
     m_bitcopy 12
     m_bitcopyto 12
     m_bitcreate 12
     m_bitdestroy 13
     m_bitfile 42
     m_bitfromfile 12, 13,
     17, 42
     m_bitget 13
     m_bitld 12, 13
     m_bitldto 13
     m_bitsave 13, 26, 39
     m_bitset 13
     m_bitvalue 13
     m_bitwrite 14, 18
     m_bitwriteto 12, 14
     m_broadcast 14, 31
     m_circle 14
     m_clear 14, 22
     m_cleareol 14
     m_cleareos 14
7777777777777777777777777777777777777777777777777                                m_clearevent 14
                                m_clearmenu 14
                                m_clearmode 15, 22,
                                35, 37
                                m_deletechar 16
                                m_deletechars 16
                                m_deleteline 16
                                m_deletelines 16
                                m_destroywin 16
                                m_down 17, 18, 24,
                                30, 38
                                m_draw 17
                                m_dupkey 16, 17, 40
                                m_ellipse 14, 17
                                m_ellipseto 17
                                menu_load 42, 46
                                m_fastdraw 17, 30
                                m_fcolor 11, 17, 18,
                                24
                                m_fgbgcolor 11, 17,
                                18, 24
                                m_flush 18, 44
                                m_font 18, 25, 27,
                                28, 41
                                m_fracdown 18
                                m_fracleft 18
                                m_fracright 18
                                m_fracup 18
                                m_func 11, 12, 14,
                                15, 17, 18, 23, 24,
                                29, 36
                                m_getbordersize 43
                                m_getchar 19
                                m_getdepth 43
                                m_getfontid 43
                                m_getfontname 43
                                m_getfontsize 43
                                m_gethostname 43
                                m_getinfo 17, 19, 26,
                                30, 31, 32, 37, 41
                                m_gets 23, 31
                                m_getscreensize 43
                                m_getwindowposition
                                43
                                m_getwindowsize 44
                                m_go 11, 17, 23
                                m_gotext 23
                                m_halfwin 23
                                m_halfwinft 23
7777777777777777777777777777777777777777777777777                                                           m_highlight 23
                                                           m_incr 24
                                                           m_lastline 40, 44
                                                           m_left 17, 18, 24,
                                                           30, 38
                                                           m_line 18, 24
                                                           m_linecolor 24
                                                           m_lineto 24
                                                           m_linkmenu 24, 26, 38
                                                           m_loadfont 18, 25
                                                           m_loadmenu 25, 30
                                                           m_makewindow 19, 44
                                                           m_menubar 25
                                                           m_menuerase 25
                                                           m_menuitem 25
                                                           m_menushow 25
                                                           m_move 25
                                                           m_movecursor 25
                                                           m_movemouse 25
                                                           m_moveprint 25
                                                           m_movewindow 26
                                                           m_newwin 16, 17, 23,
                                                           26, 30, 32
                                                           m_nomenu 26
                                                           m_nomenu2 26
                                                           m_othersave 13, 26,
                                                           39
                                                           m_pagemenu 26, 38
                                                           m_pop 26, 27, 28
                                                           m_popall 26, 27, 28,
                                                           46
                                                           m_printstr 25, 26
                                                           m_push 9, 16, 26, 27,
                                                           28, 29
                                                           m_pushsave 26, 28
                                                           m_put 29, 32, 37
                                                           m_putchar 29
                                                           m_rcircle 29
                                                           m_rellipse 29
                                                           m_resetesc 29
                                                           m_rfastdraw 17, 29
                                                           m_right 17, 18, 24,
                                                           30, 38
                                                           m_scrollregion 30, 38
                                                           m_selectmenu 25, 30
                                                           m_selectmenu2 30
                                                           m_selectwin 16, 26,
                                                           30, 44
                                                           m_sendme 30



                                     March 28, 1996       MGR 0.59  8c9 1988 Bellcore





     MGR-C Language Application Interface- 61 -           Macro and Function Index


     m_sendto 31, 32, 34
     m_setcursor 31
     m_setecho 31
     m_setesc 29, 31
     m_setevent 14, 26,
     30, 31
     m_setmode 15, 16, 22,
     27, 28, 35, 37
     m_setnoecho 37
     m_setnoraw 37
     m_setraw 37
     m_setup 18, 26, 44,
     46
     m_shapewindow 37
     m_size 37
     m_sizeall 37
     m_sleep 37
     m_snarf 29, 35, 37
     m_standend 37
     m_standout 37
     m_stringto 12, 38
     m_textregion 25, 30,
     38
     m_textreset 30, 38
     m_ttyreset 44
     m_ttyset 44
     m_unlinkmenu 25, 26,
     38
     m_unpagemenu 26, 38
     m_up 17, 18, 24, 30,
     38
     m_whatsat 38
     m_windowsave 13, 26,
     38




















777777777777777777777777777777777777777777777777777777
























































                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore





                                     - _i -





                               Table of Contents




 Introduction ............................................................    1

 Model of Interaction ....................................................    3

 Coordinate Systems ......................................................    3

 Functional Overview .....................................................    4

 Underlying Protocol .....................................................    7

 Conventions and Notation ................................................    9

 Macros ..................................................................   11

 Functions ...............................................................   40

 Using the Library .......................................................   46

 Glossary ................................................................   47

 Sample Client Program ...................................................   50

 Macros and Functions by Category ........................................   52

 Macro and Function Index ................................................   60
























                                 March 28, 1996       MGR 0.59  8c9 1988 Bellcore


