home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 402.lha / kd_freq.library_v2.00 / Programming / kd_freq.doc < prev    next >
Text File  |  1990-07-26  |  17KB  |  441 lines
  1. kd_freq.library                                                  Release 2.00
  2. ---------------                                                  ------------
  3.                              By: Khalid Aldoseri
  4.  
  5.  
  6.  
  7. 'kd_freq.library' is a standard Amiga library that has three functions:
  8. FReq(), Path() and PatMatch(). FReq() calls my file requester (FR) so that
  9. any program can use it.  The FR is totally reentrant, and you can have
  10. multiple programs calling it simultaenously.  Path() simply returns
  11. the full path to a file or directory.  PatMatch() implements AmigaDOS style
  12. wildcard pattern matching.
  13.  
  14. To open the library, use OpenLibrary() like any other normal Amiga library.
  15. Look at test.c for the exact opening procedure.  You will need to assemble
  16. and link glue.asm (either manx.glue.asm or lattice.glue.asm) along with your
  17. own object files.
  18.  
  19.   e.g.  for Manx:
  20.  
  21.        cc +l test.c
  22.        as glue.asm
  23.        ln test.o glue.o -lc32
  24.  
  25.  
  26.  
  27.                                   AutoDocs:
  28. ------------------------------------------------------------------------------
  29.  
  30. kd_freq.library/FReq
  31.  
  32. NAME
  33.  
  34.         FReq - bring up a file requester and obtain a file name.
  35.  
  36. SYNOPSIS
  37.  
  38.         result = FReq(screen,reqtitle,filename,directory,pattern,flags,extras);
  39.  
  40.         LONG  result
  41.         struct Screen *screen;
  42.         UBYTE *reqtitle;
  43.         UBYTE *filename;
  44.         UBYTE *directory;
  45.         UBYTE *pattern;
  46.         ULONG flags;
  47.         struct ExtraData *extras;
  48.  
  49.  
  50. FUNCTION
  51.  
  52.         Accepts a default directory name, default file name, and a
  53.         default pattern (standard AmigaDOS wildcard pattern) and returns
  54.         a selected directory, selected file name, and last pattern used
  55.         in the same variables that were used to call the requester.
  56.  
  57.         The 'screen' argument is a pointer to a Screen structure.  This tells
  58.         the file requester to show up on a specific screen.  If you use
  59.         NULL, then the FR will show up on the WorkBench screen.
  60.  
  61.         'reqtitle' is the title that will appear as the title of the file
  62.         requester.
  63.  
  64.         'flags' is a set of flags that control the operation of the FR.
  65.         The flags are the following:
  66.  
  67.             FR_NOINFO        Do not show any file that ends with <.info>.
  68.                              The user can change this setting later by
  69.                              clicking on the 'I' gadget.
  70.  
  71.             FR_NORESIZE      Do not allow the user to resize the FR.
  72.  
  73.             FR_NOTITLEBAR    Do not show the close window gadget, the drag
  74.                              bar, or the front/back gadgets.  The title still
  75.                              gets displayed.  This makes the FR non-movable.
  76.                              This also automatically triggers FR_NORESIZE.
  77.                              If you don't provide a title the file list will
  78.                              resize and fill in the empty space.
  79.  
  80.             FR_AUTOPOSITION  Tells the FR to decide where it wants to come up
  81.                              on its own.  (i.e. ignore LeftEdge and TopEdge)
  82.  
  83.             FR_AUTOSIZE      Tells the FR to decide its size on its own.
  84.                              (i.e. ignore Width and Height)
  85.  
  86.             FR_OKTEXT        Tells the FR that we specified an alternate
  87.                              OK text in 'extras.oktext'.
  88.  
  89.             FR_CANCELTEXT    Tells the FR that we specified an alternate
  90.                              'Cancel' text in 'extras.canceltext'.
  91.  
  92.             FR_DUALWILD      When you set this flag, the wildcard pattern
  93.                              you provide in 'pattern' is fixed and is applied
  94.                              to all files in the FR.  The user then gets a
  95.                              second wildcard in the Wildcard gadget.  (this
  96.                              defauls to #?).  In essence, this allows you
  97.                              to specify a pattern that will appply to ALL
  98.                              the FR, no matter what the user selects as a
  99.                              wildcard.  The user's wildcard is applied to
  100.                              a file after it passes from the first wildcard.
  101.  
  102.             FR_FRONTSCREEN   Forces the FR to come up on the front screen.
  103.  
  104.             FR_NOTEXTSHADOW  Turns off the text shadowing in all of the FR.
  105.  
  106.             FR_NEWFONT       Tells the FR to use a different font than the
  107.                              standard Topaz 8.  This can be any fixed spacing
  108.                              font from 5 to 16 in size.  NO sanity checking is
  109.                              done on the font size.  It is up to you to see
  110.                              how the font looks like.  The FR will rescale
  111.                              everything to suit the new font.  You need to
  112.                              provide a pointer to a TextFont structure in
  113.                              extras->NewFont.
  114.  
  115.             FR_SCREENFONT    As above, but uses the current font on the screen
  116.                              the FR will show up on.  This always overrides
  117.                              FR_NEWFONT.
  118.  
  119.             FR_REPLACEIMAGES Replaces the standard images in the FR with
  120.                              the users's own.  The ExtraData struct below
  121.                              shows where to place each pointer.  You can
  122.                              use any depth of bitplanes as long as they match
  123.                              the same width/height as the original gadgets.
  124.                              Be creative!  Note that the size of the imagery
  125.                              changes with the requested font size.
  126.  
  127.             FR_EXTENDEDSELECT Read the section on Extended Select below.
  128.  
  129.             FR_INVERTLOOK    Set this flag for an 'inverted' look for the file
  130.                              list.  This is intended for use with 'save' calls
  131.                              so that the user gets a visual difference between
  132.                              save and load requesters.
  133.  
  134.             FR_HIDEWILD      Set this flag and point extras.Hide to a character
  135.                              string of at least 32 bytes.  This should contain
  136.                              the default wildcard pattern to Hide.  i.e. any
  137.                              file matching this wildcard will not be shown in
  138.                              the file list.
  139.  
  140.             FR_NEWLOOK       If you set this flag the FR will change the
  141.                              way it looks to make it match the look of
  142.                              Intuition 2.0 and above.  This is automatically
  143.                              set if Intuition's version number is 36 or more.
  144.                              You should set this flag if you know that you
  145.                              are running under 2.0 or above.  The automatic
  146.                              enable might be removed in a later version.
  147.  
  148.  
  149.         These flags are defined in KDBase.h.  You can OR any of these flags
  150.         together.  There are no restrictions on which flags can be or'd with
  151.         others.
  152.  
  153.         The 'extras' is a struct ExtraData (as defined in KDBase.h).
  154.  
  155.  
  156.         struct ExtraData {
  157.             struct Image *UpArrow;          /* replacement image for Up Arrow */
  158.             struct Image *DnArrow;          /* replacement image for Down Arrow */
  159.             struct Image *DiskNormal;       /* replacement image for Disks */
  160.             struct Image *DiskSelected;     /* replacement select image for Disks */
  161.             struct Image *SizeStrip;        /* replacement image for Size gadgets */
  162.             UBYTE        *oktext;           /* text to be used as OK text */
  163.             UBYTE        *canceltext;       /* text to be used as CANCEL text */
  164.             USHORT       LeftEdge,TopEdge,Width,Height;
  165.             struct TextFont *NewFont;       /* New Font to use instead of Topaz 8 */
  166.             struct FileList *ExtendedList;    /* Always set to NULL at first call.  */
  167.                                             /* If FR_EXTENDEDSELECT is set, this will */
  168.                                             /* return a linked list of FileList structs. */
  169.  
  170.             UBYTE *Hide;                    /* Default hide wildcard */
  171.                                             /* Must set FR_HIDEWILD for it to be used */
  172.                                             /* Will contain a copy of the last wildcard */
  173.                                             /* the user set before exiting the FR on exit */
  174.  
  175.             ULONG unused[4];                /* for future expansion.  Always set to NULL */
  176.  
  177.             };
  178.  
  179.         You can request a specific LeftEdge, TopEdge, Width, and Height
  180.         by giving a non-zero value in any of the above arguments.  However,
  181.         it is recommended that you do not.  The requester will attempt to
  182.         come back up where it was the last time if you don't give it the
  183.         FR_AUTOSIZE and/or FR_AUTOPOSITION flags.  The default values are:
  184.  
  185.             LeftEdge    120
  186.             TopEdge      20
  187.             Width       400
  188.             Height      152
  189.  
  190.         'oktext' is the text that will be shown in the 'OK' gadget.  This
  191.         should be something like "Load" or "Save" or whatever.  The string
  192.         must not be longer than 7 characters or it will be truncated.  Make
  193.         sure that you set the FR_OKTEXT as described above.
  194.  
  195.         'canceltext' is the text that will be shown in the 'Cancel' gadget.
  196.         This should be something like "No!" or whatever.  The string
  197.         must not be longer than 7 characters or it will be truncated.  Make
  198.         sure that you set the FR_CANCELTEXT as described above.
  199.  
  200. RESULT
  201.  
  202.         directory   -   selected path
  203.         filename    -   selected file
  204.         pattern     -   last pattern used
  205.         result      -   1 = success, 0 = requester cancelled or failed.
  206.  
  207.         Note:   UBYTE directory must be least UBYTE [128] in size.
  208.                 and filename and pattern, [32].
  209.  
  210.                 e.g.
  211.  
  212.                 UBYTE directory[128];
  213.                 UBYTE filename[32];
  214.                 UBYTE pattern[32];
  215.  
  216.                 Also, make sure that they are either initialized with
  217.                 default values, or zero'd out.
  218.  
  219. BUGS
  220.  
  221.         None.
  222.  
  223. EXAMPLE
  224.  
  225.         See the file test.c for a detailed example.
  226.  
  227.  
  228.  
  229.                                 EXTENDED SELECT
  230.                                -----------------
  231.  
  232. The FR can allow the user to select multiple files from a single directory.
  233. To turn on this mode, you must set the FR_EXTENDEDSELECT flag in the FReq()
  234. call.  You must also define an extras structure and pass it in the call.
  235. Make sure that extras.ExtendedList is NULL'd out before the first time you
  236. call FReq().
  237.  
  238. When the FReq() call returns, you can check whether or not the user selected
  239. multiple files by checking to see if extras.ExtendedList contains a value.
  240. If it is not NULL, then it points to a linked list of struct FileList entries.
  241.  
  242. This returned list is yours until you free it.  The library will not free it
  243. for you unless you call FReq() again without clearing the extras.ExtendedList
  244. pointer.  
  245.  
  246.  
  247. The following is an example of how to use the Extended Select mode:
  248.  
  249.     struct ExtraData extras;
  250.     struct FileList *ext;
  251.  
  252.     extras.ExtendedList = NULL;
  253.  
  254.     if (FReq(NULL,"Test",name,dir,pat,
  255.         FR_EXTENDEDSELECT | FR_AUTOPOSITION | FR_AUTOSIZE,&extras))
  256.         {
  257.         printf("File Selected: %s%s\n",dir,name);
  258.  
  259.         if (extras.ExtendedList)    /* Check if the user selected a */
  260.             {                       /* list of files. */
  261.             ext = extras.ExtendedList;
  262.  
  263.             printf("\nExtended Select List:  (%ld bytes)\n\n",ext->private);
  264.             printf("    Size  File Name\n");
  265.             printf(" -------  -----------------------------------------\n");
  266.  
  267.             /* This just prints out the selected files and their size. */
  268.             for (; ext; ext = ext->next)
  269.                 {
  270.                 printf("%8ld  %s%s\n",ext->FileSize,directory,ext->FileName);
  271.                 } 
  272.  
  273.             /* VERY IMPORTANT!!  YOU MUST HAVE THIS IN! */
  274.             /* If the call returned a pointer to an ExtendedList */
  275.             /* then you must free it before you exit with the following */
  276.             /* FreeMem() call. */
  277.             /* You can also just leave the extras.ExtendedList pointer */
  278.             /* in the extras struct when you call FReq() again.  Freq() */
  279.             /* In this case will FreeMem() the list for you and give you */
  280.             /* a new one if need be. */
  281.             FreeMem(extras.ExtendedList,extras.ExtendedList->private);
  282.  
  283.             /* Clear out list pointer so that a subsequent call to FReq() */
  284.             /* doesn't try to FreeMem() it. */
  285.             extras.ExtendedList = NULL;
  286.             }    
  287.         }
  288.  
  289.  
  290. Notes:
  291.  
  292. - It is best to AllocMem() the extras structure since that will ensure that
  293.   it is all NULL'd out before use.
  294.  
  295. - The call returns both a normal file name and a list of files.  It is up to
  296.   the calling program to clarify this point to the user.
  297.  
  298. - Check out the manx.ext.test.c file for the full example on how to use
  299.   this facility.
  300.  
  301. - The FR_User.DOC file contains all the details on how the user can use the
  302.   Extended Select mode.
  303.  
  304. ------------------------------------------------------------------------------
  305. kd_freq.library/Path
  306.  
  307. NAME
  308.  
  309.         Path - expand a file name to its full path.
  310.  
  311. SYNOPSIS
  312.  
  313.         Path(filename);
  314.  
  315.         UBYTE *filename;
  316.  
  317.  
  318. FUNCTION
  319.  
  320.         Accepts a string that a valid AmigaDOS file or directory name and
  321.         expands it to the full path leading to the file/directory name.
  322.  
  323. RESULT
  324.  
  325.         filename    -   full path 
  326.  
  327.         Note:   UBYTE *filename must be least UBYTE [128] in size.
  328.  
  329.                 e.g.    UBYTE filename[128];
  330.  
  331.         The string is terminated with either a / or a : depending on whether
  332.         it is a valid directory or device.
  333.  
  334.         If the filename is not a valid file name, then 'filename' is truncated
  335.         to 0 length;
  336.  
  337.  
  338. BUGS
  339.  
  340.         None.
  341.  
  342.  
  343. EXAMPLE
  344.  
  345.         UBYTE filename[128] = "dh0:";
  346.  
  347.         Path(filename);
  348.  
  349. ------------------------------------------------------------------------------
  350. kd_freq.library/PatMatch
  351.  
  352. NAME
  353.  
  354.         PatMatch - do AmigaDOS style wild card filename pattern matching.
  355.  
  356. SYNOPSIS
  357.  
  358.         result = PatMatch(pattern,filename);
  359.  
  360.         LONG  result
  361.         UBYTE *pattern;
  362.         UBYTE *filename;
  363.  
  364.  
  365. FUNCTION
  366.  
  367.         Accepts a string that is a valid AmigaDOS file name (filename) and
  368.         a valid AmigaDOS wild card pattern and tells you whether the
  369.         filename matches the pattern or not.
  370.  
  371.         Supported wildcards in pattern:
  372.  
  373.             1.  Standard AmigaDOS Wildcards:
  374.             --------------------------------
  375.  
  376.             ?   Matches any single character
  377.             #p  Match any number of occurences of the pattern p
  378.             %   Matches the null string
  379.             ()  Make a group of characters into a single pattern
  380.             |   The OR operator
  381.             '   Disable wildcard interpretation of next character
  382.                 (unless it is an extended wildcard as shown below.)
  383.  
  384.             2.  Extended Wildcards:
  385.             -----------------------
  386.  
  387.             These are wildcards not supported by the standard AmigaDOS
  388.             convention, but expand it to make it more versatile.
  389.  
  390.             'd  Matches any single digit.  (0 to 9)
  391.             'a  Matches any single alpha character. (a to z)
  392.             'n  Matches any single alphanumeric character.
  393.  
  394.         For examples of standard wildcard usage, look up any AmigaDOS
  395.         tutorial book.
  396.  
  397.         Examples of extended wildcards:
  398.  
  399.         Pattern     Matching possibilities
  400.         -------     ----------------------
  401.         test'n      test0, test1, test9, testa, testA, testz, testZ
  402.         test'd      test0, test1, test9
  403.         test'a      testa, testA, testz, testZ
  404.         test 'd     test 1, test 2, test 9
  405.         test#'d     test1, test100, test10234
  406.         #'a#'d      a1, ab12, abc1, abc123, adks34234
  407.                     (matches any string with some or no alpha characters,
  408.                     then some or no digits.)
  409.         #'a'd#'d.c  a1.c, a203.c, 100.c, 1.c, adsdfs931234.c
  410.                     (matches any string that starts with some of no alpha
  411.                     characters, then at least 1 or more digits, and ends
  412.                     with .c)
  413.  
  414. RESULT
  415.  
  416.         result = -1     Syntax error in wildcard pattern.
  417.         result =  0     Filename did not match pattern.
  418.         result =  1     Filename matched pattern.
  419.  
  420. BUGS
  421.  
  422.         None.
  423.  
  424.  
  425. EXAMPLE
  426.  
  427.         LONG result;
  428.  
  429.         result = PatMatch("#?.c","test.c");
  430.  
  431.         This will result in:  result == 1
  432.  
  433. ------------------------------------------------------------------------------
  434. If you have any trouble getting any call to work, don't hesitate to email me
  435. on Compuserve 75166,2531 or leave me a message in the AmigaTech forum on CIS
  436. or mail/fax me at the address at the end of the FR_User.doc file.
  437. ------------------------------------------------------------------------------
  438.                   Copyright 1990  Khalid Aldoseri.
  439.                              19 July 1990.
  440. ------------------------------------------------------------------------------
  441.