地理信息系统开发工具GISDK使用手册英文版第三部分CreatingGISDKMacros知识讲解.doc

此文档收集于网络，如有侵权请联系网站删除
Creating GISDK Macros
1 GISDK Mechanics 3
1.1 Compiling Resources 4
1.2 Working with the GISDK Debugger 12
1.3 Installing GISDK Applications 19
Installing and Running Add-Ins 20
Installing and Running Custom Applications 20
1.4 Accessing TransCAD as a COM Object 25
1.5 Accessing TransCAD Matrices from FORTRAN Programs 44
2 Language Elements 53
2.1 Language Elements 53
2.2 Variables 54
2.3 Types 55
2.4 Variable Scope 64
2.5 Function Calls 66
2.6 Statements 69
2.7 Error Handling 75
3 Resources 76
3.1 Macros 77
3.1.1 Macro Arguments 77
3.1.2 Macro Return Values 78
3.1.3 Functions for Macros 79
3.2 Dialog Boxes 79
3.2.1 Dialog Box Arguments 80
3.2.3 Dialog Box Return Values 81
3.2.4 Position 81
3.2.5 Options 82
3.2.6 Dialog Box Items 83
3.2.7 Tab Order 98
3.2.8 Functions for Dialog Boxes 99
3.3 Toolboxes 99
3.3.1 Tool Items 100
3.3.2 Update Item 102
3.3.4 Close Item 103
3.4 Toolbars 103
3.5 Menus 104
4 Standard Interface Macros 107
Annotation Font 109
Annotation Select 109
Annotation Text 110
Call Menu Item 110
Create Legend 110
File Close All 111
Layer Settings 111
Layer Status 112
New Layer Default Settings 112
Scale for Layer 113
Setup Colors 113
Setup Colorsplay 114
Setup Fill Styles 114
Setup Fillsplay 114
Setup Line Styles 115
Setup Linesplay 115
Setup Palettes 116
Setup Quantile Fillstyles 117
Update Map Toolbar 117
Set Exist 117
Create Set 118
Delete Set 118
Locate View 118
Locate Address 121
Locate Address Results 122
Address Match 124
Get Rule Files 125
Get City Rule Files 126
Get Location Index Properties 126
Get Location Index 127
Find with Location Index 128
Drop Location Index 130
Drop All Location Indexes 131
Locate View 131
Location Index Example 133
Set Default Route System Style 136
Set Network 136

You write GISDK macros and other resources, including dialog boxes and menus, using Caliper Script, a programming language that provides full access to GISDK functions in the platform. Resources are compiled into a database, called a UI Database. This section describes the mechanics of creating UI Databases, the language elements in Caliper Script, and the types of resources that you can write. Also described are the GISDK Debugger and accessing TransCAD as an Automation Server.

For more information, see...
GISDK Mechanics
Language Elements
Resources

1 GISDK Mechanics

GISDK provides a powerful means for creating, testing, and installing add-ins, custom applications, and server applications. This section contains technical information on GISDK and how it works, including essential reference information.

For more information, see...
The Platform and the UI Database
Compiling Resources
Working with the GISDK Debugger
Installing GISDK Applications
Accessing TransCAD as an Automation Server

The Platform and the UI Database

To a user, TransCAD is a program like any other Windows program. To a GISDK developer, however, TransCAD has two distinct parts: the platform and the user interface (UI).

· The platform is the core set of geographic information system (GIS) and database management system (DBMS) capabilities that are used to make maps and perform analysis.
· The user interface (UI) is the set of menus, dialog boxes, toolbars, and toolboxes that provide a user with access to these capabilities, along with the GISDK instructions that are followed when a menu item, toolbar, toolbox, or dialog box option is chosen.

The platform is contained in the executable program file (tcw.exe) and the various dynamic link libraries (DLLs) and other files that support it. The UI is stored in a database, called the UI Database. The UI Database for TransCAD is named gis_ui and contains the following files: gis_ui.dbd, gis_ui.1, gis_ui.2, gis_ui.3, gis_ui.4, gis_ui.5, and gis_ui.6. The platform and the UI Database are inseparable -- each one is useless without the other.

When you create GISDK applications, you create your own UI Databases. When you run an add-in or custom application, you are combining the platform with your own UI Database. You choose the UI Database you want to use when you install an add-in or custom application, or by modifying the command line that starts the platform.

