Notes about Layer parameter presentation hints

Development Feature discussions
1

A layer parameter is of a certain value type: vector/point, string, integer number, real number, boolean…

In Parameter panel, each item is a layer parameter and it has a viewer and an editor widget for showing and changing its value, respectively. For each value type, there’s a correspondent viewer/editor widget type.

However, a single value type may have different purposes in a user point of view. Examples:

  • an integer number may represent an amount (like the number of points of a Star layer), but is also used to store the index of an enumeration list item (like the blend method parameter of many layer types)
  • a string is used to store a text, but it may be necessary to display a larger text typing area for an entire paragraph (like for text of Text layer) or even a file path (like audio filename of Sound layer)
  • a pair of real numbers may represent the vertex 2D-coordinates or a 2D-scaling factor (as in Stretch layer)

For the GUI to know what parameters a layer have, what are their value types and how to handle these different applications of the same value type, a layer describes its parameters by (re)implementing synfig::Layer::get_param_vocab(), that returns a list of parameter descriptions (synfig::ParamDesc objects).

In order to specifically differentiate the purpose of that value type of a given parameter, the ParamDesc may have a hint set.

By using a regular git grep set_hint, currently there are these hints:

  • enum
    • for integers
    • allow user to select an option from a combobox instead of remembering/knowing an internal number id
    • – note synfig::ParamDesc::add_enum_value() should be used together with this hint…
  • dash
    • set for some parameters, but never used
  • filename
    • for strings
    • allow user to browse the file system, instead of fill this field via typing only
  • paragraph
    • for strings
    • allow user to type text with multiple lines
  • font_family
    • for strings
    • allow user to select an available font face instead of only typing it
    • – defined in 2005, but only used this year in commit ccb98a3d95cdca341cec37814090d9ddc2d32c64
  • size
    • set for some parameters, but never used
  • width
    • set for some parameters, but never used
  • sublayer_name
    • for strings
    • used only by a parameter of Switch layer (Active Layer Name)
    • allow user, via combobox, to select a layer encapsulated by the Switch layer, instead of typing it

Beside the hint property, there is also a method synfig::ParamDesc::set_is_distance() used by some parameters. It means the viewer and editor should present data as the unit-system chosen by the user in app preferences. By default, this parameter property is false, and should be explicitly set in the param_desc.
It seems the viewer (studio::CellRenderer_ValueBase) and editor (studio::Widget_ValueBase) don’t handle it well, ignoring it in some cases – by assuming it is true.

2 Likes
2

Lists like WidthPoint list (WPList) or DashItem list (DIList) have its items described by ValueNode_Composite by default, that has its “composite” components defined via synfig::ValueNode_Composite::get_children_vocab_vfunc().

For some reason, in those cases, it isn’t referred as param_desc field in the ParamTreeStore (see CanvasTreeStore), but as child_param_desc (and param_desc contents isn’t valid – but the viewer CellRenderer ignores it – editor seems to work right).