home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / v / vista / !Manual / manual / cintro < prev    next >
Text File  |  1996-01-25  |  8KB  |  191 lines
  1. <html>
  2. <title>Class Introduction</title>
  3. <h1>Class Introduction</h1>
  4.  
  5. Vista contains a set of C++ classes.  There 4 main classes.  
  6. This section will serve as an introduction to the main classes.
  7. <p>
  8. <a name="task"></a>
  9. <h2>Task</h2>
  10.  
  11. This class represents the task in which the Vista program is running.  It 
  12. is the main controlling loop for the program and looks after all the
  13. resources of the program (Windows, messages, etc).
  14. <p>
  15. To create a new basic Task, 3 parameters are required:
  16. <p>
  17. <ol>
  18. <li>The name to give to the task.  This is the name that appears in the
  19. Task display.
  20. <li>The application name.  This is used to construct the application's
  21. "world".  A variable constructed out of this name followed by
  22. $Dir (eg EasyC$Dir) is used as the root directory for the application.
  23. All the resources for the application are found under this root.
  24. <li>The name of the sprite which will appear on the Icon Bar.  This
  25. must be in the WIMP's sprite pool.
  26. </ol>
  27. <p>
  28. In addition to these 3 parameters, the Task can be given the name of a
  29. menu to display when the user clicks 'menu' over the Icon Bar icon.  See 
  30. the section on menus later.
  31. <p>
  32. So, to create a new task, the following line would suffice:
  33. <pre>
  34. Task *my_task = new Task ("My new Task", "MyTask", "mytask") ;
  35.  
  36. </pre>
  37. There are 3 constructors available for Tasks.  Each one manifests itself
  38. differently:
  39. <p>
  40. <ol>
  41. <li><a href="file:task#ct1">Basic task</a> with icon on the icon bar given the icon name
  42. <li>Task <a href="file:task#ct2">without an icon</a> on the icon bar
  43. <li>A task with an icon on the icon bar given an <a href="file:task#ct3">existing Icon</a>.
  44. </ol>
  45. <p>
  46. Each of the constructors also has some default parameters to allow control
  47. over the advanced RISC OS 3 features such as message lists and icon
  48. positioning.
  49. <p>
  50. The task needs resources.  These consist of:
  51. <p>
  52. <ol>
  53. <li>A set of templates (filename: Templates)
  54. <li>A set of messages  (filename: Messages)
  55. <li>A set of menus     (filename: Menus)
  56. </ol>
  57. <p>   
  58. All these resources must be held under a directory called Resources in the
  59. task's root dir.  The Resources directory itself must contain a file
  60. called Country (of type Text) containing one line.  The line is the
  61. name of another directory which contains the actual Templates, Messages
  62. and Menus files.  For example, if the country for which the application
  63. is created is Uganda, then the Country file contains one line: Uganda\n
  64. and the directory structure looks like:
  65. <p>
  66. <img src="dirs">
  67. <p>
  68. Other resources are also required, such as !Sprites, !Boot and !Run files.
  69. Information on these can be found in the usual RISC OS manuals.
  70. <p>
  71. <p>
  72. Once a Task has been created, it may be run.  This is achieved by use of
  73. the 'run' method of the class.  This takes no parameters and does
  74. not usually return:
  75. <pre>
  76. my_task->run() ;
  77.  
  78. </pre>
  79. It enters a polling loop calling SWI Wimp_Poll until it is told to
  80. shutdown or stop.  
  81. <p>
  82. When the task is running, events are distributed to the objects in the 
  83. task by calling virtual functions in the objects.  Each event causes
  84. a Thread to be created to handle it.  The thread terminates when the
  85. event has been dealt with.  The fact that each event is dealt with in
  86. a thread means that the task can to anything a thread can do, such as
  87. sleep or perform a long winded calculation without having to split
  88. it up to return to poll the operating system.
  89. <p>
  90. Use of the multithreading will mean the end of the usual delays and
  91. 'hourglass' pointer inherent in single threaded tasks.
  92. <p>
  93. For more detail, click <a href="file:task">here</a>
  94.  
  95. <p>
  96. <a name="thread"></a>
  97. <h2>Thread</h2>
  98.  
  99. As described above, a Task is a RISC OS task.  It appears in the
  100. 'Task Display' dialogue box available from the Green Acorn symbol
  101. on the desktop.  The operating system takes care of the switching
  102. between the various tasks on calls to SWI Wimp_Poll.  Inside a task
  103. it is useful to be able to run more than one part of the
  104. program at once.  The Thread class acts like a pre-emptive
  105. process inside a RISC OS task.  All the threads in a task
  106. run simultaneously and can communicate with each other.  The
  107. threads are preempted by the Vista library so that the CPU
  108. time can be shared among them.
  109. <p>
  110. Each time a task receives an event from the operating system, it
  111. spawns a new Thread to deal with the event.  The thread then
  112. executes along side all other threads, each being interrupted
  113. by Vista.  This allows the event handling code to behave in any
  114. way it likes, without having to worry about returning to
  115. call Wimp_Poll.
  116. <p>
  117. While threads are running they may sleep waiting for a 'resource'.  
  118. Resources are things like timers, flags and even other threads.
  119. Thus a thread can sleep for a period of time or until another
  120. thread has finished.  
  121. <p>
  122. Like other classes within Vista, the intention is that the programmer
  123. will derive his own thread classes from those supplied and override
  124. the virtual functions.
  125. <p>
  126. For more detail, click <a href="file:thread">here</a>
  127.  
  128. <p>
  129. <a name="window"></a>
  130. <h2>Window</h2>
  131.  
  132. A Window represents a window on the screen.  The intention is that the base
  133. class Window is used to derive other classes for the actual windows which
  134. are used in the application.
  135. <p>
  136. A Window may be created as part of a task or as part of another window.  If it
  137. is part of a task it can be moved around the screen by dragging.  If it is part
  138. of a window it is moved and redrawn when its parent window is moved.  It cannot
  139. be moved independently.  A window created in this way is called a 'pane' in the
  140. PRM.
  141. <p>
  142. The classes derived from the base class Window should contain local data required
  143. for that window as class members.  The class should provide functions for the
  144. virtual functions of the Window class if it wishes to override the default
  145. action of those functions.  For example, by default the 'open' method simply
  146. opens the window (and any sub-windows).  If you want to do other things as
  147. well as this (or instead I suppose) then you should provide a function with the
  148. same name ('open') and taking the same parameters.  This new function will
  149. be called instead of the defaut one when the window needs to be opened.
  150. <p>
  151. For more detail, click <a href="file:window">here</a>
  152.  
  153. <p>
  154. <a name="icon"></a>
  155. <h2>Icon</h2>
  156.  
  157. An Icon represents one or more WIMP icons.  When you create an Icon, you give it
  158. the icon numbers of the WIMP icons to which it maps.  When the user click on
  159. any of these WIMP icons, a function within the Icon is called.  Icons may be:
  160. <p>
  161. <ul>
  162. <li>created
  163. <li>deleted
  164. <li>moved
  165. <li>selected
  166. <li>faded
  167. <li>printed to
  168. <li>read from
  169. <li>dragged
  170. </ul>
  171. <p>                         
  172. In addition, the Icon is informed of user clicks and key presses through calls to
  173. virtual functions.  If you derive a new class from the Icon base class you can
  174. provide functions to override the default behaviour of these functions.
  175. <p>
  176. An icon has a 'user reference' which it is given when it is created.  This is a
  177. void * type which can point to anything you require.  The idea of this is that
  178. you can attach data to an Icon and get access to this data when something happens
  179. to cause the Icon to be activated (clicked for example).  To do this, simply
  180. read the member 'user_ref' in the Icon.
  181. <p>
  182. Vista contains a number of higher level Icons which are derived from the Icon
  183. base class.  These are referred to as 'tools' and are detailed later in this
  184. document.  An example of a tool is a 'Slider' which allows the user to set the
  185. length of a meter bar by clicking on arrows (this is actually provided).
  186. <p>
  187. For more detail, click <a href="file:icon">here</a>
  188.  
  189. </html>
  190.  
  191.