Selection View

From Developer Documents
Jump to navigation Jump to search

The Selection View is a standard Simantics view, which shows tabbed configuration views about the current workbench selection.

Selection View (org.simantics.browsing.ui.platform.PropertyPageView)

The Selection View is contributed in org.simantics.browsing.ui.platform/plugin.xml.

Selection View displays content for the workbench selection.

Selection View listens to the active workbench part and tries to obtain org.simantics.ui.workbench.IPropertyPage via IAdaptable.getAdapter for displaying selections from the part.

Most Simantics workbench part implementations adapt into the standard property page implementation described next.

Standard property page (org.simantics.selectionview.StandardPropertyPage)

The standard property page displays a tab folder (org.simantics.selectionview.StandardProperties), which contains n tabs contributed by a set of selection processors (org.simantics.selectionview.SelectionProcessor).

Selection processing


public interface SelectionProcessor<S, B> {

    /**
     * @param selection the incoming selection to process
     * @param backend for providing back-end access to the processor
     * @return an ordered set of
     *         <code>org.simantics.browsing.ui.swt.ComparableTabContributor</code>
     *         instances representing the property tabs to be contributed to the
     *         selection view. The processor must not return <code>null</code>,
     *         return an empty collection instead.
     */
    Collection<?> process(S selection, B backend);

}

Selection is the workbench selection.

Backend is ReadGraph in most cases (could be something else if custom property pages are used).

Selection processors are contributed by

  • Extending StandardPropertyPage and overriding method getSelectionProcessor
  • Constructing StandardPropertyPage with a set of browse contexts for which selection processors can be contributed via extension point org.simantics.browsing.ui.common.selectionProcessorBinding

The obtained set of ComparableTabContributors are sorted and used to create tabs for the tabbed folder.

A modelled implementation of the SelectionProcessor interface is described next.

Modelled Selection Processor (org.simantics.selectionview.StandardSelectionProcessor)

