Object name/de: Difference between revisions

From FreeCAD Documentation
(Updating to match new version of source page)
(Updating to match new version of source page)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<languages/>
<languages/>


<span id="Introduction"></span>
== Einleitung ==
== Einleitung ==


{{TOCright}}
{{TOCright}}


Alle Objekte im Programm haben einen [[Object_name/de|Objektnamen]], der sie in einem bestimmten [[App_Document/de|Dokument]] eindeutig identifiziert.
Alle Objekte im Programm haben einen [[Object_name/de|Objektnamen]], der sie in einem bestimmten Dokument eindeutig identifiziert.


Diese Informationen gelten für alle Objekte, die von [[App_DocumentObject/de|App DokumentObjekt]] abgeleitet sind. ({{Incode|App::DocumentObject}} Klasse), die im Wesentlichen alle Objekte umfasst, die in einem Dokument erstellt werden können.
Diese Informationen gelten für alle Objekte, die von einem Dokumentobjekt ([[App_DocumentObject/de|App DocumentObject]], d.h. der Klasse {{Incode|App::DocumentObject}})abgeleitet sind, die im Wesentlichen alle Objekte umfasst, die in einem Dokument erstellt werden können.


<span id="Names"></span>
== Namen ==
== Namen ==


Namen besitzen verschiedene Eigenschaften:
There are various properties for Names:
* The {{incode|Name}} can only include simple alphanumeric characters, and the underscore, {{incode|[_0-9a-zA-Z]}}.
* Der {{incode|Name}} darf nur einfache alphanumerische Zeichen, und den Unterstrich enthalten, {{incode|[_0-9a-zA-Z]}}.
* The {{incode|Name}} cannot start with a number; it must start with a letter or the underscore, {{incode|[_a-zA-Z]}}.
* Der {{incode|Name}} darf nicht mit einer Zahl beginnen; er muss mit mit einem Buchstaben oder Unterstrich beginnen, {{incode|[_a-zA-Z]}}.
* The {{incode|Name}} is assigned at the creation time of the object; afterwards it is no longer editable. The object can never be renamed.
* Der {{incode|Name}} wird zum Zeitpunkt der Erstellung des Objekts vergeben und kann danach nicht mehr verändert werden. Der Name kann nie geändert werden.
* The {{incode|Name}} must be unique in the entire document. It doesn't matter if two objects are of completely different types, for example, one is a [[PartDesign_Pocket|PartDesign Pocket]] and the other is an [[Arch_Wall|Arch Wall]]. They must have different names.
* Der {{incode|Name}} darf im gesamten Dokument nur ein einziges Mal vorkommen. Dabei ist es egal, ob zwei Objekte komplett unterschiedlich sind wie z.B. eine [[PartDesign_Pocket/de|PartDesign Tasche]] und eine [[Arch_Wall/de|Arch Wand]]; sie müssen unterschiedliche Namen besitzen.
* When creating an object of the same type, normally the name is increased with a sequential number, thus {{incode|Box}}, {{incode|Box001}}, {{incode|Box002}}, etc. This prevents naming collision.
* Werden Objekte der gleichen Art erstellt, wird der Name mit einer fortlaufenden Zahl ergänzt; ds ergibt {{incode|Box}}, {{incode|Box001}}, {{incode|Box002}} usw. Das verhindert doppelte Namen.
* Once the object is deleted, its {{incode|Name}} becomes available to be used by a newly created object. This means that if {{incode|Box}}, {{incode|Box001}}, and {{incode|Box002}} exist, and we delete the first item, the next box created with [[Part_Box|Part Box]] will not be {{incode|Box003}}, it will be {{incode|Box}} again, because this string is available to be used once more. Notice that it is not possible to rename {{incode|Box001}} or {{incode|Box002}} to {{incode|Box}} since their names are fixed.
* Sobald ein Objekt gelöscht wurde, kann sein {{incode|Name}} wieder für ein neu erstelltes Objekt verwendet werden. Das heißt, wenn die Objekte {{incode|Box}}, {{incode|Box001}} und {{incode|Box002}} vorhanden sind und das erste gelöscht wird, bekommt das nächste Objekt [[Part_Box|Part Box]] nicht den Namen {{incode|Box003}}, sondern wieder {{incode|Box}}, da diese Zeichenkette erneut verwendet werden kann. Es ist zu beachten, dass die Namen {{incode|Box001}} oder {{incode|Box002}} nicht in {{incode|Box}} geändert werden können, da sie unveränderlich sind.


