home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / haswinlib / info / caret next >
Encoding:
Text File  |  1991-02-04  |  5.2 KB  |  117 lines
  1.  
  2.                       The HASWIN window library.
  3.                      ===========================
  4.                       Copyright H.A. Shaw 1990.
  5.                      ===========================
  6.  
  7. Carets under the HASWIN system.
  8. -------------------------------
  9.  
  10.         HASWIN provides a more complex text caret system than that provided
  11. by the WIMP.  Since there is a single caret available at any time HASWIN
  12. considers the caret to be a non-shared resource available to the user
  13. program (in the same way the pointer is a non-shared resource).  Each HASWIN
  14. window can have its own caret that is automatically selected when the
  15. window gains the input focus.  In addition to this new carets may be
  16. selected at any time.  A first-in-first-out caret stack is provided to
  17. simplify programming.  If a section of code wishes to use a caret it
  18. pushes its caret onto the stack at the begining, and pulls its caret
  19. off at the end of the code.  If no action is taken the existing caret is
  20. not changed.  Programs must be careful to pair pushes and pulls of the caret
  21. stack.
  22.  
  23.  
  24.         The HASWIN caret is a data structure created and maintained by
  25. the HASWIN routines.  A caret has the following user selected features.
  26.  
  27.         1)  A window to put the caret in.
  28.         2)  An icon to put the caret in.
  29.         3)  A x,y coordinate, height and index into a string for the caret.
  30.         4)  The colour of the caret.
  31.         5)  A set of flags to define the way the caret behaves.
  32.  
  33.         Since all of the fields of the caret structure are user setable
  34. they will all be described.
  35.  
  36. struct window   *win;
  37.         - The window to put the caret into.  If the window is not a HASWIN
  38.           one "win" is the window handle.  If 0 the caret is not in a window.
  39.  
  40. struct icon     *ic;
  41.         - The icon to put the caret into.  If the icon is not a HASWIN
  42.           one "ic" is the icon handle.  If 0 the caret is not in an icon.
  43.  
  44. int             x;
  45.         - The X coordinate of the caret in the window.  If the icon is in an
  46.           icon then this has no real meaning.
  47.  
  48. int             y;
  49.         - The Y coordinate of the caret in the window.  If the icon is in an
  50.           icon then this has no real meaning.
  51.  
  52. int             height;
  53.         - The height of the caret.  If -1 then "x", "y" and "height" are
  54.           determined from "win", "ic" and "index".
  55.  
  56. int             colour;
  57.         - The caret colour, but see flags below.
  58.  
  59. int             flags;
  60.         - A set of flags as below...
  61.               CARET_HEIGHT     mask for height of caret in OS units
  62.               CARET_COLOUR     mask for colour if USECOLOUR bit set
  63.               CARET_VDU5       use a VDU type 5 caret
  64.               CARET_INVIS      the caret is invisible
  65.               CARET_USECOLOUR  if set use COLOUR else use WIMP colour 11
  66.               CARET_WIMPCOL    if set COLOUR is real else WIMP translates
  67.               CARET_REALCOL    make colour ACTUAL colour by EOR with
  68.                                background
  69.               CARET_HASWIN     if set the caret is in a HASWIN window
  70.  
  71. int             index;
  72.           - The index of the caret into the icon "ic", if -1 then use "win",
  73.             "ic", "x" and "y" to determine "height" and "index".
  74.  
  75.  
  76.         The routines that deal with carets within the HASWIN system are
  77. described below.
  78.  
  79. caret *haswin_getcaretinfo(caret *car);
  80.         - fill in the current caret coordinates and the window and icon the
  81.           caret is in with the current state as obtained from the WIMP.
  82.           If "car" is 0 then a new caret structure is created and all its
  83.           fields are filled in from the current state.
  84.         - Returns the caret "car", the newly created caret structure,
  85.           or HASWIN_FALSE on any error.
  86.  
  87. caret *haswin_makecaret(window *win, icon *ic, int x, int y, int height,
  88.                         int colour, int flags, int index);
  89.         - Create a new caret structure.
  90.           - "win"     window to put caret in (handle for non-HASWIN windows).
  91.           - "ic"      icon to put caret in (handle for non-HASWIN windows).
  92.           - "x"       X coordinate of caret position.
  93.           - "y"       X coordinate of caret position.
  94.           - "height"  hieght of caret, if -1 then use "win", "ic", "index"
  95.                       to determine "x", "y" and "height".
  96.           - "colour"  colour of caret (but see the flags)
  97.           - "flags"   flags.
  98.           - "index"   index of the caret into "ic", if -1 then use "win",
  99.                       "ic", "x" and "y" to determine "height" and "index".
  100.         - Returns the new caret, or HASWIN_FALSE on any error.
  101.  
  102. int     haswin_popcaret(void);
  103.         - Pull a caret from the caret stack.  If the stacked caret is 0
  104.           then turn the caret off.
  105.         - Return HASWIN_TRUE if successful, or HASWIN_FALSE on any error.
  106.  
  107. int     haswin_pushcaret(caret *car);
  108.         - Push the current caret onto the caret stack and then change
  109.           the current caret to "car".  If "car" is 0 turn the caret off.
  110.         - Return HASWIN_TRUE if successful, or HASWIN_FALSE on any error.
  111.  
  112. int     haswin_setcaret(caret *car);
  113.         - Change the current caret to "car".  If "car" is 0 turn the caret
  114.           off.
  115.         - Return HASWIN_TRUE if successful, or HASWIN_FALSE on any error.
  116.  
  117.