home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 (Alt) / MACD 5.bin / workbench / libs / multireqlib.lha / MultiReq / Documentation / Library.doc < prev    next >
Encoding:
Text File  |  1992-11-12  |  15.1 KB  |  557 lines
  1. ###############################################################################
  2. ##                                                                           ##
  3. ##      M     M            ll     tt     ii    RRRRR                         ##
  4. ##      MM   MM            ll     tt           RR  RR                        ##
  5. ##      MMM MMM   uu  uu   ll    ttttt   ii    RR  RR    eeee     qqqqq      ##
  6. ##      MMMMMMM   uu  uu   ll     tt     ii    RRRRR    ee  ee   qq  qq      ##
  7. ##      MM M MM   uu  uu   ll     tt     ii    RR RR    eeeeee   qq  qq      ##
  8. ##      MM   MM   uu  uu   ll     tt     ii    RR  RR   ee        qqqqq      ##
  9. ##      MM   MM    uuuuu    ll     ttt    ii   RR  RR    eeee        qq      ##
  10. ##                                                                   qq      ##
  11. ##                                                                           ##
  12. ###############################################################################
  13.  
  14.  
  15. MultiReq v1.20 © 11/1992 by Andreas Krebs (released at 12-Nov-92)
  16.  
  17.  
  18. This file contains a detailed description of all functions of the
  19. "multireq.library". The functions are listed according to there offsets.
  20. All this functions ONLY change those registers, that are mentioned as RESULTS
  21. and sometimes D0 als return value. All other registers are not changed, also if
  22. they are used as parameters.
  23.  
  24.  
  25.  
  26. multireq.library/StrLen                                  multireq.library/StrLen
  27.  
  28. NAME
  29.   StrLen -- returns the length of a text string
  30.  
  31. SYNTAX
  32.   length = StrLen( str )
  33.   D0       -30     A0
  34.  
  35.   UWORD StrLen( UBYTE * )
  36.  
  37. FUNCTION
  38.   This function returns the length of a text string, whereby the length is
  39.   counted without the final nullbyte.
  40.  
  41. INPUTS
  42.   str - Pointer to a nullterminated string
  43.  
  44. RESULTS
  45.   length - length of the string in bytes
  46.   A0     - address of the final nullbyte
  47.  
  48. SEE ALSO
  49.   StrCpy, StrCmp, StrIns, UpperCase, TestPattern
  50.  
  51.  
  52.  
  53. multireq.library/StrCpy                                  multireq.library/StrCpy
  54.  
  55. NAME
  56.   StrCpy -- copies a text string into another
  57.  
  58. SYNTAX
  59.   StrCpy( src, dest )
  60.   -36     A0   A1
  61.  
  62.   void StrCpy( UBYTE *, UBYTE * )
  63.  
  64. FUNCTION
  65.   This function copies the text string src into the string dest, whereby the
  66.   copy-procedure ends, when the final nullbyte is reached.
  67.  
  68. INPUTS
  69.   src  - pointer to the nullterminated source string
  70.   dest - pointer to a buffer for the destination string
  71.  
  72. RESULTS
  73.   A0 - address of the final nullbyte of the source string
  74.   A1 - address of the final nullbyte of the destination string
  75.  
  76. SEE ALSO
  77.   StrLen, StrCmp, StrIns, UpperCase, TestPattern
  78.  
  79.  
  80.  
  81. multireq.library/StrCmp                                  multireq.library/StrCmp
  82.  
  83. NAME
  84.   StrCmp -- compares two strings
  85.  
  86. SYNTAX
  87.   dif = StrCmp( str1, str2 )
  88.   D0    -42     A0    A1
  89.  
  90.   WORD StrCmp( UBYTE *, UBYTE * )
  91.  
  92. FUNCTION
  93.   This function compares two text strings, whereby no difference is made between
  94.   small and capital letters and also umlauts are considered.
  95.   If dif is < 0, then string str1 is "smaller" than string str2, that means the
  96.   ASCII-code of str1 is lower than that of str2.
  97.   If dif is = 0, then str1 and str2 are equal.
  98.   If dif is > 0, then str1 is "larger" than str2.
  99.  
  100. INPUTS
  101.   str1 - pointer to the first nullterminated string
  102.   str2 - pointer to the second nullterminated string
  103.  
  104. RESULTS
  105.   dif - difference between str1 and str2
  106.   A0  - address of the different character in str1
  107.   A1  - address of the different character in str2
  108.  
  109. SEE ALSO
  110.   StrLen, StrCpy, StrIns, UpperCase, TestPattern
  111.  
  112.  
  113.  
  114. multireq.library/StrIns                                  multireq.library/StrIns
  115.  
  116. NAME
  117.   StrIns -- inserts a text string into another
  118.  
  119. SYNTAX
  120.   StrIns( src, dest )
  121.   -48     A0   A1
  122.  
  123.   void StrIns( UBYTE *, UBYTE * )
  124.  
  125. FUNCTION
  126.   This function inserts a text string into another, therefore the destination
  127.   string dest is first shifted StrLen( src ) characters and afterwards src is
  128.   placed into the formed gap.
  129.  
  130. INPUTS
  131.   src  - pointer to the string to be inserted
  132.   dest - pointer to the position, where the string should be inserted
  133.  
  134. RESULTS
  135.  
  136. SEE ALSO
  137.   StrLen, StrCpy, StrCmp, UpperCase, TestPattern
  138.  
  139.  
  140.  
  141. multireq.library/UpperCase                            multireq.library/UpperCase
  142.  
  143. NAME
  144.   UpperCase -- converts a character into a capital character
  145.  
  146. SYNTAX
  147.   character = Uppercase( character )
  148.   D0          -54        D0
  149.  
  150.   UBYTE UpperCase( UBYTE )
  151.  
  152. FUNCTION
  153.   This function converts the given symbol into a capital character, if is a
  154.   character. Special symbols like Unlauts are also considered.
  155.  
  156. INPUTS
  157.   character - the character to be converted
  158.  
  159. RESULTS
  160.   character - the corresponding capital character
  161.  
  162. SEE ALSO
  163.   StrLen, StrCpy, StrCmp, StrIns, TestPattern
  164.  
  165.  
  166.  
  167. multireq.library/TestPattern                        multireq.library/TestPattern
  168.  
  169. NAME
  170.   TestPattern -- tests, if a string matches a given pattern
  171.  
  172. SYNTAX
  173.   result = TestPattern( wild, str )
  174.   D0       -60          A0    A1
  175.  
  176.   BOOL TestPattern( UBYTE *, UBYTE * )
  177.  
  178. FUNCTION
  179.   This function tests, if the text string str matches the pattern wild. The
  180.   wildcard '*' represents a substring of any length and '|' separates two
  181.   patterns from each other.
  182.   During the test no difference is made between small and capital letters,
  183.   therefore e.g. "a*" is identical to "A*".
  184.  
  185. INPUTS
  186.   wild - pointer to the string, containing the pattern
  187.   str  - pointer to the string to be tested
  188.  
  189. RESULTS
  190.   result - TRUE (1), if the string matches the pattern, else FALSE (0)
  191.  
  192. EXAMPLES
  193.   TestPattern( "*.c|*.h", str )   - is str a C source- or include-file ?
  194.   TestPattern( "*.*|*-*", str )   - contains str a '.'- or '-'-symbol ?
  195.   TestPattern( "*", str )         - always TRUE, cause each string matches
  196.                                     this pattern
  197.  
  198. SEE ALSO
  199.   StrLen, StrCpy, StrCmp, StrIns, UpperCase
  200.  
  201.  
  202.  
  203. multireq.library/DelPort                                multireq.library/DelPort
  204.  
  205. NAME
  206.   DelPort -- deletes a message port
  207.  
  208. SYNTAX
  209.   DelPort( port )
  210.   -66      A1
  211.  
  212.   void DelPort( struct MsgPort * )
  213.  
  214. FUNCTION
  215.   This function deletes a message port, therfore it's removed from the systems
  216.   message port list and afterwards the used memory is freed again.
  217.  
  218. INPUTS
  219.   port - pointer to the MsgPort-structure of the message port
  220.  
  221. RESULTS
  222.  
  223. NOTES
  224.   This function is identical to the DeletePort-function of the linker library
  225.   amiga.lib.
  226.  
  227. SEE ALSO
  228.   CrtPort
  229.  
  230.  
  231.  
  232. multireq.library/CrtPort                                multireq.library/CrtPort
  233.  
  234. NAME
  235.   CrtPort -- creates a message port
  236.  
  237. SYNTAX
  238.   port = CrtPort( name, pri )
  239.   D0     -72      A0    D0
  240.  
  241.   struct MsgPort *CrtPort( UBYTE *, UWORD )
  242.  
  243. FUNCTION
  244.   This function creates a message port with the selected name and priority,
  245.   therefore the needed memory is allocated. When created the message port is
  246.   automatically added to the systems message port list.
  247.  
  248. INPUTS
  249.   name - pointer to a nullterminated string with the name or 0 for no name
  250.   pri  - priority the message port should have
  251.  
  252. RESULTS
  253.   port - pointer to the MsgPort-structure of the message port or 0 if an
  254.   error occured
  255.  
  256. NOTES
  257.   This function is identical to the CreatePort-function of the linker library
  258.   amiga.lib.
  259.  
  260. SEE ALSO
  261.   DelPort
  262.  
  263.  
  264.  
  265. multireq.library/GetCurrentPath                  multireq.library/GetCurrentPath
  266.  
  267. NAME
  268.   GetCurrentPath -- locates the name and path of the current directory
  269.  
  270. SYNTAX
  271.   GetCurrentPath( bufff )
  272.   -78             A0
  273.  
  274.   void GetCurrentPath( UBYTE * )
  275.  
  276. FUNCTION
  277.   This function locates the name and the path of the current directory and
  278.   writes it to the buffer defined by buff.
  279.  
  280. INPUTS
  281.   buff - pointer to a buffer, in which the name should be written
  282.  
  283. RESULTS
  284.  
  285.  
  286.  
  287. multireq.library/DrawBox                                multireq.library/DrawBox
  288.  
  289. NAME
  290.   DrawBox -- draws a rectangle with 3D-effect
  291.  
  292. SYNTAX
  293.   DrawBox( rp, x1, y1, x2, y2, col1, col2 )
  294.   -84      A1  D0  D1  D2  D3  D4    D5
  295.  
  296.   void DrawBox( struct RastPort *, UWORD, UWORD, UWORD, UWORD, UWORD, UWORD )
  297.  
  298. FUNCTION
  299.   This function draws a rectangle with 3D-effect in the specified size, whereby
  300.   the left and top border are drawn in the Color col1 and the right and bottom
  301.   one in the color col2.
  302.   
  303. INPUTS
  304.   rp   - pointer to the RastPort, that should be drawn to
  305.   x1   - x-position of the left top edge
  306.   y1   - y-position of the left top edge
  307.   x2   - x-position of the right bottom edge
  308.   y2   - y-position of the right bottom edge
  309.   col1 - color of the left and top border
  310.   col2 - color of the right and bottom border
  311.  
  312. RESULTS
  313.  
  314. NOTES
  315.   It has to made save, that x1<x2 and y1<y2, cause otherwise there might be a
  316.   crash.
  317.  
  318. SEE ALSO
  319.   DrawFilledBox
  320.  
  321.  
  322.  
  323. multireq.library/DrawFilledBox                    multireq.library/DrawFilledBox
  324.  
  325. NAME
  326.   DrawFilledBox -- draws a filled rectangle with 3D-effect
  327.  
  328. SYNTAX
  329.   DrawFilledBox( rp, x1, y1, x2, y2, col1, col2, fillcol )
  330.   -90            A1  D0  D1  D2  D3  D4    D5    D6
  331.  
  332.   void DrawFilledBox( struct RastPort *, UWORD, UWORD, UWORD, UWORD, UWORD,
  333.                       UWORD, UWORD )
  334.  
  335. FUNCTION
  336.   This function draws a filled rectangle with 3D-effect in the specified size,
  337.   therefore first the inside is filled in the color fillcol and afterwards the 
  338.   border is drawn with DrawBox.
  339.   
  340. INPUTS
  341.   rp      - pointer to the RastPort, that should be drawn to
  342.   x1      - x-position of the left top edge
  343.   y1      - y-position of the left top edge
  344.   x2      - x-position of the right bottom edge
  345.   y2      - y-position of the right bottom edge
  346.   col1    - color of the left and top border
  347.   col2    - color of the right and bottom border
  348.   fillcol - color, that should be used to fill the inside of the rectangle 
  349.  
  350. RESULTS
  351.  
  352. NOTES
  353.   It has to made save, that x1<x2 and y1<y2, cause otherwise there might be a
  354.   crash.
  355.  
  356. SEE ALSO
  357.   DrawBox
  358.  
  359.  
  360.  
  361. multireq.library/DrawTexts                            multireq.library/DrawTexts
  362.  
  363. NAME
  364.   DrawTexts -- draws several texts of the same style
  365.  
  366. SYNTAX
  367.   DrawTexts( rp, textlist)
  368.   -96        A1  A0
  369.  
  370.   void DrawTexts( struct RastPort *, struct MRText * )
  371.  
  372. FUNCTION
  373.   This function draws several texts, whereby the texts have to of the same
  374.   style, size, drawmode and background color. This parameters have to be set
  375.   before this function is called.
  376.  
  377. INPUTS
  378.   rp       - pointer to the RastPort, that should be drawn to
  379.   textlist - pointer to an array with MRText-structures and an entry with the
  380.              value -1 as last entry  
  381.  
  382. RESULTS
  383.  
  384. EXAMPLES
  385.  
  386.   static struct MRText MyTexts[]=
  387.   {
  388.     { 10, 15,  2,  6, (UBYTE *)"Text 1" },    /* x, y, pen, len, text */
  389.     { 10, 30,  1,  6, (UBYTE *)"Text 2" },
  390.     { -1, -1, -1, -1, (UBYTE *)-1 }           /* last text */
  391.   };
  392.  
  393.   /* */
  394.   DrawTexts(rp, MyTexts);
  395.   /* */
  396.  
  397.  
  398.  
  399. multireq.library/DrawWinBorder                    multireq.library/DrawWinBorder
  400.  
  401. NAME
  402.   DrawWinBorder -- draws a 3D-border around a window
  403.  
  404. SYNTAX
  405.   DrawWinBorder( win, title )
  406.   -102           A0   A1
  407.  
  408.   void DrawWinBorder( struct Window *, UBYTE * )
  409.  
  410. FUNCTION
  411.   This function draws a 3D-border for a window like WorkBench 2.0 does, whereby
  412.   the top border is wider than the other ones, cause he's containing the window
  413.   title. 
  414.   This function should only be used for windows of the type BORDERLESS, cause
  415.   otherwise there might be problems with the windows "normal" border.
  416.   This function is mainly for use under Kickstart 1.3. Under Kickstart 2.0 the
  417.   normal border should be prefered, cause he has more facilities (e.g. system-
  418.   gadgets).
  419.  
  420. INPUTS
  421.   win   - pointer to the window, that's border should be drawn
  422.   title - pointer to a nullterminated string with the window title
  423.  
  424. RESULTS
  425.  
  426.  
  427.  
  428. multireq.library/DrawGadgetBorder              multireq.library/DrawGadgetBorder
  429.  
  430. NAME
  431.   DrawGadgetBorder -- draws a border for a number of gadgets
  432.  
  433. SYNTAX
  434.   DrawGadgetBorder( gadgets, win, numgad )
  435.   -108              A0       A1   D0
  436.  
  437.   void DrawGadgetBorder( struct Gadget *, struct Window *, UWORD )
  438.  
  439. FUNCTION
  440.   This function draws for the given number of gadgets a border. The borders have
  441.   to be defined with the BORDER-macros (see multireq.h or multireq.i) in the
  442.   UserData-entry of the Gadget-structure.
  443.   The macros are used a follows:
  444.  
  445.   BORDER( type, col1, col2, fillcol )
  446.  
  447.   type - border type (see multireq.h or multireq.i)
  448.   col1, col2, fillcol - see DrawFilledBox
  449.  
  450.   A list of all possible border types is located in the include-files
  451.   (multireq.h or multireq.i).
  452.   After drawing the border, it can be necessary to refresh the gadgets (with
  453.   RefreshGadgets or RefreshGList), cause DrawGadgetBorder does no refresh and
  454.   so some other parts of the gadgets (e.g. texts) may be hidden.  
  455.  
  456. INPUTS
  457.   gadgets - pointer to the first gadget in a linked list
  458.   win     - pointer to the window, that contains the gadgets
  459.   numgad  - number of gadgets to draw a border, or -1 for all gadgets
  460.  
  461. RESULTS
  462.  
  463.  
  464.  
  465. multireq.library/InitFileReq                        multireq.library/InitFileReq
  466.  
  467. NAME
  468.   InitFileReq -- initializes a FileReq-structure
  469.  
  470. SYNTAX
  471.   InitFileReq( fr_ptr, numlist )
  472.   -114         A0      D0
  473.  
  474.   void InitFileReq( struct FileReq **, UWORD )
  475.  
  476. FUNCTION
  477.   This function initializes a FileReq-structure, therefore first the needed
  478.   memory is allocated and afterwards all needed datas of the FileRequester are
  479.   created. Afterwards a pointer to the FileReq-structure is written to the
  480.   address defined by fr_ptr.
  481.   The option numlist is not supported in this version, but it should always be
  482.   set to 2, cause otherwise there might be problems with newer version of the
  483.   multireq.library.
  484.  
  485. INPUTS
  486.   fr_ptr  - address of a pointer to a FileReq-structure
  487.   numlist - number of file lists (in this version always 2)
  488.  
  489. RESULTS
  490.  
  491. SEE ALSO
  492.   FreeFileReq, FileRequester
  493.  
  494.  
  495.  
  496. multireq.library/FreeFileReq                        multireq.library/FreeFileReq
  497.  
  498. NAME
  499.   FreeFileReq -- frees a previous initialized FileReq-structure
  500.  
  501. SYNTAX
  502.   FreeFileReq( fr_ptr )
  503.   -120         A0
  504.  
  505.   void FreeFileReq( struct FileReq ** )
  506.  
  507. FUNCTION
  508.   This function frees a FileReq-structure, created by InitFileReq. This also
  509.   includes possibly read in directories. After this the pointer to the structure
  510.   is cleared.  
  511.   This function should be used before a program quits, cause otherwise the
  512.   allocated memory is not returned to the system.  
  513.  
  514. INPUTS
  515.   fr_ptr - address of a pointer to a FileReq-structure
  516.  
  517. RESULTS
  518.  
  519. SEE ALSO
  520.   InitFileReq, FileRequester
  521.  
  522.  
  523.  
  524. multireq.library/FileRequester                    multireq.library/FileRequester
  525.  
  526. NAME
  527.   FileRequester -- starts the FileRequester
  528.  
  529. SYNTAX
  530.   status = FileRequester( filereq, screen )
  531.   D0       -126           A0       A1
  532.  
  533.   UWORD FileRequester( struct FileReq *, struct Screen * )
  534.  
  535. FUNCTION
  536.   This function starts the FileRequester on the screen defined by "screen" (0 =
  537.   WorkBench-screen) and uses therefore the values defined in the FileReq-
  538.   structure. The screen has to be a Hires-screen, cause a Lores-screen is
  539.   because of it's little wide to small for the FileRequester.
  540.   The FileRequester is described in the file "FileReq.doc".
  541.   The parameters of the FileReq-structure are described in the include-files
  542.   "multireq.h" and "multireq.i".
  543.  
  544. INPUTS
  545.   filereq - pointer to a FileReq-structure
  546.   screen  - pointer to the screen, oh which the FileRequester should be
  547.             opened
  548. RESULTS
  549.   status - Contains the status how the FileRequester was quitted. This value
  550.            is identical to the ReturnStatus-entry in the FileReq-structure.
  551.            (A list of all possible statuses is also located in the include-
  552.            files.)
  553.  
  554. SEE ALSO
  555.   InitFileReq, FreeFileReq
  556.  
  557.