Pashua 0.10.3 Documentation

Table of Contents

Introduction

What is Pashua?

Pashua ist a tool for creating native Aqua dialog windows on Mac OS X. It can be invoked from the shell and therefore is particularly useful for creating GUIs from programming languages that do not offer graphic user interfaces natively, for instance Perl, PHP or Ruby.

Pashua was written by Carsten Blüm and released as donationware (free to use, but donations welcome). Pashua’s website is www.bluem.net/en/mac/pashua/

How to use Pashua

Creating a dialog

Basically, Pashua is used like many command-line programs: you call it from your application and pass the path to a configuration file as argument (or let Pashua read the configuration string from stdin by passing - as the filename). Pashua will display a dialog that is created according to the description in the configuration file / string, while typically your application will wait for the dialog to close.

Getting values back from Pashua

Pashua will quit when the user clicks the “OK” button (or enters return), clicks the “Cancel” button or hits Escape (provided there is a cancelbutton in the window). In the first case, for every element defined in the config string, the value is returned. Let’s say, the window contains a textfield named city that holds the string “Hamburg”, then the result (written to stdout by Pashua) would contain a line city=Hamburg. Your application could read Pashua’s output and parse each of the lines to get the value for the element.

In the latter case (“Cancel” button), no values are returned, except the cancel button itself, which is returned as 1. This means: if your configuration string contains a definition like cb.type = cancelbutton and the button will be pressed, then Pashua’s output will contain cb=1.

Using the example scripts

However, you don’t have to deal with calling Pashua and interpreting the result manually—the example scripts included in the distribution do that for you. In most of these scripts, you only have to pass the configuration string to a function or method and that’s it.

Of course, if you have special needs or don’t like the way the example scripts work, you are free to write your own code; it’s completely up to you.

The window configuration

As said above, the dialog window to be created is described in a configuration file or string. For this purpose, Pashua uses a very simple and light-weight configuration syntax which describes the GUI elements to display, their properties (e.g. default values) und their order in the window.

The following part of the documentation will describe the basics of the configuration syntax, the GUI elements available and the attributes that can be set for these elements.

Basic configuration syntax rules

Pashua’s configuration syntax is pretty simple. Basic rules are:

A first example

Let’s have a look at a simple example:

# Add a text field
tx.type = textfield
tx.label = Example textfield
tx.default = Textfield content
tx.width = 310

These lines would simply mean:

Note that the above lines would suffice to display the following window:

Or, if you like to keep things really simple, passing …

tx.type = textfield

… to Pashua would result in this window:

Note: Pashua uses the standard UI elements of the Mac OS X version on which it is running. All the screenshots in this documentation were taken on OS X 10.9; if you would run the examples on Mac OS X 10.6, you would therefore see a slightly different result.

Window attributes

Window attributes are defined similar to element attributes. The only difference (apart from the fact that of course windows have other attributes than, let’s say, textfields) is the fact that you don’t have to specify an element name before the attribute, but simply an asterisk, for instance *.title = My windowtitle

Window attributes
Name Purpose Required Default
appearance Only allowed value is metal, which will create a “brushed metal” window No -
autoclosetime If set to an integer number larger than 1, the dialog will automatically close after the specified number of seconds have passed. The timer starts in the very moment when Pashua has finished parsing the configuration string and everything is set up. No -
autosavekey Can be used to preserve the window position between launches. To let Pashua differentiate between applications, you have to set this to an arbitrary string. I.e.: one application can set this to “abc” and another one to “def”, and for both applications, the window position will be saved and restored separately. No -
floating Setting autoclosetimeto 1will result in the window floating above other windows. No 0
title Sets the window title No Pashua
transparency Sets the window’s transparency, decimal value from 0 (invisible) to 1 (opaque) No 1
x Sets the horizontal position where the window should be opened on the screen ( 0 is the left border of the screen) No Window will be positioned automatically
y Sets the vertical position where the window should be opened on the screen ( 0 is the upper border of the screen) No Window will be positioned automatically

Example: Setting window attributes

