CocoaDialog Reference

Global Icons

By default, the CocoaDialog application comes with several built in icons for your use.
These icons are meant to be used as values for the global icon parameter.

Mouse over any icon to view it's name...

Global Parameters

These parameters apply to most if not all dialog types.
If for some reason you notice that one of these options isn't working for your dialog type, try running the CocoaDialog wrapper with debugging enabled.

Parameter
 Accepted Type Description
title
 string The title shown at the top of the dialog box
string_output
 boolean Enable string output instead of dialog's default.
For example, clicking on a button1 entitled "myButton" will return ["myButton"] rather than ["1"]
no_newline
 boolean Disable newlines in dialog's label attributes
width
 integer, float The desired width of the dialog in pixels
height
 integer, float The desired height of the dialog in pixels
posX
 integer, float Distance away from the left side of the screen that the dialog should be spawned (in pixels)
posY
 integer, float Distance away from the top of the screen that the dialog should be spawned (in pixels)
icon
 string Icon (from global icons) that should be used in your dialog
timeout
 integer, float Time until the dialog dies
timeout_format
 string Format for displaying the time remaining in the timeout.
Requires a string format character %s in order to show the time remaining
icon_bundle
 string Use the icon of the passed bundle ID in your dialog
icon_file
 string Absolute path to the icon file to be used in your dialog
icon_size
 integer, float Size of icon in dialog (in pixels)
icon_height
 integer, float Height of your dialog's icon (in pixels)
icon_width
 integer, float Width of your dialog's icon (in pixels)

Dialog Types

This is the listing of all available dialog types that the CocoaDialog wrapper currently supports.

To view detailed information about a dialog, click on it's image...

notify

A message box dialog used to either present the user with important information or to allow the user to make a custom selection.

notify

Additional Parameters
Parameter
 Accepted Type Description Required
title
 string The title of the notification
description
 string The message of the notification
sticky
 boolean Force the notification to stay displayed until clicked
no_growl
 boolean Disable the default use of the GrowlSDK
alpha
 integer, float Value of alpha to be used
(requires no_growl)
text_color
 string Hex notation of color to used for text
(requires no_growl)
border_color
 string Hex notation of color to use for border
(requires no_growl)
background_bottom
 string Hex notation of color to use for the bottom of the background
(requires no_growl)
background_top
 string Hex notation of color to use for the top of the background
(requires no_growl)
Implementation
PHP
Python
Ruby
$my_notification = $client->notify([
    'title'=>'My Notification',
    'description'=>'A description goes here',
    'no_growl'=true,
    'icon'=>'info'
]);
my_notification = client.notify(
    title='My Notification',
    description='A description goes here',
    no_growl=True,
    icon='info'
)
my_notification = @client.notify(
    title:'My Notifiation',
    description:'A description goes here',
    no_growl:true,
    icon:'info'
)
Returns

Notifications return nothing...

×

checkbox

A dialog that allows you to present several checkable boxes. This is useful for allowing your user to select special settings to enable in your workflow.

checkbox

Additional Parameters
Parameter
 Accepted Type Description Required
label
 string The label above the list of checkboxes
items
 list The labels for the available checkboxes in the dialog
checked
 list A list of checkbox indices to check by default (corresponds to items)
disabled
 list A list of checkbox indices to disable by default (corresponds to items)
button1
 string The default and right-most button's label
button2
 string The center-most button's label
button3
 string The left-most button's label
rows
 integer The amount of available checkbox rows
columns
 integer The amount of available checkbox columns
Implementation
PHP
Python
Ruby
...
...
...
Returns

...

×

radio

A dialog that allows you to present multiple radio toggles. This is useful for allowing your user to enable or disable aspects of your workflow.

radio

Additional Parameters
Parameter
 Accepted Type Description Required
label
 string The label above the list of radio toggles
items
 list The labels for the available radio toggles in the dialog
selected
 list A list of radio indices to select by default (corresponds to items)
disabled
 list A list of radio indices to disable by default (corresponds to items)
button1
 string The default and right-most button's label
button2
 string The center-most button's label
button3
 string The left-most button's label
rows
 integer The amount of available radio toggle rows
columns
 integer The amount of available radio toggle columns
Implementation
PHP
Python
Ruby
...
...
...
Returns

...

×

slider

A dialog that presents the user with a movable slider widget. This dialog is useful for allowing your user to adjust some predefined quality.

slider

Additional Parameters
slider
Parameter
 Accepted Type Description Required
label
 string The label above the slider widget
always_show_value
 boolean Enable a second label to always show the slider's current value
min
 integer, float The minimum value of the slider
max
 integer, float The maximum value of the slider
ticks
 integer The amount of ticks on the slider widget
slider_label
 string The label tied to the slider widget
value
 integer, float The default value of the slider widget
button1
 string The default and right-most button's label
button2
 string The center-most button's label
button3
 string The left-most button's label
return_float
 boolean Force the slider widget to return a float value
Implementation
PHP
Python
Ruby
...
...
...
Returns

...

×

msgbox

A message box dialog used to either present the user with important information or to allow the user to make a custom selection.

msgbox

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
informative_text
 string The light text below the the subheader used for displaying a message
button1
 string The default and right-most button's label
button2
 string The center-most button's label
button3
 string The left-most button's label
no_cancel
 boolean Deny access to the cancel button (if available)
float
 boolean Force dialog to float above all other windows
