Cleanup: API docs
[blender.git] / doc / python_api / examples / bpy.types.Operator.5.py
1 """
2 Modal Execution
3 +++++++++++++++
4
5 This operator defines a :class:`Operator.modal` function which running,
6 handling events until it returns ``{'FINISHED'}`` or ``{'CANCELLED'}``.
7
8 Grab, Rotate, Scale and Fly-Mode are examples of modal operators.
9 They are especially useful for interactive tools,
10 your operator can have its own state where keys toggle options as the operator
11 runs.
12
13 :class:`Operator.invoke` is used to initialize the operator as being by
14 returning ``{'RUNNING_MODAL'}``, initializing the modal loop.
15
16 Notice ``__init__()`` and ``__del__()`` are declared.
17 For other operator types they are not useful but for modal operators they will
18 be called before the :class:`Operator.invoke` and after the operator finishes.
19 """
20 import bpy
21
22
23 class ModalOperator(bpy.types.Operator):
24     bl_idname = "object.modal_operator"
25     bl_label = "Simple Modal Operator"
26
27     def __init__(self):
28         print("Start")
29
30     def __del__(self):
31         print("End")
32
33     def execute(self, context):
34         context.object.location.x = self.value / 100.0
35         return {'FINISHED'}
36
37     def modal(self, context, event):
38         if event.type == 'MOUSEMOVE':  # Apply
39             self.value = event.mouse_x
40             self.execute(context)
41         elif event.type == 'LEFTMOUSE':  # Confirm
42             return {'FINISHED'}
43         elif event.type in {'RIGHTMOUSE', 'ESC'}:  # Cancel
44             context.object.location.x = self.init_loc_x
45             return {'CANCELLED'}
46
47         return {'RUNNING_MODAL'}
48
49     def invoke(self, context, event):
50         self.init_loc_x = context.object.location.x
51         self.value = event.mouse_x
52         self.execute(context)
53
54         context.window_manager.modal_handler_add(self)
55         return {'RUNNING_MODAL'}
56
57
58 bpy.utils.register_class(ModalOperator)
59
60 # test call
61 bpy.ops.object.modal_operator('INVOKE_DEFAULT')