MasterHandler
MasterInterface

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