ORCA-C/ORCACDefs/toollib.h

194 lines
7.2 KiB
C
Raw Normal View History

/*
*
* 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