Pashua 0.11 Documentation

Table of Contents

• Introduction
  • What is Pashua?
  • Usage overview
• The window configuration
  • Basic configuration syntax rules
  • Window attributes
  • Element type: button
  • Element type: cancelbutton
  • Element type: checkbox
  • Element type: combobox
  • Element type: date
  • Element type: defaultbutton
  • Element type: image
  • Element type: openbrowser
  • Element type: password
  • Element type: popup
  • Element type: radiobutton
  • Element type: savebrowser
  • Element type: text
  • Element type: textbox
  • Element type: textfield
• FAQ
  • I can’t open Pashua, as it is from an “unidentified developer”
  • What is new in version [XY]?
  • What text encodings does Pashua support?
  • How can I dynamically configure a dialog at runtime?
  • How does Pashua handle mandatory fields?
  • Can I localize my Pashua-based application?
  • How do I display 2 or more windows one after another?
  • When will Pashua support multiple checkboxes/radiobuttons…?
  • When will Pashua support programming language [XY]?
  • May I distribute applications based on Pashua?
  • When will Pashua support progress bars?
  • How can I hide the dock icon?
  • Can I build “real” applications with Pashua?
  • What does “Pashua” mean?
• Version information

Introduction¶

What is Pashua?¶

Pashua ist a tool for creating native dialog windows on macOS. It can be invoked from the shell / Terminal and therefore is particularly useful for creating GUIs from programming languages that do not offer graphic user interfaces natively, for instance PHP or Python.

Pashua was written by Carsten Blüm and released as Open Source software under the 3-Clause BSD License. Being Open Source, it is of course free to use, but nonetheless, donations are welcome. Pashua’s website is www.bluem.net/en/projects/pashua/.

Usage overview¶

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 presses the Return key), 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 dialog configuration, 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 mentioned 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:

• Empty lines are ignored.
• Lines starting with the hash symbol # are treated as comments, like in Perl, Shell, PHP, Python, Ruby, Tcl, probably a few other languages and many Unix configuration files.
• Every command must be on its own line.
• Every command consists of: a string (called “identifier” below), followed by an equal sign =, followed by another string. The only exception to this rule is: a line consisting of nothing but a hyphen - will create a horizontal separator line at the appropriate position in the window.
• Every “identifier” must consist of a unique name for a GUI element (any ASCII string, preferably all lowercase – please note that window attributes must use an asterisk * as that name, see window attributes), followed by a period, followed by an attribute name. Each type of GUI element has its own set of allowed attributes, and a large part of this documentation deals with those properties. The name for the GUI element is not only a string that is used internally by Pashua, but it will also be used for returning values to the calling script / application, so you should regard these names as some sort of variable names.
• Anything after the equal sign is considered the value.
• Attributes and the names of the element types are case-sensitive.
• Leading and trailing whitespace is ignored for both the identifier and the value. For instance, for Pashua the following two lines would be the same:

  name.label=Please enter your name
  name.label  =	 Please enter your name

• The GUI elements are displayed in the order in which they appear in the config string. The only exception to this rule are buttons: the default button is always in the lower right corner of the window, the cancel button (if defined) is located left to the default button and any other buttons will appear in the lower left corner, from left to right, in the order they were defined.
• You don’t have to specify attributes in consecutive blocks. You can add as many empty lines as you like, and you could even mix up commands of different elements.
• When an attribute is specified more than once, the last one will be used:

  x.label = Label A
  x.label = Label B
  x.label = Label C

  … would result in the element being labeled with “Label C”. An exception to this rule is option, which is used to set values for radiobuttons, combo boxes and popups and which may be used in multiple commands.

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:

• Line 1: A comment
• Line 2: The window should contain a textfield that we simply call “tx” to be able to address it in the next lines and to get the returned value later on.
• Line 3: The textfield should be titled “Example textfield”.
• Line 4: Set the initial text displayed in the textfield to “Textfield content”.
• Line 5: Set the textfield’s width to 310 Pixels.

The above lines would suffice to display the following window:

Or, if you like to keep things really simple, the dialog configuration …

tx.type = textfield

… would result in this window:

Note: Pashua uses the standard UI elements of the macOS / OS X version on which it is running. All the screenshots in this documentation were taken on macOS 10.12; if, for instance, you would run the examples on OS X 10.9, you would therefore see the older, less flat window and button look.

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

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

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.

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

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.

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.

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 = 2017-06-23 14:38
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.

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.

