MarvinSketch: parameters and events

Version @MARVINVERSION@

Contents

  1. Parameters
    1. Applet and JavaBeans parameters
      1. Display parameters
      2. Structure display parameters
      3. Structure parameters
      4. Other parameters
    2. Applet only parameters
  2. Events fired by the JavaBean
    1. Action events
    2. Property change events
 

1   Parameters

1.1   Applet and JavaBeans parameters

Parameters of the MSketch and JMSketch applets can be set using the <param> HTML tag. Parameters of the MSketchPane JavaBean can be set using the setParams method.
For parameter constants please visit the ParameterConstants and SketchParameterConstants API.

1.1.1   Display parameters

ParameterMeaningDefault
addRemoveHatomsEnabled Add/Remove Explicit Hydrogens is enabled or disabled in the Structure menu. It will be disabled if this parameter is false. true
atomStrings Comma-separated list of string type atom properties to be enabled.
  • alias - atom aliases
  • pseudo - pseudoatoms
  • smarts - SMARTS query atom string
  • value - atom values
Example: "smarts". 		 
autoscale How to display a loaded molecule:
  • "true" - fit to the applet's window
  • "false" - use default scaling
 false
background Deprecated.  
bondDraggedAlong Bond in hand is visible (true) or not (false). This option can also be set on the Edit/Preferences/MarvinSketch panel. true
customizationEnabled Specifies whether an end-user can customize the user interface. Setting this parameter to false disables the View/Customize dialog and the View/Configurations menu. true
dispQuality Display quality.
  • 0 - low quality, faster rendering
  • 1 - high quality (antialiasing), slower rendering
 1
elements Comma-separated list of allowed elements (H, He, Li, ...). All elements in an atomic number interval can be specified with the short X-Y notation.
Example: "B-F,P-Cl". Here B-F is equivalent to B,C,N,O,F.
 H-Ha
extraBonds Comma-separated list of extra bond types.
  • bold_single - Bold single bond
  • arom - Aromatic bond
  • any - Any bond
  • 1or2 - "Single or Double" query bond
  • aromany - "Single or Aromatic" and "Double or Aromatic" query bond types
  • topology - "Chain" and "Ring" bonds (in molfiles)
  • wedge - Up and Down stereo wedge bonds
  • either - "Up or Down" and "Cis or Trans"
  • ctu - "Cis or Unspecified" and "Trans or Unspecified"
  • coordinate - Coordinate bond
Example: "arom,wedge".
See also: Query properties in file formats. 		 
molbg Molecule background color in hexadecimal value. Sets the background color of the molecule canvas. #ffffff
moreEnabled Enable/disable the Periodic System also called More button. true
queryAtoms Comma-separated list of query atoms and properties.
  • any - any atom ("A" in molfile, "*" in SMARTS),
  • arom - aliphatic and aromatic, ("a" and "A" in SMARTS),
  • conn - total number of connections, ("X" in SMARTS),
  • H - total number of hydrogens, ("H" in SMARTS),
  • hetero - heteroatom ("Q" in molfile, "[!C!H]" in SMARTS),
  • list - atom list,
  • notlist - atom 'NOT' list,
  • Rgroup - Rgroups,
  • rings - "R" in SMARTS,
  • srs - smallest ring size, "r" in SMARTS,
  • val - valence, "v" in SMARTS,
Example: "list,notlist".
See also: Query properties in file formats. 		 
reactionSupport Enables/disables reaction arrow drawing. true
simpView Visibility of the currently used bond at the mouse cursor.  
sketchArrowHeadLength Length of the displayed arrow head in Angstroms. It only affects graphical arrows. 0.8
sketchArrowHeadWidth Width of the displayed arrow head in Angstroms. It only affects graphical arrows. 0.5
sketchArrowTailLength Length of the displayed arrow tail in Angstroms. It only affects graphical arrows. 0.8
sketchArrowTailWidth Width of the displayed arrow tail in Angstroms. It only affects graphical arrows. 0.5
statusBar Enable the status bar. false
tmpls0
tmpls1
tmpls2
... 		The format of this parameter is :name:file, where name is the template set name, file is the sdf or cssdf file containing the template structures.
The file can be optionally compressed with GZIP (Java >= 1.1). A template molecule is automatically converted to 2D if the mol2dcmd field contains one of the following values:
  • z=0 - for trivial conversion,
  • clean - for sophisticated 2D cleaning.
For automatic 3D conversion, the value of the mol3dcmd field must be
  • clean - for sophisticated 3D cleaning.
