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 | * Connect a slot to the signal.
|
24 | *
|
25 | * @param slot - The slot to invoke when the signal is emitted.
|
26 | *
|
27 | * @param thisArg - The `this` context for the slot. If provided,
|
28 | * this must be a non-primitive object.
|
29 | *
|
30 | * @returns `true` if the connection succeeds, `false` otherwise.
|
31 | *
|
32 | * #### Notes
|
33 | * Slots are invoked in the order in which they are connected.
|
34 | *
|
35 | * Signal connections are unique. If a connection already exists for
|
36 | * the given `slot` and `thisArg`, this method returns `false`.
|
37 | *
|
38 | * A newly connected slot will not be invoked until the next time the
|
39 | * signal is emitted, even if the slot is connected while the signal
|
40 | * is dispatching.
|
41 | */
|
42 | connect(slot: Slot<T, U>, thisArg?: any): boolean;
|
43 | /**
|
44 | * Disconnect a slot from the signal.
|
45 | *
|
46 | * @param slot - The slot to disconnect from the signal.
|
47 | *
|
48 | * @param thisArg - The `this` context for the slot. If provided,
|
49 | * this must be a non-primitive object.
|
50 | *
|
51 | * @returns `true` if the connection is removed, `false` otherwise.
|
52 | *
|
53 | * #### Notes
|
54 | * If no connection exists for the given `slot` and `thisArg`, this
|
55 | * method returns `false`.
|
56 | *
|
57 | * A disconnected slot will no longer be invoked, even if the slot
|
58 | * is disconnected while the signal is dispatching.
|
59 | */
|
60 | disconnect(slot: Slot<T, U>, thisArg?: any): boolean;
|
61 | }
|
62 | /**
|
63 | * A concrete implementation of `ISignal`.
|
64 | *
|
65 | * #### Example
|
66 | * ```typescript
|
67 | * import { ISignal, Signal } from '@phosphor/signaling';
|
68 | *
|
69 | * class SomeClass {
|
70 | *
|
71 | * constructor(name: string) {
|
72 | * this.name = name;
|
73 | * }
|
74 | *
|
75 | * readonly name: string;
|
76 | *
|
77 | * get valueChanged: ISignal<this, number> {
|
78 | * return this._valueChanged;
|
79 | * }
|
80 | *
|
81 | * get value(): number {
|
82 | * return this._value;
|
83 | * }
|
84 | *
|
85 | * set value(value: number) {
|
86 | * if (value === this._value) {
|
87 | * return;
|
88 | * }
|
89 | * this._value = value;
|
90 | * this._valueChanged.emit(value);
|
91 | * }
|
92 | *
|
93 | * private _value = 0;
|
94 | * private _valueChanged = new Signal<this, number>(this);
|
95 | * }
|
96 | *
|
97 | * function logger(sender: SomeClass, value: number): void {
|
98 | * console.log(sender.name, value);
|
99 | * }
|
100 | *
|
101 | * let m1 = new SomeClass('foo');
|
102 | * let m2 = new SomeClass('bar');
|
103 | *
|
104 | * m1.valueChanged.connect(logger);
|
105 | * m2.valueChanged.connect(logger);
|
106 | *
|
107 | * m1.value = 42; // logs: foo 42
|
108 | * m2.value = 17; // logs: bar 17
|
109 | * ```
|
110 | */
|
111 | export declare class Signal<T, U> implements ISignal<T, U> {
|
112 | /**
|
113 | * Construct a new signal.
|
114 | *
|
115 | * @param sender - The sender which owns the signal.
|
116 | */
|
117 | constructor(sender: T);
|
118 | /**
|
119 | * The sender which owns the signal.
|
120 | */
|
121 | readonly sender: T;
|
122 | /**
|
123 | * Connect a slot to the signal.
|
124 | *
|
125 | * @param slot - The slot to invoke when the signal is emitted.
|
126 | *
|
127 | * @param thisArg - The `this` context for the slot. If provided,
|
128 | * this must be a non-primitive object.
|
129 | *
|
130 | * @returns `true` if the connection succeeds, `false` otherwise.
|
131 | */
|
132 | connect(slot: Slot<T, U>, thisArg?: any): boolean;
|
133 | /**
|
134 | * Disconnect a slot from the signal.
|
135 | *
|
136 | * @param slot - The slot to disconnect from the signal.
|
137 | *
|
138 | * @param thisArg - The `this` context for the slot. If provided,
|
139 | * this must be a non-primitive object.
|
140 | *
|
141 | * @returns `true` if the connection is removed, `false` otherwise.
|
142 | */
|
143 | disconnect(slot: Slot<T, U>, thisArg?: any): boolean;
|
144 | /**
|
145 | * Emit the signal and invoke the connected slots.
|
146 | *
|
147 | * @param args - The args to pass to the connected slots.
|
148 | *
|
149 | * #### Notes
|
150 | * Slots are invoked synchronously in connection order.
|
151 | *
|
152 | * Exceptions thrown by connected slots will be caught and logged.
|
153 | */
|
154 | emit(args: U): void;
|
155 | }
|
156 | /**
|
157 | * The namespace for the `Signal` class statics.
|
158 | */
|
159 | export declare namespace Signal {
|
160 | /**
|
161 | * Remove all connections between a sender and receiver.
|
162 | *
|
163 | * @param sender - The sender object of interest.
|
164 | *
|
165 | * @param receiver - The receiver object of interest.
|
166 | *
|
167 | * #### Notes
|
168 | * If a `thisArg` is provided when connecting a signal, that object
|
169 | * is considered the receiver. Otherwise, the `slot` is considered
|
170 | * the receiver.
|
171 | */
|
172 | function disconnectBetween(sender: any, receiver: any): void;
|
173 | /**
|
174 | * Remove all connections where the given object is the sender.
|
175 | *
|
176 | * @param sender - The sender object of interest.
|
177 | */
|
178 | function disconnectSender(sender: any): void;
|
179 | /**
|
180 | * Remove all connections where the given object is the receiver.
|
181 | *
|
182 | * @param receiver - The receiver object of interest.
|
183 | *
|
184 | * #### Notes
|
185 | * If a `thisArg` is provided when connecting a signal, that object
|
186 | * is considered the receiver. Otherwise, the `slot` is considered
|
187 | * the receiver.
|
188 | */
|
189 | function disconnectReceiver(receiver: any): void;
|
190 | /**
|
191 | * Remove all connections where an object is the sender or receiver.
|
192 | *
|
193 | * @param object - The object of interest.
|
194 | *
|
195 | * #### Notes
|
196 | * If a `thisArg` is provided when connecting a signal, that object
|
197 | * is considered the receiver. Otherwise, the `slot` is considered
|
198 | * the receiver.
|
199 | */
|
200 | function disconnectAll(object: any): void;
|
201 | /**
|
202 | * Clear all signal data associated with the given object.
|
203 | *
|
204 | * @param object - The object for which the data should be cleared.
|
205 | *
|
206 | * #### Notes
|
207 | * This removes all signal connections and any other signal data
|
208 | * associated with the object.
|
209 | */
|
210 | function clearData(object: any): void;
|
211 | /**
|
212 | * A type alias for the exception handler function.
|
213 | */
|
214 | type ExceptionHandler = (err: Error) => void;
|
215 | /**
|
216 | * Get the signal exception handler.
|
217 | *
|
218 | * @returns The current exception handler.
|
219 | *
|
220 | * #### Notes
|
221 | * The default exception handler is `console.error`.
|
222 | */
|
223 | function getExceptionHandler(): ExceptionHandler;
|
224 | /**
|
225 | * Set the signal exception handler.
|
226 | *
|
227 | * @param handler - The function to use as the exception handler.
|
228 | *
|
229 | * @returns The old exception handler.
|
230 | *
|
231 | * #### Notes
|
232 | * The exception handler is invoked when a slot throws an exception.
|
233 | */
|
234 | function setExceptionHandler(handler: ExceptionHandler): ExceptionHandler;
|
235 | }
|