path: root/app/doc/optionm.but

\# Notes:
\#
\# The "\u000" command is used to format the output. The command causes a blank line to appear between "bulleted" or "described" items.
\#
\# The "\u00B0" command gives proper format to the degree sign.
\cfg{html-local-head}{<meta name="AppleTitle" content="Options Menu" />}

\H{optionM}\i{Options Menu}

\G{png.d/moptions.png}

The \f{Options Menu} shows commands to change configuration options.

\dd \f{Colors} - Displays the Colors (\K{cmdRgbcolor}) dialog.

\u000

\dd \f{Command} - Displays the Command Options (\K{cmdCmdopt}) dialog.

\u000

\dd \f{Display} - Displays the Display (\K{cmdDisplay}) dialog.

\u000

\dd \f{Easement} - Displays the easement (\K{cmdEasement}) dialog which controls how easements (spiral transition curves) are used to join tracks.

\u000

\dd \f{Fonts} - Displays the font selection (\K{fontSelW}) dialog which selects the font used by the text (\K{cmdText}) command.  This command is only available on UNIX based systems.

\u000

\dd \f{Layout} - Displays the layout (\K{cmdLayout}) dialog.

\u000

\dd \f{Preferences} - Displays the Preferences (\K{cmdPref}) dialog.

\u000

\dd \f{Sticky} - Displays the Sticky Commands (\K{cmdSticky}) dialog.

\rule


\S{cmdRgbcolor} Colors Dialog

The \f{Colors} dialog is invoked from the Options (\K{optionM}) menu

\G{png.d/colorw.png}

The \f{Colors} dialog controls the color that various objects are drawn.

\dd \f{Border} - Sets color of Rulers, Room Boundaries and Table Edges.

\u000

\dd \f{Exception Track} - Sets color of \e{Exceptional Tracks} (\K{cmdLayout}). Those which exceed the specified grade or are have a radius smaller than the minimum set.

\u000

\dd \f{Marker} - Sets color of short lines drawn on the Ruler of the Main (\K{mainW}) window to indicate cursor position.

\u000

\dd \f{Normal Tracks} - Sets color of normal track.

\u000

\dd \f{Primary Axis} - Sets color of the large cross displayed when positioning the \f{Snap Grid} (\K{cmdGrid}) or the \f{Print Grid} (\K{cmdPrint}).

\u000

\dd \f{Profile Path} - color of the path when using the \f{Profile} (\K{cmdProfile}) command.

\u000

\dd \f{Secondary Axis} - Sets color of the large cross displayed when positioning the \f{Snap Grid} (\K{cmdGrid}) or the \f{Print Grid} (\K{cmdPrint}).

\u000

\dd \f{Selected Tracks} - Sets color of Selected track.

\u000

\dd \f{Snap Grid} - the Grid displayed by the \f{Snap Grid} (\K{cmdGrid}) dialog.

\u000

\dd \f{Track Ties} - color of ties (if drawn).

\rule


\S{cmdCmdopt} Command Option Dialog

The \f{Command Option} dialog is invoked from the Options (\K{optionM}) menu

\G{png.d/cmdopt.png}

The \f{Command Option} dialog contains items which control the behavior of some commands.

\dd \f{Default Command} - selects the \f{Properties} (\K{cmdDescribe}) or \f{Select} (\K{cmdSelect}) as the default command which is invoked when any other command (if not \f{Sticky} (\K{cmdSticky})) is canceled or completed.

\u000

\dd \e{Right-Click} - will either display a pop-up menu of available commands or command-specific options depending on whether the \e{Shift} key is being held down or not.  This option allows you to choose which operation occurs.

\u000

\dd \e{Select-Mode} - will either (a) only select the current item unless Ctrl is added or (b) will add the current item to the selection unless Ctrl is added in which case it will only select this item. 

\u000

\dd \e{Select-Zero} - if selected will perform \f{Deselect All} if the selection is not on an object.

\rule


\S{cmdDisplay} Display Dialog

