home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / haswinlib / info / pointer < prev    next >
Encoding:
Text File  |  1991-02-04  |  11.6 KB  |  238 lines
  1.  
  2.                       The HASWIN window library.
  3.                      ===========================
  4.                       Copyright H.A. Shaw 1990.
  5.                      ===========================
  6.  
  7. Mouse Pointers under the HASWIN system.
  8. ----------------------------------------
  9.  
  10.         HASWIN provides a more complex pointer system than that provided
  11. by the WIMP.  Since there is a single pointer available at any time HASWIN
  12. considers the pointer to be a non-shared resource available to the user
  13. program (in the same way the caret is a non-shared resource).  Each HASWIN
  14. window can have its own pointer that is automatically selected when the
  15. mouse is positioned over the window.  In addition to this new pointers may
  16. be selected at any time.  A first-in-first-out pointer stack is provided to
  17. simplify programming.  If a section of code wishes to display a pointer it
  18. pushes its pointer onto the stack at the begining, and pulls its pointer
  19. off at the end of the code.  If no action is taken the existing pointer is
  20. not changed.  Pointers are made up of sprites that may be in any of the
  21. sprite areas except the system area.  This is how pointers are selected on
  22. entering and leaving windows.  Programs must be careful to pair pushes and
  23. pulls of the pointer stack.
  24.  
  25.  
  26.         The HASWIN pointer is a data structure created and maintained by
  27. the HASWIN routines.  A pointer has the following user selected features.
  28.  
  29.         1)    a named sprite that defines the pointer shape.
  30.         2)    an active position that defines where the WIMP considers the
  31.               pointer to actually be.  (This is usually somewhere in the
  32.               sprite shape, but does not have to be.)
  33.         3)    A palette for the sprite, if it does not already have one.
  34.         4)    X and Y coordinates.
  35.         5)    The state of the buttons, and some control keys.
  36.         6)    The window and icon the pointer is over.
  37.  
  38.     Since all of the fields of a pointer structure are user fields they
  39. will all be described.
  40.  
  41. short           mx;
  42.         - The X coordinate of the mouse position.  This may be read after
  43.           a call to "haswin_getpointerinfo()" to get the current mouse X
  44.           position.  To move the pointer use "haswin_(push/set)pointer()"
  45.           with this field set to the required value, or use
  46.           "haswin_placepointer()".
  47.  
  48. short           my;
  49.         - The Y coordinate of the mouse position.  This may be read after
  50.           a call to "haswin_getpointerinfo()" to get the current mouse Y
  51.           position.  To move the pointer use "haswin_(push/set)pointer()"
  52.           with this field set to the required value, or use
  53.           "haswin_placepointer()".
  54.  
  55. int             ihandle;
  56.         - The handle of the icon the mouse it on top of.  This may be
  57.           read after a call to "haswin_getpointerinfo()" and may be set
  58.           before a call to "haswin_(push/set)pointer()".  If "whandle" is
  59.           greater than 0 then "ihandle" can take various negative values
  60.           as follows...
  61.                -1 work area
  62.                -2 back icon
  63.                -3 close icon
  64.                -4 title bar
  65.                -5 toggle size icon
  66.                -6 scroll up arrow
  67.                -7 vertical scroll bar
  68.                -8 scroll down arrow
  69.                -9 adjust size icon
  70.               -10 scroll left arrow
  71.               -11 horizontal scroll bar
  72.               -12 scroll right arrow
  73.               -13 outer window frame
  74.  
  75. int             whandle;
  76.         - The handle of the window the mouse it on top of.  This may be
  77.           read after a call to "haswin_getpointerinfo()" and may be set
  78.           before a call to "haswin_(push/set)pointer()".
  79.  
  80. struct window   *win;
  81.         - If "whandle" is a HASWIN window belonging to this program then
  82.           "win" points to its window structure, or 0 otherwise.
  83.  
  84. struct icon     *ic;
  85.         - If "ihandle" is a HASWIN icon belonging to this program then
  86.           "ic" points to its window structure, or 0 otherwise.
  87.  
  88. char            name[POINTER_MAXDATA];
  89.         - This contains the first POINTER_MAXDATA characters of the name
  90.           of the sprite that defines the shape of the pointer.  In this
  91.           version POINTER_MAXDATA has the value 16.
  92.  
  93. signed char     activex;
  94.         - This is the X coordinate of the active point of the pointer.
  95.  
  96. signed char     activey;
  97.         - This is the Y coordinate of the active point of the pointer.
  98.  
  99. unsigned char   number;
  100.         - This is the pointer number, from 1-4, but is unused.
  101.  
  102. unsigned char   buttons;
  103.         - This is the state of the buttons and SHIFT, CONTROL and ALT keys.
  104.           It may be read after a call to "haswin_getpointerinfo()".  The
  105.           bits of this coorespond to the three mouse buttons and the SHIFT,
  106.           CONTROL and ALT keys.
  107.               POINTER_MOUSE_R            right mouse button
  108.               POINTER_MOUSE_M           middle mouse button
  109.               POINTER_MOUSE_L             left mouse button
  110.               POINTER_MOUSE_S            Shift pressed down
  111.               POINTER_MOUSE_C          Control pressed down
  112.               POINTER_MOUSE_A              Alt pressed down
  113.               POINTER_MOUSEBUTTONS     mask of just the mouse buttons
  114.  
  115. palette         *palette;
  116.         - This points to a palette structure.  If "palette" is non-zero and
  117.           the sprite "name" does not have a palette of its own then alter
  118.           the WIMP palette to this palette when the pointer is changed to
  119.           this pointer.
  120.  
  121.  
  122.         The routines that deal with pointers within the HASWIN system are
  123. described below.
  124.  
  125. pointer *haswin_getpointerinfo(pointer *mouse);
  126.         - fill in the current mouse coordinates, button state, state of
  127.           the SHIFT, CONTROL and ALT keys and the window and icon the
  128.           pointer is over in the pointer "mouse" with the current state as
  129.           obtained from the WIMP.  If "mouse" is 0 then a new pointer
  130.           structure is created and all its fields are filled in from the
  131.           current state.
  132.         - Returns the pointer "mouse", the newly created pointer structure,
  133.           or HASWIN_FALSE on any error.
  134.  
  135. pointer *haswin_makepointer(char *name, int x, int y);
  136.         - Create a new pointer structure with the sprite "name" and active
  137.           point "x", "y".  The position and button/key state is not filled
  138.           into the new structure.
  139.         - Returns the new pointer, or HASWIN_FALSE on any error.
  140.  
  141. int     haswin_poppointer(int move);
  142.         - Pull a pointer from the pointer stack.  if "move" is HASWIN_TRUE
  143.           then move the pointer to the coordinates stored in the stacked
  144.           pointer.  If the stacked pointer is 0 then turn the pointer off.
  145.           If "move" is HASWIN_FALSE then just change the pointer shape to
  146.           the stacked shape.  If the pointer structure has a palette then
  147.           use WIMP_SetPalette to change the WIMP palette.
  148.         - Return HASWIN_TRUE if successful, or HASWIN_FALSE on any error.
  149.  
  150. int     haswin_pushpointer(pointer *mouse, int move);
  151.         - Push the current pointer onto the pointer stack and then change
  152.           the current pointer to "mouse".  If "mouse" is 0 turn the pointer
  153.           off.  If "move" is HASWIN_TRUE then move the current pointer to
  154.           the coordinates stored in "mouse".  If "move" is HASWIN_FALSE
  155.           then just change the pointer shape to "mouse".  If "mouse" has a
  156.           palette then use WIMP_SetPalette to change the WIMP palette.
  157.         - Return HASWIN_TRUE if successful, or HASWIN_FALSE on any error.
  158.  
  159. int     haswin_setpointer(pointer *mouse, int move);
  160.         - Change the current pointer to "mouse".  If "mouse" is 0 turn the
  161.           pointer off.  If "move" is HASWIN_TRUE then move the current
  162.           pointer to the coordinates stored in "mouse".  If "move" is
  163.           HASWIN_FALSE then just change the pointer shape to "mouse".  If
  164.           "mouse" has a palette then use WIMP_SetPalette to change the WIMP
  165.           palette.
  166.         - Return HASWIN_TRUE if successful, or HASWIN_FALSE on any error.
  167.  
  168. int     haswin_placepointer(window *win, int x, int y);
  169.         - Reposition the current pointer at "x","y" in the window "win".
  170.         - Returns HASWIN_TRUE if successful or HASWIN_FALSE on any error, or
  171.           if "x" or "y" were outside the window area.  If the window is not
  172.           being displayed the pointer is moved to where it would have been
  173.           if the window was being displayed and no error is returned.
  174.  
  175.  
  176.         The WIMP returns details of mouse button states in a rather
  177. inconvienent form for many purposes in that the button state code the WIMP
  178. uses for a particular button state depends upon the button type of the
  179. object the mouse in on at the time the button state changed.  It would be
  180. much more convienent to the user program if the code representating a
  181. particular button state was independent of the button type of the objects
  182. on the screen.  HASWIN therefore has a number of routines for converting
  183. between the object button type dependent button state codes that the WIMP
  184. uses and the independent codes that a user program can find more easy to
  185. use internally.  The 7 types of single button operation are represented
  186. by the following constant values
  187.  
  188. HASWIN_MOUSE_R       - right or ADJUST button pressed
  189. HASWIN_MOUSE_M       - middle or MENU button pressed
  190. HASWIN_MOUSE_L       - left or SELECT button pressed
  191. HASWIN_MOUSE_RDRAG   - right or ADJUST button dragged
  192. HASWIN_MOUSE_LDRAG   - left or SELECT button dragged
  193. HASWIN_MOUSE_RDOUB   - right or ADJUST button double clicked
  194. HASWIN_MOUSE_LDOUB   - left or SELECT button double clicked
  195.  
  196. int     haswin_buttonHASWINtoWIMP(window *win, icon *ic, int button);
  197.         - convert the button state "button" from one of the HASWIN internal
  198.           codes into a WIMP button state with reference to the window "win"
  199.           and the icon "ic".  Either "win" or "ic" may be 0.
  200.         - Returns the WIMP button code.
  201.  
  202. int     haswin_buttonWIMPtoHASWIN(window *win, icon *ic, int button);
  203.         - convert the button state "button" from the codes the WIMP uses
  204.           into codes for HASWIN with reference to the window "win" and the
  205.           icon "ic".  Either "win" or "ic" may be 0.  It is garenteed that
  206.           for a particular mouse button state (such as SELECT pressed) the
  207.           returned code will be unique to that state and is independent of
  208.           the button type of the object under the mouse pointer.
  209.         - Returns the HASWIN button code.
  210.  
  211. int     haswin_canbuttondouble(int type);
  212.         - Returns HASWIN_TRUE if the WIMP button type "type" responds to
  213.           double clicks and HASWIN_FALSE if it does not.  If the button
  214.           type is not known it returns HASWIN_UNKNOWN.
  215.  
  216. int     haswin_canbuttondrag(int type);
  217.         - Returns HASWIN_TRUE if the WIMP button type "type" responds to
  218.           drags and HASWIN_FALSE if it does not.  If the button type is
  219.           not known it returns HASWIN_UNKNOWN.
  220.  
  221. int     haswin_canbuttonselect(int type);
  222.         - Returns HASWIN_TRUE if the WIMP button type "type" responds to
  223.           select and HASWIN_FALSE if it does not.  If the button type is
  224.           not known it returns HASWIN_UNKNOWN.
  225.  
  226. int     haswin_canbuttonwrite(int type);
  227.         - Returns HASWIN_TRUE if the WIMP button type "type" is a writable
  228.           type and HASWIN_FALSE if it does not.  If the button type is not
  229.           known it returns HASWIN_UNKNOWN.
  230.  
  231. int     haswin_canbuttontwice(int type);
  232.         - Returns HASWIN_TRUE if the WIMP button type "type" responds to
  233.           drags or double clicks, ie. any mouse operation that results in
  234.           more than one event returned by SWI WIMP_Poll.  The routine
  235.           returns HASWIN_FALSE if it does not respond.  If the button type
  236.           is not known it returns HASWIN_UNKNOWN.
  237.  
  238.