Execution of an UXP script for InDesign®.
Execution of an UXP script for InDesign®. The call can be given the complete script text or the path to an idjs script file.
The specification of predefined objects is identical to the Predefined Objects of run_javascript.
In ExtentScript javascripts (jsx), the variables created from the predefined objects can simply be inserted at the start of the script. This is not possible in UXP scripts (idjs) for two reasons:
Only after these definitions the automatically generated variables of the predefined objects may follow. But since you can make these definitions
in a variety of notations (except the name app!), you must show us the place in your script where we can insert the calculated variables.
For this, write the following comment at this point (in exactly this spelling):
// priint:params
Define the script position in the UXP script where the automatically calculated variables of the predefined objects are to be inserted.
let myInDesign = require("indesign");
let app = myInDesign.app;
// #pragma once
// priint:params
...
With the comment (in exactly this spelling)
// #pragma once
you can ensure that the script is executes only only once in the Front Row,
even if multiple documents are selected.
Predefined objects can only be used in scripts whose text is defined as a string (char* or String). Predefined objects cannot be supported in file-based scripts! Scripts in the Front Row panel are read in and always executed as strings..
Attention: Many UXP functions and queries are executed asynchronously:
For example, the question about the path to the file of a document, document.fullName, is answered asynchronously and only returns the answer [object promise] without any further information. To really obtain the actual path, you must retrieve the information with await.
alert (doc.fullName); // shows '[object promise]' alert (await doc.fullName); // shows the path of the document'
That's not too bad. But unfortunately InDesign® also aborts the current undo sequence after an await and the scripts can then no longer be undone in a single step (undo entire script) but only in the individual actions of the script. If this is acceptable to you ...
Please note: If you execute run_uxpscript with Predefined Objects, the document path is required to determine the target document of the script, that means, we need to ask await doc.fullName. UXP scripts can therefore only be undone in individual steps when used with predefined objects.
The external execution of UXP scripts with sampleclient is identical to the execution of ExtentScript Java scripts. The sampleclient automatically uses the idjs extension of the scripts.
| Name | Type | Default | Description | ||||||||
| Return | int | 0 or ErrorCode This value indicates wether the script execution was successful or not. This value is not the return value of the script itself! To retreive the return value of the script, use returnType, returnValue, and returnMaxLen. |
|||||||||
| script_or_path | String or char* | - | Script code as string (UXP JavaScript) or the full file path of an UXP (idjs) or ExtentScript (jsx) Javascript file.
Please note that ExtentScript and UXP have different syntax. An automatic distinction between the two script types is only possible when specifying file paths (and is done via the file extensions). If you have a ExtentScript script as a string, you can use the function run_javascript. |
||||||||
| isPath | int | 0 | Does script_or_path contains the JavaScript text or a file path? 0 : script text 1 : path, predefined objects not supported in this case! |
||||||||
| showErrorAlert | int | 1 | Show error alert on script errors? 0 : No 1 : Yes |
||||||||
| flags | int | 0 | Additional setting for the execution. Several entries can be added together. The descriptions are taken directly from the InDesign SDK from Adobe. 1 : Indicates whether to load script into debugger for execution 0 : Push each script request as a separate undo step 2 : Push the entire script as a single regular undo step. If an error occurs, roll back to the beginning of the script request that generated the error 4 : Similar to 2, however faster because we don't snapshot each script request. If an error occurs, we roll back to the beginning of the entire script. 6 : Push the entire script as a single auto-undoable step. |
||||||||
| returnType | int | 0 | Type of returnValue. 0 : returnValue ignore kInt : returnValue is of type int* kFloat : returnValue is of type float* kString : returnValue is of type String or char* Attention: This is the type of returnValue, NOT the type of value returned by the script! If you don't know the scripts return type (or it uses a type not defined above), you may use kString, anyway. For later uses of this value, you have to convert into the appropriate type (val, fval, ...). |
||||||||
| returnValue | int*, float*, String or char* | 0 | Variable for the return value of the script 0 : ignore |
||||||||
| returnMaxLen | int | 0 | Only used in case of returnType = kString and when the return type is of type char*.
Set it to the number of bytes allocated for returnValue. 0 : don't care, I have allocated enough space. |
||||||||
| itemRefs | ItemList | - | ItemRefs which are converted to global variables in your JavaScript, see Predefined Objects | ||||||||
| ... | int, value | -,- | [Since v4.3 R36514, 12. April 2025] Arbitrarily long (also empty) list of pairs of data type and value. The information is passed in sequence as arg1, arg2, ... to the script execution and can be queried in the script with the following instruction, for example: app.scriptArgs.get("arg1");
In addition, the current script path is transferred in arg0. If the script is defined as a string, arg0 contains the value “String” Erlaubt sind folgende Typ/Wert-Paare:
|
Here is a very simple UXP script that shows the use of UXP script results.
let myInDesign = require("indesign"); const script = require("uxp").script; let app = myInDesign.app;
try { alert("aaa"); } catch (error) { alert(error); }
//script.setResult(1410); // integer (kInt) result //script.setResult(3.1415926); // float (kFloat) result script.setResult("Hallo Paula"); // String (kString) result
function alert(msg) { theDialog = app.dialogs.add(); col = theDialog.dialogColumns.add(); colText = col.staticTexts.add(); colText.staticLabel = "" + msg; theDialog.canCancel = false; theDialog.show(); theDialog.destroy(); }
This call to run_uxpscrript allows you to determine the script result of a UXP script. The UXP script is called a1.idjs and must be on your desktop.
#include "internal/types.h"
int main() { int intRet = 12; float floatRet = 12.3; String strRet = string::alloc ();
run_uxpscript ( "$DESKTOP/a1.idjs", 1, // is path 1, 3, // show error alert, undo entire script //kInt, &intRet); //kFloat, &floatRet); kString, strRet);
showmessage ("I : %d\nF : %.8f\nS : '%s'", intRet, floatRet, strRet); return 0; }
The script executes the UXP a1.idjs of your desktop with some additional arguments that are defined directly in the cScript and can be used by the UXP script a1.idjs.
#include "internal/types.h"
int main() { run_uxpscript ( "$DESKTOP/a1.idjs", 1, // is path 1, 3, // show error alert, undo entire script 0, 0, 0, 0, // no addtional items kString, "XXXX", kInt, 123, kFloat, 3.1415926, kString, 0); // defines the value "NULL" in the Javascript
return 0; }
The UXP scriprt demonstrates how arguments from calls to run_javascript can be used in UXP.
let myInDesign = require("indesign"); const script = require("uxp").script; let app = myInDesign.app;
try { alert (script.args[0].split ('=')[1]); alert (script.args[1].split ('=')[1]); alert (script.args[2].split ('=')[1]); alert (script.args[3].split ('=')[1]); alert (script.args[4].split ('=')[1]); } catch (error) { alert(error); }
function alert(msg) { theDialog = app.dialogs.add(); col = theDialog.dialogColumns.add(); colText = col.staticTexts.add(); colText.staticLabel = "" + msg; theDialog.canCancel = false; theDialog.show(); theDialog.destroy(); }
Alphabetic index HTML hierarchy of classes or Java