Amiga MA Magazine 1998 #3/amigamamagazinepolishissue1998.iso/bazy/amigadex/amigadex.doc

Text File | 1992-04-15 | 25KB | 539 lines

                            ----------------------
                             Amigadex Version 1.0
                            ----------------------


Copyright © 1992 Ray Lambert

    This file contains information about Version 1.0 of Amigadex.  Additional
features that have been added since this version are described in a separate
file called "Addendum.doc".  These two files together comprise the entire
documentation for Amigadex.  If you are already familiar with Amigadex, you
may want to skip this file and read just the addendum.



Legal Notices

    Amigadex is a copyrighted work and is NOT in the public domain.  The
author reserves all rights to this work.  The author assumes no
responsibility or liability for any damage or loss that may occur as a result
of using Amigadex.

    It is legal to distribute Amigadex in its original, unmodified form on
BBS's, user-club diskettes, and PD/ShareWare collections, however no fee may
be charged other than duplication or electronic transfer costs.  It is NOT
legal to distribute Amigadex in any commercial product without permission
from the author.  Permission is hereby expressly granted to Fred Fish to
distribute Amigadex as part of the Fred Fish Redistributable Software
Library.

    A short while ago, Amigadex almost became a commercial product.  As a
result a few versions of the program were distributed that actually claimed
to be commercial.  As it turned out however, Amigadex did not go commercial
-- it shall remain ShareWare, probably forever!  Therefore, those previous
notices are now invalid (as in '1984', I will deny they ever existed --
consider the past altered [grin]).  If you have a version which claims to be
commercial, or contains some copyright other than the author's, please do not
distribute it.  In fact, it should be destroyed and replaced with this newer
version.



Here's The Deal

    Amigadex is ShareWare.  You are expected to purchase this program by
registering it with the author after a review period of reasonable length, if
you intend to continue using it.  The standard ShareWare fee is $20 (US).  If
you find Amigadex useful and you have not yet registered, please do so!  Your
money buys you technical support, future revisions, and the LEGAL RIGHT to
use this copyrighted piece of software -- if you are not registered you are
using this program illegally!  In addition, your support helps ensure that
Amigadex will be kept up to date with new features/improvements, etc.  Upon
registration you will receive a copy of the latest version of Amigadex in the
mail, free of charge.  You will also be informed when new major releases are
available, and you will be eligible to receive these new releases for only
the cost of duplication and shipping.  You may also receive bug fixes by
request.  Note that future versions may not be publicly available.

    If you wish to reach the author to register Amigadex, or for any other
