home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / screensav / alphasave_2 / Program / ProgHelp
Text File  |  1998-07-22  |  16KB  |  430 lines
  1.                 _     ___   _   _
  2.             /\ \ \   \   \ \ \_\ \    /\     ££££  ££  £   £ ££££
  3.            /  \ \ \   \  _\ \   _ \  /  \    £    £  £ £   £ £      Version
  4.           / __ \ \ \__ \ \   \ \ \ \/ __ \   ££££ ££££  £ £  ££££      1.25
  5.          /_/  \_\ \___\ \_\   \_\ \_\/  \_\     £ £  £  £ £  £
  6.          __________________________________  ££££ £  £   £   ££££
  7.  
  8.          -------------- How to Program your Own!! ---------------
  9.          ________________________________________________________        
  10.  
  11.                     by Marc Warne of Alpha Programming
  12.  
  13. ------------------------------------------------------------------------------
  14.  
  15. Introduction
  16. ••••••••••••
  17.  
  18. All screensavers have to, in some way or another, communicate with AlphaSave.
  19. This could range from simply telling AlphaSave when the screensaver has quit, up
  20. to finding out who AlphaSave is registered to and what parameters have been set.
  21.  
  22. Please note that programming a screensaver should only be done if sufficient
  23. knowledge of programming is available.
  24.  
  25. Types of screensavers
  26. ~~~~~~~~~~~~~~~~~~~~~
  27. Essentially, there are two types of screensavers. The first is a normal, multi-
  28. tasking screensaver. The other is a single-tasking screensaver. Single-tasking
  29. screensavers are now obsolete, so this manual describes how to program a multi-
  30. tasking screensaver.
  31.  
  32. Examples
  33. ~~~~~~~~
  34. There are two simple example screensavers included - !DemoSave and !DemoSave2.
  35. !DemoSave is a multi-tasking screensaver. The !RunImage file within both of
  36. these programs may be used within your own screensavers, even if you intend to
  37. sell them.
  38.  
  39. ------------------------------------------------------------------------------
  40.  
  41. Program Resources
  42. •••••••••••••••••
  43.  
  44. In the program directory, !DemoSave can be used as a shell screensaver. Some of
  45. the files, such as !Run will need to be edited, as will the !RunImage file.
  46.  
  47. Also included are various sprite files for the screensaver. Although you do not
  48. have to stick to these, most other screensavers have the same background for the
  49. icon sprite.
  50.  
  51. The 'Data' file
  52. ~~~~~~~~~~~~~~~
  53. A file called 'Data' should be present inside all screensavers.
  54. This file has information on the screensaver, including:
  55.  
  56.     - What type of screensaver it is
  57.       (Multi-tasking or single-tasking)
  58.     - What parameters should be passed to it
  59.     - How the configuration window should look
  60.     - Who wrote it
  61.     - A short description of it
  62.     - When it was written
  63.  
  64. This file must be present in all screensavers you create, otherwise they will
  65. not function properly.
  66.  
  67. !ASMessage
  68. ~~~~~~~~~~
  69. This is a simple BASIC program which shows you how to use the AlphaSave message
  70. system. It displays whether AlphaSave is loaded, its version, whether it's
  71. registered, who it's registered to and the key code and date.
  72.  
  73. ------------------------------------------------------------------------------
  74.  
  75. Icon Maker
  76. ••••••••••
  77.  
  78. If you are making your screensaver configurable by the user (i.e. it can be
  79. configured using the screensaver config window in SaveConf), you must open the
  80. 'Icon List' and 'Icon Maker' windows by moving over to 'Saver Creation' from
  81. the icon bar.
  82.  
  83. Up to 16 icons can be created. Each icon can either be a label (descriptive text
  84. without a border), text (with an indented border - r2 border), writable (where
  85. the user can enter text/ numbers - r7 border), option (tick box) or radio (a
  86. choice of options).
  87.  
  88. Types of icons
  89. ~~~~~~~~~~~~~~
  90. Labels and text are fairly self-explanatory. The text you wish to appear is
  91. entered in the writable box at the bottom of the icon maker window. The
  92. 'H. Centered' flag sets whether the text will be centred horizontally. If it is
  93. 'Right Aligned', the text will be placed as near to the right of the window as
  94. possible.
  95.  
  96. Writable is also fairly easy to explain. This time, the white text box at the
  97. bottom is the descriptive text for the writable icon.
  98.  
  99. Option icons can either be on or off. When they are on, they usually have a
  100. tick in them.
  101.  
  102. Radio icons are a bit more difficult to explain. These are like a variety of
  103. option icons, but only one of them can be selected at any one time. The 'ESG'
  104. stands for 'Exclusive Selection Group', and for each of these groups, only one
  105. radio icon can be selected.
  106.  
  107. Colours
  108. ~~~~~~~
  109. Colours can also be set for all of the icon types, except for radio. The colours
  110. that can be chosen are the standard 16 used on the desktop. Please do not make
  111. the icons look silly by overusing colours!
  112.  
  113. Update Information Returned
  114. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  115. There is a button at the bottom of the Icon List window titled 'Update'. If
  116. this is clicked upon, it will display the type of parameter information which
  117. will be sent to the screensaver when it is loaded by AlphaSave. If there are
  118. any suitable icons, then the result will look something like:
  119.  
  120.                              {T 3}{S 4}{S 5}{S 6}
  121.  
  122. In this case, whatever is placed in the writable icon number 3 will be sent as
  123. the first parameter, and '0's or '1's (depending on whether the icon has been
  124. selected or not) sent as parameters 2, 3 and 4.
  125.  
  126. For example, let's say that the text entered by the user in icon number 3 was
  127. 'FishBang', icons 4 and 5 were selected and icon 6 was not, the returned string
  128. would be:
  129.  
  130.                              {FishBang}{1}{1}{0}
  131.  
  132. Hopefully that will make sense. If it doesn't, feel free to contact me.
  133.  
  134. ------------------------------------------------------------------------------
  135.  
  136. Programming Screensavers
  137. ••••••••••••••••••••••••
  138.  
  139. The following tutorial will tell you how to make the more up-to-date
  140. multitasking screensavers.
  141.  
  142. Step 1: Creating the screensaver directory
  143. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  144. First of all, you must create your screensaver directory. It is probably best
  145. to copy !DemoSave as another name. It is best to choose a name which roughly
  146. describes what the screensaver does (eg. !Rain, !Mirror). Try to make it a
  147. different name from those already supplied, and 10 characters or less in length.
  148.  
  149. Step 2: Screensaver resources
  150. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  151. It would be advisable to change the iconsprite of your screensaver. You may
  152. also wish to edit the !Run and !Boot files. If you wish, you can also add a
  153. !Help file.
  154.  
  155. Step 3: The 'Data' file (Icon Creator)
  156. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  157. First of all, you must open the 'Detail Files' window. This i done by clicking
  158. menu over the SaveConf icon on the icon bar, moving over to 'Saver Creation'
  159. and then 'Detail Files/Save'. Here, you can set details on your screensaver,
  160. including the name, author's name, date and a brief description. You must also
  161. make sure that 'WIMP Program' is selected so AlphaSave knows you are making a
  162. multitasking program.
  163.  
  164. If you are making your screensaver configurable by the user (i.e. it can be
  165. configured using the screensaver config window in SaveConf), see the Icon Maker
  166. section file for more information.
  167.  
  168. Step 4: The actual programming
  169. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  170.  
  171. The following will describe how the !DemoSave screensaver works.
  172.  
  173. Load the example screensaver. This is a fully working screensaver, which always
  174. changes picture. When you move/ click the mouse or press a button on the
  175. keyboard, the screensaver will exit. This is what all screensavers should do.
  176. Now I will describe how the !RunImage file works:
  177.  
  178. SYS"OS_GetEnv" TO addr$
  179.  
  180.   This just gets what parameters were sent to the screensaver, and stores them
  181.   as addr$
  182.  
  183. opt1%=VAL(FNgetquotes(addr$,1))
  184.  
  185.   This gets the setting for the first paremeter sent. As this is a selectable
  186.   icon (ie. not a writable icon), the value can either be 1 or 0. If opt1%=1
  187.   then it was selected, otherwise opt1%=0.
  188.  
  189. null$=FNgetquotes(addr$,4)
  190.  
  191.   This gets the string sent in the fourth parameter and stores it in null$.
  192.   This string must have come from a writable icon.
  193.  
  194.   The parameters sent could look something like this:
  195.  
  196.                              {1}{0}{0}{FishBang}
  197.  
  198.   opt1%=1, opt2%=0, opt3%=0, null$="FishBang"
  199.  
  200. PROCinitscrsave
  201.  
  202.   This procedure initialises the screensaver. If you look in
  203.   DEF PROCinitscrsave, you will see that it creates some arrays, sets some
  204.   default variables, starts the task, changes the mode, turns the pointer off
  205.   and opens a window.
  206.  
  207.   This window that is opened can either be a black window, or a blank window.
  208.   If the screensaver changes mode and requires a black background, you must use
  209.   PROCloadtemplate("black"). If the screensaver will do something to change the
  210.   current desktop appearence (eg. !Mirror), then PROCloadtemplate("blank")
  211.   should be used.
  212.  
  213.   PROCscrvars finds out about the current screen mode. When this is called,
  214.   xscreen% is the width of the screen, yscreen% is the height of the screen,
  215.   and res% is the resolution of the screen. This must be called before the
  216.   blank window is opened because the blank window must fill up the entire
  217.   screen.
  218.  
  219. ON ERROR PROCerror
  220.  
  221.   If an error occurs while the screensaver is active, PROCerror will be called.
  222.   This should send a message to AlphaSave saying that the screensaver has quit,
  223.   tell the user the error and quit the screensaver.
  224.  
  225. REPEAT
  226.   PROCscreensave
  227.   ...
  228. UNTIL FALSE
  229.  
  230.   This is the main loop the screensaver goes into. PROCscreensave should be
  231.   called often so it will allow other multitasking programs to do their tasks.
  232.   Usually, there will be a graphical effect happening in this loop to make the
  233.   screensaver look appealing.
  234.  
  235. Other supplied procedures
  236. ~~~~~~~~~~~~~~~~~~~~~~~~~
  237.  
  238. PROCfont
  239.  
  240.   To plot a font, use PROCfont(foreground,background,x,y,font$,text$,fontsize).
  241.   'foreground' is the foreground colour and 'background' is the background
  242.   colour used for anti- aliasing. An example would be:
  243.  
  244.              PROCfont(9,7,160,RND(800),"Corpus.Bold","DEMO",170)
  245.  
  246.   This would plot a yellow Corpus.Bold font, anti-aliased to black at
  247.   co-ordinates x=150 and y=RND(800), with the text "DEMO" and at size 170pt.
  248.  
  249. PROCwait(time)
  250.  
  251.   This procedure waits for a given amount of time PROCwait(150) will wait for
  252.   150cs, or 1.5 seconds.
  253.  
  254. PROCcheckmove
  255.  
  256.   This procedure must be called as often as possible. It checks whether the
  257.   mouse has moved, been clicked upon or a keyboard button has been pressed. If
  258.   it has, the program will call PROCend, which will end it.
  259.  
  260. PROCwimp
  261.  
  262.   This polls the WIMP
  263.  
  264. PROCloadtemplate(tempname$)
  265.  
  266.   This loads a template and stores the details in block%
  267.  
  268. PROCopenwindow(block%,win%)
  269.  
  270.   This opens a window
  271.  
  272. PROCsendmessage
  273.  
  274.   This broadcasts a WIMP message. PROCsendmessage(&4D845,0) is needed in
  275.   PROCend to tell AlphaSave that the screensaver has finished. This is
  276.   *essential* in order for AlphaSave to work.
  277.  
  278. The rules of screensaving
  279. ~~~~~~~~~~~~~~~~~~~~~~~~~
  280.  
  281. 1. There must never be the same picture on the screen for a long period of time
  282. 2. When you move the mouse or press a key, the screensaver must exit immediately
  283.  
  284. Step 5: The 'Defaults' file.
  285. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  286.  
  287. When your screensaver is installed, or the 'defaults' icon is pressed, all
  288. options will be off and writable icons empty by default. This can be changed
  289. by using a defaults file.
  290.  
  291. This is a text file in your screensaver directory. The first line of this file
  292. will be the default setting for the first icon, the second line for the second
  293. icon and so on.
  294.  
  295. If one of the icons is an option or radio icon, a value of '1' means it will
  296. be on by default, and '0' for off. For a writable icon, this will be the
  297. default text in the icon. If the icon cannot be set, eg. a label, it should
  298. have a value of '0' in the defaults file.
  299.     
  300. ------------------------------------------------------------------------------
  301.  
  302. Technical Details (not necessary for screensavers)
  303. •••••••••••••••••
  304.  
  305. AlphaSave Message Block
  306. ~~~~~~~~~~~~~~~~~~~~~~~
  307.  
  308. Message block is &4D840 - This is an official Acorn reserved message block.
  309. ------------------------------------------------------------------------------
  310.  
  311. Message_AlphaSaveAlive (&4D840)
  312.  
  313.     Checks whether AlphaSave is alive
  314.  
  315.      In: Nothing
  316.  
  317. ------------------------------------------------------------------------------
  318.  
  319. Message_AlphaSaveIsAlive (&4D841)
  320.  
  321.     Returned to say that AlphaSave is alive
  322.  
  323.      Out: q%!4 = AlphaSave task
  324.  
  325. ------------------------------------------------------------------------------
  326.  
  327. Message_AlphaSaveTimes (&4D842)
  328.  
  329.     Sent to set the AlphaSave screensaving times.
  330.  
  331.      In:
  332.       q%!20 = Number of hours
  333.       q%!24 = Number of minutes
  334.       q%!28 = Number of seconds
  335.  
  336. ------------------------------------------------------------------------------
  337.  
  338. Message_AlphaSaveInfo (&4D843)
  339.  
  340.     Asks about information on AlphaSave.
  341.  
  342.      In:
  343.       q%!20=0 : Returns version number (see below)
  344.       q%!20=1 : Returns registered status
  345.       q%!20=2 : Returns name of person who registered (or 'UNREGISTERED')
  346.       q%!20=3 : Returns key code (or 'KS0002')
  347.       q%!20=4 : Returns key date (or 'Shareware')
  348.       q%!20=5 : Returns On/Off state (screensaving is enabled or disabled)
  349.  
  350. ------------------------------------------------------------------------------
  351.  
  352. Message_AlphaSaveRecInfo (&4D844)
  353.  
  354.     Returns information sent my Message_AlphaSaveInfo.
  355.  
  356.      Out:
  357.       If (In q%!20=0): q%!20=Version number * 100
  358.       If (In q%!20=1): Unregistered: q%!20=0
  359.                          Registered: q%!20=1
  360.       If (In q%!20=2): $(q%+20)=Name of person who registered AlphaSave
  361.                                 (32 Characters)
  362.       If (In q%!20=3): $(q%+20)=Key code (32 Characters)
  363.       If (In q%!20=4): $(q%+20)=Key date (32 Chatacters)
  364.       If (In q%!20=5): q%?20=On/Off state (1=On, 0=Off)
  365.  
  366. ------------------------------------------------------------------------------
  367.  
  368. Message_AlphaSaveScrQuit (&4D845)
  369.  
  370.     Tells AlphaSave that the screensaver is quitting and that it should
  371.     continue checking for no movements to load another screensaver.
  372.  
  373.      In: Nothing
  374.  
  375. ------------------------------------------------------------------------------
  376.  
  377. Message_AlphaSaveSet (&4D846)
  378.  
  379.     Sets the state of AlphaSave.
  380.  
  381.      In:
  382.       q%!20=0 : Disables Screensaving
  383.       q%!20=1 : Enables Screensaving
  384.       q%!20=2 : Sets up time until next Wimp_Poll
  385.        q%!24 = Number of centiseconds
  386.       q%!20=3 : Sets screensaving to 'Random'
  387.       q%!20=4 : Sets screensaving to 'Ordered'
  388.       q%!20=5 : Tells AlphaSave to reload the configuration    (1.25+ only)
  389.  
  390. ------------------------------------------------------------------------------
  391.  
  392. Message_AlphaSaveUtils (&4D847)
  393.  
  394.     Allow screensavers to change certain features of AlphaSave
  395.  
  396.      In:
  397.       q%!20=0 : Load new screensaver
  398.  
  399. ------------------------------------------------------------------------------
  400.  
  401. Message_AlphaSaveDied (&4D847)
  402.  
  403.     Broadcasted to say that AlphaSave is dying
  404.  
  405. ------------------------------------------------------------------------------
  406.  
  407. Message_AlphaSaveCantScreensave (&4D848)
  408.  
  409.     Broadcasted to say that the current screensaver cannot be run (could be
  410.     due to a low-res monitor etc.) and AlphaSave should load another
  411.     screensaver
  412.  
  413.      In:
  414.       $(q%+20) : Reason why screensaver could not operate
  415.  
  416. ------------------------------------------------------------------------------
  417.  
  418. Message_AlphaSaveForced (&4D849)
  419.  
  420.     Broadcasted to AlphaSave to say that the next screensaver to be loaded
  421.     is loaded from SaveConf. This stops Message_AlphaSaveCantScreensave from
  422.     loading another screensaver and displays the reason why the screensaver
  423.     could not load. It is reset by Message_AlphaSaveScrQuit.
  424.  
  425. ------------------------------------------------------------------------------
  426.  
  427.           Please do not abuse any of these WIMP Messages in any way.
  428.  
  429. -------------------------------------------------- © 1998 Alpha Programming --
  430.