Object name/fr: Difference between revisions

From FreeCAD Documentation
(Created page with "Il existe différentes propriétés pour les étiquettes: * Le {{incode|Label}} peut accepter n'importe quelle chaîne UTF8, y compris les accents et les espaces. * La tree_...")
(Created page with "Cette propriété a été introduite dans la version 0.19. Il s'agit d'une chaîne simple qui peut contenir du texte arbitraire et peut donc être utilisée pour documenter (d...")
Line 30: Line 30:
=== Label2 ===
=== Label2 ===


Cette propriété a été introduite dans la version 0.19. Il s'agit d'une chaîne simple qui peut contenir du texte arbitraire et peut donc être utilisée pour documenter (décrire plus en détail) l'objet créé.
This property was introduced in v0.19. It is a simple string that can contain arbitrary text, and therefore can be used for documenting (describing with more detail) the created object.
* In the [[tree_view|tree view]] edit the field next to the icon, under "Description", by clicking on it and pressing {{KEY|F2}}.
* Dans la [[tree_view/fr|vue en arborescence]], modifiez le champ à côté de l'icône, sous "Description", en cliquant dessus et en appuyant sur {{KEY|F2}}.
* You can also change this property by modifying the {{incode|Label2}} attribute from the [[Python_console|Python console]].
* Vous pouvez également modifier cette propriété en modifiant l'attribut {{incode|Label2}} à partir de la [[Python_console/fr|console Python]].
* The {{PropertyData|Label2}} attribute is normally hidden in the [[property_editor|property editor]] but can be made visible by opening the context menu (right click) and selecting {{MenuCommand|Show all}}.
* L'attribut {{PropertyData|Label2}} est normalement masqué dans [[Property_editor/fr|Éditeur de propriétés]] mais peut être rendu visible en ouvrant le menu contextuel (clic droit) et en sélectionnant {{MenuCommand|Show all}}.


== Scripting ==
== Scripting ==

Revision as of 15:12, 14 July 2020

Introduction

Tous les objets du programme ont un object name qui les identifie de manière unique dans un Document donné.

Ces informations s'appliquent à tous les objets dérivés de App DocumentObject (classe App::DocumentObject), qui comprend essentiellement tous les objets qu'il est possible de créer dans un document.

Les Names

Il existe différentes propriétés pour les noms:

  • Le Name ne peut contenir que des caractères alphanumériques simples et le trait de soulignement, [_0-9a-zA-Z].
  • Le Name ne peut pas commencer par un nombre. Il doit commencer par une lettre ou le trait de soulignement, [_a-zA-Z].
  • Le Name est attribué au moment de la création de l'objet ensuite, il n'est plus modifiable. L'objet ne peut jamais être renommé.
  • Le Name doit être unique dans tout le document. Peu importe si deux objets sont de types complètement différents, par exemple, l'un est un PartDesign Poche et l'autre est un Arch Mur. Ils doivent avoir des noms différents.
  • Lors de la création d'un objet du même type, normalement le nom est augmenté d'un numéro séquentiel par exemple Box, Box001, Box002 etc.... Cela permet d'éviter la collusion des noms..
  • Une fois l'objet supprimé, son Name devient disponible pour être utilisé par un objet nouvellement créé. Cela signifie que si Box, Box001 et Box002 existent et que nous supprimons le premier élément, la boîte suivante créée avec Part Cube ne sera pas Box003, ce sera à nouveau Box, cette chaîne étant disponible pour être réutilisée. Notez qu'il n'est pas possible de renommer Box001 ou Box002 en Box car leurs noms sont fixes.

En résumé, Name agit essentiellement comme un identifiant unique (UID) pour un objet. Puisqu'un Name unique est très restrictif, tous les objets ont également une propriété Label qui permet de "renommer" l'objet en quelque chose de plus descriptif. Le Name interne reste en fait fixe, mais le Label modifiable par l'utilisateur peut être utilisé dans la plupart des situations où le Name serait utilisé. Dans l'utilisation courante dans le programme et la documentation, "renommer" signifie changer le Label et non le Name réel de l'objet.

Les Labels

