A Quick Guide to Creating Arcview Extensions

Extensions are Arcview's method of extending the capability of Arcview. Extensions are saved as files and can be sent to colleagues for use in other systems. Extensions can consist of a single button that is added to an Arcview projects View GUI and the script that is run when the user clicks. If you use Spatial Analyst, 3D Analyst, and Network Analyst then you already have used extensions.

This document takes you through the steps necessary to write an Arcview extension. You will add components to a project file and then make adjustments to the extension scripts and create and use the new extension.

1. An Athena account.
2. Although you can work in the /tmp directory of your workstation, if you want to save your work you need 1MB free space in your Athena home directory.
3. A working knowledge of basic Athena commands for moving between directories, deleting files, editing text files, and working with X displays.
4. Some knowledge of watersheds and DEMs
5. Experience with customizing the Arcview interface.
6. Some experience with Avenue including debugging and compiling scripts.
7. Ability to add extension such as Spatial Analyst to Arcview projects.

You will need to copy these two project files from the /mit/gis/programs/avenue directory  after you the gis directory ( attach gis )

• extension.apr 
• readext.apr

There are three essential scripts that are included in the extenion.apr project file. These are MakeExtension, Install, and Unstall. The MakeExtension script assembles the pieces of the extension and packs it in a folder. The Install scripts tells Arcview how to load the extension and the Uninstall script tells Arcview how to unload the extension. 

You create the extension by running the MakeExtension script. You never run the Install or Uninstall scripts. These are used indirectly when the extension is loaded. 

Open the project file using Arcview and look the the MakeExtension, Install, and Uninstall script. 

The code is directly from the extension.apr file. Comments in this version are expanded from the project version.

The MakeExtension creates the framework for creating the extension and adds the required objects to the extension. In this example, we add scripts, a button, and a tool to the extension. 

MyHydro = Extension.Make("/tmp/MyHydro.avx".AsFileName, "Local Hydro Operations", av.FindScript("Install"), av.FindScript("UnInstall"), {})

The extension object is called MyHydro. It is created with the Make request to the Extension object. There are five arguments to the request: 

1. "/tmp/MyHydro.avx".AsFileName - the actual file name and location of the extension file (always use an .avx extension). Since you are passing a string, you have to add the .AsFileName request since a filename is expected.
2. "Local Hydro Operations" the name of the extension.
3. av.FindScript("Install") - the name of the install script. Arcview uses this to determine what widgets to install and where to install them.
4. av.FindScript("UnInstall") - the name of the uninstall script.
5. {} - any dependencies such as other extensions that need to be loaded for this script to work.

MyHydro.SetAbout("Hydro - finding the downstream and downslope path of water on a DEM using a flow accumulation grid") 

You can add aversion number assuming you will be distributing new versions as you develop better code. 

MyHydro.SetExtVersion(1.0)

' In this block, you find all of the related scripts. Note the convention: each extension script starts with "_MyHydro." Checking for class = SEd looks only for scripts among the projects documents which include views and tables as well as scripts. 

• for each d in av.GetProject.GetDocs 
• if (d.Is(SEd) AND (d.GetName.Left("_MyHydro".count + 1) = "_MyHydro.")) then 
• MyHydro.Add(d.GetScript)
• end
• end

MyHydro.Add(av.FindGui("View").GetButtonBar.GetControls.Get(1))

Get the one tool associated with a relevant script and add it to the extension. The same counting method that applies to buttons also applies here. 

MyHydro.Add(av.FindGui("View").GetToolBar.GetControls.Get(1))

Sending the commit request to the your extension object writes out all of the information to a file. 

MyHydro.commit

End the script with a return. 

return nil

This script is responsible for putting the buttons, tools, and menu items into the project when the extension is loaded. The scripts are added to the project automatically. The Install script is not run by the person who creates the extension or by the user of the extension. It is run by Arcview when the extension is loaded. 

The first task is to check to see that a project is open.  Don't install if there is no current project. 

if (av.GetProject = nil) then
 return nil
end

Find the GUI associated with Views. It is always called "View" unless the user customized the view GUI. 

viewGUI = Av.GetProject.FindGUI("View")
if (viewGUI = nil) then
 return nil
end

Retrieve the buttons from the extension and add to the buttonbar.  The count variable tells Arcview where in the button bar to put the new button. This set up as a loop so that you could add multiple buttons and add them in a loop.  The 4 as the starting point in the for each loop indicates that this is the 6th item in the extension.  There are 4 scripts that where add first in the MakeExtension script, occupying positions 0, 1, 2, and 4. 

bb = viewGUI.GetButtonBar
count = 0
for each i in 4.. 4
 bb.add(Self.Get(i),count)
 count = count + 1
end

Retrieve the tools from the extension and add to the toolbar.  The count variable is used in the same way as for the button bar.  The for each loops starts at 5 since the button bar for each ended at 4. 

tb = viewGUI.GetToolBar
count = 0
for each i in 5 .. 5
 tb.add(Self.Get(i),count)
 count = count + 1
end

Return control to the extension loader. 

return nil

This script is responsible for removing the buttons, tools, and menu items into the project when the extension is removed. The scripts are removed from the project automatically. Like the Install script, the Uninstall script is not run by the person who creates the extension or by the user of the extension. It is run by Arcview when the extension is removed. 

As with Install, you can't remove an extension if there is no active project. 

if (av.GetProject = nil) then
 return nil
