home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / clib / progs / haswinlib / info / poll < prev    next >
Encoding:
Text File  |  1991-02-04  |  40.6 KB  |  699 lines

  1.  
  2.                       The HASWIN window library.
  3.                      ===========================
  4.                       Copyright H.A. Shaw 1990.
  5.                      ===========================
  6.  
  7.         HASWIN is designed to take as much of the workload of operating
  8. under the WIMP environment away from the user program as possible.  This
  9. is so that the user program (and its programmer) can concentrate on the
  10. actual application leaving all the mundane tasks to HASWIN.  In order to
  11. do this HASWIN provides an interface to the SWI WIMP_Poll that a user
  12. application would normally call to find out what changes are happening
  13. in the WIMP that the program must respond to.  The HASWIN routine
  14. "haswin_poll()" calls the WIMP and deals with most circumstances on its
  15. own.  It calls the user provided routines to deal with things it cannot
  16. know about such as drawing inside windows, loading or saving files and
  17. RAM data transfers.  It always confirms its default actions with the user
  18. program by calling the user routines before it takes any action itself.
  19. The user routines can prevent HASWIN from continuing to process by
  20. returning the value HASWIN_FALSE when they exit.  HASWIN will then abandon
  21. the current processing and the routine haswin_poll() will return.
  22. To continue processing other WIMP events haswin_poll() should be called
  23. again.  If haswin_poll() is called it is garennteed to return eventually,
  24. even if there is no WIMP event to process.
  25.         HASWIN allows the user program to provide its own polling routine
  26. that HASWIN will call.  If provided, the routine is called before HASWIN
  27. performs its actions and this allows the routine to extend, or replace
  28. the default actions of HASWIN on a per-call basis and this greatly extends
  29. the HASWIN library's functionality.  The user routine must be a C function
  30. of global scope defined as follows...
  31.  
  32.         int routine(int code, buffer *buf);
  33.  
  34.         A HASWIN function is provided to inform HASWIN of the existance of
  35. the user poll routine.
  36.  
  37. int     haswin_setuserpollroutine(int (*routine)(int code, buffer *buf));
  38.         - Set a new user routine to be called from within "haswin_poll()"
  39.           If "routine" is 0 then no routine is set.  The routine takes
  40.           two parameters when called.
  41.           - "code" is the WIMP reason code from WIMP_Poll (note: HASWIN
  42.             provides extra reason codes of its own).
  43.           - "buf" is the buffer passed from WIMP_Poll (note: HASWIN can
  44.             add extra things to this buffer as it sees fit).
  45.  
  46.         The user poll routine will be called automatically by HASWIN at
  47. least once each time "haswin_poll()" is called.  The parameter "code"
  48. contains the possible reason codes and the list below shows the codes
  49. and describes the WIMP activity that causes them to be used.
  50.  
  51. HASWIN_POLL_Nothing     - A Null_Reason_Code (0) has been received by HASWIN
  52.                           from the SWI WIMP_Poll.  The buffer contains no
  53.                           useful information and may be altered in any way.
  54.                           Since HASWIN performs no processing the user
  55.                           routine can return any value, which will be ignored
  56.                           by HASWIN and passed back to the caller of the
  57.                           haswin_poll() that caused the user routine to be
  58.                           called.
  59.  
  60. HASWIN_POLL_Redraw      - A Redraw_Window_Request (1) has been received by
  61.                           HASWIN from the SWI WIMP_Poll.
  62.                           The buffer contains...
  63.                               buf->i[ 0] = window handle to be redrawn
  64.                               buf->i[ 1] = pointer to window structure
  65.                           This reason code is used to inform the user program
  66.                           that a window is to be redrawn.  If the user
  67.                           routine returns HASWIN_FALSE then HASWIN abandons
  68.                           the redraw operation and returns HASWIN_FALSE to
  69.                           the caller of the haswin_poll() that handled the
  70.                           redraw operation.  The user routine should not
  71.                           alter the buffer.
  72.  
  73. HASWIN_POLL_PostRedraw  - Redrawing of a window is complete.
  74.                           The buffer contains...
  75.                               buf->i[ 0] = handle of window just redrawn
  76.                               buf->i[ 1] = pointer to window structure
  77.                           This reason code is used to inform the user program
  78.                           that HASWIN has completed the redraw of a window.
  79.                           Since HASWIN has no more processing to do it passes
  80.                           the return code HASWIN_TRUE or HASWIN_FALSE back
  81.                           to the caller of the haswin_poll() that handled the
  82.                           the redraw operation.  The user routine should not
  83.                           alter the buffer.
  84.  
  85. HASWIN_POLL_Open        - A Open_Window_Request (2) has been received by
  86.                           HASWIN from the SWI WIMP_Poll.
  87.                           The buffer contains...
  88.                               buf->i[ 0] = window handle
  89.                               buf->i[ 1] = visable area minimum X coordinate
  90.                               buf->i[ 2] = visable area minimum Y coordinate
  91.                               buf->i[ 3] = visable area maximum X coordinate
  92.                               buf->i[ 4] = visable area maximum Y coordinate
  93.                               buf->i[ 5] = scroll x offset
  94.                               buf->i[ 6] = scroll y offset
  95.                               buf->i[ 7] = handle to open window behind
  96.                               buf->i[ 8] = pointer to window structure
  97.                           This reason code is used to inform the user program
  98.                           that a window is to be opened.  If the user routine
  99.                           returns HASWIN_FALSE then HASWIN abandons the open
  100.                           operation and returns HASWIN_FALSE to the caller of
  101.                           the haswin_poll() that handled the open operation.
  102.                           The user routine can alter the buffer to modify how
  103.                           the window will be opened and its position.  The
  104.                           window handle and pointer to window structure
  105.                           fields of the buffer should not be altered.
  106.  
  107. HASWIN_POLL_Close       - A Close_Window_Request (3) has been received by
  108.                           HASWIN from the SWI WIMP_Poll.
  109.                           The buffer contains...
  110.                               buf->i[ 0] = window handle
  111.                               buf->i[ 1] = pointer to window structure
  112.                           This reason code is used to inform the user program
  113.                           that a window is to be closed.  If the user routine
  114.                           returns HASWIN_FALSE then HASWIN abandons the close
  115.                           operation and returns HASWIN_FALSE to the caller of
  116.                           the haswin_poll() that handled the close operation.
  117.                           The user routine should not alter the buffer.
  118.  
  119. HASWIN_POLL_Entering    - A Pointer_Entering_Window (4) has been received by
  120.                           HASWIN from the SWI WIMP_Poll.
  121.                           The buffer contains...
  122.                               buf->i[ 0] = window handle
  123.                               buf->i[ 1] = pointer to window structure
  124.                           This reason code is used to inform the user program
  125.                           that the mouse pointer is about to enter a window.
  126.                           If the user routine returns HASWIN_FALSE then
  127.                           HASWIN abandons the processing associated with the
  128.                           mouse entering window operation and returns
  129.                           HASWIN_FALSE to the caller of the haswin_poll()
  130.                           that handled the mouse entering window operation.
  131.                           The user routine should not alter the buffer.
  132.  
  133. HASWIN_POLL_Leaving     - A Pointer_Leaving_Window (5) has been received by
  134.                           HASWIN from the SWI WIMP_Poll.
  135.                           The buffer contains...
  136.                               buf->i[ 0] = window handle
  137.                               buf->i[ 1] = pointer to window structure
  138.                           This reason code is used to inform the user program
  139.                           that the mouse pointer is about to leave a window.
  140.                           If the user routine returns HASWIN_FALSE then
  141.                           HASWIN abandons the processing associated with the
  142.                           mouse leaving window operation and returns
  143.                           HASWIN_FALSE to the caller of the haswin_poll()
  144.                           that handled the mouse leaving window operation.
  145.                           The user routine should not alter the buffer.
  146.  
  147. HASWIN_POLL_Mouse_1st   - A Mouse_Click (6) has been received by HASWIN
  148.                           from the SWI WIMP_Poll.
  149.                           The buffer contains...
  150.                               buf->i[ 0] = mouse X coordinate in screen
  151.                               buf->i[ 1] = mouse Y coordinate in screen
  152.                               buf->i[ 2] = WIMP button state
  153.                               buf->i[ 3] = window handle
  154.                               buf->i[ 4] = icon handle
  155.                               buf->i[ 5] = HASWIN standard button state
  156.                               buf->i[ 6] = pointer to window structure
  157.                               buf->i[ 7] = pointer to icon structure
  158.                           This reason code is used when HASWIN detects
  159.                           that a mouse operation has occured but before
  160.                           HASWIN does any processing.  If the user routine
  161.                           returns HASWIN_FALSE then HASWIN abandons the
  162.                           processing associated with the mouse click
  163.                           operation and returns HASWIN_FALSE to the caller
  164.                           of the haswin_poll() that handled the mouse click
  165.                           operation.  The user routine may alter the buffer
  166.                           if it wishes, but HASWIN ignores any attempt to
  167.                           change the window or icon handles or structure
  168.                           pointers.  The X and Y coordinates of the mouse
  169.                           and the mouse button state may be changed however.
  170.                           Changing the X and Y coordinates can be used, for
  171.                           example, to force the mouse to align with character
  172.                           positions in the window.
  173.  
  174. HASWIN_POLL_Mouse_2nd   - A Mouse_Click (6) has been received by HASWIN
  175.                           from the SWI WIMP_Poll.
  176.                           The buffer contains...
  177.                               buf->i[ 0] = mouse X coordinate in screen
  178.                               buf->i[ 1] = mouse Y coordinate in screen
  179.                               buf->i[ 2] = WIMP button state
  180.                               buf->i[ 3] = window handle
  181.                               buf->i[ 4] = icon handle
  182.                               buf->i[ 5] = HASWIN standard button state
  183.                               buf->i[ 6] = pointer to window structure
  184.                               buf->i[ 7] = pointer to icon structure
  185.                           This reason code is used when HASWIN detects
  186.                           that a mouse operation has occured but after HASWIN
  187.                           has done some processing.  If the mouse click was
  188.                           on the MENU button this reason code will not be
  189.                           used.  If the mouse click was a SELECT or ADJUST
  190.                           DRAG or DOUBLE CLICK then the reason code
  191.                           HASWIN_POLL_Mouse_1st will be used, with a button
  192.                           state of SELECT or ADJUST and then this reason code
  193.                           will be used with the correct button state.  If
  194.                           the user routine returns HASWIN_FALSE then HASWIN
  195.                           abandons further processing associated with the
  196.                           mouse click operation and returns HASWIN_FALSE to
  197.                           the caller of the haswin_poll() that handled the
  198.                           mouse click operation.  The user routine may alter
  199.                           the buffer if it wishes, but HASWIN ignores any
  200.                           attempt to change the window or icon handles or
  201.                           structure pointers.  The X and Y coordinates of the
  202.                           mouse and the mouse button state may be changed
  203.                           however.  Changing the state is dangerous since
  204.                           HASWIN has already done some processing.  Changing
  205.                           the X and Y coordinates can be used, for example,
  206.                           to force the mouse to align with character
  207.                           positions in the window.
  208.  
  209. HASWIN_POLL_Drag        - A User_Drag_Box (7) has been received by HASWIN
  210.                           from the SWI WIMP_Poll.
  211.                           The buffer contains...
  212.                               buf->i[ 0] = minimum X coordinate
  213.                               buf->i[ 1] = minimum Y coordinate
  214.                               buf->i[ 2] = maximum X coordinate
  215.                               buf->i[ 3] = maximum Y coordinate
  216.                               buf->i[ 4] = window handle where drag started
  217.                                            or -1
  218.                               buf->i[ 5] = icon handle where drag started or
  219.                                            -1
  220.                               buf->i[ 6] = pointer to window structure where
  221.                                            drag started or 0
  222.                               buf->i[ 7] = pointer to icon structure where
  223.                                            drag started or 0
  224.                           This reason code is used to inform the user program
  225.                           that a user drag operation has finished, and that
  226.                           the user dragroutine exists, has been called and
  227.                           has returned HASWIN_TRUE.  If the user routine
  228.                           returns HASWIN_FALSE then HASWIN abandons the
  229.                           processing associated with the drag operation
  230.                           and returns HASWIN_FALSE to the caller of the
  231.                           haswin_poll() that handled the drag operation.
  232.                           The user routine may alter the buffer if it wishes,
  233.                           but HASWIN ignores any changes.
  234.  
  235. HASWIN_POLL_Key         - A Key_Pressed (8) has been received by HASWIN
  236.                           from the SWI WIMP_Poll.
  237.                           The buffer contains...
  238.                               buf->i[ 0] = window handle
  239.                               buf->i[ 1] = icon handle or -1
  240.                               buf->i[ 2] = X coordinate in screen
  241.                               buf->i[ 3] = Y coordinate in screen
  242.                               buf->i[ 4] = caret height and flags
  243.                               buf->i[ 5] = index into string of icon
  244.                               buf->i[ 6] = character code as an int
  245.                               buf->i[ 7] = pointer to window structure
  246.                               buf->i[ 8] = pointer to icon structure
  247.                           This reason code is used to inform the user program
  248.                           that a key has been pressed while one of the user
  249.                           program's windows was the input focus.  If the user
  250.                           routine returns HASWIN_FALSE then HASWIN abandons
  251.                           the processing of keys and returns HASWIN_FALSE
  252.                           to the caller of the haswin_poll() that handled the
  253.                           mouse entering window operation.  The user routine
  254.                           may alter the buffer if it wishes, but HASWIN only
  255.                           uses the character code in its processing.
  256.  
  257. HASWIN_POLL_Menu        - A Menu_Selection (9) has been received by HASWIN
  258.                           from the SWI WIMP_Poll.
  259.                           The buffer contains...
  260.                               buf->i[ 0] = number of selected item in menu
  261.                               buf->i[ 1] = number of item in 1st sub-menu
  262.                               buf->i[ 2] = number of item in 2nd sub-menu
  263.                               buf->i[ 3] = number of item in 3rd sub-menu
  264.                               ... terminates with item -1
  265.                           This reason code is used to inform the user program
  266.                           that an item in a menu has been selected.  If the
  267.                           user routine returns HASWIN_FALSE then HASWIN
  268.                           abandons the processing of the menu selection and
  269.                           returns HASWIN_FALSE to the caller of the
  270.                           haswin_poll() that handled the menu selection
  271.                           operation.  The user routine should not alter the
  272.                           buffer.
  273.  
  274. HASWIN_POLL_Scroll      - A Scroll_Request (10) has been received by HASWIN
  275.                           from the SWI WIMP_Poll.
  276.                           The buffer contains...
  277.                               buf->i[ 0] = window handle
  278.                               buf->i[ 1] = visable area minimum X coordinate
  279.                               buf->i[ 2] = visable area minimum Y coordinate
  280.                               buf->i[ 3] = visable area maximum X coordinate
  281.                               buf->i[ 4] = visable area maximum Y coordinate
  282.                               buf->i[ 5] = current scroll x offset
  283.                               buf->i[ 6] = current scroll y offset
  284.                               buf->i[ 7] = handle to open window behind
  285.                               buf->i[ 8] = scroll X direction
  286.                               buf->i[ 9] = scroll Y direction
  287.                               buf->i[10] = pointer to window structure
  288.                           This reason code is used to inform the user program
  289.                           that a scroll operation has been performed and that
  290.                           the window must be updated.  If the user routine
  291.                           returns HASWIN_FALSE then HASWIN abandons the
  292.                           scroll operation, the window does not change, and
  293.                           HASWIN_FALSE is returned to the caller of the
  294.                           haswin_poll() that handled the scroll request.
  295.                           The user routine may alter the buffer if it wishes
  296.                           and HASWIN will process the scroll request
  297.                           according to the buffer as it is after the call
  298.                           to the user routine.
  299.  
  300. HASWIN_POLL_Scrolled    - A Scroll_Request (10) has been received by HASWIN
  301.                           from the SWI WIMP_Poll.
  302.                           The buffer contains...
  303.                               buf->i[ 0] = window handle
  304.                               buf->i[ 1] = visable area minimum X coordinate
  305.                               buf->i[ 2] = visable area minimum Y coordinate
  306.                               buf->i[ 3] = visable area maximum X coordinate
  307.                               buf->i[ 4] = visable area maximum Y coordinate
  308.                               buf->i[ 5] = calculated new scroll x offset
  309.                               buf->i[ 6] = calculated new scroll y offset
  310.                               buf->i[ 7] = handle to open window behind
  311.                               buf->i[ 8] = scroll X direction
  312.                               buf->i[ 9] = scroll Y direction
  313.                               buf->i[10] = pointer to window structure
  314.                           This reason code is used to inform the user program
  315.                           that a scroll operation has been performed and that
  316.                           the window must be updated.  If the user routine
  317.                           returns HASWIN_FALSE then HASWIN abandons the
  318.                           scroll operation, the window does not change, and
  319.                           HASWIN_FALSE is returned to the caller of the
  320.                           haswin_poll() that handled the scroll request.
  321.                           The difference between this reason code and the
  322.                           reason code "HASWIN_POLL_Scroll" is that this is
  323.                           used after HASWIN has calculated the new scroll
  324.                           offsets and "HASWIN_POLL_Scroll" is used before.
  325.                           The user routine may alter the buffer if it wishes
  326.                           and HASWIN will process the scroll request
  327.                           according to the buffer as it is after the call
  328.                           to the user routine.
  329.  
  330. HASWIN_POLL_Lose_Caret  - A Lose_Caret (11) has been received by HASWIN
  331.                           from the SWI WIMP_Poll.
  332.                           The buffer contains...
  333.                               buf->i[ 0] = window handle
  334.                               buf->i[ 1] = icon handle or -1
  335.                               buf->i[ 2] = X coordinate in screen
  336.                               buf->i[ 3] = Y coordinate in screen
  337.                               buf->i[ 4] = caret height and flags
  338.                               buf->i[ 5] = index into string if writable icon
  339.  
  340. HASWIN_POLL_Gane_Caret  - A Gain_Caret (12) has been received by HASWIN
  341.                           from the SWI WIMP_Poll.
  342.                           The buffer contains...
  343.                               buf->i[ 0] = window handle
  344.                               buf->i[ 1] = icon handle or -1
  345.                               buf->i[ 2] = X coordinate in screen
  346.                               buf->i[ 3] = Y coordinate in screen
  347.                               buf->i[ 4] = caret height and flags
  348.                               buf->i[ 5] = index into string if writable icon
  349.  
  350. HASWIN_POLL_Message     - A User_Message (17) has been received by HASWIN
  351.                           from the SWI WIMP_Poll.
  352.                           Many messages are dealt with automatically by
  353.                           HASWIN and result in other calls to the user
  354.                           routine.  Unknown messages are passed to the user
  355.                           routine directly.
  356.                           The buffer contains...
  357.                               buf->i[ 0] = length of buffer (20-256) in a
  358.                                            multiple of 4 (ie. words)
  359.                               buf->i[ 1] = task handle of sender
  360.                               buf->i[ 2] = sender's reference number
  361.                               buf->i[ 3] = previous message reference number
  362.                                            or 0 if this is not a reply
  363.                               buf->i[ 4] = message type
  364.                               buf->i[ 5] = beginning of message data.
  365.  
  366. HASWIN_POLL_Message_Rec - A User_Message_Recorded (18) has been received by
  367.                           HASWIN from the SWI WIMP_Poll.
  368.                           Many messages are dealt with automatically by
  369.                           HASWIN and result in other calls to the user
  370.                           routine.  Unknown messages are passed to the user
  371.                           routine directly.
  372.                           The buffer contains...
  373.                               buf->i[ 0] = length of buffer (20-256) in a
  374.                                            multiple of 4 (ie. words)
  375.                               buf->i[ 1] = task handle of sender
  376.                               buf->i[ 2] = sender's reference number
  377.                               buf->i[ 3] = previous message reference number
  378.                                            or 0 if this is not a reply
  379.                               buf->i[ 4] = message type
  380.                               buf->i[ 5] = beginning of message data.
  381.  
  382. HASWIN_POLL_Message_Ack - A User_Message_Acknowledge (19) has been received
  383.                           by HASWIN from the SWI WIMP_Poll.
  384.                           Many messages are dealt with automatically by
  385.                           HASWIN and result in other calls to the user
  386.                           routine.  Unknown messages are passed to the user
  387.                           routine directly.
  388.                           The buffer contains...
  389.                               buf->i[ 0] = length of buffer (20-256) in a
  390.                                            multiple of 4 (ie. words)
  391.                               buf->i[ 1] = task handle of sender
  392.                               buf->i[ 2] = sender's reference number
  393.                               buf->i[ 3] = previous message reference number
  394.                                            or 0 if this is not a reply
  395.                               buf->i[ 4] = message type
  396.                               buf->i[ 5] = beginning of message data.
  397.  
  398. HASWIN_POLL_poll_Open   - A window is about to be opened as part of a HASWIN
  399.                           automatic operation.
  400.                           The buffer contains...
  401.                               buf->i[ 0] = window handle
  402.                               buf->i[ 1] = visable area minimum X coordinate
  403.                               buf->i[ 2] = visable area minimum Y coordinate
  404.                               buf->i[ 3] = visable area maximum X coordinate
  405.                               buf->i[ 4] = visable area maximum Y coordinate
  406.                               buf->i[ 5] = scroll x offset
  407.                               buf->i[ 6] = scroll y offset
  408.                               buf->i[ 7] = handle to open window behind
  409.                               buf->i[ 8] = pointer to window structure
  410.                           This reason code is used to inform a user program
  411.                           that a window is to be opened without a direct call
  412.                           to a HASWIN routine.  Windows can be opened due to
  413.                           SELECTing an icon with an associated window,
  414.                           opening a window that is a master window for pane
  415.                           or slide windows, or some selections from menus.
  416.                           If the user routine returns HASWIN_FALSE the
  417.                           window will not be opened.  The user routine may
  418.                           alter the buffer to modify how the window will be
  419.                           opened and its position.  The window handle and
  420.                           pointer to window structure fields of the buffer
  421.                           should not be altered.
  422.  
  423. HASWIN_POLL_poll_Close  - A window is about to be closed as part of a HASWIN
  424.                           automatic operation.
  425.                           The buffer contains...
  426.                               buf->i[ 0] = window handle
  427.                               buf->i[ 1] = pointer to window structure
  428.                           This reason code is used to inform a user program
  429.                           that a window is to be closed without a direct call
  430.                           to a HASWIN routine.  Windows can be closed due to
  431.                           ADJUSTing an icon with an associated window,
  432.                           closing a window that is a master window for pane
  433.                           or slide windows, or some selections from menus.
  434.                           If the user routine returns HASWIN_FALSE the
  435.                           window will not be closed.  The user routine should
  436.                           not alter the buffer.
  437.  
  438. HASWIN_POLL_poll_Menu   - A menu is about to be created as part of a HASWIN
  439.                           automatic operation.  This is usually called as a
  440.                           result of a mouse MENU click on a window on icon
  441.                           that has associated menus, windows or helps.
  442.                         - If the user routine returns HASWIN_FALSE the
  443.                           menu will not be created.
  444.  
  445. HASWIN_POLL_poll_ReMenu - A menu is about to be re-created as part of a
  446.                           HASWIN automatic operation.  This is usually
  447.                           called as a result of a menu selection using
  448.                           the ADJUST button so that the menu will not
  449.                           be closed.
  450.                         - If the user routine returns HASWIN_FALSE the
  451.                           menu will not be re-created and will disappear
  452.                           when haswin_poll() is next called.
  453.  
  454. HASWIN_POLL_poll_IHelp  - help is about to be displayed about an icon
  455.                         - If the user routine returns HASWIN_FALSE the
  456.                           help window will not be opened.
  457.  
  458. HASWIN_POLL_poll_MHelp  - help is about to be displayed about a menu
  459.                         - If the user routine returns HASWIN_FALSE the
  460.                           help window will not be opened.
  461.  
  462. HASWIN_POLL_poll_WHelp  - help is about to be displayed about a window
  463.                         - If the user routine returns HASWIN_FALSE the
  464.                           help window will not be opened.
  465.  
  466. HASWIN_POLL_poll_UQuit  - The user has asked HASWIN to quit
  467.                         - If the user routine returns HASWIN_FALSE the
  468.                           menu will not be re-created and will disappear
  469.                           when haswin_poll() is next called.
  470.  
  471. HASWIN_POLL_poll_MQuit  - A QUIT message has been received.
  472.                           This reason code allows the user routine to
  473.                           perform any processing neccessary before the
  474.                           user program exits.  When the user routine
  475.                           returns to its caller HASWIN will terminate
  476.                           execution of the user program.  This cannot be
  477.                           avioded.
  478.  
  479. HASWIN_POLL_TimeStep    - A time period has passed
  480.                         - If the user routine returns HASWIN_FALSE the
  481.                           menu will not be re-created and will disappear
  482.                           when haswin_poll() is next called.
  483.  
  484. HASWIN_POLL_poll_Load   - A DataLoad Message has been received by HASWIN
  485.                           from the SWI WIMP_Poll.  A file transfer is about
  486.                           to take place.
  487.                           the buffer contains...
  488.                               buf->i[ 0] = length of buffer (20-256) in a
  489.                                            multiple of 4 (ie. words)
  490.                               buf->i[ 1] = task handle of sender
  491.                               buf->i[ 2] = sender's reference number
  492.                               buf->i[ 3] = previous message reference number
  493.                                            or 0 if this is not a reply
  494.                               buf->i[ 4] = 
  495.                               buf->i[ 5] = destination window handle.
  496.                               buf->i[ 6] = destination icon handle
  497.                               buf->i[ 7] = destination x coordinate
  498.                               buf->i[ 8] = destination y coordinate
  499.                               buf->i[ 9] = estimated filesize in bytes
  500.                               buf->i[10] = file type
  501.                               buf->c[44] = full pathname of file, ends '\0'
  502.                           This reason code is used to inform the user program
  503.                           that a load file operation is to be performed.  If
  504.                           the user routine returns HASWIN_FALSE then HASWIN
  505.                           abandons the file operation and HASWIN_FALSE is
  506.                           returned to the caller of the haswin_poll() that
  507.                           handled the file operation.  If the user routine
  508.                           returns HASWIN_TRUE then HASWIN sends the correct
  509.                           messages to the external task and initiates the
  510.                           file transfer, calling the current user load file
  511.                           routine as defined by any calls to
  512.                           "haswin_(set/push)loadfileroutine()" to do the
  513.                           actual file transfer.
  514.  
  515. HASWIN_POLL_poll_Save   - A DataSave Message has been received by HASWIN
  516.                           from the SWI WIMP_Poll.  A file transfer is about
  517.                           to take place.
  518.                           the buffer contains...
  519.                               buf->i[ 0] = length of buffer (20-256) in a
  520.                                            multiple of 4 (ie. words)
  521.                               buf->i[ 1] = task handle of sender
  522.                               buf->i[ 2] = sender's reference number
  523.                               buf->i[ 3] = previous message reference number
  524.                                            or 0 if this is not a reply
  525.                               buf->i[ 4] = 
  526.                               buf->i[ 5] = destination window handle.
  527.                               buf->i[ 6] = destination icon handle
  528.                               buf->i[ 7] = destination x coordinate
  529.                               buf->i[ 8] = destination y coordinate
  530.                               buf->i[ 9] = estimated filesize in bytes
  531.                               buf->i[10] = file type
  532.                               buf->c[44] = full pathname of file, ends '\0'
  533.                           This reason code is used to inform the user program
  534.                           that a save file operation is to be performed.  If
  535.                           the user routine returns HASWIN_FALSE then HASWIN
  536.                           abandons the file operation and HASWIN_FALSE is
  537.                           returned to the caller of the haswin_poll() that
  538.                           handled the file operation.  If the user routine
  539.                           returns HASWIN_TRUE then HASWIN sends the correct
  540.                           messages to the external task and initiates the
  541.                           file transfer, calling the current user save file
  542.                           routine as defined by any calls to
  543.                           "haswin_(set/push)savefileroutine()" to do the
  544.                           actual file transfer.
  545.  
  546. HASWIN_POLL_Done        - Some other routine has done this
  547. HASWIN_POLL_poll_RAMrx  -
  548. HASWIN_POLL_poll_RAMtx  - 
  549.  
  550.  
  551.  
  552.  
  553.         The routine "haswin_poll()" is the called by a user program in order
  554. to make the HASWIN library operate.  Once "haswin_poll()" has been called
  555. the library takes over the operation of the WIMP environment and calls the
  556. routines within the user program as it sees fit.  It will, however, always
  557. return to the user program at intervals so that it can either be called
  558. again, or to allow the user program to perform its own processing.  Since
  559. the WIMP is a cooperative multi-tasking system haswin_poll() might not
  560. return for some time if the user program gets "swaped" to allow some other
  561. task to run.  The function is defined as...
  562.  
  563. int     haswin_poll(void);
  564.         - Call the SWI WIMP_Poll and call the HASWIN library to perform
  565.           any required functions.
  566.         - Returns HASWIN_TRUE for successful completion of the action, or
  567.           HASWIN_FALSE to indicate some problem.  Under usual conditions
  568.           the return value is ignored.
  569.  
  570.         Code of the form...
  571.  
  572.         /*
  573.          *      perform once off startup code, setup windows, icons, menus
  574.          *      pointers, etc. and inform HASWIN of routines to handle each
  575.          *      WIMP operation.
  576.          */
  577.         haswin_setuserpollroutine(userpoll);
  578.         for (;;) {
  579.                 haswin_poll();
  580.                 /*
  581.                  *      perform some regular processing
  582.                  */
  583.         }
  584.  
  585. ...is usually the way a user program interfaces HASWIN to its own code.
  586.  
  587.  
  588. Null_Reason_Code         ( 0)
  589. Redraw_Window_Request    ( 1)
  590. Open_Window_Request      ( 2)
  591.  
  592. Close_Window_Request     ( 3)
  593.         - If the window to be closed is not in the HASWIN active windows
  594.           list HASWIN takes no action except to call the user routine with
  595.           the reason code HASWIN_POLL_Close, if one is defined.
  596.  
  597. Pointer_Entering_Window  ( 4)
  598.         - If the window to be entered is not in the HASWIN active windows
  599.           list HASWIN takes no action except to call the user routine with
  600.           the reason code HASWIN_POLL_Entering, if one is defined.
  601.  
  602. Pointer_Leaving_Window   ( 5)
  603.         - If the window to be entered is not in the HASWIN active windows
  604.           list HASWIN takes no action except to call the user routine with
  605.           the reason code HASWIN_POLL_Leaving, if one is defined.
  606.  
  607. Mouse_Click              ( 6)
  608.         - If the window where the mouse operation occured is not in the
  609.           HASWIN active windows list HASWIN takes no action except to call
  610.           the user routine with the reason code HASWIN_POLL_Mouse, if one
  611.           is defined.
  612.  
  613. User_Drag_Box            ( 7)
  614.         - If the window where the drag operation occured started not in the
  615.           HASWIN active windows list HASWIN takes no action except to call
  616.           the user routine with the reason code HASWIN_POLL_Drag, if one
  617.           is defined.
  618.         - If an icon is being dragged and the icon has a dragroutine() then
  619.           call the dragroutine, and if it returns HASWIN_FALSE no further
  620.           action is performed.
  621.         - Otherwise if the user routine is defined it is called with the
  622.           reason code HASWIN_POLL_Drag, and if it returns HASWIN_FALSE no
  623.           further action is performed.
  624.         - Otherwise clear the drag box away.
  625.  
  626. Key_Pressed              ( 8)
  627.         - If the window that was the input focus when the key was pressed
  628.           is not in the HASWIN active windows list HASWIN takes no action
  629.           except to call the user routine with the reason code
  630.           HASWIN_POLL_Key, if one is defined.
  631.         - Otherwise If the key pressed was <Return> use that as if the
  632.           SELECT button was pressed.
  633.         - If the key pressed was F1 to F9 then look for the 0 to 8th icon
  634.           in the window and pretend that the SELECT button was pressed.
  635.         - If the user routine is defined it is called with the reason code
  636.           HASWIN_POLL_Key, and if it returns HASWIN_FALSE no further
  637.           action is performed.
  638.         - Pass the key on by calling the SWI HASWIN_Process_key.
  639.  
  640. Menu_Selection           ( 9)
  641.         - If the window that the menu was generated from is not in the 
  642.           HASWIN active windows list HASWIN takes no action except to call
  643.           the user routine with the reason code HASWIN_POLL_Menu, if one is
  644.           defined.
  645.  
  646. Scroll_Request           (10)
  647.         - If the window to be scrolled is not the HASWIN active windows list
  648.           HASWIN takes no action except to call the user routine with the
  649.           reason code HASWIN_POLL_Scroll, if one is defined.  Otherwise the
  650.           user routine is called with the reason code HASWIN_POLL_Scroll,
  651.           if one is defined, and if it returns HASWIN_FALSE no further
  652.           action is processed.  Otherwise the new window scroll position
  653.           is calculated.  The scroll amounts are either obtained from the
  654.           "pagex", "pagey", "scrollx", and "scrolly" fields of the window
  655.           structure or, if these are 0, default scroll amounts are used.
  656.           The default is to page scroll by one current screen width or
  657.           hieght and to line scroll by the size of one character in the
  658.           system font.  No alignment of text characters to the top or
  659.           bottom of the window work area is done.  After this calculation
  660.           the user routine is called again, but this time with the reason
  661.           code HASWIN_POLL_Scrolled, if one is defined, and if it returns
  662.           HASWIN_FALSE no further action is processed.  Otherwise the
  663.           openroutine() for the window is called and if that returns
  664.           HASWIN_FALSE no further action is processed.  Otherwise the
  665.           window is reopened at the new position.
  666.  
  667. Lose_Caret               (11)
  668.         - If the window loosing the caret is not the HASWIN active windows
  669.           list HASWIN takes no action except to call the user routine with
  670.           the reason code HASWIN_POLL_Menu, if one is defined.
  671.           Otherwise the user routine is called with the reason code
  672.           HASWIN_POLL_Lose_Caret, if one is defined, and if it returns
  673.           HASWIN_FALSE no further action is processed.
  674.  
  675. Gain_Caret               (12)
  676.         - If the window loosing the caret is not the HASWIN active windows
  677.           list HASWIN takes no action except to call the user routine with
  678.           the reason code HASWIN_POLL_Menu, if one is defined.
  679.           Otherwise the user routine is called with the reason code
  680.           HASWIN_POLL_Gain_Caret, if one is defined, and if it returns
  681.           HASWIN_FALSE no further action is processed.
  682.  
  683. User_Message             (17)
  684.         -
  685.  
  686. User_Message_Recorded    (18)
  687.         -
  688.  
  689. User_Message_Acknowledge (19)
  690.         -
  691.  
  692. All other codes
  693.         - If HASWIN receives a reason code from SWI WIMP_Poll that it does
  694.           not understand it is passed unchanged to the user routine if one
  695.           is defined.
  696.  
  697.  
  698.  
  699.