===================================
``grail.ms3d.progressmeter`` Module
===================================
.. include:: ../../version.h
.. include:: ref.h



.. contents:: Table of Contents
   :backlinks: top



--------
Overview
-------- 

This module provides you with ability to control the MineSightŪ 3D
progress meter. This is useful for giving the user an indication that a
long process may active within your script.  

-----
Usage
-----

The progress meter module defines a :c:`ProgressMeter` object that
controls access to the MineSightŪ 3D progress meter.  The progress meter
generally follows these three steps.

  1. Start the progress meter with your number of updates.
  2. Update the progress meter to a new percentage completed.
  3. Stop the progress meter to notify MineSightŪ 3D to clean up the and
     stop displaying the progress meter.

As an example, consider incrementing the progress meter as you calculate
the area of all polygons selected by the user (see the
:file:`%MEDEXE%/scripts/samples/grail.ms3d.elementop/em-calculate-area.py` script for
details).

.. Python::

   def compute_area(el):
           """Helper function computes areas."""
           if el.get_type() == element.PolygonType:
               return elementop.calc_area(el)
           else:
               return 0.0

   def areas():
       """Example of using the progressmeter."""
       if not selectionbuffer.is_selection():
           mssys.stderr.write("No selection!\n")
           return # quit        
       
       elementList = selectionbuffer.get_elements()
       numElements = len(elementList)
       
       # Start up the progress meter...
       pm = progressmeter.ProgressMeter()
       pm.start(numElements)
       
       for elementIdx in xrange(numElements):
           el = elementList[elementIdx]
           area = compute_area(el)
           mssys.stdout.write("%d: %.2f\n" % (elementIdx+1, area))
               
           # In this case we just indicate the new incremental value.    
           pm.increment(elementIdx)

           # In this case we have to specify the percentage in the range
           # 0.0 to 1.0 .
           # percent = float(elementIdx)/float(numElements)
           # pm.percent(percent)

       pm.stop()
     
In this case we use the :f:`increment` method, and supply the
progressmeter with the next index (i.e. the next iteration). We could
have just as easily computed the percentage completed, and supplied that
value via the :f:`percent` method.
     
If another process is holding onto the progress meter, the :f:`start()`
call will return 0.        

-------------------
ProgressMeter Class
-------------------

class :dc:`ProgressMeter()`
  Defines an object that provides access to the MineSightŪ 3D progress meter.

  :df:`start(count)`:
      Starts the progress meter with the given :a:`count`.
      This call will return 0 if the progress meter object can not
      start because another process is holding onto it.

  :df:`increment(step)`:
      Increments the progress meter to the new :a:`step` value. 
     
      For example if your progress meter was specified with 10
      iterations, and you set the :a:`step` to 1, the progress meter in
      MineSightŪ 3D would display 10%.

      This method is useful when you are iterating through a set of
      objects.

  :df:`percent(fractionalPercent)`:
      Takes a :a:`fractionalPercent` ranging from 0 to 1.0 and displays
      it as an integer percent ranging from 0% to 100% on the
      MineSightŪ 3D progress meter.
      
      In this case you have to compute the percentage value that you
      want displayed in the MineSightŪ 3D progress meter bar.

  :df:`update(percent)`:
      Update the progress meter with the new integer :a:`percent` value.
      You need to compute the new percentage value, and it must be
      between 0 and 100%. 

      .. Warning::
         DEPRECATED (as of MineSightŪ Grail v3.50-05)

         Prefer to use either the :f:`percent` or :f:`increment`
         function calls instead. There was a lot of misunderstanding on
         how to use this method in the past. This function call is
         equivalent to calling the :f:`percent` method and dividing your
         value by :d:`100.0`.

  :df:`stop()`:
      Stops the progress meter.