Presenting models in a user interface ===================================== .. _descriptive-phrase-example: .. findfigure:: descriptive-phrase-examples.* :smtk:`Descriptive phrases ` are used to illustrate the structure of a model. Wherever a phrase has children, they are generated by a :smtk:`subphrase generator ` 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 `. 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.