## Data Types

> ### JokerScriptRef

> > Reference to a Joker script. The typical sequence of creating a script is:

> > 1. JokerNewScript()
> > 2. JokerTokenizeScript()
> > 3. JokerParseScript() or JokerParseScriptAsHandler
> > 4. JokerRunHandler()
> > 5. JokerReleaseScript
> > Where tokenizing and parsing must be repeated whenever the text of a script changes.
> > You can keep around a parsed and tokenized script and run several handlers in it until you release it.

> > `typedef long* JokerScriptRef;`

> > See Also: | JokerNewScript, JokerDisposeScript

> ### JokerValueRef

> > Value to pass to Joker. This is like an Apple Event Descriptor. Create one, assign it a value, and pass it to JokerRunHandler() as a parameter. Return values are also returned this way. A JokerValueRef may contain any of the following data types:

> > - Long Integer
> > - ASCII Character String
> > - Quickdraw Point
> > - Quickdraw RGB Color
> > - Quickdraw Rectangle
> > - Double Precision Floating Point Number
> > - An Associative Array of other JokerValueRefs
> > Except for the last one, all of these can be converted into character strings, and under certain circumstances integers can be elevated to doubles or doubles reduced to integers.

> > `typedef long* JokerValueRef;`

> > See Also: | JokerNewValue, JokerDisposeValue

> ### JokerEntityRef

> > An entity is any kind of user-defined object. You can define your own kinds of entities and register them with JokerLib.
> > Every entity may have properties, contents and the user may define and set user properties for it. Associated with every entity is a JokerEntityProc which is called to do the actual work whenever a (non-user) property or the contents are accessed.

> > `typedef long* JokerEntityRef;`

> > See Also: | JokerNewEntity, JokerDisposeEntity, JokerRegisterObjectDescriptor JokerObjectDescriptorProcPtr, JokerEntityProcPtr

> ### JokerCallResult

> > Call results are returned by any handler call that you make in a script.

> > `typedef short JokerCallResult;`

> > See Also: | JokerCallResultEnum, JokerRunHandler, JokerHandlerCallProcPtr

> ### JokerCallResultEnum

> > These are the constant values a JokerCallResult may have.

> >     enum JokerCallResultEnum
> >     {
> >     	kJokerCallResultIntercepted	=	0,
> >     	kJokerCallResultPassed,
> >     	kJokerCallResultExited
> >     };

> > kJokerCallResultIntercepted | - | A handler caught this message, either by not passing it on or by calling exit .
> > kJokerCallResultPassed | - | The message wasn't caught or the handler that caught it passed it on.
> > kJokerCallResultExited | - | A handler caught this message and called "exit to top" to exit from this message.

> > See Also: | JokerCallResult, JokerRunHandler, JokerHandlerCallProcPtr

> ### JokerOptionID

> > Option IDs are what you use to activate/deactivare certain behaviour in the Interpreter.

> > `typedef unsigned short JokerOptionID;`

> > See Also: | JokerOptionIDEnum, JokerSetOption

> ### JokerOptionIDEnum

> > These are the constant values a JokerOptionID may have.

> >     enum JokerOptionIDEnum
> >     {
> >     	kJokerOptionAllowUnquotedLiterals = 0,
> >     	kJokerOptionDistinguishFcnCmd,
> >     	kJokerOptionUnqoutedLitsAsVars,
> >     	kJokerOptionEscapeCharsInStrings
> >     };

> > kJokerOptionAllowUnquotedLiterals | - | This entry is true or false to turn on/off support for unquoted string literals. Default is TRUE (HC).
> > kJokerOptionDistinguishFcnCmd | - | This entry is true or false to turn on/off distinction of message and function handlers. (HC uses TRUE here)
> > kJokerOptionUnqoutedLitsAsVars | - | True if you want unquoted literals to be created as a variable with its name in it, false if you really want them to be constants. (HC uses TRUE here)
> > kJokerOptionEscapeCharsInStrings | - | True if you want to support C-style escaped characters in strings to insert returns and quotes in strings. If this is on, returns in multi-line string tokens will be turned into spaces.

