13 Customizing the Model and Script Menus

For model menus, a model entry is used to select a specific model; clicking on this entry type in the model menu causes the class defining the model to be loaded. Model classes must be public subclasses of RootModel.

To add a model entry to the menu, click Add model in the edit panel. This opens an add model dialog,

which allows the user to specify the model class and (optional) build() method arguments using the “Model package”, “Model class” and “Build args” fields in the same manner discussed in Section 2.2. Multiple models may be selected in the “Model class” panel; if this is done, a separate model entry will be created for each. The menu title can be set explicitly using the “Menu title” field; otherwise, the title will default to the model class’s simple name.

Once created, a model entry can be edited by selecting it in the editor’s menu panel and clicking the Edit button, which opens an editing dialog that also allows the user to adjust the title font properties.

For model menus, a package entry is a submenu containing all the model classes found within a specified Java package and its subpackages. The submenu contents may be arranged either as a flat list, or hierarchically based on the subpackages (the default). Again, each model class must be an public subclasses of RootModel. Individual model classes can be excluded from package menu entries by defining the public boolean member variable omitFromMenu and setting it to true:

public class MyModel extends RootModel {
   ...
   public static boolean omitFromMenu = true;
   ...
}

To add a package entry to the menu, click “Add package” in the edit panel. This opens an add package dialog,

which allows the user to specify the package, menu title, and whether to use a flat or hierarchical view. Auto-completion is supported by the Package field, with the <TAB> character invoking auto-completion based on currently known packages and repeated use of either <TAB> or the up/down arrows will scroll through known packages. Package entry is completed using the <ENTER> key.

If the title is omitted (via an empty “Menu title” field), then the menu entries are not presented as a submenu, but instead are unrolled directly into the submenu containing the package entry.

Once created, a package entry can be edited by selecting it in the editor’s menu panel and clicking the Edit button. This opens an editing dialog that allows the user to adjust additional attributes, such as the title font properties, the maximum number of rows, and whether to employ scrolling, as described in more detail in Section 13.3.6.

For model menus, a “demo file” entry is a submenu containing all the models listed in a plain text file, using the format described in Section 13.5. Plain text files have the advantage of being more human-readable, and are easier to edit and comment out line.

To add a demo file entry to the menu, click “Add demo file” in the edit panel. This opens an add demo file dialog,

which allows the user to specify the file name and the menu title. If the title is omitted (via an empty “Menu title” field), then the menu entries are not presented as a submenu, but instead are unrolled directly into the submenu containing the entry.

Once created, a demo file entry can be edited by selecting it in the editor’s menu panel and clicking the Edit button. This opens an editing dialog that allows the user to adjust additional attributes, such as the title font properties, the maximum number of rows, and whether to employ scrolling, as described in more detail in Section 13.3.6.

For script menus, a script entry is used to select a specific script file; clicking on this entry type in the script menu causes this script file to be run.

To add one or more script entries to the menu, click “Add scripts” in the edit panel. This opens an add script dialog,

which allows the user to specify the script and (optional) arguments using the “Script folder”, “Script file”, and “Args” fields in the same manner discussed in Section 12.5. Multiple scripts may be selected in the “Script file” panel; if this is done, a separate entry will be created for each. The menu title can be set explicitly using the “Menu title” field; otherwise, the title will default to the script’s file name.

Once created, a script entry can be edited by selecting it in the editor’s menu panel and clicking the Edit button, which opens an editing dialog that also allows the user to adjust the title font properties.

For script menus, a script folder entry is a submenu containing all the scripts found within a specified folder. The scripts are found by searching the folder for all files that end in .py and .jy, and which also contain the special first line

where scriptTitle is the desired menu title for the script.

To add a script folder entry to the menu, click “Add script folder” in the edit panel. This opens an add script folder dialog,

which allows the user to specify the script folder and menu title via the “Script folder” and “Menu title” fields. If not explicitly specified, the title defaults to the name of the folder. If the title is omitted, by explicitly setting it to an empty string, then the menu entries are not presented as a submenu, but instead are unrolled directly into the submenu containing the script folder entry.

Once created, a script folder entry can be edited by selecting it in the editor’s menu panel and clicking the Edit button. This opens an editing dialog that allows the user to adjust additional attributes, such as the title font properties, the maximum number of rows, and whether to employ scrolling, as described in more detail in Section 13.3.6.

