When copying this resource, make sure to also copy the dialog box resources using ResEdit.
DoList is a single command which has the ability to handle a scrolling list of text strings. This is a fundamental part of the Macintosh interface, allowing a user to select one or more items from a long list.
As a HyperCard developer, all that is needed is to create a list, pass it to the DoList command, which returns the item(s) that the user selected. This list is composed of several items in a HyperTalk container separated by commas.
The item(s) that the user selects are returned in the property named
'the result'. If the user clicked on the Cancel button, 'the result' will be empty. Otherwise, it will contain one or more items, with the first item being the number of items selected, and the items themselves following.
The Modes:
DoList can be used in three different modes:
Mode 1: Uses a dialog resource for the list. This requires 2 additional
resources in the stack, 1 'DLOG' and its 'DITL' resource. This is
explained in detail later.
Mode 2: Requires NO additional resources at all. This is the simplest
and most common mode. The list box will always appear in the
center of the HyperCard window, and will always have the
same orientation.
Mode 3: Same as mode 2, but the list box position can be anywhere on
the HyperCard window. The size and orientation of the box are
not changed, only its location on the window.
Mode Parameters:
The mode being used depends on the parameters passed to the DoList command. The parameters for each mode are:
<List> is the actual list of items separated by commas.
<Flag> is 1 of 3 possible values, and determines list characteristics.
<H> is the horizontal coordinate for the list box in local coordinates.
<V> is the vertical coordinate for the list box in local coordinates.
Flag Setting:
The <Flag> parameter is passed in every mode, and determines how many items the user can select, and affects how they are selected.
<Flag> should be one of the following:
ONE Will allow the user to select only 1 item from the list.
CON Will allow the user to select 1 or more items from the list, with
the items being continous.
DIS Will allow the user to select 1 or more items from the list, in
any order, not necessarily continous.
The Result:
Immediately after calling DoList, the property 'Result' will tell you what the user did. You can say:
get the result
If it is empty, then the user clicked on the Cancel button. Otherwise, item 1 of it will be the number of items selected. If you are setting
<Flag> to be 'ONE' then this number will always be 1. Otherwise, it will be any number from zero to the number of items in the list. Once check this to find out how many items there are, you can use them in any way you wish. For example, if the user selected 1 item from the list, and you want to put this item into a container named 'choice' :
put item 2 of it into choice
Dialog Resource Format:
<Resource ID> is the ID of the 'DLOG' resource in the stack.
Item 1 must be a button item, and is used for the Select button. It can
have any position and rectangle, and is not reset.
Item 2 must be a button item, and is used for the Cancel button. It can
have any position and rectangle, and is not reset.
Item 3 must be a useritem, and is used for the list window. It must
have the rectangle and position you wish to use for the list.
Item 4 must be a useritem, and is used for outlining the Select button.
It can have any rectangle, since its rect will be set for you.
More about Mode 1:
Mode 1 requires that you create your own dialog resource. You can do this with a variety of utilities, usch as ResEdit or Dialog Creator. You can also write RMaker source code and compile it. The first 4 items must be as specified previously. You must put these resources into the resource fork of the stack, so that DoList can find them. If there is any problem with a resource or if DoList can't find a resource, the results are unpredictable, and can even produce a system bomb. DoList assumes that the resource is present and valid, and does no error checking.
I've included Mode 1 for the people who really want to change the look of the dialog box, and know how to do so. Only the first 4 items are reserved, so extra text items (such as prompts) can be easily added.
Tips For Using Mode 1:
Mode 1 makes it easy to make a flashy, nice looking list. However, there are some things to watch out for:
Since dialog resources have Global coordinate rectangles, the list will appear at the global coordinates specified in the resource, regardless of the location of the HyperCard window.
Make sure that the vertical size of useritem 3 (the list window) is a multiple of 15. This insures that it will have the proper appearance.
Make sure the visible bit of the dialog resource is false. If the dialog is initially visible, its appearance while it is being drawn to the screen is not as clean and professional-looking.
General Tips: Examine scripts in this stack for examples!
It can take a few seconds for a long list to be processed and for the list box to appear on the screen. When this is the case, it's nice to change the cursor into a watch before calling the DoList command, so the user knows that something is happening.
Using fields to hold lists instead of other types of containers can be very convienient to edit. Hide the field if you don't want the user to see it. This makes scripting much easier and more elegant.
If you are allowing users to select more than one file (see Flag Setting) then be sure to check item 1 of the result. It's possible for them to click on the Select button with no files selected, in which case item 1 of the result will be zero. You can treat this as a Cancel.
