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 that 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.

// Now the test program is used to run the toolbox instead of the macro.

Macro "lesson2"

 

    // Call the toolbox.

    result = RunDbox ("find and zoom toolbox"))

 

endMacro

 

// 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 "find and zoom toolbox"  center,center Title: "Find and Zoom" ToolBox NoKeyboard

    // 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 dbox is first opened.

    Init do

 

        // Set the layer variable for use below; always put a layer name into

        // a variable, so that if you change the layer name you only have to

        // change it in one place in your program.

        layer="Place"

 

        // 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))

    endItem

 

    // This is needed to allow the user to close the toolbox by clicking on

    // the X in the upper-right corner.

    Close do

        return()

    endItem

 

    // Create a tool that, when chosen, waits for the user to click on the map.

    // You will use the find icon from the standard Maptitude bitmap file

    // (buttons.bmp), with bitmaps for not chosen, chosen and disabled.

    Tool "click_tool" 0,1 Icons:"bmp\\buttons|33", "bmp\\buttons|67",

        "bmp\\buttons|101"   help: "Click on Map"

        do

 

            // 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",

                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.

                    // Distance will be right justified, 1 decimal, ending in column 5.

                    f_distance = {5, "R*0.0", points_list[i][1]}

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

                    f_city = {7, "L", points_list[i][2]}

                    // State will be left justified, starting in column 32.

                    f_state = {32, "L", points_list[i][3]}

                    // Second, put them together in an array.

                    f_array = { f_distance, f_city, f_state }

                    // Third, concatenate the formatting array with that array.

                    formatting_array = formatting_array + { f_array }

                    end

 

                // 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})

 

            end

        endItem

 

    // 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

 

EndDBox

 

Note: This updated macro includes an intentional typo on line 6 (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 Maptitude, 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 as shown below. (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 6.
3. Save the modified file.
4. Switch back to Maptitude.
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 "Find and Zoom" 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 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.