This module defines properties to extend blenders internal data, the result of these functions is used to assign properties to classes registered with blender and can’t be used directly. .. warning:: All parameters to these functions must be passed as keywords.
Custom properties can be added to any subclass of an ID, Bone and PoseBone.
These properties can be animated, accessed by the user interface and python like blenders existing properties.
import bpy
# Assign a custom property to an existing type.
bpy.types.Material.custom_float = bpy.props.FloatProperty(name="Test Prob")
# Test the property is there.
bpy.data.materials[0].custom_float = 5.0
A common use of custom properties is for python based Operator classes.
import bpy
class DialogOperator(bpy.types.Operator):
bl_idname = "object.dialog_operator"
bl_label = "Property Example"
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):
print("Dialog Runs")
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.dialog_operator('INVOKE_DEFAULT')
PropertyGroups can be used for collecting custom settings into one value to avoid many indervidual settings mixed in together.
import bpy
class MaterialSettings(bpy.types.PropertyGroup):
my_int = bpy.props.IntProperty()
my_float = bpy.props.FloatProperty()
my_string = bpy.props.StringProperty()
bpy.utils.register_class(MaterialSettings)
bpy.types.Material.my_settings = \
bpy.props.PointerProperty(type=MaterialSettings)
# test the new settings work
material = bpy.data.materials[0]
material.my_settings.my_int = 5
material.my_settings.my_float = 3.0
material.my_settings.my_string = "Foo"
Custom properties can be added to any subclass of an ID, Bone and PoseBone.
import bpy
# Assign a collection
class SceneSettingItem(bpy.types.PropertyGroup):
name = bpy.props.StringProperty(name="Test Prop", default="Unknown")
value = bpy.props.IntProperty(name="Test Prop", default=22)
bpy.utils.register_class(SceneSettingItem)
bpy.types.Scene.my_settings = \
bpy.props.CollectionProperty(type=SceneSettingItem)
# Assume an armature object selected
print("Adding 3 values!")
my_item = bpy.context.scene.my_settings.add()
my_item.name = "Spam"
my_item.value = 1000
my_item = bpy.context.scene.my_settings.add()
my_item.name = "Eggs"
my_item.value = 30
for my_item in bpy.context.scene.my_settings:
print(my_item.name, my_item.value)
It can be useful to perform an action when a property is changed and can be used to update other properties or synchronize with external data.
All properties define update functions except for CollectionProperty.
import bpy
def update_func(self, context):
print("my test function", self)
bpy.types.Scene.testprop = bpy.props.FloatProperty(update=update_func)
bpy.context.scene.testprop = 11.0
# >>> my test function <bpy_struct, Scene("Scene")>
Get/Set functions can be used for boolean, int, float, string and enum properties. If these callbacks are defined the property will not be stored in the ID properties automatically, instead the get/set functions will be called when the property is read or written from the API.
import bpy
# Simple property reading/writing from ID properties.
# This is what the RNA would do internally.
def get_float(self):
return self["testprop"]
def set_float(self, value):
self["testprop"] = value
bpy.types.Scene.test_float = bpy.props.FloatProperty(get=get_float, set=set_float)
# Read-only string property, returns the current date
def get_date(self):
import datetime
return str(datetime.datetime.now())
bpy.types.Scene.test_date = bpy.props.StringProperty(get=get_date)
# Boolean array. Set function stores a single boolean value, returned as the second component.
# Array getters must return a list or tuple
# Array size must match the property vector size exactly
def get_array(self):
return (True, self["somebool"])
def set_array(self, values):
self["somebool"] = values[0] and values[1]
bpy.types.Scene.test_array = bpy.props.BoolVectorProperty(size=2, get=get_array, set=set_array)
# Enum property.
# Note: the getter/setter callback must use integer identifiers!
test_items = [
("RED", "Red", "", 1),
("GREEN", "Red", "", 2),
("BLUE", "Red", "", 3),
("YELLOW", "Red", "", 4),
]
def get_enum(self):
import random
return random.randint(1, 4)
def set_enum(self, value):
print("setting value", value)
bpy.types.Scene.test_enum = bpy.props.EnumProperty(items=test_items, get=get_enum, set=set_enum)
# Testing
scene = bpy.context.scene
scene.test_float = 12.34
print(scene.test_float)
scene.test_array = (True, False)
print([x for x in scene.test_array])
#scene.test_date = "blah" # this would fail, property is read-only
print(scene.test_date)
scene.test_enum = 'BLUE'
print(scene.test_enum)
# >>> 12.34000015258789
# >>> [True, False]
# >>> 2013-01-05 16:33:52.135340
# >>> setting value 3
# >>> GREEN
Returns a new boolean property definition.
| Parameters: |
|
|---|
Returns a new vector boolean property definition.
| Parameters: |
|
|---|
Returns a new collection property definition.
| Parameters: |
|
|---|
Returns a new enumerator property definition.
| Parameters: |
|
|---|
Returns a new float property definition.
| Parameters: |
|
|---|
Returns a new vector float property definition.
| Parameters: |
|
|---|
Returns a new int property definition.
| Parameters: |
|
|---|
Returns a new vector int property definition.
| Parameters: |
|
|---|
Returns a new pointer property definition.
| Parameters: |
|
|---|
Removes a dynamically defined property.
| Parameters: |
|
|---|
Note
Typically this function doesn’t need to be accessed directly. Instead use del cls.attr
Returns a new string property definition.
| Parameters: |
|
|---|