sphinx doc gen: multiple examples possible and include the scripts docstring inline...
[blender.git] / doc / python_api / examples / bpy.types.Operator.1.py
1 """
2 Invoke Function
3 +++++++++++++++
4 This example shows how to define an operator which gets mouse input to
5 execute a function and that this operator can be invoked or executed from
6 the python api.
7
8 Also notice this operator defines its own properties, these are different
9 to typical class properties because blender registers them with the
10 operator, to use as arguments when called, saved for operator undo/redo and
11 automatically added into the user interface.
12 """
13 import bpy
14
15
16 class SimpleMouseOperator(bpy.types.Operator):
17     """This operator shows the mouse location, this string is used for the tooltip and API docs"""
18     bl_idname = "wm.mouse_position"
19     bl_label = "Invoke Mouse Operator"
20
21     x = bpy.props.IntProperty()
22     y = bpy.props.IntProperty()
23
24     def execute(self, context):
25         # rather then printing, use the report function,
26         # this way the messag appiers in the header,
27         self.report({'INFO'}, "Mouse coords are %d %d" % (self.x, self.y))
28         return {'FINISHED'}
29
30     def invoke(self, context, event):
31         self.x = event.mouse_x
32         self.y = event.mouse_y
33         return self.execute(context)
34
35 bpy.utils.register_class(SimpleMouseOperator)
36
37 # Test call to the newly defined operator.
38 # Here we call the operator and invoke it, meaning that the settings are taken
39 # from the mouse.
40 bpy.ops.wm.mouse_position('INVOKE_DEFAULT')
41
42 # Another test call, this time call execute() directly with pre-defined settings.
43 bpy.ops.wm.mouse_position('EXEC_DEFAULT', x=20, y=66)