# 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_
 * [displayAlertMessage](#displayalertmessage)
 * [displayChooseFile](#displaychoosefile)
 * [displayChooseFolder](#displaychoosefolder)
 * [displayChooseFromList](#displaychoosefromlist)
 * [displayErrorMessage](#displayerrormessage)
 * [displayMessage](#displaymessage)
 * [displayNotification](#displaynotification)
 * [displaySmallNumberTextBoxMessage](#displaysmallnumbertextboxmessage)
 * [displayTextBoxMessage](#displaytextboxmessage)
 * [displayYesNoQuestion](#displayyesnoquestion)

---

## API Documentation

#### Functions

### [displayAlertMessage](#displayalertmessage)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayAlertMessage(message) -> none`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Display an Alert Dialog (with stop icon).                                                                     |
| **Parameters**                              | <ul><li>message - The message you want to display as a string</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>IMPORTANT: This should no longer be used in favour of `hs.dialog.alert`</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 238](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L238) |

---

### [displayChooseFile](#displaychoosefile)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayChooseFile(whatMessage, fileType[, defaultLocation]) -> boolean or string`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Display a Choose File Dialog Box.                                                                     |
| **Parameters**                              | <ul><li>whatMessage - The message you want to display as a string.</li><li>fileType - The filetype you wish to display as either a string or a table of strings.</li><li>defaultLocation - Path to Default Location. Defaults to the desktop.</li></ul> |
| **Returns**                                 | <ul><li>`false` if cancelled if pressed otherwise the path to the file as a string</li></ul>          |
| **Notes**                                   | <ul><li>IMPORTANT: This should no longer be used in favour of `hs.dialog.chooseFileOrFolder`</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 165](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L165) |

---

### [displayChooseFolder](#displaychoosefolder)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayChooseFolder(whatMessage[, defaultLocation]) -> boolean or string`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Display a Choose Folder Dialog Box.                                                                     |
| **Parameters**                              | <ul><li>whatMessage - The message you want to display as a string</li><li>defaultLocation - An optional path (defaults to the user desktop)</li></ul> |
| **Returns**                                 | <ul><li>`false` if cancelled if pressed otherwise the path to the folder as a string</li></ul>          |
| **Notes**                                   | <ul><li>IMPORTANT: This should no longer be used in favour of `hs.dialog.chooseFileOrFolder`</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 207](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L207) |

---

### [displayChooseFromList](#displaychoosefromlist)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayChooseFromList(dialogPrompt, listOptions, defaultItems) -> table`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Displays a list that the user can select items from.                                                                     |
| **Parameters**                              | <ul><li>dialogPrompt - The message you want to display as a string</li><li>listOptions - A table containing all the options you want to include in the list as strings</li><li>defaultItems - A table containing all the options you want select by default in the list as strings</li></ul> |
| **Returns**                                 | <ul><li>A table with the selected items as strings</li></ul>          |
| **Notes**                                   | None |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 367](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L367) |

---

### [displayErrorMessage](#displayerrormessage)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayErrorMessage(whatError) -> none`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Display an Error Message Dialog, given the user the option to submit feedback.                                                                     |
| **Parameters**                              | <ul><li>whatError - The message you want to display as a string</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>IMPORTANT: This should no longer be used in favour of `hs.dialog.alert`</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 262](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L262) |

---

### [displayMessage](#displaymessage)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayMessage(whatMessage, optionalButtons) -> object`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Display an Error Message Dialog, given the user the option to submit feedback.                                                                     |
| **Parameters**                              | <ul><li>whatError - The message you want to display as a string</li><li>optionalButtons - Optional buttons</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>IMPORTANT: This should no longer be used in favour of `hs.dialog.alert`</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 297](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L297) |

---

### [displayNotification](#displaynotification)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayNotification(whatMessage) -> none`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Display's an alert on the screen.                                                                     |
| **Parameters**                              | <ul><li>whatMessage - The message you want to display as a string</li></ul> |
| **Returns**                                 | <ul><li>None</li></ul>          |
| **Notes**                                   | <ul><li>Any existing alerts will be removed to make way for the new one.</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 398](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L398) |

---

### [displaySmallNumberTextBoxMessage](#displaysmallnumbertextboxmessage)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displaySmallNumberTextBoxMessage(whatMessage, whatErrorMessage, defaultAnswer) -> boolean or string`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Display a dialog box prompting the user for a number input. It accepts only entries that coerce directly to class integer.                                                                     |
| **Parameters**                              | <ul><li>whatMessage - The message you want to display as a string</li><li>whatErrorMessage - The error message that appears if a user input is invalid</li><li>defaultAnswer - The default value of the text box</li></ul> |
| **Returns**                                 | <ul><li>`false` if cancelled if pressed otherwise the text entered in the dialog box</li></ul>          |
| **Notes**                                   | <ul><li>IMPORTANT: This should no longer be used in favour of `hs.dialog.textPrompt`</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 78](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L78) |

---

### [displayTextBoxMessage](#displaytextboxmessage)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayTextBoxMessage(whatMessage, whatErrorMessage, defaultAnswer, validationFn) -> boolean or string`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Display a dialog box prompting the user for a text input.                                                                     |
| **Parameters**                              | <ul><li>whatMessage - The message you want to display as a string</li><li>whatErrorMessage - The error message that appears if a user input is invalid</li><li>defaultAnswer - The default value of the text box</li><li>validationFn - A function that takes one parameter and returns a boolean value</li></ul> |
| **Returns**                                 | <ul><li>`false` if cancelled if pressed otherwise the text entered in the dialog box</li></ul>          |
| **Notes**                                   | <ul><li>IMPORTANT: This should no longer be used in favour of `hs.dialog.textPrompt`</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 119](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L119) |

---

### [displayYesNoQuestion](#displayyesnoquestion)

|                                             |                                                                                     |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature**                               | `cp.dialog.displayYesNoQuestion(message, informativeText) -> boolean`                                                                    |
| **Type**                                    | Function                                                                     |
| **Description**                             | Displays a "Yes" or "No" question.                                                                     |
| **Parameters**                              | <ul><li>whatMessage - The message you want to display as a string</li><li>informativeText - Informative text.</li></ul> |
| **Returns**                                 | <ul><li>`true` if yes is clicked otherwise `false`</li></ul>          |
| **Notes**                                   | <ul><li>IMPORTANT: This should no longer be used in favour of `hs.dialog.alert`</li></ul> |
| **Examples**                                | None |
| **Source**                                  | [src/extensions/cp/dialog/init.lua line 336](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/dialog/init.lua#L336) |

---

---

<script src="https://giscus.app/client.js"
        data-repo="CommandPost/CommandPost"
        data-repo-id="MDEwOlJlcG9zaXRvcnk3NDY0NTk2NQ=="
        data-category="Website Discussion"
        data-category-id="DIC_kwDOBHMBzc4CXFFA"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="dark"
        data-lang="en"
        crossorigin="anonymous"
        async>
</script>