Merge pull request #7393 from petecressman/pcTracker

Update Tracker.
JMRI · Oct 12, 2019 · c403671 · c403671
2 parents 1243c2c + 2869112
commit c403671
Show file tree

Hide file tree

Showing 35 changed files with 7,435 additions and 5,782 deletions.
diff --git a/default.lcf b/default.lcf
@@ -101,7 +101,6 @@ log4j.category.org.jdom2.transform=SEVERE
 # log4j.category.jmri.jmrit.beantable.LogixTableAction=DEBUG
 # log4j.category.jmri.jmrit.display=DEBUG
 # log4j.category.jmri.jmrit.display.IndicatorTrackPaths=DEBUG
-# log4j.category.jmri.jmrit.logix=DEBUG
 # log4j.category.jmri.jmrit.progsupport=TRACE
 # log4j.category.jmri.jmrit.symbolicprog.tabbedframe=DEBUG
 # log4j.category.jmri.jmrit.symbolicprog.DecVariableValue=DEBUG

diff --git a/help/en/JavaHelpSearch/DOCS b/help/en/JavaHelpSearch/DOCS
diff --git a/help/en/JavaHelpSearch/DOCS.TAB b/help/en/JavaHelpSearch/DOCS.TAB
diff --git a/help/en/JavaHelpSearch/OFFSETS b/help/en/JavaHelpSearch/OFFSETS
diff --git a/help/en/JavaHelpSearch/POSITIONS b/help/en/JavaHelpSearch/POSITIONS
diff --git a/help/en/JavaHelpSearch/SCHEMA b/help/en/JavaHelpSearch/SCHEMA
@@ -1,2 +1,2 @@
 JavaSearch 1.0
-TMAP bs=2048 rt=72 fl=-1 id1=17143 id2=1
+TMAP bs=2048 rt=72 fl=-1 id1=17148 id2=1
diff --git a/help/en/JavaHelpSearch/TMAP b/help/en/JavaHelpSearch/TMAP
diff --git a/help/en/JmriHelp_enIndex.xml b/help/en/JmriHelp_enIndex.xml
@@ -2,6 +2,8 @@
 <!DOCTYPE index PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN" "http://java.sun.com/products/javahelp/index_2_0.dtd"><!--generated by JHelpDev Version: 0.63, 14 May 2008, see jhelpdev.sourceforge.net-->
 
 <index version="1.0">
+ <indexitem text="Train Trackers " target="package.jmri.jmrit.logix.Tracker"/>
+
  <indexitem text="Acela (CTI) - Hardware, Connection, Tools " target="html.hardware.acela.index"/>
 
  <indexitem text="Acknowledgements " target="Acknowledgements"/>

diff --git a/help/en/JmriHelp_enTOC.xml b/help/en/JmriHelp_enTOC.xml
@@ -520,6 +520,8 @@
 
    <tocitem text="When Warrant Speeds Are Modified " target="package.jmri.jmrit.logix.SpeedChanges"/>
 
+   <tocitem text="Train Trackers " target="package.jmri.jmrit.logix.Tracker"/>
+
    <tocitem text="The Occupancy Block Tables " target="package.jmri.jmrit.logix.OBlockTable"/>
 
    <tocitem text="Creating and Editing OBlocks, Portals and OPaths " target="package.jmri.jmrit.logix.OBlockEdit"/>

