Package org.jetbrains.mps.openapi.util

Interface ProgressMonitor

  • public interface ProgressMonitor
    This interface is implemented by activity progress monitors. The methods of this interface are invoked by the monitored activities themselves. Activities can be viewed as a linear sequence of tasks and sub-tasks. The start() method should be called when a task begins, indicating the total amount of work expected. Subsequently, the advance() method should be called to report a progress that should be reflected in the monitor. By calling the step() method, the activity can give a visible textual label to the currently performed action. The subtask() method allows the activity to break a larger task into smaller chunks, while the progress reported by the subtask is nicely integrated into the outer task's progress monitor. The subtask() method returns a new ProgressMonitor instance that should be handed over into the sub-task so it could report its progress. Calling any method on the outer monitor, while its sub-task is active, detaches the sub-task monitor, considers the sub-task complete and ignores its further potential progress. Good practice: Calling advance(0) on the outer monitor after the sub-task finishes is a safe way to ensure the sub-task's progress is reported into the progress dialog even when the sub-task's implementation doesn't use the sub-task's ProgressMonitor instance that you passed in. A request to cancel an operation is signaled through the cancel() method. Activities should poll the monitor's isCanceled() method periodically and abort once they detect cancellation. When the task completes, the done() method should be called, perhaps from a finally block. 
       monitor.start("build", 100);
   try {
     monitor.step("check out from VCS");
     //doWork
     monitor.advance(10);
     if (monitor.isCanceled()) return;

     monitor.step("compile");
     //doWork
     monitor.advance(30);
     if (monitor.isCanceled()) return;

     ProgressMonitor sm = monitor.subtask(60);
     runTests(sm);
     monitor.advance(0);  //Just in case the runTests() method did not use sm correctly

   } finally {
     monitor.done()
   }
    After calling done(), the progress monitor cannot be reused. The API methods typically accept ProgressMonitor as their last argument and they can safely assume it is never null. It is a bad strategy to share a single instance of ProgressMonitor with sub-tasks or other tasks. A method is supposed to either use the supplied ProgressMonitor directly and exclusively or pass it on to the real activity down the stack, but never both. Never pass the monitor you are using. Always create a sub-monitor for sub-tasks. Use the EmptyProgressMonitor class to provide an all-ignoring implementation (aka NullObjectPattern). Use the ProgressMonitorAdapter class to wrap an existing progress monitor (IDEA, Eclipse). Custom implementations of ProgressMonitor are not supposed to be thread-safe. Tip for changing the header in the progress dialog 
       monitor.subTask(0, REPLACING).start("New header text", 0)
    Technically, this trick will create and start a zero-work sub-task that replaces the main header in the progress dialog. The header stays on until you call any method on 'monitor'. evgeny, 4/22/13

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void advance​(int work)
      Advance by the given number of work items.
      void cancel()  
      void done()
      Completes the monitoring
      boolean isCanceled()  
      void start​(String taskName, int totalWork)
      Starts monitoring, can only be called once.
      void step​(String title)
      Indicates a new step to mention in the progress dialog
      ProgressMonitor subTask​(int work)
      Creates a monitor for a sub-task, which, when accomplished, will complete the given number of work items of the current monitor.
      ProgressMonitor subTask​(int work, SubProgressKind kind)
      Creates a monitor for a sub-task, which, when accomplished, will complete the given number of work items of the current monitor.

    • Method Detail

      • start

        void start​(@NotNull
           String taskName,
           int totalWork)
        Starts monitoring, can only be called once.
        Parameters:
        taskName - The text to display in the progress dialog header, must not be null, can be an empty string, e.g. to keep the amount of text in the progress dialog low
        totalWork - The amount of work items to finish before completion, can be 0, in which case no advances are possible

      • advance

        void advance​(int work)
        Advance by the given number of work items.
        Parameters:
        work - The number of work items accomplished, 0 is allowed and can be used as a way to complete an unfinished sub-task's monitor

      • step

        void step​(String title)
        Indicates a new step to mention in the progress dialog
        Parameters:
        title - The text to show in the progress dialog

      • done

        void done()
        Completes the monitoring

      • isCanceled

        boolean isCanceled()

      • cancel

        void cancel()

      • subTask

        ProgressMonitor subTask​(int work)
        Creates a monitor for a sub-task, which, when accomplished, will complete the given number of work items of the current monitor. At most one sub-task can be active for a given task at any moment.
        Parameters:
        work - The number of work items to advance the current monitor when the sub-task completes
        Returns:
        The progress monitor for the sub-task.

      • subTask

        ProgressMonitor subTask​(int work,
                        SubProgressKind kind)
        Creates a monitor for a sub-task, which, when accomplished, will complete the given number of work items of the current monitor. At most one sub-task can be active for a given task at any moment.
        Parameters:
        work - The number of work items to advance the current monitor when the sub-task completes
        kind - Specifies whether and how textual information from the sub-task's monitor will be propagated onto the progress dialog
        Returns:
        The progress monitor for the sub-task.