1 | // Copyright (c) Jupyter Development Team.
|
2 | // Distributed under the terms of the Modified BSD License.
|
3 | /*-----------------------------------------------------------------------------
|
4 | | Copyright (c) 2014-2017, PhosphorJS Contributors
|
5 | |
|
6 | | Distributed under the terms of the BSD 3-Clause License.
|
7 | |
|
8 | | The full license is in the file LICENSE, distributed with this software.
|
9 | |----------------------------------------------------------------------------*/
|
10 | import { ISignal, Signal } from '@lumino/signaling';
|
11 |
|
12 | import { VirtualElement } from '@lumino/virtualdom';
|
13 |
|
14 | /**
|
15 | * An object which holds data related to an object's title.
|
16 | *
|
17 | * #### Notes
|
18 | * A title object is intended to hold the data necessary to display a
|
19 | * header for a particular object. A common example is the `TabPanel`,
|
20 | * which uses the widget title to populate the tab for a child widget.
|
21 | */
|
22 | export class Title<T> {
|
23 | /**
|
24 | * Construct a new title.
|
25 | *
|
26 | * @param options - The options for initializing the title.
|
27 | */
|
28 | constructor(options: Title.IOptions<T>) {
|
29 | this.owner = options.owner;
|
30 | if (options.label !== undefined) {
|
31 | this._label = options.label;
|
32 | }
|
33 | if (options.mnemonic !== undefined) {
|
34 | this._mnemonic = options.mnemonic;
|
35 | }
|
36 | if (options.icon !== undefined) {
|
37 | /* <DEPRECATED> */
|
38 | if (typeof options.icon === 'string') {
|
39 | // when ._icon is null, the .icon getter will alias .iconClass
|
40 | this._icon = null;
|
41 | this._iconClass = options.icon;
|
42 | } else {
|
43 | /* </DEPRECATED> */
|
44 |
|
45 | this._icon = options.icon;
|
46 |
|
47 | /* <DEPRECATED> */
|
48 | }
|
49 | /* </DEPRECATED> */
|
50 | } else {
|
51 | /* <DEPRECATED> */
|
52 | // if unset, default to aliasing .iconClass
|
53 | this._icon = null;
|
54 | }
|
55 | /* </DEPRECATED> */
|
56 |
|
57 | if (options.iconClass !== undefined) {
|
58 | this._iconClass = options.iconClass;
|
59 | }
|
60 | if (options.iconLabel !== undefined) {
|
61 | this._iconLabel = options.iconLabel;
|
62 | }
|
63 | if (options.iconRenderer !== undefined) {
|
64 | this._icon = options.iconRenderer;
|
65 | }
|
66 | if (options.caption !== undefined) {
|
67 | this._caption = options.caption;
|
68 | }
|
69 | if (options.className !== undefined) {
|
70 | this._className = options.className;
|
71 | }
|
72 | if (options.closable !== undefined) {
|
73 | this._closable = options.closable;
|
74 | }
|
75 | this._dataset = options.dataset || {};
|
76 | }
|
77 |
|
78 | /**
|
79 | * A signal emitted when the state of the title changes.
|
80 | */
|
81 | get changed(): ISignal<this, void> {
|
82 | return this._changed;
|
83 | }
|
84 |
|
85 | /**
|
86 | * The object which owns the title.
|
87 | */
|
88 | readonly owner: T;
|
89 |
|
90 | /**
|
91 | * Get the label for the title.
|
92 | *
|
93 | * #### Notes
|
94 | * The default value is an empty string.
|
95 | */
|
96 | get label(): string {
|
97 | return this._label;
|
98 | }
|
99 |
|
100 | /**
|
101 | * Set the label for the title.
|
102 | */
|
103 | set label(value: string) {
|
104 | if (this._label === value) {
|
105 | return;
|
106 | }
|
107 | this._label = value;
|
108 | this._changed.emit(undefined);
|
109 | }
|
110 |
|
111 | /**
|
112 | * Get the mnemonic index for the title.
|
113 | *
|
114 | * #### Notes
|
115 | * The default value is `-1`.
|
116 | */
|
117 | get mnemonic(): number {
|
118 | return this._mnemonic;
|
119 | }
|
120 |
|
121 | /**
|
122 | * Set the mnemonic index for the title.
|
123 | */
|
124 | set mnemonic(value: number) {
|
125 | if (this._mnemonic === value) {
|
126 | return;
|
127 | }
|
128 | this._mnemonic = value;
|
129 | this._changed.emit(undefined);
|
130 | }
|
131 |
|
132 | /**
|
133 | * Get the icon renderer for the title.
|
134 | *
|
135 | * #### Notes
|
136 | * The default value is undefined.
|
137 | *
|
138 | * DEPRECATED: if set to a string value, the .icon field will function as
|
139 | * an alias for the .iconClass field, for backwards compatibility
|
140 | */
|
141 | get icon():
|
142 | | VirtualElement.IRenderer
|
143 | | undefined
|
144 | /* <DEPRECATED> */
|
145 | | string /* </DEPRECATED> */ {
|
146 | /* <DEPRECATED> */
|
147 | if (this._icon === null) {
|
148 | // only alias .iconClass if ._icon has been explicitly nulled
|
149 | return this.iconClass;
|
150 | }
|
151 | /* </DEPRECATED> */
|
152 |
|
153 | return this._icon;
|
154 | }
|
155 |
|
156 | /**
|
157 | * Set the icon renderer for the title.
|
158 | *
|
159 | * #### Notes
|
160 | * A renderer is an object that supplies a render and unrender function.
|
161 | *
|
162 | * DEPRECATED: if set to a string value, the .icon field will function as
|
163 | * an alias for the .iconClass field, for backwards compatibility
|
164 | */
|
165 | set icon(
|
166 | value:
|
167 | | VirtualElement.IRenderer
|
168 | | undefined
|
169 | /* <DEPRECATED> */
|
170 | | string /* </DEPRECATED> */
|
171 | ) {
|
172 | /* <DEPRECATED> */
|
173 | if (typeof value === 'string') {
|
174 | // when ._icon is null, the .icon getter will alias .iconClass
|
175 | this._icon = null;
|
176 | this.iconClass = value;
|
177 | } else {
|
178 | /* </DEPRECATED> */
|
179 |
|
180 | if (this._icon === value) {
|
181 | return;
|
182 | }
|
183 | this._icon = value;
|
184 | this._changed.emit(undefined);
|
185 |
|
186 | /* <DEPRECATED> */
|
187 | }
|
188 | /* </DEPRECATED> */
|
189 | }
|
190 |
|
191 | /**
|
192 | * Get the icon class name for the title.
|
193 | *
|
194 | * #### Notes
|
195 | * The default value is an empty string.
|
196 | */
|
197 | get iconClass(): string {
|
198 | return this._iconClass;
|
199 | }
|
200 |
|
201 | /**
|
202 | * Set the icon class name for the title.
|
203 | *
|
204 | * #### Notes
|
205 | * Multiple class names can be separated with whitespace.
|
206 | */
|
207 | set iconClass(value: string) {
|
208 | if (this._iconClass === value) {
|
209 | return;
|
210 | }
|
211 | this._iconClass = value;
|
212 | this._changed.emit(undefined);
|
213 | }
|
214 |
|
215 | /**
|
216 | * Get the icon label for the title.
|
217 | *
|
218 | * #### Notes
|
219 | * The default value is an empty string.
|
220 | */
|
221 | get iconLabel(): string {
|
222 | return this._iconLabel;
|
223 | }
|
224 |
|
225 | /**
|
226 | * Set the icon label for the title.
|
227 | *
|
228 | * #### Notes
|
229 | * Multiple class names can be separated with whitespace.
|
230 | */
|
231 | set iconLabel(value: string) {
|
232 | if (this._iconLabel === value) {
|
233 | return;
|
234 | }
|
235 | this._iconLabel = value;
|
236 | this._changed.emit(undefined);
|
237 | }
|
238 |
|
239 | /**
|
240 | * @deprecated Use `icon` instead.
|
241 | */
|
242 | get iconRenderer(): VirtualElement.IRenderer | undefined {
|
243 | return this._icon || undefined;
|
244 | }
|
245 |
|
246 | /**
|
247 | * @deprecated Use `icon` instead.
|
248 | */
|
249 | set iconRenderer(value: VirtualElement.IRenderer | undefined) {
|
250 | this.icon = value;
|
251 | }
|
252 |
|
253 | /**
|
254 | * Get the caption for the title.
|
255 | *
|
256 | * #### Notes
|
257 | * The default value is an empty string.
|
258 | */
|
259 | get caption(): string {
|
260 | return this._caption;
|
261 | }
|
262 |
|
263 | /**
|
264 | * Set the caption for the title.
|
265 | */
|
266 | set caption(value: string) {
|
267 | if (this._caption === value) {
|
268 | return;
|
269 | }
|
270 | this._caption = value;
|
271 | this._changed.emit(undefined);
|
272 | }
|
273 |
|
274 | /**
|
275 | * Get the extra class name for the title.
|
276 | *
|
277 | * #### Notes
|
278 | * The default value is an empty string.
|
279 | */
|
280 | get className(): string {
|
281 | return this._className;
|
282 | }
|
283 |
|
284 | /**
|
285 | * Set the extra class name for the title.
|
286 | *
|
287 | * #### Notes
|
288 | * Multiple class names can be separated with whitespace.
|
289 | */
|
290 | set className(value: string) {
|
291 | if (this._className === value) {
|
292 | return;
|
293 | }
|
294 | this._className = value;
|
295 | this._changed.emit(undefined);
|
296 | }
|
297 |
|
298 | /**
|
299 | * Get the closable state for the title.
|
300 | *
|
301 | * #### Notes
|
302 | * The default value is `false`.
|
303 | */
|
304 | get closable(): boolean {
|
305 | return this._closable;
|
306 | }
|
307 |
|
308 | /**
|
309 | * Set the closable state for the title.
|
310 | *
|
311 | * #### Notes
|
312 | * This controls the presence of a close icon when applicable.
|
313 | */
|
314 | set closable(value: boolean) {
|
315 | if (this._closable === value) {
|
316 | return;
|
317 | }
|
318 | this._closable = value;
|
319 | this._changed.emit(undefined);
|
320 | }
|
321 |
|
322 | /**
|
323 | * Get the dataset for the title.
|
324 | *
|
325 | * #### Notes
|
326 | * The default value is an empty dataset.
|
327 | */
|
328 | get dataset(): Title.Dataset {
|
329 | return this._dataset;
|
330 | }
|
331 |
|
332 | /**
|
333 | * Set the dataset for the title.
|
334 | *
|
335 | * #### Notes
|
336 | * This controls the data attributes when applicable.
|
337 | */
|
338 | set dataset(value: Title.Dataset) {
|
339 | if (this._dataset === value) {
|
340 | return;
|
341 | }
|
342 | this._dataset = value;
|
343 | this._changed.emit(undefined);
|
344 | }
|
345 |
|
346 | private _label = '';
|
347 | private _caption = '';
|
348 | private _mnemonic = -1;
|
349 |
|
350 | private _icon:
|
351 | | VirtualElement.IRenderer
|
352 | | undefined
|
353 | /* <DEPRECATED> */
|
354 | | null /* </DEPRECATED> */;
|
355 |
|
356 | private _iconClass = '';
|
357 | private _iconLabel = '';
|
358 | private _className = '';
|
359 | private _closable = false;
|
360 | private _dataset: Title.Dataset;
|
361 | private _changed = new Signal<this, void>(this);
|
362 | }
|
363 |
|
364 | /**
|
365 | * The namespace for the `Title` class statics.
|
366 | */
|
367 | export namespace Title {
|
368 | /**
|
369 | * A type alias for a simple immutable string dataset.
|
370 | */
|
371 | export type Dataset = { readonly [key: string]: string };
|
372 |
|
373 | /**
|
374 | * An options object for initializing a title.
|
375 | */
|
376 | export interface IOptions<T> {
|
377 | /**
|
378 | * The object which owns the title.
|
379 | */
|
380 | owner: T;
|
381 |
|
382 | /**
|
383 | * The label for the title.
|
384 | */
|
385 | label?: string;
|
386 |
|
387 | /**
|
388 | * The mnemonic index for the title.
|
389 | */
|
390 | mnemonic?: number;
|
391 |
|
392 | /**
|
393 | * The icon renderer for the title.
|
394 | *
|
395 | * DEPRECATED: if set to a string value, the .icon field will function as
|
396 | * an alias for the .iconClass field, for backwards compatibility
|
397 | */
|
398 | icon?: VirtualElement.IRenderer | string;
|
399 |
|
400 | /**
|
401 | * The icon class name for the title.
|
402 | */
|
403 | iconClass?: string;
|
404 |
|
405 | /**
|
406 | * The icon label for the title.
|
407 | */
|
408 | iconLabel?: string;
|
409 |
|
410 | /**
|
411 | * @deprecated Use `icon` instead.
|
412 | */
|
413 | iconRenderer?: VirtualElement.IRenderer;
|
414 |
|
415 | /**
|
416 | * The caption for the title.
|
417 | */
|
418 | caption?: string;
|
419 |
|
420 | /**
|
421 | * The extra class name for the title.
|
422 | */
|
423 | className?: string;
|
424 |
|
425 | /**
|
426 | * The closable state for the title.
|
427 | */
|
428 | closable?: boolean;
|
429 |
|
430 | /**
|
431 | * The dataset for the title.
|
432 | */
|
433 | dataset?: Dataset;
|
434 | }
|
435 | }
|