home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / dreamscape / docs / Dreamscape / Docs / ReadMe < prev   
Encoding:
Text File  |  1996-09-28  |  7.6 KB  |  186 lines
  1.                            Dreamscape version 1.15     (28th September 1996)
  2.                           =========================
  3.  
  4. Introduction
  5. ------------
  6.  
  7. Dreamscape is a C++ class library for RISC OS 3. The current version uses the
  8. Toolbox, although a future version may be written to use the Wimp directly.
  9. Dreamscape has a lot more functionality than the other class libraries for
  10. RISC OS, and it is also better designed.
  11.  
  12. Some Dreamscape routines are also usable from C as well as C++. Dreamscape's
  13. event handling routines are much better than those provided with the Toolbox
  14. and are worth making use of even if you don't use C++.
  15.  
  16. See the Dreamscape hope page on the Web for more information:
  17.   http://www.argonet.co.uk/users/mseaborn/dscape.html
  18.  
  19.  
  20. Requirements
  21. ------------
  22. Dreamscape has been written for use with Acorn's CFront-based C++ compiler
  23. supplied with Acorn C/C++ (Cv5), and has not been tested with GNU C++ or
  24. Beebug's Easy C++. This is not much of a problem as you will need ResEd,
  25. which comes with Acorn C/C++, to write Toolbox applications, as there are no
  26. Freeware resource editors. However, if anyone tries using Dreamscape with
  27. another compiler, I would be very interested in the results.
  28.  
  29. Dreamscape uses OSLib, available from Acorn's FTP site
  30. (ftp://ftp.acorn.co.uk/). It also uses Julian Smith's make utility Makatic 2,
  31. avaialble from Hensa (ftp://micros.hensa.ac.uk/ or
  32. ftp://ftp.demon.co.uk/pub/mirrors/hensa/) under package e040. The latest
  33. version of Makatic, version 2.17, is needed.
  34.  
  35. A set of improved stubs for the Shared C Library ("asstubs") are used by the
  36. Dreamscape example programs. They are available with SDLS (the Straylight
  37. Dynamic Linking System) under package d052 on Hensa. If you don't want to
  38. bother with downloading this file, you could replace "asstubs" in each
  39. makefile with "stubs" or, more preferably, just make a copy of the "stubs"
  40. file called "asstubs".
  41.  
  42.  
  43. Long filenames
  44. --------------
  45. If you have long filenames on your computer, run the 'ExpandHdrs' file in the
  46. Utilities directory. This will give the header files their long filenames so
  47. that they can be accessed properly using long filenames. If you don't have
  48. long filenames on your computer, #including the headers using the long
  49. filename will work (providing the truncate filenames option is configured on)
  50. - you should always specify the long filename instead of the truncated
  51. filename.
  52.  
  53.  
  54. Compiling Dreamscape
  55. --------------------
  56. To save on space, this release of Dreamscape has not been compiled and does
  57. not come with the object files or library files, so you will have to compile
  58. it first to use it, although you can download the object code separately if
  59. you want. If you install Makatic 2, it would make things a lot easier to do
  60. this, as all you would have to do is double-click on !Makefile.
  61.  
  62. The best way to start off using Dreamscape would be to use the MakeApp
  63. utility to create a minimal application and experiment with it. You're
  64. welcome to look at the source code of the other examples and copy it if you
  65. want. Bear in mind that TestProg is more of a test program than an example,
  66. though, and is a bit of a mess.
  67.  
  68.  
  69. StrongHelp manual
  70. -----------------
  71. There is now a StrongHelp manual file for Dreamscape. The abstract, GUI
  72. object and gadget classes are now all documented, although the low-level,
  73. graphics and utilities classes are not.
  74.  
  75. To install the StringHelp manual, copy the Dreamscape manual file into the
  76. HelpData directory inside !StrongHlp. You will now be able to access the
  77. manual from StrongHelp’s main menu.
  78.  
  79. If you use StrongEd or Zap as your text editor, you will be able to get
  80. instant help on a keyword by placing the caret over the word and pressing F1
  81. (usually, depending on how the editor is set up). Zap is not, by default, set
  82. up to do this, so you may have to change the keymap file so that a spare key
  83. is set to execute the ‘mje_helpcontext’ command.
  84.  
  85. To get the page for a class, put the cursor over the class name and press you
  86. help key. Most of the time this will bring up the help page for the class,
  87. unless the class is nested inside another. However, you cannot get help for
  88. most methods this way, apart from a few methods that are common to many
  89. classes. The help pages for some classes have links to small pages for their
  90. methods (notably the BBox class where the purpose of the methods isn't so
  91. obvious).
  92.  
  93. If you still can't find the information you want, look at the header file.
  94. There may be classes or methods that aren't documented in the StrongHelp
  95. manual yet. Of course, with header files you have to wade through the private
  96. parts of classes and the contents of inline functions, so this isn't
  97. recommended most of the time.
  98.  
  99.  
  100. What is and isn't implemented
  101. -----------------------------
  102. Dreamscape has the following so far:
  103.  - pseudo exception handling based on setjmp/longjmp
  104.  - a string class (probably not ANSI C++ compliant though)
  105.  - STL-style linked list classes
  106.  - safe and efficient Toolbox event handling and Wimp event/message handling
  107.    (accessible from C as well as C++)
  108.  - classes for co-ordinates, bounding boxes, transformation matrices, etc.
  109.  - abstract window class
  110.  - all Toolbox objects except quit, DCS and print dbox
  111.  - all Toolbox gadgets except the draggable gadget
  112.  - abstract graphic class
  113.  - graphics classes for:
  114.     - draw files
  115.     - JPEG files
  116.     - sprite files
  117.  - the window class has the following:
  118.     - redraw handling
  119.     - click handling (including triple-click and double-drag handling)
  120.     - keyboard input handling
  121.     - drag handling (within a window)
  122.     - file/data loading
  123.  - global clipboard handling (copy and paste)
  124.  - data loading and saving (via other objects)
  125.  - memory file transfer, both send and receive
  126.  - null event handling
  127.  - methods to read screen dimensions and pixel sizes
  128.  - document and view classes (for scalable views)
  129.  - dialogue box class to handle OK, Cancel and (optionally) Save buttons
  130.  - two different types of pane handling
  131.  - list window class
  132.  - deferred delete template functions
  133.  - ...and more!
  134.  
  135. Things that need to be implemented include:
  136.  - hotkey handling (for aborting drags with Escape)
  137.  - no special key code handling (no handling of control-letter-keys)
  138.  - other Toolbox objects (just quit, DCS and print dbox)
  139.  - other Toolbox gadgets (just the draggable gadget now)
  140.  - drag and drop protocol (simple local dragging already done)
  141.  - shutdown and desktop save protocol handling
  142.  - print protocol and other print handling
  143.  - device claim protocol
  144.  - graphics class for ArtWorks files (I'll have to ask CC for documentation)
  145.  - sound and video playing (to play samples, tracks, MIDI, etc.)
  146.  - dynamic area handling
  147.  - object linking and embedding (OLE) using External Edit protocol
  148.  - support for Clares' PCA protocol
  149.  - automatic file conversion
  150.  - shifting heap handling (with Dynamite)
  151.  - multi-threading (using Simtec's API to allow the use of the Hydra)
  152.  - compression and decompression support
  153.  - ANSI C++ compliant string class
  154.  - extra list templates for easy and safe event handling
  155.  - graphics and font handling
  156.  - ...and support for lots of other things!
  157.  
  158.  
  159. Acknowledgements
  160. ----------------
  161. The header files algorithm.h and list.h were written by Paul Field
  162. (paul.field@dial.pipex.com), and are not technically a part of Dreamscape,
  163. although they may be distributed freely.
  164.  
  165.  
  166. And finally...
  167. --------------
  168. Documentation for Dreamscape is still incomplete and a little on the sparse
  169. side at the moment, so feel free to contact me if you have any problems with
  170. the library.
  171.  
  172. You can contact me via e-mail at this address:
  173.   mseaborn@argonet.co.uk
  174.  
  175. You can also contact me via snail mail, although e-mail is preferred:
  176.   102 Wilmot Way,
  177.   Banstead,
  178.   Surrey,
  179.   SM7 2QD.
  180.   (England)
  181.  
  182.  
  183. Mark Seaborn
  184. mailto:mseaborn@argonet.co.uk
  185. http://www.argonet.co.uk/users/mseaborn/
  186.