home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 5 / amigaformatcd05.iso / mui / developer / amiga-e / amigae.guide (.txt) next >
Amigaguide Document  |  1996-08-13  |  10KB  |  253 lines
  1. @DATABASE MUI-AmigaE.guide
  2. @NODE MAIN "MUI-AmigaE.guide"
  3. @NEXT INTRO
  4.               MUI DEVELOPER FILES FOR AMIGA E
  5.               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  6.     @{" First words " LINK INTRO}  IMPORTANT! READ THIS!
  7.     @{" Changes     " LINK CHANGES}  What's new ?
  8.     @{" Files       " LINK FILES}  Description of the files.
  9.     @{" Install     " LINK INSTALL}  Install the files.
  10.     @{" Problems    " LINK PROBS}  Problems with MUI and AmigaE.
  11.     @{" Future      " LINK FUTURE}  New MUI -> new files ?
  12.     @{" Author      " LINK AUTHOR}  and copyright.
  13.     @{" Disclaimer  " LINK DISCLAIMER}  No warranty!
  14. @ENDNODE
  15. @NODE INTRO "First words"
  16. @PREV MAIN
  17. @NEXT CHANGES
  18. @TOC MAIN
  19.                 FIRST WORDS
  20.                 ~~~~~~~~~~~
  21.    I moved (from Passau to Hamburg)! Because of that, I lost my old e-mail
  22. address (schulzj@fmi.uni-passau.de) and @{" my snail-mail address " LINK AUTHOR} has changed
  23.    I try to get a new e-mail address as soon as possible, but if you read
  24. this, I didn't had this new e-mail address as this MUI version was ready for
  25. distributing. So, this Amiga-E files are maybe not 100% uptodate. Have a
  26. look at the file @{" Modules/libraries/diffs.readme " LINK F_DIFFS} to see, which struct's
  27. and #defines of the original mui.h are not in the Amiga-E file. If necessay,
  28. I will distribute a "muiXXEdev.lha" with the completed Amiga-E files ASAP.
  29.    There are some other importand @{" changes " LINK CHANGES}, have a look at them!
  30. @ENDNODE
  31. @NODE CHANGES "Changes"
  32. @PREV INTRO
  33. @NEXT FILES
  34. @TOC MAIN
  35.                   CHANGES
  36.                   ~~~~~~~
  37. Changes from "mui23Edev.lha":
  38.   - E versions <3.1a are no longer supported to keep the total size of this
  39.     Amiga-E files reasonable. If you still use E v2.1b than update now or
  40.     use "mui23Edev.lha".
  41.   - The modules in "Modules/libraries" are partly generated automaticly by
  42.     Stefan Stuntz. Because he has no e-compiler, and to keep the number of
  43.     files small, only the source-code of this modules is provided. You have
  44.     to compile them into an e-module by yourself. (see @{" Install " LINK INSTALL})
  45. @ENDNODE
  46. @NODE FILES "The Files"
  47. @PREV CHANGES
  48. @NEXT INSTALL
  49. @TOC MAIN
  50.                 THE FILES
  51.                 ~~~~~~~~~
  52.     Modules/        @{" muimaster.m  " LINK F_MUIMASTER}
  53.     Modules/libraries/  @{" mui.e        " LINK F_MUIE }
  54.                 @{" muip.e       " LINK F_MUIPE}
  55.                 @{" diffs.readme " LINK F_DIFFS}
  56.     Examples/        @{" MUI-Demo.e   " LINK F_MUIDEMOE}
  57. @ENDNODE
  58. @NODE F_MUIMASTER "Files: Modules/muimaster.m"
  59. @PREV F_MUIMASTER
  60. @NEXT F_MUIE
  61. @TOC FILES
  62.                 "Modules/muimaster.m"
  63.                 ~~~~~~~~~~~~~~~~~~~~~
  64.    This file defines the functions of the muimaster.library. Copy it to
  65. EMODULES: and to use it write in your source:
  66.     MODULE 'muimaster'
  67. ATTENTION: With "mui22Edev2.lha" I changed the names of the functions from
  68. MuI_... to Mui_... (Lionel Vintenat (Mac2E) told me that Mui_... looks
  69. nicer and I think he's right.) Maybe you have to change your old sources
  70. to use this file.
  71. @ENDNODE
  72. @NODE F_MUIE "Files: Modules/libraries/mui.e"
  73. @PREV F_MUIMASTER
  74. @NEXT F_MUIPE
  75. @TOC FILES
  76.              "Modules/libraries/mui.e"
  77.              ~~~~~~~~~~~~~~~~~~~~~~~~~
  78.    This is the source-file of the e-module "mui.m". This module contains a
  79. complete translation of the original C mui.h file with only one exception:
  80. The muip_... OBJECTs are moved to the file @{" Modules/libraries/muip.e " LINK F_MUIPE}.
  81.    The #defines (and CONSTs) are written exactly the same way as in the
  82. mui.h file (with one exception: The macro String() is renamed to StringMUI()
  83. to avoid conflicts with the E function String()). The identifiers of the
  84. OBJECTs are all written totaly lowercase!!
  85.    Compile this file with the e-compiler and copy the "mui.m" you get as
  86. result to "EMODULES:libraries/mui.m". To use this module write in your
  87. source:
  88.     MODULE 'libraries/mui'
  89.    Don't forget to add "OPT PREPROCESS" to your source, if you want to use
  90. the macros!
  91.    See also: @{" Modules/libraries/muip.e " LINK F_MUIPe}
  92. @ENDNODE
  93. @NODE F_MUIPE "Files: Modules/libraries/muip.e"
  94. @PREV F_MUIE
  95. @NEXT F_DIFFS
  96. @TOC FILES
  97.              "Modules/libraries/muip.e"
  98.              ~~~~~~~~~~~~~~~~~~~~~~~~~~
  99.    This is the source for the e-module "muip.m". It contains all the
  100. MUIP_...-structs of the original C mui.h file as OBJECT's. I think, this
  101. OBJECT's are not very usefull in E, that's why I didn't include them in the
  102. first releases. But to have a complete AmigaE-MUI-Interface...
  103.    Compile this file with the e-compiler and copy the "muip.m" you get as
  104. result to "EMODULES:libraries/muip.m". To use this module write in your
  105. source:
  106.     MODULE 'libraries/muip.m'
  107. @ENDNODE
  108. @NODE F_DIFFS "Files: Modules/libraries/diffs.readme"
  109. @PREV F_MUIPE
  110. @NEXT F_MUIDEMOE
  111. @TOC FILES
  112.             "Modules/libraries/diffs.readme"
  113.             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  114.    This file contains a list of all struct's and #defines of the mui.h
  115. file, which are not translated into E. (See @{" First words " LINK INTRO} for the reason!)
  116.    If you need one of them, look at the mui.h file, or wait for an update
  117. of this AmigaE-files (available as "dev/e/muiXXEdev.lha" on aminet).
  118.    I hope this list is not too long! :-|
  119. @ENDNODE
  120. @NODE F_MUIDEMOE "Files: Examples/MUI-Demo.e"
  121. @PREV F_DIFFS
  122. @NEXT F_MUIDEMOE
  123. @TOC FILES
  124.                 "Examples/MUI-Demo.e"
  125.                 ~~~~~~~~~~~~~~~~~~~~~
  126.    This is a translation of the C demo-source "MUI-Demo.c" that came with
  127. MUI v2.1. Use it to see, how to write MUI-programms in E and where are the
  128. differences between C and E.
  129.    See also: @{" Problems " LINK PROBS}
  130. @ENDNODE
  131. @NODE INSTALL "Install"
  132. @PREV FILES
  133. @NEXT PROBS
  134. @TOC MAIN
  135.                   INSTALL
  136.                   ~~~~~~~
  137.     To install the AmigaE-MUI-files do the following:
  138.     1. Open a shell
  139.     2. CD into the 'Developer/Amiga-E/Modules' directory
  140.     3. execute 'COPY muimaster.m EMODULES:'
  141.     4. CD into the 'libraries' subdirectory
  142.     5. call the e-compiler with 'EC mui.e'
  143.     6. execute 'COPY mui.m EMODULES:libraries/mui.m'
  144.     7. call the e-compiler with 'EC muip.e'
  145.     8. execute 'COPY muip.m EMODULES:libraries/muip.m'
  146. @ENDNODE
  147. @NODE PROBS "Problems with MUI and E"
  148. @PREV INSTALL
  149. @NEXT FUTURE
  150. @TOC MAIN
  151.                PROBLEMS WITH MUI AND E
  152.                ~~~~~~~~~~~~~~~~~~~~~~~
  153.         @{" MUI_TRUE    " LINK P_TRUE}  Why a CONST MUI_TRUE?
  154.         @{" SetAttrsA() " LINK P_SETATTRSA}  Problems with set()
  155.         @{" TAG_IGNORE  " LINK P_TAGIGNORE}  Why "TAG_IGNORE,0," in some macros?
  156. @ENDNODE
  157. @NODE P_TRUE "Problems: TRUE=1 or TRUE=-1"
  158. @PREV P_TRUE
  159. @NEXT P_SETATTRSA
  160. @TOC PROBS
  161.                   TRUE=1 or TRUE=-1
  162.                   ~~~~~~~~~~~~~~~~~
  163.    In C TRUE has the value 1 but in E TRUE has the value -1. That can cause
  164. problems, therefore a CONST "MUI_TRUE" with value 1 is defined in
  165. @{" Modules/libraries/mui.e " LINK F_MUIE}. Use this one instead of TRUE whenever you want
  166. to give TRUE to MUI. See "Examples/MUI_Demo.e".
  167. @ENDNODE
  168. @NODE P_SETATTRSA "Problems: Problem with SetAttrsA()"
  169. @PREV P_TRUE
  170. @NEXT P_TAGIGNORE
  171. @TOC PROBS
  172.               Problem with SetAttrsA()
  173.               ~~~~~~~~~~~~~~~~~~~~~~~~
  174.    Whenever you try to set an attribut to the value it allready has, MUI
  175. overwrites this attribut in the taglist with TAG_IGNORE to make shure that
  176. notify-class don't react on it. This is nessesary to prevent endless-
  177. notification-loops. As long as you are a C programmer and use SetAttr()
  178. that is no problem, because MUI then changes only a *copy* of the original
  179. datas of the SetAttrs()-call. But if you use SetAttrsA(), as we must do
  180. because SetAttrs() is a function of amiga.lib, it is a problem! You only
  181. give a PTR to the original-datas with SetAttrsA() and now MUI changes this
  182. *original* datas. If you then uses this datas again at the next execution
  183. of the same SetAttrsA()-call, the datas are still changed and nothing
  184. (TAG_IGNORE) will happen :-(
  185.    One possible way to avoid this problem is, to make the attribut a non-
  186. constant data. Instead of
  187.    SetAttrsA(obj, [ MUIA_..., value, ..., TAG_DONE])
  188. write
  189.    SetAttrsA(obj, [Eval(`(MUIA_...)), value, ..., TAG_DONE])
  190.            ~~~~~~~        ~~
  191. Now everytime this SetAttrsA()-call is executed, the attribute is again
  192. "evaluated" and stored in the list.
  193.    BUT: x:=[Eval(`(MUIA_...)),...]; SetAttrsA(obj,x); SetAttrsA(obj,x) has
  194. *NOT* the wished result, because the non-constand datas of the LIST are only
  195. evaluated when x is assigned to to the LIST but not everytime this PTR to
  196. the LIST in x is used later!
  197.    To avoid the SetAttrsA()-problem the macros set() (and nnset()) in the
  198. file @{" Modules/libraries/mui.e " LINK F_MUIE} are defined like this:
  199.   #define set(obj,attr,value) SetAttrsA(obj,[Eval(`(attr)),value,TAG_DONE])
  200.    The global variable "setAttrsA" that was needed with the set() and
  201. nnset() of former releases is now obsolete.
  202. @ENDNODE
  203. @NODE P_TAGIGNORE "Problems: TAG_IGNORE,0"
  204. @PREV P_SETATTRSA
  205. @NEXT P_TAGIGNORE
  206. @TOC PROBS
  207.                 TAG_IGNORE,0
  208.                 ~~~~~~~~~~~~
  209.    Some of the macros in @{" Modules/libraries/mui.e " LINK F_MUIE} are ending with
  210. "[TAG_IGNORE,0,". That seems to be superfluous but it is needed, because in
  211. AmigaE v2.1b if you want to split a statement over several lines, you can't
  212. end a line with "[" but with a comma. And with AmigaE v3.1 it's needed to
  213. allow the same use of the macros.
  214. @ENDNODE
  215. @NODE AUTHOR "Author"
  216. @PREV FUTURE
  217. @NEXT DISCLAIMER
  218. @TOC MAIN
  219.                    AUTHOR
  220.                    ~~~~~~
  221.    IMPORTANT NOTE: I moved and my address changed! (see @{" First words " LINK INTRO})
  222.     Snail mail (new):  Jan Hendrik Schulz
  223.                Lewetzauweg 16
  224.                22455 Hamburg
  225.                Germany
  226.     e-mail:           no e-mail address available now!
  227. @ENDNODE
  228. @NODE FUTURE "Future"
  229. @PREV PROBS
  230. @NEXT AUTHOR
  231. @TOC MAIN
  232.                    FUTURE
  233.                    ~~~~~~
  234.    I try to get a new e-mail address ASAP, and I hope the next MUI version
  235. will come with an uptodate AmigaE-Interface...
  236.    If you have some ideas to make things better, please write @{" me " LINK AUTHOR}.
  237. @ENDNODE
  238. @NODE DISCLAIMER "Disclaimer"
  239. @PREV COPYRIGHTS
  240. @NEXT DISCLAIMER
  241. @TOC MAIN
  242.                  DISCLAIMER
  243.                  ~~~~~~~~~~
  244.    This files are provided "AS IS" without warrenty of any kind, expressed
  245. or implied! I'm NOT liable to you for damages or problems, including any
  246. general, special, incidental or consequential damages or problems arising
  247. out of the use or inhability to use of the files. Including but not limited
  248. to loss of data or data being rendered inaccurate or losses sustained by you
  249. or third parties or a failure of a program build with this files.
  250.    (I hope you know what I want to say! My english is not good enough to
  251. write such legal stuff!)
  252. @ENDNODE
  253.