Blitz:Asl.include.ab3
The asl.include.ab3 file provides many procedures that allow relatively easy control of the Amiga's ASL library functions, but with more flexibility than the built-in command equivalents offer. The ASL library provides standard requesters to give the user a common interface for tasks such as selecting files, fonts and screenmodes.
The general method for using all the ASL requesters in this Include is as follows:
- Set up initial requester properties and assign to a requester ID
- Open the requester
- Read the requester specifics to determine the choices made by the user
The specifics of each requester type are described below. Please note that setting most properties is optional, and omitting them will mean that the system default values will generally be used instead.
File Requester
This is used for selecting files and is the most common ASL requester.
Set File Requester Properties
The title bar text of the requester, as well as the text for the "Ok" and "Cancel" buttons are all set using the aslfr_SetRequesterTitle{} function:
aslfr_SetRequesterTitle{1, "Please select a file to open", "Open this one", "Cancel"}
This sets the title of requester ID 1 to the first string, and sets the Ok button to the second string and the Cancel button to the third string. While it may be tempting to change these buttons, please consider using the standard strings to keep things consistent for users.
The initial filename can be set using the aslfr_SetFile{} statement:
aslfr_SetFile{1, "Myfile.txt"}
This will set the initial filename of requester ID 1 to "Myfile.txt". If that name exists in the requesters directory list it will automatically be highlighted.
The file pattern can similarly be set using the ASLFR_SetPattern{} statement:
aslfr_SetPattern{1, "~(#?.info)"}
This sets the pattern to show all files except .info icon files. If you don't set the pattern, all files will be shown as default.
The initial path of the file requester can be set using the ASLFR_SetPath{} statement:
aslfr_SetPath{1, "Work:Games"}
This sets the initial path of requester ID 1 to Work:Games and lists its contents when the requester is opened. If this drawer doesn't exist, the screen will flash and the volumes list will be shown instead.
In addition to setting the path, this procedure can also set the initial file and pattern, combining all three functions above into one:
aslfr_SetPath{1, "Work:Games", "MyFile.txt", "~(#?.info)"}
In this mode, requester 1 is set up as per the previous 3 examples in one go. The final parameter is a True/False flag that tells the statement that the file and pattern fields are optional. If this is set to True, the file and pattern contents won't be updated if they're empty strings. This is useful for keeping the previous contents intact when updating isn't necessary:
aslfr_SetPath{1, "Work:Games, "", "#?.txt", True}
This will update the initial path and the pattern, but instead of setting the filename to blank, it will leave whatever was there previously intact. The default behavior is False, i.e. even empty strings will replace the previous contents.
Opening the File Requester
To open the file requester, use the aslfr_Request{} function:
result.w = aslfr_Request{1, False, True, False}
A number of parameters are required, and these set the properties of this individual requester instance. The first value is the Requester ID, so 1 in this case will use the initial settings previously set in the examples above. Using a number here that hasn't had any settings assigned will use the default settings from the OS.
The three Boolean flags set the save, multiselect and drawers only modes for the requester. Setting the save mode to True will cause the requester to open in Save Mode - colours are changed, multiselect is disabled and double-clicking an entry doesn't automatically select it. Setting multiselect to True will allow the user to choose more than one file by shift-selecting or pattern selecting. Setting drawers only mode to True will hide all files in the list and also hide the filename text box, allowing the user to only select a path. So, the example above will open in load mode, allowing multiple files to be selected, and will be in files mode.
Two other parameters are optional: a screen pointer can be provided to get the requester to open on a specific screen instead of the default, and another boolean flag can be added to enable NoIcons mode which hides all icons from the list:
result.w = aslfr_Request{1, True, False, False, *MyScreen, True}
This will open a file requester in save mode with no multiselect and no drawers-only mode, and it will open it on the screen pointed to by *MyScreen. The final True parameter will enable NoIcons mode so no .info files are shown. A null screen pointer will default to the currently used screen, but a non-null value must point to an OS screen structure. If you're unsure bus still want to use the NoIcons flag, just set this to 0.
The result variable will be set to True (-1) if a file or drawer was chosen, or False (0) if the requester was cancelled.
Getting the Selected Details
To retrieve the chosen item or items, you should first make sure that the requester wasn't cancelled by checking that the result returned was true. If the requester was cancelled, retrieving the details will give you either the previously set default selection or the selection from the previous time that requester was used. The functions aslfr_GetFile{}, aslfr_GetPath{} and aslfr_GetPattern{} are used to retrieve the contents of the file, path and pattern gadgets of the requester:
MyFile$ = aslfr_GetFile{1}
MyPath$ = aslfr_GetPath{1}
MyPattern$ = aslfr_GetPattern{1}
This will store the relevant parameters in the variables given. Two additional functions are available to deal with multiple select requesters: aslfr_GetNumFilesChosen{} and aslfr_GetNextFile{}. Both work as you might expect:
numfiles = aslfr_GetNumFilesChosen{1}
NPrint "There were ", numfiles, " files chosen"
For i = 1 to numfiles
fn$ = aslfr_GetNextFile{}
NPrint "File ", i, ": ", fn$
Next i
This example lists all of the selected files. aslfr_GetNextFile{} automatically advances through the list of selected files and will return an empty string if there are no more files to show. This means that you can also use a Repeat...Until loop for a possibly more elegant solution:
Repeat
fn$ = aslfr_GetNextFile{}
If fn$ <> "" Then NPrint "File: ", fn$
Until fn$ = ""
Note: aslfr_GetNextFile does not take a requester number argument. Instead, it works on the most recently used requester, regardless of requester ID. Also, the contents of this list are replaced every time a new file requester is used, so be careful not to depend on the values being there when the user may have opened other requesters.
Font Requester
A similar approach is taken for the font requester, however there is only ever one font requester instance taken into account so no ID is needed.
Setting Up the Font Requester
The aslfo_SetRequesterTitle{} statement does the very same job as aslfr_SetRequesterTitle{} for file requesters. The three arguments given are for the requester title, the select button text and the cancel button text:
aslfo_SetRequesterTitle{"Please select a font", "Select!", "Cancel"}
If this statement isn't used, the default strings from the OS will be used instead. To set the initial selected font, use the aslfo_SetInitialFont{} statement:
aslfo_SetInitialFont{"Topaz.font", 11}
This will initially highlight Topaz size 11 when the requester is opened. The file name of the .font file should be given along with the size.
Opening the Font Requester
Opening the font requester is similar to opening a file requester:
result.l = aslfo_Request{False, *scr}
This will open a requester on the screen pointed to by screen pointer *scr. The first parameter determines whether to allow proportional fonts. Set this to True to allow proportional fonts to be selected. Both of these parameters are optional.
Getting the Selected Details
Again, this is similar to the file requester functions. Check the result of the aslfo_Request{} function for a True result, then use the aslfo_GetFontName{} and aslfo_GetFontSize{} functions to retrieve the name and size of the font selected by the user:
If aslfo_Request{True}
fname$ = aslfo_GetFontName{}
fsize.l = aslfo_GetFontSize{}
NPrint "Selected font: ", fname$, " size ", fsize
Else
NPrint "Cancelled!"
End If
Screenmode Requester
Again, a similar approach is taken for the screenmode requester, and again there is only one instance taken into account so no requester ID is needed. Please bear in mind that screenmode IDs can and do change, so unless your software is to run solely on unexpanded classic machines (which is doubtful if you're requesting screenmodes), you cannot rely on screenmode IDs being the same from session to session or machine to machine.
Setting Up the Screenmode Requester
There are a number of parameters available for configuring the screenmode requester's behavior and to only show suitable screenmodes. The aslsm_SetRequesterTitle{} statement does the very same job as aslfr_SetRequesterTitle{} for file requesters. The three arguments given are for the requester title, the select button text and the cancel button text: aslsm_SetRequesterTitle{"Please select a screenmode", "Select!", "Cancel"}
If this statement isn't used, the default strings from the OS will be used instead.
To set the initial dimensions selected in the requester to something other than the defaults, use the aslsm_SetInitialDims{} statement:
aslsm_SetInitialDims{640, 400, 8}
This sets the initial screen size to 640x400 and the initial depth to 8 bits (256 colours).
To set the maximum and minimum dimensions that can be selected, use the aslsm_SetMaxDims{} and aslsm_SetMinDims{} statements:
aslsm_SetMaxDims{800, 600, 24}
aslsm_SetMinDims{640, 480, 16}
The screenmode requester will automatically hide any screenmodes that cannot meet the limits set by these statements, so in this case all screenmodes less than 640 pixels wide, 480 high and with less than 16-bit colour will be unavailable, as well screenmodes above 800x600 in size and 24 bits in depth.
To set the initially selected screenmode, use the aslsm_SetInitialModeID{} statement with the screenmode ID required:
aslsm_SetInitialModeID{MyScreenmode}
Where MyScreenmode is a long variable containing the screenmode ID. This can change so it should never be a constant value! To get the screenmode ID for Workbench, you can use the following code:
WbToScreen 0 *scr.Screen = Peek.l(Addr Screen(0)) MyScreenmode.l = GetVPModeID_(*scr\ViewPort)
Opening the Screenmode Requester
Again, opening the screenmode requester is similar to opening a file requester:
result.l = aslsm_Request{True, True, False, False, *scr}
This will open a requester on the screen pointed to by screen pointer *scr. The other parameters determine which options are available to the user to adjust. The first Boolean value turns on or off the display of dimension gadgets. The second controls the display of the depth slider. The third enables or disables the overscan selection gadget, and the fourth enables or disables the autoscroll checkbox. In the example above, the requester is opened with size and depth adjustment gadgets, but no overscan or autoscroll controls. Again, all these parameters are optional.
Getting the Selected Details
The aslsm_Request{} function returns the actual screenmode ID selected by the user as a long value, or 0 (False) if the requester was cancelled. If the requester returns a valid screenmode ID (i.e., a non-zero value), the individual details of the selection can be obtained using the following functions:
MyWidth.l = aslsm_GetWidth{}
MyHeight.l = aslsm_GetHeight{}
MyDepth.l = aslsm_GetDepth{}
MyScreenmode.l = aslsm_GetModeID{}
MyOverscan.l = aslsm_GetOverscan{}
MyAutoscroll.l = aslsm_GetAutoscroll{}
This will store the relevant values in the variables given.
Additional Functions
A couple of additional functions are provided for easy handling of screenmodes by your program. The aslsm_GetModeName{} returns a string containing the human-readable name of a screenmode corresponding to the given ID, for example "PAL Hires Laced":
sname$ = aslsm_GetModeName{MyScreenmode}
NPrint "The mode is: ", sname$
This will print the name of the screenmode given.
The aslsm_GetBestModeID{} function will return the ID of the best screenmode to suit the dimensions given:
MyScreenmode.l = aslsm_GetBestModeID{640, 480, 6}
Will return the screenmode ID best suited to displaying a 640x480 screen with 6-bit colour.
