Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/199.lha/GimmeLib/GIMMELIB.DOC

Text File | 1988-12-27 | 8KB | 161 lines

GIMMELIB.DOC        gimme.lib        Jan Sven Trabandt
            V1.2   31-Oct-88        {utgpu,utzoo,lsuc}!oscvax!jan

gimme.lib V1.2 (C)CopyRight 1988, Jan Sven Trabandt. All Rights Reserved.
This software may not be distributed for profit; in other words, it is
freely redistributable except that it may not be incorporated as part of any
commercial software package without my express written consent.

What is this thing??
Gimme.lib is a general purpose library of handy-dandy flexible support routines
that allow dynamic creation of intuition structures such as windows, gadgets
and screens (including double-buffering and dual playfields), quick and easy
use of the timer.device, spawning subtasks, simple IFF ILBM and 8SVX routines,
memory chaining and more...
There are currently over 100 functions.
The source to the library may be instructional in demonstrating how some aspects
of the Amiga are used (especially Intuition structures).

The include files should be located in the gimmelib subdirectory of your normal
include directory.
The functions are prototyped in gimmelib/gimmefuncs.h for quick reference and
correct use of the functions.
Documentation (similar to "man" pages) for each function is catenated together
in the DOCS file, grouped by source file; to find a function in it, search for
the function name catenated with an opening bracket, such as "gimmeBitMap(",
to find either the function's synopsis line or the start of the actual function
[this is useful since the function name "gimmeBitMap" can be referenced in many
places in the DOCS file].

Some general notes regarding gimme.lib:

0 - This library was made using Manx C V3.6a,
    and should work with Lattice with little or no modification (hopefully).
    Using a pre-compiled include file is highly recommended.

1 - Gimme.lib is almost entirely reentrant, with the following known exceptions:
    dbufvquick.c :    makeDBufVQuick(), unmakeDBufVQuick(), swapDBufVQuick()
        These routines manipulate copper lists for maximum speed
        using global copper list variables.
    requester.c  :    gimmeAutoRequest()
        This routine has default text for the yes/no gadgets which can be
        altered via global variables; if these are not changed, then the
        routine is re-entrant.
    stdstuff.c   :    gimmeStdStuff(), getRidOfStdStuff()
        These routines are primarily for a mainline and are not reentrant
        for multiple subtasks.

2 - Gimme.lib routines do not write to a CLI window or stdout, so they can be
    safely used from subtasks that have no output file associated with them.
    Known exception: gimmePicture() and gimmeSound(), which test Output()
    before doing a Write() in the case of an error.

3 - Gimme.lib routine names follow this naming convention:
    start with a lower-case letter
    each distinct "word" in the name starts with an upper-case letter,
        except for the first "word"
    underscores (_) are not used
    examples:   gimmeStringGadget, getRidOfScreen
    also, global variables start with "gim" and follow the same conventions
        as routine names.
    Exception: communic.c, where the routine names begin with c_
    for example: c_getc(), c_open().

4 - Gimme.lib routines which return a short generally return non-zero on error,
    sometimes returning different non-zero values as different error codes.

5 - Gimme.lib routines almost always take SHORTs instead of LONGs, with these
    known notable exceptions:
    flags, which are ULONGs
    size parameters passed to gimmeMessage(), chainAllocMem() and
        gimmeSubTask
    unit parameter to the time functions, as well as the (micro) second
        parameters to timeDelay() and timeDelayAsync()
    "num" pararameter in positionText()
    However, if you use 32-bit ints, you shouldn't have to typecast to a short
    as the short would be promoted to an int anyways.

6 - Specialized flags for gimme.lib routines are usually of the form
    GIM_YYY or GXX_YYY where XX denotes a 2-letter shortform for a routine
    name and YYY denotes the particular flag. For example:
    GIM_MINTERM_COPY    - general purpose copy minterm
    GPT_XCENTRE        - x-centre flag for gimmePositionText(), hence GPT

7 - Most of the gimmeXXX() routines have a corresponding getRidOfXXX() routine
    to undo the effect or deallocate memory resulting from the former routine.
    If no such getRidOfXXX() routine exists, then most likely the effects of
    the gimmeXXX() will be undone by another routine which you may have to call
    yourself -- this is most evident in the case of memory chaining.
    For example, gimmeImage() chains its memory to a given memory-chain, which
    you must free with chainFreeMem() at some point, or if you linked the image
    memory into a gadget, then getRidOfGadget() will free the image memory along
    with the rest of the gadget's memory.

8 - The gimme.lib routines do NOT, in general, check for NULL pointers in
    parameters before using them, unless the docs specifically say that NULL
    can be used as a default. However, gimme.lib can be recompiled using the
    GIMME_WIMPY option which will check with brute-force that pointers are
    non-NULL before using them.
    Important exceptions: memchain.c routines always check because it is so
    important, and menu.c routines check to make user coding easier.

9 - Since several routines are grouped together in modules, your program may
    link in more routines than it needs, so don't count on having the absolute
    smallest code possible when using gimme.lib routines...
    it's the price you pay for quick prototyping capabilities.

10- There are different versions of gimme.lib for different options:
    gimme.lib    - 16-bit int, small code/data
    gimme32.lib    - 32-bit int, small code/data
    NOTE: all the code was written for safe 16-bit use (and hence 32-bit too).
    You should be able to recompile it using large code options as well.

11- NO floating-point operations of any kind are used.
    malloc() and free() are NOT used.
    NO "int"s are used.

12- Many of the routines use my memory-chaining routines [chainAllocMem(),
    chainFreeMem(), etc.]. You may wish to look at them carefully.
    In particular, some routines such as for gadgets and windows use the
    existing structure's UserData field for its own use -- for gadgets,
    it is a memory-chain pointer which includes the gadget's structure itself.



Major Changes (in reverse chronological order)

V1.2    31-Oct-88
-----------------
    1    gadget.c: addGadgets() and removeGadgets() removed due to duplication
            of existing RKM1.2 functions AddGList() and RemoveGList().
          clearGadgets(): order of parameters changed to more closely
            resemble RefreshGadgets(), ie. gadget first, then window.
    2    font.c: gimmeFontQuick() added.
    3    graph.c: new routines for graphing added.
    4    inputhand.c: new routines to add/remove an input handler added.
    5    menu.c, menustuff.c: new routines for menus
    6    copystuff.c: new routines plus some moved from intuistuff.c,
              to copy intuition-type structure lists.
    7    communic.c: new routines for serial port


V1.1    30-Sep-88
-----------------
    1    font.c: gimmeFont now alters the TextAttr to reflect the actual
            characteristics of the font found.
    2    gadget.c: gadget routines enhanced and some split to gadgstuff.c
          getRidOfGadget() renamed to getRidOfGadgets()
          clearGadget() renamed to clearGadgets()
          added removeGadgets().
    3    postext.c: changed "num" parm in positionText() to a LONG,
            vertical text option added.
    4    stdstuff.c: new routines for opening/closing standard libraries
            and devices added.


V1.0    31-Aug-88
-----------------
    1    first reasonable release version