mol-plugin: Help panel

src/mol-plugin/skin/base/components/misc.scss

@@ -120,4 +120,15 @@
         position: absolute;
         line-height: $row-height;
     }
+}
+
+.msp-simple-help-section {
+    height: 28px;
+    line-height: 28px;
+    margin-top: 5px;
+    margin-bottom: 5px;
+    padding: 0 10px;
+    font-weight: 500;
+    background: $default-background; 
+    color: $font-color;
 }

src/mol-plugin/skin/base/components/viewport.scss

@@ -74,12 +74,12 @@
     height: 100%;
 }
 
-.msp-viewport-controls-scene-options {
+.msp-viewport-controls-panel {
     overflow-y: auto;
     max-height: 400px;
     width: 290px;
     top: 0;
-    right: $row-height + $control-spacing;
+    right: $row-height + 1px;
     position: absolute;
     background: $control-background;
 

src/mol-plugin/ui/controls/common.tsx

@@ -8,16 +8,28 @@ import * as React from 'react';
 import { Color } from '../../../mol-util/color';
 import { PurePluginUIComponent } from '../base';
 
-export class ControlGroup extends React.Component<{ header: string, initialExpanded?: boolean, hideExpander?: boolean, hideOffset?: boolean }, { isExpanded: boolean }> {
+export class ControlGroup extends React.Component<{
+    header: string,
+    initialExpanded?: boolean,
+    hideExpander?: boolean,
+    hideOffset?: boolean,
+    onHeaderClick?: () => void
+}, { isExpanded: boolean }> {
     state = { isExpanded: !!this.props.initialExpanded }
 
-    toggleExpanded = () => this.setState({ isExpanded: !this.state.isExpanded });
+    headerClicked = () => {
+        if (this.props.onHeaderClick) {
+            this.props.onHeaderClick();
+        } else {
+            this.setState({ isExpanded: !this.state.isExpanded });
+        }
+    }
 
     render() {
         // TODO: customize header style (bg color, togle button etc)
         return <div className='msp-control-group-wrapper'>
             <div className='msp-control-group-header'>
-                <button className='msp-btn msp-btn-block' onClick={this.toggleExpanded}>
+                <button className='msp-btn msp-btn-block' onClick={this.headerClicked}>
                     {!this.props.hideExpander && <span className={`msp-icon msp-icon-${this.state.isExpanded ? 'collapse' : 'expand'}`} />}
                     {this.props.header}
                 </button>

src/mol-plugin/ui/viewport.tsx

@@ -12,27 +12,34 @@ import { ParamDefinition as PD } from '../../mol-util/param-definition';
 import { PluginUIComponent } from './base';
 import { ControlGroup, IconButton } from './controls/common';
 import { SimpleSettingsControl } from './viewport/simple-settings';
+import { HelpContent } from './viewport/help';
 
 interface ViewportControlsState {
-    isSettingsExpanded: boolean
+    isSettingsExpanded: boolean,
+    isHelpExpanded: boolean
 }
 
 interface ViewportControlsProps {
-    hideSettingsIcon?: boolean
 }
 
 export class ViewportControls extends PluginUIComponent<ViewportControlsProps, ViewportControlsState> {
     state = {
         isSettingsExpanded: false,
-    }
+        isHelpExpanded: false
+    };
 
     resetCamera = () => {
         PluginCommands.Camera.Reset.dispatch(this.plugin, {});
     }
 
-    toggleSettingsExpanded = (e: React.MouseEvent<HTMLButtonElement>) => {
-        this.setState({ isSettingsExpanded: !this.state.isSettingsExpanded });
-        e.currentTarget.blur();
+    toggleSettingsExpanded = (e?: React.MouseEvent<HTMLButtonElement>) => {
+        this.setState({ isSettingsExpanded: !this.state.isSettingsExpanded, isHelpExpanded: false });
+        e?.currentTarget.blur();
+    }
+
+    toggleHelpExpanded = (e?: React.MouseEvent<HTMLButtonElement>) => {
+        this.setState({ isSettingsExpanded: false, isHelpExpanded: !this.state.isHelpExpanded });
+        e?.currentTarget.blur();
     }
 
     toggleControls = () => {
@@ -82,10 +89,16 @@ export class ViewportControls extends PluginUIComponent<ViewportControlsProps, V
                 {this.icon('screenshot', this.screenshot, 'Download Screenshot')}
                 {this.icon('tools', this.toggleControls, 'Toggle Controls', this.plugin.layout.state.showControls)}
                 {this.icon('expand-layout', this.toggleExpanded, 'Toggle Expanded', this.plugin.layout.state.isExpanded)}
-                {!this.props.hideSettingsIcon && this.icon('settings', this.toggleSettingsExpanded, 'Settings', this.state.isSettingsExpanded)}
+                {this.icon('help-circle', this.toggleHelpExpanded, 'Help', this.state.isHelpExpanded)}
+                {this.icon('settings', this.toggleSettingsExpanded, 'Settings', this.state.isSettingsExpanded)}
             </div>
-            {this.state.isSettingsExpanded && <div className='msp-viewport-controls-scene-options'>
-                <ControlGroup header='Basic Settings' initialExpanded={true} hideExpander={true} hideOffset={true}>
+            {this.state.isHelpExpanded && <div className='msp-viewport-controls-panel'>
+                <ControlGroup header='Help' initialExpanded={true} hideExpander={true} hideOffset={true} onHeaderClick={this.toggleHelpExpanded}>
+                    <HelpContent />
+                </ControlGroup>
+            </div>}
+            {this.state.isSettingsExpanded && <div className='msp-viewport-controls-panel'>
+                <ControlGroup header='Basic Settings' initialExpanded={true} hideExpander={true} hideOffset={true} onHeaderClick={this.toggleSettingsExpanded}>
                     <SimpleSettingsControl />
                 </ControlGroup>
                 {/* <ControlGroup header='Layout' initialExpanded={true}>

src/mol-plugin/ui/viewport/help.tsx

@@ -0,0 +1,170 @@
+/**
+ * Copyright (c) 2019 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import * as React from 'react';
+import { Binding } from '../../../mol-util/binding';
+import { PluginUIComponent } from '../base';
+import { StateTransformer, StateSelection } from '../../../mol-state';
+import { SelectLoci } from '../../behavior/dynamic/representation';
+import { StructureRepresentationInteraction } from '../../behavior/dynamic/selection/structure-representation-interaction';
+import { Icon } from '../controls/common';
+
+function getBindingsList(bindings: { [k: string]: Binding }) {
+    return Object.keys(bindings).map(k => [k, bindings[k]] as [string, Binding])
+}
+
+class BindingsHelp extends React.Component<{ bindings: { [k: string]: Binding } }, { isExpanded: boolean }> {
+    getBindingComponents() {
+        const bindingsList = getBindingsList(this.props.bindings)
+        return <ul style={{ paddingLeft: '20px' }}>
+            {bindingsList.map(value => {
+                const [name, binding] = value
+                return !Binding.isEmpty(binding)
+                    ? <li key={name}>{Binding.format(binding, name)}</li>
+                    : null
+            })}
+        </ul>
+    }
+
+    render() {
+        return <HelpText>{this.getBindingComponents()}</HelpText>
+    }
+}
+
+class HelpText extends React.PureComponent {
+    render() {
+        return <div className='msp-control-row msp-help-text'>
+            <div>{this.props.children}</div>
+        </div>
+    }
+}
+
+class HelpGroup extends React.Component<{ header: string, initiallyExpanded?: boolean }, { isExpanded: boolean }> {
+    state = {
+        header: this.props.header,
+        isExpanded: !!this.props.initiallyExpanded
+    }
+
+    toggleExpanded = () => this.setState({ isExpanded: !this.state.isExpanded });
+
+    render() {
+        return <div className='msp-control-group-wrapper'>
+            <div className='msp-control-group-header'>
+                <button className='msp-btn msp-btn-block' onClick={this.toggleExpanded}>
+                    <span className={`msp-icon msp-icon-${this.state.isExpanded ? 'collapse' : 'expand'}`} />
+                    {this.props.header}
+                </button>
+            </div>
+            {this.state.isExpanded && <div className='msp-control-offset' style={{ display: this.state.isExpanded ? 'block' : 'none' }}>
+                {this.props.children}
+            </div>}
+        </div>
+    }
+}
+
+function HelpSection(props: { header: string }) {
+    return <div className='msp-simple-help-section'>{props.header}</div>;
+}
+
+export class HelpContent extends PluginUIComponent {
+    componentDidMount() {
+        this.subscribe(this.plugin.events.canvas3d.settingsUpdated, () => this.forceUpdate());
+    }
+
+    private getMouseBindingComponents() {
+        const interactionBindings: { [k: string]: Binding } = {}
+        this.plugin.spec.behaviors.forEach(b => {
+            const { bindings } = b.defaultParams
+            if (bindings) Object.assign(interactionBindings, bindings)
+        })
+        return <>
+            {this.plugin.canvas3d && <HelpGroup key='trackball' header='Moving in 3D'>
+                <BindingsHelp bindings={this.plugin.canvas3d.props.trackball.bindings} />
+            </HelpGroup>}
+            <HelpGroup key='interactions' header='Select, Highlight, Focus'>
+                <BindingsHelp bindings={interactionBindings} />
+            </HelpGroup>
+        </>
+    }
+
+    private formatTriggers(binding: Binding) {
+        return binding.triggers.map(t => Binding.Trigger.format(t)).join(' or ')
+    }
+
+    private getTriggerFor(transformer: StateTransformer, name: string) {
+        const state = this.plugin.state.behaviorState
+        const selections = state.select(StateSelection.Generators.ofTransformer(transformer))
+        const params = selections.length === 1 ? selections[0].params : undefined
+        const bindings = params ? params.values.bindings : {}
+        const binding: Binding = name in bindings ? bindings[name] : Binding.Empty
+        return this.formatTriggers(binding)
+    }
+
+    render() {
+        const selectToggleTriggers = this.getTriggerFor(SelectLoci, 'clickSelectToggle')
+        const structureInteractionTriggers = this.getTriggerFor(StructureRepresentationInteraction, 'clickInteractionAroundOnly')
+        // const volumeAroundTriggers = this.getTriggerFor(StructureRepresentationInteraction, 'clickInteractionAroundOnly') // TODO get from correct behavior transform
+
+        // TODO: interactive help, for example for density
+
+        return <div>
+            <HelpSection header='Interface Controls' />
+            <HelpGroup header='Inline Help'>
+                <HelpText>Many user interface elements show a little questionmark icon when hovered over. Clicking the icon toggles the display of an inline help text.</HelpText>
+                <HelpText>Tooltips may provide additional information on a user interface element and are shown when hovering over it with the mouse.</HelpText>
+            </HelpGroup>
+            <HelpGroup header='Selections'>
+                <HelpText>
+                    The viewer allows changing colors and representations for selections of atoms, residues or chains. Selections can be created by
+                    <ul style={{ paddingLeft: '20px' }}>
+                        <li>picking elements on the 3D canvas or the sequence view using the mouse, e.g. toggle selection using {selectToggleTriggers} (for more see help section on <i>Mouse Controls</i>)</li>
+                        <li>using the <i>Add</i>, <i>Remove</i> and <i>Only</i> dropdown buttons in the <i>Manage Selection</i> panel which allow modifing the current selection by predefined sets</li>
+                    </ul>
+                </HelpText>
+            </HelpGroup>
+            <HelpGroup header='Coloring'>
+                <HelpText>
+                    There are two ways to color structures. Every representation (e.g. cartoon or spacefill) has a color theme which can be changed using the dropdown for each representation in the <i>Structure Settings</i> panel. Additionally any selection atoms, residues or chains can by given a custom color. For that, first select the parts of the structure to be colored (see help section on <i>Selections</i>) and, second, choose a color from the color dropdown botton in the <i>Selection</i> row of the <i>Change Representation</i> panel. The theme color can be seen as a base color that is overpainted by the custom color. Custom colors can be removed for a selection with the 'Clear' option in the color dropdown.
+                </HelpText>
+            </HelpGroup>
+            <HelpGroup header='Representations'>
+                <HelpText>
+                    Structures can be shown with many different representations (e.g. cartoon or spacefill). The <i>Change Representation</i> panel offers a collection of predefined styles which can be applied using the <i>Preset</i> dropdown button. Additionally any selection atoms, residues or chains can by shown with a custom representation. For that, first select the parts of the structure to be mofified (see help section on <i>Selections</i>) and, second, choose a representation to hide or show from the <i>Show</i> and <i>Hide</i> dropdown bottons in the <i>Selection</i> row of the <i>Change Representation</i> panel. The <i>Everything</i> row applies the action to the whole structure instead of the current selection.
+                </HelpText>
+            </HelpGroup>
+            <HelpGroup header='Surroundings'>
+                <HelpText>
+                    To show the surroundings of a residue or ligand, click it in the 3D scene or in the sequence widget using {structureInteractionTriggers}.
+                </HelpText>
+            </HelpGroup>
+            {/* <HelpGroup header='Densities'>
+                <HelpText>
+                    Densities can be shown for both X-ray and cryo-EM structures. By default the density around an element/atom can be shown by clicking using {volumeAroundTriggers}. The <i>Density Controls</i> panel offers a variety of options to adjust the display of density maps. The absence of the <i>Density Controls</i> panel indicates that no density is available for the loaded entry which is the case for e.g. NMR structures or very old X-ray structures.
+                </HelpText>
+            </HelpGroup> */}
+
+            <HelpSection header='How-to Guides' />
+            {/* <HelpGroup header='RCSB Molecule of the Month Style'>
+                <HelpText>
+                    <ol style={{ paddingLeft: '20px' }}>
+                        <li>First, hide everything, then show everything with the spacefill representation using the <i>Representation</i> panel.</li>
+                        <li>Change color theme of the spacefill representation to <i>illustrative</i> using the <i>Structure Settings</i> panel.</li>
+                        <li>Set render style to <i>toon</i> and activate <i>occlusion</i> in the <i>General Settings</i> panel.</li>
+                    </ol>
+                </HelpText>
+            </HelpGroup> */}
+            <HelpGroup header='Create an Image'>
+                <HelpText>
+                    <p>Use the <Icon name='screenshot' /> icon in the viewport or go to the <i>Create Image</i> panel and click <i>download</i> to get the same image you see on the 3D canvas.</p>
+                    <p>To adjust the size of the image, select <i>Custom</i> from the <i>Size</i> dropdown in the <i>Create Image</i> panel. Adjust the <i>Width</i> and <i>Height</i> using the sliders. To see an image preview with the correct aspect ratio, activate the preview by expanding the <i>Preview</i> panel.</p>
+                </HelpText>
+            </HelpGroup>
+
+            <HelpSection header='Mouse Controls' />
+            {this.getMouseBindingComponents()}
+        </div>
+    }
+}