home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff245.lzh / PathMaster / PROG.DOCS < prev    next >
Text File  |  1989-09-06  |  18KB  |  519 lines
  1.  
  2.                     PathMaster File Selector
  3.                Programmer Documentation 89-06-26.
  4.  --------------------------------------------------------------
  5.  
  6. Copyright © 1989 by Justin V. McCormick.
  7. All Rights Reserved.
  8.  
  9.   The PathMaster File Selector has only two public functions;
  10. FileSelect() and ReleaseFileSelect().  The first function
  11. invokes the selection process, and the second function
  12. purges/cleans up the allocations when you are all done.
  13.  
  14.   All PathMaster options are controlled by the FSRequest
  15. structure that you pass to FileSelect().  You initialize this
  16. structure with the destination filename buffers, default gadget
  17. settings, callbacks, and text messages you want the selector to
  18. use.
  19.  
  20.   Normally, you would initialize this structure once and reuse
  21. it for every call to FileSelect(); this keeps the selector in
  22. the same "state" as the user left it.  Or, you could have
  23. several FSRequest structures, one for Loading files, one for
  24. Saving, etc.  You can then have separate Load and Save file
  25. selector defaults that the user can customize without conflict.
  26.  
  27.   Before I detail the contents of the FSRequest structure, lets
  28. document the two functions:
  29.  
  30. Public Function Docs:
  31. ---------------------
  32. pathmaster/FileSelect
  33.  
  34.    NAME
  35.        FileSelect - Invoke the PathMaster File Selector.
  36.  
  37.    SYNOPSIS
  38.        LONG FileSelect (struct FSRequest *fsreq);
  39.         D0                    STACK
  40.  
  41.    FUNCTION
  42.        Opens the selector window using the information in
  43.        fsreq to initialize the selectors internal state
  44.        machines.  The function returns to the caller when either
  45.        the user selects a name or cancels the operation.
  46.  
  47.    INPUTS
  48.        fsreq - a pointer to an initialized FSRequest structure.
  49.  
  50.    RESULTS
  51.        Returns 0 if allocations fail.
  52.        Returns 1 if FileSelect() succeeds.
  53.  
  54.        Check the fsreq->fullname variable to determine whether user
  55.        canceled the selection; if strlen(fsreq->fullname) == 0, then
  56.        the user canceled FileSelect().
  57.  
  58.    EXCEPTIONS
  59.        Requires destination screen to be at least 495x171 pixels.
  60.  
  61.    SEE ALSO
  62.        ReleaseFileSelect
  63.  
  64.    BUGS
  65.        Sure.
  66.  
  67.  
  68. pathmaster/ReleaseFileSelect
  69.  
  70.    NAME
  71.       ReleaseFileSelect - Release/Deallocate all PathMaster caches.
  72.  
  73.    SYNOPSIS
  74.       VOID ReleaseFileSelect(VOID);
  75.  
  76.    FUNCTION
  77.       Cleanup routine for FileSelect().  If you call FileSelect,
  78.       you must call ReleaseFileSelect to return memory allocated
  79.       by the selector.  The function UnLocks any path locks and
  80.       deallocates the cached list of entries and device names.
  81.       
  82.       Normally called once by main application after the file
  83.       selector will no longer be used; e.g., at exit() time.
  84.       However, the function can be called by the application
  85.       to explicitly purge the name/device lists.  This may
  86.       be necessary to insure proper updating after deleting
  87.       files, etc. in special applications.
  88.  
  89.    INPUTS
  90.  
  91.    RESULTS
  92.  
  93.    EXCEPTIONS
  94.       Should not be called asynchronously while in FileSelect().
  95.  
  96.    SEE ALSO
  97.        FileSelect
  98.  
  99.    BUGS
  100.        None.
  101.  
  102.  
  103. * --------------------------------------------------------------------- *
  104. * The FSRequest Structure:
  105. * --------------------------------------------------------------------- *
  106.  
  107. Here is the control/state structure for FileSelect():
  108.  
  109. struct FSRequest
  110. {
  111.   BYTE dirname[300];
  112.   BYTE filename[32];
  113.   BYTE matchpattern[32];
  114.   WORD leftedge;
  115.   WORD topedge;
  116.   WORD sorttype;
  117.   UWORD flags;
  118.   ULONG windowflags;
  119.   BYTE *fullname;
  120.   BYTE *ignorepattern;
  121.   BYTE *pathgadstr;
  122.   BYTE *filegadstr;
  123.   BYTE *titlestr;
  124.   BYTE *readingstr;
  125.   BYTE *sortingstr;
  126.   BYTE *emptydirstr;
  127.   BYTE *nomatchstr;
  128.   BYTE *selectfilestr;
  129.   BYTE *selectstr;
  130.   BYTE *cancelstr;
  131.   BYTE *specgadstr;
  132.   struct Screen *userscreen;
  133.   struct MsgPort *userport;
  134.   LONG (*specgadfunc) (struct FSRequest *, struct Window *, struct Gadget *);
  135.   LONG (*dirfunc) (struct FSRequest *, struct Window *);
  136.   LONG (*filefunc) (struct FSRequest *, struct Window *);
  137.   LONG (*userfunc) (struct FSRequest *, struct Window *);
  138.   LONG (*initfunc) (struct FSRequest *, struct Window *);
  139.   LONG (*matchfunc) (struct FSRequest *, BYTE *, struct file_node *);
  140. };
  141.  
  142. * --------------------------------------------------------------------- *
  143. * FSRequest Field Descriptions:
  144. * --------------------------------------------------------------------- *
  145.  
  146.   Most of these fields should be initialized to NULL or all
  147. zeros.  Typically, the you will only need to set a few of these
  148. fields in order to call FileSelect() - the fullname, selectstr,
  149. and cancelstr fields are the only required pointers.  Please see
  150. fs.c for a complete example.
  151.  
  152.  
  153. -------------------
  154. BYTE dirname[300];
  155.  
  156.   The string space used to hold the current AmigaDOS directory
  157. path.  The 300 byte limit effectively limits directory descent
  158. to ten subdirectories, worst case.  You can fill in this string
  159. with a default directory name prior to calling FileSelect().
  160. After FileSelect() returns, you can look at this field to get
  161. the "path" part of a full path/filename returned.
  162. -------------------
  163.  
  164. -------------------
  165. BYTE filename[32];
  166.  
  167.   The string space used to hold the current or last file name typed
  168. or clicked on by the user.  You can initialize this string to hold
  169. a default filename that will appear in the file text gadget, and
  170. you can look at this field after calling FileSelect() to get just
  171. the "name" part of the full path/filename returned.
  172. -------------------
  173.  
  174. -------------------
  175. BYTE matchpattern[32];
  176.  
  177.   The string space used to hold the current or last file match
  178. pattern typed by the user.  File names that match the UNIX-style
  179. pattern will be displayed; all other filenames will be hidden.
  180. By default, the selector will use a "*" pattern to match all
  181. files unless otherwise specified.  You can initialize this
  182. string to hold a default pattern that will appear in the pattern
  183. text gadget, and examine the field after calling FileSelect() to
  184. see if the user changed the pattern template.
  185. -------------------
  186.  
  187. -------------------
  188. WORD leftedge, topedge;
  189.  
  190.   The window position relative to the upper left of the screen you
  191. want the selector to appear at.  If the user drags the selector
  192. window, the selector will update these fields so that the window
  193. will appear in that position next time FileSelect() is called
  194. using that FSRequest.
  195. -------------------
  196.  
  197. -------------------
  198. WORD sorttype;
  199.  
  200.   The type of sort to apply to files and directories scanned by
  201. the selector:
  202.   -1 = Do not sort entries.
  203.    0 = Alphabetize.
  204.    1 = Sort by Size.
  205.    2 = Sort by Time.
  206. This field is updated by the selector if the user clicks on one of
  207. the sort gadgets.
  208. -------------------
  209.  
  210. -------------------
  211. UWORD flags;
  212.  
  213.   This is a 16-bit field that controls many of the "preference"
  214. type options for the file selector.  Simply OR together the
  215. following defines (See fs.h) as desired:
  216.  
  217. /* FSRequest flags */
  218.   FS_NO_DCLICK_EXIT     /* Disable double-click file select exit     */
  219.   FS_NO_STRING_EXIT     /* Disable Return in File String Gadget exit */
  220.   FS_NO_STRING_OKAY     /* Allow exit with no file name              */
  221.   FS_SHOW_FILES_FIRST   /* Show files first in file/dir mixture      */
  222.   FS_SHOW_DIRS_FIRST    /* Show dirs first in file/dir mixture       */
  223.   FS_SHOW_FILES_ONLY    /* Don't show dirs                           */
  224.   FS_SHOW_DIRS_ONLY     /* Don't show files                          */
  225.   FS_DELAYED_SORT       /* Don't sort entries till user hits slide   */
  226. -------------------
  227.  
  228. -------------------
  229. ULONG windowflags;
  230.  
  231.   If non-NULL, the selector will use this value for its
  232. NewWindow.Flags.  Otherwise, the selector will use its default
  233. NewWindow.Flags definition:
  234.   WINDOWDRAG | WINDOWDEPTH | SMART_REFRESH | NOCAREREFRESH | ACTIVATE | RMBTRAP
  235. -------------------
  236.  
  237. -------------------
  238. BYTE *fullname;
  239.  
  240.   A pointer to a 344 byte string space that you want to contain
  241. the final full path/filename selected by the user.  If the string
  242. length is zero, this means that the user canceled the file selection
  243. process.  You may share this space amoung several FSRequest
  244. structures.
  245. -------------------
  246.  
  247. -------------------
  248. BYTE *ignorepattern;
  249.  
  250.   NULL or a pointer to a UNIX-style pattern string.  Each file the
  251. selector scans is compared to this string.  Files that match the
  252. string will not be displayed.  This is useful, for instance, to
  253. eliminate all ".info" files from the display.  Simply set
  254. FSRequest->ignorepattern = "*.info" before calling FileSelect().
  255. -------------------
  256.  
  257. -------------------
  258. BYTE *pathgadstr;
  259.  
  260.   NULL or a 4-Letter text that will appear to the left of the
  261. Directory string gadget, normally "PATH".
  262. -------------------
  263.  
  264. -------------------
  265. BYTE *filegadstr;
  266.  
  267.   NULL or a 4-Letter text that will appear to the left of the
  268. File string gadget, normally "FILE".
  269. -------------------
  270.  
  271. -------------------
  272. BYTE *titlestr;
  273.  
  274.   NULL or a pointer to the text you want to appear as the title
  275. in the titlebar of the selector window.  This string should be
  276. no more than 28 characters long.
  277. -------------------
  278.  
  279. -------------------
  280. BYTE *readingstr;
  281.  
  282.   NULL or a pointer to the text you want to appear in the
  283. selector titlebar when the selector is reading files from a
  284. device.  By default this string is "Reading...".
  285. -------------------
  286.  
  287. -------------------
  288. BYTE *sortingstr;
  289.  
  290.   NULL or a pointer to the text you want to appear in the
  291. selector titlebar when the selector is sorting files.
  292. By default this string is "Sorting...".
  293. -------------------
  294.  
  295. -------------------
  296. BYTE *emptydirstr;
  297.  
  298.   NULL or a pointer to the text you want to appear in the
  299. selector titlebar when the selector has finished reading
  300. from a valid device and there are no files in the given
  301. path.  By default this string is "Empty Directory!".
  302. -------------------
  303.  
  304. -------------------
  305. BYTE *nomatchstr;
  306.  
  307.   NULL or a pointer to the text you want to appear in the
  308. selector titlebar when there are no files in the given path that
  309. match the current pattern contained in FSRequest->matchpattern.
  310. By default this string is "Nothing matched PATTERN".
  311. -------------------
  312.  
  313. -------------------
  314. BYTE *selectfilestr;
  315.  
  316.   NULL or a pointer to the text you want to appear in the
  317. selector titlebar when the selector has finished reading files
  318. from a valid device and the selector is waiting for a user
  319. action.  By default this string is "Select Filename:".
  320. -------------------
  321.  
  322. -------------------
  323. BYTE *selectstr;
  324.  
  325.   Pointer to the text you want to appear for the select gadget.
  326. Typical examples are "OKAY", "Select", "LOAD" or "SAVE", etc.
  327. The text should not be more than 9 characters.
  328. -------------------
  329.  
  330. -------------------
  331. BYTE *cancelstr;
  332.  
  333.   Pointer to the text you want to appear for the cancel gadget.
  334. Typical examples are "CANCEL!", "EXIT", "ABORT" or "QUIT", etc.
  335. The text should not be more than 9 characters.
  336. -------------------
  337.  
  338. -------------------
  339. BYTE *specgadstr;
  340.  
  341.   NULL or a pointer to the text you want to appear for the
  342. special gadget.  Typical examples are "DELETE", "MARK", "Queue"
  343. or "Select", etc.  The text should not be more than 9
  344. characters.  You must also supply a pointer for
  345. FSRequest->specgadfunc that will be called when the user
  346. clicks on this gadget (see below).
  347. -------------------
  348.  
  349. -------------------
  350. struct Screen *userscreen;
  351.  
  352.   NULL or a pointer to the custom screen you want the selector
  353. window to appear on.  If the field is NULL, the selector will
  354. default to opening on the Workbench screen.
  355. -------------------
  356.  
  357. -------------------
  358. struct MsgPort *userport;
  359.  
  360.   NULL or a pointer to a previously open IDCMP port.  If
  361. non-NULL, the selector will include the given Port in the
  362. selectors Wait() signal mask.  If the userport is signaled, the
  363. selector will call the function pointed to by
  364. FSRequest->userfunc (see below).
  365. -------------------
  366.  
  367. -------------------
  368. LONG (*specgadfunc) (struct FSRequest *, struct Window *, struct Gadget *);
  369.  
  370.   NULL or a pointer to the function that will be called when the
  371. user clicks on the special gadget.  You must also supply text
  372. that will appear in this gadget, FSRequest->specgadstr.  When
  373. the user clicks on this gadget the selector will call your
  374. function.  Your function will be passed the same FSRequest
  375. pointer you supplied to FileSelect(), a pointer to the selector
  376. window, and a pointer to the special gadget itself.  Thus, you
  377. can read the currently selected filename from
  378. FSRequest->fullname and take appropriate action, perhaps
  379. changing the special gadget text and calling RefreshGList().
  380. -------------------
  381.  
  382. -------------------
  383. LONG (*dirfunc) (struct FSRequest *, struct Window *);
  384.  
  385.   NULL or a pointer to a function that will be called for each
  386. directory name the user clicks on or types into the PATH string
  387. gadget.  You are passed a pointer to the same FSRequest
  388. structure that FileSelect() was called with, and a pointer to
  389. the selector window.
  390. -------------------
  391.  
  392. -------------------
  393. LONG (*filefunc) (struct FSRequest *, struct Window *);
  394.  
  395.   NULL or a pointer to a function that will be called for each
  396. filename the user clicks on or types into the FILE string
  397. gadget.  You are passed a pointer to the same FSRequest
  398. structure that FileSelect() was called with, and a pointer to
  399. the selector window.
  400. -------------------
  401.  
  402. -------------------
  403. LONG (*userfunc) (struct FSRequest *, struct Window *);
  404.  
  405.   NULL or a pointer to a function that will be called when
  406. messages arrive at the supplied FSRequest->userport (see above).
  407. You are passed a pointer to the same FSRequest structure that
  408. FileSelect() was called with, and a pointer to the selector
  409. window.
  410. -------------------
  411.  
  412. -------------------
  413. LONG (*initfunc) (struct FSRequest *, struct Window *);
  414.  
  415.   NULL or a pointer to a function that will be called
  416. immediately after the selector window pops up.  You are passed a
  417. pointer to the same FSRequest structure that FileSelect() was
  418. called with, and a pointer to the selector window.  This gives
  419. you an opportunity to change screen colors, set a custom window
  420. pointer for the selector, etc. in a synchronized manner.
  421. -------------------
  422.  
  423. -------------------
  424. LONG (*matchfunc) (struct FSRequest *, BYTE *, struct file_node *);
  425.  
  426.   NULL or a pointer to a function that will be called for each
  427. entry the selector scans from a valid device.  If your function
  428. returns TRUE, the selector will add the entry to the list. If
  429. your function returns FALSE the entry will not be added to the
  430. list of entries.
  431.  
  432.   You are passed a pointer to your original FSRequest and a
  433. pointer to the new file_node structure that the selector has
  434. just read from the device.  The file_node contains:
  435.  
  436.   struct file_node
  437.   {
  438.     struct file_node *next;    /* next file_node     */
  439.     struct file_node *prev;    /* previous file_node     */
  440.     struct node_data *info;    /* file info structure    */
  441.     WORD idnum;            /* numerical position    */
  442.   }
  443.  
  444.   The node_data structure contained by each file_node holds all
  445. of the information concerning that entry.  By modifying the
  446. node_data field, you can cause certain entries be invisible or
  447. to appear highlighted, or fake a directory entry to show up as a
  448. file entry in the list:
  449.  
  450. /* File node structure */
  451.   struct node_data
  452.   {
  453.     BYTE alphadata[58];        /* ascii data              */
  454.     WORD filetype;        /* 0=Dir or 1=file flag     */
  455.     WORD showit;        /* 0=skip, 1=showable        */
  456.     WORD textcolor;        /* Pen Color to render with    */
  457.     WORD namelength;        /* Actual length of file name     */
  458.     ULONG filesize;        /* File size in bytes        */
  459.     ULONG days;            /* File creation date        */
  460.     ULONG minutes;
  461.     ULONG ticks;
  462.   };
  463. -------------------
  464.  
  465.   Please see the User Documentation for details on the PathMaster
  466. User Interface.
  467.  
  468. * --------------------------------------------------------------------- *
  469. * PathMaster Installation Notes:
  470. * --------------------------------------------------------------------- *
  471.  
  472. Initialization:
  473. ----------------
  474.  
  475.   It is presumed that both GfxBase and IntuitionBase are
  476. opened before calling FileSelect(), and are globally available.
  477. Since ActivateGadget() and some other 1.2 Kernel calls are used,
  478. you must open version 33 or later of these libraries or the Guru
  479. will probably visit.
  480.  
  481.   By default, the file selector uses a WBENCHWINDOW to open in,
  482. and does a ScreenToFront() on the window's screen after opening.
  483. You need to supply a FSRequest->userscreen pointer to your
  484. CUSTOM screen if this is not what you desire.  Note, however,
  485. that the file selector window is 495 pixels wide by 171 pixels
  486. high, so it won't open on a 320 pixel wide screen.
  487.  
  488.   The file selector uses a globally defined TextFont to insure
  489. that Topaz 8 is used for textual information.  You can change
  490. fs.h to point to a special font, however, most of the text
  491. placement assumes a non-proportional 8-point font.
  492.  
  493. Error Returns and Messages:
  494. ---------------------------
  495.  
  496.   If FileSelect() fails to open (probably due to lack of
  497. RAM for a new window) it will return a value of ZERO (0).
  498. Otherwise it returns ONE (1).
  499.  
  500.   The file selector has a large table of error messages that are
  501. used to detail specific errors in the selector window titlebar.
  502. Not all of the error messages are applicable to the file
  503. selector, but they are included because other routines can share
  504. the error messages and error reporting mechanisms.  You can
  505. reduce some of the text to a zero length string ("") if you wish
  506. to save on space a little, or change the messages if they are
  507. not appropriately worded for your application.  Just bear in
  508. mind that some of the messages will be used by FileSelect() and
  509. must fit within the titlebar of the file selector.
  510.  
  511.   Before your application exits, you should call
  512. ReleaseFileSelect() to deallocate the memory that FileSelect()
  513. uses.  Since the file selector builds a device list the first
  514. time it is called and then dynamically allocates and buffers the
  515. current directory, the next time FileSelect() is called the
  516. directory does not have to be re-scanned (unless, of course, the
  517. directory has been modified, in which case the file selector
  518. will automatically re©scan the directory).
  519.