- The location of the documentation is improved (not in the cpp file
anymore but in core-app.dox). This prevents cluttering source with
high-level overviews typical of topic documentation.
- The formatting has been made consistent.
As described in Issue 16849, the existing Tools::getUniqueName method
requires calling code to form a vector of existing names to be avoided.
This leads to poor performance both in the O(n) cost of building such a
vector and also getUniqueName's O(n) algorithm for actually generating
the unique name (where 'n' is the number of pre-existing names).
This has particularly noticeable cost in documents with large numbers
of DocumentObjects because generating both Names and Labels for each new
object incurs this cost. During an operation such as importing this
results in an O(n^2) time spent generating names.
The other major cost is in the saving of the temporary backup file,
which uses name generation for the "files" embedded in the Zip file.
Documents can easily need several such "files" for each object in the
document.
This update includes the following changes to use the newly-added
UniqueNameManager as a replacement for the old Tools::getUniqueName
method and deletes the latter to remove any temptation to use it as
its usage model breeds inefficiency:
Eliminate Tools::getUniqueName, its local functions, and its unit tests.
Make DocumentObject naming use the new UniqueNameManager class.
Make DocumentObject Label naming use the new UniqueNameManager class.
This needs to monitor DocumentObject Labels for changes since this
property is not read-only. The special handling for the Label
property, which includes optionally forcing uniqueness and updating
links in referencing objects, has been mostly moved from
PropertyString to DocumentObject.
Add Document::containsObject(DocumentObject*) for a definitive
test of an object being in a Document. This is needed because
DocumentObjects can be in a sort of limbo (e.g. when they are in the
Undo/Redo lists) where they have a parent linkage to the Document but
should not participate in Label collision checks.
Rename Document.getStandardObjectName to getStandardObjectLabel
to better represent what it does.
Use new UniqueNameManager for Writer internal filenames within the zip
file.
Eliminate unneeded Reader::FileNames collection. The file names
already exist in the FileList collection elements. The only existing
use for the FileNames collection was to determine if there were any
files at all, and with FileList and FileNames being parallel
vectors, they both had the same length so FileList could be used
for this test..
Use UniqueNameManager for document names and labels. This uses ad hoc
UniqueNameManager objects created on the spot on the assumption that
document creation is relatively rare and there are few documents, so
although the cost is O(n), n itself is small.
Use an ad hoc UniqueNameManager to name new DymanicProperty entries.
This is only done if a property of the proposed name already exists,
since such a check is more-or-less O(log(n)), almost never finds a
collision, and avoids the O(n) building of the UniqueNameManager.
If there is a collision an ad-hoc UniqueNameManager is built
and discarded after use.
The property management classes have a bit of a mess of methods
including several to populate various collection types with all
existing properties. Rather than introducing yet another such
collection-specific method to fill a UniqueNameManager, a
visitProperties method was added which calls a passed function for
each property. The existing code (e.g. getPropertyMap) would be
simpler if they all used this but the cost of calling a lambda
for each property must be considered. It would clarify the semantics
of these methods, which have a bit of variance in which properties
populate the passed collection, e.g. when there are duplicate names..
Ideally the PropertyContainer class would keep a central directory of
all properties ("static", Dynamic, and exposed by ExtensionContainer and
other derivations) and a permanent UniqueNameManager. However the
Property management is a bit of a mess making such a change a project
unto itself.
* Address the poor performance of the existing unique-name generation
As described in Issue 16849, the existing Tools::getUniqueName method
requires calling code to form a vector of existing names to be avoided.
This leads to poor performance both in the O(n) cost of building such a
vector and also getUniqueName's O(n) algorithm for actually generating
the unique name (where 'n' is the number of pre-existing names).
This has particularly noticeable cost in documents with large numbers
of DocumentObjects because generating both Names and Labels for each new
object incurs this cost. During an operation such as importing this
results in an O(n^2) time spent generating names.
The other major cost is in the saving of the temporary backup file,
which uses name generation for the "files" embedded in the Zip file.
Documents can easily need several such "files" for each object in the
document.
This update includes the following changes:
Create UniqueNameManager to keep a list of existing names organized in
a manner that eases unique-name generation. This class essentially acts
as a set of names, with the ability to add and remove names and check if
a name is already there, with the added ability to take a prototype name
and generate a unique form for it which is not already in the set.
Eliminate Tools::getUniqueName
Make DocumentObject naming use the new UniqueNameManager class
Make DocumentObject Label naming use the new UniqueNameManager class.
Labels are not always unique; unique labels are generated if the
settings at the time request it (and other conditions). Because of this
the Label management requires additionally keeping a map of counts
for labels which already exist more than once.
These collections are maintained via notifications of value changes on
the Label properties of the objects in the document.
Add Document::containsObject(DocumentObject*) for a definitive
test of an object being in a Document. This is needed because
DocumentObjects can be in a sort of limbo (e.g. when they are in the
Undo/Redo lists) where they have a parent linkage to the Document but
should not participate in Label collision checks.
Rename Document.getStandardObjectName to getStandardObjectLabel
to better represent what it does.
Use new UniqueNameManager for Writer internal filenames within the zip
file.
Eliminate unneeded Reader::FileNames collection. The file names
already exist in the FileList collection elements. The only existing
use for the FileNames collection was to determine if there were any
files at all, and with FileList and FileNames being parallel
vectors, they both had the same length so FileList could be used
for this test..
Use UniqueNameManager for document names and labels. This uses ad hoc
UniqueNameManager objects created on the spot on the assumption that
document creation is relatively rare and there are few documents, so
although the cost is O(n), n itself is small.
Use an ad hoc UniqueNameManager to name new DymanicProperty entries.
This is only done if a property of the proposed name already exists,
since such a check is more-or-less O(log(n)), almost never finds a
collision, and avoids the O(n) building of the UniqueNameManager.
If there is a collision an ad-hoc UniqueNameManager is built
and discarded after use.
The property management classes have a bit of a mess of methods
including several to populate various collection types with all
existing properties. Rather than introducing yet another such
collection-specific method to fill a UniqueNameManager, a
visitProperties method was added which calls a passed function for
each property. The existing code would be simpler if existing
fill-container methods all used this.
Ideally the PropertyContainer class would keep a central directory of
all properties ("static", Dynamic, and exposed by ExtensionContainer and
other derivations) and a permanent UniqueNameManager. However the
Property management is a bit of a mess making such a change a project
unto itself.
The unit tests for Tools:getUniqueName have been changed to test
UniqueNameManager.makeUniqueName instead.
This revealed a small regression insofar as passing a prototype name
like "xyz1234" to the old code would yield "xyz1235" whether or
not "xyz1234" already existed, while the new code will return the next
name above the currently-highest name on the "xyz" model, which could
be "xyz" or "xyz1".
* Correct wrong case on include path
* Implement suggested code changes
Also change the semantics of visitProperties to not have any short-circuit return
* Remove reference through undefined iterator
* [pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
* Fix up some comments for DOxygen
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
==========================================================
Currently changes of name or type of properties in a property container are handled by:
void PropertyContainer::handleChangedPropertyName(Base::XMLReader &reader, const char * TypeName, const char *PropName)
void PropertyContainer::changedPropertyType(Base::XMLReader &reader, const char * TypeName, Property * prop)
There is no mechanism for handling property changes by extensions. Sometimes the solution is to explicitly call the extension
from the container. However, this is a breach of the SRP, as the container should not be in a position to decide whether the
extension needs or not handle property changes. The handling code of the container changes for two different reasons, for
adapting the container to a property change of its own, and for adapting that of a property of the extension.
Illustrating it with an example, following inheritance, it goes like this:
PropertyContainer => ExtensionContainer => TransactionalObject => ViewProvider
App::Extension => ViewProviderExtension
The extension is currently not notified by the ExtensionContainer that a property needs handling. So a change in a property of
a ViewProviderExtension needs code at the ViewProvider it was added to.
This commit provides a mechanism in ExtensionContainer to call the extensions so that they can handle property changes. This
functions:
virtual bool extensionHandleChangedPropertyName(Base::XMLReader &reader, const char * TypeName, const char *PropName);
virtual bool extensionHandleChangedPropertyType(Base::XMLReader &reader, const char * TypeName, Property * prop);
Containers should always call the base class for any unhandled property change. If a sub-class container of ExtensionContainer
handles property changes itself, but not the ones of the extensions, this call to the base class ultimately ensures that if the
property was not handled by the container hierarchy, any extension is given an opportunity to handle it.
Some examples:
* A container handles the extension property change or its own:
void ContainerSubClass::handleChangedPropertyType(...)
{
if (prop == &PropertyOfExt) {
}
else if (prop == &PropertyOfCont) {
}
else {
ContainerBaseClass::handleChangedPropertyType(...);
}
}
* A container and the extension handle their own:
void ContainerSubClass::handleChangedPropertyType(...)
{
if (prop == &PropertyOfCont) {
}
else {
// This will call ExtensionContainer::handleChangedPropertyType
ContainerBaseClass::handleChangedPropertyType(...);
}
}
bool ExtensionSubClass::extensionHandleChangedPropertyType(...)
{
if (prop == &PropertyOfCont) {
return true;
}
return false;
}
No longer add dynamic property for alias, simply rely on
get(Dynamic)PropertyByName() to check for aliases.
Add new API PropertyContainer::getPropertyNamedList() so that
ExpressionCompleter can discover properties with aliases.
Changes the way PropertyContainer handles existing property while
restoring. Previously it will first ask DynamicProperty to restore
if possible, then fallback to static property if else.
This patch looks up existing property first, and only fallback to
DynamicProperty if not found. This handles situation when an object
changes an originally dynamic property into a static one. With the
original code, it will add an auto renamed dynamic property that no
one knows its existence.
Found via `codespell -q 3 -L aci,ake,aline,alle,alledges,alocation,als,ang,anid,ba,beginn,behaviour,bloaded,byteorder,calculater,cancelled,cancelling,cas,cascade,centimetre,childs,colour,colours,commen,currenty,dof,doubleclick,dum,eiter,elemente,feld,freez,hist,iff,indicies,initialisation,initialise,initialised,initialises,initialisiert,ist,kilometre,lod,mantatory,methode,metres,millimetre,modell,nd,noe,normale,normaly,nto,numer,oder,orgin,orginx,orginy,ot,pard,pres,programm,que,recurrance,rougly,seperator,serie,sinc,strack,substraction,te,thist,thru,tread,uint,unter,vertexes,wallthickness,whitespaces -S ./.git,*.po,*.ts,./ChangeLog.txt,./src/3rdParty,./src/Mod/Assembly/App/opendcm,./src/CXX,./src/zipios++,./src/Base/swig*,./src/Mod/Robot/App/kdl_cp,./src/Mod/Import/App/SCL,./src/WindowsInstaller,./src/Doc/FreeCAD.uml`
Property:
* Extended property status bitset. Mirror most of PropertyType and
allow dynamic change property type.
* Cache property name and type to improve performance
* Centralize property status change signalling
* Change aboutToSetValue()/hasSetValue() to virtual
* Add new API getFullName() to obtain full quanlified name of the property
AtomicPropertyChangeInterface:
* Allow calling aboutToSetValue()/hasSetValue() when actually changed
PropertyLists:
* Refactor implementation by an abstract class PropertyListBase and a
template class PropertyListsT, to allow better code reuse.
PropertyListT is derived from AtomicPropertyChangeInterface to allow
more efficient change on individual elements.
* All list type property now accept setting python value as a dictionary
with index as key to set individual element of a list.
* Add touch list for more efficient handling of value changes. The list
contains the index of changed value. And empty touch list should be
treated as the entire list is changed. PropertyContainerPy expose this
functionality with getPropertyTouchList().
PropertyPersistentObject:
* New property to allow dynamic creation of any FreeCAD object derived
from Base::Persistence, and use it as a property.
DynamicProperty:
* Use boost multi_index_container for efficient property lookup while
keeping order.
* Modify to be allowed to use in PropertyContainer directly
PropertyContainer:
* Use boost multi_index_container for efficient property lookup while
keeping order.
* Allow adding/removing dynamic property on all property container
* Modify Save/Restore() to persist property status, and better handle
transient property which can now be dynamically enabled/disabled per
object.
* Add new API getFullName() to obtain full quanlified name of the property.
Implemented by Document, DocumentObject, and also
ViewProviderDocumentObject if future patch
DocumentObject and FeaturePython are modified to accommondate the
dynamic property changes.
Removed get/setCustomAttribute() implementation from DocumentObjectPy,
and rely on PropertyContainerPy for the implementation, because of the
additional dynamic property support in property container.
Gui::ViewProviderDocumentObject, which is derived from
PropertyContainer, is also modified accordingly
add a special XMLAttributeError class to indicate an error when accessing a missing attribute
in PropertyContainer::Restore make error handling more flexible
PropertyContainer uses a static member of type PropertyData to register
static properties. PropertyData uses a short variable to record the
offset of the property against its container.
Because of possible 'short' truncation, when searching of property that
in fact is from another container, we must check if the pointer within
boundary. Otherwise, truncation will result in effectively random
number, and possibly causing a false hit.
I'm still finding typos in the source code. I propose that you keep this PR open prior ro relaese and then merge so that if I find other typos in the meantime they will be part this release.
Due to problems onthe windows platform the virtual inheritance approach must be dropped. NExt to the already reimplemented proeprty interface the Type interface is reimplemented too. This change allows to revert some earlier changes.
FreeCADs property system utilises some pointer math to calculate the offset between
property and base class. Due to virtual inheritance of th ePropertyContainer the memory
layout has been changed to rather random, which has lead to crashes dependend on the
order of object initialisation.
The solution is to not make PropertyContaner virtual but a class below, Base::Persitance.
Then the memory layout is random for Persistance, but it is perfectly aligned for the
base class chains from PropertyContainer onwards as well as from Extension onwards.
Hence the proeprty system was changed to take the offset always from those two.
