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