Designing Graphical Interfaces

Many tools add their own elements to the graphical interface. In the previous chapters, we used existing menus, but we can also add new panels to the Blender window.

To design an interface, we must decide which elements to show and how to reach them, what information should be provided, and which actions should be allowed.

In this chapter, you will learn how to insert new panels into different regions of Blender, how to display information and icons, and how to add buttons that can invoke operators.

This chapter will cover the following topics:

• Understanding the Blender interface
• Drawing a custom panel
• Context and UI interaction

Technical requirements

We will use Blender and Visual Studio Code in this chapter. The examples created in this chapter can be found at https://github.com/PacktPublishing/Python-Scripting-in-Blender/tree/main/ch5.

The example files include 2D images to be used as icons. Optionally, any 2D software can be used to create custom .png images, and you can use them instead.

To implement our interface, we will have to learn how Blender is structured. Let’s begin our journey into graphical interfaces with a deep dive into the Blender screen.

Areas, regions, and panels

The Blender window is split into areas. Each area can contain an editor of a different type, such as the viewport for 3D objects or the sequencer for editing videos. Each editor, or space, can contain one or more regions. The number and type of regions vary across different types of editors: for instance, some editors, such as the Preferences window, have a navigation sidebar, while others don’t.

The Blender manual explains the interface in detail: https://docs.blender.org/manual/en/3.1/interface/index.html.

What we need to know for now is that regions can contain panels, and panels are the basic containers of graphical elements such as text, editable values, and buttons.

We can create new panels with Python, which makes it possible to customize any region with ease. A panel must contain information about the area and region to which it belongs:

Figure 5.1: Areas, regions, and the panel in the Blender interface

...

Creating a simple panel

We will start with a simple panel that contains some text and icons, and we will see how to expand this initial idea into a tool that can help manage the objects in the scene.

Our panel is a new class that derives from bpy.types.Panel. Like operators, panels require some static members to be set; otherwise, they will not work. Similar to operators, panels can have a poll() class method that states under which conditions the panel can be displayed.

Instead of using the execute function, panels set up and draw their content via the draw(self, context) function.

Since we are adding a new piece to the Blender interface, we will do that inside a new add-on. It’s not mandatory, but it makes it easier to enable and disable our panel.

To keep our code orderly and clean, we will create a new folder for the scripts written for this chapter.

Setting the environment

Let’s create a folder for Chapter 5 in our Visual Studio Code project. Then...

Using layouts in our panels

If we are not happy with the default stacking of the global layout, we can add a layout type of our choice to it and use that instead, and we’ll get a different arrangement.

For instance, we can put two labels on the same line using a row. Also, even if we are happy with stacking our elements one under the other, it is good practice to create a column sub-layout anyway. This practice has at least two advantages:

• We preserve the panel's look, even if the default arrangement should change
• We do not pollute the original layout

Let’s see how we can change the way our widgets are stacked.

Arranging in columns and rows

We can nest more layout types together inside our draw function. For instance, we can place the last two labels from the previous example side by side rather than arrange them vertically. To do that, we must do two things:

1. First, we must create a column and add the first label to it.
2. Then...

Providing color feedback

Our object list will be much more useful if we can highlight which objects are selected and which are active. For instance, to reflect the selection status of an object in the color of its name, our script must perform two actions:

1. Check whether an object is selected.
2. If it’s selected or active, display its name in a different color.

Let’s learn how to perform these tasks using Blender’s API.

Checking whether an object has been selected

We can get the selection status of an object using its select_get() method. For instance, if the 'Cube' object is selected, its selected_get method will return True:

>>> import bpy
>>> bpy.data.objects['Cube'].select_get()
True

We already know from Chapter 2, that, unlike the selection status, active is not a flag of the object, so how we retrieve this information is a bit different.

Checking whether an object is active

To check whether...

Displaying buttons

Intuitively, pushing a button performs a transformative action. Since buttons take up space, the default interface displays only the more generic operations. When we write custom interfaces, we can add more buttons based on our specific needs. This is made easier by how Blender translates operators into buttons. In this section, we’ll learn how buttons and operators are equivalent when it comes to the graphical interface.

Using the operator method

We can use the UILayout.operator method to display a button. In Blender, a button executes an operator. This operator is found through its identifier – that is, the bl_idname attribute, which we encountered in Chapter 3 – and every operator must have it.

For instance, to add a button that deletes the selected objects, we must provide the identifier of the Delete operator.

If we use the Delete action from the Object menu or the X key and look into the Scripting workspace, we will find this...

Using different regions

Usually, panels can be moved freely to another part of the interface. There are a few exceptions where repositioning a panel would not make much sense. For instance, a tool that helps select the controls of a character would be of little help in the Video Editor, and its poll() method might be looking for attributes, such as animation bones, outside of the animation’s context.

Outside of those cases, changing the bl_* attributes of a Panel class is enough to move our panel to a different place. Please refer to the panel attributes that we looked at in the Creating a simple panel section of this chapter.

So, to display our panel in the 3D Viewport area, we can change the values of bl_space_type and bl_region_type as follows:

    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'

Figure 5.27: Our panel has been moved to the 3D Viewport area

By default, the...

Summary

In this chapter, we learned how to create and populate a custom UIPanel via Python and how to integrate that into our add-on. That gave us insight into how the Blender interface works in general and which steps we must take to add our widgets to it.

We also nested layouts together for a more complex appearance and displayed both native and external icons.

Lastly, we learned how to change our panel’s look according to the context without too much increase in complexity, as well as how to add functions to the UI.

This closes the first part of this book, where we gained an overall understanding of how Blender and Python work together and what Python scripts can do.

The add-on we have written relies on an external file called icon_smile_64.png. If we were to distribute it to the public, we would have to package it as a ZIP file. This is something we are going to do in Chapter 6, which marks the beginning of Part 2, Interactive Tools and Animation.

Questions

1. Is it possible for an area of the screen to host more than one editor?
2. Do all the editors consist of the same regions?
3. How do we set the editor, region, and context to which a panel belongs?
4. Must we always set a panel’s category?
5. Are the elements of a panel static or can they change dynamically?
6. Can we alter the color of a piece of text?
7. How do we display buttons?