> > See Also: | JokerOptionID, JokerSetOption

> ### JokerVTypes

> > This is a bit field with bit flags for each data type JokerValueRefs support. You can use this e.g. to determine the natural type of a JokerValueRef's contents or to determine to what types they can be converted.

> > `typedef unsigned long JokerVTypes;`

> > See Also: | JokerVTypesEnum, JokerGetValueAvailableTypes

> ### JokerVTypesEnum

> > These are the constants for the bits in JokerVTypes.

> >     enum JokerVTypesEnum
> >     {
> >     	kJokerValueTypeLong			= (1 << 0),
> >     	kJokerValueTypeDouble		= (1 << 1),
> >     	kJokerValueTypeBoolean		= (1 << 2),
> >     	kJokerValueTypeText			= (1 << 3),
> >     	kJokerValueTypeReference	= (1 << 4),
> >     	kJokerValueTypePoint		= (1 << 5),
> >     	kJokerValueTypeRectangle	= (1 << 6),
> >     	kJokerValueTypeColor		= (1 << 7),
> >     	kJokerValueTypeEntity		= (1 << 8),
> >     	kJokerValueTypeArray		= (1 << 9)
> >     };

> > kJokerValueTypeLong | - | Integer.
> > kJokerValueTypeDouble | - | Floating-point number.
> > kJokerValueTypeBoolean | - | Boolean value.
> > kJokerValueTypeText | - | Text string.
> > kJokerValueTypeReference | - | For internal use only.
> > kJokerValueTypePoint | - | A coordinate on the screen.
> > kJokerValueTypeRectangle | - | A rectangle on the screen.
> > kJokerValueTypeColor | - | An RGB color value.
> > kJokerValueTypeEntity | - | A JokerEntityRef.
> > kJokerValueTypeArray | - | An array.

> > See Also: | JokerVTypes, JokerGetValueAvailableTypes

> ### JokerEntityEvent

> > This is an action selector passed to your JokerEntityProcs to tell them what action is expected from them.

> > `typedef unsigned short JokerEntityEvent;`

> > See Also: | JokerEntityEventEnum, JokerNewEntity, JokerEntityProc

> ### JokerEntityEventEnum

> > These are the constants for JokerEntityEvents. For most of these, you are supposed to return 1 on success and NULL if you didn't perform the requested action.

> >     enum JokerEntityEventEnum
> >     {
> >     	kJokerEntityGetPropEvent = 0,
> >     	kJokerEntitySetPropEvent,
> >     	kJokerEntityGetContentsEvent,
> >     	kJokerEntityDeleteEvent
> >     };

> > kJokerEntityGetPropEvent | - | Provide the value of a property. Name is in param. Set the ValueRef param2 to the value of the property.
> > kJokerEntitySetPropEvent | - | Change a property. Name is param, new value is in param2.
> > kJokerEntityGetContentsEvent | - | Return a JokerValueRef to your object's contents. You own this JokerValueRef.
> > kJokerEntityDeleteEvent | - | A script requested to delete this object. React accordingly.

> > See Also: | JokerEntityEvent, JokerNewEntity, JokerEntityProc

> ### JokerOutputProcPtr

> > `typedef pascal long (*JokerOutputProcPtr)( char* data, long amount );`

> > Whenever a script outputs something to the console, this function is called.

> > data | - | A pointer to the text to write.
> > amount | - | The number of bytes in the pointer to write.
> > result | - | This function returns the amount of data actually written, or -1 when an error occurred.

> > See Also: | JokerSetOutputProc

> ### JokerHandlerCallProcPtr

> > `typedef pascal JokerCallResult (*JokerHandlerCallProcPtr)( Str255 handlerName, JokerValueRef result, Boolean isFcn, long paramCount, va_list args );`

