home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / utility / wnx1091 / xes_dev2.doc < prev    next >
Encoding:
Text File  |  1991-08-24  |  10.5 KB  |  307 lines
  1.  
  2.                               XES Data Structures
  3.                               ===================
  4.  
  5. Assembler declaration of an XES parameter block structure:
  6.  
  7. WNX_id          ds.w    1                       one word I.D. number
  8. WNX_idname      ds.b    16                      unique 16 byte identifier
  9. WNX_apid        ds.w    1                       application I.D. of parent
  10. WNX_grafhandle  ds.w    1                       graphics handle of parent
  11. WNX_global      ds.l    1                       ptr to parent's GLOBAL array
  12. WNX_vdiparams   ds.l    1                       ptr to parent's VDI array
  13. WNX_aesparams   ds.l    1                       ptr to parent's AES array
  14. WNX_messagebuf  ds.l    1                       ptr to parent's message buffer
  15. WNX_in          ds.w    8                       WNX_in array (8 words)
  16. WNX_out         ds.w    8                       WNX_out array (8 words)
  17. WNX_flags       ds.w    1                       event flags {a la evnt_multi}
  18. WNX_link        ds.l    1                       address for resuming execution
  19. WNX_tcount      ds.w    1                       timer count in 20ms increments
  20. WNX_troutine    ds.l    1                       address of TIMER routine
  21. WNX_mroutine    ds.l    1                       address of MESSAGE routine
  22. WNX_broutine    ds.l    1                       address of BUTTON routine
  23. WNX_kroutine    ds.l    1                       address of KEYBOARD routine
  24. WNX_rroutine    ds.l    1                       address of REDRAW routine
  25. WNX_termroutine ds.l    1                       address if WNX terminates
  26.  
  27.  
  28.  
  29. C definition of an XES parameter block structure:
  30.  
  31. typedef struct {
  32.         int     WNX_id;                 /*      unique WNX application i.d. */
  33.         char    WNX_idname[16];         /*      unique 16 byte identifier */
  34.         int     WNX_apid;               /*      application I.D. of parent */
  35.         int     WNX_grafhandle;         /*      graf_handle of parent */
  36.         long    WNX_global;             /*      ptr to parent's GLOBAL array */
  37.         long    WNX_vdiparams;          /*      ptr to parent's VDI array */
  38.         long    WNX_aesparams;          /*      ptr to parent's AES array */
  39.         long    WNX_messagebuf;         /*      ptr to parent's message buffer */
  40.         int     WNX_in[8];              /*      WNX_in array (8 words) */
  41.         int     WNX_out[8];             /*      WNX_out array (8 words) */
  42.         int     WNX_flags;              /*      event flags like evnt_multi */
  43.         long    WNX_link;               /*      address for resuming execution */
  44.         int     WNX_tcount;             /*      timer count (in 20ms increments) */
  45.         void    (*WNX_troutine)();      /*      ptr to the routine to be run on timer event */
  46.         void    (*WNX_mroutine)();      /*      this is for the message routine */
  47.         void    (*WNX_broutine)();      /*      this is for the left button click routine */
  48.         void    (*WNX_kroutine)();      /*      this is for the keyboard routine */
  49.         void    (*WNX_rroutine)();      /*      this is the for redraws */
  50.         void    (*WNX_termroutine)();   /*      this is when the WNX terminates */
  51. }xesparmblk;
  52.  
  53.  
  54.  
  55. * NOTE:  WNX_in is defined in XESBLK.H as an array of 8 words, so
  56. * to access variables, remember that WNX_in+2 in assembler would
  57. * refer to WNX_in(1) in C!
  58.  
  59.  
  60.  
  61.                           XES Function Calls (8/23/91)
  62.                           ============================
  63.  
  64. XES_submit:
  65.         This allows a WNX written in a high level language to end a routine
  66.         without using the low-level assembler RTS function.  This function
  67.         is NECESSARY at initialization time for the WNX.
  68.  
  69.  C syntax:
  70.         xes_submit(&xparmblk)
  71.  
  72.  in:    none.
  73.  
  74.  out:   none.
  75.  
  76.  
  77.  
  78. XES_init:
  79.         Tells Wind-XES the pointer to this application's XES
  80.         parameter block.
  81.  
  82.  C syntax:
  83.         xes_init(&xparmblk)
  84.         
  85.  in:    d1 = ptr to new parmblk.
  86.  
  87.  out:   parmblk variables filled with all kinds of goodies.
  88.  
  89.  
  90.  
  91. XES_rsrcinit:
  92.        This fixes up a resource, if needed, and (most importantly)
  93.        corrects some data structures internal to Wind-XES.
  94.  
  95.  C syntax:
  96.         xes_rsrcinit(fixflag,scaleflag,treeptr,&xparmblk)
  97.  
  98.  
  99.  in:    WNX_in(0).W = fixup flag... if 0, no fixup of the .RSC is
  100.                      requested.
  101.         WNX_in(1).W = scaling (0 = none, 1 = normal GEM, 2 = perfect fix)
  102.         WNX_in(2).L = if WNX_in(0) = 0, ptr to binary resource file.
  103.                      if WNX_in(0) != 0, ptr to an area of memory that
  104.                      is identical to a .RSC file on a disk, with the
  105.                      exception that it already has been fixed up. 
  106.  
  107.  out:   WNX_out(0).W = number of trees in RSC.
  108.         WNX_out(1).L = address of first tree in RSC.
  109.         WNX_out(3).L = address of the tree list in RSC.
  110.  
  111.         or: 0 for all WNX_out(0) - WNX_out(3) if failed.
  112.  
  113.  
  114.  
  115. XES_sibling:
  116.         The eXtended Environment System's way to identify duplicates of
  117.         the same task by their unique i.d's.  WNX_in(0) should be a ptr to
  118.         the string to search for.
  119.         (NOTE:  Walk through WNX_secret!)
  120.  
  121.  C syntax:
  122.         xes_sibling(&string,&xparmblk)
  123.  
  124.  in:    WNX_in(0).L = ptr to 16 byte i.d.
  125.  
  126.  out:   WNX_out(0).W = number of matches.
  127.         WNX_out(1).L = ptr to tempbuf
  128.  
  129.  
  130.         
  131. XES_inqsibling:
  132.         The eXtended Environment System can allow a WNX to pick a sibling
  133.         find out information about.
  134.         
  135.         (NOTE:  Walk through WNX_secret!)
  136.  
  137.  in:    WNX_in(0).L = ptr to 16 byte i.d.
  138.         WNX_in(2).W = WNX i.d. number of process to inquire.
  139.  
  140.  out:   WNX_out(0).L = pointer to information about WNX.
  141.  
  142.  
  143.  
  144. XES_mesagwrite:
  145.         The eXtended Environment System can allow a WNX to write messages
  146.         selectively to another WNX process.
  147.  
  148.  C syntax:
  149.         xes_mesagwrite(&message,length,&recipientlist,&xparmblk)
  150.  
  151.  in:    WNX_in(0).L = pointer to recipient list/ap_id of ACC to send to.
  152.         WNX_in(2).W = length of message (up to 256 bytes)
  153.         WNX_in(3).L = pointer to message
  154.  
  155.  out:   none.
  156.  
  157.  
  158.  
  159. XES_malloc:
  160.         A way for a WNX to allocate RAM that will not be affected by
  161.         the main application's actions.  Under some revisions of TOS, when
  162.         a m_alloc is done, if a program is running, its process descriptor
  163.         is given to the OS.  This circumvents that problem.
  164.  
  165.  C syntax:
  166.         xes_malloc(amount,&xparmblk)
  167.  
  168.  in:    WNX_in(0).L = amount of RAM to reserve.
  169.  
  170.  out:   WNX_out(0).L = address of RAM in the system.
  171.  
  172.  
  173.  
  174. XES_flush:
  175.         A WNX can terminate itself.
  176.  
  177.  C syntax:
  178.         xes_flush(&xparmblk)
  179.  
  180.  in:    none.
  181.  
  182.  out:   none.
  183.  
  184.  
  185.  
  186. XES_genv:
  187.         Returns a pointer to the vq_extnd parameters in WNX_out(0), and
  188.         a ptr to the attributes of the current virtual workstation in
  189.         WNX_out(2).  This helps in finding out (or modifying) the current
  190.         settings of the ST without performing GEM calls.
  191.         (NOTE: this is the INQ_TAB area in the Line-A!)
  192.  
  193.  C syntax:
  194.         xes_genv(&xparmblk)
  195.  
  196.  in:    none.
  197.  
  198.  out:   WNX_out(0).L = address of Line-A structure (from DC.W $A000).
  199.         WNX_out(2).L = ptr to virtual workstation attributes (45 words).
  200.         WNX_out(4).W = screen width (in pixels).
  201.         WNX_out(5).W = screen height (in pixels).
  202.         WNX_out(6).W = X scale of screen font to 8x8 font.
  203.         WNX_out(7).W = Y scale of "   "   "    "  "    " .
  204.  
  205.  
  206.  
  207. XES_pwindow:
  208.         Tells WNX how large (and where!) the parent's Wind-X window is.
  209.  
  210.  C syntax:
  211.         xes_pwindow(&xparmblk)
  212.  
  213.  in:    none.
  214.  
  215.  out:   WNX_out(0).W = x coord of Wind-X window.
  216.         WNX_out(1).W = y  "    "    "     "    .
  217.         WNX_out(2).W = width of Wind-X window.
  218.         WNX_out(3).W = height of    "     "  .
  219.         WNX_out(4).W = x coord of desktop work area.
  220.         WNX_out(5).W = y coord of "    "   "    " .
  221.         WNX_out(6).W = width of desktop work area.
  222.         WNX_out(7).W = height of  "   "   "    " .
  223.  
  224.  
  225.  
  226. XES_draw:
  227.         The eXtended Environment System's objc_DRAW.  This is intelligent
  228.         enough to check the proper settings so as to update as neatly as
  229.         possible.  This can only be used on trees in the Wind-X window.
  230.  
  231.  C syntax:
  232.         xes_draw(startindex,endindex,&xparmblk)
  233.  
  234.  in:    WNX_in(0).W = index of starting object depth.
  235.         WNX_in(1).W = index of ending object depth.
  236.  
  237.  out:   none.
  238.  
  239.  
  240.  
  241. XES_redraw:
  242.         This is an objc_draw that is capable of drawing ANY resource
  243.         in relation to the window it is to be displayed in.
  244.  
  245.  C syntax:
  246.         xes_redraw(handle,aflag,treeptr,dflag,&xparmblk)
  247.  
  248.  in:    WNX_in(0).W = window to redraw
  249.         WNX_in(1).W = align to window x and y of work area if -1.
  250.         WNX_in(2).L = ptr to resource tree
  251.         WNX_in(4).W = 0 to just to align the .RSC, otherwise, draw.
  252.  
  253.  out:   none.   
  254.  
  255.  
  256.  
  257. XES_chrsrc:
  258.         This lets the application change the resource tree used in the
  259.         Wind-X window that it is using.
  260.  
  261.  C syntax:
  262.         xes_chrsrc(treenum,&xparmblk)
  263.         
  264.  in:    WNX_in(0).W = new tree index.
  265.  
  266.  out:   WNX_out(0).W = -1 if failed, or new tree index.
  267.         
  268.  
  269.  
  270. XES_stredit:
  271.         Automatically routes user input to a mini-text editor that
  272.         validates against a template for an editable text object.
  273.         This will take considerable amounts of sweat.
  274.  
  275.  C syntax:
  276.         xes_stredit(handle,treeptr,index,ch,curspos,&xparmblk)
  277.  
  278.  in:    WNX_in(0).W = handle of the window this stuff is in.
  279.         WNX_in(1).L = address of resource tree.
  280.         WNX_in(3).W = index of object (must be F_text or F_boxtext!)
  281.         WNX_in(4).W = character to try to use.
  282.         WNX_out(5).W = -1 or requested cursor position. 
  283.         (cursor position ranges from 0 to 4095)
  284.  
  285.  out:   WNX_out(0).W = -1 if character was invalid, or ASCII value.
  286.         WNX_out+1.W = -1 or cursor position.
  287.  
  288.  
  289.  
  290. XES_xformdo:
  291.         Tells Wind-X to handle the button press currently being
  292.         processed in a similar manner to form_do under the GEM AES.
  293.         By first checking the ob_flags we determine the exit conditions
  294.         and if the object is not exitable, we return a -1.
  295.         Users cannot interact with non-exitable or hidden objects!
  296.  
  297.         NOTE:  Objects can change their ob_state in this area!
  298.  
  299.  C syntax:
  300.         xes_xformdo(handle,treeptr,index,&xparmblk)
  301.  
  302.  in:    WNX_in(0).W = handle of window this tree is in. 
  303.         WNX_in(1).L = address of resource tree.
  304.         WNX_in(3).W = index of the object (-1 if unknown).
  305.  
  306.  out:   WNX_out(0).W = index of selected object
  307.