Difference between revisions of "Mouse Manual"

From Jmol
Jump to navigation Jump to search
(Whole-molecule atom shifting and rotation on touch-only interfaces)
 
(15 intermediate revisions by 3 users not shown)
Line 141: Line 141:
 
<br />
 
<br />
  
To toggle the selection status of individula atoms:<br>
+
To toggle the selection status of individual atoms:<br>
 
Using the menus:
 
Using the menus:
 
<ol>
 
<ol>
Line 173: Line 173:
  
 
== How to change atom coordinates ==
 
== How to change atom coordinates ==
This section describes how to move individual atoms within a model
+
This section describes how to set up a Jmol applet or application so that users can move individual atoms within a model
 
with the mouse.
 
with the mouse.
  
Transformations like rotations or translations are normally applied to all atoms identically. And the stored coordinates of the
+
By default, mouse-based transformations such as rotations and translations are applied to all atoms identically. All that is happening is that the view ("the tranformation matrix, ('''show transform''')" is modified; the stored coordinates of the atoms are not changed. But Jmol can also be configured to allow users to move specific atoms or sets of atoms and store the changed coordinates permanently.
atoms are not changed. But Jmol can also be configured to move some
 
atoms individually and store the changed coordinates permanently.
 
  
There are two modes available:
+
In situations where it is desired to allow users to change atom coordinates using the mouse, certain settings must be made. This section summarizes the rather complex mix of possible settings and some of the  standard combinations that are particularly useful
# Moving only whole molecules, e.g. a whole chain
 
# Moving atoms independent of their connectivity
 
  
This section concentrates on the second mode. The two following
+
=== Default settings ===
settings are needed to activate it:
 
# [http://chemapps.stolaf.edu/jmol/docs/#k969 set allowMoveAtoms] on;
 
# [http://chemapps.stolaf.edu/jmol/docs/#k971 set allowRotateSelected] on;
 
  
There are additional switches available that influence what can be
+
The five settings involved and their default values are given below.
done and how it can be done:
+
 
# [http://chemapps.stolaf.edu/jmol/docs/#setpicking set picking]
+
[{{ScriptingDoc}}#setpicking set picking identify]
# [http://chemapps.stolaf.edu/jmol/docs/#setpickingstyle set pickingStyle]
+
 
# [http://chemapps.stolaf.edu/jmol/docs/#k993 set dragSelected]
+
[{{ScriptingDoc}}#setpickingstyle set pickingStyle toggle]
 +
 
 +
[{{ScriptingDoc}}#set_dragselected set dragSelected false]
 +
 
 +
[{{ScriptingDoc}}#set_allowrotateselected set allowRotateSelected false]
 +
 
 +
[{{ScriptingDoc}}#set_allowmoveatoms set allowMoveAtoms false];
 +
 
 +
The names of these settings are not necessarily self-explanatory. '''set picking identify''' just means that when an atom is clicked, a message is posted to the Jmol console indicating the identity of the atom picked. '''set pickingStyle toggle''' specifies the overall standard Jmol mouse bindings (but see below for a "drag" option); '''set dragSelected false''' species, within that framework, what is to happen with simple left-mouse dragging. The two '''alllow...''' settings allow restricting atom motion in ways described below.
 +
 
 +
=== Allowing whole-molecule atom shifting and rotation ===
 +
 
 +
A common need is to enable users to translate and rotate whole molecules just by clicking on them and dragging. In this way, all intramolecular relationships remain the same, and bonds are not destroyed. This is enabled using
 +
 
 +
'''set picking dragMolecule'''
 +
 
 +
The standard Jmol mouse operations are still present when the mouse is pressed off the structure, but when it is pressed on an atom, then left-drag moves that specific molecule, and alt-drag rotates that molecule around its center of geometry.
 +
 
 +
=== Whole-molecule atom shifting and rotation on touch-only interfaces ===
 +
 
 +
If it is desired to have an interface where users do not need to use ALT (for example, mobile touch-only interfaces such as tablets and smartphones), you will need to provide three buttons that toggle among modes. This requires use of the
 +
[{{ScriptingDoc}}#bind bind] and
 +
[{{ScriptingDoc}}#bind unbind]
 +
commands, which modify how mouse actions are bound to Jmol actions.
 +
This can be accomplished as follows.
 +
 
 +
Button 1 (reset):
 +
 
 +
script: '''unbind; set picking identify'''
 +
 
 +
Button 2 (translate molecule):
 +
 
 +
script '''unbind;set picking dragMolecule'''
 +
 
 +
Button 3 (rotate molecule):
 +
 
 +
script: '''set picking dragMolecule; set allowrotateselected; unbind "_dragAtom"; unbind "_rotateSelected"; bind "left+drag" _rotateSelected'''
 +
 
 +
Notice that what we are doing here is
 +
 
 +
# removing Jmol's _dragAtom binding, which is left-drag for the dragMolecule picking mode
 +
# replacing the alt-left-drag binding for _rotateSelected with a simple left-drag
 +
 
 +
=== Allowing moving and rotating of specific atoms ===
 +
 
 +
It is not always desired to restrict atom coordinate changes to whole molecules (for example, when proteins with associated water molecules are involved.) But then we need some indication of which atoms are to be moved. This is done by a number of possible means.
 +
 
 +
'''selected atoms''' Perhaps the simplest is to use the currently selected atom set. This is done by adding '''set allowMoveAtoms true'''.
 +
 +
[Note: a design flaw and associated bug in Jmol prior to 14.3.13 results in the odd behavior that setting '''allowMoveAtoms''' surreptitiously also sets both '''dragSelected''' and '''allowRotateSelected''' to the same values internally (the design flaw) ''without indicating that'' (the bug). This has been very confusing and is fixed for future versions.]
 +
 
 +
 
 +
=== Additional options ===
 +
 
 +
The table below summarizes additional options that involve how atoms are selected using special mouse settings. The following two settings are assumed:
 +
 
 +
'''set allowMoveAtoms TRUE'''
 +
 
 +
'''set allowRotateSelected TRUE'''
 +
 
 +
There are additional switches available that influence what can be done and how it can be done. Unless otherwise specified, their values are:
 +
# [{{ScriptingDoc}}#setpicking set picking IDENTIFY]
 +
# [{{ScriptingDoc}}#setpickingstyle set pickingStyle TOGGLE]
 +
# [{{ScriptingDoc}}#set_dragselected set dragSelected FALSE]
  
 
The table below summarizes information for three of the possible
 
The table below summarizes information for three of the possible
Line 203: Line 259:
 
       <th colspan="9" style="background-color: rgb(245,235,210); text-align: left; padding:0.4em;">Basic options:
 
       <th colspan="9" style="background-color: rgb(245,235,210); text-align: left; padding:0.4em;">Basic options:
 
<ul style="margin: 0.5em;">
 
<ul style="margin: 0.5em;">
  <li>[http://chemapps.stolaf.edu/jmol/docs/#k969 set allowMoveAtoms] on;</li>
+
  <li>'''set allowMoveAtoms TRUE'''</li>
  <li>[http://chemapps.stolaf.edu/jmol/docs/#k971 set allowRotateSelected] on;</li>
+
  <li>'''set allowRotateSelected TRUE'''</li>
 
</ul>
 
</ul>
 +
Helpful option:
 +
        <ul style="margin: 0.5em;">
 +
  <li>[{{ScriptingDoc}}#selectionhalos selectionHalos ON]</li>
 +
        </ul>
 
       </th>
 
       </th>
 
     </tr>
 
     </tr>
 
     <tr>
 
     <tr>
 
       <th></th>
 
       <th></th>
       <th colspan="3" style="background-color: rgb(240,240,240); text-align: left; padding:0.4em;">Option Set 1:
+
       <th colspan="3" style="background-color: rgb(240,240,240); text-align: left; padding:0.4em;" valign="top">Option 1: Allows changing coordinates
 +
 
 
<ul style="margin: 0.5em;">
 
<ul style="margin: 0.5em;">
  <li>[http://chemapps.stolaf.edu/jmol/docs/#setpicking set picking] dragSelected;</li>
+
  <li>'''set picking dragSelected'''</li>
  <li>[http://chemapps.stolaf.edu/jmol/docs/#setpickingstyle set pickingStyle] select toggle;</li>
 
  <li>[http://chemapps.stolaf.edu/jmol/docs/#k993 set dragSelected] off;</li>
 
 
</ul>
 
</ul>
 +
<br><br><b>
 +
Selecting atoms: no mouse binding
 +
<br><br>
 +
Changing Coordinates: move and rotate selected atoms
 +
<br><br></b>
 +
When the mouse is not over the structure, acts the same as Jmol defaults; when it is over the structure,
 +
binds drag, alt-drag, and shift-drag with movement in the plane of the screen, rotation, and movement perpendicular to the screen, respectively.
 +
 
       </th>
 
       </th>
       <th colspan="3" style="background-color: rgb(220,200,190); text-align: left; padding:0.4em;">Option Set 2:
+
       <th colspan="3" style="background-color: rgb(220,200,190); text-align: left; padding:0.4em;" valign="top">Option 2: Allows picking by dragging as well as changing coordinates
 +
 
 
<ul style="margin: 0.5em;">
 
<ul style="margin: 0.5em;">
  <li>[http://chemapps.stolaf.edu/jmol/docs/#setpicking set picking] dragSelected;</li>
+
  <li>'''set pickingStyle select drag'''</li>
  <li>[http://chemapps.stolaf.edu/jmol/docs/#setpickingstyle set pickingStyle] select drag;</li>
+
  <li>'''set picking dragSelected'''</li>
  <li>[http://chemapps.stolaf.edu/jmol/docs/#k993 set dragSelected] off;</li>
 
 
</ul>
 
</ul>
 +
<br><b>
 +
Selecting atoms: alt/shift-drag to select a box of atoms
 +
<br><br>
 +
Changing Coordinates: drag to move atoms; no rotation
 +
<br><br></b>
 +
 +
Selecting atoms: Binds shift-drag and alt-shift drag to "add to selection" and "remove from selection", respectively, and shift-drag to "add or toggle." Moving atoms: When the mouse is not over the structure, drag changes orientation in a standard Jmol way; when the mouse is over the structure, binds drag to "drag the structure" thus changing coordinates. Does not implement rotate.
 +
 
       </th>
 
       </th>
       <th colspan="3" style="background-color: rgb(180,245,220); text-align: left; padding:0.4em;">Option Set 3:
+
       <th colspan="3" style="background-color: rgb(180,245,220); text-align: left; padding:0.4em;" valign="top">Option 3: Allows picking by clicking as well as changing coordinates
 
<ul style="margin: 0.5em;">
 
<ul style="margin: 0.5em;">
  <li>[http://chemapps.stolaf.edu/jmol/docs/#setpicking set picking] atom;</li>
+
  <li>'''set picking ATOM'''</li>
  <li>[http://chemapps.stolaf.edu/jmol/docs/#setpickingstyle set pickingStyle] select toggle;</li>
+
  <li>'''set dragSelected TRUE'''</li>
  <li>[http://chemapps.stolaf.edu/jmol/docs/#k993 set dragSelected] on;</li>
 
 
</ul>
 
</ul>
 +
<br><b>
 +
Selecting atoms: click/double-click to select
 +
<br><br>
 +
Changing Coordinates: alt/shift-drag to rotate/move
 +
<br><br></b>
 +
Selecting atoms: Clicking on an atom (or group, or chain, etc., based on <b>set picking</b> option) toggles its selection on or off; double-clicking selects this item and deselects all others. Binds alt-drag to rotate and alt-shift-drag to move atoms.
 
       </th>
 
       </th>
 
     </tr>
 
     </tr>

Latest revision as of 10:55, 8 May 2015

Jmol / JSmol Tutorials

Geographylogo.png

Reference: English – Other: Español · Français · 日本語 ·


Manual for manipulating the molecules using the mouse in Jmol (also called 'mouse gestures')

Notes:

  1. In the usual configuration, "main button" is the left button, and "secondary button" is the right button.
  2. Reportedly, on single-button mice Alt drag may be equivalent to drag with middle button.


main button middle button secondary button
(left) (middle) (right)
Open Jmol menu Ctrl + click
or click on 'Jmol' logo
click
Rotate around X,Y drag
Move along X,Y (= translate) Shift + double-click and drag double-click and drag Ctrl + drag
works both when clicking on the molecule or away from it
Reset and centre Shift + double-click* double-click*
*only works if double-click is done away from the molecule
Rotate around Z Shift + drag horizontally drag horizontally Shift + drag horizontally
(possibly fails in Mac's)
Zoom in / out Shift + drag vertically drag vertically
or use mouse wheel
Implemented only on Jmol 10.00.22 prerelease and later:
Only work after a slab on command has been issued
Slab (slab from front) Ctrl+Shift + drag (vertically) *
Depth (slab from back) Ctrl+Shift + double-click and drag (vertically) *
Shift the slab (change slab and depth maintaining constant thickness) Alt+Ctrl+Shift + drag (vertically) *
*if this fails on a Mac, try pressing the mouse button first, then the Ctrl Shift keys, then drag
Slab can be tested in this page



How to select

  • Use the appropriate picking command, e.g.

set picking group

to toggle selection for an entire amino acid by clicking on one of its atoms,
  • Click on an atom will toggle selection status.
  • Most useful while

set display selected

is set to monitor the selection status.


To toggle the selection status of individual atoms:
Using the menus:

  1. Jmol->Main Menu->Select->Selection Halos (This is optional but very helpful. It shows you which atoms are selected by plaing a golden ring around it.)
  2. Jmol->Main Menu->Select->None (Needed because "select all" is the default at load time. Notice the non-zero number in parenthesis after the word select in the main menu. That is the number of items currently selected.
  3. Jmol->Main Menu->Set picking->Select Atom

Now click an atom once to select, click again to deselect. The halos let me know the current selection state of each atom and the count in parenthesis after the Select in Jmol->Main Menu gives me a count of the number of atoms selected.

How to make measurements

  • Distance (2 atoms):
    1. double-click on the starting atom
    2. to fix a distance measurement, double-click on second atom
  • Angle (3 atoms):
    1. double-click on the starting atom
    2. click on the second atom (central atom in angle)
    3. to fix an angle measurement, double-click on third atom
  • Torsion angle or dihedral (4 atoms)
    1. double-click on the starting atom
    2. click on the second atom
    3. click on the third atom
    4. to fix a dihedral angle measurement, double-click on fourth atom
  • In all cases:
    • move pointer over destination atom in order to see measurement results without leaving a permanent measurement
    • move outside the window in order to cancel the measurement
    • make the same measurement again in order to delete the measurement

How to change atom coordinates

This section describes how to set up a Jmol applet or application so that users can move individual atoms within a model with the mouse.

By default, mouse-based transformations such as rotations and translations are applied to all atoms identically. All that is happening is that the view ("the tranformation matrix, (show transform)" is modified; the stored coordinates of the atoms are not changed. But Jmol can also be configured to allow users to move specific atoms or sets of atoms and store the changed coordinates permanently.

In situations where it is desired to allow users to change atom coordinates using the mouse, certain settings must be made. This section summarizes the rather complex mix of possible settings and some of the standard combinations that are particularly useful

Default settings

The five settings involved and their default values are given below.

set picking identify

set pickingStyle toggle

set dragSelected false

set allowRotateSelected false

set allowMoveAtoms false;

The names of these settings are not necessarily self-explanatory. set picking identify just means that when an atom is clicked, a message is posted to the Jmol console indicating the identity of the atom picked. set pickingStyle toggle specifies the overall standard Jmol mouse bindings (but see below for a "drag" option); set dragSelected false species, within that framework, what is to happen with simple left-mouse dragging. The two alllow... settings allow restricting atom motion in ways described below.

Allowing whole-molecule atom shifting and rotation

A common need is to enable users to translate and rotate whole molecules just by clicking on them and dragging. In this way, all intramolecular relationships remain the same, and bonds are not destroyed. This is enabled using

set picking dragMolecule

The standard Jmol mouse operations are still present when the mouse is pressed off the structure, but when it is pressed on an atom, then left-drag moves that specific molecule, and alt-drag rotates that molecule around its center of geometry.

Whole-molecule atom shifting and rotation on touch-only interfaces

If it is desired to have an interface where users do not need to use ALT (for example, mobile touch-only interfaces such as tablets and smartphones), you will need to provide three buttons that toggle among modes. This requires use of the bind and unbind commands, which modify how mouse actions are bound to Jmol actions. This can be accomplished as follows.

Button 1 (reset):

script: unbind; set picking identify

Button 2 (translate molecule):

script unbind;set picking dragMolecule

Button 3 (rotate molecule):

script: set picking dragMolecule; set allowrotateselected; unbind "_dragAtom"; unbind "_rotateSelected"; bind "left+drag" _rotateSelected

Notice that what we are doing here is

  1. removing Jmol's _dragAtom binding, which is left-drag for the dragMolecule picking mode
  2. replacing the alt-left-drag binding for _rotateSelected with a simple left-drag

Allowing moving and rotating of specific atoms

It is not always desired to restrict atom coordinate changes to whole molecules (for example, when proteins with associated water molecules are involved.) But then we need some indication of which atoms are to be moved. This is done by a number of possible means.

selected atoms Perhaps the simplest is to use the currently selected atom set. This is done by adding set allowMoveAtoms true.

[Note: a design flaw and associated bug in Jmol prior to 14.3.13 results in the odd behavior that setting allowMoveAtoms surreptitiously also sets both dragSelected and allowRotateSelected to the same values internally (the design flaw) without indicating that (the bug). This has been very confusing and is fixed for future versions.]


Additional options

The table below summarizes additional options that involve how atoms are selected using special mouse settings. The following two settings are assumed:

set allowMoveAtoms TRUE

set allowRotateSelected TRUE

There are additional switches available that influence what can be done and how it can be done. Unless otherwise specified, their values are:

  1. set picking IDENTIFY
  2. set pickingStyle TOGGLE
  3. set dragSelected FALSE

The table below summarizes information for three of the possible setting combinations (tested in Jmol 14.3.13).

Basic options:
  • set allowMoveAtoms TRUE
  • set allowRotateSelected TRUE

Helpful option:

Option 1: Allows changing coordinates
  • set picking dragSelected



Selecting atoms: no mouse binding

Changing Coordinates: move and rotate selected atoms

When the mouse is not over the structure, acts the same as Jmol defaults; when it is over the structure, binds drag, alt-drag, and shift-drag with movement in the plane of the screen, rotation, and movement perpendicular to the screen, respectively.

Option 2: Allows picking by dragging as well as changing coordinates
  • set pickingStyle select drag
  • set picking dragSelected


Selecting atoms: alt/shift-drag to select a box of atoms

Changing Coordinates: drag to move atoms; no rotation

Selecting atoms: Binds shift-drag and alt-shift drag to "add to selection" and "remove from selection", respectively, and shift-drag to "add or toggle." Moving atoms: When the mouse is not over the structure, drag changes orientation in a standard Jmol way; when the mouse is over the structure, binds drag to "drag the structure" thus changing coordinates. Does not implement rotate.

Option 3: Allows picking by clicking as well as changing coordinates
  • set picking ATOM
  • set dragSelected TRUE


Selecting atoms: click/double-click to select

Changing Coordinates: alt/shift-drag to rotate/move

Selecting atoms: Clicking on an atom (or group, or chain, etc., based on set picking option) toggles its selection on or off; double-clicking selects this item and deselects all others. Binds alt-drag to rotate and alt-shift-drag to move atoms.

Click Type Click Target Comment Click Type Click Target Comment Click Type Click Target Comment
Atom Movement (only selected atoms)
x/y-shift
(along screen axes)
drag any atom drag any atom shift-alt-drag anywhere
z-shift
(perpendicular to screen)
shift-drag any atom not available not available
rotate alt-drag any atom not available alt-drag anywhere
Atom Selection
select a single atom not available shift-drag around an unselected atom click an unselected atom
alt-drag around an atom double-click an atom other atoms are deselected
deselect a single atom not available shift-drag around a selected atom click a selected atom
select multiple atoms not available shift-drag around unselected atoms not available
alt-drag around atoms
deselect multiple atoms not available shift-drag around selected atoms not available
Summary

Option set 1 (+ basic options) totally disables mouse-based selection changes and enables all three movement types (x/y-shift, z-shift, rotate).

Option set 2 (+ basic options) enables mouse-based single/multiple atom selection changes and enables only one movement type (x/y-shift).

Option set 3 (+ basic options) enables mouse-based single atom selection changes and enables two movement types (x/y-shift, rotate).