> > Whenever a handler can't be found in a script that you call using JokerRunHandler(), this callback is executed.

> > handlerName | - | The name of the handler that was called.
> > result | - | This is where you can store the result value you wish to return in response to this handler.
> > isFcn | - | TRUE if this is a function handler, FALSE if it is a command handler. If Joker is set not to distinguish between function and command messages, the value of this is undefined.
> > paramCount | - | The number of parameters passed to the handler.
> > args | - | A va_list on which va_start() has already been called. This list contains paramCount JokerValueRefs that hold the parameters passed to the handler.

> > See Also: | JokerSetHandlerCallProc, JokerCallResult, JokerCallResultEnum

> ### JokerSpendTimeProcPtr

> > `typedef pascal void (*JokerSpendTimeProcPtr)();`

> > This is called between lines when running a handler.

> > You can use this to allow the user to switch to another application while a script is running.

> > See Also: | JokerSetSpendTimeProc

> ### JokerClientCmdProcPtr

> > `typedef pascal void (*JokerClientCmdProcPtr)( long paramCount, JokerValueRef params[] );`

> > Whenever a client command you registered using JokerRegisterClientCmd() is called by the user, this function is called to handle the command.

> > paramCount | - | The number of parameters passed to the command.
> > params | - | An array containing a JokerValueRef with the value for each parameter. You mustn't dispose of these values or assign a value to them.

> > See Also: | JokerRegisterClientCmd

> ### JokerEntityProcPtr

> > `typedef pascal JokerValueRef (*JokerEntityProcPtr)( JokerEntityRef target, JokerEntityEvent event, JokerValueRef param, JokerValueRef param2 );`

> > Whenever a user-defined object is manipulated, this proc is called.

> > target | - | The object that was targeted.
> > event | - | The action requested.
> > param | - | A parameter, depending on the value of event.
> > param2 | - | A second parameter.

> > See Also: | JokerRegisterObjectDescriptor, JokerEntityRef JokerEntityEvent, JokerEntityEventEnum

> ### JokerObjectDescriptorProcPtr

> > `typedef pascal JokerEntityRef (*JokerObjectDescriptorProcPtr)( long paramCount, JokerValueRef params[] );`

> > Whenever a user-defined object descriptor is used, this function is called to return the appropriate object.

> > paramCount | - | Number of parameters passed.
> > params | - | Array with parameters.
> > result | - | Return a JokerEntityRef here, or NULL on error.

> > See Also: | JokerRegisterObjectDescriptor, JokerEntityRef

## Initialization and Global State

> Calls that manipulate Joker globally instead of per-instance.

> ### JokerInitialize

> > `JOKER_EXT void JokerInitialize();`

> > Initialize Joker's internal global data structures.

> > Call this before making any other calls to Joker-related APIs.

> > See Also: | JokerShowSplash

> ### JokerShowSplash

> > `JOKER_EXT void JokerShowSplash();`

> > Show Joker's splash screen.

> > If you haven't paid for Joker, you are required to call this function after initializing Joker using JokerInitialize(), or before your application quits. It will display a little splash screen telling the user that your product uses JokerLib.

> ### JokerSetNewlineCharacter

> > `JOKER_EXT void JokerSetNewlineCharacter( char n );`

> > Specify the default character to use for line breaks.

> > The constant "newline" represents the character to use for line breaks on the current platform. Depending on whether your application compiles under MPW or CodeWarrior, or whether you are deploying for the web or for the screen, you can specify the character to use for line breaks. This is also the character used when returning lists e.g. of the keys of an array.

> > n | - | The character to use for line breaks by default.

> ### JokerSetOption

> > `JOKER_EXT void JokerSetOption( JokerOptionID x, Boolean state );`

> > Turn on/off one of Joker's options.

> > Joker supports a number of options that control its behavior in certain situations, e.g. regarding treatment of unquoted string literals. These pertain to all scripts and must be set at startup, before parsing any scripts.

