path: root/app/doc/addm.but

\# Notes:
\#
\# The "\u000" command is used to format the output. These commands causes a blank line to appear between "bulleted" or "described" items.
\#
\# The "\u00B0" command gives proper format to the degree sign.

\C{commandMenus} Command Menus

\cfg{html-local-head}{<meta name="AppleTitle" content="Command Menus" />}

\rule

\H{addM}\i{Add Menu}

\G{png.d/madd.png}

The \f{Add Menu} has all the actions related to adding track pieces to the layout.

\dd \f{Circle Track} - place a circle of track by selecting radius, tangent and or center (\K{cmdCircle}).

\u000

\dd \f{Curved Track} - lay curved track pieces using different modes for selecting start and endpoints and radius (\K{cmdCurve}).

\u000

\dd \f{Hand-laid Turnout} - lay a turnout in place on the layout. (\K{cmdHandLaidTurnout})

\u000

\dd \f{Helix} - Add a helix. (\K{cmdHelix})

\u000

\dd \f{Parallel} - create parallel track or line to existing flex-track, straight or curved track. (\K{cmdParallel})

\u000

\dd \f{Straight Track} - lay straight track pieces of arbitrary lengths

\u000

\dd \f{Structure} - Add a predefined structure to the layout.

\u000

\dd \f{Predefined Track} - select a turnout or a piece of fixed track and place on layout.

\u000

\dd \f{Custom Turntable} - Place a turntable. (\K{cmdTurntable})

\u000

\dd \f{Block} - Create a block. (\K{cmdBlock})

\u000

\dd \f{Switchmotor} - Create a switchmotor. (\K{cmdSwitchmotor})

\u000

\dd \f{Signal} - Create a signal. (\K{cmdSignal})

\u000

\dd \f{Control} - Create a control. (\K{cmdControl})

\u000

\dd \f{Sensor} - Create a sensor. (\K{cmdSensor})

\S{cmdCircle} Circle Track

\G{png.d/bcircle.png}

A circle track is a special form of a curved track that extends 360\u00B0 and has no endpoints.  The three methods (with their Shortcut keys) used to create a Circle Track are:

\u000

\dd (\K{cmdCircleFixedRadius}). Use the Fixed Radius specified on the \e{Circle Radius} control displayed on the Status Bar (\K{mainW}).  
\c{Left-Drag} the Circle track into position.

\u000

\dd (\K{cmdCircleTangent}). \c{Left-Drag} from tangent point (Edge) of the Circle track to the Center.

\u000

\dd (\K{cmdCircleCenter}). \c{Left-Drag} from the Center of the Circle track to the edge.

\u000

A drop down menu, which allows selection of the Circle Track creation method, is invoked from the down arrow button (\G{png.d/bmenu.png}) located on the right side the Circle track button. 
Dependent upon previous selection, the Circle Track button will look like \G{png.d/bcircl1.png}, \G{png.d/bcircl2.png} or \G{png.d/bcircl3.png}.

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

\dd \e{Circle Track Button Menu}

If Snap Grid (\K{cmdGrid}) is enabled then circle centers will be constrained to the grid.

Circle tracks are useful for fitting curves into corners and other tight places.  They're also handy when establishing an initial layout and finding out "what will fit".

You can join to and from circles, after which they become curved tracks.

\rule

\S2{cmdCircleFixedRadius} Circle Fixed Radius

\G{png.d/bcircl1.png}

(\c{Control-8}) Use the Fixed Radius specified on the \e{Circle Radius} control displayed on the Status Bar (\K{mainW}).  
\c{Left-Drag} the Circle track into position. 

\rule

\S2{cmdCircleTangent} Circle Fixed Tangent

\G{png.d/bcircl2.png}

(\c{Control-9}) \c{Left-Drag} from tangent point (Edge) of the Circle track to the Center.

\rule

\S2{cmdCircleCenter} Circle From Center

\G{png.d/bcircl3.png}

(\c{Control-0}) \c{Left-Drag} from the Center of the Circle track to the edge.

\rule

\S{cmdCurve} Curved Track

\G{png.d/bcurve.png}

Creating a curve is a two step operation.

The five methods (with their Shortcut keys) used to create a Curved Track are:

