home *** CD-ROM | disk | FTP | other *** search
/ Computer Club Elmshorn Atari PD / CCE_PD.iso / pc / 0600 / CCE_0620.ZIP / CCE_0620.PD / WINX22 / WINXPROG.ENG < prev    next >
Text File  |  1993-10-17  |  11KB  |  232 lines
  1. IMPORTANT NOTES FOR WINX PROGRAMMERS (WINX 2.2 [10/17/1993])
  2.  
  3. - For the time of testing your own programs, WINX will be a helpful
  4.   tool and should always configured to display wrong parameters
  5.   for calls of the window library.
  6.   The only wind_xxx function which may be called with an invalid window
  7.   handle without getting an error report is wind_get(WF_OWNER).
  8.  
  9. - wind_get()/wind_set()
  10.   Both function now return 0 in case of an error, otherwise 1.
  11.   (up to now, the return value was ALWAYS 1)
  12.   An error is reported for example in the case, that a mode
  13.   WF_xxxx is not implemented or the call has been made with
  14.   an illegal window handle. If you start a program, you should
  15.   ALWAYS check, if wind_get() returns a sensible value. This could
  16.   be done by using the following:
  17.     #define WF_RETURN 1
  18.     retok = (wind_get( 0, WF_RETURN, &ign, &ign, &ign, &ign) == 0);
  19.   It is under all current GEM-Versions not critical to use an
  20.   unknown WF_-Mode, because it always has been ignored.
  21.  
  22. - wind_get( 0, WF_WINX(=22360='WX'), &version, &date, &func_h, &func_l)
  23.   Returns WF_WINX, if WINX >= 2.1 is installiert, otherwise 0.
  24.   version:  Bit [15..12]  beta indicator
  25.             Bit [11.. 8]  major version number (actually 2)
  26.             Bit [ 7.. 4]  minor version number (actually 1)
  27.             Bit [ 3.. 0] internal identifier
  28.   date:     creation date 
  29.   func_h/l: High and low word of the WINX cookie function address
  30.             (or NULL)
  31.  
  32. - wind_get( 0, WF_WINXCFG(=22361), &gmask, &gflags, &lmask, &lflags)
  33.   Returns the application specific configuration switches of the
  34.   currently running application.
  35.   gmask:   mask of the GLOBAL switches, which are supported by the
  36.            currently installed version of WINX
  37.   gflags:  the current setting of the GLOBAL switches. Applicable are
  38.            only those switches, which are set in mask (bit 0 - switch 1)
  39.   gmask:   mask of the LOCAL switches, which are supported by the
  40.            currently installed version of WINX
  41.   gflags:  the current setting of the LOCAL switches. Applicable are
  42.            only those switches, which are set in mask (bit 0 - switch 1)
  43.  
  44. - wind_get( rsv0, 22362-22400, &rsv2, &rsv3, &rsv4, &rsv5)
  45.   wind_set( rsv0, 22362-22400, rsv2, rsv3, rsv4, rsv5)
  46.   Undocumented and reserved WINX extensions.
  47.  
  48. - wind_get( 0, WF_TOP, &topwin, &owner, &belowwin)
  49.   Always returns the handle of the topmost window. If no window is
  50.   open, topwin will be 0.
  51.  
  52. - wind_get( win, WF_OWNER(=20), &owner, &isopen, &abovewin, &belowwin)
  53.   delivers informations of a window. the window even can be closed
  54.   (this means, it is not in the window stack) or even not exist (then
  55.   the function return 0).
  56.  
  57. - wind_set( win, WF_BOTTOM(=25), 0, 0, 0, 0)
  58.   WF_BOTTOM puts a window in the background in the window stack.
  59.   This must be an open window.
  60.  
  61. - wind_get( 0, WF_BOTTOM(=25), &bottomwin)
  62.   Returns the handle of the mostback window in the window stack.
  63.   If no window is open, bottomwin will contain -1 (NOWINDOW).
  64.  
  65. - wind_set( win, WF_BEVENT(=24), 0/1, 0, 0, 0)
  66.   WF_BEVENT takes care, that the owner of a window will not get
  67.   a WM_TOPPED-message, if somebody clicks in the window, while the
  68.   window is not active. Instead of this, a MU_BUTTON event is generated,
  69.   if the window owner has requested such an event with evnt_multi().
  70.  
  71. - wind_get( win, WF_BEVENT(=24), &v1, &v2, &v3, &v4)
  72.   Returns the BEVENT-state of the window in Bit 0 of v1.
  73.  
  74. - wind_get( win, WF_NEWDESK, &treehigh, &treelow, &treeroot)
  75.   Return the current background tree and its root object.
  76.   CAUTION: Up to now, it is not documented how this information
  77.   might be used.
  78.  
  79. - wind_get( win, WF_COLOR, &obj, &col1, &col2);
  80.   returns the colors of an objekts of the window frame.
  81.   CAUTION: obj must be passed in intin[ 2].
  82.  
  83. - wind_get( 0, WF_DCOLOR, &obj, &col1, &col2);
  84.   Returns the default color of an object of the window frame.
  85.   CAUTION: obj must be passed in intin[ 2].
  86.  
  87. - If you want to set an own background tree with wind_set( WF_NEWDESK )
  88.   you always should ask for position and dimension of its ROOT object
  89.   by calling
  90.     wind_get( 0, WF_WORKXYWH, &deskx, &desky, &deskw, &deskh)
  91.   (and NOT using WF_CURRXYWH)
  92.  
  93. - wind_set( win, WF_CURRXYWH, x, y,w, h), wind_open( win, x, y, w, h)
  94.   After these operations an application should always call
  95.     wind_get( win, WF_CURRXYWH, &currx, &curry, &currw, &currh)
  96.   to get the window rectangle, because there is a possibility that
  97.   the AES corrects the rectangle automatically.
  98.   
  99. - [WM_BOTTOMED(=33) apid 0 win 0 0 0 0]-message
  100.   This message is used by the WINX SCRENMGR to ask the application
  101.   to put its window in the background by calling
  102.     wind_set( win, WF_BOTTOM, 0,0,0,0).
  103.   After this action the application should NOT top one of its own
  104.   windows explicitly.
  105.   If an application has opened more than one window, and it doesn't
  106.   want to change the hierarchy of the windows, it should put ALL
  107.   windows in the background (it would be very practical, the AES
  108.   would have such a function...)
  109.  
  110. - programming an inverse 'change window' function
  111.   An application, which wants to give acess to such a funktion
  112.   should put its topmost window in the background with
  113.   WF_BOTTOM and then activate the now topmost window in its
  114.   own window list with WF_TOP (to make sure, that the application
  115.   always has full control of the keyboard input).
  116.  
  117. - inverse 'change window' function in applications
  118.   an application, which implements such a window should put its tomost
  119.   window to the back with WF_BOTTOM and then activate the topmost from
  120.   its own window list with WF_TOP (to make sure to still have the
  121.   key focus)
  122.  
  123. - [WM_UNTOPPED(=30) apid 0 win 0 0 0 0]-message
  124.   [WM_ONTOP(=31) apid 0 win 0 0 0 0]-message
  125.   Both messages are used to inform applications about changes in
  126.   the active window. WM_UNTOPPED is sent to the owner of the
  127.   previously active window after a window has been opened or
  128.   activated. WM_ONTOP is sent to the owner of the THEN (afterwards)
  129.   active window after closing or deactivating another window. At
  130.   the time where this message arrives, the window stack can
  131.   already have been again changed.
  132.  
  133. - wind_update() saved the list of applications waiting for update
  134.   control in a LIFO queue (this means the newest request for update
  135.   control will be fulfilled first.) WINX uses a FIFO.
  136.  
  137. - wind_update( BEG_UPDATE|0x100 );
  138.   wind_update( BEG_MCTRL|0x100 );
  139.   WINX implements the 'check and set' mode of MultiTOS AES 4.00.
  140.   This means, the control will only be taken, if not already another
  141.   application has control or is not owners of the application. If
  142.   control cannot be taken, the function returns 0.
  143.  
  144. - wind_update( END_xxxx) is now checked for underflow and generates an
  145.   alert on errors.
  146.  
  147. - wind_new() cleared all stacked update requests without any relief.
  148.   WINX sees wind_new() as a function to clear off after a crashed
  149.   application, so it only clears off THEIR update requests. The new
  150.   initialistion of the window management is performed under strict
  151.   UPDATE control, this guarantees, that windows do not disappear while
  152.   an accesory might have the update control.
  153.  
  154. - evnt_multi()
  155.   The realtime functions of WINX can only work, if with the usage of
  156.   MU_TIMER the timer value is set to a value greater than 0, because
  157.   evnt_multi() does not pass the requests to the kernal, but only reads
  158.   queued events.
  159.  
  160. - fill pattern base coordinate
  161.   If this switch is turned on WINX takes care that during the drawing
  162.   of a GEM-Object, the fill pattern will be drawn be relative to the left
  163.   topmost edge of the object (instead of being at 0/0 of the current
  164.   screen). Only THIS way, the redraw can be reduced to the parts of
  165.   the object, which have been invisible before a window has been
  166.   moved etc, so this is an elementary neccesity for realizing stuff
  167.   like realtime moving of filled objects and realtime scrolling.
  168.  
  169. - the value of the WINX cookie contains a pointer to a function, that
  170.   returns some information about some functionality of the current
  171.   version of WINX
  172.  
  173.     long cdecl winxfunc(short founcid,...);  /* PureC syntax) */
  174.  
  175.   The parameters are passed on the stack. The result is returned in
  176.   register D0. If not explicitly defined in a different way, a return
  177.   value of -1L means, that the function is not existing or is not
  178.   applicable in this moment.
  179.   Some functions are reserved for internal communication. No register
  180.   except D0 are changed after a function call.
  181.  
  182.   Some WINX internal variables can be accessed through TSR programs.
  183.   Detailed information can be supplied by the author.
  184.  
  185. - appl_getinfo()
  186.   WINX versions >= 2.2 offer the new AES call appl_getinfo().
  187.  
  188.     #define WF_WINX 22360
  189.     
  190.     int has_appl_getinfo( void)
  191.     /* Returns TRUE, if the AES has the appl_getinfo call */
  192.     {
  193.       static int hagi = -1;
  194.       int ign;
  195.  
  196.       if (hagi < 0) {      
  197.         hagi = ((_GemParBlk.global[ 0] >= 0x400) ||
  198.           (wind_get( 0, WF_WINX, &ign, &ign, &ign, &ign) == WF_WINX));
  199.       };
  200.       return( hagi);
  201.     } /* has_appl_getinfo */
  202.  
  203. - Overview of assignment of button clicks to applications
  204.  
  205.   mouse     ||    front window    | background window  | desktop  |   menu   |
  206.   click     ||  frame   work area |  frame   work area |          |          |
  207.   ----------++--------------------+--------------------+----------+----------+
  208.             ||                                                               |
  209.             ||                     AES versions <= 3.20                      |
  210.             ||                                                               |
  211.   left      || SCRENMGR   owner   | SCRENMGR  SCRENMGR |  owner   | SCRENMGR |
  212.             ||                    |                    |          |          |
  213.   right     ||  owner     owner   |   top       top    |   top    |   top    |
  214.             ||                                                               |
  215.             ||                     MultiTOS 1.01 (5/93)                      |
  216.             ||                                                               |
  217.   left      || SCRENMGR   owner   | SCRENMGR    sm/o   |  owner   | SCRENMGR |
  218.             ||                    |                    |          |          |
  219.   right     || SCRENMGR   owner   | SCRENMGR   owner   |  owner   | SCRENMGR |
  220.             ||                                                               |
  221.             ||                           WINX 2.1                            |
  222.             ||                                                               |
  223.   left      || SCRENMGR   owner   | SCRENMGR    sm/o   |  owner   | SCRENMGR |
  224.             ||                    |                    |          |          |
  225.   right  G2+|| SCRENMGR   owner   | SCRENMGR   owner   |  owner   | SCRENMGR |
  226.          G2-||  owner     owner   |   top       top    |   top    |   top    |
  227.   ----------++--------------------+--------------------+----------+----------+
  228.   
  229.                 top  =  owner of the top window
  230.                 sm/o =  SCRENMGR or owner (if BEVENT flag is set)
  231.                 G2   =  .GLOBAL switch 2 of WINX
  232.