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

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

All rights reserved.



       Short english manual for MultiDialog >=V1.00 (4/4/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 or Magix). (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 want 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 MULTIDIAL.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)).


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 " Lschen "-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. This
window has 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 (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> ".



 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. In this case the
  menu title remains inverted and there is no reaction, 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!)

  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). If available it installs a cookie ("MDIA"),
too.
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)
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)
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 ftp-server
ftp.informatik.rwth-aachen.de (Germany).

It is suggested that non german-users of MultiDialog donate an amount
equivalent to US $10 to their local Greenpeace-organisation.

