home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / language / bob / doc / Tutorial / 04 < prev   
Encoding:
Text File  |  1994-07-14  |  5.4 KB  |  167 lines
  1. ArmBob v.1.02 Tutorial 4                               GCW 06/06/94
  2.  
  3. Wimp programming
  4. ----------------
  5. The example !Exec is provided, as a minimal framework to start
  6. with. It uses no classes. When double-clicked !Exec should put
  7. its icon on the iconbar. Its iconbar menu has two items - Info and
  8. Quit. If an object is dragged onto its iconbar icon, the file
  9. !Exec.exec will be obeyed, with the object's pathname as argument.
  10. Clicking Select or Adjust on the iconbar icon will open an Edit
  11. window on !Exec.exec. A directory !Exec.Lib is provided for tools
  12. to be used by !Exec. An example provided in !Exec.Lib is Templread,
  13. a template disassembler. It expects a template file as argument, 
  14. and when run opens an editable window on Bob source code defining 
  15. the template's windows. A window called, say xyz, is defined by the 
  16. data in a buffer called xyz_buf.
  17.  
  18. !Exec is an application whose !RunImage file has filetype BobProj.
  19. Shift-double-click it to see its contents.
  20.  
  21. Bob:h.wimp.templates     Library file: load templates, get window handles
  22. Bob:h.wimp.ev_process    Library file: main loop for wimp programs
  23. <Exec$dir>.main          Main program
  24.  
  25. Two library files are specified, and the textfile main. Main contains
  26. the function main - the entry point into the program. The first line
  27. (apart from comments) is
  28.  
  29.                 @b = @(newstring(500)); 
  30.  
  31. which creates a fixed buffer, 500 bytes long, at the address @b. Note
  32. the convention of using @ as the first letter to remind ourselves that
  33. @b is an address.
  34.  
  35. Then
  36.  
  37.  handler = newvector(20);         
  38.  handler[Mouse_Click] = do_Mouse_Click;
  39.  handler[Menu_Selection] = do_Menu_Selection;
  40.  handler[User_Message] = handler[User_Message_Recorded] = do_Message;
  41.  
  42. creates a vector of handlers to respond to the window manager. We only
  43. need to respond to four reason codes:
  44.  
  45.           Mouse_Click
  46.           Menu_Selection
  47.           User_Message
  48.           User_Message_Recorded
  49.  
  50. The handler's components for these reason codes are set to functions
  51. appearing later in the file Main. The rest are nil by default.
  52. A generic handler function takes two arguments - the first, the address
  53. of a message buffer - the second is a user-parameter, that can be used
  54. for passing in data. In this example, the user-parameter has the value
  55. nil. The handler function must return FALSE if it is to cause the
  56. program to terminate, and TRUE otherwise.
  57.  
  58. The statement
  59.  
  60.  in (mesg_list= newstring(8)) put
  61.      { Message_DataLoad; 0; } 
  62.  
  63. creates a two-word buffer called mesg-list, containing the messages
  64. we want !Exec to receive. The 'in .. put { .. ; ... ;}' structure
  65. is convenient for filling buffers with words and strings.
  66.  
  67. We start !Exec as a wimp task with
  68.  
  69.  wimp_init(310,"Exec",mesg_list);
  70.  
  71. The Info box item of the menu is defined in a template file. The lines
  72.  
  73.  (wind = newvector(1))[0] = "info";
  74.  info = templates("<Exec$Dir>.Templates",wind)[0];
  75.  
  76. load the template and get the window-handle 'info' of this box. The
  77. templates function, defined in Bob:h.wimp.templates takes two arguments,
  78. the first, a string, the pathname of the template file, the second
  79. a vector of window names. It returns a vector of corresponding window
  80. handles. The vector 'wind' is defined as a 1-component vector.
  81.  
  82. The lines
  83.  
  84.  icon = make_icon();
  85.  menu = make_menu();
  86.  
  87. should be self-explanatory. The function main finishes with the
  88. statement that does all the work
  89.  
  90.  event_process(&1933,@b,handler,nil); 
  91.  
  92. The function event_process is defined in Bob:h.ev_process.
  93.  
  94. event_process(mask,buffer,action,user)
  95. {
  96.  local r, respond, go_on;
  97.  r = newvector(8);
  98.  go_on = TRUE;
  99.  while(go_on)
  100.  {
  101.   r[0] = mask;
  102.   r[1] = buffer;
  103.   swi("Wimp_Poll",r);
  104.   go_on =
  105.      (typeof(respond = action[r[0]])
  106.                == BYTECODE)?respond(buffer,user):TRUE;
  107.  }
  108.  wimp_closedown();
  109. }
  110.  
  111. This function polls the wimp, and, if the component of the vector
  112. 'action' (which MUST have at least 20 components) given by the
  113. returned reason-code is a function, that function is called. If the
  114. function returns FALSE, execution falls through to wimp_closedown
  115. and the function main terminates.
  116.  
  117. The event_process function provides a way of modularizing wimp
  118. programs. It is the possibility of having vectors of functions which
  119. enables ArmBob to gain in expressiveness over Basic.
  120.  
  121. Now let us look at the handler functions. The most interesting is
  122.  
  123. do_Message(a,user)
  124. {
  125.  switch(£(a+16))
  126.     {
  127.      case Message_Quit:
  128.        return FALSE;  // i.e. do not continue
  129.        break;
  130.      case Message_DataLoad:  
  131.         if (£(a+20)==-2 && £(a+24)==icon)
  132.            act(a,user_process);
  133.         return TRUE;
  134.         break;
  135.      default:
  136.         return TRUE;
  137.         break;
  138.     }
  139. }
  140.  
  141. The first argument a is the address of the message buffer. The £ operator
  142. fetches the integer stored at its argument. If a DataLoad message is
  143. received because something has been dragged to the iconbar icon,
  144. then act(a,user_process) is called. The function act gets the pathname
  145. and filetype of the object dragged, acknowledges the DataLoad message,
  146. and passes the pathname and filetype to its second argument.
  147.  
  148. act(a,f)
  149. {
  150.  local filename, filetype;
  151.  filename = $(a+44);
  152.  filetype = £(a+40);
  153.  ££(a+16,Message_DataLoadAck);
  154.  ££(a+12,£(a+8));
  155.  r[0] = User_Message_Acknowledge;
  156.  r[1] = a;
  157.  r[2] = 0;
  158.  swi("Wimp_SendMessage",r);
  159.  f(filename,filetype);
  160. }
  161.  
  162. The $ function returns the string (terminated by an ASCII code less
  163. than 32) stored at an address. The ££ function may be used for poking 
  164. 4-byte words into positions in buffers.
  165.  
  166. Note how the function f, the action to be taken, is passed as a parameter.
  167.