Globals: Dynamic Monitor

Dynamic Monitor

Availability  LightWave 6.0
Component  Modeler
Header  lwdyna.h

The Modeler monitor global returns functions for initializing and displaying a progress dialog in Modeler. See also the monitor global for Layout.

Global Call

   DynaMonitorFuncs *monf;
   monf = global( LWDYNAMONITORFUNCS_GLOBAL, GFUSE_TRANSIENT );

The global function returns a pointer to a DynaMonitorFuncs.

   typedef struct st_DynaMonitorFuncs {
      LWMonitor * (*create)  (const char *, const char *);
      void        (*destroy) (LWMonitor *);
   } DynaMonitorFuncs;

mon = create( title, caption )

Create a monitor. This function returns an LWMonitor structure (described below) containing the actual progress display functions. The title text is ordinarily displayed at the top of the monitor dialog, and the caption text is displayed at the bottom. If create returns NULL, your plug-in should continue to run without reporting an error. Monitors are nice to have, but aren't essential.

destroy( mon )

Free a monitor obtained from create.

LWMonitor

The monitor structure returned by create is defined in the lwmonitor.h header file.

   typedef struct st_LWMonitor {
      void      *data;
      void     (*init) (void *, unsigned int);
      int      (*step) (void *, unsigned int);
      void     (*done) (void *);
   } LWMonitor;

data

An opaque pointer to private data. Pass this as the first argument to all of the monitor functions.

init( data, total )

Initialize the monitor. The total argument is the number of steps in the task to be monitored. It's up to you to decide what constitutes a step.

cancelled = step( data, increment )

Advance the progress display by the fraction total/increment. When the sum of the steps reaches total, the progress display will indicate to the user that the task has finished. If step returns 1, the user has requested that the task be aborted.

done( data )

Remove the progress display. This should always be called, even if the task doesn't finish.

Example

This code fragment demonstrates the use of a monitor. Macros in lwmonitor.h allow you to call the LWMonitor functions without worrying about whether the create call succeeded.

   #include <lwserver.h>
   #include <lwdyna.h>

   DynaMonitorFuncs *monf;
   LWMonitor *mon = NULL;

   monf = global( LWDYNAMONITORFUNCS_GLOBAL, GFUSE_TRANSIENT );

   if ( monf )
      mon = monf->create( "Hello", "Just fooling around" );

   MON_INIT( mon, 100 );
   for ( i = 0; i < 100; i += 2 ) {
      ...do something that takes a long time...
      if ( MON_INCR( mon, 2 )) break;
   }
   MON_DONE( mon );

   ...
   if ( monf && mon )
      monf->destroy( mon );