#cp.dialog

A collection of handy Dialog tools for CommandPost.

Where possible, hs.dialog should be used instead of cp.dialog - however, there are still some instances where cp.dialog is preferred (i.e. if you want a dialog box to appear as if it's been generated by Final Cut Pro).


#API Overview

Functions - API calls offered directly by the extension


#API Documentation

#Functions

Signaturecp.dialog.displayAlertMessage(message) -> none
TypeFunction
DescriptionDisplay an Alert Dialog (with stop icon).
Parameters
  • message - The message you want to display as a string
Returns
  • None
Notes
  • IMPORTANT: This should no longer be used in favour of hs.dialog.alert
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 238

Signaturecp.dialog.displayChooseFile(whatMessage, fileType[, defaultLocation]) -> boolean or string
TypeFunction
DescriptionDisplay a Choose File Dialog Box.
Parameters
  • whatMessage - The message you want to display as a string.
  • fileType - The filetype you wish to display as either a string or a table of strings.
  • defaultLocation - Path to Default Location. Defaults to the desktop.
Returns
  • false if cancelled if pressed otherwise the path to the file as a string
Notes
  • IMPORTANT: This should no longer be used in favour of hs.dialog.chooseFileOrFolder
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 165

Signaturecp.dialog.displayChooseFolder(whatMessage[, defaultLocation]) -> boolean or string
TypeFunction
DescriptionDisplay a Choose Folder Dialog Box.
Parameters
  • whatMessage - The message you want to display as a string
  • defaultLocation - An optional path (defaults to the user desktop)
Returns
  • false if cancelled if pressed otherwise the path to the folder as a string
Notes
  • IMPORTANT: This should no longer be used in favour of hs.dialog.chooseFileOrFolder
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 207

Signaturecp.dialog.displayChooseFromList(dialogPrompt, listOptions, defaultItems) -> table
TypeFunction
DescriptionDisplays a list that the user can select items from.
Parameters
  • dialogPrompt - The message you want to display as a string
  • listOptions - A table containing all the options you want to include in the list as strings
  • defaultItems - A table containing all the options you want select by default in the list as strings
Returns
  • A table with the selected items as strings
NotesNone
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 367

Signaturecp.dialog.displayErrorMessage(whatError) -> none
TypeFunction
DescriptionDisplay an Error Message Dialog, given the user the option to submit feedback.
Parameters
  • whatError - The message you want to display as a string
Returns
  • None
Notes
  • IMPORTANT: This should no longer be used in favour of hs.dialog.alert
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 262

Signaturecp.dialog.displayMessage(whatMessage, optionalButtons) -> object
TypeFunction
DescriptionDisplay an Error Message Dialog, given the user the option to submit feedback.
Parameters
  • whatError - The message you want to display as a string
  • optionalButtons - Optional buttons
Returns
  • None
Notes
  • IMPORTANT: This should no longer be used in favour of hs.dialog.alert
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 297

Signaturecp.dialog.displayNotification(whatMessage) -> none
TypeFunction
DescriptionDisplay's an alert on the screen.
Parameters
  • whatMessage - The message you want to display as a string
Returns
  • None
Notes
  • Any existing alerts will be removed to make way for the new one.
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 398

Signaturecp.dialog.displaySmallNumberTextBoxMessage(whatMessage, whatErrorMessage, defaultAnswer) -> boolean or string
TypeFunction
DescriptionDisplay a dialog box prompting the user for a number input. It accepts only entries that coerce directly to class integer.
Parameters
  • whatMessage - The message you want to display as a string
  • whatErrorMessage - The error message that appears if a user input is invalid
  • defaultAnswer - The default value of the text box
Returns
  • false if cancelled if pressed otherwise the text entered in the dialog box
Notes
  • IMPORTANT: This should no longer be used in favour of hs.dialog.textPrompt
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 78

Signaturecp.dialog.displayTextBoxMessage(whatMessage, whatErrorMessage, defaultAnswer, validationFn) -> boolean or string
TypeFunction
DescriptionDisplay a dialog box prompting the user for a text input.
Parameters
  • whatMessage - The message you want to display as a string
  • whatErrorMessage - The error message that appears if a user input is invalid
  • defaultAnswer - The default value of the text box
  • validationFn - A function that takes one parameter and returns a boolean value
Returns
  • false if cancelled if pressed otherwise the text entered in the dialog box
Notes
  • IMPORTANT: This should no longer be used in favour of hs.dialog.textPrompt
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 119

Signaturecp.dialog.displayYesNoQuestion(message, informativeText) -> boolean
TypeFunction
DescriptionDisplays a "Yes" or "No" question.
Parameters
  • whatMessage - The message you want to display as a string
  • informativeText - Informative text.
Returns
  • true if yes is clicked otherwise false
Notes
  • IMPORTANT: This should no longer be used in favour of hs.dialog.alert
ExamplesNone
Sourcesrc/extensions/cp/dialog/init.lua line 336