asl.library Reference

Comprehensive function reference for asl.library, synthesised from the AmigaOS NDK 3.2 Release 4 (Autodocs/AG/asl).

This page documents 5 functions of asl.library. Each function entry follows the canonical autodoc format. struct Name, union Name, enum Name are clickable links to the type definition in the types reference.

Function index

AbortAslRequest()

AbortAslRequest -- attempt to abort an asl requester. (V44)

Synopsis

AbortAslRequest(requester); A0

VOID AbortAslRequest(APTR requester);

Function

The different types of asl requesters are modal (as of V44). Yet at times it may be necessary to abort a modal requester from a different task context. AbortAslRequest() will attempt to tell the modal asl requester provided to shut down and perform as if the user had clicked on the requester's window close gadget. This may take some time to complete; be prepared to handle this.

Inputs

requester - requester obtained from AllocAslRequest(), or NULL in which case this function does nothing.

See also

AslRequest()

ActivateAslRequest()

ActivateAslRequest -- attempt to activate an asl requester. (V44)

Synopsis

ActivateAslRequest(requester); A0

VOID ActivateAslRequest(APTR requester);

Function

The different types of asl requesters are modal (as of V44). Yet at times it may be necessary to activate a modal requester from a different task context.

Inputs

requester - requester obtained from AllocAslRequest(), or NULL in which case this function does nothing.

See also

AslRequest()

AllocAslRequest()

AllocAslRequest -- allocate an ASL requester. (V36) AllocAslRequestTags -- varargs stub for AllocAslRequest(). (V36)

Synopsis

requester = AllocAslRequest(reqType,tagList); D0 D0 A0

APTR AllocAslRequest(ULONG,TagItem*);

requester = AllocAslRequestTags(reqType,firstTag, ...);

APTR AllocAslRequestTags(ULONG,Tag,...);

Function

Allocates an ASL requester data structure of the specified type.

Inputs

type - type of requester to allocate. Currently defined types are ASL_FileRequest, ASL_FontRequest and ASL_ScreenModeRequest. ASL_ScreenModeRequest is available starting with asl.library V38 only. tags - pointer to an optional tag list specifying how to initialize the data structure returned by this function. See the documentation for AslRequest() for an explanation of how to use the currently defined tags.

Results

requester - an initialized requester data structure, or NULL on failure. The data structure returned corresponds to the requested type; ASL_FileRequest -> (struct FileRequester ) ASL_FontRequest -> (struct FontRequester ) ASL_ScreenModeRequest -> (struct ScreenModeRequester *)

Notes

As of V38-V40 the ASL requester uses gadtools.library routines to create and maintain its user interface. Every IntuiMessage the library passes through the functions specified with ASLSM_IntuiMsgFunc and ASLSM_HookFunc will have been filtered through the gadtools.library/GT_GetIMsg() routine.

Bugs

Under V38 and V39, the filtering functions for the file requester were only asked to filter drawer selections if the ASLFR_FilterDrawers tag was set to TRUE. The compatible behavior, reestablished in V40, is to always pass drawers for filtering.

See also

AslRequest(), FreeAslRequest()

AslRequest()

AslRequest -- get input from user using an ASL requester. (V36) AslRequestTags -- varargs stub for AslRequest(). (V36)

Synopsis

result = AslRequest(requester,tags); D0 A0 A1

BOOL AslRequest(APTR,TagItem*);

result = AslRequestTags(requester,firstTag,...);

BOOL AslRequestTags(APTR,Tag,...);

Function

Prompts the user for input, based on the specific type of requester and modifying tags. The actions and results are specific to the type of requester, 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, FALSE is returned, otherwise the requester's data structure 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

requester - requester structure allocated with AllocAslRequest(). If this parameter is NULL, this function will always return FALSE with a dos.library/IoErr() result of ERROR_NO_FREE_STORE. tags - pointer to an optional tag list which may be used to control features of the requester.

Results

result - FALSE if the user cancelled the requester or if something prevented the requester from opening. If TRUE, values in the requester structure will be set depending on the particular type of requester.

     Under V38, If the return value is FALSE, you can look
     at the result from the dos.library/IoErr() function to
     determine whether the requester was cancelled or simply
     failed to open. If dos.library/IoErr() returns 0, then the
     requester was cancelled, any other value indicates a failure
     to open. Current possible failure codes are
     ERROR_NO_FREE_STORE which indicates there was not enough
     memory, and ERROR_NO_MORE_ENTRIES which indicates no modes
     were available for display in the screen mode requester
     (usually because the application filter hook filtered them
     all away)

Notes

As of V38-V40 the ASL requester uses gadtools.library routines to create and maintain its user interface. Every IntuiMessage the library passes through the functions specified with ASLSM_IntuiMsgFunc and ASLSM_HookFunc will have been filtered through the gadtools.library/GT_GetIMsg() routine.

Bugs

Under V38 and V39, the filtering functions for the file requester were only asked to filter drawer selections if the ASLFR_FilterDrawers tag was set to TRUE. The compatible behavior, reestablished in V40, is to always pass drawers for filtering.

See also

AllocAslRequest(), FreeAslRequest()

FreeAslRequest()

FreeAslRequest -- frees resources allocated by AllocAslRequest(). (V36)

Synopsis

FreeAslRequest(requester); A0

VOID FreeAslRequest(APTR);

Function

FreeAslRequest() frees any system resources allocated by AllocAslRequest(). Once a requester has been freed, it can no longer be used with other calls to AslRequest().

Inputs

requester - requester obtained from AllocAslRequest(), or NULL in which case this function does nothing.

See also

AllocAslRequest()