home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / l / libstore / Manual
Encoding:
Text File  |  1994-05-01  |  11.8 KB  |  265 lines
  1. WIMP programming: a crash course.
  2.  
  3. If you already know how to program the WIMP, you may skip this bit, as
  4. double-clicking on !LibStore should tell you all you need. However,
  5. for a newcomer all this business of icons creation and menus can be
  6. very confusing.
  7.  
  8. Newcomers:
  9.  
  10. 1. Get a template editor. This doesn't have to be the famous !FormEd,
  11. which I gave up ages ago. !Glazier is very good, but the public domain
  12. version is very buggy. The best I have come across is !TemplEd, which
  13. is PD and can be obtained from various PD libraries.
  14. 2. You need to be reasonably good at programming BASIC!
  15. 3. A good editor is recommended. It is not advisable to run from outside
  16. the desktop, so it must be multitasking. !Edit (RO3) just passes, but
  17. !Zap v1.00+ is probably the best freeware one (v0.90 has got a major
  18. bug which causes it to seize up).
  19. 4. Some form of debugging tool that lets you kill a program when
  20. it gets in a loop is also recommended. I use 'BugBuster' from RISC User,
  21. and I know of no others, but I might write my own someday...
  22. 5. Get RISC OS 3. Most people already have it, but if you don't...
  23.    a) all programs I use work on it (and I have one or two golden
  24.       oldies.
  25.    b) despite rumours to the contrary, most old hard discs and filing
  26.       systems work without upgrading, although upgrading is recommended.
  27.    c) It is wonderful compared to RO2. Having the applics in ROM is
  28.       really convienient.
  29.    d) It looks really good when you run !Newerlook (PD from doggysoft)
  30.       and almost manages to impress PC users (who are jealous because
  31.       they're stuck with MS Windows which is slow, buggy and ugly).
  32. 6. To really understand what's going on, get a book on the WIMP.
  33.  
  34. Starting out
  35.  
  36. If you have attempted at writing your own WIMP proggies before you
  37. will appreciate that reams and reams of code are needed simply to
  38. get a simple program that bleeps every so often, and there is the
  39. problem of the fact that if you get a value wrong, very strange things
  40. can happen (light pink windows in 256 colour modes for example). However,
  41. you need not worry any more! The libraries here are provided to take all
  42. the work and hassle out of writing a multi-tasking program.
  43.  
  44. Loading libraries
  45.  
  46. To load one of these wonderful, all singing, all dancing libraries, you
  47. need to include a line of the form:
  48. LIBRARY "SystemLib:<Libtype>.<Libname>"
  49. <Libtype> is the type of library. At the time of writing, there is just
  50. 'WIMP' and 'Sprites'.
  51.  
  52. A first program
  53.  
  54. Well, it's time to marvel at a bleeping desktop... this program simply
  55. bleeps every second and is quit via the task manager.
  56.  
  57. REM >!Runimage (Wimp Library Demo 1) }
  58. REM by Andrew Hunter                 } --- standard waffle - what it's for,
  59. REM for 32-bit machines              }     etc.
  60. :                                      --- useful to break up program.
  61. LIBRARY "SystemLib:WimpLib.Poll"       --- load library(s)
  62. ON ERROR SYS "Wimp_CloseDown":REPORT:PRINT ERL:END - report errors.
  63. PROCstartup("Wimplib1 (Bleeper)",2) --- Tell the WIMP we want in.
  64. respond%(0)=TRUE                    --- we want to be told about NULL events
  65. PROCpollidle(0,100)                 --- let the library do the work...
  66. END                                 --- goodbye!
  67. :
  68. DEFPROCrespond_null                 --- null event occured, so...
  69. VDU7                                --- be wonderful
  70. ENDPROC                             --- go back to the library.
  71.  
  72. It is very simple to understand, and an incredibly short program.
  73. Things to note:
  74.  
  75. PROCstartup() - takes two things: the name ("Wimplib1...") that appears
  76.                 in the task manager, and the version of RISC OS that
  77.                 it is designed to run under. This starts up the WIMP,
  78.                 sets up block% (famous among WIMP programmers everywhere)
  79.                 and any other arrays/variables needed (such as respond%).
  80. PROCpollidle - one of two - PROCpoll() and PROCpollidle. Both take a mask,
  81.                which might as well be 0. If you don't need null events,
  82.                set it to one. PROCpollidle takes a time (in centiseconds)
  83.                to place between null events.
  84. respond%() - tells the library which events to respond to. A full list
  85.              can be found in the instructions for the 'Poll' library.
  86.  
  87. Application directories
  88.  
  89. Not all programmers know how to create one of these properly. It's simple
  90. but tedious, so there are several programs that automate this. I don't
  91. use them. So...
  92.  
  93. 1. Create a directory with a name beginning with ! (it won't show the
  94. ordinary directory icon...)
  95. 2. SHIFT+ double click on it.
  96. 3. Create a '!Run' file containing lines like the following (it should
  97. be of type Obey):
  98. |
  99. | !Run file for !myapp
  100. |
  101.  
  102. Set myapp$Dir <Obey$Dir>          --- so you can shove it anywhere you like.
  103. Iconsprites <Obey$Dir>.!Sprites   --- if you have a !Sprites file
  104. WimpSlot -min 8192K -max 16384K   --- memory requirements (OTT here!)
  105. <myapp$Dir>.!RunImage
  106.  
  107. Change myapp to whatever the name of your program.
  108. 4. Save your program inside as !RunImage.
  109. 5. Create the sprite for it. Make sure it gives a good idea of what the
  110. program does. The best sprites can be created with the aid of !ChangeFSI.
  111. Call the sprite '!myapp' (or whatever the name of the directory is) and
  112. save it in a file called '!Sprites'.
  113.  
  114. Templates
  115.  
  116. Why did I just explain that to you? Well, you will need it for the next
  117. demo which is...
  118.  
  119. TEMPLATES!
  120.  
  121. I could show you the method !WimpLib2 & 3 uses which is to do it manually.
  122. This is boring and tedious, and lends itself to long programs. Once
  123. a window is created, the library does all the handling for you.
  124.  
  125. Two libraries are used here:
  126. Templates & Windows.
  127.  
  128. Templates provides facilities for the loading of templates, and windows
  129. provides facilities for maintaining them.
  130.  
  131. So, having loaded the two libraries, you have to create a template. Firstly
  132. you have to design it using a template editor, placing icons, etc where you
  133. want them. Make sure that the template is redrawn by the WIMP (i.e. is not
  134. hatched by the template proggy). Then you have to start up the windows
  135. routine using startup_windows() with the maximum number of windows you want
  136. to use. Straight afterwards call PROCload_templates() with the name of the
  137. template file (eg: <myapp$dir>.Templates), and the amount of space to
  138. reserve for indirected space (4096 is normally plenty). Then create a
  139. procedure DEFPROCuser_load. This has to tell the template library which
  140. templates to load. You can place many different types of template load
  141. routine inside this procedure, but the simplest to use is
  142. FNcreate_template(). This returns the window handle (as well as storing it in
  143. an array) and actually creates the window. You may then open the window using
  144. PROCopenwindow(), giving it the window handle.
  145.  
  146. The poll library will handle all events associated with the window, so once
  147. you have opened it, you no longer need to worry about it. If you want to have
  148. a look at a demo program, a suitably commented one is provided in the !Demos
  149. application (SHIFT+double click it to find it).
  150.  
  151. Responding to events
  152.  
  153. An array, respond%() is set up by PROCstartup(). This allows you to tell the
  154. library which events your task wants to respond to. The main ones are:
  155.  
  156. 3 - window closing. The templates demo uses this to detect when you are
  157. closing its window, so it can quit. If this is set to TRUE, PROCrespond_close
  158. is called every time the close button is clicked on one of your windows.
  159. 6 - mouse clicked. This is called when the mouse is clicked over an object
  160. belonging to your task - an icon or a window usually. PROCrespond_click is
  161. called.
  162. 9 - menu clicked. This is called whenever a selection is made off a menu.
  163. PROCrespond_menu is called.
  164.  
  165. To activate an event, set respond%(n) to TRUE, where n is the event number.
  166. You should also set the variable quit% to TRUE when you want your task to
  167. end.
  168.  
  169. Windows
  170.  
  171. You do not need to keep track of all the window handles in your program, as
  172. the library provides an array that does it all for you. This array is called
  173. handle%(). handle%(0) contains the first created windows handle, handle%(1)
  174. contains the second and so on.
  175.  
  176. Handling clicks
  177.  
  178. To handle clicks, set respond%(6) to TRUE. Then, every time a click event
  179. occurs, your DEFPROCrespond_click will be called, with various variables set
  180. up. The ones you should be interested in are ihandle%, whandle% and button%,
  181. which contain the window handle and the icon handle of the window and icon
  182. that was clicked on. The icon handle is the icon number that you gave it in
  183. the template editor. This stays fixed. The window handle can vary, so I
  184. recommend using the handle%() array to find it. button% contains the mouse
  185. button number: 1 for adjust, 2 for menu and 4 for select (yes - it is four).
  186.  
  187. Icons
  188.  
  189. You now need the 'Icons' library.
  190.  
  191. The most important procedures in handling icons are: PROCnewtext()
  192. PROCnewvalid() FNreadicon() PROCiconbaricon()
  193.  
  194. PROCnewtext() takes the window handle, icon handle and the text to change
  195. that icons contents to. The icon MUST be indirected.
  196.  
  197. PROCnewvalid() takes the window handle, icon handle and the text to change
  198. that icons validation string to. The icon MUST be indirected.
  199.  
  200. FNreadicon() takes the window and icon handle and returns its contents in
  201. text.
  202.  
  203. PROCiconbaricon() creates an icon on the iconbar. It takes the name of the
  204. sprite and which side the icon should go on - -1 for the right or -2 for the
  205. left.
  206. Note that the demo for this has very few comments, as the functions are
  207. mostly self-explainitory. To quit this demo, click the right mouse button on
  208. the iconbar icon.
  209.  
  210. Filing operations
  211.  
  212. You now need the 'Messages' library.
  213.  
  214. I am leaving out the instructions for the menus because even under !Libstore
  215. they are surprisingly complex. If you want to have a go, there is a demo of
  216. the menus and the procedures are described in the !Libstore application.
  217. !Libstore makes the WIMP messaging system very simple. It deals with almost
  218. all of the messages involved, in the end returning you with a filename you
  219. can save to.
  220.  
  221. Firstly, you have to set respond%(17),(18),(19) all to TRUE, and add
  222. DEFPROCrespond_message, which simply calls PROCstandard_messages. The need
  223. for this is due the the structure of !LibStore. For saving, you then need to
  224. add three functions which return appropriate values:
  225. FNtype : returns the filetype of the file
  226. FNlen : returns the estimated length (or -1 if you can't be bothered)
  227. FNname : returns the filename (just the filename, without the pathname before
  228. it, i.e. 'Jim' not 'ADFS::MyDisc.$.Demos.Libstore.Jim'). A function
  229. 'FNfilename()', which takes a full pathname, is provided to strip the path
  230. from the front of the filename.
  231.  
  232. There are then two procedures you need to add:
  233. DEFPROCdosave(filename$) - saves the file to 'filename$'.
  234. DEFPROCdoload(filename$,type%) - loads file 'filename$' which has filetype
  235. 'type%'. To start the whole process off, PROCdragbox() needs to be called
  236. with the window handle and icon handle of the sprite icon.
  237.  
  238. Errors:
  239.  
  240. The oddest error is 'window definition won't fit'. This is caused when you
  241. are loading templates and IS NOT MY FAULT. Its cause can be either that you
  242. have spelt the name wrong (RO gets confused and tries to load a non-existant
  243. template) or that you have created a HUGE template that just won't fit into
  244. the memory !LibStore has reserved for it. You could try increasing the 4096
  245. in PROCload_templates to 8192 or 16384, but if that doesn't work, use lots of
  246. small windows rather than one large one.
  247.  
  248. Contacting me:
  249.  
  250. I can be contacted over Arcade BBS as Ahunter. Please don't
  251. hesitate to report any bugs, although as I have been using this for over two
  252. years without fault, I doubt there are any... You can also ask questions,
  253. tell me how rushed this manual is and generally critisise, but only expect
  254. replies for the former.
  255.  
  256. I hope you find this useful and produce many great programs with it.
  257.  
  258. Disclaimer:
  259.  
  260. I can take no responsibilty for loss or damage of data resulting from the use
  261. of this application and the libraries therein. You use this entirely at your
  262. own risk.
  263.  
  264. Bye!
  265.