Merge pull request #297 from cjakeman/timetable-window2

Adds a Timetable tab to the map window which is useful for players and timetable creators.
https://blueprints.launchpad.net/or/+spec/timetable-window

Author: cjakeman

Source/Documentation/Manual/appendices.rst

@@ -471,7 +471,7 @@ The defined ORTS signal types can be set in the signal type definition and used
 in the same way as the default MSTS types.
 
 Note that SPEED is a fixed signal type which is available in OR without explicit definition (see below for
-details on SPEED type signals). Also note that any type definition starting with “OR_” is not valid, these
+details on SPEED type signals). Also note that any type definition starting with "OR\_" is not valid, these
 names are reserved for future default types in OR.
 
 Syntax:

Source/Documentation/Manual/driving.rst

@@ -619,8 +619,8 @@ While the activity is running relevant data are stored and displayed.
 The stored data are used to generate a report at the end of the activity.
 
 
-``How it does work``
-''''''''''''''''''''
+``How It Works``
+''''''''''''''''
 
 Activity evaluation is enabled only for Activity mode, and requires the 
 "Debrief evaluation" checkbox in the main menu window to be enabled.
@@ -672,7 +672,7 @@ Cliking **Actual status: (**\ |darr| **)**\  expanded real-time display appears.
 
 
 
-Cliking **Actual status: (**\ |uarr| **)**\  collapses all items.
+Clicking **Actual status: (**\ |uarr| **)**\  collapses all items.
 
 Once the activity has ended, the report file is created and a new window displays it.
 
@@ -708,39 +708,43 @@ In such case the activity saves will have the "Eval" checkbox checked in the res
 
 .. _driving-dispatcher:
 
-Dispatcher Window
-=================
+Map Window
+==========
+
+Use the map window to monitor and control train operation. 
+The :ref:`Map window <options-map-window>` option must be selected prior to starting the simulation.
 
-The dispatcher window is a very useful tool to monitor and control train 
-operation. The :ref:`Dispatcher window <options-dispatcher>` option 
-must be selected.
-
-The dispatcher window is actually created by pressing ``<Ctrl+9>``. The 
-window is created in a minimized state, so to display it in front of the OR 
-window you must click on ``<Alt+Tab>`` and select the dispatcher window 
-icon, or click on one of the OR icons in the taskbar. If you are running OR 
-in full-screen mode, you must also have the :ref:`Fast full screen Alt+Tab 
-<options-fullscreen>` option selected to have both the OR and the 
-dispatcher windows displayed at the same time. After the dispatcher window 
-has been selected with ``<Alt+Tab>``, successive Alt_Tabs will toggle 
-between the OR window and the dispatcher window.
+The map window is opened and closed by pressing ``<Ctrl+9>``. 
+After the map window  has been selected with ``<Alt+Tab>``, successive 
+Alt+Tabs will toggle between the OR window and the dispatcher window.
 
-The dispatcher window is resizable and can also be maximized, e.g. on a 
-second display. You can define the level of zoom either by changing the 
-value within the ``Res`` box or by using the mouse wheel. You can pan 
-through the route by moving the mouse while pressing the left button. You 
-can hold the shift key while clicking the mouse in a place in the map; this 
-will quickly zoom in with that place in focus. You can hold Ctrl while 
-clicking the mouse in a place in the map, which will zoom out to show the 
-whole route. Holding Alt and clicking will zoom out to show part of the 
-route.
+The map window contains 2 tabs: Dispatcher and Timetable. Both provide maps of
+the route with each train following its own path.
+
+The map window is resizable and can also be maximized, e.g. on a 
+second display. 
+
+To pan, use the left mouse button to drag the map around.
+
+To zoom, use left and right mouse buttons together and drag vertically
+or use the mouse wheel.
+
+To zoom in centred on a location, press Shift and click the left mouse button
+at that location.
+
+To zoom out from a location, press Alt and click the left mouse button.
+
+To zoom out fully, press Ctrl and click the left mouse button.
+
+Dispatcher Tab
+--------------
 
 .. image:: images/driving-dispatcher.png
 
-The dispatcher window shows the route layout and monitors the movement of 
-all trains. While the player train is identified by the ``0`` string, 
-AI trains are identified by 
-their OR number (that is also shown in the :ref:`Extended HUD for Dispatcher 
+The dispatcher window shows the route layout, monitors the movement of 
+all trains and allows you to change switches and signals.
+While the player train is identified by the ``0`` label, 
+AI trains are identified by an Id number (as shown in the :ref:`Extended HUD for Dispatcher 
 Information <driving-hud-dispatcher>`), followed by the service name. 
 Static consists are identified as in MSTS.
 
@@ -807,8 +811,8 @@ will remain centered on that train.
 
 .. _driving-dispatcher-for-ai-trains:
 
-Using dispatcher window for AI trains
--------------------------------------
+Using dispatcher tab for AI trains
+''''''''''''''''''''''''''''''''''
 
 What is described here is valid only for activity mode and explore in 
 activity mode.
@@ -822,7 +826,7 @@ re-route it without getting it back on the original route.
 It is suggested to look at this video which explains some practical case 
 https://youtu.be/-f0XVg7bSgU before continuing reading.
 
-To perform this correctly and in a way more similar to reality, some rules have to 
+To perform this correctly and in a way closer to reality, some rules have to 
 be followed.
 The concept is that switches must be manually thrown only if they aren't reserved by a train. 
 To be sure of this it is necessary to force to stop the last signal(s) between train(s) 
@@ -844,6 +848,63 @@ waiting points in the abandoned part of route will be lost.
 
 The re-routed train may be also the player train (be it autopiloted or not).
 
