Programming a ToolValidator class
Release 9.3 Last modified June 3, 2010	Print all topics in : "Creating script tools"

Note: This topic was updated for 9.3.1.

For an overview of the ToolValidator class and use of parameter methods, see Customizing script tool behavior.

Accessing the tool parameters

def __init__(self):
  import arcgisscripting as ARC
  self.GP = ARC.create(9.3)
  self.params = self.GP.getParameterInfo()

  import arcgisscripting
  gp = arcgisscripting.create()
  params = gp.getParameterInfo()

Order of parameters

NOTE: The list of parameters is 0-based, so the first parameter is at position zero in the list. So, to access the third parameter

p3 = self.params[2]

Methods

Properties

Property name	Read/Write	Value(s)	Description
Name		String	Parameter name as defined on the Parameters tab of the tool's properties.
Direction		String: "nput, Output	Input/Output direction of the parameter as defined on the Parameters tab of the tool's properties.
Datatype		String	Data type as defined on the Parameters tab of the tool's properties.
ParameterType		String: Required, Optional, Derived	Type as defined on the Parameters tab of the tool's properties.
ParameterDependencies		Python List	A list of indexes of each dependent parameter.
Value		Value object	The value of the parameter.
DefaultEnvironmentName		String	Environment as defined on the Parameters tab of the tool's properties.
Enabled		Boolean	False if the parameter is dimmed (unavailable).
Altered		Boolean	True if the user has modified the value.
HasBeenValidated		Boolean	True if the internal validation routine has checked the parameter.
Category		String	The category of the parameter.
Schema		GP Schema object	The schema of the output dataset.
Filter		GP Filter object	The filter to apply to values in the parameter.
Symbology		String	The pathname to a layer file (.lyr) used for drawing the output.
Message		String	The message to be displayed to the user. See SetErrorMessage() and SetWarningMessage() above.

ToolValidator properties versus script tool properties

ParameterDependencies

• For an output dataset parameter whose type is Derived, the dependency is the index of the parameter from which the output is to be derived.
  
• For certain input data types, the dependency is the index of the parameter containing the information used by the control, as shown in the table below.
  

def initializeParameters(self):
  # Set the dependencies for the output and its schema properties
  #
  self.params[2].ParameterDependencies = [0, 1]

Value

  # If the option to use a weights file is selected, enable the 
  #   parameter for specifying the file, otherwise disable it
  #
  if self.params[3].Value == "Get Spatial Weights From File":
      self.params[8].Enabled = True
  else:
      self.params[8].Enabled = False

  if str(self.params[0].Value) == "E:\data\example.gdb\roads":

NOTE: When using the geoprocessing describe method, never use the string representation of the value.

  desc = self.GP.describe(str(self.params[0].Value))

  desc = self.GP.describe(self.params[0].Value)

NOTE: Don't use geoprocessing object methods that take a catalog path, such as ListFields, in ToolValidator. The dataset may not exist when your tool is validated in ModelBuilder, and the method may fail. (In the case of ListFields, you can use the Describe Fields method instead.)

  fc = self.params[0].Value
  shapetype = self.GP.Describe(fc).ShapeType.lower()
    if shapetype == "point" or shapetype == "multipoint":

Altered

  if not self.params[2].Altered:
      self.params[2].Value = "POINT"

HasBeenValidated

# Set the default distance threshold to 1/100 of the larger of the width
#  or height of the extent of the input features. Do not set if there is no 
#  input dataset yet, or if the input features have already been validated,
#  or the user has set a specific distance (Altered is true).
# 
import string
if self.params[0].Value and not self.params[0].HasBeenValidated:
  if not self.params[6].Altered: 
    extent = self.GP.Describe(self.params[0].Value).Extent
    width = extent.Width
    height = extent.Height
    if width > height:
      self.params[6].Value = width / 100
    else:
      self.params[6].Value = height / 100

Category

  def initializeParameters(self):
    self.params[4].Category = "Options"
    self.params[5].Category = "Options"
    self.params[6].Category = "Advanced"
    self.params[7].Category = "Advanced"

Symbology

Every output parameter of type feature class, table, raster, or workspace has a schema object. Only output feature classes, tables, rasters, and workspaces have a schema—other types do not. The schema object is created for you by geoprocessing. You access this schema through the parameter object and set the rules for describing the output of your tool. After you set the schema rules, and on return from the ToolValidator class, the geoprocessing internal validation code examines the rules you set and updates the description of the output.

