App::ObjectIdentifier Class Reference

#include <ObjectIdentifier.h>

Classes

class  Component
 A component is a part of a Path object, and is used to either name a property or a field within a property. More...
 
class  DocumentMapper
 
struct  ResolveResults
 
class  String
 

Public Types

typedef std::map< App::DocumentObject *, std::set< std::string > > Dependencies
 Type for storing dependency of an ObjectIdentifier. More...
 
typedef std::map< std::pair< App::DocumentObject *, std::string >, std::string > SubNameMap
 

Public Member Functions

void addComponent (Component &&c)
 
void addComponent (const Component &c)
 
template<typename C >
void addComponents (const C &cs)
 
bool adjustLinks (ExpressionVisitor &v, const std::set< App::DocumentObject * > &inList)
 
App::ObjectIdentifier canonicalPath () const
 Create a canonical representation of an object identifier. More...
 
 FC_DEFAULT_CTORS (ObjectIdentifier)
 
const std::vector< Component > & getComponents () const
 
Dependencies getDep (bool needProps, std::vector< std::string > *labels=nullptr) const
 Get dependencies of this object identifier. More...
 
void getDep (Dependencies &deps, bool needProps, std::vector< std::string > *labels=nullptr) const
 Get dependencies of this object identifier. More...
 
void getDepLabels (std::vector< std::string > &labels) const
 Returns all label references. More...
 
App::DocumentgetDocument (String name=String(), bool *ambiguous=nullptr) const
 Find a document with the given name. More...
 
String getDocumentName () const
 Get the document name from this object identifier. More...
 
App::DocumentObjectgetDocumentObject () const
 Get the document object for the object identifier. More...
 
String getDocumentObjectName () const
 Get the document object name. More...
 
App::DocumentObjectgetOwner () const
 
App::PropertygetProperty (int *ptype=nullptr) const
 Get pointer to property pointed to by this object identifier. More...
 
const ComponentgetPropertyComponent (int i, int *idx=nullptr) const
 Get Component at given index i. More...
 
std::vector< ComponentgetPropertyComponents () const
 
std::string getPropertyName () const
 Get the name of the property. More...
 
Py::Object getPyValue (bool pathValue=false, bool *isPseudoProperty=nullptr) const
 
std::vector< std::string > getStringList () const
 Get components as a string list. More...
 
const std::string & getSubObjectName () const
 
const std::string & getSubObjectName (bool newStyle) const
 
std::string getSubPathStr (bool toPython=false) const
 
App::any getValue (bool pathValue=false, bool *isPseudoProperty=nullptr) const
 Get the value of the property or field pointed to by this object identifier. More...
 
bool hasDocumentObjectName (bool forced=false) const
 
std::size_t hash () const
 
void importSubNames (const SubNameMap &subNameMap)
 
bool isLocalProperty () const
 
bool isTouched () const
 
int numComponents () const
 Return number of components. More...
 
int numSubComponents () const
 Compute number of sub components, i.e excluding the property. More...
 
 ObjectIdentifier (const App::Property &prop, int index=INT_MAX)
 Construct an ObjectIdentifier object given a property. More...
 
 ObjectIdentifier (const App::PropertyContainer *_owner, bool localProperty)
 
 ObjectIdentifier (const App::PropertyContainer *_owner=nullptr, const std::string &property=std::string(), int index=INT_MAX)
 Construct an ObjectIdentifier object, given an owner and a single-value property. More...
 
bool operator!= (const ObjectIdentifier &other) const
 Compare object identifier with other. More...
 
bool operator< (const ObjectIdentifier &other) const
 Compare object identifier with other. More...
 
App::ObjectIdentifieroperator<< (Component &&value)
 
App::ObjectIdentifieroperator<< (const Component &value)
 << operator, used to add a component to the object identifier. More...
 
bool operator== (const ObjectIdentifier &other) const
 Compare object identifier with other. More...
 
bool relabeledDocument (ExpressionVisitor &v, const std::string &oldLabel, const std::string &newLabel)
 