> > x | - | The ID representing the option to set.
> > state | - | TRUE to activate the behavior, FALSE to deactivate it.

> ### JokerSetOutputProc

> > `JOKER_EXT void JokerSetOutputProc( JokerOutputProcPtr p );`

> > Specify a callback function to handle console output.

> > Whenever the user requests data to be output to the console, either by using "put" without a destination or by assigning a value to standardOutput, the JokerOutputProc is called to display this value however you see fit.

> > p | - | A pointer to a JokerOutputProc to call.

> > See Also: | JokerOutputProcPtr

> ### JokerSetHandlerCallProc

> > `JOKER_EXT void JokerSetHandlerCallProc( JokerHandlerCallProcPtr p );`

> > Specify a callback function to be called when a message was not intercepted.

> > Whenever you send a message using JokerRunHandler() and the message is not intercepted by the user at all or the user passes the message after handling it, the HandlerCallProc is called to give you the opportunity of handling the message.

> > p | - | A pointer to a JokerHandlerCallProc to call.

> > See Also: | JokerHandlerCallProcPtr

> ### JokerSetSpendTimeProc

> > `JOKER_EXT void JokerSetSpendTimeProc( JokerSpendTimeProcPtr p );`

> > Specify a callback function to be called between lines.

> > After each line Joker executes during a call to JokerRunHandler(), the JokerSpendTimeProc is called. You can use this procedure to drive running animations or movies, give idle time to other programs etc.

> > p | - | A pointer to a JokerSpendTimeProc to call.

> > See Also: | JokerSpendTimeProcPtr

> ### JokerRegisterClientCmd

> > `JOKER_EXT void JokerRegisterClientCmd( long paramCount, StringPtr inIdentifiers[], Boolean hasDirectArg, JokerClientCmdProcPtr p );`

> > Register a custom command.

> > Whenever a custom command is called by a script, the JokerClientCmdProc is called with the parameters in an array.
> > Currently, Joker has a limit of five parameters per client command. Also, you may only declare one command with the same name.

> > paramCount | - | Number of parameters to the command, not including the direct argument.
> > inIdentifiers | - | inIdentifiers[0] contains the name of the command. Any additional entries contain the labels for the corresponding indirect parameters. If any of those entries is NULL or an empty string, it is assumed that the parameter has no label. Labels and command names may only consist of one word. Joker makes a copy of the data in this array, you needn't keep it around after this call has returned.
> > hasDirectArg | - | TRUE if you want to have a direct argument, FALSE if you want the command to start immediately with the first argument's label.
> > p | - | The callback function to call whenever this command is invoked.

> > See Also: | JokerClientCmdProcPtr

> ### JokerRegisterObjectDescriptor

> > `JOKER_EXT void JokerRegisterObjectDescriptor( long paramCount, StringPtr inIdentifiers[], Boolean hasDirectArg, JokerObjectDescriptorProcPtr proc );`

> > Register syntax for referring to your user-defined objects.

> > Whenever a script encounters an object descriptor in a script which you registered using this function, it calls the object descriptor proc you specified for this type. This proc is then responsible for returning the JokerEntityRef associated with that object. The paramCount and inIdentifiers and hasDirectArg parameters behave the same as for client commands.

> > paramCount | - | Number of parameters to the command, not including the direct argument.
> > inIdentifiers | - | inIdentifiers[0] contains the name of the object kind. Any additional entries contain the labels for the corresponding indirect parameters. If any of those entries is NULL or an empty string, it is assumed that the parameter has no label. Labels and command names may only consist of one word. Joker makes a copy of the data in this array, you needn't keep it around after this call has returned.
> > hasDirectArg | - | TRUE if you want to have a direct argument, FALSE if you want the object descriptor to start immediately with the first argument's label.

> > See Also: | JokerObjectDescriptorProcPtr, JokerEntityRef

> ### JokerGetErrorString

> > `JOKER_EXT Boolean JokerGetErrorString( StringPtr str );`

> > Returns an error string, or an empty string if no error occurred.

