                        FormDoIt! (Version 1.2)
                             by Dan Wilga

        Copyright  1991, Gribnif Software.  All Rights Reserved.

This program may be distributed without charge, provided that this text
file is present and that it and the program files are unmodified.


Overview
--------

  The FormDoIt! program replaces the parts of the GEM environment that
  handles the standard dialog and alert boxes that appear in most Atari
  programs.  Enhancements that FormDoIt! offers include:

  o Keyboard Equivalents for dialog and alert box buttons.
  o [Undo] key to exit dialog and alert boxes.
  o Enhanced editable text fields.
  o Ability to insert extended characters into editable text fields.
  o Editable alert box icons.
  o Control over the default exit button in alerts and dialogs.


Included Files
--------------

  This archive should include the following files:

    1.  FORMDOIT.PRG  - The FormDoIt! utility.
    2.  FORMDOIT.TXT  - The file you are reading now.

    3.  ENGLISH .UND  - Sample English [Undo] keywords.
    4.  GERMAN  .UND  - Sample German [Undo] keywords.
    5.  DEFAULT .BL3  - FormDoIt! default alert box icons.
    6.  BORING  .BL3  - Original system alert box icons.
    7.  INVERSE .BL3  - Inverse version of original system alert box icons.


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

  Place the FORMDOIT.PRG in your system's AUTO folder.  Optionally, you
  can also install it by running it from the desktop of your choice.


Enhancements
------------

  Default Button
  --------------

    Normally, if you press the [Return] key while in a dialog or alert box,
    the "default" exit button is selected.  This button can usually be
    identified by its extra thick border.

    With FormDoIt! you can change which of the exit buttons is considered
    the default by holding down the [Alternate] key and pressing the [Tab]
    key.  When you do this, you should see the thick border move from one
    exit button to the next.

    This change is not permanent, many programs will automatically return
    the default button back once you exit that dialog or alert box.

  Exit Button
  -----------

    When using FormDoIt!, if you press the [Undo] key, the first button
    found that contains the word "Cancel", "Quit", "Exit", "Abort", or "No"
    will be selected.

    Since all buttons in a dialog and alert box are in an internal order,
    it will choose the button that makes the first match (even if there is
    more than one button with a string that matches).

    You can change the strings used by FormDoIt! for this feature by
    creating a file called FORMDOIT.UND.  If FormDoIt! finds this file when
    it first runs (in the same directory it was run from), the file
    contents are used instead of the previous mentioned strings.  The file
    is a simple text file with each button string on a line by itself.
    There should be no empty lines in the file, and the carriage return
    should immediately follow the last letter of each line.  The included
    GERMAN.UND file can be renamed to FORMDOIT.UND if you happen to use
    German programs.  If you wish to create your own custom FORMDOIT.UND
    file, you can use the ENGLISH.UND as a guide.

  Buttons
  -------

    FormDoIt! provides keyboard equivalents for all the other buttons in a
    dialog or alert box.  FormDoIt! scans all the buttons in the dialog box
    and assigns each one a unique keyboard equivalent.  When the dialog box
    appears, it will look slightly different because there will be short
    lines underneath characters in most of the buttons.  If you hold down
    the [Alternate] key and press the character that is underlined, that
    button will be selected.  Up to 20 buttons in a dialog can have
    [Alternate] key assignments.

    The method for choosing which letter to assign to a specific button is
    rather simple.  FormDoIt! scans all the buttons in order and looks for
    the first unique character (that has not been used before) in that
    button.  Once it finds it, it assigns it that key and underlines the
    letter.  If a button has no unique characters (because they all were
    already used in the dialog box) then it will not receive a keyboard
    equivalent.  The scanning is done following the internal order of all
    the dialog box buttons.

    If you don't like the "underline" keyboard equivalents, you can turn
    this feature off.  This is done by holding down both [Shift] keys and
    pressing the [Backspace] key.  You will hear a short sound effect
    indicating your selection.  Pressing these keys again will turn the 
    "underline" keyboard equivalents back on.

    See the "Configuration Options" section for more information on how to
    more permanently turn this feature on or off.
    
    Some dialog boxes will look odd if these underscores are not undrawn
    before control returns to the program that called FormDoIt. If this is
    a concern, you can permanently configure FormDoIt to always undraw the
    underscores. See the "Configuration Options" section.

  Alert Boxes
  -----------

    With FormDoIt! you can define what the standard alert box icons (stop
    sign, question mark, and exclamation mark) look like.  Once you use
    FormDoIt! you will see that it changes these (I got bored of the same
    old ones).

    If FormDoIt! finds a file called FORMDOIT.BL3 at bootup, the icons
    contained in that file are used in place of the default ones inside of
    FormDoIt!.  Included with this program are three files:

    BORING .BL3 - These are the old standard GEM alert box icons.
    DEFAULT.BL3 - These are the defaults FormDoIt! normally uses.
    INVERSE.BL3 - These are an inverse version of DEFAULT.BL3.

    The .BL3 files are in Degas Elite block format.  They can be edited and
    re-saved using Degas Elite.  If you edit them, you must be very careful
    to make sure that the new file you save is a block that is exactly
    32x96.  The "Snap" feature in Degas is helpful for this purpose.

  Editable Text Fields
  --------------------

    An editable text field is a string within a dialog box that has a
    vertical line cursor so that you can modify it with the keyboard.
    FormDoIt! emulates the normal GEM dialog text field functions:

      o The [Tab] and down-arrow keys move to the next editable field.
      o The up-arrow key moves to the previous editable field.
      o The left and right-arrow keys move the cursor within a field.
      o The [Esc] key clears an editable field.
      o The [Backspace] and [Delete] keys delete characters before and
        after the cursor.
      o The mouse can be used to select an editable field.

    It also adds a number of extensions:

      o [Tab] and down-arrow will move the cursor to the first editable
        field in a dialog box if it is already at the last one.
      o Up-arrow will also wrap, from the first field to the last.
      o [Shift] left-arrow will move the cursor to the leftmost character,
        and [Shift] right-arrow will move all the way to the right.
      o If there is no default button in a dialog box, the [Return] key
        will advance the cursor to the next editable field.
      o The mouse will position the cursor to the character closest to
        where the mouse button was pressed, not just to the end of the
        line.

    It also lets you enter extended (non-keyboard) characters (note that
    not every character is valid for all text fields and may be ignored):

      1.  Press the [Insert] key.  This opens a box that contains the
          entire character set.  Click with the mouse on the character to
          use.  You can click anywhere outside the box or press a key to
          remove the box if you decide not to use it.

      2.  If you know the ASCII value of a particular character, you can
          hold down the [Alternate] key and type it, in decimal, using the
          keypad.  A character is generated as soon as the [Alternate] key
          is released or three digits have been pressed.  For example, to
          enter an "A" (ASCII 65), you would do the following:
            Hold down the [Alternate] key
            Press 6 on the keypad
            Press 5 on the keypad
            Release the [Alternate] key

    It also evades a system bug:

      o If you have TOS 1.0, you may have run into the "underscore bug".
        Typing an underscore ("_") character with certain types of editable
        fields would cause GEM to crash.

        FormDoIt! prevents this crash from happening.  If you type an
        underscore by accident, FormDoIt! will ignore it.


