page Macros
The C library interface macros expand into expressions that convert their command specification into the stream protocol. Compile time and run time options are available that globally alter the behavior of these macros to the specific needs of the client program. The options are detailed in the 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 command (a command identifier - argument count combination) that is accepted by has a macro which invokes that function. Inserts a space character at the current character cursor position. The remaining characters on the line, if any, are shifted to the right. Inserts space characters at the current character cursor position. The remaining characters on the line, if any, are shifted to the right. 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. Inserts blank lines at current row. The current row, and any below it, are shifted down. The bottom lines of text are scrolled off the window. It is much more efficient to call m_addlines n once, than it is to call m_addline times. 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. An arc centered at x y is drawn counter clockwise from x1 y1 to x2 y2 using the current drawing function (see m_func ). 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. The background color for text operations is set to which is an index into the color lookup table. This command has no effect on a monochrome display. See also m_fcolor and m_fgbgcolor . Create the scratchpad bitmap of size by with bit depth having undefined initial contents. This macro is identical to m_bitcreate except that if 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. Prepare to download a color or monochrome bitmap to the window. This macro instructs that the next bytes received will be interpreted as a bitmap image to be displayed on the window starting at location x y , and of size by by in bits. Downloading bitmaps requires an eight bit channel between 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 is insufficient to fill the entire bitmap, the remainder of the bits are set to undetermined values. The bitmap data is sent in external format. Prepare to download a bitmap to the scratchpad bitmap If does not already exist, (see m_bitcreate ), it is created automatically with size by by in bits. This function instructs that the next bytes received will be interpreted as a bitmap image to be copied to scratchpad bitmap at location This function requires an eight bit channel between 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 is insufficient to fill the entire bitmap, the remainder of the bits are set to undetermined values. The bitmap data is sent in external format. Copy a rectangle from one place on the window to another with the copy function set by m_func n . The rectangular area at of size by is combined with the rectangle at according to the last function set by m_func . The resultant rectangle is placed at Combine the rectangle at position of size by of bitmap with the rectangle of the same size at of bitmap The bit-blt function used to combine the two rectangles is set by m_func . and 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 does not already exist, it is created with a size of by Create the scratchpad bitmap of size by 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 bitmaps may also be created implicitly by specifying a non-existent bitmap as the destination of m_bitwriteto , m_bitcopyto , m_bitld , or m_stringto . Destroys scratchpad bitmap and frees all the resources associated with it. If does not exist, this macro has no effect. Copy the file on the machine into the scratchpad bitmap The scratchpad bitmap is created if it does not already exist. returns a single line containing the and of the bitmap, or a if the file could not be found or loaded. If does not start with or The file is prefixed with 's home directory and starting with are evaluated relative to the directory current when was invoked. The formats of bitmap files are described in the header file. Upload part of a bitmap. bytes of bitmap starting bytes from the beginning of the bitmap are sent to the client program from After this call, the client is expected to read bytes from the input stream. The image data is sent in external bitmap format, i.e., raster scan order, 8 pixels to a bigendian byte, padded at the right of every line to 8 bits. should be kept small (about 80 bytes), to avoid potential flow control problems, with bitmaps uploaded in multiple passes. The data sent by for this macro requires an eight bit data channel, so its use is discouraged. The macro m_bitsave should be used instead when possible. Prepare to download a monochrome bitmap to the window. This is identical to a call to m_bitcld with the parameter deep set to one. Prepare to download a monochrome bitmap to the scratchpad bitmap This is identical to a call to m_bitcldto with the parameter deep set to one. Save a scratchpad bitmap on the file on the file system. If does not start with or is prefixed with 's home directory and starting with are evaluated relative to the directory current when was invoked. Specifying to be (zero) saves the entire display contents to the file. The functions m_windowsave and m_othersave are used to save contents of entire windows. Set the value of the pixel on the bitmap to the value given in In a monochrome version of the 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. Get the current value of the pixel x, y in the bitmap 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. The rectangular region of the window, starting at of extent by is set, cleared or inverted as determined by the previous call to m_func . The rectangular region of bitmap starting at of extent by is set, cleared or inverted as determined by the previous call to m_func . If the destination does not exist, it is created with the dimensions by The message is broadcast to all windows that are is turned on by setting the 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 messages that get interpreted and executed as commands. A circle of radius is drawn, centered at 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 is scaled based upon the average and of the window. Use m_ellipse to obtain a scaled circle. The current is cleared, and the character cursor is moved to position 0 0 . If no is set, m_clear clears the entire window. All of the characters on the current line, starting with the current character to the end of the are cleared. If no is set, m_cleareol clears to the edge of the window. All of the characters in the current from the current character to the end of the are cleared. If no is set, m_clear clears to the end of the window. Event is cleared. The integer is one of: or See m_setevent for a description of the events. If menu exists, it is cleared. 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 .
window coordinate mode is turned off. The window is now in window coordinates. All window coordinates range from 0 0 in the upper left corner to 999 999 at the lower right.
Bury the window. Unlike the other window modes, 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 intersecting it will appear in front of it.
Do not automatically activate the window the next time it receives output.
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 is turned on.
This window is not the destination of stuff written to "/dev/console".
Buckey keys, those with value from 128-255, can cause server functions to be executed when typed at the keyboard, if the BUCKEY capability was configured into the server at compile time.
Accept keyboard input if the window is active.
Report changes in window sizes to the OS, if the OS wants to know the sizes of terminals attached to ttys.
Wrap the character cursor to the next line when it reaches the right margin of the
Do not overstrike characters. Text is copied to the window as if m_func BIT_SRC is set.
The system function fails if any errors are found. This is indicated by flashing the window. The contents of the buffer are left undisturbed. Normally this only happens if some process unknown to scribbles into the region being cut.
Sets the system function to cut individual characters, instead of entire lines only.
The system function cuts text exactly as it appears on the window. All interior white space is converted to all trailing white space is treated as a
Event stacking is turned off. Event strings are only returned for the current window context and not for any contexts stacked with m_push .
Characters are drawn in black with a white background.
The window foreground color is set to and the window background color is set to
The keyboard escape character is turned off. This mode is turned on by calling m_dupkey . There is no corresponding call to m_setmode . 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 The next characters are deleted, starting at the character cursor position. Any characters on the line to the right of the cursor are shifted left character positions. The last characters on the line are set to The line at the cursor position is deleted. Any lines below the cursor are shifted up one line. The last line is cleared. The next lines starting at the cursor position and toward the bottom of the window are deleted. Any lines below the deleted ones are shifted up lines. The last lines are cleared. It is more efficient to make one call to m_deletelines than to call m_deleteline times. Destroy alternate window created by calling m_newwin . If output is currently directed to this window, it is automatically re-directed to the window. See also m_selectwin . Move the character cursor down tenths of a character height. This may cause the window to scroll. See also m_left , m_right , and m_up . Draw a line from current to x y . The macro m_go is used to move the The is left at x y , the end point of the line. Every time the character 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 and string with a two character code whose first character is and whose second character is anything but or When this mode is set, all replies to queries, as with m_getinfo are prepended by the two character sequence followed by 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 commands that return a character string to the client program, such as m_newwin or m_bitfromfile . Draw an ellipse centered at x y . The values for and 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 and are scaled based upon the average width and height of the window. Draw an ellipse on scratchpad bitmap centered at x y where 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 and are scaled based upon the average and of the window. If the offscreen bitmap does not exist, this call has no effect. The next bytes of are sent to are to be interpreted as lines drawn in mode, starting at x y . mode permits the rapid drawing of short vectors by encoding an displacement location in a single byte. The coordinate is contained in the most significant 4 bits, the coordinate in the least significant 4 bits. Values for and represent displacements from the previous location, and range from +7 to -8. A 7 is coded as a -8 as If both and are zero (i.e. The next coordinate is taken to be a instead of a An eight bit channel between and the client program is required for mode. See also m_rfastdraw . The foreground color for text operations is set to , which is an index into the color lookup table. This command has no effect on a monochrome display. See also m_bcolor and m_fgbgcolor . The foreground and background colors for graphics operations are set to , and , 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 background) remains unchanged. See also m_bcolor and m_fcolor . Flush the output buffer. This is equivalent to the stdio function and is needed only when the flag is specified in the call to m_setup .