diff --git a/help/en/Map.jhm b/help/en/Map.jhm
diff --git a/help/en/package/jmri/jmrit/logix/Tracker.shtml b/help/en/package/jmri/jmrit/logix/Tracker.shtml
@@ -0,0 +1,148 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+"http://www.w3.org/TR/html4/strict.dtd">
+
+<html lang="en">
+<head>
+  <meta name="generator" content=
+  "HTML Tidy for Mac OS X (vers 31 October 2006 - Apple Inc. build 15.17), see www.w3.org">
+
+  <title>JMRI: Using Trackers</title>
+  <meta name="author" content="Pete Cressman">
+  <meta name="keywords" content="JMRI help Using Tracker">
+  <!-- Style -->
+  <meta http-equiv="content-type" content=
+  "text/html; charset=us-ascii">
+  <link rel="stylesheet" type="text/css" href="/css/default.css"
+  media="screen">
+  <link rel="stylesheet" type="text/css" href="/css/print.css"
+  media="print">
+  <link rel="icon" href="/images/jmri.ico" type="image/png">
+  <link rel="home" title="Home" href="/"><!-- /style -->
+</head>
+
+<body>
+  <!--#include virtual="/Header" -->
+
+  <div class="nomenu" id="mBody">
+    <div id="mainContent">
+      <h1>Train Trackers</h1>
+     	A <b>Tracker</b> is a means to to see the movement of trains on your layout panel. 
+    	A Tracker has a marker identifying a train 
+    	moving on your panel layout diagram following wherever an operator
+    	drives his train on your layout.  The position of each tracked train and the time is spends 
+    	occupying a block is displayed in a window. A status log
+    	is kept of the progress of the trackers.
+
+      <h2>What's Needed to Have a Tracker</h2>
+      	Trackers function on the same foundation as Warrants. That is, track occupation
+      	detection is by <b>OBlocks</b> and the directions trains move by
+      	<b>Portals</b> and <b>Paths</b>. For detailed information about what 
+      	these objects are and how to make
+      	them see <a href="../display/CircuitBuilder.shtml">Circuit Builder</a>
+      	or <a href="../OBlockTable.shtml">Occupancy Block Tables</a>. 
+      	<p>
+      	Next, your panel
+      	layout diagram must done with Indicator Track icons. These icons display the status
+      	of the block they represent with colors and can show names.  If your diagram has already 
+      	been created using regular track icons, they can easily be converted to Indicator
+      	Track icons with <b><a href="../display/CircuitBuilder.shtml">Circuit Builder</a></b>. 
+      	The <a href="../display/ItemPalette.shtml">Item Palette</a> has more information
+      	about Indicator Track icons.
+      	</p><p>
+      	All the track of your layout should be represented
+      	with OBlocks, even the sections with no sensors. Although Tracker cannot detect
+      	when such a "dark block" is entered, it is smart enough to know when a train has
+      	passed through one. So it is beneficial to configure them when there is a path
+      	through them connecting one occupancy block with another. 
+      	</p><p>
+      	The last requirement is each block should have
+      	at least one Indicator Track icon configured to display names. The popup
+      	window displayed when the <i>Edit Icon</i> menu item is selected
+      	has a checkbox labeled "<i>Display Train Name when occupied</i>".
+      	(You must edit with 
+      	<a href="../display/ControlPanelEditor.shtml">Control Panel Editor</a>
+      	to get this window.) 
+      	Check this box to show the current location of a tracked train.
+      	</p>
+
+      <h2>How to Make a Tracker</h2>
+      	The <b>Warrants</b> menu has a <i>Train Trackers</i> item that opens the 
+      	<b>Tracker Table</b> window. The table has a <b>New Tracker</b> button that
+      	displays a Create Tracker dialog. Enter the name of the train and the block 
+      	that it occupies to make a tracker for the train. The name will appear on
+      	the track icon selected for display in every block the train occupies. As 
+      	train moves track icons change colors and show the name of the tracker
+
+		<h3>An Easier Way to Make a Tracker</h3>
+      	A much easier way to make a Tracker is simply to drag and drop a <b>Marker</b>
+      	icon onto the block the train occupies. This opens the <b>Tracker Table</b> window
+      	automatically and creates a Tracker with the text and color of the marker.
+      	When a tracker is made this way, the marker will return to its docking position.
+      	A marker's docking position can be set from it's popup menu. Markers have
+      	a popup menu to configure them when not in an editing mode, but setting the
+      	docking position must be done in an editing mode.
+
+       <h2>The Tracker Table</h2>
+      	 The Tracker Table window consists of a list of the active trackers with their current
+      	 status. Each line shows the block the train is currently occupying the longest and
+      	 the elapsed time it has been there.
+      	 A <b>Stop</b> button on each row will terminate the tracker.
+		<p>
+		 Below the list
+      	 is the <b>Last Event</b> status window. The events shown are: when a trains enters
+      	 a block, leaves a block and any error or warning message.  When leaving a block
+      	 the elapsed time the
+      	 block was occupied is recorded. A mouse click on the window drops
+      	 down a record of the last 20 events.
+		</p><p>
+		 Below the status window are two buttons;
+      	 the <b>New tracker</b> button which was mentioned above, and the 
+      	 <b>Refresh Tracker Info</b> button. The button updates the elapsed time each tracker
+      	 has spent in its current block.
+      	 </p>
+      	 <h3>The Tracking Options Menu</h3>
+      	 The <b>Tracking Options</b> menu has three items:
+      	 <ul>
+      	 	<li><b>Multiple Trackers Ranking</b> applies only when several trackers are running.
+      	 		It is an advanced feature discussed below.</li>
+      	 	<li><b>OBlock Pick List</b> opens a OBlock table window. The items can be dragged to
+      	 		the New Tracker dialog.</li>
+      	 	<li><b>Open Session Log</b> opens a dialog to create a session log.  All Tracker events
+      	 		and Warrant events are logged to this file. The default directory of this file
+      	 		is the <i>File Location</i> directory you specified in Preferences.</li>
+      	</ul>
+
+       <h2>When Multiple Trackers Are Active</h2>
+      	A tracker posts an identifying label on all the blocks that
+      	its train currently occupies.
+      	Any block adjacent to the head or tail of its train becoming occupied
+      	is assumed to be the move of the train.  However, when two or
+      	more trackers have adjacent blocks in common and a common block becomes
+      	occupied, which tracker has actually made the move is indeterminate. 
+      	When this happens a dialog is displayed for the 
+      	panel user to determine which tracked train occupies contested the block.
+
+		<h3>Filtering Multiple Trackers</h3>      	
+      	When multiple trackers "compete" for occupation of a block there is no way to
+      	guarantee the selection of the train actually entering the block.  However,
+      	the Tracker Table can make an educated guess. The <b>Multiple Trackers Ranking</b>
+      	menu item <i>Only Show Most Likely Trackers</i> activates this feature. Note that
+      	unlike warrants which always set turnouts to be paths in a block, manual operators
+      	can throw switches that don't configure a path. This "Most Likely" option is
+      	based on the following logic:
+      	<p>
+      	A tracker that has both a path set to exit its current block and a path set to enter
+      	the newly occupied block is chosen over a tracker having only one path exiting 
+      	or entering the block. The latter such tracker has precedence over a tracker with
+      	neither an exit nor an entrance path set.
+      	</p><p>
+      	This could be useful in situations where the panel operator does not have full
+      	view of the layout. Should ties occur in the ranking, the dialog to pick the
+      	tracker is displayed.
+      	</p>
+
+      <!--#include virtual="/Footer" -->
+    </div><!-- closes #mainContent-->
+  </div><!-- closes #mBody-->
+</body>
+</html>
diff --git a/help/en/releasenotes/current-draft-note.shtml b/help/en/releasenotes/current-draft-note.shtml
@@ -449,6 +449,15 @@
             <li></li>
         </ul>
 
