home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / armbob / armbob_1 / ARMBOB / doc / Tutorial / 04 < prev   
Encoding:
Text File  |  1995-01-06  |  5.6 KB  |  170 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 three 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, and the third a pointer to a mask word to tell the
  55. window manager which events our task is not interested in receiving. 
  56. In this example, the user-parameter has the value nil. The handler 
  57. function must return FALSE if it is to cause the program to terminate, 
  58. and TRUE otherwise.
  59.  
  60. The statement
  61.  
  62.  in (mesg_list= newstring(8)) put
  63.      { Message_DataLoad; 0; } 
  64.  
  65. creates a two-word buffer called mesg-list, containing the messages
  66. we want !Exec to receive. The 'in .. put { .. ; ... ;}' structure
  67. is convenient for filling buffers with words and strings.
  68.  
  69. We start !Exec as a wimp task with
  70.  
  71.  wimp_init(310,"Exec",mesg_list);
  72.  
  73. The Info box item of the menu is defined in a template file. The lines
  74.  
  75.  (wind = newvector(1))[0] = "info";
  76.  info = templates("<Exec$Dir>.Templates",wind)[0];
  77.  
  78. load the template and get the window-handle 'info' of this box. The
  79. templates function, defined in Bob:h.wimp.templates takes two arguments,
  80. the first, a string, the pathname of the template file, the second
  81. a vector of window names. It returns a vector of corresponding window
  82. handles. The vector 'wind' is defined as a 1-component vector.
  83.  
  84. The lines
  85.  
  86.  icon = make_icon();
  87.  menu = make_menu();
  88.  
  89. should be self-explanatory. The function main finishes with the
  90. statement that does all the work
  91.  
  92.  (maskptr = newvector(1))[0] = &1933;
  93.  event_process(maskptr,@b,handler,nil); 
  94.  
  95. The function event_process is defined in Bob:h.ev_process.
  96.  
  97. event_process(maskptr,buffer,action,user)
  98. {
  99.  local r, respond, go_on;
  100.  r = newvector(8);
  101.  go_on = TRUE;
  102.  while(go_on)
  103.  {
  104.   r[0] = maskptr[0];
  105.   r[1] = buffer;
  106.   swi("Wimp_Poll",r);
  107.   go_on =
  108.      (typeof(respond = action[r[0]])
  109.                == BYTECODE)?respond(buffer,user,maskptr):TRUE;
  110.  }
  111.  wimp_closedown();
  112. }
  113.  
  114. This function polls the wimp, and, if the component of the vector
  115. 'action' (which MUST have at least 20 components) given by the
  116. returned reason-code is a function, that function is called. If the
  117. function returns FALSE, execution falls through to wimp_closedown
  118. and the function main terminates.
  119.  
  120. The event_process function provides a way of modularizing wimp
  121. programs. It is the possibility of having vectors of functions which
  122. enables ArmBob to gain in expressiveness over Basic.
  123.  
  124. Now let us look at the handler functions. The most interesting is
  125.  
  126. do_Message(a,user,maskptr)
  127. {
  128.  switch(£(a+16))
  129.     {
  130.      case Message_Quit:
  131.        return FALSE;  // i.e. do not continue
  132.        break;
  133.      case Message_DataLoad:  
  134.         if (£(a+20)==-2 && £(a+24)==icon)
  135.            act(a,user_process);
  136.         return TRUE;
  137.         break;
  138.      default:
  139.         return TRUE;
  140.         break;
  141.     }
  142. }
  143.  
  144. The first argument a is the address of the message buffer. The £ operator
  145. fetches the integer stored at its argument. If a DataLoad message is
  146. received because something has been dragged to the iconbar icon,
  147. then act(a,user_process) is called. The function act gets the pathname
  148. and filetype of the object dragged, acknowledges the DataLoad message,
  149. and passes the pathname and filetype to its second argument.
  150.  
  151. act(a,f)
  152. {
  153.  local filename, filetype;
  154.  filename = $(a+44);
  155.  filetype = £(a+40);
  156.  ££(a+16,Message_DataLoadAck);
  157.  ££(a+12,£(a+8));
  158.  r[0] = User_Message_Acknowledge;
  159.  r[1] = a;
  160.  r[2] = 0;
  161.  swi("Wimp_SendMessage",r);
  162.  f(filename,filetype);
  163. }
  164.  
  165. The $ function returns the string (terminated by an ASCII code less
  166. than 32) stored at an address. The ££ function may be used for poking 
  167. 4-byte words into positions in buffers.
  168.  
  169. Note how the function f, the action to be taken, is passed as a parameter.
  170.