> > str | - | This Pascal string is set to the error message, or to an empty string if there was no error. This may be NULL if you're not interested in the error string but want to determine solely whether an error occurred.
> > result | - | TRUE if there was an error, FALSE if not.

## Manipulating Scripts

> ### JokerNewScript

> > `JOKER_EXT JokerScriptRef JokerNewScript();`

> > Create a new script reference.

> > This calls JokerRetainScript() on the new script once. Balance this call with one to JokerReleaseScript() when you are done using it.

> > result | - | A reference to a newly created script.

> > See Also: | JokerReleaseScript, JokerRetainScript

> ### JokerRetainScript

> > `JOKER_EXT void JokerRetainScript( JokerScriptRef s );`

> > Increase the reference count of a script.

> > Scripts in Joker are reference-counted, this means that you can have several places of your code sharing a script without having to worry about one disposing of it and pulling the rug from under another place's feet. Every call to JokerRetainScript() must be balanced with a call to JokerReleaseScript(). As long as you are still retaining a script it can't be disposed of. When the last to retain releases a script, it will be disposed of. Since JokerRunHandler() also retains the scripts it runs, you can not dispose of a running script by accident.

> > s | - | The script to retain.

> > See Also: | JokerReleaseScript

> ### JokerReleaseScript

> > `JOKER_EXT void JokerReleaseScript( JokerScriptRef s );`

> > Decrease the reference count of a script, releasing it if the refcount hits zero.

> > s | - | The script to release. The JokerScriptRef may not be valid anymore after calling this.

> > See Also: | JokerRetainScript

> ### JokerTokenizeScript

> > `JOKER_EXT void JokerTokenizeScript( JokerScriptRef s, const char* data, long length );`

> > Assign the text of a script to a JokerScriptRef and prepare it for parsing.

> > You must tokenize a script using this call before you can parse it. You can call JokerTokenizeScript() a second time on a script to assign it new text, but then you must also re-parse it.
> > You do not need to keep around the script text after tokenizing it, Joker makes a copy for internal use.

> > s | - | The script to assign the text to. You must have created this JokerScriptRef using JokerNewScript().
> > data | - | A pointer to the script text.
> > length | - | The size in bytes of the data in data.

> ### JokerParseScript

> > `JOKER_EXT void JokerParseScript( JokerScriptRef s );`

> > Parse the list of tokens in a script.

> > Parsing a script converts the list of tokens into a list of instructions. This is not unlike compiling a script, just that Joker generates more high-level instructions, not machine code. You must parse a script using this call or using JokerParseScriptAsHandler() before you can run any handlers inside it.

> > s | - | The script containing the tokens to parse. The script must have been tokenized already.

> > See Also: | JokerParseScriptAsHandler

> ### JokerParseScriptAsHandler

> > `JOKER_EXT void JokerParseScriptAsHandler( JokerScriptRef s, Str255 handlerName, Boolean isFcn );`

> > Parse the list of tokens in a script as if they were a handler with the specified name.

> > The text that was tokenized must be a raw list of commands, they mustn't contain any "on"/"function" lines or their corresponding "end" lines.
> > This call will currently only work if Joker is set up not to distinguish between function and command message handlers.

> > s | - | The script containing the tokens to parse. The script must have been tokenized already.
> > handlerName | - | The name of the handler to generate.
> > isFcn | - | TRUE if you want to generate a function, FALSE if you want a command. This parameter is currently ignored.

> > See Also: | JokerParseScript

> ### JokerRunHandler

> > `JOKER_EXT JokerCallResult JokerRunHandler( JokerScriptRef s, Str255 handlerName, Boolean isFcn, JokerValueRef returnValue, long paramCount, ... );`

> > Run a function or command message handler in a JokerScriptRef.

> > A script may consist of a number of procedures and functions (command and function message handlers). This function looks up a function by name and runs it. While a script is running, this call increses its reference count so you can't accidentally dispose the running script.

