ASL Library

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 the “Utility Library” chapter), 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 1.3 (V34) and 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. Hence, the asl.library has been added to Release 2 of the Amiga operating system to make requesters more consistent. With asl.library, requesters are also much easier to create and take less memory.

_boxThe ASL Library Requires Release 2.The asl.library requires Release 2 of the Amiga operating system, so only applications running under Release 2 and later versions of the Amiga OS can call its functions.

Requesters are very flexible and can be used for many different purposes. The Release 2 asl.library supports the two 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

Creating a File 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.

Here’s a listing of the FileRequester structure. (The FontRequester structure is discussed in more detail later in this chapter.)

struct FileRequester    {          /* (from <libraries/asl.h>)     */
        APTR    rf_Reserved1;
        BYTE    *rf_File;          /* Filename pointer             */
        BYTE    *rf_Dir;           /* Directory name pointer       */
        CPTR    rf_Reserved2;
        UBYTE   rf_Reserved3;
        UBYTE   rf_Reserved4;
        APTR    rf_Reserved5;
        WORD    rf_LeftEdge,rf_TopEdge; /* Preferred window pos   */
        WORD    rf_Width,rf_Height;     /* Preferred window size  */
        WORD    rf_Reserved6;
        LONG    rf_NumArgs;        /* A-la WB Args, for multiselects */
        struct WBArg *rf_ArgList;
        APTR    rf_UserData;       /* Applihandle (you may write!!)  */
        APTR    rf_Reserved7;
        APTR    rf_Reserved8;
        BYTE    *rf_Pat;           /* Pattern match pointer          */
        };                         /* note - more reserved fields follow */

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.

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.

Figure 16-1: The ASL File Requester

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.

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

Specifying Requester Options With TagItems

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>. The basic tag items (used in the first example listed below) are:

[h]

<tbody> </tbody>

Requester Tag Name	Used For
ASL_Hail	String to place in the title bar of the requester window
ASL_Width	Requester window width
ASL_Height	Requester window height
ASL_LeftEdge	Requester window y origin
ASL_TopEdge	Requester window x origin
ASL_OKText	String to place in OK gadget of requester
ASL_CancelText	String to place in Cancel gadget of requester
ASL_File	Default file name (for file requesters only)
ASL_Dir	Default directory name (for file requesters only)

Note that you are currently limited to about six characters for the replacement text if you use either the ASL_OKText or ASL_CancelText tags to change the text that appears in the OK and Cancel gadgets.

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().

Simple ASL File Requester Example

Here’s a short example showing how to create a file requester with asl.library. If AslRequest() returns TRUE then the rf_File and rf_Dir fields of the requester data structure contain the name and directory of the file the user selected. Note that the user can type in the a name for the file and directory, which makes it possible for a file requester to return a file and directory that do not (currently) exist.

;/* filereq.c - Execute me to compile me with SASC 5.10
LC -b1 -cfistq -v -y -j73 filereq.c
Blink FROM LIB:c.o,filereq.o TO filereq LIBRARY LIB:LC.lib,LIB:Amiga.lib
quit
*/
#include <exec/types.h>
#include <exec/libraries.h>
#include <libraries/asl.h>
#include <clib/exec_protos.h>
#include <clib/asl_protos.h>
#include <stdio.h>

#ifdef LATTICE
int CXBRK(void)     { return(0); }  /* Disable Lattice CTRL/C handling */
void chkabort(void) { return; }     /* really */
#endif

UBYTE *vers = "$VER: filereq 37.0";

#define MYLEFTEDGE 0
#define MYTOPEDGE  0
#define MYWIDTH    320
#define MYHEIGHT   400

struct Library *AslBase = NULL;

struct TagItem frtags[] =
{
    ASL_Hail,       (ULONG)"The RKM file requester",
    ASL_Height,     MYHEIGHT,
    ASL_Width,      MYWIDTH,
    ASL_LeftEdge,   MYLEFTEDGE,
    ASL_TopEdge,    MYTOPEDGE,
    ASL_OKText,     (ULONG)"O KAY",
    ASL_CancelText, (ULONG)"not OK",
    ASL_File,       (ULONG)"asl.library",
    ASL_Dir,        (ULONG)"libs:",
    TAG_DONE
};

