You are on page 1of 6

Lesson 2: Adding a Toolbox Página 1 de 6

TransCAD 7 Help
Home / Welcome to GISDK Help

Lesson 2: Adding a Toolbox

Now, instead of having the test program supply a coordinate, you want to get it from the users when they click on the
map. A toolbox is a dialog box that stays on the screen all the time. It can contain a "tool" that captures the user’s
interaction with the map. The test program (now called macro "lesson2") calls the toolbox which will, in turn, call the
"get nearest points" macro developed in Lesson 1. The source code for Lesson 2 is stored in the LESSON2.RSC file in the
GISDK\SAMPLES folder. Below is the source code, excluding the "get nearest points" macro that remains unchanged.

// This code is in lesson2.rsc.

Macro "lesson2"
// Save the name of the current layer.
curr_layer = GetLayer()

// Set the current layer to the line layer.

line_layer = "Highway"

// Define the fields in the network as length and travel time. The
// first element in the array is the field name you assign in the
// network. The second and third elements are the field names in
// the highway database in the forward and reverse directions.
linkflds = {{"Length", line_layer+".Length", line_layer+".Length"},
{"[Travel Time]", line_layer+".[Travel Time]",
line_layer+".[Travel Time]"}}

// Share the network as you will need it in other macros in this file.
shared net

// Create the network and assign a temporary name to the network.

net = createNetwork(,GetTempFileName("*.net"),"Network",linkflds,,)

// Restore the current layer.


// Call the toolbox.

result=RunDbox("get best route toolbox"))

// Create a toolbox, which is a type of dialog box (dbox).

// The keyword "ToolBox" makes the dialog box display until closed by
// the user. The keyword NoKeyboard moves the focus to the toolbox
// immediately when user clicks in it.
Dbox "get best route toolbox" center,center Title: "Get Best Route" ToolBox
// A description of the dialog box:
// Displays Click on Map tool and Edit Text item to input search
// distance. Defaults search distance to 5 miles; when user clicks
// on the map, call the macro to find nearest places and then
// display the array. This section is automatically run when the

mk:@MSITStore:C:\Program%20Files%20(x86)\TransCAD%207.0\transcaddk.chm::/dk... 05-05-2017
Lesson 2: Adding a Toolbox Página 2 de 6

// dbox is first opened.

Init do
// Set the point layer variable for use below; always put a layer
// name into a variable, so that if you change the name you only
// have to change it in one place in your program.
// Set the highway and node layer variables.
highway_layer = "Highway"
node_layer = "CDF Node Layer"
// Initialize the search_distance to 5 miles, based on the
// current map units. R2I() changes a real number to an integer.
current_units = GetMapUnits("Plural")
search_distance = R2I(5 * GetUnitSize("Miles", current_units))
// This is needed to allow the user to close the toolbox by clicking
// on the X in the upper-right corner. This also clears any path
// annotations that were drawn previously.
Close do
if aid <> null then DropAnnotation(, aid)
// Create a tool that, when chosen, waits for the user to click on the map.
// You will use the find icon from the standard TransCAD bitmap file
// (MainButtons.bmp), with bitmaps for not chosen, chosen and disabled.
Tool "click_tool" 0,1 Icon: "bmp\\MainButtons|16" help: "Click on Map"
// Wait for user to click on map.
clicked_point = ClickCoord()
// Run the nearest places macro from lesson 1.
// A program line can be continued on to the next line at
// any point except in the middle of a string.
points_list = RunMacro("get nearest points", point_layer,
node_layer, clicked_point, search_distance)
// If the macro found points then display the data; if no
// points are found, the macro has already displayed a
// message, so just drop through to end of item.
if points_list<>null then do
// You will copy the data into a formatting array for use
// in a scroll list in lesson 3.
// To demonstrate another way to create an array, you will
// build it by concatenation rather than dimensioning it.
// First set the formatting array to null.
formatting_array = null
// Now loop through the list of points and their data
for i = 1 to points_list.length do
// Concatenate the array with an array containing your
// data. First, create arrays for the formatting of
// each field. Net distance and Crow distance will be
// right justified, 1 decimal, ending in columns 5
// and 18.
f_netdistance = {5, "R*0.0", points_list[i][1]}
f_distance = {18, "R*0.0", points_list[i][2]}

mk:@MSITStore:C:\Program%20Files%20(x86)\TransCAD%207.0\transcaddk.chm::/dk... 05-05-2017
Lesson 2: Adding a Toolbox Página 3 de 6

// City will be left justified, starting in column 25.

f_city = {25, "L", points_list[i][3]}
// State will be left justified, starting in column 46.
f_state = {46, "L", points_list[i][4]}
// Second, put them together in an array.
f_array = { f_netdistance, f_distance, f_city, f_state }
// Third, concatenate the formatting array with that array.
formatting_array = formatting_array + { f_array }
// For checking purposes look at the original array and the
// formatting array. To show more than one variable with
// ShowArray(), combine them both into an array.
ShowArray({"points_list=", points_list,
"formatting_array=", formatting_array})
// Display the current integer value of search_distance and
// allow user to change it.
// Place the title at column 6, .5 rows down, and 16 characters wide.
Text "Search Distance" 6, .5, 16
// Place the integer edit box below the "Search Distance" title and
// make it 4 characters wide.
Edit Integer 8, 2.0, 4 Variable: search_distance
// Place the text for the current map units right after and on
// the same line as the integer edit box.
Text after, same Variable: current_units


