Blitz:Requesters

Requesters are a standard part of the AmigaOS GUI system, and serve to give the user a consistent and intuitive interface for many tasks, such as selecting files or giving warnings. They are the equivalent of "dialog boxes" on other platforms. ASL.library is the part of the OS that provides some of this functionality, however this was only added in release 2.0 of the OS, so you can't use the ASL requesters on older versions. Blitz does offer alternative versions of the file requester commands for use with OS 1.x, and these will be substituted automatically if you use ASLFileRequest$ on a 1.x machine.

Blitz offers some simple methods for using the standard ASL requesters in your programs, allowing you to take advantage of the system to keep things consistent across all applications. The standard built-in commands are very simple to use and suitable for most cases. However, more flexibility is offered by alternative Userlib commands and by the AmiBlitz asl.include.ab3 file.

Intuition Requesters

These requesters are simple requesters that are part of Intuition, and are generally in the form of simple messages or choices. The standard "Please insert volume Workbench: in any drive" requester is this type. A simple command can be used to pause your program, open a requester, and wait for the user to respond to the message:

result = Request("Test Request", "Please choose an option|(This is the second line)", "Option 1|Option 2|Cancel")

This example opens a standard requester with the title "Test request", and containing the message in the second argument. The pipe character (|) indicates a new line, so the message can be split across multiple lines to prevent the requester getting too wide. The third argument determines the contents of the requester's gadgets, with each gadget separated by a pipe character. At least one gadget should be specified, up to as many as you can fit across the screen. Bear in mind that some people might have quite a low screen resolution and so may not be able to see all of the requester if the message or gadgets are too wide.

The result reflects the gadget clicked by the user. The rightmost gadget always returns 0, so it's best to use this one for the cancel or decline option. All other gadgets return a value reflecting their position, starting with 1 at the left. So, in the example above, clicking Option 1 returns 1, Option 2 returns 2 and Cancel returns 0.

Note: This requester function is part of the ElmoreSysLib, which is a UserLib commonly distributed with Blitz and AmiBlitz. Some older versions of Blitz Basic might not have it included, in which case you will have to find it separately and add it to your Blitz setup, or else update your installation to a newer version of Blitz.

ASL Requesters with Internal Commands

This is probably the simplest method of using the ASL requesters in your program, though some flexibility is lost in the simplicity. Note that all strings should be pre-allocated as the OS will write to them directly.

File Requester

This is the standard requester for selecting a file. Its template is as follows:

result$ = ASLFileRequest$(Title$, Pathname$, Filename$ [,Pattern$] [,x, y, w, h])

Title$ is the phrase to be shown in the requester's title bar. Pathname$ and Filename$ are the starting values for those fields and will determine what directory and file are already selected when the requester is opened. The optional Pattern$ is an AmigaDOS filter pattern for the requester, for example "#?" to show all files, or "#?.mp3" to just show files with the .mp3 extension. If this is omitted, all files will be shown. The last 4 optional parameters determine the position and size in pixels of the requester, and all must be either supplied or omitted. If these are omitted, the default position and size will be used which may not be ideal. Note that there is no possibility to get this requester to behave as a "Save" requester, i.e. to prohibit double-click selection and change colours to show the user that they're selecting a file to save.

Path Requester

This requester is almost identical to the file requester above, except that it allows the user to just select a drawer instead of a file. Its template looks like this:

result$ = ASLPathRequest$(Title$, Pathname$ [,x, y, w, h])

Font Requester

This requester allows the user to select a font from the installed fonts in a nice, convenient way complete with preview. Using it however requires a Newtype pointer so it's slightly more complicated to implement:

*result.fontinfo = ASLFontRequest(flags)

The result is stored in the Newtype structure pointed to by *result. The Newtype itself must be defined as follows:

NEWTYPE .fontinfo
  name.s
  ysize.w
  style.b
  flags.b
  pen1.b
  pen2.b
  drawmode.b
  pad.b
End NEWTYPE

The results of the requester will be stored in this structure, although null will be returned if it is cancelled so be sure to check that the pointer is not null before examining the results! The name field is the filename of the font. The ysize is its selected height. The style field contains a value representing the soft-style applied (none, bold, italic or both). Flags contains flags specific to the selection. Pen 1 and pen2 contain the text pen and background pen selected respectively. Drawmode represents the drawing method - text only, text & field, outline etc., depending on the version of the OS. And finally, pad is simply a padding byte that is unused.

The flags parameter supplied to the requester determines which options should be available to the user, and is made up from adding together the following flags:

Flag	Option
#FOF_DOFRONTPEN	Allow user to select font pen
#FOF_DOBACKPEN	Allow user to select background pen
#FOF_DOSTYLE	Allow user to select font style
#FOF_DODRAWMODE	Allow user to select drawing mode
#FOF_FIXEDWIDTHONLY	Only allow fixed width (monospaced) fonts

An example of use is as follows:

NEWTYPE .fontinfo
  name.s
  ysize.w
  style.b
  flags.b
  pen1.b
  pen2.b
  drawmode.b
  pad.b
End NEWTYPE

FindScreen 0

*result.fontinfo = ASLFontRequest(15)

If *result ; Check if the requester produced a result
  NPrint "Font name: ", *result\name
  NPrint "Font size: ", *result\ysize
  NPrint "Font style: ", *result\style
  NPrint "Font colour: ", *result\pen1
  NPrint "Background colour: ", *result\pen2
  NPrint "Drawmode: ", *result\drawmode
Else
  NPrint "Requester cancelled"
Endif

ASL Include

The AmiBlitz Include file for handling ASL requesters allows a flexible approach to configuring the requesters. Please see the ASL Include page for details.