dbell@daisy.UUCP (David I. Bell) (03/10/85)
I have finally created a manual page for DPY (which was posted recently). The following contains the original nroff input file, and also the final output file in case you can't run it off yourself. Enjoy. - dbell - #---Cut here and place in it's own directory, then feed to Bourne shell--- # This is a shell archive. Remove anything before this line, then # unpack it by saving it in a file and typing "sh file". (Files # unpacked will be owned by you and have default permissions.) # This archive contains: # dpy.3 (17265 chars) # dpy.doc (20751 chars) # echo x - dpy.3 sed -e 's/^X//' > "dpy.3" << '//E*O*F dpy.3//' X.TH DPY 3 "7 March 1985" X.UC 4 X.SH NAME Xdpy \- new screen updating routines X.SH SYNOPSIS X.nf X.ft B Xdpyinit(ttytype, modestring) Xchar *ttytype, *modestring; X Xdpywindow(minrow, maxrow, mincol, maxcol) Xint minrow, maxrow, mincol, maxcol; X Xdpyread(prompt, routine, buf, count) Xchar *prompt; Xint (*routine)(); Xchar *buf; Xint count; X Xdpymove(row, col) Xint row, col; X Xdpyplace(row, col, ch) Xint row, col; Xchar ch; X Xdpywrite(buf, count) Xchar *buf; Xint count; X Xdpyprintf(fmt [,args] ...) Xchar *fmt; X Xdpychar(ch) Xchar ch; X Xdpystr(str) Xchar *str; X Xdpyget(row, col) Xint row, col; X Xdpyclrline() X Xdpyclrwindow() X Xdpyhome() X Xdpygetrow() X Xdpygetcol() X Xdpyupdate() X Xdpyredraw() X Xdpystop() X Xdpyclose() X.ft R X.fi X.SH DESCRIPTION X.I XDpy Xis a terminal display package much like X.IR curses (3). XHowever, X.I dpy Xdoes not provide all of the capabilities of X.IR curses , Xbut instead tries to focus on the following two goals: X.TP 5n X1. XAllow the programmer to easily define and update many different Xrectangles of data on the screen at the same time. X.TP X2. XBe as fast as possible. X.PP XA tutorial on the usage of X.I dpy Xappears later in this document. XThe remainder of this section describes the procedures. X X.I Dpyinit Xmust be called before any other call to X.I dpy (except for X.IR dpyclose ). XIt allocates memory for two screen images, Xdefines the current window to be the whole screen, Xsets the current write location to the upper left corner of the screen, Xuses X.IR signal (2) Xto cause the terminal stop character to trap to X.I dpystop Xfor pretty program stopping (only on BSD systems), and sets the terminal Xmodes to allow for terminal input of various kinds. XThe actual terminal screen is not cleared until the first X.I dpyupdate Xcall is made, so that you can initialize your program based upon the Xterminal size before deciding to continue. X.I Ttytype Xis a string specifying the terminal type (example: "vt100"), Xor NULL to use the value specified by the X.I TERM Xenvironment variable. X.I Modestring Xis a string specifying how input is to be treated from the terminal. XEach mode is specified by a single letter, preceeded by an (optional) plus Xsign to enable the mode, or preceeded by a minus sign to disable the mode. XModes can be separated by spaces. XModes not mentioned in the string are unchanged. XThe currently defined mode letters are: X.TP 5n X.B e X(echo) Echoing of input characters occurs. X.TP X.B c X(cbreak) Characters are returned without waiting for a newline and tty Xsignals are processed. X.TP X.B r X(raw) Characters are returned exactly as typed and tty signals are disabled. X.PP XThus the normal terminal modes before starting X.I dpy Xare described by the string "e -c -r". XIf X.I modestring Xis a NULL pointer, then the default modes of "-e c" are used. XIf the X.I dpyread Xcall is to be used in your program, then you must specify that echoing Xis disabled, and that either cbreak or raw mode is enabled. X.I Dpyinit Xreturns nonzero with an error message typed if it cannot initialize. X X.I Dpyclose Xhomes down to the lower left corner of the terminal screen, clears the last Xline of the screen, frees the memory allocated by X.IR dpyinit, Xand restores the original terminal modes. XThis is useful just before exiting from your program. X.I Dpyclose Xis guaranteed to do nothing if X.I dpyinit Xhas not yet been completed, so that it is safe to call X.I dpyclose Xat any time. X X.I Dpyupdate Xmakes the terminal screen look like the future screen image, Xusing a minimal amount of terminal I/O. XThe cursor is also positioned to the current write location. XThis routine must be called when you have completed your writing of data to Xthe future screen image, in order to make those changes visible to the user. X X.I Dpywindow Xspecifies the rectangle where characters will be placed in the future Xscreen image, and sets the current write location to the top left Xcorner of the rectangle. XThe upper left corner of the window has the coordinates specified by X.I minrow Xand X.IR mincol , Xand the lower right corner has the coordinates specified by X.I maxrow Xand X.IR maxcol . XThese coordinates are the absolute screen coordinates, where Xthe upper left corner of the screen is row 0 and column 0. XNegative numbers specify row or column numbers from the bottom or Xright edges of the screen. XFor example, X.nf X dpywindow(0, -1, 0, -1); X.fi Xdefines a window which fills the whole screen. XReturns nonzero if the coordinates are illegal. X X.I Dpywrite Xwrites X.I count Xcharacters from location X.I buf Xto the future screen image at the current write location in the current Xwindow, and updates the current write location appropriately. XThis call does not do any actual I/O to the terminal. XControl characters are handled reasonably, as is running off the end Xof a line or the window. XThis routine is called by X.IR dpychar, X.IR dpystr, Xand X.IR dpyprintf, Xand is therefore the most efficient way to give characters to X.IR dpy . XReturns nonzero if not all the characters fit in the window. X X.I Dpychar Xwrites the single character X.I ch Xto the future screen image. XReturns nonzero if the character couldn't fit in the window. X X.I Dpystr Xwrites the null terminated string X.I str Xto the future screen image. XReturns nonzero if any of the string couldn't fit in the window. X X.I Dpyprintf Xwrites a formated string to the future screen image in the manner of X.IR printf (3). X.I Fmt Xis the format string, and X.I args Xare arguments to the format string. XReturns nonzero if any of the string couldn't fit in the window. X X.I Dpyclrline Xclears the rest of the line in the future screen image (by changing Xthe characters to spaces), but does not change the current write location. XWriting a linefeed to the future screen performs this function, Xin addition to moving the write location to the next line. X X.I Dpyclrwindow Xclears the rest of the window in the future screen image, but Xdoes not change the current write location. XWhen rewriting a window completely, this should be called when done so Xthat any old contents of the window will be sure to be cleared out. X X.I Dpymove Xchanges the current write location to the specified X.I row Xand X.I column Xnumbers, relative to the upper left corner of the current window. XThe upper left corner of the window is row 0 and column 0. XNegative numbers measure from the last row or column of the window. XFor example, X.nf X dpymove(-1, 0); X.fi Xpositions to the beginning of the last line of the window. XThis does not set the actual terminal's cursor location unless it is Xalso followed by a call to X.IR dpyupdate . XReturns nonzero if the coordinates are illegal. X X.I Dpyhome Xmoves the current write location to the top left corner of the window. XThis function is useful between updates if your program iteratively Xrewrites the whole screen as one window. X X.I Dpygetrow Xreturns the row number of the current write location. XThis is the row number where the next character written would go. XIf the next character written would not fit in the window, -1 is returned. XThis number is relative to the first line of the current window. XFor example, if the current write location is at the beginning of Xthe top line of the window, this function returns zero. X X.I Dpygetcol Xreturns the column number of the current write location. XThis is the column number where is next character written would go. XIf the next character written would not fit in the window, -1 is returned. XThis number is relative to the current window. XFor example, if the current write location is at the beginning of a line Xin the window, this function returns zero. X X.I Dpyredraw Xredraws the screen to make it look like the current screen image. XThis is used to fix the screen when it becomes trashed due to glitches or Xother programs also writing to the screen. XThis does not change the current or future screen images. X X.I Dpystop Xsuspends execution of the process in a nice way by homing down to the lower Xleft corner of the terminal screen, clearing the last line of the screen, Xrestoring the original terminal modes, and then stopping the process. XIf the process is continued, terminal modes are restored, Xthe screen is redrawn, and execution proceeds. XThis is called automatically when the terminal's stop character (usually ^Z) Xis typed by the user. X.I Dpystop Xis a null routine for non-BSD systems. X X.I Dpyplace Xplaces the character X.I ch Xwithin the current window at the coordinates specified by X.I row Xand X.IR col . XThe character should not be a control character. XThe coordinates can be negative to measure from the last row or column Xof the window. XThe current write location is unchanged. XLike X.I dpywrite Xand similar routines, this routine only affects the Xfuture screen image, and does no terminal I/O. XReturns nonzero if the coordinates are illegal. X X.I Dpyget XReturns the character from the current window which is at the coordinates Xspecified by X.I row Xand X.IR col. XThe coordinates can be negative to measure from the last row or column of Xthe window. XThe character returned is from the future screen image, not the current Xscreen image. XThe current write location is unchanged. XReturns negative if the coordinates are illegal. X X.I Dpyread Xreads input from the user while showing the input Xdata on the screen. XEditing of the input and updating of the screen is automatically Xperformed by X.IR dpy . XThe entire current window is used to display the input, and therefore Xyou must set the window to your desired input location before calling X.IR dpyread . XTypically, you specify the window to be a single line at the top or bottom Xof the screen. XIf the X.I prompt Xstring pointer is not NULL, then the prompt string will appear at the Xbeginning of the window, followed by the data typed by the user. XTo display the user's input without any prompt, specify a pointer to a Xnull string. XIf X.I prompt Xis NULL, then the window will be untouched and no terminal I/O at all will Xbe performed (useful when input is from a script or file). X.I Buf Xand X.I count Xspecify the area in the calling program where the Xdata being read is stored, in the manner of X.IR read (2). XThe data will be what was typed by the Xuser, not what is seen on the screen (i.e. control characters appear Xon the screen as ^X, but appear in the buffer as themselves). XIf more data is typed than fits in the window, the data in the window Xis automatically scrolled to keep the current input location visible. X.I Routine Xis a function variable which specifies a routine which is called to Xprovide the input characters for X.IR dpyread . X.I Routine Xis called with the previous character read (-1 on the first call). XIt must return the next character read, or -1 to end input and cause X.I dpyread Xto return. XProviding the previous character as an argument allows a routine to easily Xreturn a break character as input, and then end the input on the next call. XIf X.I routine Xis 0, then a default routine will be used which reads from the standard input Xuntil an end of file or newline is typed (which is included in the buffer). XWhenever the character count would be exceeded, then X.I dpyread Xwill warn the user with a bell and discard the input character. X.I Dpyread Xreturns the number of characters read into the buffer, which is not Xguaranteed to contain a terminating null or newline character. X.SH "TUTORIAL" XThe routines in the X.I dpy Xlibrary are called directly by the user program. XNone of these routines are a macro, so that there is no need to include a Xheader file to use X.IR dpy . XThese routines use the X.I termlib X(or X.I curses Xunder System V) library routines to obtain the proper terminal escape sequences. XTherefore, you load your program as in the following examples: X.nf X X cc -o yourprog yourprog.c -ldpy -ltermlib for BSD Xor: X cc -o yourprog yourprog.c -ldpy -lcurses for System V X X.fi X.I Dpy Xkeeps two arrays which hold images of the terminal screen. XThe first array (the "current screen") is a copy of what the terminal Xscreen really looks like. XThe second array (the "future screen") is a copy of what the Xcalling program wants the screen to look like. XThe use of X.I dpy Xproceeds in two phases under the control of the calling program, as follows: X XIn the first phase, only the future screen is manipulated. XThe calling program positions the "current write location" as desired Xwithin the future screen, and writes new information within it. XThe X.IR dpywrite , X.IR dpychar , X.IR dpystr , X.IR dpyprintf , Xand X.I dpyplace Xroutines are used for this purpose. XDuring this phase, no actual I/O occurs and the terminal screen remains Xunchanged. X XIn the second phase, the calling program uses the X.I dpyupdate Xroutine to update the screen. X.I Dpy Xcompares the future screen contents with the current screen contents, Xand does whatever terminal I/O is required in order to make the current Xscreen look like the future screen. XAfter this is done, the two screen images are identical. XIn addition, the terminal's cursor is positioned to the current write position. X XThe calling program usually uses X.I dpy Xby looping between the above two phases. XIt defines what the screen should look like, updates the screen, Xdefines the screen again, updates it again, and so on. XIn doing so, the program can be "dumb" or "smart". XA dumb program rewrites all of the data in its windows each iteration of Xthe loop, and depends on X.I dpy Xto prevent terminal I/O for unchanging data. XThus a dumb program can be very trivial, and doesn't have to know anything Xabout what is happening on the screen. X XIf generating a new screenful of data from scratch is too much work for Xthe program to do for each iteration, then a good compromise is to keep an Xinternal copy of the screen in the program, update that copy appropriately, Xand then execute one X.I dpywrite Xcall to give X.I dpy Xthe new data. X XA smart program knows the exact locations of the desired screen changes Xeach iteration of the loop, and only rewrites the necessary locations Xby using appropriate X.I dpymove Xand X.I dpyplace Xcalls. XThis runs faster than a dumb program, but has the disadvantage of Xintroducing complexity and possible bugs into the program. X XPutting data into the future screen is much like writing to a real terminal. XThere is a "current write location", which is similar to the cursor of the Xterminal. XLike a terminal, characters written to X.I dpy Xappear at the current write location, and automatically advance its location. XWhen the rightmost location on a line is reached, the current write location Xis automatically moved to the leftmost location on the next line. X XPrinting characters are stored as is, and will later be visible. XBut control characters have special effects like on a terminal. XIn particular, linefeed moves to the beginning of the next line, return Xmoves back to the beginning of the current line, tab moves to the next Xtab stop as if the corresponding number of spaces were given, and backspace Xbacks up by one location. XOther control characters appear in ^X format. X XWriting to the future screen differs from writing to most real terminals Xin a couple of ways. XFirstly, scrolling does not occur. XIf the end of the screen is reached, any further characters are ignored. XThe X.I dpyread Xcall is an exception, and does provide for scrolling. X XSecondly, it is possible to limit output to a X.IR window, Xwhich is a rectangle of any size on the screen. XThe location and size of a window is specified by the program when it wants to Xlimit output to a rectangle. XThis window acts just like a regular terminal screen of the appropriate size. XFurthermore, coordinates are relative to the window's upper left corner, Xso a routine which writes in the window does not need to know where it is. XData in the future screen which lies outside of the window is untouched, Xno matter what is done within the window. X XTypically, a program divides the screen up into several windows Xwhich do not overlap. XData can then be written to each window independently, Xwithout regard to where each window is. XFor example, a linefeed character moves to the beginning of the next line in Xthe current window, instead of to the beginning of the next line of the screen. XMultiple writes to the same location do not cause any problems. XTherefore, when windows do overlap and then X.I dpyupdate Xis called, each screen location just displays the character which was Xlast written there. X XFinal hints: X XA window can be filled with a background character by simply writing that Xcharacter to the window until a nonzero return value is obtained, meaning Xthe window is full. X XIf a region of the screen is never changed (such as a help text), then that Xregion should be in its own window. XThen it only needs to be written once. X XThe terminal size can be found after calling X.I dpyinit Xby calling X.nf X dpymove(-1, -1); X.fi Xto move to the lower right corner of the screen, and then calling X.I Xdpygetrow Xand X.I dpygetcol Xto return the row and column numbers. X XWhile writing data to the window, X.I dpygetrow Xand X.I dpygetcol Xare useful in order to Xremember the location of a particular position in the window. XWhen all of the data has been written, then X.I dpymove Xcan be used to position the cursor back to that location. XIn this way, you don't have to worry about line wrapping or control character Xexpansions when computing how to position the cursor on a particular Xcharacter of your data. X.SH AUTHOR XDavid I. Bell //E*O*F dpy.3// echo x - dpy.doc sed -e 's/^X//' > "dpy.doc" << '//E*O*F dpy.doc//' X X X XDPY(3) UNIX Programmer's Manual DPY(3) X X X XNAME X dpy - new screen updating routines X XSYNOPSIS X dpyinit(ttytype, modestring) X char *ttytype, *modestring; X X dpywindow(minrow, maxrow, mincol, maxcol) X int minrow, maxrow, mincol, maxcol; X X dpyread(prompt, routine, buf, count) X char *prompt; X int (*routine)(); X char *buf; X int count; X X dpymove(row, col) X int row, col; X X dpyplace(row, col, ch) X int row, col; X char ch; X X dpywrite(buf, count) X char *buf; X int count; X X dpyprintf(fmt [,args] ...) X char *fmt; X X dpychar(ch) X char ch; X X dpystr(str) X char *str; X X dpyget(row, col) X int row, col; X X dpyclrline() X X dpyclrwindow() X X dpyhome() X X dpygetrow() X X dpygetcol() X X dpyupdate() X X dpyredraw() X X X XPrinted 3/7/85 7 March 1985 1 X X X X X X XDPY(3) UNIX Programmer's Manual DPY(3) X X X X dpystop() X X dpyclose() X XDESCRIPTION X _D_p_y is a terminal display package much like _c_u_r_s_e_s(3). How- X ever, _d_p_y does not provide all of the capabilities of X _c_u_r_s_e_s, but instead tries to focus on the following two X goals: X X 1. Allow the programmer to easily define and update many X different rectangles of data on the screen at the same X time. X X 2. Be as fast as possible. X X A tutorial on the usage of _d_p_y appears later in this docu- X ment. The remainder of this section describes the pro- X cedures. X X _D_p_y_i_n_i_t must be called before any other call to _d_p_y (_e_x_c_e_p_t X _f_o_r _d_p_y_c_l_o_s_e). It allocates memory for two screen images, X defines the current window to be the whole screen, sets the X current write location to the upper left corner of the X screen, uses _s_i_g_n_a_l(2) to cause the terminal stop character X to trap to _d_p_y_s_t_o_p for pretty program stopping (only on BSD X systems), and sets the terminal modes to allow for terminal X input of various kinds. The actual terminal screen is not X cleared until the first _d_p_y_u_p_d_a_t_e call is made, so that you X can initialize your program based upon the terminal size X before deciding to continue. _T_t_y_t_y_p_e is a string specifying X the terminal type (example: "vt100"), or NULL to use the X value specified by the _T_E_R_M environment variable. _M_o_d_e_- X _s_t_r_i_n_g is a string specifying how input is to be treated X from the terminal. Each mode is specified by a single X letter, preceeded by an (optional) plus sign to enable the X mode, or preceeded by a minus sign to disable the mode. X Modes can be separated by spaces. Modes not mentioned in X the string are unchanged. The currently defined mode X letters are: X X e (echo) Echoing of input characters occurs. X X c (cbreak) Characters are returned without waiting for a X newline and tty signals are processed. X X r (raw) Characters are returned exactly as typed and tty X signals are disabled. X X Thus the normal terminal modes before starting _d_p_y are X described by the string "e -c -r". If _m_o_d_e_s_t_r_i_n_g is a NULL X pointer, then the default modes of "-e c" are used. If the X X X XPrinted 3/7/85 7 March 1985 2 X X X X X X XDPY(3) UNIX Programmer's Manual DPY(3) X X X X _d_p_y_r_e_a_d call is to be used in your program, then you must X specify that echoing is disabled, and that either cbreak or X raw mode is enabled. _D_p_y_i_n_i_t returns nonzero with an error X message typed if it cannot initialize. X X _D_p_y_c_l_o_s_e homes down to the lower left corner of the terminal X screen, clears the last line of the screen, frees the memory X allocated by _d_p_y_i_n_i_t, and restores the original terminal X modes. This is useful just before exiting from your pro- X gram. _D_p_y_c_l_o_s_e is guaranteed to do nothing if _d_p_y_i_n_i_t has X not yet been completed, so that it is safe to call _d_p_y_c_l_o_s_e X at any time. X X _D_p_y_u_p_d_a_t_e makes the terminal screen look like the future X screen image, using a minimal amount of terminal I/O. The X cursor is also positioned to the current write location. X This routine must be called when you have completed your X writing of data to the future screen image, in order to make X those changes visible to the user. X X _D_p_y_w_i_n_d_o_w specifies the rectangle where characters will be X placed in the future screen image, and sets the current X write location to the top left corner of the rectangle. The X upper left corner of the window has the coordinates speci- X fied by _m_i_n_r_o_w and _m_i_n_c_o_l, and the lower right corner has X the coordinates specified by _m_a_x_r_o_w and _m_a_x_c_o_l. These coor- X dinates are the absolute screen coordinates, where the upper X left corner of the screen is row 0 and column 0. Negative X numbers specify row or column numbers from the bottom or X right edges of the screen. For example, X dpywindow(0, -1, 0, -1); X defines a window which fills the whole screen. Returns X nonzero if the coordinates are illegal. X X _D_p_y_w_r_i_t_e writes _c_o_u_n_t characters from location _b_u_f to the X future screen image at the current write location in the X current window, and updates the current write location X appropriately. This call does not do any actual I/O to the X terminal. Control characters are handled reasonably, as is X running off the end of a line or the window. This routine X is called by _d_p_y_c_h_a_r, _d_p_y_s_t_r, and _d_p_y_p_r_i_n_t_f, and is there- X fore the most efficient way to give characters to _d_p_y. X Returns nonzero if not all the characters fit in the window. X X _D_p_y_c_h_a_r writes the single character _c_h to the future screen X image. Returns nonzero if the character couldn't fit in the X window. X X _D_p_y_s_t_r writes the null terminated string _s_t_r to the future X screen image. Returns nonzero if any of the string couldn't X fit in the window. X X X X XPrinted 3/7/85 7 March 1985 3 X X X X X X XDPY(3) UNIX Programmer's Manual DPY(3) X X X X _D_p_y_p_r_i_n_t_f writes a formated string to the future screen X image in the manner of _p_r_i_n_t_f(3). _F_m_t is the format string, X and _a_r_g_s are arguments to the format string. Returns X nonzero if any of the string couldn't fit in the window. X X _D_p_y_c_l_r_l_i_n_e clears the rest of the line in the future screen X image (by changing the characters to spaces), but does not X change the current write location. Writing a linefeed to X the future screen performs this function, in addition to X moving the write location to the next line. X X _D_p_y_c_l_r_w_i_n_d_o_w clears the rest of the window in the future X screen image, but does not change the current write loca- X tion. When rewriting a window completely, this should be X called when done so that any old contents of the window will X be sure to be cleared out. X X _D_p_y_m_o_v_e changes the current write location to the specified X _r_o_w and _c_o_l_u_m_n numbers, relative to the upper left corner of X the current window. The upper left corner of the window is X row 0 and column 0. Negative numbers measure from the last X row or column of the window. For example, X dpymove(-1, 0); X positions to the beginning of the last line of the window. X This does not set the actual terminal's cursor location X unless it is also followed by a call to _d_p_y_u_p_d_a_t_e. Returns X nonzero if the coordinates are illegal. X X _D_p_y_h_o_m_e moves the current write location to the top left X corner of the window. This function is useful between X updates if your program iteratively rewrites the whole X screen as one window. X X _D_p_y_g_e_t_r_o_w returns the row number of the current write loca- X tion. This is the row number where the next character writ- X ten would go. If the next character written would not fit X in the window, -1 is returned. This number is relative to X the first line of the current window. For example, if the X current write location is at the beginning of the top line X of the window, this function returns zero. X X _D_p_y_g_e_t_c_o_l returns the column number of the current write X location. This is the column number where is next character X written would go. If the next character written would not X fit in the window, -1 is returned. This number is relative X to the current window. For example, if the current write X location is at the beginning of a line in the window, this X function returns zero. X X _D_p_y_r_e_d_r_a_w redraws the screen to make it look like the X current screen image. This is used to fix the screen when X it becomes trashed due to glitches or other programs also X X X XPrinted 3/7/85 7 March 1985 4 X X X X X X XDPY(3) UNIX Programmer's Manual DPY(3) X X X X writing to the screen. This does not change the current or X future screen images. X X _D_p_y_s_t_o_p suspends execution of the process in a nice way by X homing down to the lower left corner of the terminal screen, X clearing the last line of the screen, restoring the original X terminal modes, and then stopping the process. If the pro- X cess is continued, terminal modes are restored, the screen X is redrawn, and execution proceeds. This is called automat- X ically when the terminal's stop character (usually ^Z) is X typed by the user. _D_p_y_s_t_o_p is a null routine for non-BSD X systems. X X _D_p_y_p_l_a_c_e places the character _c_h within the current window X at the coordinates specified by _r_o_w and _c_o_l. The character X should not be a control character. The coordinates can be X negative to measure from the last row or column of the win- X dow. The current write location is unchanged. Like X _d_p_y_w_r_i_t_e and similar routines, this routine only affects the X future screen image, and does no terminal I/O. Returns X nonzero if the coordinates are illegal. X X _D_p_y_g_e_t Returns the character from the current window which X is at the coordinates specified by _r_o_w and _c_o_l. The coordi- X nates can be negative to measure from the last row or column X of the window. The character returned is from the future X screen image, not the current screen image. The current X write location is unchanged. Returns negative if the coor- X dinates are illegal. X X _D_p_y_r_e_a_d reads input from the user while showing the input X data on the screen. Editing of the input and updating of X the screen is automatically performed by _d_p_y. The entire X current window is used to display the input, and therefore X you must set the window to your desired input location X before calling _d_p_y_r_e_a_d. Typically, you specify the window X to be a single line at the top or bottom of the screen. If X the _p_r_o_m_p_t string pointer is not NULL, then the prompt X string will appear at the beginning of the window, followed X by the data typed by the user. To display the user's input X without any prompt, specify a pointer to a null string. If X _p_r_o_m_p_t is NULL, then the window will be untouched and no X terminal I/O at all will be performed (useful when input is X from a script or file). _B_u_f and _c_o_u_n_t specify the area in X the calling program where the data being read is stored, in X the manner of _r_e_a_d(2). The data will be what was typed by X the user, not what is seen on the screen (i.e. control char- X acters appear on the screen as ^X, but appear in the buffer X as themselves). If more data is typed than fits in the win- X dow, the data in the window is automatically scrolled to X keep the current input location visible. _R_o_u_t_i_n_e is a func- X tion variable which specifies a routine which is called to X X X XPrinted 3/7/85 7 March 1985 5 X X X X X X XDPY(3) UNIX Programmer's Manual DPY(3) X X X X provide the input characters for _d_p_y_r_e_a_d. _R_o_u_t_i_n_e is called X with the previous character read (-1 on the first call). It X must return the next character read, or -1 to end input and X cause _d_p_y_r_e_a_d to return. Providing the previous character X as an argument allows a routine to easily return a break X character as input, and then end the input on the next call. X If _r_o_u_t_i_n_e is 0, then a default routine will be used which X reads from the standard input until an end of file or new- X line is typed (which is included in the buffer). Whenever X the character count would be exceeded, then _d_p_y_r_e_a_d will X warn the user with a bell and discard the input character. X _D_p_y_r_e_a_d returns the number of characters read into the X buffer, which is not guaranteed to contain a terminating X null or newline character. X XTUTORIAL X The routines in the _d_p_y library are called directly by the X user program. None of these routines are a macro, so that X there is no need to include a header file to use _d_p_y. These X routines use the _t_e_r_m_l_i_b (or _c_u_r_s_e_s under System V) library X routines to obtain the proper terminal escape sequences. X Therefore, you load your program as in the following exam- X ples: X X cc -o yourprog yourprog.c -ldpy -ltermlib for BSD X or: X cc -o yourprog yourprog.c -ldpy -lcurses for System V X X _D_p_y keeps two arrays which hold images of the terminal X screen. The first array (the "current screen") is a copy of X what the terminal screen really looks like. The second X array (the "future screen") is a copy of what the calling X program wants the screen to look like. The use of _d_p_y X proceeds in two phases under the control of the calling pro- X gram, as follows: X X In the first phase, only the future screen is manipulated. X The calling program positions the "current write location" X as desired within the future screen, and writes new informa- X tion within it. The _d_p_y_w_r_i_t_e, _d_p_y_c_h_a_r, _d_p_y_s_t_r, _d_p_y_p_r_i_n_t_f, X and _d_p_y_p_l_a_c_e routines are used for this purpose. During X this phase, no actual I/O occurs and the terminal screen X remains unchanged. X X In the second phase, the calling program uses the _d_p_y_u_p_d_a_t_e X routine to update the screen. _D_p_y compares the future X screen contents with the current screen contents, and does X whatever terminal I/O is required in order to make the X current screen look like the future screen. After this is X done, the two screen images are identical. In addition, the X terminal's cursor is positioned to the current write posi- X tion. X X X XPrinted 3/7/85 7 March 1985 6 X X X X X X XDPY(3) UNIX Programmer's Manual DPY(3) X X X X The calling program usually uses _d_p_y by looping between the X above two phases. It defines what the screen should look X like, updates the screen, defines the screen again, updates X it again, and so on. In doing so, the program can be "dumb" X or "smart". A dumb program rewrites all of the data in its X windows each iteration of the loop, and depends on _d_p_y to X prevent terminal I/O for unchanging data. Thus a dumb pro- X gram can be very trivial, and doesn't have to know anything X about what is happening on the screen. X X If generating a new screenful of data from scratch is too X much work for the program to do for each iteration, then a X good compromise is to keep an internal copy of the screen in X the program, update that copy appropriately, and then exe- X cute one _d_p_y_w_r_i_t_e call to give _d_p_y the new data. X X A smart program knows the exact locations of the desired X screen changes each iteration of the loop, and only rewrites X the necessary locations by using appropriate _d_p_y_m_o_v_e and X _d_p_y_p_l_a_c_e calls. This runs faster than a dumb program, but X has the disadvantage of introducing complexity and possible X bugs into the program. X X Putting data into the future screen is much like writing to X a real terminal. There is a "current write location", which X is similar to the cursor of the terminal. Like a terminal, X characters written to _d_p_y appear at the current write loca- X tion, and automatically advance its location. When the X rightmost location on a line is reached, the current write X location is automatically moved to the leftmost location on X the next line. X X Printing characters are stored as is, and will later be X visible. But control characters have special effects like X on a terminal. In particular, linefeed moves to the begin- X ning of the next line, return moves back to the beginning of X the current line, tab moves to the next tab stop as if the X corresponding number of spaces were given, and backspace X backs up by one location. Other control characters appear X in ^X format. X X Writing to the future screen differs from writing to most X real terminals in a couple of ways. Firstly, scrolling does X not occur. If the end of the screen is reached, any further X characters are ignored. The _d_p_y_r_e_a_d call is an exception, X and does provide for scrolling. X X Secondly, it is possible to limit output to a _w_i_n_d_o_w, which X is a rectangle of any size on the screen. The location and X size of a window is specified by the program when it wants X to limit output to a rectangle. This window acts just like X a regular terminal screen of the appropriate size. X X X XPrinted 3/7/85 7 March 1985 7 X X X X X X XDPY(3) UNIX Programmer's Manual DPY(3) X X X X Furthermore, coordinates are relative to the window's upper X left corner, so a routine which writes in the window does X not need to know where it is. Data in the future screen X which lies outside of the window is untouched, no matter X what is done within the window. X X Typically, a program divides the screen up into several win- X dows which do not overlap. Data can then be written to each X window independently, without regard to where each window X is. For example, a linefeed character moves to the begin- X ning of the next line in the current window, instead of to X the beginning of the next line of the screen. Multiple X writes to the same location do not cause any problems. X Therefore, when windows do overlap and then _d_p_y_u_p_d_a_t_e is X called, each screen location just displays the character X which was last written there. X X Final hints: X X A window can be filled with a background character by simply X writing that character to the window until a nonzero return X value is obtained, meaning the window is full. X X If a region of the screen is never changed (such as a help X text), then that region should be in its own window. Then X it only needs to be written once. X X The terminal size can be found after calling _d_p_y_i_n_i_t by cal- X ling X dpymove(-1, -1); X to move to the lower right corner of the screen, and then X calling _d_p_y_g_e_t_r_o_w and _d_p_y_g_e_t_c_o_l to return the row and column X numbers. X X While writing data to the window, _d_p_y_g_e_t_r_o_w and _d_p_y_g_e_t_c_o_l X are useful in order to remember the location of a particular X position in the window. When all of the data has been writ- X ten, then _d_p_y_m_o_v_e can be used to position the cursor back to X that location. In this way, you don't have to worry about X line wrapping or control character expansions when computing X how to position the cursor on a particular character of your X data. X XAUTHOR X David I. Bell X X X X X X X X X X XPrinted 3/7/85 7 March 1985 8 X X X //E*O*F dpy.doc// echo done
yhe@ornl-msr (Young Etheridge) (03/22/85)
Am experiencing what seems to be a cursor settling problem with dpy when in the noecho-raw initialization mode. Data in some windows on a screen do not appear in the correct location if they appear at all. The same software initialized to noecho-cbreak work as required. My application requires that I be in the raw mode. yhe@ornl-msr