CocoaDialog - Documentation

CocoaDialog
overview | download | documentation | examples | todo | sf.net project page

# Documentation

#### (CocoaDialog 2.1.0)

The following document provides an overview of how to use CocoaDialog, as well as the various run modes and commandline options available. Visit the examples page to see more practical examples of its use. (It's really not as complicated as it may seem from this page).

## Contents

## Executing CocoaDialog

### Overview

CocoaDialog is run directly from the commandline by executing the binary file within the `.app` bundle. The path to it will be `CocoaDialog.app/Contents/MacOS/CocoaDialog`
If CocoaDialog is in your `~/Applications` directory, for example, the executable will be: `~/Applications/CocoaDialog.app/Contents/MacOS/CocoaDialog`

From here on we will refer to this binary file as simply `CocoaDialog`

### Easy way to invoke CocoaDialog

This is a simple wrapper script. Put it somewhere in your `$PATH`. For example, mine is `~/bin/CocoaDialog`, and I have `export PATH=$PATH:~/bin` in my `~/.bash_profile`.

Now from the shell or other scripts, I can just do `CocoaDialog` to invoke the program.

download this wrapper script

    #!/usr/bin/perl
    use strict;
    use warnings;

    my $path = "/Users/markstra/Applications"; # Change this!
    my $cd = "$path/CocoaDialog.app/Contents/MacOS/CocoaDialog";

    system($cd, @ARGV);

### Runmode and options

CocoaDialog is always executed with the following format:

CocoaDialog runmode options

The `runmode` is always required, and specifies which GUI control to use.
An example is:

CocoaDialog yesno-msgbox --title "Delete backups" --text "Delete all the backups?" --informative-text "This cannot be un-done"

See Run Modes / GUI Controls for a list of available controls.

## Return Values / Output

The return value of a control will simply be printed to `stdout`. This makes it trivial to determine the user input in any shell, programming or scripting language.

In bash you could find it like this:

rv=`CocoaDialog yesno-msgbox --string-output`
echo "User pressed the $rv button"

Controls that return multiple values will print each on its own line (separated by newlines).

## Global Options

The following options can be supplied for any of the run modes (GUI controls).

‑‑title "text for title" | Sets the window's title
‑‑string‑output | Makes yes/no/ok/cancel buttons return values as "Yes", "No", "Ok", or "Cancel" instead of integers. When used with custom button labels, returns the label you provided.
‑‑no‑newline | By default, return values will be printed with a trailing newline. This will suppress that behavior. Note that when a control returns multiple lines this will only suppress the trailing newline on the last line.
‑‑width integer | Sets the width of the window. It's not advisable to use this option without good reason, and some controls won't even respond to it. The automatic size of most windows should suffice.
‑‑height integer | Sets the height of the window. It's not advisable to use this option without good reason, and some controls won't even respond to it. The automatic size of most windows should suffice.
‑‑debug | If you are not getting the results you expect, try turning on this option. When there is an error, it will print `ERROR:` followed by the error message.
‑‑help | Gives a list of options and a link to this page.

## Icons

The `msgbox`, `ok-msgbox`, `yesno-msgbox`, and `bubble` dialogs allow you to specify icons. In addition to using your own, you may also choose from the following stock icons that are included with CocoaDialog.

If you want to use a mix of stock icons and custom icons, just use the custom icon option (either `--icon-file` or `--icon-files`, see the documentation for the particular run mode), and provide the path to the stock icon `.icns` file located in `CocoaDialog.app/Contents/Resources/`.

cocoadialog | atom | computer | document | find | finder
firewire | folder | gear | globe | hazard | heart
hourglass | info | ipod | person | sound | x

Thanks to Laurent Baumann for providing these. Visit his webpage at http://ave.ambitiouslemon.com

## Run Modes / GUI Controls

Notes: The right-most button of controls with buttons has the key-equivalent of enter. Any button with a label "Cancel" has the key-equivalent of escape.

### bubble

This is a fancy-looking, little bubble dialog window. You can have one or more displayed at a time. You can use it to display short, temporary messages to the user. The bubbles will remain in the upper-right corner until the user clicks them, or they time out. They will time out in 4 seconds by default, and all of them will close when the user clicks one. This behavior can be changed with the options below. Note: The bubble has a fixed size. Any text beyond its capacity will simply be cut off. This is on the TODO list for future releases. returns: nothing. If it's not obvious, note that the program doesn't return until the bubbles have timed out, or been clicked. If you want your script to continue immediately after displaying them, it's up to you to make your script do this (most likely by invoking CocoaDialog as a background process). Example bubble shell script
Options for single or multiple bubbles:
‑‑timeout numSeconds | The amount of time, in seconds, that the bubble(s) will be displayed. Clicking them will make them closer sooner. Unlike other dialogs, bubbles time out by default. Default value is `4`.
‑‑no‑timeout | Don't time out. By default the bubbles will time out after 4 seconds. With this option enabled, they will stay visible until the user clicks them.
‑‑alpha alphaValue | The alpha value (controls transparency) for the bubble(s). A number between 0 and 1. Default is `0.95`.
‑‑x‑placement placement | This can be `left`, `right`, or `center`.
‑‑y‑placement placement | This can be `top`, `bottom`, or `center`.
Options for a single bubble:
‑‑text "body of the bubble" | required. The body text of the bubble.
‑‑title "title of the bubble" | required. The title of the bubble.
‑‑icon stockIconName | The name of the stock icon to use. This is incompatible with `--icon-file` Default is `cocoadialog`
‑‑icon‑file "/full/path/to/icon file" | The full path to the custom icon image you would like to use. Almost every image format is accepted. This is incompatible with the `--icon` option.
‑‑text‑color colorHexValue | The color of the text on the bubble in 6 character hexadecimal format (like you use in html). Do not prepend a "#" to this value. Examples: "000000" for black, or "ffffff" for white. The default is determined by your system, but should be `000000`.
‑‑border‑color colorHexValue | The color of the border in 6 character hexadecimal format (like you use in html). Do not prepend a "#" to this value. Examples: "000000" for black, or "ffffff" for white. The default is `808080`.
‑‑background‑top colorHexValue | The color of the top of the background gradient in 6 character hexadecimal format (like you use in html). Do not prepend a "#" to this value. Examples: "000000" for black, or "ffffff" for white. The default is `B1D4F4`.
‑‑background‑bottom colorHexValue | The color of the bottom of the background gradient in 6 character hexadecimal format (like you use in html). Do not prepend a "#" to this value. Examples: "000000" for black, or "ffffff" for white. The default is `EFF7FD`.
Options for a multiple bubbles:
‑‑texts List of bodies for the bubbles | required. A list of body texts to use in the bubbles. Example: `"This is bubble 1" bubble2 "and bubble 3"` This must have the same number of items as the `--titles` list.
‑‑titles List of titles for the bubbles | required. A list of titles to use in the bubbles. Example: `"Title for bubble 1" "And bubble2" "Bubble 3"` This must have the same number of items as the `--texts` list.
‑‑icons List of stock icon names | The names of the stock icons to use. This is incompatible with `--icon-files`. If there are less icon names provided than there are bubbles, it will use the default for the remaining. Defaults are `cocoadialog`
‑‑icon‑files List of full paths to icon files | A list of files to use as icons. This is incompatible with `--icons`. If there are less icon files provided than there are bubbles, it will use the default for the remaining. Look at the Icons section to see how to mix custom icons with stock icons.
‑‑text‑colors List of hex colors | See the single bubble section for details.
‑‑border‑colors List of hex colors | See the single bubble section for details.
‑‑background‑tops List of hex colors | See the single bubble section for details.
‑‑background‑bottoms List of hex colors | See the single bubble section for details.
‑‑independent | This makes clicking one bubble not close the others. The default behavior is to close all bubbles when you click one.

back to runmodes/controls
up to global options

### msgbox

This control provides a generic message box. It allows you to customize the labels of the buttons. At least one button (`--button1`) must be specified. If labels for the other buttons are not given, the buttons will not appear on the message box. Buttons go from right to left. `--button1` is the right-most button. returns: `1`, `2`, or `3` depending on which button was pressed; or the label of the button if the `--string-output` option is given.. If the dialog times out, it will return `0` or `timeout`. Also see the yesno-msgbox and ok-msgbox. Example msgbox shell script
Options: (in addition to global options)
‑‑text "main text message" | This is the main, bold message text.
‑‑informative‑text "extra informative text to be displayed" | This is the extra, smaller message text.
‑‑icon stockIconName | The name of the stock icon to use. This is incompatible with `--icon-file` Default is no icon.
‑‑icon‑file "/full/path/to/icon file" | The full path to the custom icon image you would like to use. Almost every image format is accepted. This is incompatible with the `--icon` option.
‑‑float | Float on top of all windows.
‑‑timeout numSeconds | The amount of time, in seconds, that the window will be displayed if the user does not click a button. Does not time out by default.
‑‑button1 "label for button 1" | required. This is the right-most button.
‑‑button2 "label for button 2" | This is the middle button.
‑‑button3 "label for button 3" | This is the left-most button. This will not be displayed if there is no `--button2` label specified.

back to runmodes/controls
up to global options

### ok-msgbox

This control provides a standard Ok/Cancel message box. returns: `1` for ok, `2` for cancel depending on which button was pressed; `Ok` or `Cancel` if the `--string-output` option is given. If the dialog times out, it will return `0` or `timeout`. Example ok-msgbox shell script
Options: (in addition to global options)
‑‑text "main text message" | This is the main, bold message text.
‑‑informative‑text "extra informative text to be displayed" | This is the extra, smaller text.
‑‑no‑cancel | Don't show a cancel button, only "Ok".
‑‑icon stockIconName | The name of the stock icon to use. This is incompatible with `--icon-file` Default is no icon.
‑‑icon‑file "/full/path/to/icon file" | The full path to the custom icon image you would like to use. Almost every image format is accepted. This is incompatible with the `--icon` option.
‑‑float | Float on top of all windows.
‑‑timeout numSeconds | The amount of time, in seconds, that the window will be displayed if the user does not click a button. Does not time out by default.

back to runmodes/controls
up to global options

### yesno-msgbox

This control provides a standard Yes/No/Cancel message box. returns: `1` for yes, `2` for no, `3` for cancel depending on which button was pressed; `Yes`, `No`, or `Cancel` if the `--string-output` option is given. If the dialog times out, it will return `0` or `timeout`. Example yesno-msgbox shell script
Options: (in addition to global options)
‑‑text "main text message" | This is the main, bold message text.
‑‑informative‑text "extra informative text to be displayed" | This is the extra, smaller text.
‑‑no‑cancel | Don't show a cancel button.
‑‑icon stockIconName | The name of the stock icon to use. This is incompatible with `--icon-file` Default is no icon.
‑‑icon‑file "/full/path/to/icon file" | The full path to the custom icon image you would like to use. Almost every image format is accepted. This is incompatible with the `--icon` option.
‑‑float | Float on top of all windows.
‑‑timeout numSeconds | The amount of time, in seconds, that the window will be displayed if the user does not click a button. Does not time out by default.

back to runmodes/controls
up to global options

### inputbox

This control provides a one line input box and customizable buttons. At least one button (`--button1`) must be specified. If labels for the other buttons are not given, the buttons will not appear on the message box. Buttons go from right to left. `--button1` is the right-most button. returns: `1`, `2`, or `3` depending on which button was pressed; or the label of the button if the `--string-output` option is given. On the next line will be the text provided by the user in the textbox. On a timeout, it will return `0` or `timeout`, and the text from the textbox will not be returned. Also see the standard-inputbox. Example inputbox Perl script
Options: (in addition to global options)
‑‑text "initial text" | This is the initial text in the input box.
‑‑informative‑text "extra informative text to be displayed" | This is the text for the label above the input box.
‑‑button1 "label for button 1" | required. This is the right-most button.
‑‑button2 "label for button 2" | This is the middle button.
‑‑button3 "label for button 3" | This is the left-most button. This will not be displayed if there is no `--button2` label specified.
‑‑float | Float on top of all windows.
‑‑timeout numSeconds | The amount of time, in seconds, that the window will be displayed if the user does not click a button. Does not time out by default.
‑‑no‑show | This makes it a secure inputbox. Instead of what the user types, only dots will be shown.

back to runmodes/controls
up to global options

### standard-inputbox

This control provides a standard input box with "Ok" and "Cancel" buttons. returns: `1` for ok, `2` for cancel depending on which button was pressed; `Ok`, or `Cancel` if the `--string-output` option is given. On the next line will be the text provided by the user in the textbox. On a timeout, it will return `0` or `timeout`, and the text from the textbox will not be returned. Example standard-inputbox Perl script
Options: (in addition to global options)
‑‑text "initial text" | This is the initial text in the input box.
‑‑informative‑text "extra informative text to be displayed" | This is the text for the label above the input box.
‑‑no‑cancel | Don't show a cancel button.
‑‑float | Float on top of all windows.
‑‑timeout numSeconds | The amount of time, in seconds, that the window will be displayed if the user does not click a button. Does not time out by default.
‑‑no‑show | This makes it a secure inputbox. Instead of what the user types, only dots will be shown.

back to runmodes/controls
up to global options

### secure-inputbox

This is an alias for running an inputbox with the `--no-show` option. All options available to inputbox are available to `secure-inputbox`.

back to runmodes/controls
up to global options

### secure-standard-inputbox

This is an alias for running a standard-inputbox with the `--no-show` option. All options available to standard-inputbox are available to `secure-standard-inputbox`.

back to runmodes/controls
up to global options

### fileselect

This control provides a file selection window. returns: the files or directories selected by the user, or nothing if they cancel. Example fileselect shell script
Options: (in addition to global options)
‑‑text "main text message" | This is the text displayed at the top of the fileselect window.
‑‑select‑directories | Allow the user to select directories as well as files. Default is to disallow it.
‑‑select‑only‑directories | Allows the user to select only directories.
‑‑packages‑as‑directories | Allows the user to navigate into packages as if they were directories, rather than selecting the package as a file.
‑‑select‑multiple | Allow the user to select more than one file. Default is to allow only one file/directory selection.
‑‑with‑extensions list of extensions | Limit selectable files to ones with these extensions. `list of extensions` should be space separated, and given as multiple arguments (ie: don't double quote the list). Example: `CocoaDialog fileselect --with-extensions .c .h .m .txt` The period/dot at the start of each extension is optional.
‑‑with‑directory directory | Start the file select window in `directory`. The default value is up to the system, and will usually be the last directory visited in a file select dialog.
‑‑with‑file file | Start the file select window with `file` already selected. By default no file will be selected. This must be used with `--with-directory`. It should be the filename of a file within the directory.

back to runmodes/controls
up to global options

### filesave

This control provides a file save window, which allows the user to select a file, or specify a new file. This dialog allows the user to create directories. However, if the user specifies a file that does not yet exist, it will not be created. This is a task for your script. returns: the file selected (which may not exist), or nothing if they cancel.
Options: (in addition to global options)
‑‑text "main text message" | This is the text displayed at the top of the filesave window.
‑‑packages‑as‑directories | Allows the user to navigate into packages as if they were directories, rather than selecting the package as a file.
‑‑no‑create‑directories | Prevents the user from creating new directories.
‑‑with‑extensions list of extensions | Limit selectable files (including files the user creates) to ones with these extensions. `list of extensions` should be space separated, and given as multiple arguments (ie: don't double quote the list). Example: `CocoaDialog filesave --with-extensions .c .h .m .txt` The period/dot at the start of each extension is optional.
‑‑with‑directory directory | Start the file save window in `directory`. The default value is up to the system, and will usually be the last directory visited in a file dialog.
‑‑with‑file file | Start the file save window with `file` already selected. By default no file will be selected. This must be used with `--with-directory`. It should be the filename of a file within the directory.

back to runmodes/controls
up to global options

### textbox

This is a text box with a large text area. At least one button (`--button1`) must be specified. If labels for the other buttons are not given, the buttons will not appear on the text box. Buttons go from right to left. `--button1` is the right-most button. returns: `1`, `2`, or `3` depending on which button was pressed; or the label of the button if the `--string-output` option is given. If the `--editable` option was given, it will print the contents of the text box following the return value for the button. On a timeout, it will return `0` or `timeout`, and the text from the textbox will not be returned. Example textbox Perl script
Options: (in addition to global options)
‑‑text "main text message" | This is the text that goes into the text box. This value overrides `--text-from-file`.
‑‑text‑from‑file filename | Fills the text box with the contents of `filename`
‑‑informative‑text "extra informative text to be displayed" | This is the message above the text box.
‑‑button1 "label for button 1" | required. This is the right-most button.
‑‑button2 "label for button 2" | This is the middle button.
‑‑button3 "label for button 3" | This is the left-most button. This will not be displayed if there is no `--button2` label specified.
‑‑editable | Makes the text box editable. When this option is set, the return value for the button will be followed with the contents of the text box.
‑‑focus‑textbox | This option is only useful when `--editable` is set. This makes the initial focus on the textbox rather than the rightmost button.
‑‑selected | Selects all the text in the text box.
‑‑scroll-to bottom_or_top | Where `bottom_or_top` is one of `bottom` or `top`. Causes the text box to initially scroll to the bottom or top if the text it contains is larger than its current view. Default is `top`.
‑‑float | Float on top of all windows.
‑‑timeout numSeconds | The amount of time, in seconds, that the window will be displayed if the user does not click a button. Does not time out by default.

back to runmodes/controls
up to global options

### progressbar

The progress bar is a bit different, and slightly more complex than the other controls. It has no return value, but reads input on `stdin`. It will continue to display until it reads an `EOF`. Input for the progress bar is in the form: `newPercent updated text to be displayed` and must be terminated by a newline. If you want to leave the current text intact, just provide the new percent. `newPercent` should be a number. Examples (the first sets new text, the second leaves the old text): 26 We're now at 26% 26 In your code it would like this: `"26 We're at 26%\n"`. That newline is important. Ideas and help for working with the progressbar in the shell Example progressbar Perl script Example progressbar shell script Python class for working with the progressbar
Options: (in addition to global options)
‑‑text "initial text to display" | This is the text that will be initially displayed.
‑‑percent number | Initial percentage, between 0 and 100, for the progress bar
‑‑indeterminate | This option makes the progress bar an animated "barbershop pole" (for lack of better description). It does not indicate how far the operations you're performing have progressed; it just shows that your application/script is busy. You can still update the text of the label when writing to CocoaDialog's `stdin` - and it doesn't matter what percentage you feed it.

back to runmodes/controls
up to global options

### dropdown

This control provides a dropdown list of items to select from and customizable buttons. Values for the dropdown list must be provided. At least one button (`--button1`) must be specified. If labels for the other buttons are not given, the buttons will not appear on the message box. Buttons go from right to left. `--button1` is the right-most button. returns: `1`, `2`, or `3` depending on which button was pressed; or the label of the button if the `--string-output` option is given. Returns `4` (for both regular and `--string-output`) if the user didn't press a button due to `--exit-onchange`. On the following line will be the index (zero-based) of the selected item, or its label if the `--string-output` option is given. On a timeout, it will return `0` or `timeout`, and the selected item will not be returned. Also see the standard-dropdown. Example dropdown Perl script
Options: (in addition to global options)
‑‑text "text" | This is the text for the label above the dropdown box.
‑‑items list of values | required. These are the labels for the options provided in the dropdown box. `list of values` should be space separated, and given as multiple arguments (ie: don't double quote the entire list. Provide it as you would multiple arguments for any shell program). The first item in the list is always selected by default. Example: `CocoaDialog dropdown --text "Favorite OS?" --items "GNU/Linux" "OS X" Windows Amiga "TI 89" --button1 "Ok"`
‑‑pulldown | Sets the style to a pull-down box, which differs slightly from the default pop-up style. The first item remains visible. This option probably isn't very useful for a single-function dialog such as those CocoaDialog provides, but I've included it just in case it is. To see how their appearances differ, just try them both.
‑‑button1 "label for button 1" | required. This is the right-most button.
‑‑button2 "label for button 2" | This is the middle button.
‑‑button3 "label for button 3" | This is the left-most button. This will not be displayed if there is no `--button2` label specified.
‑‑exit‑onchange | Makes the program exit immediately after the selection changes, rather than waiting for the user to press one of the buttons. This makes the return value for the button `4` (for both regular output and with `--string-output`).
‑‑float | Float on top of all windows.
‑‑timeout numSeconds | The amount of time, in seconds, that the window will be displayed if the user does not click a button. Does not time out by default.

back to runmodes/controls
up to global options

### standard-dropdown

This control provides a dropdown list of items to select from and the standard "Ok" and "Cancel" buttons. Values for the dropdown list must be provided. returns: `1` for ok, `2` for cancel, depending on which button was pressed; or `Ok` or `Cancel` if the `--string-output` option is given. Returns `4` (for both regular and `--string-output`) if the user didn't press a button due to `--exit-onchange`. On the following line will be the index (zero-based) of the selected item, or its label if the `--string-output` option is given. On a timeout, it will return `0` or `timeout`, and the selected item will not be returned.
Options: (in addition to global options)
‑‑text "text" | This is the text for the label above the dropdown box.
‑‑items list of values | required. These are the labels for the options provided in the dropdown box. `list of values` should be space separated, and given as multiple arguments (ie: don't double quote the entire list. Provide it as you would multiple arguments for any shell program). The first item in the list is always selected by default. Example: `CocoaDialog dropdown --text "Favorite OS?" --items "GNU/Linux" "OS X" Windows Amiga "TI 89" --button1 "Ok"`
‑‑pulldown | Sets the style to a pull-down box, which differs slightly from the default pop-up style. The first item remains visible. This option probably isn't very useful for a single-function dialog such as those CocoaDialog provides, but I've included it just in case it is. To see how their appearances differ, just try them both.
‑‑exit‑onchange | Makes the program exit immediately after the selection changes, rather than waiting for the user to press one of the buttons. This makes the return value for the button `4` (for both regular output and with `--string-output`).
‑‑no‑cancel | Don't show a cancel button.
‑‑float | Float on top of all windows.
‑‑timeout numSeconds | The amount of time, in seconds, that the window will be displayed if the user does not click a button. Does not time out by default.

back to runmodes/controls
up to global options