home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / TRSICAT.LZX / CATS_CD2_TRSI / Inc&AD2.0 / Text_Autodocs / asl.doc < prev    next >
Encoding:
Text File  |  1992-09-02  |  10.4 KB  |  330 lines
  1. TABLE OF CONTENTS
  2.  
  3. asl.library/AllocAslRequest
  4. asl.library/AllocFileRequest
  5. asl.library/AslRequest
  6. asl.library/FreeAslRequest
  7. asl.library/FreeFileRequest
  8. asl.library/RequestFile
  9.  
  10.  
  11. asl.library/AllocAslRequest               asl.library/AllocAslRequest
  12.  
  13.   NAME
  14.     AllocAslRequest -- alloc an ASL requester, with TagItem modifiers (V36)
  15.  
  16.   SYNOPSIS
  17.     request = AllocAslRequest( type, ptags )
  18.     D0               D0     A0
  19.  
  20.     APTR    request;
  21.     ulong    type;
  22.     struct TagItem    *ptags;
  23.  
  24.   FUNCTION
  25.     Allocates an ASL requester data structure of the specified type,
  26.     with optional TagItem modifiers.
  27.  
  28.   INPUTS
  29.     type = type of requester to create.  Currently defined types
  30.         include ASL_FileRequest and ASL_FontRequest.
  31.     ptags = pointer to a tagitem array, which is defined for each
  32.         specified type.  See "asl.h" and example programs for usage
  33.         of various tag types.  See AslRequest() for specifications
  34.         of currently defined tag values and their effects.
  35.  
  36.     Note that tag values stay in effect for each use of the
  37.     requester until they are cleared or modified by passing the
  38.     same tag with a new value.
  39.  
  40.     AllocAslRequestTags( type, tags... ) which accepts your tags
  41.     on the stack, is available in amiga.lib.
  42.  
  43.     Example Usage: AllocAslRequestTags( ASL_FileRequest,
  44.                             ASL_Hail, "My Title Bar",
  45.                             TAG_DONE );
  46.  
  47.   RESULT
  48.     Pointer to an initialized requester data structure, or NULL on
  49.     failure.  The data structure returned will match the requested
  50.     type; for type ASL_FileRequest, a struct FileRequester *; for
  51.     ASL_FontRequest, a struct FontRequester *.
  52.  
  53.     The requester returned may then be passed to AslRequest(), and
  54.     is freed by calling FreeAslRequest().
  55.  
  56.   SEE ALSO
  57.     AslRequest(), FreeAslRequest()
  58.  
  59.  
  60. asl.library/AllocFileRequest               asl.library/AllocFileRequest
  61.  
  62.   NAME
  63.     AllocFileRequest -- allocates a FileRequester structure (V36)
  64.  
  65.   SYNOPSIS
  66.     request = AllocFileRequest()
  67.     D0
  68.  
  69.     struct FileRequester *request;
  70.     
  71.   FUNCTION
  72.     Creates and initializes the data structure required to pass to the
  73.     RequestFile() function.
  74.  
  75.   INPUTS
  76.     None.  If you wish to get other than default values, you can use
  77.     AllocAslRequest() to set up a file request with tag items.
  78.  
  79.   RESULT
  80.     Pointer to a struct FileRequester, which is to be passed to the
  81.     RequestFile() function.
  82.  
  83.     The returned FileRequester pointer has public fields which are
  84.     readable by the application as defined in aslbase.h. 
  85.  
  86.   CAUTION
  87.     The application MUST use either the AllocFileRequest(), or
  88.     AllocAslRequest(), function to allocate the structure to be passed to
  89.     the FileRequest() or AslRequest() functions; it is not possible to
  90.     create a struct FileRequest except through the library calls.
  91.  
  92.     Also, any modifications MUST be done through TagItem values, rather
  93.     than directly modifying, unless explicitly documented otherwise.
  94.  
  95.   SEE ALSO
  96.     RequestFile(), FreeAslRequest(), AslRequest()
  97.  
  98.  
  99. asl.library/AslRequest                     asl.library/AslRequest
  100.  
  101.   NAME
  102.     AslRequest -- get input from user for an ASL requester (V36)
  103.  
  104.   SYNOPSIS
  105.     BOOL result = AslRequest( request, ptags );
  106.     D0                        A0       A1
  107.  
  108.     BOOL    result;
  109.     APTR    request;
  110.     struct TagItem    *ptags;
  111.  
  112.   FUNCTION
  113.     Prompts the user for input, based on the specific type of
  114.     requester and modifying tagitems.  The actions and results
  115.     are specific to the type but in general the action is to open
  116.     a requesting window prompting the user for a specific input.
  117.     If the user cancels or the system aborts the request, NULL
  118.     is returned, otherwise the request data structure readable
  119.     data reflects the user input.
  120.     Note that tag values stay in effect for each use of the
  121.     requester until they are cleared or modified by passing the
  122.     same tag with a new value.
  123.  
  124.   INPUTS
  125.     request = requester structure allocated with AllocAslRequest().
  126.     ptags = pointer to an array of TagItems which may be used to
  127.         modify the requester.
  128.  
  129.     AslRequestTags( type, tags... ) which accepts your tags
  130.     on the stack, is available in amiga.lib.
  131.  
  132.     Example Usage: AslRequestTags( ASL_FileRequest,
  133.                        ASL_Hail, "My Title Bar",
  134.                        TAG_DONE );
  135.  
  136.   TAGS
  137.  
  138.     ( REMEMBER - ALL DATA STRUCTURES ARE READ-ONLY EXCEPT BY USING
  139.       TAGITEMS !!! )
  140.  
  141.     ASL_Hail (STRPTR) - Hailing text to prompt user, typically
  142.         displayed in window title bar.
  143.     ASL_Window (struct Window *) - Parent window for the request
  144.         function, which is used to select the screen on which the
  145.         requesting window will be displayed and also is used for
  146.         a shared IDCMP port.
  147.  
  148.     ASL_LeftEdge (WORD) - Preferred display position for left edge where
  149.         request window should open.
  150.     ASL_TopEdge (WORD) - Preferred top edge of request window.
  151.     ASL_Width (WORD)   - Preferred width of request window.
  152.     ASL_Height (WORD)  - Preferred height of request window.
  153.  
  154.     ASL_HookFunc (APTR) - Pointer to callback function, specific to
  155.         each AslRequest type.
  156.  
  157.     ASL_File (STRPTR) - FileRequester initial filename string.
  158.     ASL_Dir (STRPTR) - FileRequester initial directory path string.
  159.  
  160.     ASL_FontName (STRPTR) - FontRequester initial fontname string.
  161.     ASL_FontHeight (UWORD) - FontRequester initial height (ta_YSize).
  162.     ASL_FontStyles (UBYTE) - FontRequester initial styles (ta_Style).
  163.     ASL_FontFlags (UBYTE) - FontRequester initial flags (ta_Flags).
  164.     ASL_FrontPen (BYTE) - FontRequester front pen color (fo_FrontPen).
  165.     ASL_BackPen (BYTE) - FontRequester back pen color (fo_BackPen).
  166.     ASL_MinHeight (UWORD) - Minimum height for FontRequester display
  167.         of font sizes.  (Application must check return value).
  168.     ASL_MaxHeight (UWORD) - Maximum height for FontRequester display
  169.         of font sizes. (Application must check ta_YSize returned).
  170.  
  171.     ASL_OKText (STRPTR) - Replacement for default "OK" gadget text.
  172.         ( Limited to approx. six characters ).
  173.     ASL_CancelText (STRPTR) - Replacement for default "CANCEL"
  174.         gadget text. ( Limited to approx. six characters ).
  175.  
  176.     ASL_FuncFlags (ULONG) - Function flags, depends on requester
  177.         type.  Example: FILF_SAVE for FileRequester.
  178.     ASL_ExtFlags1 (ULONG) - Extended flags (to pass FILF1_ bitdefs)
  179.            Example: FIL1F_NOFILES for file requester
  180.  
  181.   RESULT
  182.     If NULL, typically the user cancelled the requester or a system
  183.     failure prevented the requester from being opened.  If non-zero,
  184.     values will be set depending on the particular type of request,
  185.     in the requesting data structure.  See "libraries/asl.h" for
  186.     information on the READ-ONLY fields in each specific type of
  187.     requester.
  188.  
  189.   NOTES
  190.  
  191.     Asl provides a way for applications to interact with requester
  192.     operation via a callback (hook) function.  For the ASL file and
  193.     font requesters, there are two ASL_FuncFlags to specify that you
  194.     want a callback:
  195.  
  196.          for FileRequester: FILF_DOWILDFUNC and FILF_DOMSGFUNC
  197.          for FontRequester: FONF_DOWILDFUNC and FONF_DOMSGFUNC
  198.  
  199.     The DOWILDFUNC allows you to perform the pattern matching.
  200.     The DOMSGFUNC allows you to handle IDCMP messages received
  201.     for windows that are sharing a UserPort with the requester.
  202.  
  203.     If you set one or both of these flags via the ASL_FuncFlags
  204.     tagitem, you must provide a pointer to your hook function
  205.     using the ASL_HookFunc tagitem.  Your function will be called
  206.     as follows:
  207.     
  208.      ULONG rf_Function(ULONG Mask, CPTR Object, CPTR AslRequester)
  209.     
  210.     The Mask value is a copy of the specific ASL_FuncFlag value
  211.     the callback is for.  Object is a pointer to a data object
  212.     specific to the reason for the callback (defined by Mask).
  213.     AslRequester is a pointer to the requester structure.
  214.  
  215.     Note that you can only define one HookFunc per requester.
  216.     Your hook function must examine the Mask passed to it to
  217.     determine what the callback is for and what the Object is.
  218.  
  219.     The following table will explain what is passed to, and
  220.     expected to be returned by a hook functions for various masks:
  221.  
  222.     FileRequester DOWILDFUNC
  223.     Purpose: to accept or reject individual files for display list
  224.     Inputs:    Mask        = FILF_DOWILDFUNC
  225.         Object        = struct AnchorPath *
  226.         AslRequester    = struct FileRequester *
  227.     Result: You return zero to accept file for display in list
  228.  
  229.  
  230.     FontRequester DOWILDFUNC
  231.     Purpose: to accept or reject individual fonts for display list
  232.     Inputs:    Mask        = FONF_DOWILDFUNC
  233.         Object        = struct TextAttr *
  234.         AslRequester    = struct FontRequester *
  235.     Result: You return non-zero to accept font for display in list
  236.  
  237.  
  238.     FileRequester (or FontRequester) DOMSGFUNC 
  239.     Purpose: to handle IDCMP msgs for other windows sharing port
  240.     Inputs:    Mask        = FILF_DOMSGFUNC (FONF_DOMSGFUNC)
  241.         Object        = struct IntuiMessage *
  242.         AslRequester    = struct FileRequester (FontRequester) *
  243.     Result: You must return the Object pointer (asl will Reply the Object)
  244.  
  245.   SEE ALSO
  246.     AllocAslRequest(), FreeAslRequest()
  247.  
  248.  
  249. asl.library/FreeAslRequest                 asl.library/FreeAslRequest
  250.  
  251.   NAME
  252.     FreeAslRequest - frees requester obtained from AllocAslRequest (V36)
  253.  
  254.   SYNOPSIS
  255.     FreeAslRequest( request )
  256.             A0
  257.  
  258.     APTR request;
  259.  
  260.   FUNCTION
  261.     FreeAslRequest() is used to free the structure returned by
  262.     AllocAslRequest() or AllocFileRequest(), in order to free
  263.     all resources associated with that requester after the
  264.     application has completed all use of the data structures.
  265.  
  266.   INPUTS
  267.     request - value returned from AllocAslRequest() or
  268.             AllocFileRequest().
  269.  
  270.   RESULT
  271.     None.  All resources associated with the request will be
  272.     freed.
  273.  
  274.   SEE ALSO
  275.     AllocAslRequest(), AslRequest(), AllocFileRequest()
  276.  
  277.  
  278. asl.library/FreeFileRequest                asl.library/FreeFileRequest
  279.  
  280.   NAME
  281.     FreeFileRequest -- frees requester allocated by AllocFileRequest (V36)
  282.  
  283.   SYNOPSIS
  284.     FreeFileRequest( request )
  285.              A0
  286.  
  287.     struct FileRequester *request;
  288.  
  289.   FUNCTION
  290.     This function is identical to the FreeAslRequest() function, but is
  291.     documented for source code compatability and ease of use.
  292.     Applications may use either FreeAslRequest() or FreeFileRequest() to
  293.     free the data structures allocated by AllocFileRequest().
  294.  
  295.   INPUTS
  296.     request = the return value from AllocFileRequest().
  297.  
  298.   SEE ALSO
  299.     FreeAslRequest()
  300.  
  301. asl.library/RequestFile                    asl.library/RequestFile
  302.  
  303.   NAME
  304.     RequestFile -- request user to select file(s) (V36)
  305.  
  306.   SYNOPSIS
  307.     BOOL result = RequestFile( request )
  308.     D0                         A0
  309.  
  310.     BOOL    result;
  311.     struct FileRequester *request;
  312.  
  313.   FUNCTION
  314.     RequestFile() displays a file requester and waits for the user to
  315.     select filenames or cancel the request.  This function is identical
  316.     to the AslRequest() function, except that there is no TagList to
  317.     modify the settings for the requester.  See AslRequest() for details.
  318.  
  319.   INPUT
  320.     request = struct FileRequester * returned by AllocFileRequest().
  321.  
  322.   RESULT
  323.     result - See AslRequest() result.  NULL indicates cancelled.
  324.  
  325.   SEE ALSO
  326.     AllocFileRequest(), FreeFileRequest(), AslRequest()
  327.  
  328.  
  329.  
  330.