地理信息系统开发工具GISDK使用手册英文版第三部分

1、.Creating GISDK Macros1 GISDK Mechanics31.1 Compiling Resources41.2 Working with the GISDK Debugger121.3 Installing GISDK Applications19Installing and Running Add-Ins20Installing and Running Custom Applications201.4 Accessing TransCAD as a COM Object251.5 Accessing TransCAD Matrices from FORTRAN Pro

2、grams442 Language Elements532.1 Language Elements532.2 Variables542.3 Types552.4 Variable Scope642.5 Function Calls662.6 Statements692.7 Error Handling753 Resources763.1 Macros773.1.1 Macro Arguments773.1.2 Macro Return Values783.1.3 Functions for Macros793.2 Dialog Boxes793.2.1 Dialog Box Arguments

3、803.2.3 Dialog Box Return Values813.2.4 Position813.2.5 Options823.2.6 Dialog Box Items833.2.7 Tab Order983.2.8 Functions for Dialog Boxes993.3 Toolboxes993.3.1 Tool Items1003.3.2 Update Item1023.3.4 Close Item1033.4 Toolbars1033.5 Menus1044 Standard Interface Macros107Annotation Font109Annotation S

4、elect109Annotation Text110Call Menu Item110Create Legend110File Close All111Layer Settings111Layer Status112New Layer Default Settings112Scale for Layer113Setup Colors113Setup Colorsplay114Setup Fill Styles114Setup Fillsplay114Setup Line Styles115Setup Linesplay115Setup Palettes116Setup Quantile Fil

5、lstyles117Update Map Toolbar117Set Exist117Create Set118Delete Set118Locate View118Locate Address121Locate Address Results122Address Match124Get Rule Files125Get City Rule Files126Get Location Index Properties126Get Location Index127Find with Location Index128Drop Location Index130Drop All Location

6、Indexes131Locate View131Location Index Example133Set Default Route System Style136Set Network136You 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 compi

7、led 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,

8、 see.GISDK Mechanics Language Elements Resources 1 GISDK MechanicsGISDK 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 informat

9、ion.For more information, see.The Platform and the UI DatabaseCompiling ResourcesWorking with the GISDK Debugger Installing GISDK ApplicationsAccessing TransCAD as an Automation Server The Platform and the UI DatabaseTo a user, TransCAD is a program like any other Windows program. To a GISDK develop

10、er, 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 se

11、t 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 v

12、arious 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 th

13、e 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 inst

14、all an add-in or custom application, or by modifying the command line that starts the platform.1.1 Compiling ResourcesWhen 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 c

15、ompiled 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,

16、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 app

17、lication, 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 n

18、umber 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 butto

19、ns in the GISDK toolbox·The rscc.exe program from DOS or Windows·LoadResourceFile() from within your own GISDK applicationFor more information, see.Compiling and Testing with the GISDK ToolboxCompiling with the Stand-Alone Resource CompilerCompiling with LoadResourceFile()User-Defined Comp

20、ilation FlagsCompiling and Testing with the GISDK ToolboxThe GISDK toolbox is an add-in that contains tools you use to compile and test GISDK applications:ToolFunctionCompile resource file(s) to the default UI DatabaseTest a macro or dialog boxCompile resource file(s) to a stand-alone UI DatabaseSta

21、rt the GISDK DebuggerExecute one or more Caliper Script statements immediatelyWhen 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 re

22、source 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 resourc

23、e 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 GISD

24、K 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 t

25、ype 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:StatementWhen to use itShowMessage()To display debugging

26、 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-inDestroyProgressBar()If your GISDK macro accidentally leaves

27、 a progress bar on the screen, this statement will get rid of itSetScale()To change the map scale to an appropriate valueRunMacro()To run a GISDK macro you use for testing or debugging purposesImmediate execution can be used to import files, perform selection, read and update data values, and more.

28、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()

29、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 Database1.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

30、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 Database1.Click in the GISDK toolbox to display the Compile dialog box.2.Choose the file containing a list of resource file nam

