@DATABASE MUI-AmigaE.guide

@NODE MAIN "MUI-AmigaE.guide"
@NEXT INTRO

		      MUI DEVELOPER FILES FOR AMIGA E
		      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	@{" First words " LINK INTRO}  IMPORTANT! READ THIS!

	@{" Changes     " LINK CHANGES}  What's new ?
	@{" Files       " LINK FILES}  Description of the files.
	@{" Install     " LINK INSTALL}  Install the files.

	@{" Problems    " LINK PROBS}  Problems with MUI and AmigaE.
	@{" Future      " LINK FUTURE}  New MUI -> new files ?

	@{" Author      " LINK AUTHOR}  and copyright.
	@{" Disclaimer  " LINK DISCLAIMER}  No warranty!

@ENDNODE

@NODE INTRO "First words"
@PREV MAIN
@NEXT CHANGES
@TOC MAIN

				FIRST WORDS
				~~~~~~~~~~~

   I moved (from Passau to Hamburg)! Because of that, I lost my old e-mail
address (schulzj@fmi.uni-passau.de) and @{" my snail-mail address " LINK AUTHOR} has changed
too.

   I try to get a new e-mail address as soon as possible, but if you read
this, I didn't had this new e-mail address as this MUI version was ready for
distributing. So, this Amiga-E files are maybe not 100% uptodate. Have a
look at the file @{" Modules/libraries/diffs.readme " LINK F_DIFFS} to see, which struct's
and #defines of the original mui.h are not in the Amiga-E file. If necessay,
I will distribute a "muiXXEdev.lha" with the completed Amiga-E files ASAP.

   There are some other importand @{" changes " LINK CHANGES}, have a look at them!

@ENDNODE

@NODE CHANGES "Changes"
@PREV INTRO
@NEXT FILES
@TOC MAIN

				  CHANGES
				  ~~~~~~~

Changes from "mui23Edev.lha":
  - E versions <3.1a are no longer supported to keep the total size of this
    Amiga-E files reasonable. If you still use E v2.1b than update now or
    use "mui23Edev.lha".
  - The modules in "Modules/libraries" are partly generated automaticly by
    Stefan Stuntz. Because he has no e-compiler, and to keep the number of
    files small, only the source-code of this modules is provided. You have
    to compile them into an e-module by yourself. (see @{" Install " LINK INSTALL})

@ENDNODE

@NODE FILES "The Files"
@PREV CHANGES
@NEXT INSTALL
@TOC MAIN

				THE FILES
				~~~~~~~~~

	Modules/	    @{" muimaster.m  " LINK F_MUIMASTER}

	Modules/libraries/  @{" mui.e        " LINK F_MUIE }
			    @{" muip.e       " LINK F_MUIPE}
			    @{" diffs.readme " LINK F_DIFFS}

	Examples/	    @{" MUI-Demo.e   " LINK F_MUIDEMOE}

@ENDNODE

@NODE F_MUIMASTER "Files: Modules/muimaster.m"
@PREV F_MUIMASTER
@NEXT F_MUIE
@TOC FILES

			    "Modules/muimaster.m"
			    ~~~~~~~~~~~~~~~~~~~~~

   This file defines the functions of the muimaster.library. Copy it to
EMODULES: and to use it write in your source:

	MODULE 'muimaster'

