LabRPS: Created page with "== Introduction == {{TOCright}} 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 ({{incode|App::DocumentObject}} class), which essentially comprises all objects that are possible to create in a document. == Names == There are various properties for Names: * The {{incode|Name}} can only include simple alphan..."

2024-10-28T14:04:57Z

Created page with "== Introduction == {{TOCright}} 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 ({{incode|App::DocumentObject}} class), which essentially comprises all objects that are possible to create in a document. == Names == There are various properties for Names: * The {{incode|Name}} can only include simple alphan..."

New page

== Introduction ==

{{TOCright}}

All objects in the program have an [[Object_name|object name]] that uniquely identifies them in a given document.

This information applies to all objects derived from [[App_DocumentObject|App DocumentObject]] ({{incode|App::DocumentObject}} class), which essentially comprises all objects that are possible to create in a document.

== Names ==

There are various properties for Names:
* The {{incode|Name}} can only include simple alphanumeric characters, and the underscore, {{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]}}.
* The {{incode|Name}} is assigned at the creation time of the object; afterwards it is no longer editable. The object can never be renamed.
* The {{incode|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 {{incode|Sim}}, {{incode|Sim001}}, {{incode|Sim002}}, etc. This prevents naming collision.
* Once the object is deleted, its {{incode|Name}} becomes available to be used by a newly created object. This means that if {{incode|Sim}}, {{incode|Sim001}}, and {{incode|BSim002}} exist, and we delete the first item, the next sim created will not be {{incode|Sim003}}, it will be {{incode|Sim}} again, because this string is available to be used once more. Notice that it is not possible to rename {{incode|Sim001}} or {{incode|Sim002}} to {{incode|Sim}} since their names are fixed.

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.

== Labels ==

There are various properties for Labels:
* 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 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.
* 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|Sim (Wind Simulation)}}.
* 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 ===

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}} (or rather {{KEY|Return}} on macOS).
* 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}}.

== Scripting ==

{{Emphasis|See also:}} [[LabRPS_Scripting_Basics|LabRPS Scripting Basics]], and [[Scripted_objects|scripted objects]].

Any object in the software is internally created with the {{incode|addObject()}} method of the document.

{{Code|code=
import LabRPS as App

doc = App.newDocument()
obj = doc.addObject("WindLab::Simulation", "Name")
obj.Label = "Custom label"
}}

=== Name ===

The {{incode|addObject}} function has two basic string arguments.

* The first argument indicates the type of object, in this case, {{incode|"WindLab::Simulation"}}.
* The second argument is a string that defines the {{incode|Name}} attribute. If it is not provided, it defaults to the same name as the class of the object, that is, {{incode|"WindLab_Simulation"}}, where the two invalid symbols, the colons {{incode|::}}, are replaced by two underscores {{incode|__}}.
** The {{incode|Name}} can only include simple alphanumeric characters, and the underscore, {{incode|[_0-9a-zA-Z]}}. If other symbols are given, these will be converted to underscores; for example, {{incode|"A+B:C*"}} is converted to {{incode|"A_B_C_"}}.
** The {{incode|Name}} cannot start with a number; it must start with a letter or the underscore, {{incode|[_a-zA-Z]}}. For example, {{incode|"123ABC"}} is converted to {{incode|"_23ABC"}}.
** The {{incode|Name}} is fixed at creation time; it cannot be modified afterwards.
** 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 ===

The {{incode|Label}} is a property of the created object and can be changed to a more meaningful text.
* Upon creating the object, the {{incode|Label}} is the same as the {{incode|Name}}.
* However, unlike the {{incode|Name}}, the {{incode|Label}} can accept any UTF8 string, including accents and spaces.
* The {{incode|Label}} can be changed at any point in time just by assigning the desired string, <code>obj.Label = "New label"</code>

=== Getting an object by Name or Label ===

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=
import LabRPS as App

obj1 = App.ActiveDocument.Sim
obj2 = App.ActiveDocument.Sim001
obj3 = App.ActiveDocument.Sim002
}}

This is equivalent to using the {{incode|getObject}} method of the Document.
{{Code|code=
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 {{incode|Label}}.
{{Code|code=
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 {{incode|Label}} is in general not unique, the {{incode|getObjectsByLabel}} method returns a list with all objects found with that {{incode|Label}}. However, if the {{incode|Label}} is unique in the document then the first element in that list should be the desired object.

{{Userdocnavi}}

Object name - Revision history