// A macro to get the nearest points on the search layer and the highway distances
// between the source and target points
Macro "get nearest points" (search_layer, node_layer, subject_point,
// Each macro should have a description at the beginning:
// Finds points within search_distance units of subject_point on
// search_layer and returns an array containing a data array for each
// point, with network distance, crow flight distance, city and state;
// the data arrays are in order by network distance. This macro is
// designed to work with the Place and Highway layers in
// Store the current layer, then make the specified layer the working layer.
curr_layer = GetLayer()
// Find the nearest points in the working layer and return, in array rhs,
// the record handles (the string form of the record ID) for the closest
// records. The last argument, an options array, can be null.
rhs = LocateNearestRecords(subject_point, search_distance, null)
// If no points were found then display message and return.
if rhs = null then do
ShowMessage('Sorry, no points were within your search distance.')
// Reset the layer to the stored layer; this is very important
// when an add-in is working with the standard interface

mk:@MSITStore:C:\Program%20Files%20(x86)\TransCAD%207.0\transcaddk.chm::/dk... 05-05-2017
Lesson 2: Adding a Toolbox Página 4 de 6


// Dimension an array to the length of the record handles (rhs) array.

Dim data[rhs.length]
// share the network variable
shared net
// Look through the record handles array.
for i = 1 to rhs.length do
// Use the record handle to set the current record position on the
// current view (which in this case is the Place layer).
SetRecord(, rhs[i])
// Get the point coordinate for the current record on the current
// layer, converting the record handle to its numeric equivalent (an
// ID).
target_point = GetPoint(rh2id(rhs[i]))
// Get the distance between the clicked point and the current point.
distance = GetDistance(subject_point, target_point)
// Set the current layer to the node layer and get the node IDs of
// the nodes closest to the subject_point and the target_point,
// converting the record handle to its numeric equivalent
rh1 = LocateNearestRecord(subject_point, search_distance)
rh2 = LocateNearestRecord(target_point, search_distance)
node1 = rh2id(rh1)
node2 = rh2id(rh2)

// Calculate the shortest path between the subject and target point
// using the first network field (distance). Only do this if the
// two nodes are not the same, otherwise, network_distance = 0.
// Also, gather the list of link IDs and directions that form the
// best network path.
if node1 <> node2 then do
sp = ShortestPath(net, {node1, node2}, 1, )
network_distance = sp[1]
links = sp[2]
directions = sp[3]
network_distance = 0
// Add data to the output array. To add data from a current record
// for a layer use a "field specification", which is the layer name
// in a variable + "." + field name, e.g., not
data[i]={network_distance, distance,,
search_layer.state, target_point, links, directions}
end // end of record handles loop
// Reset the layer and return the data array to the calling program

mk:@MSITStore:C:\Program%20Files%20(x86)\TransCAD%207.0\transcaddk.chm::/dk... 05-05-2017
Lesson 2: Adding a Toolbox Página 5 de 6

Note: This updated macro includes an intentional typo on line 29 (an extra close parenthesis in the RunDbox()
command), to show you what happens when GISDK encounters a syntax error during compilation. Let’s go ahead and
compile the new version.

To Compile the Enhanced Version

1. From your text editor, open and examine the contents of the LESSON2.RSC file in the GISDK\SAMPLES folder.

2. From TransCAD, click in the GISDK Toolbox to display the Compile File dialog box.

3. From the GISDK\SAMPLES folder, choose the file named LESSON2.RSC and click Open.

GISDK compiles the file. When the GISDK compiler encounters a syntax error, it creates an error file listing each error
that was encountered. The error file has the same name as the resource file and an extension of .ERR, and is always
placed in the same folder as the resource file itself. GISDK also displays the contents of the error file. (If you don’t see
the error message, it is possible that someone else may already have run this tutorial and fixed the typo.)

For those of you who use a programmers’ editor, the error file is in the standard format that is created by most
compilers, so you can hot-key through the error and resource files.

To Correct the Resource Error

1. Switch back to the text editor.

2. Remove the extra close parenthesis in line 29.

3. Save the modified file.

4. Switch back to TransCAD.

5. Click in the GISDK Toolbox to display the Compile File dialog box.

6. Choose the LESSON2.RSC file and click Open.

This time, GISDK compiles the file successfully.

Note that GISDK compiles programs that are stored in files. This means that you must save your file using your text
editor program before you can compile and run it with GISDK. Note also that you do not actually need to be running
your text editor to compile or run a GISDK program. However, if you get into the habit of running GISDK and your text
editor at the same time, you’ll find you can modify your files and compile them very efficiently.

To Run the Enhanced Add-In

1. Click on the Lessons map to make it the active window.

2. Click in the GISDK Toolbox to display the Test an Add-In dialog box.

3. Click Macro in the Type of Add-In radio list.

4. Type "lesson2" in the Name text box.

5. Click OK. The add-in starts running and displays the "Get Best Route" toolbox in the center of the screen.

6. Click the Click on Map tool , then click on the map within 5 miles of a place. The add-in displays the arrays of
data for the nearest points.

7. Change the search distance to 1 mile and click over a mile away from any places. The add-in displays the "no

mk:@MSITStore:C:\Program%20Files%20(x86)\TransCAD%207.0\transcaddk.chm::/dk... 05-05-2017
Lesson 2: Adding a Toolbox Página 6 de 6

points" message.

8. Click the X in the upper right hand corner to close the toolbox.

You have proven that the toolbox is working. Again, leave the map open. You’ll be using it again in a few minutes.

Go to Lesson 3: Adding a Dialog Box.

©2015 Caliper Corporation

mk:@MSITStore:C:\Program%20Files%20(x86)\TransCAD%207.0\transcaddk.chm::/dk... 05-05-2017