Templates may have abbreviations if the abbreviation fields are specified. 		click here
ttmpls0
ttmpls1
ttmpls2
... 		Templates to be displayed on the template toolbar. Same as tmpls but these template groups will also appear on the template toolbar by default. click here
template.2d Enables (true) or disables (false) to change the visible template groups on the Advanced Templates Toolbar.
When enabled, the visibility of all template groups can be altered using the Template Library.		 true
templateToolbarCustomizable Enables (true) or disables (false) to change the visible template groups on the Advanced Templates Toolbar.
When enabled, the visibility of all template groups can be altered using the Template Library.		 true
transferButtonIcon Sets the location of a custom icon for the Transfer action.  
transferButtonText Sets custom text for the Transfer action.  
transferButtonVisible Makes the Transfer button visible on the General Toolbar. false
viewonly Visualization mode: hide editing buttons; "true" or "false". false
verticalbar Deprecated.  
xtmpls File containing extra templates. Extra templates are placed beside the normal templates and they appear on the template toolbar by default. (see tmpls).  
2dviewerEnabled Enable (true) or disable(false) 2D viewer true
3dviewerEnabled Enable (true) or disable(false) 3D viewer true

1.1.2   Structure display parameters

ParameterMeaningDefault
absLabel Show (true) or hide (false) "Absolute" label  
atomFont Atom symbol/label font: Serif, SansSerif or Monospaced SansSerif
atomMappingVisible Show (true) or hide (false) atom mapping true
atomNumbersVisible Show (true) or hide (false) atom numbers false
atomsize Atom symbol font size in C-C bond length units:
atomsize*1.54 Å = atomsize*scale points
0.4
atomSymbolsVisible Show (true) or hide (false) atom symbols true
ballRadius Ball radius for "ballstick" rendering mode, in units of covalent radius. 0.5
bondLengthVisible Show (true) or hide (false) bond length labels false
bondSpacing Double bond spacing in C-C bond length units:
spacing*1.54 Å = spacing*scale pixels
0.18
chiralitySupport When to show atom chirality (R/S).
  • off - never
  • selected - if chiral flag is set for the molecule or the atom's enhanced stereo type is absolute
  • all - always
 off
colorScheme Color scheme.
  • mono - monochrome
  • cpk - Corey-Pauling-Kultun
  • shapely - shapely (residue types)
  • group - residue sequence numbers
 cpk
downWedge Wedge bond display convention. Down wedge points downward in MDL's convention (mdl), upward (at the chiral center) in Daylight's (daylight). mdl
explicitH Show (true) or hide (false) explicit hydrogens true
ezVisible Show (true) or hide (false) E/Z labels false
grinvVisible Show (true) or hide (false) graph invariants (canonical labels) false
implicitH How to display H labels.
  • off
  • hetero - on heteroatoms
  • heteroterm - on hetero or terminal atoms
  • all - all atoms
 heteroterm
lonePairsVisible Show (true) or hide (false) lone pairs false
lonePairsAutoCalc Switch on (true) or off (false) automatic calculation of lone pairs. The lonePairsVisible parameter should be set to true to display the result of the automatic calculation. false
maxscale Maximizes the magnification for autoscale to prevent overscaling of small molecules. It is usually set to 28, which is the scale factor for 100% magnification.  
reactionErrorVisible Deprecated. false
rendering Rendering style.
  • wireframe - wireframe
  • wireknobs - wireframe with knobs
  • sticks - 3D sticks
  • ballstick - ball & stick
  • spacefill - balls
 wireframe
rgroupsVisible Show (true) or hide (false) R-group definitions. true
scale Magnification. A 1.54 Å long C-C bond is magnified to scale pixels. 28
sketchAnyBond Display type of the Any bond in the sketcher:
  • auto - displayed as dashed line in most cases, solid line only when all bonds are generated from atom coordinates (e.g. XYZ and PDB files).
  • dashed - displayed as dashed line
  • solid - displayed as solid line
 auto
stickdst Stick distance of atoms in C-C bond length units. 0.3
showSets Show the specified atom sets only. Comma separated list of set sequence numbers (0, ..., 63).  
sketchCarbonVisibility Display the label of carbon atoms in structures.
  • on - Always show the atom labels of carbon atoms.
  • off - Never show the atom labels of carbon atoms.
  • inChain - Show the atom labels of carbon atoms at straight angles and at implicit Hydrogens.