The \f{Display} dialog is invoked from the Options (\K{optionM}) menu

\G{png.d/displayopt.png}

The \f{Display} dialog contains items which control the display of objects on the Main window.

\dd \f{Auto Pan} - if enabled, dragging near the edge of the Main Canvas (\K{mainW}) will cause the canvas to move to follow the mouse.

\u000

\dd \f{Car Labels} - controls the grouping and display of \f{Cars} on the \f{Hot Bar} (\K{cmdHotBar}) during the \f{Train} (\K{cmdTrain}) command.  This can be a combination of \f{Prototype}, \f{Manufacturer}, \f{Part Number} and \f{Item}.

\u000

\dd \f{Color Tracks} - when set to layers, tracks are drawn with color of the layer (\K{cmdLayer}) they belong to and not the normal track color.
This can be disabled in the Layer dialog for each Layer by unchecking the \f{Use Color} checkbox.

\u000

\dd \f{Color Draws} - when set to layers, non-tracks (lines, table edges and structures) are drawn with color of the layer (\K{cmdLayer}) they belong to rather than based on thier own object setting.
This can be disabled in the Layer dialog for each Layer by unchecking the \f{Use Color} checkbox.

\u000

\dd \f{Constrain Drawing Area to Room Boundaries} - when Zooming and moving the Main Canvas (\K{mainW}) may show areas beyond the boundaries of the room.
Setting this option constrains the Main Canvas to minimize these areas (the \f{grey} area).

\u000

\dd \f{Dont Hide System Cursor} - when XTrackCAD substitutes a specialized cursor to show actions that will occur (or are occuring) it will normallly hide the System Cursor.  This option suppresses this behaviour and leaves the system cursor in place.

\u000

\dd \f{Draw EndPts} - when to draw endpoints between connected track: never, only for turnouts or for all tracks.

\u000

\dd \f{Draw Unconnected EndPts} - how to draw unconnected endpoints; normally, with a thick line or with a thick line in the exception color.

\u000

\dd \f{Draw Ties} - how to draw ties under the rails when the drawing Scale is smaller than half of the \f{Two Rail Scale}. Note that \K{cmdTies} can be used to hide ties for selected tracks.

\u000

\dd \f{Draw Centers} - enable or disable drawing of center markings (ie. crosshairs) for curved track.

\u000

\dd \f{Draw Tunnel} - how to draw hidden tracks (\K{cmdTunnel}), either not at all, as dashed lines or as normal solid lines (which might be faster).

\u000

\dd \f{Hide Trains On Hidden Track} - controls whether trains (\K{cmdTrain}) on invisible layers (\K{cmdLayer}) or hidden tracks (\K{cmdTunnel}) (if hidden tracks are not drawn) are displayed.

\u000

\dd \f{Hot Bar Labels} - controls the format of titles for objects on the \f{Hot Bar} (\K{cmdHotBar}).

\u000

\dd \f{Label Enable} - individual control over whether to display various types of labels.  You may want to turn some of these off if your layout is too cluttered.

\lcont{

\u000

\b \e{Cars} - Reporting mark labels on cars - the content shown on the Cars label is either the Repmarks (if the Rep Number is set), or the car index number (with a "#" before it). See the Car Part dialog \K{carpart}.

\b \e{EndPt Elevations} - Elevation markers attached to endpoints.

\b \e{Lengths} - Length of flex-track attached to ends of turnouts all the way to the next turnout.

\b \e{Track Descriptions} - Title of each turnout and sectional track, optional details of each piece of Flexible Track. These can be shown or hidden using the Move Description \K{cmdMoveLabel} command.

\b \e{Track Elevations} - Computed elevations at the center of each track.

}

\u000

\dd \f{Label Font Size} - controls font size for Labels on layout.

\u000

\dd \f{Layout Labels} - controls the format of titles for Turnouts and Structures displayed on the Layout.

\u000

\dd \f{Label Scale} - the program will draw labels only when the drawing Scale is smaller or equal to this value.