void main(int argc, char **argv)
{
    struct FileRequester *fr;

    if (AslBase = OpenLibrary("asl.library", 37L))
    {
        if (fr = (struct FileRequester *)
            AllocAslRequest(ASL_FileRequest, frtags))
        {
            if (AslRequest(fr, NULL))
            {
                printf("PATH=%s  FILE=%s\n", fr->rf_Dir, fr->rf_File);
                printf("To combine the path and filename, copy the path\n");
                printf("to a buffer, add the filename with Dos AddPart().\n");
            }
            FreeAslRequest(fr);
        }
        else printf("User Cancelled\n");

        CloseLibrary(AslBase);
    }
}

File Pattern Matching and Multiple Selects

A file requester can filter out certain file and directory entries using the “wildcard” feature of AmigaDOS. To activate the wildcard feature for a file requester, you use the ASL_FuncFlags tag. Each bit in the ASL_FuncFlags tag item controls a special option of the requester depending on its type (file or font). See <libraries/asl.h> for a complete listing of the options that the ASL_FuncFlags tag controls.

[h]

<tbody> </tbody>

File Requester Flag	Used For
FILF_PATGAD	Enables the file name pattern matching gadget
FILF_MULTISELECT	Enables multiple selection of files
FILF_NEWIDCMP	Use separate IDCMP for requester sharing
	a custom screen (see below)
FILF_SAVE	Makes the file requester a save requester (see below)

If the FILF_PATGAD bit of the ASL_FuncFlags tag is set, the file requester will appear with a “Pattern” gadget in addition to the usual file name and directory name gadgets. The user can type an AmigaDOS wildcard pattern into this gadget and the pattern will be used to limit the file names that appear in the requester. An application can also supply a default pattern using the ASL_Pattern tag item. A hidden unchangeable pattern can be created by supplying an ASL_Pattern without a FILF_PATGAD gadget. Such invisible patterns should not be used if there is any reason that the user may need to access a file which does not match the pattern.

Another feature of the ASL file requester is multiple selection. When multiple selection is enabled, the user can choose more than one file name in a single directory by selecting names in the requester’s scrolling list gadget with the mouse. This option, like pattern matching, is set up with the ASL_FuncFlags tag.

If the FILF_MULTISELECT bit of the ASL_FuncFlags tag is set, the file requester will allow multiple selection. When the user selects several file names through the multiple selection feature, the FileRequester’s rf_NumArgs field contains the number of files selected and the rf_ArgList field contains a pointer to an array of WBArg structures (defined in <workbench/startup.h>). There is a WBArg structure containing a file name for each file the user selected.

The following example illustrates a file requester with both a pattern matching gadget and multiple selection enabled.

;/* filepat.c - Execute me to compile me with SASC 5.10
LC -b1 -cfistq -v -y -j73 filepat.c
Blink FROM LIB:c.o,filepat.o TO filepat LIBRARY LIB:LC.lib,LIB:Amiga.lib
quit
*/
#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/screens.h>
#include <graphics/displayinfo.h>
#include <libraries/asl.h>
#include <workbench/startup.h>

#include <clib/asl_protos.h>
#include <clib/exec_protos.h>
#include <clib/intuition_protos.h>
#include <stdio.h>

#ifdef LATTICE
int CXBRK(void)     { return(0); }  /* Disable Lattice CTRL/C handling */
void chkabort(void) { return; }     /* really */
#endif

UBYTE *vers = "$VER: filepat 37.0";

struct Library *AslBase = NULL;
struct Library *IntuitionBase = NULL;
struct Screen *screen = NULL;
struct Window *window = NULL;