Configuration Options
---------------------

  To temporarily disable FormDoIt!, hold down both [Shift] keys while
  pressing the [Delete] key.  A sound effect will indicate your selection.
  FormDoIt! will become disabled until you re-activate it or reboot.  To
  turn FormDoIt! back on, press the same keys again.

  To temporarily disable the "underline" keyboard equivalents, hold down
  both [Shift] keys while pressing the [Backspace] key.  A sound effect
  will indicate your selection.  To turn the "underline" keyboard
  equivalents back on, press the same keys again.

  A more permanent way of setting these options is to run FORMDOIT.PRG from
  the desktop.  When it is loaded this way, you will see an option labeled
  "Configure".  Using this button you can set the two options described
  above, and one additional option, called "Undraw Underscores". If this
  option is "On", then FormDoIt will always undraw any underscores it puts
  in buttons before returning control to the program. Some dialogs look
  better with this option on, but some dialogs will be a bit slower. If you
  start seeing lots of underscores appearing in one button of a dialog, you
  may want to try turing this option on.

  The "Save" button will save your selection inside the FORMDOIT.PRG.  The
  "Set" option will set the options without saving them.  Changes do not
  take effect until you exit the configuration dialog box.

  If you have already run FORMDOIT.PRG once (say, for instance, in your AUTO
  folder), then the options will be saved to that copy. Otherwise, they will
  be saved within the copy you are currently running.


Compatibility
-------------

  While every effort has been made to assure that this program works with
  other programs, there are a few things worth mentioning:

  o Some programs use their own dialog and alert box manager and therefore
    will not benefit from FormDoIt!.  Examples of this are Tempus II,
    K-Resource, WordPerfect, and SuperBase.

  o Some programs only use their own dialog and alert box manager part of
    the time, and therefore still benefit from FormDoIt! within some of
    their dialog boxes.  The best example of this is GEnie's Aladdin.

  o Universal Item Selector's (UIS III) own keyboard equivalents prevent the
    [Undo] feature in FormDoIt! from working.

  o FormDoIt! has stricter error checking for alert boxes than GEM has.
    Consequently, you may find one or two programs which use more than 30
    characters per line in the alert text or more than 10 characters in a
    button.  For these, FormDoIt! will chop off the remainder (unlike GEM,
    which can produce some very odd looking alerts!).