\u000

\dd \f{List Labels} - controls the format of titles for turnouts and structures displayed in lists (such as the \f{Parts List} (\K{cmdEnum})).

\u000

\dd \f{Live Map} - if checked then the Main Window (\K{mainW}) will be updated as you drag on the \f{Map Window} (\K{cmdMap}).  Note that this can be slow.

\u000

\dd \f{Map Scale} - scale of the Map (\K{cmdMap}) window.  Increase this value to make the \f{Map} window smaller when working with large layouts.  \f{Note:} you cannot make the \f{Map} window larger than the screen.

\u000

\dd \f{Train Update Delay} - number of milliseconds between updates in the \f{Train Simulation} (\K{cmdTrain}) mode.  A lower value will generate a smoother display but reduces system responsiveness.

\u000

\dd \f{Two Rail Scale} - draw tracks using two lines when the drawing Scale is smaller than this value.

\rule


\S{cmdEasement} \i{Easements}

Easements are special sections of gradually curving track used to connect straight and curved tracks (or two curved tracks). Easements reduce the effects of sudden changes in track curves which can cause jerky motion and derailments.

Easements can be created every time you \f{Join} (\K{cmdJoin}) tracks, \f{Extend} (\K{extendTrack}) a track or create a \f{Tangent} (\K{createTangent}) track.

When using easements, an error message will be generated if tracks have a radius that is too small or are too short for the transition curve.

The \f{Easement} dialog is invoked from the Options (\K{optionM}) menu.

\dd \G{png.d/easew.png}

\u000

\dd \f{Value} - allows fine tuning of the easement parameters (restricted to values >= 0.5).

\u000

\dd \f{R} - minimum radius of the curved track.

\u000

\dd \f{X} - offset between a straight and curved track.

\u000

\dd \f{L} - length of the transition track.

\u000

\dd Radio button group with \f{None}, \f{Sharp}, \f{Normal}, \f{Broad} and \f{Cornu}. Corresponding \f{Value}s for these buttons are 0, 0.5, 1.0, 2.0 and -1.0. Select \f{None} to turn easements off.

For traditional fixed sharpness easements see \k{EasementsTraditional}, for Cornu Easements see \k{EasementsCornu}.

\S2{EasementsCornu} \i{Cornu Easements}

The Cornu Easements work in a different way to the other easements. They use all the space available to minimize sharpness, so you can control the sharpness for each curve you draw by the distance apart, radius and angle of the two end points.

The Cornu is a mathematical curve that has the property that the curvature (inverse of the radius) varies linearly along its length. Using an open-source Cornu library written by Dr Raph Levin, we can calculate an Cornu easment to suit the end conditions of radius, curve center, angle and position. A Cornu easement can be constructed between two tracks by using the values of these parameters.

To draw an cornu easement see \k{joinCornu}, to Modify it afterwards see \k{chgCornu}.

\S2{EasementsTraditional} \i{Easements with Fixed Sharpness}

The values \f{R}, \f{X} and \f{L} are read-only. They are set using the radio buttons or the \f{Value} field which can be set to 0 (No Easment) or between 0.21 (sharpest Easement) 100 (broadest Easment).

These values indicate the worst case of joining a straight track with a curve of radius \f{R}. The two tracks are separated by the offset \f{X} while the easement curve extends for \f{L/2} inches or centimeters to each side of the endpoints.

The formula used to draw non-Cornu easements is:

\c          x = l * l * l / (6 * R * L)
\e                               b   b
\c          r = L * R/l
\e              b   b

where

\b \f{l} is the distance along the tangent to the easement.

\b \f{R} is the final radius of the easement.

\b \f{L} is the total length of the easement along the tangent.

\b \f{x} is the offset from the tangent at \f{l}.

\b \f{r} is the radius of easement curve at \f{l}.

The Easement Button (\G{png.d/beasement.png}) on the Main Window (\K{mainW}) changes its label to indicate the current easement value.