App::ObjectIdentifier relativeTo (const App::ObjectIdentifier &other) const
 Construct the simplest possible object identifier relative to another. More...
 
bool replaceObject (ObjectIdentifier &res, const App::DocumentObject *parent, App::DocumentObject *oldObj, App::DocumentObject *newObj) const
 
void resolveAmbiguity ()
 
std::string resolveErrorString () const
 
void setComponent (int idx, Component &&comp)
 
void setComponent (int idx, const Component &comp)
 
void setDocumentName (String &&name, bool force=false)
 Set the document name for this object identifier. More...
 
void setDocumentObjectName (const App::DocumentObject *obj, bool force=false, String &&subname=String(), bool checkImport=false)
 
void setDocumentObjectName (String &&name, bool force=false, String &&subname=String(), bool checkImport=false)
 Set the document object name of this object identifier. More...
 
void setValue (const App::any &value) const
 Set value of a property or field pointed to by this object identifier. More...
 
std::string toEscapedString () const
 Escape toString representation so it is suitable for being embedded in a python command. More...
 
std::string toPersistentString () const
 
const std::string & toString () const
 Create a string representation of this object identifier. More...
 
bool updateElementReference (ExpressionVisitor &v, App::DocumentObject *feature=nullptr, bool reverse=false)
 
bool updateLabelReference (App::DocumentObject *, const std::string &, const char *)
 
bool verify (const App::Property &prop, bool silent=false) const
 
virtual ~ObjectIdentifier ()
 

Static Public Member Functions

static Component ArrayComponent (int _index)
 
static Component MapComponent (const String &_key)
 
static Component MapComponent (String &&_key)
 
static ObjectIdentifier parse (const App::DocumentObject *docObj, const std::string &str)
 Parse a string to create an object identifier. More...
 
static Component RangeComponent (int _begin, int _end=INT_MAX, int _step=1)
 
static Component SimpleComponent (const char *_component)
 
static Component SimpleComponent (const String &_component)
 
static Component SimpleComponent (String &&_component)
 

Protected Member Functions

Py::Object access (const ResolveResults &rs, Py::Object *value=nullptr, Dependencies *deps=nullptr) const
 
void getDepLabels (const ResolveResults &result, std::vector< std::string > &labels) const
 
void getSubPathStr (std::ostream &ss, const ResolveResults &result, bool toPython=false) const
 Get sub field part of a property as a string. More...
 
void resolve (ResolveResults &results) const
 Resolve the object identifier to a concrete document, documentobject, and property. More...
 
void resolveAmbiguity (ResolveResults &results)
 
App::PropertyresolveProperty (const App::DocumentObject *obj, const char *propertyName, App::DocumentObject *&sobj, int &ptype) const
 

Static Protected Member Functions

static App::DocumentObjectgetDocumentObject (const App::Document *doc, const String &name, std::bitset< 32 > &flags)
 Search for the document object given by name in doc. More...
 

Protected Attributes

std::vector< Componentcomponents
 
String documentName
 
bool documentNameSet
 
String documentObjectName
 
bool documentObjectNameSet
 
bool localProperty
 
App::DocumentObjectowner
 
std::pair< std::string, std::string > shadowSub
 
String subObjectName
 

Friends

struct ResolveResults
 

Member Typedef Documentation

◆ Dependencies

typedef std::map<App::DocumentObject *, std::set<std::string> > App::ObjectIdentifier::Dependencies

Type for storing dependency of an ObjectIdentifier.

The dependency is a map from document object to a set of property names. An object identifier may references multiple objects using syntax like 'Part.Group[0].Width'.

Also, we use set of string instead of set of Property pointer, because the property may not exist at the time this ObjectIdentifier is constructed.

◆ SubNameMap

typedef std::map<std::pair<App::DocumentObject*,std::string>,std::string> App::ObjectIdentifier::SubNameMap

Constructor & Destructor Documentation

◆ ObjectIdentifier() [1/3]

