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 reachestotal
, the progress display will indicate to the user that the task has finished. Ifstep
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 );