Object name
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 (App::DocumentObject
class), which essentially comprises all objects that are possible to create in a document.
Names
There are various properties for Names:
- The
Name
can only include simple alphanumeric characters, and the underscore,[_0-9a-zA-Z]
. - The
Name
cannot start with a number; it must start with a letter or the underscore,[_a-zA-Z]
. - The
Name
is assigned at the creation time of the object; afterwards it is no longer editable. The object can never be renamed. - The
Name
must be unique in the entire document. - When creating an object of the same type, normally the name is increased with a sequential number, thus
Sim
,Sim001
,Sim002
, etc. This prevents naming collision. - Once the object is deleted, its
Name
becomes available to be used by a newly created object. This means that ifSim
,Sim001
, andBSim002
exist, and we delete the first item, the next sim created will not beSim003
, it will beSim
again, because this string is available to be used once more. Notice that it is not possible to renameSim001
orSim002
toSim
since their names are fixed.
In summary, the Name
essentially acts like a unique identifier (UID) for an object. Since a unique Name
is very restrictive, all objects also have a Label
property which allows "renaming" the object to something more descriptive. The internal Name
actually remains fixed, but the user editable Label
can be used in most situations where the Name
would be used. In common usage in the program and the documentation, "renaming" means changing the Label
and not the actual Name
of the object.
Labels
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 theName
. Therefore, whenever a new object is created, it is a good practice to change theLabel
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 theName
first, followed by the user editableLabel
in parentheses, for example,Sim (Wind Simulation)
. - By default the
Label
is unique, just like theName
. 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 theLabel
is not unique in the document, and may actually be repeated. However, the recommendation is to keep theLabel
unique, as this is probably what is most useful to identify different objects. When writing custom functions that manipulate objects, the methods should use theName
of the object rather than itsLabel
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 DataLabel2 attribute is normally hidden in the property editor but can be made visible by opening the context menu (right click) and selecting Show all.
Scripting
See also: LabRPS Scripting Basics, and scripted objects.
Any object in the software is internally created with the addObject()
method of the document.
import LabRPS as App doc = App.newDocument() obj = doc.addObject("WindLab::Simulation", "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,
"WindLab::Simulation"
. - 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,"WindLab_Simulation"
, 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.
- The
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 theName
. - However, unlike the
Name
, theLabel
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 LabRPS as App obj1 = App.ActiveDocument.Sim obj2 = App.ActiveDocument.Sim001 obj3 = App.ActiveDocument.Sim002
This is equivalent to using the getObject
method of the Document.
import LabRPS as App obj1 = App.ActiveDocument.getObject('Sim') obj2 = App.ActiveDocument.getObject('Sim001') obj3 = App.ActiveDocument.getObject('Sim002')
However, it is also possible to get the object by the more descriptive Label
.
import LabRPS as App obj1 = App.ActiveDocument.getObjectsByLabel("Simulation of wind on the south building")[0] obj2 = App.ActiveDocument.getObjectsByLabel("Cable-stayed bridge wind simulation")[0] obj3 = App.ActiveDocument.getObjectsByLabel("Wind for buffeting analyis")[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.
- Getting started
- Installation: Download, Windows, Linux, Mac, Additional components, AppImage
- Basics: About LabRPS, Interface, RPS Objects, Object name, Preferences, Workbenches, Document structure, Properties, Help LabRPS, Donate
- Help: Tutorials, Video tutorials
- Workbenches: Std Base, WindLab, SeismicLab, SeaLab, UserLab, Spreadsheet, Plot, Web
- Hubs: User hub, Power users hub, Developer hub