addcallback

objs.addcallback(target: ENSOBJ | str, obj: Any, method: str, userdata: Any | None = None, attrs: List[int] = [], flags: int = 0) → int

Set up a Python callback that will be executed when the selected conditions are met.

Note: this method should only be used in EnSight Python scripts. For PyEnSight scripts, use: pyensight.Session.add_callback() instead.

This function will register a callback on the target. The target can either be an EnSight ENSOBJ object or the name of a class (e.g. “ENS_PART”). A Python function of the form:

class obj:
    def method(self, target: "ENSOBJ", attribute: int, userdata: Any) -> int:
        return 0

will be called whenever an attribute of the target object/class changes. The object whose attribute changed will be passed to the callback as target. The actual attribute that changed is passed to the callback as the attribute parameter. By default, the callback is made for all attributes, but a restricted list of attributes can be provided by the attrs keyword. If a value is specified via the userdata keyword, it will passed to the callback as well. The return value of the callback controls if the callback will be made again in the future. If any value other than 0 is returned, the callback is removed from the queue and will not be called again.

Args:

target:

The ENSOBJ instance or the string name of the ENSOBJ subclass that the callback should respond to attribute changes on.

obj:

The Python object that has the named callback method.

method:

The string name of the method on obj that should be called when the attribute change conditions are met.

userdata:

An optional object that will be passed to the callback. Often used as a differentiator when the same method is register for multiple target/attribute tuples.

attrs:

The list of attribute IDs. If there is a change in any of the attributes on the target object, then the callback will be executed.

flags:

ensight.objs.EVENTMAP_FLAG_IMMEDIATE causes the callback to be called immediately instead of being queued up for later when EnSight is idle. Use this flag with caution, it can be very expensive and can lead to recursion issues. ensight.objs.EVENTMAP_FLAG_COMP_LOCAL causes multiple consecutive instances of this callback in the deferred event queue to be consolidated into a single event. ensight.objs.EVENTMAP_FLAG_COMP_GLOBAL performs the same consolidation, but allows for discontinuous instances of the callback to be collapsed to the last callback instance.

Returns:

The registered callback id on success or -1 if the callback could not be registered.