Customizing a tool dialog


Summary
This topic describes how to customize a tool dialog using the methods on the GPParameter class. The parameters in the tool dialog can be categorized to save screen space, and they can be enabled or disabled on the fly. The display order of the parameters can be changed as well.

In this topic

About customizing a tool dialog

A geoprocessing tool dialog is the user interface for a custom function tool. The input and output parameters of the tool as well as the behavior of the tool at run time are defined in the tool dialog. Tool dialog boxes reside in ArcToolbox and can be consumed by the ArcMap, ArcCatalog, ArcGlobe, and ArcScene applications. A GPParameter class corresponds to an input or an output parameter of the custom geoprocessing function tool represented by the tool dialog. The properties of the GPParameter class for a custom geoprocessing function tool are defined in the BaseGeoprocessingTool.getParameterInfo() method and can be altered by the BaseGeoprocessingTool.updateParameters() method. For more information on creating custom geoprocessing tools, see Creating a custom function tool class.
The GPParameter methods—setCategory(), setEnabled(), and setDisplayOrder()—allow you to customize the parameters in the tool dialog.

Categorizing parameters

A custom geoprocessing tool can have multiple input and output parameters. The parameters can be required or optional.
The setCategory() method of the GPParameter object allows you to categorize parameters in a tool dialog. Parameters that belong to the same category are listed in a text box that is expandable and collapsible in the tool dialog box. The Category property can hide optional parameters of a geoprocessing tool.
If your custom geoprocessing function tool has multiple input and output parameters, categorize them to save screen space and to focus on the primary arguments. The following screen shot shows an example of categorizing parameters:
The following code snippet shows how to set the Category property of a custom geoprocessing tool:
[Java] 
//Code snippet to categorize parameters.

public class CustomGPFunctionTool extends BaseGeoprocessing Tool{

    public IArray getParameterInfo()throws IOException, AutomationException{

        IArray parameterArray = new Array();

        GPParameter parameter = new GPParameter();
        parameter.setName("Parameter1");
        parameter.setDisplayName("Parameter 1");
        parameter.setDirection
            (esriGPParameterDirection.esriGPParameterDirectionInput);
        parameter.setCategory("Input Parameters");
        parameterArray.add(parameter);

        parameter = new GPParameter();
        parameter.setName("Parameter2");
        parameter.setDisplayName("Parameter 2");
        parameter.setDirection
            (esriGPParameterDirection.esriGPParameterDirectionInput);
        parameter.setCategory("Input Parameters");
        parameterArray.add(parameter);

        parameter = new GPParameter();
        parameter.setName("Parameter3");
        parameter.setDisplayName("Parameter 3");
        parameter.setDirection
            (esriGPParameterDirection.esriGPParameterDirectionInput);
        parameter.setCategory("Input Parameters");
        parameterArray.add(parameter);

        //Create output parameters.
    }
    //Implement other methods.
}
The previous code creates a tool dialog similar to the following screen shots. The first screen shot shows the Input Parameters category collapsed. The second screen shot shows the Input Parameters category expanded.

Enabling and disabling parameters

