MasterHandler
Availability LightWave 6.0
Component Layout
Header lwmaster.h
Masters can issue commands like generics, but unlike
generics, masters can respond to the user's changes to a scene as the scene is being
composed. Masters are handlers, so they have persistent instances that can be saved in
scene files. Masters can be used to record a sequence of commands for scripting or as a
central point of control for a suite of handler plug-ins.
Activation Function
XCALL_( int ) MyMaster( long version, GlobalFunc *global,
LWMasterHandler *local, void *serverData );
The local argument to a master's activation function is an LWMasterHandler.
typedef struct st_LWMasterHandler {
LWInstanceFuncs *inst;
LWItemFuncs *item;
int type;
double (*event) (LWInstance, const LWMasterAccess *);
unsigned int (*flags) (LWInstance);
} LWMasterHandler;
The first two members of this structure point to standard handler
functions. In addition to these, a master handler provides a type code, an event
function and a flags function.
- type
- This can be one of the following.
LWMAST_SCENE
- LWMAST_OBJECTS
- LWMAST_EFFECTS
LWMAST_LAYOUT
The SCENE type is the most common. OBJECTS and EFFECTS types
are reserved for future enhancement of the class. LAYOUT masters are like SCENE
masters, but they survive scene clearing and can therefore be used to automate scene
management.
- val = event( instance, access )
- The event function is called to notify the handler that something has happened.
Information about the event is included in the access structure, described below. The
handler can respond to the event by issuing commands through functions provided in the
access structure. The return value is currently ignored and should be set to 0.
f = flags( instance )
- Returns flag bits combined using bitwise-or. No flags are currently defined, so this
function should simply return 0.
Interface Activation Function
XCALL_( int ) MyInterface( long version, GlobalFunc *global,
LWInterface *local, void *serverData );
This is the standard interface activation for
handlers.
Master Access
This is the structure passed to the handler's event function.
typedef struct st_LWMasterAccess {
int eventCode;
void *eventData;
void *data;
LWCommandCode (*lookup) (void *, const char *cmdName);
int (*execute) (void *, LWCommandCode cmd, int argc,
const DynaValue *argv,
DynaValue *result);
int (*evaluate) (void *, const char *command);
} LWMasterAccess;
- eventCode
eventData
- The type of event and its associated data. The event can be one of the following.
LWEVNT_NOTHING
- Not currently used.
- LWEVNT_COMMAND
- A user action corresponding to a command. The eventData
is a string containing the command and its arguments, written in the same format used by
the evaluate function to issue commands.
- LWEVNT_TIME
- Sent whenever the frame slider is moved, which includes playing the scene, but not
playing back a preview. This allows masters to remain synchronized in time with the Layout
interface.
- LWEVNT_SELECT
- Sent when the item selection has changed.
data
- An opaque pointer to data used internally by Layout. Pass this as the first argument to
the lookup, execute and evaluate functions.
cmdcode = lookup( data, cmdname )
- Returns an integer code corresponding to the command name. The command is issued by
passing the command code to the execute function. Command codes are constant for
a given Layout session, so this only needs to be called once per command, after which the
codes can be cached and used multiple times.
result = execute( data, cmdcode, argc, argv, cmdresult )
- Issue the command given by the command code argument. argv is an array of DynaValue arguments. argc is the number of arguments in
the argv array. The result of the command is written in cmdresult. The
function returns 1 if it succeeds or 0 if it does not.
result = evaluate( data, cmdstring )
- Issue the command with the name and arguments in the command string. This is an
alternative to using lookup and execute. The command and its arguments
are written to a single string and delimited by spaces. The function returns 1 if it
succeeds or 0 if it does not.
See the Commands pages for a complete list of the
commands that can be issued in Layout, as well as a detailed explanation of the formatting
of command arguments for both the execute and evaluate methods.
History
The LWEVNT_SELECT event code was added in LightWave 7.0.
Example
The macro sample is a master that records a sequence
of commands and saves it as an LScript. |