> > s | - | The script containing the handler to run. You must already have tokenized and parsed the script.
> > handlerName | - | The name of the handler to call. Case is not important.
> > isFcn | - | TRUE if the message handler to call is a function, FALSE if it is a command. This parameter is ignored if Joker is set up not to distinguish between commands and functions.
> > returnValue | - | A JokerValueRef created using JokerNewValue(). This value will be set to the return value of the handler.
> > paramCount | - | The number of parameters to follow.
> > ... | - | paramCount parameters, each a JokerValueRef containing the values to pass as parameters to the handler.
> > result | - | A constantindicating whether the handler intercepted the message, exited to top or passed it.

> > See Also: | JokerCallResult, JokerCallResultEnum

## Manipulating JokerEntityRefs

> ### JokerNewEntity

> > `JOKER_EXT JokerEntityRef JokerNewEntity( JokerEntityProcPtr p );`

> > Create a new JokerEntityRef.

> > Create a JokerEntityRef for each object which you want to be controllable from a script. Note that these objects will automatically keep track of any user properties that are defined for them.

> > result | - | A new JokerEntityRef. You are responsible for disposing of this. Whenever a script refers to this object and your JokerObjectDescriptorProc returns this JokerEntityRef, the associated JokerEntityProc is called.

> > See Also: | JokerDisposeEntity, JokerEntityRef

> ### JokerDisposeEntity

> > `JOKER_EXT void JokerDisposeEntity( JokerEntityRef jer );`

> > Get rid of a JokerEntityRef created using JokerNewEntity().

> > jer | - | The JokerEntityRef you want to dispose of. This JokerEntityRef is no longer valid after this call.

> > See Also: | JokerNewEntity, JokerEntityRef

> ### JokerGetEntityRefCon

> > `JOKER_EXT long JokerGetEntityRefCon( JokerEntityRef jer );`

> > Return the refCon of a JokerEntityRef.

> > The refCon is a long that you may freely use for whatever purpose you can think of. Usually a refCon is used to keep a pointer to the actual object that this JokerEntityRef is associated with.

> > jer | - | The JokerEntityRef whose RefCon you want to get.

> > See Also: | JokerSetEntityRefCon, JokerNewEntity, JokerDisposeEntity, JokerEntityRef

> ### JokerSetEntityRefCon

> > `JOKER_EXT void JokerSetEntityRefCon( JokerEntityRef jer, long value );`

> > Change the refCon of a JokerEntityRef.

> > The refCon is a long that you may freely use for whatever purpose you can think of. Usually a refCon is used to keep a pointer to the actual object that this JokerEntityRef is associated with.

> > jer | - | The JokerEntityRef whose RefCon you want to change.

> > See Also: | JokerGetEntityRefCon, JokerNewEntity, JokerDisposeEntity, JokerEntityRef

> ### JokerGetEntityPropertyArray

> > `JOKER_EXT JokerValueRef JokerGetEntityPropertyArray( JokerEntityRef jer );`

> > Create an array with the property names as indexes and the property values as array element values.

> > jer | - | The object whose properties you are interested in.
> > result | - | A value containing an array. You dispose of this.

> > See Also: | JokerGetEntityPropertyNameArray, JokerSetEntityPropertyArray

> ### JokerGetEntityPropertyNameArray

> > `JOKER_EXT JokerValueRef JokerGetEntityPropertyNameArray( JokerEntityRef jer );`

> > Create an array containing the property names. The indexes are integers from 1 to the number of properties.

> > jer | - | The object whose properties you are interested in.
> > result | - | A value containing an array. You need to dispose of this.

> > See Also: | JokerGetEntityPropertyArray, JokerSetEntityPropertyArray

> ### JokerSetEntityPropertyArray

> > `JOKER_EXT void JokerSetEntityPropertyArray( JokerEntityRef jer, JokerValueRef v );`

> > Set the user properties of an entity to be the values of an array.

> > The array indexes are used as property names and the values of the array elements are used as property values.