\dd

\dd \K{cmdCurveEndPt}. Drag out the end and then set its radius by dragging the endpoint.

\u000

\dd \K{cmdCurveTangent}. Drag from the an endpoint to the center and then drag the second enpoint around that center.

\u000

\dd \K{cmdCurveCenter}. Drag from the Center of the Curved track to one of the endpoints. Position the second endpoint around the center.

\u000

\dd \K{cmdCurveChord}. Drag from one endpoint to the other endpoint to form the Chord of the Curve.  Drag the arc out to form the Curve.

\u000

\dd \K{cmdBezier}. Construct a Bezier by placing its four control points.

\u000

A drop-down menu, which allows selection of the Curved Track creation method, is invoked from the down arrow button (\G{png.d/bmenu.png}) located on the right side the Curved track button. Dependent upon previous selection, the Curved Track button will look like \G{png.d/bcurve1.png}, \G{png.d/bcurve2.png}, \G{png.d/bcurve3.png}, \G{png.d/bcurve4.png}, \G{png.d/bezier.png} or \G{png.d/bcornu.png}.

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

\dd \e{Curved Track Button Menu}

For all but the Bezier Curve, two Red arrow heads will be drawn after the first step to indicate where you can \c{Left-Drag} to complete the second step.

A straight track will be created if the second endpoint is lined up with the first endpoint except for Bezier tracks.

If the Snap Grid (\K{cmdGrid}) is enabled then the endpoints will be constrained to the grid if they are not snapped to another object. \c{Shift} ensures that other objects will be ignored.

Optionally, the curve center point and radius can be displayed for the Curve. This is enabled by the Move Label (\K{cmdMoveLabel}) command.
 
For Beziers, the active control point will be drawn in red and the available endpoints are shown with circles. 


\f{Note:} You can also create Straight and Curved tracks using \k{cmdModify} by \c{Left-Drag}ing out extra track from an open end-point.

\rule

\S2{cmdCurveEndPt} Curved Track from End Point

\G{png.d/bcurve1.png} 

(\c{Control-4}) Drag from one endpoint in the direction of the Curve at that point and release. \c{Left-Drag} the red arrows to position the second endpoint.

While the first endpoint is being placed, and \f{MagneticSnap} is enabled, unless \e{Alt} is held, if the cursor is on a track, the new curve end will "Snap" to the nearest open track endpoint and you will drag out the second end in aligned to that track, once you are dragging the second end it will be restricted to an arc that has the same end angle as the first endpoint. After a track is competed, the new track will be connected to this first track.
This will also happen with \f{MagneticSnap} if \e{Alt} is held.

\rule

\S2{cmdCurveTangent} Curved track from Tangent

\G{png.d/bcurve2.png} 