inChain
stickThickness 3D stick diameter for "sticks" and "ballstick" rendering modes, in Angstroms. 0.1
valenceErrorVisible Highlight (by underlining) the labels of those atoms with valence errors. This option can also be set on the Edit/Preferences/MarvinSketch panel.
  • true - display errors
  • false - do not display errors
 true
viewAnyBond Display type of the Any bond in the viewer:
  • auto - displayed as dashed line in most cases, solid line only when all bonds are generated from atom coordinates (e.g. XYZ and PDB files).
  • dashed - displayed as dashed line
  • solid - displayed as solid line
 auto
wireThickness Line thickness for "wireframe" and "wireknobs" rendering modes, in Angstroms. 0.064

1.1.3   Structure parameters

ParameterMeaningDefault
atomSetColor0
atomSetColor1
...
atomSetColor63		 Atom set color as hexadecimal value.  
bondSetColor1
...
bondSetColor63		 Bond set color as hexadecimal value.  
importConv Conversion(s) after molecule loading. Currently the following options are implemented:
"a" or "+a"     General aromatization
"a_bas" or "+a_bas"     Basic aromatization
"-a" dearomatization
"H" or "+H"     add explicit H atoms
"-H" remove explicit H atoms
"c" automatic cleaning
  
cleanDim Number of space dimensions for cleaning.
  • 2 - two-dimensional cleaning
  • 3 - three-dimensional cleaning
See also: cleanOpts, importConv.		 2
cleanOpts Options for 2D or 3D cleaning.
cleanOpts accepts the same parameter values as clean2dOpts or clean3dOpts depending on the cleaning dimension (cleanDim). 		 
clean2dOpts Options for 2D cleaning (0D->2D) See base 2D cleaning options  
clean3dOpts Options for 3D cleaning (0D->3D) See base 3D cleaning options  
setColoringEnabled Atom/bond set coloring. true

1.1.4   Other parameters

