bundles/org.simantics.browsing.ui/src/org/simantics/browsing/ui/GraphExplorer.java

   1 /*******************************************************************************
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management
   3  * in Industry THTH ry.
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *
   9  * Contributors:
  10  *     VTT Technical Research Centre of Finland - initial API and implementation
  11  *******************************************************************************/
  12 package org.simantics.browsing.ui;
  13
  14 import java.util.Collection;
  15 import java.util.Map;
  16 import java.util.Set;
  17 import java.util.function.BiFunction;
  18 import java.util.function.Consumer;
  19
  20 import org.eclipse.core.runtime.IAdaptable;
  21 import org.simantics.browsing.ui.NodeContext.CacheKey;
  22 import org.simantics.browsing.ui.NodeContext.PrimitiveQueryKey;
  23 import org.simantics.browsing.ui.NodeContext.QueryKey;
  24 import org.simantics.browsing.ui.content.Labeler;
  25 import org.simantics.browsing.ui.content.Labeler.Modifier;
  26 import org.simantics.utils.threads.IThreadWorkQueue;
  27
  28 /**
  29  *
  30  */
  31 public interface GraphExplorer extends IAdaptable {
  32
  33     /**
  34      * A key that can be used to associate GraphExplorer instances with other
  35      * objects in, e.g. SWT widgets using Widget.setData(String, Object).
  36      */
  37     public static final String KEY_GRAPH_EXPLORER = "GraphExplorer";
  38
  39     /**
  40      * @see #setAutoExpandLevel(int)
  41      */
  42     public static int ALL_LEVELS = -1;
  43
  44     public static final Object EMPTY_INPUT = new Object() {
  45
  46         @Override
  47         public String toString() { return "GraphExplorer.EMPTY_INPUT"; };
  48
  49     };
  50
  51     /**
  52      * @deprecated not needed anymore, just remove all uses
  53      */
  54     @Deprecated
  55     public interface ModificationContext extends IAdaptable {
  56
  57     }
  58
  59     /**
  60      * An IGraphExplorer has a UI which uses some toolkit (AWT/SWT). The
  61      * toolkits are assumed to be single-threaded. The return value of this
  62      * method indicates the thread used for UI-related accesses.
  63      *
  64      * @return the single access thread used by this GraphExplorer
  65      */
  66     IThreadWorkQueue getThread();
  67
  68     /**
  69      * Override this method to customize the maximum amount of child nodes that
  70      * are shown for any node. The returned value must be non-negative.
  71      *
  72      * Use {@link Integer#MAX_VALUE} to maximize the limit.
  73      *
  74      * @return max amount of children shown for a node, must not be negative
  75      */
  76     int getMaxChildren();
  77     void setMaxChildren(int maxChildren);
  78
  79     /**
  80      * Query for context-specific max children to show value using the provided
  81      * query manager and node context.
  82      *
  83      * @param manager
  84      * @param context
  85      * @return node specific child limit or what is returned by
  86      *         {@link #getMaxChildren()} if node specific limit is not set
  87      */
  88     int getMaxChildren(NodeQueryManager manager, NodeContext context);
  89
  90     /**
  91      * TODO: documentation
  92      *
  93      * @param <T>
  94      * @param processor
  95      */
  96     <T> void setProcessor(NodeQueryProcessor<T> processor);
  97     <T> NodeQueryProcessor<T> getProcessor(QueryKey<T> key);
  98
  99     /**
 100      * TODO: documentation
 101      *
 102      * @param <T>
 103      * @param processor
 104      */
 105     <T> void setPrimitiveProcessor(PrimitiveQueryProcessor<T> processor);
 106     <T> PrimitiveQueryProcessor<T> getPrimitiveProcessor(PrimitiveQueryKey<T> key);
 107
 108     /**
 109      * Associates the provided DataSource implementation with class T in this
 110      * GraphExplorer. PrimitiveQueryProcessor implementations can access these
 111      * data sources through the class provided by
 112      * {@link DataSource#getProvidedClass()}. Specifying a new association for
 113      * the same T will overwrite the previous data source association.
 114      *
 115      * @param <T> the provided data source type
 116      * @param dataSource the data source
 117      */
 118     <T> void setDataSource(DataSource<T> dataSource);
 119
 120     /**
 121      * Removes the data source associated with the provided class.
 122      *
 123      * @param forProvidedClass
 124      * @return the removed data source association
 125      */
 126     <T> DataSource<T> removeDataSource(Class<T> forProvidedClass);
 127
 128     void setUIContexts(Set<String> contexts);
 129
 130     /**
 131      * Set the root input object of this explorer.
 132      * @param root the input object, may <b>not</b> be <code>null</code>
 133      */
 134     void setRoot(Object root);
 135
 136     /**
 137      * Set the root node context of this explorer. Allows the client to provide
 138      * the complete NodeContext to be used as the explorer root input while
 139      * {@link #setRoot(Object)} only allows the client to provide the
 140      * {@link BuiltinKeys#INPUT} data for the root NodeContext.
 141      *
 142      * @param root the root node context, may <b>not</b> be <code>null</code>
 143      */
 144     void setRootContext(NodeContext context);
 145
 146     /**
 147      * Get the current UI item context of the root input object.
 148      *
 149      * Return value is undefined for a disposed or uninitialized GraphExplorer.
 150      * An explorer is uninitialized when {@link #setRoot(Object)} or
 151      * {@link #setRootContext(NodeContext)} has not been invoked yet.
 152      *
 153      * @return input object's UI item context
 154      */
 155     NodeContext getRoot();
 156
 157     /**
 158      * Get the parent node context of the specified node context. If there is no
 159      * visible parent node in the explorer, <code>null</code> is returned.
 160      *
 161      * Only to be invoked from the UI thread (see {@link #getThread()}.
 162      *
 163      * @param context the context to the possible parent node for
 164      * @return <code>null</code> if there is no parent node
 165      */
 166     NodeContext getParentContext(NodeContext context);
 167
 168     /**
 169      * Consult the explorer's cache for the specified node and key. The method
 170      * will return a result only if the requested query has been previously
 171      * performed and has not been cleared (invalidated).
 172      *
 173      * @param <T>
 174      * @param context the UI item's context
 175      * @param key the cache key to consult for
 176      * @return the value in the cache or <code>null</code> if no value was found
 177      */
 178     <T> T query(NodeContext context, CacheKey<T> key);
 179
 180     // --- UI related things ---
 181
 182     public interface TransientExplorerState {
 183         Integer getActiveColumn();
 184     }
 185
 186     Object getWidgetSelection();
 187     TransientExplorerState getTransientState();
 188
 189     SelectionDataResolver getSelectionDataResolver();
 190     void setSelectionDataResolver(SelectionDataResolver r);
 191
 192     /**
 193      * @return the current {@link SelectionFilter}
 194      */
 195     SelectionFilter getSelectionFilter();
 196
 197     /**
 198      * Set new {@link SelectionFilter} for this explorer to control what will be
 199      * put into selections provided by this <code>GraphExplorer</code>.
 200      *
 201      * TODO: specify what should happen to the current provided selection when a
 202      * new filter is set. Should it change immediately or be left as is?
 203      *
 204      * @param f the new filter or <code>null</code> to disable filtering
 205      */
 206     void setSelectionFilter(SelectionFilter f);
 207
 208     void setSelectionTransformation(BiFunction<GraphExplorer, Object[], Object[]> f);
 209
 210     //ISelectionProvider getSelectionProvider();
 211
 212     void setColumnsVisible(boolean visible);
 213     void setColumns(Column[] columns);
 214     void setColumns(Column[] columns, Consumer<Map<Column, Object>> callback);
 215     Column[] getColumns();
 216
 217     /**
 218      * @param context
 219      */
 220     boolean select(NodeContext context);
 221     boolean selectPath(Collection<NodeContext> contexts);
 222     boolean isVisible(NodeContext context);
 223
 224     /**
 225      * Sets the expanded state of the specified node context.
 226      *
 227      * <p>
 228      * May work asynchronously.
 229      * </p>
 230      *
 231      * @param context the context to set the expanded state for
 232      * @param expanded <code>true</code> to expand, <code>false</code> to
 233      *        collapse
 234      */
 235     void setExpanded(NodeContext context, boolean expanded);
 236
 237     <T> void addListener(T listener);
 238     <T> void removeListener(T listener);
 239
 240     void setFocus();
 241
 242     /**
 243      * Attempts to start in-line editing at the specified INodeContext in this
 244      * graph explorer. The nature of the in-line editing (i.e. used controls)
 245      * depends on the kind of {@link Modifier} returned by the {@link Labeler}
 246      * of the specified node context. The labeler is determined by the
 247      * {@link BuiltinKeys#SELECTED_LABELER} query.
 248      *
 249      * <p>
 250      * Only to be invoked from the UI thread (see {@link #getThread()}.
 251      *
 252      * @param context the node, i.e. tree item or tree-table row to start
 253      *        editing on
 254      * @param columnKey a key to identify the column to edit. This argument must
 255      *        match one of the keys of the tree columns set using
 256      *        {@link #setColumns(Column[])}.
 257      * @return <code>true</code> if the editing process was successfully
 258      *         initiated
 259      */
 260     String startEditing(NodeContext context, String columnKey);
 261     String startEditing(String columnKey);
 262
 263     /**
 264      * @return <code>true</code> if the explorer is disposed.
 265      */
 266     boolean isDisposed();
 267
 268     /**
 269      * Return the backing UI control of this GraphExplorer.
 270      *
 271      * @param <T>
 272      * @return
 273      */
 274     <T> T getControl();
 275
 276     /**
 277      * @deprecated not needed anymore, just remove calls
 278      */
 279     @Deprecated
 280     void setModificationContext(ModificationContext modificationContext);
 281
 282     /**
 283      * Sets the auto-expand level to be used when the input of the viewer is set
 284      * using {@link #setInput(Object)}. The value 0 means that there is no
 285      * auto-expand; 1 means that the invisible root element is expanded (since
 286      * most concrete subclasses do not show the root element, there is usually
 287      * no practical difference between using the values 0 and 1); 2 means that
 288      * top-level elements are expanded, but not their children; 3 means that
 289      * top-level elements are expanded, and their children, but not
 290      * grandchildren; and so on.
 291      * <p>
 292      * The value {@value #ALL_LEVELS} means that all subtrees should be
 293      * expanded.
 294      * </p>
 295      *
 296      * @param level non-negative level, or {@value #ALL_LEVELS} to expand all
 297      *        levels of the tree
 298      */
 299     void setAutoExpandLevel(int level);
 300
 301     /**
 302      * Sets the implementation that this GraphExplorer shall use to persist its
 303      * state when disposed and to load its state when created.
 304      *
 305      * In order to restore a previously persisted state, this method must be
 306      * called before invoking {@link #setRoot(Object)} or
 307      * {@link #setRootContext(NodeContext)}.
 308      *
 309      * @param persistor the persistor to use
 310      */
 311     void setPersistor(StatePersistor persistor);
 312
 313     /**
 314      * @return <code>true</code> if the explorer is in editable state
 315      * @see #setEditable(boolean)
 316      */
 317     boolean isEditable();
 318
 319     /**
 320      * Makes this explorer editable or non-editable as far as this
 321      * implementation is concerned. For a non-editable explorer
 322      * {@link #startEditing(String)} and
 323      * {@link #startEditing(NodeContext, String)} will do nothing. Externally
 324      * added listeners (see {@link #addListener(Object)}) will still get
 325      * notified of events so those need to be handled separately.
 326      *
 327      * <p>
 328      * By default, implementations should be editable.
 329      */
 330     void setEditable(boolean editable);
 331
 332     /**
 333      * Returns underlaying data object, which was clicked (with mouse).
 334      * @param event Mouse Event (usually org.eclipse.swt.events.MouseEvent)
 335      */
 336     public Object getClicked(Object event);
 337
 338 }