Inner workings of the property sheet widget

The property sheet in ml.ui.core.propertysheet is a complex widget used for various purposes in several places in the Moonlight|3D user interface. It is a very powerful tool to create dynamic user interfaces. But this power also makes its a little hard to understand.

The basic design

A property sheet builds its contents from the PropertyContainer? that is assigned to it by the user. It builds a list of categories and a list of property editors inside each category. The categories are foldable in the user interface to shorten long lists of properties. Property editors are assigned one or more properties for which they provide the user interface. There are two kinds of property editors; specialised property editors with additional parameters and default property editors which are available for most property types. Specialised property editors are described in more detail below. Default property editors are available for property types where such an editor makes sense. Array types are not covered by default editors because there are always additional semantics involved when these types are used.

Special property sheet definitions

Moonlight|3D loads a list of special property sheet definitions from XML files on startup. These change the property sheets created for certain property containers. The property sheet performs the following steps to consider property sheed definitions while building a sheet for a property container:

  • check if the type of the property container matches the type given in the sheet definition
  • if the container implements NamedObject? and a name is given in the sheet definition, also check if the name of the container matches the sheet definition
  • if a matching sheet definition is found, build categories and property editors as defined in the sheet
  • for each property in the container not covered yet build a default property editor and add it to the "Other Properties" category

TODO: describe XML property sheet defintions

Generic property editors

For the following types exist generic property editors that are automatically used if no editor is defined explicitely:

  • String
  • Integer
  • Float
  • Boolean
  • Vector3D
  • Colour

Specialised property editors

Currently the following specialised property editors are implemented:

  • DummyEditor?: does not display any widgets, useful to hide an internal property
  • DirectoryListEditor?: allows editing of a StringArray? property as a list of directories
  • IntegerMap?: displays a dropdown widget with predefined strings that are internally converted to numeric values for an Integer property

TODO: describe parameters for specialised property editors