home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / toollib_2 / !ReadMe < prev   
Text File  |  1996-07-19  |  7KB  |  198 lines
  1. ToolLib v1.13 - 14/6/1996 (c) Paul Field
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3. ToolLib is a library of functions for OSLib/Toolbox programmers. Although
  4. fairly small at the moment, it has some powerful features such as exception
  5. handling and interfaces to the Toolbox SaveAs system that make Type 3 saving
  6. (i.e. in-memory or file) a complete doddle.
  7.  
  8. You'll find a fair amount of documentation in the library header files
  9. and the example applications demonstrate how to use the major features of
  10. the library.
  11.  
  12.  
  13. Facilities provided by ToolLib
  14. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15.  
  16. allocate     This is a simple wrapper for the malloc() functions which
  17.              throws exceptions when memory allocation fails.
  18.             
  19. application  This is an application framework which sets up the facilities
  20.              a toolbox application will need (e.g. toolbox initialisation,
  21.              Quit message/event handlers, error handlers) and performs
  22.              the event polling loop.
  23.             
  24. backtrace    Generates a stack backtrace on stderr (useful for
  25.              debugging - especially exceptions).
  26.  
  27. box          Various routines for dealing with os_box (e.g. clipping,
  28.              detecting overlaps).
  29.  
  30. ci_string    Routines for case-insensitive comparison of strings
  31.  
  32. error        This is a system for reporting errors (mainly exceptions).
  33.  
  34. exception    This is a system for handling errors using an exception system
  35.              similar to C++. It's not as powerful as C++'s exceptions but
  36.              it's far better (easier to use, reliable) than passing error
  37.              codes around (or not checking for errors at all).
  38.             
  39. fast_trig    Routines for performing trigonomic functions very quickly.
  40.  
  41. list         A list data type.
  42.  
  43. message      An interface to MessageTrans which enables you to look up
  44.              messages from the Messages files.
  45.             
  46. nevent       An event handling system, similar to Acorn's event library
  47.              but with more advanced facilities and debugging checks.
  48.  
  49. nev_message  Allows you to register handlers for Wimp messages.
  50.  
  51. nev_toolbox  Allows you to register handlers for Toolbox events.
  52.  
  53. nev_wimp     Allows you to register handlers for Wimp events.
  54.  
  55. saver        In combination with save_buffer this completely handles type 3
  56.              data transfer from a saveas object.
  57.  
  58. save_buffer  Provides a uniform interface for data transfer either to a file
  59.              or another application (using type 3 transfer).
  60.  
  61. set          A set data type.
  62.  
  63. shifting     An alternative to flex which throws exceptions on error and
  64.              provides a 'better' interface (including debug checks).
  65.  
  66. shifting_send Allows data from shifting blocks to be sent to the save buffer.
  67.             
  68. tbx          General toolbox utilities (currently just one function to return
  69.              the task name).
  70.  
  71. text_plot    Functions for plotting text using the desktop font (using
  72.              Wimp_TextOp in RISC OS 3.5+ and an alternative method in
  73.              earlier OS versions).
  74.  
  75. Further details of each system is given in the system's header file.
  76. A detailed introduction to the exception handling system appears
  77. in CAUGers 3:2.
  78.  
  79.  
  80. Compiling an application
  81. ~~~~~~~~~~~~~~~~~~~~~~~~
  82. You will need to link your application against the following libraries:
  83.  
  84.   ToolLib:o.ToolLib  (or ToolLib:o.ToolLibDbg for the debug version)
  85.   C:o.flexlib        (only necessary if you use the shifting system)
  86.   C:o.stubs
  87.   OSLib:o.OSLib
  88.  
  89. Have a look at the example applications and their MakeFiles for a starting
  90. point.
  91.  
  92.  
  93. The debug version
  94. ~~~~~~~~~~~~~~~~~
  95. The library ToolLib:o.ToolLibDbg is a debug version of the ToolLib library.
  96. It performs a large number of integrity checks (using assert()), for example
  97. on function arguments, and also produces a stack backtrace on stderr whenever
  98. an exception occurs (so it's easy to find out where things went wrong).
  99.  
  100. When using the debug version of ToolLib you are advised to redirect the
  101. standard error stream as described in CAUGers 1:3 and 1:4.
  102. All of the example programs redirect the error stream to pipe:$.debug - 
  103. look at their initialisation code to see how.
  104.  
  105.  
  106. The memory-checking version
  107. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  108. The library ToolLib:o.ToolLibMem is a memory-checking version of the
  109. ToolLib library for use with Julian Smith's MemCheck system.
  110. The library will automatically initialise the system and make these
  111. calls:
  112.    MemCheck_SetStoreMallocFunctions(1);
  113.    MemCheck_InterceptSCLStringFunctions();
  114.  
  115. The shifting system will automatically register its memory blocks with the
  116. MemCheck system.
  117.  
  118.  
  119. The profiling version
  120. ~~~~~~~~~~~~~~~~~~~~~
  121. The library ToolLib:o.ToolLibPrf is for use with Julian Smith's
  122. HierProf profiling system. If you use ToolLib's application.h
  123. then profiling will be automatically initialised and output
  124. automatically generated when the program terminates.
  125.  
  126.  
  127. The future
  128. ~~~~~~~~~~
  129. As I continue to develop applications I will extend this library.
  130. If you develop useful routines based on OSLib and/or using exceptions please
  131. send them to me so I can include them in the library.
  132.  
  133.  
  134. Help!
  135. ~~~~~
  136. If there's anything you don't understand please let me know so I can improve
  137. the library and its documentation. If you have any sensible criticisms of the
  138. code (stylistic, organisational or whatever) please also let me know.
  139.  
  140.  
  141. History
  142. ~~~~~~~
  143. v1.10 - added abstract data types: list and set
  144.  
  145. v1.11 - added shifting_send
  146.         changed to use Makatic for building
  147.         added memory-checking build
  148.         added profiling build
  149.         changed action_QUIT to 0x82a91 to match Toolbox quit objects' quit message
  150.  
  151. v1.12 - new nevent system
  152.         changes to list and set ADTs (to use list_ptr and set_ptr)
  153.         added ci_string
  154.         exception now catches SIGABRT (catches assert() failures)
  155.         changes to error and message: error now reports strings and
  156.            so messages doesn't need to look up messages for error blocks.
  157.         added error_report_information()
  158.         added message_lookup_in_list()
  159.            
  160.  
  161. v1.13 - added text_plot
  162.  
  163.  
  164.  
  165.  
  166. Known problems/limitations
  167. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  168. There is currently no way to deal with user_message_acknowledge in the 
  169. nevent system
  170.  
  171. Invlidation of list_ptrs by certain list calls is not currently checked
  172. by the list system.
  173.  
  174. List test harness doesn't test list_ptr violations
  175.  
  176. Set is based on lists and so uses a linear search algorithm: using a
  177. (appoximately) balanced tree data structure (e.g. AVL trees,
  178. red-black trees) would be better.
  179.  
  180.  
  181.  
  182. Contact details
  183. ~~~~~~~~~~~~~~~
  184. Paul Field
  185. Editor of CAUGers
  186. 346 Chadwell Heath Lane
  187. Chadwell Heath
  188. Romford
  189. Essex
  190. RM6 4YH
  191. UK
  192.  
  193.  
  194. phone:   uk:   0 181 598 9676
  195.      non-uk: +44 181 598 9676
  196.  
  197. email: paul.field@dial.pipex.com
  198.