Layout Monitor
Availability LightWave 7.0 | Component Layout | Header lwmonitor.h
The Layout monitor global returns functions for initializing and displaying a progress dialog in Layout. This is primarily for showing the progress of lengthy or complex operations in non-handler plug-in classes. Filters and file importer classes have their own monitor mechanisms. See also the monitor global for Modeler.
Global Call
LWLMonFuncs *lmonf; lmonf = global( LWLMONFUNCS_GLOBAL, GFUSE_TRANSIENT );
The global function returns a pointer to an LWLMonFuncs.
typedef struct st_LWLMonFuncs { LWLMonID (*create) (void); void (*setup) (LWLMonID, char *title, unsigned int flags, const char *histfile); void (*setwinpos)(LWLMonID, int x, int y, int w, int h); void (*init) (LWLMonID, unsigned int total, const char *); int (*step) (LWLMonID, unsigned int incr, const char *); void (*done) (LWLMonID); void (*destroy) (LWLMonID); } LWLMonFuncs;
mon = create()
- Create a new monitor instance. The monitor returned by
create
is passed as the first argument to the other monitor functions. setup( mon, title, flags, histfile )
- Configure the monitor. The
title
string is the title of the monitor window. Thehistfile
is the filename of a history file where messages displayed to the user will also be written. This can be NULL if you don't want a history file. The flags can be any of the following combined using bitwise-or.LMO_NOABORT
- By default, the user can inform you that your operation should be stopped. This flag disables the Abort button.
LMO_REVIEW
- If this is set, the monitor window remains open after you call
done
. This allows the user to review the messages displayed during the operation. LMO_HISTAPPEND
- By default, the history file is overwritten each time
init
is called. This flag causes new message strings to be appended to the file instead. LMO_IMMUPD
- Enables immediate update of the monitor on every step. The default is to delay updates to avoid incurring too much overhead for rapid step events.
setwinpos( mon, x, y, w, h )
- Set the position and size of the monitor window. The dimensions are in pixels. If you don't call this, Layout will select defaults for you.
init( mon, total, message )
- Open the monitor window. The
total
is the number of steps in the operation. Whilestep
is being called, Layout displays your progress to the user as a percentage of this total. Themessage
is the first string displayed to the user. abort = step( mon, increment, message )
- Advance the progress display by the fraction
total/increment
. When the sum of the steps reaches the total, the progress display will indicate to the user that the task has finished. An increment of 0 is valid and can be used to change the message without changing the progress indication. Themessage
can also be NULL, in which case Layout may substitute a generic progress message. Ifstep
returns 1, the user has requested that the task be aborted. done( mon )
- Tell the monitor that the task has been completed. If the flags passed to
setup
includedLMO_REVIEW
, the monitor window remains open and control won't be returned fromdone
until the user closes the window. Otherwisedone
closes the window and control returns immediately. destroy( mon )
- Free the monitor instance and resources allocated by
create
. If it's open, the monitor window will be closed.
Example
This code fragment creates and displays a monitor in Layout. Displaying progress to the user is helpful but not essential, so in most cases failure in some part of the monitor processing shouldn't cause your plug-in to fail.
#include <lwserver.h> #include <lwgeneric.h> #include <lwmonitor.h> #include <time.h> LWLMonFuncs *monf; LWLMonID mon; int i, total, step; /* get the global and a monitor */ monf = global( LWLMONFUNCS_GLOBAL, GFUSE_TRANSIENT ); if ( monf ) { mon = monf->create(); if ( mon ) monf->setup( mon, "Just Testing", LMO_REVIEW, NULL ); } ... /* perform a lengthy task */ if ( monf && mon ) monf->init( mon, total, "Starting..." ); for ( i = 0; i < total; i += step ) { ...do something... if ( monf && mon ) if ( monf->step( mon, step, NULL )) { monf->step( mon, 0, "Aborted!" ); break; } } if ( monf && mon ) monf->done( mon ); ... /* no longer need the monitor */ if ( monf && mon ) monf->destroy( mon );