home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 28 / amigaformatcd28.iso / -seriously_amiga- / programming / c / oui / readme.first < prev    next >
Text File  |  1998-04-23  |  5KB  |  135 lines
  1. Object User Interface is copyright © 1998, Dominique Lorre
  2.  
  3. First, I would like to apologize for the lack of documentation.
  4. The explanation for this is that :
  5. - OUI has been designed to suit my needs
  6. - The interface is changing so often that any documentation would have
  7. become obsolete quickly.
  8.  
  9. The reasons why I am releasing OUI are :
  10.  
  11. - It may be of benefit to the Amiga community
  12. - I am tired of coding examples programs in C, which produce very long code
  13.   and make me reinvent the wheel at each time.
  14.  
  15. A note about GNU compiler
  16.  
  17. The GNU compiler is distributed with the GNU general public license.
  18. Making a GNU OUI version is possible via a file named fstabs.h which is
  19. distributed under this license. This should not mean that OUI is following
  20. this license. If this is a problem to anyone, just tell me and I will simply
  21. remove the GNU support since the additional file is not needed by OUI but by
  22. the GNU compiler itself.
  23.  
  24. OUI is distrbuted under Copyrighted freeware. Feel free to use and modify this
  25. files as long as you are developping for the Amiga OS. If you want to release
  26. add-ons for OUI, feel free to do it but your files should not be mixed with
  27. the OUI main archive (oui.lha).
  28.  
  29.  
  30. A note about GUI systems
  31.  
  32. OUI is not a GUI system, it is a C++ encapsulation of some AmigaOS functions.
  33. Making OUI work with any GUI system should not be a problem.
  34.  
  35.  
  36. What is OUI ?
  37.  
  38. OUI provides the following services for the C++ developper :
  39.  
  40. locale support (independent, locale.cc, include/locale.h)
  41. The locale support provides a lstring class which has the ability of creating
  42. CatComp descriptors files automatically. You can use these features without
  43. using any other feature of OUI.
  44.  
  45.  
  46. memory support (independent, new.cc, include/new.h)
  47. The memory support provides a pool based memory allocation. It does not
  48. handles exceptions but rather provides an Oxygene feature which is a small
  49. amount of memory released by the application when things are going wrong.
  50. This can help the user quitting safely its applications when memory has
  51. gone out. A side effect of this is that OUI programs cannot be tested with
  52. memoration since memoration will eat the Oxygene pool as soon as OUI release it.
  53. Of course, any data allocated with new will be released on program exit wether
  54. or not you use delete on it.
  55.  
  56. list support (independent, slist.cc, include/slist.h)
  57. These lists are much like the AmigaOS ones. Because of the virtual functions
  58. I decided to not declare the nodes as AmigaOS MinNodes.
  59.  
  60. screens, windows and gadgets support (the big stuff).
  61. The principle is the following :
  62. Each OUI application which plans to use windows must declare a screen.
  63. A screen can be a custom screen or a lock on a public screen.
  64. The screen class contains useful informations such as the size, the ratio
  65. and also tries to calculate extra pens (such as RED and GREEN).
  66.  
  67. A window is opened in two step :
  68. first you use the new operator on it with the parameters you declared in
  69. the class (for example the size).
  70. second, you open it with others parameters (for example the screen pointer).
  71.  
  72. When you open a window you may add gadgets to it. For this you should allocate
  73. a gadgetlist with the maximum number of gadgets you plan to use. This is quite
  74. boring but I did not found a better way yet (Any idea ?). Then you add the gadgets
  75. to the gadget list. The gadets can be of gadtools, Boopsi or anywhere else.
  76.  
  77. The window class also provides support for special rendering such as background
  78. Bitmaps, areadraw and clipping.
  79. Many other system functions have also been encapsulated. Menu functions were
  80. added and also the cleanup code has been carefully designed. When processing
  81. events, you will have control on the way you want to handle these. Keyboard
  82. support has been added.
  83.  
  84. In conclusion, the first window application I have ported from C to C++
  85. has been reduced from 1400 lines to 700 for the same functionnalities.
  86.  
  87.  
  88. Evolution of OUI.
  89.  
  90. I do not guarantee anything except this : the set() gadgets functions are planned to
  91. move to a TagItem version and are guaranteed to change. The locale, new and slist
  92. support should not change much. When upgrading oui, the best thing will be
  93. to recompile every module, and sometime you will have to modify some of your code.
  94. Of course, this warning is excessive but it happened in the past that I had to
  95. make big modifications in the interface.
  96.  
  97. Installing OUI
  98.  
  99. The best is to create a drawer named OUI and another named Ulib and to assign
  100. Ulib: to this drawer. Then you place the OUI code in the OUI drawer and the
  101. library itself in Ulib:. The Oui_localise version is for making .ct and .cd
  102. files automatically and is generally not much used.
  103.  
  104. Compiling OUI
  105.  
  106. If you use SAS/C the call is :
  107.  
  108. SMake -b smakeXXX.def where XXX is your compiler flavor.
  109.  
  110. For GNU you will find the appropriate GNUMakefile.
  111.  
  112.  
  113. Compiling with OUI
  114.  
  115. Do not forget to add XXX/OUI/include and XXX/OUI/include/gadgets to your
  116. INCLUDE path (XXX is the Path where you created the OUI drawer).
  117.  
  118. Programming example :
  119.  
  120. You should look to the envman.lha archive for a complete example of programming
  121. with oui.
  122.  
  123. HWGRCS support
  124. You can use the ciall file for automatical RCS support if you plan to use your custom
  125. OUI. The ciall.lha archive will be uploaded separately.
  126.  
  127. The Author:
  128. You can reach me at :
  129. Dominique Lorre
  130. le Fabary, BAT C
  131. 4, Allée des Peupliers
  132. 13100 Aix-en-Provence, FRANCE
  133. EMAIL: dlorre@caramail.com
  134.  
  135.