Implementation
PHP
Python
Ruby
$my_message_box = $client->msgbox([
    'title'=>'My Message Box',
    'text'=>'This is the heading of my message box',
    'informative_text'='Informational text goes in here',
    'button1'=>'Click Me!',
    'button2'=>"Don't click me...",
    'icon'=>'info'
]);
my_message_box = client.msgbox(
    title='My Message Box',
    text='This is the heading of my message box',
    informative_text='Informational text goes in here',
    button1='Click Me!',
    button2='Don\'t click me...',
    icon='info'
)
my_message_box = @client.msgbox(
    title:'My Message Box',
    text:'This is the heading of my message box',
    informative_text:'Informational text goes in here',
    button1:'Click Me!',
    button2:'Don\'t click me...',
    icon:'info'
)
Returns

Unless the string_output parameter is set to true, the msgbox dialog returns the number of the button selected by the user as a string in an array. Suppose that the user clicks the button with the label Click Me!

The msgbox dialog would then return...

["1"]
×

ok_msgbox

A simplified version of the msgbox dialog. This dialog has predefined buttons, used for presenting the user with a simple informational dailog.

ok_msgbox

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
informative_text
 string The light text below the the subheader used for displaying a message
no_cancel
 boolean Deny access to the cancel button (if available)
float
 boolean Force dialog to float above all other windows
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

yesno_msgbox

A variation of the ok_msgbox dialog. This dialog has predefined buttons, used for presenting the user with a simple informational dailog.

yesno_msgbox

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
informative_text
 string The light text below the the subheader used for displaying a message
no_cancel
 boolean Deny access to the cancel button (if available)
float
 boolean Force dialog to float above all other windows
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

inputbox

A input box dialog used to take input from the user. Used for allowing a user to accept somekind of specific string.

inputbox

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
informative_text
 string The light text below the the subheader used for displaying a message
button1
 string The default and right-most button's label
button2
 string The center-most button's label
button3
 string The left-most button's label
no_cancel
 boolean Deny access to the cancel button (if available)
float
 boolean Force dialog to float above all other windows
no_show
 boolean Force input widget to mask input (password like)
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

standard_inputbox

A simplified version of the inputbox dialog. This dialog has predefined buttons used for asking the user for simple input.

standard_inputbox

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
informative_text
 string The light text below the the subheader used for displaying a message
no_cancel
 boolean Deny access to the cancel button (if available)
float
 boolean Force dialog to float above all other windows
no_show
 boolean Force input widget to mask input (password like)
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

secure_inputbox

A secured input box dialog used to take input from the user. Useful for allowing the user to enter some kind of password.

secure_inputbox

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
informative_text
 string The light text below the the subheader used for displaying a message
button1
 string The default and right-most button's label
button2
 string The center-most button's label
button3
 string The left-most button's label
float
 boolean Force dialog to float above all other windows
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

secure_standard_inputbox

A combination of the secure and standard inputbox dialogs. This dialog has predefined buttons and a secure input field.

secure_standard_inputbox

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
informative_text
 string The light text below the the subheader used for displaying a message
no_cancel
 boolean Deny access to the cancel button (if available)
float
 boolean Force dialog to float above all other windows
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

fileselect

This dialog allows you to navigate and select a file off the system. This dialog is useful for asking a user to select some file.

fileselect

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
select_directories
 boolean Allow the user to select directories as well as files
select_only_directories
 boolean Force the user to only select directories
select_multiple
 boolean Allow the user to make multiple selections
with_extensions
 list Force the user to only select files with an extension from this list
with_directory
 string Absolute path to directory to select by default
with_file
 string Absolute path to file to select by default
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

filesave

This dialog allows you to navigate and select a file off the system. This dialog is useful for asking a user to select some file.

filesave

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
packages_as_directories
 boolean Treat package files as directories
no_create_directories
 boolean Don't allow users to create directories from the dialog
with_extensions
 list Force the user to only save files with an extension from this list
with_directory
 string Absolute path to directory to select by default
with_file
 string Absolute path to file to select by default
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

textbox

A box with a large textbox widget. Used to allow the user to view or edit the contents of a file.

textbox

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
informative_text
 string The light text below the the subheader used for displaying a message
text_from_file
 string Absolute path to file from which to load text into the textbox widget
button1
 string The default and right-most button's label
button2
 string The center-most button's label
button3
 string The left-most button's label
editable
 boolean Allow the user to edit the text in the textbox widget
focus_textbox
 boolean Focus on the textbox widget on dialog spawn
selected
 boolean Select all the text in the textbox widget on dialog spawn
scroll_to
 string Scroll down to the given text in the textbox widget
float
 boolean Force dialog to float above all other windows
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

dropdown

A box with a dropdown widget. Used to allow the user to select a single element from some list.

standard_dropdown

A simplified version of the dropdown dialog. This dialog has predefined buttons.

standard_dropdown

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
items
 list The available items in the dropdown widget
pulldown
 boolean Enable the pulldown style for the dropdown widget
exit_onchange
 boolean Exit the dialog as soon as the dropdown selection is changed
float
 boolean Force dialog to float above all other windows
Implementation
PHP
Python
Ruby
...
...
...
Returns

×

progressbar

A dialog that allows you to present a progress bar to the user. This is useful for showing the progress of some process.

progressbar

Additional Parameters
Parameter
 Accepted Type Description Required
text
 string The bold text shown as a subheader in the dialog
percent
 integer, float The percent of the progress bar on dialog spawn
indeterminite
 boolean Force the dialog to show an indeterminate progress bar
stoppable
 boolean Allow the progress bar dialog to be stopped
float
 boolean Force dialog to float above all other windows
Methods
Method
Parameters
Returns
 Description
update
 text percent 1 if dialog is still alive 0 if dialog is dead Updates the state of the progress bar.
Parameters are passed explicitly
finish
 0 Kills the current instance of the progress bar.
Refrain from using this method.
Implementation
PHP
Python
Ruby
...
...
...
Returns

×