Migrated source code from Simantics SVN

[simantics/platform.git] / bundles / org.simantics.utils.datastructures / src / org / simantics / utils / datastructures / hints / IHintTracker.java

diff --git a/bundles/org.simantics.utils.datastructures/src/org/simantics/utils/datastructures/hints/IHintTracker.java b/bundles/org.simantics.utils.datastructures/src/org/simantics/utils/datastructures/hints/IHintTracker.java
new file mode 100644 (file)
index 0000000..48c7dd6
--- /dev/null
+++ b/bundles/org.simantics.utils.datastructures/src/org/simantics/utils/datastructures/hints/IHintTracker.java
@@ -0,0 +1,51 @@
+/*******************************************************************************\r
+ * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
+ * in Industry THTH ry.\r
+ * All rights reserved. This program and the accompanying materials\r
+ * are made available under the terms of the Eclipse Public License v1.0\r
+ * which accompanies this distribution, and is available at\r
+ * http://www.eclipse.org/legal/epl-v10.html\r
+ *\r
+ * Contributors:\r
+ *     VTT Technical Research Centre of Finland - initial API and implementation\r
+ *******************************************************************************/\r
+package org.simantics.utils.datastructures.hints;\r
+\r
+/**\r
+ * IHintTracker is an interface for tracking any hints of a single IHintContext.\r
+ * \r
+ * <p>\r
+ * The main purpose of this interface is to enable very easy switching of the\r
+ * tracked hint context. Only a call to the {@link #track(IHintContext)} method\r
+ * is required. All hint listeners registered into the tracked will\r
+ * automatically be switched to listen to the new context instead. Hint\r
+ * listeners can be added or removed while tracking an IHintContext.\r
+ * </p>\r
+ * \r
+ * <p>\r
+ * Always be sure to {@link #untrack()} any IHintContext that you're tracking\r
+ * after the tracker is no longer needed. Otherwise you will most likely have\r
+ * invalid listeners within the tracked IHintContext resulting in erroneous\r
+ * behavior.\r
+ * </p>\r
+ * \r
+ * @author Tuukka Lehtonen\r
+ */\r
+public interface IHintTracker extends IHintObservable {\r
+\r
+    /**\r
+     * Start tracking the specified IHintContext with all the listeners\r
+     * registered into this IHintObservable. Tracking of any previous\r
+     * IHintContext will be discontinued.\r
+     * \r
+     * @param ctx the new IHintContext to track\r
+     */\r
+    public void track(IHintContext ctx);\r
+    \r
+    /**\r
+     * A call to this method should have the same implications as a\r
+     * <code>track(null)</code> call.\r
+     */\r
+    void untrack();\r
+    \r
+}\r