-/*******************************************************************************\r
- * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
- * in Industry THTH ry.\r
- * All rights reserved. This program and the accompanying materials\r
- * are made available under the terms of the Eclipse Public License v1.0\r
- * which accompanies this distribution, and is available at\r
- * http://www.eclipse.org/legal/epl-v10.html\r
- *\r
- * Contributors:\r
- * VTT Technical Research Centre of Finland - initial API and implementation\r
- *******************************************************************************/\r
-package org.simantics.browsing.ui;\r
-\r
-import java.util.Collection;\r
-import java.util.Map;\r
-import java.util.Set;\r
-import java.util.function.Consumer;\r
-\r
-import org.eclipse.core.runtime.IAdaptable;\r
-import org.simantics.browsing.ui.NodeContext.CacheKey;\r
-import org.simantics.browsing.ui.NodeContext.PrimitiveQueryKey;\r
-import org.simantics.browsing.ui.NodeContext.QueryKey;\r
-import org.simantics.browsing.ui.content.Labeler;\r
-import org.simantics.browsing.ui.content.Labeler.Modifier;\r
-import org.simantics.utils.datastructures.BinaryFunction;\r
-import org.simantics.utils.threads.IThreadWorkQueue;\r
-\r
-/**\r
- * \r
- */\r
-public interface GraphExplorer extends IAdaptable {\r
- \r
- /**\r
- * A key that can be used to associate GraphExplorer instances with other\r
- * objects in, e.g. SWT widgets using Widget.setData(String, Object).\r
- */\r
- public static final String KEY_GRAPH_EXPLORER = "GraphExplorer";\r
-\r
- /**\r
- * @see #setAutoExpandLevel(int)\r
- */\r
- public static int ALL_LEVELS = -1;\r
-\r
- public static final Object EMPTY_INPUT = new Object() {\r
-\r
- @Override\r
- public String toString() { return "GraphExplorer.EMPTY_INPUT"; };\r
-\r
- };\r
-\r
- /**\r
- * @deprecated not needed anymore, just remove all uses\r
- */\r
- @Deprecated\r
- public interface ModificationContext extends IAdaptable {\r
-\r
- }\r
-\r
- /**\r
- * An IGraphExplorer has a UI which uses some toolkit (AWT/SWT). The\r
- * toolkits are assumed to be single-threaded. The return value of this\r
- * method indicates the thread used for UI-related accesses.\r
- * \r
- * @return the single access thread used by this GraphExplorer\r
- */\r
- IThreadWorkQueue getThread();\r
-\r
- /**\r
- * Override this method to customize the maximum amount of child nodes that\r
- * are shown for any node. The returned value must be non-negative.\r
- * \r
- * Use {@link Integer#MAX_VALUE} to maximize the limit.\r
- * \r
- * @return max amount of children shown for a node, must not be negative\r
- */\r
- int getMaxChildren();\r
- void setMaxChildren(int maxChildren);\r
-\r
- /**\r
- * Query for context-specific max children to show value using the provided\r
- * query manager and node context.\r
- * \r
- * @param manager\r
- * @param context\r
- * @return node specific child limit or what is returned by\r
- * {@link #getMaxChildren()} if node specific limit is not set\r
- */\r
- int getMaxChildren(NodeQueryManager manager, NodeContext context);\r
-\r
- /**\r
- * TODO: documentation\r
- * \r
- * @param <T>\r
- * @param processor\r
- */\r
- <T> void setProcessor(NodeQueryProcessor<T> processor);\r
- <T> NodeQueryProcessor<T> getProcessor(QueryKey<T> key);\r
-\r
- /**\r
- * TODO: documentation\r
- * \r
- * @param <T>\r
- * @param processor\r
- */\r
- <T> void setPrimitiveProcessor(PrimitiveQueryProcessor<T> processor);\r
- <T> PrimitiveQueryProcessor<T> getPrimitiveProcessor(PrimitiveQueryKey<T> key);\r
-\r
- /**\r
- * Associates the provided DataSource implementation with class T in this\r
- * GraphExplorer. PrimitiveQueryProcessor implementations can access these\r
- * data sources through the class provided by\r
- * {@link DataSource#getProvidedClass()}. Specifying a new association for\r
- * the same T will overwrite the previous data source association.\r
- * \r
- * @param <T> the provided data source type\r
- * @param dataSource the data source\r
- */\r
- <T> void setDataSource(DataSource<T> dataSource);\r
-\r
- /**\r
- * Removes the data source associated with the provided class.\r
- * \r
- * @param forProvidedClass\r
- * @return the removed data source association\r
- */\r
- <T> DataSource<T> removeDataSource(Class<T> forProvidedClass);\r
-\r
- void setUIContexts(Set<String> contexts);\r
-\r
- /**\r
- * Set the root input object of this explorer.\r
- * @param root the input object, may <b>not</b> be <code>null</code>\r
- */\r
- void setRoot(Object root);\r
-\r
- /**\r
- * Set the root node context of this explorer. Allows the client to provide\r
- * the complete NodeContext to be used as the explorer root input while\r
- * {@link #setRoot(Object)} only allows the client to provide the\r
- * {@link BuiltinKeys#INPUT} data for the root NodeContext.\r
- * \r
- * @param root the root node context, may <b>not</b> be <code>null</code>\r
- */\r
- void setRootContext(NodeContext context);\r
-\r
- /**\r
- * Get the current UI item context of the root input object.\r
- * \r
- * Return value is undefined for a disposed or uninitialized GraphExplorer.\r
- * An explorer is uninitialized when {@link #setRoot(Object)} or\r
- * {@link #setRootContext(NodeContext)} has not been invoked yet.\r
- * \r
- * @return input object's UI item context\r
- */\r
- NodeContext getRoot();\r
-\r
- /**\r
- * Get the parent node context of the specified node context. If there is no\r
- * visible parent node in the explorer, <code>null</code> is returned.\r
- * \r
- * Only to be invoked from the UI thread (see {@link #getThread()}.\r
- * \r
- * @param context the context to the possible parent node for\r
- * @return <code>null</code> if there is no parent node\r
- */\r
- NodeContext getParentContext(NodeContext context);\r
-\r
- /**\r
- * Consult the explorer's cache for the specified node and key. The method\r
- * will return a result only if the requested query has been previously\r
- * performed and has not been cleared (invalidated).\r
- * \r
- * @param <T>\r
- * @param context the UI item's context\r
- * @param key the cache key to consult for\r
- * @return the value in the cache or <code>null</code> if no value was found\r
- */\r
- <T> T query(NodeContext context, CacheKey<T> key);\r
-\r
- // --- UI related things ---\r
-\r
- public interface TransientExplorerState {\r
- Integer getActiveColumn(); \r
- }\r
- \r
- Object getWidgetSelection();\r
- TransientExplorerState getTransientState();\r
- \r
- SelectionDataResolver getSelectionDataResolver();\r
- void setSelectionDataResolver(SelectionDataResolver r);\r
-\r
- /**\r
- * @return the current {@link SelectionFilter}\r
- */\r
- SelectionFilter getSelectionFilter();\r
-\r
- /**\r
- * Set new {@link SelectionFilter} for this explorer to control what will be\r
- * put into selections provided by this <code>GraphExplorer</code>.\r
- * \r
- * TODO: specify what should happen to the current provided selection when a\r
- * new filter is set. Should it change immediately or be left as is?\r
- * \r
- * @param f the new filter or <code>null</code> to disable filtering\r
- */\r
- void setSelectionFilter(SelectionFilter f);\r
-\r
- void setSelectionTransformation(BinaryFunction<Object[], GraphExplorer, Object[]> f);\r
-\r
- //ISelectionProvider getSelectionProvider();\r
-\r
- void setColumnsVisible(boolean visible);\r
- void setColumns(Column[] columns);\r
- void setColumns(Column[] columns, Consumer<Map<Column, Object>> callback);\r
- Column[] getColumns();\r
-\r
- /**\r
- * @param context\r
- */\r
- boolean select(NodeContext context);\r
- boolean selectPath(Collection<NodeContext> contexts);\r
- boolean isVisible(NodeContext context);\r
-\r
- /**\r
- * Sets the expanded state of the specified node context.\r
- * \r
- * <p>\r
- * May work asynchronously.\r
- * </p>\r
- * \r
- * @param context the context to set the expanded state for\r
- * @param expanded <code>true</code> to expand, <code>false</code> to\r
- * collapse\r
- */\r
- void setExpanded(NodeContext context, boolean expanded);\r
-\r
- <T> void addListener(T listener);\r
- <T> void removeListener(T listener);\r
-\r
- void setFocus();\r
-\r
- /**\r
- * Attempts to start in-line editing at the specified INodeContext in this\r
- * graph explorer. The nature of the in-line editing (i.e. used controls)\r
- * depends on the kind of {@link Modifier} returned by the {@link Labeler}\r
- * of the specified node context. The labeler is determined by the\r
- * {@link BuiltinKeys#SELECTED_LABELER} query.\r
- * \r
- * <p>\r
- * Only to be invoked from the UI thread (see {@link #getThread()}.\r
- * \r
- * @param context the node, i.e. tree item or tree-table row to start\r
- * editing on\r
- * @param columnKey a key to identify the column to edit. This argument must\r
- * match one of the keys of the tree columns set using\r
- * {@link #setColumns(Column[])}.\r
- * @return <code>true</code> if the editing process was successfully\r
- * initiated\r
- */\r
- String startEditing(NodeContext context, String columnKey);\r
- String startEditing(String columnKey);\r
-\r
- /**\r
- * @return <code>true</code> if the explorer is disposed.\r
- */\r
- boolean isDisposed();\r
-\r
- /**\r
- * Return the backing UI control of this GraphExplorer.\r
- * \r
- * @param <T>\r
- * @return\r
- */\r
- <T> T getControl();\r
-\r
- /**\r
- * @deprecated not needed anymore, just remove calls\r
- */\r
- @Deprecated\r
- void setModificationContext(ModificationContext modificationContext);\r
-\r
- /**\r
- * Sets the auto-expand level to be used when the input of the viewer is set\r
- * using {@link #setInput(Object)}. The value 0 means that there is no\r
- * auto-expand; 1 means that the invisible root element is expanded (since\r
- * most concrete subclasses do not show the root element, there is usually\r
- * no practical difference between using the values 0 and 1); 2 means that\r
- * top-level elements are expanded, but not their children; 3 means that\r
- * top-level elements are expanded, and their children, but not\r
- * grandchildren; and so on.\r
- * <p>\r
- * The value {@value #ALL_LEVELS} means that all subtrees should be\r
- * expanded.\r
- * </p>\r
- * \r
- * @param level non-negative level, or {@value #ALL_LEVELS} to expand all\r
- * levels of the tree\r
- */\r
- void setAutoExpandLevel(int level);\r
-\r
- /**\r
- * Sets the implementation that this GraphExplorer shall use to persist its\r
- * state when disposed and to load its state when created.\r
- * \r
- * In order to restore a previously persisted state, this method must be\r
- * called before invoking {@link #setRoot(Object)} or\r
- * {@link #setRootContext(NodeContext)}.\r
- * \r
- * @param persistor the persistor to use\r
- */\r
- void setPersistor(StatePersistor persistor);\r
-\r
- /**\r
- * @return <code>true</code> if the explorer is in editable state\r
- * @see #setEditable(boolean)\r
- */\r
- boolean isEditable();\r
-\r
- /**\r
- * Makes this explorer editable or non-editable as far as this\r
- * implementation is concerned. For a non-editable explorer\r
- * {@link #startEditing(String)} and\r
- * {@link #startEditing(NodeContext, String)} will do nothing. Externally\r
- * added listeners (see {@link #addListener(Object)}) will still get\r
- * notified of events so those need to be handled separately.\r
- * \r
- * <p>\r
- * By default, implementations should be editable.\r
- */\r
- void setEditable(boolean editable);\r
- \r
- /**\r
- * Returns underlaying data object, which was clicked (with mouse).\r
- * @param event Mouse Event (usually org.eclipse.swt.events.MouseEvent) \r
- */\r
- public Object getClicked(Object event);\r
-\r
-}\r
+/*******************************************************************************
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management
+ * in Industry THTH ry.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * VTT Technical Research Centre of Finland - initial API and implementation
+ *******************************************************************************/
+package org.simantics.browsing.ui;
+
+import java.util.Collection;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.Consumer;
+
+import org.eclipse.core.runtime.IAdaptable;
+import org.simantics.browsing.ui.NodeContext.CacheKey;
+import org.simantics.browsing.ui.NodeContext.PrimitiveQueryKey;
+import org.simantics.browsing.ui.NodeContext.QueryKey;
+import org.simantics.browsing.ui.content.Labeler;
+import org.simantics.browsing.ui.content.Labeler.Modifier;
+import org.simantics.utils.datastructures.BinaryFunction;
+import org.simantics.utils.threads.IThreadWorkQueue;
+
+/**
+ *
+ */
+public interface GraphExplorer extends IAdaptable {
+
+ /**
+ * A key that can be used to associate GraphExplorer instances with other
+ * objects in, e.g. SWT widgets using Widget.setData(String, Object).
+ */
+ public static final String KEY_GRAPH_EXPLORER = "GraphExplorer";
+
+ /**
+ * @see #setAutoExpandLevel(int)
+ */
+ public static int ALL_LEVELS = -1;
+
+ public static final Object EMPTY_INPUT = new Object() {
+
+ @Override
+ public String toString() { return "GraphExplorer.EMPTY_INPUT"; };
+
+ };
+
+ /**
+ * @deprecated not needed anymore, just remove all uses
+ */
+ @Deprecated
+ public interface ModificationContext extends IAdaptable {
+
+ }
+
+ /**
+ * An IGraphExplorer has a UI which uses some toolkit (AWT/SWT). The
+ * toolkits are assumed to be single-threaded. The return value of this
+ * method indicates the thread used for UI-related accesses.
+ *
+ * @return the single access thread used by this GraphExplorer
+ */
+ IThreadWorkQueue getThread();
+
+ /**
+ * Override this method to customize the maximum amount of child nodes that
+ * are shown for any node. The returned value must be non-negative.
+ *
+ * Use {@link Integer#MAX_VALUE} to maximize the limit.
+ *
+ * @return max amount of children shown for a node, must not be negative
+ */
+ int getMaxChildren();
+ void setMaxChildren(int maxChildren);
+
+ /**
+ * Query for context-specific max children to show value using the provided
+ * query manager and node context.
+ *
+ * @param manager
+ * @param context
+ * @return node specific child limit or what is returned by
+ * {@link #getMaxChildren()} if node specific limit is not set
+ */
+ int getMaxChildren(NodeQueryManager manager, NodeContext context);
+
+ /**
+ * TODO: documentation
+ *
+ * @param <T>
+ * @param processor
+ */
+ <T> void setProcessor(NodeQueryProcessor<T> processor);
+ <T> NodeQueryProcessor<T> getProcessor(QueryKey<T> key);
+
+ /**
+ * TODO: documentation
+ *
+ * @param <T>
+ * @param processor
+ */
+ <T> void setPrimitiveProcessor(PrimitiveQueryProcessor<T> processor);
+ <T> PrimitiveQueryProcessor<T> getPrimitiveProcessor(PrimitiveQueryKey<T> key);
+
+ /**
+ * Associates the provided DataSource implementation with class T in this
+ * GraphExplorer. PrimitiveQueryProcessor implementations can access these
+ * data sources through the class provided by
+ * {@link DataSource#getProvidedClass()}. Specifying a new association for
+ * the same T will overwrite the previous data source association.
+ *
+ * @param <T> the provided data source type
+ * @param dataSource the data source
+ */
+ <T> void setDataSource(DataSource<T> dataSource);
+
+ /**
+ * Removes the data source associated with the provided class.
+ *
+ * @param forProvidedClass
+ * @return the removed data source association
+ */
+ <T> DataSource<T> removeDataSource(Class<T> forProvidedClass);
+
+ void setUIContexts(Set<String> contexts);
+
+ /**
+ * Set the root input object of this explorer.
+ * @param root the input object, may <b>not</b> be <code>null</code>
+ */
+ void setRoot(Object root);
+
+ /**
+ * Set the root node context of this explorer. Allows the client to provide
+ * the complete NodeContext to be used as the explorer root input while
+ * {@link #setRoot(Object)} only allows the client to provide the
+ * {@link BuiltinKeys#INPUT} data for the root NodeContext.
+ *
+ * @param root the root node context, may <b>not</b> be <code>null</code>
+ */
+ void setRootContext(NodeContext context);
+
+ /**
+ * Get the current UI item context of the root input object.
+ *
+ * Return value is undefined for a disposed or uninitialized GraphExplorer.
+ * An explorer is uninitialized when {@link #setRoot(Object)} or
+ * {@link #setRootContext(NodeContext)} has not been invoked yet.
+ *
+ * @return input object's UI item context
+ */
+ NodeContext getRoot();
+
+ /**
+ * Get the parent node context of the specified node context. If there is no
+ * visible parent node in the explorer, <code>null</code> is returned.
+ *
+ * Only to be invoked from the UI thread (see {@link #getThread()}.
+ *
+ * @param context the context to the possible parent node for
+ * @return <code>null</code> if there is no parent node
+ */
+ NodeContext getParentContext(NodeContext context);
+
+ /**
+ * Consult the explorer's cache for the specified node and key. The method
+ * will return a result only if the requested query has been previously
+ * performed and has not been cleared (invalidated).
+ *
+ * @param <T>
+ * @param context the UI item's context
+ * @param key the cache key to consult for
+ * @return the value in the cache or <code>null</code> if no value was found
+ */
+ <T> T query(NodeContext context, CacheKey<T> key);
+
+ // --- UI related things ---
+
+ public interface TransientExplorerState {
+ Integer getActiveColumn();
+ }
+
+ Object getWidgetSelection();
+ TransientExplorerState getTransientState();
+
+ SelectionDataResolver getSelectionDataResolver();
+ void setSelectionDataResolver(SelectionDataResolver r);
+
+ /**
+ * @return the current {@link SelectionFilter}
+ */
+ SelectionFilter getSelectionFilter();
+
+ /**
+ * Set new {@link SelectionFilter} for this explorer to control what will be
+ * put into selections provided by this <code>GraphExplorer</code>.
+ *
+ * TODO: specify what should happen to the current provided selection when a
+ * new filter is set. Should it change immediately or be left as is?
+ *
+ * @param f the new filter or <code>null</code> to disable filtering
+ */
+ void setSelectionFilter(SelectionFilter f);
+
+ void setSelectionTransformation(BinaryFunction<Object[], GraphExplorer, Object[]> f);
+
+ //ISelectionProvider getSelectionProvider();
+
+ void setColumnsVisible(boolean visible);
+ void setColumns(Column[] columns);
+ void setColumns(Column[] columns, Consumer<Map<Column, Object>> callback);
+ Column[] getColumns();
+
+ /**
+ * @param context
+ */
+ boolean select(NodeContext context);
+ boolean selectPath(Collection<NodeContext> contexts);
+ boolean isVisible(NodeContext context);
+
+ /**
+ * Sets the expanded state of the specified node context.
+ *
+ * <p>
+ * May work asynchronously.
+ * </p>
+ *
+ * @param context the context to set the expanded state for
+ * @param expanded <code>true</code> to expand, <code>false</code> to
+ * collapse
+ */
+ void setExpanded(NodeContext context, boolean expanded);
+
+ <T> void addListener(T listener);
+ <T> void removeListener(T listener);
+
+ void setFocus();
+
+ /**
+ * Attempts to start in-line editing at the specified INodeContext in this
+ * graph explorer. The nature of the in-line editing (i.e. used controls)
+ * depends on the kind of {@link Modifier} returned by the {@link Labeler}
+ * of the specified node context. The labeler is determined by the
+ * {@link BuiltinKeys#SELECTED_LABELER} query.
+ *
+ * <p>
+ * Only to be invoked from the UI thread (see {@link #getThread()}.
+ *
+ * @param context the node, i.e. tree item or tree-table row to start
+ * editing on
+ * @param columnKey a key to identify the column to edit. This argument must
+ * match one of the keys of the tree columns set using
+ * {@link #setColumns(Column[])}.
+ * @return <code>true</code> if the editing process was successfully
+ * initiated
+ */
+ String startEditing(NodeContext context, String columnKey);
+ String startEditing(String columnKey);
+
+ /**
+ * @return <code>true</code> if the explorer is disposed.
+ */
+ boolean isDisposed();
+
+ /**
+ * Return the backing UI control of this GraphExplorer.
+ *
+ * @param <T>
+ * @return
+ */
+ <T> T getControl();
+
+ /**
+ * @deprecated not needed anymore, just remove calls
+ */
+ @Deprecated
+ void setModificationContext(ModificationContext modificationContext);
+
+ /**
+ * Sets the auto-expand level to be used when the input of the viewer is set
+ * using {@link #setInput(Object)}. The value 0 means that there is no
+ * auto-expand; 1 means that the invisible root element is expanded (since
+ * most concrete subclasses do not show the root element, there is usually
+ * no practical difference between using the values 0 and 1); 2 means that
+ * top-level elements are expanded, but not their children; 3 means that
+ * top-level elements are expanded, and their children, but not
+ * grandchildren; and so on.
+ * <p>
+ * The value {@value #ALL_LEVELS} means that all subtrees should be
+ * expanded.
+ * </p>
+ *
+ * @param level non-negative level, or {@value #ALL_LEVELS} to expand all
+ * levels of the tree
+ */
+ void setAutoExpandLevel(int level);
+
+ /**
+ * Sets the implementation that this GraphExplorer shall use to persist its
+ * state when disposed and to load its state when created.
+ *
+ * In order to restore a previously persisted state, this method must be
+ * called before invoking {@link #setRoot(Object)} or
+ * {@link #setRootContext(NodeContext)}.
+ *
+ * @param persistor the persistor to use
+ */
+ void setPersistor(StatePersistor persistor);
+
+ /**
+ * @return <code>true</code> if the explorer is in editable state
+ * @see #setEditable(boolean)
+ */
+ boolean isEditable();
+
+ /**
+ * Makes this explorer editable or non-editable as far as this
+ * implementation is concerned. For a non-editable explorer
+ * {@link #startEditing(String)} and
+ * {@link #startEditing(NodeContext, String)} will do nothing. Externally
+ * added listeners (see {@link #addListener(Object)}) will still get
+ * notified of events so those need to be handled separately.
+ *
+ * <p>
+ * By default, implementations should be editable.
+ */
+ void setEditable(boolean editable);
+
+ /**
+ * Returns underlaying data object, which was clicked (with mouse).
+ * @param event Mouse Event (usually org.eclipse.swt.events.MouseEvent)
+ */
+ public Object getClicked(Object event);
+
+}
Code Review / simantics / platform.git / blobdiff