Personnalisation du comportement de l'outil dans une boîte à outils Python
La validation concerne tout ce qui se passe avant d'appuyer sur le bouton OK d'un outil. Lorsque vous créez vos propres outils personnalisés, la validation vous permet de personnaliser les modalités de réaction des paramètres ainsi que leurs interactions avec les valeurs et avec les autres paramètres. La validation s'effectue avec un bloc de code Python permettant de contrôler le comportement de l'outil.
Pour en savoir plus sur la validation, reportez-vous à la rubrique Présentation de la validation dans les outils de script.
Dans une boîte à outils Python, chaque paramètre d'outil dispose d'un objet Parameter associé comportant les propriétés et méthodes utiles à la validation d'outils. Dans une boîte à outils Python, les paramètres sont définis dans la méthode getParameterInfo de la classe d'outils. Le comportement de ces paramètres et la façon dont ils interagissent l'un avec l'autre et les entrées sont validés d'après la méthode updateParameters de la classe d'outils.
Accès aux paramètres de l'outil
Les objets Parameter constituent la fondation de la définition des paramètres et leur interaction dans une boîte à outils Python. La procédure habituelle consiste à créer la liste de paramètres dans la méthode getParameterInfo de la classe d'outil, comme illustré dans le code ci-dessous.
def getParameterInfo(self):
#Define parameter definitions
# First parameter
param0 = arcpy.Parameter(
displayName="Input Features",
name="in_features",
datatype="GPFeatureLayer",
parameterType="Required",
direction="Input")
return [param0]
Pour en savoir plus sur la définition des paramètres dans une boîte à outils Python, consultez la rubrique Définition de paramètres dans une boîte à outils Python.
Objet Parameter
Méthodes
|
Nom de la méthode |
Description de l'utilisation |
|---|---|
|
setErrorMessage(message:string) |
Indique une erreur sur le paramètre (un X rouge) avec le message fourni. Les outils ne s'exécutent pas si l'un des paramètres comporte une erreur. |
|
setWarningMessage(message:string) |
Indique qu'un avertissement sur le paramètre (un triangle jaune) avec le message fourni. Contrairement aux erreurs, les outils s'exécutent avec les messages d'avertissement. |
|
setIDMessage(messageType: string, messageID: string, {AddArgument1}, {AddArgument2}) |
Permet de définir un message système. Les arguments sont les mêmes que pour la fonction AddIDMessage. |
|
clearMessage() |
Supprime le texte de message et définit le statut sur information (pas d'erreur ou d'avertissement). |
|
hasError() |
Renvoie la valeur True si le paramètre contient une erreur. |
|
hasWarning() |
Renvoie la valeur True si le paramètre contient un avertissement. |
|
isInputValueDerived() |
Renvoie la valeur True si l'outil est validé à l'intérieur d'un Modèle et si la valeur en entrée correspond à la sortie d'un autre outil dans le modèle. |
Propriétés
|
Nom de la propriété |
Lecture/écriture |
Valeur(s) |
Description |
|---|---|---|---|
|
name |
Lecture seule |
Chaîne |
Nom du paramètre. |
|
direction |
Lecture seule |
Chaîne : "Entrée", "Sortie" |
Direction d'entrée/sortie du paramètre. |
|
datatype |
Lecture seule |
Chaîne |
Pour obtenir une liste de types de données de paramètre, consultez la rubrique Définition de types de données de paramètre dans une boîte à outils Python. |
|
parameterType |
Lecture seule |
Chaîne : "Requis", "Facultatif", "Dérivé" |
Type de paramètre. |
|
parameterDependencies |
Lecture/écriture |
Liste Python |
Liste des index de chaque paramètre dépendant. |
|
valeur |
Lecture/écriture |
Objet Value |
Valeur du paramètre. |
|
defaultEnvironmentName |
Lecture seule |
Chaîne |
Paramètre d'environnement par défaut. |
|
enabled |
Lecture/écriture |
Booléen |
Valeur False si le paramètre est indisponible. |
|
altered |
Lecture seule |
Booléen |
Valeur True si l'utilisateur a modifié la valeur. |
|
hasBeenValidated |
Lecture seule |
Booléen |
Valeur True si la routine de validation interne a vérifié le paramètre. |
|
category |
Lecture/écriture |
Chaîne |
Catégorie du paramètre. |
|
structure |
Lecture seule |
Objet Schema |
Structure du jeu de données en sortie. |
|
filter |
Lecture seule |
Objet Filter |
Filtre à appliquer aux valeurs dans le paramètre. |
|
symbologie |
Lecture/écriture |
Chaîne |
Chemin d'accès à un fichier de couches (.lyr) utilisé pour afficher la sortie. |
|
message |
Lecture seule |
Chaîne |
Message à afficher à l'utilisateur. Reportez-vous aux méthodes SetErrorMessage et SetWarningMessage ci-dessus. |
parameterDependencies
Vous définissez généralement des dépendances de paramètres à utiliser par l'objet Schema. Dans deux cas, les dépendances peuvent avoir déjà été définies dans la méthode getParameterInfo de l'outil.
- Pour un paramètre de jeu de données en sortie de type Dérivé, la dépendance est l'index du paramètre à partir duquel la sortie est dérivée.
- Pour certains types de données en entrée, la dépendance est l'index du paramètre qui contient les informations utilisées par le contrôle, comme illustré dans la table ci-dessous.
|
Type de données en entrée |
Type de données dépendantes |
Description |
|---|---|---|
|
Champ ou expression SQL |
Table |
Table qui contient les champs. |
|
Elément INFO ou expression INFO |
Table INFO |
La table INFO qui contient les attributs. |
|
Classe d'entités de couverture |
Couverture |
La couverture qui contient des entités. |
|
Unités de surface ou unités linéaires |
Jeu de données géographiques |
Un jeu de données géographiques utilisé pour déterminer les unités par défaut. |
|
Système de coordonnées |
Espace de travail |
Un espace de travail utilisé pour déterminer le système de coordonnées par défaut. |
|
Paramètres de hiérarchie Network Analyst |
Jeu de données réseau |
Le jeu de données réseau qui contient les informations de hiérarchie. |
|
Table de valeurs géostatistiques |
Couche géostatistique |
Couche d'analyse qui contient les tables. |
Remarque :parameterDependencies équivaut au paramètre Obtenu à partir de de l'assistant Outil de script.
Les dépendances sont généralement définies dans la méthode getParameterInfo :
def getParameterInfo(self):
#Define parameter definitions
# First parameter
param0 = arcpy.Parameter(
displayName="Input Features",
name="in_features",
datatype="GPFeatureLayer",
parameterType="Required",
direction="Input")
# Second parameter
param1 = arcpy.Parameter(
displayName="Sinuosity Field",
name="sinuosity_field",
datatype="Field",
parameterType="Optional",
direction="Input")
param1.value = "sinuosity"
# Third parameter
param2 = arcpy.Parameter(
displayName="Output Features",
name="out_features",
datatype="GPFeatureLayer",
parameterType="Derived",
direction="Output")
param2.parameterDependencies = [param0.name]
param2.schema.clone = True
params = [param0, param1, param2]
return params
valeur
C'est la valeur du paramètre que l'utilisateur a saisie ou que vous avez définie à l'aide d'un programme. Vous pouvez définir cette valeur dans la méthode getParameterInfo, auquel cas elle devient la valeur initiale par défaut du paramètre. Vous pouvez également définir la valeur dans updateParameters en réponse aux informations saisies par l'utilisateur, comme illustré ci-dessous.
def updateParameters(self, parameters):
# 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 the user has set a specific distance (Altered is true).
#
if parameters[0].value:
if not parameters[6].altered:
extent = arcpy.Describe(parameters[0].value).extent
if extent.width > extent.height:
parameters[6].value = extent.width / 100
else:
parameters[6].value = extent.height / 100
return
La propriété value d'un paramètre renvoie un objet, sauf si le paramètre n'est pas renseigné, auquel cas value renvoie None. Pour éviter qu'un paramètre ne soit pas renseigné, utilisez un contrôle if avant d'utiliser sa valeur.
L'extrait de code ci-dessous vérifie si la valeur est égale à la chaîne "Extraire les pondérations spatiales à partir du fichier". Ce test fonctionne car le type de données du paramètre est une chaîne.
# If the option to use a weights file is selected, enable the
# parameter for specifying the file, otherwise disable it
if parameters[3].value: # check that parameter has a value
if parameters[3].value == "Get Spatial Weights From File":
parameters[8].enabled = True
else:
parameters[8].enabled = False
Comme un objet Value ne prend pas en charge la gestion des chaînes, utilisez la propriété de valeur de l'objet Value lorsqu'une chaîne doit être gérée ou analysée. L'exemple de code utilise la méthode os.path.dirname pour renvoyer le répertoire à partir d'un jeu de données.
if parameters[0].value:
workspace = os.path.dirname(parameters[0].value.value)
With the exception of Describe, don't use methods that take a catalog path, such as ListFields, in validation. The dataset may not exist when your tool is validated in ModelBuilder, and the method may fail or give unexpected results.
In the specific case of ListFields, the Describe object's fields property will provide the equivalent information.
Remarque :Don't set a parameter value in updateMessages() since the value will not be validated by the internal validation routine.
altered
altered a la valeur True si l'utilisateur a modifié la valeur d'un paramètre, en saisissant un chemin en sortie, par exemple. Lorsqu'un paramètre a été modifié, il le reste jusqu'à ce que l'utilisateur vide (efface) la valeur, auquel cas il revient à son précédent état. La modification d'une valeur à l'aide d'un programme avec un code de validation ne change pas l'état Altered. Autrement dit, si vous définissez une valeur pour un paramètre, l'état Altered du paramètre ne change pas.
La propriété altered permet de déterminer si vous pouvez modifier la valeur d'un paramètre. Supposez par exemple qu'un outil contienne un paramètre de classe d'entités et un paramètre de mot-clé. Si la classe d'entités contient des points ou des polygones, les mots-clés sont RED, GREEN et BLUE et si elle contient des lignes, les mots-clés sont ORANGE, YELLOW, PURPLE et WHITE.
Supposons que l'utilisateur entre une classe d'entités ponctuelles. Si le paramètre de mot-clé est inchangé, vous définissez la valeur sur RED, car c'est la valeur par défaut.
Si une classe d'entités linéaires est entrée, vous définissez la valeur par défaut sur ORANGE tant que le paramètre de mot-clé reste inchangé.
Cependant, si le paramètre de mot-clé a été modifié par l'utilisateur (c'est-à-dire si le mot-clé est défini sur GREEN), vous ne devez pas réinitialiser le mot-clé : l'utilisateur a fait son choix (GREEN) et vous ne connaissez pas son intention, il peut modifier la classe d'entités afin que GREEN soit valide ou modifier le mot-clé (en spécifiant PURPLE, par exemple). Puisque GREEN ne fait pas partie de l'ensemble de mots-clé que vous avez créé pour les lignes, la validation interne marque le paramètre comme contenant une erreur. L'utilisateur a alors deux options : modifier la classe d'entités en entrée ou modifier le mot-clé.
if not parameters[2].altered:
parameters[2].value = "POINT"
hasBeenValidated
La valeur de hasBeenValidated est false si la valeur d'un paramètre a été modifiée par l'utilisateur depuis le dernier appel de la méthode updateParameters et de la validation interne. Lorsque la validation interne est appelée, le géotraitement définit automatiquement hasBeenValidated sur True pour chaque paramètre.
hasBeenValidated permet de déterminer si l'utilisateur a modifié une valeur depuis le dernier appel de la méthode updateParameters. Vous pouvez utiliser cette information pour décider si vous devez effectuer un contrôle du paramètre.
def updateParameters(self, parameters):
# 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 the user has set a specific distance (Altered is true).
#
if parameters[0].value:
if not parameters[6].altered:
extent = arcpy.Describe(parameters[0].value).extent
if extent.width > extent.height:
parameters[6].value = extent.width / 100
else:
parameters[6].value = extent.height / 100
return