Context - Using the Poll Method
Blend File
Introduction
Not every action is appropriate for every situation.
For that reason, Blender operators work with an idea called contexts.
A context is a is just what it sounds like.
It's a way to refer to the situation at hand.
This tutorial introduces the
poll method which will help us with that job.
By covering this, we will learn about and their advantages for assessing situations.
Brightening A Lamp
Let's suppose we wanted to take a selected lamp in a scene and brighten it by 50%.
The brightening of the lamp itself is really just property setting and simple math.
The
execute method shown below is pretty straight forward.
If you are unfamiliar with how execute works, you can
check out City Destroyer for a simple introduction or
here for a more in depth look.
def execute( self, context ):
lampData = context.object.data
en = lampData.energy
en = en + ( .5 * en )
lampData.energy = en
return {"FINISHED"}
Nothing special so far, right?
There are other things to consider here.
What if nothing is selected?
What if the thing selected isn't a lamp?
It doesn't make sense to work on something that's not selected.
Nor does it make sense to do brighten something that isn't a lamp.
That's where the
poll comes in.
This method checks and sees whether or not an operator makes sense for the context.
Context is the key thing here.
The
poll method checks to help ensure the user uses the operator the way it's supposed to be used.
Here's what the code should look like for that poll method.
@classmethod
def poll( self, context ):
ob = context.object
if ob == None:
return False
elif ob.select and ob.type == 'LAMP':
return True
return False
The checks placed here should be pretty straight forward.
Some object has to be in the context to begin with and it has to be selected.
We also ensure that we are dealing with a lamp.
Failing either of these would yield a false result.
This would mean the context was wrong for this operation.
Let's copy some code in and hit alt-p to run it.
The source code to copy is shown below...
import bpy
class LampBrightener( bpy.types.Operator ):
bl_label = "Lamp Brightener"
bl_idname = "bpt.typecheck"
def execute( self, context ):
lampData = context.object.data
en = lampData.energy
en = en + ( .5 * en )
lampData.energy = en
return {"FINISHED"}
@classmethod
def poll( self, context ):
ob = context.object
if ob == None:
return False
elif ob.select and ob.type == 'LAMP':
return True
return False
def register():
bpy.utils.register_class( LampBrightener )
def unregister():
bpy.utils.register_class( LampBrightener )
if __name__ == '__main__':
register()
Running the Operator
To run the operator, press Alt-p select the lamp, hit the space bar, type in
Lamp Brightener and hit enter.
Once you've done that, go to the lamp object data in the properties panel.
Here's the change you should see.
Before
After
Now, let's change the selection.
If you don't already have one, add a mesh object to the scene.
Select it.
Now, hit the space bar, clear anything that's already in the text field, and type in
Lamp Brightener.
You should see that the operator doesn't show up in the list.
That's exactly what it should be.
Blender was smart enough to check the context and saw that the
Lamp Brightener didn't work here.
So, it wasn't an option.
Conclusions
The
poll method plays an important role in Blender scripts.
With it, the scripts you use can have proper constraints ensuring that they are used as intended.
The topic of context goes well beyond what's covered in this tutorial.
For example,
poll methods can be used in other types of objects as well, not just operators.
Panels, for example, can use
poll to determine what situations they should be made available.
Last but not least, explore the
bpy.context submodule.
The entire area of the api is dedicated to access to the scenes, objects, bones, and so forth directly relevant to the context you're working in.
Spend a little time exploring it.
Familiarity will make your own scripts much easier and intuitive to put together.
Best of luck and happy Blendering.
Blend File
