@database EasylifeMUI.guide @author "Paul Hickman" @$VER: EasylifeMUI.guide 1.10 (30.03.95) @width 77 @index Easylife.guide/CommandIndex @node main "Easylife Magic User Interface Programming" @toc Easylife.guide/main @prev main @next MUIintro @{u}@{b}Easylife Extension V1.10 - By Paul Hickman@{uu} E-Mail: ph@doc.ic.ac.uk@{ub} @{u}Magic User Interface programming@{uu} @{"MUI Introduction " link MUIintro} @{"General Notes " link MUInotes} @{"Taglist Parsing " link TagContents} @{"MUI Commands & Functions " link MuiContents} @{"Support Procedures " link MUIProcs} @{u}MUI Support Programs@{uu} @{"Variable Checker " link VarChecker.guide/main} @{"Program Optimser " link Optimse.guide/main} @{"Equates To Tags " link EquatesToTags.guide/main} @{"Taglist Editor " link TagEditor.guide/main} @endnode @node MUIintro "MUI / Introduction" @toc main @prev MUIintro @next MUInotes @{b}@{u}MUI Introduction@{ub}@{uu} Magic User Interface is a set of standard library libraries that allow you to easily build user interfaces using enhanced versions of the standard intuition gadgets. MUI interfaces as fully font sensitive, will resize themselves to fit in the window and offer the user an incredible amount of control over the layout and appearance of the interface. All this, and it is easy to program too! It is possible to build a complete interface using only 3 of easylife functions provided here - the rest are there for convience and to make you programs shorter. @endnode @node MUInotes "MUI / Generate Notes" @toc main @prev MUIintro @next TagContents @{u}@{b}MUI General Notes@{ub}@{uu} @{b}Before You Start@{ub} Before using MUI from AMOS, or reading the rest of this document, you should do the following: - Install the MUI users archive (mui22usr.lha) distribution on your system, as per normal. - Unpack the MUI developers archive (mui22dev.lha) and copy the developers guide into a directory assigned to HELP: (You can use Assign ADD ). - Convert the MUI autodocs to amigaguide format, using the AdToHt utility supplied with Amigaguide (It is in the amigaguide program archive on aminet). To do this, make the directory where you want to put the guides, then cd to the parent directory of the mui Autodocs. If you have the C system include files (.h) type: AdToHt AUTODOCS=AutoDocs INCLUDES= HYPERTEXT= Else ensure there are not filenames ending in .h / .i in ram: and type: AdToHt AUTODOCS=AutoDocs INCLUDES=Ram: HYPERTEXT= - Assign HELP: To the directory containing the converted amigaguide files, using assign ADD in your user startup. This will allow the hypertext links in this document to MUI tags & library functions to work. - Copy the MUI.i file from the assembler section of the developers guide, and the C examples, then you can delete the rest of that archive (Unlessyou want to use MUI from another language also). The MUI.i file can be a useful reference, and is requied to write Hook functions. - Read the MUI user guide & developers guide (Except the custom class section) before looking at this manual. You may also find it benifical to look at the autodocs entries for the following before going any further, as they are among the principle MUI tags. If you have converted the autodocs to amigagudie successfuly, these links will work: @{u}Applictaion.guide:@{uu} @{"Application.mui " link HELP:MUI_Application.guide/Application.mui} @{"MUIM_Application_Input " link HELP:MUI_Application.guide/MUIM_Application_Input} @{"MUIA_Application_ReturnID " link HELP:MUI_Application.guide/MUIA_Application_ReturnID} @{"MUIA_Application_Base " link HELP:MUI_Application.guide/MUIA_Application_Base} @{"MUIA_Application_Title " link HELP:MUI_Application.guide/MUIA_Application_Title} @{"MUIA_Application_Window " link HELP:MUI_Application.guide/MUIA_Application_Window} @{u}Notify.guide:@{uu} @{"Notify.mui " link HELP:MUI_Notify.guide/Notify.mui} @{"MUIM_Notify " link HELP:MUI_Notify.guide/MUIM_Notify} @{"MUIM_Set " link HELP:MUI_Notify.guide/MUIM_Set} @{u}Group.guide:@{uu} @{"Group.mui " link HELP:MUI_Group.guide/Group.mui} @{"MUIA_Group_Child " link HELP:MUI_Group.guide/MUIA_Group_Child} @{"MUIA_Group_Horiz " link HELP:MUI_Group.guide/MUIA_Grouo_Horiz} @{u}Text.guide@{uu} @{"Text.mui " link HELP:MUI_Text.guide/Text.mui} @{"MUIA_Text_Contents " link HELP:MUI_Text.guide/MUIA_Text_Contents} @{u}Area.guide@{uu} @{"Area.mui " link HELP:MUI_Area.guide/Area.mui} @{"MUIA_Background " link HELP:MUI_Area.guide/MUIA_Background} @{"MUIA_Frame " link HELP:MUI_Area.guide/MUIA_Frame} @{"MUIA_Weight " link HELP:MUI_Area.guide/MUIA_Weight} @{u}Window.guide:@{uu} @{"Window.mui " link HELP:MUI_Window.guide/Window.mui} @{"MUIA_Window_RootObject " link HELP:MUI_Window.guide/MUIA_Window_RootObject} @{"MUIA_Window_ID " link HELP:MUI_Window.guide/MUIA_Window_ID} @{"MUIA_Window_Open " link HELP:MUI_Window.guide/MUIA_Window_Open} @{"MUIA_Window_Title " link HELp:MUI_Window.guide/MUIA_Window_Title} @{b}Standard Taglists@{ub} MUI depends heavily on taglists to supply arguments to its functions. There are only 5 major MUI library calls, but they can take hundreds of different arguments! In the formal commodore sense, a taglist is an array of pairs of longwords. Each pair is called a tagitem. The first longword of tagitem is the tag, the value of which defines which parameter is being defined by this tagitem. The second is the data value, which is the value of the parameter. E.g. Were the AMOS Screen Open command to take a taglist, it might be something like: dc.l $80000001,0 dc.l $80000002,320 dc.l $80000003,200 dc.l $80000004,16 dc.l $80000005,0 dc.l 0 NOTE: The taglist ends in a single 0 to mark the end of the taglist. This notation 'dc.l' is standard assembler notation. It means each argument takes 1 longword of memory. THe values $80000001 etc. represent the paramenters Screen No, Screen Width etc. With Easylife this taglist would be created in a string with: _TAGLIST$=Ellong$($80000001)+Ellong$(0) etc. As you can see is not very readable. It is easier to give names to the tags and to the data value where they are special values, so the taglist above becomes: dc.l Screen_Number,0 dc.l Screen_Width,320 dc.l Screen_Height,200 dc.l Screen_Colours,16 dc.l Screen_Mode,Lowres dc.l TAG_DONE NOTE: In a taglist, the tags to not have to be in any particular order. However, while this is alright for assembler, C and other compiled languages as the symbolic names are replaced by the hex values by the compiler, AMOS has to decode these names at runtime. Easylife not only provides functions to create taglists from these symbolic names, it also provides an optimiser program which will go through your program, and replace all of the name strings with actual hex values. @{b}MUI Taglists@{ub} While some MUI commands/functions take standard taglists as arguments, some take taglists of a special format, where there is a fixed number of items, which must occur in a certain order, and not neccessarily in pairs. The format of such taglists is given with the commands that use them. The first section of this manual deals with the functions used to create such taglists. The second with the commands & functions with take the taglists as parameters to communicate with MUI. @endnode @node TagContents "MUI / Taglist Functions - Contents" @toc main @prev MUIIntro @next Tag @{b}@{u}MUI Taglist Functions@{uu}@{ub} @{"Converting A Tag To A Value" link C_Tag} @{"Integers in Taglists " link C_TagInt} @{"Strings in Taglists " link C_TagStr} @{"String Storage Mode " link C_TagKeep} @{"Child Object Tags " link C_TagAttach} @{"Taglist Banks " link C_TagList} @{"Memory Allocation Blocks " link C_TagBlockSize} @endnode @node C_Tag "MUI / Converting A Tag To A Value" @toc TagContents @prev Tag @next TagInt @aka Tag$ @{b}Command Syntax@{ub} =Tag( @{i}TAG$ @{ui}) =Tag$( @{i}TAG$ @{ui}) =Tag$( @{i}TAG1$ , TAG2$ @{ui}) =Tag$( @{i}TAG1$ , TAG2$ , TAG3$ @{ui}) @{b}Description@{ub} To use any function which takes a Tag as an argument, Bank 13 of your program must be a "Tag" bank, containing the symbolic string representation of the tags, with their numeric equivilents. Using a tag is similar to an AMOSPro equate, but more powerful, as the tag string is converted at runtime, not at test time, so it may be a variable, or a string expression. The first format is almost identical to the AMOSPro Equ function. It takes a tag string, and returns the integer it represents, only using the tagbank, not the equates system. The next three take up to 3 tag strings, and return the integers they represent as longwords in a string. E.g. A$=Tag$("TAG_NO_1","TAG_NO_2") Is equivilent to: A$=Ellong$(Tag("TAG_NO_1"))+Ellong$(Tag("TAG_NO_2")) @{b}Errors@{ub} @{u}Unmatched Tag@{uu} The string you have specifed as one of the tag arguments does not exist in the tagbank (Or the tagbank is corrupt). @{u}Bank Not Reserved@{uu} There is no bank 13, or it is not a tagbank. @{b}See Also@{ub} @{"= Tag$ " link C_TagInt} (Integer Form) @{"= Tag Str$ " link C_TagStr} @{"= Tag Attach$ " link C_TagAttach} @{"Equates_To_Tags.AMOS" linke Equates_To_Tags.guide/main} @endnode @node C_TagInt "MUI / Integers in Taglists" @toc TagContents @prev Tag @next TagStr @{b}Command Syntax@{ub} =Tag$( @{i}TAG$ @{ui}To @{i}VALUE @{ui}) =Tag$( @{i}TAG1$ , TAG2$ @{ui}To @{ui}VALUE @{ui}) @{b}Description@{ub} To use any function which takes a Tag as an argument, Bank 13 of your program must be a "Tag" bank, containing the symbolic string representation of the tags, with their numeric equivilents. The tag arguments are converted into their integer equivilents, as per usualy, but the resulting string returned as the longword @{i}VALUE @{ui} appended to the end - e.g.: If TAG_NO_1 has the value $80001000 and TAG_NO_2 the value $30, the call: A$=Tag$("TAG_NO_1","TAG_NO_2" To $11223344) Will return a string containing the bytes: $80,$00,$10,$00,$00,$00,$00,$30,$11,$22,$33,$44 @{b}Notes@{ub} - Do not use the Tag functions with tags that expect a string a the tag argument e.g. The tag "MUIA_String_Contents" which sets the string to go in a string gadget should be followed by a longword pointer to a string. Do not use: A$=Tag$("MUIA_String_Contents" To Varptr(S$)) As AMOS relocates all its strings during garbage collection. Use the @{"Tag Str$" link C_TagStr} function instead. - Also, do not use the Tag functions with tags that expect a pointer to an object as the tag argument, such as "MUIA_Group_Child" as easylife needs to know when an object is being made a child of another. Instead use @{"Tag Attach$" link C_TagAttach}. @{b}Errors@{ub} @{u}Unmatched Tag@{uu} The string you have specifed as one of the tag arguments does not exist in the tagbank (Or the tagbank is corrupt). @{u}Bank Not Reserved@{uu} There is no bank 13, or it is not a tagbank. @{b}See Also@{ub} @{"= Tag$ " link C_Tag} (Tags Only Form) @{"= Tag Str$ " link C_TagStr} @{"= Tag Attach$ " link C_TagAttach} @{"Equates_To_Tags.AMOS" linke Equates_To_Tags.guide/main} @endnode @node C_TagStr "MUI / Using Strings In Taglists" @toc TagContents @prev TagInt @next TagKeep @aka TagStr$ @{b}Command Syntax@{ub} =Tag Str( @{i}STRING$ @{ui}) =Tag Str( @{i}STRING$ @{ui}To @{i}OBJECT @{ui}) =Tag Str$( @{i}STRING$ @{ui}) =Tag Str$( @{i}STRING$ @{ui}To @{i}OBJECT @{ui}) =Tag Str$( @{i}TAG$ , STRING$ @{ui}) =Tag Str$( @{i}TAG$ , STRING$ @{ui} To @{i}OBJECT @{ui}) @{b}Description@{ub} The Tag Str$ function stores a string for use in a taglist. Where an @{i}OBJECT @{ui}is specified, the string is stored with that object, so when the object is disposed of, the string is also disposed of. If no @{i}OBJECT @{ui}is specified, the string is stored in a buffer, which is attached to the next object that is created with Mui New, as if it had be stored with the new object after the object was created. The first 2 forms return the address of the stored string. This address will not change, even if no @{i}OBJECT @{ui}was specified. The next 2 forms return the longword address of the stored string in a 4 character string. The last 2 forms return a 8 character string, the first 4 characters are the longword value of the TAG$ and the last 4 characters are that address of the string. This is the most commonly used form of Tag Str$ - e.g. To change the string of an existing string gadget: A$=Tag Str$("MUIA_String_Contents","Fred" To STR_OBJ) @{b}Notes@{ub} - Chr$(0) is automatically appended to the string when it is stored, because MUI expects NULL terminated strings. - Easylife handles the memory allocation & deallocation of stored strings. - Since the address must not change, there is no garbage collection of stored strings. - The storing is subject to the setting of @{"Tag Keep" link C_TagKeep} at the time of the execution of the Tag Str$ instruction. @{b}Errors@{ub} @{u}Unmatched Tag@{uu} The TAG$ string could not be found in the tagbank, or the tagbank is corrupt. @{u}Bank Not Reserved@{uu} Bank 13 does not exist, or is not a tagbank. I.E. The bank name is not "Tags ". @{u}Illegal MUI Object Address@{uu} The @{i}OBJECT @{ui}you have specified does not exist. @{b}See Also@{ub} @{"= Tag " link C_Tag} @{"Tag Keep " link C_TagKeep} @{"Mui Begin" link C_MuiNew} @endnode @node C_TagKeep "MUI / String Storage Mode" @toc TagContents @prev TagStr @next TagAttach @{b}Command Syntax@{ub} Tag Keep True Tag Keep False @{b}Description@{ub} When you store a string using @{"Tag Str$" link C_TagStr}, there are two possible ways to store the string. 1) Tag Keep @{i}True @{ui} The string is stored with the object. If the Tag Str$ function does not specify which object to store it with, it is stored with the next object created with @{"Mui New" link C_MuiNew}. The string is only disposed of when: a) The object is disposed of. b) A string attribute of the object, that was previous set to the string is changed. 2) Tag Keep @{i}False @{ui} The string is not stored with the object at all, but it is stored in a temporary buffer, which is erased the next time any command, or function which accepts a taglist as an argument is used (E.g. Mui New, =Mui Fn Mui Do). Use this setting for temporary strings for the next taglist, such as MUIA_Text_Contents strings which MUI always makes a copy of. @{b}Notes@{ub} - When using Tag Keep False, the strings are disposed of AFTER the Command / Funcion which uses the taglist has be executed. @{b}Errors@{ub} None. @{b}See Also@{ub} @{"Mui Begin " link C_MuiNew} @{"= Tag Str$" link C_TagStr} @{"= Mui New " link C_MuiNew} @endnode @node C_TagAttach "MUI / Attaching Child Objects To Parents" @toc TagContents @prev TagKeep @next TagList @{b}Command Syntax@{ub} =Tag Attach$( @{i}CHILD_OBJECT , TAG$ @{ui}) =Tag Attach$( @{i}CHILD_OBJECT @{ui}To @{i}TAG @{ui}) @{b}Description@{ub} Tag Attach is used to make an existing object the child of an object that is yet to be created. If the parent object already exists, use @{"Mui Add" link C_MuiAdd} instead. A$=Tag Attach(WIN_OBJ,"MUIA_Application_Window") Is exactly the same as: A$=Tag$("MUIA_Application_Window" To WIN_OBJ) Except that Easylife now knows that WIN_OBJ will be a child object of the next object created. Therefore when the parent object is disposed of, EasyLife will know that MUI has also disposed of the child, so the childs stored strings can also be disposed of. The string returned contains 2 longwords - the tag value followed by the address of the child object - ready to become part of the parents taglist. The second format allows you to specify a numeric value for the tag, instead of the tag string. @{b}Notes@{ub} - Always use Tag Attach to connect children to parents. To not use Tag$, or Easylife may become confused when it comes to memory deallocation.@{b} Not doing this may cause a system crash@{{ub}. - The parent object is the object in whose taglist the string returnd by this function is used in with the Mui New function. Make sure that the taglist returned is used in the creation of an object. @{b}Errors@{ub} @{u}Unmatched Tag@{uu} The TAG$ string could not be found in the tagbank, or the tagbank is corrupt. @{u}Bank Not Reserved@{uu} Bank 13 does not exist, or is not a tagbank. I.E. The bank name is not "Tags ". @{u}Illegal MUI Object Address@{uu} The @{i}CHILD_OBJECT @{ui}you have specified does not exist. @{u}Illegal Function Call@{uu} The @{i}CHILD_OBJECT @{ui}is already attached to another object. Each object can only appear once in the application tree. @{b}See Also@{ub} @{"= Tag " link C_Tag} @{"Mui Add " link C_MuiAdd} @{"Mui New " link C_MuiNew} @endnode @node C_Taglist "MUI / Using Taglist Banks" @toc TagContents @prev TagAttach @next TagBlockSize @{b}Command Syntax@{ub} =Taglist( @{i}NAME$ @{ui}) =Taglist( @{i}NAME$ , PARAM1 @{ui}) =Taglist( @{i}NAME$ , PARAM1 , PARAM2 @{ui}) Etc. This function may have up to 8 parameters. @{b}Description@{ub} The Taglist Editor program allows you to interactively create taglists and store them in an AMOS bank. This function extracts an individual taglist from the bank and returns a copy of the list as a string, with the parameters instantiated. @{b}Notes@{ub} - The number of extra parameters depends on how many parameters are required by the specified taglist. @{b}Errors@{ub} @{u}Unmatched Tag@{uu} The name of the taglist is a tag. This error occurs if it is not found in the taglist bank. @{u}Bank Not Reserved@{uu} This error can occur for 2 reasons: - The taglist bank (14) does not exist. - The taglist specified uses a bank pointer as a special tag, and the bank number it specifies does not exist. @{u}Illegal Function Call@{uu} This error will occur if you specify the wrong number of parameters for this specified taglist. @{b}See Also@{ub} @{"Taglist Editor.AMOS" link TaglistEditor.guide/main} @endnode @node C_TagBlockSize "MUI / Memory Allocation Block Size" @toc TagContents @prev TagList @next MuiContents @{b}Command Syntax@{ub} Tag Block Size @{i}SIZE @{ui} @{b}Description@{ub} When Easylife has to allocate memory for a stored string, instead of allocating each string seperately & fragmenting the system memory, Easylife simply allocates a large block of memory, then allocates strings from that. When one block is full, it allocates another block. This has the added advantage that at the end of a program, Easylife can ensure everything is deallocated just by freeing the blocks. This command sets the size of the blocks, in bytes. @{b}Notes@{ub} - The default value is 8K. - You cannot change the block size while blocks are allocated, so this must be used before any @{"Tag Str$" link C_TagStr} functions. @{b}Errors@{ub} @{u}Illegal Funcion Call@{uu} You have specified a block size smaller than 4K, or larger than 256K. This error also occurs if any blocks are allocated while you try to change the size. @endnode @node MuiContents "MUI / MUI Commands & Functions - Contents" @toc Main @prev MuiContents @next MuiNew @{b}@{u}MUI Commands & Functions@{uu}@{ub} @{u}Section 1: Object Creation / Destruction@{uu} @{"Creating New Objects " link C_MuiNew} @{"The Applicaion Object " link C_MuiApp} @{"Built-in Objects " link C_MuiMake} @{"Disposing Of Objects " link C_MuiDispose} @{u}Section 2: Communicating With Objects@{uu} @{"Getting An Attribute's Value " link C_MuiGet} @{"Setting An Attribute's Value " link C_MuiSet} @{"Do Method " link C_MuiDo} @{"Notification " link C_MuiNotify} @{u}Section 3: Misc Features@{uu} @{"Getting User Input " link C_MuiInput} @{"Simple Requesters " link C_MuiRequest} @{"Flushing Strings " link C_MuiFlush} @{"Dynamic Addition Of Children " link C_MuiAdd} @{"Dynamic Removal Of Children " link C_MuiRemove} @{"Hook Functions " link C_MuiHook} @endnode @node C_MuiNew "MUI / Creating Objects" @aka C_MuiBegin @toc MuiContents @prev MuiContents @next MuiApp @{b}Command Syntax@{ub} Mui Begin True Mui Begin False =Mui New( @{i}CLASS$ @{ui}) =Mui New( @{i}CLASS$ , TAGLIST$ @{ui}) @{b}Description@{ub} The Mui New function creates a new MUI object, and binds any strings that have been stored since the last call to Mui Begin to the new object. This means that those strings are automatically disposed of when the object is disposed of. @{i}CLASS$ @{ui}is the name of the MUI class of the object you wish to create an instance of. If specified, @{i}TAGLIST$ @{ui}is a list of create-time attribute tagitems, terminated with "TAG_DONE". The address of the newly created object is returned, or 0 if the object could not be created (Normally due to an error in the taglist). The call to Mui Begin marks the begining of the definition of the new MUI object. The True / False parameter specifies the initial setting of @{"Tag Keep" link C_TagKeep} for the new object. The current setting from the previous object is stored on a stack, and is restored when the new object is created, with Mui New, so you may carry on supplying tags to the old object - E.g. 'Start an object, with permanent strings ' Mui Begin True S$=Tag Str$("MUIA_String_Contents","Fred") 'Start & Create a second object with temporary strings ' Mui Begin False L$=Tag$("MUIA_Frame","MUIA_Frame_InputList") LIST_OBJ=Mui New("List.mui",L$+Tag$("TAG_DONE")) 'Now LIST_OBJ is created, the strings have been set back to 'permanent, and we can carry on creating STR_OBJ S$=S$+Tag$("MUIA_String_MaxLen" To 10) STR_OBJ=Mui New("String.mui",S$+Tag$("TAG_DONE")) Although this example is somewhat artifical, it does allow procedures to create objects to be written with the knowledge that they won't interfere with any object that was midway through creation when they were called. @{b}Notes@{ub} - You must have called Mui Begin before calling Mui New to define where the strings for the new object start, even if the object has no strings. - Mui New restores the previous objects Tag Keep setting, if there was a previous object being defined. - Do not use Mui New to create application objects. Use the function @{"Mui Application" link C_MuiApp} instead. - You do not need an Mui Begin instuction to create objects with @{"Mui Make" link C_MuiMake}. - Calls to Mui Begin can be nested arbitarily deep. @{b}Errors@{ub} @{u}Missing Mui Begin Instruction@{uu} Before each call to Mui New, there must be an Mui Begin command. This error occurs if no command could be found for this funcion. However, that does not neccessarily mean that you forgot it with this call e.g. Mui Begin False _PROC 1 OBJ=Mui New('String.mui') End Procedure _PROC_1 Mui Begin False _PROC_2 End Proc[Mui New('List.mui')] Procedure _PROC_2 End Proc[Mui New('Text.mui')] In this example, _PROC_2 has the Mui Begin missing, but the error is returned when the 'String.mui' object is created, as _PROC_2 finds _PROC_1's Mui Begin, so _PROC_1 then finds the main program's Mui Begin, and therefore the Main program cannot find an Mui tag start call. @{b}See Also@{ub} @{"Mui Flush " link C_MuiFlush} @{"Mui Dispose " link C_MuiDispose} @{"Mui Make " link C_MuiMake} @{"Mui Application " link C_MuiApp} @endnode @node C_MuiApp "MUI / The Application Object" @aka C_MuiApplication @toc MuiContents @prev MuiNew @next MuiMake @{b}Command Syntax@{ub} =Mui Application @{i}TAGLIST$@{ui} =Mui App @{b}Description@{ub} Each MUI appilication program you write must contain an application object, and only one application object. This is used as the root of the object tree, and to communicate with Arexx / Commodities & Your AMOS Program. The Mui Application function used instead of Mui New to create the application object. All the rules about Mui New apply to Mui Application, including the use of @{"Mui Begin" link C_MuiNew}, the attaching of strings stored with @{"Tag Str$" link C_TagStr} without a destination object, etc. The only differences between this and @{"Mui New" link C_MuiNew} are: a) You don't need to specify the class - it is always "Application.mui' b) Easylife records that this is the application object. Both functions return the address of the application object. Mui App will return 0 if no application object has been created. @{b}Notes@{ub} - Any comments made about @{"Mui New" link C_MuiNew} in this manual also apply to this function. - Always use this function to create the application object, so that Easylife knows which is your application object. - Use Mui App instead of assigning a variable to your appication object. Use the return value of Mui Application to test if the application was created correctly - E.g.: If Mui Applicaton(_TAGLIST$)=0 Print "Failed To Create Application." End End If It is not necessary to perform this sort of check on any other object, as if they fail to create, they will return 0. When you make them the child of another object, that object will also fail to create, as one of it's children is null (0). Since everything is a child, or grandchild etc. of the application, if just one of the other objects failed, the application will fail. The exception to this rule is objects with are not part of the appication at creation time, but will be added with @{"Mui Add" link C_MuiAdd} @{b}Errors@{ub} @{u}Illegal Function Call@{uu} You may only create one application object at a time. One must be disposed of before another is created. @{u}Missing Mui Begin Instruction@{uu} See @{"Mui New" link C_MuiNew} errors for details. @endnode @node MuiMake "MUI / Built-in Objects" @toc MuiContents @prev MuiApp @next MuiMakeButton The MUI master library has a number of objects built-in, to save time & memory with repeated taglists. Easylife provides functions to create some of the more useful builtin objects: @{" Mui Make Button " link C_MuiMakeButton} @{" Mui Make PopButton " link C_MuiMakePopButton} @endnode @node C_MuiMakeButton "MUI / Built-in Objects / Button Object" @toc MuiMake @prev MuiMake @next MuiMakePopButton @{b}Command Syntax@{ub} =Mui Make Button( @{i}LABEL @{ui}) @{b}Description@{ub} This function creates a normal button object. @{i}LABEL$ @{ui}is the text to appear in the button. You do not need to call @{"Mui Begin" link C_MuiNew} before this function, and stored strings are not assigned to this object unlike if it were created with @{"Mui New" link C_MuiNew}. @{b}Errors@{ub} A return value of 0 signifies the object couldn't be created. @endnode @node C_MuiMakePopButton "MUI / Built-in Objects / PopButton Object" @toc MuiMake @prev MuiMakeButton @next MuiDispose @{b}Command Syntax@{ub} =Mui Make Popbutton( @{i}IMAGE @{ui}) @{b}Description@{ub} This function creates a pop button object. A pop button is the little graphic button you sometimes see on the right of a string gadget, which pops up a requester of some kind when you pressed. @{i}IMAGE @{ui}is the standard MUI Image number to use for the button. (Use an MUII.... Tag). You do not need to call @{"Mui Begin" link C_MuiNew} before this function, and stored strings are not assigned to this object unlike if it was created with @{"Mui New" link C_MuiNew}. @{b}Errors@{ub} A return value of 0 signifies the object couldn't be created. @endnode @node C_MuiDispose "MUI / Disposing Of Objects" @toc MuiContents @prev MuiMakePopButton @next MuiGet @{b}Command Syntax@{ub} Mui Dispose @{i}OBJECT @{ui} @{b}Description@{ub} This function removes an MUI object from memory, and deallocates any strings easylife has attached to it. In addition, all of its children are recursively deallocated, allong with their strings. @{b}Notes@{ub} - All Mui Objects which are not children of other objects are automatically disposed of by the easylife @{"Default" link Easylife.guide/CommandEffects} routine. This usualy means the application object, and the any objects you have created for dynamic addition/remove, which are currently removed from the application tree. - You can only dispose of an @{i}OBJECT @{ui}if it is NOT the child of another object. MUI enforces this restriction, but EasyLife will check this is true for you ('Cos it's so nice :-) @{b}Errors@{ub} @{u}Illegal MUI Object Address@{uu} The @{i}OBJECT @{ui}you are trying to dispose of does not exist. @{u}Illegal Function Call@{uu} The @{i}OBJECT @{ui}you are trying to dispose of is the child of another object. @endnode @node C_MuiGet "MUI / Reading the value of an attribute of an object" @toc MuiContents @prev MuiDispose @next MuiSet @{b}Command Syntax@{ub} =Mui Get( @{i}OBJECT , TAG$ @{ui}) =Mui Get( @{i}OBJECT @{ui}To @{i}TAG @{ui}) =Mui Get$( @{i}OBJECT , TAG$ @{ui}) =Mui Get$( @{i}OBJECT@{ui} To @{i}TAG @{ui}) @{b}Description@{ub} The Mui Get function takes an @{i}OBJECT, @{ui}and an MUIA tag (Either as a string, or numeric value) as parameters, and returns the value of the attribute as an integer. If the attribute is a pointer to a string, use Mui Get$ to return a @{b}copy@{ub} of the string. E.g. A$=Mui Get$(STR_OBJ,"MUIA_String_Contents") @{b}Notes@{ub} - If the string attribute is NULL, Mui Get$ returns an empty string. - The attribute you attempt to get must be readable. In the MUI autodocs, there is a set of 3 flags in square brackets after the tag name. The full set is [ISG]. To use Mui Get, or Mui Get$, the 'G' flag must be present. @{b}Errors@{ub} @{u}Illegal MUI Object Address@{uu} The @{i}OBJECT @{ui}you have specified does not exist. Easylife does not check the value of the tag you pass, so if you pass an illegal value as a tab, anything could happen. @endnode @node C_MuiSet "MUI / Setting An Attribute's Value" @aka C_MuiSetStr @toc MuiContents @prev MuiGet @next MuiDo @{b}Command Syntax@{ub} Mui Set @{i}OBJECT , TAG$ , VALUE @{ui} Mui Set @{i}OBJECT To TAG , VALUE @{ui} Mui Set Str @{i}OBJECT , TAG$ , STRING$ @{ui} Mui Set Str @{i}OBJECT To TAG , STRING$ @{ui} @{b}Description@{ub} Mui Set changes an attribute of an object. The @{i}TAG$ @{ui} should normally be an MUIA tag. You may use the Tag function for MUIV values. The second form takes a numerical value for the tag, instead of a string. Mui Set Str changes an attribute of an object to a string. @{i}STRING$ @{ui}is permanently stored with the object, if the current @{"Tag Keep" link C_TagKeep} setting is true, otherwise it is disposed of after the attribute has been set. The string is stored in the same way as @{"Tag Str$" link C_TagStr}, but if the old setting of the tag that is being changed is recognised as a stored string, it is deallcoated first. @{b}Notes@{ub} - Only use Mui Set Str for tags which expect pointer to strings as their arguments. - The string is not permanently stored if the Tag Keep setting is on False - It is permissable to use the empty string, which sets the tag to NULL. - Do not use Mui Set for strings, unless you know the address of the string will not change. - The attribute you attempt to set must be setable. In the MUI autodocs, there is a set of 3 flags in square brackets after the tag name. The full set is [ISG]. To use Mui Set, or Mui Set Str, the 'S' flag must be present. @{b}Errors@{ub} @{u}Illegal MUI Object Address@{uu} The @{i}OBJECT @{ui}you have specified does not exist. Easylife does not check the value of the tag you pass, so if you pass an illegal value as a tab, anything could happen. @endnode @node C_MuiDo "MUI / Do Method" @aka C_MuiFn @toc MuiContents @prev MuiSet @next MuiNotify @{b}Command Syntax@{ub} Mui Do @{i}OBJECT , TAGLIST$ @{ui} =Mui Fn( @{i}OBJECT , TAGLIST$ @{ui}) @{b}Description@{ub} Mui Do & Mui Fn are identical, except Mui Fn returns a result, and Mui Do does not. They are both used to execute MUI Methods (MUIM_... tags). The decision of which one to use depends on whether the method returns a meaningful result - If it does use Mui Fn, otherwise use Mui Do. The @{i}TAGLIST$ @{ui}must being with an MUIM_... tag describing the method to be performed. The number, and format of the remaining taglist entries depend on the methods. Some will have a fixed number, others variable. In general, these taglists to not obey the rule of tags occuring in pairs, and order is usually important. @{b}Notes@{ub} - If you use Mui Fn for a method which does not return a value, it will still work - You will just get random garbage in the returned value. - If you use Mui Do for a method which does return a value, the method is still performed, but you will not be able to access the result. - Do not pass empty taglists. - The @{"Taglist$" link C_Taglist} function can be used to provide the taglist parameter. The @{"Default Taglist Bank" link C_TaglistEditor.guide/DefaultBank} provides many usefull taglists. @{b}Errors@{ub} @{u}Illegal MUI Object Address@{uu} The @{i}OBJECT @{ui}you have specified does not exist. @endnode @node C_MuiNotify "MUI / Notification" @toc MuiContents @prev MuiDo @next MuiInput @{b}Command Syntax@{ub} Mui Notify @{i}OBJECT , TAG$ , VALUE @{ui}To @{i}DEST_OBJECT , TAGLIST$ @{ui} Mui Notify @{i}OBJECT @{ui}To @{i}TAG , VALUE @{ui}To @{i}DEST_OBJECT , TAGLIST$ @{ui} @{b}Description@{ub} Mui Notify is a specialised version of the Mui Do command, where the taglist is an MUIM_Notify taglist. @{i}OBJECT @{ui} is the object you wish send send to notify method to. @{i}TAG$, @{ui}or @{i}TAG @{ui}is the tag to watch. @{i}VALUE @{ui} is the value you wish to watch for @{i}TAG$/TAG @{ui} changing to. DEST_OBJECT is the object you wish to send a method to whenever the notification is to a occur. @{i}TAGLIST$ @{ui}is the method to send to @{i}DEST_OBJECT @{ui} when notification occurs. @{b}Notes@{ub} - Use Tag("MUIV_Everytime") for @{i}VALUE @{ui}to be notified of every change. - You do not have to use Mui Notify for notification - @{"Mui Do" link C_ MuiDo} can also be used, and is particularly usefull in conjunction with the @{"Taglist$" link C_Taglist} function, and the @{"Default Taglist Bank" link C_ TaglistEditor.guide/DefaultBank} which contains many common notification taglists. - Unlike when creating MUIM_Notify taglists by hand, you do not have to include the length of the @{i}TAGLIST$ @{ui} anywhere in the arguments. @{b}Errors@{ub} @{u}Unmatched Tag@{uu} @{i}TAG$ @{ui}could not be found in Bank 13. @{u}Bank Not Reserved@{uu} Bank 13 is not reserved, or is not a tag bank. @{u}Illegal MUI Object Address@{uu} Either @{i}OBJECT, @{ui}or @{i}DEST_OBJECT @{ui}is not a valid MUI Object. @endnode @node C_MuiInput "MUI / Reading Input From An MUI Application" @toc MuiContents @prev MuiNotify @next MuiRequest @{b}Command Syntax@{ub} =Mui Input @{b}Description@{ub} You should very rarely have to call Mui Input directly in your program. The exception to this is that you should use: NULL=Mui Input After receiving a MUIA_Application_ReturnID notification from an object that is in the popup of a PopString object, and that has changed the string. You must call Mui Input before you read that string with Mui Get$, otherwise you will read the string in the gadget before the popup that is sending the notification has changed it. The normal way you calling Mui Input is by calling the _MUI_MAIN_LOOP procedure from the MUI_Support.AMOS library of procedures. This will using Mui Input call the procedures: - _USER_RETURN_ID when an MUIM_Application_ReturnID returns a value - _MUI_APPLICATION_QUIT when you should quit the program. See the MUI_Support.AMOS program for full details. @{b}Notes@{ub} - The Amos screen should always be put to the back when Mui Input is called. Mui Input does not do anything if the AMOS screen is visible. Mui Input prevents screen switching back to AMOS will it is executing. - You should lock Amos To Back while running MUI commands anyway, otherwise the system might hang if the AMOS screen is in front, and you'll have to reboot. Only leave it unlock while you are debugging. - If you want to know what Mui Input Actually Does: 1) If AMOS screen is in front, the function aborts. Otherwise AMOS Lock is called. 2) If there was a last call to Mui Input and MUI asked to wait on some signals, the exec.library wait function is called. 3) The application object is send an MUIA_Application_Input Method 4) The signals are stored to be waited on next time 5) The previous state of Amos' Lock/Unlock is restored 6) The return value of the MUIA_Application_Input is returned. @{b}Errors@{ub} @{u}Illegal MUI Object Address@{uu} You have not created an application object with Mui Application (Or it has been disposed of). @endnode @node C_MuiRequest "MUI / Simple Requesters" @toc MuiContents @prev MuiInput @next MuiFlush @{b}Command Syntax@{ub} =Mui Request(WIN_OBJ , TITLE$ , GAD$ , TEXT$) =Mui Request(WIN_OBJ , TITLE$ , GAD$ , TEXT$ , PAR$) @{b}Description@{ub} This pops up a requester, similar to the normal intuition EZRequest with some text and a row of buttons. The difference is it is an MUI window, with tab cycling, MUI text formatting, and keyboard shortcuts. WIN_OBJ is a window object to centre the requester over. Use 0, if you do not want the requester centred over a window. TITLE$ is the string to go in the requester window title bar. GAD$ specifies the text for the row of buttons. Each button is seperated with a '|' character. If the entry for a button begins with a '*', that is made the default entry (Selected if return is pressed). A character in the button text can be made a keyboard shortcut for the button by preceeding it with an '_' character. TEXT$ is the text to fill the body of the requester. It can contain newlines and escape codes for normal MUI text formatting. It can also contain C-Style %ld , %s , etc. to insert strings and numbers into the text. PAR$ contains the longword parameters for such codes in the order they occur. The result is the number of the button pressed. Buttons are numbered left to right, begining with 1, except that the rightmost button is button 0. (Commodores fault, not mine) E.g. TIT$="System Request" GAD$=" _Retry |* _Cancel " TEX$="Please Insert Volume"+Chr$(10)+"WIBBLE:" RES = Mui Request(0,TIT$,GAD$,TEX$) @{b}Notes@{ub} - If no application object exists, intuitions EZRequest will be called instead. This means the '*' and '_' will have no special meaning and will be displayed in the button text. @{b}Errors@{ub} @{u}Illegal MUI Object Address@{uu} You have specified a non-existant window to centre on. @endnode @node C_MuiFlush "MUI / Flushing An Objects Strings" @{b}Command Syntax@{ub} Mui Flush @{i}OBJECT @{ui} @{b}Description@{ub} This function erases from memory all strings attached to an @{i}OBJECT, @{ui} without disposing of the @{i}OBJECT. @{ui} It is usefull to list objects after the list has been cleared with MUIM_List_Clear to regain the memory taken up by the old list. @{b}Errors@{ub} @{u}Illegal MUI Object Address@{uu} The @{i}OBJECT@{ui} you have specified does not exist. @endnode @node C_MuiAdd "MUI / Dynamically Adding Child Objects" @toc MuiContents @prev MuiFlush @next MuiRemove @{b}Command Syntax@{ub} Mui Add @{i}CHILD @{ui}To @{i}PARENT @{ui} @{b}Description@{ub} Normally you make every object a child, or decendant of your application object when that is created. However, sometimes that is not possible. E.g. You may wish to popup a file selector window, or your applicaton may support editing multiple projects simultaneously, in which case you need to add a new window for each project. Fortunately MUI allows you to dynamically add children to some objects after they are created. In V2.2 this means: - New windows can be added to an application object. - New objects can be added to a group. (If the group is NOT in an open window). Mui Add can be used to add a new child to an existing object. The child should be created just like any other Mui Object. @{b}Notes@{ub} - Until the child is added, it is not part of the application, and will not be automatically disposed of when you dispose of the application object. - Conversely, after it has been added, it is part of the appliction, and should not be disposed of as a seperate object, or MUI will crash the system. - The Easylife @{"Default" link Easylife.guide/CommandEffects} routine will correct dispose of all un-added objects along with the application object. @{b}Errors@{ub} @{u}Illegal MUI Object Address@{uu} Either @{i}CHILD @{ui}or @{i}PARENT @{ui} is not a valid MUI object address. @{u}Illegal Function Call@{uu} The @{i}CHILD @{ui}is already part of the application tree. @endnode @node C_MuiRemove "MUI / Dynamically Removing A Child Object" @toc MuiContents @prev MuiAdd @next MuiHook @{b}Command Syntax@{ub} Mui Remove @{i}CHILD @{ui}To @{i}PARENT @{ui} @{b}Description@{ub} This is the opposite of the @{"Mui Add" link C_MuiAdd} command (Suprisingly). It allows you to remove a child object from the application tree. Currently 2 types of child can be removed: - Windows can be removed from the application. - Objects can be removed from a group, if the group is not in an open window. @{b}Notes@{ub} - Any Window, or Group Child can be removed. It does not have to be a child previously added with @{"Mui Add" link C_MuiAdd}. - Removing the child does not dispose of the object, it simply takes it out of the application tree. You may dispose of it, or you can add it to another part of the application tree to "move" the object. - Once it has been remove, the object is not disposed of automatically when you dispose of the application object. However it is still disposed of by the easylife @{"Default" link Easylife.guide/CommandEffects} routine. @endnode @node C_MuiHook "MUI / Hook Functions" @toc MuiContents @prev MuiRemove @next main @{b}Command Syntax@{ub} =Mui Hook( @{i}ADDRESS , DATA @{ui}) @{b}Description@{ub} Unfortunately, It is not possible to write an MUI hook function in AMOS (Or is it? You tell me!). However Easylife does support the use of assembler hook functions. When a hook is required in a taglist, use Mui hook to create it. ADDRESS is the address of the start of the Assembler Code. DATA is a longword that will be in register A4 when the hook code is called by MUI. Its most useful purpose is as a pointer to a larger data area. @{b}Notes@{ub} - You should not use the same hook twice, but you can create more than one hook with the same @{i}ADDRESS @{ui}and @{i}DATA. @{ui} @{b}See Also@{ub} The include file MUI/MUI-Hook-Functions.i The example file MUI/Listview-Hooks.s @endnode