*.title = A window title
*.transparency = 0.95
*.x = 50
*.y = 60

Element type: button

A button works similar to the default button: when clicked, it closes the window and returns all elements’ values, but additionally, the button’s own value is returned as 1. Buttons (“regular” buttons, not the cancel button or the default button) are always positioned in the lower left area of the window, though you can position them absolutely using attributes x and y

Attributes for elements of type button
Name Purpose Required Default
label Sets the button’s text Yes
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No

Return value: Either 1 (button clicked) or 0 (button not clicked)

Example: Using button

b.type = button
b.label = My button

Element type: cancelbutton

A cancelbutton can be triggered using Escape and closes the window without returning any values, except the cancelbutton’s own variable, which will be returned as 1. The cancel button is always positioned to the left of the default button and can not be moved to any other position.

Attributes for elements of type cancelbutton
Name Purpose Required Default
label Sets the button title No Depends on the localization.
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No

Return value: Either 1 (button clicked / user pressed Escape / user pressed Cmd-W) or 0 (button not clicked)

Example: Using cancelbutton

cb.type = cancelbutton
cb.label = Close this dialog
cb.tooltip = Closes this window without returning the values entered

Element type: checkbox

Displays a checkbox

Attributes for elements of type checkbox
Name Purpose Required Default
label Creates a label / title next to the checkbox Yes
default Set this to 1 if you want the checkbox to be checked by default. No
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
relxHorizontal offset, relative to the position the element would have if relx was not used (e.g.: relx specifies the distance from the left window border). Any integer can be used as relx value.No0
relyRelative vertical distance to the next element below (“relative” means that the value is added to the default distance). Any integer larger than -20 can be used as rely value.No0

Return value: Either 1 (checkbox checked) or 0 (checkbox not checked)

Example: Using checkbox

chk.type = checkbox
chk.label = If you like, you can use a really long label, as the window will scale accordingly
chk.tooltip = Yes, it’s that simple!

Element type: combobox

A combo box is a combination of a popup menu and a textfield: the user can either choose a value from a list or enter any string.

Attributes for elements of type combobox
Name Purpose Required Default
labelCreates a label above this elementNo
option Adds a value to the list of values. Can (usually should) be used more than once. Yes (one option attribute is required, others are optional)
completion Controls if and how autocompletion is performed. Possible values are 0 (no completion), 1 (completes the first item in the completion list which matches the entered string, case-sensitive), or 2 (ditto, but case-insensitive). No 1
mandatory If set to a true value (everything other than 0, “n”, “no”, empty), input is mandatory. No No
placeholderIf present, this string will be as the field’s placeholder string.No
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No
width Width in pixels No 200
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
relxHorizontal offset, relative to the position the element would have if relx was not used (e.g.: relx specifies the distance from the left window border). Any integer can be used as relx value.No0
relyRelative vertical distance to the next element below (“relative” means that the value is added to the default distance). Any integer larger than -20 can be used as rely value.No0

Return value: String contents (may be an empty string)

Example: Using combobox

cb.type = combobox
cb.label = My combobox label
cb.default = Gromit
cb.option = Wallace
cb.option = Harold
cb.option = Maude
cb.width = 220
cb.tooltip = Choose from the list or enter another name

Element type: date

The date element lets the user choose a date, a time or both. It can be displayed in textual or graphical style.

Attributes for elements of type date
Name Purpose Required Default
label Sets the date picker’s label (displayed above) No
textual Should the textual display style be used instead of the graphical style? No 0 (No)
date Should the user be able to chose a date? No 1 (Yes)
time Should the user be able to chose the time? No 0 (No)
default Default date and/or time that should be selected when the dialog is opened. The only string format that is guaranteed to work is “yyyy-mm-dd [hh:mm]”, for instance “2011-11-29 12:34” or “2011-11-29”. Other string formats such as “12/24/2004”, “next wednesday” or “tomorrow” may work, too. No Current date and/or time
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
y Absolute vertical position in the window, measured from the lower border of the content area No
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No

