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), but it may not be entirely up to date.
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, 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.
|
Changing the Icon
To change the icon, simply replace CocoaDialog.app/Contents/Resources/cocoaDialog.icns with an icon file of your own.
Be sure yours has the same filename.
You can create an icon file from a regular picture file using "Icon Composer," included with Apple's Developer Tools. (it should be located at: /Developer/Applications/Utilities/Icon Composer.app)
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
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
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
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
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.
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
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.
|
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
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
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
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.
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
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.
On the following line will be the index (zero-based) of the selected
item, or its label if the --string-output option is
given.
Also see the
standard-dropdown.
|
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
0 (for both regular output and with
--string-output). |
|
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.
On the following line will be the index (zero-based) of the selected
item, or its label if the --string-output option is
given.
|
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
0 (for both regular output and with
--string-output). |
| ‑‑no‑cancel |
Don't show a cancel button. |
|
back to runmodes/controls
up to global options
