home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / a / armedit / Docs / Banner < prev    next >
Text File  |  1997-01-20  |  9KB  |  235 lines
  1. File        : Banner
  2. Date        : 20-Jan-97
  3. Author      : © A.Thoukydides, 1995, 1997
  4. Description : Description of the "Banner" application.
  5.  
  6.  
  7. INTRODUCTION
  8.  
  9. The "Banner" application displays a banner window in the desktop, either for
  10. a predetermined length of time or until it is clicked on with the mouse.
  11. It is intended to be used while an application is loading, but it may also be
  12. used for other purposes. The layout of the window is specified by a templates
  13. file, which may include requests for text substitution from an optional
  14. messages file. Anti-aliased fonts are fully supported, and sprites are loaded
  15. into the application sprite area rather than the shared wimp pool.
  16.  
  17. This application is FreeWare; it may be freely used and copied. However, I
  18. retain full copyright. See the section on "LEGAL MATTERS" for more details.
  19.  
  20.  
  21. USAGE
  22.  
  23. The syntax is:
  24.  
  25.     Banner [<time>] [-Messages <messagesfile>] [-Sprites <spritefile>]
  26.            [-Templates <templatesfile>]
  27.  
  28. where
  29.  
  30.     <time>          - The time in centi-seconds for which the window should
  31.                       be left open. If no value is specified then the window
  32.                       will remain open until the pointer is clicked on it.
  33.                       A reasonable value is 250 (for 2½ seconds).
  34.  
  35.     <messagesfile>  - The pathname of the messages file to use. The default
  36.                       filename is <Obey$Dir>.Resources.Messages.
  37.  
  38.     <spritefile>    - The pathname of the sprites file to use. The default
  39.                       filename is <Obey$Dir>.Resources.Sprites.
  40.  
  41.     <templatesfile> - The pathname of the templates file to use. The default
  42.                       filename is <Obey$Dir>.Resources.Templates.
  43.  
  44. All of the keywords may be abbreviated to their first letter. The files
  45. are used as follows:
  46.                   
  47.     Messages    - A MessageTrans file containing text to replace indirected
  48.                   text only icons with. The text following an "M" command in
  49.                   an icon validation string, up to the next semi-colon or
  50.                   terminator, is used as a token to pass to
  51.                   MessageTrans_Lookup. If a match is found then the icon text
  52.                   is replaced by the specified string, otherwise the icon
  53.                   text is unchanged. This can be used, for example, to
  54.                   display the program version number of licence details.
  55.  
  56.     Sprites     - A sprite file to be loaded into the application sprite area.
  57.                   The program first checks whether a file more suitable for
  58.                   current mode is present (e.g. Sprites23, Sprites22 etc)
  59.                   using the same rules as for IconSprites. If a high-res
  60.                   monochrome mode is being used then Sprites23 is tried,
  61.                   otherwise the file SpritesXY is tried (where X and Y are
  62.                   the number of OS units per pixel in the two directions).
  63.  
  64.     Templates   - A wimp template file which must contain a window
  65.                   definition called "banner" to be displayed.
  66.  
  67. Only the Templates file is actually required; the other two are optional.
  68.  
  69. These files can be shared with the main application; in fact it is quite a
  70. good idea to do so, e.g. a Version token in the messages file can be used for
  71. both the ProgInfo window and the banner.
  72.  
  73. It is up to the user of this program to ensure that it is given a suitably
  74. sized wimpslot. The memory required is given approximately by:
  75.  
  76.     Size of the Banner executable
  77.   + Combined sizes of the three resource files
  78.   + 6 kbytes of extra workspace
  79.  
  80. If you have alternative sprite file remember to use the size of the largest
  81. file when deciding how much memory to allocate. If there is insufficient
  82. memory to load the high-res sprites file then the standard resolution version
  83. is tried instead.
  84.  
  85. Probably the best way of using this program in the start-up of an application
  86. is to have two Obey files. The first one, "!Run", is started when the
  87. application is run:
  88.  
  89.     | > <App$Dir>.!Run
  90.     
  91.     | Set a system variable to the application directory
  92.     Set App$Dir <Obey$Dir>
  93.  
  94.     | Load the application sprites
  95.     IconSprites <App$Dir>.!Sprites
  96.  
  97.     | Check that there is likely to be sufficient memory for both programs
  98.     WimpSlot -min 576K -max 576K
  99.  
  100.     | Start the next part of the program loading once "Banner" has initialised
  101.     Filer_Run <App$Dir>.!Run2
  102.  
  103.     | Ensure that there is sufficient memory for the "Banner" program
  104.     WimpSlot -min 64K -max 64K
  105.  
  106.     | Run the banner program, leaving window open for 2.5 seconds
  107.     Run <App$Dir>.Banner 250
  108.  
  109. Remember that "Banner", unless told otherwise, will look for its resources in
  110. "<Obey$Dir>.Resources", which in this case will be the same as
  111. "<App$Dir>.Resources". The second Obey file, "!Run2", is started by the first
  112. one using a "Filer_Run" command causing it to start once the "Banner"
  113. application has started polling the wimp:
  114.  
  115.     | > !Run2
  116.     
  117.     | Load any required resources, e.g. modules
  118.     
  119.     | Check that there is still sufficient memory to run
  120.     WimpSlot -min 512K -max 512K
  121.  
  122.     | Finally start the application
  123.     Run <App$Dir>.!RunImage %*0
  124.  
  125. This is not the only way in which "Banner" can be used, but it is one of the
  126. better ways as it does not significantly increase the start-up time of the
  127. application; the application and resources can continue loading while the
  128. banner is being displayed.
  129.  
  130.  
  131. LEGAL MATTERS
  132.  
  133. The "Banner" application and documentation is supplied "as is"; no warranty,
  134. express or implied, of the merchantability of this software or its fitness
  135. for any particular purpose is given. In no circumstances shall the author, or
  136. any provider or distributor of this software, be liable for any damage, loss
  137. of profits, or any indirect or consequential loss arising out of the use of
  138. this software or inability to use this software.
  139.  
  140. This application is FreeWare. Permission is granted for anyone to distribute
  141. it unchanged and in its entirety, providing that no profit is made in the
  142. process. The "Banner" application may not be distributed if modified or
  143. incomplete; neither may it be distributed without this documentation.
  144.  
  145. To use this application, or any part of it, as part of a system or other
  146. application that is for sale (for however much and for whatever reasons) or
  147. released as copyright material then the author's express permission in
  148. writing must be obtained. The author maintains copyright on all the material
  149. supplied and reserves the right to change these conditions at any time
  150. without notice.
  151.  
  152.  
  153. CONTACTING THE AUTHOR
  154.  
  155. I would be interested in hearing of any bugs or other unexpected features in
  156. this application, and will endeavour to correct any such problems in future
  157. releases. Suggestions for improvements are also most welcome. Implementation
  158. depends upon practicability and on how much spare time I have.
  159.  
  160. If you have any comments on this program, or would like to suggest ways in
  161. which it could be improved, I can be contacted at one of the following
  162. addresses:
  163.     
  164.     Thalna
  165.     2 Dukes Drive
  166.     Bearwood
  167.     Bournemouth
  168.     Dorset
  169.     BH11 9SZ
  170.     
  171.     alex@thouky.tcp.co.uk
  172.  
  173. If in any communication you make specific reference to the program code please:
  174.  
  175.     Quote the version number and date of the application (it is contained
  176.     near the start of the executable binary).
  177.     
  178.     Refer only to the application as released.
  179.     
  180.     Supply as many details as possible about the problem, including the
  181.     hardware and software configuration of the machine being used.
  182.  
  183. Please send a stamped and self addressed envelope, or give details of how to
  184. contact via e-mail, if you would like a reply.
  185.  
  186. I hope you find this application of some use.
  187.  
  188.  
  189. ACKNOWLEDGEMENTS
  190.  
  191. I would like to the thank the following people for their contributions to
  192. the development of this application:
  193.  
  194.     Acorn Computers - The Risc PC, RISC OS and the ObjAsm assembler.
  195.     Aidan Corey     - Good ideas for improvements.
  196.     Dominic Symes   - The brilliant !Zap editor; get a copy immediately.
  197.     Robin Watts     - !Larger, the greatest backdrop program ever.
  198.     Mark Wooding    - !Glass, the best template editor.
  199.  
  200. and everyone at the Acorn User Group in Oxfor