home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / haswinlib / info / text < prev    next >
Encoding:
Text File  |  1991-02-04  |  12.4 KB  |  248 lines
  1.  
  2.                       The HASWIN window library.
  3.                      ===========================
  4.                       Copyright H.A. Shaw 1990.
  5.                      ===========================
  6.  
  7. Drawing text in windows under the HASWIN system.
  8. -------------------------------------------------
  9.         HASWIN provides a simple text overlay for windows.  HASWIN maintains
  10. a 2-D grid of character cells that are overlayed over the window and redrawn
  11. automatically by HASWIN.  The text overlay may be larger or smaller than the
  12. window itself but the top left character is always aligned with the top left
  13. corner of the window work area.  The top left corner of the text overlay has position 0,0 and axes are counted right positive and down positive.
  14. Routines are provided to insert and delete characters and lines and move the
  15. text cursor.  It is also possible to determine various characteristics of
  16. the text overlay, such as its size and the position of the text cursor.  A
  17. VDU stream-like interface is provided.
  18.  
  19.         A text overlay is made from the following structure.  Routines are
  20. provided for all access to the structure and it should NEVER need to be used
  21. directly in user programs.
  22.  
  23. typedef struct text {
  24.         char            *text;       /* pointer to character data area     */
  25.         int             xsize,ysize; /* X and Y sizes of data area         */
  26.         int             xposn,yposn; /* cursor is before this position.    */
  27.         char            fcol, bcol;  /* foreground and background colours. */
  28. } text;
  29.  
  30.         The following routines are provided to create text overlays and
  31. manipulate them.  The simplest way to create a text overlay for a window is
  32. to set the WINDOW_AUTOTEXT flag for a window when it is created with the
  33. haswin_make{pane/slide}window() routines.  See later for what the
  34. WINDOW_AUTOTEXT flag causes HASWIN to do after window creation.
  35.  
  36. int     haswin_maketextoverlay(window *win, int x, int y, char f, char b);
  37.         - This routine creates a text overlay of size "x" by "y" in the
  38.           window "win".  "f" is the foreground and "b" the background colour
  39.           for the overlay.  If a caret does not already exist in the window
  40.           one is created for it so that text may be inserted automatically
  41.           by the user.
  42.         - If a text area already exists in the window "win" then it is
  43.           altered to reflect the new size, and any existing characters are
  44.           copied.  If either "x" or "y" are 0 on entry then the existing
  45.           text area is not altered in that axis.
  46.         - Returns HASWIN_TRUE if successful, or HASWIN_FALSE on any error.
  47.  
  48. text    *haswin_textmakearea(text *txt, int x, int y, char f, char b);
  49.         - This routine creates a text overlay of size "x" by "y" and returns
  50.           a pointer to it.  "f" is the foreground and "b" the background
  51.           colour for the overlay.
  52.         - If the text area "txt" is non-zero then it is altered to reflect
  53.           the new size, and any existing characters are copied.  If either
  54.           "x" or "y" are 0 on entry then the existing text area is not
  55.           altered in that axis.
  56.         - Returns a pointer to the new text area, or 0 on any error.
  57.  
  58. int     haswin_textredraw(window *win, int x0, int x1, int y0, int y1);
  59.         - Force the text overlay between the character positions "x0","y0"
  60.           and "x1","y1" for the window "win" to be redrawn.
  61.  
  62. int     haswin_textvdu(window *win, char ch)
  63.         - Send the character "ch" along the VDU like stream for the window
  64.           "win".  The characters understood by the VDU stream are listed
  65.           below.
  66.         - Returns HASWIN_TRUE if successful, or HASWIN_FALSE on any error.
  67.  
  68.         character      action
  69.           ^@   0        NULL
  70.           ^G   7        ring the bell
  71.           ^H   8        move left  (stops at left edge)
  72.           ^I   9        move right  (wraps to next line, stops at bottom)
  73.           ^J  10        move down  (bottom wraps to top)
  74.           ^K  11        move up  (top wraps to bottom)
  75.           ^L  12        clear text  (move cursor to top left)
  76.           ^M  13        move to begining of next line (can scroll)
  77.           ^N  14        insert character
  78.           ^O  15        insert line
  79.           ^P  16        delete character
  80.           ^Q  17        delete line
  81.           ^R  18        scroll left
  82.           ^S  19        scroll right
  83.           ^T  20        scroll down
  84.           ^U  21        scroll up
  85.           ^*  30        move cursor to top left.
  86.        <sp>-~ 32-126    character added to text (wraps to next line, scrolls)
  87.           ^?  127       delete character and move left (stops at left edge)
  88.         Unknown characters are ignored.  New characters added to the text
  89.         overwrite those that are already in the text overlay.  The text
  90.         overlay is automatically updated.  The characters that scroll off the
  91.         top, bottom or sides of the text overlay are lost.
  92.  
  93. int     haswin_textdeletechar(window *win, int x, int y);
  94.         - delete the character at the position "x", "y" in window "win" and
  95.           move the rest of the characters in the line to take up the space.
  96.           A space character is added to the end of the line.
  97.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  98.  
  99. int     haswin_textdeleteline(window *win, int y);
  100.         - delete line "y" in window "win" and move the rest of the lines in
  101.           the text overlay to take up the space.
  102.           A blank line is added to the end of the text overlay.
  103.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  104.  
  105. int     haswin_textinsertchar(window *win, int x, int y);
  106.         - insert a space character at the position "x", "y" in window "win"
  107.           and move the rest of the characters in the line to give the space.
  108.           The last character on the line is lost.
  109.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  110.  
  111. int     haswin_textinsertline(window *win, int y);
  112.         - insert a blank line "y" in window "win" and move the rest of the
  113.           text overlay to give the space.  The last line in the text overlay
  114.           is lost.
  115.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  116.  
  117. int     haswin_textscrolldown(window *win);
  118.         - move all the characters in the text overlay down one line.  The
  119.           last line is lost, and a blank line is created at the top of the
  120.           text overlay.
  121.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  122.  
  123. int     haswin_textscrollup(window *win);
  124.         - move all the characters in the text overlay up one line.  The
  125.           first line is lost, and a blank line is created at the bottom of
  126.           the text overlay.
  127.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  128.  
  129. int     haswin_textscrollright(window *win);
  130.         - move all the characters in the text overlay right one character.
  131.           The last character of each line is lost, and a blank character is
  132.           created at the left end of each line.
  133.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  134.  
  135. int     haswin_textscrollleft(window *win);
  136.         - move all the characters in the text overlay left one character.
  137.           The first character of each line is lost, and a blank character is
  138.           created at the right end of each line.
  139.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  140.  
  141. int     haswin_textgetchar(window *win, int x, int y);
  142.         - returns the character at the position "x", "y" in the text overlay
  143.           of the window "win", or HASWIN_UNKNOWN if no character can be
  144.           found.
  145.  
  146. int     haswin_textmove(window *win, int x, int y);
  147.         - move the text cursor for the window "win" to the position "x", "y"
  148.           in the text overlay.
  149.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  150.  
  151. int     haswin_textprintf(window *win, const char *fmt, ...);
  152.         - Use vsprintf() to process the string "fmt" and the following
  153.           arguments and then call haswin_textvdu() on the string.  Note that
  154.           \n means move vertically down one line, and \r means move down to
  155.           the beginning of the next line.
  156.         - returns the number of characters sent to the VDU stream for the
  157.           window, or HASWIN_FALSE on any error.
  158.  
  159. int     haswin_textgetxposn(window *win);
  160.         - return the X coordinate of the text cursor position for the window
  161.           "win", or HASWIN_UNKNOWN on any error.
  162.  
  163. int     haswin_textgetyposn(window *win);
  164.         - return the Y coordinate of the text cursor position for the window
  165.           "win", or HASWIN_UNKNOWN on any error.
  166.  
  167. int     haswin_textgetxsize(window *win);
  168.         - return the X size of the text cursor position for the window "win"
  169.           or HASWIN_UNKNOWN on any error.
  170.  
  171. int     haswin_textgetysize(window *win);
  172.         - return the Y size of the text cursor position for the window "win"
  173.           or HASWIN_UNKNOWN on any error.
  174.  
  175. int     haswin_converttxtxtowin(window *win, int x);
  176.         - This routine returns the X window offset for the window "win" of
  177.           the left hand edge of the character position nearest to the
  178.           position "x" in the window "win".
  179.         - returns HASWIN_UNKNOWN on any error.
  180.  
  181. int     haswin_converttxtytowin(window *win, int y);
  182.         - This routine returns the Y window offset for the window "win" of
  183.           the bottom edge of the character position nearest to the position
  184.           "y" in the window "win".
  185.         - returns HASWIN_UNKNOWN on any error.
  186.  
  187. int     haswin_converttxtxytowin(window *win, int *x, int *y);
  188.         - This routine takes the x,y position of a character in the text
  189.           overlay of the window "win" and replaces the values by the window
  190.           offset in the window "win" of the bottom left corner of the
  191.           character.
  192.         - returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  193.  
  194. int     haswin_convertwinxtotxt(window *win, int x);
  195.         - This routine takes a X offset in the window "win" and returns the
  196.           X position of the nearest character in the text overlay for the
  197.           window "win" to the offset "x".
  198.         - returns HASWIN_UNKNOWN on any error.
  199.  
  200. int     haswin_convertwinytotxt(window *win, int y);
  201.         - This routine takes a Y offset in the window "win" and returns the
  202.           Y position of the nearest character in the text overlay for the
  203.           window "win" to the offset "y".
  204.         - returns HASWIN_UNKNOWN on any error.
  205.  
  206. int     haswin_convertwinxytotxt(window *win, int *x, int *y);
  207.         - This routine takes an x,y offset in the window "win" and replaces
  208.           the values by the X,Y position of the nearest character in the
  209.           text overlay for the window "win".
  210.         - returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  211.  
  212. int     haswin_converttxtxtoscr(window *win, int x);
  213.         - This routine returns the real screen X position of the left hand
  214.           edge of the character position nearest to the position "x" in the
  215.           window "win".
  216.         - returns HASWIN_UNKNOWN on any error.
  217.  
  218. int     haswin_converttxtytoscr(window *win, int y);
  219.         - This routine returns the real screen Y position of the left hand
  220.           edge of the character position nearest to the position "y" in the
  221.           window "win".
  222.         - returns HASWIN_UNKNOWN on any error.
  223.  
  224. int     haswin_converttxtxytoscr(window *win, int *x, int *y);
  225.         - This routine takes the x,y position of a character in the text
  226.           overlay of the window "win" and replaces the values by the real
  227.           screen coordinates of the bottom left corner of the character.
  228.         - returns HASWIN_TRUE if successful or HASWIN_FALSE on any error.
  229.  
  230. int     haswin_convertscrxtotxt(window *win, int x);
  231.         - This routine takes a real screen X position and returns the X
  232.           position of the nearest character position in the text overlay for
  233.           the window "win".
  234.         - returns HASWIN_UNKNOWN on any error.
  235.  
  236. int     haswin_convertscrytotxt(window *win, int y);
  237.         - This routine takes a real screen Y position and returns the Y
  238.           position of the nearest character position in the text overlay for
  239.           the window "win".
  240.         - returns HASWIN_UNKNOWN on any error.
  241.  
  242. int     haswin_convertscrxytotxt(window *win, int *x, int *y);
  243.         - This routine takes a real screen X,Y position and replaces these
  244.           by the values of the x,y position of the nearest character
  245.           position in the text overlay for the window "win".
  246.         - returns HASWIN_UNKNOWN on any error.
  247.  
  248.