ATTENTION: With "mui22Edev2.lha" I changed the names of the functions from
MuI_... to Mui_... (Lionel Vintenat (Mac2E) told me that Mui_... looks
nicer and I think he's right.) Maybe you have to change your old sources
to use this file.

@ENDNODE

@NODE F_MUIE "Files: Modules/libraries/mui.e"
@PREV F_MUIMASTER
@NEXT F_MUIPE
@TOC FILES

			 "Modules/libraries/mui.e"
			 ~~~~~~~~~~~~~~~~~~~~~~~~~

   This is the source-file of the e-module "mui.m". This module contains a
complete translation of the original C mui.h file with only one exception:
The muip_... OBJECTs are moved to the file @{" Modules/libraries/muip.e " LINK F_MUIPE}.

   The #defines (and CONSTs) are written exactly the same way as in the
mui.h file (with one exception: The macro String() is renamed to StringMUI()
to avoid conflicts with the E function String()). The identifiers of the
OBJECTs are all written totaly lowercase!!

   Compile this file with the e-compiler and copy the "mui.m" you get as
result to "EMODULES:libraries/mui.m". To use this module write in your
source:

	MODULE 'libraries/mui'

   Don't forget to add "OPT PREPROCESS" to your source, if you want to use
the macros!

   See also: @{" Modules/libraries/muip.e " LINK F_MUIPe}

@ENDNODE

@NODE F_MUIPE "Files: Modules/libraries/muip.e"
@PREV F_MUIE
@NEXT F_DIFFS
@TOC FILES

			 "Modules/libraries/muip.e"
			 ~~~~~~~~~~~~~~~~~~~~~~~~~~

   This is the source for the e-module "muip.m". It contains all the
MUIP_...-structs of the original C mui.h file as OBJECT's. I think, this
OBJECT's are not very usefull in E, that's why I didn't include them in the
first releases. But to have a complete AmigaE-MUI-Interface...

   Compile this file with the e-compiler and copy the "muip.m" you get as
result to "EMODULES:libraries/muip.m". To use this module write in your
source:

	MODULE 'libraries/muip.m'

@ENDNODE

@NODE F_DIFFS "Files: Modules/libraries/diffs.readme"
@PREV F_MUIPE
@NEXT F_MUIDEMOE
@TOC FILES

			"Modules/libraries/diffs.readme"
			~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   This file contains a list of all struct's and #defines of the mui.h
file, which are not translated into E. (See @{" First words " LINK INTRO} for the reason!)

   If you need one of them, look at the mui.h file, or wait for an update
of this AmigaE-files (available as "dev/e/muiXXEdev.lha" on aminet).

   I hope this list is not too long! :-|

@ENDNODE

@NODE F_MUIDEMOE "Files: Examples/MUI-Demo.e"
@PREV F_DIFFS
@NEXT F_MUIDEMOE
@TOC FILES

			    "Examples/MUI-Demo.e"
			    ~~~~~~~~~~~~~~~~~~~~~

   This is a translation of the C demo-source "MUI-Demo.c" that came with
MUI v2.1. Use it to see, how to write MUI-programms in E and where are the
differences between C and E.

   See also: @{" Problems " LINK PROBS}

@ENDNODE

@NODE INSTALL "Install"
@PREV FILES
@NEXT PROBS
@TOC MAIN

				  INSTALL
				  ~~~~~~~

    To install the AmigaE-MUI-files do the following:

	1. Open a shell
	2. CD into the 'Developer/Amiga-E/Modules' directory
	3. execute 'COPY muimaster.m EMODULES:'
	4. CD into the 'libraries' subdirectory
	5. call the e-compiler with 'EC mui.e'
	6. execute 'COPY mui.m EMODULES:libraries/mui.m'
	7. call the e-compiler with 'EC muip.e'
	8. execute 'COPY muip.m EMODULES:libraries/muip.m'

@ENDNODE

@NODE PROBS "Problems with MUI and E"
@PREV INSTALL
@NEXT FUTURE
@TOC MAIN

			   PROBLEMS WITH MUI AND E
			   ~~~~~~~~~~~~~~~~~~~~~~~

		@{" MUI_TRUE    " LINK P_TRUE}  Why a CONST MUI_TRUE?
		@{" SetAttrsA() " LINK P_SETATTRSA}  Problems with set()
		@{" TAG_IGNORE  " LINK P_TAGIGNORE}  Why "TAG_IGNORE,0," in some macros?

@ENDNODE

@NODE P_TRUE "Problems: TRUE=1 or TRUE=-1"
@PREV P_TRUE
@NEXT P_SETATTRSA
@TOC PROBS

			      TRUE=1 or TRUE=-1
			      ~~~~~~~~~~~~~~~~~

   In C TRUE has the value 1 but in E TRUE has the value -1. That can cause
problems, therefore a CONST "MUI_TRUE" with value 1 is defined in
@{" Modules/libraries/mui.e " LINK F_MUIE}. Use this one instead of TRUE whenever you want
to give TRUE to MUI. See "Examples/MUI_Demo.e".

@ENDNODE

@NODE P_SETATTRSA "Problems: Problem with SetAttrsA()"
@PREV P_TRUE
@NEXT P_TAGIGNORE
@TOC PROBS

			  Problem with SetAttrsA()
			  ~~~~~~~~~~~~~~~~~~~~~~~~

   Whenever you try to set an attribut to the value it allready has, MUI
overwrites this attribut in the taglist with TAG_IGNORE to make shure that
notify-class don't react on it. This is nessesary to prevent endless-
notification-loops. As long as you are a C programmer and use SetAttr()
that is no problem, because MUI then changes only a *copy* of the original
datas of the SetAttrs()-call. But if you use SetAttrsA(), as we must do
because SetAttrs() is a function of amiga.lib, it is a problem! You only
give a PTR to the original-datas with SetAttrsA() and now MUI changes this
*original* datas. If you then uses this datas again at the next execution
of the same SetAttrsA()-call, the datas are still changed and nothing
(TAG_IGNORE) will happen :-(

   One possible way to avoid this problem is, to make the attribut a non-
constant data. Instead of

   SetAttrsA(obj, [ MUIA_..., value, ..., TAG_DONE])

write

   SetAttrsA(obj, [Eval(`(MUIA_...)), value, ..., TAG_DONE])
		   ~~~~~~~        ~~
Now everytime this SetAttrsA()-call is executed, the attribute is again
"evaluated" and stored in the list.

   BUT: x:=[Eval(`(MUIA_...)),...]; SetAttrsA(obj,x); SetAttrsA(obj,x) has
*NOT* the wished result, because the non-constand datas of the LIST are only
evaluated when x is assigned to to the LIST but not everytime this PTR to
the LIST in x is used later!

   To avoid the SetAttrsA()-problem the macros set() (and nnset()) in the
file @{" Modules/libraries/mui.e " LINK F_MUIE} are defined like this:

  #define set(obj,attr,value) SetAttrsA(obj,[Eval(`(attr)),value,TAG_DONE])

   The global variable "setAttrsA" that was needed with the set() and
nnset() of former releases is now obsolete.

@ENDNODE

@NODE P_TAGIGNORE "Problems: TAG_IGNORE,0"
@PREV P_SETATTRSA
@NEXT P_TAGIGNORE
@TOC PROBS

				TAG_IGNORE,0
				~~~~~~~~~~~~

   Some of the macros in @{" Modules/libraries/mui.e " LINK F_MUIE} are ending with
"[TAG_IGNORE,0,". That seems to be superfluous but it is needed, because in
AmigaE v2.1b if you want to split a statement over several lines, you can't
end a line with "[" but with a comma. And with AmigaE v3.1 it's needed to
allow the same use of the macros.

@ENDNODE

@NODE AUTHOR "Author"
@PREV FUTURE
@NEXT DISCLAIMER
@TOC MAIN

				   AUTHOR
				   ~~~~~~

   IMPORTANT NOTE: I moved and my address changed! (see @{" First words " LINK INTRO})

	Snail mail (new):  Jan Hendrik Schulz
			   Lewetzauweg 16
			   22455 Hamburg
			   Germany

	e-mail:		   no e-mail address available now!

@ENDNODE

@NODE FUTURE "Future"
@PREV PROBS
@NEXT AUTHOR
@TOC MAIN

				   FUTURE
				   ~~~~~~

   I try to get a new e-mail address ASAP, and I hope the next MUI version
will come with an uptodate AmigaE-Interface...

   If you have some ideas to make things better, please write @{" me " LINK AUTHOR}.

@ENDNODE

@NODE DISCLAIMER "Disclaimer"
@PREV COPYRIGHTS
@NEXT DISCLAIMER
@TOC MAIN

				 DISCLAIMER
				 ~~~~~~~~~~

   This files are provided "AS IS" without warrenty of any kind, expressed
or implied! I'm NOT liable to you for damages or problems, including any
general, special, incidental or consequential damages or problems arising
out of the use or inhability to use of the files. Including but not limited
to loss of data or data being rendered inaccurate or losses sustained by you
or third parties or a failure of a program build with this files.

   (I hope you know what I want to say! My english is not good enough to
write such legal stuff!)

@ENDNODE