To review, the flow of control is as follows:

1. When the tool dialog is first opened, initializeParameters() is called. You set up the static rules (rules that don't change based on user input) for describing the output. No output description is created at this time since the user hasn't specified values for any of the parameters (unless you've provided default values).
   
2. Once the user interacts with the tool dialog in any way, updateParameters() is called.
   
3. updateParameters() can modify the schema object to account for dynamic behavior that can't be determined from the parameter dependencies (such as adding a new field like Add Field).
   
4. After returning from updateParameters(), the internal validation routines are called and the rules found in the schema object are applied to update the description of the output data.
   
5. updateMessages() is then called. You can examine the warning and error messages that internal validation may have created and modify them or add your own custom warning and error messages.
   

Using FirstDependency

  # Set the dependencies for the output and its schema properties
  #
  self.params[2].ParameterDependencies = [0, 1]

Case insensitive

Type

Clone

• If parameter.ParameterType is Derived, an exact copy is made. This is the behavior of the Add Field tool.
  
• If parameter.ParameterType is Required, an exact copy is also made, but the catalog path to the dataset is changed. Catalog paths consist of two parts: the workspace and the base name. For example
  

E:\Data\TestData\netcity.gdb\infrastructure\roads



Workspace =E:\Data\TestData\netcity.gdb\infrastructure and Base name = roads

The rules used to construct new output names are as follows:



• The base name is the same as the base name of the first input parameter containing a dataset (not the first dependency but the first parameter) appended with the name of the script tool (for example, roads_MyTool).
  
• The workspace is set to the scratch workspace environment setting. If this is empty, the current workspace environment setting is used. If this is empty, the workspace of the first input parameter containing a dataset is used. If this workspace is read-only, then the system temp directory is used.
  

  def initializeParameters(self):
    # Set the dependencies for the output and its schema properties
    #  The two input parameters are feature classes.
    #
    self.params[2].ParameterDependencies = [0, 1]

    # Feature type, geometry type, and fields all come from the first 
    #  dependency (parameter 0), the input features
    #
    self.params[2].Schema.FeatureTypeRule = "FirstDependency"
    self.params[2].Schema.GeometryTypeRule = "FirstDependency"
    self.params[2].Schema.FieldsRule = "FirstDependency"

    # The extent of the output is the intersection of the input features 
    #  and the clip features (parameter 1)
    #
    self.params[2].Schema.ExtentRule = "Intersection"

    return

  def initializeParameters(self):
    # Set the dependencies for the output and its schema properties
    #  The two input parameters are feature classes.
    #
    self.params[2].ParameterDependencies = [0, 1]
    self.params[2].Schema.Clone = True
    return

  def updateParameters(self):
    # The only property of the clone that changes is that the extent 
    #  of the output is the intersection of the input features 
    #  and the clip features (parameter 1)
    #
    self.params[2].Schema.ExtentRule = "Intersection"
    return

FeatureTypeRule

FeatureType

GeometryTypeRule

Point and Multipoint = 0

Polyline = 1

Polygon = 2

GeometryType

ExtentRule

    # The extent of the output is the intersection of the input features 
    #  and the clip features (the dependent parameters)
    #
    self.params[2].Schema.ExtentRule = "Intersection"

Extent

self.params[2].Schema.ExtentRule = "AsSpecified"
self.params[2].Schema.Extent = "123.32 435.8 987.3 567.9"

xmin = 123.32
ymin = 435.8
xmax = 987.3
ext = [xmin, ymin, xmax, 567.9]
self.params[2].Schema.Extent = ext

FieldsRule

  def initializeParameters(self):
    # Set the dependencies for the output and its schema properties
    #  The two input parameters are feature classes.
    #
    self.params[2].ParameterDependencies = [0, 1]

    # Feature type, geometry type, and fields all come from the first 
    #  dependency (parameter 0), the input features
    #
    self.params[2].Schema.FeatureTypeRule = "FirstDependency"
    self.params[2].Schema.GeometryTypeRule = "FirstDependency"
    self.params[2].Schema.FieldsRule = "FirstDependency"

    # The extent of the output is the intersection of the input features 
    #  and the clip features (parameter 1)
    #
    self.params[2].Schema.ExtentRule = "Intersection"

    return

AdditionalFields

CellSizeRule

CellSize

RasterRule

RasterFormatRule

AdditionalChildren

inFeatures = self.params[0].Value

class ToolValidator:
  def __init__(self):
    import arcgisscripting as ARC
    self.GP = ARC.create(9.3)
    self.params = self.GP.getparameterinfo()

  def initializeParameters(self):
    self.params[3].ParameterDependencies = [2]  # input workspace
    self.params[3].Schema.Clone = True  # Copy all existing contents to output
    return

  def updateParameters(self):
    inFC = self.params[0].Value     # input feature class
    inTable = self.params[1].Value  # input table
    inWS = self.params[2].Value     # input workspace
    if inFC and inTable and inWS:
      self.params[3].Schema.AdditionalChildren = [inFC, inTable]
    return

  children = []    # New empty list
  children.append(inFC)
  children.append(inTable)
  children.append(["polygon", "SummaryPolygon"])
  self.params[3].Schema.AdditionalChildren = children

  # Create a field object with the name "Category" and type "Long"
  #
  newField = self.GP.CreateObject("Field")
  newField.Name = "Category"
  newField.Type = "Long"

  # Describe the input feature class in order to get its list of fields. The 9.3
  #  version of the geoprocessing object returns fields in a Python list, unlike
  #  previous versions, which returned fields in an enumerator.
  #
  desc = self.GP.Describe(inFC)
  fieldList = desc.Fields

  # Add the new field to the list
  #
  fieldList.append(newField)

  # Create a new child based on the input feature class, but with the 
  #  additional field added
  #
   newChild = [desc.ShapeType, desc.CatalogPath, fieldList,                   desc.Extent, desc.SpatialReference]

  # Now create our list of children and add to the schema
  #
  children = []
  children.append(newChild)
  children.append(inTable)
  children.append(["polygon", "SummaryPolygon"])
  self.params[3].Schema.AdditionalChildren = children

# 0 - input features (multivalue)
# 1 - input workspace
# 2 - derived workspace

class ToolValidator:
  def __init__(self):
    import arcgisscripting as ARC
    self.GP = ARC.create(9.3)
    self.params = self.GP.getparameterinfo()

  def initializeParameters(self):
    self.params[2].ParameterDependencies = [1]
    self.params[2].Schema.Clone = True
    return

  def updateParameters(self):
    inVT = self.params[0].Value   # multivalue ValueTable
    inWS = self.params[1].Value   # WorkSpace

    # Add each feature class to the output workspace. In addition,
    #  add a new field "ProjectID" to each feature class
    #
    if inVT and inWS:
        rowCount = inVT.rowcount  # Number of rows in the MultiValue table
        children = []
        newField = self.GP.CreateObject("Field")
        newField.Name = "ProjectID"
        newField.Type = "Long"
        for row in range(0, rowCount):
            value = inVT.GetValue(row, 0)
            if value:
                d = self.GP.Describe(value)
                fieldList = d.Fields

                # Note -- not checking if field already exists
                #
                fieldList.append(newField)

                # Create new child with additional ProjectID field and
                #  add child to list of children
                #
                child = [d.shapetype, d.catalogpath, fieldList]
                children.append(child)            

        self.params[2].Schema.AdditionalChildren = children
    return

  def updateMessages(self):
    return

The filter object allows you to specify the choices available to the user for a parameter. For example, you can set up a field filter that limits choices to just text fields. A filter does three jobs.

• A filter only presents the user with valid choices when browsing for data. If you set your filter for point feature classes, only point feature classes are shown when the user browses for data. If you set your filter for text fields, the drop-down list of fields only shows text fields.
  
• If a user types in a parameter value (rather than picking a value from the list or file browser), the value is checked against the filter. If the user enters an invalid value (a numeric field instead of a text field, for example), a warning or error is automatically given.
  
• Because values are checked against their filter by internal validation, a filter frees you from having to program your own custom validation in the Toolvalidator class.
  

• On the Parameters tab of the tool's properties dialog, click the parameter, then click the cell next to Filter and choose the filter type from the drop-down list. After choosing the filter type, a dialog box opens where you specify the values for the filter.
  


• You can set the values programmatically in ToolValidator (examples are given below). Geoprocessing creates filters automatically for parameters of type string, long, double, feature class, file, field, and workspace. Even if you don't choose a filter on the tool's properties dialog, there is still a filter associated with the parameter—it's just empty. An empty filter is the same as having no filter. By adding values to an empty filter, you activate the filter and the user's choices are limited by the contents of the filter.
  

Properties

ValueList

  def initializeParameters(self):
    # Set the fixed list of "file format type" parameter choices and its
    #  default value
    #
    self.params[1].Filter.List = ["OLD_FORMAT", "NEW_FORMAT"]
    self.params[1].Value = "OLD_FORMAT"
    return

NOTE: The list of values you provide in ToolValidator always replaces the values set in the tool's properties dialog. This behavior allows you to update the values based on other parameters.

  def updateParameters(self):
    # Update the value list filter of the "feature type in file" parameter 
    #   depending on the "file format type" parameter.
    #
    if self.params[1].Value.upper() == "OLD_FORMAT":
      self.params[2].Filter.List = ["POINT", "LINE", "POLYGON"]
    elif self.params[1].Value.upper() == "NEW_FORMAT":
      self.params[2].Filter.List = ["POINT", "LINE", "POLYGON",                                     "POINT_WITH_ANNO",                                     "LINE_WITH_ANNO",                                     "POLYGON_WITH_ANNO"]

    # Provide default value for "feature type in file" parameter
    #
    if not self.params[2].Altered:
      self.params[2].Value = "POINT"

  # Set filter for a Long parameter
  #
  self.params[7].Filter.List = [10, 20, 30, 40, 50]

  # Set filter for a Double parameter
  #
  self.params[8].Filter.List = [10.0, 12.5, 15.0]

  def initializeParameters(self):
    # Set the Boolean choice for including or excluding angles
    #
    self.params[6].Filter.List = ["ANGLE", "NO_ANGLE"]

    # Set the default value to false (no angle)
    #
    self.params[6].Value = "NO_ANGLE"
    return

  def updateParameters(self):
    # Enable angle format parameter if user wants angles
    #
    if self.params[6].Value.upper() == "ANGLE":
      self.params[7].Enabled = True

Range

  def initializeParameters(self)
    # Utility values must be between -10 and 10.
    #
    self.params[7].Filter.List = [-10, 10]

Setting filter type on long and double parameters

  def initializeParameters(self)
    # Set the 'score' value parameters to a range filter
    #
    self.params[7].Filter.Type = "Range"
    self.params[7].Filter.List = [-10, 10]

FeatureClass

  def updateParameters(self):
    # Set the input feature type of the second parameter based
    #  on the feature type of the first parameter.
    #
    if self.params[0].Value:
      desc = self.GP.describe(self.params[0].Value)
      feature_type = desc.ShapeType.lower()

      if feature_type == "polygon":
        self.params[1].Filter.List = ["point", "multipoint"]

      elif feature_type == "polyline":
        self.params[1].Filter.List = ["polygon"]

      elif feature_type == "point" or            feature_type == "multipoint":
        self.params[1].Filter.List = ["polyline"]

      else:
        self.params[1].Filter.List = []

    return

File

  def initializeParameters(self)
    # Set the input file type to our recognized options file suffixes
    #
    self.params[0].Filter.List = ["opt56", "opt57", "globalopt"]
    return

Field

  self.params[1].Filter.List = ["short", "long", "float", "text"]
  self.params[1].Filter.List = ["smallinteger", "integer", "single", "string"]

  self.params[1].Filter.List = ["short", "long"]
  # 
  if self.params[1].Filter.List[0].lower() == "smallinteger":
    # do something

  def initializeParameters(self):
    self.params[1].Filter.List = ["short", "long", "float", "double"]
    return

  def updateParameters(self):
    if self.params[0].Value and not self.params[1].Altered:
        self.params[1].Value = ""
        desc = self.GP.Describe(self.params[0].Value)
        fields = desc.Fields

        # Set default to the first field that matches our filter
        #
        for field in fields:
            fType = field.type.lower()
            if fType == "smallinteger" or                fType == "integer" or                fType == "single" or                fType == "double":
                self.params[1].Value = field.Name
                break
    return

NOTE: Do not use the geoprocessing ListFields method in ToolValidator. Instead, use the Describe method as shown above.

Workspace

• FileSystem
  
A system folder used to store shapefiles, ArcInfo coverages, INFO tables, and grids


• LocalDatabase
  
A personal or file geodatabase


• RemoteDatabase
  
An ArcSDE database connection