home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / code_examples / pfiler / prog.doc < prev    next >
Text File  |  1990-10-29  |  10KB  |  293 lines
  1.  
  2.                The PFiler File-Selector
  3.  
  4.         1990 by Preben L. Nielsen.
  5.         This is Public Domain.
  6.  
  7.  
  8.           The PFiler File-Selector has only two public functions;
  9.         FileSelect() and FreeFileSelect().  The first function
  10.         invokes the selection process, and the second function
  11.         cleans up the allocations when you are all done.
  12.  
  13.           All options are controlled by the FileSelectRequest
  14.         structure that you pass to FileSelect().  You initialize this
  15.         structure with the pointers to filename buffers, and text you want
  16.         the selector to use.
  17.  
  18.           Normally, you would initialize this structure once and reuse
  19.         it for every call to FileSelect(); this keeps the selector in
  20.         the same "state" as the user left it.
  21.  
  22.           Below is some detail about the two functions and the contents
  23.     of the FileSelectRequest structure.
  24.  
  25. PFiler/FileSelect
  26.  
  27.    NAME
  28.         FileSelect - Invoke the File Selector.
  29.  
  30.    SYNOPSIS
  31.         LONG FileSelect (struct FileSelectRequest *FSReq);
  32.         D0                        STACK
  33.  
  34.    FUNCTION
  35.           Opens the selector window using the information in
  36.         FSReq to initialize the selector.
  37.  
  38.           The function returns to the caller when:
  39.         1: It couldn't open the window or allocate the memory for
  40.                internal use.
  41.             2: The user has selected a file by
  42.            a: double-clicking on a filename.
  43.                b: pressing return while the filename string-gadget is active.
  44.                c: clicking the 'Ok' gadget.
  45.             3: The user cancels the operation by clicking the 'Cancel' gadget.
  46.  
  47.    INPUTS
  48.         FSReq - a pointer to an initialized FileSelectRequest structure.
  49.  
  50.    RESULTS
  51.         Returns FSENoMem if not enough memory for internal use
  52.         Returns FSENoWin if it couldn't open the window
  53.         Returns FSENoLib if it couldn't open the dos, graphics, and intuition libraries
  54.         Returns FSENeg   if user canceled the operation
  55.         Returns FSEPos   if user selected a file
  56.  
  57.           In case FileSelect() returns FSEPos the FSReq->PathBuffer and the
  58.         FSReq->FileBuffer contain the path and the file-name selected by
  59.         the user.
  60.  
  61.    EXCEPTIONS
  62.  
  63.  
  64.    SEE ALSO
  65.         FreeFileSelect
  66.  
  67.    BUGS
  68.         None known.
  69.  
  70.  
  71.  
  72.  
  73.    NAME
  74.         FreeFileSelect - Deallocate cached list.
  75.  
  76.    SYNOPSIS
  77.         VOID FreeFileSelect(struct FileSelectRequest *FSReq);
  78.                                         STACK
  79.    FUNCTION
  80.           This is a cleanup routine for FileSelect(). you MUST call
  81.         call FreeFileSelect() to return memory allocated
  82.         by the call to FileSelect(). The function deallocates the
  83.         cached list of entries and device names.
  84.       
  85.           This function should be called after the file selector
  86.         will no longer be used.
  87.           However, the function can be called to explicitly purge
  88.         the name/device lists, and thereby force the next call to
  89.         FileSelect() to re-scan the directory and device-list.
  90.           FreeFileSelect() knows if FSReq contains a list to deallocate,
  91.         and is harmless otherwise.
  92.  
  93.    INPUTS
  94.         FSReq - a pointer to an initialized FileSelectRequest structure.
  95.  
  96.    RESULTS
  97.  
  98.    EXCEPTIONS
  99.  
  100.    SEE ALSO
  101.         FileSelect
  102.  
  103.    BUGS
  104.         None.
  105.  
  106.  
  107. * --------------------------------------------------------------------- *
  108. * The FileSelectRequest Structure:
  109. * --------------------------------------------------------------------- *
  110.           The FileSelectRequest is what the user has to pass as
  111.         the only parameter to FileSelect(). It is the control/state
  112.         structure for FileSelect().
  113.  
  114. struct FileSelectRequest
  115. {
  116.   WORD LeftEdge;
  117.   WORD TopEdge;
  118.   WORD Flags;
  119.   WORD PathChars;
  120.   WORD FileChars;
  121.   UBYTE *PathBuffer;
  122.   UBYTE *FileBuffer;
  123.   UBYTE *TitleTxt;
  124.   UBYTE *PosTxt;
  125.   UBYTE *NegTxt;
  126.   struct Screen *Screen;
  127. /* These are -PRIVATE-. The user SHOULDN'T modify them. Only set them to 0        */
  128. /* or call FreeFileSelect() before the first call to FileSelect() with this structure*/
  129. /* See below                                        */
  130.   LONG Priv1[2];
  131.   WORD Priv2[6];
  132. };
  133.  
  134. * -----------------------------------------------
  135. * FileSelectRequest Field Descriptions:
  136. * -----------------------------------------------
  137. WORD LeftEdge, TopEdge;
  138.  
  139.     This is the position relative to the upper left of the screen you
  140.   want the selector to appear at.
  141.     After a call to FileSelect(), these fields will contain the
  142.   last position of the window before it was closed.
  143.  
  144. -------------------------------------------------
  145. WORD Flags;
  146.     See PFiler.h for defines.
  147.  
  148. -------------------------------------------------
  149. WORD PathChars
  150.  
  151.     It is for the user to decide the size of 'PathBuffer'.
  152.     Prior to calling FileSelect() you must initialize this
  153.   field to the number of bytes in 'PathBuffer'
  154.  
  155. -------------------------------------------------
  156. WORD FileChars
  157.  
  158.     It is for the user to decide the size of 'FileBuffer'.
  159.     Prior to calling FileSelect() you must initialize this
  160.   field to the number of bytes in 'PathBuffer'
  161.     With the current versions of AmigaDOS, 33 bytes will allow
  162.   'FileBuffer' to be able contain any filename.
  163.  
  164. -------------------------------------------------
  165. UBYTE *PathBuffer;
  166.  
  167.     This is a pointer to the string space used to hold the current
  168.   AmigaDOS directory path.  The user decides the size, and informs
  169.   FileSelect() by setting the field 'PathChars'. You can fill in this
  170.   string with a directory name prior to calling FileSelect(). The
  171.   Contents of this buffer will appear in the Path string-gadget.
  172.   After FileSelect() returns, you can look at this field to get
  173.   the "path" part of the full path/filename returned.
  174.  
  175. -------------------------------------------------
  176. UBYTE *FileBuffer;
  177.  
  178.     This is a pointer to the string space used to hold the current
  179.   file name typed or clicked on by the user. The user decides the
  180.   size, and informs FileSelect() by setting the field 'FileChars'.
  181.   You can fill in this1 string with a file name prior to calling
  182.   FileSelect(). The Contents of this buffer will appear in the File
  183.   string-gadget. After FileSelect() returns, you can look at this
  184.   field to get the "file" part of a full path/filename returned.
  185.  
  186. -------------------------------------------------
  187. UBYTE *TitleTxt;
  188.  
  189.     Initialize this to NULL or a pointer to the text you want to
  190.   appear as the title in the titlebar of the selector window.
  191.     Initializing to NULL will give the default 'Select a file..'.
  192.  
  193. -------------------------------------------------
  194. BYTE *PosTxt;
  195.  
  196.     Initialize this to NULL or a pointer to the text you want to
  197.   appear in the select gadget.
  198.     Typical examples are "OKAY", "Select", "LOAD" or "SAVE", etc.
  199.   The text should not be more than 6 characters.
  200.     Initializing to NULL will give the default 'Ok'.
  201.  
  202. -------------------------------------------------
  203. BYTE *NegTxt;
  204.  
  205.     Initialize this to NULL or a pointer to the text you want to
  206.   appear in the cancel gadget.
  207.     Typical examples are "CANCEL!", "EXIT", "ABORT" or "QUIT", etc.
  208.   The text should not be more than 6 characters.
  209.     Initializing to NULL will give the default 'Cancel'.
  210.  
  211. -------------------------------------------------
  212. struct Screen *Screen;
  213.  
  214.     NULL or a pointer to the custom screen you want the selector
  215.   window to appear on.  If the field is NULL, the selector will
  216.   open on the Workbench screen.
  217.  
  218.  
  219. -------------------------------------------------
  220.     The rest of the FileSelectRequest structure is for
  221.   internal use in FileSelect() and FreeFileSelect().
  222.     These fields SHOULD NOT be modified BETWEEN calls
  223.   to FileSelect() and FreeFileSelect(). They contain
  224.   values that enables the selector to be started in
  225.   the same state it was last left in.
  226. -------------------------------------------------
  227. LONG Priv1[2]
  228.  
  229.      These long-words are actually pointers.
  230.  
  231.      Priv1[0] contains a pointer to the cashed list of
  232.    file, directory, and device names. When called,
  233.    FileSelect() uses this field to determine, whether to
  234.    start in the same state it was last left, or whether
  235.    to re-scan the directory and device-list.
  236.      A call to FreeFileSelect() clears this field after
  237.    deallocating the list. THEREFORE, initialize this
  238.    field to NULL before the first Call to FileSelect(), AND
  239.    DON'T modify it between calls to FileSelect() and
  240.    FreeFileSelect().
  241.  
  242.      Priv1[1] contains, if Priv1[0]<>NULL, a pointer to an
  243.    entry in the list, containing the first name to be shown
  244.    on the display.
  245.  
  246.  
  247.      The format of the Entries in the list is:
  248.  
  249.   struct EntryNode
  250.   {
  251.    struct EntryNode *EntryNext;        /* This is a single-linked list         */
  252.    LONG EntryType;            /* See defines below                */
  253.    WORD EntrySize;            /* Size of this node itself (The size of this    */
  254.                     /* structure depends on length of the name)    */
  255.    UBYTE EntryName[ ??? ];        /* NULL-terminated string containing name.    */ 
  256.   };
  257.  
  258. #define DIRTYPE    =-1            /* Node contains the name of a directory    */
  259. #define DEVICETYPE =-2            /* Node contains the name of a device        */
  260. #define VOLUMETYPE =-3            /* Node contains the name of a volume        */
  261. #define ASSIGNTYPE =-4            /* Node contains the name of a logical device    */
  262.                     /* A Node containing the name of file is    */
  263.                     /* characterized by having a type >=0        */
  264.  
  265. -------------------------------------------------
  266. WORD Priv2[6]
  267.  
  268.      Five of these 6 WORD's are counters.
  269.      Priv2[5] is a few flags used internally by FileSelect(), and
  270.    stored here to survive from call to call.
  271.  
  272.      The cashed list of file, directory, and device names, could
  273.    look like this:
  274.         myfile1        \ Files
  275.         myfile2        /
  276.         mydir1         \ Directories
  277.         mydir2         /
  278.         DF0:           \ Devices
  279.         DF1:           /
  280.         WBenchDisk1.3  \ Volumes
  281.         CLIDisk2:      /
  282.         C:             \ Logical devices
  283.         DEVS:          /
  284.  
  285.         Priv2[1] contains the number of Files           in the list
  286.         Priv2[2] contains the number of Directories     in the list
  287.         Priv2[3] contains the number of Devices, Volumes and
  288.                                         Logical devices in the list
  289.         Priv2[4] contains the total number of entries in the list
  290.  
  291.         Priv2[0] contains the position of Priv1[1] in the list
  292.  
  293.