Difference between revisions of "Blitz:Asl.include.ab3"

From Amiga Coding
Jump to: navigation, search
(Set File Requester Properties)
Line 44: Line 44:
 
<code>ASLFR_Request{1, True, False, False, *MyScreen, True}</code>
 
<code>ASLFR_Request{1, True, False, False, *MyScreen, True}</code>
 
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.
 
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.
 +
 +
[[Category:Blitz Basic / AmiBlitz|Blitz]]
 +
[[Category:Advancing With Blitz|Advancing With Blitz]]
 +
[[Category:AmiBlitz Includes|AmiBlitz Includes]]

Revision as of 12:40, 25 September 2015

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