Filter

Summary

The filter object allows you to specify the choices available for a parameter.

Discussion

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 text fields. A filter does three jobs:

• A filter only presents the user with valid choices when browsing for data. If you set a filter for point feature classes, only point feature classes are shown when the user browses for data. If you set a filter for text fields, the drop-down list of fields only shows text fields.
• If a user types a parameter value (rather than choosing a value from the list or file browser), the value is compared to the filter. If the user enters an invalid value (a numeric field instead of a text field, for example), a warning or error occurs.
• Because values are compared to their filter by internal validation, you don't have to program custom validation in the ToolValidator class.

There are two ways to specify filters:

• On the Parameters tab of the tool's properties dialog box, click the parameter, click the cell next to Filter, and choose the filter type from the drop-down list. After choosing the filter type, a dialog box appears where you specify the values for the filter.
• You can set the values programmatically in a ToolValidator class (examples are below). This provides some customization options that are not possible using the tool's properties dialog box, including defining dynamic filters based on other parameter values, filters for composite data types, and multiple filter types on the same parameter. Geoprocessing creates filters automatically for parameters of type string, long, double, feature class, file, field, and workspace. If you don't choose a filter on the tool's properties dialog box, a filter is still associated with the parameter—it's just empty. An empty filter is the same as 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

Property	Explanation	Data Type
list (Read and Write)	If you do not want to filter values, set the list property to an empty list. The data type specified depends on the filter type (ValueList, Range, FeatureClass, File, Field, and Workspace).	String
type (Read and Write)	The type of filter (ValueList, Range, FeatureClass, File, Field, and Workspace). You can set the type of filter when using Long, Double, Linear Unit, Areal Unit, and Time Unit parameters. For other types of parameters, there is only one valid type of filter, so setting the type on these parameters is ignored. If you do not want to filter values, set the list property to an empty list.	String

Code sample

Filter example

An example of dynamically updating a value list filter containing a choice list of keywords. If the user enters "OLD_FORMAT" in the second parameter, the third parameter contains "POINT", "LINE", and "POLYGON". If "NEW_FORMAT" is entered, the third parameter contains three additional choices.

import arcpy

class ToolValidator:
    def __init__(self):
        self.params = arcpy.GetParameterInfo()

    def initializeParameters(self):
        return

    def updateParameters(self):
        # Provide default values for "file format type" and
        #  "feature type in file"
        if not self.params[1].altered:
            self.params[1].value = "OLD_FORMAT"
        if not self.params[2].altered:
            self.params[2].value = "POINT"

        # Update the value list filter of the "feature type in file"
        # parameter depending on the type of file (old vs. new format)
        # input
        if self.params[1].value == "OLD_FORMAT":
            self.params[2].filter.list = ["POINT", "LINE", "POLYGON"]
        elif self.params[1].value == "NEW_FORMAT":
            self.params[2].filter.list = ["POINT", "LINE", "POLYGON",
                                          "POINT_WITH_ANNO",
                                          "LINE_WITH_ANNO",
                                          "POLYGON_WITH_ANNO"]

        return

    def updateMessages(self):
        return

Filter example 2

An example where the value list filter in the second parameter changes based on the shape type found in the first parameter, a feature class.

def updateParameters(self):
    # Update the value list filter in the second parameter based
    # on the shape type in the first parameter
    string_filter = self.params[1].filter
    feature_class = self.params[0].value
    if feature_class:
        shape_type = arcpy.Describe(feature_class).shapeType
        if shape_type in ["Point", "Multipoint"]:
            string_filter.list = ["RED", "GREEN", "BLUE"]
        elif shape_type == "Polygon":
            string_filter.list = ["WHITE", "GRAY", "BLACK"]
        else:
            string_filter.list = ["ORANGE", "INDIGO", "VIOLET"]
    else:
        string_filter.list = ["RED", "GREEN", "BLUE"]

    # If the user hasn't changed the keyword value, set it to the
    # default value (first value in the value list filter).
    if not self.params[1].altered:
        self.params[1].value = string_filter.list[0]

    return