ParameterMeaningDefault
escapeChar Escape character to use for parsing the value of the mol parameter.  
abbrevgroups Replacing the built-in abbreviated group collection with a custom one. The parameter value is the location of the file containing the custom abbreviated groups.
Live applet example: MarvinSketch Example - Abbreviated groups		 chemaxon/marvin
/templates
/default.abbrevgroup
abbrevgroupsAllowed Enables/disables the usage of abbreviated groups. If the function is disabled, typing with the keyboard over the canvas will only allow changing atom and bond types.
Live applet example: MarvinSketch Example - Student Examination 		true
defaultSaveFormat Sets the default chemical file format in the Save As dialog. mrv
debug Debug mode. Possible values: 0, 1, 2. 0
menuconfig Specifies an alternative menu customization file location instead of the default .chemaxon/{MarvinSketch_version}/customization.xml (Unix) or chemaxon/{MarvinSketch_version}/customziation.xml (Windows) file under the user's home. Please note that if this parameter is used, the customizationEnabled parameter is automatically set to false.
If you use applet, the value of this parameter has to be an URL. It can be relative to the applet codebase (e.g. examples/applets/sketch/myconfig.xml). The applet codebase gives the location of the marvin directory on the server (e.g.: http://www.myserver.com/marvin). Of course, the config file can be located on an other server, in this case you have to give the absolute URL of the config file (e.g.: http://www.otherserver.com/marvin-config/myconfig.xml). 		 
mergedst Merge distance of atoms in C-C bond length units. 0.1
molFormat Default file format: mol, csmol, smiles, cxsmiles, cml, pdb, pov, sybyl, or xyz. mol
shortcuts Specifies an alternative shortcut customization file location instead of the default .chemaxon/{MarvinSketch_version}/shortcuts.xml (Unix) or chemaxon/{MarvinSketch_version}/shortcuts.xml (Windows) file under the user's home. Please note that if this parameter is used, the customizationEnabled parameter is defaults to false.  
sketchHelp MarvinSketch help contents. chemaxon/marvin/help
/sketch-index.html
sketchQuickHelp MarvinSketch quick help. chemaxon/marvin/help
/sketch.html
toolbarFloatable Setting this parameter to false makes the toolbars immovable. true
undo Maximum number of undo operations. 50
viewHelp MarvinView help contents. chemaxon/marvin/help
/view-index.html
viewQuickHelp MarvinView quick help. chemaxon/marvin/help
/view.html

Applet example: 

<applet CODE=MSketch WIDTH=480 HEIGHT=400>
<param NAME="background" VALUE="#cccccc>
<param NAME="molbg" VALUE="#ffffff">
<param NAME="implicitH" VALUE="hetero">
</applet>
Bean example: 
MSketchPane sketchPane = new MSketchPane();
sketchPane.setParams(
    "background=#cccccc\n"+
    "molbg=#ffffff\n"+
    "implicitH=hetero\n");

1.1   Applet only parameters

The following parameters are meaningful only for the applets (MSketch, JMSketch) and not for the JavaBean (MSketchPane).

ParameterMeaningDefault
menubar Enable the embedded menubar. true
buttonmenubar Enable menubar in button (/hide) mode if the menubar parameter is true. Combine it with the detach parameter to set the button mode.
True, to allow, false to deny menu bar on the big sketcher button.		 true
detach Detachment behavior. The value consists of some optional arguments: show/hide size, and maxscale. If more arguments are included, they must be separated by a comma.
To detach the sketcher from the web page and display it in a separate window, set "show".
To detach the sketcher without displaying the separate window, set "hide".
Both settings make the applet on the web page look like a molecule viewer.

The initial size of the sketcher window can be specified with "size=widthxheight"
Examples: "show", "size=500x500", "hide,size=500x500".
In case the maxscale argument is set, it can prevent small molecules to be overscaled on the button.
Example for maximum 100% magnification: "hide,maxscale=28"
Live applet example: MarvinSketch Example - Pure visualization mode 		size=444x350
undetachByX Sketcher window close (x) behavior.
false: always hide sketcher
true: replace viewer component by sketcher in web browser window if the applet is large enough (>= 400x300) 		true
mol The molecule file to be loaded at startup, as either a URL or the file itself (inline) in MDL mol, compressed mol, SMILES, SMARTS, etc format.
Newlines occurring in the string must be replaced or preceded by "\n" and backslashes are recommended to be escaped as "\\".
The file format and/or import options can be specified if one of the following forms is used:
"file{options}",
"file{MULTISET,options}",
"file{format:}",
"file{format:options}", or
"file{format:MULTISET,options}".
If the MULTISET option is specified, then a multi-molecule file is read into one molecule object containing multiple atom sets.
Examples: "foo.xyz{f1.4C4}", "foo.xyz.gz{gzip:xyz:MULTISET,f1.4C4}" 		 
preload Deprecated  
cacheMols Store loaded molecules in an internal cache (true or false). false
loadMols Comma-separated list of molfiles to preload. Useful for caching molecules in JavaScript "slideshows".  
usedJars Comma-separated list of additional jar files that can be used by the applet. The additional files have to be defined with their paths relative to the applet's base.  
imageSaveURL The URL of the cgi, jsp or asp file use to save the image posted by the applet to the server.
The cgi has to read the image from the standard input into a byte array, save it to a temporary file and send back the absolute path of the file to the applet.
A jsp example: saveimage.jsp 		 
imageSaveFormat The default file format for image saving. png
imageShowURL The URL of the cgi, jsp or asp file that either saves the data into a file generated by the applet or shows the generated image that was saved to a temporary file by imageSaveURL.
The posted parameters:
namedescription
filename If the applet generated an image, it was saved into a temporary file on the server. In this case this parameter contains the absolute path of the temporary file.
type Sets the type of the file and its extension.
It can be: "mol", "csmol", "pdb", "sybyl", "xyz", "jpeg", "png", "pov", "svg".
where Sets the location in which the image will be "shown"
Possible values: "file", "browser", null.
  • "file" - the generated data will be saved into a file.
  • "browser" - the data will be displayed in a browser window.
data If the applet generated a kind of molecule format file (see: formats), it is posted by this parameter. In this case the text file have to be saved as a file.
A jsp example: showimage.jsp 		 
molLoaderFinishedEvent Evaluates a JavaScript code after the loading of the molecule into the editor is finished. This "event" is invoked if molecule is loaded-in into the applet in any of the following cases:
  • Automaticaly, at applet starting: (using the mol applet parameter)
  • Calling (J)MSketch.setMol(...) from JavaScript.
Note: If the MAYSCRIPT option is not specified, JavaScript can not be evaluated from the applet. E.g.:
     msketch_mayscript=true;
     msketch_begin("marvin",400,300);
     msketch_param("mol","caffeine.mol");
     msketch_param("molLoaderFinishedEvent","js:alert('Molecule is loaded-in.')");
     msketch_end();
 
listenpropertychange Switch on/off property change event listener to the applet. If listener is active, the applet will call propertyChange(prop) JavaScript method. If you would like to handle property change events in JavaScript, implement this method in your html source. Note: If the MAYSCRIPT option is not specified, JavaScript can not be evaluated from the applet. E.g.:
     function propertyChange(prop) {
        if(document.textform != null) {
            var s = document.textform.txt.value;
            document.textform.txt.value = s + "\n" + prop;
        }
     }

     msketch_mayscript=true;
     msketch_begin("marvin",400,300);
     msketch_param("listenpropertychange","true");
     msketch_end();
If you also specify the "appletid" parameter, its value will appear in the name of the property as prefix (e.g.: "firstapplet.mol"). 		false
appletid Identify applet in property change event notifications to JavaScript. Use this parameter with listenpropertychange when more than one applet are located on the same web page. It helps to identify which applet sent the notification.
skin Change the component's Look & Feel (only in SWING applet). If you do not specify this parameter, Marvin will use the default LookAndFeel style.
This parameter value is the name of the new LookAndFeel class. 		javax.swing.plaf
.metal
.MetalLookAndFeel
splashScreenImage Change the component's splash screen displayed at startup. If you do not specify this parameter, Marvin will use its default splash screen.
This parameter value is the relative path of the image, specify relatively to the CODEBASE
Note: Animated gif files can be displayed badly (flashing, or too fast animation) 		null
license Sets the contents of a pre-read license file to the license manager to read and validate licenses from.  
licenseFile Sets the license file location to the license manager to read and validate licenses from.  
legacy_lifecycle The "legacy_lifecycle" is a general Java applet parameter. If its value is true, it helps avoid destroying the applet when you leaves the applet page. If you use "marvin.js", it sets its value to true automatically unless you specify its value explicitly. By the way, the default value of this parameter in Java is false. See the discussion about it on the forum.  
preload You can specifies modules to load them in advance before startup of the MarvinSketch applet. The value of this parameter is the comman separated list of modules. The order of modules determine which module is loaded earlier and which one is loaded later. You can choose from the following modules.  
bgloadPriority You can specify the order of the modules for background loading. After startup of MarvinSketch, modules that are not used yet are started downloading in the background to fast up their initalization of their first usage. The value of this parameter is a comma separated list of modules that get priority for loading. You can choose from the following modules. See also bgloadEnabled.  
bgloadEnabled Let or deny loading of rest of modules in a background thread after startup. Set this parameter to true to accept background loading. Set it to false if you would like to reject this functionality. true

2   Events fired by the JavaBean

2.1   Action events

To handle the action events of MSketchPane, the java.awt.event.ActionListener interface must be implemented.

Source nameSource component typeMeaning
"close" javax.swing.JMenuItem File/Close has been chosen, sketcher window should be closed.

Example: 

sketchPane.addActionListener(this);
    ...

public void actionPerformed(ActionEvent ev) {
    if(ev.getSource() instanceof JComponent) {
	String name = ((JComponent)ev.getSource()).getName();
	if(name.equals("close")) {
	    dispose();
	}
    }
}

2.2   Property change events

To handle the property change events of MSketchPane, the java.beans.PropertyChangeListener interface must be implemented.

Property nameTypeMeaning
"mol" Molecule The molecule is replaced or altered.
"file" java.io.File Molecule file changed from File/Open or File/Save As.
"implicitH" String Implicit Hydrogen display style changed.
"explicitH" Boolean Explicit Hydrogen display style changed.
true: show explicit H atoms
false: hide explicit H atoms
"colorScheme" String Color scheme changed.
"autoscale" Boolean Autoscale changed.
"rendering" String Rendering style changed.
"wireThickness" Double Wire thickness changed.
"stickThickness" Double Sticks diameter changed.
"ballRadius" Double Ball radius changed.
"grinvVisible" Boolean Graph invariants displayed/not displayed.
"downWedge" String Down wedge bond orientation changed.
"objectAtPointer" Object The MolAtom or MolBond object at the mouse pointer.
"invisibleSets" Long Visibility of atom sets changed.
"atomNumbersVisible" Boolean Visibility of atom numbers changed.
"atomMappingVisible" Boolean Visibility of atom mapping changed.
"popupMenusEnabled" Boolean Popup menus are enabled/disabled.
"valenceErrorVisible" Boolean Visibility of valence errors changed.
"reactionErrorVisible" Boolean Visibility of reaction errors changed.

Example: 

    sketchPane.addPropertyChangeListener(this);
    ...

public void propertyChange(PropertyChangeEvent ev) {
    String name = ev.getPropertyName();
    if(name.equals("file")) {
	File f = (File)ev.getNewValue();
	if(f != null)
	    setTitle("MarvinSketch: "+f.getName());
    }
}