Understand ESRI sample scripts and user created scripts

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

• 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:
  
  

  Code:
  ' 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:
  
  

  Code:
  ' 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.
  
  

  Code:
  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
  
  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:
  
  

  Code:
  ' 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.