bundles/org.simantics.browsing.ui/src/org/simantics/browsing/ui/BuiltinKeys.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 \r
  16 import org.simantics.browsing.ui.NodeContext.ConstantKey;\r
  17 import org.simantics.browsing.ui.NodeContext.ParametrizedPrimitiveQueryKey;\r
  18 import org.simantics.browsing.ui.NodeContext.PrimitiveQueryKey;\r
  19 import org.simantics.browsing.ui.NodeContext.QueryKey;\r
  20 import org.simantics.browsing.ui.content.CheckedStateFactory;\r
  21 import org.simantics.browsing.ui.content.ComparableContext;\r
  22 import org.simantics.browsing.ui.content.ComparableContextFactory;\r
  23 import org.simantics.browsing.ui.content.ImageDecorator;\r
  24 import org.simantics.browsing.ui.content.ImageDecoratorFactory;\r
  25 import org.simantics.browsing.ui.content.Imager;\r
  26 import org.simantics.browsing.ui.content.ImagerFactory;\r
  27 import org.simantics.browsing.ui.content.LabelDecorator;\r
  28 import org.simantics.browsing.ui.content.LabelDecoratorFactory;\r
  29 import org.simantics.browsing.ui.content.Labeler;\r
  30 import org.simantics.browsing.ui.content.LabelerFactory;\r
  31 import org.simantics.browsing.ui.content.PrunedChildrenResult;\r
  32 import org.simantics.browsing.ui.content.Viewpoint;\r
  33 import org.simantics.browsing.ui.content.ViewpointContribution;\r
  34 import org.simantics.browsing.ui.content.ViewpointContributionFactory;\r
  35 import org.simantics.browsing.ui.content.ViewpointFactory;\r
  36 \r
  37 /**\r
  38  * Keys and key classes for different queries and graph explorer nodes.\r
  39  * \r
  40  * <p>\r
  41  * <code>QueryKey</code> instances are for identifying normal queries to be\r
  42  * performed. Also {@link NodeQueryProcessor}s, i.e. the query implementations,\r
  43  * use them to identify the query that they are capable of answering (see\r
  44  * {@link NodeQueryProcessor#getIdentifier()} method).\r
  45  * </p>\r
  46  * \r
  47  * <p>\r
  48  * Both <code>PrimitiveQueryKey</code> instances and\r
  49  * <code>ParametrizedPrimitiveQueryKey</code> classes are used for identifying\r
  50  * queries that are performed by {@link PrimitiveQueryProcessor}s.\r
  51  * </p>\r
  52  * \r
  53  * TODO: specify for every query key or query key class: description, query dependencies, query return value\r
  54  */\r
  55 public interface BuiltinKeys {\r
  56 \r
  57     public static class InputKey implements ConstantKey<Object> {\r
  58         private InputKey() {}\r
  59         @Override\r
  60         public String toString() {\r
  61             return "INPUT";\r
  62         }\r
  63     };\r
  64 \r
  65     /**\r
  66      * This key is used for storing the main input object into a\r
  67      * {@link NodeContext}.\r
  68      * \r
  69      * <p>\r
  70      * See <code>org.simantics.browsing.ui.common.NodeContextBuilder</code> and\r
  71      * <code>org.simantics.browsing.ui.common.NodeContextUtil</code> for ways of\r
  72      * creating NodeContext instances.\r
  73      */\r
  74     public static final ConstantKey<Object> INPUT = new InputKey();\r
  75 \r
  76     public static class UIContextKey implements ConstantKey<String> {\r
  77         private UIContextKey() {}\r
  78         @Override\r
  79         public String toString() {\r
  80             return "UI_CONTEXT";\r
  81         }\r
  82     };\r
  83 \r
  84     /**\r
  85      * This key is used for storing the node-specific ui context into a\r
  86      * {@link NodeContext}.\r
  87      * \r
  88      * <p>\r
  89      * See <code>org.simantics.browsing.ui.common.NodeContextBuilder</code> and\r
  90      * <code>org.simantics.browsing.ui.common.NodeContextUtil</code> for ways of\r
  91      * creating NodeContext instances.\r
  92      */\r
  93     public static final ConstantKey<String> UI_CONTEXT = new UIContextKey();\r
  94     \r
  95     public static class BrowseContextKey implements ConstantKey<Object> {\r
  96         private BrowseContextKey() {}\r
  97         @Override\r
  98         public String toString() {\r
  99             return "BROWSE_CONTEXT";\r
 100         }\r
 101     };\r
 102 \r
 103     /**\r
 104      * This key is used for storing the node-specific BrowseContext input object into a\r
 105      * {@link NodeContext}.\r
 106      * \r
 107      * <p>\r
 108      * See <code>org.simantics.browsing.ui.common.NodeContextBuilder</code> and\r
 109      * <code>org.simantics.browsing.ui.common.NodeContextUtil</code> for ways of\r
 110      * creating NodeContext instances.\r
 111      */\r
 112     public static final ConstantKey<Object> BROWSE_CONTEXT = new BrowseContextKey();\r
 113 \r
 114     public static class ActionBrowseContextKey implements ConstantKey<Object> {\r
 115         private ActionBrowseContextKey() {}\r
 116         @Override\r
 117         public String toString() {\r
 118             return "ACTION_BROWSE_CONTEXT";\r
 119         }\r
 120     };\r
 121 \r
 122     /**\r
 123      * This key is used for storing the node-specific ActionBrowseContext input\r
 124      * object into a {@link NodeContext}.\r
 125      * \r
 126      * <p>\r
 127      * See <code>org.simantics.browsing.ui.common.NodeContextBuilder</code> and\r
 128      * <code>org.simantics.browsing.ui.common.NodeContextUtil</code> for ways of\r
 129      * creating NodeContext instances.\r
 130      */\r
 131     public static final ConstantKey<Object> ACTION_BROWSE_CONTEXT = new ActionBrowseContextKey();\r
 132 \r
 133     public static class FilterKey implements ConstantKey<String> {\r
 134         private FilterKey() {}\r
 135         @Override\r
 136         public String toString() {\r
 137             return "FILTER";\r
 138         }\r
 139     };\r
 140 \r
 141     /**\r
 142      * This key is used for storing the filter string object into it a\r
 143      * {@link NodeContext}. The value is used by primitive query viewpoints to\r
 144      * perform pruning.\r
 145      * \r
 146      * <p>\r
 147      * See <code>org.simantics.browsing.ui.common.NodeContextBuilder</code> and\r
 148      * <code>org.simantics.browsing.ui.common.NodeContextUtil</code> for ways of\r
 149      * creating NodeContext instances.\r
 150      */\r
 151     public static final ConstantKey<String> FILTER = new FilterKey();\r
 152 \r
 153     public static final QueryKey<Viewpoint> SELECTED_VIEWPOINT = new QueryKey<Viewpoint>() {\r
 154         @Override\r
 155         public String toString() {\r
 156             return "SELECTED_VIEWPOINT";\r
 157         }\r
 158     };\r
 159 \r
 160     public static final QueryKey<String> ACTIVE_FILTER = new QueryKey<String>() {\r
 161         @Override\r
 162         public String toString() {\r
 163             return "ACTIVE_FILTER";\r
 164         }\r
 165     };\r
 166 \r
 167     public static final QueryKey<Collection<ViewpointContribution>> VIEWPOINT_CONTRIBUTIONS = new QueryKey<Collection<ViewpointContribution>>() {\r
 168         @Override\r
 169         public String toString() {\r
 170             return "VIEWPOINT_CONTRIBUTIONS";\r
 171         }\r
 172     };\r
 173 \r
 174     /**\r
 175      * A query for all available viewpoint factories for the current input.\r
 176      * <p>\r
 177      * Depends on: {@link #INPUT}\r
 178      * <p>\r
 179      * Returns: a non-null collection\r
 180      */\r
 181     public static final QueryKey<Collection<ViewpointFactory>> VIEWPOINT_FACTORIES = new QueryKey<Collection<ViewpointFactory>>() {\r
 182         @Override\r
 183         public String toString() {\r
 184             return "VIEWPOINT_FACTORIES";\r
 185         }\r
 186     };\r
 187 \r
 188     public static class SelectedViewpointFactoryKey extends ParametrizedPrimitiveQueryKey<ViewpointFactory> {\r
 189         public SelectedViewpointFactoryKey(Collection<ViewpointFactory> factories) {\r
 190             super(factories);\r
 191             assert factories != null;\r
 192         }\r
 193         @Override\r
 194         public String getKeyName() {\r
 195             return "SELECTED_VIEWPOINT_FACTORY";\r
 196         }\r
 197     };\r
 198 \r
 199     public static class ViewpointKey extends ParametrizedPrimitiveQueryKey<Viewpoint> {\r
 200         public ViewpointKey(ViewpointFactory factory) {\r
 201             super(factory);\r
 202             assert factory != null;\r
 203         }\r
 204         @Override\r
 205         public String getKeyName() {\r
 206             return "VIEWPOINT";\r
 207         }\r
 208     };\r
 209 \r
 210     public static class ViewpointContributionKey extends ParametrizedPrimitiveQueryKey<ViewpointContribution> {\r
 211         public ViewpointContributionKey(ViewpointContributionFactory factory) {\r
 212             super(factory);\r
 213             assert factory != null;\r
 214         }\r
 215         @Override\r
 216         public String getKeyName() {\r
 217             return "VIEWPOINT_CONTRIBUTION";\r
 218         }\r
 219     };\r
 220 \r
 221     /**\r
 222      * Used by <code>GraphExplorer.setTextAndImage</code>.\r
 223      */\r
 224     public static final QueryKey<Collection<LabelDecoratorFactory>> LABEL_DECORATOR_FACTORIES = new QueryKey<Collection<LabelDecoratorFactory>>() {\r
 225         @Override\r
 226         public String toString() {\r
 227             return "LABEL_DECORATOR_FACTORIES";\r
 228         }\r
 229     };\r
 230     /**\r
 231      * Used by <code>GraphExplorer.setTextAndImage</code>.\r
 232      */\r
 233     public static final QueryKey<Collection<LabelDecorator>> LABEL_DECORATORS = new QueryKey<Collection<LabelDecorator>>() {\r
 234         @Override\r
 235         public String toString() {\r
 236             return "LABEL_DECORATORS";\r
 237         }\r
 238     };\r
 239     /**\r
 240      * Used by <code>GraphExplorer.setTextAndImage</code>.\r
 241      */\r
 242     public static final QueryKey<Collection<ImageDecoratorFactory>> IMAGE_DECORATOR_FACTORIES = new QueryKey<Collection<ImageDecoratorFactory>>() {\r
 243         @Override\r
 244         public String toString() {\r
 245             return "IMAGE_DECORATOR_FACTORIES";\r
 246         }\r
 247     };\r
 248     /**\r
 249      * Used by <code>GraphExplorer.setTextAndImage</code>.\r
 250      */\r
 251     public static final QueryKey<Collection<ImageDecorator>> IMAGE_DECORATORS = new QueryKey<Collection<ImageDecorator>>() {\r
 252         @Override\r
 253         public String toString() {\r
 254             return "IMAGE_DECORATORS";\r
 255         }\r
 256     };\r
 257 \r
 258     public static final QueryKey<Labeler> SELECTED_LABELER = new QueryKey<Labeler>() {\r
 259         @Override\r
 260         public String toString() {\r
 261             return "SELECTED_LABELER";\r
 262         }\r
 263     };\r
 264 \r
 265     public static final QueryKey<Imager> SELECTED_IMAGER = new QueryKey<Imager>() {\r
 266         @Override\r
 267         public String toString() {\r
 268             return "SELECTED_IMAGER";\r
 269         }\r
 270     };\r
 271 \r
 272     public static final QueryKey<Collection<LabelDecoratorFactory>> SELECTED_LABEL_DECORATOR_FACTORIES = new QueryKey<Collection<LabelDecoratorFactory>>() {\r
 273         @Override\r
 274         public String toString() {\r
 275             return "SELECTED_LABEL_DECORATOR_FACTORIES";\r
 276         }\r
 277     };\r
 278 \r
 279     public static final QueryKey<Collection<ImageDecoratorFactory>> SELECTED_IMAGE_DECORATOR_FACTORIES = new QueryKey<Collection<ImageDecoratorFactory>>() {\r
 280         @Override\r
 281         public String toString() {\r
 282             return "SELECTED_IMAGE_DECORATOR_FACTORIES";\r
 283         }\r
 284     };\r
 285 \r
 286     /**\r
 287      * A query for all available labeler factories for the current input.\r
 288      * <p>\r
 289      * Depends on: {@link #INPUT}\r
 290      * <p>\r
 291      * Returns: a non-null collection\r
 292      */\r
 293     public static final QueryKey<Collection<LabelerFactory>> LABELER_FACTORIES = new QueryKey<Collection<LabelerFactory>>() {\r
 294         @Override\r
 295         public String toString() {\r
 296             return "LABELER_FACTORIES";\r
 297         }\r
 298     };\r
 299 \r
 300     /**\r
 301      * A query for all available imager factories for the current input.\r
 302      * <p>\r
 303      * Depends on: {@link #INPUT}\r
 304      * <p>\r
 305      * Returns: a non-null collection\r
 306      */\r
 307     public static final QueryKey<Collection<ImagerFactory>> IMAGER_FACTORIES = new QueryKey<Collection<ImagerFactory>>() {\r
 308         @Override\r
 309         public String toString() {\r
 310             return "IMAGER_FACTORIES";\r
 311         }\r
 312     };\r
 313 \r
 314     public static class LabelerKey extends ParametrizedPrimitiveQueryKey<Labeler> {\r
 315         public LabelerKey(LabelerFactory factory) {\r
 316             super(factory);\r
 317             assert factory != null;\r
 318         }\r
 319         @Override\r
 320         public String getKeyName() {\r
 321             return "LABELER";\r
 322         }\r
 323     };\r
 324 \r
 325     public static class CheckedStateKey extends ParametrizedPrimitiveQueryKey<CheckedState> {\r
 326         public CheckedStateKey(CheckedStateFactory factory) {\r
 327             super(factory);\r
 328             assert factory != null;\r
 329         }\r
 330         @Override\r
 331         public String getKeyName() {\r
 332             return "CHECK_STATE";\r
 333         }\r
 334     };\r
 335 \r
 336     public static class LabelDecoratorKey extends ParametrizedPrimitiveQueryKey<LabelDecorator> {\r
 337         public LabelDecoratorKey(LabelDecoratorFactory factory) {\r
 338             super(factory);\r
 339             assert factory != null;\r
 340         }\r
 341         @Override\r
 342         public String getKeyName() {\r
 343             return "LABEL_DECORATOR";\r
 344         }\r
 345     };\r
 346 \r
 347     public static class ImagerKey extends ParametrizedPrimitiveQueryKey<Imager> {\r
 348         public ImagerKey(ImagerFactory factory) {\r
 349             super(factory);\r
 350             assert factory != null;\r
 351         }\r
 352         @Override\r
 353         public String getKeyName() {\r
 354             return "IMAGER";\r
 355         }\r
 356     };\r
 357 \r
 358     public static class ImageDecoratorKey extends ParametrizedPrimitiveQueryKey<ImageDecorator> {\r
 359         public ImageDecoratorKey(ImageDecoratorFactory factory) {\r
 360             super(factory);\r
 361             assert factory != null;\r
 362         }\r
 363         @Override\r
 364         public String getKeyName() {\r
 365             return "IMAGE_DECORATOR";\r
 366         }\r
 367     };\r
 368 \r
 369     /**\r
 370      * A query that returns a collection of {@link SelectionRequest}s based on\r
 371      * the current input. The selection requests are used to dictate whether a\r
 372      * child INodeContext of the input INodeContext gets filtered out from the\r
 373      * result of the {@link #PRUNED_CHILDREN} query.\r
 374      * \r
 375      * <p>\r
 376      * The query is free to return <code>null</code> if there are no filters for\r
 377      * the query input.\r
 378      * </p>\r
 379      */\r
 380     public static final PrimitiveQueryKey<Collection<SelectionRequest>> SELECTION_REQUESTS = new PrimitiveQueryKey<Collection<SelectionRequest>>() {\r
 381         @Override\r
 382         public String toString() {\r
 383             return "SELECTION_REQUEST";\r
 384         }\r
 385     };\r
 386 \r
 387     //------------------------------------------------------------------------\r
 388 \r
 389     /**\r
 390      * A query that requests for the currently selected viewpoint of a node\r
 391      * context, gets all of its children from the viewpoint and prunes the set\r
 392      * of children based on active filters (selection requests).\r
 393      * <p>\r
 394      * Depends on: {@link #SELECTED_VIEWPOINT}, {@link #SELECTION_REQUESTS}\r
 395      * <p>\r
 396      * Returns: A {@link PrunedChildrenResult} which contains the pruned set of\r
 397      * children as INodeContext[] and the original amount of children before\r
 398      * pruning them.\r
 399      */\r
 400     public static final QueryKey<PrunedChildrenResult> PRUNED_CHILDREN = new QueryKey<PrunedChildrenResult>() {\r
 401         @Override\r
 402         public String toString() {\r
 403             return "PRUNED_CHILDREN";\r
 404         }\r
 405     };\r
 406 \r
 407     /**\r
 408      * A query to transform INodeContext's into ComparableContexts that can be\r
 409      * sorted.\r
 410      * <p>\r
 411      * Depends on: {@link #PRUNED_CHILDREN}\r
 412      * <p>\r
 413      * Returns: ComparableContext[] of the same size as the input or\r
 414      * <code>null</code> if no selected ComparableFactory could be discovered\r
 415      * which indicates that child nodes cannot be sorted.\r
 416      */\r
 417     public static final QueryKey<ComparableContext[]> COMPARABLE_CHILDREN = new QueryKey<ComparableContext[]>() {\r
 418         @Override\r
 419         public String toString() {\r
 420             return "COMPARABLE_CHILDREN";\r
 421         }\r
 422     };\r
 423 \r
 424     /**\r
 425      * A query for all available comparable factories for the current input.\r
 426      * <p>\r
 427      * Depends on: {@link #INPUT}\r
 428      * <p>\r
 429      * Returns: a non-null collection\r
 430      */\r
 431     public static final QueryKey<Collection<ComparableContextFactory>> COMPARABLE_FACTORIES = new QueryKey<Collection<ComparableContextFactory>>() {\r
 432         @Override\r
 433         public String toString() {\r
 434             return "COMPARABLE_FACTORIES";\r
 435         }\r
 436     };\r
 437 \r
 438     public static class SelectedComparableFactoryKey extends ParametrizedPrimitiveQueryKey<ComparableContextFactory> {\r
 439         public SelectedComparableFactoryKey(Collection<ComparableContextFactory> factories) {\r
 440             super(factories);\r
 441             assert factories != null;\r
 442         }\r
 443         @Override\r
 444         public String getKeyName() {\r
 445             return "SELECTED_COMPARABLE_FACTORY";\r
 446         }\r
 447     }\r
 448 \r
 449     /**\r
 450      * Returns the final child nodes for a node after pruning and sorting them.\r
 451      * If you need to discover the set of children for a node you should use\r
 452      * {@link BuiltinKeys#PRUNED_CHILDREN} instead if you don't need the\r
 453      * sorting. To get the non-pruned set of all children of a node\r
 454      * <p>\r
 455      * Depends on: {@link BuiltinKeys#COMPARABLE_CHILDREN},\r
 456      * {@link BuiltinKeys#PRUNED_CHILDREN}\r
 457      * <p>\r
 458      * Returns: an array of {@link NodeContext}s.\r
 459      */\r
 460     public static final QueryKey<NodeContext[]> FINAL_CHILDREN = new QueryKey<NodeContext[]>() {\r
 461         @Override\r
 462         public String toString() {\r
 463             return "FINAL_CHILDREN";\r
 464         }\r
 465     };\r
 466 \r
 467     /**\r
 468      * Returns whether a node is expanded in the UI or not.\r
 469      * <p>\r
 470      * Returns: {@link Boolean#TRUE} if expanded, {@link Boolean#FALSE} if not.\r
 471      */\r
 472     public static final PrimitiveQueryKey<Boolean> IS_EXPANDED = new PrimitiveQueryKey<Boolean>() {\r
 473         @Override\r
 474         public String toString() {\r
 475             return "IS_EXPANDED";\r
 476         }\r
 477     };\r
 478 \r
 479     /**\r
 480      * Tells whether a node is "checked" in the UI or not. This only takes\r
 481      * effect if the GraphExplorer was created with support for checkedness\r
 482      * visualisation.\r
 483      * <p>\r
 484      * Returns: {@link CheckedState}\r
 485      */\r
 486     public static final QueryKey<CheckedState> IS_CHECKED = new QueryKey<CheckedState>() {\r
 487         @Override\r
 488         public String toString() {\r
 489             return "IS_CHECKED";\r
 490         }\r
 491     };\r
 492 \r
 493     /**\r
 494      * Returns how many children should maximally be shown for a node. By\r
 495      * default the set of shown children is pruned if there are too many of them\r
 496      * to be shown.\r
 497      * <p>\r
 498      * Returns:\r
 499      * <ul>\r
 500      * <li>0 < x &le; {@value Integer#MAX_VALUE} to tell the maximum amount of\r
 501      * children to show</li>\r
 502      * <li><code>null</code> indicates don't care</li>\r
 503      * </ul>\r
 504      * May not return < 0.\r
 505      */\r
 506     public static final PrimitiveQueryKey<Integer> SHOW_MAX_CHILDREN = new PrimitiveQueryKey<Integer>() {\r
 507         @Override\r
 508         public String toString() {\r
 509             return "SHOW_MAX_CHILDREN";\r
 510         }\r
 511     };\r
 512 \r
 513     public static class IsRootKey implements ConstantKey<Object> {\r
 514         private IsRootKey() {}\r
 515         @Override\r
 516         public String toString() {\r
 517             return "IS_ROOT";\r
 518         }\r
 519     };\r
 520 \r
 521     /**\r
 522      * Set to {@link Boolean#TRUE} for a NodeContext that describes the root\r
 523      * input of a {@link GraphExplorer}.\r
 524      */\r
 525     public static final ConstantKey<Object> IS_ROOT = new IsRootKey();\r
 526 \r
 527 }\r