194 lines
7.2 KiB
C
194 lines
7.2 KiB
C
/*
|
|
*
|
|
* ToolLib.h - Interface file for functions contained in
|
|
* ToolLib library. These functions can be used by
|
|
* programs that are to be operated as tools under the
|
|
* APW shell on the Apple IIgs.
|
|
*
|
|
* Copyright Apple Computer, Inc. 1989
|
|
* All rights reserved
|
|
*
|
|
* Author: Greg Branche
|
|
*
|
|
*/
|
|
|
|
#ifndef __ToolLib__
|
|
#define __ToolLib__
|
|
|
|
/************************************************************
|
|
|
|
<<< CursorCtl - Cursor Control Routines >>>
|
|
|
|
This file contains:
|
|
|
|
InitCursorCtl(delaycount) - Init CursorCtl to set the spin delay
|
|
RotateCursor(counter) - Sequence through cursor frames for counter mod delay
|
|
SpinCursor(increment) - Sequence mod delay incrementing internal counter
|
|
Hide_Cursor() - Hide the current cursor
|
|
Show_Cursor() - Show the cursor
|
|
|
|
************************************************************/
|
|
|
|
extern pascal void InitCursorCtl(/* delaycount */);/*
|
|
unsigned long delaycount;
|
|
|
|
Initialize the CursorCtl unit. This should be called once prior to calling
|
|
any of the other CursorCtl routines. If delaycount = 0, then the default delay
|
|
value of 32 will be used. Ensure that the value being passed as delaycount is
|
|
32-bits in size (long)
|
|
*/
|
|
|
|
extern pascal void Show_Cursor();/*
|
|
|
|
This function removes the default inverse space cursor from the screen and replaces it
|
|
with the first frame of the animated cursor. It then outputs a backspace so that any
|
|
subsequent characters will automatically overwrite the cursor character.
|
|
*/
|
|
|
|
extern pascal void RotateCursor(/* counter */);/*
|
|
unsigned long counter;
|
|
|
|
RotateCursor is called to rotate the "I am active" "spinning wheel" cursor. The next cursor
|
|
("frame") is used when (counter MOD delaycount) (as specified in the InitCursorCtl call) = 0
|
|
(counter is some kind of incrementing or decrementing index maintained by the caller). A
|
|
positive counter sequences forward through the cursors (e.g., it rotates the cursor
|
|
"clockwise"), and a negative cursor sequences through the cursors backwards (e.g., it
|
|
rotates the cursor counterclockwise).
|
|
*/
|
|
|
|
extern pascal void SpinCursor(/* increment */);/*
|
|
unsigned short increment;
|
|
|
|
SpinCursor is similar in function to RotateCursor, except that instead of passing a counter,
|
|
an increment is passed and added to a counter maintained here. SpinCursor is provided for
|
|
those users who do not happen to have a convenient counter handy but still want to use the
|
|
spinning cursor. A positive increment sequences forward through the cursors (rotating the
|
|
cursor clockwise), and a negative increment sequences backward through the cursors (rotating
|
|
the cursor counterclockwise). A zero value for the increment resets the counter to zero.
|
|
Note, it is the increment, and not the value of the counter that determines the sequencing
|
|
direction of the cursor (and hence the spin direction of the cursor).
|
|
*/
|
|
|
|
extern pascal void Hide_Cursor();/*
|
|
|
|
Hides the current character of the spinning cursor. Use this routine when you wish to
|
|
revert to the standard inverse space cursor.
|
|
*/
|
|
|
|
/************************************************************
|
|
|
|
ErrMgr.h - //GS equivalent of the MPW Error Manager
|
|
|
|
************************************************************/
|
|
|
|
extern void InitErrMgr(/* toolErrFilename, sysErrFilename, showToolErrNbrs */);
|
|
/* char *toolErrFilename;
|
|
char *sysErrFilename;
|
|
boolean showToolErrNbrs;
|
|
|
|
Initializes the error manager. If toolErrFilename is not null, this will open the resource fork
|
|
of that file to allow access to tool-specific error messages. If sysErrFilename is not null,
|
|
this will open the resource fork of that file instead of the standard APW error message file.
|
|
If showToolErrNbrs is TRUE, then any call to GetSysErrText will show the decimal and hexadecimal
|
|
error number in parentheses after the text of the error message. If this is false, all that
|
|
GetSysErrText will provide is the text of the message.
|
|
|
|
To use the error manager, your tool must start up the Resource Manager prior to calling
|
|
InitErrMgr. This function will NOT do it for you.
|
|
*/
|
|
|
|
extern void CloseErrMgr();
|
|
/*
|
|
This simply closes any resources files opened by InitErrMgr. It is not absolutely required that
|
|
you call this function prior to exiting your tool, but it is available. If it is not called, the
|
|
Resource Manager will automatically close any files opened. You must shutdown the Resource
|
|
Manager yourself.
|
|
*/
|
|
|
|
extern char *GetSysErrText(/* errNbr,errMsg */);
|
|
/* unsigned errNbr;
|
|
StringPtr errMsg;
|
|
|
|
GetSysErrText performs a resource lookup for the supplied errNbr. It does this by calculating
|
|
which resource number to use from the system resource file or the tool-specific error file.
|
|
|
|
The function places the error message text in the buffer pointed to by errMsg, and also returns
|
|
a pointer to a standard C string representing the error message associated with the given error
|
|
number. If there is message text available for the given error number, the string will have
|
|
the following format:
|
|
|
|
### {tool name}: {message text}
|
|
|
|
If no specific message is available, the string will have the following format:
|
|
|
|
### {tool name}: Error {decimal error number} ($xxxx)
|
|
|
|
where $xxxx is the hexadecimal error code.
|
|
*/
|
|
|
|
/************************************************************
|
|
|
|
gsString.h - header file for GS/OS string support functions
|
|
|
|
************************************************************/
|
|
|
|
#ifdef __GSOS__
|
|
|
|
extern GSString255 *c2gsstr(/* str, pathGS */);
|
|
/* char *str;
|
|
GSString255 *pathGS;
|
|
|
|
This function accepts a null terminated C string and copies it to a
|
|
GS/OS-style string (length word followed by the characters of the string).
|
|
On return, the function returns the pointer to the pathname structure
|
|
*/
|
|
|
|
extern char *gs2cstr(/* pathGS, str */);
|
|
/* GSString255 pathGS;
|
|
char *str;
|
|
|
|
This function converts a GS/OS-style string (word length followed by the
|
|
characters of the string) to a normal, null terminated C string. On exit
|
|
it returns a pointer to the string (which is the same as that specified
|
|
on entry).
|
|
*/
|
|
|
|
extern void colonize(/* fileName */);
|
|
/* char *fileName;
|
|
|
|
normalizes a filename string so that it contains only colons as pathname
|
|
separators. If there are no separators in the filename, the name is left
|
|
unchanged. If the filename contains no slashes, the filename is left
|
|
unchanged.
|
|
*/
|
|
#endif
|
|
|
|
/************************************************************
|
|
|
|
pause.h - header file for APW-compatible pause function
|
|
|
|
************************************************************/
|
|
|
|
extern int pause();
|
|
/*
|
|
This function should be called periodically by an APW tool to check for
|
|
a pending keypress and/or command-. (abort signal). If the command-.
|
|
keypress is pending, the function will return a non-zero value
|
|
(signifying TRUE). If any other keypress is pending, the function
|
|
will display an hourglass character on the screen and pause until
|
|
another key is pressed.
|
|
|
|
The value returned is either non-zero (TRUE), indicating that command-.
|
|
has been pressed and the tool should abort, or 0 (false), indicating
|
|
that processing should proceed.
|
|
*/
|
|
|
|
extern int wait();
|
|
/*
|
|
This function operates similarly to the pause() function, except that
|
|
it forces a keypress prior to returning to the caller. That is, it
|
|
waits in a loop until a keypress occurs. The values returned are the
|
|
same as described for the pause() function.
|
|
*/
|
|
#endif
|