(\c{Control-5}) Drag from one of the endpoints (which will behave like the first point in "CurvedTrack From End" to the Center of the Curved track and release.  
\c{Left-Drag} on the arrows to position the second endpoint.

While the endpoints are being placed, if \f{MagneticSnap} is enabled, unless \c{Alt} is held down, they will "Snap" to an open track endpoint of the tracks underneath the cursor and you can only drag out the control point aligned to the end of those tracks. 
After the new track is completed, it will be connected to these existing track.
If \f{MagneticSnap} is disabled, the snap will only happen if \e{Alt} is held.

\rule

\S2{cmdCurveCenter} Curved Track From Center

\G{png.d/bcurve3.png} 

(\c{Control-6}) Drag from the Center of the Curved track to one of the endpoints and release.  \c{Left-Drag} to position the second endpoint.

While the endpoints are being placed, if \f{MagneticSnap} is enabled, unless \c{Alt} is held down, they will "Snap" to an open track endpoint of the tracks underneath the cursor and you can only drag out the control point aligned to the end of those tracks. 
After the new track is completed, it will be connected to these existing track.
If \f{MagneticSnap} is disabled, the snap will only happen if \e{Alt} is held.

\rule

\S2{cmdCurveChord} Curved Track from Chord 

\G{png.d/bcurve4.png} (\c{Control-7}) Drag from one endpoint to the other endpoint to form the Chord of the Curve and release.  \c{Left-Click} on the center of the track and Drag to form the Curve.
The first end point acts like "CurvedTrack From End". If an exitsing track end is selected, the Chord will only move along line orthogonal to the track.

While the endpoints are being placed, if \f{MagneticSnap} is enabled, unless \c{Alt} is held down, they will "Snap" to an open track endpoint of the tracks underneath the cursor and you can only drag out the control point aligned to the end of those tracks. 
After the new track is completed, it will be connected to these existing track.
If \f{MagneticSnap} is disabled, the snap will only happen if \e{Alt} is held.

\rule

\S2{cmdBezier} Curved Bezier Track

\G{png.d/bezier.png} 

\c{Left-Click} to place one endpoint and \c{Left-Drag} out the first control point and release, \c{Left-Click} to place the second Endpoint and \c{Left-Drag} out the second control point and release. 
Once all 4 points are placed, you can pick one at a time and drag it to move it. 
Complete the Curve by pressing \c{Enter|, or Reject it with c\{Esc}.

While the endpoints are being placed, if \f{MagneticSnap} is enabled, unless \c{Alt} is held down, they will "Snap" to an open track endpoint of the tracks underneath the cursor and you can only drag out the control point aligned to the end of those tracks. 
After the new track is completed, it will be connected to these existing track.
If \f{MagneticSnap} is disabled, the snap will only happen if \e{Alt} is held.

\rule

\S{cmdCornu} Create Cornu Track

\dd \G{png.d/bcornu.png} \c{Left-Click} to place each endpoint on an open track end or just on the layout.
During the move to the click, if \f{MagneticSnap} is enabled, an anchor will show when the cursor is near an open end point. This can be inhibited with \e{Alt}. 
If \f{MagneticSnap} is disabled this will only happen if \e{Alt} is held.

\c{Left-Drag} if the endpoint not on an existing track drags out the end angle of the new track. This is shown by the Cornu endanchor. 

\G{png.d/cornuendanchor.png}

The anchor is only drawn for Cornu ends that are not joined to existing tracks and it shows the position, direction and radius of the track, and has anchors for altering these properties. 
When the Cornu is joined to a track, it uses the properties of the end of that track instead. 
Anchor point handles are drawn outside the end of the Cornu track to allow track-pins to be edited on the track itself.
\c{Left-Click} to place the second Endpoint either on a track endpoint or not. \c{Left-Drag} sets the second end angle like the first for unconnected end-points. 

Complete the Curve by pressing \c{Enter}, or Reject it with \c{Esc}.

The radius and angle of the selected open Cornu end can also be set with text entry boxes in the Status Bar.

When either endpoint is being moved it will "Snap" to an open track endpoint of the tracks underneath the cursor unless \c{Shift} is held. 
You can then only move the endpoint along that track if it is splitable, or in an extension of it. After the new track is completed, it will be connected to these existing tracks.

Cornu Track Pins are further explained in \K{joinCornu} - they constrain the Cornu curve to smoothly pass through thier position as well as satisfying the end conditions. You can place them by clicking on the Cornu and select, \e{Drag} to move them around or hit \e{Delete} to remove them.

If the end is not connected, an anchor will enable the end-angle and radius to be set by dragging. Initially the end radius is set to be zero and the angle will be picked to create a smooth curve given the end angle.  Altering the end angle with the anchor resets the radius to zero.

\u000


\S{cmdHandLaidTurnout} Hand-laid Turnouts

\G{png.d/bhndldto.png}

Hand-laid turnouts are created by specifying 3 values:

\b Position of \e{Frog}

\b Angle of \e{Frog} (the frog number)

\b Position of \e{Points}

First select the position for the Frog (\K{generalTerms}) on an existing track and then \e{Drag} away to specify the angle of the \e{Frog}.  The angle in degrees and equivalent frog number is displayed on the status bar.  When you release, the line indicating the angle jumps to one side of the track to show you the center line of the new leg of the turnout.

Next \c{Left-Click} and \c{Left-Drag} to position the Points (\K{generalTerms}) for the turnout.  As you \c{Left-Drag}, tracks will be drawn showing the turnout.  When you release the turnout is created.

You cannot place the \e{Frog} or \e{Points} on a turnout, circle or helix.  However, you can create overlapping Hand-laid Turnouts.

There are constraints on where you can place the \e{Points} in relation to the \e{Frog}.  You cannot place the \e{Points} too close the \e{Frog}.  When placing Hand-laid Turnout on a curved track you may get unexpected results, especially when placing the \e{Points} a long way from the \e{Frog}.  Try changing the \e{Frog} angle to get different results.

Note: the drawing is an approximation to show the location of the \e{Points} and \e{Frog}.  The piece of track considered (by \e{XTrackCAD}) to be a Hand-laid Turnout is a short section of track located at the \e{Points} and extending toward the \e{Frogs}.  Other track segments are created between the \e{Points} and \e{Frog} and a short straight segment is drawn after the \e{Frog}.  These other segments are independent of the turnout and can be removed or modified, although this is probably not a good idea.

\rule


\S{cmdHelix} Helix Track

A helix track is used to change the elevation of track in a restricted space.  A helix is drawn as a circle of track, but in 3 dimensions it would resemble a cork screw or the pattern of threads on a bolt.

\G{png.d/ahelix.png}

A helix is defined by the number of \e{Turns} and \e{Radius}.

The helix dialog allows you to calculate these values based other parameters such as the \e{Elevation Difference}, \e{Grade}, \e{Vertical Angular Separation}.  \e{Angular Separation} is the difference in degrees between tracks entering and exiting the helix. Changing any of these values effects the other values. For example, increasing the \e{Radius} decreases the \e{Grade}. Changing the number of \e{Turns} affects the \e{Vertical Separation} and either the \e{Radius} or \e{Grade}.

In the case where different parameters could be affected (for instance changing \e{Elevation Difference} can affect \e{Radius} or \e{Grade}) the last parameter you changed will be preserved.  If you set the \e{Grade} and then \e{Elevation Difference} then the \e{Radius} will be adjusted.

Changing \e{Vertical Separation} affects \e{Turns} which must be an integer value (no fractions), and this in turn affects the \e{Vertical Separation}.  When you set \e{Vertical Separation} you are specifying the minimum separation which is adjusted upwards to the actual value.

Note: only the \e{Radius} and \e{Turns} are used when creating the helix.  After joining the helix to other tracks, you will want to establish the heights of the endpoints at each end of the helix.  You can use the Elevation (\K{cmdElevation}) command to do this.

A helix is placed the same way as a Circle Track (\K{cmdCircle}) with the addition that you specify the number of turns as well the as the radius of the helix.  Then the helix is dragged into position on the layout.

You can join to a helix in the same way you join to a circle.  However, once joined the helix is still drawn as a circle of track.

A label for the helix is drawn at it's the center.  If the elevations are set (either by a Defined Elevation point or connecting to a Defined Elevation point) for the two ends of the helix then the label contains the computed grade and vertical separation between layers as well as the number of turns and total length.  The label can be moved or turned off by the Move Label (\K{cmdMoveLabel}) command.

\rule

\S{cmdParallel} Parallel Track or Line

You can pick between two Parallel Commands:

\dd

\u000

\dd \K{cmdParallelTrack}. You can create a new track parallel to any straight, curved, bezier, cornu or easement track.  

\u000

\dd \K{cmdParallelLine}. You can create a line parallel to any straight, curved, bezier, cornu or easement track or straight lines, curved lines and PolyLines.

\rule

\S2{cmdParallelTrack} Parallel Track

\G{png.d/bparallel.png} 

Select the Track you want to parallel with \c{Left-Click}, and the new parallel track will appear beside it.  You control which side the new track will be on by \c{Left-Drag}ging the cursor from one side to the other of the selected track before releasing it.

\G{png.d/statusbarparallel.png}

The \f{Parallel Separation} control (Visible in the Status Bar) displays the intended separation between parallel tracks/line.  This value can be changed before selecting a track.  The value must be greater than 0.0 if the gauges are equal.
 
\b If the gauges are equal, a value of 0.0 means that the rail of the second track is overlaid on the first to simulate dual guage track. The railside that the new track "shares" is set by which side of center the cursor is on when released.
The new track will have NoTies set on.

\b The seperation can be automatically increased using the \f{Radius Factor} value. If this is set to 0.0 (default) the seperation value will be used regardless of radius.
If the value is set to 1.0, the seperation will be increased by a scaled 2864 inches per inch of curvature of the paralled track - this is in accordance with North American prototype practice.
Other values of Radius Factor will alter by an equivalent percentage. For example, 0.5 would use 50% of this increase.

\u000

This command is very useful for creating sidings and yards as well as dual track.

\b No parallel to a turnouts or a non-straight piece of sectional track is created.

\b It is possible to create tracks that abut (the endpoints are very close and aligned). 
These endpoints will be automatically connected.

\rule

\S2{cmdParallelLine} Parallel Lines

\G{png.d/bparalleline.png}

Select the Track or Line you want to parallel with \c{Left-Click}, and the new parallel line will appear beside it.

\b Note that Lines are not joined - if you wish you can select a series of Lines and turn them into a PolyLine using \K{cmdJoinLine}.

\rule

\S{cmdStraight} Straight Track

\G{png.d/bstraigh.png}

Straight track is a created by \c{Left-Click} to select the first endpoint then \c{Left-Drag}ing the cursor to the point where you want the second endpoint to be.
Unless \c{Shift} is held down when the first endpoint is being placed and the cursor is on a track, the new straight end will "Snap" to the nearest open track endpoint and you can drag out the second end aligned to that track. After a track is competed, the new track will be connected to the existing track.

If the Snap Grid (\K{cmdGrid}) is enabled then the endpoints will be constrained to the grid.

\rule


\S{cmdStructure} Structure

\G{png.d/bstruct.png}

The \f{Structure} command places diagrams of structures (buildings, bridges and other scenic elements) on the layout.  The operation is similar to the Turnout (\K{cmdTurnout}) command.

\G{png.d/strsel.png}

When you select a structure from the list, its diagram is drawn in the diagram canvas.  The dimensions are also listed on the dialog.

The \f{Structure Selection} dialog will disappear while dragging on the layout if the \f{Hide} Check Box on the dialog is set.  This is useful if you have a small screen.

See the Hot Bar (\K{cmdHotBar}) command for details on placing Structures on the layout.

\f{Structures} are placed on the layout in same way as \f{turnouts} except that there is no \e{Active endpoint} and structures do not align with existing tracks.

\rule


\S{cmdTurnout} Turnouts

\G{png.d/bturnout.png}

Turnouts (and sectional track) are created by the \f{Turnout} command \I{Created by Turnout Command}.  When you select the turnout command, the \f{Turnout Selection} dialog is displayed which contains a list of available turnouts and sectional track for the current scale (\K{cmdLayout}) and a diagram of the selected turnout.

You can use the Parameter File Dialog (\K{cmdPrmfile}) to control what turnouts are available.

\G{png.d/turnsel.png}

Select a turnout from the scrolling list by \c{Left-Click}ing on it. Move to the Layout and \c{Left-Click} where the turnout should be placed. The Turnout will snap to nearby flextracks or open endpoints. By \c{Left-Drag}ing you can move the turnout around. Additional \c{Left-Click}s change the way the turnout is placed.

The \f{New} button invokes the Turnout Designer (\K{cmdTurnoutNew}) dialog.  This button displays a pop-up-menu list of various types of turnouts and sectional track.

The \f{Turnout Selection} window will disappear while dragging on the layout if the \f{Hide} Check Box on the dialog is set.  This is useful if you have a small screen.

See the Hot Bar (\K{cmdHotBar}) command for details on placing Turnouts on the layout.

\rule


\S{cmdTurntable} Turntables

\G{png.d/bturntbl.png}

Turntables of specified diameter are created with the \f{Turntable} command.

\G{png.d/statusbarturntable.png}

The \e{Turntable Diameter} control (Visible in the Status Bar) displays the current diameter of the turntable.  This value can be changed before dragging the turntable into position. The value must be greater than 0.0.

The \f{Modify command} (\K{cmdModify}) can be used to create turntable stall tracks.  Select the turntable and drag the stall track to the proper angle and length.  You can also connect to a turntable with the \f{Join command} (\K{cmdJoin}).

The \f{Turntable Angle} control on the Preferences (\K{cmdPref}) dialog controls how closely you can place tracks connected to a turntable.  If you want to create stall tracks every 7.5\u00B0, set the \f{Turntable Angle} control to 7.5 and place the track as close to each other as allowed.  \e{XTrackCAD} makes sure they will be separated by the correct angle.

\rule

\S{cmdBlock} Block

\G{png.d/bblock.png}

A block is created by first selecting the track segments in the block and then
selecting \f{Create Block} from either the Add menu \K{cmdAdd} or from the block menu on the
hotbar.  A block gets a name and a script.  The name is only used for
identification and the script is used by the layout control software.  The
script should provide whatever information is needed by the layout control
software to determine block occupancy.  This could be a code snippet to
retrieve the state of the block occupancy or it could be the address of the
sensor, etc.

\G{png.d/block.png}

The create block dialog has spaces for two text strings. One is the name and
the other is a block occupancy script. The name identifies the block and the
script is information used by the layout control software to detect block
occupancy. The script could be a code snippet or I/O device address
information, etc.

\rule

\S{cmdSwitchmotor} Switchmotor

\G{png.d/bswitchmotor.png}

A switchmotor is created by selecting \f{Create SwitchMotor} from either the Add
menu \K{cmdAdd} or from the switchmotor menu on the hotbar and then clicking on a turnout.
A switchmotor gets a name and three scripts. The name is only used for
identification and the three scripts are used by the layout control software.
The three scripts are for throwing the turnout to its "normal" position,
throwing the turnout to its "reverse" position, and a script to read a point
position sensor. These scripts could be code snippets or they could be
addresses of I/O devices, etc.

\G{png.d/switchmotor.png}

The create switchmotor dialog has spaces for four text strings. One is the
name and the other three are scripts for Normal, Reverse, and Point Sense. The
name identifies the switchmotor and the scripts are information used by the
layout control software to throw the turnout to the normal position, throw the
turnout to the reverse position, and sense the point position. The scripts
could be code snippets or I/O device address information, etc.

\rule

\S{cmdSignal} Signal

\G{png.d/bsignal.png}

A signal is created by selecting \f{Create Signal} from either the Add menu \K{cmdAdd} or
from the hotbar. Use the mouse to select a location (left button) and then
draging (left button down) the signal to set its orientation. Once the left
button is released, a Create/Edit Signal dialog box is displayed, and you can
fill in the signal's properties: name, fine tune the location and orientation,
number of heads, and the aspects.

\G{png.d/signal.png}

The create/edit signal dialog has spaces for the name of the signal, its
location and orientation, the number of heads (1, 2, or 3), and a list of
aspects.  Each aspect has a name and a script.  The name could be a rule book
name (Clear, Aproach, Stop, etc.) or the actual color(s) displayed (green,
yellow, red, etc.).  The script is just some information for the layout
control software to actually effect the display of the aspect -- this could be
the LCC event id to trigger the aspect or it could be a code snippet that
causes the aspect to be displayed.

\rule

\S{cmdControl} Control

\G{png.d/bControl.png}

A control is created by selecting \f{Create Control} from either the Add menu \K{cmdAdd} or
from the hotbar. Use the mouse to select a location (left button) and then
dragging (left button down) the control to where you want it.  Once the left
button is released, a Create/Edit Control dialog box is displayed, and you can
fill in the control's properties: name, fine tune the location, and the on and
off scripts.

\G{png.d/control.png}

The create/edit control dialog has entry fields for the name of the control, its
location, and a pair of scripts, one to turn the control on and one to turn
the control off. The scripts are just some information for the layout control
software to actually effect the state on the control (on or off).

\rule

\S{cmdSensor} Sensor

\G{png.d/bSensor.png}

A sensor is created by selecting \f{Create Sensor} from either the Add menu \K{cmdAdd} or
from the hotbar. Use the mouse to select a location (left button) and then
dragging (left button down) the sensor to where you want it. Once the left
button is released, a Create/Edit Sensor dialog box is displayed, and you can
fill in the sensor's properties: name, fine tune the location, and the script.

\G{png.d/sensor.png}

The create/edit sensor dialog has spaces for the name of the sensor, its
location, and a script. The script is just some information for the layout
control software to actually return the state of the sensor (on or off).