MultiDialog (GEM-Dialogs in Windows) ========================================= Copyright (c) 1992-93 Helmut Neukirchen B”nnersdyk 63 D-47803 Krefeld Germany e-mail: hn@pool.informatik.rwth-aachen.de All rights reserved. Short english manual for MultiDialog >=V1.00 (05/30/93) --------------------------------------------------------- Any commercial distribution is strictly prohibited! (MultiDialog is a kind of Public Domain.) What does MultiDialog ? ------------------------- MultiDialog puts nearly any GEM-dialogbox into a GEM-Window. The result is that you can access the menu-bar or other applications while a dialog is running. This is especially VERY usefull for multitasking TOS-releases. Though MultiDialog was designed to work with Atari's MultiTOS it runs with all other TOS versions, too (i.e. TOS 1.0 - 4.xx and multitasking enhancements like MultiGEM). (I hope :-) Installation -------------- MultiDialog can be installed (and configured) in several ways, because it can be started as a GEM-Applikation, a GEM-Accessory or as an AUTO-folder TOS-program (You just need to change the extension of "MULTDIAL.*" from "PRG" to "ACC" - the program-file is the same, it recognizes the way it's started!). I suggest the following way of installation: 1. Copy MULTDIAL.PRG to your AUTO-folder. (MULTDIAL.PRG will display a message when it's started via the AUTO-folder.) If you have to configure MultiDialog very often: 2. Copy MULTDIAL.ACC in your root-directory (or from whereever your ACC's are loaded.) If you don't want to reset (in order to load the AUTO-Folder), you can install MultiDialog just by starting MULTDIAL.PRG from the Desktop, too. Configuring MultiDialog ------------------------- You can configure MultiDialog using a GEM-dialog. To do so you should have MULTDIAL.ACC installed and chose the menu-item "MultiDialog" from the accessory-menu. (If MultiDialog wasn't installed or if it isn't installed as Accessory you will have to start MULTDIAL.PRG now to install or to configure MultiDialog.) A dialogbox should appear now. - The first parameter you can change is "MultiDialog: [An|Aus]". When " An " is selected this means that MultiDialog does interfere in the AES-calls to handle dialogs. When " Aus " is selected MultiDialog does not interfere in these calls (But still remains installed in memory and in several vector-chains.) The next items consider application specific configurations. - "FormCenter: [immer|Mitte|Ecke|Maus]" is the AES-routine which centers a dialogbox in the middle of the screen. Especially when using bigscreens it's annoying that a small dialogbox appears in the middle of the big screen, because you have to move the mouse quite far. MultiDialog can stop this. You can tell MultiDialog to put dialogboxes in the upper left corner (item " Ecke "), just at the mouse-pointers position (item " Maus ") or in the middle (items " immer " or " Mitte "). The options " Mitte ", " Ecke " and " Maus " do remember the position a dialogbox had before, so you can move them at a position you like and they'll appear from now on at this position. If they are displayed for the first time they'll appear in the corner, the middle or at the mouse-position (just as you've configured). In contrast the item " immer " displays the dialogbox in the middle everytime (just as you are used to with the original GEM-routine). If you've got any problems with dialogboxes which are not completely visible try the " immer "-button, it's the most compatible. - The next line "Fenster bei: [Alert|FormDial|FormDo]" considers the circumstances to open a window for a dialogbox. The first item " Alert " is used to decide whether alertboxes should be displayed in windows or not. I suggest to activate this because MultiDialog can handle alertboxes without any problems (well, in fact you might get problems with the redraw...). The next two items refer to ordinary dialogboxes. " FormDial " is the most comfortable setting, but it works only with programs which use FormDial calls. The last item " FormDo " works with nearly any program, but it is not a very elegant way. A window is created at the beginning of a FormDo-call and deleted at the end of the FormDo call. There are two disadvantages: In a lot of dialogs the user can scroll or display different items (e.g. the "Install icon"-dialog of Atari's NEWDESK, but this is no good example as you will see later). In this case the window MultiDialog creates is opened and closed every time a new item is displayed. This slows down the dialog very much. The window MultiDialog creates is opened AFTER the dialog was drawn. When createing the window the dialog might get painted by other windows which are already visible. So the optic gets destroyed. - to handle this problem you can choose with "ObjcDraw bei FormDo: [Ja|Nein]" whether to repaint the dialog or not. " Ja " will repaint the dialog if the window was created by FormDo. This can slow down the dialog handle once again. Furthermore some programs do paint some graphics (e.g. images, color ranges) in the dialog which MultiDialog cannot repaint. For those programs you should choose " Nein ". Because you won't have these problems with FormDial-dialogs this selection is only available if " FormDo " is selected at the "Fenster bei:" line. (That's why I say "Fenster bei: [FormDial]" is more comfortable, because this setting is absolutely compatible to the original GEM-routines (with 1 exception - see Bugs/Restrictions)). - With the last option "Fenstertitel: [Ja|Nein]" you can tell MultiDialog to create dialog-windows with or without a titlebar. "Ja" enables the titlebar, "Nein" disables it. In order to move a dialog-window you have to click at the background of a dialogbox and drag it around. Because some programs need other configurations than other programs you can tell MultiDialog to take for specific applications specific configurations - MultiDialog switches automatically. - The " Neu "-button is used to create new entries in the auto- switch list. You can type in the name of the application in the edit field and MultiDialog takes the configuration you have chosen for that application (take the name which is displayed as window-name). - With the up- and down-arrow you can scroll between the different applications which need a special configuration. Most of the application work with the same standard configuration. This configuration-entry has the name " Default "; MultiDialog takes it if it couldn't find the application's name in the list you've entered. - If you want to delete entries from the auto-switch list you have to use the " L”schen "-button which deletes the entry which is visible at the moment. (You can't delete the " Default " entry!) - The " Sichern "-button saves the auto-switch list in your AUTO-folder in a file named "MULTDIAL.INF" which will be loaded next time if it is is found in your AUTO-folder. - " OK " closes the dialogbox. " Abbruch " does the same but it doesn't update the changes you have made (this only works with the changes you've made on the entry which is visible now. Whenever you press the arrow-buttons the changes for that entry are updated at once.) How to handle MultiDialogs ---------------------------- Dialogs which profit of MultiDialog will appear in a window. Depending on your configuration this window might have the title " MultiDialog: " (where is the name of the application). If MultiDialog recognizes an accessory the app_name will be " Accessory " (using MultiTOS you'll see the names of accessories, too). You can manipulate the buttons of the concerning dialog as you're used to. But furthermore you can now access the menu-bar (e.g. the accessories) and the windows of other application which can do graphics in their windows even while the dialog is active. (Now that's what I call real Multitasking! :-) Though you can select items from the menu-bar the application which displays the dialog can't react to them because at this time it is waiting for the dialog and it isn't prepared to perform any other action. If the MultiDialog-window was opened by a FormDial call you can also move the dialog using the move-bar of the window or by dragging the backround of the dialogbox (this feature is similar to "fly-dial"). (If the program uses only FormDo and you have selected "Fenster bei: [FormDo]" you can't move it!) In the case a program calls FormDial but doesn't call FormDo a window is created too, but you can't access the menu-bar and all the other wonderfull things MultiDialog makes possible. In this case the name of that window is just " Dialog: " (only if window-titles are activated). Known Bugs/Restrictions ------------------------- I don't know any bugs which really cause a crash, most are just restrictions. (So I'm waiting for bug-reports I can reproduce.) - First the ones concerning Singletask-TOS: The Desktop does not use TRAP #2-GEM calls so MultiDialog can't affect the Desktop's dialogboxes. (The Multitasking-Desktop of MultiTOS uses TRAP #2 calls, so it uses MultiDialogs.) MultiDialog can't find out the names of accessories, so auto- switch for accessories is not possible. (AES<4.0 has no possibility to search for processes.) - MultiDialog is aware of MultiTOS, so there's only one bug: MultiDialog uses the appl_search-call to inquire the name of an application; this changes the appl_search counter. So if an application does an appl_search, then a dialog and after that a second appl_search, the second appl_search returns not the expected values, because in the meantime MultiDialog used appl_search, too. - Now the problems you'll have with all TOS-releases: Programs which already use own dialog-handlers (e.g. fly-dials) won't use MultiDialog, because they don't make a FormDo call which MultiDialog needs. Sometimes redraw for the programs window(s) is not possible because MultiDialog has to do the redraw. MultiDialog can only redraw the area which was visible when the MultiDialog-window was opened. Some programs reserve almost any memory which is available. MultiDialog needs some space to put dialogs into windows. The dialogs of that programs won't appear in windows (that application won't run correctly under MultiTOS either)! With MultiDialog you can access the menu-bar even while doing a dialog. But the program can't react to any events, because it's just waiting for the dialog and nothing else: first you have to end the active dialog. (It's the same with the programs window(s) or desktop: you can't work with them until the dialog is ended.) Every time the dialog is moved or redrawed the cursor of an edit- field is set at the end of this field. It's not a good idea to start or terminate a program or to change the resolution while a MultiDialog is visible (The first case considers single tasking TOS, the last MultiTOS.). MultiDialog can handle this cases, but to do so it has to end a dialog by force: It ends the dialog by doing as if the user pressed the default-button (which is usually "OK" or "CANCEL") - if no default-button exists it simulates a press of the last button in the object-tree of the dialog (which is usually the "CANCEL"-button). But these buttons might be e.g. a "DELETE ALL/FORMAT HARDDISK/START NUCLEAR-WAR"-button or something similar, so you'd better end any MultiDialogs manually and do then the resolution change or start/terminate a program. The file-selector isn't displayed in a window. (So it still blocks screen output.) Now a really annoying problem :-( If a program makes more FormDial(FMD_START) calls than FormDial(FMD_FINISH) calls "dead" windows remain on the screen. These windows can't be closed or moved - a way to get rid of them is to terminate the program to which they belong. You should disable "Fenster bei: [FormDial]" and use instead "Fenster bei: [FormDo]" if you have this problem. (This is the reason why I've implemented the auto-switch feature - and probably the reason why Atari didn't implement the MultiDialog stuff in MultiTOS!) Note: This behaviour is not a bug in MultiDialog, it's a real bug in the concerning application which should be reported to the developers of this application. Moreover MultiTOS' NEWDESK has exactly this bug: Any dialog which offers the " Skip "-option calls for each file a form_dial(FMD_START) but only one form_dial(FMD_FINISH) at the end. MultiDialog tries to fix this, but this might fail with new MultiTOS releases. (I reported this to Eric Smith, let's hope he fixes it!) If you're using an old MultiTOS (01/15/93) you have to add the entry "OLDMTOS" to the auto-switch list, to inform MultiDialog of this old MultiTOS. How to get rid of that dead windows ? After exiting the concerning program the dead window will be deleted. A method to remove dead window without exiting is the following way: 1. Switch MultiDialog off ("MultiDialog: Aus") 2. Let the concerned program open a dialog once again. Often this dialog catches the dead window. 3. Quit the dialog. Maybe the dead window will be closed, too. 4. Now you can switch on MultiDialog again. In case you encounter any program-crashes in combination with MultiDialog and other resident utilities you may try to change their positions in the AUTO-folder (while testing MULTDIAL.PRG was the last program in my AUTO-folder). Please send bug-reports concerning MultiDialog to the addresses mentioned above (e-mail prefered). Some notes for programmers ---------------------------- First: Don't Panic! Second: MultiDialog bends some vectors using XBRA-structures (the id is "MDIA"). It uses the TRAP #2 (GEM), TRAP #13 (BIOS) and the gem- vector 258 (etv_term). It is suggested to use MultiDialog only in environments which use XBRA-structures for TRAP #2 and etv_term, too. If available a cookie ("MDIA") is installed. The cookie MDIA points to a longword, which contains MultiDialogs default configuration: The highest bit (#31) is equivalent to the "MultiDialog: An/Aus"-button (bit set: on, bit cleared: off). The other bits are not documented and mustn't be changed. The preceding word reflects the bcd-coded version of MultiDialog (e.g. V1.01=$0101, V1.23=$0123). Versions older than 1.01 are indicated by $0000: IF versionword= $0000 THEN version<1.01 ELSE version=versionword The preceding word contains a bitvector, which shows MultiDialog's abilities (this might differ from the configuration the user has chosen): bit 0: a new form_center is implemented bit 1: form_dial and form_do open a window for dialogs bit 2: form_alert opens a window bit 3: form_do allows to use shortcuts bit 4: dialog-windows may have no NAME and no MOVER (all other bits are reserved) bits set mean that the according ability is implemented. In versions older than 1.01 this word contains $0000 and has to be read as $0007: IF version=$0000 THEN abilities=$0007 ELSE abilities=abilityword summary: word: abilities (version=$0000=>$0007) word: version ($0000=>version<1.01) cookie-jar: MDIA pointer ----> long: default configuration This memory-region has the protection-attribute GLOBAL. For any dialog displayed it needs memory via Malloc for local- variables, the window and quite a lot memory to save the screen for redraw requests (on ST's thats 32KB, but with true-color and bigscreen it can be 0.5MB and more. But it doesn't crash if there's not enough memory it just can't do the redraw or create the window!) (I've to use Malloc's because MultiDialog has to be fully reentrant and supports an infinite amount of dialogs at the same time.) If you want your program to profit from MultiDialog you should use FormDial(FMD_START) at the beginning of a dialog, a FormDo in the middle and FormDial(FMD_FINISH) at the end. Take care that any FormDial(FMD_START) has an corresponding FormDial(FMD_FINISH) - otherwise MultiDialog won't delete it's windows correctly. A dialog-routine should look like that: form_center(dialog,size_x,size_y,size_w,size_h) wind_update(BEG_UPDATE) wind_update(BEG_MCTRL) /* not necessary */ form_dial(FMD_START, size_x, size_y, size_w, size_h, size_x, size_y, size_w, size_h) objc_draw(dialog,ROOT,MAX_DEPTH,size_x, size_y, size_w, size_h) rc=form_do(dialog,ROOT) form_dial(FMD_FINISH, size_x, size_y, size_w, size_h, size_x, size_y, size_w, size_h) wind_update(END_MCTRL) /* not necessary */ wind_update(END_UPDATE) When using special objects which are updated using objc_draw during the dialog you should take the objects real coordinates (e.g. with Objc_offset) as clipping area - not the area you've got from form_center. This is because the user might have moved the dialog out of the clipping area (remember MultiDialog allows to move the dialog - you get fly-dials for free!). Future Extensions ------------------- Besides bug fixing future versions might support the keyboard to operate the buttons of a dialog. In addition I'm planning to write a CPX to configure MultiDialog. I'm thinking of an english release, too. So if you're interested in an english configuration dialog, you should tell me. Distribution --------------------- MultiDialog must be spread free of any charge. Commercial distribution (e.g. on PD-collections or with commercial programs) is strictly prohibited! So spread MultiDialogs on your local mailboxes. The author makes no warranty, the entire risk is with the user. You can get new versions directly from the author (by sending a formatted disk, a self addressed enveloped and sufficient International Reply Coupons) or maybe via FTP on the german ftp-server ftp.informatik.rwth-aachen.de in the directory pub/atari/mint (may change). It is suggested that non german-users of MultiDialog donate an amount equivalent to US $10 to their local Greenpeace-organisation.