. If you pass a null function pointer, the default comparison routine will be called, which checks to see if every data byte matches.
Include: chunkarr.h
Tips and Tricks: If you know the element is already in the array, you can increment its reference count by calling
ElementArrayAddReference()
.
Be Sure To: Lock the block on the global heap before calling (unless it is fixed).
See Also: ElementArrayAddReference()
.
word ElementArrayAddElementHandles( MemHandle mh, /* Global handle of LMem heap */ ChunkHandle chunk /* Chunk handle of element array */ void * element, /* Element to add */ dword callBackData, /* Passed to the Callback routine */ Boolean _pascal (*callback) (void *elementToAdd, void *elementFromArray, dword valueForCallback));
This routine is exactly like
ElementArrayAddElement()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
Tips and Tricks: If you know the element is already in the array, you can increment its reference count by calling
ElementArrayAddReference()
.
Be Sure To: Lock the block on the global heap before calling (unless it is fixed).
See Also: ElementArrayAddReference()
.
void ElementArrayAddReference( optr arr, /* optr to element array */ word token); /* Index number of element */
This routine increments the reference count of a member of an element array.
Be Sure To: Lock the block on the global heap before calling (unless it is fixed).
See Also: ElementArrayAddElement()
.
void ElementArrayAddReferenceHandles( MemHandle mh, /* Handle of LMem heap's block */ ChunkHandle ch, /* Handle of element array */ word token); /* Index number of element */
This routine is exactly like
ElementArrayAddReference()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
ChunkHandle ElementArrayCreate( MemHandle mh, /* Handle of LMem heap's block */ word elementSize, /* Size of each element, or zero * for variable-sized */
word headerSize); /* Header size (zero for default) */
This routine creates an element array in the indicated LMem heap. It creates an
ElementArrayHeader
structure at the head of the chunk. If you want to leave extra space before the start of the array, you can pass a larger header size; if you want to use the standard header, pass a header size of zero.
You can specify the size of each element. Remember that the first three bytes of every element in an element array are the element's
RefElementHeader
; structure, which contains the reference count; leave room for this when you choose a size. For arrays with variable-sized elements, pass a size of zero.
Include: chunkarr.h
Tips and Tricks: You may want to declare a structure for array elements; the first component should be a
RefElementHeader
. You can pass the size of this structure to
ElementArrayCreate()
.
If you want extra space after the
ElementArrayHeader
, you may want to create your own header structure, the first element of which is an
ElementArrayHeader
. You can pass the size of this header to
ElementArrayCreate()
, and access the data in your header via the structure.
Be Sure To: Lock the block on the global heap before calling this routine (unless it is fixed). If you pass a header size, make sure it is larger than
sizeof(ElementArrayHeader)
.
ChunkHandle ElementArrayCreateAt( optr arr, /* optr of chunk for array */ word elementSize, /* Size of each element, or zero * for variable-sized */
word headerSize); /* Header size (zero for default) */
This routine is just like
ElementArrayCreate()
above, except that the element array is created in a pre-existing chunk. The contents of that chunk will be overwritten.
Include: chunkarr.h
Warnings: If the chunk isn't large enough, it will be resized. This will invalidate all pointers to chunks in that block.
ChunkHandle ElementArrayCreateAtHandles( MemHandle mh, /* Handle of LMem heap */ ChunkHandle ch /* Create array in this chunk */ word elementSize, /* Size of each element, or zero * for variable-sized */
word headerSize); /* Header size (zero for default) */
This routine is exactly like
ElementArrayCreateAt()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
Warnings: If the chunk isn't large enough, it will be resized. This will invalidate all pointers to chunks in that block.
void ElementArrayDelete( optr arr, /* optr to element array */ word token); /* index of element to delete */
This routine deletes an element from an element array regardless of its reference count. The routine is passed the element array's optr and the token for the element to delete.
Note that when an element is removed, it is actually resized down to zero size and added to a list of free elements. That way the index numbers of later elements are preserved.
Include: chunkarr.h
Be Sure To: Lock the block on the global heap before calling (unless it is fixed).
See Also: ElementArrayRemoveReference()
.
void ElementArrayDeleteHandles( MemHandle mh, /* Handle of LMem heap */ ChunkHandle ch, /* Chunk handle of element array */ word token); /* Index of element delete */
This routine is exactly like
ElementArrayDelete()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
Be Sure To: Lock the block on the global heap before calling (unless it is fixed).
See Also: ElementArrayRemoveReference()
.
void ElementArrayElementChanged( optr arr, /* optr to element array */ word token, /* Index number of element */ dword callbackData, /* This is passed along to callback */ Boolean _pascal (*callback) /* Returns true if elements identical */ (void * elementChanged, void * elementToCompare, dword valueForCallback));
This routine checks to see if an element is identical to any other elements in the same element array. This is used after an element has changed to see if it now matches another element. If the element matches another, it will be deleted, and the other element will have its reference count incremented.
The routine is passed an optr to the element array, the token of the element which is being checked, a dword of data (which is passed to the callback routine), and a pointer to a callback comparison routine. The callback routine itself is passed pointers to two elements and the
callbackData
argument passed to
ElementArrayElementChanged()
. The callback routine should be declared _pascal. If the two elements are identical, the callback should return
true
(i.e. non-zero); otherwise, it should return
false
.
If you pass a null function pointer,
ElementArrayElementChanged()
will do a bytewise comparison of the elements.
Include: chunkarr.h
void ElementArrayElementChangedHandles( MemHandle memHandle, /* Handle of LMem heap's block */ ChunkHandle chunkHandle, /* Chunk handle of element array */ word token, /* Index number of element */ dword callbackData, /* This is passed along to * callback */
Boolean _pascal (*callback) /* Returns true if elements identical */ (void * elementChanged, void * elementToCompare, dword valueForCallback));
This routine is exactly like
ElementArrayElementChanged()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
word ElementArrayGetUsedCount( optr arr, /* optr to element array */ dword callbackData, /* This is passed to callback routine */ Boolean _pascal (*callback) /* return true to count this element */ (void * element, dword cbData));
This routine counts the number of active elements in an element array; that is, elements which have a reference count of one or greater. It can be instructed to count every element, or every element which matches certain criteria. The routine is passed three parameters: the optr of the chunk array, a dword which is passed to the callback routine, and a callback routine which determines whether the element should be counted. The callback routine,which should be declared _pascal, is passed the dword an a pointer to an element. It should return true if the element should be counted; otherwise, it should return false . To count every element, pass a null callback pointer.
Include: chunkarr.h
See Also: ElementArrayTokenToUsedIndex()
,
ElementArrayUsedIndexToToken()
.
void ElementArrayGetUsedCountHandles( MemHandle mh, /* Handle of LMem heap's block */ ChunkHandle ch, /* Chunk handle of element array */ dword callbackData, /* This is passed to callback routine */ Boolean _pascal (*callback) /* return true to count this element */ (void * element, dword cbData));
This routine is exactly like
ElementArrayGetUsedCount()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
void ElementArrayRemoveReference( optr arr, /* optr of element array */ word token, /* Index of element to * unreference */
dword callbackData, /* Passed to callback routine */ void _pascal (*callback) (void *element, dword valueForCallback)); /* Routine is called if element is actually removed */
This routine decrements the reference count of the specified element. If the reference count drops to zero, the element will be removed. If an element is to be removed,
ElementArrayRemoveReference()
calls the callback routine on that element. The callback routine should perform any cleanup necessary; it is passed a pointer to the element and the
callbackData
argument. If you pass a null function pointer, no callback routine will be called.
Note that when an element is removed, it is actually resized down to zero size and added to a list of free elements. That way the index numbers of later elements are preserved.
Be Sure To: Lock the block on the global heap before calling (unless it is fixed).
See Also: ElementArrayDelete()
.
Include: chunkarr.h
void ElementArrayRemoveReferenceHandles( MemHandle mh, /* Handle of LMem heap */ ChunkHandle ch, /* Chunk handle of element array */ word token, /* Index of element to unreference */ dword callbackData, /* Passed to callback routine */ void _pascal (*callback) (void *element, dword valueForCallback)); /* Routine is called if element is actually removed */
This routine is exactly like
ElementArrayRemoveReference()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
word ElementArrayTokenToUsedIndex( optr arr, /* Handle of element array */ word token, /* Index of element to unreference */ dword callbackData, /* Data passed to callback routine */ Boolean _pascal (*callback) /* Return true to count this element */ (void *element, dword cbData));
This routine is passed the token of an element array. It translates the token into an index from some non-standard indexing scheme. The indexing scheme can either number the elements from zero, counting only those elements in use (i.e. those with a reference count greater than zero); or it can use a more restrictive scheme. If a callback routine is passed, the callback routine will be called for every used element; it should be declared _pascal and return true if the element should be counted. If a null callback pointer is passed, every used element will be counted.
Include: chunkarr.h
word ElementArrayTokenToUsedIndexHandles( MemHandle mh, /* Handle of LMem heap */ ChunkHandle ch, /* Chunk handle of element array */ word token, /* Index of element to unreference */ dword callbackData, /* Data passed to the * callback routine */
Boolean _pascal (*callback) /* Return true to count this element */ (void *element, dword cbData));
This routine is exactly like
ElementArrayTokenToUsedIndex()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
word ElementArrayUsedIndexToToken( optr arr, /* optr to element array */ word index, /* Find token of element with this index */ dword callbackData, /* This is passed to the callback routine */ Boolean _pascal (*callback) /* Return true to count this element */ (void *element, dword cbData));
This routine takes an index into an element array from some non-standard indexing scheme. The routine finds the element specified and returns the element's token. The indexing scheme can either number the elements from zero, counting only those elements in use (i.e. those with a reference count greater than zero); or it can use a more restrictive scheme. If a callback routine is passed, the callback routine will be called for every used element; it should should be declared _pascal return true if the element should be counted. If a null callback pointer is passed, every used element will be counted.
If no matching element is found,
ElementArrayUsedIndexToToken()
returns CA_NULL_ELEMENT.
Include: chunkarr.h
word ElementArrayUsedIndexToTokenHandles( MemHandle mh, /* Handle of LMem heap's block */ ChunkHandle ch, /* Handle of element array */ word index, /* Find token of element with this index */ dword callbackData, /* Data passed to the * callback routine */
Boolean _pascal (*callback) /* Return true to count this element */ (void *element, dword cbData));
This routine is exactly like
ElementArrayUsedIndexToToken()
above, except that the element array is specified by its global and chunk handles (instead of with an optr).
Include: chunkarr.h
void FatalError( word errorCode);
This routine causes a fatal error, leaving
errorCode
for the debugger.
word FileClose( /* returns error */ FileHandle fh, /* File to close */ Boolean noErrorFlag); /* Set if app. can't handle * errors */
This routine closes an open byte file. If the routine succeeds, it returns zero. If the routine fails and
noErrorFlag
is
false
(i.e., zero),
FileClose()
returns a member of the
FileError
enumerated type. If the routine fails and
noErrorFlag
is
true
(i.e., non-zero), the routine will fatal-error.
Warnings: The
noErrorFlag
parameter should be
true
only during debugging.
Include: file.h
word FileCommit( /* returns error */ FileHandle fh, Boolean noErrorFlag); /* set if can't handle errors */
FileCommit()
forces the file system to write any cached information about a file to the disk immediately. If it is successful, it returns zero. If it fails, it returns an error code. If the routine fails and
noErrorFlag
is
true
(i.e. non-zero), the routine will fatal-error.
Warnings: The
noErrorFlag
parameter should be
true
only during debugging.
Include: file.h
DiskHandle FileConstructFullPath( char * * buffer, /* Path string is written here */ word bufSize, /* Length of buffer (in bytes) */ DiskHandle disk, /* Disk or standard path; null for * current path */
const char * tail, /* Path relative to handle */ Boolean addDriveLetter); /* Should path begin with drive * name? */
This routine translates a GEOS directory specification into a complete path string. It writes the string into the passed buffer. The directory is specified by two arguments: The first,
disk
, is the handle of a disk; this may also be a standard path constant. (If a null handle is passed, the current working directory is used.) The second,
tail
, is a pointer to the character string representing the tail end of the path.
FileConstructFullPath()
appends this relative path to the location indicated by the disk handle. It then constructs a full path string, beginning with that disk's root directory, and writes it to the buffer passed. If
addDriveName
is
true
(i.e. non-zero), the path string will begin with the drive's name and a colon. The pointer pointed to by
buffer
will be updated to point to the end of the constructed string.
Examples: The following call to
FileConstructFullPath()
might yield these results:
Sample call to FileConstructFullPath()
/* Here we find out the full path of a subdirectory of the DOCUMENT directory */
DiskHandle documentDisk; char pathBuffer[256]; /* long enough for most paths */ char *pB = &pathBuffer;
documentDisk = FileConstructFullPath(&pB, /* pointer to pointer */ 256, /* Length of buffer */ SP_DOCUMENT, /* This can be a disk or * standard path */ "MEMOS\\JANUARY", /* In C strings, the * backslash must be * doubled */ TRUE); /* Prepend drive name */
/* If the standard paths are set up in the default configuration, "documentDisk" * would be the handle of the main hard drive, and pathBuffer would contain a * string like "C:\GEOWORKS\DOCUMENT\MEMOS\JANUARY" */
See Also: FileParseStandardPath()
.
Include: file.h
word FileCopy( /* returns error */ const char * source, /* Source path and file name */ const char * dest, /* Destination path and file name */ DiskHandle sourceDisk, /* These handles may be Standard */ DiskHandle destDisk); /* Path constants, or null to indi- * cate current working directory */
This routine makes a copy of a file. The source and destination are specified with path strings. Each string specifies a path relative to the location specified by the corresponding disk handle. If the handle is a disk handle, the path is relative to that disk's root. If the disk handle is a standard path constant, the path string is relative to that standard path. If the disk handle is null, the path is relative to the current working directory.
If
FileCopy()
is successful, it returns zero. Otherwise, it returns one of the following error codes:
See Also: FileMove()
.
Include: file.h
FileHandle FileCreate( /* sets thread's error value */ const char * name, /* relative to working directory */ FileCreateFlags flags, /* see below */ FileAttrs attributes); /* FileAttrs of new file */
This routine creates a byte file. The file may be a DOS file or a GEOS byte file. If the file is successfully opened,
FileCreate()
will return the file's handle; otherwise, it will return a null handle and set the thread's error value.
The second parameter is a word-length
FileCreateFlags
record. The third parameter,
attributes
, describes the
FileAttrs
record to be set for the new file.
If successful,
FileCreate()
returns the file's handle. If it is unsuccessful, it returns a null handle and sets the thread's error value (accessible via
ThreadGetError()
). The following error values are commonly returned:
FileCreate()
will fail until a file is closed.
FileCreate()
was called with FILE_CREATE_ONLY and a file with the specified name already exists.
FileCreate()
was called with FILE_CREATE_TRUNCATE or FILE_CREATE_NO_TRUNCATE and a file exists in a different format than desired; i.e. you passed FCF_NATIVE and the file already exists in the GEOS format, or vice versa.Examples: An example of usage is shown below.
Example of FileCreate() usage
/* Here we create a DOS file in the current working directory. If the file already * exists, we open the existing file and truncate it. */
FileHandle newFile;
newFile = FileCreate("NEWFILE.TXT", ( (FILE_CREATE_TRUNCATE | FCF_NATIVE) | (FILE_ACCESS_RW | FILE_DENY_RW)), 0); /* set no attribute bits */
See Also: FileCreateTempFile()
,
FileOpen()
.
Include: file.h
word FileCreateDir( /* Returns error & sets thread's error value */ const char * name); /* Relative path of new directory */
This routine creates a new directory. The parameter is a path string; the path is relative to the current directory. The last element of the path string must be the directory to create.
If
FileCreateDir()
is successful, it returns zero and clears the thread's error value. Otherwise, it returns an error code and sets the thread's error value (accessible via
ThreadGetError()
). The following errors are returned:
FileCreateDir()
to create the directory within a directory which does not exist.
See Also: FileDeleteDir()
.
Include: file.h
FileHandle FileCreateTempFile( /* Sets thread's error value */ char * dir, /* directory, relative to working dir.; * file name replaces 14 trailing null * characters upon return */
FileCreateFlags flags, FileAttrs attributes);
This routine creates and opens a temporary file in the directory specified. The routine automatically selects a name for the temporary file. No creation flags are needed, since the file will definitely be created anew and will be used only by this geode. The directory string must end with fourteen null bytes (enough to be replaced by the new file's name).
If
FileCreateTempFile()
is successful, it returns the file's handle as well as the string passed in
dir
, with the trailing null characters replaced by the file name. If it is unsuccessful, it returns a null handle and sets the thread's error value to a member of the
FileError
enumerated type. (This error value is accessible via
ThreadGetError()
.)
Tips and Tricks: Temporary files are usually created in a subdirectory of SP_PRIVATE_DATA.
See Also: FileCreate()
.
Include: file.h
word FileDelete( /* returns error */ const char * name); /* path relative to working directory */
This routine deletes a file. If it is successful, it returns zero; otherwise, it returns a
FileError
. Common errors include:
Include: file.h
word FileDeleteDir( /* Returns error & sets thread's error value */ const char * name); /* Relative path of directory to delete */
This argument deletes an existing directory. The parameter is a string which specifies the directory's position relative to the current working directory. The last element of the path string must be the name of the directory to delete.
If
FileDeleteDir()
is successful, it returns zero and clears the thread's error value. Otherwise, it returns an error code and sets the thread's error value (accessible via
ThreadGetError()
). The following errors are returned:
See Also: FileCreateDir()
.
Include: file.h
FileHandle FileDuplicateHandle( /* Sets thread's error value */ FileHandle fh);
This routine duplicates the handle of an open file and returns the duplicate handle. The duplicate handle has the same read/write position as the original. Both handles will have to be closed for the file to be closed. If there is an error,
FileDuplicateHandle()
returns a null handle and sets the thread's error value (accessible via
ThreadGetError()
).
Include: file.h
word FileEnum( /* returns number of files returned */ FileEnumParams * params, /* described below */ MemHandle * bufCreated, /* FileEnum will allocate a return- * buffer block & write its handle * here */
word * numNoFit); /* Number of files not handled is * written here */
This routine is used to examine all the files in a directory. The routine can filter the files by whether they have certain extended attributes. It creates a buffer and writes information about the files in this buffer. This routine can be called in many different ways; full details are available.
Structures:
FileEnum()
uses several structures and enumerated types. They are shown below; the detailed description of the structures follows.
/* Types, values, and structures passed * to the FileEnum() routine: */
typedef enum /* word */ { FESRT_COUNT_ONLY, FESRT_DOS_INFO, FESRT_NAME, FESRT_NAME_AND_ATTR
} FileEnumStandardReturnType; typedef enum /* word */ { FESC_WILDCARD
} FileEnumStandardCallback; /* Types, values, and structures returned * by the FileEnum() routine: */
typedef struct { FileAttrs DFIS_attributes; FileDateAndTime DFIS_modTimeDate; dword DFIS_fileSize; FileLongName DFIS_name; DirPathInfo DFIS_pathInfo;
} FEDosInfo; typedef struct _FileEnumCallbackData { FileExtAttrDesc FECD_attrs[1];
} FileEnumCallbackData; typedef struct _FileEnumParams { FileEnumSearchFlags FEP_searchFlags; FileExtAttrDesc * FEP_returnAttrs; word FEP_returnSize; FileExtAttrDesc * FEP_matchAttrs; word FEP_bufSize; word FEP_skipCount; word _pascal (*FEP_callback) (struct _FileEnumParams *params, FileEnumCallbackData *fecd, word frame); FileExtAttrDesc * FEP_callbackAttrs; dword FEP_cbData1; dword FEP_cbData2; word FEP_headerSize;
} FileEnumParams;
Most of the information passed to
FileEnum()
is contained in a
FileEnumParams
structure. The fields of the structure are as follows:
FEP_searchFlags
FileEnumSearchFlags
(described below). These flags specify which files at the current location will be examined by
FileEnum()
. They also specify such things as whether a callback routine should be used.
FEP_returnAttrs
FileExtAttrDesc
structures. The last structure should have its
FEA_attr
field set to FEA_END_OF_LIST. The array specifies what information will be returned by
FileEnum()
. The
FileExtAttrDesc
structure is used in a slightly different way than usual. Every file will have an entry in the return buffer; this entry will contain all the extended attribute information requested. Each
FileExtAttrDesc
structure will specify where in that entry its information should be written. The
FEAD_value
field should contain only an offset value; the extended attribute will be written at that offset into the entry. (You can specify an offset by casting an integer value to type
void *
.) The
FEAD_size
value specifies how long the return value can be. You can also request certain return values by setting
FEP_returnAttrs
to equal a member of the
FileEnumStandardReturnType
(again, by casting the
FileEnumStandardReturnType
value to type
void *
). The
FileEnumStandardReturnType
enumerated type is described later in this section.
FEP_returnSize
FileExtAttrDesc
structures was passed, each entry in the returned buffer will contain all the extended attribute information requested for that file.
FEP_matchAttrs
FileExtAttrDesc
structures. The last structure should have its
FEA_attr
field set to FEA_END_OF_LIST.
FileEnum()
will automatically filter out and ignore all files whose attributes do not match the ones specified by this array. For attributes that are word-sized records,
FEAD_value.offset
holds the bits that must be set, and
FEAD_value.segment
holds the bits that must be clear. For byte-sized flags,
FEAD_value.offset.low
contains the flags that must be set, and
FEAD_value.offset.high
contains flags that must be clear. Byte- and word-sized non-flag values are stored in
FEAD_value.offset
. For all other values,
FEAD_value
holds a pointer to the exact value to match, and
FEAD_size
specifies the length of that value (in bytes). If you do not want to filter out any files in the working directory, or if you will use the callback routine to filter the files, pass a null pointer in this field.
FEP_bufS
FEP_skipCount
FEP_bufSize
to examine many files a few at a time. For example, if you only wanted to examine ten files at a time, you would set
FEP_bufSize
to ten and
FEP_skipCount
to zero.
FileEnum()
would return the data for the first ten files which match the search criteria. After processing the returned data, if there were any files left over, you could call
FileEnum()
again, this time with
FEP_skipCount
set to ten;
FileEnum()
would handle the next ten matching files and return the data about them. In this way you could walk through all the matching files in the directory. Note that if the
FileEnumSearchFlags
bit FESF_REAL_SKIP is set (in FEP
_searchFlags
), the first files in the directory will be skipped
before
they are tested to see if they match. This is faster, since the match condition won't have to be checked for the first files in the directory.
FEP_callback
FileEnumParams
structure, a pointer to the current stack frame (which is used by some assembly callback routines), and a pointer to an array of
FileExtAttrDesc
structures. These structures are all the attributes required either for return, matching, or callback (see FEP
_callbackAttrs
below), with the information for the current file filled in; you can search through them directly for the information you want, or you can call
FileEnumLocateAttr()
to search through this array. If the file should be accepted by
FileEnum()
, the callback should return
true
; otherwise it should return
false
. You can also instruct
FileEnum()
to use one of the standard callback routines by passing a member of the
FileEnumStandardCallback
enumerated type. In this case,
FEP_callbackAttrs
is ignored;
FileEnum()
will automatically pass the appropriate information to the callback routine. (Note that if the FESF_CALLBACK bit of the
FEP_searchFlags
field is not set, the
FEP_callback
field is ignored.)
FEP_callbackAttrs
FileExtAttrDesc
structures. The last structure should have its
FEA_attr
field set to FEA_END_OF_LIST. The array will be filled in with the appropriate information for each file before the callback routine is called. Note that if the FESF_CALLBACK bit of the
FEP_searchFlags
is not set, the
FEP_callbackAttrs
is ignored. If you do not need any attributes passed to the callback routine, set this field to be a null pointer.
FEP_cbData1
,
FEP_cbData2
FileEnum()
; they are used to pass information to the callback routine. If you do not call a standard callback routine, you may use these fields any way you wish.
FEP_headerSize
FileEnum()
will leave an empty header space at the beginning of the return buffer. The size of the header is specified by this field. If FESF_LEAVE_HEADER is clear, this field is ignored.
The first field of the
FileEnumParams
structure,
FEP_searchFlags
, is a word-length record containing
FileEnumSearchFlags
. The following flags are available:
FileEnum()
.
FileEnum()
.
FileEnum()
.
FileEnum()
.
FileEnum()
will return the number of files passed through in order to get enough files to fill the buffer; the return value can thus be the real-skip count for the next pass.
FileEnum()
should call a callback routine to determine whether a file should be accepted.
FileEnumParams
fields
FEP_callback1
and
FEP_callback2
are far pointers to movable memory that must be locked before
FileEnum()
is called.
FileEnum()
should leave an empty header space at the start of the return buffer. The size of this buffer is specified by the
FEP_headerSize
field.
The
FileEnumStandardReturnType
enumerated type has the following values; they are used in conjunction with the
FEP_returnAttrs
field of the
FileEnumParams
structure.
FileEnum()
will not allocate any memory and will not return data about files; instead, it will simply return the number of files which match the specified criteria.
FileEnum()
will return an array of
FEDosInfo
structures. These structures contain basic information about the file: its virtual name, size, modification date, DOS attributes, and path information (as a
DirPathInfo
record).
FileEnum()
will return an array of
FileLongName
strings, each one of which is FILE_LONGNAME_BUFFER_SIZE characters long; every one of these will contain a file's virtual name followed by a null terminator.
FileEnum()
will return an array of
FENameAndAttr
structures, each one of which contains a file's DOS attributes and virtual name.
The
FEDosInfo
structure includes a word-sized record (
DFIS_pathInfo
) which describes the file's position relative to the standard paths. It contains the following fields:
StandardPath
constant for a standard path containing the file. This need not be the "closest" standard path; for example, if the file is in the "World" directory, this constant might nevertheless be SP_TOP.
See Also: FileEnumLocateAttr()
,
FileEnumWildcard()
.
Include: fileEnum.h
void * FileEnumLocateAttr( /* returns NULL if attr not found */ FileEnumCallbackData* fecd, /* Passed to callback routine */ FileExtendedAttribute attr, /* Search for this attribute */ const char * * name); /* Attribute name (if second * argument is FEA_CUSTOM) */
FileEnum()
can be instructed to call a callback routine to decide which files to filter out. This callback routine is passed an array of
FileExtAttrDesc
structures. To find a particular extended attribute in this array, call
FileEnumLocateAttr()
. This routine will find the address of the value of the attribute desired, and return that address. If the attribute is not in the array,
FileEnumLocateAttr()
will return a null pointer.
Include: fileEnum.h
Boolean FileEnumWildcard( FileEnumCallbackData * fecd, /* Passed to callback routine */ word frame); /* Inherited stack frame */
This routine is a utility used by
FileEnum()
and is rarely used by applications. It checks to see if the virtual name of the current file (the file currently being evaluated by
FileEnum()
) matches the pattern in the
FEP_cbData1
field of the
FileEnumParams
structure.
The
fecd
parameter is a pointer to the callback data of the
FileEnum()
routine. The frame parameter is a pointer to the
FileEnum()
stack frame: The first dword is the
FEP_cbData1
field, and the second is the
FEP_cbData2
field.
This routine returns
true
(non-zero) if the file name and pattern match. Otherwise, it returns
false
.
Include: fileEnum.h
VMFileHandle FileFromTransferBlockID(id); TransferBlockID id;
This macro extracts a VMFileHandle from a value of type
TransferBlockID
.
FileAttrs FileGetAttributes( /* Sets thread's error value */ const char * path); /* file's path relative to current * working directory */
This routine returns the standard
FileAttrs
attributes for a file. The file may be a GEOS file or a plain DOS file. Note that you can also get a file's attributes by getting the file's FEA_FILE_ATTR extended attribute. If an error occurs, this routine sets the thread's error (accessible via
ThreadGetError()
).
See Also: FileAttrs
,
FileSetAttributes()
.
Include: file.h
DiskHandle FileGetCurrentPath( char * buffer, /* Path string is written here */ word bufferSize); /* Size of buffer in bytes */
This routine writes the current path string (without drive specifier) to the buffer provided. If the buffer is too small, it truncates the path to fit. It returns the handle of the disk containing the current path. If the current path was declared relative to a standard path, the standard path constant will be returned.
Include: file.h
FileDateAndTime
FileGetDateAndTime( /* sets thread's error value */
FileHandle fh);
This routine finds out the time a file was last modified. This routine can be called on GEOS or non-GEOS files. Note that you can also find out the modification time of a file by checking the extended attribute FEA_MODIFICATION. If unsuccessful, it sets the thread's error value (accessible via
ThreadGetError()
).
See Also: FileDateAndTime
,
FileSetDateAndTime()
.
Include: file.h
DiskHandle FileGetDiskHandle( /* sets thread's error value */ FileHandle fh);
This routine returns the handle of the disk containing an open file. If unsuccessful, it sets the thread's error value (accessible via
ThreadGetError()
).
Include: file.h
word FileGetHandleExtAttributes( FileHandle fh, /* open file's handle */ FileExtendedAttribute attr, /* attribute to get */ void * buffer, /* attribute is written here */ word bufSize); /* length of buffer in bytes */
This routine gets one or more extended attributes of an open file. (To get the attributes of a file without opening it, call
FileGetPathExtAttributes()
.) If a single attribute is requested, the attribute will be written in the buffer passed. If several attributes are requested,
attr
should be set to FEA_MULTIPLE, and
buffer
should point to an array of
FileExtAttrDesc
structures. In this case,
bufSize
should be the number of structures in the buffer, not the length of the buffer.
If
FileGetHandleExtAttributes()
is successful, it returns zero. Otherwise, it returns one of the following error codes:
Tips and Tricks: Note that the only way to recover a custom attribute is by passing FEA_MULTIPLE, and using a
FileExtAttrDesc
to describe the attribute.
See Also: FileGetPathExtAttributes()
.
Include: file.h
word FileGetPathExtAttributes( const char * path, /* path relative to current * working directory */
FileExtendedAttribute attr, /* attribute to get */ void * buffer, /* attribute is written here */ word bufSize); /* length of buffer in bytes */
This routine gets one or more extended attributes of a GEOS file. If a single attribute is requested, the attribute will be written in the buffer passed. If several attributes are requested,
attr
should be set to FEA_MULTIPLE, and
buffer
should point to an array of
FileExtAttrDesc
structures. In this case,
bufSize
should be the number of structures in the buffer, not the length of the buffer.
If
FileGetPathExtAttributes()
is successful, it returns zero. Otherwise, it returns one of the following error codes:
Tips and Tricks: Note that the only way to recover a custom attribute is by passing FEA_MULTIPLE, and using a
FileExtAttrDesc
to describe the attribute.
See Also: FileGetHandleExtAttributes()
.
Include: file.h
word FileLockRecord( /* returns error */ FileHandle fh, dword filePos, /* lock starting at this position... */ dword regLength); /* lock this many bytes */
This routine puts a lock on a part of a byte file. It first checks to make sure that there are no locks that overlap the region specified; if there are, it will fail and return ERROR_ALREADY_LOCKED. If there are no locks, it will place a lock on the region specified and return zero.
Warnings: Locking a region only prevents threads from locking part of the same region; it does not prevent them from reading from or writing to the region. If applications use this mechanism, they have to make sure to call
FileLockRecord
before trying to access a part of a file.
See Also: FileUnlockRecord()
,
HandleP()
.
word FileMove( /* Returns error */ const char * source, /* source path and file name */ const char * dest, /* destination path and file name */ DiskHandle sourceDisk, /* These handles may be Standard */ DiskHandle destDisk); /* Path constants, or null to indi- * cate current working directory */
This routine moves a file from one location to another. The source and destination are specified with path strings. Each string specifies a path relative to the location specified by the corresponding disk handle. If the handle is a disk handle, the path is relative to that disk's root. If the disk handle is a standard path constant, the path string is relative to that standard path. If the disk handle is null, the path is relative to the current working directory.
If
FileMove()
is successful, it returns zero. Otherwise, it returns one of the following error codes and sets the thread's error value.
See Also: FileCopy()
.
Include: file.h
FileHandle FileOpen( /* sets thread's error value */ const char * name, /* relative to working dir */ FileAccessFlags flags); /* Permissions/exclusions */
This routine opens a file for bytewise access. The file may be a DOS file or a GEOS byte file. If the file is successfully opened,
FileOpen()
will return the file's handle; otherwise, it will return a null handle and set the thread's error value (accessible via
ThreadGetError()
). Errors typically set by this routine are listed below:
FileOpen()
will fail until a file is closed.
See Also: FileCreate()
,
FileAccessFlags
.
Include: file.h
StandardPath FileParseStandardPath( DiskHandle disk, const char ** path);
This routine is passed a full path (relative to the passed disk or a standard path, if the disk handle is null) and finds the standard path which most closely contains that path. It updates the pointer whose address is passed so that it points to the trailing portion of the path string. For example, if you pass the path string "\GEOWORKS\DOCUMENT\MEMOS\APRIL", the pointer would be updated to point to the "\MEMOS\APRIL" portion, and the
StandardPath
SP_DOCUMENT would be returned. If the path passed does not belong to a standard path, the constant SP_NOT_STANDARD_PATH will be returned, and the pointer will not be changed.
Include: file.h
void FilePopDir();
FilePopDir()
pops the top directory off the thread's directory stack and makes it the current working directory.
See Also: FilePushDir()
.
Include: file.h
dword FilePos( /* Sets thread's error value */ FileHandle fh, dword posOrOffset, FilePosMode mode);
This routine changes the current file position. The position can be specified in three ways, depending on the value of the mode argument:
FilePos()
returns a 32-bit integer. This integer specifies the absolute file position after the move (relative to the start of the file). On an error, it sets the thread's error value (accessible via
ThreadGetError()
).
Tips and Tricks: To find out the current file position without changing it, call
FilePos()
with mode FILE_POS_RELATIVE and offset zero.
Include: file.h
void FilePushDir();
FilePushDir()
pushes the current working directory onto the thread's directory stack. It does not change the current working directory.
See Also: FilePopDir()
.
Include: file.h
word FileRead( FileHandle fh, /* handle of open file */ void * buf, /* copy data to this buffer */ word count, /* Length of buffer (in bytes) */ Boolean noErrorFlag); /* Set if app can't * handle errors */
This routine copies data from a file into memory. It starts copying from the current position in the file. If possible, it will copy enough data to fill the buffer. If
FileRead()
is successful, it returns the number of bytes copied. If an error occurs,
FileRead()
returns -1 and sets the thread's error value (usually to ERROR_ACCESS_DENIED). The current file position will be changed to the first byte after the ones which were read.
In C, there is no way to determine whether an ERROR_SHORT_READ_WRITE error occurs. To check whether all of the data was actually copied into memory, you must compare the number of bytes actually read with the number requested to be read. If your read operation requires multiple
FileRead()
operations, you may should read until zero bytes are returned.
To retrieve the thread error value, use
ThreadGetError()
.
If the argument
noErrorFlag
is set to
true
(i.e. non-zero),
FileRead()
will fatal-error if an error occurs (including an ERROR_SHORT_READ_WRITE).
Warnings: Pass
noErrorFlag
true
only during debugging.
Include: file.h
word FileRename( const char * oldName, /* Relative to working directory */ const char * newName); /* Name only, without path */
This routine changes a file's name. It cannot move a file to a different directory; to do that, call
FileMove()
. If the routine is successful, it returns zero; otherwise, it returns a
FileError
. Common errors include
See Also: FileMove()
.
Include: file.h
DiskHandle FileResolveStandardPath( char ** buffer, /* Write path here; update pointer * to point to end of path */
word bufSize, /* Size of buffer (in bytes) */ const char * path, /* Relative path of file */ FileResolveStandardPathFlags flags, /* Flags are described below */ FileAttrs *attrsPtr); /* Empty buffer, will be filled with attrs of passed file, if any */
This routine finds a file relative to the current location, then writes the full path to the file, starting at the root of the disk ( not at a standard path). It writes the path to the passed buffer, updating the pointer to point to the null at the end of the path string; it also returns the handle of the disk. If it cannot find the file it returns a null path.
Structures: A record of
FileResolveStandardPathFlags
is passed to
FileResolveStandardPath()
. The following flags are available:
FileResolveStandardPath()
should not check whether the passed path actually exists; instead, it should assume that the path exists in the first directory comprising the standard path, and return accordingly.Include: file.h
word
FileSetAttributes( /* returns error value */
const char * path, /* file's path relative to current
* working directory */
FileAttrs attr); /* new attributes for the file */
This routine changes the standard DOS attributes of a DOS or GEOS file. Note that you can also change the attributes of a file by setting the extended attribute FEA_FILE_ATTR.
See Also: FileAttrs
,
FileGetAttributes()
.
Include: file.h
DiskHandle FileSetCurrentPath( DiskHandle disk, /* May be a standard path constant */ const char * path); /* path string, null-terminated */
This routine changes the current path. It is passed two parameters: The first is the handle of the disk containing the new current path (this may be a standard path constant). The second is a null-terminated path string. It is specified with normal DOS conventions: directories are separated by backslashes; a period (".") indicates the current directory; and a pair of periods ("..") indicates the parent of the current directory. The string may not contain wildcard characters.
If
disk
is a disk handle, the path is relative to the root directory of that disk; if
disk
is a standard path constant, the path is relative to the standard path; if it is null, the path is relative to the current working directory.
FileSetCurrentPath()
returns the disk handle associated with the new current path; this may be a standard path constant. If
FileSetCurrentPath()
fails, it returns a null handle.
See Also: FileSetStandardPath()
.
Include: file.h
word
FileSetDateAndTime( /* returns error */
FileHandle fh, /* handle of open file */
FileDateAndTime dateAndTime); /* new modification time */
This routine changes a file's last-modification time-stamp. This routine can be called on GEOS or non-GEOS files. Note that you can also change the modification time of a file by changing the extended attribute FEA_MODIFICATION. If unsuccessful, this routine returns an error and sets the thread's error value (accessible via
ThreadGetError()
).
See Also: FileDateAndTime
,
FileGetDateAndTime()
.
Include: file.h
word FileGetPathExtAttributes( /* returns error */ FileHandle fh, /* handle of open file */ FileExtendedAttribute attr, /* attribute to get */ const void * buffer, /* attribute is read from here */ word bufSize); /* length of buffer in bytes */
This routine sets one or more extended attributes of an open GEOS file. (To set the attributes of a file without opening it, call
FileSetPathExtAttributes()
.) If a single attribute is specified, the attribute's new value will be read from the buffer passed. If several attributes are to be changed,
attr
should be set to FEA_MULTIPLE, and
buffer
should point to an array of
FileExtAttrDesc
structures. In this case,
bufSize
should be the number of structures in the buffer, not the length of the buffer.
If
FileSetHandleExtAttributes()
is successful, it returns zero. Otherwise, it sets the thread's error value (accessible via
ThreadGetError()
) and returns one of the following error codes:
FileSet...()
routines.
Tips and Tricks: Note that the only way to create or change a custom attribute is by passing FEA_MULTIPLE, and using a
FileExtAttrDesc
to describe the attribute.
See Also: FileSetPathExtAttributes()
.
Include: file.h
word FileSetPathExtAttributes( const char * path, /* path relative to current * working directory */
FileExtendedAttribute attr, /* attribute to get */ const void * buffer, /* attribute is read from here */ word bufSize); /* length of buffer in bytes */
This routine sets one or more extended attributes of a file. If a single attribute is specified, the attribute will be written in the buffer passed. If several attributes are to be changed,
attr
should be set to FEA_MULTIPLE and
buffer
should point to an array of
FileExtAttrDesc
structures. In this case,
bufSize
should be the number of structures in the buffer, not the length of the buffer.
If
FileSetPathExtAttributes()
is successful, it returns zero. Otherwise, it sets the thread's error value (accessible via
ThreadGetError()
) and returns one of the following error codes:
FileSetPathExtAttributes()
returns this if any geode (including the caller) has the file open with "deny-write" exclusive access, or if the file is not writable.
FileSet...ExtAttributes()
routines.
Tips and Tricks: Note that the only way to create or change a custom attribute is by passing FEA_MULTIPLE, and using a
FileExtAttrDesc
to describe the attribute.
See Also: FileSetHandleExtAttributes()
.
Include: file.h
void FileSetStandardPath( StandardPath path); /* StandardPath to set */
This routine changes the current working directory to one of the system's StandardPath directories. Pass a standard path.
Include: file.h
dword FileSize( FileHandle fh); /* handle of open file */
This routine returns the size of the open file specified.
Include: file.h
word FileTruncate( FileHandle fh, /* handle of open file */ dword offset, /* offset at which to truncate */ Boolean noErrorFlag);
This routine truncates the specified file at the passed offset. The
offset
parameter can also be thought of as the desired file size. If the high bit of
noErrorFlag
is one, then no errors will be returned.
Include: file.h
word FileUnlockRecord( /* returns error */ FileHandle fh, /* handle of open file dword filePos, /* Release lock that starts here */ dword regLength); /* and is this long */
This routine releases a lock on a part of a byte-file. The lock must have been previously placed with
FileLockRecord()
.
See Also: FileLockRecord()
,
HandleV()
.
Include: file.h
word FileWrite( /* sets thread's error value */ FileHandle fh, /* handle of open file */ const void * buf, /* Copy from here into file */ word count, /* # of bytes to copy */ Boolean noErrorFlag); /* Set if can't handle errors */
This routine copies a specified number of bytes from a buffer to the file. The bytes are written starting with the current position in the file; any data already at that location will be overwritten.
FileWrite()
returns the number of bytes written. If
FileWrite()
could not write all the data (e.g. if the disk ran out of space), it will set the thread's error value (accessible via
ThreadGetError()
) to ERROR_SHORT_READ_WRITE and return the number of bytes that were written. If it could not write the data to the file at all (e.g. if you do not have write-access to the file), it will return -1 and set the thread's error value to ERROR_ACCESS_DENIED. In any event, the file position will be changed to the first byte after the ones written.
If the argument
noErrorFlag
is set to
true
(i.e. non-zero),
FileWrite()
will fatal-error if an error occurs.
Warnings: Pass
noErrorFlag
true
only during debugging.
Include: file.h
Boolean FloatAsciiToFloat( /* returns FALSE on success */ word floatAtoFflags, word stringLength, void *string, void *resultLocation);
This routine is used to convert an ASCII string to a floating point number. It takes the following arguments:
FloatAsciiToFloatFlags
field determines what will be done with the generated floating point number. At most one flag may be set. If FAF_PUSH_RESULT is set, then the number will be pushed on the floating-point stack. If the FAF_STORE_NUMBER flag is set, the number will be returned at the resultLocation address.word FloatFloatToAscii( /* returns # of chars in ASCII string */ FFA_stackFrame *stackFrame, char *resultString, FloatNum *number);
This routine converts a floating point number to an ASCII string. It uses a complicated data structure,
FFA_stackFrame
. To convert floating point numbers to ASCII without filling in this structure, use the
FloatFloatToAscii_StdFormat()
routine instead. Unless a special flag is passed, this routine will convert the top number of the floating point stack and pop it.
FloatFloatToAscii()
takes the following arguments:
FFA_stackFrame
structure. This structure contains a structure of parameters to
FloatFloatToAscii()
; also, the routine will return some information in this structure. The structure is discussed in detail below.If you pass the FFAF_FROM_ADDR flag, then instead of converting the number at the head of the floating-point stack, the routine will convert this number.
The routine explicitly returns the number of characters in the generated string, not counting the null terminator. It will return zero if an error occurred.
 When
