Dev documentation: about the nested splitter Provider classes

[Edward K. Ream]

For a long time I thought the Provider classes were kinda mysterious. As soon as I started using them, their mystery disappeared.

This post will tell document these Provider classes in more detail. This post will be pre-writing for a dev info issue.

Overview

Terry created the Provider classes as part of his free_layout project, in plugins/free_layout.py This project also contains the nested splitter Gui code, in plugins/nested_splitter.py. The nested splitter code creates the so-called Easter Egg interface, which appears if you right-click the divider between any two panes.

The Provider interface

The Provider classes implement an interface, partially described in the docstring for the FreeLayoutController class in free_layout.py and more fully described in the docstring for NestedSplitter.register_provider.

The interface works like an extended factory method. Provider classes must contain the following methods:

ns_provides: Return a list of tuples ('Item name', '__item_id') that describe the panes returned by the factory.
 

ns_provide(id_): This is the factory itself. It returns the Qt pane for id's that the Provider provides, and None otherwise.

The following methods are optional:

ns_provider_id(): return the id string for the Qt pane provided by the provider.

ns_title(_id): Return the desired window title for the Qt pane with the given id string.

And that's probably all you need to know.

Examples in the viewrendered plugins

The VR plugin provides a different Qt pane for each outline (commander). There is a separate Provider for each commander, and each Provider has a distinct id from all other VR providers.

At present, the same is true for the VR3 plugin, but #1683 suggests using a global Qt pane. To do this, the Provider would simply use a single id for global Qt pane.  Like this:

- ns_provides: return ('VR3 pane', '_vr3')

- ns_provide: return a singleton, global, Qt dock.

- ns_provider_id(): return '_vr3'

- ns_title(_id): return 'VR3 pane'

Summary

Terry's Provider interface provides a framework for creating various kinds of factory methods.

The VR and VR3 plugins use this interface to create and describe the Qt panes that they create.

All comments, questions and corrections are welcome.

Edward