import defined from "../Core/defined.js";
import DeveloperError from "../Core/DeveloperError.js";
import Event from "../Core/Event.js";
import Property from "./Property.js";
function resolve(that) {
let targetProperty = that._targetProperty;
if (!defined(targetProperty)) {
let targetEntity = that._targetEntity;
if (!defined(targetEntity)) {
targetEntity = that._targetCollection.getById(that._targetId);
if (!defined(targetEntity)) {
// target entity not found
that._targetEntity = that._targetProperty = undefined;
return;
}
// target entity was found. listen for changes to entity definition
targetEntity.definitionChanged.addEventListener(
ReferenceProperty.prototype._onTargetEntityDefinitionChanged,
that
);
that._targetEntity = targetEntity;
}
// walk the list of property names and resolve properties
const targetPropertyNames = that._targetPropertyNames;
targetProperty = that._targetEntity;
for (
let i = 0, len = targetPropertyNames.length;
i < len && defined(targetProperty);
++i
) {
targetProperty = targetProperty[targetPropertyNames[i]];
}
// target property may or may not be defined, depending on if it was found
that._targetProperty = targetProperty;
}
return targetProperty;
}
/**
* A {@link Property} which transparently links to another property on a provided object.
*
* @alias ReferenceProperty
* @constructor
*
* @param {EntityCollection} targetCollection The entity collection which will be used to resolve the reference.
* @param {string} targetId The id of the entity which is being referenced.
* @param {string[]} targetPropertyNames The names of the property on the target entity which we will use.
*
* @example
* const collection = new Cesium.EntityCollection();
*
* //Create a new entity and assign a billboard scale.
* const object1 = new Cesium.Entity({id:'object1'});
* object1.billboard = new Cesium.BillboardGraphics();
* object1.billboard.scale = new Cesium.ConstantProperty(2.0);
* collection.add(object1);
*
* //Create a second entity and reference the scale from the first one.
* const object2 = new Cesium.Entity({id:'object2'});
* object2.model = new Cesium.ModelGraphics();
* object2.model.scale = new Cesium.ReferenceProperty(collection, 'object1', ['billboard', 'scale']);
* collection.add(object2);
*
* //Create a third object, but use the fromString helper function.
* const object3 = new Cesium.Entity({id:'object3'});
* object3.billboard = new Cesium.BillboardGraphics();
* object3.billboard.scale = Cesium.ReferenceProperty.fromString(collection, 'object1#billboard.scale');
* collection.add(object3);
*
* //You can refer to an entity with a # or . in id and property names by escaping them.
* const object4 = new Cesium.Entity({id:'#object.4'});
* object4.billboard = new Cesium.BillboardGraphics();
* object4.billboard.scale = new Cesium.ConstantProperty(2.0);
* collection.add(object4);
*
* const object5 = new Cesium.Entity({id:'object5'});
* object5.billboard = new Cesium.BillboardGraphics();
* object5.billboard.scale = Cesium.ReferenceProperty.fromString(collection, '\\#object\\.4#billboard.scale');
* collection.add(object5);
*/
function ReferenceProperty(targetCollection, targetId, targetPropertyNames) {
//>>includeStart('debug', pragmas.debug);
if (!defined(targetCollection)) {
throw new DeveloperError("targetCollection is required.");
}
if (!defined(targetId) || targetId === "") {
throw new DeveloperError("targetId is required.");
}
if (!defined(targetPropertyNames) || targetPropertyNames.length === 0) {
throw new DeveloperError("targetPropertyNames is required.");
}
for (let i = 0; i < targetPropertyNames.length; i++) {
const item = targetPropertyNames[i];
if (!defined(item) || item === "") {
throw new DeveloperError("reference contains invalid properties.");
}
}
//>>includeEnd('debug');
this._targetCollection = targetCollection;
this._targetId = targetId;
this._targetPropertyNames = targetPropertyNames;
this._targetProperty = undefined;
this._targetEntity = undefined;
this._definitionChanged = new Event();
targetCollection.collectionChanged.addEventListener(
ReferenceProperty.prototype._onCollectionChanged,
this
);
}
Object.defineProperties(ReferenceProperty.prototype, {
/**
* Gets a value indicating if this property is constant.
* @memberof ReferenceProperty.prototype
* @type {boolean}
* @readonly
*/
isConstant: {
get: function () {
return Property.isConstant(resolve(this));
},
},
/**
* Gets the event that is raised whenever the definition of this property changes.
* The definition is changed whenever the referenced property's definition is changed.
* @memberof ReferenceProperty.prototype
* @type {Event}
* @readonly
*/
definitionChanged: {
get: function () {
return this._definitionChanged;
},
},
/**
* Gets the reference frame that the position is defined in.
* This property is only valid if the referenced property is a {@link PositionProperty}.
* @memberof ReferenceProperty.prototype
* @type {ReferenceFrame}
* @readonly
*/
referenceFrame: {
get: function () {
const target = resolve(this);
return defined(target) ? target.referenceFrame : undefined;
},
},
/**
* Gets the id of the entity being referenced.
* @memberof ReferenceProperty.prototype
* @type {string}
* @readonly
*/
targetId: {
get: function () {
return this._targetId;
},
},
/**
* Gets the collection containing the entity being referenced.
* @memberof ReferenceProperty.prototype
* @type {EntityCollection}
* @readonly
*/
targetCollection: {
get: function () {
return this._targetCollection;
},
},
/**
* Gets the array of property names used to retrieve the referenced property.
* @memberof ReferenceProperty.prototype
* @type {}
* @readonly
*/
targetPropertyNames: {
get: function () {
return this._targetPropertyNames;
},
},
/**
* Gets the resolved instance of the underlying referenced property.
* @memberof ReferenceProperty.prototype
* @type {Property|undefined}
* @readonly
*/
resolvedProperty: {
get: function () {
return resolve(this);
},
},
});
/**
* Creates a new instance given the entity collection that will
* be used to resolve it and a string indicating the target entity id and property.
* The format of the string is "objectId#foo.bar", where # separates the id from
* property path and . separates sub-properties. If the reference identifier or
* or any sub-properties contains a # . or \ they must be escaped.
*
* @param {EntityCollection} targetCollection
* @param {string} referenceString
* @returns {ReferenceProperty} A new instance of ReferenceProperty.
*
* @exception {DeveloperError} invalid referenceString.
*/
ReferenceProperty.fromString = function (targetCollection, referenceString) {
//>>includeStart('debug', pragmas.debug);
if (!defined(targetCollection)) {
throw new DeveloperError("targetCollection is required.");
}
if (!defined(referenceString)) {
throw new DeveloperError("referenceString is required.");
}
//>>includeEnd('debug');
let identifier;
const values = [];
let inIdentifier = true;
let isEscaped = false;
let token = "";
for (let i = 0; i < referenceString.length; ++i) {
const c = referenceString.charAt(i);
if (isEscaped) {
token += c;
isEscaped = false;
} else if (c === "\\") {
isEscaped = true;
} else if (inIdentifier && c === "#") {
identifier = token;
inIdentifier = false;
token = "";
} else if (!inIdentifier && c === ".") {
values.push(token);
token = "";
} else {
token += c;
}
}
values.push(token);
return new ReferenceProperty(targetCollection, identifier, values);
};
/**
* Gets the value of the property at the provided time.
*
* @param {JulianDate} time The time for which to retrieve the value.
* @param {object} [result] The object to store the value into, if omitted, a new instance is created and returned.
* @returns {object} The modified result parameter or a new instance if the result parameter was not supplied.
*/
ReferenceProperty.prototype.getValue = function (time, result) {
const target = resolve(this);
return defined(target) ? target.getValue(time, result) : undefined;
};
/**
* Gets the value of the property at the provided time and in the provided reference frame.
* This method is only valid if the property being referenced is a {@link PositionProperty}.
*
* @param {JulianDate} time The time for which to retrieve the value.
* @param {ReferenceFrame} referenceFrame The desired referenceFrame of the result.
* @param {Cartesian3} [result] The object to store the value into, if omitted, a new instance is created and returned.
* @returns {Cartesian3} The modified result parameter or a new instance if the result parameter was not supplied.
*/
ReferenceProperty.prototype.getValueInReferenceFrame = function (
time,
referenceFrame,
result
) {
const target = resolve(this);
return defined(target)
? target.getValueInReferenceFrame(time, referenceFrame, result)
: undefined;
};
/**
* Gets the {@link Material} type at the provided time.
* This method is only valid if the property being referenced is a {@link MaterialProperty}.
*
* @param {JulianDate} time The time for which to retrieve the type.
* @returns {string} The type of material.
*/
ReferenceProperty.prototype.getType = function (time) {
const target = resolve(this);
return defined(target) ? target.getType(time) : undefined;
};
/**
* Compares this property to the provided property and returns
* true
if they are equal, false
otherwise.
*
* @param {Property} [other] The other property.
* @returns {boolean} true
if left and right are equal, false
otherwise.
*/
ReferenceProperty.prototype.equals = function (other) {
if (this === other) {
return true;
}
const names = this._targetPropertyNames;
const otherNames = other._targetPropertyNames;
if (
this._targetCollection !== other._targetCollection || //
this._targetId !== other._targetId || //
names.length !== otherNames.length
) {
return false;
}
const length = this._targetPropertyNames.length;
for (let i = 0; i < length; i++) {
if (names[i] !== otherNames[i]) {
return false;
}
}
return true;
};
ReferenceProperty.prototype._onTargetEntityDefinitionChanged = function (
targetEntity,
name,
value,
oldValue
) {
if (defined(this._targetProperty) && this._targetPropertyNames[0] === name) {
this._targetProperty = undefined;
this._definitionChanged.raiseEvent(this);
}
};
ReferenceProperty.prototype._onCollectionChanged = function (
collection,
added,
removed
) {
let targetEntity = this._targetEntity;
if (defined(targetEntity) && removed.indexOf(targetEntity) !== -1) {
targetEntity.definitionChanged.removeEventListener(
ReferenceProperty.prototype._onTargetEntityDefinitionChanged,
this
);
this._targetEntity = this._targetProperty = undefined;
} else if (!defined(targetEntity)) {
targetEntity = resolve(this);
if (defined(targetEntity)) {
this._definitionChanged.raiseEvent(this);
}
}
};
export default ReferenceProperty;