robot_designer_plugin.core.operators module

This submodule provides the base class and decorators, and some functions for defining Blender operators that register automatically.

class robot_designer_plugin.core.operators.RDOperator

Bases: bpy.types.Operator

Base class for the operators in the RobotDesigner.

Blender operators are defined as class objects derived from bpy.types.Operator. A plugin must register these classes by calling bpy.utils.register_class() which causes blender to create a callable function out of a method (bpy.types.Operator.execute()) that accepts keyword arguments that are bound to the class’ attributes – if they are subclasses of bpy.types.Property. Note that the static method has not the same arguments and operates on its attributes. Finally, the operator is addressed to by its ID. For example:

class NewOp(bpy.types.Operator):
    bl_label = "Description" # Obligatory
    bl_idname = "plugin_name.newop" # obligatory

    test = StringProperty() # A property. It's value is passed when calling the operator.

    def execute(self, context):
        self.report({INFO}, self.text)
        return {'FINISHED'}

# ...

bpy.utils.register(NewOp)

# ...

bpy.ops.plugin_name.newop(test="Hello World)

This example show an operator that opens a window containing the message “Hello World”. While this is feasible for smaller plugins, what happens, if you have a lot of operators written, and you want to have code completion. What happens if you want to refactor the names of of the identifier or class attributes. While for the latter there is no simple solution available, the robot_designer_plugin.core provides this wrapper class with an additional run(**kwargs) method (that can—and should—be overridden to provide keyword completion). Furthermore, it provides decorators for automatically setting preconditions (that define the bpy.types.Operator.poll() method) for automatic condition checking, logging functionality and post condition checking. Together with the pluginmanager.PluginManager.register() method, this makes developing faster ( code completion, code navigation, less verbosity, …) and safer.

An examplary operator looks like this:

A template is located in <RobotDesignerDirectory>/resources/templates/operator.py (where you should insert the path to the repository) that can be used to quickly write new operators.

static OperatorLogger(func)

Decorator for the bpy.types.Operator.execute method (only for sub classes of RDOperator).

Performs logging and exception handling.

static Postconditions(*conditions)

Method decorator for the bpy.types.Operator.execute() method. Works only with operators derived RDOperator.

Checks whether post conditions are met after calling the operator. Reports an error message to the log file (see logfile)

Parameters

conditions – a number of subclasses of conditions.Condition.

static Preconditions(*conditions)

Class decorator for operators.

Registers the conditions (of type conditions.Condition) for its subclasses. They will be checked within the poll() and place_button() methods.

Parameters

conditions – a number of subclasses of conditions.Condition.

logger = <Logger Operators (INFO)>

For convenience, every the operators share a logging instance.

static pass_keywords()

Helper function that extracts the arguments of the callee (must be a (class) method) and returns them.

Credits to Kelly Yancey

classmethod place_button(layout, text=None, infoBox=None, **kwargs)

This is a convenience method that let’s the developer create a button executing the operator from the gui. The results of the poll() method (i.e., checking it’s conditions) can be optionally passed to an gui.InfoBox instance such that a report for a group of operators can be displayed (i.e., why it is not executable)

Parameters

• layout – the gui element to place the button (see bpy.types.Panel.draw())

• text – Optionally override the text in the bl_label attribute.

• infoBox – Optional instance of gui.InfoBox

• kwargs – Additional keyword arguments to bpy.types.UILayout.operator())

Returns

The operator instance (this can be used to set one of the class’s attributes)

classmethod poll(context)

The bpy.types.Operator.poll() class method is called every time, an operator is to be executed, but also when it is placed in a guy (it becomes greyed out). This method is defined in this base class and the checks are defined by a list of conditions.Condition derived classes that are given by the Preconditions() decorator. Derived classes do not need to override this method and should call the parent’s method otherwise.

Parameters

context (bpy.types.Context) – The actual Blender context.

Returns

classmethod run(**kwargs)

Enables to run an operator by calling its class object. Child classes should override this method with keywords. Then your IDE will be able to assist you The pass_keywords() function makes overriding very convenient (just copy the method’s body):

In addition, this method also does extensive error and exception handling writing everything to the log file (see logfile).

Parameters

kwargs – The keyword arguments passed to the Operator (must match the names of the class’s attributes (only of type :class:`bpy.types.Property).

Returns

The return values of bpy.types.Operator.execute().

robot_designer_plugin.core.operators.get_registered_operator(operator)

Helper function that gets the registered Blender operator based on its bl_idname tag.

Parameters

operator – A subclass of RDOperator class.

Returns

The actually callable operator function. One has to pass keyword arguments that match the name of the classes attributes.