The implementation of modelled selection processor does the following procedure:

  1. Try to get a model resource from the workbench selection.
  2. <syntaxhighlight lang="java"> private Resource getModel(ReadGraph graph, Object selection) throws DatabaseException {

       Variable variable = ISelectionUtils.filterSingleSelection(selection, Variable.class);
       if (variable != null)
           return Variables.getModel(graph, variable);
    
       Resource model = ISelectionUtils.getSinglePossibleKey(selection,
               SelectionHints.KEY_MODEL, Resource.class);
       if (model == null) {
           Resource r = ISelectionUtils.getSinglePossibleKey(selection,
                   SelectionHints.KEY_MAIN, Resource.class);
           if (r != null)
               model = graph.sync(new PossibleModel(r));
       }
       return model != null
               && graph.isInstanceOf(model, SimulationResource.getInstance(graph).Model)
               ? model
               : null;
    

    } </syntaxhighlight>

  3. Seek all instances of http://www.simantics.org/SelectionView-0.0/TabContribution from model dependencies and adapt (ReadGraph.adapt) them to org.simantics.selectionview.TabContribution.
  4. <syntaxhighlight lang="python"> SEL.VariableTabContribution <T SEL.TabContribution

     >-- SEL.VariableTabContribution.HasTest <R L0.DependsOn
     >-- SEL.VariableTabContribution.HasView <R L0.DependsOn
     >-- SEL.VariableTabContribution.HasPriority <R L0.DependsOn
    

    SEL.TypedVariableTabContribution <T SEL.VariableTabContribution

     >-- SEL.TypedVariableTabContribution.HasType <R L0.DependsOn
    

    </syntaxhighlight>

    <syntaxhighlight lang="java"> public interface TabContribution<T> {

       void contribute(ReadGraph graph, T selection, Collection<ComparableTabContributor> result)
               throws DatabaseException;	
    

    } </syntaxhighlight>

    (SEL.VariableTabContribution.HasView refers to a Modelled View configuration for describing the contents of the tab.)

    Seek all instances of http://www.simantics.org/SelectionView-0.0/SelectionTransformation (which are also L0.Function) and apply them (org.simantics.db.common.utils.Functions#exec) as long as needed to obtain a closure of inputs.

    Feed all inputs to the found TabContributions to obtain a set of tabs.

    Tab implementation

    The standard way of implementing a tab is a Simantics Modelled View.

    Generic configurations for modelled tabs can be found in the ontology http://www.simantics.org/SelectionViewUI-1.0.

    The standard modelled property tab is http://www.simantics.org/SelectionViewUI-1.0/StandardProperties

    
    SEL.StandardPropertiesBase <T VIEW.Explorer
      @L0.assert VIEW.Control.layoutData
        _ : VIEW.GridLayout.GridData
          VIEW.GridLayout.GridData.horizontalGrab true
          VIEW.GridLayout.GridData.verticalGrab true
      @L0.assert VIEW.Control.style 
        _ : VIEW.Control.Style
          VIEW.Control.Style.HasConstant VIEW.Control.Style.Constant.Multi
          VIEW.Control.Style.HasConstant VIEW.Control.Style.Constant.FullSelection
      @L0.assert VIEW.Explorer.columns 
        _ : VIEW.Explorer.ColumnList
          @L0.list
            SEL.PropertyColumn
            SEL.ValueColumn
            SEL.UnitColumn
      @L0.assert VIEW.Explorer.input MOD.Functions.singleVariableSelection
      @L0.assert VIEW.Explorer.browseContext
        _ : VIEW.ResourceURI
          VIEW.ResourceURI.HasResource SEL.StandardPropertiesBase.BrowseContext : SEL.StandardProperties.BrowseContextStandardChildren
    
    SEL.StandardProperties : SEL.StandardPropertiesBase
    
    

    where input is obtained from modelled view runtime state

    
        @SCLValue(type = "ReadGraph -> Resource -> Variable -> Variable")
        public static Variable singleVariableSelection(ReadGraph graph, Resource resource, Variable context) throws DatabaseException {
        	return ScenegraphLoaderUtils.getVariableSelection(graph, context);
        }
    
    

    and browsing rules are defined by

    
    SEL.StandardProperties.BrowseContextStandardChildren <T SEL.StandardProperties.BrowseContextWithoutChildren
      @L0.assert VP.BrowseContext.HasChildContribution 
        _ : VP.ChildContribution
          VP.ChildContribution.HasParentNodeType MOD.ModelingBrowseContext.Variable
          VP.ChildContribution.HasChildNodeType MOD.ModelingBrowseContext.Variable
          VP.ChildContribution.HasRule _ : MOD.ModelingBrowseContext.VariablePropertyRule
            MOD.ModelingBrowseContext.VariablePropertyRule.RequireProperty "HasStandardPropertyInfo"
      @L0.assert VP.BrowseContext.HasChildContribution 
        _ : VP.ChildContribution
          VP.ChildContribution.HasParentNodeType MOD.ModelingBrowseContext.Variable
          VP.ChildContribution.HasChildNodeType SEL.CategoryNode
          VP.ChildContribution.HasRule _ : SEL.VariablePropertyCategoryRule
    
    SEL.StandardProperties.BrowseContextWithoutChildren <T VP.BrowseContext
      @L0.assert VP.BrowseContext.HasVisualsContribution
        _ : VP.VisualsContribution
          VP.VisualsContribution.HasNodeType MOD.ModelingBrowseContext.Variable
          VP.VisualsContribution.HasRule SEL.VariablePropertyLabelRule
      @L0.assert VP.BrowseContext.HasVisualsContribution
        _ : VP.VisualsContribution
          VP.VisualsContribution.HasNodeType SEL.CategoryNode
          VP.VisualsContribution.HasRule SEL.CategoryNodeLabelRule
      @L0.assert VP.BrowseContext.HasVisualsContribution
        _ : VP.VisualsContribution
          VP.VisualsContribution.HasNodeType MOD.ModelingBrowseContext.Variable
          VP.VisualsContribution.HasRule SEL.StandardPropertySorterRule
      @L0.assert VP.BrowseContext.HasVisualsContribution
        _ : VP.VisualsContribution
          VP.VisualsContribution.HasNodeType MOD.ModelingBrowseContext.Variable
          VP.VisualsContribution.HasRule SEL.VariablePropertyModifierRule
      @L0.assert VP.BrowseContext.HasVisualsContribution
        _ : VP.VisualsContribution
          VP.VisualsContribution.HasNodeType MOD.ModelingBrowseContext.Variable
          VP.VisualsContribution.HasRule SEL.VariableDecorationRule
      @L0.assert VP.BrowseContext.HasVisualsContribution
        _ : VP.VisualsContribution
          VP.VisualsContribution.HasNodeType SEL.CategoryNode
          VP.VisualsContribution.HasRule SEL.CategoryDecorationRule
    
    

    The rules of the standard browse context are as follows:

    • MOD.ModelingBrowseContext.VariablePropertyRule returns all properties (Variable.browseProperties) such that
      • All results contain all properties defined by VariablePropertyRule.RequireProperty
    • SEL.VariablePropertyCategoryRule returns a set of categories collected from all suitable properties (as above)
      • categories are identified by
        • var#HasStandardPropertyInfo#CategoryName
        • var#HasStandardPropertyInfo#CategorySortingName
      • hidden categories are not shown
        • see var#HasStandardPropertyInfo#IsHidden
    • SEL.VariablePropertyLabelRule collects a String->String map by searching properties var where
      • key is the value of (var#HasDisplayColumn)
      • value is the (Bindings.STRING) value of var
    • SEL.CategoryNodeLabelRule returns the map "HasDisplayProperty" -> ((CategoryNode)content).getName()
    • SEL.StandardPropertySorterRule sorts properties and categories by sorting name where sorting name is
      • (p#SortingName) or if absent (p#HasDisplayProperty) for a variable p
      • ((CategoryNode)content).getSortingName() for categories
    • SEL.VariablePropertyModifierRule returns org.simantics.browsing.ui.content.Labeler.Modifier by
      • finding the column property (by var#HasDisplayColumn)
      • trying to obtain a custom modifier (var#HasCustomModifier)
      • trying to obtain an enumeration modifier by listing (var#HasEnumerationValues) and returning org.simantics.browsing.ui.graph.impl.EnumerationVariableModifier3
      • returning org.simantics.browsing.ui.model.modifiers.VariableModifier2
    • SEL.VariableDecorationRule offsets the property name column of properties by one
    • SEL.CategoryDecorationRule displays categories as bold

    The standard implementation can be customised by e.g.

    • Introducing more columns
    • Applying property filtering (RequiresProperty)
    • Adding decorations

    Some other notable points

    • Modifier uses the property 'HasInputValidator' for getting a validator
    • Modifier writes with Bindings.STRING into the label property.
    • The labels may apply transformations such as unit conversion or formatting i.e. they can not be used for obtaining raw property data.

    Selection View Title

    By default the selection view title is set to Selection. However it is possible for tab contributions to customize the title text. On the low-level customization happens through the org.simantics.selectionview.IPropertyTab2 interface which tab contributions can implement.

    public interface IPropertyTab2 extends IPropertyTab {
    
        /**
         * @param updateCallback a callback that <em>can be</em> invoked by
         *        getPartName if it wishes to change the part name. If the page does
         *        not wish to change the part name, it does not have to invoke the
         *        updateCallback. A <code>null</code> value indicates that the part
         *        name should be returned to its default value. The method should
         *        use the selection received by
         *        {@link #setInput(org.simantics.db.management.ISessionContext, ISelection, boolean)}
         *        as input for constructing the part title.
         */
        void updatePartName(Callback<String> updateCallback);
    
    }
    

    Contributing custom title logic is not yet possible through modelling, only by implementing your own custom org.simantics.selectionview.PropertyTabContributor, e.g. by customizing org.simantics.selectionview.ModelledTabContributor or org.simantics.selectionview.PropertyTabContributorImpl.

    Summary

    Future developments

    Some generic Variable properties should be used in rules. These properties include

    • #classifications
    • #valid
    • #validator
    • #expression
    • #required
    • #default
    • #readOnly

    The Variable model includes a generic model for connections, which should also be supported in the standard properties

    Selection view title logic modelling shall be added.