+   <h3>Tracker</h3>
+        <a id="Tr" name="Tr"></a>
+        <ul>
+            <li>A Tracker help page is added.</li>
+            <li>Tracking can be done with intermediate cars unequippted to draw current.</li>
+            <li>Tracker can recover occupation lost due to poor electrical contact.</li>
+            <li>Tracking can be followed through dark OBlocks.</li>
+        </ul>
+
    <h3>Warrants</h3>
         <a id="Wt" name="Wt"></a>
         <ul>

diff --git a/help/en/webindex.shtml b/help/en/webindex.shtml
@@ -20,6 +20,12 @@
 <!--#include virtual="indexheader" -->
 <ul>
 
+<li>
+<a href="package/jmri/jmrit/logix/Tracker.shtml">Train Trackers </a>
+<ul></ul>
+</li>
+
+
 <li>
 <a href="html/hardware/acela/index.shtml">Acela (CTI) - Hardware, Connection, Tools </a>
 <ul></ul>

diff --git a/java/.settings/JMRI PanelPro.launch b/java/.settings/JMRI PanelPro.launch
@@ -20,5 +20,5 @@
 <listEntry value="org.eclipse.debug.ui.launchGroup.run"/>
 </listAttribute>
 <booleanAttribute key="org.eclipse.jdt.launching.ATTR_USE_START_ON_FIRST_THREAD" value="true"/>
-<stringAttribute key="org.eclipse.jdt.launching.WORKING_DIRECTORY" value="${project_loc:jmri}"/>
+<stringAttribute key="org.eclipse.jdt.launching.WORKING_DIRECTORY" value="${project_loc:JMRI}"/>
 </launchConfiguration>
diff --git a/java/src/jmri/jmrit/display/Editor.java b/java/src/jmri/jmrit/display/Editor.java
@@ -691,11 +691,13 @@ public void paint(Graphics g) {
                     g2d.setStroke(new BasicStroke(2.0f));
                 }
                 for (Positionable p : _selectionGroup) {
-                    if (!(p instanceof PositionableShape)) {
-                        g.drawRect(p.getX(), p.getY(), p.maxWidth(), p.maxHeight());
-                    } else {
-                        PositionableShape s = (PositionableShape) p;
-                        s.drawHandles();
+                    if (p != null) {
+                        if (!(p instanceof PositionableShape)) {
+                            g.drawRect(p.getX(), p.getY(), p.maxWidth(), p.maxHeight());
+                        } else {
+                            PositionableShape s = (PositionableShape) p;
+                            s.drawHandles();
+                        }
                     }
                 }
             }

diff --git a/java/src/jmri/jmrit/display/IndicatorTrackPaths.java b/java/src/jmri/jmrit/display/IndicatorTrackPaths.java
@@ -17,7 +17,7 @@
  *
  * @author Pete Cressman Copyright (c) 2012
  */