> > jer | - | The object whose user properties you want to change.
> > v | - | An array with [property name] = elements, as it is returned by JokerGetEntityPropertyArray.

> > See Also: | JokerGetEntityPropertyArray

## Manipulating JokerValueRefs

> ### JokerNewValue

> > `JOKER_EXT JokerValueRef JokerNewValue();`

> > Create a new JokerValueRef.

> > result | - | A new JokerValueRef. You are responsible for disposing of this. You can assign a value to this JokerValueRef using any of the calls below.

> > See Also: | JokerDisposeValue, JokerValueRef

> ### JokerCopyValue

> > `JOKER_EXT JokerValueRef JokerCopyValue( JokerValueRef v );`

> > Create a copy of a JokerValueRef.

> > v | - | The JokerValueRef to copy.
> > result | - | A JokerValueRef to a copy of v. You are responsible for disposing of this.

> > See Also: | JokerCopyValue, JokerValueRef

> ### JokerDisposeValue

> > `JOKER_EXT void JokerDisposeValue( JokerValueRef v );`

> > Dispose of a JokerValueRef when you're done using it.

> > After you have called this, the JokerValueRef is no longer valid.
> > If the value passed in v contains an array, its array elements are automatically disposed of by this.
> > Do not call this function on any parameters you receive in any of the callback functions, or on any array elements you obtain using JokerFetchValueElement().

> > v | - | The JokerValueRef to get rid of.

> > See Also: | JokerNewValue, JokerFetchValueElement, JokerValueRef

> ### JokerGetValueAvailableTypes

> > `JOKER_EXT JokerVTypes JokerGetValueAvailableTypes( JokerValueRef v );`

> > Retrieve information on what data types are available in a value.

> > Use this to determine whether the value you are dealing with supports the data type you need.

> > v | - | The JokerValueRef to get information on.
> > result | - | A bit field with constants from the JokerVTypesEnum indicating available types.

> > See Also: | JokerVTypes, JokerVTypesEnum, JokerValueRef

## Assigning Values to JokerValueRefs

> ### JokerSetValueLong

> > `JOKER_EXT void JokerSetValueLong( JokerValueRef v, long n );`

> > Set the value of the specified JokerValueRef to a signed long integer.

> > v | - | The JokerValueRef to which to assign the value.
> > n | - | The value to assign to the JokerValueRef.

> ### JokerSetValueDouble

> > `JOKER_EXT void JokerSetValueDouble( JokerValueRef v, double n );`

> > Set the value of the specified JokerValueRef to a double.

> > v | - | The JokerValueRef to which to assign the value.
> > n | - | The value to assign to the JokerValueRef.

> ### JokerSetValueString

> > `JOKER_EXT void JokerSetValueString( JokerValueRef v, Str255 str );`

> > Set the value of the specified JokerValueRef to some text read from a Pascal string.

> > v | - | The JokerValueRef to which to assign the value.
> > str | - | A Pascal string with a length byte containing the text to copy to the JokerValueRef.

> ### JokerSetValueChars

> > `JOKER_EXT void JokerSetValueChars( JokerValueRef v, char* data, long length );`

> > Set the value of the specified JokerValueRef to some text read from a char*.

> > v | - | The JokerValueRef to which to assign the value.
> > data | - | A pointer to the data to copy to the value.
> > length | - | The number of bytes to copy from data to the JokerValueRef.

> ### JokerSetValuePoint

> > `JOKER_EXT void JokerSetValuePoint( JokerValueRef v, const Point pos );`

> > Set the value of the specified JokerValueRef to a Point.

> > v | - | The JokerValueRef to which to assign the value.
> > pos | - | The value to assign.

> ### JokerSetValueColor

> > `JOKER_EXT void JokerSetValueColor( JokerValueRef v, const RGBColor* col );`

> > Set the value of the specified JokerValueRef to an RGBColor.

> > v | - | The JokerValueRef to which to assign the value.
> > col | - | The value to assign.

