home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The Fred Fish Collection 1.5
/
ffcollection-1-5-1992-11.iso
/
ff_disks
/
300-399
/
ff396.lha
/
pfiler
/
Prog.Doc
< prev
next >
Wrap
Text File
|
1990-10-29
|
10KB
|
293 lines
The PFiler File-Selector
1990 by Preben L. Nielsen.
This is Public Domain.
The PFiler File-Selector has only two public functions;
FileSelect() and FreeFileSelect(). The first function
invokes the selection process, and the second function
cleans up the allocations when you are all done.
All options are controlled by the FileSelectRequest
structure that you pass to FileSelect(). You initialize this
structure with the pointers to filename buffers, and text you want
the selector to use.
Normally, you would initialize this structure once and reuse
it for every call to FileSelect(); this keeps the selector in
the same "state" as the user left it.
Below is some detail about the two functions and the contents
of the FileSelectRequest structure.
PFiler/FileSelect
NAME
FileSelect - Invoke the File Selector.
SYNOPSIS
LONG FileSelect (struct FileSelectRequest *FSReq);
D0 STACK
FUNCTION
Opens the selector window using the information in
FSReq to initialize the selector.
The function returns to the caller when:
1: It couldn't open the window or allocate the memory for
internal use.
2: The user has selected a file by
a: double-clicking on a filename.
b: pressing return while the filename string-gadget is active.
c: clicking the 'Ok' gadget.
3: The user cancels the operation by clicking the 'Cancel' gadget.
INPUTS
FSReq - a pointer to an initialized FileSelectRequest structure.
RESULTS
Returns FSENoMem if not enough memory for internal use
Returns FSENoWin if it couldn't open the window
Returns FSENoLib if it couldn't open the dos, graphics, and intuition libraries
Returns FSENeg if user canceled the operation
Returns FSEPos if user selected a file
In case FileSelect() returns FSEPos the FSReq->PathBuffer and the
FSReq->FileBuffer contain the path and the file-name selected by
the user.
EXCEPTIONS
SEE ALSO
FreeFileSelect
BUGS
None known.
NAME
FreeFileSelect - Deallocate cached list.
SYNOPSIS
VOID FreeFileSelect(struct FileSelectRequest *FSReq);
STACK
FUNCTION
This is a cleanup routine for FileSelect(). you MUST call
call FreeFileSelect() to return memory allocated
by the call to FileSelect(). The function deallocates the
cached list of entries and device names.
This function should be called after the file selector
will no longer be used.
However, the function can be called to explicitly purge
the name/device lists, and thereby force the next call to
FileSelect() to re-scan the directory and device-list.
FreeFileSelect() knows if FSReq contains a list to deallocate,
and is harmless otherwise.
INPUTS
FSReq - a pointer to an initialized FileSelectRequest structure.
RESULTS
EXCEPTIONS
SEE ALSO
FileSelect
BUGS
None.
* --------------------------------------------------------------------- *
* The FileSelectRequest Structure:
* --------------------------------------------------------------------- *
The FileSelectRequest is what the user has to pass as
the only parameter to FileSelect(). It is the control/state
structure for FileSelect().
struct FileSelectRequest
{
WORD LeftEdge;
WORD TopEdge;
WORD Flags;
WORD PathChars;
WORD FileChars;
UBYTE *PathBuffer;
UBYTE *FileBuffer;
UBYTE *TitleTxt;
UBYTE *PosTxt;
UBYTE *NegTxt;
struct Screen *Screen;
/* These are -PRIVATE-. The user SHOULDN'T modify them. Only set them to 0 */
/* or call FreeFileSelect() before the first call to FileSelect() with this structure*/
/* See below */
LONG Priv1[2];
WORD Priv2[6];
};
* -----------------------------------------------
* FileSelectRequest Field Descriptions:
* -----------------------------------------------
WORD LeftEdge, TopEdge;
This is the position relative to the upper left of the screen you
want the selector to appear at.
After a call to FileSelect(), these fields will contain the
last position of the window before it was closed.
-------------------------------------------------
WORD Flags;
See PFiler.h for defines.
-------------------------------------------------
WORD PathChars
It is for the user to decide the size of 'PathBuffer'.
Prior to calling FileSelect() you must initialize this
field to the number of bytes in 'PathBuffer'
-------------------------------------------------
WORD FileChars
It is for the user to decide the size of 'FileBuffer'.
Prior to calling FileSelect() you must initialize this
field to the number of bytes in 'PathBuffer'
With the current versions of AmigaDOS, 33 bytes will allow
'FileBuffer' to be able contain any filename.
-------------------------------------------------
UBYTE *PathBuffer;
This is a pointer to the string space used to hold the current
AmigaDOS directory path. The user decides the size, and informs
FileSelect() by setting the field 'PathChars'. You can fill in this
string with a directory name prior to calling FileSelect(). The
Contents of this buffer will appear in the Path string-gadget.
After FileSelect() returns, you can look at this field to get
the "path" part of the full path/filename returned.
-------------------------------------------------
UBYTE *FileBuffer;
This is a pointer to the string space used to hold the current
file name typed or clicked on by the user. The user decides the
size, and informs FileSelect() by setting the field 'FileChars'.
You can fill in this1 string with a file name prior to calling
FileSelect(). The Contents of this buffer will appear in the File
string-gadget. After FileSelect() returns, you can look at this
field to get the "file" part of a full path/filename returned.
-------------------------------------------------
UBYTE *TitleTxt;
Initialize this to NULL or a pointer to the text you want to
appear as the title in the titlebar of the selector window.
Initializing to NULL will give the default 'Select a file..'.
-------------------------------------------------
BYTE *PosTxt;
Initialize this to NULL or a pointer to the text you want to
appear in the select gadget.
Typical examples are "OKAY", "Select", "LOAD" or "SAVE", etc.
The text should not be more than 6 characters.
Initializing to NULL will give the default 'Ok'.
-------------------------------------------------
BYTE *NegTxt;
Initialize this to NULL or a pointer to the text you want to
appear in the cancel gadget.
Typical examples are "CANCEL!", "EXIT", "ABORT" or "QUIT", etc.
The text should not be more than 6 characters.
Initializing to NULL will give the default 'Cancel'.
-------------------------------------------------
struct Screen *Screen;
NULL or a pointer to the custom screen you want the selector
window to appear on. If the field is NULL, the selector will
open on the Workbench screen.
-------------------------------------------------
The rest of the FileSelectRequest structure is for
internal use in FileSelect() and FreeFileSelect().
These fields SHOULD NOT be modified BETWEEN calls
to FileSelect() and FreeFileSelect(). They contain
values that enables the selector to be started in
the same state it was last left in.
-------------------------------------------------
LONG Priv1[2]
These long-words are actually pointers.
Priv1[0] contains a pointer to the cashed list of
file, directory, and device names. When called,
FileSelect() uses this field to determine, whether to
start in the same state it was last left, or whether
to re-scan the directory and device-list.
A call to FreeFileSelect() clears this field after
deallocating the list. THEREFORE, initialize this
field to NULL before the first Call to FileSelect(), AND
DON'T modify it between calls to FileSelect() and
FreeFileSelect().
Priv1[1] contains, if Priv1[0]<>NULL, a pointer to an
entry in the list, containing the first name to be shown
on the display.
The format of the Entries in the list is:
struct EntryNode
{
struct EntryNode *EntryNext; /* This is a single-linked list */
LONG EntryType; /* See defines below */
WORD EntrySize; /* Size of this node itself (The size of this */
/* structure depends on length of the name) */
UBYTE EntryName[ ??? ]; /* NULL-terminated string containing name. */
};
#define DIRTYPE =-1 /* Node contains the name of a directory */
#define DEVICETYPE =-2 /* Node contains the name of a device */
#define VOLUMETYPE =-3 /* Node contains the name of a volume */
#define ASSIGNTYPE =-4 /* Node contains the name of a logical device */
/* A Node containing the name of file is */
/* characterized by having a type >=0 */
-------------------------------------------------
WORD Priv2[6]
Five of these 6 WORD's are counters.
Priv2[5] is a few flags used internally by FileSelect(), and
stored here to survive from call to call.
The cashed list of file, directory, and device names, could
look like this:
myfile1 \ Files
myfile2 /
mydir1 \ Directories
mydir2 /
DF0: \ Devices
DF1: /
WBenchDisk1.3 \ Volumes
CLIDisk2: /
C: \ Logical devices
DEVS: /
Priv2[1] contains the number of Files in the list
Priv2[2] contains the number of Directories in the list
Priv2[3] contains the number of Devices, Volumes and
Logical devices in the list
Priv2[4] contains the total number of entries in the list
Priv2[0] contains the position of Priv1[1] in the list