Custom Menus

Custom pop-up menus

NOTE:

If you find trouble trying to use this feature, make sure to update Jmol version to at least 11.6.13 or 11.7.21; 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 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 ""

• To insert the applet with your own menu:
  • If you are using Jmol.js 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 (not a recommended method), use

param=menuFile value="myMenu.mnu"

as one of the parameters of the tag.

How to check the current menu

These allow to retrieve the current pop-up menu definition (equivalent to the contents of the loaded menu file).

Please note that, if you are using a language other than US English, what is retrieved will be the translated menu. So, you will probably want to switch to en_US first, then get the menu.

• show menu will display it in the console (app and applet).
• write menu "fileName" allows to save it to a file (app and signed applet).
• getProperty "menu" also allows to retrieve it, to be used in some scripted action.

How to write your own custom menu

(Updated as of Jmol version 11.6.13 and 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.

Your custom menu needs only include the menu entries that you want to change. That is, the custom menu supplements the default one, and only the entries you define in it will overwrite or supplement the default menu.

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 the 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, the last two menu entries in the previous example will invoke these commands:

color atoms opaque 
color atoms translucent

(the same will do all the sub-entries defined under schemeMenu and all the entries summarized by the @COLOR predefined set).

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

For example:

translucent | Make Translucent

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