Bellhop Panel Package for Perl Reference

 

Overview

The Bellhop Panel package for Perl defines methods that you can use to interact with users using panels and dialogs. You can choose from prompt panels, alert panels, list panels and file open/save panels. In addition to the functions to create the panels, there are a few global constants that are defined to indicate the return values for some of the dialog box panels.

 

Return Values Defined for Panel Package

The following global variables are automatically available to your Perl scripts and are used to identify the various return values from certain Panel methods by their symbolic name. You can use these symbolic names instead of creating new strings. For more information on the meaning of these types, see the Apple developer documentation for the AppKit Types and Constants.

 

Method List for Panel Package

The following methods are available in the panel extension:

NOTE: Each function is shown with the arguments that are expected when invoking the function. For functions that require strings and numbers you can pass normal scalar values, however for arrays and hashes you must pass in references. Similarly, numeric and string return values are returned as scalars, however arrays and hashes are returned as references. Array and hash references can contain nested structures.

 

Method Descriptions for Panel Package

Panel::show_info(aTitle, aMsg, defBtn, altBtn, othBtn)
Shows a standard info panel to the user. The title of the panel is specified in the aTitle parameter, and the message of the panel is in aMsg. If the defBtn is non-nil, then its value is displayed as the default button's title in the info panel. If the defBtn is nil, then a standard "OK" button is displayed and all other buttons are omitted. The altBtn holds the text of the alternate button's title. If this value is nil, then it and the other button are ignored. The othBtn holds the text of the other button's title. If it is nil, then it is not displayed on the panel. The function returns one of the "alert return" constants (e.g. $NSAlertDefaultReturn) specifying which button the user pressed.

 

Panel::show_alert(aTitle, aMsg, defBtn, altBtn, othBtn)
Works the same way as the Panel::show_info() function above, however it is used to display an alert type panel instead of a regular info panel. It also returns one of the "alert return" constants.

 

Panel::show_prompt(aTitle)
Displays a prompt to the user and a text box in which they can enter any text. The text of the prompt is specified by the aTitle parameter. The text that the user entered is returned as a Perl string. If the user didn't enter any text, then undef is returned.

 

Panel::show_select(aTitle, aList)
Displays a list selection panel to the user. The title of the panel is specified in aTitle, which should be a string. If no value is given, a default title will be used. The aList parameter should contain an array reference of strings that are to be presented to the user as a list from which they can make a selection. The panel allows the user to select multiple values from the list. The function returns a reference to an array of the items (strings) that the user selected.

 

Panel::show_select_indices(aTitle, aList)
Operates similar to the Panel::show_select() method above, however instead of returning the strings that the user selected, it returns a reference to an array of the indices of each item that was selected.

 

Panel::show_file_open(aDir, someTypes, allowMultiple)
Presents the user with a file open panel, from which they can select a file(s). The aDir string specifies a start directory for the panel. If aDir is undef, then the panel starts at a default directory (usually the user's home directory). The someTypes parameter is a reference to an array of strings that represent the types of files that the user is allowed to select. If this value is undef, then the user can pick all files. The allowMultiple flag indicates whether or not the user is allowed to pick multiple files. This method returns a reference to an array of file paths representing the files that the user selected.

 

Panel::show_dir_open(aDir, someTypes, allowMultiple)
The Panel::show_dir_open() method is similar to the Panel::show_file_open() method above, except that it only allows the user to select directories. It returns a reference to an array of strings representing the directories that the user selected.

 

Panel::show_file_save(aDir, aFile)
Presents the user with a file save panel, which allows them to save a file to a location. The aDir string specifies a start directory for the panel. If aDir is undef, then the panel starts at a default directory (usually the user's home directory). The aFile parameter is a string that will serve as a "suggested" filename. The user is free to change it using the save panel. This method returns the fullpath of the file that was saved as a string.