page@swan.ulowell.edu (Bob Page) (12/02/88)
Submitted-by: oscvax!jan@uunet.UU.NET (Jan Sven Trabandt)
Posting-number: Volume 2, Issue 74
Archive-name: libraries/gimme.1
Gimme.lib is a bunch of routines I've grouped together over the year
and is particularly useful for dealing with Intuition structures as
well as some devices. It's a (Manx) library to be linked in to a
program.
Look at the file "gimmefuncs.h" to see the function prototypes
for the whole kit-and-kaboodle (there are around 120 functions).
# This is a shell archive.
# Remove everything above and including the cut line.
# Then run the rest of the file through sh.
#----cut here-----cut here-----cut here-----cut here----#
#!/bin/sh
# shar: Shell Archiver
# Run the following text with /bin/sh to create:
# DOCS.part1
# This archive created: Thu Dec 1 19:44:20 1988
cat << \SHAR_EOF > DOCS.part1
/*
* NAME: gimmeBitMap
*
* SYNOPSIS: bm = gimmeBitMap( depth, width, height );
* struct BitMap *bm;
*
* INPUTS: SHORT depth; number of required bitplanes
* SHORT width; number of columns wide in pixels
* SHORT height; number of rows high in pixels
*
* DESCRIPTION: Allocate and initialize/clear a BitMap struct.
* If the depth, width and height parameters are strictly positive,
* the required bit-planesare allocated as well, and the BitMap
* is properly initialized,
* otherwise the BitMap is cleared.
*
* RESULTS: Returns pointer to a BitMap, or NULL if anything went wrong.
*
* SEE ALSO: getRidOfBitMap
*/
/*
* NAME: getRidOfBitMap
*
* SYNOPSIS: err = getRidOfBitMap( bitmap );
* short err;
*
* INPUTS: struct BitMap *bitmap; pointer to initialized bitmap
*
* DESCRIPTION: Deallocate memory for a bitmap, including bitplanes.
* Number of bitplanes determined from bitmap.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: gimmeBitMap
*/
/*
* NAME: gimmeBitPlanes
*
* SYNOPSIS: flags = gimmeBitPlanes( bm, myflags );
* ULONG flags;
*
* INPUTS: struct BitMap *bm; ptr to initialized BitMap
* ULONG myflags; flags for routine
*
* DESCRIPTION: Allocate bit-plane(s) given an initialized BitMap struct,
* according to the flags:
* - contiguous - all planes allocated contiguously,
* as required for Image data
* - separate - all planes allocated individually
* - default - try contiguous first, then separate
*
* Note: the "initialized" BitMap struct should not have any
* planes allocated for it prior to this call, as the plane
* pointers are stored in the BitMap's Planes[] field.
*
* RESULTS: Returns actual flags used.
* Check if bm->Planes[0] is non-NULL to see if successfull,
* or if the returned flags equals the error flag defined in
* bitplane.h
*
* SEE ALSO: getRidOfBitPlanes
*/
/*
* NAME: getRidOfBitPlanes
*
* SYNOPSIS: err = getRidOfBitPlanes( bitmap, myflags );
* short err;
*
* INPUTS: struct BitMap *bitmap; pointer to initialized bitmap
* ULONG myflags; flags for routine
*
* DESCRIPTION: Deallocate memory for a bitmap's bitplanes.
* Number of bitplanes determined from bitmap.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: gimmeBitPlanes
*/
/*
* NAME: getDefaultColors
*
* SYNOPSIS: colortable = getDefaultColors();
* USHORT *colortable;
*
* DESCRIPTION: Get pointer to the default color table.
*
* RESULTS: Returns pointer to the default color table,
* or NULL if there is none.
*/
/*
* NAME: setColors
*
* SYNOPSIS: error = setColors( screen, colortable, colors );
* short error;
*
* INPUTS: struct Screen *screen; pointer to Intuition screen
* USHORT *colortable; or use NULL for default color table
* SHORT colors; number of colors to set
*
* DESCRIPTION: Set the colors of an Intuition screen.
*
* RESULTS: Returns non-zero on error (eg. if default color table
* requested but not large enough).
*/
/*
* NAME: checkColors
*
* SYNOPSIS: err = checkColors( screen, colors );
* short err;
*
* INPUTS: struct Screen *screen; pointer to Intuition screen
* SHORT colors; number of colors to check
*
* DESCRIPTION: Check colors of an Intuition screen by writing "hi!" in
* every color on the screen.
*
* Note: This is intended for "debug" purposes, as it will
* overwrite the screen's display.
*
* RESULTS: Returns non-zero on error.
*/
/*
* NAME: c_init
*
* SYNOPSIS: err = c_init();
* short err;
*
* DESCRIPTION: Initialize the communication interface software.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_open
*/
/*
* NAME: c_open
*
* SYNOPSIS: err = c_open( parms );
* short err;
*
* INPUTS: struct c_parameters *parms; serial setup parameters
*
* DESCRIPTION: Open the communications channel to the serial device.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_setup, c_init
*/
/*
* NAME: c_setup
*
* SYNOPSIS: err = c_setup( parms );
* short err;
*
* INPUTS: struct c_parameters *parms; serial setup parameters
*
* DESCRIPTION: Set the parameters that configure the serial port for
* communication.
* The different modes for serial configuration are not set in
* this function. They are only done in c_open.
*
* NOTE: the serial port must already be successfully opened by
* c_open and there should be no pending commands on the port.
*
* RESULTS: Returns a non-zero error code (see shandler.h) upon error.
*
* SEE ALSO: c_open
*/
/*
* NAME: c_getc
*
* SYNOPSIS: err = c_getc( charptr );
* short err;
*
* INPUTS: char *charptr; pointer to location to put character
*
* DESCRIPTION: Get a single character from the serial channel, with a
* "large" timeout.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_gets, c_getline, c_emptyc
*/
/*
* NAME: c_emptyc
*
* SYNOPSIS: err = c_emptyc();
* short err;
*
* DESCRIPTION: Flush the buffer, with a "small" timeout.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_getc, c_gets, c_getline
*/
/*
* NAME: c_putc
*
* SYNOPSIS: err = c_putc( character );
* short err;
*
* INPUTS: char character; character to send
*
* DESCRIPTION: Send one character to the serial channel.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_puts
*/
/*
* NAME: c_gets
*
* SYNOPSIS: err = c_gets( buffer, num_to_get );
* short err;
*
* INPUTS: char *buffer; buffer to store characters
* SHORT num_to_get; number of characters to get
*
* DESCRIPTION: Get the specified number of characters from
* the input channel and places them in the buffer.
* Note: does NOT stop reading on a '\0', nor is a '\0' appended.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_getc, c_getline
*/
/*
* NAME: c_getline
*
* SYNOPSIS: err = c_getline( buffer, num_to_get );
* short err;
*
* INPUTS: char *buffer; buffer to store characters
* SHORT num_to_get; number of characters to get
*
* DESCRIPTION: Get up to the specified number of characters,
* or until the end-of-line character is found,
* from the input channel and place them in the buffer.
* The default end-of-line character is 0x0d (CR) (check
* gimmelib/shandler.h to be sure), but this can be changed
* using the c_setEOL() routine.
* Note: the end-of-line character is kept in the buffer
* and NO '\0' is appended.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_setEOL, c_getc, c_gets
*/
/*
* NAME: c_setEOL
*
* SYNOPSIS: err = c_setEOL( eol_character )
* short err;
*
* INPUTS: char eol_character; new end-of-line character
*
* DESCRIPTION: Set the end-of-line character for use with c_getline().
* Note: the end-of-line character must be changed (if desired)
* after each c_open().
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_getline, c_open
*/
/*
* NAME: c_puts
*
* SYNOPSIS: err = c_puts( buffer, num_to_put );
* short err;
*
* INPUTS: char *buffer;
* SHORT num_to_put;
*
* DESCRIPTION: Send the specified number of characters to the serial port
* starting at the location pointed to by buffer.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_putc
*/
/*
* NAME: c_close
*
* SYNOPSIS: err = c_close();
* short err;
*
* DESCRIPTION: Close the communications channel.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_init, c_open
*/
/*
* NAME: c_done
*
* SYNOPSIS: err = c_done();
* short err;
*
* DESCRIPTION: De-initialize the communication interface software,
* i.e. tell it you are completely done with it.
*
* RESULTS: Returns a non-zero code on error (see gimmelib/shandler.h).
*
* SEE ALSO: c_init, c_open, c_close
*/
/*
* NAME: copyDataImage
*
* SYNOPSIS: err = copyDataImage( data, image );
* short err;
*
* INPUTS: USHORT *data; pointer to start of data to copy
* struct Image *image; image to receive data
*
* DESCRIPTION: Copy the data into the image's data buffer (in chip memory).
* Note: the image must already have a data buffer.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: gimmeImage, copyImageData
*/
/*
* NAME: copyImageData
*
* SYNOPSIS: err = copyImageData( image, data );
* short err;
*
* INPUTS: struct Image *image; image to receive data
* USHORT *data; pointer to start of data to copy
*
* DESCRIPTION: Copy the image's actual data into a supplied buffer.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: gimmeImage, copyDataImage
*/
/*
* NAME: copyBorder
*
* SYNOPSIS: border = copyBorder( memheadptr, oldborder, numbord, myflags );
* struct Border *border;
*
* INPUTS: void **memheadptr; pointer to chained-memory head
* struct Border *oldborder; border to copy (first of list)
* SHORT numbord; # of borders to copy, -1 for all
* ULONG myflags; flags for this routine
*
* DESCRIPTION: Copy numbord Border structs beginning with oldborder.
* A numbord of -1 means all the borders in the list.
*
* The flags define how much detail should be copied.
*
* NOTE: chainAllocMem is used and you
* should use chainFreeMem eventually to free the memory;
*
* RESULTS: Returns pointer to Border, or NULL.
*
* SEE ALSO: chainAllocMem, chainFreeMem, gimmeBorder
*/
/*
* NAME: copyImage
*
* SYNOPSIS: image = copyImage( memheadptr, oldimage, numimage, myflags );
* struct Image *image;
*
* INPUTS: void **memheadptr; pointer to chained-memory head
* struct Image *oldimage; image to copy (first of list)
* SHORT numimage; # of images to copy, -1 for all
* ULONG myflags; flags for this routine
*
* DESCRIPTION: Copy numimage Image structs beginning with oldimage.
* A numimage of -1 means all the images in the list.
*
* The flags define how much detail should be copied.
*
* NOTE: chainAllocMem is used and you
* should use chainFreeMem eventually to free the memory;
*
* RESULTS: Returns pointer to Image, or NULL.
*
* SEE ALSO: chainAllocMem, chainFreeMem, gimmeImage
*/
/*
* NAME: copyIntuiText
*
* SYNOPSIS: it = copyIntuiText( memheadptr, olditext, numitext, myflags );
* struct IntuiText *it;
*
* INPUTS: void **memheadptr; pointer to chained-memory head
* struct IntuiText *olditext; itext to copy (first of list)
* SHORT numitext; # of itexts to copy, -1 for all
* ULONG myflags; flags for this routine
*
* DESCRIPTION: Copy numitext IntuiText structs beginning with olditext.
* A numitext of -1 means all the IntuiTexts in the list.
*
* The flags define how much detail should be copied.
*
* NOTE: chainAllocMem is used and you
* should use chainFreeMem eventually to free the memory;
*
* RESULTS: Returns pointer to IntuiText, or NULL.
*
* SEE ALSO: chainAllocMem, chainFreeMem, gimmeIntuiText
*/
/*
* NAME: copyMenuItem
*
* SYNOPSIS: item = copyMenuItem( memheadptr, olditem, numitem, numsub,
* myflags );
* struct MenuItem *item;
*
* INPUTS: void **memheadptr; pointer to chained-memory head
* struct MenuItem *olditem; item to copy (first of list)
* SHORT numitem; #items to copy, -1 for all
* SHORT numsub; #subitems to copy, -1 for all
* ULONG myflags; flags for this routine
*
* DESCRIPTION: Copy numitem MenuItem structs beginning with olditem.
* A numitem of -1 means all the items in the list.
* For each MenuItem copied, numsub subitems will be copied as
* well (a numsub of -1 means all subitems).
*
* The flags define how much detail should be copied.
*
* NOTE: chainAllocMem is used and you
* should use chainFreeMem eventually to free the memory;
*
* RESULTS: Returns pointer to MenuItem, or NULL.
*
* SEE ALSO: chainAllocMem, chainFreeMem, gimmeMenuItem
*/
/*
* NAME: copyMenu
*
* SYNOPSIS: menu = copyMenu( memheadptr, oldmenu, nummenu, numitem,
* numsub, myflags );
* struct Menu *menu;
*
* INPUTS: void **memheadptr; pointer to chained-memory head
* struct Menu *oldmenu; menu to copy (first of list)
* SHORT nummenu; #menus to copy, -1 for all
* SHORT numitem; #menus to copy, -1 for all
* SHORT numsub; #submenus to copy, -1 for all
* ULONG myflags; flags for this routine
*
* DESCRIPTION: Copy nummenu Menu structs beginning with oldmenu.
* A nummenu of -1 means all the menus in the list.
* For each Menu copied, numitem menuitems will be copied as
* well (a numitem of -1 means all menuitems) via copyMenuItem
* using numsub for the number of subitems to copy.
*
* The flags define how much detail should be copied.
*
* NOTE: chainAllocMem is used and you
* should use chainFreeMem eventually to free the memory;
*
* RESULTS: Returns pointer to Menu, or NULL.
*
* SEE ALSO: chainAllocMem, chainFreeMem, gimmeMenu, copyMenuItem
*/
/*
* NAME: makeDBuf
*
* SYNOPSIS: err = makeDBuf( screen, bmptr );
* short err;
*
* INPUTS: struct Screen *screen; ptr to single-buffered screen
* struct BitMap **bmptr; ptr to bitmap ptr for second buffer
*
* DESCRIPTION: Change a single-buffered Intuition screen into a
* double-buffered screen.
* If you already have your own bitmap for the secondary buffer,
* bmptr should point to the bitmap pointer;
* otherwise bmptr should point to a NULL pointer, in which case
* a bitmap of the same depth/width/height as the screen is
* dynamically created, and the pointer to this bitmap is
* returned in *bmptr.
*
* Note: you must not alter the bitmap pointer placed in *bmptr.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: unmakeDBuf, swapDBuf
*/
/*
* NAME: unmakeDBuf
*
* SYNOPSIS: err = unmakeDBuf( screen, bmptr, bm );
* short err;
*
* INPUTS: struct Screen *screen; ptr to double-buffered screen
* struct BitMap **bmptr; ptr to bitmap ptr for second buffer
* struct BitMap *bm; ptr to bitmap to be freed
*
* DESCRIPTION: Changes a double-buffered screen [as made by makeDBuf]
* back into a single-buffered screen.
* The screen's buffers are swapped if necessary to ensure that
* a CloseScreen() will work properly.
* If bm is non-NULL, the bitmap will be freed (de-allocated);
* this is intended primarily to be used to free the bitmap that
* was created by makeDBuf if you did not previously have
* a bitmap for the secondary buffer.
*
* Note: the screen and bmptr parameters should be exactly the
* same as those given to makeDBuf.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: makeDBuf, swapDBuf
*/
/*
* NAME: swapDBuf
*
* SYNOPSIS: err = swapDBuf( screen, minterm );
* short err;
*
* INPUTS: struct Screen *screen; ptr to double-buffered screen
* SHORT minterm; minterm for the copy
*
* DESCRIPTION: Switch the display and draw buffers for the screen.
* The minterm is used to specify the type of blit used to copy
* the new displayed buffer (source) to the new hidden/drawing
* buffer (dest).
* Some common minterms are:
* 0x000 - clear destination
* 0x0c0 - vanilla copy (result: source only)
* 0x0a0 - no copy (result: dest only)
*
* Note: this routine hums along fine if the screen is not
* actually double-buffered, doing no swap and no copy.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: makeDBuf, unmakeDBuf
*/
/*
* NAME: makeDBufQuick
*
* SYNOPSIS: err = makeDBufQuick( screen, bmptr, lcprptr, scprptr );
* short err;
*
* INPUTS: struct Screen *screen; ptr to single-buffered screen
* struct BitMap **bmptr; ptr to bitmap ptr for second buffer
* struct cprlist **lcprptr; ptr to (long) copper list pointer
* struct cprlist **scprptr; ptr to (short) copper list pointer
*
* DESCRIPTION: Change a single-buffered Intuition screen into a
* double-buffered screen.
* If you already have your own bitmap for the secondary buffer,
* bmptr should point to the bitmap pointer;
* otherwise bmptr should point to a NULL pointer, in which case
* a bitmap of the same depth/width/height as the screen is
* dynamically created, and the pointer to this bitmap is
* returned in *bmptr.
*
* Note: you must not alter the bitmap pointer placed in *bmptr.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: unmakeDBufQuick, swapDBufQuick
*/
/*
* NAME: unmakeDBufQuick
*
* SYNOPSIS: err = unmakeDBufQuick( screen, bmptr, bm,
* lcprptr, scprptr );
* short err;
*
* INPUTS: struct Screen *screen; ptr to double-buffered screen
* struct BitMap **bmptr; ptr to bitmap ptr for second buffer
* struct BitMap *bm; ptr to bitmap to be freed
* struct cprlist **lcprptr; ptr to (long) copper list pointer
* struct cprlist **scprptr; ptr to (short) copper list pointer
*
* DESCRIPTION: Changes a double-buffered screen [as made by makeDBufQuick]
* back into a single-buffered screen.
* The screen's buffers are swapped if necessary to ensure that
* a CloseScreen() will work properly.
* If bm is non-NULL, the bitmap will be freed (de-allocated);
* this is intended primarily to be used to free the bitmap that
* was created by makeDBufQuick if you did not previously have
* a bitmap for the secondary buffer.
*
* Note: the screen and bmptr parameters should be exactly the
* same as those given to makeDBufQuick.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: makeDBufQuick, swapDBufQuick
*/
/*
* NAME: swapDBufQuick
*
* SYNOPSIS: err = swapDBufQuick( screen, minterm, lcprptr, scprptr );
* short err;
*
* INPUTS: struct Screen *screen; ptr to double-buffered screen
* SHORT minterm; minterm for the copy
* struct cprlist **lcprptr; ptr to (long) copper list pointer
* struct cprlist **scprptr; ptr to (short) copper list pointer
*
* DESCRIPTION: Switch the display and draw buffers for the screen.
* The minterm is used to specify the type of blit used to copy
* the new displayed buffer (source) to the new hidden/drawing
* buffer (dest).
* Some common minterms are:
* 0x000 - clear destination
* 0x0c0 - vanilla copy (result: source only)
* 0x0a0 - no copy (result: dest only)
*
* Note: this routine hums along fine if the screen is not
* actually double-buffered, doing no swap and no copy.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: makeDBufQuick, unmakeDBufQuick
*/
/*
* NAME: makeDBufVQuick
*
* SYNOPSIS: err = makeDBufVQuick( screen, bmptr );
* short err;
*
* INPUTS: struct Screen *screen; ptr to single-buffered screen
* struct BitMap **bmptr; ptr to bitmap ptr for second buffer
*
* DESCRIPTION: Change a single-buffered Intuition screen into a
* double-buffered screen.
* If you already have your own bitmap for the secondary buffer,
* bmptr should point to the bitmap pointer;
* otherwise bmptr should point to a NULL pointer, in which case
* a bitmap of the same depth/width/height as the screen is
* dynamically created, and the pointer to this bitmap is
* returned in *bmptr.
*
* Note: you must not alter the bitmap pointer placed in *bmptr.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: unmakeDBufVQuick, swapDBufVQuick
*/
/*
* NAME: unmakeDBufVQuick
*
* SYNOPSIS: err = unmakeDBufVQuick( screen, bmptr, bm );
* short err;
*
* INPUTS: struct Screen *screen; ptr to double-buffered screen
* struct BitMap **bmptr; ptr to bitmap ptr for second buffer
* struct BitMap *bm; ptr to bitmap to be freed
*
* DESCRIPTION: Changes a double-buffered screen [as made by makeDBufVQuick]
* back into a single-buffered screen.
* The screen's buffers are swapped if necessary to ensure that
* a CloseScreen() will work properly.
* If bm is non-NULL, the bitmap will be freed (de-allocated);
* this is intended primarily to be used to free the bitmap that
* was created by makeDBufVQuick if you did not previously have
* a bitmap for the secondary buffer.
*
* Note: the screen and bmptr parameters should be exactly the
* same as those given to makeDBufVQuick.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: makeDBufVQuick, swapDBufVQuick
*/
/*
* NAME: swapDBufVQuick
*
* SYNOPSIS: err = swapDBufVQuick( screen, minterm );
* short err;
*
* INPUTS: struct Screen *screen; ptr to double-buffered screen
* SHORT minterm; minterm for the copy
*
* DESCRIPTION: Switch the display and draw buffers for the screen.
* The minterm is used to specify the type of blit used to copy
* the new displayed buffer (source) to the new hidden/drawing
* buffer (dest).
* Some common minterms are:
* 0x000 - clear destination
* 0x0c0 - vanilla copy (result: source only)
* 0x0a0 - no copy (result: dest only)
*
* Note: this routine hums along fine if the screen is not
* actually double-buffered, doing no swap and no copy.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: makeDBufVQuick, unmakeDBufVQuick
*/
/*
* NAME: makeDualPlayfield
*
* SYNOPSIS: err = makeDualPlayfield( screen, ri, reldepth );
* short err;
*
* INPUTS: struct Screen *screen; ptr to single-playfield screen
* struct RasInfo *ri; ptr to RasInfo for second playfield
* SHORT reldepth; depth of second playfield relative
* to first playfield (0 or -1)
*
* DESCRIPTION: Change a single-playfield Intuition screen into a
* dual-playfield screen.
* Fully initializes the RasInfo struct pointed at by ri,
* and links it into the screen's RasInfo.
* A bitmap of the appropriate depth and same width/height will
* be dynamically created - the pointer is returned in ri->BitMap
* The possible depth combinations are limited (see RKM), but
* essentially:
* - the first playfield can be at most depth 3
* - the second playfield must have same depth or 1 less.
* Therefore "reldepth" must be 0 or -1.
* NOTE: present default: the first playfield is given video
* priority over the second playfield (though you can set the
* PFBA flag yourself if you do it right - CAUTION!).
*
* Note: you must have opened the screen using OpenScreen()
* without specifying DUALPF in the NewScreen's Flags field before
* calling this routine to keep things consistent (1.2 Intuition
* does not support opening/closing DUALPF screens properly).
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: unmakeDualPlayfield
*/
/*
* NAME: unmakeDualPlayfield
*
* SYNOPSIS: err = unmakeDualPlayfield( screen );
* short err;
*
* INPUTS: struct Screen *screen; pointer to dual-playfield screen
*
* DESCRIPTION: Changes a dual-playfield screen [as made by makeDualPlayfield]
* back into a single-playfield screen.
*
* NOTE: The bitmap *currently* used for the second-playfield is
* de-allocated, making the second playfield's RasInfo's BitMap
* pointer invalid. This will be the same bitmap that was
* allocated by makeDualPlayfield ONLY if you don't play
* around with the second-playfield's RasInfo's BitMap pointer.
*
* Note: you must call this routine before you do a CloseScreen()
* to keep things consistent (1.2 Intuition does not fully support
* opening/closing DUALPF screens properly).
*
* RESULTS: Returns non-zero on error (eg screen is NULL or screen is not
* dual-playfield).
*
* SEE ALSO: makeDualPlayfield
*/
/*
* NAME: gimmeFont
*
* REQUISITES: struct DiskfontBase *DiskfontBase; properly initialized
*
* SYNOPSIS: textfont = gimmeFont( textattr );
* struct TextFont *textfont;
*
* INPUTS: struct TextAttr *textattr; ptr to font description
*
* DESCRIPTION: Load specified font from disk (check in memory first).
* NOTE: the textattr may be altered to reflect actual font found.
*
* NOTE: you must have a global variable named DiskfontBase,
* declared as a "struct DiskfontBase *", already initialized by
* by opening the diskfont.library with code similar to the
* following:
* struct DiskfontBase *DiskfontBase;
* DiskfontBase = (struct DiskfontBase *)
* OpenLibrary("diskfont.library", 0L);
* { check for NULL pointer returned on error }
*
* RESULTS: Returns TextFont or NULL on error.
* The TextAttr's ta_YSize and ta_Style fields are altered to
* reflect those of the actual font found if successful.
*
* SEE ALSO: gimmeFontLazy, getRidOfFont
*/
/*
* NAME: gimmeFontLazy
*
* REQUISITES: struct DiskfontBase *DiskfontBase; properly initialized
*
* SYNOPSIS: textfont = gimmeFontLazy( name, size );
* struct TextFont *textfont;
*
* INPUTS: UBYTE *name; name of desired font
* UWORD size; y-size of desired font
*
* DESCRIPTION: Load specified font from disk (check in memory first).
* NOTE: a similar font may be used if the exact font is not found.
*
* NOTE: you must have a global variable named DiskfontBase --
* see gimmeFont for information on how to initialize it.
*
* RESULTS: Returns TextFont or NULL on error.
*
* SEE ALSO: gimmeFont, getRidOfFont
*/
/*
* NAME: getRidOfFont
*
* SYNOPSIS: err = getRidOfFont( textfont );
* short err;
*
* INPUTS: struct TextFont *textfont; pointer to TextFont
*
* DESCRIPTION: Releases access to a disk font obtained via gimmeFont(Quick).
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: gimmeFont, gimmeFontLazy
*/
/*
* NAME: getRidOfGadgets
*
* SYNOPSIS: err = getRidOfGadgets( firstgadget );
* short err;
*
* INPUTS: struct Gadget *firstgadget; pointer to first Gadget
*
* DESCRIPTION: Frees memory allocated for each gadget in chain, starting
* with firstgadget, using chainFreeMem.
*
* NOTE: uses a gadget's UserData field as pointer to head of
* memory-chain, as returned by chainAllocMem and set by the
* other gimme-gadget routines.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: chainAllocMem, chainFreeMem, gimmeXXXGadget
*/
/*
* NAME: gimmeBoolGadget
*
* REQUISITES: struct GfxBase *GfxBase; properly initialized - but only if
* ysize == -1, !window && !textattr
*
* SYNOPSIS: gp = gimmeBoolGadget( window, id, left, top, xsize, ysize,
* s, s2, textattr, myflags );
* struct Gadget *gp;
*
* INPUTS: struct Window *window; window for gadget, or NULL
* USHORT id; non-zero id for gadget
* SHORT left; left offset in pixels
* SHORT top; top offset in pixels
* SHORT xsize; total width in pixels, or -1
* SHORT ysize; total height in pixels, or -1
* UBYTE *s; main text string
* UBYTE *s2; auxiliary text string, or NULL
* struct TextAttr *textattr; pointer to font, or NULL
* ULONG myflags; flags for the routine
*
* DESCRIPTION: Allocate and initialize a boolean Gadget structure,
* including a border.
* The border is created appropriately enough to enclose
* the string nicely. Note: this routine succeeds even if no
* border was allocated (check gp->GadgetRender for a non-NULL
* value if you want to be sure that a border was allocated).
*
* NOTE: For text (with a border), not an image.
*
* If the window is non-NULL, some further customization of the
* gadget is done; notably the FgPen, BgPen and DrawMode of the
* window's rastport are used.
* If xsize or ysize are non-positive (use -1), appropriate
* value(s) are calculated to enclose the string nicely.
* If the auxiliary string s2 is NULL, a *hit select* boolean
* gadget is constructed, otherwise a *toggle select* boolean
* gadget is constructed -- NOTE: due to the odd nature of the
* toggle-selected text, you must use toggleBoolGadget upon
* receiving the GADGETDOWN message to effect the toggle visibly
* in the window.
*
* If xsize is non-positive and s2 is non-NULL,
* the border is constructed to enclose the longer string nicely
* and the shorter string is centred in the box accordingly,
* without residue of the longer string when displayed (toggled).
* The textattr can be NULL to use the default font.
* The flags (see gimmelib/postext.h) allow special effects for
* positioning the gadget:
* - if xsize is "real" (positive):
* - x-flags cause the final gadget box to be placed
* accordingly within the region from left to left+xsize
* (eg. x-centre means the gadget is centred within
* xsize bits, offset by the left parm)
* - if xsize is -1 (non-postive):
* - the left parameter is taken to be the coordinate
* as specified by the x-flags
* (eg. x-centre means the left parm is actually the
* centre of the gadget in the x-direction)
* - the y-flags always modify the meaning of the top parm
* (eg. y-centre means the top parm is actually the
* centre of the gadget in the y-direction)
*
* NOTE: The auxiliary string's IntuiText is stored in
* the gadget's SelectRender field. You must leave this field
* alone, which also means do not use the GADGHIMAGE flag.
* The two strings can be switched and displayed by using
* toggleBoolGadget.
*
* NOTE: To remove the border permanently, do something similar
* to the following (with appropriate error checking):
* gp = gimmeBoolGadget(...);
* pluckChainMem( &gp->UserData, gp->GadgetRender );
* gp->GadgetRender = NULL;
* (the pluckChainMem is not absolutely necessary, since the
* border's memory would be freed when getRidOfGadgets is called)
*
* If all goes well, the head pointer to chained memory for the
* gadget and its other required structures is stored in the
* gp->UserData field. You must preserve this pointer!!
* If you need to use the UserData yourself, be sure to save
* gp->UserData somewhere safe after calling this routine.
* When you are done with the gadget you must ensure that the
* chained memory head pointer is restored into gp->UserData
* before you call getRidOfGadgets.
*
* NOTE: if you supply an auxiliary string s2 to create a toggle
* gadget, and window is non-NULL, then the window's rastport's
* drawmode should be JAM2 otherwise visual confusion may occur
* upon toggling and/or clearing.
*
* RESULTS: Returns pointer to boolean gadget, or NULL.
* Note: The gadget is NOT added to the window.
*
* SEE ALSO: toggleBoolGadget, getRidOfGadgets, gimmeBoolImageGadget
*/
/*
* NAME: gimmeBoolImageGadget
*
* SYNOPSIS: gp = gimmeBoolImageGadget( window, id, left, top, depth, width,
* height, myflags, dep2, wid2, ht2 );
* struct Gadget *gp;
*
* INPUTS: struct Window *window; window for gadget, or NULL
* USHORT id; non-zero id for gadget
* SHORT left; left offset in pixels
* SHORT top; top offset in pixels
* SHORT depth; depth of primary image
* SHORT width; width of primary image, in pixels
* SHORT height; height of primary image, in pixels
* ULONG myflags; flags for the routine
* SHORT dep2; depth of secondary image, or <= 0
* SHORT wid2; width of secondary image, or <= 0
* SHORT ht2; height of secondary image, or <= 0
*
* DESCRIPTION: Allocate and initialize a boolean Gadget structure,
* including Image structure(s) and data memory (via gimmeImage)
* for the primary image, and for the secondary image if the
* 3 size specifications for it are strictly positive.
* Note that for the primary image, you can specify zero for any
* of its dimensions so that an Image structure but no data memory
* is allocated.
*
* NOTE: For images, not text.
*
* If the secondary image's dimensions are improper, a *hit select*
* boolean gadget is constructed, otherwise a *toggle select*
* boolean gadget is constructed.
* NOTE: if you wish the secondary image to merely be highlighting
* imagery for a *hit select* boolean gadget, you should do this:
* gp->Activation = RELVERIFY;
* after this function call (note your two images should overlap
* exactly to keep things clean on the screen).
* NOTE: if you wish to toggle manually, do the following:
* gp->Flags = GADGIMAGE | GADGHNONE;
* gp->Activation = GADGIMMEDIATE;
* after this function call. Then, when you receive a GADGETDOWN
* message, call toggleBoolGadget to switch the imagery. This is
* similar to the system toggle select except that toggleBoolGadget
* erases the current image before drawing the "alternate" image
* and redefines the gadget's select box for the new image.
*
* The flags (see gimmelib/postext.h) alter the meaning of the
* top and left parameters, with respect to the size of the
* primary image.
*
* If all goes well, the head pointer to chained memory for the
* gadget and its other required structures is stored in the
* gp->UserData field. You must preserve this pointer!!
* If you need to use the UserData yourself, be sure to save
* gp->UserData somewhere safe after calling this routine.
* When you are done with the gadget you must ensure that the
* chained memory head pointer is restored into gp->UserData
* before you call getRidOfGadgets.
*
* RESULTS: Returns pointer to boolean gadget, or NULL.
* Note: The gadget is NOT added to the window.
*
* SEE ALSO: toggleBoolGadget, getRidOfGadgets, gimmeBoolGadget
*/
/*
* NAME: gimmePropGadget
*
* SYNOPSIS: gp = gimmePropGadget( window, id, left, top, xsize, ysize,
* label, textattr, activflags, propflags );
* struct Gadget *gp;
*
* INPUTS: struct Window *window; window for gadget, or NULL
* USHORT id; non-zero id for gadget
* SHORT left; left offset in pixels
* SHORT top; top offset in pixels
* SHORT xsize; total width in pixels
* SHORT ysize; total height in pixels
* UBYTE *label; gadget label, or NULL
* struct TextAttr *textattr; pointer to font, or NULL
* ULONG activflags; gadget Activation flags
* ULONG propflags; flags for PropInfo
*
* DESCRIPTION: Allocate and initialize a string Gadget structure,
* including PropInfo and optional label.
* If the window is non-NULL, some further customization of the
* gadget is done; notably the FgPen, BgPen and DrawMode of the
* window's rastport are used for the label.
* The xsize and ysize parms define the size of the actual,
* gadget, NOT including the (optional) label.
* Note: if xsize and/or ysize are non-positive, you must set
* the appropriate flags (such as GRELWIDTH, GRELHEIGHT) in the
* gadget's Flags field after this routine returns.
* If label is non-NULL, a label is set up with the actual prop
* gadget to the right of the label.
* The textattr can be NULL to use the default font.
* The activflags are set in the gadget's Activation field.
* The propflags are set in the gadget's PropInfo structure - see
* gimmePropInfo for details on how these flags are used.
* Note: if you wish to change the knob imagery to your own, do
* something similar to the following after this routine:
* gp->GadgetRender = (APTR) <your image or border>;
* ((struct PropInfo *)gp->SpecialInfo)->Flags &= ~AUTOKNOB;
* gp->Flags &= ~GADGIMAGE; ;; ONLY if you want a BORDER
*
* If all goes well, the head pointer to chained memory for the
* gadget and its other required structures is stored in the
* gp->UserData field. You must preserve this pointer!!
* If you need to use the UserData yourself, be sure to save
* gp->UserData somewhere safe after calling routine.
* When you are done with the gadget you must ensure that the
* chained memory head pointer is restored into gp->UserData
* before you call getRidOfGadgets.
*
* RESULTS: Returns pointer to prop gadget, or NULL.
* Note: The gadget is NOT added to the window.
*
* SEE ALSO: getRidOfGadgets, gimmePropInfo
*/
/*
* NAME: gimmePropInfo
*
* SYNOPSIS: pi = gimmePropInfo( memheadptr, flags );
* struct PropInfo *pi;
*
* INPUTS: void **memheadptr; pointer to chained-memory head
* ULONG flags; flags for PropInfo
*
* DESCRIPTION: Allocate and initialize a PropInfo structure.
*
* The PropInfo's flags are set to "AUTOKNOB | flags"
* which you can change after this function returns.
*
* The allocated memory is chained to the memory chain pointed
* at by memheadptr using chainAllocMem.
* Eventually chainFreeMem should be called on the memhead.
*
* RESULTS: Returns pointer to PropInfo, or NULL.
*
* SEE ALSO: chainAllocMem, chainFreeMem
*/
/*
* NAME: gimmeStringGadget
*
* REQUISITES: struct GfxBase *GfxBase; properly initialized - but only
* needed if !window && !textattr
*
* SYNOPSIS: gp = gimmeStringGadget( window, id, left, top, width, maxbuf,
* s, label, textattr, activflags );
* struct Gadget *gp;
*
* INPUTS: struct Window *window; window for gadget, or NULL
* USHORT id; non-zero id for gadget
* SHORT left; left offset in pixels
* SHORT top; top offset in pixels
* SHORT width; total width in pixels
* SHORT maxbuf; maximum buffer size including '\0'
* UBYTE *s; initial text string
* UBYTE *label; gadget label, or NULL
* struct TextAttr *textattr; pointer to font, or NULL
* ULONG activflags; gadget Activation flags
*
* DESCRIPTION: Allocate and initialize a string Gadget structure,
* including border, StringInfo, buffers and optional label.
* If the window is non-NULL, some further customization of the
* gadget is done; notably the FgPen, BgPen and DrawMode of the
* window's rastport are used for the label and border.
* The border is width pixels wide and high enough to enclose
* the string nicely. Note: this routine succeeds even if no
* border was allocated (check gp->GadgetRender for a non-NULL
* value if you want to be sure that a border was allocated).
* If you want to remove the border, do something similar to this:
* pluckChainMem( &gp->UserData, gp->GadgetRender );
* gp->GadgetRender = NULL;
* If label is non-NULL, a label is set up with the actual string
* gadget to the right of the label.
* NOTE: the width includes space taken by the label (if any).
* The textattr can be NULL to use the default font.
* The activflags are set in the gadget's Activation field.
*
* Note: the actual string is rendered in the screen's font.
* This is normally the font specified when the screen is opened.
* However, doing a SetFont() on the screen's rastport to alter the
* font (and even if you change the screen's Font field as well)
* will cause the string gadget to be handled a little awkwardly:
* the initial rendering will occur in the screen's original font,
* and once the gadget is selected, the "new" font will be used for
* rendering; however, the "old" font's character width is used to
* determine which character in the string gadget is clicked on,
* which may result in some visual confusion.
*
* If all goes well, the head pointer to chained memory for the
* gadget and its other required structures is stored in the
* gp->UserData field. You must preserve this pointer!!
* If you need to use the UserData yourself, be sure to save
* gp->UserData somewhere safe after calling routine.
* When you are done with the gadget you must ensure that the
* chained memory head pointer is restored into gp->UserData
* before you call getRidOfGadgets.
*
* RESULTS: Returns pointer to string gadget, or NULL.
* Note: The gadget is NOT added to the window.
*
* SEE ALSO: getRidOfGadgets, gimmeStringInfo
*/
/*
* NAME: gimmeStringInfo
*
* SYNOPSIS: si = gimmeStringInfo( memheadptr, bufsize, s, flags );
* struct StringInfo *si;
*
* INPUTS: void **memheadptr; pointer to chained memory head
* SHORT bufsize; maximum size including nullchar
* UBYTE *s; initial string
* ULONG flags; flags for StringInfo: only LONGINT checked
*
* DESCRIPTION: Allocate and initialize a StringInfo structure,
* including space for the main and undo buffers.
* If the LONGINT flag is set in flags, the initial string s
* should consist of a valid long integer in ascii format.
*
* The allocated memory is chained to the memory chain pointed
* at by memheadptr using chainAllocMem.
* Eventually chainFreeMem should be called on the memhead.
*
* RESULTS: Returns pointer to StringInfo, or NULL.
*
* SEE ALSO: chainAllocMem, chainFreeMem
*/
/*
* NAME: clearGadgets
*
* SYNOPSIS: err = clearGadgets( firstgadget, window, req, numgad );
* short err;
*
* INPUTS: struct Gadget *firstgadget; first gadget to clear
* struct Window *window; gadget's window
* struct Requester *req; gadget's requester, or NULL
* SHORT numgad; # of gadgets to clear, or -1
*
* DESCRIPTION: Clear the imagery of numgad gadgets in a window, starting with
* firstgadget.
* If numgad is negative, the whole list starting with firstgadget
* is cleared. If numgad is zero, no gadgets are cleared.
* NOTE: the gadget cannot be in a requester, so if the req
* parameter is non-NULL, the gadget(s) will not be cleared and
* an error returned.
* NOTE: The requester is ignored unless the first gadget has the
* REQGADGET gadget type flag set; you should ensure that this flag
* is consistently set or clear in each gadget in the list.
* It is assumed that all gadgets are in the requester if the first
* one is.
* NOTE: the gadget(s) will be cleared regardless of whether it
* actually exists in the window or requester.
*
* If RefreshGadgets() is called after this routine, the gadget(s)
* will be displayed normally.
*
* NOTE: active "invisible" gadgets may look odd; especially a
* previously activated string gadget and when you click somewhere
* else, the cursor in the string gadget is redrawn by Intuition.
* The cause of this may be the following: if a string gadget has
* the GADGHCOMP flag set, then the cursor is drawn when a
* RefreshGadgets() is done (possibly only if the gadget is in a
* requester).
*
* RESULTS: Returns non-zero on error.
* Note that the Gadget's display on screen is cleared to the
* background colour of the window's rastport immediately.
*
* SEE ALSO: RefreshGList, RemoveGList, AddGList
*/
/*
* NAME: toggleBoolGadget
*
* SYNOPSIS: error = toggleBoolGadget( window, gadget, req );
* short error;
*
* INPUTS: struct Window *window; gadget's window
* struct Gadget *gadget; boolean gadget to toggle
* struct Requester *req; gadget's requester, or NULL
*
* DESCRIPTION: Toggle a boolean gadget's text OR image, by switching it
* with the alternative text or image respectively.
*
* If it is a text gadget:
* NOTE: the alternative text pointer is originally stored in
* the gadget's SelectRender field by gimmeBoolGadget.
* You must leave this field alone, which also means do not use
* the GADGHIMAGE flag.
* If it is an image gadget:
* the current ("old") image is erased before the new image is
* drawn, and the select box of the gadget is altered to the
* dimensions of the new image (this works perfectly only if
* the image's top left corner is the same as the gadget's).
*
* RESULTS: Returns non-zero on error.
* Note: this routine only refreshes this gadget.
*
* SEE ALSO: gimmeBoolGadget, clearGadgets
*/
/*
* NAME: findGadget
*
* SYNOPSIS: gp = findGadget( firstgadget, id );
* struct Gadget *gp;
*
* INPUTS: struct Gadget *firstgadget; pointer to Gadget list
* USHORT id; id of Gadget being sought
*
* DESCRIPTION: Search linked list of Gadgets, starting with firstgadget,
* for the first Gadget with GadgetID equal to id.
*
* RESULTS: Returns pointer to Gadget matching the id, or NULL if none.
*/
/*
* NAME: findMyFirstGadget
*
* SYNOPSIS: gp = findMyFirstGadget( window, id );
* struct Gadget *gp;
*
* INPUTS: struct Gadget *firstgadget; pointer to Gadget list
* USHORT id; threshold id to skip over
*
* DESCRIPTION: Search linked list of Gadgets, starting with firstgadget,
* for the first Gadget with GadgetID strictly greater than id.
*
* RESULTS: Returns pointer to first Gadget with a greater id,
* or NULL if none.
*/
/*
* NAME: gimmeGraph
*
* SYNOPSIS: gr = gimmeGraph( newgraph, bitmap, areainfo, tmpras );
* GRAPH *gr;
*
* INPUTS: struct NEWGRAPH *newgraph; ptr to initialized NEWGRAPH
* struct BitMap *bitmap; bitmap pointer, or NULL
* struct AreaInfo *areainfo; areainfo pointer, or NULL
* struct TmpRas *tmpras; tmpras pointer, or NULL
*
* DESCRIPTION: Create and initialize a GRAPH structure,
* according to the specifications in the newgraph.
* The axes and title will be rendered immediately unless the
* appropriate flag is set, in which case you can modify the GRAPH
* structure, then call drawGraphAxes yourself after this routine.
*
* NOTE: currently the graph routines only properly support 1st
* quadrant graphing with a right-handed coordinate system
* (ie the axes should increase in value up and to the right).
* If you use scrolling (via DELTA flags), you should avoid
* values that fall exactly on an axis.
*
* If the newgraph's rastport pointer is non-NULL, the actual
* rastport is copied into the graph structure, leaving the
* rastport pointed at by the newgraph forever untouched;
* otherwise the graph's rastport is initialized by InitRastPort().
* If bitmap is non-NULL, the bitmap pointer is copied into the
* graph's rastport's bitmap pointer.
* NOTE: if you specified a rastport in the newgraph and no bitmap
* parameter, the bitmap in that rastport will be used; otherwise
* you MUST specify a valid bitmap pointer as a parameter.
*
* The areainfo and tmpras parameters go together, and are used
* only if either or both FILLTO flags are set.
* If areainfo (or tmpras) is non-NULL, the pointer will be set
* in the graph's rastport. If areainfo (or tmpras) is NULL, then
* an AreaInfo struct and vector buffer (or TmpRas struct and a
* raster the same size as the bitmap) are allocated for you.
* NOTE: if you specify the same areainfo and/or tmpras for two
* or more graphs, you must ensure that any addToGraph using FILLTO
* is not done concurrently, since technically the areainfo/tmpras
* structs should be unique for each graph.
*
* The graphing routines are intended to be reasonably flexible;
* you can alter the fonts and colours for the various titles and
* labvels (title refers to words; label refers to the numbers on
* an axis) after this routine -- currently, the labels default to
* use the same font as their respective titles; the axes' title
* colours default to the same as the title colour; and the axes'
* label colours default to the axes colour.
* NOTE: if you wish to use different fonts for the labels, you
* can set the appropriate graph's textfont pointer, for example
* by assigning the title-textfont to the x-label-textfont, or
* setting it to NULL to use the "default" font;
* however, it is recommended that you do not introduce new fonts
* unless you know how to handle fonts properly (in particular
* do not play around with the three title font pointers).
*
* Points are added to the graph dynamically using addToGraph.
*
* See gimmelib/graph.h for descriptions of the various graphing
* structures and flags; note that some of the newgraph flags
* apply to how axis information is used.
*
* Note: all allocated memory, including the GRAPH struct itself,
* is chained and the header is stored in the GRAPH's memhead
* field, which is used by getRidOfGraph to deallocate memory.
* You should use getRidOfGraph to free all the memory allocated
* by this routine.
*
* RESULTS: Returns a pointer to a GRAPH, or NULL if anything went wrong.
*
* SEE ALSO: addToGraph, getRidOfGraph, gimmeFont, drawGraphAxes,
* chainAllocMem
*/
/*
* NAME: getRidOfGraph
*
* SYNOPSIS: err = getRidOfGraph( graph );
* short err;
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
*
* DESCRIPTION: Close a graph, freeing any allocated memory and releasing
* access to fonts accessed by gimmeGraph.
* May clear the graph first if the flags dictate it.
*
* RESULTS: Returns non-zero on error.
*
* SEE ALSO: gimmeGraph, clearGraph, getRidOfFont, chainFreeMem
*/
/*
* NAME: clearGraph
*
* SYNOPSIS: clearGraph( graph );
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
*
* DESCRIPTION: Clear a graph.
* Effectively this means drawing the axes, labels and titles
* in the background colour and then clearing the rectangular
* region of the graph (bounded by the axes).
* Note: the graph struct is otherwise unchanged after this call.
*
* SEE ALSO: gimmeGraph, getRidOfGraph
*/
/*
* NAME: resetGraph
*
* SYNOPSIS: resetGraph( graph );
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
*
* DESCRIPTION: Resets a graph to the beginning.
* Effectively this means clearing the graph, re-initializing
* appropriate variables such as first and last point, undoing
* the effects of any scrolling, etc. and redrawing the "empty"
* graph if the graph's flags dictate it.
*
* SEE ALSO: gimmeGraph, clearGraph, drawGraphAxes, getRidOfGraph
*/
/*
* NAME: drawGraphAxesOnly
*
* SYNOPSIS: drawGraphAxesOnly( graph );
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
*
* DESCRIPTION: Draw the axes (lines only -- not labels) of a graph.
* Existing axes (if any) are NOT cleared first.
*
* SEE ALSO: drawGraphAxes, gimmeGraph, clearGraph
*/
/*
* NAME: drawGraphAxes
*
* SYNOPSIS: drawGraphAxes( graph );
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
*
* DESCRIPTION: Draw the axes including labels, titles and graph title
* of a graph in appropriate fonts, colours and positions.
* This means main title centred over the graph quad, the x-title
* centred under the x-axis (and labels), and the y-axis vertical
* and centred left of the y-axis (and labels).
*
* Existing axes, labels and titles (if any) are NOT cleared first.
*
* RESULTS: Returns the maximum width required for the labels (not titles).
*
* SEE ALSO: drawGraphAxes, gimmeGraph, clearGraph, drawGraphTitle,
* drawGraphXtitle, drawGraphYtitle
*/
/*
* NAME: drawGraphTitle
*
* SYNOPSIS: drawGraphTitle( graph, xoff, yoff, myflags );
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
* SHORT xoff; offset from y-axis in pixels
* SHORT yoff; offset from x-axis in pixels
* ULONG myflags; flags ala positionText
*
* DESCRIPTION: Draw the main title for a graph in the appropriate font
* and colour at (xoff, yoff) relative to the graph origin
* as modified by myflags via positionText.
* NOTE: yoff is positive upwards from the x-axis, and negative
* downwards (opposite to the normal rastport offsets).
*
* Existing title (if any) is NOT cleared first.
*
* SEE ALSO: drawGraphAxes, gimmeGraph, clearGraph, positionText
*/
/*
* NAME: drawGraphXtitle
*
* SYNOPSIS: drawGraphXtitle( graph, xoff, yoff, myflags );
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
* SHORT xoff; offset from y-axis in pixels
* SHORT yoff; offset from x-axis in pixels
* ULONG myflags; flags ala positionText
*
* DESCRIPTION: Draw the title for a graph's x-axis in the appropriate font
* and colour at (xoff, yoff) relative to the graph origin
* as modified by myflags via positionText.
* NOTE: yoff is positive upwards from the x-axis, and negative
* downwards (opposite to the normal rastport offsets).
*
* Existing title (if any) is NOT cleared first.
*
* SEE ALSO: drawGraphAxes, gimmeGraph, clearGraph, positionText
*/
/*
* NAME: drawGraphYtitle
*
* SYNOPSIS: drawGraphYtitle( graph, xoff, yoff, myflags );
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
* SHORT xoff; offset from y-axis in pixels
* SHORT yoff; offset from x-axis in pixels
* ULONG myflags; flags ala positionText
*
* DESCRIPTION: Draw the title for a graph's y-axis in the appropriate font
* and colour at (xoff, yoff) relative to the graph origin
* as modified by myflags via positionText.
* NOTE: yoff is positive upwards from the x-axis, and negative
* downwards (opposite to the normal rastport offsets).
*
* Existing y-title (if any) is NOT cleared first.
*
* SEE ALSO: drawGraphAxes, gimmeGraph, clearGraph, positionText
*/
/*
* NAME: graphWriteLabel
*
* SYNOPSIS: graphWriteLabel( graph, myflags, first, last, step )
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
* ULONG myflags; flags for this routine
* SHORT first; low coordinate to start at
* SHORT last; high coordinate to end at
* SHORT step; fixed step size, 0 for automagic size
*
* DESCRIPTION: Draw the labels for one axis of a graph in the appropriate font
* and colour (note: does not draw axis title).
*
* Automagically labels an axis between the coords first and last
* inclusive (the first and last parms should be reasonable -- not
* checked).
* If step is zero (0) then labels for first and last are rendered,
* and as many labels as reasonably possible are placed starting
* next to first and going towards just before last, leaving a
* reasonable amount of space between labels.
* If step is strictly positive, then a label is written for the
* coords: first, first+step, first+step+step,...,last
* (note that if last is not n-steps away from first then a label
* for last itself will not be drawn).
* Note: the step size should not be too small (not checked).
*
* NOTE: exact label "wording" depend on the axis scale and certain
* graph flags.
*
* Warning: this is a very recursive routine (unless you give
* a fixed step size).
*
* RESULTS: Returns the maximum width of the labels for this axis.
*
* SEE ALSO: drawGraphAxes, gimmeGraph, clearGraph
*/
/*
* NAME: addToGraph
*
* SYNOPSIS: addToGraph( graph, x, y );
*
* INPUTS: GRAPH *graph; pointer to a GRAPH structure
* SHORT x; x coordinate of new point to add
* SHORT y; y coordinate of new point to add
*
* DESCRIPTION: Add a point to the graph, rendered according to the flags
* in the graph structure.
* This includes lines, block fills etc. as well as scrolling
* if necessary.
* Note: the point is moved to the boundary of the rectangular
* region defined by the origin and the size of the axes
* if the point would fall outside of this boundary.
*
* NOTE: if either FILLTO flag is set in the graph, the proper
* initialized AreaInfo and TmpRas structures must exist
* (gimmeGraph takes care of this if either FILLTO flag was set
* when it was called) otherwise crashes will occur.
*
* SEE ALSO: gimmeGraph, getRidOfGraph, drawGraphAxes
*/
/*
* NAME: addInputHandler
*
* SYNOPSIS: ioreq = addInputHandler( handler, data, pri, name );
* struct IOStdReq *ioreq;
*
* INPUTS: void (*handler)(); address of handler routine
* APTR data; pointer to data area for handler
* BYTE pri; priority for the handler
* UBYTE *name; name for input handler, or NULL
*
* DESCRIPTION: Add an input handler to the system.
* The priority indicates the priority level of the input handler;
* note that Intuition operates at priority fifty (50).
* The name is optional.
*
* Your "real" input handler routine should be written as if called
* from the following C-language statement (see manuals):
* newEventChain = handler( oldEventChain, data );
* This isn't entirely true... the routine "handler" should
* actually expect the oldEventChain and data parameters
* in A0 and A1 respectively (see manuals).
* IF your real input handler is written in C, make your real
* input handler act like the above C-language call and also
* you must set up an interface routine similar to the following:
* #asm
* _handler:
* MOVEM.L D2/D3/A4/A6,-(sp) ; save some registers
* MOVEM.L A0/A1,-(sp) ; set up parms for C
* JSR _myrealhandler
* LEA 8(sp),sp ; pop parms
* MOVEM.L (sp)+,D2/D3/A4/A6 ; restore registers
* RTS ; return in D0
* #endasm
* then call this routine using "handler", NOT "myrealhandler",
* as the handler parameter.
*
* NOTE: your "real" input handler may have to do a geta4() as
* the first thing (or the Lattice equivalent) to set up a special
* pointer for small code/data models.
*
* NOTE: do not fiddle with the iorequest; in particular, you
* must not alter the ioreq->io_Data pointer.
*
* RESULTS: Returns a pointer to a IOStdReq, or NULL if unsuccessful.
*
* SEE ALSO: removeInputHandler
*/
/*
* NAME: removeInputHandler
*
* SYNOPSIS: err = removeInputHandler( ioreq );
SHAR_EOF
# End of shell archive
exit 0
--
Bob Page, U of Lowell CS Dept. page@swan.ulowell.edu ulowell!page
Have five nice days.