Presenting models in a user interface
=====================================

.. _descriptive-phrase-example:

.. findfigure:: descriptive-phrase-examples.*

   :smtk:`Descriptive phrases <DescriptivePhrase>` are used to
   illustrate the structure of a model.
   Wherever a phrase has children, they are generated by a
   :smtk:`subphrase generator <SubphraseGenerator>` instance
   — which acts as a delegate for descriptive phrases.

SMTK provides several classes to help user-interface developers present
hierarchical and/or list views of solid modeling entities to users.
There are many different circumstances where these views are needed,
so flexibility is a key requirement.
Some of these use cases include:

+ A tree view showing modeling entities to allow selection when
  entities are obscured in a 3-D rendering by other geometry (e.g.,
  a face inside a cavity) or not being illustrated (e.g., oriented
  shell uses are not usually explicitly rendered but may be
  associated with boundary conditions rather than faces in some
  multiphysics simulations).
+ A list view displaying group membership and allowing drag-and-drop
  modifications.
+ A list view showing entities ordered by their intersection points
  along a ray fired through a rendered view (for selection of
  entities as input to operations or association with simulation
  attributes).
+ A tree view illustrating relationships between entities and
  sizing functions and/or feature definitions used to constrain
  meshers.
+ A tree view showing relationships between model concepts
  or categories and model entities.
  For example, a simulation may be defined without reference
  to geometry, knowing only that a boundary condition exists
  wherever solid material meets ambient air. A tree view can
  be used to assign geometric regions to materials (solid, air)
  and the tree view would allow selections that render where
  the boundary condition would be applied with those assignments.

In some instances (use cases that present list views), each entity
should be displayed without any children.

In other instances it may be desirable for entities in a tree view
to show an abbreviated hierarchy rather than the full hierarchy;
it is rare for users to interact directly with oriented
use records (edge- or face-uses) or shells or loops. Rather than
having cells present use-records as children and force users to open, for example,
a face's face-use and then the face-use's loop and then one of the loop's
edge-uses to obtain an edge bounding the face, the face should present
its bounding edges as direct children.

Finally, there are circumstances when the full solid-model hierarchy should
be presented.

Instead of writing a separate model or widget for each use case,
SMTK provides a framework that can express any of these cases.
The framework consists of two base classes plus some subclasses of each.
The base classes are not tied to any particular user interface library
so that they can be used in both desktop and web applications.
An adaptor to the Qt model-view-controller system is provided,
named :smtk:`QEntityItemModel`.

The first base class is :smtk:`DescriptivePhrase`.
Instances of DescriptivePhrase or its subclasses are arranged in a tree.
Each phrase has at most one parent and zero or more children.
List views are expressed as one parent phrase with no grandchildren.
A descriptive phrase may be asked for a solid modeling entity related to it,
but the returned entity may be invalid (such as the case when a phrase is
used to group other phrases).
Descriptive phrases also

+ must provide a type which user interfaces may use to alter presentation style,
+ must provide a textual title and may also provide a subtitle (as is commonly used in iOS table views),
+ may provide an icon and/or a color,
+ may mark elements such as the title, subtitle, or color as mutable (indicating that the user may change it).

The :smtk:`SubphraseGenerator` class is the second base class in the user-interface presentation system.
Descriptive phrases store a list of children but they are not responsible for computing
that list, nor is the list computed except on demand.
Instead, each phrase (or its parent, if it has one) stores a reference to an instance of a
SubphraseGenerator that will compute children when they are requested from a descriptive phrase.

The SubphraseGenerator is separate from the DescriptivePhrase class so that
different user-interface components can use the same set of phrases but
arrange them in different ways.
For example, a widget for selecting a model might subclass the subphrase generator
to only enumerate sub-model and sub-group children of a DescriptivePhrase;
while a model-detail widget might include volumes, faces,
edges, and vertices as children.
Another example is shown in the
:ref:`figure at the top of this subsection <descriptive-phrase-example>`.

Here, additional summary phrases are inserted in the lower figure to reduce clutter
when a phrase has many children.
The subphrase generator is completely programmable, so multiple summaries could be
added to distinguish children of different types.

