This is ExportedVariable.rtf in view mode; [Download] [Up]
intuitiv'3d API documentation Copyright ©1993 by Cub'x SystÜmes. All Rights Reserved.
Exported Variables
Exported Variables is a function package that has been designed to speed-up the realization of archiving methods and, for future use, to allow a class to simply export instance variable that are consistent. A class that needs to use exported variable has to provide a method ( - exportedVariable: , - exportedVariableFor: ) that returns a data representation which describes instance variable names and types.
A function called inside the - read or - write method implementation of an abstract super-class then asks the caller its exported variable and performs the read or write operations.
A class only has to describe its own instance variable, not the instance variables inherited from its super-class. The Exported Variable package uses the Objective-C run-time functions to read the inheritance tree and asks each class that provides the exportation method for exported variable .
Types and constants used to describe instance variables
Variables types are described using the following constants:
Constant: Objective C / Renderman / Appkit Type
EV_FLOAT float
EV_DOUBLE double
EV_CHAR char
EV_UCHAR unsigned char
EV_SHORT short
EV_LONG long
EV_INT int
EV_UINT unsigned int
EV_BOOL BOOL
EV_OBJECT id
EV_3DPOINT float[3]
EV_NXCOLOR NXColor
EV_NULL specify the end of the exported variable array.
The ExportedVariable type describes an instance variable:
typedef struct _ExportedVariable
{
char *variableName;
char *variableType;
unsigned long variableLength;
} ExportedVariable;
variableName a constant string that contains the name of the instance variable.
variableType a EV_xxx constant according to the type of the variable or EV_NULL if this is the end of the exported variable array.
variableLength contains the number of element inside your instance variable. If your variable is not an array, you can initialize this field with 0 or 1. Otherwise, you should initialize variableLength with the number of element in your array.
Methods that should be implemented to describe instance variables.
If you want to export your own instance variable, you have to provide one of the following methods. If your subclass doesn't add any new instance variable, you don't have to do anything.
exportedVariable
+ (ExportedVariable*) exportedVariable
This method returns the instance variable description of the receiving class. A typical implementation is done using a static auto-initialized array of ExportedVariable:
+ (ExportedVariable*) exportedVariable
{
static ExportedVariable ev[] = {
{"MyVar1", EV_FLOAT, 1 },
{"MyVar2",EV_BOOL, 1 },
{NULL,EV_NULL, 0}};
return ev;
}
exportedVariableFor:
+ (ExportedVariable*) exportedVariableFor: (long) classVersion
This method is the same than - exportedVariable but gives you a chance to return a different version of exported variable according to the class version. Exported Variable functions first attempts to call the + exportedVariable method and then attempts to call + exportedVariableFor: method. Here is a typical implementation of the + exportedVariableFor: method:
+ (ExportedVariable*) exportedVariableFor:(long) classVersion
{
switch( classVersion )
{
case 0:
return ev_version_0;
case 1:
return ev_version_1;
...
}
}
Functions to use the Exported Variable package.
Inside intuitiv'3d you rarely have to use theses functions directly since they are called in all abstract super-classes (CX3DObject / CX3DNode / CX3DShader ). Nevertheless, if you have to make new classes that don't inherit from an intuitiv'3d's abstract super-class, you are encouraged to use the Exported Variable package.
evReadVariableForObject
SUMMARY Read from an NXTypedStream the exported variable of an object.
DECLARED IN i3d/ExportedVariable.h
SYNOPSIS
void evReadVariableForObject(NXTypedStream *s,id obj)
DESCRIPTION This function asks all classes of obj for the exported variables , reads from the streams variable's values and then initialize the instance obj. You can call this function inside the - read: implementation of your class. Here is a typical implementation of the - read: method:
- read:(NXTypedStream*)s
{
[super read:s];
evReadVariableForObject(s,self);
return self;
}
evWriteVariableForObject
SUMMARY Write to an NXTypedStream the exported variable of an object.
DECLARED IN i3d/ExportedVariable.h
SYNOPSIS
void evWriteVariableForObject(NXTypedStream *s,id obj)
DESCRIPTION This function ask all classes of obj for the exported variable and then writes to the stream s variable's values. You can call this function inside the - write: implementation of your class. Here is a typical implementation of the - write: method:
- write:(NXTypedStream*)s
{
[super write:s];
evWriteVariableForObject(s,self);
return self;
}
Important note
Although Exported Variable supported types includes most of the types used, there are cases where you cannot use exported variable for all instance variables. For example, exported variables do not support strings or complex data representations. In this case, you can export variables that are exportable and overload - read: and - write: methods in order to save un-exported variables.These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.