|
| 1 | +--- |
| 2 | +title: How it works |
| 3 | +description: More details about UXP Scripting |
| 4 | +contributors: |
| 5 | + - https://github.com/amandahuarng |
| 6 | +--- |
| 7 | + |
| 8 | +# How UXP Scripting Works |
| 9 | +Each Photoshop script file is a plain text file with a `.psjs` file extension. We plan on expanding UXP scripting to other applications and supporting opening scripts via double-click in the future. When this happens, the file extension will help identify which application the script should be launched in. |
| 10 | + |
| 11 | +## Execution Context |
| 12 | +Photoshop sets an execution context while invoking a script. |
| 13 | + |
| 14 | +Within each execution context, only one script can be executed at a time. You cannot invoke another script from the running script. Using the UXP script module, you can access `ExecutionContext`. |
| 15 | + |
| 16 | +```js |
| 17 | +const script = await require("uxp").script; |
| 18 | +const executionContext = script.executionContext; |
| 19 | +``` |
| 20 | +It provides details about the current script execution, methods to send data to Photoshop, and events to manage script lifecycles. You can also use methods belonging to `executionControl.hostControl` to suspend/resume history states and auto close documents. Read more in the scripting [reference](../reference/). |
| 21 | + |
| 22 | +## Events |
| 23 | +Script execution can be cancelled when: |
| 24 | +* a user clicks on "Cancel" in the progress bar |
| 25 | +* Photoshop encounters some exception in running a script file |
| 26 | + |
| 27 | +Script developers can add event handlers to get notified when the command has been cancelled. The callback will receive "reason" as a parameter. |
| 28 | + |
| 29 | +```js |
| 30 | +executionContext.onCancel.addListener((reason) => { |
| 31 | + // reason would be a json object set by PS while cancelling |
| 32 | + reject("Message"); |
| 33 | +}); |
| 34 | +``` |
| 35 | + |
| 36 | +## User Interface |
| 37 | +Scripts can only show a dialog UI. Any UI created by a script is modal in nature and must use **global await** or it will be destroyed when the script is done running. Photoshop automatically shows a **progress bar** if the script takes more than 2-3 seconds to finish. |
| 38 | + |
| 39 | + |
| 40 | +### Global Await |
| 41 | +`await` expressions cause `async` function execution to pause until a Promise is either fulfilled or rejected, and to resume execution |
| 42 | +of the `async` function after fulfillment. When resumed, the value of the `await` expression is that of the fulfilled Promise. |
| 43 | + |
| 44 | +Global await means awaiting for a global scope async function to finish. |
| 45 | + |
| 46 | +```js |
| 47 | +function anyAsyncFunction() { |
| 48 | + return new Promise((resolve, reject) => { |
| 49 | + const val = Math.random(); |
| 50 | + if (val > 0.5) { |
| 51 | + console.log("Resolve promise"); |
| 52 | + resolve(val); |
| 53 | + } else { |
| 54 | + console.error("Rejecting promise"); |
| 55 | + reject(val); |
| 56 | + } |
| 57 | + }) |
| 58 | +} |
| 59 | + |
| 60 | +// Global await |
| 61 | +try { |
| 62 | + const val = await anyAsyncFunction(); |
| 63 | + console.log("Value from function", val); |
| 64 | +} catch { |
| 65 | + console.log("Rejected promise!;") |
| 66 | +} |
| 67 | +console.log("Script completed"); |
| 68 | +``` |
| 69 | + |
| 70 | +## Permitted UXP Modules |
| 71 | +With plugin development, developers define which UXP modules they want to access in the `manifest.json` file. Script permissions are managed by Photoshop internally and no manifest configuration is required. |
| 72 | + |
| 73 | +**At this time, not all UXP modules are accessible by scripts but we plan on enabling more modules in future UXP versions.** All modules that are currently supported are enabled by default: |
| 74 | + |
| 75 | + |
| 76 | +| UXP Module | Supported | Current Access Level | Sample |
| 77 | +| --- | --- | --- | --- | |
| 78 | +| Fonts | Yes | Installed fonts can be read | [View sample.](../samples/index.md#access-installed-fonts) | |
| 79 | +| Clipboard | Yes | Read/write access | [View sample.](../samples/index.md#readwrite-to-clipboard)| |
| 80 | +| LocalFileSystem | Yes | File pickers can be used to open/save files. You can also call the ```getTemporaryFolder API``` to access a temporary data folder. | [View sample.](../samples/index.md#access-the-local-filesystem) | |
| 81 | +| Network | No | | |
| 82 | +| LaunchProcess | No | | |
| 83 | +| WebView | No | | |
| 84 | +| IPC | No | | |
| 85 | + |
| 86 | +If you need to use the UXP modules that are not yet enabled for scripts, you should opt to create a UXP plugin instead. |
| 87 | + |
| 88 | +## FAQ |
| 89 | +* What are the required minimum versions for UDT (for debugging) and Photoshop? |
| 90 | + * UXP Scripting is available in Photoshop v23.5 and UDT v1.6. |
| 91 | +* Can you invoke a script from within another script? |
| 92 | + * No, inter-script communication is not possible. |
| 93 | +* Can you pass arguments to scripts? |
| 94 | + * For this first release, passing arguments is not supported but **will be possible in a future release.** |
| 95 | +* Can scripts be executed from plugins? |
| 96 | + * No; however, any UXP script code should be able to run from within a UXP plugin. |
| 97 | +* Can I enable permissions for a module? |
| 98 | + * Developers cannot enable or seek the permission for a module. All permitted modules are enabled by default. |
| 99 | +* Why only a limited number of modules are permitted in PS? Do we expect other modules to be enabled in the future? |
| 100 | + * This is the first release of the UXP script module, and we’re working on enabling permissions to access more modules in upcoming releases. |
0 commit comments