In summary, the {{incode|Name}} essentially acts like a unique identifier (UID) for an object. Since a unique {{incode|Name}} is very restrictive, all objects also have a {{incode|Label}} property which allows "renaming" the object to something more descriptive. The internal {{incode|Name}} actually remains fixed, but the user editable {{incode|Label}} can be used in most situations where the {{incode|Name}} would be used. In common usage in the program and the documentation, "renaming" means changing the {{incode|Label}} and not the actual {{incode|Name}} of the object.
Zusammengefasst stellt der {{incode|Name}} einen eindeutigen Identifikator (unique identifier, UID) eines Objekts dar. Da ein eindeutiger {{incode|Name}} sehr eingeschränkt ist, besitzen Objekte auch noch die Eigenschaft {{incode|Label}}, die ermöglicht, das Objekt "umzubenennen", also eine besser beschreibende Benennung hinzuzufügen. Der interne {{incode|Name}} bleibt tatsächlich unverändert, aber die vom Benutzer editierbare Benennung {{incode|Label}} kann in den meisten Fällen an Stelle des {{incode|Namens}} verwendet werden. In der üblichen Verwendung im Programm bezieht sich "umbenennen" auf das {{incode|Label}} (Benennung) und nicht auf den wirklichen {{incode|Namen}} des Objekts.


== Labels ==
<span id="Labels"></span>
== Benennungen ==


There are various properties for Labels:
There are various properties for Labels:
* The {{incode|Label}} can accept any UTF8 string, including accents and spaces.
* The {{incode|Label}} can accept any UTF8 string, including accents and spaces.
* The [[tree_view|tree view]] actually displays the {{incode|Label}} of the object, not the {{incode|Name}}. Therefore, whenever a new object is created, it is a good practice to change the {{incode|Label}} to a more descriptive string. To rename (relabel) the object, select it in the tree view and press {{KEY|F2}}, or open the context menu (right-click) and choose {{MenuCommand|Rename}}.
* The [[tree_view|tree view]] actually displays the {{incode|Label}} of the object, not the {{incode|Name}}. Therefore, whenever a new object is created, it is a good practice to change the {{incode|Label}} to a more descriptive string. To rename (relabel) the object, select it in the tree view and press {{KEY|F2}} (or rather {{KEY|Return}} on macOS), or open the context menu (right-click) and choose {{MenuCommand|Rename}}.
* Even after an object was renamed (relabelled), the internal {{incode|Name}} will still be reported in many places, for example, in the [[status_bar|status bar]] or in the [[selection_view|selection view]], when the object is selected.
* Even after an object was renamed (relabelled), the internal {{incode|Name}} will still be reported in many places, for example, in the [[Status_bar|status bar]] or in the [[Selection_view|selection view]], when the object is selected.
* Since the internal functions of the program refer to the objects by {{incode|Name}}, many dialogs will display the {{incode|Name}} first, followed by the user editable {{incode|Label}} in parentheses, for example, {{incode|Box (Extruded piece)}}.
* Since the internal functions of the program refer to the objects by {{incode|Name}}, many dialogs will display the {{incode|Name}} first, followed by the user editable {{incode|Label}} in parentheses, for example, {{incode|Box (Extruded piece)}}.
* By default the {{incode|Label}} is unique, just like the {{incode|Name}}. However, this behavior can be changed in the [[Preferences_Editor|preferences editor]], {{MenuCommand|Edit → Preferences → General → Document → Allow duplicate object labels in one document}}. This means that in general the {{incode|Label}} is not unique in the document, and may actually be repeated. However, the recommendation is to keep the {{incode|Label}} unique, as this is probably what is most useful to identify different objects. When writing custom functions that manipulate objects, the methods should use the {{incode|Name}} of the object rather than its {{incode|Label}} to guarantee that the correct object is used.
* By default the {{incode|Label}} is unique, just like the {{incode|Name}}. However, this behavior can be changed in the [[Preferences_Editor|preferences editor]], {{MenuCommand|Edit → Preferences → General → Document → Allow duplicate object labels in one document}}. This means that in general the {{incode|Label}} is not unique in the document, and may actually be repeated. However, the recommendation is to keep the {{incode|Label}} unique, as this is probably what is most useful to identify different objects. When writing custom functions that manipulate objects, the methods should use the {{incode|Name}} of the object rather than its {{incode|Label}} to guarantee that the correct object is used.
* When using [[Expressions|expressions]], for example, in the [[Property_editor|property editor]] or in a [[Spreadsheet|spreadsheet]], the Label can be referenced using double brackets made of the less than and greater than symbols.

