This function is used to select one or more files and/or folders from a standard OS X file dialog (or alternately from a panel which supports dragging). The paths of the selected items will be saved to a track or a named variable as a list delimited by the default list delimiter (\~).
When files can be returned, you can optionally supply a list of filename extensions which will be accepted. The extensions are separated by spaces, commas (,), slashes (/), newline characters or the default list delimiter (\~). Note, you do not have to include a leading . on an extension. Hint: enter public.image to accept all image files.
When files and folders can be selected and multiple items can be returned,you can enable the Identify folders with a trailing / option. This can be used to easily differentiate between folders and files. If you do not enable the option, you may have to use a Test If File Exists statement to determine if a returned path is a file or folder.
When only a single file can be selected, you can enable the New setting. This will allow you to specify a file which does not exist. Note that if the selected file exists, the OS may issue a File Already Exists warning. This can be ignored.
The supplied text strings may contain any of the escape sequences described in Escape Sequences. Only the first non blank line of the prompt will be displayed.
The statement supports additional configurability which is documented in Advanced Prompt Statement Functionality. These settings can be configured by clicking on small button with the gear icon.
You can elect to issue a beep with the prompt.
The prompt is only issued once per set of files when run stepwise.
The function is valid while batch processing but is intended to be used within the special Batch Start and Batch End inline actions.
By default, the statement will cause action processing to be terminated if the user selects Cancel as opposed to providing a selection. If the set state option is enabled, the action test state will be set to false if the user cancelled otherwise it will be set to true.
The statement can be run in two modes. The first is by means of standard system file open/save panels which is described above. The second is via a panel displayed in the Action Pending Window which allows you to drag and drop files and folders for selection. This mode is not available when New is selected.
When the Display a drop panel option is enabled, the system open/save panels will not be used. A drop panel will be displayed in the Action Pending Window. Button configuration is the same as for any other Prompt statement. In order to Continue, at least one item must be dropped into the displayed target in order to satisfy the prompt statement's validation process. This is not configurable. If you want to exit without cancelling, with no files dragged, use an Exit button. Note that resizing the panel will make the drop target larger.
You can configure up to four buttons. See Configuring Buttons on Prompt Statements for more information. Which button was pressed can be determined from the Prompt Chosen Button named variable. There is no requirement for buttons to be contiguous. At runtime when a button configured to be a Menu is clicked and a menu item is selected, the panel is closed and named variable Prompt Menu Item Reference will reference which menu item was selected. The Prompt Menu Formatting topic describes how to format the menus. Note that a Multi Line Editor button can be used to display the currently dropped files in an editor panel where dropped items can be removed.
Which dragged items will be accepted depends on the File and Folder checkboxes and the File types field.
You can drag items more than once to the drag target. ie. you can add items. The number of items which will be accepted depends on the Allow multiple checkbox. When a drag has been accepted, the drag target image's center will change to green.
You can also enable the Exit on drag option. When enabled, the panel will close immediately after a drag is accepted. The Prompt Chosen Button named variable will be set to -1001.
The Action Pending Window can be configured to resize automatically or to retain its last displayed size. When displaying the drag panel this may not be advantageous. By default the drag panel is set to a fixed default size.
Whenever a drag panel is displayed and the window is closed, a Prompt Window Size named variable will be written as widthxheight, -1. Whenever a drag panel is to be displayed, the size in the named variable, if valid, will be used. If the size is not valid, (formatted incorrectly or too small), the default window sizing algorithm will be used.
Note that the Prompt Window Size named variable is also set when exiting a panel issued by the Prompt from Container statement. When set in this manner the third component (-1) will never be less than 0. This method ensures that the two statements do not read dimensions generated by a different statement.
Both the system and drop panel approaches allow the specification of criteria to limit the types of items that can be provided.
When an action is started by a droplet which passes a list of files, the types of files are not limited. When the Filter Droplet files setting is enabled, the statement will analyze the list of files in the Droplet Files named variable and will remove all items which do not meet the criteria specified in this statement. The updated list is written back to the Droplet Files named variable and may be empty. There is no displayed UI component when Filter dropped files is enabled.