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;
\r
14 import java.util.Collection;
\r
15 import java.util.Map;
\r
16 import java.util.Set;
\r
17 import java.util.function.Consumer;
\r
19 import org.eclipse.core.runtime.IAdaptable;
\r
20 import org.simantics.browsing.ui.NodeContext.CacheKey;
\r
21 import org.simantics.browsing.ui.NodeContext.PrimitiveQueryKey;
\r
22 import org.simantics.browsing.ui.NodeContext.QueryKey;
\r
23 import org.simantics.browsing.ui.content.Labeler;
\r
24 import org.simantics.browsing.ui.content.Labeler.Modifier;
\r
25 import org.simantics.utils.datastructures.BinaryFunction;
\r
26 import org.simantics.utils.threads.IThreadWorkQueue;
\r
31 public interface GraphExplorer extends IAdaptable {
\r
34 * A key that can be used to associate GraphExplorer instances with other
\r
35 * objects in, e.g. SWT widgets using Widget.setData(String, Object).
\r
37 public static final String KEY_GRAPH_EXPLORER = "GraphExplorer";
\r
40 * @see #setAutoExpandLevel(int)
\r
42 public static int ALL_LEVELS = -1;
\r
44 public static final Object EMPTY_INPUT = new Object() {
\r
47 public String toString() { return "GraphExplorer.EMPTY_INPUT"; };
\r
52 * @deprecated not needed anymore, just remove all uses
\r
55 public interface ModificationContext extends IAdaptable {
\r
60 * An IGraphExplorer has a UI which uses some toolkit (AWT/SWT). The
\r
61 * toolkits are assumed to be single-threaded. The return value of this
\r
62 * method indicates the thread used for UI-related accesses.
\r
64 * @return the single access thread used by this GraphExplorer
\r
66 IThreadWorkQueue getThread();
\r
69 * Override this method to customize the maximum amount of child nodes that
\r
70 * are shown for any node. The returned value must be non-negative.
\r
72 * Use {@link Integer#MAX_VALUE} to maximize the limit.
\r
74 * @return max amount of children shown for a node, must not be negative
\r
76 int getMaxChildren();
\r
77 void setMaxChildren(int maxChildren);
\r
80 * Query for context-specific max children to show value using the provided
\r
81 * query manager and node context.
\r
85 * @return node specific child limit or what is returned by
\r
86 * {@link #getMaxChildren()} if node specific limit is not set
\r
88 int getMaxChildren(NodeQueryManager manager, NodeContext context);
\r
91 * TODO: documentation
\r
96 <T> void setProcessor(NodeQueryProcessor<T> processor);
\r
97 <T> NodeQueryProcessor<T> getProcessor(QueryKey<T> key);
\r
100 * TODO: documentation
\r
105 <T> void setPrimitiveProcessor(PrimitiveQueryProcessor<T> processor);
\r
106 <T> PrimitiveQueryProcessor<T> getPrimitiveProcessor(PrimitiveQueryKey<T> key);
\r
109 * Associates the provided DataSource implementation with class T in this
\r
110 * GraphExplorer. PrimitiveQueryProcessor implementations can access these
\r
111 * data sources through the class provided by
\r
112 * {@link DataSource#getProvidedClass()}. Specifying a new association for
\r
113 * the same T will overwrite the previous data source association.
\r
115 * @param <T> the provided data source type
\r
116 * @param dataSource the data source
\r
118 <T> void setDataSource(DataSource<T> dataSource);
\r
121 * Removes the data source associated with the provided class.
\r
123 * @param forProvidedClass
\r
124 * @return the removed data source association
\r
126 <T> DataSource<T> removeDataSource(Class<T> forProvidedClass);
\r
128 void setUIContexts(Set<String> contexts);
\r
131 * Set the root input object of this explorer.
\r
132 * @param root the input object, may <b>not</b> be <code>null</code>
\r
134 void setRoot(Object root);
\r
137 * Set the root node context of this explorer. Allows the client to provide
\r
138 * the complete NodeContext to be used as the explorer root input while
\r
139 * {@link #setRoot(Object)} only allows the client to provide the
\r
140 * {@link BuiltinKeys#INPUT} data for the root NodeContext.
\r
142 * @param root the root node context, may <b>not</b> be <code>null</code>
\r
144 void setRootContext(NodeContext context);
\r
147 * Get the current UI item context of the root input object.
\r
149 * Return value is undefined for a disposed or uninitialized GraphExplorer.
\r
150 * An explorer is uninitialized when {@link #setRoot(Object)} or
\r
151 * {@link #setRootContext(NodeContext)} has not been invoked yet.
\r
153 * @return input object's UI item context
\r
155 NodeContext getRoot();
\r
158 * Get the parent node context of the specified node context. If there is no
\r
159 * visible parent node in the explorer, <code>null</code> is returned.
\r
161 * Only to be invoked from the UI thread (see {@link #getThread()}.
\r
163 * @param context the context to the possible parent node for
\r
164 * @return <code>null</code> if there is no parent node
\r
166 NodeContext getParentContext(NodeContext context);
\r
169 * Consult the explorer's cache for the specified node and key. The method
\r
170 * will return a result only if the requested query has been previously
\r
171 * performed and has not been cleared (invalidated).
\r
174 * @param context the UI item's context
\r
175 * @param key the cache key to consult for
\r
176 * @return the value in the cache or <code>null</code> if no value was found
\r
178 <T> T query(NodeContext context, CacheKey<T> key);
\r
180 // --- UI related things ---
\r
182 public interface TransientExplorerState {
\r
183 Integer getActiveColumn();
\r
186 Object getWidgetSelection();
\r
187 TransientExplorerState getTransientState();
\r
189 SelectionDataResolver getSelectionDataResolver();
\r
190 void setSelectionDataResolver(SelectionDataResolver r);
\r
193 * @return the current {@link SelectionFilter}
\r
195 SelectionFilter getSelectionFilter();
\r
198 * Set new {@link SelectionFilter} for this explorer to control what will be
\r
199 * put into selections provided by this <code>GraphExplorer</code>.
\r
201 * TODO: specify what should happen to the current provided selection when a
\r
202 * new filter is set. Should it change immediately or be left as is?
\r
204 * @param f the new filter or <code>null</code> to disable filtering
\r
206 void setSelectionFilter(SelectionFilter f);
\r
208 void setSelectionTransformation(BinaryFunction<Object[], GraphExplorer, Object[]> f);
\r
210 //ISelectionProvider getSelectionProvider();
\r
212 void setColumnsVisible(boolean visible);
\r
213 void setColumns(Column[] columns);
\r
214 void setColumns(Column[] columns, Consumer<Map<Column, Object>> callback);
\r
215 Column[] getColumns();
\r
220 boolean select(NodeContext context);
\r
221 boolean selectPath(Collection<NodeContext> contexts);
\r
222 boolean isVisible(NodeContext context);
\r
225 * Sets the expanded state of the specified node context.
\r
228 * May work asynchronously.
\r
231 * @param context the context to set the expanded state for
\r
232 * @param expanded <code>true</code> to expand, <code>false</code> to
\r
235 void setExpanded(NodeContext context, boolean expanded);
\r
237 <T> void addListener(T listener);
\r
238 <T> void removeListener(T listener);
\r
243 * Attempts to start in-line editing at the specified INodeContext in this
\r
244 * graph explorer. The nature of the in-line editing (i.e. used controls)
\r
245 * depends on the kind of {@link Modifier} returned by the {@link Labeler}
\r
246 * of the specified node context. The labeler is determined by the
\r
247 * {@link BuiltinKeys#SELECTED_LABELER} query.
\r
250 * Only to be invoked from the UI thread (see {@link #getThread()}.
\r
252 * @param context the node, i.e. tree item or tree-table row to start
\r
254 * @param columnKey a key to identify the column to edit. This argument must
\r
255 * match one of the keys of the tree columns set using
\r
256 * {@link #setColumns(Column[])}.
\r
257 * @return <code>true</code> if the editing process was successfully
\r
260 String startEditing(NodeContext context, String columnKey);
\r
261 String startEditing(String columnKey);
\r
264 * @return <code>true</code> if the explorer is disposed.
\r
266 boolean isDisposed();
\r
269 * Return the backing UI control of this GraphExplorer.
\r
274 <T> T getControl();
\r
277 * @deprecated not needed anymore, just remove calls
\r
280 void setModificationContext(ModificationContext modificationContext);
\r
283 * Sets the auto-expand level to be used when the input of the viewer is set
\r
284 * using {@link #setInput(Object)}. The value 0 means that there is no
\r
285 * auto-expand; 1 means that the invisible root element is expanded (since
\r
286 * most concrete subclasses do not show the root element, there is usually
\r
287 * no practical difference between using the values 0 and 1); 2 means that
\r
288 * top-level elements are expanded, but not their children; 3 means that
\r
289 * top-level elements are expanded, and their children, but not
\r
290 * grandchildren; and so on.
\r
292 * The value {@value #ALL_LEVELS} means that all subtrees should be
\r
296 * @param level non-negative level, or {@value #ALL_LEVELS} to expand all
\r
297 * levels of the tree
\r
299 void setAutoExpandLevel(int level);
\r
302 * Sets the implementation that this GraphExplorer shall use to persist its
\r
303 * state when disposed and to load its state when created.
\r
305 * In order to restore a previously persisted state, this method must be
\r
306 * called before invoking {@link #setRoot(Object)} or
\r
307 * {@link #setRootContext(NodeContext)}.
\r
309 * @param persistor the persistor to use
\r
311 void setPersistor(StatePersistor persistor);
\r
314 * @return <code>true</code> if the explorer is in editable state
\r
315 * @see #setEditable(boolean)
\r
317 boolean isEditable();
\r
320 * Makes this explorer editable or non-editable as far as this
\r
321 * implementation is concerned. For a non-editable explorer
\r
322 * {@link #startEditing(String)} and
\r
323 * {@link #startEditing(NodeContext, String)} will do nothing. Externally
\r
324 * added listeners (see {@link #addListener(Object)}) will still get
\r
325 * notified of events so those need to be handled separately.
\r
328 * By default, implementations should be editable.
\r
330 void setEditable(boolean editable);
\r
333 * Returns underlaying data object, which was clicked (with mouse).
\r
334 * @param event Mouse Event (usually org.eclipse.swt.events.MouseEvent)
\r
336 public Object getClicked(Object event);
\r