1 | /**
|
2 | * A class which attaches a value to an external object.
|
3 | *
|
4 | * #### Notes
|
5 | * Attached properties are used to extend the state of an object with
|
6 | * semantic data from an unrelated class. They also encapsulate value
|
7 | * creation, coercion, and notification.
|
8 | *
|
9 | * Because attached property values are stored in a hash table, which
|
10 | * in turn is stored in a WeakMap keyed on the owner object, there is
|
11 | * non-trivial storage overhead involved in their use. The pattern is
|
12 | * therefore best used for the storage of rare data.
|
13 | */
|
14 | export declare class AttachedProperty<T, U> {
|
15 | /**
|
16 | * Construct a new attached property.
|
17 | *
|
18 | * @param options - The options for initializing the property.
|
19 | */
|
20 | constructor(options: AttachedProperty.IOptions<T, U>);
|
21 | /**
|
22 | * The human readable name for the property.
|
23 | */
|
24 | readonly name: string;
|
25 | /**
|
26 | * Get the current value of the property for a given owner.
|
27 | *
|
28 | * @param owner - The property owner of interest.
|
29 | *
|
30 | * @returns The current value of the property.
|
31 | *
|
32 | * #### Notes
|
33 | * If the value has not yet been set, the default value will be
|
34 | * computed and assigned as the current value of the property.
|
35 | */
|
36 | get(owner: T): U;
|
37 | /**
|
38 | * Set the current value of the property for a given owner.
|
39 | *
|
40 | * @param owner - The property owner of interest.
|
41 | *
|
42 | * @param value - The value for the property.
|
43 | *
|
44 | * #### Notes
|
45 | * If the value has not yet been set, the default value will be
|
46 | * computed and used as the previous value for the comparison.
|
47 | */
|
48 | set(owner: T, value: U): void;
|
49 | /**
|
50 | * Explicitly coerce the current property value for a given owner.
|
51 | *
|
52 | * @param owner - The property owner of interest.
|
53 | *
|
54 | * #### Notes
|
55 | * If the value has not yet been set, the default value will be
|
56 | * computed and used as the previous value for the comparison.
|
57 | */
|
58 | coerce(owner: T): void;
|
59 | /**
|
60 | * Get or create the default value for the given owner.
|
61 | */
|
62 | private _createValue;
|
63 | /**
|
64 | * Coerce the value for the given owner.
|
65 | */
|
66 | private _coerceValue;
|
67 | /**
|
68 | * Compare the old value and new value for equality.
|
69 | */
|
70 | private _compareValue;
|
71 | /**
|
72 | * Run the change notification if the given values are different.
|
73 | */
|
74 | private _maybeNotify;
|
75 | private _pid;
|
76 | private _create;
|
77 | private _coerce;
|
78 | private _compare;
|
79 | private _changed;
|
80 | }
|
81 | /**
|
82 | * The namespace for the `AttachedProperty` class statics.
|
83 | */
|
84 | export declare namespace AttachedProperty {
|
85 | /**
|
86 | * The options object used to initialize an attached property.
|
87 | */
|
88 | interface IOptions<T, U> {
|
89 | /**
|
90 | * The human readable name for the property.
|
91 | *
|
92 | * #### Notes
|
93 | * By convention, this should be the same as the name used to define
|
94 | * the public accessor for the property value.
|
95 | *
|
96 | * This **does not** have an effect on the property lookup behavior.
|
97 | * Multiple properties may share the same name without conflict.
|
98 | */
|
99 | name: string;
|
100 | /**
|
101 | * A factory function used to create the default property value.
|
102 | *
|
103 | * #### Notes
|
104 | * This will be called whenever the property value is required,
|
105 | * but has not yet been set for a given owner.
|
106 | */
|
107 | create: (owner: T) => U;
|
108 | /**
|
109 | * A function used to coerce a supplied value into the final value.
|
110 | *
|
111 | * #### Notes
|
112 | * This will be called whenever the property value is changed, or
|
113 | * when the property is explicitly coerced. The return value will
|
114 | * be used as the final value of the property.
|
115 | *
|
116 | * This will **not** be called for the initial default value.
|
117 | */
|
118 | coerce?: (owner: T, value: U) => U;
|
119 | /**
|
120 | * A function used to compare two values for equality.
|
121 | *
|
122 | * #### Notes
|
123 | * This is called to determine if the property value has changed.
|
124 | * It should return `true` if the given values are equivalent, or
|
125 | * `false` if they are different.
|
126 | *
|
127 | * If this is not provided, it defaults to the `===` operator.
|
128 | */
|
129 | compare?: (oldValue: U, newValue: U) => boolean;
|
130 | /**
|
131 | * A function called when the property value has changed.
|
132 | *
|
133 | * #### Notes
|
134 | * This will be invoked when the property value is changed and the
|
135 | * comparator indicates that the old value is not equal to the new
|
136 | * value.
|
137 | *
|
138 | * This will **not** be called for the initial default value.
|
139 | */
|
140 | changed?: (owner: T, oldValue: U, newValue: U) => void;
|
141 | }
|
142 | /**
|
143 | * Clear the stored property data for the given owner.
|
144 | *
|
145 | * @param owner - The property owner of interest.
|
146 | *
|
147 | * #### Notes
|
148 | * This will clear all property values for the owner, but it will
|
149 | * **not** run the change notification for any of the properties.
|
150 | */
|
151 | function clearData(owner: any): void;
|
152 | }
|