void main(int argc, char **argv)
{
    struct FileRequester *fr;
    struct WBArg *frargs;
    int x;

    if (AslBase = OpenLibrary("asl.library", 37L))
    {
        if (IntuitionBase = (struct IntuitionBase *)
                OpenLibrary("intuition.library", 37L))
        {
            if (screen = (struct Screen *)OpenScreenTags(NULL,
                    SA_DisplayID, HIRESLACE_KEY,
                    SA_Title, "ASL Test Screen",
                    TAG_END))
            {
                if (window = (struct Window *)OpenWindowTags(NULL,
                        WA_CustomScreen, screen,
                        WA_Title, "Demo Customscreen, File Pattern, Multi-select",
                        WA_Flags, WINDOWDEPTH | WINDOWDRAG,
                        TAG_END))
                {
                    if (fr = (struct FileRequester *)
                        AllocAslRequestTags(ASL_FileRequest,
                            ASL_Hail, (ULONG)"FilePat/MultiSelect Demo",
                            ASL_Dir,  (ULONG)"libs:",
                            ASL_File, (ULONG)"asl.library",

                            /* Initial pattern string for pattern matching */
                            ASL_Pattern, (ULONG)"~(rexx#?|math#?)",

                            /* Enable multiselection and pattern match gadget */
                            ASL_FuncFlags, FILF_MULTISELECT | FILF_PATGAD,

                            /* This requester comes up on the screen of this
                            ** window (and uses window's message port, if any).
                            */
                            ASL_Window, window,
                            TAG_DONE))
                    {
                        /* Put up file requester */
                        if (AslRequest(fr, 0L))
                        {
                            /* If the file requester's rf_NumArgs field
                            ** is not zero, the user multiselected. The
                            ** number of files is stored in rf_NumArgs.
                            */
                            if (fr->rf_NumArgs)
                            {
                                /* rf_ArgList is an array of WBArg structures
                                ** (see <workbench/startup.h>). Each entry in
                                ** this array corresponds to one of the files
                                ** the user selected (in alphabetical order).
                                */
                                frargs = fr->rf_ArgList;

                                /* The user multiselected, step through
                                ** the list of selected files.
                                */
                                for ( x=0;  x < fr->rf_NumArgs;  x++ )
                                    printf("Argument %d: PATH=%s FILE=%s\n",
                                        x, fr->rf_Dir, frargs[x].wa_Name);
                            }
                            else
                                /* The user didn't multiselect, use the
                                ** normal way to get the file name.
                                */
                                printf("PATH=%s FILE=%s\n", fr->rf_Dir, fr->rf_File);
                        }
                        /* Done with the FileRequester, better return it */
                        FreeAslRequest(fr);
                    }
                    CloseWindow(window);
                }
                CloseScreen(screen);
            }
            CloseLibrary(IntuitionBase);
        }
        CloseLibrary(AslBase);
    }
}

The previous example demonstrates two alternate functions for creating and using ASL requesters:

APTR AllocAslRequestTags( ULONG type, Tag Tag1, ... );
BOOL AslRequestTags( APTR request, Tag Tag1, ... );

AllocAslRequestTags()

can be used instead of AllocAslRequest() to allocate and set up the file requester. This is an amiga.lib function that will accept TagItems directly in its parameter list, rather than a pointer to an array of TagItems.

Similarly, AslRequestTags() will accept TagItems directly instead of requiring a pointer to an array of TagItems as AslRequest() does.

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. The example above shows how the ASL_Window tag is used with a file requester.

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.

The Save Requester

The save requester is a special type of file requester used for save operations. It differs from the regular ASL file requester in several ways. First, the color of the text making up the file names and the background color are interchanged. This makes it more apparent to the user that they are looking at a save requester (instead of the usual load requester).

Another difference, is that a save requester does not allow the user to select an existing file name by double-clicking on an entry in the scrolling list gadget. This helps prevent the user from accidentally overwriting the wrong file.

Save requesters can also create directories. If the user types a directory name into the save requester and the directory doesn’t exist, the save requester will create that directory (after getting the user’s permission via another requester).

To create a save requester, set the FILF_SAVE flag of the ASL_FuncFlags tag. Remember that ASL tags and flag values are preserved across calls to AslRequest(), so if you use a save requester, you must clear the FILF_SAVE bit and reset your ASL_FuncFlags when you want a load requester. Note that it does not make sense to have multiselection in a save requester, so the FILF_SAVE flag overrides the FILF_MULTISELECT flag.