ObjectIdentifier::ObjectIdentifier ( const App::PropertyContainer _owner = nullptr,
const std::string &  property = std::string(),
int  index = INT_MAX 
)

Construct an ObjectIdentifier object, given an owner and a single-value property.

Parameters
_ownerOwner of property.
propertyName of property.

References addComponent(), ArrayComponent(), owner, setDocumentObjectName(), and SimpleComponent().

◆ ObjectIdentifier() [2/3]

ObjectIdentifier::ObjectIdentifier ( const App::PropertyContainer _owner,
bool  localProperty 
)

References owner.

◆ ObjectIdentifier() [3/3]

ObjectIdentifier::ObjectIdentifier ( const App::Property prop,
int  index = INT_MAX 
)

Construct an ObjectIdentifier object given a property.

The property is assumed to be single-valued.

Parameters
propProperty to construct object identifier for.

References addComponent(), ArrayComponent(), App::Property::getContainer(), App::Property::getName(), App::Property::hasName(), owner, setDocumentObjectName(), and SimpleComponent().

◆ ~ObjectIdentifier()

virtual App::ObjectIdentifier::~ObjectIdentifier ( )
virtual

Member Function Documentation

◆ access()

Py::Object ObjectIdentifier::access ( const ResolveResults rs,
Py::Object *  value = nullptr,
Dependencies deps = nullptr 
) const
protected

◆ addComponent() [1/2]

void App::ObjectIdentifier::addComponent ( Component &&  c)

◆ addComponent() [2/2]

void App::ObjectIdentifier::addComponent ( const Component c)

Referenced by ObjectIdentifier().

◆ addComponents()

template<typename C >
void App::ObjectIdentifier::addComponents ( const C &  cs)

◆ adjustLinks()

◆ ArrayComponent()

static Component App::ObjectIdentifier::ArrayComponent ( int  _index)
static

◆ canonicalPath()

ObjectIdentifier ObjectIdentifier::canonicalPath ( ) const

Create a canonical representation of an object identifier.

The main work is actually done by the property's virtual canonicalPath(...) method, which is invoked by this call.

Returns
A new object identifier.

References owner.

◆ FC_DEFAULT_CTORS()

App::ObjectIdentifier::FC_DEFAULT_CTORS ( ObjectIdentifier  )

◆ getComponents()

const std::vector< Component > & App::ObjectIdentifier::getComponents ( ) const

◆ getDep() [1/2]

ObjectIdentifier::Dependencies ObjectIdentifier::getDep ( bool  needProps,
std::vector< std::string > *  labels = nullptr 
) const

Get dependencies of this object identifier.

Parameters
needPropswhether need property dependencies.
labelsoptional return of any label references.

In case of multi-object references, like 'Part.Group[0].Width', if no property dependency is required, then this function will only return the first referred object dependency. Or else, all object and property dependencies will be returned.

References getDep().

Referenced by getDep(), App::Expression::getDepObjects(), App::Expression::getDeps(), and App::PropertyExpressionEngine::hasSetValue().

◆ getDep() [2/2]

void ObjectIdentifier::getDep ( Dependencies deps,
bool  needProps,
std::vector< std::string > *  labels = nullptr 
) const

Get dependencies of this object identifier.

Parameters
depsreturns the dependencies.
needPropswhether need property dependencies.
labelsoptional return of any label references.

In case of multi-object references, like 'Part.Group[0].Width', if no property dependency is required, then this function will only return the first referred object dependency. Or else, all object and property dependencies will be returned.

References access(), and getDepLabels().

◆ getDepLabels() [1/2]

void ObjectIdentifier::getDepLabels ( const ResolveResults result,
std::vector< std::string > &  labels 
) const
protected

◆ getDepLabels() [2/2]

void ObjectIdentifier::getDepLabels ( std::vector< std::string > &  labels) const

Returns all label references.

References getDepLabels(), and ResolveResults.

Referenced by getDep(), and getDepLabels().