{{Code|code=
<<Custom Label With Spaces>>.Height
<<Label may use UTF8 characters>>.Width
}}


=== Label2 ===
=== Label2 ===


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.
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}}.
* In the [[Tree_view|tree view]] edit the field next to the icon, under "Description", by clicking on it and pressing {{KEY|F2}} (or rather {{KEY|Return}} on macOS).
* You can also change this property by modifying the {{incode|Label2}} attribute from the [[Python_console|Python console]].
* You can also change this property by modifying the {{incode|Label2}} attribute from the [[Python_console|Python console]].
* 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}}.
* 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}}.


== Scripting ==
<span id="Scripting"></span>
== Skripten ==


{{Emphasis|See also:}} [[FreeCAD Scripting Basics|FreeCAD Scripting Basics]], and [[scripted objects|scripted objects]].
{{Emphasis|Siehe auch:}} [[FreeCAD_Scripting_Basics/de|FreeCAD Grundlagen Skripten]] und [[Scripted_objects/de|Skriptgenerierte Objekte]].


Any object in the software is internally created with the {{incode|addObject()}} method of the document. The majority of 2D and 3D objects that the user will see in the [[3D_view|3D view]] are derived from a [[Part_Feature|Part Feature]]. In the following example, the object created is a [[Part_Box|Part Box]].
Any object in the software is internally created with the {{incode|addObject()}} method of the document. The majority of 2D and 3D objects that the user will see in the [[3D_view|3D view]] are derived from a [[Part_Feature|Part Feature]]. In the following example, the object created is a [[Part_Box|Part Box]].
Line 62: Line 72:
** The {{incode|Name}} must be unique in the entire document. If the same {{incode|"Name"}} is used, a sequential number will be appended automatically so that the resulting names are unique; for example, if {{incode|"Name"}} already exists, then new objects will be called {{incode|"Name001"}}, {{incode|"Name002"}}, {{incode|"Name003"}}, etc.
** The {{incode|Name}} must be unique in the entire document. If the same {{incode|"Name"}} is used, a sequential number will be appended automatically so that the resulting names are unique; for example, if {{incode|"Name"}} already exists, then new objects will be called {{incode|"Name001"}}, {{incode|"Name002"}}, {{incode|"Name003"}}, etc.


=== Label ===
<span id="Label"></span>
=== Benennung ===


The {{incode|Label}} is a property of the created object and can be changed to a more meaningful text.
The {{incode|Label}} is a property of the created object and can be changed to a more meaningful text.
Line 69: Line 80:
* The {{incode|Label}} can be changed at any point in time just by assigning the desired string, <code>obj.Label = "New label"</code>
* The {{incode|Label}} can be changed at any point in time just by assigning the desired string, <code>obj.Label = "New label"</code>


<span id="Getting_an_object_by_Name_or_Label"></span>
=== Getting an object by Name or Label ===
=== Ein Objekt mit Namen oder Benennung aufrufen ===


All objects in a document are data attributes of the corresponding [[App_Document|Document]] object. The attribute's name correspond to the internal {{incode|Name}} of the object.
All objects in a document are data attributes of the corresponding [[App_DocumentObject|Document]] object. The attribute's name correspond to the internal {{incode|Name}} of the object.


