Custom Menus

Custom pop-up menus

NOTE:

If you find trouble trying to use this feature, make sure to update to Jmol version 11.7.21 or later; there are bugs in the localization of custom pop-up menus in previous versions.

Starting on v. 11.3.15, Jmol (both application and applet) allows a customized pop-up menu instead of the standard default menu. Custom menus are defined using plain-text files according to certain syntax and rules.

How to load a custom menu

• To open the application with your own menu, use

-m myMenu.mnu

as a command-line parameter.

• To insert the applet with your own menu:
  • If you are using Jmol.js (recommended) to insert the applet, use

JmolSetCallback("menuFile","myMenu.mnu") 

after JmolInitialize() and prior to JmolApplet().

• If you are directly inserting the applet or object tag, use

param=menuFile value="myMenu.mnu"

as one of the parameters of the tag.

• To switch to your own menu on the applet via scripting, use

load menu "myMenu.mnu"

To get back the default menu, use an empty string:

load menu ""

How to check the current menu

• show menu will display the current menu definition in the console (app and applet).
• write menu "fileName" allows to save the current menu definition to a file (app and signed applet).
• getProperty "menu" also allows to retrieve the current menu definition.

How to write your own custom menu

(Updated as of Jmol version 11.7.21)

The menu file (a plain-text file) contains three parts:

1. Part I contains the menu structure.
2. Part II contains all the Jmol scripts that correspond to a menu click.
3. Part III contains additional words that will be translated.

Part I: Menu Structure

Each definition consists of

key | label = [menu list]

for example:

 zoomMenu | Zoom = zoom50 zoom100 zoom150 zoom200 zoom400 zoom800 - zoomIn zoomOut

The words used for the key are arbitrary designations, but they must end with the letters "Menu". They must not contain spaces. They are case sensitive.

The label is what the user sees. Or, rather, the translation of that label (see below) is what the user sees.

The menu list is a space-separated list of submenu keys or item keys (see Part II) or, if not listed in Part II, a single-word Jmol script word, such as "cpk".

A hyphen indicates the location for a horizonatal menu separator.

Menu items starting with @ are predefined sets. For example:

 [color_atoms]Menu | Atoms = schemeMenu - @COLOR - opaque translucent

Here @COLOR is a predefined set:

 @COLOR = black white red orange yellow green cyan blue indigo violet

You can create your own predefined terms and use them anywhere you want. Predefined terms may contain more predefined terms.

Don't do this: @COLOR = something something @COLOR

"Checkbox" at the end of a menu item creates a check box. These objects operate by setting Jmol true/false parameters. The name of the checkbox must correspond to the name of a valid Jmol parameter.

 atomMenu | Atoms = showHydrogensCheckbox - atomNone - atom15 atom20 atom25 atom50 atom75 atom100   

A note about language translation

The way translation works is that a code preprocessor identifies text that in the CODE is written as GT._("...."). This is called *internationalization*, and it occurs when the Jmol distribution is built.

Then, when that method is executed in the running Jmol program, the table for the selected language is looked up. If that phrase has been translated into that particular language by a human volunteer, then the translated phrase is returned. This is called *localization*.

All menu labels will be sent through the GT._() method. If you change a menu label to a phrase that has not been internationalized, then it won't be localized. It will appear in the language in which you have written it here. Just be aware of that.

Computed menus

Menu keys containing the term "Computed" are modified after the fact. You should be able to omit them, but this needs additional testing (by YOU!)

Special identifiers in this section

Certain all-capitalized words anywhere in a key are significant. They relate to specific Jmol data options. If a model set does not involve data that are relevant to this option, then this menu item will be present but disabled (greyed out). Note that if a menu key is greyed out, then submenu items of that key are not visible, so those item keys do not need the identifier as well. This is the case with many PDB identifiers -- if you move them to another menu, make sure that menu has "PDB" in it or add PDB somewhere in the name.

The following options exist as of Jmol 11.3.15:

• CHARGE data set includes partial charge information
• FRAMES data set includes multiple frames
• PDB data set is PDB file format information (HETERO, etc.)
• SYMMETRY data set includes symmetry information
• UNITCELL data set contains a unit cell
• VIBRATION data set includes vibration data

A key may contain multiple option identifiers.

In addition, APPLET indicates that this item should show up only in the Jmol applet menu, not the Jmol application menu

If a key includes a phrase in square brackets, as in

 [color_atoms]Menu | Atoms = schemeMenu - @COLOR - opaque translucent

then for all menu and submenu items under this menu the script given in Part II is prepended with that phrase, with underscore replaced with space. For example,

Part II: Key Definitions

This section contains the Jmol equivalents of all action items.

Each definition consists of

key | label = [Jmol script]

or

someCheckbox | label = [on script] | [off script]

for example:

stereoNone | None = stereo off
showAxesCheckbox | Axes = set showAxes true | set showAxes false;set axesMolecular

Each key should be referred to explicitly in at least one menu list in Part I.

The label is what the user sees. Or, rather, the translation of that label (see above) is what the user sees.

For checkboxes, the on and off scripts are not required if the action is simply to turn a Jmol parameter on or off.

Special identifiers in this section

"SELECT" at the beginning of a definition wraps the definition with "select thisModel and ()".

For example:

invertSelection | Invert Selection = SELECT not selected

"#" anywhere in a definition indicates that the script evaluation should be done in "silent" mode -- that is, without sending messages to the console or status line Note that checkboxes are always executed in silent mode.

Part III: Word Translations

This section contains a few additional words that are translated as menu labels. They are menu items that do not otherwise have Jmol script definitions listed in Part II.

Each definition consists of

key | label

Examples of menus

Default menu is built using this file.

An example of custom menu: test.mnu

If you design a new menu, please share it in the Custom pop-up menus section within Recycling Corner.

Contributors

AngelHerraez