Return value: Depends on the values of attributes date and time. If only a date can be selected, it will be a date string in yyyy-mm-dd format, if only a time can be selected, the format will be hh:mm. If both are enabled, you will get a date and time string in yyyy-mm-dd hh:mm format. If you only need part of this information, you have to extract the desired substrings yourself.

Example: Using date

d.type = date
d.label = Example date
d.default = 2007-05-30 17:00
d.time = 1

Element type: defaultbutton

When the default button is pressed, the window is closed and all elements’ values are returned to the calling script. The default button is always located in the lower right corner of the window and can’t be moved to any other position.

A default button is added to each window automatically – you only have to specify it explicitly, if you want to set the label or a tooltip or need the return value (i.e.: has it been clicked?) of this button.

Attributes for elements of type defaultbutton
Name Purpose Required Default
label Sets the button title No OK
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No

Return value: Either 1 (button clicked / user pressed Return) or 0 (button not clicked)

Example: Using defaultbutton

db.type = defaultbutton
db.label = Click here to close the window and save the values

Element type: image

This element displays an image (or a PDF file), optionally scaling it to a maximum width or height. Pashua can handle any image type that is supported by NSImage. This includes TIFF, GIF, JPEG, PNG, PDF, PICT and EPS.

Attributes for elements of type image
Name Purpose Required Default
labelCreates a label above this elementNo
path Filesystem path to the image Yes
border Set this to 1 to display a border for the image No 0
maxwidth If this attribute is set to some integer number, the image will be scaled down to this width (including border), if it’s wider No
maxheight If this attribute is set to some integer number, the image will be scaled down to this height (including border), if it’s higher No
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
relxHorizontal offset, relative to the position the element would have if relx was not used (e.g.: relx specifies the distance from the left window border). Any integer can be used as relx value.No0
relyRelative vertical distance to the next element below (“relative” means that the value is added to the default distance). Any integer larger than -20 can be used as rely value.No0

Return value: None

Example: Using image

img.type = image
img.label = This is Pashua’s icon, scaled down a little bit
img.path = /Applications/Pashua.app/Contents/Resources/AppIcon.icns
img.maxwidth = 64
img.border = 1

Element type: openbrowser

An openbrowser is used for choosing a filesystem path. It consists of a textfield, a button and (optionally) a label. The textfield holds the actual element value (the file path), while the button (which is localized) is used to invoke a file selector sheet. Moreover, a file can be dragged & dropped onto the textfield.

Attributes for elements of type openbrowser
Name Purpose Required Default
labelCreates a label above this elementNo
width Sets the width (overall width of texfield and button) No 300
default Default path No
filetype File types that can be selected in the open dialog or dropped onto the textfield; takes a space-delimited list of filename extensions (such as jpg gif tif etc.). In addition to filename extensions, you can use directory to let the user choose directories. If only directory is specified, the user won’t be able to choose any files. If only filename extensions are specified, the user won’t be able to choose directories. If you don’t specify filetype at all, the user will be able to choose anything in the open dialog box. No
mandatory If set to a true value (everything other than 0, “n”, “no”, empty), input is mandatory. No No
placeholderIf present, this string will be as the field’s placeholder string.No
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
relxHorizontal offset, relative to the position the element would have if relx was not used (e.g.: relx specifies the distance from the left window border). Any integer can be used as relx value.No0
relyRelative vertical distance to the next element below (“relative” means that the value is added to the default distance). Any integer larger than -20 can be used as rely value.No0

Return value: Full filesystem path for the selected item (may be an empty string)

Example: Using openbrowser

opb.type = openbrowser
opb.label = Please select an image
opb.default = /a/very/long/path/to/a/file.jpg
opb.filetype = jpg tiff tif gif png psd
opb.width = 250

Element type: password

This element is identical to a textfield, except that it hides whatever is typed into it. Moreover, you can’t copy or drag text from a password element.

