Blender Addons




GUI and Properties Discussion

Blend File

Introduction
This tutorial surveys the different kinds of custom properties. It covers the relationship between properties and the GUI. You'll see in this discussion how a property type determines the kind of panel widget you get. This survey should be a handy guide for making GUI interfaces and operators for your scripts.

Word of warning: Don't bother copying the snippets sprinkled throughout this lesson. These snippets are examples only. For a full working example to copy, use the script at the end of this lesson. That having been said, let us begin.

Simple Single Value Properties
The simplest kind of property holds only a single value. This could be an integer, float, string, or boolean value.

String properties in the panel are represented by a text field. Integers and floating point values, on the other hand, have sliders. These sliders can be set to default values and can have useful constraints for putting a limit on the range of possible values a property should be allowed to have.

Boolean properties are represented by checkboxes and can also have defaults set. The setting of the property is intuitive. Checked means true and unchecked sets the property to false. 

scnType = bpy.types.Scene # saves typing

StringProperty = bpy.props.StringProperty
FloatProperty = bpy.props.FloatProperty
IntProperty = bpy.props.IntProperty
BoolProperty = bpy.props.BoolProperty

# single value properties.
scnType.my_string_prop = StringProperty(  name="Example String", 
					default="hello", 
					description = "An example string property")
scnType.my_float_prop = FloatProperty( name = "Example Float", 
				      default = .5, min = 0, max=1,
				      description = "An example float property" )
scnType.my_int_prop = IntProperty( name = "Example Int", 
				 default = 5, min = 0, max = 10, 
				 description = "An example integer" )
scnType.my_bool_prop = BoolProperty( name="Example Bool", 
				   description = "This is a boolean", 
			           default=True )


Single Value Properties
Single Value Property Widgets



Vector Properties
Vectors are represented as triplets. Typically, triplets set x, y, and z coordinate values. This makes sense for determining certain coordinate related values in 3D space.

Float and Integer vectors behave similiarly to single value properties. The only difference is that things are set in terms of triples. Likewise, where a single value property can only have 1 default, vectors have exactly 3. Also, just like single value properties, you can have range limits put on them. 

# vector based properties( commonly used to refer to some 3D sense of a thing )

BoolVectorProperty = bpy.props.BoolVectorProperty
IntVectorProperty = bpy.props.IntVectorProperty
FloatVectorProperty = bpy.props.FloatVectorProperty

scnType.my_bool_vector = BoolVectorProperty(  name = "Example Bool Vector", 
					   description = "Bool Vector Description",
                                           default = (  True, False, True) )
                                                            
scnType.my_int_vector = IntVectorProperty(  name = "Example Int Vector", 
					 description = "Int Vector Description",
                                         default = (  2,5,7), min = 0, max=10)

scnType.my_float_vector = FloatVectorProperty( name = "Example float vector", 
					     description = "Float Vector Description",
                                             default = (  3.2, 5.6, 1.0 ), 
					     min = 0, max = 7 )


Vector Value Properties
Vector Value Property Widgets




List Properties
An EnumProperty is for lists of string based data. In a property panel, it shows up as a drop down list. Functionally, it's somewhat similiar to drop down lists in html. Every entry in the list is based on triples. The values in those triples are for value, caption, and description respectively. 

# triplet setup.... ( return value, name, description )
animaniacs = [  ( "Yaco1", "Yaco", "Yaco Warner Desc" ), 
	   ( "Wacko2", "Wacko", "Wacko Warner Desc" ),
	  ( "Dot3", "Dot", "Dot Warner Desc" )]
enumProp = bpy.props.EnumProperty( name = "Cartoon Characters", 
				items = animaniacs, 
				description = "Choose a character" )

scnType.dropDownProp = enumProp


List Value Property
List Value Property Widget



Conclusions
This look into the relationship between property widgets and properties in Blender will help you build good panels for your scripts. Here is the code listing for this discussion. 

