Properties & Parameters

Relevant source files

The following files were used as context for generating this wiki page:

• src/App/PropertyContainer.h
• src/App/Property.cpp
• src/App/DynamicProperty.cpp
• src/App/PropertyExpressionEngine.cpp
• src/Mod/Assembly/Gui/Resources/translations/Assembly.ts
• src/Mod/BIM/Resources/translations/Arch_af.ts

The "Properties & Parameters" system serves as the foundational data management framework within Parashell. It provides a structured way to define, store, and manipulate data fields (properties) associated with document objects. This system supports a wide range of functionalities, including data persistence, graphical user interface integration, and a powerful expression engine for parametric relationships.

At its core, the system allows objects to expose their internal state through typed properties. These properties are managed by containers that handle change notifications, multi-language support (via translation files), and dynamic property addition at runtime. This architecture ensures that any change in a parameter can automatically trigger updates across dependent features, maintaining the parametric integrity of the design.

Sources: src/App/PropertyContainer.h:87-95, src/App/Property.cpp:35-50

Architecture and Components

Property Containers

A PropertyContainer is the base class for all objects that hold properties. It manages the collection of both static properties (defined at compile-time) and dynamic properties (added at runtime). The container provides the interface for finding properties by name, accessing property metadata (groups, documentation), and managing the persistence of these properties to XML.

Property Types and Metadata

Properties are defined with specific types that determine their behavior in the editor and during file operations. These are controlled via the PropertyType enumeration.

Flag	Description
Prop_None	Default behavior.
Prop_ReadOnly	The property cannot be modified in the UI editor.
Prop_Hidden	The property is not visible in the UI editor.
Prop_Transient	Content is not saved to file, but name and type are preserved.
Prop_Output	Modification does not "touch" the parent container.
Prop_NoRecompute	Modification does not trigger a recomputation of the object.
Prop_NoPersist	The property is entirely excluded from file saving.

Sources: src/App/PropertyContainer.h:60-84

Property Management Logic

Static vs. Dynamic Properties

Static properties are typically defined in C++ using macros like ADD_PROPERTY within the object's constructor. Dynamic properties, managed by the DynamicProperty class, allow for runtime expansion of an object's parameter set. This is crucial for features like custom attributes in BIM or assembly joints where parameters depend on user-selected geometry.

Change Notification System

The system implements a callback mechanism to handle property modifications. When a property value changes, it invokes onBeforeChange() and onChanged() on the container. This allows objects to react to parameter updates, such as recalculating geometry or updating dependent links.

Sources: src/App/Property.cpp:115-130, src/App/PropertyContainer.h:565-580

Expression Engine Integration

The PropertyExpressionEngine allows properties to be driven by formulas instead of static values. This enables complex parametric dependencies where one parameter can be calculated based on others (e.g., Height = Width * 1.5).

Key functionalities include:

• Formula Parsing: Evaluates mathematical expressions and references to other objects.
• Dependency Tracking: Ensures that if a source property changes, all dependent expressions are re-evaluated.
• Path Resolution: Supports resolving complex paths like Object.Constraints.Length.

Sources: src/App/PropertyExpressionEngine.cpp:50-85, src/App/Property.cpp:250-270

Translation and Localization

Properties often include human-readable strings for groups and documentation. The project uses .ts files to translate these metadata elements into various languages, ensuring that the property editor is accessible to global users.

Location	Context	Source Content Example
src/Mod/Assembly/...	App::Property	"The type of the joint"
src/Mod/BIM/...	App::Property	"The intervals between axes"

Sources: src/Mod/Assembly/Gui/Resources/translations/Assembly.ts:183-200, src/Mod/BIM/Resources/translations/Arch_af.ts:10-25

Implementation Example: Adding a Property

Developers add properties to classes derived from PropertyContainer using the following pattern:

// Inside a DocumentObject derived class
App::PropertyFloat Length;

// Inside the constructor
ADD_PROPERTY_TYPE(Length, (10.0), "Dimensions", App::Prop_None, "The length of the block");

Sources: src/App/PropertyContainer.h:605-615

The property system ensures that "Length" is automatically registered for UI display, XML serialization, and use within the Expression Engine.

Sources: src/App/Property.cpp:200-220, src/App/PropertyContainer.h:200-210