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

   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
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.browsing.ui;\r
  13 \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
  18 \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
  27 \r
  28 /**\r
  29  * \r
  30  */\r
  31 public interface GraphExplorer extends IAdaptable {\r
  32         \r
  33     /**\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
  36      */\r
  37     public static final String KEY_GRAPH_EXPLORER = "GraphExplorer";\r
  38 \r
  39     /**\r
  40      * @see #setAutoExpandLevel(int)\r
  41      */\r
  42     public static int ALL_LEVELS = -1;\r
  43 \r
  44     public static final Object EMPTY_INPUT = new Object() {\r
  45 \r
  46         @Override\r
  47         public String toString() { return "GraphExplorer.EMPTY_INPUT"; };\r
  48 \r
  49     };\r
  50 \r
  51     /**\r
  52      * @deprecated not needed anymore, just remove all uses\r
  53      */\r
  54     @Deprecated\r
  55     public interface ModificationContext extends IAdaptable {\r
  56 \r
  57     }\r
  58 \r
  59     /**\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
  63      * \r
  64      * @return the single access thread used by this GraphExplorer\r
  65      */\r
  66     IThreadWorkQueue getThread();\r
  67 \r
  68     /**\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
  71      * \r
  72      * Use {@link Integer#MAX_VALUE} to maximize the limit.\r
  73      * \r
  74      * @return max amount of children shown for a node, must not be negative\r
  75      */\r
  76     int getMaxChildren();\r
  77     void setMaxChildren(int maxChildren);\r
  78 \r
  79     /**\r
  80      * Query for context-specific max children to show value using the provided\r
  81      * query manager and node context.\r
  82      * \r
  83      * @param manager\r
  84      * @param 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
  87      */\r
  88     int getMaxChildren(NodeQueryManager manager, NodeContext context);\r
  89 \r
  90     /**\r
  91      * TODO: documentation\r
  92      * \r
  93      * @param <T>\r
  94      * @param processor\r
  95      */\r
  96     <T> void setProcessor(NodeQueryProcessor<T> processor);\r
  97     <T> NodeQueryProcessor<T> getProcessor(QueryKey<T> key);\r
  98 \r
  99     /**\r
 100      * TODO: documentation\r
 101      * \r
 102      * @param <T>\r
 103      * @param processor\r
 104      */\r
 105     <T> void setPrimitiveProcessor(PrimitiveQueryProcessor<T> processor);\r
 106     <T> PrimitiveQueryProcessor<T> getPrimitiveProcessor(PrimitiveQueryKey<T> key);\r
 107 \r
 108     /**\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
 114      * \r
 115      * @param <T> the provided data source type\r
 116      * @param dataSource the data source\r
 117      */\r
 118     <T> void setDataSource(DataSource<T> dataSource);\r
 119 \r
 120     /**\r
 121      * Removes the data source associated with the provided class.\r
 122      * \r
 123      * @param forProvidedClass\r
 124      * @return the removed data source association\r
 125      */\r
 126     <T> DataSource<T> removeDataSource(Class<T> forProvidedClass);\r
 127 \r
 128     void setUIContexts(Set<String> contexts);\r
 129 \r
 130     /**\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
 133      */\r
 134     void setRoot(Object root);\r
 135 \r
 136     /**\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
 141      * \r
 142      * @param root the root node context, may <b>not</b> be <code>null</code>\r
 143      */\r
 144     void setRootContext(NodeContext context);\r
 145 \r
 146     /**\r
 147      * Get the current UI item context of the root input object.\r
 148      * \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
 152      * \r
 153      * @return input object's UI item context\r
 154      */\r
 155     NodeContext getRoot();\r
 156 \r
 157     /**\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
 160      * \r
 161      * Only to be invoked from the UI thread (see {@link #getThread()}.\r
 162      * \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
 165      */\r
 166     NodeContext getParentContext(NodeContext context);\r
 167 \r
 168     /**\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
 172      * \r
 173      * @param <T>\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
 177      */\r
 178     <T> T query(NodeContext context, CacheKey<T> key);\r
 179 \r
 180     // --- UI related things ---\r
 181 \r
 182     public interface TransientExplorerState {\r
 183         Integer getActiveColumn();      \r
 184     }\r
 185     \r
 186     Object getWidgetSelection();\r
 187     TransientExplorerState getTransientState();\r
 188     \r
 189     SelectionDataResolver getSelectionDataResolver();\r
 190     void setSelectionDataResolver(SelectionDataResolver r);\r
 191 \r
 192     /**\r
 193      * @return the current {@link SelectionFilter}\r
 194      */\r
 195     SelectionFilter getSelectionFilter();\r
 196 \r
 197     /**\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
 200      * \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
 203      * \r
 204      * @param f the new filter or <code>null</code> to disable filtering\r
 205      */\r
 206     void setSelectionFilter(SelectionFilter f);\r
 207 \r
 208     void setSelectionTransformation(BinaryFunction<Object[], GraphExplorer, Object[]> f);\r
 209 \r
 210     //ISelectionProvider getSelectionProvider();\r
 211 \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
 216 \r
 217     /**\r
 218      * @param context\r
 219      */\r
 220     boolean select(NodeContext context);\r
 221     boolean selectPath(Collection<NodeContext> contexts);\r
 222     boolean isVisible(NodeContext context);\r
 223 \r
 224     /**\r
 225      * Sets the expanded state of the specified node context.\r
 226      * \r
 227      * <p>\r
 228      * May work asynchronously.\r
 229      * </p>\r
 230      * \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
 233      *        collapse\r
 234      */\r
 235     void setExpanded(NodeContext context, boolean expanded);\r
 236 \r
 237     <T> void addListener(T listener);\r
 238     <T> void removeListener(T listener);\r
 239 \r
 240     void setFocus();\r
 241 \r
 242     /**\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
 248      * \r
 249      * <p>\r
 250      * Only to be invoked from the UI thread (see {@link #getThread()}.\r
 251      * \r
 252      * @param context the node, i.e. tree item or tree-table row to start\r
 253      *        editing on\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
 258      *         initiated\r
 259      */\r
 260     String startEditing(NodeContext context, String columnKey);\r
 261     String startEditing(String columnKey);\r
 262 \r
 263     /**\r
 264      * @return <code>true</code> if the explorer is disposed.\r
 265      */\r
 266     boolean isDisposed();\r
 267 \r
 268     /**\r
 269      * Return the backing UI control of this GraphExplorer.\r
 270      * \r
 271      * @param <T>\r
 272      * @return\r
 273      */\r
 274     <T> T getControl();\r
 275 \r
 276     /**\r
 277      * @deprecated not needed anymore, just remove calls\r
 278      */\r
 279     @Deprecated\r
 280     void setModificationContext(ModificationContext modificationContext);\r
 281 \r
 282     /**\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
 291      * <p>\r
 292      * The value {@value #ALL_LEVELS} means that all subtrees should be\r
 293      * expanded.\r
 294      * </p>\r
 295      * \r
 296      * @param level non-negative level, or {@value #ALL_LEVELS} to expand all\r
 297      *        levels of the tree\r
 298      */\r
 299     void setAutoExpandLevel(int level);\r
 300 \r
 301     /**\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
 304      * \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
 308      * \r
 309      * @param persistor the persistor to use\r
 310      */\r
 311     void setPersistor(StatePersistor persistor);\r
 312 \r
 313     /**\r
 314      * @return <code>true</code> if the explorer is in editable state\r
 315      * @see #setEditable(boolean)\r
 316      */\r
 317     boolean isEditable();\r
 318 \r
 319     /**\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
 326      * \r
 327      * <p>\r
 328      * By default, implementations should be editable.\r
 329      */\r
 330     void setEditable(boolean editable);\r
 331     \r
 332     /**\r
 333      * Returns underlaying data object, which was clicked (with mouse).\r
 334      * @param event Mouse Event (usually org.eclipse.swt.events.MouseEvent) \r
 335      */\r
 336     public Object getClicked(Object event);\r
 337 \r
 338 }\r