A parameter can be enabled (made available) or disabled (made unavailable). The following screen shot shows enabled and disabled parameter text boxes in a tool dialog:
You can set the initial state of a parameter as enabled or disabled using the GPParameter.setEnabled() method when you create the parameter with the getParameterInfo() method. Alternatively, you can enable or disable the parameter based on the value of other parameters in the implementation of the updateParameters() method.
The following code snippet of the Add Field tool, which adds a new field to the specified feature class, shows how to enable the Field Length parameter based on the value of the Field Type parameter using the updateParameters() method. The Field Length parameter is initially disabled by the getParameterInfo() method, then enabled by the updateParameters() method when the value of the Field Type parameter is designated as type Text.
[Java] 
public IArray getParameterInfo()throws IOException, AutomationException{
    IArray parameters = new Array();
    GPParameter parameter;

    //Define parameters.

    //Parameter 1: Input feature
    parameter = new GPParameter();
    parameter.setName("in_Feature");
    parameter.setDisplayName("Input Feature");
    parameter.setDirection(esriGPParameterDirection.esriGPParameterDirectionInput);
    parameter.setParameterType(esriGPParameterType.esriGPParameterTypeRequired);
    parameter.setDataTypeByRef(new DEFeatureClassType());
    parameter.setValueByRef(new DEFeatureClass());
    parameters.add(parameter);

    //Parameter 2: Field name 
    parameter = new GPParameter();
    parameter.setName("in_fieldName");
    parameter.setDisplayName("Field Name");
    parameter.setDirection(esriGPParameterDirection.esriGPParameterDirectionInput);
    parameter.setParameterType(esriGPParameterType.esriGPParameterTypeRequired);
    parameter.setDataTypeByRef(new GPStringType());
    parameter.setValueByRef(new GPString());
    parameters.add(parameter);

    //Parameter 3: Field type
    parameter = new GPParameter();
    parameter.setName("in_fieldType");
    parameter.setDisplayName("Field Type");
    parameter.setDirection(esriGPParameterDirection.esriGPParameterDirectionInput);
    parameter.setParameterType(esriGPParameterType.esriGPParameterTypeRequired);
    parameter.setDataTypeByRef(new GPStringType());
    parameter.setValueByRef(new GPString());

    //Define domain values for the string.
    IGPCodedValueDomain domain = new GPCodedValueDomain();
    domain.addStringCode("TEXT", "TEXT");
    domain.addStringCode("LONG", "LONG");
    domain.addStringCode("DOUBLE", "DOUBLE");
    domain.addStringCode("SHORT", "SHORT");
    domain.addStringCode("FLOAT", "FLOAT");
    parameter.setDomainByRef((IGPDomain)domain);
    parameters.add(parameter);

    //Parameter 4: Field length
    parameter = new GPParameter();
    parameter.setName("in_fieldLength");
    parameter.setDisplayName("Field Length");
    parameter.setDirection(esriGPParameterDirection.esriGPParameterDirectionInput);
    parameter.setParameterType(esriGPParameterType.esriGPParameterTypeOptional);
    parameter.setDataTypeByRef(new GPStringType());
    GPString fieldType = new GPString();
    parameter.setValueByRef(fieldType);

    //The parameter is initially defined as disabled.
    parameter.setEnabled(false);
    parameters.add(parameter);

    return parameters;
}

public void updateParameters(IArray paramvalues, IGPEnvironmentManager envMgr){
    try{

        IGPParameter3 in_fieldType = (IGPParameter3)paramvalues.getElement(2);
        //If the FieldType parameter value is altered by the user,

        if (in_fieldType.isAltered()){
            //get the parameter value of FieldType.
            String fieldType = in_fieldType.getValue().getAsText();
            IGPParameterEdit3 in_fieldLength = (IGPParameterEdit3)
                paramvalues.getElement(3);

            //Check whether the value is Text.
            if (fieldType.equalsIgnoreCase("TEXT")){
                //Enable the FieldLength parameter.
                in_fieldLength.setEnabled(true);
            }
            else{
                //If the value is not Text, disable the parameter.
                in_fieldLength.setEnabled(false);
            }
        }
    }
    catch (AutomationException e){
        e.printStackTrace();
    }
    catch (IOException e){
        e.printStackTrace();
    }
}

}
The previous code creates a tool dialog similar to the following screen shots. The Field Length parameter is disabled when the field type is designated as DOUBLE, but it is enabled when designated as TEXT.

Changing the parameter display order

By default, parameters are listed in the tool dialog box in the order they appear in the array returned by the BaseGeoprocessingTool.getParameterInfo() method. For legacy support, you can override the display order by setting the Display order property of each parameter. If you are not building legacy functions, do not use display order. Use the order of the parameters in the array instead, since they match the scripting and command line usage.


See Also:

Defining domain for tool parameters
Creating a custom function tool class



Development licensingDeployment licensing
Engine Developer KitEngine
ServerServer
ArcGIS for Desktop BasicArcGIS for Desktop Basic
ArcGIS for Desktop StandardArcGIS for Desktop Standard
ArcGIS for Desktop AdvancedArcGIS for Desktop Advanced