Knowledge Base - Technical Articles


Technical Article   HowTo:  Understand ESRI sample scripts and user created scripts

Article ID: 19682
Software:  ArcView GIS 3.0, 3.0a, 3.0b, 3.1, 3.2, 3.2a
Platforms: N/A

Summary

The construction of an Avenue script determines how and when the script can be ran successfully. Before using a script you should know the answers to the following questions:

• What is the purpose of the script?

• Do I need to make any changes to the script in order to run it in my project?

• Which GUI should I run the script on?

• Should the script be attached to a button, tool, or menu control?

• If the script should be attached to a tool, should it be ran as a Click event or an Apply event?

This article will help you answer these questions.

Procedure

Many Avenue programmers include information about the script in the header section of the code. In place of a header the programmer may choose to distribute the script with a text file. This file often contains details and specific instructions for using the script. The script may also be imbedded in a document that contains instructions. Details may appear as comment lines throughtout the script.

If you encounter unfamiliar concepts in the header, or associated text files, search the ArcView Help for more information.

  • Script purpose:

    The script purpose should be stated clearly in the script header or text file. If the script lacks a header or text file, run the script in a new empty project to determine what the purpose might be.
  • Making changes to the code:

    In some cases you may be required to replace certain parts of the script to make it work in your project. For example:

    ' This script returns a list of themes in a view. 
    
    ' Copy and paste this code into a new script window.
    ' Replace the text MyView with the name of your view.
    ' Compile and run the script.

    ' Get the view.
    TheView = Av.FindDoc("MyView")

    ' Get a list of themes in the view.
    TheThemes = TheView.GetThemes

    ' Return the list of themes in a message box.
    MsgBox.ListAsString(TheThemes, TheView.GetName
    ++"contains these Themes.", "Theme List")

    Let's suppose you would like to run this code on a view named City Parcels. You would change the first line of code to:

    ' Get the view.
    
    TheView = Av.FindDoc("City Parcels")

  • Finding the GUI:

    If the script's header or text file dows not contain information about which GUI to run the script on, examine the code and look for the text GetActiveDoc.

    TheDoc = Av.GetActiveDoc
    
    TheGraphicsList = TheDoc.GetGraphics

    Notice the variable to the left of the equals sign. Programmers commonly use the the following variable names to reference document types.

    ¤ Views: "theView", "MyView" or "v".
    ¤ Tables: "theTable", "MyTable" or "t".
    ¤ Layouts: "theLayout", "MyLayout or "l".

    In the case above, it is not clear from the variable name, TheDoc, which document type is intended; however, the second line of code gives us a clue. The request GetGraphics can only be sent to view and layout documents; therefore, you could attach this script to a button on the View GUI or the Layout GUI.
  • Running the script:

    You can run a script by clicking on the

    Run compiled script button button or by attaching the script to a button, tool, or menu control. Again, the programmer should provide information for running the script.

    There are two kinds of scripts, those that require input from the user and those that do not. Scripts that require user input should be attached to the Apply event of a tool. Scripts that do not require user input can be attached to the Click event of a tool, button, or menu control.

    Let's examine this script:

    ' This script blinks features of the active theme in a view
    
    ' which are clicked on by a user. Attach the script to the
    ' Apply event of Tool on the View GUI. Select the tool then
    ' click on the view.
    '
    ' Get the active theme in the view.
    theView = av.GetActiveDoc
    theTheme = theView.GetThemes.Get(0)
    '
    ' Return point click on by user.
    p = theView.GetDisplay.ReturnUserPoint
    '
    ' Get the feature that intersect the point.
    FeatureList = theTheme.FindByPoint( p )
    '
    ' Blink each reocrd that intersect the point.
    for each f in FeatureList
    theTheme.BlinkRecord( f )
    end

    We can tell from the first line of code that this script should be ran on the View GUI. Looking at the third line we can tell that this script should be attached to an Apply event of a tool. This third line requires that the user clicks the view to return a point. That point is used later to find features of the active theme. If we attach this script to a Click event the code runs immediately. There is no opportunity to click the view; thus, you get an error.

    Scripts that do not need to be attached to the Apply event of a tool can also be ran by doing the following.

    1. Position the Script window and the appropriate document window so both are visible.
    2. Make the document active.
    3. Click directly on the Script window.
    4. Click the Run button.

Created: 6/11/2001
Last Modified: 7/24/2001

If you would like to post a comment, please login