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

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 Programs442 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 Arguments803.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 Select109Annotation Text110Call Menu Item110Create Legend110File Close All111Layer Settings111Layer Status112New Layer Default Settings112Scale for Layer113Setup Colors113Setup Colorsplay114Setup Fill Styles114Setup Fillsplay114Setup Line Styles115Setup Linesplay115Setup Palettes116Setup Quantile Fillstyles117Update 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 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 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 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 information.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 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 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 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 toolboxThe rscc.exe program from DOS or WindowsLoadResourceFile() 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 Compilation 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 DatabaseStart 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 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:StatementWhen to use itShowMessage()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-inDestroyProgressBar()If your GISDK macro accidentally leaves 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. 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 WindowsAssignment statements will have no effect, unless the variable you are assigning to is a global variableThe 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 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 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 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 Database1.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 Database1.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 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.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 Immediately1.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 CompilerResources 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 Databasefname1.rsc, fname2.rsc, etc. are the names of resource files to be compiledThe 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 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.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 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 applications menu system. (The code 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, null) 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/ 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 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 fileshared rsc_file_name/ 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 menu 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 the 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:Your resource files include debugging statements that you want to include for testing purposes, but not for a finished productYou 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 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 statesvw = StatesSetLayer(vw)/ Start the loop by finding the first state.rec = GetFirstRecord(vw + |, )while rec null do/. do some processing here ./ Heres 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 the name of each state will be displayed as it is processed. If this resource is compiled wi