◆ getDocument()

Document * ObjectIdentifier::getDocument ( String  name = String(),
bool ambiguous = nullptr 
) const

Find a document with the given name.

Parameters
nameName of document
Returns
Pointer to document, or 0 if it is not found or not uniquely defined by name.

References App::GetApplication(), App::Application::getDocument(), getDocumentName(), and App::Application::getDocuments().

Referenced by getDocumentObject(), and resolve().

◆ getDocumentName()

ObjectIdentifier::String ObjectIdentifier::getDocumentName ( ) const

Get the document name from this object identifier.

Returns
Document name as a String object.

Referenced by getDocument().

◆ getDocumentObject() [1/2]

DocumentObject * ObjectIdentifier::getDocumentObject ( ) const

Get the document object for the object identifier.

Returns
Pointer to document object, or 0 if not found or uniquely defined.

References getDocument(), and getDocumentObject().

Referenced by Gui::InputField::bind(), App::ObjectIdentifier::String::checkImport(), SpreadsheetGui::DlgBindSheet::DlgBindSheet(), getDocumentObject(), resolve(), and App::PropertyExpressionEngine::validateExpression().

◆ getDocumentObject() [2/2]

App::DocumentObject * ObjectIdentifier::getDocumentObject ( const App::Document doc,
const String name,
std::bitset< 32 > &  flags 
)
staticprotected

Search for the document object given by name in doc.

Name might be the internal name or a label. In any case, it must uniquely define the document object.

Parameters
docDocument to search
nameName to search for.
Returns
Pointer to document object if a unique pointer is found, 0 otherwise.

◆ getDocumentObjectName()

ObjectIdentifier::String ObjectIdentifier::getDocumentObjectName ( ) const

Get the document object name.

Returns
String with name of document object as resolved by object identifier.

Referenced by Sketcher::SketchObject::carbonCopy().

◆ getOwner()

App::DocumentObject * App::ObjectIdentifier::getOwner ( ) const

Referenced by relativeTo().

◆ getProperty()

Property * ObjectIdentifier::getProperty ( int ptype = nullptr) const

Get pointer to property pointed to by this object identifier.

Returns
Point to property if it is uniquely defined, or 0 otherwise.

Referenced by Gui::ExpressionBinding::bind(), App::VariableExpression::getProperty(), and App::PropertyExpressionEngine::setValue().

◆ getPropertyComponent()

const App::ObjectIdentifier::Component & App::ObjectIdentifier::getPropertyComponent ( int  i,
int idx = nullptr 
) const

Get Component at given index i.

Parameters
iIndex to get
idxoptional return of adjusted component index
Returns
A component.

◆ getPropertyComponents()

std::vector< ObjectIdentifier::Component > ObjectIdentifier::getPropertyComponents ( ) const

◆ getPropertyName()

std::string App::ObjectIdentifier::getPropertyName ( ) const

Get the name of the property.

Returns
Name

◆ getPyValue()

◆ getStringList()

std::vector< std::string > ObjectIdentifier::getStringList ( ) const

◆ getSubObjectName() [1/2]

const std::string & ObjectIdentifier::getSubObjectName ( ) const

◆ getSubObjectName() [2/2]

const std::string & ObjectIdentifier::getSubObjectName ( bool  newStyle) const

◆ getSubPathStr() [1/2]

std::string ObjectIdentifier::getSubPathStr ( bool  toPython = false) const

◆ getSubPathStr() [2/2]

void ObjectIdentifier::getSubPathStr ( std::ostream &  s,
const ResolveResults result,
bool  toPython = false 
) const
protected

Get sub field part of a property as a string.

Returns
String representation of path.

◆ getValue()

App::any ObjectIdentifier::getValue ( bool  pathValue = false,
bool isPseudoProperty = nullptr 
) const

Get the value of the property or field pointed to by this object identifier.

All type of objects are supported. Some types are casted to FC native type, including: Int, Float, String, Unicode String, and Quantities. Others are just kept as Python object wrapped by App::any.

