4.3BSD-UWisc/man/cat3/xtext.3x

XTEXT(3X)           UNIX Programmer's Manual            XTEXT(3X)



NAME
     Xtext - routines to provide simple text output windows

SYNOPSIS
     #include <X/Xtext.h>

     TextWindow *TextCreate(width, height, x, y, parent,
          fontname, bwidth, fgpixel, bgpixel,
          bordercolor, fastscroll);
     int height, width, x, y, bwidth, fgpixel, bgpixel,
     fastscroll;
     Window parent;
     char *fontname;
     Pixmap bordercolor;

     TextDestroy(t);
     TextWindow *t;

     TextClear(t);
     TextWindow *t;

     TextRedisplay(t);
     TextWindow *t;

     int TextEvent(t, e);
     TextWindow *t;
     XEvent *e;

     TextPutString(t, str);
     TextWindow *t;
     char *str;

     TextPutChar(t, ch);
     TextWindow *t;
     char ch;

     TextPrintf(t, format [ , arg ] ... )
     TextWindow *t;
     char *format;

     TextFlush(t);
     TextWindow *t;

DESCRIPTION
     These functions provide a simple interface to text output
     windows.

     _T_e_x_t_C_r_e_a_t_e creates a window that is _w_i_d_t_h characters wide
     and _h_e_i_g_h_t characters high.  It is located with its upper
     left hand corner located at the point _x, _y in the window
     _p_a_r_e_n_t. The foreground (i.e. the characters) is in the color
     _f_g_p_i_x_e_l and the background is the color _b_g_p_i_x_e_l. The border



Printed 1/10/87           April 10 1986                         1






XTEXT(3X)           UNIX Programmer's Manual            XTEXT(3X)



     is _b_w_i_d_t_h pixels wide and filled with the Pixmap _b_o_r_d_e_r_-
     _c_o_l_o_r. If _f_a_s_t_s_c_r_o_l_l is nonzero, text containing multiple
     newlines is displayed with a single jump scroll rather than
     with a single scroll for each newline.

     The structure _T_e_x_t_W_i_n_d_o_w is defined in
     /_u_s_r/_i_n_c_l_u_d_e/_X/_X_t_e_x_t._h.  The only field that should be of
     interest to most applications is _w, the X Window id of the
     created window.  This is quite useful if the application
     wishes to map the created window.

     _T_e_x_t_D_e_s_t_r_o_y destroys the window described by its argument.
     The window is also destroyed automatically if the process
     creating it is terminated.

     _T_e_x_t_C_l_e_a_r clears the window described by its argument.

     _T_e_x_t_R_e_d_i_s_p_l_a_y redisplays the window described by its argu-
     ment.  If the argument is NULL, all active text windows are
     redisplayed.

     _T_e_x_t_E_v_e_n_t handles the event passed to it.  It returns 0 if
     it was an event the library knows how to deal with, and 1 if
     it was an event of an unknown type; the latter should only
     happen if the application has changed the event mask for the
     window.  Any event that the application receives that has as
     its _w_i_n_d_o_w the window id of the text window should be passed
     to _T_e_x_t_E_v_e_n_t for handling.  Scrolling text generates an
     event per line of events, so the application should check
     for them frequently.  An alternative routine, _T_e_x_t_F_l_u_s_h, can
     be used to handle all outstanding events for all active text
     windows.

     _T_e_x_t_P_u_t_S_t_r_i_n_g prints its string in its window.  The charac-
     ter '\n' (newline) is treated specially, and any other char-
     acter is taken from the font.  If the string contains multi-
     ple newlines, a single scroll is done for each line unless
     the _f_a_s_t_s_c_r_o_l_l argument was non-zero in the call to
     _T_e_x_t_C_r_e_a_t_e.

     _T_e_x_t_P_u_t_C_h_a_r is similar to _T_e_x_t_P_u_t_S_t_r_i_n_g but only prints a
     single character.  Again, newline is treated specially.

     _T_e_x_t_P_r_i_n_t_f is similar to the standard function _p_r_i_n_t_f except
     that it prints its result in the specified window.  The
     resulting string is passed to _T_e_x_t_P_u_t_S_t_r_i_n_g. See also the
     BUGS section at the end of this page.

     _T_e_x_t_F_l_u_s_h is analogous to the stdio function _f_f_l_u_s_h in that
     it causes all outstanding output requests to be flushed to
     the specified window.  If the argument is NULL, all windows
     are flushed.  For novice X developers, this routine



Printed 1/10/87           April 10 1986                         2






XTEXT(3X)           UNIX Programmer's Manual            XTEXT(3X)



     eliminates the need for event handling from X applications.

SEE ALSO
     printf(3S), xterm(1), X(8C)

AUTHORS
     Paul Asente, Stanford University; Mark Colan, MIT Project
     Athena/IBM

BUGS
     _T_e_x_t_P_r_i_n_t_f will truncate the output if the resulting string
     is more than 2048 characters long.

     Since X operates asynchronously, it is possible to get way
     ahead of the server.  This means that it may be quite a
     while between when a scroll happens on the screen and when
     _X_t_e_x_t gets around to filling in areas that couldn't be
     scrolled normally.  This should only happen if the applica-
     tion issues a great many output requests very quickly, or if
     it doesn't get around to receiving the events _X_t_e_x_t needs to
     fill these areas in.  Also, some strange TCP bugs are
     invoked if an application which has gotten far ahead of the
     X server is stopped (as with a control-Z).
































Printed 1/10/87           April 10 1986                         3