1.1 Compiling Resources

When you write GISDK programs, they are stored in ordinary text files that are known as resource files. Resource files always have an extension of .rsc. Because Caliper Script is a compiled language, the programs you write must be compiled before they can be run. The program that compiles the resources is known as the resource compiler. The compiled resources are stored in a UI Database.

Here is a flow chart that shows the relationship between resources, the resource compiler, the UI Database, and the platform.

The resource compiler can compile a single resource file, or a group of files, at one time. To compile a group of files, you create a list file. A list file is a text file with an extension of .lst that contains the names of all the resource files in your GISDK application, one per line.

The resource compiler checks resource files as they are compiled for various types of errors, including errors in syntax, invalid statements, and mismatched do-end statements. If errors are detected, the resource compiler creates an error file listing each error and the line number at which it was detected. 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 includes several versions of the resource compiler. You can choose to compile resource files using:

· The buttons in the GISDK toolbox
· The rscc.exe program from DOS or Windows
· LoadResourceFile() from within your own GISDK application

For more information, see...
Compiling and Testing with the GISDK Toolbox
Compiling with the Stand-Alone Resource Compiler
Compiling with LoadResourceFile()
User-Defined Compilation Flags

Compiling and Testing with the GISDK Toolbox

The GISDK toolbox is an add-in that contains tools you use to compile and test GISDK applications:

Tool Function
Compile resource file(s) to the default UI Database
Test a macro or dialog box
Compile resource file(s) to a stand-alone UI Database
Start the GISDK Debugger
Execute one or more Caliper Script statements immediately

When you installed TransCAD, the GISDK Toolbox add-in was added to the add-ins.txt file, just like any other add-in.

The button in the GISDK Toolbox compiles resources into a UI Database named test_ui. When you compile a resource file (or several resource files in a list file) using the button, first the test_ui database is cleared, and then the compiled resources are added to that database.

The button in the GISDK Toolbox tests a resource that you compiled into the test_ui database. You specify the name of the resource to run, and whether it is a macro or a dialog box.

The button in the GISDK Toolbox lets you choose the UI Database in which to store the compiled resources. The database you choose is cleared, and then the compiled resources are added to the database.

The button in the GISDK Toolbox starts the GISDK Debugger, which helps you find and fix runtime problems in GISDK macros. You can set breakpoints in resource files, see the call stack, see the values of variables, and set up a watch list. The GISDK Debugger runs along side TransCAD, in a separate window.

The button in the GISDK Toolbox lets you type Caliper Script commands into a dialog box and have them executed immediately. This is often helpful when you are testing or debugging your GISDK programs.

There are many cases where immediate execution of a statement is helpful. For example:

Statement
When to use it
ShowMessage()
To display debugging information (e.g., ShowMessage(GetLayer()) to display the name of the current layer; or ShowMessage(state_view.Name) to see the name of the State your GISDK macro loop is working on)
SetLayer()
To set the current layer before testing an add-in
DestroyProgressBar()
If your GISDK macro accidentally leaves a progress bar on the screen, this statement will get rid of it
SetScale()
To change the map scale to an appropriate value
RunMacro()
To run a GISDK macro you use for testing or debugging purposes

Immediate execution can be used to import files, perform selection, read and update data values, and more. However, certain commands may not have the desired effect. Here are a few examples:

· The Exit() statement will terminate TransCAD and return you immediately to Windows
· Assignment statements will have no effect, unless the variable you are assigning to is a global variable
· The Return() statement will have no visible effect, because it simply returns from the immediate execution GISDK macro.

) To Compile a Resource File into the Default UI Database

1. Click in the GISDK toolbox to display the Compile dialog box.
2. Choose the file to compile and click OK.
GISDK compiles the resource file into the test_ui database. If any errors are encountered, the compiler creates an error file and displays a message.

) To Compile a List of Resource Files into the Default UI Database

1. Click in the GISDK toolbox to display the Compile dialog box.
2. Choose the file containing a list of resource file names to compile and click OK.
GISDK compiles the resource files into the test_ui database. If any errors are encountered, the compiler creates error files and displays a message.

) To Test a Resource in the Default UI Database