Parameters
pathValueif true, calls the property's getPathValue(), which is necessary for Qunatities to work.
Returns
The value of the property or field.

References access(), App::Property::getPathValue(), App::ExtensionContainer::getPropertyByName(), isLocalProperty(), owner, App::ObjectIdentifier::ResolveResults::propertyIndex, App::ObjectIdentifier::ResolveResults::propertyType, App::pyObjectToAny(), App::ObjectIdentifier::ResolveResults::resolvedProperty, and Base::PyException::ThrowException().

◆ hasDocumentObjectName()

bool ObjectIdentifier::hasDocumentObjectName ( bool  forced = false) const

◆ hash()

std::size_t ObjectIdentifier::hash ( ) const

References toString().

◆ importSubNames()

◆ isLocalProperty()

bool App::ObjectIdentifier::isLocalProperty ( ) const

◆ isTouched()

bool ObjectIdentifier::isTouched ( void  ) const

◆ MapComponent() [1/2]

static Component App::ObjectIdentifier::MapComponent ( const String _key)
static

◆ MapComponent() [2/2]

static Component App::ObjectIdentifier::MapComponent ( String &&  _key)
static

◆ numComponents()

int ObjectIdentifier::numComponents ( ) const

Return number of components.

Returns
Number of components in this identifier.

◆ numSubComponents()

int ObjectIdentifier::numSubComponents ( ) const

Compute number of sub components, i.e excluding the property.

Returns
Number of components.

◆ operator!=()

bool ObjectIdentifier::operator!= ( const ObjectIdentifier other) const

Compare object identifier with other.

Parameters
otherOther object identifier
Returns
true if they differ from each other.

◆ operator<()

bool ObjectIdentifier::operator< ( const ObjectIdentifier other) const

Compare object identifier with other.

Parameters
otherOther object identifier.
Returns
true if this object is less than the other.

References owner, and toString().

◆ operator<<() [1/2]

ObjectIdentifier & ObjectIdentifier::operator<< ( ObjectIdentifier::Component &&  value)

◆ operator<<() [2/2]

ObjectIdentifier & ObjectIdentifier::operator<< ( const Component value)

<< operator, used to add a component to the object identifier.

Parameters
valueComponent object
Returns
Reference to itself.

◆ operator==()

bool ObjectIdentifier::operator== ( const ObjectIdentifier other) const

Compare object identifier with other.

Parameters
otherOther object identifier.
Returns
true if they are equal.

References owner, and toString().

◆ parse()

ObjectIdentifier ObjectIdentifier::parse ( const App::DocumentObject docObj,
const std::string &  str 
)
static

◆ RangeComponent()

static Component App::ObjectIdentifier::RangeComponent ( int  _begin,
int  _end = INT_MAX,
int  _step = 1 
)
static

◆ relabeledDocument()

bool ObjectIdentifier::relabeledDocument ( ExpressionVisitor v,
const std::string &  oldLabel,
const std::string &  newLabel 
)

◆ relativeTo()

◆ replaceObject()

◆ resolve()

◆ resolveAmbiguity() [1/2]

◆ resolveAmbiguity() [2/2]

void ObjectIdentifier::resolveAmbiguity ( ResolveResults results)
protected

◆ resolveErrorString()

std::string ObjectIdentifier::resolveErrorString ( ) const

◆ resolveProperty()

Property * ObjectIdentifier::resolveProperty ( const App::DocumentObject obj,
const char *  propertyName,
App::DocumentObject *&  sobj,
int ptype 
) const
protected

◆ setComponent() [1/2]

void App::ObjectIdentifier::setComponent ( int  idx,
Component &&  comp 
)

◆ setComponent() [2/2]

void App::ObjectIdentifier::setComponent ( int  idx,
const Component comp 
)

◆ setDocumentName()

void ObjectIdentifier::setDocumentName ( ObjectIdentifier::String &&  name,
bool  force = false 
)

Set the document name for this object identifier.

