Filter

Summary

The Filter object limits 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 the following:

• A filter 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 provides a parameter value (rather than choosing a value from the list or file browser), the value is compared to the filter. If the user provides an invalid value (a numeric field instead of a text field, for example), a warning or error occurs.
• Because values are compared to the filter by internal validation, you don't need to program custom validation in the ToolValidator class.

You can specify filters by doing either of the following :

• 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.
• Set the values programmatically in a ToolValidator class (examples are below). This provides 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, but it's 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)	Specifies the values or the constraints of the filter. The type of values depend on the type property.	String
type (Read and Write)	Specifies the type of filter. ValueList—A list of string or numeric values used with String, Long, Double, Boolean, Linear Unit, Areal Unit, and Time Unit data types. For String or numeric filters, provide a list of values, and only those values will be considered valid and shown in a drop-down list on the tool dialog box. For Linear Unit, Areal Unit, and Time Unit data types, provide a list of unit keyword strings, and only values using those units will be considered valid and shown in the unit drop-down list on the tool dialog box. Range—A minimum and maximum value used with Long, Double, Linear Unit, Areal Unit, and Time Unit data types. For Long and Double filters, provide a list with two items: the minimum and maximum value. Only numbers specified between the minimum and maximum will be considered valid. For Linear Unit, Areal Unit, and Time Unit Range filters, provide a list with two items: the minimum and maximum value including a unit, for example, ["1 Meters", "100 Meters"]. FeatureClass—A list of allowable feature class types. Valid values are Point, Multipoint, Polyline, Polygon, MultiPatch, Annotation, and Dimension. More than one value can be supplied to the filter. File—A list of file suffixes, for example, [".txt", ".xml"]. Field—A list of allowable field types specified by the Short, Long, Single, Double, Text, Date, OID, Geometry, Blob, Raster, GUID, GlobalID, and XML values. More than one value can be supplied to the filter. Workspace—A list of allowable workspace types specified by the FileSystem, LocalDatabase, and RemoteDatabase values. More than one value can be supplied to the filter.	String

Code sample

Filter example 1

The following is 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", "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

The following is an example in which the value list filter in the second parameter changes based on the shape type 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

Filter example 3

The following is an example in which the value list filter in the third parameter is populated by the attributes from the field selected in the second parameter.

def updateParameters(self):
    # Update the value list filter in the third parameter based on the
	   # attributes of the field selected in the second parameter

    if self.params[1].value:
        fc = self.params[0].value
        field = self.params[1].valueAsText
        values = self.params[2].filter
        attribute_values = [row[0] for row in arcpy.da.SearchCursor(fc, [field])]
        unique_attributes = set(attribute_values)
        values.list = [int(value) for value in unique_attributes]
    return