User:Theeth/API Design

From BlenderWiki

Introduction

This page will contain informations/opinions on API design, mostly regarding the registration issues.

Definitions

In this text, I will use the following terms:

• extension: python modules/packages that are self sufficient in defining a Blender extension. This can range from a single file to a series of packages.
• Built in RNA types: all RNA types that are defined before any extension comes into play (including extensions that are enabled by default)
• Well defined: a class definition that correctly fulfills the contract of its RNA type
• Register: a class that is registered is recognized as part of the internal RNA system. It is a valid RNA type.
• Unregister: a class that is unregistered is (no longer) a part of the internal RNA system. It is not a valid RNA type.

Protagonists

Types that need registration:

1. Operators
2. Macro Operators
3. ID Property Groups
4. UI Elements (Panel, Menu, Header, Generic UI, ...)
5. Render Engines

In all cases, the classes need to be well defined before registration.

Things that affect or are affected by registration:

1. Defining properties
   1. Properties on built in RNA types
   2. Properties on RNA types defined in the same extension
2. Loading an extension
3. Unloading an extension

Dependencies

Operators

Only after registration:

• Adding operator to a macro

Need to verify if operator properties can be added after registration or only before. --Theeth 20:52, 7 November 2010 (UTC)

Macro Operators

While macros are also valid operators, they work a bit differently, that's why their dependencies are listed separately.

Only after registration:

• Adding operators in the macro

ID Property Groups

Only after registration:

• Defining properties as part of the group
• Defining a property with the group as its type
  • Including using the group as an operator property

Needs to be unregistered after all properties using this type have been removed (including operators)

UI Elements

No dependency. Can be loaded/unloaded in any order.

Note: Order of registration affects drawing order for panels. This is bad and should be changed internally.

Render Engines

No dependency. Can be loaded/unloaded in any order.

Registration Order

The safest "fixed" way:

1. ID Property Groups
   1. Register group
   2. Define group properties
   3. Define properties with group as property type
2. Operators
   1. Register operator
   2. Define operator properties [might have to be done before, not sure]
3. Macros
   1. Register macro
   2. Add operators to macro
4. UI Elements
5. Render Engines

Unregistration Order

The safest "fixed" way

1. Render Engines
2. UI Elements
3. Macros
4. Operators
5. ID Property Groups
   1. Remove properties with group as property type (only for properties added to built in RNA types)
   2. Unregister group

Creating RNA types at runtime