If force is true, the document name will always be included in the string representation.

Parameters
nameName of document object.
forceForce name to be set

References documentName, documentNameSet, and draftfunctions.move::move().

Referenced by resolveAmbiguity(), and setDocumentObjectName().

◆ setDocumentObjectName() [1/2]

◆ setDocumentObjectName() [2/2]

void ObjectIdentifier::setDocumentObjectName ( ObjectIdentifier::String &&  name,
bool  force = false,
ObjectIdentifier::String &&  subname = String(),
bool  checkImport = false 
)

Set the document object name of this object identifier.

If force is true, the document object will not be resolved dynamically from the object identifier's components, but used as given by this method.

Parameters
nameName of document object.
forceForce name to be set.

References documentObjectName, documentObjectNameSet, draftfunctions.move::move(), owner, and subObjectName.

Referenced by ObjectIdentifier(), and resolveAmbiguity().

◆ setValue()

void ObjectIdentifier::setValue ( const App::any value) const

Set value of a property or field pointed to by this object identifier.

This method uses Python to do the actual work. and a limited set of types that can be in the App::any variable is supported: Base::Quantity, double, char*, const char*, int, unsigned int, short, unsigned short, char, and unsigned char.

Parameters
valueValue to set

References access(), App::ObjectIdentifier::ResolveResults::propertyType, App::pyObjectFromAny(), and Base::PyException::ThrowException().

◆ SimpleComponent() [1/3]

static Component App::ObjectIdentifier::SimpleComponent ( const char *  _component)
static

◆ SimpleComponent() [2/3]

static Component App::ObjectIdentifier::SimpleComponent ( const String _component)
static

◆ SimpleComponent() [3/3]

static Component App::ObjectIdentifier::SimpleComponent ( String &&  _component)
static

◆ toEscapedString()

std::string ObjectIdentifier::toEscapedString ( ) const

Escape toString representation so it is suitable for being embedded in a python command.

Returns
Escaped string.

References Base::Tools::escapedUnicodeFromUtf8(), and toString().

Referenced by Gui::ExpressionBinding::apply().

◆ toPersistentString()

◆ toString()

const std::string & ObjectIdentifier::toString ( ) const

Create a string representation of this object identifier.

An identifier is written as document::documentobject.property.subproperty1...subpropertyN document# may be dropped; it is assumed to be within owner's document. If documentobject is dropped, the property is assumed to be owned by the owner specified in the object identifiers constructor.

Returns
A string

References documentName, documentNameSet, documentObjectName, documentObjectNameSet, App::ObjectIdentifier::String::getString(), getSubPathStr(), localProperty, owner, subObjectName, and App::ObjectIdentifier::String::toString().

Referenced by access(), Gui::QuantitySpinBox::boundToName(), Sketcher::SketchObject::carbonCopy(), hash(), operator<(), operator==(), and toEscapedString().

◆ updateElementReference()

bool ObjectIdentifier::updateElementReference ( ExpressionVisitor v,
App::DocumentObject feature = nullptr,
bool  reverse = false 
)

◆ updateLabelReference()

◆ verify()

bool ObjectIdentifier::verify ( const App::Property prop,
bool  silent = false 
) const

Friends And Related Function Documentation

◆ ResolveResults

friend struct ResolveResults
friend

Referenced by getDepLabels(), and getSubPathStr().

Member Data Documentation

◆ components

std::vector<Component> App::ObjectIdentifier::components
protected

Referenced by getPropertyComponents().

◆ documentName

◆ documentNameSet

bool App::ObjectIdentifier::documentNameSet
protected

◆ documentObjectName

◆ documentObjectNameSet

bool App::ObjectIdentifier::documentObjectNameSet
protected

◆ localProperty

bool App::ObjectIdentifier::localProperty
protected

◆ owner

◆ shadowSub

std::pair<std::string,std::string> App::ObjectIdentifier::shadowSub
protected

◆ subObjectName


The documentation for this class was generated from the following files: