Milestones feature

The Milestones feature is designed for Polylines and Polygons.

The purpose is to display additional info on the map following the Polyline/Polygon path, like:

• a work-in-progress icon every 100 pixels
• a direction arrow every 10 km
• a slice of the path in a different color

The Milestones feature uses several specific classes and concepts:

• MilestoneStep - a pixel position where a milestone should be displayed, for instance the position where I should display an icon
• abstract MilestoneLister - which computes the list of the MilestoneSteps, for instance every 10km of the Polyline/Polygon path
• abstract MilestoneDisplayer - which displays each MilestoneStep, for instance a bitmap display
• MilestoneManager - which embeds a MilestoneLister and a MilestoneDisplayer, to be used in the Polyline/Polygon's draw method

The purpose of the abstract MilestoneLister is to create a list of MilestoneSteps, from a list of PointL that are the Polyline/Polygon GeoPoint vertices projected on the Canvas.

A MilestoneStep is a pixel position where a milestone should be displayed, with an orientation and an optional parameter. When the MilestoneLister is working, the result will be something like:

• in this pixel position on the screen (this is where we will display something somehow)
• the Polyline/Polygon path orientation is x degrees (we may need that if we want to follow the path orientation)
• and this is the nth MilestoneStep computed so far (we may need that if we want to display something different every m step)

The following classes extend MilestoneLister:

• MilestoneVertexLister simply lists the vertices - use case - if I want to display all the vertices
• MilestoneMiddleLister lists all the vertices' segments' middle, provided that there are enough pixels between them - use case - if I want to display a direction arrow at each segments' middle (which may not be relevant after all)
• MilestonePixelDistanceLister lists every x pixels of the path after an initial value - use case - if I want to follow the Polyline/Polygon with a direction arrow every 50 pixels starting at the start vertex + 25 pixels
• MilestoneMeterDistanceLister lists every [x,y,z,...] meters of the path - use case - if I want to display something every 10km, or in a more refined way the important steps of a marathon [0km, 10km, 20km, 21.097km, 30km, 40km, 42.195km]
• MilestoneMeterDistanceSliceLister lists the vertices for a slice of the path between two distances - use case - if I want to display a slice of the road, between 0 and "x" km, animating by increasing "x"

The purpose of abstract class MilestoneDisplayer is to display milestones. Its abstract method is draw(Canvas, Object), which draws on pixel (0,0) with no rotation. Its main method is draw(Canvas, MilestoneStep), which rotates and translates the Canvas according to the MilestoneStep, before calling the abstract draw method with the MilestoneStep optional parameter.

The following classes extend MilestoneDisplayer:

• MilestoneBitmapDisplayer displays a single Bitmap - use case - if I want to display a work-in-progress icon, or if I want to display a direction arrow that follows the path's trajectory
• MilestonePathDisplayer displays a single Path - use case - if I want to display a 5-branch star (computed from a Path), or if I want to display a direction arrow (computed from a Path) that follows the path's trajectory
• MilestoneLineDisplayer displays a polyline - use case - if I want to highlight a slice of the Polyline/Polygon path

The purpose of class MilestoneManager is:

• to embed a MilestoneLister and a MilestoneDisplayer
• to be used in Polyline/Polygon's draw method, where the list of MilestoneSteps is computed, then displayed

In the draw method of Polyline/Polygon, each of their MilestoneManagers will:

• compute from scratch all the MilestoneSteps it has to display using its MilestoneLister
• display these MilestoneSteps using its MilestoneDisplayer

The distances in meters between all the Polyline/Polygon vertices are previously computed in LinearRing.getDistances(), and can be used by the MilestoneLister.

The MilestoneManagers of Polyline/Polygon can be set using method setMilestoneManagers.