The Directory Requester

Sometimes a program may only require a directory name from the user. There is another variation on asl.library’s file requester that allows this. The ASL_ExtFlags1 tag contains a flag bit to toggle this option. If the FIL1F_NOFILES flag of ASL_ExtFlags1 is set, the requester will appear without a string gadget for file names and will display only directory names in the scrolling list gadget. When AslRequest() (or AslRequestTags() ) returns successfully, the rf_Dir field of the FileRequester structure contains the name of the directory the user selected.

Another flag defined for ASL_ExtFlags1 is FIL1F_MATCHDIRS. If file pattern matching is on (see the FILF_PATGAD flag for ASL_FuncFlags), setting FIL1F_MATCHDIRS tells the file requester to pattern match directory names as well as file names. Of course, if both of these ASL_ExtFlags1 flags are set, the requester will only pattern match directory names.

Creating a Font Requester

The ASL library also contains a font requester. Using the font requester is very similar to using the file requester. First, allocate a requester structure with AllocAslRequest() or AllocAslRequestTags(). The type should be set to ASL_FontRequest in order to get a FontRequester structure:

struct FontRequester    {
    APTR    fo_Reserved1[2];
    struct TextAttr fo_Attr;    /* Returned TextAttr            */
    UBYTE   fo_FrontPen;        /* Returned pens, if selected   */
    UBYTE   fo_BackPen;
    UBYTE   fo_DrawMode;
    APTR    fo_UserData;
    /* missing from asl.h but present in this structure */
    SHORT   fo_LeftEdge, fo_TopEdge, fo_Width, fo_Height;
    };

Once the requester is set up, call AslRequest() or AslRequestTags() to make the requester appear on screen. These functions return TRUE if the user makes a selection. In that case, the font selected is returned as a TextAttr structure in the fo_Attr field of the FontRequester structure. (The TextAttr structure is defined in <graphics/text.h>. See the Amiga ROM Kernel Manual: Includes and Autodocs for a complete listing.) If the user cancels the font requester FALSE is returned.

Figure 16-2: The ASL Font Requester

When the requester is no longer needed, call FreeAslRequest() to deallocate the requester data structure.

Specifying Font Requester Options With TagItems

As with a file requester, the font requester is specified with a TagItem list. There are several tags that are specific to the font requester:

[h]

<tbody> </tbody>

Font Requester Tag Name	Used For
ASL_FontName	Default font (fo_Attr.ta_Name)
ASL_FontHeight	Default font size (fo_Attr.ta_YSize)
ASL_FontStyles	Default font style (fo_Attr.ta_Style)
ASL_FontFlags	Default font flags (fo_Attr.ta_Flags)
ASL_FrontPen	Default font color (fo_FrontPen)
ASL_BackPen	Default font background color (fo_BackPen)
ASL_ModeList	Alternate strings for the drawing mode gadget
	(see below)
ASL_MinHeight	Minimum font height the requester will display
ASL_MaxHeight	Maximum font height the requester will display

Note that the last two tags only limit the range of font sizes that the font requester displays, the user is free to type in any value.

Font requesters have additional special options that are controlled through the ASL_FuncFlags tag. This tag works the same way as it does with file requesters but with different options available. Recall that the data for this tag is divided into bit fields, each of which controls a requester option. The flags used with the ASL_FuncFlags tag in a font requester are defined in <libraries/asl.h>:

[h]

<tbody> </tbody>

Font Requester Flags	Used For
FONF_FRONTCOLOR	Enables font color selection gadgets
FONF_BACKCOLOR	Enables font background color selection gadget
FONF_STYLES	Enables font style selection gadget
FONF_FIXEDWIDTH	Limits display to fixed width fonts only
FONF_DRAWMODE	Enables font draw mode gadget

A simple font requester (one without any of the above FONF_ flags set) only lets the user choose a font and a Y size. Setting the flags above adds options to the font requester. FONF_FRONTCOLOR and FONF_BACKCOLOR add color selection gadgets to the requester, one for choosing a font’s foreground color (labeled “Text”) and the other for choosing the background color (labeled “Field”). The font requester records the user’s setting in the FontRequester’s fo_FrontPen and fo_BackPen fields.