Please note that you can either specify width/height or maxwidth/maxheight – otherwise, you will get an error.

On the other hand, it is valid to specify only a width without a height or vice versa (and the same is true for maxwidth and maxheight). In this case, Pashua will try to make the best of the situation and either calulcate the missing value based on the image ratio from the given value (if without “max” prefix) or set the missing value based on the main window’s resolution (if with “max” prefix).

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.

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 = 300

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.

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

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.

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.

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

Element type: text¶

This element displays multi-line, wrapping text. The width of the element does not adapt automatically to the content, but uses the given width (or the default width, if no width is specified.) On the other hand, the height is automatically set to the minimum height needed to display the text using the given (or default) width.

Return value: None

Example: Using text

txt.type = text
txt.default = Paragraph one, demo text[return][return]Paragraph two

Element type: textbox¶

A textbox is a scrollable, multi-line text container. The scrollbar will appear automatically if needed. Note: If you have changed the system’s scrollbar behaviour to display both arrows at both ends (e.g. using TinkerTool), the scrollbar might not appear for small heights.

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

Example: Using textbox

tb.type = textbox
tb.default = Line 1[return]Line 2[return]Line 3
tb.width = 300
tb.height = 60

Element type: textfield¶

A textfield is a simple, one-line text input field with an optional label displayed above the textfield.

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

Example: Using textfield

txf.type = textfield
txf.label = Enter placeholder text
txf.default = Lorem ipsum dolor sit amet
txf.width = 300

FAQ¶

I can’t open Pashua, as it is from an “unidentified developer”¶

If your Mac tells you that Pashua cannot be opened, as it is an application by an unidentified developer, this is nothing to worry about. On my website, you can find more detailed information on this, but the short summary is: simply use the contextual menu (right-click or Ctrl-click on Pashua’s icon), then choose item “Open” and confirm that you want to open it.

What is new in version [XY]?¶

Please take a look at the version history.

What text encodings does Pashua support?¶

For some time, Pashua had offered specifying the text encoding of the configuration string, as there were languages which had limited or no support for UTF-8. Today, UTF-8 is ubiquitous, so this option was removed. Pashua will auto-detect the encoding of a configuration file and return the values in the same encoding. This implies that command-line option -e, which was used to set the encoding, is now completely ignored. Please note: Guessing the encoding only works with configuration files. If you pass the configuration via STDIN, Pashua will expect it to be UTF-8.

How can I dynamically configure a dialog at runtime?¶

The dialog configuration which is passed to Pashua is a string. Often, this string will be static, but sometimes it can be useful or necessary to have either dynamic parts in it or even completely construct it at runtime. A simple example would be a tool which, for some reason, contains a date field which should be pre-filled with the current date. Let’s imagine that this tool is based on a Bash script – this script could get the date from the date command-line tool and save it in a variable using TODAY=$(date '+%Y-%m-%d') and then insert it into the dialog configuration, using something like datefield.default ${TODAY}. This is only a very simple example, but hopefully you get the point: Pashua does not care how the dialog configuration string was created – it only has to fulfill the syntax rules. Pashua will not even know if the configuration is static or if and how it was created at runtime.

If you take a look at the example scripts, you will see that they make use of dynamic configuration strings: Pashua’s icon is added to the example dialog, and this is done by locating the path to Pashua.app at runtime and deriving the icon’s path from that location.

How does Pashua handle mandatory fields?¶

Some of the element types (those for which it makes sense) can be defined as mandatory. This means that the dialog cannot be closed as long as the element is empty. Here, “empty” means that the element does not have a string value or that the string value contains only whitespace; the digit zero (0) is not regarded as empty. Radio buttons are regarded as empty as long as none of the buttons has been clicked.

This screenshot shows a visual marker which is displayed next to a mandatory element when the “OK” button is clicked:

Can I localize my Pashua-based application?¶

Pashua itself is localized in English, German and French. The localizations are used for the menu bar, the application about box, button titles (defaultbutton, cancelbutton, savebrowser and openbrowser buttons) and of course for error messages. It’s your application’s responsibility to provide localization by passing an appropriate configuration string to Pashua for anything else that should be localized. Hint: if you want to build a multi-language application and need to detect the user’s preferred language from the shell, you can use defaults read -g AppleLocale

How do I display 2 or more windows one after another?¶

You can call Pashua multiple times, but this will result in successive application launches (with the icon moving in and out of the Dock), which is annoying. Hiding the Dock icon helps a lot in this case, but it’s only a remedy – not a real solution.