Programmer Notes
----------------

  You can disable FormDoIt! so that it will not process some dialog boxes
  that a program uses.  This, however, is something that should be set up
  by the author of the program, as this entails modifying data in the
  resource file for a program.

  In the OBJECT structure, the element ob_type is a word, however only the
  lower 8 bits are looked at by GEM.  For this reason, one can use the
  upper eight bits as one sees fit.  If the root object of a tree contains
  the constant 113 ($71) in the upper nybble of the ob_type word, then the
  regular GEM form_do() will be used.  Alternately, any objects within a
  tree whose ob_type field contains this value will not have an "underline"
  keyboard equivalent assigned to them.


Version Changes
---------------

  1.2:  Works with keyboard equivalents in CodeKeys and MaxiFile.
        Works with right mouse button presses in MaxiFile.
        Does not need to be disabled to record a CodeKeys macro.
        Removed the UIS hack; should work with all versions of UIS, even II.
        Undo strings work with buttons that have leading or trailing spaces.
        Added Undraw Underscores option.
  1.1a: Fixed a very rare bug that could cause certain alerts not to be
            processed.
        Control key handling has been changed so that, among other things,
            Control-M, Control-I, and Control-Return produce extended
            characters as they should.
        Response time for TOUCHEXIT objects has been improved. This is
            expecially noticeable for things like scroll bars in UIS.
        Objects that are SELECTED and EXIT but not SELECTABLE are handled
            correctly.
  1.1:  The "No" string was added to the [Undo] key.
        Shift-shift-backspace to disable underlines.
        Running it a second time in the AUTO folder has no effect.
        The configuration can be changed and saved.
        Opening a folder for the first time in UIS 3.0 should work.
        Added the ob_type flags for disabling.
        Added Alternate-Tab for swithching default button.
        Saved some code by always running in supervisor mode.
        Sped up mose clicking for objects that are not TOUCHEXIT.
        Can be compressed using DC Squish.
  1.0b: Objects that are SELECTABLE but not EXIT are handled correctly.
        Objects that are SELECTABLE and TOUCHEXIT are handled correctly.
        Will not crash programs that make AES calls in supervisor
            mode (like HotWire)
        As many brackets in an alert string as possible are ignored.
  1.0a: Fixed a bug that could cause GDOS detection code to crash.


About "Colaware":
----------------

  You've heard of public domain, you've heard of shareware. This program,
  however, is Colaware:  if you like it, you are encouraged (though not
  necessarily required) to send copious quantities of highly caffeinated
  beverages (Coke, Pepsi, Jolt, etc.) to the address below (via U.S. Mail,
  please; UPS won't deliver to a P.O. Box) so that I can continue to create
  more products like this one.  Coupons are accepted.

    Gribnif Software
    P.O. Box 350
    Hadley, MA  01035
    
  Internet:  Dan.Wilga@saturn.ucc.umass.edu
  GEnie:     GRIBNIF


If you like this program, you might want to take a look at some of our 
commercial products:


  NeoDesk 3 - The Ultimate Desktop
  ================================

    NeoDesk 3 is the most powerful, complete, and easy to use graphical
    desktop available for the Atari ST/TT.  Not only does it make your
    computer easier to use but it adds a very complete series of new
    features and enhancements.  These include improved file operations,
    custom icons, icon editor, desktop icons, desktop notes, independent
    custom windows, macros, keyboard equivalents, and much much more!!  The
    package a 150 page manual.  A free demo version is available from GEnie
    or your local BBS.

  NeoDesk CLI
  ===========

    The NeoDesk CLI is a complete add-on command line interpreter for the
    NeoDesk 3 desktop replacement package.  It runs out of its own GEM
    window and includes a very complete batch programming language.  This
    allows for such things as the creation of powerful batch files which
    let you automate your computer.  The NeoDesk CLI uses both MS-DOS and
    UNIX style commands to simplify its use.  The package includes a 70
    page manual.  A free demo version is also available.

  You can order these products by calling our toll free order line (USA,
  Canada, Hawaii, PR, and Alaska only): (800) 284-4742 (orders only!)

  You can also order by sending us the correct amount from the chart below
  to: Gribnif Software, P.O. Box 350, Hadley, MA 01035:

    NeoDesk 3........................................$69.95 ___________

    NeoDesk CLI......................................$29.95 ___________

    Shipping (USA: $2.00 / Canada: $3.00 / Foreign: $5.00)  ___________

  If you have any questions or comments, you can call us at (413) 584-7887.
  You can also fax us at (413) 584-2565.

