home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / utility / wnx1091 / xes_dev1.doc < prev    next >
Text File  |  1991-10-20  |  35KB  |  730 lines
  1.                 XES:  eXtended Environment System
  2.                 =================================
  3.  
  4.  
  5.  
  6.             Official Documentation for XES Programmers
  7.                           October 20,1991
  8.  
  9.                                 by
  10.  
  11.                       Charles H. Medley, Jr.
  12.                          ENiGMA Software
  13.                      659 Kennedy Street, N.E.
  14.                      Washington, D.C.  20011
  15.                           (202) 636-9078
  16.  
  17.  
  18.  
  19.                          Simple Overview
  20.                          +-+-+-+-+-+-+-+
  21.  
  22.      The XES consists of two parts:
  23.  
  24.           o    The TRAP #5 Dispatcher.
  25.  
  26.           o    The User Mode Handler.
  27.  
  28.  
  29.      Every XES function is accessed by passing parameter(s) on the 
  30. stack,  and then doing a TRAP #5.   To allow for full independence 
  31. between copies of Wind-X,  and their utilities, the TRAP #5 simply 
  32. "fixes"  up the parameters and passes them to a subroutine I  call 
  33. the User Mode Handler.
  34.  
  35.      The  purpose  of the User Mode Handler is to  replace  large, 
  36. memory hogging subroutines that would be required for almost every 
  37. WNX application with a simple call.
  38.  
  39.      This  allows the XES to serve as a way to do complicated  AES 
  40. functions,  and  replace large subroutines that would normally  be 
  41. needed  within an application with one call.   A good  example  of 
  42. this  is  XES_REDRAW (43) which can handle window redraws  for  an 
  43. XES-based application,  with just a few lines of code.   I will go 
  44. into detail on how each call works later on in this document.
  45.  
  46.      The method used by the XES is this:
  47.  
  48.           o    Wind-XES does a JSR into the WNX application to
  49.                begin to run it.
  50.  
  51.           o    When  the WNX does a call to the XES (via TRAP  #5) 
  52.                it's execution is stopped, and the system is put in 
  53.                supervisor  mode.   The data and address  registers 
  54.                are saved (A1-A6 and D3-D7 are saved).
  55.  
  56.           o    The  Trap  Handler adjusts the value on  the  stack 
  57.                where  the RTE is to occur (from the TRAP  #5)  and 
  58.                saves  the  RTE address for use by  the  User  Mode 
  59.                Handler,  and  then does an RTE back to the  parent 
  60.                copy of Wind-X's User Mode Handler after setting.
  61.  
  62.           o    The   User  Mode  Handler  performs  the   function 
  63.                requested and JSRs back into the WNX's code at  the 
  64.                location that the TRAP #5 would have RTE'd back to.
  65.                This  means  that  you should NOT try  to  fix  the 
  66.                stack  up,  like  you  do after a  normal  call  to 
  67.                GEMDOS,  because the User Mode Handler has  already 
  68.                dealt with that.   The original A1-A6/D3-D7  values 
  69.                are restored (as of 9/09/90 version  incarnation of
  70.                the XES).
  71.  
  72.           o    This  occurs  over and over until  either  the  WNX 
  73.                process   hits   an  RTS  that   doesn't   have   a 
  74.                corresponding BSR/JSR within it's code, or until it 
  75.                reaches a XES_SUBMIT call.  
  76.  
  77.      One  thing  to note is that all data  and  address  registers 
  78. should  be assumed to be unknown values when a WNX is first  JSRed 
  79. to.   This may change by the time Wind-XES makes it to market, but 
  80. for the most part, this isn't needed.  Also, note that the  SR  is
  81. not properly restored after the TRAP #5 call, so don't count on 
  82. the CCR remaining unchanged after a TRAP #5 as you can with other 
  83. TRAPs.  
  84.  
  85.  
  86.  
  87.  
  88.                      How To Write For the XES
  89.                      +-+-+-+-+-+-+-+-+-+-+-+-
  90.  
  91.      A WNX application has to do two things first:
  92.  
  93.           1)   It  must  call  XES_INIT  with  the  address  of  a 
  94.                parameter block of the form:
  95.  
  96.      Name                Size           Purpose
  97.      ----                ----           -------
  98.      WNX_id              (word)         one word I.D. number, 
  99.                                         assigned by the XES.
  100.      WNX_idname          (16 bytes)     unique 16 byte identifier
  101.                                         set by WNX.
  102.      WNX_apid            (word)         application I.D. of parent 
  103.                                         copy of Wind-X
  104.      WNX_grafhandle      (word)         graphics handle of parent
  105.      WNX_global          (long)         ptr to parent's GLOBAL
  106.                                         array
  107.      WNX_vdiparams       (long)         ptr to parent's VDI
  108.                                         array
  109.      WNX_aesparams       (long)         ptr to parent's AES array
  110.      WNX_messagebuf      (long)         ptr to parent's message
  111.                                         buffer
  112.      WNX_in              (8 words)      WNX_in array
  113.      WNX_out             (8 words)      WNX_out array
  114.      WNX_flags           (word)         event flags (a la the AES
  115.                                         call evnt_multi)
  116.      WNX_link            (long)         address for resuming
  117.                                         execution (used by XES)
  118.      WNX_tcount          (word)         timer count in 20ms 
  119.                                         between events.
  120.      WNX_troutine        (long)         address of TIMER routine
  121.      WNX_mroutine        (long)         address of MESSAGE routine
  122.      WNX_broutine        (long)         address of BUTTON routine
  123.      WNX_kroutine        (long)         address of KEYBOARD
  124.                                         routine
  125.      WNX_rroutine        (long)         address of REDRAW routine
  126.      WNX_termroutine     (long)         address if WNX terminates 
  127.                                         (this    runs   after    a 
  128.                                         WNX_flush call!)
  129.  
  130.                The values for  WNX_id,  WNX_apid,  WNX_grafhandle, 
  131.                WNX_global,      WNX_vdiparams,      WNX_aesparams, 
  132.                WNX_messagebuf,  and  WNX_link are set by  the  XES 
  133.                immediately after this call.
  134.  
  135.           2)   Now,  the WNX must do a XES_RSRCINIT with a pointer 
  136.                to a binary resource that has yet to be fixed up to 
  137.                the proper screen coordinates.  Because the GEM AES 
  138.                is not friendly to programmers who design resources 
  139.                in  color,  various options are allowed with a  one 
  140.                word  flag  which permits you to determine  if  the 
  141.                resource  is  scaled  in any way  relative  to  the 
  142.                screen font size (which is how GEM does it), and if 
  143.                so,  how.   This  first call to  XES_RSRCINIT  will 
  144.                initialize  the resource that will be displayed  in 
  145.                the main Wind-XES window.
  146.  
  147.                Note:  You may also use a resource  that  has  been 
  148.                previously fixed, but the  provision  for  this  is
  149.                not fully implemented as of 8/23/91.   Also,  Laser 
  150.                C's RCP.PRG can generate a  .C  file  that  is,  in 
  151.                essence, a .RSC file that you can "imbed" in your C 
  152.                applications.  It will need a  "fixup",  so  simply 
  153.                pass a pointer to the array it defines,  and  Wind-
  154.                XES will work everything out...
  155.  
  156.           3)   At this point,  the WNX application can do anything 
  157.                it wishes (i.e.  initialize system variables,  find 
  158.                out information about the screen,  etc...) and even 
  159.                call  the XES until it does a  XES_SUBMIT.   It  is 
  160.                good  practice to do the XES_SUBMIT and NOT an  RTS 
  161.                on this part of the code.   The WNX application  is 
  162.                required  to  supply pointers to  subroutines  that 
  163.                should  be executed by Wind-XES  when  events  that 
  164.                it  is looking for occur BEFORE the  XES_SUBMIT  is 
  165.                done.   By  making  the processing the  GEM  events 
  166.                modular  this helps improve  execution  speed,  and 
  167.                makes life easier on WNX programmers,  particularly 
  168.                those who are writing piecemeal.
  169.  
  170.      For  more  information on  the  XES_INIT,  XES_RSRCINIT,  and 
  171. XES_SUBMIT, consult the section on XES functions.
  172.  
  173.      As  a  note  to more sophisticated  (and  usually  dangerous) 
  174. programmers,  there  are  ways to determine if an  application  is 
  175. running  as  a  WNX,  as an ACC or as  a  GEM  program.   When  an 
  176. application   is  a  desk  accessory,   the  value  P_PARENT   (at 
  177. basepage+36 in your application) will be 0.  For WNX applications, 
  178. this points to the basepage of the parent copy of Wind-X, which is 
  179. what is running the WNX as a child process.   However,  to  ensure 
  180. that  you  can tell it is not running as a GEM  program,  you  can 
  181. simply  look  at  P_RESERVED (basepage+40) where you  will  see  a 
  182. longword containg the ASCII equivalent of the string "XES".
  183.  
  184. (NOTE:  Atari has officially changed  this.   The  current  method 
  185. would be to check to see if your P_RESERVED (basepage+40)  is  the
  186. longword $00584553 ("XES"), and if it is, you are a .WNX.  If not, 
  187. then check the current value of A0, and if A0 is null, you  are  a 
  188. .PRG, otherwise, you are an .ACC.  This method won't  work  inside 
  189. the Laser C shell, though.)
  190.  
  191.  
  192.                 Handling Events the ENiGMA Way...
  193.                 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  194.  
  195.      If  you look at the structure of the parameter block used  in 
  196. XES_INIT,  you see that you have to supply pointers to routines to 
  197. be  executed on events.   As stated earlier,  you must assume  all 
  198. data and address registers are unknown when these routines start!
  199. (NOTE:  This may change by release day!)
  200.  
  201.      The way this works is that Wind-XES catches events, and first 
  202. it handles any of its  own  (i.e.,  window  redraws  of  the  main 
  203. Wind-XES window, etc...), and then begins to dispatch to  each  of
  204. its children, which can then take action on the events.
  205.  
  206.      To  aid  the  WNX programmer,  Wind-XES passes some  valuable 
  207. information,  depending  on  the event type,  to the  WNX  in  the 
  208. WNX_out array...
  209.  
  210.  
  211.  
  212.      "Link" Events
  213.      *-*-*-*-*-*-*
  214.  
  215.           To  get access to these,  set bit #6 of  the  WNX_flags.  
  216.      This  feature  should  be able to work,  but has  yet  to  be 
  217.      tested.   If you are writing a WNX,  try to avoid using  this 
  218.      call until we have verified it is 100% working!
  219.  
  220.           "Link"  allows you to recieve information as if you  had 
  221.      done an EVNT_MULTI.   You recieve information in your WNX_out 
  222.      array giving your information about the type of event(s) that 
  223.      occurred.
  224.  
  225.      WNX_out+0.W    =    bits 0-5 tell which events occurred.
  226.      WNX_out+2.W    =    mouse x coordinate at time of event.
  227.      WNX_out+4.W    =    mouse y coordinate "  "    "  "    .
  228.      WNX_out+6.W    =    the button state.
  229.      WNX_out+8.W    =    states  of  the  alternate,   shift,  and 
  230.                          control keys.
  231.      WNX_out+10.W   =    number of times left button was clicked.
  232.      WNX_out+12.W   =    key scan code for keyboard event.           
  233.      WNX_out+14.W   =    the handle of the active GEM window  (the 
  234.                          one on top!).   The handle is negated  if 
  235.                          the window is NOT the Wind-XES window,and 
  236.                          and is  positive if it  is  the  Wind-XES
  237.                          window.
  238.  
  239.  
  240.           "Link" mode also tells Wind-XES to turn  operation  over
  241.      to the WNX application at the address contained in  WNX_link.  
  242.      This  is  so  that a programmer can  dynamically  change  the 
  243.      "return" address without mucking with the stack.
  244.  
  245.           A "Link" mode call should not terminate with an RTS, but 
  246.      instead, with a XES_SUBMIT, which places the address that the 
  247.      TRAP #5 would have RTE'd back to in WNX_link.
  248.  
  249.           Be cautious with "link" mode!
  250.  
  251.  
  252.  
  253.      Keyboard Events
  254.      *-*-*-*-*-*-*-*
  255.  
  256.           Bit  0 of the WNX_flags must be set to be able to  check 
  257.      for keyboard events.  The WNX application will get control of 
  258.      the CPU,  and the routine pointed to by WNX_kroutine will  be 
  259.      JSRed to.
  260.  
  261.      Parameters passed to the WNX are:
  262.  
  263.      WNX_out+0.W    =    scan code of key that was pressed.
  264.      WNX_out+14.W   =    the handle of the active GEM window  (the 
  265.                          one on top!).   The handle is negated  if 
  266.                          the window is NOT  the  Wind-XES  window,
  267.                          and is positive if  it  is  the  Wind-XES
  268.                          window.
  269.  
  270.           The keyboard routine should terminate with either an RTS 
  271.      or a XES_SUBMIT.
  272.  
  273.  
  274.  
  275.      Mouse Button Events
  276.      *-*-*-*-*-*-*-*-*-*
  277.  
  278.           Bit  1 of WNX_flags must be set to handle  mouse  button 
  279.      events.  The routine pointed to by WNX_broutine is JSRed to.
  280.  
  281.           Due to an idiosyncracy of Wind-X,  you can only wait for 
  282.      a  "left mouse button pressed" event.   This limits you to  a 
  283.      "one button" mouse for this kind of input.   Future revisions 
  284.      may change this but no such plan has been implemented.
  285.  
  286.      WNX_out+0.W    =    mouse button state.
  287.      WNX_out+2.W    =    x coordinate of mouse.
  288.      WNX_out+4.W    =    y coordinate of mouse.
  289.      WNX_out+6.W    =    number of times mouse entered the state.
  290.      WNX_out+8.W    =    the states of the alternate,  control and 
  291.                          shift keys during the event.
  292.      WNX_out+10.W   =    index  of  the object  clicked  on  (this 
  293.                          applies only to the resource displayed in 
  294.                          the   main   Wind-XES window,    and   no 
  295.                          "simulated"   FORM_DO   call   has   been 
  296.                          performed.   Call  XES_FORMDO  with  this 
  297.                          value in WNX_in+6.W to perform a FORM_DO- 
  298.                          like action.
  299.      WNX_out+14.W   =    the handle of the active GEM window  (the 
  300.                          one on top!).   The handle is negated  if 
  301.                          the window is NOT  the  Wind-XES  window,
  302.                          and is positive if  it  is  the  Wind-XES
  303.                          window.
  304.  
  305.           You can use mouse button events to handle events for not 
  306.      just the main Wind-XES window, but a  window  opened  by  the
  307.      WNX.  Simply do  an XES_XFORMDO for the window  you  need  to
  308.      know about!
  309.  
  310.  
  311.  
  312.      Message Events
  313.      *-*-*-*-*-*-*-
  314.  
  315.           Bit  4 must be set in WNX_flags for the WNX  to  process 
  316.      GEM  messages.   The  routine pointed to by  WNX_broutine  is 
  317.      JSRed to.
  318.  
  319.           This  is  very important:   A WNX must never  alter  the 
  320.      contents  of the message buffer (the address of which  is  in 
  321.      WNX_messagebuf) because other WNXes may have a need to  check 
  322.      for events!
  323.  
  324.           With this, you can check for GEM events, and even send a 
  325.      message  to  another resident  application,  including  other 
  326.      WNXes (provided they, too, are looking for messages).
  327.  
  328.      WNX_out+0.W    =    RESERVED (usually 1)
  329.      WNX_out+2.W    =    type of message.
  330.      WNX_out+14.W   =    the handle of the active GEM window  (the 
  331.                          one on top!).   The handle is negated  if 
  332.                          the window is NOT  the  Wind-XES  window,
  333.                          and is positive if it is the Wind-XES
  334.                          window.
  335.  
  336.  
  337.  
  338.      Timer Events
  339.      *-*-*-*-*-*-
  340.  
  341.           Bit 5 must be set for a timer event to be processed by a 
  342.      WNX.  The routine pointed to by WNX_troutine is JSRed to.
  343.  
  344.           A  WNX  can  wait for a timer event  for  no  less  than 
  345.      20ms,  which  is the finest timer event possible on  the  ST.  
  346.      There are no guarantees by either GEM,  the AES,  or the  XES 
  347.      that exactly 20ms has elapsed between calls.   In  fact,  one 
  348.      should  check the system clock (via the BIOS) or  install  an 
  349.      interrupt (which should NEVER call the XES!) to handle  time-
  350.      critical code...
  351.  
  352.      (IMPORTANT NOTE:  Never give less than a 1/5  second (i.e., a
  353.      WNX_tcount of 10) delay between timer events  when your timer
  354.      routine is calling GEMDOS, BIOS or XBIOS.   Right  now,  some 
  355.      testing has indicated a problems occurring when programs  are
  356.      run while such tight time constraints are being placed on the
  357.      system.  Case in point is the sample code  provided  for  the
  358.      BIN2C.WNX file converter, which does disk writes on the timer
  359.      routine.  On my 16mhz 68000 machine, when WNX_tcount  is  set     
  360.      to  10,  it  works  reliably  with  programs  being  run  and 
  361.      terminate in rapid succession (using DC Desktop or the normal
  362.      ST Desktop on TOS 1.2.).  With a WNX_tcount of 1, the program
  363.      will crash under the same conditions.  This is why  BIN2C.WNX
  364.      is not very fast... <grin>)
  365.  
  366.           When  a WNX is given control after a  timer  event,  the 
  367.      following parameters are passed:
  368.  
  369.      WNX_out+0.W    =    reserved  (usually 1)
  370.      WNX_out+2.L    =    number  of timer events processed by  the 
  371.                          parent  copy  of  Wind-XES since it   was 
  372.                          launched.   (naturally,   limited  to  32
  373.                          bits!)
  374.      WNX_out+14.W   =    the handle of the active GEM window  (the 
  375.                          one on top!).   The handle is negated  if 
  376.                          the window is NOT  the  Wind-XES  window, 
  377.                          and is positive if  it  is  the  Wind-XES
  378.                          window.
  379.  
  380.  
  381.  
  382.      The Purposes of WNX_rroutine and WNX_termroutine
  383.      *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-
  384.  
  385.           WNX_rroutine is automatically JSRed to if it is nonzero. 
  386.      No bits in WNX_flags need be set.   WNX_rroutine is  executed 
  387.      every time the main Wind-XES window is redrawn, and it should 
  388.      not  do  an XES_DRAW of an object in that window  during  the 
  389.      execution  of  WNX_rroutine.   No parameters  are  placed  in 
  390.      WNX_out.
  391.  
  392.           A good use for WNX_rroutine is checking things that  may 
  393.      change.  The ENiGMA Control Panel checks both the system time 
  394.      and  date and pops in to supervisor mode to check the  system 
  395.      palette in order to accurately represent any changes to these 
  396.      values.
  397.  
  398.           WNX_termroutine is run when a WNX is about to  terminate 
  399.      and  get  flushed from memory.   As stated  earlier  in  this 
  400.      documentation,  it should be used for housekeeping  purposes, 
  401.      like restoring stolen vectors,  etc...   However,  if D0.L is 
  402.      equal  to  the ASCII value of the 24 bits that  make  up  the 
  403.      string "XES",  the WNX is kept in memory, but  Wind-XES  will
  404.      act oblivious to it.   As of 9/09/90,  this  feature  is  not
  405.      fully implemented, but will be at the time of release.      
  406.  
  407.  
  408.      
  409.           
  410.                 XES Functions (08/23/91 Revision)
  411.                 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  412.  
  413.      All XES functions, excluding XES_INIT are performed like  so:
  414.  
  415.                move.w    <function_id>,-(a7)
  416.                move.w    #-1,-(a7)
  417.                trap      #5
  418.  
  419.      ...where the <function_id> is the number corresponding to the 
  420. XES function you want.  XES_INIT works like so:
  421.  
  422. xes_init       move.l    <pointer to parameter blk>,-(a7)
  423.                move.w    #0,-(a7) 
  424.                trap      #5
  425.  
  426.      The following are descriptions of the various XES  functions.  
  427. The descriptions are in a format, like this:
  428.  
  429. <name of function>  (<function number (decimal)>) 
  430. <WNX_in parameters>
  431. <WNX_out parameters>
  432. <description of the function>
  433.  
  434.  
  435.  
  436. XES_submit          (-1)
  437. in:  none.
  438. out: none.
  439.  
  440.      This  allows  a WNX to stop execution of itself and  to  turn 
  441. over  control to the XES so that other processes can get a  chance 
  442. to  run.   In most cases,  an RTS without a corresponding  JSR/BSR 
  443. would  suffice,  but  you  should use XES_submit  after  your  WNX 
  444. initialization code.
  445.  
  446.  
  447.  
  448. XES_init            (0)
  449. in:  none.
  450. out: none.
  451.  
  452.      This initializes the XES parameter block of your  application 
  453. and  makes sure it is recognized by the system.   You  should  NOT 
  454. have any code preceding this,  as your program may be flushed  due 
  455. to any number of reasons (i.e.  insufficient RAM,  conflicts  with 
  456. other application's interfaces, etc...).
  457.  
  458.  
  459.  
  460. XES_rsrcinit        (1)
  461. in:  WNX_in+0.W     =    non-zero causes .RSC to be fixed up.
  462.      WNX_in+2.W     =    type of fixup.
  463.                               0    =  no scaling.
  464.                               1    =  scale pixel coords only.
  465.                               2    =  scale both pixel and
  466.                                       character coords.
  467.      WNX_in+4.L     =    if WNX_in+0 = 0, a pointer to the binary 
  468.                          resource to be fixed up, or else it is a 
  469.                          pointer to a structure like this:
  470.  
  471.                          pointer to a .RSC header
  472.                          pointer to the first tree in the .RSC
  473.  
  474.                          Where the .RSC  header  is  of  the  same 
  475.                          format as the header of a binary resource 
  476.                          file (.RSC).
  477.  
  478. out: WNX_out+0.W    =    number of trees in resource,  or 0 if the 
  479.                          call failed.
  480.      WNX_out+2.L    =    address of first tree in resource.
  481.      WNX_out+6.L    =    address of the tree list in resource.
  482.  
  483.      The  first  time  this  call  is  made,  it  should  be  done 
  484. immediately after a XES_init.  This first call tells Wind-XES what 
  485. the resource that it will  be  displaying  in  the  main  Wind-XES
  486. window for this WNX will be.   When Wind-XES is loading a  utility
  487. in, it checks to see if it will fit  from  the  width  and  height 
  488. coordinates  of  the  largest  resource  tree  contained  in  that
  489. resource, and if there is not enough space in the Wind-XES window,
  490. the application  is  flushed  immediately.   Subsequent  calls  to
  491. XES_rsrcinit  can  be  used  to  initialize  resources  for  other
  492. purposes,  such as windows  (see Paint-X).
  493.  
  494.  
  495.  
  496. XES_sibling         (2)
  497. in:  WNX_in+0.L     =    pointer to 16 byte i.d. name field.
  498. out: WNX_out+0.W    =    number of WNXes in system with that  i.d. 
  499.                          name.
  500.      WNX_out+2.L    =    a  pointer  to  "tempbuf",  which  is  a 
  501.                          buffer containing a list of the matching 
  502.                          .WNXes  in the system.  The format of an
  503.                          entry in this structure is:
  504.  
  505.                          application i.d. of parent.W
  506.                          WNX i.d. of matching child.W
  507.  
  508.                          If both are null, you are at the  end  of 
  509.                          the "match" list.
  510.  
  511.      This function's sole purpose is to provide a way for a WNX to 
  512. find  out if multiple copies of itself have been  installed.   For 
  513. some  programs,  mainly vector stealers,  having  multiple  copies 
  514. installed  can create headaches.   All this function does is  find 
  515. out   how   many   copies   are   installed.    A   new   function 
  516. (WNX_inqsibling) will probably be added which returns  information 
  517. about each of the WNX processes that matches.
  518.  
  519.  
  520.  
  521. XES_mesagwrite      (4)
  522. in:  WNX_in+0.L     =   pointer to recipient list/ap_id of ACC to send to.
  523.      WNX_in+4.W     =   length of message (up to 256 bytes)
  524.      WNX_in+6.L     =   pointer to message
  525.  
  526. out: none.
  527.  
  528. The eXtended Environment System can allow a WNX to write messages
  529. selectively to another WNX process.  The recipient list 
  530. is a structure of the form:
  531.  
  532.      (parent's ap_id).W | (32  bit  bit  field,  representing  the
  533.      32 potential children of that parent).L
  534.  
  535. A set bit means to write to that child. 
  536.  
  537.  
  538.  
  539. XES_malloc          (38)
  540. in:  WNX_in+0.L     =    amount of memory to allocate
  541. out: WNX_out+0.L    =    0  if failed,  or location  of  allocated 
  542.                          RAM.
  543.  
  544.      This function is used in order to fix a bug in some revisions 
  545. of TOS that frees up memory allocated by a desk  accessory.   This 
  546. happens mainly when a DA (or WNX, for that matter) is trying to do 
  547. a M_ALLOC while a GEM program is running at the same  time.   When 
  548. GEMDOS does the M_ALLOC,  it incorrectly gives the "ownership"  of 
  549. that block of RAM to the GEM program.   This function is the  only 
  550. known  "illegal" call in Wind-X,  but it is necessary in order  to 
  551. prevent this GEMDOS bug from affecting program performance.
  552.  
  553.      To free up this RAM, simply use M_FREE (the GEMDOS call).
  554.  
  555.  
  556.  
  557. XES_flush           (39)
  558. in:  none.
  559. out: none.
  560.  
  561.      Tells the XES to terminate the execution of this application, 
  562. and to free up the memory used by it.  The WNX will still have the 
  563. WNX_termroutine  executed before being flushed,  so it can do  any 
  564. cleanup it finds necessary (i.e.,  restore altered system vectors, 
  565. close windows, etc...)
  566.  
  567.  
  568.  
  569. XES_genv            (40)
  570. in:  none.
  571. out: WNX_out+0.L    =    address of the Line-A structure.
  572.      WNX_out+4.L    =    ptr to virtual workstation attributes  (a 
  573.                          45 word structure).
  574.      WNX_out+8.W    =    screen width (in pixels).
  575.      WNX_out+10.W   =    screen height (in pixels).
  576.      WNX_out+12.W   =    X  scale of screen font to an 8x8  screen 
  577.                          font  (i.e.,  a 16x8 system  screen  font  
  578.                          would make this value 2.
  579.      WNX_out+14.W   =    Y  scale of screen font to an 8x8  screen 
  580.                          font.
  581.  
  582.      This  call  simply  lets  the WNX  know  about  the  system's 
  583. graphics capabilities.   You should note that the GEM work area is 
  584. not  the same as the screen size.   To avoid doing a  WIND_GET  to 
  585. find the work area on the desktop,  use XES_pwindow instead, since 
  586. during  the accessory loading process,  calling the AES  would  be 
  587. unpredictable  from  a  WNX  (and calling the  AES  during  a  WNX 
  588. initialization should be avoided!).
  589.  
  590.      The  scales of the screen fonts is handy for when you have  a 
  591. slider defined for a resource,  and the resource changes size  due 
  592. to the changes from an 8x8 screen font (color STs) to 8x16  screen 
  593. font  (monochrome).   This usually is a problem  for  applications 
  594. that have vertical sliders, and the problem occurs naturally under 
  595. GEM,  and is not limited to Wind-X.   (In fact, this is a neat fix 
  596. for it!)
  597.  
  598.  
  599.  
  600. XES_pwindow         (41)
  601. in:  none.
  602. out: WNX_out+0.W    =    X   coordinate  of  the   Wind-XES window 
  603.                          containing this application.
  604.      WNX_out+2.W    =    Y coordinate of the Wind-XES window.
  605.      WNX_out+4.W    =    W (width) of the Wind-XES window.
  606.      WNX_out+6.W    =    H (height) of the Wind-XES window.
  607.      WNX_out+8.W    =    X coord of desktop work area.
  608.      WNX_out+10.W   =    Y coord of "     "   "    " .
  609.      WNX_out+12.W   =    W of the   "     "   "    " .
  610.      WNX_out+14.W   =    H of the   "     "   "    " .
  611.  
  612.      The  purpose  of  this  function  was  mainly  to  discourage 
  613. programmers  from using the GEM AES WIND_GET call to find out  how 
  614. large   the   desktop   work  area  was   during   their   program 
  615. initialization,  which  may  occur  during  the  loading  of  desk 
  616. accessories.   AES calls by a WNX, from within Wind-XES running  a
  617. DA during the loading of DAs can cause unexpected problems.
  618.  
  619.      Basically,  WNX_out+8  to WNX_out+14 work like that  WIND_GET 
  620. call to find out the coordinates of the desktop work area.
  621.  
  622.      WNX_out+0  to  WNX_out+6 allow the application  to  find  the 
  623. coordinates of the main  window  used  by  the  copy  of  Wind-XES
  624. running it.
  625.  
  626.  
  627.  
  628. XES_draw            (42)
  629. in:  WNX_in+0.W     =    index of the starting object's depth  for 
  630.                          the XES_draw.
  631.      WNX_in+2.W     =    index of the ending object's depth.
  632. out: none.
  633.  
  634.      This  call  is used to allow a WNX to  redraw  its  interface 
  635. inside  of  the  Wind-XES window.   A good example of  this is the 
  636. TIME.WNX  program,  which  updates  even when  other  windows  are 
  637. overlapping it.  XES_draw is intelligent enough to output properly 
  638. even with other windows  overlapping  the  main  Wind-XES  window,
  639. which contains  the  resource you're  redrawing,  and  this allows
  640. for "background" output.
  641.  
  642.  
  643.  
  644. XES_redraw          (43)
  645. in:  WNX_in+0.W     =    handle of the window to redraw.
  646.      WNX_in+2.W     =    alignment flag.
  647.                               0 =  use ob_x and ob_y of resource.
  648.                              -1 = align to window's work area.  
  649.      WNX_in+4.L     =    address  of  the  resource  tree  to  use 
  650.                          during the redraw.
  651. out: none.
  652.  
  653.      This  is  a potent function which allows for quick  and  easy 
  654. redraws of windows that contain resource trees.   All you need  to 
  655. provide for the call is the handle of the window to redraw, a flag 
  656. fr alignment,  and the address of the tree to use for the  redraw.  
  657. There ARE limitations:
  658.  
  659.      o    Wind-XES currently  only draws 10 levels  deep  into  the 
  660.           resource tree.
  661.  
  662.      o    Wind-XES does not check for proper  pointers  and  values 
  663.           in this routine, so BE CAREFUL!
  664.  
  665.      These limitations may be removed by release day.
  666.  
  667.      The beauty of this call is that with six lines of  code,  you 
  668. can redraw a window.   For example,  in Paint-X, two resources are 
  669. initialized,  and  the second resource has a pointer to its  first 
  670. resource  tree called "rsrcptr2".   This is the resource with  the 
  671. icons showing the drawing tools, among other things.
  672.  
  673. xes_redraw_example
  674.                move.w    w_handle,WNX_in
  675.                move.w    #-1,WNX_in+2
  676.                move.l    rsrcptr2,WNX_in+4
  677.  
  678.                move.w    #43,-(a7)
  679.                move.w    #-1,-(a7)
  680.                trap      #5
  681.  
  682.      However,  you  should always have  your  WNX_mroutine,  which 
  683. catches  GEM  message  events ready to  catch  the  window  redraw 
  684. requests  from  GEM for your WNX's window if you wish to  do  this 
  685. properly,  as  Wind-XES  doesn't  notify  you  officially  of  the
  686. redraw (GEM does this very well,  you know!).    It  is  a  simple
  687. matter  to check  for the redraw message and to make sure the
  688. window  handle matches yours before calling XES_redraw.
  689.  
  690.  
  691.  
  692. XES_chrsrc          (50)
  693. in:  WNX_in+0.W     =    index of the new tree to use.
  694. out: WNX_out+0.W    =    the new tree's index (-1 if failed)
  695.  
  696.      This  call  allows you to use a resource that  has  different 
  697. resoruce  tree  "forks" within the Wind-XES main window.   A  good 
  698. example  is the ENiGMA Control Panel (ECP.WNX) which  has  several 
  699. levels the user can interact with, thanks to this call.
  700.  
  701.  
  702.  
  703. XES_stredit         (64)
  704. in:  WNX_in+0.W     =    handle of the window this resource is in.
  705.      WNX_in+2.L     =    address   of  resource  tree   containing 
  706.                          editable object.
  707.      WNX_in+6.W     =    index  of  the editable object  (must  be 
  708.                          F_text or F_boxtext!).
  709.      WNX_in+8.W     =    key   press  to  check  (uses   scan-code 
  710.                          method, like C_RAWIO and EVNT_KEYBD).
  711.      WNX_in+10.W    =    requested   cursor  position  inside   of 
  712.                          editable  field.  (-1  makes  the  cursor 
  713.                          position the first empty character inside 
  714.                          of the displayed string). 
  715. out: WNX_out+0.W    =    ASCII  character's  value.   -1  if  call 
  716.                          failed.
  717.      WNX_out+2.W    =    new cursor position (-1 if call failed).
  718.  
  719.      This  function lets the programmer use editable text  objects 
  720. within the framework of Wind-XES without halting  other processes.  
  721. Care  should  be  taken because the user  can  edit  multiple  WNX 
  722. processes  simulaneously  (i.e.,  the same keypress goes  to  four 
  723. different  applications!).   However,  the  advantage is  that  it 
  724. allows  all  of  the WNX tasks to  continue  running  without  the 
  725. interruption a GEM AES FORM_DO will cause.
  726.  
  727.      The limitation on this call is that the window containing the 
  728. editable  object MUST be on top.   This prevents  keypresses  from 
  729. going  to processes that are underneath the "active"  window,  and 
  730. makes handling the XES_stredit call much