Navigation

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.val_int = 5
material.my_settings.val_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)
bpy.props.BoolProperty(name="", description="", default=False, options={'ANIMATABLE'}, subtype='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’, ‘ANIMATABLE’].
  • subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘NONE’].
bpy.props.BoolVectorProperty(name="", description="", default=(False, False, False), options={'ANIMATABLE'}, subtype='NONE', size=3)

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’, ‘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].
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’, ‘ANIMATABLE’].
bpy.props.EnumProperty(items, name="", description="", default="", options={'ANIMATABLE'})

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’, ‘ANIMATABLE’, ‘ENUM_FLAG’].
  • items (sequence of string triplets) – sequence of enum items formatted: [(identifier, name, description), ...] where the identifier is used for python access and other values are used for the interface.
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')

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’, ‘ANIMATABLE’].
  • subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘NONE’].
  • unit (string) – Enumerator in [‘NONE’, ‘LENGTH’, ‘AREA’, ‘VOLUME’, ‘ROTATION’, ‘TIME’, ‘VELOCITY’, ‘ACCELERATION’].
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)

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’, ‘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].
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')

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’, ‘ANIMATABLE’].
  • subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘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)

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’, ‘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].
bpy.props.PointerProperty(type="", description="", options={'ANIMATABLE'})

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’, ‘ANIMATABLE’].
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')

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’, ‘ANIMATABLE’].
  • subtype (string) – Enumerator in [‘FILE_PATH’, ‘DIR_PATH’, ‘FILENAME’, ‘NONE’].

Table Of Contents

Previous topic

Application Data (bpy.app)

Next topic

Math Types & Utilities (mathutils)

© Copyright Blender Foundation. Created using Sphinx 1.0.7.