{{Code|code=
{{Code|code=

Latest revision as of 16:20, 20 May 2023

Einleitung

Alle Objekte im Programm haben einen Objektnamen, der sie in einem bestimmten Dokument eindeutig identifiziert.

Diese Informationen gelten für alle Objekte, die von einem Dokumentobjekt (App DocumentObject, d.h. der Klasse App::DocumentObject)abgeleitet sind, die im Wesentlichen alle Objekte umfasst, die in einem Dokument erstellt werden können.

Namen

Namen besitzen verschiedene Eigenschaften:

  • Der Name darf nur einfache alphanumerische Zeichen, und den Unterstrich enthalten, [_0-9a-zA-Z].
  • Der Name darf nicht mit einer Zahl beginnen; er muss mit mit einem Buchstaben oder Unterstrich beginnen, [_a-zA-Z].
  • Der Name wird zum Zeitpunkt der Erstellung des Objekts vergeben und kann danach nicht mehr verändert werden. Der Name kann nie geändert werden.
  • Der Name darf im gesamten Dokument nur ein einziges Mal vorkommen. Dabei ist es egal, ob zwei Objekte komplett unterschiedlich sind wie z.B. eine PartDesign Tasche und eine Arch Wand; sie müssen unterschiedliche Namen besitzen.
  • Werden Objekte der gleichen Art erstellt, wird der Name mit einer fortlaufenden Zahl ergänzt; ds ergibt Box, Box001, Box002 usw. Das verhindert doppelte Namen.
  • Sobald ein Objekt gelöscht wurde, kann sein Name wieder für ein neu erstelltes Objekt verwendet werden. Das heißt, wenn die Objekte Box, Box001 und Box002 vorhanden sind und das erste gelöscht wird, bekommt das nächste Objekt Part Box nicht den Namen Box003, sondern wieder Box, da diese Zeichenkette erneut verwendet werden kann. Es ist zu beachten, dass die Namen Box001 oder Box002 nicht in Box geändert werden können, da sie unveränderlich sind.

Zusammengefasst stellt der Name einen eindeutigen Identifikator (unique identifier, UID) eines Objekts dar. Da ein eindeutiger Name sehr eingeschränkt ist, besitzen Objekte auch noch die Eigenschaft Label, die ermöglicht, das Objekt "umzubenennen", also eine besser beschreibende Benennung hinzuzufügen. Der interne Name bleibt tatsächlich unverändert, aber die vom Benutzer editierbare Benennung Label kann in den meisten Fällen an Stelle des Namens verwendet werden. In der üblichen Verwendung im Programm bezieht sich "umbenennen" auf das Label (Benennung) und nicht auf den wirklichen Namen des Objekts.

Benennungen

There are various properties for Labels:

  • The Label can accept any UTF8 string, including accents and spaces.
  • The tree view actually displays the Label of the object, not the Name. Therefore, whenever a new object is created, it is a good practice to change the Label to a more descriptive string. To rename (relabel) the object, select it in the tree view and press F2 (or rather Return on macOS), or open the context menu (right-click) and choose Rename.
  • Even after an object was renamed (relabelled), the internal Name will still be reported in many places, for example, in the status bar or in the selection view, when the object is selected.
  • Since the internal functions of the program refer to the objects by Name, many dialogs will display the Name first, followed by the user editable Label in parentheses, for example, Box (Extruded piece).
  • By default the Label is unique, just like the Name. However, this behavior can be changed in the preferences editor, Edit → Preferences → General → Document → Allow duplicate object labels in one document. This means that in general the Label is not unique in the document, and may actually be repeated. However, the recommendation is to keep the Label unique, as this is probably what is most useful to identify different objects. When writing custom functions that manipulate objects, the methods should use the Name of the object rather than its Label to guarantee that the correct object is used.
  • When using expressions, for example, in the property editor or in a spreadsheet, the Label can be referenced using double brackets made of the less than and greater than symbols.
<<Custom Label With Spaces>>.Height
<<Label may use UTF8 characters>>.Width

Label2

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 edit the field next to the icon, under "Description", by clicking on it and pressing F2 (or rather Return on macOS).
  • You can also change this property by modifying the Label2 attribute from the Python console.
  • The DatenLabel2 attribute is normally hidden in the property editor but can be made visible by opening the context menu (right click) and selecting Show all.

Skripten

Siehe auch: FreeCAD Grundlagen Skripten und Skriptgenerierte Objekte.

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.

Benennung

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"

Ein Objekt mit Namen oder Benennung aufrufen

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.