1 /*******************************************************************************
\r
2 * Copyright (c) 2007, 2010 Association for Decentralized Information Management
\r
3 * in Industry THTH ry.
\r
4 * All rights reserved. This program and the accompanying materials
\r
5 * are made available under the terms of the Eclipse Public License v1.0
\r
6 * which accompanies this distribution, and is available at
\r
7 * http://www.eclipse.org/legal/epl-v10.html
\r
10 * VTT Technical Research Centre of Finland - initial API and implementation
\r
11 *******************************************************************************/
\r
12 package org.simantics.browsing.ui.common;
\r
14 import java.util.Collection;
\r
16 import org.simantics.browsing.ui.GraphExplorer;
\r
17 import org.simantics.browsing.ui.NodeContext;
\r
18 import org.simantics.browsing.ui.Tester;
\r
19 import org.simantics.browsing.ui.content.CheckedStateFactory;
\r
20 import org.simantics.browsing.ui.content.ComparableContextFactory;
\r
21 import org.simantics.browsing.ui.content.ImageDecoratorFactory;
\r
22 import org.simantics.browsing.ui.content.ImagerFactory;
\r
23 import org.simantics.browsing.ui.content.LabelDecoratorFactory;
\r
24 import org.simantics.browsing.ui.content.LabelerFactory;
\r
25 import org.simantics.browsing.ui.content.ViewpointFactory;
\r
26 import org.simantics.utils.datastructures.ComparatorFactory;
\r
29 * An interface for retrieving a collection of {@link Evaluator}s based on any
\r
30 * input object ({@link #get(Object)}.
\r
33 * {@link EvaluatorDataImpl} is the default class-based concrete implementation of
\r
34 * this interface that clients can and should use.
\r
38 * @see EvaluatorDataImpl
\r
40 public interface EvaluatorData {
\r
43 * A transformer from one input object to another. The idea is that before
\r
44 * resolving an Evaluator for an input object, all possible input
\r
45 * transformations have been executed.
\r
48 * Consider classes A and B which have are of a separate inheritance
\r
49 * hierarchy and share no common interfaces. In principle, this mechanism
\r
50 * should allow clients to define evaluators for class B, define a
\r
51 * transformer from class A to B and give input objects of class A, and
\r
52 * evaluator for class B would get resolved for these inputs.
\r
55 * NOTE: this mechanism is not in use yet.
\r
58 public interface Transformer {
\r
59 Object transform(Object source);
\r
63 * An evaluator describes available ways of
\r
65 * <li>producing content for a {@link GraphExplorer}, i.e. detemining the
\r
66 * children of a {@link NodeContext} (see {@link ViewpointFactory})</li>
\r
67 * <li>sorting the produced child content for a {@link NodeContext} (see
\r
68 * {@link ComparableContextFactory})</li>
\r
69 * <li>producing labels for the produced {@link NodeContext}s (see
\r
70 * {@link LabelerFactory})</li>
\r
71 * <li>decorating labels produced for {@link NodeContext}s (see
\r
72 * {@link LabelDecoratorFactory})</li>
\r
75 * An evaluator may produce several alternatives for each of the above
\r
76 * tasks, sorted by preference numbers bound to the factories. Picking the
\r
77 * factory to use is not the task of the evaluator.
\r
79 * @see EvaluatorImpl
\r
81 public interface Evaluator {
\r
83 EvaluatorTree<ComparableContextFactory> getComparableContextTree();
\r
84 EvaluatorTree<ImagerFactory> getImagerTree();
\r
85 EvaluatorTree<ImageDecoratorFactory> getImageDecoratorTree();
\r
86 EvaluatorTree<LabelDecoratorFactory> getLabelDecoratorTree();
\r
87 EvaluatorTree<LabelerFactory> getLabelerTree();
\r
88 EvaluatorTree<CheckedStateFactory> getCheckStateTree();
\r
89 EvaluatorTree<ViewpointFactory> getViewpointTree();
\r
92 * A convenience method for building an evaluator by adding viewpoint to
\r
93 * the ViewpointFactory EvaluatorTree root. Maybe should not be in the
\r
96 * @param factory the factory to add
\r
98 * @return this evaluator to allow chained initialization
\r
100 Evaluator addViewpoint(ViewpointFactory factory, double preference);
\r
101 Evaluator addComparableContext(ComparableContextFactory factory, double preference);
\r
102 Evaluator addLabeler(LabelerFactory factory, double preference);
\r
103 Evaluator addCheckState(CheckedStateFactory factory, double preference);
\r
104 Evaluator addLabelDecorator(LabelDecoratorFactory factory, double preference);
\r
105 Evaluator addComparator(ComparableContextFactory factory, double preference);
\r
106 Evaluator addImager(ImagerFactory factory, double preference);
\r
107 Evaluator addImageDecorator(ImageDecoratorFactory factory, double preference);
\r
112 * A node in a tree of factories. Each node is associated with a
\r
113 * {@link Tester} that determines whether the factories associated with this
\r
114 * node should be included in the available factory evaluation result of the
\r
115 * specified {@link NodeContext} input.
\r
118 * The factory tree structure allows optimization of factory resolution when
\r
119 * there are lots of factories available. By grouping factories under tree
\r
120 * nodes with a suitable tester allows more efficient result calculation.
\r
123 * Should not be created directly. Use
\r
124 * <code>Evaluator.add*Branch(Tester)</code> to create new evaluation tree
\r
127 * @param <Factory> one of factories listed as "see also"
\r
129 * @see ViewpointFactory
\r
130 * @see ComparatorFactory
\r
131 * @see LabelerFactory
\r
132 * @see LabelDecoratorFactory
\r
134 public interface EvaluatorTree<Factory> {
\r
137 * @return a tester to indicate whether the factories in this tree node
\r
138 * should be added to the factory evaluation result.
\r
140 Tester getTester();
\r
144 * @param preference
\r
145 * @return this {@link EvaluatorTree} instance for chained initialization
\r
147 EvaluatorTree<Factory> addFactory(Factory factory, double preference);
\r
151 * @return the new {@link EvaluatorTree} branch created as a child of
\r
152 * this {@link EvaluatorTree}
\r
154 EvaluatorTree<Factory> addBranch(Tester tester);
\r
157 * @return preference-wrapped factories accepted by this EvaluatorTree node
\r
159 Collection<Preference<Factory>> getAcceptedFactories();
\r
162 * @return preference-wrapped child tree nodes of this EvaluatorTree node
\r
164 Collection<EvaluatorTree<Factory>> getChildren();
\r
169 * Creates a new Evaluator that is completely separate from this
\r
170 * {@link EvaluatorData}. {@link #addEvaluator(Class, Evaluator)} can later
\r
171 * be used to bind the evaluator to any number of EvaluatorData instances.
\r
173 * @return new {@link Evaluator} instance
\r
175 Evaluator newEvaluator();
\r
178 * Bind the specified evaluator to the specified class. After this results
\r
179 * of {@link #get(Object)} should include <code>eval</code> for any input
\r
180 * object that is an instance of <code>clazz</code>.
\r
185 void addEvaluator(Class<?> clazz, Evaluator eval);
\r
188 * Attempts to get a collection of possible <code>Evaluator</code> instances
\r
189 * for the specified input object.
\r
192 * The resolution of "possible evaluators" can be based on, e.g. Class
\r
193 * comparison, <code>instanceof</code> queries or adaptation through
\r
194 * Eclipse's <code>IAdaptable</code> interface.
\r
197 * @param input any object that represents the input for producing some
\r
199 * @return an empty collection if no <code>Evaluator</code> could be found
\r
200 * to take care of the specified kind of input
\r
202 Collection<Evaluator> get(Object input);
\r
205 * An evaluator entry descriptor returned by
\r
206 * {@link EvaluatorData#enumEvaluators()}.
\r
208 public static interface EvaluatorEntry {
\r
209 public Class<?> getClazz();
\r
210 public Collection<Evaluator> getEvaluators();
\r
214 * Enumerates all the evaluators added by the client using
\r
215 * {@link #addEvaluator(Class, Evaluator)}.
\r
217 Collection<EvaluatorEntry> enumEvaluators();
\r
218 <T> T getBrowseContext();
\r