When will Pashua support multiple checkboxes/radiobuttons…?¶

You can use any GUI element as often as you like; the only exceptions are the cancelbutton and the defaultbutton. You only have to make sure that the names are unique:

chk1.type = checkbox
chk1.label = Checkbox 1

chk2.type = checkbox
chk2.label = A second checkbox

chk3.type = checkbox
chk3.label = Checkbox #3

When will Pashua support programming language [XY]?¶

The question is not, when Pashua will support the programming language, but rather vice versa. Pashua does not care (and does not even know) from which programming language it was invoked. It gets a dialog configuration, it does its job, it returns the resulting values and quits. That’s all. Basically you can use Pashua from any language that is able to write a file or write to a Unix pipe, call an application with command line arguments, manipulate strings and declare variables dynamically or handle associative arrays. If code for your favourite language is not included in the Pashua distribution or in the Pashua Bindings Repository, simply go ahead and write the code yourself.

May I distribute applications based on Pashua?¶

Starting with version 0.11, Pashua is Open Source Software, licensed under the 3-Clause BSD License. As long as you comply with the license, any usage of the source code, part of the source or use (including redistribution) of the compiled binary is permitted.

When will Pashua support progress bars?¶

Progress bars are a UI element I am asked for regularly. The problem with progress bars is that they conceptually differ from Pashua’s approach. When Pashua gets a dialog description and puts the dialog on screen, it is in control and runs independently from the process from which it was started. A progress bar, on the other hand, would require continuous (or at least periodic) interaction with that process, as Pashua would need to receive updates – at the very least least to be informed when the operation which the progress bar represents has been finished, or maybe also to display the current length of the bar, in case it is a determinate progress indicator.

As you can see, the “Fire and forget” approach and the “Start and control Pashua” approach are two different kettles of fish, and this is why progress bars won’t be needed in the foreseeable future. If you really need a progress bar and you need it now, you can still use cocoaDialog.

How can I hide the dock icon?¶

Most Cocoa applications can be modified so that the Dock icon and the application-specific menu bar are hidden – and Pashua is no exception to this rule. You can achieve this by opening the file Info.plist inside Pashua’s application bundle and changing the line below the one containing LSUIElement from <false/> to <true/>. If you don’t notice any change in Pashua’s behaviour, you should log out and back in.

Can I build “real” applications with Pashua?¶

Native OS X applications are nothing like folders with a name that ends with “.app” (invisible in the Finder by default) and that have a specific directory structure in them. You can examine such a folder (called an “application bundle”) by context-clicking on the name and choosing the appropriate option from the contextual menu (in English it is “Show Package Contents”, in German it is “Paketinhalt zeigen”).

As a starting point, an example for a doubleclickable, “real” application with a Pashua GUI is provided. When you play around with the application bundle, there are a few things to keep in mind:

• The script that is the “engine” inside the application bundle must have the same name as the bundle itself (without the “.app” extension). Example: If your application should have the name “Hello world”, then the script in Hello world.app/Contents/MacOS/ must be named “Hello world”.
• The script must have the executable bit set, i.e.: it must be executable at the shell. If it is not yet, do a chmod +x /path/to/the/script
• Modify file Contents/Info.plist inside the application bundle to match your needs. You will at least have to change the “Doubleclickable Example” string to your applications’name (in the example above, it would have to be “Hello world”). Moreover, you should set the CFBundleIdentifier value (currently “com.example.pashua-doubleclickable-example”) to an appropriate value.
• Modify the application author and copyright info in Contents/Resources/English.lproj/InfoPlist.strings inside the application bundle.
• When using a Perl or Python script, you should put the corresponding module inside the same folder (*.app/Contents/MacOS/) as the script.
• I haven’t managed to get AppleScript to work inside application bundles. You can use a wrapper shell script containing something like

  #!/bin/sh
  scriptpath=`dirname "$0"`
  osascript "$scriptpath/my_applescript.app"

  …, but though this will work, the application will not finish launching (the Dock icon won’t stop hopping).

What does “Pashua” mean?¶

Naming things is not easy, and while searching for a name, at some point I started to play around with acronyms from “Perl”, “and”, “shell” (actually, at the beginning – 2003 – I only thought of Perl and shell scripts) and “UI” – and eventually came up with “Pashua”. So, basically, it does not mean anything.

Version information¶

Pashua 0.11 was released on 05/27/2018.

For information on changes and the complete version history, please take a look at the website.