A submenu entry is a generalized submenu that can contain an arbitrary list of other menu entries, and is used to create hierarchical menus.

To add a submenu entry to the menu, click “Add submenu” in the edit panel. This opens an add submenu dialog,

which allows the user to specify the submenu’s title. Once the submenu is created, new menu entries can be added to it by selecting the submenu in the editor’s menu panel and then clicking the appropriate Add buttons; the new entries will be placed at the end of the submenu. Alternatively, if the user selects a non-submenu entry within the submenu, and then clicks one of the Add buttons, the new entry will be placed in the location indicated by the selection.

Once created, a submenu entry can be edited by selecting it and clicking the Edit button, which opens an editing dialog that allows the user to adjust additional attributes, including whether to support scrolling, the maximum numbers of rows in the menu, and the title font properties:

Scrolling can be useful for submenus with many entries: when the number of rows exceeds the specified maximum, then the menu is presented within a scrolling pane. Otherwise, if scrolling is not enabled, extra entries are accommodated by adding additional columns to the menu (Figure 58).

Both the package, demo file and script folder entries (Sections 13.3.2, 13.3.3 and 13.3.5) are also themselves submenus, and so the scrolling and maximum rows attributes can be set for these as well.

A label entry is an inactive text element that cannot be selected in the menu. It can be used to label a group of entries. To help distinguish a label from an active menu item, the default font style is set to "italic".

To add a label entry to the menu, click “Add label” in the edit panel. This opens an add label dialog,

in which the user enters the label title. After it has been created, the label can be edited by selecting it in the editor’s menu panel and clicking Edit, which opens an editing dialog that allows the user to also adjust the title font properties.

A separator entry is a horizontal line that visually separates menu entries. It can help distinguish groups of related menu items.

To add a separator entry to the menu, click “Add separator” in the edit panel. This will simply add a separator at the location indicated by the current selection; no dialog is needed.

The root elements ModelMenu and ScriptMenu encapsulate the entire description for either a model or script menu. They must make reference to the schema for validation purposes. The following code snippet can be used as a template for creating a model menu file,

while the next snippet can be used for script menus:

Describes a model menu entry (Section 13.3.1), with the class attribute specifying the model class, which must be a public subclass of RootModel.

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

Describes a package entry (Section 13.3.2), with the name attribute specifying the Java package containing the model classes.

If the title attribute is omitted, then the submenu contents are unrolled directly into the parent menu.

If font information is provided, it is applied to all entries. The following snippet creates a submenu containing every instance of RootModel found in the package artisynth.demos.mech, with a small font specified for all entries to get the menu to fit easily on the screen:

Describes a demo file entry (Section 13.3.3), with the file attribute specifying the path to the file listing the models. If this path is relative and not absolute, the parser tries to locate the file with respect to (in order) (a) the folder containing the XML file being read, (b) the user’s home folder and (c) the ArtiSynth installation folder.

If the title attribute is omitted, then the submenu contents are unrolled directly into the parent menu. If font information is provided, it is applied to all model entries that are created.

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

Describes a script menu entry (Section 13.3.4), with the file attribute specifying the path to the script file. If this path is relative and not absolute, the parser tries to locate the file with respect to (in order) (a) the user’s home folder and (b) the ArtiSynth installation folder.

The following snippet creates a script entry titled "run models", which will run the script /home/lloyd/modelrunner.py:

Describes a submenu entry containing all scripts located automatically within a specific folder, as detailed in Section 13.3.5, with the file attribute specifying the path to the folder. If this path is relative and not absolute, the parser tries to locate the folder with respect to (in order) (a) the user’s home folder and (b) the ArtiSynth installation folder.

If the title attribute is omitted, then the submenu contents are unrolled directly into the parent menu. If font information is provided, it is applied to all entries.

The following snippet creates a script folder entry titled "Demo scripts", based on all the script files in the folder src/artisynth/demos/scripts:

Describes a submenu menu entry (Section 13.3.6).

The following code snippet creates a submenu "FEM Models", which in turn lists three specific FEM models:

Describes a label entry (Section 13.3.7).

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

Describes a separator entry (Section 13.3.8). 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.

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.