-class IndicatorTrackPaths {
+public class IndicatorTrackPaths {
 
     protected ArrayList<String> _paths;      // list of paths that this icon displays
     private boolean _showTrain;         // this track icon should display _loco when occupied
@@ -108,7 +108,7 @@ protected String getStatus(OBlock block, int state) {
         return status;
     }
 
-    private void removeLocoIcon() {
+    public void removeLocoIcon() {
         if (_loco != null) {
             _loco.remove();
             _loco = null;
@@ -125,7 +125,7 @@ protected void setLocoIcon(OBlock block, Point pt, Dimension size, Editor ed) {
             removeLocoIcon();
             return;
         }
-        if (_loco != null) {
+        if (_loco != null || pt == null) {
             return;
         }
         trainName = trainName.trim();

diff --git a/java/src/jmri/jmrit/display/LocoIcon.java b/java/src/jmri/jmrit/display/LocoIcon.java
@@ -329,9 +329,8 @@ public void doMouseReleased(MouseEvent event) {
                     if (name == null || name.length() == 0) {
                         name = getUnRotatedText();
                     }
-                    if (InstanceManager.getDefault(TrackerTableAction.class).markNewTracker(block, name) != null) {
-                        dock();
-                    }
+                    InstanceManager.getDefault(TrackerTableAction.class).markNewTracker(block, name, this);
+                    dock();
                 }
                 break;
             }

diff --git a/java/src/jmri/jmrit/display/controlPanelEditor/EditCircuitPaths.java b/java/src/jmri/jmrit/display/controlPanelEditor/EditCircuitPaths.java
@@ -527,7 +527,7 @@ private OPath makeOPath(String name, ArrayList<Positionable> pathGp) {
                     Portal portal = ((PortalIcon) pos).getPortal();
                     if (!toPortal.equals(portal) && !fromPortal.equals(portal)) {
                         JOptionPane.showMessageDialog(this, Bundle.getMessage("tooManyPortals"),
-                                Bundle.getMessage("makePath"), JOptionPane.INFORMATION_MESSAGE);
+                               Bundle.getMessage("makePath"), JOptionPane.INFORMATION_MESSAGE);
                         return null;
                     }
                 }
@@ -787,6 +787,7 @@ private void clearPath(boolean hidePortals) {
                     ((IndicatorTrack)pos).removePath(TEST_PATH);
                 }
             }
+            _pathGroup.clear();
             int oldState = _homeBlock.getState();
             int newState = oldState & ~OBlock.ALLOCATED;
             _homeBlock.pseudoPropertyChange("state", oldState, newState);

diff --git a/java/src/jmri/jmrit/display/controlPanelEditor/shape/LocoLabel.java b/java/src/jmri/jmrit/display/controlPanelEditor/shape/LocoLabel.java
@@ -2,26 +2,43 @@
 
 import java.awt.Font;
 import java.awt.Graphics;
+import java.awt.Graphics2D;
+
+import javax.swing.JPopupMenu;
+
 import jmri.jmrit.display.Editor;
 import jmri.jmrit.logix.OBlock;
 
 public class LocoLabel extends PositionableRoundRect {
 
-    OBlock _block;
+    private OBlock _block;
 
     public LocoLabel(Editor editor) {
         super(editor);
+        setEditable(false);
     }
 
     public void setBlock(OBlock b) {
         _block = b;
         invalidateShape();
     }
 
+    /**
+     * Deprecated. No replacement for this method
+     * @return Oblock having an IndicatorTrack icon which is displaying this object
+     */
+    @Deprecated     // only known user is LocoLabelXml 2+ years ago
     public OBlock getBlock() {
         return _block;
     }
 
+    @Override
+    public boolean showPopUp(JPopupMenu popup) {
+        setRotateMenu(popup);
+        getEditor().setRemoveMenu(this, popup);
+        return true;
+    }
+
     @Override
     public void paint(Graphics g) {
         super.paint(g);
@@ -46,6 +63,10 @@ public void paint(Graphics g) {
     }
 
     @Override
+    protected void paintHandles(Graphics2D g2d) {
+    }
+
+        @Override
     public boolean storeItem() {
         return false;
     }

diff --git a/java/src/jmri/jmrit/display/controlPanelEditor/shape/configurexml/LocoLabelXml.java b/java/src/jmri/jmrit/display/controlPanelEditor/shape/configurexml/LocoLabelXml.java
@@ -12,6 +12,7 @@
  *
  * @author Pete Cressman Copyright (c) 2012
  */
+@Deprecated     // Very unlikely to have been used for 2+ years or more. Usefulness doubtful.  
 public class LocoLabelXml extends PositionableRectangleXml {
 
     public LocoLabelXml() {