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 which also includes 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 #include #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 .