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

Documentation

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).

This documentation is also available offline in the Resources directory of the application bundle (CocoaDialog.app/Contents/Resources/documentation.html).

Contents

Executing CocoaDialog

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

See the examples page for a simple way to find the binary in its most common locations. From here on we will refer to this binary file as simply CocoaDialog

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, makes it return the label you provided.
‑‑no‑newline By default, return values will be printed with a trailing newline. This will suppress that behavior. Note this will only suppress the trailing newline on the last line when a control returns multiple lines.
‑‑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.

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.

msgbox

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.

Also see the yesno-msgbox and ok-msgbox.

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.
‑‑style style Where style is one of informational, warning, or critical. Default is informational. This option specifies the style of the message box. The main difference between the styles is the icon that is shown.
‑‑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

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.

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.
‑‑style style Where style is one of informational, warning, or critical. Default is informational. This option specifies the style of the message box. The main difference between the styles is the icon that is shown.
‑‑no‑cancel Don't show a cancel button, only "Ok".

back to runmodes/controls
up to global options

yesno-msgbox

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.

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.
‑‑style style Where style is one of informational, warning, or critical. Default is informational. This option specifies the style of the message box. The main difference between the styles is the icon that is shown.
‑‑no‑cancel Don't show a cancel button.

back to runmodes/controls
up to global options

inputbox

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.

Also see the standard-inputbox.

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.

back to runmodes/controls
up to global options

standard-inputbox

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.

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.

back to runmodes/controls
up to global options

fileselect

fileselect

This control provides a file selection window.

returns: the files or directories selected by the user, or nothing if they cancel.

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‑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 broken This does not currently work. TODO. Start the file select window with file already selected. By default no file will be selected.

back to runmodes/controls
up to global options

textbox

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.

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.
‑‑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.

back to runmodes/controls
up to global options

progressbar

progressbar indeterminate 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 this: "26 We're at 26%\n". That newline is important.

Be sure to look at the examples if you're still unclear about the progress bar.

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