end

Nor can you remove if the project is being closed.

if (Av.GetProject.IsClosing) then
 return nil
end

Find the View GUI 

ViewGUI = Av.FindGUI("View")

Remove the button(s).  The "for each" counter is the same as for the install script. You don't have to identify where the buttons are on the buttonbar as you needed to when you placed them. 

if (viewGUI <> nil) then
 

 for each i in 5 .. 5
   viewGUI.GetButtonBar.Remove(self.Get(i))
 end ' for each loop

Remove the button(s).  The comments for removing buttons also applies here. 

 for each i in 6 .. 6
  viewGUI.GetToolBar.Remove(self.Get(i))
 end

end ' if ViewGUI <> nil

Return control to the extension unloader. 

return nil 

The Extension file is not created until you run the MakeExtension script. Simply run the scrip using either the run icon when the script is open or click on the RUN button when the MakeExtension script is highlighted in the list of scripts. 

Keep this Arcview session open. 

Result: look for the file in the directory where you intended to store it. 

You will need to test the extension in another project. You will have obscure probelms if you try to open the extension in the same instance of Arcview that you used to look at extension.apr project. Instead, open the readext.apr profile in Arcview. 

arcview readext.apr

You should run the script while it is open.  Either click on the Run button in the buttonbar or click on the Run  button in the project window.

From the Athena prompt, attach the /mit/gis/data/grids directory. Use the File->Extensions menu choice and select the new Local Hydro Operations extension. Check to see that the Spatial Analyst extension is checked. Check it, if it isn't checked already, and press the OK button to activate your choices. You should see a new button and a new tool when View1 is the active document. The new button creates the Flow Direction and Flow Accumulation grids from the DEM. The Use the View->Add Themes menu choice to add the ashfield_nos DEM in the /mit/gis/data/grids directory. 

Use the new button to create the Flow Direction and Flow Accumulation grids. Remember to make the DEM the active theme (remember the difference between active and visisble - the checkbox makes it visible, clicking on the legend entry will make the theme active). 

Use the new tool to create the downstream grid. Remember to make the Flow Accumulation grid the active grid. Look at the table that is created. You will use it in the next step. 

Keep this Arcview session open. 

You will use the code in Exercise 4 from the Script writing exercises. 

Open extension.apr file in Arcview. 

Open the Script section of the project by clicking on the Script icon in the extension.apr project window. Press the new button to open a new script window. Copy and paste the code into new script window. Compile the script. Now use the Script->Properties menu choice to change the name of the script. You change the name by changing Script1 to _MyHydro.MakeEventTheme. An Event Theme is essentially a geodatabase with point topology. 

Now open the the Customize menu bydouble clicking on the buttonbar or toolbar but not on any of the buttons or tools. Change the Type to View and Category to Buttons on this menu. Select the Flow Direction/Flow Accumulation button by clicking on it. Press the New button to create a new button. A new blank button should appear to the right of the Flow Direction/Flow Accumulation button. 

Add the new _MyHydro.MakeEventTheme as the click response by clicking on the Click entry and select the script from the list of scripts. Add a help item by clicking on the Help entry and adding this text "Makes an event theme from the table '_tablename'". This is the table that is created when you run the downstream tool. 

Now you have to make changes to the three scripts required for making the extension: MakeExtension, Install, and Uninstall. 

MakeExtension

You don't need to account for the script since the script will be automatically added since it has the same prefix as the other extension scripts. You do have to add an additional line following the 

MyHydro.Add(av.FindGui("View").GetButtonBar.GetControls.Get(1) 

line. The new line is identical except you change Get(1) to Get(2). Remember that the buttonbar acts as a list. The new button is the third button so it is added as number 2 in the list which starts at zero. 

You should add all buttons together and all tools together since this will make install and uninstalling the widgets much easier. 

Install

You need to account for the new script and button here.

Change this code:

• bb = viewGUI.GetButtonBar
• count = 0
• for each i in 4 .. 4 
• bb.add(Self.Get(i),count)
• count = count + 1
• end

And change this code:

• bb = viewGUI.GetToolBar
• count = 0
• for each i in 5 .. 5 
• tb.add(Self.Get(i),count)
• count = count + 1
• end

Uninstall

You also need to account for the new script and button here.

Change this code:

• for each i in 4 .. 4 
• viewGUI.GetButtonBar.Remove(self.Get(i))
• end for each i in 5 .. 5 
• viewGUI.GetToolBar.Remove(self.Get(i))
• end 

Before you create the new extension, unload the Local Hydro extension from the readext.apr project. You do this by opening the Extension menu (File->Extension menu choice), unchecking the Local Hydro extension, and then pressing the OK button. 

You will need to compile the MakeExtension, Install, and Uninstall scripts after you made the changes to them. Run the MakeExtension script. This creates a new file in the /tmp directory. 

Go back to the readext.apr project window. Add the Local Hydro extension. You do this by opening the Extenion menu (File->Extension menu choice), checking the Local Hydro extension, and then pressing the OK button. 

Check that you have the "_tablename" table then press the button and look for the new theme in the view and the legend. 

Before saving your project, you should unload the extension. Since the extension is located in the /tmp directory on the machine your are using, you will not have access to it if you save the project in your Athena account and you try to open the projects in the future. 

Since both of these projects wrote all temporary files into the /tmp directory there should not be any stray files, grids, or coverages to delete.