+Timetable Tab
+-------------
+
+This tab shows the same route and trains as the dispatch tab but, with its focus on a timetable
+of trains, is provided to assist timetable builders.
+
+In this tab, for clarity, you can use the checkboxes to hide or reveal the labels for platforms,
+sidings, switches, signals and trains. The simulation time is also on view.
+
+As shown below, the basic red train label identifies the train. 
+
+.. image:: images/timetable_tab1.png
+
+Trains are drawn in green except that locos are drawn in brown. To indicate direction, the leading
+vehicle is draw in a lighter shade.
+
+The "Active trains" selection shows trains that are currently delivering a service.
+The "All trains" selection also shows inactive and static trains with labels in dark red.
+
+Inactive trains are not part of a current service - i.e. their start time has not been reached or 
+they have arrived at their destination and not yet been re-formed for another service - see 
+:ref:`#dispose commands<timetable-dispose>`.
+
+Static trains do not move and are shown in gray. They created with the $static command.
+
+.. raw:: latex
+
+   \clearpage
+
+When you select the "Train state" checkbox, the train labels extend to provide key information matching 
+that from the :ref:`HUD <driving-hud-dispatcher>` as shown below:
+
+.. image:: images/timetable_tab2.png
+
+.. raw:: latex
+
+   \clearpage
+
+The path element of the train state can be very lengthy, so this is only shown where the path
+contains the characters # & * ^ ~ which indicate :ref:`a track section that is in contention <driving-hud-section-state>`.
+
+In the image below, train 192 crosses the path of train 117.
+
+.. image:: images/timetable_tab3.png
+
+.. raw:: latex
+
+   \clearpage
+
+The "Signal state" checkbox reveals the aspect of each signals and also indicates the id number 
+of the train that is approaching. In this image, signal 462 is showing an APPROACH_1 aspect for train 114.
+
+.. image:: images/timetable_tab4.png
+
+The adjustment for "Daylight offset (hrs)" is provided for convenience to advance the sun as it moves 
+across the sky so that night time trains can be more easily observed in daylight.
+
 Additional Train Operation Commands
 ===================================
 
@@ -2009,6 +2070,8 @@ A detailed explanation of the various columns follows:
       refer to the train numbers as shown at the start of each row. Below, 
       <n> indicates such a number.
 
+.. _driving-hud-section-state:      
+
         - <n> section is occupied by train <n>.
         - (<n>) section is reserved for train <n>.
         - # (either with <n> or on its own) section is claimed by a train 

Source/Documentation/Manual/images/options-general.png

@@ -32,9 +32,9 @@ sometimes use a view other than the cabview to follow the train, and
 therefore will not see the alerter warning, selecting the related option
 *Also in external views* enables the alerter in those views as well.
 
-.. _options-dispatcher:
+.. _options-map-window:
 
-Dispatcher window
+Map window
 -----------------
 
 It is suggested to always select this option. When this option is selected,
@@ -45,7 +45,7 @@ option :ref:`Fast fullscreen Alt+Tab <options-fullscreen>`.
 
 Through this window you can monitor train movements and also influence
 them, by setting signals and switches. A complete description of the
-dispatcher window can be found :ref:`here <driving-dispatcher>`.
+dispatcher tab can be found :ref:`here <driving-dispatcher>`.
 
 .. image:: images/options-dispatcher.png
 
@@ -252,12 +252,14 @@ Fast full-screen Alt+Tab
 
 When this option is selected, and OR is running full-screen, pressing
 Alt+Tab leaves OR full-screen and running, and allows the
-:ref:`Dispatcher Window <driving-dispatcher>` to be shown in front of it. If this option is not selected, OR is
-minimized. The Dispatcher Window :ref:`option <options-dispatcher>` must also be selected and the
-Dispatcher Window started with Ctrl+9 to display the Dispatcher Window.
-Each successive press of Alt+Tab will toggle between the Dispatcher window
+:ref:`Dispatcher Window <driving-dispatcher>` to be shown in front of it. 
+If this option is not selected, OR is minimized. 
+Each successive press of Alt+Tab will toggle between the map window
 and the OR window.
 
+Note: To display the Map Window, the :ref:`Map window option <options-map-window>` 
+must also be selected and the Map Window started with Ctrl+9.
+
 Glass on in-game windows
 ------------------------
 

Source/Documentation/Manual/images/timetable_tab1.png

@@ -140,7 +140,7 @@ public OptionsForm(UserSettings settings, UpdateManager updateManager, bool init
             checkAlerterExternal.Checked = Settings.Alerter && !Settings.AlerterDisableExternal;
             checkSpeedControl.Checked = Settings.SpeedControl;
             checkConfirmations.Checked = !Settings.SuppressConfirmations;
-            checkViewDispatcher.Checked = Settings.ViewDispatcher;
+            checkViewMapWindow.Checked = Settings.ViewDispatcher;
             checkUseLargeAddressAware.Checked = Settings.UseLargeAddressAware;
             checkRetainers.Checked = Settings.RetainersOnAllCars;
             checkGraduatedRelease.Checked = Settings.GraduatedRelease;
@@ -431,7 +431,7 @@ void buttonOK_Click(object sender, EventArgs e)
             Settings.AlerterDisableExternal = !checkAlerterExternal.Checked;
             Settings.SpeedControl = checkSpeedControl.Checked;
             Settings.SuppressConfirmations = !checkConfirmations.Checked;
-            Settings.ViewDispatcher = checkViewDispatcher.Checked;
+            Settings.ViewDispatcher = checkViewMapWindow.Checked;
             Settings.UseLargeAddressAware = checkUseLargeAddressAware.Checked;
             Settings.RetainersOnAllCars = checkRetainers.Checked;
             Settings.GraduatedRelease = checkGraduatedRelease.Checked;