1. Click in the GISDK toolbox to display the Test an Add-In dialog box.
2. Choose the type of add-in that you are testing from the Type of Add-In radio buttons, Macro or Dialog Box.
3. Type the name of the resource you want to test, and click OK.
GISDK tests the resource you chose. If you want to test a resource where there is interaction with a map or other window, such as clicking to select a map feature, you will need to compile the resource file into a custom UI Database, install it as an add-in, and run it from the Add-Ins dialog box.

) To Compile a Resource File into a Custom UI Database

1. Click in the GISDK toolbox to display the Compile dialog box.
2. Choose the file to compile and click OK. GISDK displays the Save As dialog box.
3. Type the name of the UI Database you want to create, and click OK.
GISDK compiles the resource file into the UI Database that you chose. If any errors are encountered, the compiler creates error files and displays a message.

) To Compile a List of Resource Files into a Custom UI Database

1. Click in the GISDK toolbox to display the Compile dialog box.
2. Choose the file containing a list of resource file names to compile and click OK. GISDK displays the Save As dialog box.
3. Type the name of the UI Database you want to create, and click OK.
GISDK compiles the resource files into the UI Database that you chose. If any errors are encountered, the compiler creates error files and displays a message.

) To Execute Caliper Script Commands Immediately

1. Click in the GISDK toolbox to display the Immediate Execution dialog box.
2. Type the statement or statements you want to execute. Type Ctrl-Enter to advance to the next line.
3. Click OK when you are done.
The statements you typed are written to a resource file, compiled, and run.

Compiling with the Stand-Alone Resource Compiler

Resources can be compiled from the DOS command line or from the Windows Program Manager using the stand-alone version of the resource compiler (rscc.exe). This program accepts a command line of the following form:

rscc {-c} -u uidbname fname1.rsc fname2.rsc...

where:

· The -u flag indicates that the following entry in the command line (uidbname) is the path and file name (without extension) of the UI Database
· fname1.rsc, fname2.rsc, etc. are the names of resource files to be compiled
· The optional -c flag indicates that the UI Database should be cleared before compilation

If you do not use the -c flag, compiled resources will replace any existing resources that come from a file with the same name. If you compile a file called test.rsc, any resources from a previous version of test.rsc are removed from the UI Database before the new test.rsc is compiled.

A group of resource files can be compiled in one step using a list file as follows:

rscc {-c} -u uidbname @listfile1 @listfile2...

where listfile1, listfile2, etc. are names of list files, as described above. Note that the optional -c flag speeds up compilation by quite a bit when you are compiling a large number of resource files.

You can also combine list files and resource files in the command line, as in the following example:

rscc -c -u myxfac menus.rsc macros.rsc @rsc_list.txt

You cannot use the stand-alone version of the resource compiler while the UI Database is in use by the platform. For example, if you are working on a custom application that is stored in a UI Database named my_app, you cannot run the resource compiler using that same UI Database while the custom application is running.

Compiling with LoadResourceFile()

Your own GISDK applications can use LoadResourceFile() to compile resources. LoadResourceFile() lets you specify the UI Database you want to use and the resource file you want to compile. You cannot use a list file with LoadResourceFile(), though you can easily create a GISDK macro loop to load any number of resource file in sequence. In fact, you can use GISDK to design and implement your own custom dialog box that lets you choose the resources you want to compile and the name of the target UI Database.

If you are creating a custom application, you can include the following two menu items and the associated GISDK macros in your application. This lets you compile resources by choosing the appropriate commands from your own application's menu system. (The code that follows can be found in the utils.rsc file in the gisdk\samples folder).

// Here are two menu items...
// Move these into your menu system.
// This one asks the user for the name of a resource file, and compiles it
Menuitem "Compile Resource" do RunMacro("load a resource file", null) end
// This one immediately re-compiles the last resource file that was compiled
Menuitem "Re-Compile" do RunMacro("reload a resource file") end

// This first macro loads a resource file...
Macro "load a resource file" (filename)
shared rsc_file_name

if filename = null then do
// Ask the user which file to compile...
on escape do Return() end
rsc_file_name = ChooseFile({{"Resource","*.rsc"}},
"Compile Resource", {{"ReadOnly Box", "No"}})
on escape default
end
else rsc_file_name=filename

SetCursor("Hourglass")

// Do some basic error trapping...
on notfound do