BasicExternalObject.cpp File Reference

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

#include "BasicExternalObject.h"
#include "SoSharedLibDefs.h"
#include <string>

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)
BASICEXTERNALOBJECT_API long	appendString (TaggedData *argv, long argc, TaggedData *retval)
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.

---

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

---

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

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

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

static char* getNewBuffer

(

string &

s

)

[static]

Utility function to handle strings and memory clean up.

Parameters:

s

- The referenced string

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

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