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 Element classes (see grail.ms3d.element) that can be queried.

Alternatively, you can create a new edit mode through the 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 em-selectionbuffer.py script found in the $(MEDEXE)\scripts\samples\grail.ms3d.selectionbuffer directory.

Exceptions

exception SelectionBufferError

Class for exceptions which are specific to this module.

Functions

get_elements([filterList])

Returns a list of Element classes.

You can supply an optional 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,

selected = selectionbuffer.get_elements([element.ShellType])

The list can contain any type element type that you desire.

is_selection()

Returns 1 if the user has made a selection; 0 otherwise.

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 Element's. If the user does not select anything, None is passed instead.

The 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 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:

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 bar will not be called.

If another edit mode is started, whether though one of the other 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:

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 select_elements and 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.

select_element(callback, filterList=None)

Exactly the same as select_elements, except it starts an edit mode to select a single element.

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.

cancel_select_elements()

Cancels the currently running select_elements.

Calls the python callback function with None.

If there is no select_elements function currently running, a SelectionBufferError is raised instead.

cancel_select_element()

Same as cancel_select_elements except it works to cancel a call to select_element.

cancel_select_point()

Same as cancel_select_elements except it works to cancel a call to select_point.