X-Git-Url: https://gerrit.simantics.org/r/gitweb?p=simantics%2Fplatform.git;a=blobdiff_plain;f=bundles%2Forg.simantics.browsing.ui%2Fsrc%2Forg%2Fsimantics%2Fbrowsing%2Fui%2FGraphExplorer.java;fp=bundles%2Forg.simantics.browsing.ui%2Fsrc%2Forg%2Fsimantics%2Fbrowsing%2Fui%2FGraphExplorer.java;h=570ac7f79a0639cacbc56bdf1239b833941d7bb7;hp=0000000000000000000000000000000000000000;hb=969bd23cab98a79ca9101af33334000879fb60c5;hpb=866dba5cd5a3929bbeae85991796acb212338a08 diff --git a/bundles/org.simantics.browsing.ui/src/org/simantics/browsing/ui/GraphExplorer.java b/bundles/org.simantics.browsing.ui/src/org/simantics/browsing/ui/GraphExplorer.java new file mode 100644 index 000000000..570ac7f79 --- /dev/null +++ b/bundles/org.simantics.browsing.ui/src/org/simantics/browsing/ui/GraphExplorer.java @@ -0,0 +1,332 @@ +/******************************************************************************* + * 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 + * @param processor + */ + void setProcessor(NodeQueryProcessor processor); + NodeQueryProcessor getProcessor(QueryKey key); + + /** + * TODO: documentation + * + * @param + * @param processor + */ + void setPrimitiveProcessor(PrimitiveQueryProcessor processor); + PrimitiveQueryProcessor getPrimitiveProcessor(PrimitiveQueryKey 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 the provided data source type + * @param dataSource the data source + */ + void setDataSource(DataSource dataSource); + + /** + * Removes the data source associated with the provided class. + * + * @param forProvidedClass + * @return the removed data source association + */ + DataSource removeDataSource(Class forProvidedClass); + + void setUIContexts(Set contexts); + + /** + * Set the root input object of this explorer. + * @param root the input object, may not be null + */ + 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 not be null + */ + 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, null is returned. + * + * Only to be invoked from the UI thread (see {@link #getThread()}. + * + * @param context the context to the possible parent node for + * @return null 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 + * @param context the UI item's context + * @param key the cache key to consult for + * @return the value in the cache or null if no value was found + */ + T query(NodeContext context, CacheKey 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 GraphExplorer. + * + * 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 null to disable filtering + */ + void setSelectionFilter(SelectionFilter f); + + void setSelectionTransformation(BinaryFunction f); + + //ISelectionProvider getSelectionProvider(); + + void setColumnsVisible(boolean visible); + void setColumns(Column[] columns); + void setColumns(Column[] columns, Consumer> callback); + Column[] getColumns(); + + /** + * @param context + */ + boolean select(NodeContext context); + boolean selectPath(Collection contexts); + boolean isVisible(NodeContext context); + + /** + * Sets the expanded state of the specified node context. + * + *

+ * May work asynchronously. + *

+ * + * @param context the context to set the expanded state for + * @param expanded true to expand, false to + * collapse + */ + void setExpanded(NodeContext context, boolean expanded); + + void addListener(T listener); + 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. + * + *

+ * 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 true if the editing process was successfully + * initiated + */ + String startEditing(NodeContext context, String columnKey); + String startEditing(String columnKey); + + /** + * @return true if the explorer is disposed. + */ + boolean isDisposed(); + + /** + * Return the backing UI control of this GraphExplorer. + * + * @param + * @return + */ + 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. + *

+ * The value {@value #ALL_LEVELS} means that all subtrees should be + * expanded. + *

+ * + * @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 true 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. + * + *

+ * By default, implementations should be editable. + */ + void setEditable(boolean editable); + +}