MUI - MagicUserInterface A system to create and maintain graphical user interfaces (c) Copyright 1993 by Stefan Stuntz - ShareWare - Introduction ************ The concepts behind MUI ======================= MagicUserInterface, MUI for short, is a complete system to create and maintain graphical user interfaces. Creating such GUIs has been a big problem for a very long time, because the programmer got only little support from the operating system. Coming with Kickstart 2.0, the `gadtools library' was one step into the right direction, but even using this library generation of complex and flexible interfaces stayed difficult and still needs a lot of time. Today there are some tools available that make the usage of `gadtools library' much easier, however, even these results often are not satisfying. The biggest problem of the existing tools for the creation of user interfaces is the inflexible result. Most programs are still using builtin fonts and window sizes, although in times of high resolution graphics adapters this is nearly unbearable! However, it has to be said that Amiga users had to live with similar shortcomings all the time. Even the preferences programs of the workbench are all still using the default font topaz/8. MUI tries to end these disadvantages. The central thought behind MUI assumes that only the user (and not the programmer) of an application knows, how this program looks and is used best on his personal computer. Because of this MUI applications don't contain any absolut values for sizes or positions; the programmer instead only defines objects and groups of objects. The objects are set during the runtime by MUI according to the settings of the user. Consequently a MUI application gives the user many important advantages: - Font sensitivity It is possible to set the used font vor every MUI application. Gone are the times where A2024 users had to suffer from the programs that use the tiny topaz-8 font. And even better - MUI gives the user no restrictions, which fonts he has to use; especially propotional fonts are explicitly allowed. The proportional fonts make a program much nicer and even reduce the space the program's window need. - Changable window sizes All MUI windows have a sizing gadget which allows the user to change the window size until it fits his needs. As smaller the window becomes as closer the control items within the window come together. When the window becomes larger, there will be more space for displaying information (e.g. in listviews). Size and position of a window can be saved, for you have your favourite setting just after starting the program. - Flexibility Nearly all elements can be changed by the user regarding their look alike. The user determines the thickness of the borders, how the scrollbars have to look, which images have to be used and how much space is to be inserted between the lines of a listview. MUI gives the user a lot of possibilities to change the look and feel of an MUI application, see *Note The MUI preferences program: PRF_INTRO for details. - Controlling by keyboard Usually graphical user interfaces, and of course MUI applications as well, are controlled by mouse. However, many users would like to use the keyboard, because many operations can be executed faster and more conforable. Because of this, all MUI objects (e.g. string gadgets, radio buttons or listview) can be controlled by keyboard as well as by mouse! You even can put away your mouse completely, it is not needed any longer. - System integration MUI applications cooperate with the operation system in many ways. Every program can be iconified and uniconified by pushing a button or by using the Commodities exchange program. Furthermore does every MUI application have an Arexx-Port that allows you to control the complete user interface (and more) by remote control. - Adjusting to its environment For a MUI program it doesn't matter, if it runs on the Workbench or on a public screen, if the resolution of the screen is 640x200 or 1280x1024 pixels or if there are 4 or 256 colors available. Every application can be made to open on every screen and adapts itself to its environment. All settings mentioned above (and even more) can be changed by the user via the MUI preferences program. This can be done for all applications together (global) or for every single application. System requirements =================== MUI runs on version 2.0 of the Amiga operation system and above. Kickstart 1.3 is *not* supported; the times for that operation systems a gone completely. For the use of MUI a harddisk is highly recommended, although floppy disk usage is still possible. Due to the modular concept of MUI the first start of an application will last "a little" longer. MUI does not require a special processor type, but of course faster machines make life easier. For the managment and the layout of the objects many complex calculations are needed, so a "bare" 68000 computer could be a bit slow. MUI applications should run even on a machine with only 512 KB free RAM space, but it could become short quite soon. One (1) MB RAM should be sufficient even for complex MUI applications. Installation ============ MUI is distributed together with the Installer programm of Commodore; therefore installation shouldn't be a problem. Double click on the `MUI-Install' icon and the installation procedure starts its work. Special features of MUI applications ************************************ Windows ======= As already mentioned above, nearly all MUI windows are resizable. This allows the user to determine, if he wants his control items (i.e. buttons, listviews, a.s.o.) small and space saving, or bigger and easy to survey. As it would be very annoying to have to adjust size and position every time an application comes up, all MUI windows remember their size and position and supply these values, when the application comes up again. This is true for the "normal" window position and size as well as for the values of the window in "zoomed" state (after you hit the zoom gadget). After a reboot these informations about the windows a usually lost, if you have not saved them by hitting the `Save' button in the preferences window. By doing so all data regarding the windows are saved and are available even after a reset from now on. In addition to the depth and zoom gadget there is a third button in the titlebar of every MUI window. This button is used to iconify the whole application. All windows (and screens if available) of the application are closed and a little application icon appears on the Workbench. Doubleclicking on this icon makes the application open its window(s) (and screen) again. Keyboard control ================ All control items in a MUI window can be controlled completely by keyboard. The known keyboard shortcuts (marked by an underlined character) are supported of course. However this method comes to ts limits, if you look at listviews or cycle gadgets. Because of this the `TAB' cycling - up to now only used for string gadgets - has been made available for MUI applications. In MUI windows you can activate every object (not only string gadgets) by hitting the `TAB' key. As soon as you activated an object it can be controlled by keyboard. - Button gadgets `Return' is the equivalent for clicking with the mouse on a button. Pushing and releasing a button is handled in a different way. If you have already pushed a knob, you can cancel this action by pushing `Shift' additionally, before you release the `Return' key. - Checkmark gadgets An active checkmark gadget can be controled via `Space' or `Return'; the status of this gadget is toggled every time you hit the according key. - Slider gadgets The value of horizontal or vertical slider gadgets can be changed using the four cursor keys. Using qualifier keys additionally allows you to change the increase/decrease amount of the sliders. - Cycle gadgets An active cycle gadget can be switched by pushing the cursor keys. The `Return' key pops up the popup menu (as long as you did not disable this feature in the MUI preferences program). - Radio-Buttons Radio buttons are controlled by the cursor keys as well. - Listviews In an activated listview the cursor can be moved line by line using the cursor keys and together with the corresponding qualifier keys pagewise or even to the top or to the bottom. The `Return' key simulates a double click. If multiselect is allowed in a listview, you can select the different items with the `Space' key. - Windows If an application has opened several windows simultaneously that can be controlled at the same time, you can switch from one to another using the `Alt-Tab' key or the `Shift-Alt-Tab' key respectively. if the window has a close gadget, you can hit the `ESC' key to close the window. All explantations refer to the default settings, using the preferences program, you can change all used keyboard combinations until they suit you needs (see *Note Keyboard-Configuration: PRF_KEYBOARD). Listviews ========= The listviews of MUI work pixel orientated; it is possible that the line at the upper or lower border of the listview is shown only partially! Pixel orientated listviews are used on all modern operating systems to prevent the eyes from loosing the connection to the text (within the listview). Unfortunately, the resolution of the Amiga mouse is not sufficient to allow scrolling of lists that contain many entries by a few pixels only. For this reason, MUI supplies a "smoothing" option. Please see *Note Listviews: PRF_OBJECTS_LISTVIEWS for details. Cycle gadgets ============= The MUI cycle gadgets support - besides their "normal" function (next entry be clicking on them, previous entry by holding `Shift' additionally) - a popup menu feature. This popup menu pops up as soon as the the text section of the cycle gadget is hit and allows a quick and clear selection of one of the entries. The exact behaviour of the popup menus can be changed in the *Note MUI preferences program: PRF_INTRO Commodities interface ===================== Every MUI application ties itself in the system as a commodity. Because of this the user can control any MUI application via the `Commodities Exchange' program, i.e MUI Applications can be iconified or canceled for example. Builtin Arexx port ================== Every MUI application is able to receive commands via the builtin Arexx port. There are some default commands which are understood by every program: - QUIT Ends the application. - HIDE Hides (iconifies) the application - SHOW Shows (pops up) an iconified application. - INFO ITEM/A According to the given parameter the result string is filled with the following contents: - "title" Title of the application - "author" Author of the application - "copyright" Copyright message - "description" Short description - "version" Version string - "base" Name of the Arexx port - HELP FILE/A A list of all ARexx commands available for the application is written into the given file. In addition to the default commands an MUI application can (and of course should) support many application specific commands. The help list will contain these commands as well. Some little example scripts can be found in the `Rexx' drawer of the main directory of the distribution. Preferences Program ******************* Overview ======== The philosophy of MUI lies in the demand that an application should make as little statements about its user interface as possible. In general the progammer of a MUI application combines single control items (i.e. gadgets, borders, etc.) to groups and defines the relative position of these groups to each other. Further settings, for example the font name(s), the distance between the elements of a group and even the appearance of the frames and images, can be set by the user of the application. These settings are all done in the *Note MUI preferences program: PRF_MAIN. Please notice that the programmer of a MUI application is able to ignore many of the usually settable values and realize his own ideas for a "nice" graphical user interface. To talk turkey: If someone really wants topaz/8 and nothing else, the user cannot do anything against it. Of course, no programmer should try to decrease the possibilities of MUI in such a way. Main window =========== The preferences program consists of a main window, from which you can call different subwindows. Every subwindow covers a certain part of the configuration of an application. All windows are running parallel, i.e. it is possible to open several windows and change the settings in these windows "at the same" time. MUI supplies the possibility to change all settings for every single application. For this reaseon the preferences program shows a list of the program names that have already been started. The settings shown in the different subwindows refer to the currently active application name. In most cases however, it is more useful to change these parameters global, i.e. for all applications together. Do do so there exists an entry `-Global' at the very beginning of the list. If this entry is active, the setting made in the different subwindows are used for all applications, as long as the global and the local value had been the same before the change! If there exists for example a global setting for the font `helvetica/13', but the MUI preferences program has been set to font `Times/18', a change of this font in the *global* settings is done to all applications but the MUI preferences program. If a certain application is active, the `Default' button can be used to discard its local settings (after a safety requester) and make it inherit all the global settings. The application list still has another feature: If you doubleclick on an entry, an information requester will pop up, in which important data is displayed. For example the name of the Arexx port and the version number will be displayed. Please notice that this will be possible only if the application is currently running. At the lower window border are the `Save', `Use' and `Cancel' buttons, already known from the several system preferences programs; additionally you'll find a `Test' gadget. This `Test' gadget, which can be reached out of every subwindow by holding down `Amiga-T' via a menu item, can be considered to be the most used function in the preferences program. Especially in the beginning you may want to play around with the different settings of the MUI preferences program, until you have found the configuration that fits your needs. Pushing the `Test' button makes all applications currently running adjust their parameters to the new values. It is possible to change the settings of a running application and see immediatly the consequences of your actions. Please notice that it is possible that pushing the `Test' button seems to have no effect at all! Current applications will only update themselves, if their parameters do really change. If you e.g. change the local settings of MUI preferences program for the frame thickness, the `MUI-Demo' program will not update at all. The `Use'-Gadget saves the changes to the `ENV:' drawer and ends the preferences program. Please notice that the `ENV:' directory usualy resides in the `RAM DISK:' and a reset discardes all the settings made before. To save the settings for longer than until the next reset, you have to hit the `Save' button. All changes are saved to harddisk (`ENVARC:') and can be always used from now on. Besides the configured values themselves, all window positions of all applications are saved. If you hit `Cancel', all changes will be discarded. Applications that have already adjusted themselves to the new settings, because you hit `Test' return to their previous appearance. According to system preferences programs no savety savety request happens. Object window ============= Some settings for different interface elements are collected in the `Objects' window: Listviews --------- The `Leading' value determines the number of additional pixels that are inserted between the lines of a listview to improve readability. According to the used font and your personal taste it could make sense to set higher values, especially if you use small fonts as `topaz/8'; `Smoothing' enables the smoothing of the listviews. This setting has the effect that the the position of a list is not adjustable to the scrollbar immediately, but follows the scrollbar in steps depending to the speed of the movement. Thereby your eyes don't loose the contact to the text and can follow the movement more easily. As higher the smoothing value is, as bigger is the resulting effect. Selecting zero (0) does prevent the listviews from doing any smoothing at all. In multiselect listviews the user can select either `shifted' or `Always'. `Shifted' enables the usual multiselect mechanism, i.e. you have to hold down the `Shift' key while you are selecting the entries. If you select `Always', you don't have to hold down the `Shift' key. `Refresh' determines the kind of the listview refreshing. `Linear' refreshes the lines as usual from top to bottom, `intermixed' refreshes the lines intermixed, what should result in a "nicer" appearance especially on slow machines. The position of the arrow gadgets at the scrollbars can be controled by the `Arrows' gadget. There are three options. Cycle Popups ------------ The cycle gadgets of MUI supply a popup menu for easier usage, which is opened as soon as you have hit the gadget. It allows an easy and quick selection of the desired entry. `Level' determines the minimal number of entries that are needed to supply a popup menu. If you don't like popup menus, you just have to select a high value and you'll never see them. Usually popup menus appear directly under the gadget. For fast usage and less mouse movement you can configure the popup menus in a way that let the active entry appear just below the mouse pointer. For this reason there are the two options of the `Position' gadget. Window Spacing -------------- In this window you can determine the distance between the window border and the window contents pixel by pixel. Usually identical values for `Left' and `Right' as well as for `Top' and `Bottom' make sense, therefore these gadgets are connected one-sided. As soon as you move the `Left' or `Top' slider, the `Right' or `Bottom' sliders are moving automatically. To allow different values this connection does not work verse vica as well! If you move `Right/Bottom' the value of `Left/Top' stays untouched. Group Spacing ------------- A group object does nothing else but grouping other objects. Such a group is e.g. the group that contains the buttons for the subwindows in the MUI preferences. Using the the two parameters at `Group spacing' you can adjust the horizontal as well as the vertical distance between two elements of a group. Radio Button Spacing -------------------- These settings take only effect in connection with the radio button gadgets and determine, how much space is inserted between the single lines (`Vertical') and between the the knob and the description text (`Horizontal'). Frame window ============ Frames are important elements to create a straightforward graphical user interface and to separate single groups from each other. However, frames are a matter of taste, therefore you can change the appearance of all used frames. In usual (not MUI) programs for the Amiga, the frames have vertical lines with double the thickness of the horizontal lines. This comes from the fact that the usual resolution on old Amigas has been 640x200 (or 640x256 on PAL systems). On these systems the vertical and horizontal lines *seemed* to be the same thickness. Nowadays, where highres graphics adapters and flickerfixers are used very often and the resolution most often has a ratio of 1:1, there is no need to enlarge the frames in this way. MUI allows you to change the thickness of the frames using the `Thickness' cycle gadget. Framed groups can have a title. The color of this frame title can be set via the `Title Color' gadget. Three options are avalable: Black, White ore 3D. The title of the group is centered hoizontally at the upper part of the frame. Selecting `Title Pos' changes the vertical position of this title text. `Centered' centers the title text verticaly refering to the frame, `above' sets the baseline of the text to the value of the frame. This setting stands in connection to the inner spacing of a group frame, which is discussed below, see *Note Frame configuration: PRF_FRAMES_EDIT. When a programmer creates a MUI application, he doesn't set the look, but only the type for the frames. For example, a button gadgets gets a button frame and a string gagets gets a string frame. The appearance of the frames is determined by the user. Therefore all possible frame types are colleted in a list, together with a small picture that displays the currently selected look of a frame. The current frames are used in the following way: - Button frame for usual button gadgets, as for example for the `Edit' button below this list. - Image frame for small buttons that contain nothing but an image, e.g. the arrow gadgets in a scrollbar. - Text frame for text gadgets on which can neither be clicked upon nor can be edited and are used only to display information, e.g. status lines. - String frame for string gadgets. - Read list for listviews that only display a list and that can't be clicked upon. - Input-List for listviews in which the user can select entries, e.g. all listviews of the MUI preferences program. - Prop frame for all prop gadgets, used for example within scrollbars and sliders. - Group frame to group objects, for example the buttons for the subwindows of the MUI preferences programm are surrounded by a group frame. By a double click on an entry of a list or by using the `Edit' gadget the frame configuration window can be opened.: Frame configuration ------------------- In the frame window of MUI you can select one out of a list of predefined frames. The different possibilities are displayed in the `Type' gadget There exist two versions of every frame, `Raised' an `Recessed'. For every frame the distance between the frame and its contents can be changed by setting the appropriate slider gadgets. Usually you will select equal values for `Left/Right' and `Top/Border'. Therefore these sliders are connected in the same way as in *Note Window Spacing: PRF_OBJECTS_WINDOW. Please notice that it can make sense to select *different* values for `Top' and `Bottom' to equalize insymmetries, caused by the descenders of the used font. Image window ============ Graphical user interfaces often use little image, e.g. arrow buttons or slider knobs. A MUI application usually doesn't define these images, it just says it wants an arrow and MUI supplies this arrow. This allows the user to configure, how this arrow actually shall look like. Here comes a list of the images available for configuration: - `ArrowUp', `ArrowDown', `ArrowLeft', `ArrowRight' Four arrows aiming in the four different directions. - `CheckMark', `Radio-Button', `Cycle' The known images of the respective control item. Please notice that the checkmark image is only visible in selected state! - `PopUp', `PopFile', `PopDrawer' Images for popup buttons besides string gadgets. `PopUp' is used if neither a file nor a drawer is wanted. - `Drawer', `HardDisk', `Disk', `Chip', `Volume' Default images for the entries of a file requester. - `PropKnob' Image for the knob within the prop gadget Besides the list with these default images, you'll find the different background types. You can select many different backgrounds for MUI, e.g. one background for windows, another for the button gadgets and another for listviews. If you like colorful user interfaces, you'll surely be happy with MUI. - `Window' The window background is used on every place that doesn't match another background type, especially where no objects are. - `Requester' Background for MUI requesters, e.g. for the `About' requester of the preferences program. - `Textfield' Framed text fields (e.g. status lines) use this background type. - `Button' used for buttons containing text and for cycle gadgets. - `Active Gadget' a gadget which has been activated by `Tab' gets this background. - `Selected Gadget' a gadget which was selected by hit with the mouse, is marked by this background (besides the inversion of the frame). - `Listview' appears behind the lines of a listview. - `Listview Cursor' the cursor in a listview. - `Listview Selected' selected entries in a listview. - `Listview Selected+Cursor' the cursor on a selected entry of a listview. - `Prop-Gadget Background' the background in a prop gadget, i.e. the area on which the knob is moved around. After the meaning of every entry has been discussed, lets come to their configuration. A double click or the corresponing `Edit' button below the list opens the image configuration window for the active entry. There is no difference between a background pattern and a image configuration. Image configuration ------------------- MUI "understands" many image types: - Pattern A pattern is a simple matrix, some of them are already built into MUI. Patterns suit to be used as background image, but can also be used for several default images, such as the prop gadget knob. - Builtin-Images For all default images there is already one predefined look. These builtin images are made out of vectors and can be enlarged without limits. - MBR-Images These are IFF brushes using a special palette for the colors. The palette allows MUI to adapt the images to the colors of the used screen. On the MUI distribution disk there are several MBR images; of course you may create your own MBR images with an appropriate painting program. MBR images can't change their size. - Boopsi-Images A boopsi image actually is a program that is called every time it has to be drawn. Such images exist as shared libraries and should be stored in the `sys:classes/Images' drawer on your system partition. MUI comes along with some of these images that are made for the knob of a prop gadget. - Alien-Images Starting with Kickstart 3.0 there are the socalled `datatypes' available. With these datatypes it is possible to load any picture file, no matter if they are IFF, GIF or other formats. MUI supports that and allows you to use any datatype picture for background or standard image in all applications. Please notice that this feature is available only it you run Kickstart 3.0 and above. The `Image-Edit' window allows you to assign an image out of the categories mentioned above, to all standard images or backgrounds. An image assignment consists of a string that is either a special value identifying a builtin image or the complete path name for images stored on disk. The image path can be entered "by hand". However, it is easier to hit the buttons just beneath the two status lines. The `Pattern' line contains all builtin patterns, the `Builtin' line contains all builtin vector images. The three buttons `MUI Brush', `Boopsi' and `Alien' call a file requester, from which you can select the desired files. The default paths can be set in the *Note General Window: PRF_GENERAL, furthermore the previous set path is remembered. Note: `Alien' is only available with Kickstart 3.0 and above. Font window =========== MUI uses five fonts that can be used by applications: - `Normal' This font is used for all texts as long as there was no other font configured explicitly. - `List' The defaullt font for listviews. - `Tiny' This font is used for small an quite unimportant descriptions. The lettering of the scale object (see `MUI-Demo') is using this font for example. - `Fixed' If a program needs a fixed width font, it uses this one. - `Title' This font is used for the group titles. If a font field stays empty MUI uses appropriate default fonts, i.e. the system default font for the fixed font and the default font of the screen for all the others. Screen window ============= MUI applications are able to run on any public screen. The programmer doesn't have to care about - it's all done by MUI. The public screen name can be set in the MUI preferences program, and even better, MUI contains kind of a screen manager that allows you to configure any screen with any size and resolution. To configure a public screen the string gadget at the lower end of the window should be used. If the selected screen is already available, when the application starts up, it will be used. Otherwise MUI scans the list of the builtin screen manager for the desired screen name and opens it, if available. If the wanted public screen either couldn't be found or couldn't be opened (e.g. because of insufficient memory), the application starts on the default public screen (usualy this is the Workbench screen). The biggest part of the window is covered by the screen manager. In this list you'll find the names of all screens already set and two items that correspond to the default public screen and to the Workbench screen. To create a new screen, just hit the `New' gadget. A new screen entry is added to the screen list. This screen's parameters can ba adjusted in another window. Screen configuration -------------------- This window allows you to adjust the different parameters of a screen. First of all there should be a screen name, which is used to find the screen. This name can be entered in the `Public Screen' string gadget. All public screens in the system must have different names. The `Title' string gadget may be used to enter the text that has to appear in the screen's titlebar, the `Font' string gadget contains the default font of the screen, which is used for the screen an all its windows. In the `Screen Mode' group the display mode, the resolution and the number of colors is shown. If you hit the `Adjust' button, a screenmode requester pops up that can be used to change these parameters. Besides these essential values, the screen can have the following features: - `Auto Scroll' If the screen was set larger than the visible part was defined, it will be scrolled automatically as soon as the mouse touches the screen border. - `Draggable' If the screen doesn't have this attribute, it can't be dragged. - `Exclusive' The screen cannot share its display with other screens; it will be displayed separately (Kick 3.x only). - `Interleaved' This attribute reduces - if set - the flicker, that appears especially during the scrolling of lists on colorful screens (Kick 3.x only). - `Open Behind' The screen will be opened behind all other screens. - `System Default' The screen is declared to be the system default screen. All windows that are opened on the system's default screen (e.g. shell windows), are routed to this screen. Keyboard window =============== All keys that are used to control the MUI applications, can be configured in this window. The entries of the list are speaking for themselves, the format is the same as the one used for the input events of the `commodities.library'. Special attention earns the `Press' key. MUI needs this key to be able to react on key releases. Therefore this qualifier description has to contain the string `-upstroke'. System window ============= The `System window' contains some settings that refer to the cooperation of MUI and the operating system. Windows can be refreshed either `smart' (fast but eating chip memory) or `simple' (slower but no need for memory). The `Window Refresh' cycle gadget can be used to set one of these refresh types. Into the `Startup' and `Shutdown' string gadgets two commands can be entered that are executed automatically before and after running the application. It is possible for example to use an external screen manager for opening the desired screen for the application (if the builtin screen manager doesn't fit your needs). Another possibility is to use a simple `echo' command to save the startup and shutdown time of the application. The `Iconify-Hotkey' allows you to enter a key combination that iconifies the application (and pops it up again). The format is the same as the one described for the input events of the `commodities.library'. If the `Iconify-Gadget' checkmark is set, every window of the application gets an additional gadget in the upper window frame that makes the window iconify as soon as you hit it. Usually an appicon is created for every iconified application on the Workbench. Doubleclicking this icon reactivates the application. If `Iconify-Icon' is not set, no AppIcon appears. The application activation can still be done via the iconify hotkey or the `Commodities Exchange Program'. `Start Iconified' determines, if the application will be iconified at startup. This will make sense, for example, if you place some tools into the `WBStartup' drawer, to make them available via keystroke. General window ============== This window is used to set some values used by the MUI preferences program itself, i.e. the preferences of the preferences. The three string gadgets of this window give the path names which will be used, if the corresponding button in the *Note Image configuration: PRF_IMAGES_EDIT is hit. CLI interface ============= The MUI preferences program supplies a small CLI interface that can be used to give other programs access to MUIs builtin screen manager utility. The syntax is: NAME,OPEN/S,CLOSE/S NAME: Name of a (already configured) public screen OPEN: Open screen CLOSE: Close screen ARexx Port ========== The preferences program contains a simple ARexx port, defining the following four commands. * `SAVE' Does the same as the `Save'-Button. * `USE' Does the same as the `Use'-Button. * `TEST' Does the same as the `Test'-Button. * `CANCEL' Does the same as the `Cancel'-Button. Of course the *Note standard ARexx commands: USE_AREXX can also be used. Programming MUI *************** Object Oriented Programming =========================== MUI is based upon BOOPSI, the `Basic Object Orientated Programming System for Intuition'. To understand MUI is a good idea to get at least a littel overview about the concepts of object orientated programming. A good and sufficient introduction to this theme can be found in the first section of the BOOPSI chapter in `Rom Kernel Reference Manual - Libraries'. The following documentation about the programming of MUI assumes that terms as "objects", "classes", "methods" and "attributes" are known. MUI Class Tree ============== All classes of the MUI system are built into a fixed tree. This tree starts directly below BOOPSIs rootclass, other BOOPSI classes are not used. Nevertheless it's possible to include BOOPSI gadgets in MUI applications, see the `Autodocs' for details. Following is the complete class tree: +-----------+ ! rootclass ! +-----------+ ! +--------+ ! Notify ! +--------+ ! +----------------------+-----------------------------+ ! ! ! +------+ +--------+ +-------------+ ! Area ! ! Window ! ! Application ! +------+ +--------+ +-------------+ ! ! +-----+-------+-------+-------+-------+-------+-------+-------+ ! ! ! ! ! ! ! ! ! ! +-----+ +----+ +------+ +----+ +------+ +-----+ +-----+ +------+ ! !Image! !Text! !String! !Prop! !Slider! !Gauge! !Scale! !Boopsi! ! +-----+ +----+ +------+ +----+ +------+ +-----+ +-----+ +------+ ! +---------------+-----------------------------+ ! ! +------+ ! ! List ! ! +------+ ! ! ! +-------------+-----------+ ! ! ! ! ! +---------+ +----------+ +-------+ +-------+ !Floattext! !Volumelist! !Dirlist! ! Group ! +---------+ +----------+ +-------+ +-------+ ! +------------+---------+--------+ ! ! ! ! +---------+ +--------+ +-----+ +-----+ !Scrollbar! !Listview! !Radio! !Cycle! +---------+ +--------+ +-----+ +-----+ Every class is coming with a seperate documentation, located in the `Developer/Autodocs/' drawer of this distribution. This documentation contains a complete description of all methods and attributes, together with some background information what the class is used for. Application Tree ================ Every MUI application consists of a collection of many objects, which are all connected in one big tree: certain objects can have one more children. The root object of an application, the "father" of all other objects, is the application object. It handles all kinds of communication, e.g. user input, commodities messages or ARexx commands. An application object can manage any number of children, these children are all window objects representing the different sub windows of an application. Every window object itself handles exactly one child. This is usually an object of group class and describes the complete layout of texts and gadgets within the window. Of course objects of group class may also contain children, being either a gadget (e.g. a string object) or another group containing lots of children again. Following is a little diagram to make things clear how an application could look: +-------------+ ! Application ! +-------------+ ! ... ------+---------------+-----------------+------ ... ! ! +--------+ +--------+ ! Window ! ! Window ! +--------+ +--------+ ! ! +-------+ ! Group ! ... +-------+ ! +------------+-+--------+-----------------+ ! ! ! ! +--------+ +-------+ +------+ +-------+ ! String ! ! Group ! ! Text ! ! Group ! +--------+ +-------+ +------+ +-------+ ! ! +-----+-----+ +-----------+------------+ ! ! ! ! ! +------+ +-------+ +------+ +-------+ +--------+ ! List ! ! Cycle ! ! List ! ! Group ! ! String ! +------+ +-------+ +------+ +-------+ +--------+ ! +-----+-----+ ! ! +-------+ +-------+ ! Radio ! ! Radio ! +-------+ +-------+ This structuring also appears in the source code of a MUI program. Generation of the application is usually done with one big command that returns a pointer to the application object. Within this command, all children (windows, groups, gadgets) are created "on the fly". Object Handling =============== A MUI object is created using the command Object * MUI_NewObject(STRPTR class, Tag tag1, ..., TAG_DONE); which can be found in `muimaster.library' The parameter `class' gives the name of the object class (e.g. `MUIC_Window', `MUIC_Slider',...). If the needed class isn't already loaded it is loaded from disk (as well as eventually needed superclasses). Together with the values of the taglist it is possible to give the object certain attributes at time of generation. The kind of the used attributes does depend strongly on the used object class, of course. Generating a string object e.g. could look like this: MyString = MUI_NewObject(MUIC_String, MUIA_Frame , MUIV_Frame_String, MUIA_String_Contents, "foobar", MUIA_String_MaxLen , 80, TAG_DONE); As already mentioned above, an object is able to understand all attributes and methods of its superclass(es) in addition to its own ones. As the string class is a subclass of the area class, the `MUIA_Frame' attribute can be used for the string class as well, although the string class itself doesn't know how to handle it. A completed object can be controlled by the usual BOOPSI functions of the operating system. Atributes are set using `SetAttrs()' and retrieved using `GetAttr()': char *contents; SetAttrs(MyString,MUIA_String_Contents,"look",TAG_DONE); GetAttr(MUIA_String_Contents,MyString,&contents); printf("Always %s on the bright side of life.",contents); Many MUI classes support special functions, that can be called using the `DoMethod()' function: DoMethod(mylist,MUIM_List_Remove,42); /* und weg ist der 42. Eintrag... */ All classes, their methods and attributes are discussed in great detail in the autodoc files coming with this distribution. If an object is no longer needed, it can be deleted using: VOID MUI_DisposeObject(Object *obj); Of course after doing so, you cannot access this object any longer! When deleting objects, the parent-child connections play an important role: If you delete some object that contains children, all of these children (and their children, and the children of these children, ...) will also get disposed. Thus, you will usually only need one call to `MUI_DisposeObject()' to get rid of the complete application with all its windows and gadgets. Macros ====== The creation of a MUI user interface usually happens via a single (but big) `MUI_NewObject()' command. Many tags are given to this function as parameters and the tag values often contain `MUI_NewObject()' calls again. Because of the large quantity of function calls such a generation would become very complex soon. To prevent this, there are some predefined macros within the include files for "C" programmers that shorten many function calls. It is possible for example to use WindowObject instead of MUI_NewObject(MUIC_Window Please notice that the window object does contain an opening bracket, which means that you do a function call. Such macros have to be finished by a TAG_DONE) or the appropriate macro: End Besides these "open ended" macros there are some complete objects defined in `mui.h'. SimpleButton("Cancel") for example, creates a complete button object. These macros can of course be used directly in your own applications, but are mainly intended as kind of examples. Taking a look on `mui.h' can be useful even for non "C" programmers because it is well documented and contains many hints, how to manage certain problems. Layout ====== The layout of a MUI window (the positions and sizes of all its elements) is not fixed, but adapts itself dynamically to the existing environment. This concept makes it possible that applications adapt themselves to all used fonts and window sizes and the programmer even doesn't have to care about. To define the layout of a window, you have to use objects of group class. A group object has the ability to tell his children how they are positioned. There are e.g. horizontal or vertical groups, or even groups that layout there children in a two dimensional matrix. A small example may illustrate this. The layout of a file requester has to be created. This requester could look look this: +---------------------------------------+ ! ! ! +------------------------+ +------+ ! ! ! ! ! ! ! ! ! C (dir) ! ! dh0: ! ! ! ! Classes (dir) ! ! dh1: ! ! ! ! Devs (dir) ! ! dh2: ! ! ! ! Expansion (dir) ! ! df0: ! ! ! ! ... ! ! df1: ! ! ! ! Trashcan.info 1.172 ! ! df2: ! ! ! ! Utilities.info 632 ! ! ram: ! ! ! ! WBStartup.info 632 ! ! rad: ! ! ! ! ! ! ! ! ! +------------------------+ +------+ ! ! ! ! Path: _____________________________ ! ! ! ! File: _____________________________ ! ! ! ! +------+ +--------+ ! ! ! Okay ! ! Cancel ! ! ! +------+ +--------+ ! ! ! +---------------------------------------+ This layout has to be broken up into horizontal and vertical groups. In this case the window contains one vertical group with four children. The first and the fourth child are again groups and contain hoizontal children. Using MUI such a layout would look like: VGroup, Child, HGroup, Child, FileListview, Child, DeviceListview, End, Child, PathGadget, Child, FileGadget, Child, HGroup, Child, OkayButton, Child, CancelButton, End, End; That's all the programmer has to specify regarding the layout. All objects know their minimal and maximal sizes and are managed automatically by the MUI system according to the size of the window. The layout process can be influenced in many ways, e.g. by inserting space objects or by assigning different weights. More information on these topics can be found in the autodocs. Notification ============ The central element for controlling a MUI application is the notify mechanism. Using it, it is possible to make objects talk to each other or talk to the application. To demonstrate these options, the listview is a good choice. Such a listview usually consists of a list with some entries and a scrollbar to move around within this list. The position of the top line of a list is specified by the listviews `List_TopPixel' attribute. This special list has to be controlled by a scrollbar. A scrollbar has a `Prop_First' attribute as well that gives its position and it changes its value automatically as soon as the the user moves the knob. To connect the two elements, the list and the scrollbar, one would use a notify command: DoMethod(ScrollbarObject,Notify,Prop_First,EveryTime, ListObject,3,Set,List_TopPixel,TriggerValue); To make it clear: Every time, the scrollbar object changes its `Prop_First' value, the list object shall change its `List_TopPixel' attribute accordingly. From now on the list and the scrollbar are connected to each other. As soon as the proportional gadget is moved, the position of the list changes accordingly; the programmer doesn't have to care about. MUI does already have an complete listview object that has the connection above (and some others) already implemented. The notify mechanism, however, can be used for many other tasks. In the `MUI-Demo' program, for example, the button gadgets are connected to the convenient windows; clicking on a button opens a window automatically. Futher information can be found in the autodocs for the notify class. Late Binding ============ Usually the complete user interface of an application is created by one single command. This has the advantage that all objects exist at the same time and you always can access them; furthermore the error handling becomes very easy. There area cases, in which it makes sense to create certain windows only if they are actually needed: For example, if an application supplies many subwindows and would use too much memory, or if the number and contents of needed windows is not known at application startup time. Therefore MUI supports the option of "late binding". Using this mechanism children can be added and removed after their object already has been created. MUI uses the methods `OM_ADDMEMBER' and `OM_REMMEMBER' to make this possible: DoMethod(parent,OM_ADDMEMBER,child); /* add child object */ DoMethod(parent,OM_REMMEMBER,child); /* remove child object */ The two methods are only supported by MUI's application and group class; these are the only classes that can manage several children. Please notice: for objects that do not have parents, be it, because they are not yet connected using `OM_ADDMEMBER' or because they are disconnected using `OM_REMMEMBER', the programmer is responsible for deleting by calling `MUI_DisposeObject()'. On the other side, objects that still are children of other objects must not be deleted! Dynamic Windows --------------- Let's say an application object is already set up and another (not yet existing) window has to be added. To do so the window object has to be created first: win = WindowObject, MUIA_Window_Title, "New Window", WindowContents, VGroup, Child, ..., Child, ..., Child, ..., End, End, End; if (!win) fail(); /* necessary !! */ After the window object is created, it can be added to the application as one of its children: DoMethod(app,OM_ADDMEMBER,win); Now this window has become a part of the application, just as if it had been created as a subwindow together with the application object. It can be opened and closed by setting the according attributes and will be deleted automatically as soon as the application is ended. Usually, however, you'll want to delete this window directly after usage, because the late binding wouldn't make much sense otherwise. After closing the window via set(win,MUIA_Window_Open,FALSE); you can remove it by calling DoMethod(app,OM_REMMEMBER,win); After this you have to delete the window object "by hand", since the application no longer knows of it: MUI_DisposeObject(win); This method makes it possible to create subroutines that open their own window, wait for some imput events und return something. To illustrate this, here is a short example: set(app,MUIA_Application_Sleep,TRUE); // disable other windows win = WindowObject, ...., End; // create new window if (win) // ok ? { DoMethod(app,OM_ADDMEMBER,win); // add window... set(win,MUIA_Window_Open,TRUE); // and open it while (running) { switch (DoMethod(app,MUIM_Application_Input,&sigs)) { ... // Extra Input loop. For this window only. ... // Notice: The special value ... // MUIV_Application_ReturnID_Quit should be recognized ... // as well } } set(win,MUIA_Window_Open,FALSE); // Close window DoMethod(app,OM_REMMEMBER,win); // remove MUI_DisposeObject(win); // and kill it } set(app,MUIA_Application_Sleep,FALSE); // wake up the application Dynamic Groups -------------- In the same was you can add windows to an application after its creation, you can add elements to already existing group objects. This may be useful if a group contains many similar children or if the number of children is not known in the beginning. You can add new elements to groups or delete them again, but the window that contains this group must not be open! A small example: app = ApplicationObject, ..., SubWindow, win = WindowObject, WindowContents, VGroup, ..., grp = VGroup, End, ..., End, End, End; /* The group 'grp' has been created without any children */ /* The window must not be opened now */ for (i=0; i