VkProgressDialog(3x)

NAME
     VkProgressDialog - A dialog manager supporting interruptible dialogs with
     a progress indicator

INHERITS FROM
     VkInterruptDialog : VkBusyDialog : VkDialogManager : VkComponent :
     VkCallbackObject

HEADER FILE
     #include <Vk/VkProgressDialog.h>

PUBLIC PROTOCOL SUMMARY
   Constructor/Destructor
           VkProgressDialog(const char* name, Boolean showCancel = TRUE);
           virtual void ~VkProgressDialog(void);


   Changing Percent Done Notification
           Boolean setPercentDone(int);


CLASS DESCRIPTION
          This class supports applications that perform lengthy, interruptible
          tasks, and wish to display progress to the user using a bar graph in
          a dialog.

          VkProgressDialog is used in nearly the same manner as
          VkInterruptDialog.  In addition to the features provided by
          VkInterruptDialog, applications may call the setPercentDone() method
          to change a graphical progress indicator in the dialog.

          By default, VkProgressDialog shows a "Cancel" button to the user to
          permit interruptible tasks.  If you do not wish to allow users to
          interrupt your task, you can prevent the "Cancel" button from
          appearing by passing FALSE as the second parameter in the
          VkProgressDialog constructor.



FUNCTION DESCRIPTIONS
   VkProgressDialog()
           VkProgressDialog(const char* name, Boolean showCancel = TRUE);


          Initialize a VkProgressDialog object. Normally, applications can use
          the globally instantiated theProgressDialog.

          The showCancel parameter determines whether or not a "Cancel" button
          is shown when the dialog is posted.  By default, the "Cancel" button
          will appear.  If you pass FALSE as the value of showCancel, the
          "Cancel" button will not appear.

          The "Cancel" button, if present, is handled in the same manner as
          that for VkInterruptDialog.

   ~VkProgressDialog()
           virtual void ~VkProgressDialog(void);


          Free the memory associated with a VkProgressDialog object.

   setPercentDone()
           void setPercentDone(int percentDone);


          Change the dialog's graphical progress indicator.  The percentDone
          parameter should be an integer between 0 and 100, where 100
          represents a fully completed task.  inclusive.

EXAMPLE
          The following code segment installs the progress dialog, and
          performs a simulated lengthy task, checking for interrupts
          periodically and updating the progress indicator.


           int i, j, k = 0;

            // Install the progress dialog as the
            // dialog to post when busy

            theApplication->setBusyDialog(theProgressDialog);

            // Start being "busy"

            theApplication->busy("Very Busy",
                                 (BusyWindow *) clientData);

            k = 0;
            int percentDone = 0;

            for (i=0; i<10000; i++)
            {
               // Every so often, see if the task
               // was interrupted

                  if(theProgressDialog->wasInterupted())
                  {
                      break;  // kick out of current
                              // task if user interrupts
                  }

                  // Update the percent done indicator.  Do this only if
                  // we've made more than a one percent increment in progress.
                  // This avoids updating the dialog more frequently than is
                  // really necessary.

                  if ((i / 100) > percentDone)
                  {
                      percentDone = i / 100;
                      theProgressDialog->setPercentDone(percentDone);
                  }

                  sleep(1);
              }

              // Task done, so we're not busy anymore

              theApplication->notBusy();

              // Restore the application's busy dialog
              // as the default

              theApplication->setBusyDialog(NULL);



INHERITED MEMBER FUNCTIONS
   Inherited from VkInterruptDialog
          wasInterrupted(), interruptedCallback


   Inherited from VkDialogManager
          show(), hide(), className(), clearCache(), prepost(), ok(),
          cancel(), apply(), setTitle(), setButtonLabels(), unpost(),
          unpostAll(), centerOnScreen(), lastPosted(), post(), postModal(),
          postBlocked(), postAndWait(), post(), _action, _showOK, _showCancel,
          _showApply, _allowMultipleDialogs, _minimizeMultipleDialogs,
          prepostCallback


   Inherited from VkComponent
          installDestroyHandler(), removeDestroyHandler(), widgetDestroyed(),
          setDefaultResources(), getResources(), manage(), unmanage(),
          baseWidget(), okToQuit(), _name, _baseWidget, _w, deleteCallback


   Inherited from VkCallbackObject
          callCallbacks(), addCallback(), removeCallback(),
          removeAllCallbacks()


VIEWKIT 2.1 CHANGES
     In multi-screen enabled applications or components, references to
     theProgressDialog will only be valid for the default screen in the
     application.  The following new function API will return the
     VkProgressDialog associated with the appropriate screen and should be
     used instead of theProgressDialog;


           VkProgressDialog *getAppProgressDialog(VkComponent *comp);


CLASSES USED BY THIS CLASS
     VkApp

SEE ALSO
     VkInterruptDialog, VkBusyDialog, VkDialogManager, VkComponent, VkApp
     ViewKit Programmer's Guide
     The X Window System, DEC Press, Bob Sheifler and Jim Gettys
     The X Window System Toolkit, DEC Press, Paul Asente and Ralph Swick
     The OSF/Motif Programmers Reference, Prentice Hall, OSF