FONF_STYLES sets up several gadgets to choose the style of the font (bold, italics, underline). The font requester saves these settings in the fo_Attr.ta_Style bit field according to the style flags defined in <graphics/text.h>. FONF_FIXEDWIDTH limits the font name display to fixed width (non-proportional) fonts (note that this does not prevent the user from typing in a proportional font name).

FONF_DRAWMODE adds a cycle gadget to the font requester so the user can choose the draw mode. The draw mode is saved in the requester’s fo_DrawMode field. The number stored there corresponds to the draw mode’s position in the gadget’s cycle.

The draw mode cycle gadget initially is labeled “Mode” and has three elements in its cycle: “JAM1”, “JAM2”, and “Complement”. These yield a result of 0, 1, and 2, respectively. It is possible to change the names and number of draw modes with the ASL_ModeList tag. This tag accepts a pointer to an array of strings. The first string replaces “Mode” as the label for the draw mode cycle gadget. The strings that follow replace the elements of the cycle gadget. The last entry in the array has to be NULL to tell the requester where the list of entries ends.

Example Font Requester

The following example illustrates how to use a font requester.

;/* fontreq.c - Execute me to compile me with Lattice 5.10
LC -b1 -cfistq -v -y -j73 fontreq.c
Blink FROM LIB:c.o,fontreq.o TO fontreq LIBRARY LIB:LC.lib,LIB:Amiga.lib
quit
*/

#include <exec/types.h>
#include <libraries/asl.h>

#include <clib/asl_protos.h>
#include <clib/exec_protos.h>

#include <stdio.h>

#ifdef LATTICE
int CXBRK(void)     { return(0); }  /* Disable Lattice CTRL/C handling */
void chkabort(void) { return; }     /* really */
#endif

UBYTE *vers = "$VER: fontreq 37.0";

struct Library *AslBase = NULL;

/* Our replacement strings for the "mode" cycle gadget.  The
** first string is the cycle gadget's label.  The other strings
** are the actual strings that will appear on the cycle gadget.
*/
UBYTE *modelist[] =
{
    "RKM Modes",
    "Mode 0",
    "Mode 1",
    "Mode 2",
    "Mode 3",
    "Mode 4",
    NULL
};


void main(int argc, char **argv)
{
    struct FontRequester *fr;

    if (AslBase = OpenLibrary("asl.library", 37L))
    {
        if (fr = (struct FontRequester *)
            AllocAslRequestTags(ASL_FontRequest,
                /* tell the requester to use my custom mode names */
                ASL_ModeList, modelist,

                /* Supply initial values for requester */
                ASL_FontName, (ULONG)"topaz.font",
                ASL_FontHeight, 11L,
                ASL_FontStyles, FSF_BOLD | FSF_ITALIC,
                ASL_FrontPen,  0x00L,
                ASL_BackPen,   0x01L,

                /* Only display font sizes between 8 and 14, inclusive. */
                ASL_MinHeight, 8L,
                ASL_MaxHeight, 14L,

                /* Give all the gadgetry, but only display fixed width fonts */
                ASL_FuncFlags, FONF_FRONTCOLOR | FONF_BACKCOLOR |
                    FONF_DRAWMODE | FONF_STYLES | FONF_FIXEDWIDTH,
                TAG_DONE))
        {
            /* Pop up the requester */
            if (AslRequest(fr, NULL))
            {
                /* The user selected something,  report their choice */
                printf("%s\n  YSize = %d  Style = 0x%x   Flags = 0x%x\n"
                       "  FPen = 0x%x   BPen = 0x%x   DrawMode = 0x%x\n",
                               fr->fo_Attr.ta_Name,
                               fr->fo_Attr.ta_YSize,
                               fr->fo_Attr.ta_Style,
                               fr->fo_Attr.ta_Flags,
                               fr->fo_FrontPen,
                               fr->fo_BackPen,
                               fr->fo_DrawMode);
            }
            else
                /* The user cancelled the requester, or some kind of error
                ** occurred preventing the requester from opening. */
                printf("Request Cancelled\n");
            FreeAslRequest(fr);
        }
        CloseLibrary(AslBase);
    }
}

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:

