home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / vista_1 / !Manual_manual_intro < prev    next >
Encoding:
Text File  |  1996-01-25  |  10.2 KB  |  263 lines
  1. <html>
  2. <title>Introduction</title>
  3. <h1>Introduction</h1>
  4.  
  5. Vista is a C++ class library written specifically for RISC OS (version
  6. 3.10 or later).  It is designed to be easy to use for the beginner and
  7. powerful enough to satisfy the most experienced programmers.  It
  8. provides a set of base classes from which the user can derive his own 
  9. classes to suit his application.  The basic idea is that a Vista class on
  10. its own will provide a basic operation (such as display a window on
  11. the screen).  If the user wishes to do something else other than
  12. that provided by the Vista class, he will need to derive a new one,
  13. inheriting the Vista class, and write his own code to do as he wishes.
  14. <p>
  15. Vista is a complete environment in which RISC OS WIMP programs may be
  16. written.  The environment interacts with the Operating System through
  17. a set of C++ classes.  The classes provide an interface to the
  18. base operating system routines which suits the C++ programming
  19. paradigm, as well as providing additional functionality not available
  20. to users of other libraries.
  21. <p>
  22. Vista is based around four fairly complex classes: 
  23. <ul>
  24. <li><a href="file:cintro#task">Task</a>:
  25. <li><a href="file:cintro#thread">Thread</a>:
  26. <li><a href="file:cintro#window">Window</a>:
  27. <li><a href="file:cintro#icon">Icon</a>: 
  28. </ul>
  29. <p>
  30. A <a href = "file:cintro#task">Task</a> is the framework in which a program based on Vista runs. 
  31. <p>
  32. It consists
  33. of a set of <a href="file:cintro#window">Windows.</a>  
  34. The task keeps track of the Windows it owns.  
  35. <p>
  36. Each
  37. Window can contain a number of <a href="file:cintro#icon">Icons.</a>  
  38. An Icon can be something like
  39. a button which the user can press.  
  40. <p>
  41. A <a href="file:cintro#thread">Thread</a>is an object that behaves
  42. like a 'process' within a task.  Threads run until they terminate, but
  43. are scheduled by the library to share the CPU, much like the processes
  44. in a pre-emptive operating system.  They share program and data
  45. space with all other threads.
  46. <p>
  47. An important feature of Vista is the <a href="file:cintro#thread">pre-emptive multithreading.</a>  A
  48. program written for RISC OS running under the WIMP must call the
  49. OS routine Wimp_Poll continually in order to let other tasks
  50. run and have events delivered to it.  This imposes a structure
  51. on the code which must have an 'event loop'.  While this is 
  52. appropriate for simple event based programs, it can become
  53. restrictive when imposed on complex programs which are
  54. not inherently event based.
  55. <p>
  56. A program written under Vista does not have this structure imposed
  57. on it.  The program can be written in any fashion, but Vista will
  58. ensure that the OS is called at the appropriate frequency.  This
  59. allows the program to, say, enter a tight loop during a calculation
  60. lasting a few minutes.  Multithreading is an important programming
  61. technique which has gained popularity in recent years.  It allows
  62. a program to execute in a pseudo-parallel fashion in a single
  63. task.  It has many powerful features of which the Vista user can
  64. now make use.
  65. <p>
  66. This manual will attempt to guide the newcomer through writing a Vista
  67. application and will also serve as a reference when the library is
  68. more familiar.
  69. <p>
  70.  
  71. <p>
  72. <a name="concepts"></a>
  73. <h2>Concepts</h2>
  74.  
  75. Those familiar with programming RISC OS under the WIMP will be aware
  76. of the method in which a program executes.  After a brief initialisation
  77. period, the program places an icon on the iconbar and enters a forever
  78. loop calling Wimp_Poll and acting on the events returned from it.  This
  79. program structure is fine for purely event driven programs, but can become
  80. limiting when dealing with other types of program.  For example, the
  81. Easy C/C++ compiler is not event driven, so it must have a timer
  82. set up to call Wimp_Poll for it at the correct frequency.  This is
  83. a contrived situation which is viewed as an aberration and is
  84. best avoided.
  85. <p>
  86. Vista is different.  It provides a simple framework in which your
  87. program consists of a set of objects, all of which have operations
  88. invoked on them.  An object can be viewed as a piece of 'living data'.
  89. When writing a program using Vista, there is no need to have an 
  90. event loop as Vista does this for you.  Vista receives the events
  91. from the operating system and invokes the appropriate function
  92. in an appropriate object.
  93. <p>
  94. A normal WIMP program displays a few windows on the screen and allows
  95. the user to do things with them.  Vista also allows the windows
  96. to contain 'Objects'.  An Object is something inside a window that
  97. needs to be drawn.  Examples are sprites, lines, blocks of text, etc.
  98. Once the program has created the objects, the objects themselves
  99. are responsible for redrawing so the application doesn't need to
  100. care about them.
  101. <p>
  102.  
  103. <a name="use"></a>
  104. <h2>How to use Vista</h2>
  105.  
  106. To go about writing a program using Vista you first need to decide on 
  107. what windows will be in your program.  Once you decide on the type
  108. of windows that will appear, you need to define a class derived
  109. from the class Window for each type. 
  110. Generally speaking, there will be one source file and one header file
  111. for each major class in the program.
  112. <p>
  113. After deciding on the windows, you need to decide what the windows are
  114. going to do.  A window will receive input from the user by actions
  115. such as mouse clicks, menu selections, dragging etc.  Each window
  116. type needs to define functions for each form of input it is 
  117. willing to accept.  For example, if you are going to deal with
  118. mouse clicks, define a function called 'click' conforming to the
  119. function of the same name in the Window class:
  120. <pre>
  121.  
  122. void click(int mx, int my, int buttons, int icon) ;
  123.  
  124. </pre>
  125. In C++, by defining a function in a derived class with the same
  126. "signature" as a virtual function in a base class, you are
  127. overriding the base class function.  This means that your
  128. click function will receive all mouse click events instead of
  129. that in the Window class.  Note that you must copy the signature
  130. of the virtual function exactly (except for the names of the
  131. parameters of course).  This means it must have the same
  132. return type, same name and same parameter types.
  133. <p>
  134. Next, you can decide on the shape of your windows including the
  135. Icons you want in it.  For an icon to be use as output, you
  136. need to make it into an instance of the Vista class 'Icon'. 
  137. If your icon is just used for input, you don't need to make
  138. it into an 'Icon' instance, just deal with it in the
  139. window 'click' function instead.  If an icon is an 'Icon'
  140. instance it will always receive input in preference to the
  141. window's input functions.
  142. <p>
  143. Another important aspect of a Vista program is the functionality
  144. of the Task class.  You will need to derive a new class from
  145. the 'Task' Vista class and provide some action functions as
  146. you do for windows.  Tasks generally act on icon bar clicks
  147. and menu selections.  They can receive messages from other
  148. tasks through 'Channels' they have defined.
  149. <p>
  150. It is also important to keep in mind that Vista is a multi-threaded
  151. library.  This is implemented by use of low level OS feature
  152. known as 'Callbacks'.  A callback is activated on a timer which
  153. must only be running when the OS has switched the task as being the
  154. 'current task'.  Vista ensures this by switching off the
  155. timer just before calling Wimp_Poll, and back on again when
  156. the task regains control.  Therefore, you <b>must not</b>
  157. call any OS routine that switched control to another
  158. task directly.  The only 2 routines that do this are Wimp_Poll
  159. and Wimp_StartTask.  Vista supplies a 'spawn' function as 
  160. veneer around Wimp_StartTask, and handles all Wimp_Poll
  161. calls itself.  You should never call these routines yourself.
  162. <p>
  163. Another feature of the multi-threading is that the task is never
  164. 'busy'.  This means you should never have the need to use
  165. the 'hourglass' as you can receive events at all times.  This
  166. might have some design implications on strictly single-threaded
  167. designs (which are rare in C++).
  168. <p>
  169. Vista is supplied with a few powerful 'tools' which are really
  170. composite icons.  Examples of these are the Adjuster, Slider and
  171. Popup tools.  These are as specified in the RISC OS Style Guide
  172. and behave as expected.  Because they are derived from the
  173. Icon class, they are accessed just like a normal icon and
  174. are very easy to use.  For example, to set a Meter to a certain
  175. value, use the call:
  176. <pre>
  177.  
  178. meter->write (value) ;
  179.  
  180. </pre>
  181. And to read the value of an adjuster, use:
  182. <pre>
  183.  
  184. adjuster->read (value) ;
  185.  
  186. </pre>
  187. Vista is also supplied with a set of useful windows which are derived
  188. from the Window class.  These are things like a DialogueBox class
  189. or an IconGrid (a window which behaves like a Filer directory viewer).
  190. These derived windows can be used in your programs.
  191. <p>
  192. Another supplied feature is a set of 'Objects'.  These are things within
  193. a Window like a piece of text or a sprite or drawfile.  These, in themselves,
  194. may not be exactly as required by your applications, but you can derive
  195. new objects from them to supply the required functionality.
  196. <p>
  197. Finally, Vista is supplied with a few example programs which you are
  198. encouraged to look at, understand and copy.  More examples may
  199. come in the future, but it is hoped that the set supplied are
  200. sufficient to give you a taste of the power of the library.
  201. <p>
  202.  
  203. <a name="idents"></a>
  204. <h2>Defined Identifiers</h2>
  205. Like any program, Vista has a set of identifiers that it uses.  You cannot
  206. use these identifiers in your programs if you include the Vista
  207. headers.  The identifiers used by Vista are used for class names and are:
  208. <ul>
  209. <li>Channel
  210. <li>DataSave
  211. <li>DeferredDelete
  212. <li>Icon
  213. <li>IconSet
  214. <li>Menu
  215. <li>MenuItem
  216. <li>MsgTrans
  217. <li>Object
  218. <li>IconObject
  219. <li>RawSpriteObject
  220. <li>TextObject
  221. <li>LineObject
  222. <li>FontObject
  223. <li>DrawObject
  224. <li>SpriteObject
  225. <li>Task
  226. <li>ControlThread
  227. <li>DebugWin
  228. <li>sprite_area
  229. <li>TaskError
  230. <li>TemplateEntry
  231. <li>Template
  232. <li>Thread
  233. <li>ThreadResource
  234. <li>ThreadTimer
  235. <li>ThreadPipe
  236. <li>ThreadSemaphore
  237. <li>MainThread
  238. <li>ResourceThread
  239. <li>ThreadManager
  240. <li>Adjuster
  241. <li>Meter
  242. <li>Slider
  243. <li>Popup
  244. <li>MouseTracker
  245. <li>Window
  246. <li>IconGrid
  247. <li>DialogueBox
  248. <li>Attribute
  249. <li>StringAtribute
  250. <li>IntegerAttribute
  251. <li>BoolAttribute
  252. <li>SetAttribute
  253. <li>CancelButton
  254. <li>OKButton
  255. <li>SaveBox
  256. <li>SaverFile
  257. <li>ProgramInfo
  258. </ul>
  259. In addition, there are two functions with signatures 'dprintf (char*...)'
  260. and 'print (char*...)' defined.  All other functions are class member
  261. functions and so are coded with the class name.
  262. </html>
  263.