ASL Library

This page is currently being updated to AmigaOS 4.x. Some of the information contained here may not yet be applicable in part or totally.

ASL Library

This chapter describes the asl.library. The sole purpose of this library is to provide standard file and font requesters for application programs.

It is easier to understand the asl.library if you are familiar with some basic concepts of the Amiga operating system, especially TagItem arrays (described in Utility Library), Intuition screens and windows, graphics library font structures, and AmigaDOS pattern matching.

About Requesters

Requesters are temporary sub-windows used for confirming actions or selecting options. The most common type of requester is a file requester which is used to pick a file name for a load or save operation.

Under earlier versions of the Amiga operating system there was limited support for requesters. Intuition provides simple requesters which can be used to request responses such as OK or Cancel from the user. More elaborate Intuition requesters can be created by adding additional features such as string gadgets, however the result of this is that each application writer develops their own style of requester. With asl.library, requesters are much easier to create and take less memory.

Requesters are very flexible and can be used for many different purposes. The asl.library supports the three most common type of requesters:

• File requesters for choosing a file name in a load or save operation
• Font requesters for choosing a font in a text operation
• Screen Mode requesters for choosing a new screen with specific attributes

Creating an ASL Requester

Opening an ASL requester requires the use of three functions:

APTR request = AllocAslRequest( ULONG type, struct TagItem *tagList );
BOOL success = AslRequest( APTR request, struct TagItem *tagList );
VOID           FreeAslRequest( APTR request );

The first function you should call is AllocAslRequest(). This allocates the main data structure you will use, either a FileRequester structure or a FontRequester structure. You specify the type of requester you want for AllocAslRequest() by setting the type argument. This can be one of two values defined in <libraries/asl.h>: either ASL_FileRequest, to ask for a FileRequester structure, or ASL_FontRequest, to ask for a FontRequester structure.

Both AllocAslRequest() and AslRequest() accept a TagItem array or tag list as an argument. The tag list is used to initialize or alter the values in the requester data structure.

A single TagItem consists of a tag name and an associated tag value. Tag items that apply to the asl.library are defined in <libraries/asl.h>.

Whichever requester type you use, you must allocate the requester structure with the AllocAslRequest() function call. Do not create the data structure yourself. The values in this structure are for read access only. Any changes to them must be performed only through asl.library function calls.

Displaying an ASL Requester

Once you have set up a requester structure with AllocAslRequest(), call AslRequest() to make the requester appear on screen. AslRequest() takes the requester data structure as an argument using it as a specification for the requester that it creates on screen.

AslRequest() is always synchronous to the calling program. That is, control does not return to your program until the user makes a selection or cancels. AslRequest() returns TRUE, if the user selects a file (or a font). In that case the file (or font) name that the user selected is returned in the requester data structure. AslRequest() returns FALSE if the user cancels the requester or the requester failed for some reason.

The contents of an ASL requester data structure are preserved across calls to AslRequest(). So, until the requester is freed, tag settings and user selections will remain in the data structure unless they are altered by tags in subsequent calls to AslRequest(). This is very useful because it allows the requester to remember and redisplay the user's previous selections. However, this also means that the programmer must assure that any addresses passed in ASL tags remain valid, or are refreshed on each call to AslRequest().

Generally, options that you wish to specify only once, such as the initial position and size, should be specified as tags when you allocate the requester. Options that you wish to control for each use of the requester should be passed as tags each time the requester is opened with AslRequest().

ASL Requesters and Custom Screens

An application that uses a custom screen normally wants its requesters to open on its screen. Using the ASL_Window tag, a program can associate a requester with a specific window so that the requester appears on the same screen as the window. The ASL_Window tag is followed by a pointer to a window structure. ASL_Window works with both file and font requesters.

Normally, a requester associated with a window (using ASL_Window) shares that window's IDCMP port for its communication. An application may not want to share an IDCMP port with the requester. Using the ASL_FuncFlags tag, a program can ask for a requester that creates its own IDCMP port. There are two flags that accomplish this. The first, FILF_NEWIDCMP, is used on file requesters. The other, FONF_NEWIDCMP, is used on font requesters.

Freeing an ASL Requester

When you have finished with a requester use the FreeAslRequest() function to deallocate the requester data structure.

Common Tags Used by All Requester Types

These tags apply to all three types of ASL requesters: the file requester, the font requester and the screen mode requester. Each tag in the list below is prepended with ASLxx_. The actual tag names used by ASL will be prepended with ASLFR_, ASLFO_ or ASLSM_ depending on what type of requester is being used.

