Adobe ExtendScript Toolkit

ExtendScript ToolKit

# BasicExternalObject.cpp File Reference

## Detailed Description

The sample shows how to implement a basic external object and to extend the JavaScript DOM.

The sample demonstrates how to pass simple data types back to JavaScript from the External Object such as Strings, booleans, integers and scripts.

All of the exported functions that are available to JavaScript take 3 arguments:

- An array of variant data.
- An argument count.
- A variant data structure that takes the return value.

The variant data is of type TaggedData, which represents a JavaScript argument. The supported data types for TaggedData are:

- Undefinied
- Boolean
- Double
- String
- Script

For information on how to call the individual methods then see the comments for each methods or see the loadExternalObject.jsx script file that accompanies this sample.

See SoSharedLibDefs.h for error codes and return types

See sampleprojects for information on how to build the library

See installing for information on how to install and use the library

## Functions

static char * | getNewBuffer (string &s)
| Utility function to handle strings and memory clean up.
BASICEXTERNALOBJECT_API long | makeArray (TaggedData *argv, long argc, TaggedData *retval)
| Create a three-element array as a script and returns that array.
BASICEXTERNALOBJECT_API long | getAverage (TaggedData *argv, long argc, TaggedData *retval)
| Computes the average of passed integers.
BASICEXTERNALOBJECT_API long | appendString (TaggedData *argv, long argc, TaggedData *retval)
| Appends a string onto the passed argument.
BASICEXTERNALOBJECT_API long | myScript (TaggedData *argv, long argc, TaggedData *retval)
| Returns a script that creates a new dialog window within the ESTK.
BASICEXTERNALOBJECT_API long | acceptBoolean (TaggedData *argv, long argc, TaggedData *retval)
| accepts a single parameter of true or false.
BASICEXTERNALOBJECT_API void | ESFreeMem (void *p)
| Free any string memory which has been returned as function result.
BASICEXTERNALOBJECT_API long | ESGetVersion ()
| Returns the version number of the library.
BASICEXTERNALOBJECT_API char * | ESInitialize (const TaggedData **argv, long argc)
| Initialize the library and return function signatures.
BASICEXTERNALOBJECT_API void | ESTerminate ()
| Terminate the library.

## Function Documentation

BASICEXTERNALOBJECT_API long acceptBoolean | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | retval |
| ) |  |  |

accepts a single parameter of true or false.

This methods returns a string to JavaScript describing the value that was passed in as an argument. To call from JavaScript:

     myObj.acceptBoolean(true);

If the arguments are not correct then a bad argument error code is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | retval | The return value to be passed back to JavaScript

References TaggedData_s::data, getNewBuffer(), TaggedData_s::intval, TaggedData_s::string, and TaggedData_s::type.

BASICEXTERNALOBJECT_API long appendString | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | retval |
| ) |  |  |

Appends a string onto the passed argument.

This function only accepts a single argument, a String. The passed argument is appended with another string and then returned back to the scripting environment. To call from JavaScript:

     myObj.appendString("A String");

If the arguments are not correct then a bad argument error code is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | retval | The return value to be passed back to JavaScript

References TaggedData_s::data, getNewBuffer(), TaggedData_s::string, and TaggedData_s::type.

BASICEXTERNALOBJECT_API void ESFreeMem | ( | void * | p | ) |

Free any string memory which has been returned as function result.

Parameters:

  | *p | Pointer to the string

BASICEXTERNALOBJECT_API long ESGetVersion | ( |  | ) |

Returns the version number of the library.

ExtendScript publishes this number as the version property of the object created by new ExternalObject.

BASICEXTERNALOBJECT_API char* ESInitialize | ( | const TaggedData ** | argv,
|  | long | argc |
| ) |  |  |

Initialize the library and return function signatures.

These signatures have no effect on the arguments that can be passed to the functions. They are used by JavaScript to cast the arguments, and to populate the reflection interface.

BASICEXTERNALOBJECT_API void ESTerminate | ( |  | ) |

Terminate the library.

Does any necessary clean up that is needed.

BASICEXTERNALOBJECT_API long getAverage | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | retval |
| ) |  |  |

Computes the average of passed integers.

From JavaScript, this function can be called with any number of arguments. The passed arguments must be numbers and not strings. To call from JavaScript:

     myObj.average(10, 20, 30);

If the arguments are not correct then a bad argument error code is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | retval | The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::fltval, and TaggedData_s::type.

static char* getNewBuffer | ( | string & | s | ) | `[static]`

Utility function to handle strings and memory clean up.

Parameters:

  | s | - The referenced string

Referenced by acceptBoolean(), appendString(), makeArray(), and myScript().

BASICEXTERNALOBJECT_API long makeArray | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | retval |
| ) |  |  |

Create a three-element array as a script and returns that array.

The return type is set to kTypeScript so when the string is returned to the scripting engine it will be evaluated and ran as a script. From JavaScript this methods accept zero arguments:

     myObj.makeArray();

If the arguments are not correct then a bad argument error code is returned.

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | retval | The return value to be passed back to JavaScript

References TaggedData_s::data, getNewBuffer(), TaggedData_s::string, and TaggedData_s::type.

BASICEXTERNALOBJECT_API long myScript | ( | TaggedData * | argv,
|  | long | argc,
|  | TaggedData * | retval |
| ) |  |  |

Returns a script that creates a new dialog window within the ESTK.

The return type is set to kTypeScript so when the string is returned to the scripting engine it will be evaluated and ran as a script. The return script creates a new dialog window named 'Externalobject' with a 'OK' button that when clicked closes the connection between the jsx and ExternalObject.

Function accepts any number of parameters of any data type but will ignore them. To call from JavaScript:

     myObj.myScript();

Parameters:

  | argv | - The JavaScript argument
  | argc | the argument count
  | retval | The return value to be passed back to JavaScript

References TaggedData_s::data, getNewBuffer(), TaggedData_s::string, and TaggedData_s::type.

Copyright© 2008 Adobe Systems Incorporated. All rights reserved.

Terms of Use Online Privacy Policy Adobe and accessibility Avoid software piracy Permissions and Trademarks