"""
Type Samples - A Collection of types set up to be displayed in the 
object properties panel
Hit alt-p to run this.
Go to object properties and scroll to the bottom to view.
"""
import bpy
 
class TypeSamplerPanel(bpy.types.Panel):
    bl_label = "Type Samples"
    bl_space_type = "PROPERTIES"
    bl_region_type = "WINDOW"
    bl_context = "object"
 
    def draw(self, context):
        scn = bpy.context.scene
        layout = self.layout
        row = layout.row()
        col = row.column()
 
        col.prop( scn, "my_string_prop" )      
        col.prop( scn, "my_float_prop" )    
        col.prop( scn, "my_int_prop" )     
        col.prop( scn, "my_bool_prop" )   
        col.prop( scn, "my_bool_vector" )    
        col.prop( scn, "my_int_vector" )
        col.prop( scn, "my_float_vector" )
        col.prop( scn, "dropDownProp" )
 
        col.operator( "bpt.sample_op" )
 
 
class SampleOperator(bpy.types.Operator):
 
    bl_idname = "bpt.sample_op"
    bl_label = "Sample Button Caption"
 
    def invoke(self, context, event ):
        self.report( "INFO", "I PUSHED THE BUTTON" )
        return {'FINISHED'}
 
 
def register():
    bpy.utils.register_class( TypeSamplerPanel )
    bpy.utils.register_class( SampleOperator )


def unregister():
    bpy.utils.register_class( TypeSamplerPanel )
    bpy.utils.register_class( SampleOperator )


if __name__ == "__main__":
    register()
 
if __name__ == '__main__':
    scnType = bpy.types.Scene
    # single value properties.
    StringProperty = bpy.props.StringProperty
    FloatProperty = bpy.props.FloatProperty
    IntProperty = bpy.props.IntProperty
    BoolProperty = bpy.props.BoolProperty
    
    scnType.my_string_prop = StringProperty(  name="Example String", 
                                            default="hello", 
                                description = "String Property Desc")
                                
    scnType.my_float_prop = FloatProperty( name = "Example Float", 
                                      default = .5, min = 0, max=1,
                                    description = "Float Prop Desc" )
                                    
    scnType.my_int_prop = IntProperty( name = "Example Int", 
                                       default = 5, min = 0, max = 10, 
                                    description = "Int Prop Desc" )
                                    
    scnType.my_bool_prop = BoolProperty( name="Example Bool", 
                                         description = "Bool Prop Desc", 
                                         default=True )
 
 
    # vector based properties
    # ( commonly used to refer to some 3D sense of a thing )
    BoolVectorProperty = bpy.props.BoolVectorProperty
    IntVectorProperty = bpy.props.IntVectorProperty
    FloatVectorProperty = bpy.props.FloatVectorProperty
    
    scnType.my_bool_vector = BoolVectorProperty(  name = "Example Bool Vector", 
                                              description = "Bool Vector Desc",
                                               default = (  True, False, True) )
 
    scnType.my_int_vector = IntVectorProperty(  name = "Example Int Vector", 
                                             description = "Int Vector Desc",
                                                default = (  2,5,7), 
                                                min = 0, max=10)
 
    scnType.my_float_vector = FloatVectorProperty( name = "Example float vector", 
                                               description = "Float Vector Desc",
                                               default = (  3.2, 5.6, 1.0 ), 
                                               min = 0, max = 7 )
 
    # triplet setup.... ( return value, name, description )
    EnumProperty = bpy.props.EnumProperty
    animaniacs = [  ( "Yaco1", "Yaco", "Yaco Warner Desc" ), 
           ( "Wacko2", "Wacko", "Wacko Warner Desc" ),
          ( "Dot3", "Dot", "Dot Warner Desc" )]
    enumProp = EnumProperty( name = "Cartoon Characters", items = animaniacs, 
                    description = "Choose a character" )
 
    scnType.dropDownProp = enumProp

Blend File