home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / MUI / MUI22E.LHA / Amiga-E / ReadMe < prev   
Encoding:
Text File  |  1994-08-11  |  9.7 KB  |  235 lines
  1.  
  2.                    INTRODUCTION
  3.                    ~~~~~~~~~~~~
  4.  
  5.    The original files for Amiga-E programmer that came with the developer
  6. archive of MUI until now are not very usefull.
  7.    The muimaster.m file, that should define all the functions of the
  8. muimaster.library, is not up-to-date, and the mui.e file is only a very bad
  9. replacement for the mui.h file that C programmer could use!
  10.  
  11.    Thats why I created my own MUI-AmigaE-interface. This archive (as a
  12. replacement for the original Amiga-E drawer of the MUI developer archive)
  13. contains nearly all what's needed to write MUI-programs in E and some
  14. additional informations in this file! The only "extra" you need (to use the
  15. macrofile) is the program "Mac2E". (Mac2e can be found e.g. in the
  16. AmigaE v3 distribution)
  17.  
  18.  
  19.                  CHANGES
  20.                  ~~~~~~~
  21.                   
  22. - New modules for MUI 2.2 (Only "modules/libraries/mui.m" is new)
  23. - New filename-extensions to give a better indication of the filetype
  24. - Some new files
  25. - Sourcecodes etc. changed to use tabs instead of spaces were possible to
  26.   decrease filesize. (Use an editor or textviewer with tabstops at every
  27.   8th column to get correct textformating!)
  28.  
  29.  
  30.  
  31.                THE NEW FILENAME-EXTENSIONS
  32.                ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  33.  
  34. ".e"   - An E-sourcecode that could be compiled directly.
  35. ".m"   - An E-module file.
  36. ".em"  - An E-Sourcecode with some macros. Mac2E is needed to create the
  37.      E-Sourcecode (".e") for the E-compiler EC.
  38. ".ma"  - This is a macrofile. Use PreMac2E to build the pre-analysed
  39.      macrofile (".pma").
  40. ".pma" - And this is a pre-analysed macrofile
  41.  
  42.  
  43.  
  44.                 THE FILES
  45.                 ~~~~~~~~~
  46.  
  47. "ReadMe" - This file. Please read the entire file before mailing me some-
  48.    thing like: "This files are creating only errors, what make I wrong?"
  49.    There are some special problems with MUI and Amiga-E which can cause
  50.    big trouble :-(
  51.    Go on reading and don't make this faults :-)
  52.  
  53. "Modules/muimaster.m" - This file defines the functions of the
  54.    muimaster.library. Copy it to EMODULES: and write "MODULE 'muimaster'"
  55.    in your source to use it.
  56.  
  57. "Modules/libraries/mui.m" - This file (and the next one) contain the most
  58.    definitions of the mui.h file that came for C programmer with the
  59.    developer archive of MUI 2.2. Use this C mui.h file with its comments to
  60.    get more information about this definitions!
  61.       In this mui.m module all CONSTs and the structs (OBJECTs) which are
  62.    of interest for E programmer, are defined. To see which structs are in
  63.    this module, use the ShowModule-tool that came with the E compiler.
  64.    Therefore all OBJECTs are collected at the beginning of the module.
  65.       The CONSTs are written exactly the same way as in the mui.h file
  66.    (with lowercase letters - that is no problem as long as the two first
  67.    are uppercase, even if the E-language-description says that CONSTs have
  68.    to be totaly uppercase!) So it's no problem to use this files even if
  69.    you had used the macrofile that came with "Mac2E" until now. 
  70.       The identifiers of the OBJECTs are written totaly lowercase!!
  71.       Copy this file to EMODULES:libraries/ and write
  72.    "MODULE 'libraries/mui'" in your source to use it.
  73.  
  74. "MacroFiles/mui.ma" - This file contains the most macro definitions of the
  75.    mui.h file which are, caused by the limitations of E, not in the file
  76.    above. Only "the most", because some of them couldn't be translated to
  77.    E, but they are not very important.
  78.       To use this file and its macrodefinitions you need the program
  79.    "Mac2E", and if you use a version >= 3 of "Mac2E" you need the pre-
  80.    analysed macrofile (see below) which can allso be build with "PreMac2E"
  81.    and this file.
  82.       As a result of moving the CONSTs to the E-module-file mui.m above,
  83.    instead of using only one macrofile like the one that came with "Mac2E",
  84.    it's possible to write MUI programs *without* using this macrofile and
  85.    "Mac2E", but I wouldn't do it!!! With this macrofile it's possible to
  86.    write MUI programs in E nearly the same way as in C.
  87.       The more interesting advantage of puting the CONSTs in a E-module is
  88.    the much more readable source after using "Mac2E". Sometimes - not
  89.    often, but sometimes - it's better to search an error in the source that
  90.    was created by "Mac2E" and than it's better to read
  91.    "MUIA_String_Contents" instead of "$80428FFD".
  92.       The macronames are written the same way as the C originals in mui.h -
  93.    with one exception: The macro "String()" is renamed to "StringMUI()" to
  94.    avoid conflicts with the E-Function String()
  95.       Copy this file to ... where you want it - for example in a
  96.    MacroFiles-directory in your Amiga-E-directory.
  97.  
  98. "MacroFiles/mui.pma" - This is the pre-analysed version of the macrofile
  99.    "MacroFiles/mui.ma" above.
  100.  
  101. "Sources/doMethod.e" - To write MUI programs, you need a DoMethod function.
  102.    Because this function is part of the amiga.lib, which we don't have as E
  103.    programmer, you have to use your own one, or better use this one written
  104.    by Wouter van Oortmerssen.
  105.       Copy it into your source to use it and look at the demo-source
  106.    "Sources/MUI_Demo.em" to see, how to use it.
  107.  
  108. "Modules/tools/domethod.m" - This is the domethod-funktion as E-module for
  109.    the new AmigaE v3. Copy it to EMODULES:tools/ and you can simply write
  110.    "MODULE 'tools/domethod'" inside your source if you need it.
  111.  
  112. "Source/installhook.e" - Sometimes - for example if you use PopUps - you
  113.    need hooks. This source gives you a PROC that makes it very easy to
  114.    install the needed hook-structures. Look at this source (the comments)
  115.    and the demo-source "Sources/PopUp.em" to see, how to use it.
  116.       This source (without the comments) and an E-module of it can also be
  117.    found in the AmigaE v3 distribution. It's only still included here for
  118.    users of the old AmigaE v2.1b.
  119.  
  120. "Source/installhook2.e" - Special version of installhook. Use it, if you
  121.    don't need a pointer to the hookstructure inside your hookfunktion.
  122.    Because of the differend names you can use both versions in the same
  123.    source.
  124.  
  125. "Modules/tools/installhook2.m" - This is the installhook2-funktion above
  126.    as E-module for the new AmigaE v3. Copy it to EMODULES:tools/ and you
  127.    can simply write "MODULE 'tools/installhook2'" inside your source if
  128.    you need it.
  129.  
  130. "Source/MUI-Demo.em" - This is a translation of the C demo-source
  131.    "MUI-Demo.c" that came with MUI. Use it to see, how to write MUI-
  132.    programms in E and where are the differences between C and E.
  133.  
  134. Source/MUI-Demo.e" - This is the source above after running it through
  135.    Mac2E. You can directly compile it.
  136.  
  137. "Source/PopUp.em" - This is a translation of the demo-source "PopUp.c" that
  138.    came with MUI. Use it to see, how to use the installhook-PROC.
  139.  
  140. "Source/PopUp.e" - And again the source after the usage of Mac2E.
  141.  
  142.  
  143.  
  144.              PROBLEMS WITH MUI AND E
  145.              ~~~~~~~~~~~~~~~~~~~~~~~
  146.  
  147.                 TRUE=1 or TRUE=-1
  148.                 -----------------
  149.  
  150.    In C TRUE has the value 1 but in E TRUE has the value -1. That can cause
  151. problems, therefore a CONST "MUI_TRUE" with value 1 is defined in
  152. "Modules/libraries/mui.m". Use this one instead of TRUE whenever you want
  153. to give TRUE to MUI. See "Sources/MUI_Demo.em" and "Sources/PopUp.em"
  154.  
  155.  
  156.             Problem with SetAttrsA()
  157.             ------------------------
  158.  
  159.    Whenever you try to set an attribut to the value it allready has, MUI
  160. overwrites this attribut in the taglist with TAG_IGNORE to make shure that
  161. notify-class don't react on it. This is nessesary to prevent endless-
  162. notification-loops. As long as you are a C programmer and use SetAttr()
  163. that is no problem, because then MUI changes only a *copy* of the original
  164. datas of the SetAttrs()-call. But if you use SetAttrsA(), as we must do
  165. because SetAttrs() is a function of amiga.lib, it is a problem! You only
  166. give a PTR to the original-datas with SetAttrsA() and now MUI changes this
  167. *original* datas. If you than uses this datas again, they are still changed
  168. and nothing (TAG_IGNORE) will happen. One possible way to avoid this
  169. problem is, to make the attribut a non-constant data. Instead of
  170.  
  171.    SetAttrsA(obj, [ MUIA_..., value, ..., TAG_DONE])
  172.  
  173. write
  174.  
  175.    SetAttrsA(obj, [ var + MUIA_..., value, ..., TAG_DONE])
  176.            ~~~~~~~
  177. with var=0. Now everytime this SetAttrsA()-call is executet, the attribute
  178. is again "evaluated" and stored in the list.
  179.    Because of that I have defined the macros set() and nnset() in
  180. "MacroFiles/mui.ma" this way and if you want to use them you have to DEFine
  181. a global(!) variable setAttrsA in your source and set it to 0 !!!
  182. (E.g. with DEF setAttrsA=0)
  183.    BUT: x:=[...]; SetAttrsA(obj,x); SetAttrsA(obj,x) has *NOT* the wished
  184. result, because the non-constand datas of the LIST are only evaluated when
  185. x is assigned to to the LIST but not everytime this PTR to the LIST in x is
  186. used later!
  187.  
  188.  
  189.                   TAG_IGNORE,0,
  190.                   -------------
  191.  
  192.    Some of the macros in "MacroFiles/mui.ma" are ending with
  193. "[ TAG_IGNORE,0,". That seems to be superfluous but it is needed, because
  194. in E if you want to split a statement over several lines, you can't end a
  195. line with "[" but with a comma. (See program "OptiMUI" that cames with
  196. "Mac2E")
  197.  
  198.  
  199.  
  200.                AUTHORS (AND COPYRIGHTS)
  201.                ~~~~~~~~~~~~~~~~~~~~~~~~
  202.  
  203. Jan Hendrik Schulz (that's me): - muimaster.m
  204.  (schulzj@fmi.uni-passau.de)    - mui.m
  205.                 - mui.ma and mui.pma
  206.                 - translations of MUI-Demo and PopUp to E
  207.                 - installhook2.e and installhook2.m
  208.                 - this ReadMe-file
  209.  
  210. Stefan Stuntz: - MUI with mui.h and the original C versions of
  211.          MUI-Demo.e and PopUp.e
  212.  
  213. Lionel Vintenat: - Mac2E
  214.  
  215.  
  216. Wouter van Oortmerssen: - Amiga-E
  217.             - doMethod.e
  218.             - installhook.e
  219.  
  220.  
  221.  
  222.  
  223.                    FUTURE
  224.                    ~~~~~~
  225. - With future versions of MUI this files will be included. (If Stefan don't
  226.   forget it again like now with MUI 2.2)
  227.  
  228.  
  229.                 BUGS
  230.                 ~~~~
  231. - The PupUp-example hangs if you try to close it but there are still some
  232.   ASL-PopUps open. I don't know why! If anybody sees the bug, please send
  233.   me a mail.
  234.  
  235.