Globals: Layout Monitor

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. The histfile 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. While step is being called, Layout displays your progress to the user as a percentage of this total. The message 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. The message can also be NULL, in which case Layout may substitute a generic progress message. If step 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 included LMO_REVIEW, the monitor window remains open and control won't be returned from done until the user closes the window. Otherwise done 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 );