> ### JokerSetValueRect

> > `JOKER_EXT void JokerSetValueRect( JokerValueRef v, const Rect* box );`

> > Set the value of the specified JokerValueRef to a rectangle.

> > v | - | The JokerValueRef to which to assign the value.
> > box | - | The value to assign.

## Arrays in JokerValueRefs

> ### JokerFetchValueElement

> > `JOKER_EXT JokerValueRef JokerFetchValueElement( JokerValueRef v, Str255 index );`

> > This returns a reference to a value with the specified index in the specified value's array. If there is no such element yet, a new one is created. You get the actual element, modifying it modifies the array.

> > Every value can be an associative array, the indices are strings. However, a value can only either directly contain a value, or it can contain array elements. It may not contain both. If you assign one, the other is cleared.

> > v | - | The JokerValueRef from which to get the element.
> > index | - | The array index of the element you want to get/create.
> > result | - | The JokerValueRef to the element requested. Do not dispose of this JokerValueRef, or you'll damage the array it belongs to.

> ### JokerCountValueElements

> > `JOKER_EXT long JokerCountValueElements( JokerValueRef v );`

> > Returns the number of elements in a JokerValueRef's array.

> > v | - | The JokerValueRef of which to count the elements.
> > result | - | The number of elements in the array.

## Retrieving Values from JokerValueRefs

> ### JokerGetValueLong

> > `JOKER_EXT long JokerGetValueLong( JokerValueRef v );`

> > Retrieve the value of the specified JokerValueRef as a signed long integer.

> > v | - | The JokerValueRef from which to get the value.
> > result | - | The value retrieved.

> ### JokerGetValueDouble

> > `JOKER_EXT double JokerGetValueDouble( JokerValueRef v );`

> > Retrieve the value of the specified JokerValueRef as a double.

> > v | - | The JokerValueRef from which to get the value.
> > result | - | The value retrieved.

> ### JokerGetValueString

> > `JOKER_EXT void JokerGetValueString( JokerValueRef v, Str255 str );`

> > Retrieve the value of the specified JokerValueRef as a Pascal String with a length byte.

> > v | - | The JokerValueRef from which to get the value.
> > str | - | The value retrieved is assigned to the memory pointed to by this StringPtr.

> ### JokerGetValueChars

> > `JOKER_EXT long JokerGetValueChars( JokerValueRef v, char* data, long maxLen );`

> > Retrieve the value of the specified JokerValueRef as a stream of characters.

> > v | - | The JokerValueRef from which to get the value.
> > data | - | The value retrieved is assigned to the memory pointed to by this char*.
> > maxLen | - | The size of the buffer pointed to by data. This call will at most return maxLen bytes of data.
> > result | - | The number of characters still left after returning maxLen data. If this is a negative number, add it to maxLen to find out how much data was returned.

> ### JokerGetValuePoint

> > `JOKER_EXT void JokerGetValuePoint( JokerValueRef v, Point* pos );`

> > Retrieve the value of the specified JokerValueRef as a Point.

> > v | - | The JokerValueRef from which to get the value.
> > pos | - | The value retrieved is assigned to the memory pointed to by this Point*.

> ### JokerGetValueColor

> > `JOKER_EXT void JokerGetValueColor( JokerValueRef v, RGBColor* col );`

> > Retrieve the value of the specified JokerValueRef as a RGBColor.

> > v | - | The JokerValueRef from which to get the value.
> > col | - | The value retrieved is assigned to the memory pointed to by this RGBColor*.

> ### JokerGetValueRect

> > `JOKER_EXT void JokerGetValueRect( JokerValueRef v, Rect* box );`

> > Retrieve the value of the specified JokerValueRef as a rectangle.

> > v | - | The JokerValueRef from which to get the value.
> > box | - | The value retrieved is assigned to the memory pointed to by this Rect*.

(c) Copyright 2001 by M. Uli Kusterer, all rights reserved.