Tag Name	Used For
ASLxx_PubScreenName	Name of a public screen on which to open the requester.
ASLxx_Screen	Pointer to a screen on which to open the requester.
ASLxx_PrivateIDCMP	Specifies separate IDCMP for the requester window (this replaces the FILF_NEWIDCMP and FONF_NEWIDCMP flags in the ASL_FuncFlags tag used in V37).
ASLxx_IntuiMsgFunc	Function to call when an unknown message arrives at a shared IDCMP used by the requester window (this replaces the ASL_HookFunc tag and the FILF_DOMSGFUNC and FONF_DOMSGFUNC flags in the ASL_FuncFlags used in V37).
ASLxx_SleepWindow	Modal requester. Specifies that input should be blocked in the parent window.
ASLxx_UserData	A 32-bit value copied into the user data field of the requester structure.
ASLxx_TextAttr	Font to use for requester window gadgets and menus.
ASLxx_Locale	Locale (and language) to use for the requester window.
ASLxx_FilterFunc	Function to call for each item (file, font or mode) encountered. If the function returns TRUE, the item is displayed in the list view gadget, otherwise it is rejected and not displayed. (This replaces the ASL_HookFunc tag and the FILF_DOWILDFUNC and FONF_DOWILDFUNC flags in ASL_FuncFLags used in V37.)

Calling Custom Functions from a Requester

The ASL_HookFunc tag passes an ASL requester a pointer to a custom function. The requester can use this function for two purposes. The first is to determine if the requester should display a particular file or font name. The other purpose is to process messages that the requester receives at its IDCMP port that are not meant for the requester. Hook functions are set up through flag values used with the ASL_FuncFlags tag:

Hook Function Flag	Used For
FILF_DOWILDFUNC	Call user hook function on each name in a file requester
FONF_DOWILDFUNC	Call user hook function on each name in a font requester
FILF_DOMSGFUNC	Call user hook function for IDCMP messages not used by a file requester
FONF_DOMSGFUNC	Call user hook function for IDCMP messages not used by a font requester

The FILF_DOWILDFUNC and FONF_DOWILDFUNC flags cause a requester to call the function you specify with the ASL_HookFunc tag for every file or font entry. The requester displays the file or font name only if your hook function tells it to. For a file requester, if your hook function returns a zero, the file requester will display the file name. For a font requester, if your hook function returns anything but zero, the font requester will display the font name and size.

The FILF_DOMSGFUNC and FONF_DOMSGFUNC flags cause a requester to call your hook function whenever it receives an IntuiMessage that it cannot use at the IDCMP port that it shares with your window. (See the section on "ASL Requesters and Custom Screens" earlier in this chapter for more information about sharing IDCMP ports.) If the requester receives any messages that are not meant for the requester it will call your hook function (specified with the ASL_HookFunc tag). Your hook function is responsible for returning a pointer to the IntuiMessage. The requester will take care of replying to the message.

Parameters Passed to Custom Hook Functions

A requester always passes three parameters to your custom hook function:

ULONG MyHookFunc(ULONG type, CPTR object, CPTR AslRequester)

If MyHookFunc() is called from a file requester doing _DOWILDFUNC, the three parameters are:

type

FILF_DOWILDFUNC

object

pointer to an AnchorPath structure (from <dos/dosasl.h>)

AslRequester

pointer to the FileRequester that called the hook function

The hook custom function should return a zero to display this file.

The AnchorPath structure is a dos.library structure used in pattern matching. Refer to the AmigaDOS Manual, 3rd Edition for more information.

If MyHookFunc() is called from a font requester doing _DOWILDFUNC, the three parameters are:

type

FONF_DOWILDFUNC

object

pointer to a TextAttr structure (from <graphics/text.h>)

AslRequester

pointer to the FontRequester that called the hook function

The hook custom function should return non-zero to display this particular font size.

If MyHookFunc() is called from a file or font requester doing _DOMSGFUNC, the three parameters are:

type

FILF_DOMSGFUNC (file requester) or FONF_DOMSGFUNC (font requester)

object

pointer to the IntuiMessage for the function to process

AslRequester

pointer to the FileRequester or FontRequester that called the hook function

The hook custom function should return a pointer to the IntuiMessage.

Notice that it is possible for a requester to use both _DOWILDFUNC and _DOMSGFUNC at the same time. Your hook function has to differentiate between the two cases by testing the type passed to it. It is not possible for a font and file requester to share a hook function for a _DOWILDFUNC, because FILF_DOWILDFUNC is defined to be the same value as FONF_DOWILDFUNC, so the hook function cannot tell if the object (from the prototype above) is a pointer to an AnchorPath structure or a pointer to a TextAttr structure. It is possible for font and file requesters to share one hook function for _DOMSGFUNC (even though FILF_DOMSGFUNC and FONF_DOMSGFUNC are equal) because, in this case, font and file requesters both call your hook function in the same manner.

