/**
* @page TrickViewPage
* @section LEVEL3 Trick View
*
* %Trick View (hereafter referred to as TV) is a graphical user interface that allows users to view and modify Trick-managed
* variables in a simulation while it is running. It also provides for the launching of integrated strip charts and can save
* and restore lists of variables and their associated strip charts.
*
* @see @ref ExternalApplications "Runtime GUIs"
*
* @section LEVEL4 Launching
* TV can be launched via one of:
*
* - From the @ref SimControlPanel "Simulation Control Panel", under the Actions menu.
*
* @image html ../../../doxygen/images/tv_launch.jpg
* @image rtf ../../../doxygen/images/tv_launch.jpg
*
* - From the command line:
* @code tv [options] @endcode
* The TV launch script is located in $TRICK_HOME/bin. Pass \-\-help for a description of
* available options.
*
* For additional launching options, see @ref ExternalApplicationsAutomaticLaunching "Automatically Launching Applications".
*
* @section LEVEL4 Automatically Opening Files
*
* Files that are to be automatically opened when TV launches can be specified via one of:
*
* - From the command line, use the \-\-open option.
* File paths are relative to the directory from which TV launches.
*
* - From the input file or user model code, use Trick::TrickView::set_auto_open_file.
* File paths are relative to the directory containing the S_main executable.
*
* Opening a TV file will overwrite the current cycle period or any argument to \-\-cycle with the value from
* the file, subject to the minimum cycle period.
*
* @section LEVEL4 Automatically Opening and Setting Files
*
* Files that are to be automatically opened and set when TV launches can be specified via one of:
*
* - From the command line, use the \-\-openSet option.
* File paths are relative to the directory from which TV launches.
*
* - From the input file or user model code, use Trick::TrickView::set_auto_open_and_set_file.
* File paths are relative to the directory containing the S_main executable.
*
* Opening a TV file will overwrite the current cycle period or any argument to \-\-cycle with the value from
* the file, subject to the minimum cycle period.
*
* @section LEVEL4 Automatically Setting Files
*
* Files that are to be automatically set when TV launches can be specified via one of:
*
* - From the command line, use the \-\-set option.
* File paths are relative to the directory from which TV launches.
*
* - From the input file or user model code, use Trick::TrickView::set_auto_set_file.
* File paths are relative to the directory containing the S_main executable.
*
* @section LEVEL4 Strip-Chart-Only Mode
*
* Once a collection of strip charts is established and saved to a TV file, you may wish to prevent future launches from
* displaying the main GUI window to allow users to view the strip charts without providing them (potentially dangerous)
* access to the simulation's internal variables. You can cause %Trick View to launch in strip-chart-only mode via one of:
*
* - From the command line, use the \-\-stripChartsOnly option.
*
* - From the input file or user model code, use Trick::TrickView::set_strip_charts_only.
*
* Note that you must provide a TV file to be automatically opened as described above when launching in strip-chart-only
* mode.
*
* @section LEVEL4 The Trick View GUI
*
* The GUI pictured below may have a different look and feel based on the architecture of the machine on which it is running,
* but the functionality will remain the same.
*
* @image html ../../../doxygen/images/TrickView.jpg
* @image rtf ../../../doxygen/images/TrickView.jpg
*
* @section LEVEL5 File Buttons
*
* The file buttons provide for persistent storage of lists of variables of interest. From left to right, they are:
*
* - New
* Clears the variable table.
*
* - Open
* Opens a dialog allowing the user to select a TV file. The variable table will be cleared and replaced by
* the variables from the file. The saved cycle period and any strip charts will be restored.
*
* - Open And Set
* Opens a dialog allowing the user to select a TV file. The variable table will be cleared and replaced by
* the variables from the file. Additionally, the variables will be set to their corresponding values in the file.
* The saved cycle period and any strip charts will be restored.
*
* - Set
* Opens a dialog allowing the user to select a TV file. The variables listed in the file will be set to
* their corresponding values in the file. The variable table, cycle period, and any strip charts will be unaffected.
*
* - Save
* Opens a dialog allowing the user to specify a file name. The variables in the variable table and their associated
* information, the cycle period, and any strip charts will be written to the file.
*
* @section LEVEL5 Monitor Button
*
* The monitor button displays the current state of the monitor and allows the user to toggle receiving updates on the
* variables in the variable table. A blue screen indicates that updates are being received. A black screen indicates they
* are not.
*
* @section LEVEL5 Variable Buttons
*
* The variable buttons affect variables in the variable table. From left to right, they are:
*
* - Strip Chart
* Launches a strip chart that will plot all selected variables on the same graph while the simulation is running.
*
* - Delete
* Removes the selected variables from the variable table and all strip charts.
*
* @section LEVEL5 Variable Hierarchy Tree
*
* This panel displays all of the simulation's Trick-managed variables in a hierarchical format. Initially, only the
* top-level simulation objects are displayed. A variable representing a structure or class containing variables can be
* expanded or collapsed by double-clicking its name or by single-clicking the expand/collapse node to the left of its name.
* Double-clicking a variable that does not represent a structure or class will add it to the variable table. Multiple
* variables can be simultaneously selected via the shift and control (command on Mac) keys. Variables can also be added by
* selecting them, right-clicking anywhere in the variable hierarchy tree, and selecting Add Selection from the
* pop-up menu. Adding a variable that represents a structure or class will add all of its contained variables (at all lower
* levels). The top layer of the variable hierarchy tree will be populated when TV has finished parsing the information from
* the simulation, which takes place in the background. Lower levels are loaded on-demand as the tree is expanded. Although
* unlikely to occur in practice, it is possible that expanding every node in a large simulation will consume all of the
* application's available memory, in which case it will become extremely unresponsive.
*
* @section LEVEL5 Search Panel
*
* The search panel allows the user to search the variable hierarchy tree by partial name or regular expression, with an
* option for case sensitivity. Resulting listed variables can be added to the variable table in manners similar to those
* of the variable hierarchy tree. The search panel becomes available for use at the same time as the variable hierarchy
* tree. Search progress is indicated by a progress bar below the results list. During the initial search, only an
* indication of activity is given while the application counts the total number of simulation objects. In subsequent
* searches, a quantitative value of progress is displayed.
*
* @section LEVEL5 Index Specification Window
*
* When adding variables to the variable table, if any variables are pointers or arrays, the index specification window will
* be displayed, allowing the user to specify the ranges to add.
*
* @image html ../../../doxygen/images/TVSpecifyIndices.jpg
* @image rtf ../../../doxygen/images/TVSpecifyIndices.jpg
*
* Each array displays a combo box over its allowable range. Each pointer has a single text box that accepts values in the
* form minimum-maximum. Character pointers and arrays have a check box allowing them to be treated as strings.
* The position radio buttons specify where in the variable table the variables will be added, relative to the currently
* selected row.
*
* @section LEVEL5 Variable Table
*
* The variable table lists all the added variables, displaying their names, values, units, and formats. Columns can be
* freely rearranged by clicking and dragging their headers. Rows can be sorted by clicking the column header corresponding
* to the property by which they should be sorted. Rows are sorted first by the most recently clicked column header, then by
* the header clicked before that, and so forth. Rows can be manually reordered by clicking and dragging them. Note that
* manual reordering will remove any currently applied sorting. Further display customization is available via the Column
* Control Menu, which is accessed by clicking the miniature table icon in the upper right-hand corner of the table. Pressing
* the Delete key while the variable table has focus is equivalent to clicking the delete variable button.
*
* While you cannot actually change a variable's name, you can quickly add another variable of a similar name by
* double-clicking the name cell of a variable and modifying it. The original variable will remain unchanged, and a variable
* of the new name will be added.
*
* Each variable's value is displayed according to its type and format. Booleans are represented by check boxes; enumerated
* types, by combo boxes; and all other types, by a string. Modifying a variable's value is achieved by clicking the check
* box, selecting a value from the combo box, or directly entering a new value. Inputs are validated against the variable's
* type before being submitted to the Variable Server. Note that the displayed value will not change until the
* Variable Server reflects the change.
*
* Variable units are displayed via a combo box containing all of the supported units. To change a variable's units, click
* its units cell and select a new value. Note that the displayed units will not change until the Variable Server reflects
* the change.
*
* Variable formats are displayed via a combo box containing all of the supported formats for the variable's type. To change
* a variable's format, click its format cell and select a new value. The displayed value will be updated immediately.
*
* Multiple, non-contiguous selections are allowed and may be used to affect mass value, unit, and format changes. When
* performing a mass edit, the assigned/selected value will only be applied to variables that can accept it.
*
* @subsection LEVEL6 Invalid References
*
* Variables that the Variable Server failed to resolve display values of \ and are
* highlighted in red. Such a variable's value and units cannot be changed, but its name can still be modified for the
* purpose of adding new variables.
*
* @section LEVEL5 Manual Entry Field
*
* The manual entry field provides the user a means by which to directly add a variable of any name. This is useful if a
* variable's information is not present in the S_sie.resource file or the file itself is not present, or if the variable
* is a pointer to the beginning of an array. Multiple elements of an arrayed variable can be added by specifying the range
* within the brackets, such as:
*
* @code ball.obj.state.output.position[0-1] @endcode
*
* Note that pointers cannot be dereferenced using the pointer dereference operator (*) in TV. Instead, the user
* should treat the pointer as a single-element array and append the variable's name with [0].
*
* @section LEVEL5 Purge Button
*
* The purge button removes all variables from the variable table that have a value of \.
*
* @section LEVEL5 Resolve Button
*
* The resolve button submits a request to the Variable Server to attempt to resolve all invalid references to legal values,
* which can be useful if a previously null pointer has become valid.
*
* @section LEVEL5 Connection Status Bar
*
* The connection panel displays host and port information when TV is connected to a simulation. When disconnected, clicking
* on the combo box displays a list of available simulations to which to connect. Alternately, the information can be
* entered directly into the panel in the form of host:port.
*
* @section LEVEL5 Clearing Logged Data
*
* TV records the value of every variable in the variable table each time the Variable Server sends a report. This allows
* newly launched strip charts to include data going back all the way to the point at which the variable was first added.
* This can eventually result in a large amount of memory usage. If performance begins to degrade, you can clear the log of
* all values via the Action menu of either TV or any strip chart. Note that this will erase any data currently
* being displayed on any strip charts.
*
* @section LEVEL5 Settings
*
* The Settings dialog can be accessed via the File menu and allows the user to alter the behavior of TV.
* See @ref ExternalApplications "Runtime GUIs" for a detailed description of Application Behavior and Cycle Period options.
*
* @image html ../../../doxygen/images/TVSettings.jpg
* @image rtf ../../../doxygen/images/TVSettings.jpg
*
* @subsection LEVEL6 Variable Tree Order
*
* The order in which the variable hierarchy is displayed has two options:
*
* - Alphabetic
* Variables are sorted alphabetically.
*
* - Declared
* Variables are sorted according to their order of declaration within the simulation.
*
* @subsection LEVEL6 Variable Addition
*
* The placement of newly added variables within the variable table is specified via the Position combo box. The available
* options are Top, Before, After, and Bottom. The Before
* and After options are relative to the currently selected row.
*
* Character pointers and arrays can be treated as strings by default by checking the char[] as string check
* box. When added as such, arrays will be collapsed into single string entries. Otherwise, they will be displayed element
* by element.
*
* @subsection LEVEL6 Font Size
*
* This setting affects the variable hierarchy tree, search panel, and variable table text size.
*
* @subsection LEVEL6 Default Units
*
* Default units for each unit type can be specified via its corresponding combo box, which lists all of its available
* units. Selecting xx results in units as specified in the model code. The Default All check box,
* when selected, is equivalent to selecting xx for all unit types.
*
* @subsection LEVEL6 Default Formats
*
* Default formats for each variable type can be specified via its corresponding combo box.
*
* @section LEVEL4 The Strip Chart GUI
*
* Strip charts allow users to plot variables in the variable table in real-time. The GUI pictured below may have a different
* look and feel based on the architecture of the machine on which it is running, but the functionality will remain the same.
*
* @image html ../../../doxygen/images/Stripchart.jpg
* @image rtf ../../../doxygen/images/Stripchart.jpg
*
* @section LEVEL5 Domain Axis Panel
*
* The domain axis panel allows the user to affect the range of the domain axis.
*
* - All
* The domain axis will continuously adjust to contain the entirety of all plotted variables' domain values.
*
* - Strip
* The domain axis will continuously scroll such that the latest sub-set (as set by the adjacent text box) of domain values
* is contained.
*
* - Fixed
* The domain axis will not automatically change.
*
* @section LEVEL5 Display Panel
*
* The display panel allows the user to specify whether or not the chart should display certain features.
*
* - Lines
* When enabled, lines will be drawn between the data points.
*
* - Points
* When enabled, the data points themselves will be drawn.
*
* - Legend
* When enabled, the chart's legend will be shown.
*
* @section LEVEL5 Variables Panel
*
* The variables panel allows the user to add and remove dependent variables, and to change the independent variable. To add
* a dependent variable, select it from the adjacent combo box and click the Add button. To remove a dependent
* variable, select it from the adjacent combo box and click the Remove button. To change the independent
* variable, select it from the adjacent combo box.
*
* @section LEVEL5 Right-Click Menu
*
* Right-clicking the plot area will display a context menu with the following options:
*
* - Properties
* Opens a dialog allowing the user to customize the plot as described below.
*
* - Copy
* Copies the plot to the clipboard, allowing the user to paste the content into other applications.
*
* - Save As...
* Opens a dialog allowing the user to save the plot as a PNG file.
*
* - Print...
* Opens a dialog allowing the user to print the plot.
*
* - Zoom In
* Zooms in either or both axes. This can also be achieved by left-click-dragging a box from its top-left to bottom-right
* corner.
*
* - Zoom Out
* Zooms out either or both axes. This can also be achieved by left-click-dragging any other way than described above.
*
* - Auto Range
* Automatically adjusts one or both axes.
*
* @section LEVE5 Chart Properties Dialog
* The Chart Properties dialog can be opened by selecting Properties from the plot's right-click menu.
* It allows the user to customize the appearance of the chart. These settings are part of the properties that are saved
* in TV files.
*
* @image html ../../../doxygen/images/TVChartPropertiesTitleTab.jpg
* @image rtf ../../../doxygen/images/TVChartPropertiesTitleTab.jpg
*
* The Title tab allows the user to toggle visibility of the title and to set the title's text, font, size,
* and color.
*
* @image html ../../../doxygen/images/TVChartPropertiesPlotTab.jpg
* @image rtf ../../../doxygen/images/TVChartPropertiesPlotTab.jpg
*
* The Plot tab allows the user to set the label text, font, size, and color for the domain and range axes.
* It also provides for toggling the visibility of each axis' tick labels and marks, for setting each axis' label font
* and size, and for adjusting the range of each axis.
*
* @image html ../../../doxygen/images/TVChartPropertiesAppearanceTab.jpg
* @image rtf ../../../doxygen/images/TVChartPropertiesAppearanceTab.jpg
*
* The Appearance tab within the Plot tab allows the user to set the plot's border's width and
* color and the plot's background color. It also provides for inverting the axes.
*
* @image html ../../../doxygen/images/TVChartPropertiesOtherTab.jpg
* @image rtf ../../../doxygen/images/TVChartPropertiesOtherTab.jpg
*
* The Other tab allows the user to set the background color of the area surrounding the plot (outside of the
* plot's borders) and also provides for toggling of the anti-aliasing feature. Modifying series properties is not currently
* supported.
*
* @section LEVEL4 TV Files
*
* TV files allow the user to store the states of the variable table and any existing strip charts to persistent
* memory. This saves configuration time for commonly used variable lists and strip chart selections.
*
* TV files have changed format a number of times since the release of %Trick 10. Originally, they were simple custom text
* files. This evolved into a custom XML format (%Trick 10.4) which provided for better verification under a formal language.
* As the amount and types of data to be saved to persistent memory between sessions increased, it became obvious that the
* creating and parsing of custom-defined XML elements was not maintainable in the long run. Thus, the persistent storage
* mechanism was changed to Java's serialization protocol (%Trick 10.7), which stores data in binary. This delegated nearly
* all of the work to Java, reducing the code related to saving and restoring state to a few lines. However, users that had
* come to rely on the capability to manually modify TV files found the new format unacceptable, since it was no longer
* human-readable. Therefor, the storage mechanism has changed once again to an XML format. This time the marshaling and
* unmarshaling is delegated entirely to Java's JAXB library, which encodes Java classes that follow the JavaBean design
* pattern, to which much of TV's package has been modified to adhere. This achieves most of the best of both of the previous
* formats while incurring code overhead somewhere between the two. TV is backwards-compatible with the two previous formats
* (to %Trick 10.4) but will always save in the current (JAXB) format. The XML schema, which is automatically created by
* JAXB, can be found at trickView.xsd.
*
* There is one special case in which backwards-compatibility is not maintained. TV files from %Trick 10.4 to 10.6 rely on
* the variable hierarchy tree being parsed before the file is loaded so that enumeration descriptions are available.
* However, the variable hierarchy tree is now populated in the background so that the GUI is immediately responsive upon
* launch. Therefor, if an old-format TV file containing enumeration variables is specified to be automatically loaded on
* launch and the variable hierarchy tree is slow to load, the enumeration variables will fail to resolve to valid values
* and will display