The following diagrams illustrates the \f{R}, \f{X} and \f{L} values and the resulting easement curve.

\G{png.d/easeex1.png}

\G{png.d/easeex2.png}

If curves with a radius larger than \f{R} or two curves (that bend in the same direction) are being connecting then the easement curve will be shorter and the offset smaller.  If the computed offset is small then no easement is generated.

A curved track that bends in one direction and then bends in the opposite direction is an \e{S-curve}.  This will generate the worst case easement which is two easement curves placed end to end.

Refer to instruction in \k{EasementsSectional} when using sectional track.

\rule


\S2{EasementsSectional} \i{Easements and Sectional Track}

Easements require the possibility of creating track with arbitrary radii. Therefore easements are not possible if sectional track is used. It is best to turn \f{Easements} off when using sectional track.

\rule


\S{fontSelW} Font Selection

The font selection dialog allows selection of the font used by the text (\K{cmdText}) command.  This command is valid only on UNIX based systems.

\G{png.d/fonts.png}

\rule


\S{cmdLayout} Layout Dialog

The \f{Layout Options} dialog, displayed by the Options (\K{optionM}) or the File (\K{fileM} menu, contains items controlling the current layout.

\dd \G{png.d/layout.png}

\u000

\dd \f{Gauge} - Drop down menu used to select track gauge.

\u000

\dd \f{Height} - Height of layout drawing which, depending on the \f{Unit} setting (English or Metric) established in the \f{Preferences} dialog (\K{cmdPref}), is measured in inches or centimeters.

\u000

\dd \f{Room Width} - Width of layout drawing which, depending on the \f{Unit} setting (English or Metric) established in the \f{Preferences} dialog (\K{cmdPref}), is measured in inches or centimeters.

\u000

\dd \f{Scale} - Drop down menu used to select track scale.

\u000

\dd \f{Title} - Two lines that can be used to enter title and subtitle descriptions for the layout. Information entered in these fields will be shown on any printout of your layout design.

\u000

\dd \f{Maximum Track Grade} - Specifies maximum track elevation expressed as a percent (%). Tracks with a larger elevation are considered exceptional and drawn in the exception (\K{cmdRgbcolor}) color.

\u000

\dd \f{Minimum Track Radius} - Specifies minimum track radius (in inches or centimeters). Curved tracks with a smaller radius are considered exceptional and drawn in the exception (\K{cmdRgbcolor}) color.

\u000

\dd \f{Background File Name} - The last 40 characters of the full file pathname for the image used for a temporary background behind all the drawn objects. It is set using the \f{Browse} and reset with the \f{Clear} buttons.
It is also cleared along with all the other background values after a \f{Open} or \f{New} command.
The file is initally specified to be in the local file system. In order to send it along with the layout, use \f{Save As} command and specify the \i{Archive} Archive format (*.xtce).
This will create a single zipped package file containing the layout and the image file which can be sent and will open on a different system.
If this has been done, after \f{Open} of the archive, the image file path will point into the extracted archive file directory.
It can be changed to a new local file and the next \f{Save} will rebuild the package using the new image file instead of the old one.

\u000

\dd \f{Background Pos X, Y} - The offset of the bottom left corner of the background image from the origin (in inches or centimeters) after rotation.

\u000

\dd \f{Background Size} - The model size (in inches or cm) to scale the base of the background image to (measured from bottom left to bottom right as displayed after any rotation has been applied). Note - A value of 0.0 means that no scaling is applied and the image is shown at its current size in pixels regardless of scale or zoom.

\u000

\dd \f{Background Screen} - The amount of screening (from 0 to 100%) to apply to the background image. Screening allows objects drawn over the image to be seen more clearly. 0 means no screening, while 100% means noting will be shown.

\u000

\dd \f{Background Angle} - The rotation angle to apply to the background image (in degrees) about its center before it is moved so that its bottom left corner is offset by the \f{Background Pos} setting.

\rule

\S{cmdPref} Preferences Dialog

This dialog controls some parameters which likely will not be changed frequently.

\dd \G{png.d/pref.png}

\u000

\dd \f{Angles} - controls the angle system. \f{Polar}: 0\u00B0 is up and angles are measured clockwise, or \f{Cartesian}: 0\u00B0 is to the right and angles are measured counter-clockwise.

\u000

\dd \f{AutoSave} \i{AutoSave} - specifies the number of Check Points taken before an AutoSave. The same number of checkpoints are retained in a circular archive set in the (\K{workDir}) named for the layout file.  Setting this value to 0 disables AutoSave. 

\u000

\dd \f{Balloon Help} - disables the display of \f{Balloon Help} (\K{windowTerms}) which usually is shown when the cursor is placed over a control.

\u000

\dd \f{Show FlexTrack} - disables the display or \f{FlexTrack} (\K{generalTerms}) which is shown on the left of the Toolbar.

\u000

\dd \f{Check Point} \i{AutoSave} - specifies the Check Point frequency; the number of modifications made to the layout since the last save. The layout is automatically saved to the Check Point file (\K{workDir}) when the Check Point frequency is reached. Setting this value to 0 disables use of the Checkpoint file \e{and AutoSave}. Upon restart, if the program was not saved normally, the user will be prompted to see if they want to resume at the last checkpoint.

\u000

\dd \f{Connection Angle} - as below for Connection Distance for the angle between endpoints.

\u000

\dd \f{Connection Distance} - the maximum distance between endpoints that can be connected.  This affects the \f{Join} (\K{cmdJoin}) command and auto-connection during \f{Parallel} (\K{cmdParallel}) commands and placing \f{Turnouts} (\K{cmdHotBar}).  The default value for this field is 0.100 inches or 0.254 CM. Changing this value is not recommended.

\u000

\dd \f{Drag Distance} - controls how far you can move the cursor (in pixels) before \e{XTrackCAD} considers the action to be a drag instead of a click.

\u000

\dd \f{Drag Timeout} - controls how long you can hold a mouse button down (in milliseconds) before \e{XTrackCAD} considers the action to be a drag instead of a click.

\u000

\dd \f{Length Format} - controls how lengths are displayed.  Combinations of feet and inches (or meters, centimeters and millimeters) with support for decimal or fractional measures. \f{Note:} lengths can be entered in any format and are converted on entry.

\u000

\dd \f{Max Coupling Speed} - trains (\K{cmdTrain}) moving faster than this speed will crash when running into other trains or hitting the end of a track or an open turnout.  Crashed trains must be manually moved back onto the track.

\u000

\dd \f{Min Grid Spacing} - minimum distance between \f{Grid} (\K{cmdGrid}) lines (in pixels).  If the grid lines are closer then drawing them is suppressed.

\u000

\dd \f{Min Track Length} - specifies the minimum length of a track.  Shorter tracks will not be created.

\u000

\dd \f{On Program Startup} - if set to \q{Load Last Layout}, \e{XTrackCAD} will automatically re-open the layout file that was open when \e{XTrackCAD} last closed. Selecting \q{Start New Layout} opens a blank layout canvas.

\u000

\dd \f{Turntable Angle} - minimum angle between adjacent tracks connected to a \f{Turntable} (\K{cmdTurntable}).

\u000

\dd \f{Units} - choose between English (inches) or Metric (centimeters) measurements.

\u000

\dd \f{Write Settings} - Save the current settings to a named settings file

\u000

\dd \f{Read Settings} - Load settings from a named settings file

\rule


\S{cmdSticky} Sticky Dialog

By default, when commands complete, the defined \f{Default Command} (\K{cmdCmdopt}) becomes active.  If a command is \f{sticky}, the defined \f{Default Command} is ignored and the current command remains active after completion.

The \f{Sticky} dialog controls which commands remain active after completion.

\G{png.d/sticky.png}

Selecting a command makes it \f{sticky}. Un-selecting a command causes the defined \f{Default Command} to become active after command completion.

\rule