bundles/org.simantics.utils.datastructures/src/org/simantics/utils/datastructures/hints/IHintTracker.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.utils.datastructures.hints;\r
  13 \r
  14 /**\r
  15  * IHintTracker is an interface for tracking any hints of a single IHintContext.\r
  16  * \r
  17  * <p>\r
  18  * The main purpose of this interface is to enable very easy switching of the\r
  19  * tracked hint context. Only a call to the {@link #track(IHintContext)} method\r
  20  * is required. All hint listeners registered into the tracked will\r
  21  * automatically be switched to listen to the new context instead. Hint\r
  22  * listeners can be added or removed while tracking an IHintContext.\r
  23  * </p>\r
  24  * \r
  25  * <p>\r
  26  * Always be sure to {@link #untrack()} any IHintContext that you're tracking\r
  27  * after the tracker is no longer needed. Otherwise you will most likely have\r
  28  * invalid listeners within the tracked IHintContext resulting in erroneous\r
  29  * behavior.\r
  30  * </p>\r
  31  * \r
  32  * @author Tuukka Lehtonen\r
  33  */\r
  34 public interface IHintTracker extends IHintObservable {\r
  35 \r
  36     /**\r
  37      * Start tracking the specified IHintContext with all the listeners\r
  38      * registered into this IHintObservable. Tracking of any previous\r
  39      * IHintContext will be discontinued.\r
  40      * \r
  41      * @param ctx the new IHintContext to track\r
  42      */\r
  43     public void track(IHintContext ctx);\r
  44     \r
  45     /**\r
  46      * A call to this method should have the same implications as a\r
  47      * <code>track(null)</code> call.\r
  48      */\r
  49     void untrack();\r
  50     \r
  51 }\r