@database "asl"
@master "Work:RKM/Includes&Autodocs/doc/asl.doc"

@Node Main "asl.doc"
@toc "2.0Includes_Autodocs/Autodocs"

@{" AllocAslRequest() " Link "AllocAslRequest()"}     @{" AslRequest() " Link "AslRequest()"}        @{" FreeFileRequest() " Link "FreeFileRequest()"}
@{" AllocFileRequest() " Link "AllocFileRequest()"}    @{" FreeAslRequest() " Link "FreeAslRequest()"}    @{" RequestFile() " Link "RequestFile()"}

@EndNode

@Node "AllocAslRequest()" "asl.library/AllocAslRequest"

NAME
    AllocAslRequest -- alloc an ASL requester, with @{"TagItem" Link "ADCD_v1.2:Inc&AD2.0/Includes/utility/tagitem.h/Main" 31} modifiers (V36)

SYNOPSIS
    request = AllocAslRequest( type, ptags )
    D0                         D0    A0

    APTR    request;
    ulong   type;
    struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.0/Includes/utility/tagitem.h/Main" 31}       *ptags;

FUNCTION
    Allocates an ASL requester data structure of the specified type,
    with optional @{"TagItem" Link "ADCD_v1.2:Inc&AD2.0/Includes/utility/tagitem.h/Main" 31} modifiers.

INPUTS
    type = type of requester to create.  Currently defined types
        include ASL_FileRequest and ASL_FontRequest.
    ptags = pointer to a tagitem array, which is defined for each
        specified type.  See "asl.h" and example programs for usage
        of various tag types.  See @{"AslRequest()" Link "AslRequest()"} for specifications
        of currently defined tag values and their effects.

    Note that tag values stay in effect for each use of the
    requester until they are cleared or modified by passing the
    same tag with a new value.

    AllocAslRequestTags( type, tags... ) which accepts your tags
    on the stack, is available in amiga.lib.

    Example Usage: AllocAslRequestTags( ASL_FileRequest,
                                        ASL_Hail, "My Title Bar",
                                        TAG_DONE );

RESULT
    Pointer to an initialized requester data structure, or NULL on
    failure.  The data structure returned will match the requested
    type; for type ASL_FileRequest, a struct @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} *; for
    ASL_FontRequest, a struct @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} *.

    The requester returned may then be passed to @{"AslRequest()" Link "AslRequest()"}, and
    is freed by calling @{"FreeAslRequest()" Link "FreeAslRequest()"}.

SEE ALSO
    @{"AslRequest()" Link "AslRequest()"}, @{"FreeAslRequest()" Link "FreeAslRequest()"}

@EndNode

@Node "AllocFileRequest()" "asl.library/AllocFileRequest"

NAME
    AllocFileRequest -- allocates a @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} structure (V36)

SYNOPSIS
    request = AllocFileRequest()
    D0

    struct @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} *request;

FUNCTION
    Creates and initializes the data structure required to pass to the
    @{"RequestFile()" Link "RequestFile()"} function.

INPUTS
    None.  If you wish to get other than default values, you can use
    @{"AllocAslRequest()" Link "AllocAslRequest()"} to set up a file request with tag items.

RESULT
    Pointer to a struct @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65}, which is to be passed to the
    @{"RequestFile()" Link "RequestFile()"} function.

    The returned @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} pointer has public fields which are
    readable by the application as defined in aslbase.h.

CAUTION
    The application MUST use either the AllocFileRequest(), or
    @{"AllocAslRequest()" Link "AllocAslRequest()"}, function to allocate the structure to be passed to
    the FileRequest() or @{"AslRequest()" Link "AslRequest()"} functions; it is not possible to
    create a struct FileRequest except through the library calls.

    Also, any modifications MUST be done through @{"TagItem" Link "ADCD_v1.2:Inc&AD2.0/Includes/utility/tagitem.h/Main" 31} values, rather
    than directly modifying, unless explicitly documented otherwise.

SEE ALSO
    @{"RequestFile()" Link "RequestFile()"}, @{"FreeAslRequest()" Link "FreeAslRequest()"}, @{"AslRequest()" Link "AslRequest()"}

@EndNode

@Node "AslRequest()" "asl.library/AslRequest"

NAME
    AslRequest -- get input from user for an ASL requester (V36)

SYNOPSIS
    BOOL result = AslRequest( request, ptags );
    D0                        A0       A1

    BOOL    result;
    APTR    request;
    struct @{"TagItem" Link "ADCD_v1.2:Inc&AD2.0/Includes/utility/tagitem.h/Main" 31}       *ptags;