Il existe différentes propriétés pour les étiquettes:

  • Le Label peut accepter n'importe quelle chaîne UTF8, y compris les accents et les espaces.
  • La vue en arborescence affiche en fait le Label de l'objet et pas le Name. Par conséquent, chaque fois qu'un nouvel objet est créé, il est recommandé de remplacer Label par une chaîne plus descriptive. Pour renommer l'objet, sélectionnez-le dans l'arborescence et appuyez sur F2, ou ouvrez le menu contextuel (clic droit) et choisissez Rename.
  • Même après qu'un objet a été renommé (ré-étiqueté), le Name interne sera toujours déclaré à de nombreux endroits, par exemple, dans la Barre d'état ou dans la Fenêtre de sélection lorsque l'objet est sélectionné.
  • Étant donné que les fonctions internes du programme font référence aux objets par Name, de nombreuses boîtes de dialogue affichent le Name en premier suivi de l'étiquette Label modifiable par l'utilisateur entre parenthèses, par exemple, Box (Extruded piece).
  • Par défaut, le Label est unique, tout comme le Name. Cependant, ce comportement peut être modifié dans éditeur de préférences, Edition → Préférences → Général → Document → Autoriser la duplication des étiquettes dans un document. Cela signifie qu'en général, Label n'est pas unique dans le document et peut en fait être répété. Cependant, la recommandation est de garder le Label unique, car c'est probablement ce qui est le plus utile pour identifier différents objets. Lors de l'écriture de fonctions personnalisées qui manipulent des objets, les méthodes doivent utiliser le Name de l'objet plutôt que son Label pour garantir que l'objet correct est utilisé.

Label2

Cette propriété a été introduite dans la version 0.19. Il s'agit d'une chaîne simple qui peut contenir du texte arbitraire et peut donc être utilisée pour documenter (décrire plus en détail) l'objet créé.

  • Dans la vue en arborescence, modifiez le champ à côté de l'icône, sous "Description", en cliquant dessus et en appuyant sur F2.
  • Vous pouvez également modifier cette propriété en modifiant l'attribut Label2 à partir de la console Python.
  • L'attribut DonnéesLabel2 est normalement masqué dans Éditeur de propriétés mais peut être rendu visible en ouvrant le menu contextuel (clic droit) et en sélectionnant Show all.

Scripting

See also: FreeCAD Scripting Basics, and scripted objects.

Any object in the software is internally created with the addObject() method of the document. The majority of 2D and 3D objects that the user will see in the 3D view are derived from a Part Feature. In the following example, the object created is a Part Box.

import FreeCAD as App

doc = App.newDocument()
obj = doc.addObject("Part::Box", "Name")
obj.Label = "Custom label"

Name

The addObject function has two basic string arguments.

  • The first argument indicates the type of object, in this case, "Part::Box".
  • The second argument is a string that defines the Name attribute. If it is not provided, it defaults to the same name as the class of the object, that is, "Part__Box", where the two invalid symbols, the colons ::, are replaced by two underscores __.
    • The Name can only include simple alphanumeric characters, and the underscore, [_0-9a-zA-Z]. If other symbols are given, these will be converted to underscores; for example, "A+B:C*" is converted to "A_B_C_".
    • The Name cannot start with a number; it must start with a letter or the underscore, [_a-zA-Z]. For example, "123ABC" is converted to "_23ABC".
    • The Name is fixed at creation time; it cannot be modified afterwards.
    • The Name must be unique in the entire document. If the same "Name" is used, a sequential number will be appended automatically so that the resulting names are unique; for example, if "Name" already exists, then new objects will be called "Name001", "Name002", "Name003", etc.

Label

The Label is a property of the created object and can be changed to a more meaningful text.

  • Upon creating the object, the Label is the same as the Name.
  • However, unlike the Name, the Label can accept any UTF8 string, including accents and spaces.
  • The Label can be changed at any point in time just by assigning the desired string, obj.Label = "New label"

Getting an object by Name or Label

All objects in a document are data attributes of the corresponding Document object. The attribute's name correspond to the internal Name of the object.

import FreeCAD as App

obj1 = App.ActiveDocument.Box
obj2 = App.ActiveDocument.Box001
obj3 = App.ActiveDocument.Box002

This is equivalent to using the getObject method of the Document.

import FreeCAD as App

obj1 = App.ActiveDocument.getObject('Box')
obj2 = App.ActiveDocument.getObject('Box001')
obj3 = App.ActiveDocument.getObject('Box002')

However, it is also possible to get the object by the more descriptive Label.

import FreeCAD as App

obj1 = App.ActiveDocument.getObjectsByLabel("Concrete wall")[0]
obj2 = App.ActiveDocument.getObjectsByLabel("Custom parallelepiped")[0]
obj3 = App.ActiveDocument.getObjectsByLabel("Some special name for this cube__002")[0]

Given that the Label is in general not unique, the getObjectsByLabel method returns a list with all objects found with that Label. However, if the Label is unique in the document then the first element in that list should be the desired object.