reason, you may do so at this address:

        Ray Lambert
        PO Box 1253
        Westport, Massachusetts  02790

    You may also call (if it's a decent hour!):

        [phone]



Overview

    Amigadex is a disk-based "address book".  It is intended to be used as a
personal data base for the names/addresses/phone numbers of all your friends
and/or business associates.  The field names are pre-set for this purpose,
however there are no restrictions as to what type of data may be placed into
each field other than the length of the data -- maximum length for each field
is 79 characters.  Amigadex may be used to maintain a small mailing list
however it may be a little limited for high-volume usage where a full-blown
data base program would be more useful.

    The Amigadex data base uses the idea of "cards" -- each entry into the
"card file" has its own separate card.  Using Amigadex, you can view and/or
edit the cards that are in your card file.  Amigadex also includes a flexible
print utility and an import function which allows data from other
applications to be easily introduced into Amigadex.  The print utility can
also write cards to a text file, permitting mail-merge type operations.
Amigadex can be operated either with the mouse or the keyboard.  Most of the
gadgets that appear will be in the shape of file cards, and will be referred
to as "card gadgets".  Most of the options available to you at any time will
be presented as card gadgets along the bottom of the Amigadex window (which
is also in the shape of a card :^) .  This is referred to as a "menu".  The
first "menu" that is available when Amigadex is run is referred to as the
"main menu".



Getting Started, The Card File

    Since the job of Amigadex is maintaining the card file, Amigadex will not
execute if there is none available.  Therefore, you must supply the name of a
card file.  If the file that you supply doesn't exist, Amigadex will create
it for you, after verifying this action with you.  There are a number of ways
to indicate which card file to use when invoking the program.  The simplest
method is to NOT indicate a card file.  When this happens, Amigadex will
display a requester asking you to enter the name of the card file you wish to
use.  The default card file name is "s:Amigadex.Cards", and this name will
appear in the requester for you to select or change.  The remaining methods
are available either only from Workbench or only from the CLI.



Getting Started, Workbench

    From the Workbench you may put the name of your card file in the "Tool
Types" field of the Amigadex icon.  You may do this by clicking once on the
gadget, and then selecting the "Info" item from the "Workbench" menu.  The
format for the icon command is: "CARDFILE=cardfilename" where "cardfilename"
is the name of your card file.  As an example, the default name would be
entered into the icon as such:

        CARDFILE=s:Amigadex.Cards

    Note that it is desirable to use a specific path to the card file because
you never know what disk directory your Amiga will be logged-into when you
invoke Amigadex.  Example:

        CARDFILE=Workbench:Amigadex/My.Cards

    Two other parameters, "SEARCHFLAGS=" and "PRINTFLAGS=", can also be
defined as Tool Types.  These will be discussed later.



Getting Started, CLI

    From the CLI you may pass the card file name on the command line when
invoking Amigadex.  Example:

        AMIGADEX S:AMIGADEX.CARDS

    This will use the card file "S:AMIGADEX.CARDS".  One additional option is
to use a text editor to create the Amigadex.Config file with the name of your
card file in it.



Amigadex.Config file

    To save you the trouble of going through the steps just mentioned to
start Amigadex (especially from the CLI), one additional method of supplying
Amigadex with the information it needs is described here.  If no card file is
specified on the command line (from the CLI) or if no card file is specified
in the icon (from Workbench) then Amigadex will attempt to find a file called
"Amigadex.Config".  It will first look in the currently logged directory for
this file.  If it doesn't find it there it will look in your "S:" directory.
(If it still can't find the file it will resort to the requester mentioned
earlier).  The config file contains the same information as the icon.  If
you're using Workbench, the only benefit you gain from using the config file
is that you can directly modify it from within Amigadex via the Config Window
(see below).  To modify the icon, you must use Workbench's "Info" menu
option.

    The config file is just a plain text file with three lines in it.  The
first line contains just the card file name, the second contains the Search
Flags (see below), and the third line contains the Print Flags (also see
below).  This file can be edited using any text editor that doesn't add any
binary characters to the file.  Amigadex will optionally create this file for
you from the Config window (see below).  An example Amigadex.Config file with
all the default information in it is as follows:

        Line #1:  S:Amigadex.Cards
        Line #2:  YYYYYYY
        Line #3:  YYYYYNN



Search Flags

    When browsing through your card file, Amigadex will allow you to enter a
Search String for selective viewing and/or printing of entries in the file.
Amigadex will search in all the fields that are indicated by the Search Flags
for the Search String that you supply.  First, a list of the available
fields...

        1. Name
        2. Address 1
        3. Address 2
        4. Address 3
        5. Address 4
        6. Phone #
        7. Comment

    From the Config window (see below) you may set/clear any of the search
flags.  You may also set the initial flags either from the Amigadex icon or
in the Amigadex.Config file.  If a flag is ON then that will tell Amigadex to
look in that field when searching.



Print Flags

    The Print Flags are very much like the Search Flags except in function.
The Print Flags indicate to Amigadex which fields should be printed in Print
Mode (see below).  For example, if you are printing mailing labels, you most
likely would not want the "Phone #" field to be printed.  You also may not
want the Comment field to be printed.  Therefore, you would clear the Print
Flags for these two items, and they would not be printed.



Setting Flags

    Search Flags may be defined in the Config Window (see below) and Print
Flags may be defined in the Print Set-up Window, (also see below) once
Amigadex is running.  If you wish to define them either within the icon or
within the Amigadex.Config file, you must understand how they are coded.  A
simple string of seven "Y" and/or "N" characters are used to define the Flags
in the icon or in the config file.  Each position in the string corresponds
to one field.  Position #1 corresponds to field #1, position #2 with field
#2, etc.  The default Search Flags are all on, and therefore the string would
look like this: "YYYYYYY" (without the quotes).  The default Print Flags
have all fields set except numbers 6 and 7 (phone # and comment).  The
resulting string would look like this: "YYYYYNN".  Within the icon, these
strings must be preceded by the commands "SEARCHFLAGS=" for the Search Flags,
and "PRINTFLAGS=" for the Print Flags.  For example, the default Flags would
be defined as such in an icon:

        SEARCHFLAGS=YYYYYYY
        PRINTFLAGS=YYYYYNN



The Card Window

    When Amigadex executes it will display a window which appears like a
giant file card.  This window is affectionately referred to as the "card
window" throughout this documentation.  At the very top of the window is a
blank area which is used for simple messages.  Below that area is the card
itself.  Within the card are the field names and a line for each field where
information contained in that field will be displayed and edited.  Below the
fields is an area which is used to display various card gadgets which give
access to Amigadex's various features.  In between the message line and the
top of the main card, and to the left of the card's "index tab", is found two
displays which will report the current card number and the total amount of
cards in the current card file at all times.



Amigadex System Gadgets

    Amigadex uses custom imagery for all its rendering in the card window,
including the normal system gadgets.  The drag gadget is in the "index tab"
of the card window and works exactly like a normal drag gadget.  The depth
gadgets are located in the upper right corner of the window, as is normal
with other windows.  They look similar to Intuition's depth gadgets, except
they contain little images of file cards.  (What?  MORE cards???  :^) From
the "main menu" a Quit card gadget is available in the lower right corner of
the window which does the job of a close gadget.

    One addition to the system gadgets is found just below the depth gadgets
in the upper right corner of the card window when the Main Menu is active.
This is an "Iconify" gadget.  It looks like a file card with a fancy letter
"I" in its center.  When clicked, it will remove the card window from the
Workbench Screen and replace it with a single tiny card which behaves similar
to a Workbench icon.  It can be dragged around the Workbench screen, and,
when double-clicked, it will disappear and replace Amigadex's card window on
the Workbench Screen.  "Iconifying" puts Amigadex "to sleep" until you need
it next.  It will also free-up about 16k of memory for usage by other
programs.



The Main Menu

    "Menus" here refers to the lower area of the card window where you will
normally find up to five card gadgets that allow you to do certain functions
within Amigadex.  The "main menu" is what you will first see once you've
gotten into Amigadex.  The options available are:

    Add
        Allows you to add a new card to the card file.  Amigadex will
        first search through the card file looking for deleted cards.
        Pressing Esc during this searching process will abort it and return
        you to the main menu.  If no deleted cards are found then a new card
        is added to the file.  Either way, you will be placed into "Edit
        Mode" (see below) to enter the information for the new card.

    Browse
        Allows you to look through and/or edit/delete cards in the card
        file.  This is referred to as "Browse Mode" (see below).

    Print
        Allows you to print the contents of cards.  This is known as
        "Print Mode" (see below).

    Config
        Allows you to define Search Flags, select a new card file
        and/or save a config file via the Config Window (see below).

    Quit
        Quits Amigadex.



Edit Mode

    Edit mode allows you enter/edit information for any card.  If you are
editing an existing card the information for that card will be placed in the
card window.  A cursor will appear on the first field and you may edit that
information.  Pressing RETURN will move the cursor down to the next field.
You may also click anywhere in any of the fields to move the cursor there.
Right-Amiga-X will clear all the text on the line where the cursor is.
Right-Amiga-Q will replace the original contents of the line as it was when
the cursor was last placed on that line.  If the cursor should disappear,
simply use your mouse to click on one of the lines and the cursor will
return.  Two card gadgets will be found on the card window at this point.

    File
        Saves the card as it appears on the screen to the current card
        file.

    Toss
        Aborts the edit process.  If changes have been made you will be
        asked to verify this operation first.



Browse Mode

    Before entering Browse Mode you will be presented with the "Enter Browse
Parameters" requester.  Two string gadgets and two card gadgets will be found
in this requester.  The string gadgets allow you to enter the card number to
begin searching at, and a Search String for selective browsing.  Leaving the
"Card Number" gadget blank will assume that you wish to start at card number
one.  Leaving the "Search String" gadget blank will display all cards in the
file.  Pressing RETURN when the cursor is in the "Search String" gadget is
the same as clicking on the "Okay" card gadget.  Clicking on the "Okay" card
gadget instructs Amigadex to begin browsing.  Clicking on the "Cancel" card
gadget tells Amigadex to forget what you just did and return you to where you
last where.  After clicking on "Okay" Amigadex will search for the first card
to display.  If it cannot find a card for whatever reason, a requester will
appear informing you that no cards where found and it will wait for you to
click on an "Okay" gadget.  When a card is found you will then enter Browse
Mode.

    When in Browse Mode you will find five card gadgets and two special
"Arrow Gadgets".  The information for the current card will be displayed in
the card window.  Amigadex allows you to enter information for each field
which may not completely fit in the card window.  The information will scroll
left-right when you type in Edit Mode.  In Browse Mode however, if you wish
to view a piece of information which doesn't quite fit on a line, you will
need to use the Arrow Gadgets.  These two gadgets are found on the left
border of the card window whenever you are in Browse Mode.  They will scroll
the card information currently being displayed left or right.  The top gadget
scrolls right, and the bottom gadget scrolls left.  The imagery will remind
you which is which.  The five card gadgets are as follows:

    Next
        Moves forward through the card file.  The search information
        you specified is used to continue the search to show you the next
        card in the file.  When the end of the card file is reached Amigadex
        will re-position to the beginning of the card file.

    Last
        Moves backwards through the card file.  The search information
        you specified is used to continue the search to show you the
        previous card in the file.  When the beginning of the file is
        reached Amigadex will re-position to the end of the card file.

    Edit
        Enters Edit Mode (see above) to allow you to edit the current card.

    Delete
        Used to delete the current card.  You will always be asked to
        verify this action.

    Done
        Exits Browse Mode and returns to the main menu.

    One additional gadget is available in Browse Mode which is invisible.
This invisible gadget is located on the Card Number which is displayed on the
top of the card window (under the message line).  Clicking on the card number
will bring-up the "Enter Browse Parameters" requester to allow you to either
jump to another card in the file, change your Search String, or both.



Print Mode

    Print Mode is where you will be allowed to print the contents of cards in
your card file.  The "Print Set-up Window" allows you to enter all the
information you will need to configure the printing process, and you will
always see the set-up window when you click on the "Print" card gadget from
the main menu.  There are two modes of printing available, "normal" and
"continuous," which are explained below.



Print Mode, The Print Set-up Window

    This window is separate from the card window, with normal system gadgets,
etc.  The information is arranged in two columns within the window.  On the
left is a series of toggle gadgets which allow you to set/clear the Print
Flags.  These toggle gadgets appear as three-dimensional cubes.  When they
are selected (turned on) a check-mark will appear inside the cube.  Alongside
the toggle gadgets is text which identifies which field each gadget
represents.  All fields which are selected here (when the cube contains a
check-mark) will be printed on your labels, etc.  The ones that are not
checked, will not appear in the printed output.  The status of the Print
Flags may be saved to your "Amigadex.Config" file from the Config Window (see
below).

    The right column contains several string gadgets that allow you to set
search parameters, media size and output device.  The search parameters that
you enter here work exactly like those set in Browse Mode.  The media size
parameters are specified in character positions.  The "Media Height"
parameter is of most use when printing labels as it allows Amigadex to
calculate how many lines to insert between labels in order to advance
properly to the next label.  Your Media Height must be large enough to fit
all the fields that you select to print.  The "Media Width" parameter is used
to truncate any lines of text that are too long to fit on the media.  The
default values for the Media size parameters are suitable for standard size
mailing labels at six lines per inch using a ten point font (normal printer
defaults).

    The "Output Device" is where the printed output will be sent to.  This
can be any valid AmigaDOS device.  The default device is "PRT:", your
Preferences printer.  It could also be a file in case you need to write the
contents of some of your cards to a text file to import the information into
another program; a mail-merge for instance.

    Below the "Output Device" string gadget you will find another toggle
gadget with the words "Continuous Mode" beside it.  When this item is
checked, printing will take place in "Continuous Mode" (see below),
otherwise, printing will be done in "Normal Mode" (also see below).

    Finally, there are two card gadgets on the bottom of column two of the
set-up window.  The "Okay" card gadget will accept all the input in the
set-up window and begin the actual printing activity.  The "Cancel" card
gadget will exit the set-up window and return you to the main menu, aborting
the print operation.



Print Mode, Normal Mode

    The Normal Printing mode is very much like the Browse Mode (described
above).  All the gadgets and options that are available in Browse Mode are
available in this mode, with the exception of the "Edit" and "Delete"
options, and one additional card gadget for printing.  The "Print" card
gadget will send the currently displayed card to the Output Device that you
specified in the set-up window.  This approach to printing gives you full
control over which cards get printed.  You may browse through your card file
and print only the cards that you wish.  When you are done, click on the
"Done" gadget.



Print Mode, Continuous Mode

    Continuous Mode allows Amigadex to quickly print a large batch of cards
with as little intervention from you as possible.  All cards which are found
to match the Search String that you specify in the set-up window will be sent
to the Output Device.  Note that the Search Flags that you define in the
Config Window (see below) or that you set either in the Amigadex icon or in
the Amigadex.Config file will determine which fields are examined for the
Search String; just as in Browse Mode.  While printing is taking place in
this mode, two card gadgets are available for you to click on:

    Pause
        This will suspend the printing process until further instructions
        are given by you via a "pause requester", which will appear after
        clicking "Pause".  The "pause requester" will contain two card
        gadgets to click on:

            Okay
                Resumes the printing process exactly where it left off.

            Cancel
                Aborts the printing process and returns you to the main menu.

    Done
        This will abort the printing process and return you to the main menu.



The Config Window

    This window is a separate window like the Print Set-up Window.  It will
allow you to set the Search Flags and to change the card file that you are
working with.  It will also allow you to save this information in an
Amigadex.Config file.  Two columns of information will be presented to you.
The left column will appear almost exactly like the left column of the Print
Set-up Window (described above).  A series of toggle gadgets, each one
representing a field, will be displayed with the field name to the right of
the toggle gadget.  When the gadget is toggled on, searching in that field is
enabled.

    The right column contains a single string gadget and three card gadgets.
The string gadget is used to enter the name of the card file that you wish to
work with.  The name of the card file that you are currently working with
will be displayed by default.  Below this string gadget are the three card
gadgets:

    Save
        This option will attempt to create an Amigadex.Config file.  Saved
        within the Config file will be the name of the card file which is
        displayed in the Card File string gadget, and the current state of
        the Search Flags as well as the current state of the Print Flags.
        This information will be used the next time you start-up Amigadex,
        assuming that you save it properly.  A simple file requester will be
        displayed before Amigadex actually tries to write the Config file
        out.  This requester will allow you to change the file name that
        Amigadex will use to save the file.  Note however, as described
        above, when Amigadex runs it will only look for a file called
        "Amigadex.Config", first in the current directory, and then in the S:
        directory if not found in the current directory.  After saving the
        Config file, the information you defined in the Config Window will be
        used by Amigadex to continue its operation.  It will try to access
        the new card file that you enter (if you did so), and will prompt you
        to create the new card file if it doesn't already exist.

    Use
        Puts the newly defined configuration information into use as
        described above, but will not attempt to save it to a config file
        first.

    Cancel
        Cancels any changes you made to the configuration information.  If
        you actually have made changes you will be asked to verify the
        operation.

    All three of the above options will close the Config Window and return
you to the main menu.