                MultiDialog (GEM-Dialogs in Windows)
             =========================================

Copyright (c) 1992-93 Helmut Neukirchen
                      Bnnersdyk 63
                      D-47803 Krefeld
                      Germany
              e-mail: hn@pool.informatik.rwth-aachen.de

All rights reserved.



       Short english manual for MultiDialog >=V1.03 (12/21/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). 
MultiDialog does not work with Mag!X 2.XX. I don't have reports about
Geneva, so please tell me if they work together!



 Installation
--------------

MultiDialog can be installed in two ways, because it can be 
started as a GEM-Applikation or as an AUTO-folder TOS-program
(ACC not supported anymore!) Configure MultiDialog via XCONTROL
and the MULTDIAL.CPX module.

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.)

2. Copy MULTDIAL.CPX in your XCONTROL CPX path.

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.

MultiDialogs supports keyboard shortcuts, now. In order to use them
you've to install the program Let'em Fly (LETEMFLY.PRG), too.
I suggest to use versions >=1.20 of Let'em Fly; copy it just in
front of MultiDialog into the AUTO-folder.


 Configuring MultiDialog
-------------------------

You can configure MultiDialog using a CPX module. To do so you 
should have MULTDIAL.CPX in your CPX path installed and choose the 
entry "MultiDialog" from XCONTROL's scroll list.
(If MultiDialog wasn't installed you will have to start MULTDIAL.PRG now
in order to install MultiDialog.)

A CPX dialog should appear now. (With non-german XCONTROL the messages should
be in english. Please inform me if they are not!)

In the first line the version-number of the installed MultiDialog is displayed.

- On the right side there is a popup-menu with the possible selections 
  "On"/"Off". When "On" is selected this means that MultiDialog does 
  interfere in the AES-calls to handle dialogs. When " Off " 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: Always/Center/Mouse/Corner" 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, just at the 
  mouse-pointers position or in the center of the screen. The options
  "Center", "Corner" and "Mouse" 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 "Always" 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 "Always"-button, it's the most 
compatible.

- The next line "FormDial: Window/Normal" tells MultiDialog wether to
  put a dialog at a form_dial-call in a window or not. This is the
  best time to redirect a dialog, but it works only with programs which 
  use FormDial calls. 

- "FormDo: Window/Normal" Putting dialogs at a form_do in a window 
  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.

- "FormAlert: Window/Normal" 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...).

 
- "ObjcDraw on FormDo: Yes/No" tells MultiDialog how to handle the problem 
  which was mentioned at the end of the "FormDo" explanation. You can choose 
  whether to repaint the dialog or not. "Yes" 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 "No".

- With the option "Window titles: Yes/No" you can choose between
  dialog-windows with or without a titlebar. In order to move a dialog-window 
  without a titlebar you have to click at the background of the dialogbox 
  and drag it around.
  
- "Shortcut: Yes/No" If a MultiDialog which supports keyboard shortcuts
  is installed you may deactivate them with this switch.
  (At the moment shortcuts are only available if you have installed
  Let'em Fly and MultiDialog.)


Because some programs need other configurations than other 
programs you can tell MultiDialog to take for specific 
applications specific configurations - MultiDialog switches 
automatically.

- The "New"-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 the popup on the left side of the "New" button (probably named
  "Default") 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 "Delete"-button which deletes the entry which is 
  visible at the moment. (You can't delete the "Default" entry!)

- The "Save" 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. "Cancel" 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 select the popup on the left side of "New" 
  (or "New", "Delete") the changes for that entry are updated at once.)

- Furthermore the "Info" button displays a help page where you'll find
  a summary of this manual.
  

 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: <app_name> " (where <app_name> 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: <app_name> " (only
if window-titles are activated).


 Keyboard shortcuts
--------------------

At the moment accelerator-keys are implemented using Oliver Scheel's
AES enhancer Let'em Fly. So you have to install Let'em Fly, too.

Let'em Fly is - similar to MultiDialog - FreeWare and available at least
on german ftp-servers (search for ltmf*.*). Refer the LTMF documentation
for copy conditions and further information.
Though MultiDialog switches Let'em fly automatically of, you'd better
switch Let'em fly manually of and save this setting!

A dialog which supports shortcuts has additional marks on the accelerator
key (depending on the Let'em Fly setting an underlined letter or the letter 
is printed in a different color).
You may use the shortcut letter while pressing the ALTERNATE key to
simulate a press on the according button. (When there's no editabe text field
in the dialog you won't need the ALTERNATE key. Alertboxes support the
function keys F1-F3, too.)
Buttons named "Cancel", "Abort", etc. are mapped to the UNDO key, "Help"
buttons on the HELP key.

You can only use accelerator keys for dialogs which are displayed in the 
top window just as they are only redrawn if they are in the top window.


 Known Bugs/Restrictions
-------------------------

In the past I didn't know any bugs which really cause a crash, most were 
just restrictions. But now, I know at least 2 real problems:

- The multitasking-enhancement Mag!X 2.XX does not work with MultiDialog.

- Some programm which don't call appl_init may irritate MultiDialog.

Now, the smaller bugs:

- 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.)

  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 choose "FormDial: Normal" and use instead 
  "FormDo: Windosw" 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.

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 global MultiDialog "On/Off"-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 (due to a bug V1.02 appears as V1.01):
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) /* now suggested */
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) /* now suggested */
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!).


Remember: any program, which uses the AES, has to call appl_init first!
Otherwise MultiDialog does not catch their calls.
Because there are a lot of CPX-modules which don't call appl_init
(MultiDialog ignores them) here's ATARI's example CPX initialization:

CPXINFO
*cpx_init( Xcpb )
XCPB *Xcpb;
{
    xcpb = Xcpb;
    
    appl_init(); /* Important! */
        
    if( xcpb->booting )
    {
       ...


In contrast to the original AES, MultiDialog needs space on the user-stack.
Be sure to provide ca. 0.5 KB free stack before calling AES-functions.


 Future Extensions
-------------------

A Programmers Interface is in development (see the german document
PROG_GER.TXT).
I want to support the MTOS new window facilities, too.
There is a demand for a TOS-like look of alert-boxes.
I'm thinking on a VSCR support, too. 
MultiDialog and Let'em Fly might melt together.
It is possible that MultiDialog provides an online-help in dialogs
for other applications.

 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.

Credits:
            Andreas Alich, Dieter Fiebelkorn, Filipe Martins,
              Olaf Mootz, Oliver Scheel, Oliver Schildmann