FUNCTION
    Prompts the user for input, based on the specific type of
    requester and modifying tagitems.  The actions and results
    are specific to the type but in general the action is to open
    a requesting window prompting the user for a specific input.
    If the user cancels or the system aborts the request, NULL
    is returned, otherwise the request data structure readable
    data reflects the user input.
    Note that tag values stay in effect for each use of the
    requester until they are cleared or modified by passing the
    same tag with a new value.

INPUTS
    request = requester structure allocated with @{"AllocAslRequest()" Link "AllocAslRequest()"}.
    ptags = pointer to an array of TagItems which may be used to
        modify the requester.

    AslRequestTags( type, tags... ) which accepts your tags
    on the stack, is available in amiga.lib.

    Example Usage: AslRequestTags( ASL_FileRequest,
                                   ASL_Hail, "My Title Bar",
                                   TAG_DONE );

TAGS

    ( REMEMBER - ALL DATA STRUCTURES ARE READ-ONLY EXCEPT BY USING
      TAGITEMS !!! )

    ASL_Hail (STRPTR) - Hailing text to prompt user, typically
        displayed in window title bar.
    ASL_Window (struct @{"Window" Link "ADCD_v1.2:Inc&AD2.0/Includes/intuition/intuition.h/Main" 797} *) - Parent window for the request
        function, which is used to select the screen on which the
        requesting window will be displayed and also is used for
        a shared IDCMP port.

    ASL_LeftEdge (WORD) - Preferred display position for left edge where
        request window should open.
    ASL_TopEdge (WORD) - Preferred top edge of request window.
    ASL_Width (WORD)   - Preferred width of request window.
    ASL_Height (WORD)  - Preferred height of request window.

    ASL_HookFunc (APTR) - Pointer to callback function, specific to
        each AslRequest type.

    ASL_File (STRPTR) - @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} initial filename string.
    ASL_Dir (STRPTR) - @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} initial directory path string.

    ASL_FontName (STRPTR) - @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} initial fontname string.
    ASL_FontHeight (UWORD) - @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} initial height (ta_YSize).
    ASL_FontStyles (UBYTE) - @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} initial styles (ta_Style).
    ASL_FontFlags (UBYTE) - @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} initial flags (ta_Flags).
    ASL_FrontPen (BYTE) - @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} front pen color (fo_FrontPen).
    ASL_BackPen (BYTE) - @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} back pen color (fo_BackPen).
    ASL_MinHeight (UWORD) - Minimum height for @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} display
        of font sizes.  (Application must check return value).
    ASL_MaxHeight (UWORD) - Maximum height for @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} display
        of font sizes. (Application must check ta_YSize returned).

    ASL_OKText (STRPTR) - Replacement for default "OK" gadget text.
        ( Limited to approx. six characters ).
    ASL_CancelText (STRPTR) - Replacement for default "CANCEL"
        gadget text. ( Limited to approx. six characters ).

    ASL_FuncFlags (ULONG) - Function flags, depends on requester
        type.  Example: FILF_SAVE for @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65}.
    ASL_ExtFlags1 (ULONG) - Extended flags (to pass FILF1_ bitdefs)
               Example: FIL1F_NOFILES for file requester

RESULT
    If NULL, typically the user cancelled the requester or a system
    failure prevented the requester from being opened.  If non-zero,
    values will be set depending on the particular type of request,
    in the requesting data structure.  See "libraries/asl.h" for
    information on the READ-ONLY fields in each specific type of
    requester.

