Dev:Py/Blender2.5/Layouts/Guidelines

From BlenderWiki

[edit] Why Code Guidelines?

- Layout files are new in 2.5, so it's the right time to write and keep them clean.

- Modifying the layout is also interesting for artists. Keep the code as readable as possible is important for them. Also coders who don't work on these files should be able to learn the code as fast as possible.

[edit] Which scripts?

These guidelines are for every official python script which use buttons inside of blenders interface. So, all button files inside of release/ui. And other scripts (for Render integration...like Povray in release/io) which are bundled with Blender. Scripts using their own interface and not Blenders Layout Engine don't have to follow these guidelines.

[edit] Assignments

The code has lots of different assignment names. Col, colsub, subsub1, sub etc. Let's try to keep that consistent:

row for layout.row()
col for layout.column()
flow for layout.column_flow()

Please also use these names for split layouts. For example col = split.column().

Use "sub" for sublayouts, 
and if you need more subsub etc. 

[edit] Example Code

Some examples how it should look.

The Basic Code of each panel:

class MATERIAL_PT_material(MaterialButtonsPanel):
	__label__ = "Shading"

	def draw(self, context):
		layout = self.layout 

		mat = context.material
		ob = context.object
		slot = context.material_slot
		space = context.space_data

First define the layout.

Empty line.

Define all context you need for the panel. Use short and easy assignement names.

Layout Split Code:

		split = layout.split()
	
		col = split.column()
		col.itemR(mat, "alpha", slider=True)
		col.itemR(mat, "ambient", slider=True)
		col.itemR(mat, "emit")
		col.itemR(mat, "translucency", slider=True)
				
		col = split.column()
		col.itemR(mat, "z_transparency")
		col.itemR(mat, "shadeless")	
		col.itemR(mat, "tangent_shading")
		col.itemR(mat, "cubic", slider=True)

If you need a sublayout because of align, greying out or something else,
use sub as assignement name:

                sub = col.column(align=True)
                sub.itemR(mat, "bla")

First define the split.

Empty line.

Now pack every column in 1 block, this improves the readability. Sub layout blocks can be separated as well if this improves the readability.

Greying out:

For greying out first define the active/enabled rule, then put the buttons there:

Right:
sub = col.column()
sub.active = tex.distance_metric == 'MINKOVSKY'
sub.itemR(tex, "minkovsky_exponent", text="Exponent")

Wrong:
sub = col.column()
sub.itemR(tex, "minkovsky_exponent", text="Exponent")
sub.active = tex.distance_metric == 'MINKOVSKY'