In this article:
Functions for Creating a Map Window
The interface to the PC*MILER Rail-Connect mapping functions gives you control over when and how pins, routes and lines are drawn, and allows data about a pin to be displayed in a dialog box when the pin is chosen.
All arguments are strings, and the separator between elements in stops, styles, options and labels is a vertical bar ('|'). For example, "Newark NJ|Chicago IL|191600" is a valid series of stops, and "Red|5" is a valid style. The separator for an importance range is two periods (".."). For example, "1..4" is a valid importance range, as is simply "4" (the trip appears at levels 4 and higher).
Functions for Creating a Map Window
This function creates a new map window. The first argument is the handle to the parent window. If the first argument is NULL, the new window will be created as a child of the desktop window. A standalone overlapped map window will be created as a child to this parent window and the title, width and the height for the map window will be set. This map window always stays on top of the parent window and it has a title and border.
This function returns the valid handle to the map window if it creates the map window successfully. It returns NULL on error.
This function creates a new map window as a child of the parent window. In this case, the map window is not a standalone window. Instead it gets created in the client rectangle of the parent window. The new map window does not have a title or border.
The first argument, which is the handle to the parent window, must not be NULL.
This function returns the valid handle to the map window, if it creates the map window successfully. It returns NULL in case of error or if the parent window handle is NULL.
A Delphi canvas, Visual Basic Form or a Borland OWL TFrameWindow could all be parent windows.
In order to resize the map canvas, you should forward resize messages from the parent to the map window child using PCRSResizeMapChild.
This function returns FALSE if the parent window does not exist. Otherwise, it resizes a map canvas to the size of the parent window created using PCRSCreateMapWin. Calling this function will make the map child resize itself to fit exactly inside the parent window.
Returns FALSE if the map window was not created successfully or TRUE if it was created successfully and is ready for further use. It is a quick programmatic way to check if the map window is ready for use.
Pin Functions
Create or update a pin. The pin is uniquely identified by layerID and ID. If the given pin does not exist, it is created. If it does exist, all data for the pin is updated. The return code is negative if there is an error. If the layer identified by layerID does not exist, then a layer is created.
The field ID can be any text string.
The field importance determines a level of importance for the given pin. The importance of a pin determines at what level of detail the pin is drawn. Level of detail works as follows: as the user zooms in to tighter areas on the map, the level of detail increases. This means that less significant roads, places, and pins come into view as the user zooms in. There are six levels of detail.
For pins, importance can be a number between 1 and 8. Importance level 1 is the most important; pins with importance level 1 are always shown. Pins with importance level 8 are only shown when the user is zoomed in very tight.
If you do not care about importance, specify "1" for the importance argument. Pins with importance level 1 will always be shown.
Importance can be specified as a range, such as "1..3". If a pin's importance is specified as a range, then it will only be shown when the map's level of detail falls into that range. For example, suppose a pin is assigned the importance range "1..5". The pin will show up when the map's level of detail is between 1 and 5. Detail level 5 roughly corresponds to a zoom level of a single state. Therefore, the pin will not show up when the map is zoomed in tighter than a single state.
Ranges can be useful when trying to reduce clutter on the map. Using importance ranges, one could set-up different views of the same data, each with different levels of detail. For example, suppose one is trying to plot 200 icons in two neighboring states. When the map is zoomed to the entire United States, the 200 icons in those two states become very cluttered.
To solve this problem, one could create two pins--one for each state--that are displayed at importance levels "1..3". Then, the 200 pins could be marked with importance levels "4..6". This has the effect of showing two pins--one in each state--at the U.S. level. As the user "zooms down" to the state level, the two aggregate pins will disappear, and the 200 pins will appear.
The field symbol must specify a valid symbol. Can be internal DLL type (such as ‘Green Box 5’, ‘Red Box 15’ – indicates size), or user supplied path to a .BMP or .PNG file (‘c:\pins\myIcon.bmp’).
The field location is a text string specifying a Station/State, i.e. a station name followed by a two-character state abbreviation (example: Houston TX).
The field data is an optional list of up to 8 values for PC*MILER Rail to store and display in an information dialog when the pin is clicked on. The values in the list are delimited by vertical bars.
This function deletes the pin identified by ID in the layer layerID.
This function removes the layer identified by layerID from the map. All pins in the layer are deleted.
PC*MILER Rail-Connect Icons
TIP: Size the canvas before beginning to draw.
A PC*MILER Rail-Connect icon is a text string composed of two parts: type and color. Available icons are listed in the map_opts.ini file (shown below) found in the App folder of your PC*MILER Rail installation.
In addition to the icons, a Box or Circle can be plotted with a size argument (e.g. ‘Red Box 10’) which sets the box’s size in pixels.
You can also plot icons of your own design. To do so, pass the complete path to a .BMP or .PNG file to the PlotPin or PlotPinID functions. For example, if you pass the path C:\ALK Technologies\PCRWINXX\pins\icon.bmp to either function, you’ll see a new bitmap with the word ‘ICON’ on it displayed on your map. Pins must be in .BMP or .PNG format.
Trip and Line Functions
This function calculates and draws a trip on the map where routeName is the feature layer to add the new trip to, this name will be displayed in the map window. Use routeName to delete this trip, using PCRSDeleteTripByName.
orig and dest: string containing origin/destination place code
origRR and destRR: origin/destination railroad SCAC code (4-char abbrev.)
origGeo and destGeo: City, SPLC, FSAC, ERPC, or Rule260
pMiles: pointer into which calculated trip distance will be placed (in tenths of miles/kms)
See PCRSPlotTrip above.
Additional arguments:
routeType: I (interactive, i.e. standard) or A (autoroutes)
routeMethod: F (familized, for autoroutes) or N (not familized, for standard)
Where layerID is the feature layer to add the new line to, ID is its unique identifier, importance is a range of numbers denoting which levels of detail it will appear at, symbol is what color and width to use, and locations is the list of points (PC*MILER Rail place names) that make up the line.
All arguments are strings, and the separator between elements in symbols and locations is a vertical bar ('|'). For example, "Houston TX|Chicago IL|191600" is a valid series of points, and "Red|5" is a valid symbol. The separator for an importance range is two periods (".."). For example, "1..4" is a valid importance range, as is simply "4" (the trip appears at levels 4 and higher). An importance level of 1 is the highest, meaning the line will always appear.
This function frames the line created using PCRSPlotLine.
This function can be used to add a pre-defined route (created with PCRSNewTrip) to the map using its unique trip ID. This requires that the trip ID be valid, that the trip is already properly populated, and has been successfully run.
This function deletes the trip created using PCRSAddRouteToMap.
This function removes the trip identified by routeName.
This function deletes all trips created using PCRSPlotTrip or PCRSPlotTrip2.
This function removes the line identified by ID in the layer layerID.
Layer Management Functions
The user can group pins, trips, and lines into "layers" or "pinmaps." These layers can be modified by the user through DLL function calls.
This function changes the visibility of the layer specified by layerID. If the show parameter is non-zero, the layer is visible. If the show parameter is zero, the layer is hidden. It is NOT deleted. Layers can be shown or hidden as often as desired.
Zooms the map to include all the pins in the pinmap layer layerID.
Deletes the layer specified by layerID.
Zooms the map in by one zoom level.
Zooms the map out by one zoom level.