[h]

<tbody> </tbody>

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:

FILF_DOWILDFUNC

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

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:

FONF_DOWILDFUNC

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

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:

FILF_DOMSGFUNC (file requester) or FONF_DOMSGFUNC (font requester)

pointer to the IntuiMessage for the function to process

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 - Execute me to compile me with Lattice 5.10
LC -b1 -cfistq -v -y -j73 filehook.c
Blink FROM LIB:c.o,filehook.o TO filehook LIBRARY LIB:LC.lib,LIB:Amiga.lib
quit
*/
#include <exec/types.h>
#include <intuition/intuition.h>
#include <dos/dosasl.h>
#include <libraries/asl.h>

#include <clib/exec_protos.h>
#include <clib/dos_protos.h>
#include <clib/asl_protos.h>
#include <clib/intuition_protos.h>
#include <stdio.h>

#ifdef LATTICE
int CXBRK(void)     { return(0); }  /* Disable Lattice CTRL/C handling */
void chkabort(void) { return; }     /* really */
#endif

#define DESTPATLENGTH 20

UBYTE *vers = "$VER: filehook 37.0";

CPTR HookFunc();

struct Library *AslBase = NULL;
struct Library *IntuitionBase = NULL;
struct Window  *window = NULL;

/* this is the pattern matching string that the hook function uses */
UBYTE *sourcepattern = "(#?.info)";
UBYTE pat[DESTPATLENGTH];

void main(int argc, char **argv)
{
    struct FileRequester *fr;

    if (AslBase = OpenLibrary("asl.library", 37L))
    {
        if (IntuitionBase = (struct IntuitionBase *)
                    OpenLibrary("intuition.library", 37L))
        {
            /* This is a V37 dos.library function that turns a pattern matching
            ** string into something the DOS pattern matching functions can
            ** understand.
            */
            ParsePattern(sourcepattern, pat, DESTPATLENGTH);

            /* open a window that gets ACTIVEWINDOW events */
            if (window = (struct Window *)OpenWindowTags(NULL,
                    WA_Title, "ASL Hook Function Example",
                    WA_IDCMP, IDCMP_ACTIVEWINDOW,
                    WA_Flags, WFLG_DEPTHGADGET,
                    TAG_END))
            {
                if (fr = AllocFileRequest())
                {
                    if (AslRequestTags(fr,
                        ASL_Dir, (ULONG)"SYS:Utilities",
                        ASL_Window, window,
                        ASL_TopEdge, 0L,
                        ASL_Height, 200L,
                        ASL_Hail, (ULONG)"Pick an icon, select save",
                        ASL_HookFunc, (ULONG)HookFunc,
                        ASL_FuncFlags, FILF_DOWILDFUNC | FILF_DOMSGFUNC | FILF_SAVE,
                        ASL_OKText, (ULONG)"Save",
                        TAG_DONE))
                    {
                        printf("PATH=%s FILE=%s\n", fr->rf_Dir, fr->rf_File);
                        printf("To combine the path and filename, copy the path\n");
                        printf("to a buffer, add the filename with Dos AddPart().\n");
                    }
                    FreeFileRequest(fr);
                }
                CloseWindow(window);
            }
            CloseLibrary(IntuitionBase);
        }
        CloseLibrary(AslBase);
    }
}

CPTR HookFunc(LONG type, CPTR obj, struct FileRequester *fr)
{
    static BOOL returnvalue;
    switch(type)
    {
        case FILF_DOMSGFUNC:
        /* We got a message meant for the window */
            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 = 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( (CPTR)(! returnvalue) );
            break;
    }
}

Function Reference

The following are brief descriptions of the ASL library functions. See the Amiga ROM Kernel Reference Manual: Includes and Autodocs for details on each function call. All of these functions require Release 2 or a later version of the operating system.

[h] Functions for ASL Requesters

<thead> </thead> <tbody> </tbody>

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()