1 | /**
|
2 | * A type alias for a slot function.
|
3 | *
|
4 | * @param sender - The object emitting the signal.
|
5 | *
|
6 | * @param args - The args object emitted with the signal.
|
7 | *
|
8 | * #### Notes
|
9 | * A slot is invoked when a signal to which it is connected is emitted.
|
10 | */
|
11 | export declare type Slot<T, U> = (sender: T, args: U) => void;
|
12 | /**
|
13 | * An object used for type-safe inter-object communication.
|
14 | *
|
15 | * #### Notes
|
16 | * Signals provide a type-safe implementation of the publish-subscribe
|
17 | * pattern. An object (publisher) declares which signals it will emit,
|
18 | * and consumers connect callbacks (subscribers) to those signals. The
|
19 | * subscribers are invoked whenever the publisher emits the signal.
|
20 | */
|
21 | export interface ISignal<T, U> {
|
22 | /**
|
23 | * Block the signal during the execution of a callback.
|
24 | *
|
25 | * ### Notes
|
26 | * The callback function must be synchronous.
|
27 | *
|
28 | * @param fn The callback during which the signal is blocked
|
29 | */
|
30 | block(fn: () => void): void;
|
31 | /**
|
32 | * Connect a slot to the signal.
|
33 | *
|
34 | * @param slot - The slot to invoke when the signal is emitted.
|
35 | *
|
36 | * @param thisArg - The `this` context for the slot. If provided,
|
37 | * this must be a non-primitive object.
|
38 | *
|
39 | * @returns `true` if the connection succeeds, `false` otherwise.
|
40 | *
|
41 | * #### Notes
|
42 | * Slots are invoked in the order in which they are connected.
|
43 | *
|
44 | * Signal connections are unique. If a connection already exists for
|
45 | * the given `slot` and `thisArg`, this method returns `false`.
|
46 | *
|
47 | * A newly connected slot will not be invoked until the next time the
|
48 | * signal is emitted, even if the slot is connected while the signal
|
49 | * is dispatching.
|
50 | */
|
51 | connect(slot: Slot<T, U>, thisArg?: any): boolean;
|
52 | /**
|
53 | * Disconnect a slot from the signal.
|
54 | *
|
55 | * @param slot - The slot to disconnect from the signal.
|
56 | *
|
57 | * @param thisArg - The `this` context for the slot. If provided,
|
58 | * this must be a non-primitive object.
|
59 | *
|
60 | * @returns `true` if the connection is removed, `false` otherwise.
|
61 | *
|
62 | * #### Notes
|
63 | * If no connection exists for the given `slot` and `thisArg`, this
|
64 | * method returns `false`.
|
65 | *
|
66 | * A disconnected slot will no longer be invoked, even if the slot
|
67 | * is disconnected while the signal is dispatching.
|
68 | */
|
69 | disconnect(slot: Slot<T, U>, thisArg?: any): boolean;
|
70 | }
|
71 | /**
|
72 | * A concrete implementation of `ISignal`.
|
73 | *
|
74 | * #### Example
|
75 | * ```typescript
|
76 | * import { ISignal, Signal } from '@lumino/signaling';
|
77 | *
|
78 | * class SomeClass {
|
79 | *
|
80 | * constructor(name: string) {
|
81 | * this.name = name;
|
82 | * }
|
83 | *
|
84 | * readonly name: string;
|
85 | *
|
86 | * get valueChanged: ISignal<this, number> {
|
87 | * return this._valueChanged;
|
88 | * }
|
89 | *
|
90 | * get value(): number {
|
91 | * return this._value;
|
92 | * }
|
93 | *
|
94 | * set value(value: number) {
|
95 | * if (value === this._value) {
|
96 | * return;
|
97 | * }
|
98 | * this._value = value;
|
99 | * this._valueChanged.emit(value);
|
100 | * }
|
101 | *
|
102 | * private _value = 0;
|
103 | * private _valueChanged = new Signal<this, number>(this);
|
104 | * }
|
105 | *
|
106 | * function logger(sender: SomeClass, value: number): void {
|
107 | * console.log(sender.name, value);
|
108 | * }
|
109 | *
|
110 | * let m1 = new SomeClass('foo');
|
111 | * let m2 = new SomeClass('bar');
|
112 | *
|
113 | * m1.valueChanged.connect(logger);
|
114 | * m2.valueChanged.connect(logger);
|
115 | *
|
116 | * m1.value = 42; // logs: foo 42
|
117 | * m2.value = 17; // logs: bar 17
|
118 | * ```
|
119 | */
|
120 | export declare class Signal<T, U> implements ISignal<T, U> {
|
121 | /**
|
122 | * Construct a new signal.
|
123 | *
|
124 | * @param sender - The sender which owns the signal.
|
125 | */
|
126 | constructor(sender: T);
|
127 | /**
|
128 | * The sender which owns the signal.
|
129 | */
|
130 | readonly sender: T;
|
131 | /**
|
132 | * Block the signal during the execution of a callback.
|
133 | *
|
134 | * ### Notes
|
135 | * The callback function must be synchronous.
|
136 | *
|
137 | * @param fn The callback during which the signal is blocked
|
138 | */
|
139 | block(fn: () => void): void;
|
140 | /**
|
141 | * Connect a slot to the signal.
|
142 | *
|
143 | * @param slot - The slot to invoke when the signal is emitted.
|
144 | *
|
145 | * @param thisArg - The `this` context for the slot. If provided,
|
146 | * this must be a non-primitive object.
|
147 | *
|
148 | * @returns `true` if the connection succeeds, `false` otherwise.
|
149 | */
|
150 | connect(slot: Slot<T, U>, thisArg?: any): boolean;
|
151 | /**
|
152 | * Disconnect a slot from the signal.
|
153 | *
|
154 | * @param slot - The slot to disconnect from the signal.
|
155 | *
|
156 | * @param thisArg - The `this` context for the slot. If provided,
|
157 | * this must be a non-primitive object.
|
158 | *
|
159 | * @returns `true` if the connection is removed, `false` otherwise.
|
160 | */
|
161 | disconnect(slot: Slot<T, U>, thisArg?: any): boolean;
|
162 | /**
|
163 | * Emit the signal and invoke the connected slots.
|
164 | *
|
165 | * @param args - The args to pass to the connected slots.
|
166 | *
|
167 | * #### Notes
|
168 | * Slots are invoked synchronously in connection order.
|
169 | *
|
170 | * Exceptions thrown by connected slots will be caught and logged.
|
171 | */
|
172 | emit(args: U): void;
|
173 | private _blockedCount;
|
174 | }
|
175 | /**
|
176 | * The namespace for the `Signal` class statics.
|
177 | */
|
178 | export declare namespace Signal {
|
179 | /**
|
180 | * Block all signals emitted by an object during
|
181 | * the execution of a callback.
|
182 | *
|
183 | * ### Notes
|
184 | * The callback function must be synchronous.
|
185 | *
|
186 | * @param sender The signals sender
|
187 | * @param fn The callback during which all signals are blocked
|
188 | */
|
189 | function blockAll(sender: unknown, fn: () => void): void;
|
190 | /**
|
191 | * Remove all connections between a sender and receiver.
|
192 | *
|
193 | * @param sender - The sender object of interest.
|
194 | *
|
195 | * @param receiver - The receiver object of interest.
|
196 | *
|
197 | * #### Notes
|
198 | * If a `thisArg` is provided when connecting a signal, that object
|
199 | * is considered the receiver. Otherwise, the `slot` is considered
|
200 | * the receiver.
|
201 | */
|
202 | function disconnectBetween(sender: any, receiver: any): void;
|
203 | /**
|
204 | * Remove all connections where the given object is the sender.
|
205 | *
|
206 | * @param sender - The sender object of interest.
|
207 | */
|
208 | function disconnectSender(sender: any): void;
|
209 | /**
|
210 | * Remove all connections where the given object is the receiver.
|
211 | *
|
212 | * @param receiver - The receiver object of interest.
|
213 | *
|
214 | * #### Notes
|
215 | * If a `thisArg` is provided when connecting a signal, that object
|
216 | * is considered the receiver. Otherwise, the `slot` is considered
|
217 | * the receiver.
|
218 | */
|
219 | function disconnectReceiver(receiver: any): void;
|
220 | /**
|
221 | * Remove all connections where an object is the sender or receiver.
|
222 | *
|
223 | * @param object - The object of interest.
|
224 | *
|
225 | * #### Notes
|
226 | * If a `thisArg` is provided when connecting a signal, that object
|
227 | * is considered the receiver. Otherwise, the `slot` is considered
|
228 | * the receiver.
|
229 | */
|
230 | function disconnectAll(object: any): void;
|
231 | /**
|
232 | * Clear all signal data associated with the given object.
|
233 | *
|
234 | * @param object - The object for which the data should be cleared.
|
235 | *
|
236 | * #### Notes
|
237 | * This removes all signal connections and any other signal data
|
238 | * associated with the object.
|
239 | */
|
240 | function clearData(object: any): void;
|
241 | /**
|
242 | * A type alias for the exception handler function.
|
243 | */
|
244 | type ExceptionHandler = (err: Error) => void;
|
245 | /**
|
246 | * Get the signal exception handler.
|
247 | *
|
248 | * @returns The current exception handler.
|
249 | *
|
250 | * #### Notes
|
251 | * The default exception handler is `console.error`.
|
252 | */
|
253 | function getExceptionHandler(): ExceptionHandler;
|
254 | /**
|
255 | * Set the signal exception handler.
|
256 | *
|
257 | * @param handler - The function to use as the exception handler.
|
258 | *
|
259 | * @returns The old exception handler.
|
260 | *
|
261 | * #### Notes
|
262 | * The exception handler is invoked when a slot throws an exception.
|
263 | */
|
264 | function setExceptionHandler(handler: ExceptionHandler): ExceptionHandler;
|
265 | }
|
266 | //# sourceMappingURL=index.d.ts.map |
\ | No newline at end of file |