home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armbob / doc / Ref / LowLevel < prev    next >
Encoding:
Text File  |  1994-06-25  |  4.2 KB  |  125 lines
  1. ArmBob v.1.02 Reference                                GCW 06/06/94
  2.  
  3.          ----------------- LOW LEVEL ---------------
  4.  
  5. To access the operating system, the swi function is provided.
  6.  
  7. swi(x,r)   nil      x is either the SWI integer or the SWI's name
  8.                     as a string. r is a vector of at least 8 integers.
  9.     SWI x is called with register values given by the components 
  10.     r[0], r[1], ... r[7] and the function  returns with the returned 
  11.     values of the registers in the components of r.
  12.  
  13. Note that even though a SWI may pass no values in registers, it is
  14. necessary for the second argument of swi to be a vector with at least
  15. 8 components.
  16.  
  17. Wimp tasks may be started with the function wimp_init.
  18.  
  19. wimp_init(vn,name,mesg_list)   integer   vn is 100 times the version
  20.                                          of RISC OS being used, name is
  21.              the name of the wimp task, and mesg_list is a buffer,
  22.              given as a string or its integer address, containing the
  23.              messages, stored as words and terminated by 0, which the
  24.              task wishes to receive. The function returns the task handle
  25.              as an integer.
  26.  
  27. Programs running as wimp tasks must use the function wimp_closedown
  28. before terminating.
  29.  
  30. wimp_closedown()      nil     De-register the task with the task manager.
  31.  
  32. Look at the example of !Harness to see how the library Bob:h.wimp
  33. is used. If the function event_process is used, a separate call to
  34. wimp_closedown is not needed. Instead, a 20-element vector of message
  35. handlers should be defined, that return FALSE if the program is to
  36. quit, and TRUE otherwise.
  37.  
  38. To display an error message in a dialogue box use wimp_report.
  39.  
  40. wimp_report(s)    integer     Display string s in a dialogue box and
  41.                               return 0 if no key or mouse button is
  42.                               clicked, 1 if the OK button is selected,
  43.                               and 2 if the CANCEL button is selected.
  44.                                 
  45. To use a string as a buffer, say for a window or menu definition,
  46. a new syntactic form has been added. 
  47.  
  48.   in <buffer> put { item1 ; item2 ; ..... }
  49.  
  50. where <buffer> could be either a string or an integer address, and
  51. the items are either integers or strings. 
  52.  
  53. The following function is useful for putting null-terminated strings 
  54. into buffers and padding out with nulls to the next word boundary:
  55.  
  56.   align_null(s)
  57.   {
  58.    local len;
  59.    s += 0;
  60.    len = sizeof(s);
  61.    switch (len%4)
  62.    {
  63.     case 1: 
  64.       s += 0;
  65.     case 2:
  66.       s += 0;
  67.     case 3:
  68.       s += 0;
  69.       break;
  70.     }
  71.     return s;
  72.   } 
  73.  
  74. Sometimes one wishes to put into a buffer not a string but an indirect 
  75. reference to a string. For this the function @ has been provided.
  76.  
  77. @(s)  integer     Returns the address of the first (i.e 0-th) character
  78.                   in the string s.
  79.  
  80. As far as swi is concerned, string components of a register-vector
  81. are automatically converted to their integer addresses.
  82.  
  83. One may access the contents of an integer address or string using
  84. the "peek" functions $,£,`.
  85.  
  86. $(x)     string     Returns the string delimited by a character with
  87.                     an ASCII code less than 32 stored at the address x.
  88.  
  89. £(x)     integer    Returns as an integer the contents of the 4-byte 
  90.                     word at the address x or in the string x.
  91.  
  92. `(x)     integer    Returns as an integer the contents of the byte at
  93.                     the address x or in the string x.
  94.  
  95. If s is a string `(s) is the same as s[0] and £(s) is just
  96.  
  97.                 s[0] + s[1]<<8 + s[2]<<16 + s[3]<<24
  98.  
  99. It is worth mentioning that strings' contents automatically start on
  100. word boundaries.
  101.  
  102. To "poke" values into a string the functions $$, ££, `` are provided.
  103.  
  104. $$(x,s)    string   Place string s at address x, and return s.
  105.  
  106. ££(x,n)    integer  Place word n at address x, and return n.
  107.  
  108. ``(x,c)    integer  Place byte c at address x, and return c.
  109.  
  110. Example
  111. -------
  112.  
  113. A function to read the command line:
  114.  
  115.           getenv()
  116.           {
  117.            local r;
  118.            r = newvector(8);
  119.            swi("OS_GetEnv",r);
  120.            return($(r[0]));
  121.           }
  122.  
  123. See also Bob:h.hidden and Bob:h.chain, and the files in Bob:h.wimp.
  124.  
  125.               --------- END ----------