net.kolls.railworld
Class RailSegment

java.lang.Object
  extended by net.kolls.railworld.RailSegment
Direct Known Subclasses:
Curve, FourWay, Label, Signal, Switch, TrackSegment

public abstract class RailSegment
extends java.lang.Object

The interface which must be implemented for something to be considered a rail segment. Most segments will derive from an existing segment (usually TrackSegment and not implement this interface directly!

Author:
Steve Kollmansberger

Field Summary
protected  RailSegment[] dests
          Various connections to this segment.
 EditCanvas ec
          The canvas to register undo information with, if any.
protected static Distance MOUSE_NEAR
          How close does the mouse need to be to count as being "near" something?
protected  java.awt.geom.Point2D[] pts
          Points that make up this segment.
static Distance RAIL_BED_WIDTH
          The width of the rail bed (gravel)
static Distance RAIL_WIDTH
          The width of the rail line itself.
protected  java.util.Set<Train> trains
          Trains present in this segment
 
Constructor Summary
RailSegment()
           
 
Method Summary
abstract  boolean canErase()
          Can this segment be erased? In some cases, other segments must be erased first.
 boolean carHidden()
          Should cars on this segment be drawn, or hidden? Defaults to false (not hidden).
 boolean click(java.awt.geom.Point2D pos, RailCanvas rc)
          Whenever a user clicks on the canvas, all dynamic segments receive this event.
protected abstract  SegmentEditPoint createSEP(int ptIdx, RailSegment attach)
          Given a point index in the pts array and possibly a railsegment to attach, return a segmenteditpoint if such attachment is possible.
abstract  RailSegment dest(RailSegment source)
          Each rail segment must at the very least tell us where it comes from and where it goes, currently.
 java.util.ArrayList<RailSegment> destNZ(RailSegment source)
          Finds the first non-zero length RailSegment going away from the source.
abstract  void draw(int z, java.awt.Graphics2D gc)
          Draw the segment.
abstract  javax.swing.JPanel editPanel()
          You are guaranteed that the variable ec will be set prior to this call.
 void enter(Train t)
          Notification that a train is in the segment.
 RailSegment getDest(int dest)
          Returns a given destination RailSegment.
 int getDests()
           
 java.awt.geom.Point2D getPoint(int ptIdx)
          Returns a given point.
abstract  java.awt.geom.Point2D getPoint(RailSegment start, double myPos)
           
 int getPoints()
           
 boolean isDynamic()
          Dynamic segments receive additional events while the game is running; non-dynamic segments are only asked to draw z levels 1 and 2 at draw static time.
abstract  Distance length()
          all segments have a length can be 0 for signals, etc.
 java.lang.String mouseOver(java.awt.geom.Point2D pos)
          Whenever a user mouses over the canvas, all dynamic segments receive this event.
 SegmentEditPoint nearEditPoint(java.awt.geom.Point2D loc, RailSegment attach)
          Given a point, find out if it is near one of our edit handles (z=5).
 double pixelStep(double myPos)
          Given a position (percentage), move one pixel and give the new percentage.
abstract  void recomp()
          Called when changes are made; recompute or update any associated values.
 void setDest(int point, boolean ifNotNull, RailSegment value)
          Updates one of the connecting segments to this segment.
 void setPoint(int point, java.awt.geom.Point2D p)
          Update a drawing point.
 boolean singleton()
          Singleton segments may only have one train in them at a time.
 double step(double myPos, double mySpeed)
           
 java.util.Set<Train> trains()
          Note: Set contents will be maintained automatically, read only
 void update(java.awt.geom.Point2D original, java.awt.geom.Point2D replacement)
          Update a point location for this segment.
 int update(RailSegment test, RailSegment newValue)
          Updates a connection from a given segment to a new one.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

RAIL_BED_WIDTH

public static final Distance RAIL_BED_WIDTH
The width of the rail bed (gravel)


RAIL_WIDTH

public static final Distance RAIL_WIDTH
The width of the rail line itself. This is the rail-to-rail width.


MOUSE_NEAR

protected static final Distance MOUSE_NEAR
How close does the mouse need to be to count as being "near" something?


ec

public EditCanvas ec
The canvas to register undo information with, if any.

See Also:
editPanel()

dests

protected RailSegment[] dests
Various connections to this segment. Indexed based on point values for set.


pts

protected java.awt.geom.Point2D[] pts
Points that make up this segment. May be used for various reasons, should not be interpreted as a line or any other shape.


trains

protected java.util.Set<Train> trains
Trains present in this segment

Constructor Detail

RailSegment

public RailSegment()
Method Detail

canErase

public abstract boolean canErase()
Can this segment be erased? In some cases, other segments must be erased first.

Returns:
Indicates if the segment may be erased as-is.

carHidden

public boolean carHidden()
Should cars on this segment be drawn, or hidden? Defaults to false (not hidden).

Returns:
A boolean indicating if cars are hidden or not.

click

public boolean click(java.awt.geom.Point2D pos,
                     RailCanvas rc)
Whenever a user clicks on the canvas, all dynamic segments receive this event. Check to see if the position is at your segment (within some reasonable grace) Indicate if you performed an action or not. This tells the system to continue to try to find a segment to handle the event or not. Defaults to no action, returns false to indicate nothing happened, system should try another segment.

Parameters:
pos - The click position
rc - The current canvas which contains this segment
Returns:
If an action/change was performed
See Also:
isDynamic()

dest

public abstract RailSegment dest(RailSegment source)
Each rail segment must at the very least tell us where it comes from and where it goes, currently. Indicate where you are coming from, it says where you're going. Null value means end of line. These values may be dynamic, as in a switch.

Parameters:
source - The rail segment of origin
Returns:
The destination rail segment, or null if there is none.

destNZ

public final java.util.ArrayList<RailSegment> destNZ(RailSegment source)
Finds the first non-zero length RailSegment going away from the source. Returns the sequence of segments (*including* the current one) required to get there.

Parameters:
source - The originating segment
Returns:
A vector of the segments, in order, traversed to arrive at the non-zero length segment.
See Also:
dest(RailSegment)

draw

public abstract void draw(int z,
                          java.awt.Graphics2D gc)
Draw the segment. Segments have several z-layers to allowed slightly overlaping pieces to still look nice. z = 1 is a static layer (lowest) z = 2 is a static layer (highest) z = 3 is reserved z = 4 is the dynamic layer. This is redrawn frequently, if requested by the segment.

Parameters:
z - The currently z-layer to draw
gc - A Graphics2D graphics context.
See Also:
isDynamic()

editPanel

public abstract javax.swing.JPanel editPanel()
You are guaranteed that the variable ec will be set prior to this call. So if you need to refresh the canvas or make any changes to it, you can use that variable.

Returns:
A JPanel to display in the sidebar to edit this segment's properties. Please keep width at 200 pixels top.

enter

public void enter(Train t)
Notification that a train is in the segment. You may be notified arbitrarily often/many times. Check trains() to see if it remains. Defaults to no behavior.

Parameters:
t - The train in the segment.

getDest

public final RailSegment getDest(int dest)
Returns a given destination RailSegment.

Parameters:
dest - Which connection number (as defined by the individual class) to retrieve.
Returns:
The RailSegment corresponding to that connection.

getPoint

public final java.awt.geom.Point2D getPoint(int ptIdx)
Returns a given point.

Parameters:
ptIdx - The point index to retreive.
Returns:
The Point2D from the pts array.

getPoint

public abstract java.awt.geom.Point2D getPoint(RailSegment start,
                                               double myPos)
Parameters:
start - The segment of origin
myPos - Percentage (0-1) along the segment
Returns:
A Point2D indicating the actual point that location represents

isDynamic

public boolean isDynamic()
Dynamic segments receive additional events while the game is running; non-dynamic segments are only asked to draw z levels 1 and 2 at draw static time. Defaults to false (not dynamic). Non-dynamic segments also may not receive notifications for various events.

Returns:
Indicates if the segment should receive z=4 draw events and click events.
See Also:
draw(int, Graphics2D), click(Point2D, RailCanvas)

length

public abstract Distance length()
all segments have a length can be 0 for signals, etc. length must be the same no mattter which 'way' you traverse the segment Distance may be a 0-foot distance, but not may be null.

Returns:
The Distance of the segment.

mouseOver

public java.lang.String mouseOver(java.awt.geom.Point2D pos)
Whenever a user mouses over the canvas, all dynamic segments receive this event. Check to see if the position is at your segment (as in click). Return a describe if applicable, otherwise null. Defaults to returning null.

Parameters:
pos - The mouse position
Returns:
Description if applicable, otherwise null
See Also:
isDynamic()

nearEditPoint

public final SegmentEditPoint nearEditPoint(java.awt.geom.Point2D loc,
                                            RailSegment attach)
Given a point, find out if it is near one of our edit handles (z=5). If so, check if we can attach the segment requested (may be null for no segment to attach). If so, return an edit point

Parameters:
loc - The point location
attach - The segment (or null) that wants to attach here
Returns:
A SegmentEditPoint, or null.

pixelStep

public final double pixelStep(double myPos)
Given a position (percentage), move one pixel and give the new percentage.

Parameters:
myPos - The current percentage (0-1) along the segment.
Returns:
The new percentage, or 1 if the end of the segment has been exceeded, for moving forward one pixel.

setDest

public final void setDest(int point,
                          boolean ifNotNull,
                          RailSegment value)
Updates one of the connecting segments to this segment. Each type of segment must define its own point constants. Note this is an undoable edit if the edit canvas undo manager is available.

Parameters:
point - A value defined by the rail segment to indicate one of its ends
ifNotNull - Only perform the update if the value is currently null
value - The new rail segment

setPoint

public final void setPoint(int point,
                           java.awt.geom.Point2D p)
Update a drawing point.

Parameters:
point - The point index (meaning defined by the individual segment) to update.
p - The new point

getDests

public final int getDests()
Returns:
The numbers of destinations this segment has

getPoints

public final int getPoints()
Returns:
The number of drawing points this segment has

singleton

public boolean singleton()
Singleton segments may only have one train in them at a time. If additional trains are detected, a rail accident occurs. Defaults to false (not a singleton).

Returns:
If the segment may only have one train on it at a time

step

public final double step(double myPos,
                         double mySpeed)
Parameters:
myPos - The current percentage (0-1) along the segment
mySpeed - The current MPH
Returns:
The new percentage location, or 1 if the end of the segment has been exceeded. Note that the origin does not matter because the length must be the same either way.

trains

public final java.util.Set<Train> trains()
Note: Set contents will be maintained automatically, read only

Returns:
What trains are (at least partially) in this segment

update

public final void update(java.awt.geom.Point2D original,
                         java.awt.geom.Point2D replacement)
Update a point location for this segment. You must be able to handle original locations that are not your points (in which case do nothing) This updates end points only.

Parameters:
original - The original location
replacement - The new location

update

public final int update(RailSegment test,
                        RailSegment newValue)
Updates a connection from a given segment to a new one. This is an undoable edit if the edit canvas undo manager is available.

Parameters:
test - The original segment to replace
newValue - The new segment to replace it with
Returns:
The point id (used for @link{#set}) which was updated, or -1 if no update occured.

createSEP

protected abstract SegmentEditPoint createSEP(int ptIdx,
                                              RailSegment attach)
Given a point index in the pts array and possibly a railsegment to attach, return a segmenteditpoint if such attachment is possible. If the attach segment is null, no segment is attaching, just user editing.

Parameters:
ptIdx - The index into the pts array.
attach - The segment that desires to attach. (Note: do not attach the segment automatically; it will be called through the anchor method in the edit point).
Returns:
A SegmentEditPoint if possible, otherwise null.

recomp

public abstract void recomp()
Called when changes are made; recompute or update any associated values.