Property Definitions (bpy.props)¶

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.

Assigning to Existing Classes¶

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

Operator Example¶

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')

PropertyGroup Example¶

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"

Collection Example¶

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)

Update Example¶

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")>

bpy.props.BoolProperty(name="", description="", default=False, options={'ANIMATABLE'}, subtype='NONE', update=None)¶

Returns a new boolean property definition.

Parameters:

name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].
subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘NONE’].
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

bpy.props.BoolVectorProperty(name="", description="", default=(False, False, False), options={'ANIMATABLE'}, subtype='NONE', size=3, update=None)¶

Returns a new vector boolean property definition.

Parameters:

name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
default (sequence) – sequence of booleans the length of size.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].
subtype (string) – Enumerator in [‘COLOR’, ‘TRANSLATION’, ‘DIRECTION’, ‘VELOCITY’, ‘ACCELERATION’, ‘MATRIX’, ‘EULER’, ‘QUATERNION’, ‘AXISANGLE’, ‘XYZ’, ‘COLOR_GAMMA’, ‘LAYER’, ‘NONE’].
size (int) – Vector dimensions in [1, and 32].
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

bpy.props.CollectionProperty(items, type="", description="", default="", options={'ANIMATABLE'})¶

Returns a new collection property definition.

Parameters:	type (class) – A subclass of `bpy.types.PropertyGroup`. name (string) – Name used in the user interface. description (string) – Text used for the tooltip and api documentation. options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].

bpy.props.EnumProperty(items, name="", description="", default="", options={'ANIMATABLE'}, update=None)¶

Returns a new enumerator property definition.

Parameters:

name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
default (string or set) – The default value for this enum, A string when ENUM_FLAG is disabled otherwise a set which may only contain string identifiers used in items.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘ENUM_FLAG’].
items (sequence of string triplets or a function) – sequence of enum items formatted: [(identifier, name, description), ...] where the identifier is used for python access and other values are used for the interface. For dynamic values a callback can be passed which returns a list in the same format as the static list. This function must take 2 arguments (self, context)
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

bpy.props.FloatProperty(name="", description="", default=0.0, min=sys.float_info.min, max=sys.float_info.max, soft_min=sys.float_info.min, soft_max=sys.float_info.max, step=3, precision=2, options={'ANIMATABLE'}, subtype='NONE', unit='NONE', update=None)¶

Returns a new float property definition.

Parameters:

name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].
subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘NONE’].
unit (string) – Enumerator in [‘NONE’, ‘LENGTH’, ‘AREA’, ‘VOLUME’, ‘ROTATION’, ‘TIME’, ‘VELOCITY’, ‘ACCELERATION’].
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

bpy.props.FloatVectorProperty(name="", description="", default=(0.0, 0.0, 0.0), min=sys.float_info.min, max=sys.float_info.max, soft_min=sys.float_info.min, soft_max=sys.float_info.max, step=3, precision=2, options={'ANIMATABLE'}, subtype='NONE', size=3, update=None)¶

Returns a new vector float property definition.

Parameters:

name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
default (sequence) – sequence of floats the length of size.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].
subtype (string) – Enumerator in [‘COLOR’, ‘TRANSLATION’, ‘DIRECTION’, ‘VELOCITY’, ‘ACCELERATION’, ‘MATRIX’, ‘EULER’, ‘QUATERNION’, ‘AXISANGLE’, ‘XYZ’, ‘COLOR_GAMMA’, ‘LAYER’, ‘NONE’].
size (int) – Vector dimensions in [1, and 32].
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

bpy.props.IntProperty(name="", description="", default=0, min=-sys.maxint, max=sys.maxint, soft_min=-sys.maxint, soft_max=sys.maxint, step=1, options={'ANIMATABLE'}, subtype='NONE', update=None)¶

Returns a new int property definition.

Parameters:

name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].
subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘NONE’].
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

bpy.props.IntVectorProperty(name="", description="", default=(0, 0, 0), min=-sys.maxint, max=sys.maxint, soft_min=-sys.maxint, soft_max=sys.maxint, options={'ANIMATABLE'}, subtype='NONE', size=3, update=None)¶

Returns a new vector int property definition.

Parameters:

name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
default (sequence) – sequence of ints the length of size.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].
subtype (string) – Enumerator in [‘COLOR’, ‘TRANSLATION’, ‘DIRECTION’, ‘VELOCITY’, ‘ACCELERATION’, ‘MATRIX’, ‘EULER’, ‘QUATERNION’, ‘AXISANGLE’, ‘XYZ’, ‘COLOR_GAMMA’, ‘LAYER’, ‘NONE’].
size (int) – Vector dimensions in [1, and 32].
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

bpy.props.PointerProperty(type="", description="", options={'ANIMATABLE'}, update=None)¶

Returns a new pointer property definition.

Parameters:

type (class) – A subclass of bpy.types.PropertyGroup.
name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

bpy.props.RemoveProperty(attr)¶

Removes a dynamically defined property.

Parameters:	attr (string) – Property name.

bpy.props.StringProperty(name="", description="", default="", maxlen=0, options={'ANIMATABLE'}, subtype='NONE', update=None)¶

Returns a new string property definition.

Parameters:

name (string) – Name used in the user interface.
description (string) – Text used for the tooltip and api documentation.
options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’].
subtype (string) – Enumerator in [‘FILE_PATH’, ‘DIR_PATH’, ‘FILENAME’, ‘NONE’].
update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None.

Property Definitions (bpy.props)¶

Assigning to Existing Classes¶

Operator Example¶

PropertyGroup Example¶

Collection Example¶

Update Example¶

Table Of Contents

Previous topic

Next topic

Navigation

Property Definitions (bpy.props)¶

Assigning to Existing Classes¶

Operator Example¶

PropertyGroup Example¶

Collection Example¶

Update Example¶

Table Of Contents

Previous topic

Next topic

Quick search