ArtiSynth User Interface Guide

14 Customizing the Models Menu

The Models menu is automatically created at run-time. By default, it has the format described in Section 2.1 However, it is possible to supply an alternative Models menu either of the following command-line parameters:

-demosFile <filename>

Specifies a flat list of models to be loaded, using a plain text format.

-demosMenu <filename>

Specifies a menu that may contain hierarchies, separators, and icons, using an XML format.

A description of both file formats are provided in the following sections.

14.1 Plain text format

In the plain text format, entries are listed as title-class pairs, separated by whitespace. Lines beginning with a hash (#) are ignored. Titles containing spaces must be surrounded by quotation marks. The following is an example:

# Inverse Demos
HydrostatInvDemo artisynth.models.inversedemos.HydrostatInvDemo
"Tongue tracking" artisynth.models.inversedemos.TongueTip

14.2 XML format

The XML format was designed to give users more control over the appearance of the menu. An XML schema is provided that describes and enforces the required document structure (src/artisynth/core/modelmenu/modelmenu.xsd). The following XML elements are defined:

ModelMenu: the root element of the document
model: specifies a model that can be loaded
separator: inserts a horizontal line that separates entries
label: inserts an inactive text entry
menu: creates a sub-menu
package: finds and lists all models from a specified Java package
demosFile: imports all models from a file in plain text format
history: adds a set of recently loaded models
include: imports a menu from another XML file
hidden: convenience element for hiding menu entries (i.e. commenting them out)

A detailed description of each of the element types and their supported attributes is provided in the next sections. Attributes marked by an asterisk are required in the element definition. Some attributes, such as icon, refer to an external file location. The parser tries to find included files by searching directories in the following order:

  • The root directory (i.e. absolute path)

  • The local directory, relative to the XML file

  • All directories listed in ARTISYNTH_PATH

The first readable file found is used.

14.2.1 The root element

The root element encapsulates the entire menu description. It must make reference to the schema for validation purposes. The following code snippet can be used as a template for creating a new menu file.

<?xml version="1.0" encoding="UTF-8"?>
<ModelMenu xmlns="http://www.artisynth.org"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.artisynth.org src/artisynth/core/modelmenu/modelmenu.xsd"
   >
      #... contents of menu ...#
</ModelMenu>

Note:
The second value of schemaLocation is the location of the schema file, which may need to be modified depending on its path relative to the current XML file.

14.2.2 Models

Individual models are inserted into the menu using a model element. These specify a class to load when the menu entry is selected. The model must be a sub-class of RootModel.

Attributes:
class*: the class to load when the entry is selected args: command-line style arguments to be passed to the model text: the text to display in the menu (default: the class name) icon: filename of an icon (relative or absolute path) fontname: font family for the displayed text fontstyle: font style, from {"", "bold", "italic", "bold italic"} fontsize: font size

The following snippet creates a menu entry titled "Muscle Arm", which will launch the model FemMuscleArm.

   <model class="artisynth.models.femdemos.FemMuscleArm" text="Muscle Arm" />

14.2.3 Separators

A separator is a horizontal line that visually separates menu entries. It can help distinguish groups of related menu items. The separator element has no attributes. The following snippet adds a separator line between models found in the artisynth.models.femdemos package and those in artisynth.models.inversedemos.

   <package source="artisynth.models.femdemos" />
   <separator/>
   <package source="artisynth.models.inversedemos" />

14.2.4 Labels

Labels are inactive text entries; they cannot be selected in the menu. They can be used to label a group of entries. To help distinguish a label from an active menu item, it is recommended to set the font style to "italic".

Attributes:
text*: the text to display in the menu icon: filename of an icon (relative or absolute path) fontname: font family for the displayed text fontstyle: font style, from {"", "bold", "italic", "bold italic"} fontsize: font size

In the following code snippet, a label is added before the tongue tracking models.

   <label text="Tongue Tracking Models" fontstyle="italic" />
   <model class="artisynth.models.tracker.JawDynamicTongue" />
   <model class="artisynth.models.tracker.JawKinematicTongue" />

14.2.5 Sub-menus

Menu hierarchies can be created using the menu element. Apart from the root element, this is the only non-empty element type. It can contain any number of valid elements apart from the root element.

Attributes:
text*: the text to display for the sub-menu icon: filename of an icon (absolute or relative path) fontname: font family for the displayed text fontstyle: font style, from {"", "bold", "italic", "bold italic"} fontsize: font size

The following code snippet creates a sub-menu "FEM Models" with a specified icon, and lists all models found within the artisynth.models.femdemos package.

<menu text="FEM Models" icon="resources/icons/FEM.gif">
   <package source="artisynth.models.femdemos" />
</menu>

14.2.6 Packages

The package element can be used to include all models belonging to a particular Java package and its sub-packages. A base class can also be specified so that only models that are instances of that base class are added. For example to include all models that are sub-classes of HexTongueDemo, the following line can be used:

   <package source="artisynth.models" base="artisynth.models.femdemos.HexTongueDemo" />

The models can be displayed in either a flat or hierarchical structure. To reduce the number of sub-menus, and to shorten some of the displayed text, a "compactness" level is introduced. Illustrative examples for the options are provided in Figure 57.

compact flat hierarchical
0
1
2
Figure 57: View options for the XML element <package source="artisynth" base="HexTongueDemo"/>

Attributes:
source*: the package to search for models base: the base class from which all models must inherit (default: RootModel) args: command-line style arguments to be passed to the models view: display format {"flat", "hierarchicial"} (default: "hierarchical") compact: level of compactness {0, 1, 2} (default: 0) 0: A new sub-menu is created for each sub-package (hierarchical), displayed text refers to full package.class name relative to source (flat) 1: Sub-packages containing a single entity are merged into the parent menu (hierarchical), displayed text refers to unique part of the package.class name only (flat) 2: Sub-packages containing a single entity are merged into the parent menu (hierarchical) and displayed text refers to the class name only (hierarchical/flat) fontname: font family for the displayed text fontstyle: font style, from {"", "bold", "italic", "bold italic"} fontsize:: font size

If font information is provided, it is applied to all entries.

   <package source="" view="flat" compact="2" fontsize="5"/>

The previous listing adds every single instance of RootModel found in the source tree to the menu. To get the menu to fit on the screen, compact="2" was used to strip away all package information from the displayed text, and a tiny font was applied to all entries.

Note:
The package element should be used sparingly for two main reasons:

  1. 1.

    Each element adds to the ArtiSynth start-up time.

  2. 2.

    Not all models are functional.

The reason for the start-up delay is that to populate the menu, the parser has to search through the supplied package, create an instance of each class, and test if it is a sub-class of base. The parser also has no way of detecting whether or not a model is functional, so all classes matching the criteria are added.

14.2.7 Plain text files

The XML format supports loading models from a demosFile that uses the original plain text format. Plain text files have the advantage of being more human-readable, and are easier to edit/comment lines out. Models are listed in the current sub-menu.

Attributes:
file*: plain text file to load fontname: font family for the displayed text fontstyle: font style, from {"", "bold", "italic", "bold italic"} fontsize: font size

The following line loads all models from the original default ArtiSynth Models menu.

   <demosFile file=".demoModels" />

If font information is provided, it is applied to all model entries that are created.

14.2.8 History

If model history tracking is enabled, then a set of recent items can be added to the menu. To enable history tracking, pass the following command-line parameter to ArtiSynth on load:
      -historyFile <filename>
The history element then specifies the number of most recently loaded models to add to the history menu.

Attributes:
size: number of recent models to add (default: "4") fontname: font family for the displayed text fontstyle: font style, from {"", "bold", "italic", "bold italic"} fontsize: font size

14.2.9 Importing other XML files

To facilitate modularity, the include element can be used to import all menu content from another XML menu file. All elements contained within the root element of the included file are inserted into the current sub-menu.

Attributes:
file*: XML file to import

The following code imports the contents from two different XML menu files, and separates them with a separator item.

   <include file="demos.xml" />
   <separator/>
   <include file="mymodels.xml" />

14.2.10 Hiding elements

It is often convenient to have the ability to "comment-out" lines in any kind of coding system: the data remains in the file, but has no effect when processed. The typical method for commenting in XML is to use the <!-- --> tags. Unfortunately, this can be messy, and comments cannot contain other comments. For this reason, a special hidden element was created. Any entries within a hidden element are ignored by the parser.

   <!– temporarily hide FEM demos –>
   <hidden>
     <!– All FEM demos –>
     <package source="artisynth.models.femdemos" view="flat"/>
   <hidden/>