Introduction to Joker

Joker is a nice little package of utility code that is intended to let a client application execute programs written in one of the highest-level languages I have ever encountered, HyperTalk. HyperTalk is the "scripting" language used by Apple's HyperCard application. It also has been cloned by numerous other applications, including IncWell's SuperCard, MacroMedia's Director, MetaCard corp's MetaCard and Oracle's Media Objects.

The HyperTalk language provides the following benefits:

HyperTalk is not a Macro language like AppleScript. Though it is at least as easy to use as many Macro languages, it packs more power and doesn't suffer the primitive syntax many users have had to contend with up to now. Its lack of static data typing makes HyperTalk an ideal language for the casual programmer, while its text manipulation capabilities and powerful instructions still make it a valuable asset for professional programmers.

Joker has been designed to easily allow your application to make its objects (windows, documents, etc.) controllable with Joker and to add client-defined commands that work on these or other objects. This includes adding English-like syntax and thus prevents the user from even noticing that she is dealing with a library.

Furthermore Joker is a partially interpreted language, which does away with the long wait for the program to be compiled. You can simply code and execute.


Scripts

Just like you have the source code file as the basic storage element in languages like C, a Script is the basic storage element for code in Joker.
However, to allow for maximum flexibility, a Script is not tied to any file or resource type. A Script in Joker is simply an opaque reference to a block of data, which corresponds to the plain text form of your source code.

Whenever you want to execute HyperTalk code using Joker, you need a script. You create a new script object and give it the plain text form of your code. It will then perform translation of this script and determine the names of the handlers contained in this script.

As soon as you have done this, you can begin using the code by simply invoking one of the handlers in the script.


Handlers

A Handler in Joker is conceptually the same as a subroutine in other programming languages. A Handler takes parameters, which let you pass data into a handler. In addition, each handler may have a return value.

There are two kinds of handlers:

A command message handler is used like a command ("procedure" in Pascal parlance), and the return value is usually only employed to return error information, while a function message handler is usually used like any other built-in function or value, inside expressions if desired, where its return value will be inserted after it has been called.

A message handler is identified by its name and can be called both by the client application as well as from another handler. The process of calling a message handler is usually referred to as "sending a message". Such a message can then be intercepted by the message handler, the handler can decide to abort script execution entirely, or it can simply pass (i.e. hand on) the message up the hierarchy. How this hierarchy looks and whether it exists at all is left to the client. It could be a virtual function hierarchy where the message is passed to the superclass, or it could be a messaging hierarchy where the message is passed to another instance of an object.


Values

HyperTalk insulates the user from the fact that computers internally use different data types. While this means that you can not override functions based on their data types, it allows for e.g. simply requesting the fifth character of a number. Joker will automatically perform the conversion to a string and extract the appropriate character. It also makes file i/o a lot easier, because you can simply read the string "true" and use it as a boolean right away.

This flexibility however, has to end when the client application, written in a 3rd generation language like C or Pascal, needs to pass values into Joker, or retrieve handlers' return values from Joker. To account for this, Joker has the concept of a Value.

A Value is an object whose sole purpose is to contain data of various types and to convert between them. It generally works like a union in C. You just create an instance of a Value, and store a long, double, string, point, rectangle, RGB color or array in it. You can also extract values as any of these data types from a Value, as long as they are compatible.

Generally, all values can be converted to strings and back, and longs can be converted to doubles, and in some cases doubles to longs.


Entities

To be able to "see" an object in the client application, Joker uses Entities. An entity is an object on which you can install callback functions. Whenever a script tries to manipulate such an entity, which you can associate with your application's internal representation of its objects, Joker will call your callback and tell you about this. Then, the client is responsible for actually reacting on the messages.

All entities have a couple of common characteristics:


Object Descriptors

Since Joker does not know anything about the client application's objects, there needs to be a way for the application to specify which entity goes with what object. To achieve this, special syntax (an "object descriptor") can be registered with Joker that allows specifying an object from a script. The client simply registers a callback and whenever a particular object descriptor is encountered in a script during execution, the callback will be called upon to return the appropriate Entity for whatever the user entered.


Tokenizing, parsing and execution

Whenever a script is executed, Joker needs to perform two steps to translate it from its original text form into a form that can be executed by the computer.

  1. Tokenization - During this step, Joker performs a first analysis of the stream of characters that is the text of the script. It divides it into tokens ("words"), which are simply small numbers telling apart all the identifiers in your script. Since a number takes about 2 bytes, while the text representation of a token takes 1 byte per character (e.g. 6 bytes for the "return" keyword), this speeds up the process of parsing the script, as Joker doesn't have to re-read each and every character when it wants to look ahead, and has to work with much less data.
    Before executing or parsing a script, you must _always_ first tokenize it.
  2. Parsing - This is the actual process of translating the script into something useful. Joker will go over all tokens in the script and create "instructions" for each line. This is also the step where Joker splits the script into the separate message handlers. Once a script has been parsed successfully, you can execute (or "run") any of its handlers.


Using Joker


Configuring and initializing Joker

Before you can use Joker, there is some setup work you have to do. First of all, before making your first call to any other Joker function, you must call the JokerInitialize() function, to allow Joker to set up everything. After that, you should call JokerShowSplash() to let your users know you are using Joker.

Apart from these two, you might want to call JokerSetNewline() to make sure Joker's output is formatted according to the needs of the slient application and and your console. You can also modify the behaviour of Joker using the JokerSetOption() call. Finally, you might want to reroute the "output" and '"put" without destination' commands to somewhere else than the console by specifying a JokerOuputProc. There are additional callback procedures that you may want to register at this time, as well. Finally, this is a good time to register any commands and object descriptors.


Running a script from a text file

!!! TO DO !!!

See Also:  JokerScriptRef

Entities

!!! TO DO !!!

See Also:  JokerEntityEventEnum

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:

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, JokerVTypes

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, JokerValueRef

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, JokerValueRef

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-2002 by M. Uli Kusterer, all rights reserved.