--- /dev/null
+/*******************************************************************************\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
Code Review / simantics / platform.git / blobdiff