doc/python_api/examples/bpy.types.Operator.1.py

   1 """
   2 Invoke Function
   3 +++++++++++++++
   4 :class:`Operator.invoke` is used to initialize the operator from the context
   5 at the moment the operator is called.
   6 invoke() is typically used to assign properties which are then used by
   7 execute().
   8 Some operators don't have an execute() function, removing the ability to be
   9 repeated from a script or macro.
  10
  11 This example shows how to define an operator which gets mouse input to
  12 execute a function and that this operator can be invoked or executed from
  13 the python api.
  14
  15 Also notice this operator defines its own properties, these are different
  16 to typical class properties because blender registers them with the
  17 operator, to use as arguments when called, saved for operator undo/redo and
  18 automatically added into the user interface.
  19 """
  20 import bpy
  21
  22
  23 class SimpleMouseOperator(bpy.types.Operator):
  24     """ This operator shows the mouse location,
  25         this string is used for the tooltip and API docs
  26     """
  27     bl_idname = "wm.mouse_position"
  28     bl_label = "Invoke Mouse Operator"
  29
  30     x = bpy.props.IntProperty()
  31     y = bpy.props.IntProperty()
  32
  33     def execute(self, context):
  34         # rather than printing, use the report function,
  35         # this way the message appears in the header,
  36         self.report({'INFO'}, "Mouse coords are %d %d" % (self.x, self.y))
  37         return {'FINISHED'}
  38
  39     def invoke(self, context, event):
  40         self.x = event.mouse_x
  41         self.y = event.mouse_y
  42         return self.execute(context)
  43
  44 bpy.utils.register_class(SimpleMouseOperator)
  45
  46 # Test call to the newly defined operator.
  47 # Here we call the operator and invoke it, meaning that the settings are taken
  48 # from the mouse.
  49 bpy.ops.wm.mouse_position('INVOKE_DEFAULT')
  50
  51 # Another test call, this time call execute() directly with pre-defined settings.
  52 bpy.ops.wm.mouse_position('EXEC_DEFAULT', x=20, y=66)