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