Example ASL Requester With Custom Hook Function

The following example illustrates the use of a hook function for both _DOWILDFUNC and _DOMSGFUNC.

/*
** filehook.c
*/
#include <exec/types.h>
#include <intuition/intuition.h>
#include <dos/dosasl.h>
#include <libraries/asl.h>
 
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/asl.h>
#include <proto/intuition.h>
 
#define DESTPATLENGTH 20
 
struct AslIFace *IAsl = NULL;
struct IntuitionIFace *IIntuition = NULL;
 
struct Window  *window = NULL;
 
/* this is the pattern matching string that the hook function uses */
CONST_STRPTR sourcepattern = "(#?.info)";
TEXT pat[DESTPATLENGTH];
 
uint32 HookFunc(int32 type, APTR obj, struct FileRequester *fr);
 
 
int main(int argc, char **argv)
{
    struct FileRequester *fr;
 
    struct Library *AslBase = IExec->OpenLibrary("asl.library", 50);
    IAsl = (struct AslIFace*)IExec->GetInterface(AslBase, "main", 1, NULL);
 
    struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
    IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
 
    if (IAsl != NULL && IIntuition != NULL)
    {
            IDOS->ParsePattern(sourcepattern, pat, DESTPATLENGTH);
 
            /* open a window that gets ACTIVEWINDOW events */
            if (window = IIntuition->OpenWindowTags(NULL,
                    WA_Title, "ASL Hook Function Example",
                    WA_IDCMP, IDCMP_ACTIVEWINDOW,
                    WA_Flags, WFLG_DEPTHGADGET,
                    TAG_END))
            {
                if (fr = IAsl->AllocFileRequest())
                {
                    if (IAsl->AslRequestTags(fr,
                        ASL_Dir, "SYS:Utilities",
                        ASL_Window, window,
                        ASL_TopEdge, 0,
                        ASL_Height, 200,
                        ASL_Hail, "Pick an icon, select save",
                        ASL_HookFunc, HookFunc,
                        ASL_FuncFlags, FILF_DOWILDFUNC | FILF_DOMSGFUNC | FILF_SAVE,
                        ASL_OKText, "Save",
                        TAG_END))
                    {
                        IDOS_>Printf("PATH=%s FILE=%s\n", fr->rf_Dir, fr->rf_File);
                        IDOS->Printf("To combine the path and filename, copy the path\n");
                        IDOS->Printf("to a buffer, add the filename with Dos AddPart().\n");
                    }
                    IAsl->FreeFileRequest(fr);
                }
                IIntuition->CloseWindow(window);
            }
        }
    }
 
    IExec->DropInterface((struct Interface*)IIntuition);
    IExec->CloseLibrary(IntuitionBase);
 
    IExec->DropInterface((struct Interface*)IAsl);
    IExec->CloseLibrary(AslBase);
 
    return 0;
}
 
uint32 HookFunc(int32 type, APTR obj, struct FileRequester *fr)
{
    static BOOL returnvalue;
    switch(type)
    {
        case FILF_DOMSGFUNC:
        /* We got a message meant for the window */
            IDOS->Printf("You activated the window\n");
            return(obj);
            break;
        case FILF_DOWILDFUNC:
        /* We got an AnchorPath structure, should
        ** the requester display this file? */
 
            /* MatchPattern() is a dos.library function that
            ** compares a matching pattern (parsed by the
            ** ParsePattern() DOS function) to a string and
            ** returns true if they match. */
            returnvalue = IDOS->MatchPattern(pat,
                    ((struct AnchorPath *)obj)->ap_Info.fib_FileName);
 
            /* we have to negate MatchPattern()'s return value
            ** because the file requester expects a zero for
            ** a match not a TRUE value */
            return( ! returnvalue );
            break;
    }
}

Function Reference

The following are brief descriptions of the ASL library functions. See the SDK for details on each function call.

Function	Description
AllocAslRequest()	Allocates an ASL font or file requester from a TagItem array
AllocAslRequestTags()	Same as AllocAslRequest() but accepts tags directly
AslRequest()	Displays an ASL requester with options set up in a TagItem array
AslRequestTags()	Same as AslRequest() but accepts tags directly
FreeAslRequest()	Deallocates an ASL requester created with AllocAslRequest()