Object name/pl

Introduction
All objects in the program have an object name that uniquely identifies them in a given Document.

This information applies to all objects derived from App DocumentObject ( class), which essentially comprises all objects that are possible to create in a document.

Names
There are various properties for Names:
 * The can only include simple alphanumeric characters, and the underscore,.
 * The cannot start with a number; it must start with a letter or the underscore,.
 * The is assigned at the creation time of the object; afterwards it is no longer editable. The object can never be renamed.
 * The 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 and the other is an Arch Wall. They must have different names.
 * When creating an object of the same type, normally the name is increased with a sequential number, thus, , , etc. This prevents naming collision.
 * Once the object is deleted, its becomes available to be used by a newly created object. This means that if, , and  exist, and we delete the first item, the next box created with Part Box will not be , it will be  again, because this string is available to be used once more. Notice that it is not possible to rename  or  to  since their names are fixed.

In summary, the essentially acts like a unique identifier (UID) for an object. Since a unique is very restrictive, all objects also have a  property which allows "renaming" the object to something more descriptive. The internal actually remains fixed, but the user editable  can be used in most situations where the  would be used. In common usage in the program and the documentation, "renaming" means changing the and not the actual  of the object.

Labels
There are various properties for Labels:
 * The can accept any UTF8 string, including accents and spaces.
 * The tree view actually displays the of the object, not the . Therefore, whenever a new object is created, it is a good practice to change the  to a more descriptive string. To rename (relabel) the object, select it in the tree view and press, or open the context menu (right-click) and choose.
 * Even after an object was renamed (relabelled), the internal 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, many dialogs will display the first, followed by the user editable  in parentheses, for example,.
 * By default the is unique, just like the . However, this behavior can be changed in the preferences editor, . This means that in general the  is not unique in the document, and may actually be repeated. However, the recommendation is to keep the  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  of the object rather than its  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.

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.
 * In the tree view edit the field next to the icon, under "Description", by clicking on it and pressing.
 * You can also change this property by modifying the attribute from the Python console.
 * The attribute is normally hidden in the property editor but can be made visible by opening the context menu (right click) and selecting.

Scripting
FreeCAD Scripting Basics, and scripted objects.

Any object in the software is internally created with the 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.

Name
The function has two basic string arguments.


 * The first argument indicates the type of object, in this case,.
 * The second argument is a string that defines the attribute. If it is not provided, it defaults to the same name as the class of the object, that is,, where the two invalid symbols, the colons , are replaced by two underscores.
 * The can only include simple alphanumeric characters, and the underscore, . If other symbols are given, these will be converted to underscores; for example,  is converted to.
 * The cannot start with a number; it must start with a letter or the underscore, . For example,  is converted to.
 * The is fixed at creation time; it cannot be modified afterwards.
 * The must be unique in the entire document. If the same  is used, a sequential number will be appended automatically so that the resulting names are unique; for example, if  already exists, then new objects will be called, , , etc.

Label
The is a property of the created object and can be changed to a more meaningful text.
 * Upon creating the object, the is the same as the.
 * However, unlike the, the can accept any UTF8 string, including accents and spaces.
 * The can be changed at any point in time just by assigning the desired string,

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 of the object.

This is equivalent to using the method of the Document.

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

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