[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [34954] trunk/blender: python api docs & examples for registrable Menu/Panel/Operator/ PropertyGroup classes.
Campbell Barton
ideasman42 at gmail.com
Fri Feb 18 09:47:38 CET 2011
Revision: 34954
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=34954
Author: campbellbarton
Date: 2011-02-18 08:47:37 +0000 (Fri, 18 Feb 2011)
Log Message:
-----------
python api docs & examples for registrable Menu/Panel/Operator/PropertyGroup classes.
Modified Paths:
--------------
trunk/blender/doc/python_api/examples/bpy.types.Operator.1.py
trunk/blender/doc/python_api/examples/bpy.types.Operator.2.py
trunk/blender/doc/python_api/examples/bpy.types.Operator.py
trunk/blender/doc/python_api/sphinx_doc_gen.py
trunk/blender/release/scripts/modules/bpy_types.py
trunk/blender/release/scripts/ui/properties_material.py
Added Paths:
-----------
trunk/blender/doc/python_api/examples/bpy.ops.1.py
trunk/blender/doc/python_api/examples/bpy.ops.py
trunk/blender/doc/python_api/examples/bpy.types.Menu.1.py
trunk/blender/doc/python_api/examples/bpy.types.Menu.2.py
trunk/blender/doc/python_api/examples/bpy.types.Menu.py
trunk/blender/doc/python_api/examples/bpy.types.Operator.3.py
trunk/blender/doc/python_api/examples/bpy.types.Operator.4.py
trunk/blender/doc/python_api/examples/bpy.types.Operator.5.py
trunk/blender/doc/python_api/examples/bpy.types.Panel.1.py
trunk/blender/doc/python_api/examples/bpy.types.Panel.2.py
trunk/blender/doc/python_api/examples/bpy.types.Panel.py
trunk/blender/doc/python_api/examples/bpy.types.PropertyGroup.py
Added: trunk/blender/doc/python_api/examples/bpy.ops.1.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.ops.1.py (rev 0)
+++ trunk/blender/doc/python_api/examples/bpy.ops.1.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -0,0 +1,22 @@
+"""
+Execution Context
++++++++++++++++++
+
+When calling an operator you may want to pass the execution context.
+
+This determines the context thats given to the operator to run in, and weather
+invoke() is called or execute().
+
+'EXEC_DEFAULT' is used by default but you may want the operator to take user
+interaction with 'INVOKE_DEFAULT'.
+
+The execution context is as a non keyword, string argument in:
+('INVOKE_DEFAULT', 'INVOKE_REGION_WIN', 'INVOKE_REGION_CHANNELS',
+'INVOKE_REGION_PREVIEW', 'INVOKE_AREA', 'INVOKE_SCREEN', 'EXEC_DEFAULT',
+'EXEC_REGION_WIN', 'EXEC_REGION_CHANNELS', 'EXEC_REGION_PREVIEW', 'EXEC_AREA',
+'EXEC_SCREEN')
+"""
+
+# group add popup
+import bpy
+bpy.ops.object.group_instance_add('INVOKE_DEFAULT')
Added: trunk/blender/doc/python_api/examples/bpy.ops.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.ops.py (rev 0)
+++ trunk/blender/doc/python_api/examples/bpy.ops.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -0,0 +1,30 @@
+"""
+Calling Operators
++++++++++++++++++
+
+Provides python access to calling operators, this includes operators written in
+C, Python or Macros.
+
+Only keyword arguments can be used to pass operator properties.
+
+Operators don't have return values as you might expect, instead they return a
+set() which is made up of: {'RUNNING_MODAL', 'CANCELLED', 'FINISHED',
+'PASS_THROUGH'}.
+Common return values are {'FINISHED'} and {'CANCELLED'}.
+
+
+Calling an operator in the wrong context will raise a RuntimeError,
+there is a poll() method to avoid this problem.
+
+Note that the operator ID (bl_idname) in this example is 'mesh.subdivide',
+'bpy.ops' is just the access path for python.
+"""
+import bpy
+
+# calling an operator
+bpy.ops.mesh.subdivide(number_cuts=3, smoothness=0.5)
+
+
+# check poll() to avoid exception.
+if bpy.ops.object.mode_set.poll():
+ bpy.ops.object.mode_set(mode='EDIT')
Added: trunk/blender/doc/python_api/examples/bpy.types.Menu.1.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.Menu.1.py (rev 0)
+++ trunk/blender/doc/python_api/examples/bpy.types.Menu.1.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -0,0 +1,37 @@
+"""
+Submenus
+++++++++
+This menu demonstrates some different functions.
+"""
+import bpy
+
+
+class SubMenu(bpy.types.Menu):
+ bl_idname = "OBJECT_MT_select_submenu"
+ bl_label = "Select"
+
+ def draw(self, context):
+ layout = self.layout
+
+ layout.operator("object.select_all", text="Select/Deselect All")
+ layout.operator("object.select_inverse", text="Inverse")
+ layout.operator("object.select_random", text="Random")
+
+ # access this operator as a submenu
+ layout.operator_menu_enum("object.select_by_type", "type", text="Select All by Type...")
+
+ layout.separator()
+
+ # expand each operator option into this menu
+ layout.operator_enum("object.lamp_add", "type")
+
+ layout.separator()
+
+ # use existing memu
+ layout.menu("VIEW3D_MT_transform")
+
+
+bpy.utils.register_class(SubMenu)
+
+# test call to display immediately.
+bpy.ops.wm.call_menu(name="OBJECT_MT_select_submenu")
Added: trunk/blender/doc/python_api/examples/bpy.types.Menu.2.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.Menu.2.py (rev 0)
+++ trunk/blender/doc/python_api/examples/bpy.types.Menu.2.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -0,0 +1,16 @@
+"""
+Extending Menus
++++++++++++++++
+When creating menus for addons you can't reference menus in blenders default
+scripts.
+
+Instead the addon can add menu items to existing menus.
+
+The function menu_draw acts like Menu.draw
+"""
+import bpy
+
+def menu_draw(self, context):
+ self.layout.operator("wm.save_homefile")
+
+bpy.types.INFO_MT_file.append(menu_draw)
Added: trunk/blender/doc/python_api/examples/bpy.types.Menu.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.Menu.py (rev 0)
+++ trunk/blender/doc/python_api/examples/bpy.types.Menu.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -0,0 +1,32 @@
+"""
+Basic Menu Example
+++++++++++++++++++
+This script is a simple menu, menus differ from panels in that they must
+reference from a header, panel or another menu.
+
+Notice the 'CATEGORY_MT_name' :class:`Menu.bl_idname`, this is a naming
+convention for menus.
+
+.. note::
+
+ Menu subclasses must be registered before referencing them from blender.
+"""
+import bpy
+
+
+class BasicMenu(bpy.types.Menu):
+ bl_idname = "OBJECT_MT_select_test"
+ bl_label = "Select"
+
+ def draw(self, context):
+ layout = self.layout
+
+ layout.operator("object.select_all", text="Select/Deselect All")
+ layout.operator("object.select_inverse", text="Inverse")
+ layout.operator("object.select_random", text="Random")
+
+
+bpy.utils.register_class(BasicMenu)
+
+# test call to display immediately.
+bpy.ops.wm.call_menu(name="OBJECT_MT_select_test")
Modified: trunk/blender/doc/python_api/examples/bpy.types.Operator.1.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.Operator.1.py 2011-02-18 07:42:38 UTC (rev 34953)
+++ trunk/blender/doc/python_api/examples/bpy.types.Operator.1.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -1,6 +1,13 @@
"""
Invoke Function
+++++++++++++++
+:class:`Operator.invoke` is used to initialize the operator from the context
+at the moment the operator is called.
+invoke() is typically used to assign properties which are then used by
+execute().
+Some operators don't have an execute() function, removing the ability to be
+repeated from a script or macro.
+
This example shows how to define an operator which gets mouse input to
execute a function and that this operator can be invoked or executed from
the python api.
@@ -14,7 +21,9 @@
class SimpleMouseOperator(bpy.types.Operator):
- """This operator shows the mouse location, this string is used for the tooltip and API docs"""
+ """ This operator shows the mouse location,
+ this string is used for the tooltip and API docs
+ """
bl_idname = "wm.mouse_position"
bl_label = "Invoke Mouse Operator"
Modified: trunk/blender/doc/python_api/examples/bpy.types.Operator.2.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.Operator.2.py 2011-02-18 07:42:38 UTC (rev 34953)
+++ trunk/blender/doc/python_api/examples/bpy.types.Operator.2.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -1,7 +1,17 @@
"""
Calling a File Selector
+++++++++++++++++++++++
-This example shows how an operator can use the file selector
+This example shows how an operator can use the file selector.
+
+Notice the invoke function calls a window manager method and returns
+RUNNING_MODAL, this means the file selector stays open and the operator does not
+exit immediately after invoke finishes.
+
+The file selector runs the operator, calling :class:`Operator.execute` when the
+user confirms.
+
+The :class:`Operator.poll` function is optional, used to check if the operator
+can run.
"""
import bpy
@@ -13,9 +23,13 @@
filepath = bpy.props.StringProperty(subtype="FILE_PATH")
+ @classmethod
+ def poll(cls, context):
+ return context.object is not None
+
def execute(self, context):
file = open(self.filepath, 'w')
- file.write("Hello World")
+ file.write("Hello World " + context.object.name)
return {'FINISHED'}
def invoke(self, context, event):
Added: trunk/blender/doc/python_api/examples/bpy.types.Operator.3.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.Operator.3.py (rev 0)
+++ trunk/blender/doc/python_api/examples/bpy.types.Operator.3.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -0,0 +1,31 @@
+"""
+Dialog Box
+++++++++++
+This operator uses its :class:`Operator.invoke` function to call a popup.
+"""
+import bpy
+
+
+class DialogOperator(bpy.types.Operator):
+ bl_idname = "object.modal_operator"
+ bl_label = "Simple Modal Operator"
+
+ my_float = bpy.props.FloatProperty(name="Some Floating Point")
+ my_bool = bpy.props.BoolProperty(name="Toggle Option")
+ my_string = bpy.props.StringProperty(name="String Value")
+
+ def execute(self, context):
+ message = "Popup Values: %f, %d, '%s'" % \
+ (self.my_float, self.my_bool, self.my_string)
+ self.report({'INFO'}, message)
+ return {'FINISHED'}
+
+ def invoke(self, context, event):
+ wm = context.window_manager
+ return wm.invoke_props_dialog(self)
+
+
+bpy.utils.register_class(DialogOperator)
+
+# test call
+bpy.ops.object.modal_operator('INVOKE_DEFAULT')
Added: trunk/blender/doc/python_api/examples/bpy.types.Operator.4.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.Operator.4.py (rev 0)
+++ trunk/blender/doc/python_api/examples/bpy.types.Operator.4.py 2011-02-18 08:47:37 UTC (rev 34954)
@@ -0,0 +1,46 @@
+"""
+Custom Drawing
+++++++++++++++
+By default operator properties use an automatic user interface layout.
+If you need more control you can create your own layout with a
+:class:`Operator.draw` function.
+
+This works like the :class:`Panel` and :class:`Menu` draw functions, its used
+for dialogs and file selectors.
+"""
+import bpy
+
+
+class CustomDrawOperator(bpy.types.Operator):
+ bl_idname = "object.custom_draw"
+ bl_label = "Simple Modal Operator"
+
+ filepath = bpy.props.StringProperty(subtype="FILE_PATH")
+
+ my_float = bpy.props.FloatProperty(name="Float")
+ my_bool = bpy.props.BoolProperty(name="Toggle Option")
+ my_string = bpy.props.StringProperty(name="String Value")
+
+ def execute(self, context):
+ print()
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list