31、es 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 Database1.Click in the GISDK toolbox to display the Test an Add-In dialog box.2.Choose

32、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

33、 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 Database1.Click in the GISDK toolbox to display the Compile dialog box.2.Choose the file to com

34、pile 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

35、 of Resource Files into a Custom UI Database1.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.GIS

36、DK 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 Immediately1.Click in the GISDK toolbox to display the Immediate Execution dialog box.2.Type the statement or

37、 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 CompilerResources can be compiled from the DOS command line or from the Windows

38、 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

39、(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 compilationIf you do not use the -c flag, compiled resources will replace any existing resources t

40、hat 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 uidbnam

41、e 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 i

42、n the following example:rscc -c -u myxfac menus.rsc macros.rsc rsc_list.txtYou 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

43、 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 w

44、ant 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 an

45、d 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 cod

46、e that follows can be found in the utils.rsc file in the gisdksamples 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 itMenuitem "Compile Resource" do RunMacro("load a resource file", nul

47、l) end/ This one immediately re-compiles the last resource file that was compiledMenuitem "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_nameif filename = null then do

48、/ Ask the user which file to compile.on escape do Return() endrsc_file_name = ChooseFile("Resource","*.rsc", "Compile Resource", "ReadOnly Box", "No")on escape defaultendelse rsc_file_name=filenameSetCursor("Hourglass")/ Do some basic error

49、 trapping.on notfound doResetCursor()Return() endon error doResetCursor()ShowMessage("Compilation Failed.")Return()end/ Compile the resource file into the current UI databaseLoadResourceFile(,rsc_file_name,)ResetCursor()EndMacroMacro "reload a resource file"shared rsc_file_name/

50、See if something has already been compiled.if rsc_file_name = null then ShowMessage("No resource file was previously loaded.")else / Compile it again.RunMacro("load a resource file", rsc_file_name)endMacroNever use LoadResourceFile() to compile a resource file that contains a men

51、u or dialog box that is currently displayed. For example, suppose you are running a custom application that has menus and toolbars that you designed yourself. If you use LoadResourceFile() to compile the resource files that contain the menus and toolbars while those menus or toolbars are shown on th

52、e screen, your menus may cease to function.User-Defined Compilation FlagsYou can add user-defined compilation flags to your resource files to control which lines in the file are processed by the resource compiler. User-defined compilation flags are useful in the following type of circumstances:·

53、;Your resource files include debugging statements that you want to include for testing purposes, but not for a finished product·You want to be able to produce small variations on an application without duplicating lots of GISDK program codeHere is a sample GISDK macro that loops over each state

54、 and does some processing on it. This GISDK macro includes a debugging message that lets you know which state you are on.Macro "loop over states"vw = "States"SetLayer(vw)/ Start the loop by finding the first state.rec = GetFirstRecord(vw + "|", )while rec <> null

55、do/. do some processing here ./ Here's the debugging message.>XShowMessage("Finished with " + vw.Name)rec = GetNextRecord(vw + "|", , )endendMacroIf this resource is compiled with the X compilation flag, the debugging message will be included in the compiled resource, and

56、the name of each state will be displayed as it is processed. If this resource is compiled without the X compilation flag, the debugging message will be excluded from the compiled resource.You can create up to 26 user-defined compilation flags, one for each letter of the alphabet. In a resource file,

57、 you can mark lines for conditional compilation by using the < character (to exclude) or > (to include) character in column 1 of the file, followed immediately by one or more compilation flags.Here are some examples:Macro "extremely silly macro">AShowMessage("The A flag was u

58、sed ")>BShowMessage("The B flag was used ")>ABShowMessage("A, B, or both A and B were used ")<AShowMessage("The A flag was not used")<BShowMessage("The B flag was not used")<ABShowMessage("Neither the A nor B flag was used")endMacroTo compile a resource file using custom compilation flags, follow the instructions below:Compilation methodHow to use flagsGISDK ToolboxType the fla