NOTES

    Asl provides a way for applications to interact with requester
    operation via a callback (hook) function.  For the ASL file and
    font requesters, there are two ASL_FuncFlags to specify that you
    want a callback:

         for FileRequester: FILF_DOWILDFUNC and FILF_DOMSGFUNC
         for FontRequester: FONF_DOWILDFUNC and FONF_DOMSGFUNC

    The DOWILDFUNC allows you to perform the pattern matching.
    The DOMSGFUNC allows you to handle IDCMP messages received
    for windows that are sharing a UserPort with the requester.

    If you set one or both of these flags via the ASL_FuncFlags
    tagitem, you must provide a pointer to your hook function
    using the ASL_HookFunc tagitem.  Your function will be called
    as follows:

     ULONG rf_Function(ULONG Mask, CPTR Object, CPTR AslRequester)

    The Mask value is a copy of the specific ASL_FuncFlag value
    the callback is for.  Object is a pointer to a data object
    specific to the reason for the callback (defined by Mask).
    AslRequester is a pointer to the requester structure.

    Note that you can only define one HookFunc per requester.
    Your hook function must examine the Mask passed to it to
    determine what the callback is for and what the Object is.

    The following table will explain what is passed to, and
    expected to be returned by a hook functions for various masks:

    @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} DOWILDFUNC
    Purpose: to accept or reject individual files for display list
    Inputs: Mask            = FILF_DOWILDFUNC
            Object          = struct @{"AnchorPath" Link "ADCD_v1.2:Inc&AD2.0/Includes/dos/dosasl.h/Main" 53} *
            AslRequester    = struct @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} *
    Result: You return zero to accept file for display in list


    @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} DOWILDFUNC
    Purpose: to accept or reject individual fonts for display list
    Inputs: Mask            = FONF_DOWILDFUNC
            Object          = struct @{"TextAttr" Link "ADCD_v1.2:Inc&AD2.0/Includes/graphics/text.h/Main" 66} *
            AslRequester    = struct @{"FontRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 147} *
    Result: You return non-zero to accept font for display in list


    @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} (or FontRequester) DOMSGFUNC
    Purpose: to handle IDCMP msgs for other windows sharing port
    Inputs: Mask            = FILF_DOMSGFUNC (FONF_DOMSGFUNC)
            Object          = struct @{"IntuiMessage" Link "ADCD_v1.2:Inc&AD2.0/Includes/intuition/intuition.h/Main" 679} *
            AslRequester    = struct @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} (FontRequester) *
    Result: You must return the Object pointer (asl will Reply the Object)

SEE ALSO
    @{"AllocAslRequest()" Link "AllocAslRequest()"}, @{"FreeAslRequest()" Link "FreeAslRequest()"}

@EndNode

@Node "FreeAslRequest()" "asl.library/FreeAslRequest"

NAME
    FreeAslRequest - frees requester obtained from @{"AllocAslRequest" Link "asl/AllocAslRequest()"} (V36)

SYNOPSIS
    FreeAslRequest( request )
                    A0

    APTR request;

FUNCTION
    FreeAslRequest() is used to free the structure returned by
    @{"AllocAslRequest()" Link "AllocAslRequest()"} or @{"AllocFileRequest()" Link "AllocFileRequest()"}, in order to free
    all resources associated with that requester after the
    application has completed all use of the data structures.

INPUTS
    request - value returned from @{"AllocAslRequest()" Link "AllocAslRequest()"} or
                    @{"AllocFileRequest()" Link "AllocFileRequest()"}.

RESULT
    None.  All resources associated with the request will be
    freed.

SEE ALSO
    @{"AllocAslRequest()" Link "AllocAslRequest()"}, @{"AslRequest()" Link "AslRequest()"}, @{"AllocFileRequest()" Link "AllocFileRequest()"}

@EndNode

@Node "FreeFileRequest()" "asl.library/FreeFileRequest"

NAME
    FreeFileRequest -- frees requester allocated by @{"AllocFileRequest" Link "asl/AllocFileRequest()"} (V36)

SYNOPSIS
    FreeFileRequest( request )
                     A0

    struct @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} *request;

FUNCTION
    This function is identical to the @{"FreeAslRequest()" Link "FreeAslRequest()"} function, but is
    documented for source code compatability and ease of use.
    Applications may use either @{"FreeAslRequest()" Link "FreeAslRequest()"} or FreeFileRequest() to
    free the data structures allocated by @{"AllocFileRequest()" Link "AllocFileRequest()"}.

INPUTS
    request = the return value from @{"AllocFileRequest()" Link "AllocFileRequest()"}.

SEE ALSO
    @{"FreeAslRequest()" Link "FreeAslRequest()"}

@EndNode

@Node "RequestFile()" "asl.library/RequestFile"

NAME
    RequestFile -- request user to select file(s) (V36)

SYNOPSIS
    BOOL result = RequestFile( request )
    D0                         A0

    BOOL    result;
    struct @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} *request;

FUNCTION
    RequestFile() displays a file requester and waits for the user to
    select filenames or cancel the request.  This function is identical
    to the @{"AslRequest()" Link "AslRequest()"} function, except that there is no TagList to
    modify the settings for the requester.  See @{"AslRequest()" Link "AslRequest()"} for details.

INPUT
    request = struct @{"FileRequester" Link "ADCD_v1.2:Inc&AD2.0/Includes/libraries/asl.h/Main" 65} * returned by @{"AllocFileRequest()" Link "AllocFileRequest()"}.

RESULT
    result - See @{"AslRequest()" Link "AslRequest()"} result.  NULL indicates cancelled.

SEE ALSO
    @{"AllocFileRequest()" Link "AllocFileRequest()"}, @{"FreeFileRequest()" Link "FreeFileRequest()"}, @{"AslRequest()" Link "AslRequest()"}


@EndNode

