Nazwa obiektu

From FreeCAD Documentation
Revision as of 14:33, 28 October 2023 by Kaktus (talk | contribs) (Created page with "{{Emphasis|Zobacz również:}} Podstawy tworzenia skryptów FreeCAD, oraz Obiekty skryptowe.")

Wprowadzenie

Wszystkie obiekty w programie mają nazwę obiektu, która jednoznacznie identyfikuje je w obrębie danego dokumentu.

Informacje te dotyczą wszystkich obiektów pochodnych od App: Obiektu dokumentu (klasa App::DocumentObject), która zasadniczo obejmuje wszystkie obiekty, które można utworzyć w dokumencie.

Nazwy

Nazwy mają różne właściwości:

  • Nazwa może zawierać tylko proste znaki alfanumeryczne i znak podkreślenia, [_0-9a-zA-Z].
  • Nazwa nie może zaczynać się od cyfry, musi zaczynać się od litery lub podkreślenia, [_a-zA-Z].
  • Nazwa jest przypisywana w czasie tworzenia obiektu, później nie można jej już edytować. Nigdy nie można zmienić nazwy obiektu.
  • Nazwa musi być unikalna w całym dokumencie. Nie ma znaczenia, czy dwa obiekty są zupełnie różnych typów, na przykład jeden to kieszeń środowiska Projekt Części, a drugi to ściana środowiska Architektura. Muszą one mieć różne nazwy.
  • Podczas tworzenia obiektu tego samego typu, zwykle nazwa jest zwiększana o kolejny numer, a więc Sześcian, Sześcian001, Sześcian002 itd. Zapobiega to kolizji nazw.
  • Po usunięciu obiektu, jego Nazwa staje się dostępna do użycia przez nowo utworzony obiekt. Oznacza to, że jeśli istnieją obiekty Sześcian, Sześcian001 i Sześcian002, a my usuniemy pierwszy z nich, to następnym obiektem utworzonym za pomocą Part Box nie będzie Sześcian003, lecz Sześcian, ponieważ ciąg ten jest dostępny do ponownego użycia. Zauważ, że nie jest możliwa zmiana nazwy obiektu Sześcian001 lub Sześcian002 na Sześcian, ponieważ ich nazwy są niezmienne.

Podsumowując, Nazwa zasadniczo działa jak unikalny identyfikator (UID) dla obiektu. Ponieważ unikalna Nazwa jest bardzo restrykcyjna, wszystkie obiekty mają również właściwość Etykieta, która umożliwia "zmianę nazwy" obiektu na coś bardziej opisowego. Wewnętrzna Nazwa faktycznie pozostaje stała, ale edytowalna przez użytkownika Etykieta może być używana w większości sytuacji, w których użyto by Nazwy. W powszechnym użyciu w programie i dokumentacji "zmiana nazwy" oznacza zmianę Etykiety, a nie rzeczywistej Nazwy obiektu.

Etykiety

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

Etykieta2

Jest to prosty ciąg znaków, który może zawierać dowolny tekst, a zatem może być używany do dokumentowania (opisywania z większą ilością szczegółów) utworzonego obiektu.

  • W oknie widoku drzewa edytuj pole obok ikony, w kolumnie "Opis", klikając je i naciskając F2 (lub raczej Entern na macOS).
  • Można również zmienić tę właściwość, modyfikując atrybut Etykieta2 z poziomu Konsoli Python.
  • Atrybut DANEEtykieta2 jest normalnie ukryty w edytorze właściwości, ale może być uwidoczniony poprzez otwarcie menu podręcznego (kliknięcie prawym przyciskiem myszy) i wybranie Wyświetl wszystko.

Tworzenie skryptów

Zobacz również: Podstawy tworzenia skryptów FreeCAD, oraz Obiekty skryptowe.

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.

Etykieta

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.