From Amiga Coding
Revision as of 13:17, 1 October 2015 by Daedalus (talk | contribs)
Jump to: navigation, search

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: <code>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.