Attributes for elements of type password
Name Purpose Required Default
label Creates a label/title above this element No
width The textfield’s width in pixels No 200
default The textfield’s initial contents No
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
mandatory If set to a true value (everything other than 0, “n”, “no”, empty), input is mandatory. No No
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
relxHorizontal offset, relative to the position the element would have if relx was not used (e.g.: relx specifies the distance from the left window border). Any integer can be used as relx value.No0
relyRelative vertical distance to the next element below (“relative” means that the value is added to the default distance). Any integer larger than -20 can be used as rely value.No0

Return value: String contents (may be an empty string)

Example: Using password

pw.type = password
pw.label = Please enter your password
pw.default = Secret!
pw.width = 120

Element type: popup

A popup is an element that lets the user choose one value from a list of possible values

Attributes for elements of type popup
Name Purpose Required Default
option Any string that should appear as an entry in the popup, can (and probably should) be used more than once Yes (one option is required, others are (sic!) optional)
default Default value (should match one of the optionattributes No
labelCreates a label above this elementNo
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No
mandatory If set to a true value (everything other than 0, “n”, “no”, empty), input is mandatory. No No
width Width in pixels No 200
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
relxHorizontal offset, relative to the position the element would have if relx was not used (e.g.: relx specifies the distance from the left window border). Any integer can be used as relx value.No0
relyRelative vertical distance to the next element below (“relative” means that the value is added to the default distance). Any integer larger than -20 can be used as rely value.No0

Return value: Selected item as string (may be an empty string)

Example: Using popup

p.type = popup
p.label = Example popup menu
p.width = 310
p.option = Popup menu item #1
p.option = Popup menu item #2
p.option = Popup menu item #3
p.default = Popup menu item #2

Element type: radiobutton

A radiobutton element lets the user choose a value from a pre-defined list of values.

Attributes for elements of type radiobutton
Name Purpose Required Default
labelCreates a label above this elementNo
option Any string that should be used as a selectable value. Should be used more than once. Yes (at least one option is required)
default The value that should be selected by default. Of course, this must be one of the option values to work. No
disabled If set to 1, the element will be disabled, so that the default value cannot be changed. No 0
tooltipString to use as tooltip for the button. Use \n to insert a linebreak.No
mandatory If set to a true value (everything other than 0, “n”, “no”, empty), input is mandatory. No No
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
relxHorizontal offset, relative to the position the element would have if relx was not used (e.g.: relx specifies the distance from the left window border). Any integer can be used as relx value.No0
relyRelative vertical distance to the next element below (“relative” means that the value is added to the default distance). Any integer larger than -20 can be used as rely value.No0

Return value: Selected radiobutton’s label as string (may be an empty string)

Example: Using radiobutton

radio.type = radiobutton
radio.label = How would you like your coffee?
radio.option = Black
radio.option = With milk
radio.option = With milk and sugar
radio.option = Only sugar, no milk
radio.default = With milk

Element type: savebrowser

A savebrowser can be used for setting a path and name for a new file. It consists of a textfield, a button and (optionally) a label. The textfield holds the actual element value (the file path and name), while the button (which is localized) is used to invoke a file selector sheet.

Attributes for elements of type savebrowser
Name Purpose Required Default
labelCreates a label above this elementNo
width Sets the width (overall width of texfield and button) No 300
default Default path No
filetype File extension to use for the save dialog box; if this attribute is used, the user will be forced to use that extension for the name No
mandatory If set to a true value (everything other than 0, “n”, “no”, empty), input is mandatory. No No
placeholderIf present, this string will be as the field’s placeholder string.No
xAbsolute horizontal position in the window, measured from the left border of the content areaNo
yAbsolute vertical position in the window, measured from the lower border of the content areaNo
relxHorizontal offset, relative to the position the element would have if relx was not used (e.g.: relx specifies the distance from the left window border). Any integer can be used as relx value.No0
relyRelative vertical distance to the next element below (“relative” means that the value is added to the default distance). Any integer larger than -20 can be used as rely value.No0

Return value: Full filesystem path (may be an empty string, if no path chosen by user)

Example: Using savebrowser

svb.type = savebrowser
svb.label = Please set the destination path
svb.default = /tmp/foo
svb.filetype = jpg
svb.width = 360