FloatFloatToAscii()
returns, some of the other fields will have been filled in with potentially useful information:
FloatFloatToAsciiData
fields are internal.typedef struct { FloatFloatToAsciiFormatFlags formatFlags; byte decimalOffset; byte totalDigits; byte decimalLimit; char preNegative[SIGN_STR_LEN+1]; char postNegative[SIGN_STR_LEN+1]; char prePositive[SIGN_STR_LEN+1]; char postPositive[SIGN_STR_LEN+1]; char header[PAD_STR_LEN+1]; char trailer[PAD_STR_LEN+1]; byte FFTAP_unused; } FloatFloatToAsciiParams;
The
FloatFloatToAsciiParams
structure determines how
FloatFloatToAscii()
should format its generated string. It contains the following fields:
FloatFloatToAsciiFormatFlags
structure containing flags used to fine-tune the formatting.typedef WordFlags FloatFloatToAsciiFormatFlags; #define FFAF_FLOAT_RESERVED 0x8000 #define FFAF_FROM_ADDR 0x4000 #define FFAF_DONT_USE_SCIENTIFIC 0x0200 #define FFAF_SCIENTIFIC 0x0100 #define FFAF_PERCENT 0x0080 #define FFAF_USE_COMMAS 0x0040 #define FFAF_NO_TRAIL_ZEROS 0x0020 #define FFAF_NO_LEAD_ZERO 0x0010 #define FFAF_HEADER_PRESENT 0x0008 #define FFAF_TRAILER_PRESENT 0x0004 #define FFAF_SIGN_CHAR_TO_FOLLOW_HEADER 0x0002 #define FFAF_SIGN_CHAR_TO_PRECEDE_TRAILER 0x0001
The
FloatFloatToAsciiFormatFlags
field contains the following flags:
FloatFloatToAscii()
will convert the number at the top of the floating point stack. By passing this flag, you ask that the routine instead convert the number pointed to by its
number
argument.typedef struct { FloatFloatToDateTimeParams FFA_dateTimeParams; } FloatFloatToDateTimeData; typedef struct { FloatFloatToDateTimeFlags FFA_dateTimeFlags; word FFA_year; byte FFA_month; byte FFA_day; byte FFA_weekday; byte FFA_hours; byte FFA_minutes; byte FFA_seconds; } FloatFloatToDateTimeParams;
The
FloatFloatToDateTime
structure is used to pass and return information for the formatting of date and time strings.
FloatFloatToDateTimeFlags
field fine-tunes the way in which to format the date string.typedef WordFlags FloatFloatToDateTimeFlags; #define FFDT_DATE_TIME_OP 0x8000 #define FFDT_FROM_ADDR 0x4000 #define FFDT_FORMAT 0x3fff
The
FloatFloatToDateTimeFlags
field determines how the date/time should be formated.
DateTimeFormat
value.
See Also: FloatFloatToAscii_StdFormat()
.
word FloatFloatToAscii_StdFormat( char *string, FloatNum *number, FloatFloatToAsciiFormatFlags format, word numDigits, word numFractionalDigits)
This routine formats a floating point number as an ASCII string. It is similar in purpose to
FloatFloatToAscii()
. However, this routine does not require the use of the daunting
FFA_stackFrame
data structure. It has the following arguments:
FloatFloatToAsciiFormatFlags
. This data type is discussed under
FloatFloatToAscii()
. The following flags are permitted: FFAF_FROM_ADDR, FFAF_SCIENTIFIC, FFAFF_PERCENT, FFAF_USE_COMMAS, FFAF_NO_TRAIL_ZEROS.The routine returns the number of characters in the resulting string, or zero if there was an error.
See Also: FloatFloatToAscii()
.
FieldID FoamDBAddFieldToRecord( VMFileHandle file, MemHandle record, byte *fieldName, word fieldType);
Adds a field to the record record and gives it the name fieldName. A unique FieldID
is assigned to the new field and returned. The Foam Database uses the fieldType to determine the sort order of the records (i.e., a field of type "3" will be inserted after all the existing fields of type "3", but before the fields of type "4"). If you are using this routine within the context of a ContDB
, then fieldType should be one of the ContdbFieldType
values (see below). Otherwise, you may set your own field type.
/* * The standard field types in the contact database */ typedef ByteEnum ContdbFieldType; #define CFT_NAME 0 #define CFT_COMPANY 1 #define CFT_TITLE 2 #define CFT_ADDRESS 3 #define CFT_PHONE 4 #define CFT_FAX 5 #define CFT_EMAIL 6 #define CFT_DTMF 7 #define CFT_NOTES 8 /* Only available in Communicator products after Feb 1997: */ #define CFT_URL 9 #define CFT_PASSWORD 10 #define CFT_TEL_FAX 11 #define CFT_TEL_DATA 12
Include: foamdb.h
RecordID FoamDBBinarySearch( VMFileHandle file, MemHandle record, PCB(int, callback, (void * passedRecord, /* Callback routine */ void * curRecord )));
This routine performs a binary search of the Foam database file to determine the index of record. The database is sorted according to an application-defined callback routine, so FoamDBBinarySearch()
can find record in a divide-and-conquer method using a callback routine based on the same sorting scheme. If this routine finds record, it returns the RecordID
of this record in the database; otherwise, it returns where this record would belong in the database.
(PCB
is a GEOS macro that defines a callback routine.) The prototype for this callback routine should be of the form:
int _pascal MyCallBackRoutine(void * passedRecord, void * curRecord);The callback routine should return +1 if the record passedRecord comes after curRecord, -1 if passedRecord comes before curRecord, and 0 if the items match.
Include: foamdb.h
word FoamDBClose( VMFileHandle file);
Closes the file. It is the same as
VMClose()
.
If successful, returns non-zero; if an error occurred, then it returns FALSE
and the error value must be retrieved by
ThreadGetError().
Include: foamdb.h
MemHandle FoamDBCreateEmptyRecord( VMFileHandle file);
Creates a new record in the database, gives it a unique ID, and returns
the handle of the record data. This record will contain no fields or data.
This record does not get saved to the database unless
FoamDBSaveRecord()
is called.
Warning: If you want to free the memory associated with a record, do not use
MemFree()
;
instead call
FoamDBDiscardRecord()
to discard any record changes or
FoamDBSaveRecord()
to commit them to the the database.
Include: foamdb.h
void FoamDBDeleteFieldFromRecord( VMFileHandle file, MemHandle record, FieldID id); /* Field to delete */
Deletes field ID id from the record of the database file. id is the ID of the field as returned from
FoamDBAddFieldToRecord()
.
While it's not a pretty solution, you can also get the FieldID
of a field from the FH_id
part of the FieldHeader
struct.
Include: foamdb.h
Boolean FoamDBDeleteRecord( VMFileHandle file, MemHandle record); /* Record to terminated */
This routine frees up the record data in record, and, if the record exists in the database, deletes it from the database as well.
Returns non-zero if the record did not exist in the database.
Include: foamdb.h
void FoamDBDiscardRecord( VMFileHandle file, MemHandle record);
This routine discards any changes to the passed record record and frees up the record data stored in the passed handle, but does nothing to the data stored in the database file.
Include: foamdb.h
MemHandle FoamDBDuplicateRecord( VMFileHandle file, MemHandle record);
Duplicates an existing record record of FoamDB file, assigns a new ID to it, and returns the handle of the duplicate.
Warning: As with
FoamDBCreateEmptyRecord()
,
the record must eventually be saved or destroyed by calling
FoamDBDiscardRecord()
or
FoamDBSaveRecord()
.
Include: foamdb.h
Boolean FoamDBFieldEnum( MemHandle record, void *enumData, PCB(Boolean, callback, /* Non-zero to stop enum */ (FieldHeader *field, void *callbackEnumData))); /* Callback routine */
This routine essentially "walks" through each field in the specified record and invokes the specified callback routine for each field. enumData can point to the initial value of an application-defined buffer or data structure if one is used by the callback routine, otherwise it can be ignored. This pointer is passed to the callback routine.
The callback routine accepts two parameters; a pointer to the current field field, and some application-defined data callbackEnumData. callbackEnumData
may be used to store information between different calls to the callback
routine such as storing the longest string yet found or performing
complex filtering on the record (in which case callbackEnumData could
point to an array of field IDs gathered from the field pointer).
To end the enumeration before reaching the last field in the
record, return TRUE
(or any non-zero value) from the callback routine.
To use the callback routine:
/* * Prototype of callback routine */ Boolean _pascal ExampleCallback (FieldHeader *field, void *callbackEnumData); ... /* * Call FoamDBFieldEnum() */ ok = FoamDBFieldEnum(recordHandle, &someDataStruct, ExampleCallback);
See Also: FoamDBLockedRecordEnum()
.
Include: foamdb.h
RecordID FoamDBGetCurrentRecordID( VMFileHandle file);
Returns the RecordID
that would be set for the next record in the database file.
Include: foamdb.h
word FoamDBGetFieldData( VMFileHandle file, MemHandle record, FieldID id, char *dest, /* Buffer to store data */ word maxBytesToGet); /* # bytes of data */
Copies the data from the specified field of record into the buffer dest. maxBytesToGet specifies the maximum number of bytes to copy into the buffer.
Returns the number of bytes actually copied.
Warning: The standard and most efficient way to store string data is without a null terminator, so when working with string data be sure to use the returned data size.
Include: foamdb.h
Boolean FoamDBGetFieldName( VMFileHandle file, MemHandle record, FieldID id, TCHAR *dest, /* Buffer to put name (null-terminated) */ word maxBytesToGet); /* Number of characters to get */
Copies the name of the field ID id into the buffer dest.
Returns zero if field exists, non-zero if it doesn't.
Warning: Field names are null-terminated.
Include: foamdb.h
Boolean FoamDBGetFieldType( VMFileHandle file, MemHandle record, FieldID id, byte *type);
Gets the type of field ID id and puts it into type. Note that this type is a ContdbFieldType
.
Returns zero if field exists, non-zero if it does not.
Include: foamdb.h
dword FoamDBGetNextPrevRecord( VMFileHandle file, RecordID record, word count);
This routine returns the index into the huge array of a record count records away from the record with the RecordID
record. count can be negative or positive, so this routine lets you move forwards or backwards through the database. Should the requested record be invalid, either because there is no record with RecordID
record or the requested index is beyond the bounds of the database, this routine will return record.
Include: foamdb.h
dword FoamDBGetNumVisibleRecords( VMFileHandle file);
This routine returns the number of visible records in the database file. This is often used when providing a list of records to a user.
Include: foamdb.h
MemHandle FoamDBGetRecordFromID( VMFileHandle file, RecordID id);
This routine looks for a record in the database with the ID id, copies it
into memory, and returns the handle. If no record in the database had
the passed ID, this routine returns NullHandle
.
Warning:
The handle returned should be freed using
FoamDBDeleteRecord()
,
FoamDBDiscardRecord()
, or
FoamDBSaveRecord()
.
Include: foamdb.h
RecordID FoamDBGetRecordID( MemHandle record);
Given a record handle, returns the RecordID
of the record.
Include: foamdb.h
MemHandle FoamDBGetVisibleRecord( VMFileHandle file, dword index);
This routine finds the visible record with the index of index, copies the data into memory,
and returns the handle of the block to the caller. If index is out of bounds,
FoamDBGetVisibleRecord()
returns NullHandle.
Warning:
The handle returned should be freed using
FoamDBDeleteRecord()
,
FoamDBDiscardRecord()
, or
FoamDBSaveRecord().
Include: foamdb.h
Boolean FoamDBLockedRecordEnum( MemHandle record, void *enumData, PCB(Boolean, callback, /* Non-zero to stop enum */ (FieldHeader *field, void *callbackEnumData))); /* Callback routine */
This routine calls a callback routine for each field in a locked down record. The callback routine is used the same way as in
FoamDBFieldEnum()
.
It should be of the prototype
/* * Prototype of callback routine */ Boolean _pascal ExampleCallback (FieldHeader *field, void *callbackEnumData);
Include: foamdb.h
Boolean FoamDBMapNameToToken( VMFileHandle file, TCHAR *nameToLookFor, word *token);
This routine looks up the field named nameToLookFor in the database file and checks to see if any fields have that name.
Returns TRUE
(-1) if found, FALSE
(0) if not found. token will be the index to the element within the FieldName
element array. This is not something that will normally be used by an application.
Include: foamdb.h
Boolean FoamDBMapTokenToName( VMFileHandle file, word nameToken, word maxBytesToCopy, TCHAR *dest);
This routine finds the field name associated with the token nameToken in the database file file, and copies at maximum maxBytesToCopy bytes of that name into the buffer dest. The routine returns non-zero if the token was out of bounds.
Warning: Field names are null-terminated.
Include: foamdb.h
VMFileHandle FoamDBOpen( char *filename, word mapBlockSize, word majorProtocol, /* Existing file protocol must match major and minor protocols */ word minorProtocol);
Opens an existing database file filename, or creates a new one if it does not
currently exist. Returns the handle of the database file or NullHandle if the
file could not be opened.
ThreadGetError()
can be called to return the
error type, which is the error returned from
VMOpen()
, or -1 if there was
a protocol mismatch.
mapBlockSize is used to specify the size of the map block for the database.
The default (minimum) size is sizeof(FoamDBMap)
, but more space can
be allocated if the application needs to store extra data in the map block.
When creating a new file, the new file will be assigned the protocol number passed in majorProtocol and minorProtocol. When opening an existing file, the protocol number of the file is compared against the protocol number passed in majorProtocol and minorProtocol, and if they do not match, an error of -1 is returned.
Include: foamdb.h
void FoamDBResortDatabase( VMFileHandle file, PCB(sword, callback, (RecordHeader *record1, RecordHeader *record2))); /* Callback Routine */
This routine resorts the database file using the application-defined callback function to determine record order. As with the routine
FoamDBSaveRecord()
,
the callback routine should return -1 if record1 should come before record2, or +1 if record1 should come after record2 in the database. The prototype for the callback routine should look like:
sword _pascal MyCallBackRoutine(RecordHeader *record1, RecordHeader *record2);
Include: foamdb.h
void FoamDBResumeNotifications( VMFileHandle file);
This routine resumes the generation of notifications for the database file. These notifications are FoamDBActionType
s.
See Also: FoamDBSuspendNotifications()
.
Include: foamdb.h
void FoamDBResumeUpdates( VMFileHandle file);
This routine resumes the generation of updates for the database file.
Include: foamdb.h
dword FoamDBSaveRecord( VMFileHandle file, MemHandle record, PCB(sword, callback, (RecordHeader *record1, RecordHeader *record2))); /* Callback routine */
This routine saves the record record in the database file file, and frees up the passed memory block containing the record data. The callback routine determines where in the database the record should be stored. The Contdb
library provides a front-end to this routine,
ContactSaveRecord()
,
which should be used when saving records to a contact database.
PCB()
is a GEOS macro which signifies that one of the parameters for
FoamDBSaveRecord()
will be a callback routine that will return a sword
and accept two RecordHeader
s. This callback routine should be declared as:
sword _pascal MyCallBackRoutine(RecordHeader *record1, RecordHeader *record2);
It should return -1 if record1 should come before record2, or +1 if record1 should come after record2 in the database.
Include: foamdb.h
void FoamDBSetCurrentRecordID( VMFileHandle file, RecordID id);
Sets the record ID that will be used for the next created record.
Include: foamdb.h
void FoamDBSetFieldData( VMFileHandle file, MemHandle record, FieldID id, char *data, /* Data to be stored */ word dataSize); /* How many bytes of data */
Stores dataSize bytes of data in the field ID id of record.
Warning: When storing ASCII data (strings), the strings should not be null terminated. For example, if you want to store the string "ABCD
", then let data be a pointer to the string and let dataSize equal 4.
Include: foamdb.h
void FoamDBSetFieldName( VMFileHandle file, MemHandle record, FieldID id, char *name);
Changes the name of the field with the ID id of record to name.
Warning: name is a null-terminated string.
Include: foamdb.h
void FoamDBSetNameForToken( VMFileHandle file, word nameToken, TCHAR *name);
Sets the name for the field identified by nameToken token
in the database's FieldName
element array.
Warning: Field names are null-terminated.
Include: foamdb.h
void FoamDBSuspendNotifications( VMFileHandle file);
This routine stops the generation of notifications to the database file. Calls to this routine
must be matched by calls to
FoamDBResumeNotifications()
,
Include: foamdb.h
void FoamDBSuspendUpdates( VMFileHandle file);
This routine stops the generation of updates for the database file. Calls to this routine
must be matched by calls to
FoamDBResumeUpdates()
.
Warning: It is dangerous to prevent updates.
Include: foamdb.h
Boolean FoamDBVisibleRecordEnum( VMFileHandle file, void *enumData, PCB(Boolean, callback, /* Non-zero to stop enum */ (RecordHeader *record, void *callbackEnumData))); /* Callback Routine */This routine calls an application-specified callback routine for each visible record in the database. The callback routine can return non-zero to stop the enumeration. enumData is a pointer to any kind of data that your application needs to pass to the callback routine and that the callback routine can modify. The callback routine can return non-zero to stop the enumeration.
For a more complete explanation of using callback routines in a FoamDB, refer to the explanation given for the similar routine
FoamDBFieldEnum()
.
The callback routine should be declared as
/* * Prototype of callback routine */ Boolean _pascal myCallBackRoutine(RecordHeader *record, void *callbackEnumData);
Include: foamdb.h
Boolean FoamDBVisibleRecordEnumWithRange( VMFileHandle file, void *enumData, dword startElement, dword numOfRecords, PCB(Boolean, callback, /* Non-zero to stop enum */ (RecordHeader *record, void *callbackEnumData))); /* Callback routine */
This routine calls the application-specified callback routine for some visible records in the database, starting with the record number startElement, and continuing for numOfRecords records. enumData is a pointer to any kind of data that your application needs to pass to the callback routine and that the callback routine can modify. The callback routine can return non-zero to stop the enumeration.
For a more complete explanation of using callback routines in a FoamDB, refer to the explanation given for the similar routine
FoamDBFieldEnum()
.
The callback routine should be declared as
/* * Prototype of callback routine */ Boolean _pascal myCallBackRoutine(RecordHeader *record, void *callbackEnumData);
Include: foamdb.h
dword FormatIDFromManufacturerAndType(mfr, type); ManufacturerIDs mfr; ClipboardItemFormat type;
This macro takes a manufacturer ID and a format type (e.g. CIF_TEXT) and combines them into a dword argument of the type
ClipboardItemFormatID
.
void free( void * blockPtr); /* address of memory to free */
The
malloc()
family of routines is provided for Standard C compatibility. The kernel will allocate a fixed block to satisfy the geode's
malloc()
requests; it will allocate memory from this block. When the block is filled, it will allocate another fixed malloc-block. When all the memory in the block is freed, the memory manager will automatically free the block.
When a geode is finished with some memory it requested from
malloc()
, it should free the memory. That makes it easier for
malloc()
to satisfy memory request. It can free the memory by passing the address which was returned by
malloc()
(or
calloc()
or
realloc()
) when the memory was allocated. All of the memory will be freed.
The memory must be in a malloc-block assigned to the geode calling
free()
. If you want to free memory in another geode's malloc-block, call
GeoFree()
.
Include: stdlib.h
Warnings: Pass exactly the same address as the one returned to you when you allocated the memory. If you pass a different address,
free()
will take unpredictable actions, including possibly erasing other memory or crashing the system.
word FractionOf( WWFixedAsDWord wwf);
This macro returns the fractional portion of a
WWFixedAsDWord
value.
Include: geos.h
Boolean GCNListAdd( optr OD, /* optr to add to list */ ManufacturerID manufID, /* manufacturer ID of list */ word listType); /* list type */
This routine adds an object pointer (optr) to a GCN list interested in a particular change. The routine must be passed the optr to add, along with the
manufID
and the type of the list to add it to. If no list of the specified manufacturer and type currently exists, a new list will be created.
This routine will return
true
if the optr was successfully added to the GCN list and
false
if the optr could not be added. An optr cannot be added to a GCN list if it currently exists on that list.
Include: gcnlist.goh
Boolean GCNListAddHandles( MemHandle mh, /* handle of object to add */ ChunkHandle ch, /* chunk of object to add */ ManufacturerIDs manufID, /* manufacturer ID of list */ word listType); /* list type */
This routine is exactly the same as
GCNListAdd()
, except it takes the memory and chunk handles of the object rather than a complete optr.
Include: gcnlist.goh
Boolean GCNListAddToBlock( optr OD, /* optr of list to add */ ManufacturerID manufID, /* manufacturer ID of list */ word listType, /* list type */ MemHandle mh, /* handle of block holding list */ ChunkHandle listOfLists); /* chunk of list of lists * in block */
This routine adds a new GCN list to a block containing the GCN lists. Pass it the optr of the chunk containing the new GCN list as well as the list's type and manufacturer ID. Pass also the memory handle and chunk handle of the chunk containing the GCN "list of lists" which will manage the new list.
This routine returns true of the new optr is added to the GCN mechanism, false if it could not be added (if it was already there).
Warnings: This routine may resize chunks in the block, so you should dereference any pointers after calling this routine.
Include: gcnlist.goh
ChunkHandle GCNListCreateBlock( MemHandle mh); /* handle of the locked LMem block */
This routine creates a list of lists for the GCN mechanism. It is rarely, if ever, called by applications. Pass it the handle of the locked LMem block in which the list should be created.
Include: gcnlist.goh
void GCNListDestroyBlock( MemHandle mh, /* handle of locked block to * be destroyed */
ChunkHandle listOfLists); /* chunk of list of lists */
This routine destroys a GCN list of lists and all the GCN lists associated with it. Pass it the handle of the locked LMem block containing the lists as well as the chunk handle of the chunk containing the list of lists.
Include: gcnlist.goh
void GCNListDestroyList( optr list); /* optr of the GCN list to be destroyed */
This routine destroys the specified GCN list.
Include: gcnlist.goh
void GCNListRelocateBlock( MemHandle mh, /* handle of locked LMem block * containing GCN lists */
ChunkHandle listOfLists, /* chunk of list of lists */ MemHandle relocBlock); /* handle of block containing * relocation information */
This routine relocates the GCN list of lists in the specified block, updating all the optrs stored therein.
Warnings: This routine can resize and/or move the LMem block, so you should dereference pointers after calling it.
Include: gcnlist.goh
Boolean GCNListRemove( optr OD, /* the optr to be removed */ ManufacturerID manufID, /* manufacturer ID of the list */ word listType); /* list type */
This routine removes the passed optr from the specified GCN list. The routine must be passed the optr to remove along with the manufacturer ID and list type of the list to remove it from.
This routine will return
true
if the optr was successfully removed from the GCN list and
false
if the optr could not be found on the GCN list and therefore could not be removed.
Include: gcnlist.goh
Boolean GCNListRemoveFromBlock( optr OD, /* optr of GCN list to remove */ ManufacturerID manufID, /* manufacturer of list to remove */ word listType, /* type of list being removed */ MemHandle mh, /* handle of locked LMem block * containing the list of lists */
ChunkHandle listOfLists); /* chunk of list of lists */
This routine removes a GCN list from a GCN list block and from the list of lists therein.
Include: gcnlist.goh
Boolean GCNListRemoveHandles( MemHandle mh, ChunkHandle ch, ManufacturerID manufID, word listType);
This routine is exactly the same as
GCNListRemove()
, except it specifies the object to be removed via handles rather than an optr.
Include: gcnlist.goh
See Also: GCNListRemove()
.
word GCNListSend( ManufacturerID manufID, /* manufacturer of list */ word listType, /* notification type */ EventHandle event, /* event to be sent to list */ MemHandle dataBlock, /* data block, if any */ word gcnListSendFlags); /* GCNListSendFlags */
This routine sends a message to all objects in the specified GCN list. The message is specified in
event
, and the list is specified in
manufID
and
listType
. The message will be sent asynchronously (some time after the change has occurred) by the message queue.
The
dataBlock
parameter contains the memory handle of an extra data block to be sent with the notification, if any; this block should also be specified in the classed event. If no data block is required, pass a NullHandle. If a data block with a reference cound is used, increment the reference count by one before calling this routine; this routine decrements the count and frees the block if the count reaches zero.
The
gcnListSendFlags
parameter is of type
GCNListSendFlags
, which has only one meaningful flag for this routine:
event
will be returned by the routine. If this flag is not set, the return value will be the number of messages sent out.Include: gcnlist.goh
word GCNListSendToBlock( ManufacturerID manufID, /* manufacturer id of list */ word listType, /* notification type */ EventHandle event, /* event to be sent to list */ MemHandle dataBlock, /* data block, if any */ MemHandle mh, /* handle of locked LMem block * containing GCN list of lists */
ChunkHandle listOfLists, /* chunk of list of lists */ GCNListSendFlags flags); /* GCNListSendFlags */
This routine sends the specified
event
to the specified list, just as
GCNListSend()
.
GCNListSendToBlock()
, however, specifies a particular instance of the GCN list by specifying the appropriate list of lists in
mh
and
listOfLists
. Other parameters and return values are identical to
GCNListSend()
.
See Also: GCNListSend()
.
Include: gcnlist.goh
void GCNListSendToList( optr list, /* optr of GCN list */ EventHandle event, /* event to send to list */ MemHandle dataBlock, /* handle of data block, if any */ GCNListSendFlags flags); /* GCNListSendFlags */
This routine sends the specified
event
to the specified GCN
list
. The list is specified explicitly by optr as opposed to by manufacturer ID and type. The event will be sent via the proper queues to all objects registered on the list. After the notification is handled by all notified objects, the event will be freed, as will the data block passed. (If no data block, pass NullHandle in
dataBlock
)
The
flags
parameter can have one flag, GCNLSF_SET_STATUS. If this flag is set, the event passed will be set as the list's status message.
Include: gcnlist.goh
See Also: GCNListSend()
.
void GCNListSendToListHandles( MemHandle mh, /* handle of list's block */ ChunkHandle ch, /* chunk of list */ EventHandle event, /* event to send to list */ MemHandle dataBlock, /* handle of data block, if any */ GCNListSendFlags flags); /* GCNListSendFlags */
This routine is exactly the same as
GCNListSendToList()
; the list is specified not by optr, however, but by a combination of its global and chunk handles.
See Also: GCNListSendToList()
.
Include: gcnlist.goh
Boolean GCNListUnRelocateBlock( MemHandle mh, /* handle of the locked lmem block * containing the list of lists */
ChunkHandle listOfLists, /* chunk of the list of lists */ MemHandle relocBlock); /* handle of block containing * relocation/unrelocation info */
This routine unrelocates the specified list of lists, updating all the optrs according to the information in relocBlock . This routine is rarely, if ever, used by applications; it is used primarily by the UI when shutting down to a state file.
It returns
true
if the specified list of lists has no lists saved to state and therefore is simply destroyed. The return value is
false
if the list of lists is saved to the state file normally.
Include: gcnlist.goh
word GenCopyChunk( MemHandle destBlock, /* handle of locked LMem block into * which chunk will be copied */
MemHandle blk, /* handle of locked source LMem block */ ChunkHandle chnk, /* chunk handle of chunk to be copied */ word flags); /* CompChildFlags */
This is a utility routine that copies one LMem chunk into a newly created chunk. The routine will allocate the new chunk in the block passed in
destBlock
and will return the chunk handle of the new chunk. It is used primarily by the UI to duplicate generic object chunks.
The source chunk is specified by the global handle
blk
and the chunk handle
chnk
. The
flags
parameter contains a record of
CompChildFlags
, of which only the CCF_MARK_DIRTY flag is meaningful. If this flag is set, the new chunk will be marked dirty.
Warnings: This routine may resize and/or move chunks and blocks, so you must dereference pointers after calling it.
Include: genC.goh
optr GenFindObjectInTree( optr startObject, /* optr of object at which to start search */ dword childTable); /* pointer to table of bytes, each indicating * the position of the child at the given * level; -1 is the end of the table */
This utility routine finds the object having the optr
startObject
in the generic tree. Applications will not likely need this routine.
The childTable parameter points to a table of bytes, each byte representing the child number to be found at each level. The first byte indicates the child of startObject to get; the second byte indicates the child to get at the next level; the third byte indicates the child to get at the next level, and so on. A byte of -1 indicates the end of the table. The object found will be returned.
Include: genC.goh
void GenInsertChild( MemHandle mh, /* handle of parent */ ChunkHandle chnk, /* chunk of parent */ optr childToAdd, /* optr of new child */ optr referenceChild, /* optr of reference child */ word flags); /* CompChildFlags */
This utility routine adds a child object to a composite object. It is used almost exclusively by the UI for generic objects--applications will typically use
MSG_GEN_ADD_CHILD
.
See Also: MSG_GEN_ADD_CHILD
.
Warnings: This routine may move or resize chunks and/or object blocks; therefore, you must dereference pointers after calling it.
Include: genC.goh
This is an Esp-only routine. In most cases, Goc programmers will use
MSG_GEN_OUTPUT_ACTION
instead.
void GenProcessGenAttrsAfterAction( MemHandle mh, /* handle of object calling the routine */ ChunkHandle chnk); /* chunk of object calling the routine */
This utility routine processes various attributes for a generic object after the object's action message has been sent. It is used almost exclusively by the generic UI after
MSG_GEN_OUTPUT_ACTION
or
GenProcessAction()
.
Warnings: This routine may move or resize chunks and/or object blocks; therefore, you must dereference pointers after calling it.
Include: genC.goh
void GenProcessGenAttrsBeforeAction( MemHandle mh, /* handle of object calling the routine */ ChunkHandle chnk); /* chunk of object calling the routine */
This utility routine processes various attributes for a generic object before the object's action message has been sent. It is used almost exclusively by the generic UI before
MSG_GEN_OUTPUT_ACTION
or
GenProcessAction()
.
Warnings: This routine may move or resize chunks and/or object blocks; therefore, you must dereference pointers after calling it.
Include: genC.goh
VMFileHandle GenProcessUndoGetFile();
This routine returns the handle of the file that holds the process' undo information.
Include: Objects/gProcC.goh
Boolean GenProcessUndoCheckIfIgnoring();
This routine returns true if the process is currently ignoring actions.
Include: Objects/gProcC.goh
void GenRemoveDownwardLink( MemHandle mh, /* handle of calling object */ ChunkHandle chnk, /* chunk of calling object */ word flags); /* CompChildFlags */
This utility routine removes a child from the generic tree, preserving the child's upward link and usability flags. It is called primarily by the generic UI and is rarely used by applications. The flags parameter specifies whether the object linkage should be marked dirty by passing the CCF_MARK_DIRTY flag.
Warnings: This routine may move or resize chunks and/or object blocks; therefore, you must dereference pointers after calling it.
Include: genC.goh
void GenSetUpwardLink( MemHandle mh, /* handle of calling object */ ChunkHandle chnk, /* chunk of calling object */ optr parent); /* optr of calling object's parent */
This utility routine converts the child/parent link to an upward-only link. Pass the handle and chunk of the locked child object and the optr of the parent composite.
Include: genC.goh
QueueHandle GeodeAllocQueue();
This routine allocates an event queue which can then be attached to a thread with
ThreadAttachToQueue()
. It returns the queue's handle if one is allocated; it will return zero otherwise. This routine is used outside the kernel only in exceptional circumstances.
Be Sure To: You must free the queue when you are done with it; use
GeodeFreeQueue()
.
Include: geode.h
MemHandle GeodeDuplicateResource( MemHandle mh); /* handle of geode resource to duplicate */
This routine reads a resource from a geode into a newly-allocated block (allocated by this routine). Any relocations on the resource to itself are adjusted to be the duplicated block. The handle of the duplicated block is returned.
Include: resource.h
GeodeHandle GeodeFind( const char * name, /* geode's permanent name */ word numChars, /* number of characters to match: * 8 for name, 12 for name.ext */ GeodeAttrs attrMatch, /* GeodeAttrs that must be set */ GeodeAttrs attrNoMatch); /* GeodeAttrs that must be off */
This routine finds a geode given its permanent name, returning the geode handle if found. If the geode can not be found, a null handle will be returned. Pass it the following:
name
numChars
attrMatch
GeodeAttrs
the subject geode must have set for a positive match.
attrNoMatch
GeodeAttrs
the subject geode must have cleared for a positive match.Include: geode.h
word GeodeFindResource( FileHandle file, /* geode's executable file */ word resNum, /* resource number to find */ word resOffset, /* offset to resource */ dword * base); /* pointer to second return value */
This routine locates a resource within a geode's executable (
.geo
) file. It returns the size of the resource as well as the base position of the first byte of the resource in the file (pointed to by
base
). Pass the following:
file
resNum
resOffset
base
Structures: A geode's executable file is laid out as shown below.
0: Geode file header
1: Imported Library Table
2: Exported Routine Table
3: Resource Size Table
4: Resource Position Table
5: Relocation Table Size Table
6: Allocation Flags Table
7+: application resources
Include: geode.h
void GeodeFlushQueue( QueueHandle source, /* source queue to flush */ QueueHandle dest, /* queue to hold flushed events */ optr obj /* object to handle flushed events */ MessageFlags flags); /* MF_INSERT_AT_FRONT or zero */
This routine flushes all events from one event queue into another, synchronously. Pass it the following:
source
dest
obj
flags
MessageFlags
. The only meaningful flag for this routine is MF_INSERT_AT_FRONT, which should be set to flush source queue's events to the front of the destination queue. If this flag is not passed, events will be appended to the queue.Include: geode.h
void GeodeFreeDriver( GeodeHandle gh); /* handle of the driver */
This routine frees a driver geode that had been loaded with
GeodeUseDriver()
. Pass it the geode handle of the driver as returned by that routine.
Include: driver.h
void GeodeFreeLibrary( GeodeHandle gh); /* handle of the library */
This routine frees a library geode that had been loaded with
GeodeUseLibrary()
. Pass it the geode handle of the library.
Include: library.h
void GeodeFreeQueue( QueueHandle qh); /* handle of queue being freed */
This routine frees an event queue allocated with
GeodeAllocQueue()
. Any events still on the queue will be flushed as with
GeodeFlushQueue()
. You must pass the handle of the queue to be freed.
Include: geode.h
optr GeodeGetAppObject( GeodeHandle gh); /* handle of the application geode */
This routine returns the optr of the specified geode's GenApplication object. The geode should be an application. Pass zero to get the optr of the caller's application object.
Include: geode.h
GeodeHandle GeodeGetCodeProcessHandle();
This routine returns the geode handle of the geode that owns the block in which the code which calls this routine resides.
Include: geode.h
GeodeHandle GeodeGetDefaultDriver( GeodeDefaultDriverType type); /* type of default driver to get */
This routine returns the default driver's geode handle for the type passed. The type must be one of the values of
GeodeDefaultDriverType
.
Include: driver.h
word GeodeGetInfo( GeodeHandle gh, /* handle of the subject geode */ GeodeGetInfoType info, /* type of information to return */ void * buf); /* buffer to contain returned info */
This routine returns information about the specified geode. The geode must be loaded already. The meaning of the returned word depends on the value passed in
info
; the
GeodeGetInfoType
is shown below. Pass the following:
gh
info
buf
GeodeGetInfoType
has the following enumerations (only one may be requested at a time):
GeodeAttrs
corresponding to those attributes set for the geode. Pass a null buffer pointer.
GeosFileType
indicating the type of file storing the geode. Pass a null buffer pointer.
buf
, and the buffer will contain the
ReleaseNumber
structure of the geode.
buf
, and the buffer will contain the
ProtocolNumber
structure of the geode.
buf
, and the buffer will contain a
GeodeToken
structure containing the token characters and token ID of the geode's token.
buf
, and the buffer will contain a null-terminated character string representing the geode's permanent name (as set in its geode parameters file). Note that the buffer must be at least 13 bytes.Include: geode.h
optr GeodeGetOptrNS( optr obj);
This routine unrelocates an optr, changing the virtual-segment handle to an actual global handle.
Include: resource.h
GeodeHandle GeodeGetProcessHandle();
This routine returns the geode handle of the current executing process (i.e. the owner of the current running thread). Use it when you need to pass your application's geode handle or Process object's handle to a routine or message.
Include: geode.h
DriverInfoStruct * GeodeInfoDriver( GeodeHandle gh); /* handle of the driver to get information about */
This routine returns information about the specified driver geode. Pass the geode handle of the driver as returned by
GeodeUseDriver()
. It returns a pointer to a
DriverInfoStruct
structure, shown below.
typedef struct { void (*DIS_strategy)(); DriverAttrs DIS_driverAttributes; DriverType DIS_driverType; } DriverInfoStruct;
For full information on this structure, see the
DriverInfoStruct
reference entry.
Include: driver.h
word GeodeInfoQueue( QueueHandle qh); /* queue to query */
This routine returns information about a specific event queue. Pass the handle of the queue; for information about the current process' queue, pass a null handle. This routine returns the number of events (or messages) currently in the queue.
Include: geode.h
GeodeHandle GeodeLoad( const char * name, /* file name of geode */ GeodeAttrs attrMatch, /* GeodeAttrs that must be set */ GeodeAttrs attrNoMatch, /* GeodeAttrs that must be clear */ word priority, /* priority of the loaded geode */ dword appInfo, /* special load information */ GeodeLoadError * err); /* returned error value */
This routine loads the specified geode from the given file and then executes the geode based on its type. It returns the geode handle of the loaded geode if successful; if unsuccessful, the returned value will be NullHandle and the
err
pointer will point to an error value. Pass this routine the following:
name
attrMatch
GeodeAttrs
that must be set in the specified geode for the load to be successful.
attrNoMatch
GeodeAttrs
that must be cleared in the specified geode for the load to be successful. (That is, each bit which is set in
attrNoMatch
must be clear in the geode's
GeodeAttrs
field.)
priority
appInfo
err
GeodeLoadError
which will hold any returned error values.
Warnings: If you load a geode dynamically with
GeodeLoad()
, you must be sure to free it when you are done with
GeodeFreeDriver()
or
GeodeFreeLibrary()
.
Include: geode.h
See Also: UserLoadApplication()
.
void GeodeLoadDGroup( MemHandle mh);
This routine forces the
dgroup
segment into the data-segment register. This routine expects the
MemHandle
of the code resource, which can be retrieved with
GeodeGetCodeProcessHandle()
.
Include: resource.h
word GeodePrivAlloc( GeodeHandle gh, /* handle of the owner of the * newly-allocated private data */
word numWords); /* number of words to allocate */
This routine allocates a string of contiguous words in all geodes' private data areas; each set of words will be owned by the geode specified in
gh
. The data allocated can be accessed with
GeodePrivWrite()
and
GeodePrivRead()
and must be freed with
GeodePrivFree()
. The return value will be the offset to the start of the allocated range, or zero if the routine could not allocate the space.
Each geode has a block of private data the is accessed using the
GeodePriv...()
routines. A specific geode's private data block is expanded only when a valid
GeodePrivWrite()
is performed for the geode. Space is "allocated" in the data blocks of all geodes (loaded or yet-to-be loaded) simultaneously via a call to
GeodePrivAlloc()
. Data that have never been written are returned as all zeros.
Include: geode.h
void GeodePrivFree( word offset, /* offset returned by GeodePrivAlloc() */ word numWords); /* number of words to free */
This routine frees a group of contiguous words from all geodes' private data areas. The space must previously have been allocated with
GeodePrivAlloc()
. Pass the offset to the words as returned by
GeodePrivAlloc()
as well as the number of words to be freed.
Include: geode.h
void GeodePrivRead( GeodeHandle gh, /* handle of owner of private data */ word offset, /* offset returned by * GeodePrivAlloc() */
word numWords, /* number of words to read */ word * dest); /* pointer to buffer into which data * will be copied */
This routine reads a number of words from the geode's private data area. Pass the following:
gh
offset
GeodePrivAlloc()
.
numWords
dest
numWords
words long.Include: geode.h
void GeodePrivWrite( GeodeHandle gh, /* handle of owner of private data */ word offset, /* offset returned by * GeodePrivAlloc() */
word numWords, /* number of words to be written */ word * src); /* buffer containing data */
This routine writes a number of words into a geode's private data area. The area being written must have been allocated previously with
GeodePrivAlloc()
. Pass the following:
gh
offset
GeodePrivAlloc()
.
numWords
src
Include: geode.h
void GeodeSetDefaultDriver( GeodeDefaultDriverType type, /* type of default driver to set */ GeodeHandle gh); /* driver to set as the default */
This routine sets the default driver for the indicated driver type. Pass the type of default driver in
type
and the handle of the driver in
gh
. The type must be a value of
GeodeDefaultDriverType
.
Include: driver.h
GeodeHandle GeodeUseDriver( const char * name, /* file name of driver to load */ word protoMajor, /* expected major protocol */ word protoMinor, /* expected minor protocol */ GeodeLoadError * err); /* pointer to returned error */
This routine dynamically loads a driver geode given the driver's file name. It returns the geode handle of the driver if successful; if unsuccessful, it returns an error code of type
GeodeLoadError
pointed to by
err
. Pass this routine the following:
name
protoMajor
protoMinor
err
GeodeLoadError
in which any error values will be returned.Tips and Tricks: It is much easier to automatically load the drivers you need by noting them in your geode parameters file.
Be Sure To: If you use
GeodeUseDriver()
to dynamically load a driver, you must also use
GeodeFreeDriver()
to free it when you are done using it.
Include: driver.h
GeodeHandle GeodeUseLibrary( const char * name, /* file name of library to load */ word protoMajor, /* expected major protocol */ word protoMinor, /* expected minor protocol */ GeodeLoadError * err); /* pointer to returned error */
This routine dynamically loads a library geode when given the library's file name. (The library must be in the thread's working directory.) It returns the geode handle of the loaded library if successful; if unsuccessful, it returns an error code (
GeodeLoadError
) pointed to by
err
. Pass this routine the following parameters:
name
protoMajor
protoMinor
err
GeodeLoadError
which will contain any returned error values.
Be Sure To: If you dynamically load a library with
GeodeUseLibrary()
, you must manually free it when finished, with
GeodeFreeLibrary()
.
Include: library.h
void * GeoFree( void * blockPtr, /* address of memory to free */ GeodeHandle geodeHan); /* owner of block to be used */
The routine
malloc()
can free only memory in the malloc-block belonging to the calling geode. If you want to free memory in another geode's malloc-block, call
GeoFree()
. Passing a null
GeodeHandle
will make
GeoMalloc()
act on memory in the calling geode's malloc-block.
Include: geode.h
Warnings: Pass exactly the same address as the one returned to you when you allocated the memory. If you pass a different address,
GeoFree()
will take unpredictable actions, including possibly erasing other memory or crashing the system.
See Also: free()
.
void * GeoMalloc( size_t blockSize, /* # of bytes to allocate*/ GeodeHandle geodeHan, /* Owner of block to be used */ word zeroInit); /* Zero-initialize memory? */
The routine
malloc()
automatically allocates memory in the malloc-block belonging to the calling geode. It does not zero-initialize the memory. If you want to zero-initialize the memory, or want to allocate it in another geode's malloc-block, call
GeoMalloc()
. Pass
true
(i.e., non-zero) in
zeroInit
to zero-initialize the memory.
Passing a null
GeodeHandle
will make
GeoMalloc()
allocate the memory in the calling geode's malloc-block. If "zeroInit" is true, the memory will be initialized to null bytes; otherwise, the memory will be left uninitialized.
Include: geode.h
Warnings: All memory allocated with
malloc()
is freed when GEOS shuts down.
See Also: malloc()
.
void * GeoReAlloc( void * blockPtr, /* address of memory to resize */ size_t newSize, /* New size in bytes */ GeodeHandle geodeHan); /* Owner of block to be used */
The routine
realloc()
can resize only memory in the malloc-block belonging to the calling geode. If you want to resize memory in another geode's malloc-block, call
GeoReAlloc()
. Passing a null
GeodeHandle
will make
GeoReAlloc()
act on memory in the calling geode's malloc-block.
If the block is resized larger, the new memory will not be zero-initialized. Resizing a block smaller will never fail. If
GeoReAlloc()
fails, it will return a null pointer (zero). If you pass a
newSize
of zero, the passed block pointer is freed and the return pointer is a null pointer.
Include: geode.h
Warnings: Pass exactly the same address as the one returned to you when you allocated the memory. If you pass a different address,
GeoReAlloc()
will take unpredictable actions, including possibly erasing other memory or crashing the system.
See Also: realloc()
.
void GrApplyRotation( GStateHandle gstate, /* GState to alter */ WWFixedAsDWord angle); /* degrees counterclockwise */
Apply a rotation to the GState's transformation matrix.
Include: graphics.h
void GrApplyScale( GStateHandle gstate, /* GState to alter */ WWFixedAsDWord xScale, /* new x scale factor */ WWFixedAsDWord yScale); /* new y scale factor */
Apply a scale factor to the GState's transformation matrix.
Include: graphics.h
void GrApplyTransform( GStateHandle gstate, /* GState to draw to */ const TransMatrix *tm); /* transformation matrix to apply */
Apply a transformation, expressed as a transformation matrix, to a GState's coordinate system.
Include: graphics.h
void GrApplyTranslation( GStateHandle gstate, /* GState to alter */ WWFixedAsDWord xTrans, /* translation in x */ WWFixedAsDWord yTrans); /* translation in y */
Apply a translation to the GState.
Include: graphics.h
void GrApplyTranslationDWord( GStateHandle gstate, /* GState to alter */ sdword xTrans, /* extended translation in x */ sdword yTrans); /* extended translation in y */
Apply a 32-bit integer extended translation to the GState.
Include: graphics.h
void GrBeginPath( GStateHandle gstate, /* GState to alter */ PathCombineType params); /* path parameters */
Starts or alters the path associated with a GState. All graphics operations that are executed until
GrEndPath()
is called become part of the path.
Depending on the value of the
params
field, the new path may replace the old path, or may be combined with the old path by intersection or union.
Include: graphics.h
void GrBeginUpdate( GStateHandle gstate); /* GState to draw to */
Called by an application to signal that it is about to begin updating the exposed region. This routine is normally called as part of a
MSG_META_EXPOSED
handler. Blanks out the invalid area.
Include: win.h
void GrBitBlt( GStateHandle gstate, /* GState to draw to */ sword sourceX, /* original x origin */ sword sourceY, /* original y origin */ sword destX, /* new x origin */ sword destY, /* new y origin */ word width, /* width of area */ word height, /* height of area */ BLTMode mode); /* draw mode (see below) */
Transfer a bit-boundary block of pixels between two locations in video memory. This routine is useful for animation and other applications which involve moving a drawing around the screen.
Structures:
typedef enum /* word */ { BLTM_COPY, /* Leave source region alone */ BLTM_MOVE, /* Clear & invalidate source rect */ BLTM_CLEAR /* Clear source rectangle */ } BLTMode;
Include: graphics.h
void GrBrushPolyline( GStateHandle gstate, /* GState to draw to */ const Point * points, /* array of Point structures to draw */ word numPoints, /* number of points in array */ word brushH, /* brush height */ word brushW); /* brush width */
Draw a brushed connected polyline. Note that this routine ignores the GState's line width, and instead uses a brush height and width, measured in pixels.
Include: graphics.h
dword GrCharMetrics( GStatehandle gstate, /* GState to get metrics for */ GCM_info info, /* information to return */ word ch); /* character of type Chars */
Returns metric information for a single character of a font. This information is used to determine the drawing bounds for a character. To find out how wide a character is (how much space to leave for it if drawing a line of text character-by-character), use
GrCharWidth()
instead.
Structures:
typedef enum { GCMI_MIN_X, /* return = value << 16 */ GCMI_MIN_X_ROUNDED, /* return = value */ GCMI_MIN_Y, /* return = value << 16 */ GCMI_MIN_Y_ROUNDED, /* return = value << 16 */ GCMI_MAX_X, /* return = value << 16 */ GCMI_MAX_X_ROUNDED, /* return = value << 16 */ GCMI_MAX_Y, /* return = value << 16 */ GCMI_MAX_Y_ROUNDED /* return = value << 16 */ } GCM_Info;
See Also: GrCharWidth()
.
Include: font.h
dword GrCharWidth( /* Returns width << 16 */ GStateHandle gstate, /* GState to query */ word ch); /* character of type Chars */
Return the width of a single character. Note that this routine does not take into account track kerning, pairwise kerning, space padding, or other attributes that apply to multiple characters.
Include: graphics.h
FontID GrCheckFontAvailID( FontEnumFlags flags, word family, FontID id);
See if font (identified by ID) exists.
Include: graphics.h
FontID GrCheckFontAvailName( FontEnumFlags flags, word family, const char * name);
See if font (identified by name) exists.
Include: graphics.h
void GrClearBitmap( GStateHandle gstate); /* GState to affect */
Clear out the content of a bitmap. Note that the part of the bitmap actually cleared depends on the bitmap mode. For the normal mode, the data portion of the bitmap is cleared. If the bitmap is in BM_EDIT_MASK mode, then the mask is cleared and the data portion is left alone.
Include: graphics.h
void GrCloseSubPath( GStateHandle gstate); /* GState to affect */
Geometrically closes the currently open path segment. Note that you must still call
GrEndPath()
to end the path definition.
Include: graphics.h
void GrComment( GStateHandle gstate, /* GState to affect */ const void * data, /* comment string */ word size); /* Size of data, in bytes */
Write a comment out to a graphics string.
Include: graphics.h
GSRetType GrCopyGString( GStateHandle source, /* GState from which to get GString */ GStateHandle dest, /* GState to which to copy GString */ GSControl flags); /* flags for the copy */
Copy all or part of a Graphics String. The
GSControl
record can have the following flags:
GSC_ONE /* just do one element */ GSC_MISC /* return on MISC opcode */ GSC_LABEL /* return on GR_LABEL opcode */ GSC_ESCAPE /* return on GR_ESCAPE opcode */ GSC_NEW_PAGE /* return when we get to a NEW_PAGE */ GSC_XFORM /* return on TRANSFORMATIONopcode */ GSC_OUTPUT: /* return on OUTPUT opcode */ GSC_ATTR /* return on ATTRIBUTE opcode */ GSC_PATH /* return on PATH opcode */
The return value can be any one of
GSRetType
, a byte-size field:
GSRT_COMPLETE GSRT_ONE GSRT_MISC GSRT_LABEL GSRT_ESCAPE GSRT_NEW_PAGE GSRT_XFORM GSRT_OUTPUT GSRT_ATTR GSRT_PATH GSRT_FAULT
Include: gstring.h
VMBlockHandle GrCreateBitmap( BMFormat initFormat, /* color fomat of bitmap */ word initWidth, /* initial width of bitmap */ word initHeight, /* initial height of bitmap */ VMFileHandle vmFile, /* VM file to hold bitmap's data*/ optr exposureOD, /* optr to get MSG_META_EXPOSED */ GStateHandle * bmgs); /* Draws to this GState * will draw to the bitmap */
This routine allocates memory for a bitmap and creates an off-screen window in which to hold the bitmap. This routine takes the following arguments:
The routine returns a
VMBlockHandle
, the handle of the block within the passed VM file which contains the bitmap's data. The block will be set up as the first block of a HugeArray. Its header area will be filled with the following:
CBitmap
structure which contains some basic information about the bitmap.The bitmap's raw data is in the VM block, but outside of the header area.
Include: graphics.h
GStateHandle GrCreateGString( Handle han, /* memory, stream, or VM file handle */ GStringType hanType, /* type of handle in han parameter */ word * gsBlock); /* returned for GST_MEMORY and * GST_VMEM types only */
Open a graphics string and start redirecting graphics orders to the string. The hanType parameter must be GST_MEMORY, GST_STREAM, or GST_VMEM.
Include: gstring.h
word GrCreatePalette( /* Returns # of entries in color table * or 0 for monochrome or 24-bit */
GStateHandle gstate);
Create a color mapping table and associate it with the current window. Initialize the table entries to the default palette for the device.
Include: graphics.h
GStateHandle GrCreateState( WindowHandle win); /* Window in which GState will be active */
Create a graphics state (GState) block containg default GState information.
If zero is passed, then the GState created will have no window associated with it.
Include: graphics.h
void GrDeleteGStringElement( GStateHandle gstate, /* GState containing GString */ word count); /* number of elements to delete */
Delete a range of GString elements from the GString in the passed GState.
Include: graphics.h
void GrDestroyBitmap( GStateHandle gstate, /* GState containing bitmap */ BMDestroy flags); /* flags for removing data */
Free the bitmap and disassociate it with its window. Depending on the passed flag, the bitmap's data may be freed or preserved. Thus, it is possible to remove the GString used to edit the bitmap while maintaining the bitmap in a drawable state.
Structures:
typedef ByteEnum BMDestroy; /* BMD_KILL_DATA, BMD_LEAVE_DATA */
Include: graphics.h
void GrDestroyGString( Handle gstring, /* Handle of GString */ GStateHandle gstate, /* NULL, or handle of another * gstate to free*/
GStringKillType type); /* Kill type for data removal */
Destroys a GString. Depending on the
GStringKillType
argument, this either constitutes removing the GState from the GString data; or freeing both the GState and the GString's data. If you have been drawing the GString to a GState, you should pass the GState's handle as
gstate
, and this routine will do some cleaning up.
Structures:
typedef ByteEnum GStringKillType; /* GSKT_KILL_DATA, GSKT_LEAVE_DATA */
Include: gstring.h
void GrDestroyPalette( GStateHandle gstate); /* GState of palette to destroy */
Free any custom palette associated with the current window.
Include: graphics.h
void GrDestroyState( GStateHandle gstate); /* GState to be destroyed */
Free a graphics state block.
Include: graphics.h
void GrDrawArc( GStateHandle gstate, /* GState to draw to */ sword left, /* bounds of box outlining arc */ sword top, sword right, sword bottom, word startAngle, /* angles in degrees word endAngle, * counter-clockwise */ ArcCloseType arcType); /* how the arc is closed */
Draw an arc along the ellipse that is specified by a bounding box, from the starting angle to the ending angle.
Include: graphics.h
void GrDrawArc3Point( GStateHandle gstate, /* GState to draw to */ const ThreePointArcParams *params);
Draw a circular arc, given three points along the arc; both endpoints and any other point on the arc.
Include: graphics.h
void GrDrawArc3PointTo( GStateHandle gstate, /* GState to draw to */ const ThreePointArcToParams *params);
As
GrDrawArc3Point()
, above, except that the current position is automatically used as one of the endpoints.
Include: graphics.h
void GrDrawBitmap( GStateHandle gstate, /* GState to draw to */ sword x, /* x starting point */ sword y, /* y starting point */ const Bitmap * bm, /* pointer to the bitmap */ Bitmap * _pascal (*callback) (Bitmap *bm)); /* NULL for no callback */
Draw a bitmap. Note that if the bitmap takes up a great deal of memory, it is necessary to manage its memory when drawing. If the bitmap resides in a
HugeArray
(true of any bitmap created using
GrCreateBitmap()
), then calling
GrDrawHugeBitmap()
will automatically take care of memory management. Otherwise, you may wish to provide a suitable callback routine. This routine should be declared _pascal and is passed a pointer into the passed bitmap and is expected to return a pointer to the next slice. This allows the bitmap to be drawn in horizontal bands, or swaths.
Include: graphics.h
void GrDrawBitmapAtCP( GStateHandle gstate, /* GState to draw to */ const Bitmap * bm, /* pointer to the bitmap */ Bitmap * _pascal (*callback) (Bitmap *bm)); /* NULL for no callback */
This routine is the same as
GrDrawBitmap()
, above, except that the bitmap is drawn at the current position.
Include: graphics.h
void GrDrawChar( GStateHandle gstate, /* GState to draw to */ sword x, /* x position at which to draw */ sword y, /* y position at which to draw */ word ch); /* character of type Chars */
Draw a character at the given position with the current text drawing attributes.
Include: graphics.h
void GrDrawCharAtCP( GStateHandle gstate, /* GState to draw to */ word ch); /* character of type Chars */
Draw a character at the current position with the current text drawing attributes.
Include: graphics.h
void GrDrawCurve( GStateHandle gstate, /* GState to draw to */ const Point *points); /* array of four Points */
Draw a Bezier curve.
Include: graphics.h
void GrDrawCurveTo( GStateHandle gstate, /* GState to draw to */ const Point *points); /* array of three Points */
Draw a Bezier curve, using the current postion as the first point.
Include: graphics.h
void GrDrawEllipse( GStateHandle gstate, /* GState to draw to */ sword left, /* bounding box bounds */ sword top, sword right, sword bottom);
Draw an ellipse, defined by its bounding box.
Include: graphics.h
GSRetType GrDrawGString( GStateHandle gstate, /* GState to draw to */ Handle gstringToDraw, /* GString to draw */ sword x, /* point at which to draw */ sword y, GSControl flags, /* GSControl record */ GStringElement * lastElement); /* pointer to empty structure */
Draw a graphics string. The passed control flag allows drawing to stop upon encountering certain kinds of drawing elements. If this causes the drawing to stop in mid-string, then the routine will provide a pointer to the next
GStringElement
to be played.
GrSaveState()
on the GState before drawing the GString (and call
GrRestoreState()
afterwards). If you will draw anything else to this GState after the GString, you must call
GrDestroyGString()
on the GString, and pass this GState's handle as the gstate argument so that
GrDestroyGString()
can clean up the GState.
GrLoadGString()
).
GSControl
argument which requests that the system stop drawing the GString when it encounters a certain type of GString element. If the GString interpreter encounters one of these elements, it will immediately stop drawing. The GString will remember where it stopped drawing. If you call
GrDrawGString()
with that same GString, it will continue drawing where you left off.
GStringElement
structure.
GrDrawGString()
will return a value here when it is finished drawing. If the GString has stopped drawing partway through due to a passed
GSControl
, the returned
GStringElement
value will tell you what sort of command was responsible for halting drawing. For instance, if you had instructed
GrDrawGString()
to halt on an `output' element (GrDraw...() or GrFill...() commands), then when
GrDrawGString()
returns, you would check the value returned to see what sort of output element was present.Include: gstring.h
GSRetType GrDrawGStringAtCP( GStateHandle gstate, /* GState to draw to */ GStringeHandle gstringToDraw, /* GString to draw */ GSControl flags, /* GSControl flags */ GStringElement * lastElement); /* last element to draw */
Draw a graphics string as
GrDrawGString()
, above, except that drawing takes place at the current position.
GrSaveState()
on the GState before drawing the GString (and call
GrRestoreState()
afterwards). If you will draw anything else to this GState after the GString, you must call
GrDestroyGString()
on the GString, and pass this GState's handle as the gstate argument so that
GrDestroyGString()
can clean up the GState.
GrLoadGString()
).
GSControl
argument which requests that the system stop drawing the GString when it encounters a certain type of GString element. If the GString interpreter encounters one of these elements, it will immediately stop drawing. The GString will remember where it stopped drawing. If you call
GrDrawGString()
with that same GString, it will continue drawing where you left off.
GStringElement
structure.
GrDrawGString()
will return a value here when it is finished drawing. If the GString has stopped drawing partway through due to a passed
GSControl
, the returned
GStringElement
value will tell you what sort of command was responsible for halting drawing. For instance, if you had instructed
GrDrawGString()
to halt on an `output' element (GrDraw...() or GrFill...() commands), then when
GrDrawGString()
returns, you would check the value returned to see what sort of output element was present.Include: gstring.h
void GrDrawHLine( GStateHandle gstate, /* GState to draw to */ sword x1, /* first horizontal coordinate */ sword y, /* vertical position of line */ sword x2); /* second horizontal coordinate */
Draw a horizontal line.
Include: graphics.h
void GrDrawHLineTo( GStateHandle gstate, /* GState to draw to */ sword x); /* ending horizontal coordinate */
Draw a horizontal line starting from the current position.
Include: graphics.h
void GrDrawHugeBitmap( GStateHandle gstate, /* GState to draw to */ sword x /* Point at which to draw */ sword y, VMFileHandle vmFile, /* VM File holding HugeArray */ VMBlockHandle vmBlk); /* VM block of HugeArray */
Draw a bitmap that resides in a HugeArray.
Include: graphics.h
See Also: GrDrawBitmap()
,
GrDrawHugeBitmapAtCP()
,
GrDrawHugeImage()
.
void GrDrawHugeBitmapAtCP( GStateHandle gstate, /* GState to draw to */ VMFileHandle vmFile, /* VM file containing HugeArray */ VMBlockHandle vmBlk); /* VM block containing HugeArray */
As
GrDrawHugeBitmap()
, above, except that the bitmap is drawn at the current position.
Include: graphics.h
See Also: GrDrawBitmapAtCP()
,
GrDrawHugeBitmap()
.
void GrDrawHugeImage( GStateHandle gstate, /* GState to draw to */ sword x /* point at which to draw */ sword y, ImageFlags flags, VMFileHandle vmFile, /* VM file holding HugeArray */ VMBlockHandle vmBlk); /* VM block holding HugeArray */
Draw a bitmap that resides in a
HugeArray
drawn on an assumption of one device pixel per bitmap pixel. The bitmap will not draw rotated or scaled. Depending on the value of the flags argument, the bitmap may be expanded so that a square of device pixels displays each bitmap pixel.
Include: graphics.h
See Also: GrDrawImage()
,
GrDrawHugeBitmapAtCP()
.
void GrDrawImage( GStateHandle gstate, /* GState to draw to */ sword x /* point at which to draw */ sword y, ImageFlags flags, const Bitmap * bm); /* pointer to bitmap */
Draw a bitmap. Note that the bitmap will be drawn on an assumption of one device pixel per bitmap pixel. The bitmap will not draw rotated or scaled. Depending on the value of the flags argument, the bitmap may be expanded so that a square of device pixels displays each bitmap pixel.
Include: graphics.h
See Also: GrDrawHugeImage()
,
GrDrawBitmap()
.
void GrDrawLine( GStateHandle gstate, /* GState to draw to */ sword x1, /* First coordinate of line */ sword y1, sword x2, /* Second coordinate of line */ sword y2);
Draw a line.
Include: graphics.h
See Also: GrDrawLineTo()
,
GrDrawHLine()
,
GrDrawVLine()
.
void GrDrawLineTo( GStateHandle gstate, /* GState to draw to */ sword x, /* Second coordinate of line */ sword y);
Draw a line starting from the current position.
Include: graphics.h
See Also: GrDrawLine()
,
GrDrawHLineTo()
,
GrDrawVLineTo()
.
void GrDrawPath( GStateHandle gstate); /* GState to draw to */
Draws the stroked version of the current path, using the current graphic line attributes.
Include: graphics.h
void GrDrawPoint( GStateHandle gstate, /* GState to draw to */ sword x, /* Coordinates of point to draw */ sword y);
Draw a pixel.
Include: graphics.h
void GrDrawPointAtCP( GStateHandle gstate); /* GState to draw to */
Draw a pixel.
Include: graphics.h
void GrDrawPolygon( GStateHandle gstate, /* GState to draw to */ const Point * points, /* array of points in polygon */ word numPoints); /* number of points in array */
Draws a connected polygon.
Include: graphics.h
void GrDrawPolyline( GStateHandle gstate, /* GState to draw to */ const Point * points, /* array of points in polyline */ word numPoints); /* number of points in array */
Draws a simple polyline.
Include: graphics.h
void GrDrawRect( GStateHandle gstate, /* GState to draw to */ sword left, /* bounds of rectangle to draw */ sword top, sword right, sword bottom);
Draws the outline of a rectangle.
Include: graphics.h
void GrDrawRectTo( GStateHandle gstate, /* GState to draw to */ sword x, /* opposite corner of rectangle */ sword y);
Draws the outline of a rectangle, with one corner defined by the current position.
Include: graphics.h
void GrDrawRegion( GStateHandle gstate, /* GState to draw to */ sword xPos, /* Position at which to draw */ sword yPos, const Region * reg, /* Region definition */ sword param0, /* value to use with * parameterized coordinates */
sword param1); /* value to use with * parameterized coordinates */
Draw a region. The area will be rendered filled with the GState's area attributes.
Include: graphics.h
void GrDrawRegionAtCP( GStateHandle gstate, /* GState to draw to */ const Region * reg, /* region definition */ sword param0, /* Value to use with parameterized coordinates */ sword param1, /* Value to use with parameterized coordinates */ sword param2, /* Value to use with parameterized coordinates */ sword param3); /* Value to use with parameterized coordinates */
Draw a region at the current pen position. The area will be rendered filled with the GState's area attributes.
Include: graphics.h
void GrDrawRelArc3PointTo( const ThreePointRelArcToParams *params);
Draw a circular arc relative to the current point given two additional points: the other endpoint and any other point on the arc, both described in relative coordinates.
Include: graphics.h
void GrDrawRelLineTo( GStateHandle gstate, /* GState to draw to */ WWFixedAsDWord x, /* horizontal offset of second point */ WWFixedAsDWord y); /* vertical offset of second point */
Draw a line from the current pen position, given a displacement from the current pen position to draw to.
Include: graphics.h
void GrDrawRoundRect( GStateHandle gstate, /* GState to draw to */ sword left, /* bounds of rectangle */ sword top, sword right, sword bottom, word cornerRadius); /* radius of corner rounding */
Draw the outline of a rounded rectangle.
Include: graphics.h
void GrDrawRoundRectTo( GStateHandle gstate, /* GState to draw to */ sword x, /* opposite corner of bounds */ sword y, word cornerRadius); /* radius of corner rounding */
Draw the outline of a rounded rectangle, where one corner of the bounding rectangle is the current position.
Include: graphics.h
void GrDrawSpline( GStateHandle gstate, /* GState to draw to */ const Point * points, /* array of points */ word numPoints,); /* number of points in array */
Draw a Bézier spline.
Include: graphics.h
See Also: GrDrawCurve()
.
void GrDrawSplineTo( GStateHandle gstate, /* GState to draw to */ const Point *points, /* array of points */ word numPoints); /* number of points in array */
Draw a Bezier spline, using the current position as one endpoint.
Include: graphics.h
See Also: GrDrawCurveTo()
.
void GrDrawText( GStateHandle gstate, /* GState to draw to */ sword x, /* point at which to draw */ sword y, const Chars * str, /* pointer to character string */ word size); /* length of string */
Draw a string of text. The string is represented as an array of characters. Note that the text will be drawn using the GState's font drawing attributes and that this routine does not accept any style run arguments.
If the passed
size
argument is zero, the string is assumed to be null-terminated.
Include: graphics.h
void GrDrawTextAtCP( GStateHandle gstate, /* GState to draw to */ const Chars * str, /* pointer to character string */ word size); /* length of string */
As
GrDrawText()
, above, except that the text is drawn at the current position.
If the passed
size
argument is zero, the string is assumed to be null-terminated.
Include: graphics.h
void GrDrawVLine( GStateHandle gstate, /* GState to draw to */ sword x, /* horizontal position of line */ sword y1, /* first vertical coordinate */ sword y2); /* second vertical coordinate */
Draw a vertical line.
Include: graphics.h
void GrDrawVLineTo( GStateHandle gstate, /* GState to draw to */ sword y); /* second vertical position */
Draw a vertical line starting from the current position.
Include: graphics.h
GStateHandle GrEditBitmap( VMFileHandle vmFile, /* VM file of bitmap */ VMBlockHandle vmBlock, /* VM block of bitmap */ optr exposureOD); /* optr to get MSG_META_EXPOSED */
This routine attaches a GState to the passed bitmap so that new drawings may be be sent to the bitmap.
Include: graphics.h
GStateHandle GrEditGString( Handle vmFile, /* VM file containing the GString */ word vmBlock); /* VM block containing the GString */
This routine takes the location of a GString data block stored in a VM file. It will associate a GState with this GString data and returns the handle of this GState. Any graphics commands issued using this GStateHandle will be appended to the GString.
Include: graphics.h
GStringErrorType GrEndGString( GStateHandle gstate); /* GState to draw to */
Finish the definition of a graphics string.
Structures:
typedef enum { GSET_NO_ERROR, GSET_DISK_FULL } GStringErrorType;
Include: graphics.h
void GrEndPath( GStateHandle gstate); /* GState to draw to */
Finish definition of a path. Further graphics commands will draw to the display, as normal.
Include: graphics.h
void GrEndUpdate( GStateHandle gstate); /* GState to draw to */
Unlocks window from an update.
Include: win.h
word GrEnumFonts( /* Return value = number of fonts found */ FontEnumStruct * buffer, /* buffer for returned values */ word size, /* number of structures to return */ FontEnumFlags flags, /* FontEnumFlags */ word family); /* FontFamily */
Generate a list of available fonts. The font information includes both the font's ID and a string name.
Structures:
typedef struct { FontID FES_ID; char FES_name[FID_NAME_LEN]; } FontEnumStruct;
Include: font.h
void GrEscape( GStateHandle gstate, /* GState to draw to */ word code, /* escape code */ const void * data, /* pointer to the data */ word size); /* Size of data, in bytes */
Write an escape code to a graphics string.
Include: graphics.h
void GrFillArc( GStateHandle gstate, /* GState to draw to */ sword left, /* bounding rectangle */ sword top, sword right, sword bottom, word startAngle, /* angles in degrees word endAngle * counter-clockwise */ ArcCloseType closeType); /* OPEN, CHORD, or PIE */
Fill an elliptical arc. The arc is defined by the bounding rectangle of the base ellipse and two angles. Depending on how the arc is closed, this will result in either a wedge or a chord fill.
Include: graphics.h
void GrFillArc3Point( GStateHandle gstate, /* GState to draw to */ const ThreePointParams *params);
Fill an arc. Depending on how the arc is closed, this will result in either a wedge or a chord fill. The arc is defined in terms of its endpoints and one other point, all of which must lie on the arc.
Include: graphics.h
void GrFillArc3PointTo( GStateHandle gstate, /* GState to draw to */ const ThreePointArcParams *params);
As
GrFillArc3Point()
, above, except that one endpoint of the arc is defined by the current position.
Include: graphics.h
void GrFillBitmap ( GStateHandle gstate, /* GState to draw to */ sword x, /* point at which to draw */ sword y, const Bitmap * bm, /* pointer to bitmap */ Bitmap * _pascal (*callback) (Bitmap *bm));
Fill a monochrome bitmap with the current area attributes. The arguments to this routine are the same as those for
GrDrawBitmap()
.
Include: graphics.h
void GrFillBitmapAtCP ( GStateHandle gstate, /* GState to draw to */ const Bitmap * bm, /* pointer to bitmap */ Bitmap * _pascal (*callback) (Bitmap *bm));
Fill a monochrome bitmap with the current area attributes. The bitmap will be drawn at the current position. The arguments to this routine are the same as those for
GrDrawBitmapAtCP()
.
Include: graphics.h
void GrFillHugeBitmap( GStateHandle gstate, sword x, sword y, VMFileHandle vmFile, VMBlockHandle vmBlk);
This routine fills a monochrom bitmap where said bitmap is stored in a huge array data structure. The bitmap is specified by means of the vmFile and vmBlk arguments which should reference the huge array.
Include: graphics.h
void GrFillHugeBitmapAtCP( GStateHandle gstate, VMFileHandle vmFile, VMBlockHandle vmBlk);
This routine fills a monochrom bitmap where said bitmap is stored in a huge array data structure. It will draw at the GState's current position. The bitmap is specified by means of the vmFile and vmBlk arguments which should reference the huge array.
Include: graphics.h