Hierarchical Phrases

Descriptive phrase trees may be flat or deeply nested. They are flexible and may be configured to present the same resources and components in many different ways, while accommodating changes to those resources and components in response to editing operations.

In order to deal with this complexity, the duties of phrases are split across several classes:

  • Phrase models are responsible for determining which descriptive phrases belong at the root of the tree. They also provide utilities used to

    • watch for events that may change the tree and

    • determine how to notify user interfaces of those changes in terms of deleted, added, re-ordered, and modified phrases.

    • mark each descriptive phrase with optional, clickable badge icons.

  • Descriptive phrases are only responsible for storing child phrases and, optionally, a reference to a subphrase generator that can create or update the list of child phrases on demand. They also own a reference to another class responsible for the phrase’s content (i.e., title, subtitle, and other related information).

  • Subphrase generators create or update a list of child phrases when given a reference to a potential parent phrase.

  • Phrase content classes own a reference to a persistent object and determine what about that object should be presented (i.e., they determine the topic of the phrase). One content class may hold a model face and present the face’s name as the phrase title/topic, while another class may hold the same face but present one of the face’s properties as its topic.

Phrase Models

Todo

Describe the base phrase model class

There are several phrase model subclasses:

ReferenceItemPhraseModel,

which lists components available for use in a ReferenceItem. The top-level phrases it presents are persistent objects that either are or may be added to a ReferenceItem that you provide to the phrase model during configuration. It is used by the qtReferenceItem class to present components that may be selected by a user in order to populate some item.

ResourcePhraseModel,

which lists resources matching a given set of filters at its top level. It is used by the pqSMTKResourcePanel class to present a list of resources that have been loaded.

ComponentPhraseModel,

which lists components matching a given set of filters at its top level.

SelectionPhraseModel,

which lists objects held by a Selection <smtk::view::Selection> (which you provide at configuration time). By default, it will list all selected objects, regardless of the selection value. However, you may optionally specify a bit mask so that only objects whose selection values match the mask are shown.

Phrase Content Types

Todo

Describe the base phrase content class and its children

Subphrase Generators

Todo

Describe the base subphrase generator class and its children

Badges

Each phrase model owns a BadgeSet used to decorate phrases. User interfaces that present phrases can ask the badge set for an array of Badges that apply to a given phrase. The returned array of badges will be ordered consistently. Each badge has an SVG string to use as an icon, an optional tool tip, and an “action” method used to perform some task when users click on the badge.