home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 191.lha / ARequester / readme < prev    next >
Text File  |  1988-04-28  |  6KB  |  177 lines
  1.                         ANOTHER FILE REQUESTER
  2.  
  3. 1) Features
  4.  
  5.   Another file requester, intended to out-do all others. You be the judge of
  6.   that. This is NOT really a requester, but a window. It is easier to do
  7.   this with a window and the user can drag the window around. You also get
  8.   a few other neat features if you use a window.
  9.  
  10.   The file requester will accept file and directory names up to the max
  11.   allowable by Amiga DOS. This feat is accomplished by the use of a
  12.   horisontal scroll bar.
  13.  
  14.   Arrow gadgets are provided to allow the user to scroll the screen around
  15.   in one line increments. If you hold down the arrow gadgets the screen
  16.   will scroll by one line every time an INTUITICK happens.
  17.  
  18.   The scroll bars update the screen without letting up on them.
  19.  
  20.   You can use the window on any Amiga screen and use the colors that
  21.   the file requester was designed with.
  22.  
  23.   The file requester can operate simultaneously (almost) with input from
  24.   other windows. A user function is called whenever one of a spcified set of
  25.   signals arrives.
  26.  
  27.   Directory entries are packed in such a way as to minimize memory useage
  28.   and maximize speed.
  29.  
  30.   Entries are sorted in alpabetical order with the sub-directories appearing
  31.   first. A very fast recursive sorting function is used and the sort is
  32.   done on an index of pointers instead of the data itself.
  33.  
  34.   The code compiles with Aztec C small and large (+p) memory models. Since
  35.   the source compiles with the +p option in Aztec I assume it will work well
  36.   with lattice. A minimal demonstration program is provided.
  37.  
  38.  
  39. 2) Function description
  40.  
  41. NAME
  42.          file_requester
  43.  
  44. SYNOPSIS
  45.          #include "req.h"
  46.  
  47.          long file_requester(r)
  48.          FileReq *r;
  49.  
  50. FUNCTION
  51.          Allows the user to browse through the filing system. If the user
  52.          presses OKAY then the selected path and file are stored in the
  53.          FileReq structure.
  54.  
  55. ARGUMENT
  56.          r - A pointer to a filled out FileReq structure.
  57.  
  58. RETURNS
  59.          OKAY is returned if the user has selected the okay button.
  60.          If the user selected OKAY the selected path and file will be
  61.          copied to the appropriate members of the FileReq structure.
  62.  
  63.          CANCEL is returned if the user pressed the cancel button.
  64.  
  65.          FILEREQ_ERROR is returned if there was an error.
  66.  
  67.  
  68. 3) The FileReq structure
  69.  
  70.   typedef struct
  71.   {
  72.   struct Screen *screen;
  73.   UBYTE *path;
  74.   UBYTE *file;
  75.   UBYTE *heading;
  76.   UBYTE *buf;
  77.   long bufsize;
  78.   long n_entries;
  79.   UWORD flags;
  80.   ULONG user_signals;
  81.   PFV user_func;
  82.   } FileReq;
  83.  
  84.  
  85.   Here are the meanings of the variables and flags in the FileReq structure:
  86.  
  87.  
  88.   screen
  89.       A pointer to an intuition custom screen or NULL if you are using the
  90.       workbench screen.
  91.  
  92.   path
  93.       A pointer to a buffer to contain the initial path used by the file
  94.       requester. Also if the user selects the OAKY button the path the
  95.       user selected will be copied to this buffer, so it better be big
  96.       enough.
  97.  
  98.   file
  99.       A pointer to a buffer to contain the initial file used by the file
  100.       requester. If the user selects the OKAY button the file the user
  101.       selected will be copied to this buffer.
  102.  
  103.   heading
  104.       A pointer to a null-terminated string that will appear centered
  105.       at the top of the window.
  106.  
  107.   buf
  108.       A pointer to a buffer to be used as storage for the directory entries
  109.       and an index of the directory entries. This variable may be set to
  110.       NULL and space will be allocated for the buffer with AllocMem.
  111.  
  112.   bufsize
  113.       The size of the provided buffer in bytes, or the size of the buffer
  114.       to be allocated (if the buf variable is NULL).
  115.  
  116.   n_entries
  117.       The maximum number of entries to be used by the file requester. The
  118.       file requester creates an index of pointers to entries depending
  119.       on this variable.
  120.  
  121.   flags
  122.       The flags variable has two possible flags to be set.
  123.  
  124.       CLI_BIT is set by you if your program was executed from the CLI.
  125.       The full path name of the current directory can be easily
  126.       discovered from programs executed from the CLI. If the argc argument
  127.       to main is not zero then it was executed from the CLI.
  128.  
  129.       NATURAL_COLOR_BIT is set by you if you want to change the colors of
  130.       the view port to those used to design this function. You are
  131.       responsible for setting them back again. This is not recomended for
  132.       programs that operate on the workbench screen.
  133.  
  134.   user_signals
  135.       A set of signals that will trigger the execution of the user function.
  136.       Set user_signals to zero if they are not being used. You sould know
  137.       about signals before you use it.
  138.  
  139.   user_func
  140.       The function that gets called when one of the specified signals is
  141.       received. The function is called with a long integer that contains
  142.       the signals that triggered the calling of this function. Set this
  143.       variable to NULL if you are not using it.
  144.  
  145.  
  146. 4) Credits
  147.  
  148.   This blasted thing took longer than one might expect to write. I did it
  149.   because I kept seeing things on BBS's that said 'File Requester just like
  150.   the one in DPaint'. Big Deal! it doesn't take much to copy someone else's
  151.   work. This one is LIKE NO ONE ELSES (I hope). It was written with Aztec
  152.   C 3.40a. Also I wrote a similar one for IBM PC's and got a lot of feed-
  153.   back from users about it, made improvements, and wrote this one. I added
  154.   another vertical scroll-bar on the left for left-handed mouse users and
  155.   had to put in the horisontal scroll bar because the Amiga file names can
  156.   be longer than could normally fit in the window. Also I hope you don't
  157.   mind that I erase the drag-gadget on the window.
  158.  
  159.   I am giving this code away. It is in the public domain and may not be
  160.   sold. Use it at your own risk (it has been tested well). If you use the
  161.   file requester in any commercial program please send me a copy of your
  162.   program. If you don't send me a copy of your program you will be given
  163.   bad reviews or something else equally horrible. Even if you write a
  164.   shareware or PD program using the file requester you should send me a
  165.   copy of it.
  166.  
  167.  
  168.       Robert W. Albrecht
  169.       1457 Zion Way
  170.       Ventura CA 93003
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.