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


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


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

This module contains functions for working with the selection buffer and edit modes
within MS-3D.

In MS-3D the Selection Buffer is all the elements that the user has
selected. Once the user has made a selection, the selection buffer will contain a
list of :c:`Element` classes (see grail.ms3d.element_) that can be
queried.

.. note:: New in version 7.00

Alternatively, you can create a new edit mode through the :f:`select_*` functions, to allow
the user to interactively select elements whilst the script is running, without the need to 
interfere with the selection buffer.

-------
Example
-------

The following example illustrates what you can do with the selectionbuffer
module. The example is taken from the :file:`em-selectionbuffer.py` script
found in the :file:`$(MEDEXE)\\scripts\\samples\\grail.ms3d.selectionbuffer`
directory.

.. Python::

    # Indicate if there is a selection or not.
    #
    if selectionbuffer.is_selection():
        print "Elements have been selected."
    else:
        print "No elements have been selected."
        print "Please select elements."
        return # Quit
    
    # Get All Elements
    #
    print "Number of selected elements: ",
    selectedElements = selectionbuffer.get_elements()
    print len(selectedElements)
    
    # The following will get a subset of "filtered" elements.
    #
    print "Number of selected MARKERS: ",
    selectedElements = selectionbuffer.get_elements([element.MarkerType])
    print len(selectedElements)

    print "Number of selected SHELLS: ",
    selectedElements = selectionbuffer.get_elements([element.ShellType])
    print len(selectedElements)

    print "Number of selected POLYLINES: ",
    selectedElements = selectionbuffer.get_elements([element.PolylineType])
    print len(selectedElements)

    print "Number of LABELS (Semi, Non, and Transform): ",
    selectedElements = selectionbuffer.get_elements(
        [element.SemiTransformLabelType,
         element.NonTransformLabelType,
         element.TransformLabelType]
        )
    print len(selectedElements)


----------
Exceptions
----------
exception :de:`SelectionBufferError`
   Class for exceptions which are specific to this module.
   

---------
Functions
---------

:df:`get_elements([filterList])`
   Returns a list of :c:`Element` classes.
   
   You can supply an optional :a:`filterList` of element types that can be used
   to get a subset of the selected elements. For example, if you are only
   interested in retrieving all Shells from the user's selected element
   list then you could do the following,
   
   .. Python::
   
     selected = selectionbuffer.get_elements([element.ShellType])
     
   The list can contain any type element type that you desire.

  
:df:`is_selection()`
   Returns :a:`1` if the user has made a selection; :a:`0` otherwise.


.. note:: The following functions are new in 7.00

:df:`select_elements(callback, filterList=None)`
   Starts an edit mode for selecting multiple elements. Once a selection has
   been made, callback is called with a list of :c:`Element`'s. If the user does
   not select anything, :d:`None` is passed instead.

   The :a:`filterList` parameter is optional. If specified, it must be an iterable
   object containing element types. The user will only be able to select
   elements of a type in the :a:`filterList`.

   Once this function has been called, it cannot be called again until the 
   user has completed the selection. If it is called before then, it will
   raise an exception.

   For example:

   .. Python::
     def foo(elements):
        print "Foo"

     def bar(elements):
        print "Bar"

     selectionbuffer.select_elements(foo)
     try:
        selectionbuffer.select_elements(bar)
     except selectionbuffer.SelectionBufferError:
        print "Oops!"

   The above code will print "Oops!" to the message window, and after
   the user makes a selection, will print "Foo" to the message window.
   The function :f:`bar` will not be called.

   If another edit mode is started, whether though one of the other
   :f:`select_*` functions in this module or other means, then the callback
   will be made with whatever is currently selected, and the edit mode
   will be terminated.

   Another example:

   .. Python::
     def foo(elements):
        print "Foo says: ", elements

     def bar(element):
        print "Bar says: ", element

     selectionbuffer.select_elements(foo)
     selectionbuffer.select_element(bar)

   If in the above code the user does not make a selection between the
   call to :f:`select_elements` and :f:`select_element`, then "Foo says: None"
   will be printed to the message window, followed by "Bar says: 
   <Element object at 0xABCDE123>" once the user selects an element.

   Also note that this edit mode will not interfere with the current
   selection buffer.


:df:`select_element(callback, filterList=None)`
   Exactly the same as :f:`select_elements`, except it starts an edit mode to
   select a single element.


:df:`select_point(callback)`
   Almost exactly the same as `select_elements`, except it starts an edit mode
   to select a single point, and does not accept a filter list.

   Point selection will honour the global snap mode.


:df:`cancel_select_elements()`
   Cancels the currently running :f:`select_elements`. 

   Calls the python callback function with :d:`None`.
   
   If there is no :f:`select_elements` function currently running, a 
   :c:`SelectionBufferError` is raised instead.


:df:`cancel_select_element()`
   Same as :f:`cancel_select_elements` except it works to cancel a call to 
   :f:`select_element`.


:df:`cancel_select_point()`
   Same as :f:`cancel_select_elements` except it works to cancel a call to
   :f:`select_point`.