0
# Lumino Widgets
1

2
Lumino Widgets is a comprehensive UI widget toolkit for building desktop-like web applications. It provides a flexible widget system with layout management, panels, menus, docking, tabs, and many other UI components for creating sophisticated user interfaces that mimic desktop application experiences in the browser.
3

4
## Package Information
5

6
- **Package Name**: @lumino/widgets
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Version**: 2.7.1
10
- **Installation**: `npm install @lumino/widgets`
11

12
## Core Imports
13

14
```typescript
15
import { Widget, BoxPanel, DockPanel, TabBar, MenuBar } from "@lumino/widgets";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { Widget, BoxPanel, DockPanel, TabBar, MenuBar } = require("@lumino/widgets");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { Widget, BoxPanel, DockPanel, TabPanel } from "@lumino/widgets";
28

29
// Create widgets
30
const widget1 = new Widget({ node: document.createElement('div') });
31
widget1.node.textContent = 'Widget 1';
32
widget1.title.label = 'First Widget';
33

34
const widget2 = new Widget({ node: document.createElement('div') });
35
widget2.node.textContent = 'Widget 2';
36
widget2.title.label = 'Second Widget';
37

38
// Create a tab panel to organize widgets
39
const tabPanel = new TabPanel();
40
tabPanel.addWidget(widget1);
41
tabPanel.addWidget(widget2);
42

43
// Create a dock panel for advanced layout
44
const dockPanel = new DockPanel();
45
dockPanel.addWidget(tabPanel);
46

47
// Attach to DOM
48
Widget.attach(dockPanel, document.body);
49
```
50

51
## Architecture
52

53
Lumino Widgets is built around several key architectural concepts:
54

55
- **Widget Hierarchy**: `Widget` is the base class for all UI components, providing lifecycle management, event handling, and DOM integration
56
- **Layout System**: Abstract `Layout` classes manage widget positioning and sizing within containers
57
- **Panel System**: Specialized containers (`Panel`, `BoxPanel`, `SplitPanel`, etc.) that combine widgets with specific layouts
58
- **Title System**: `Title` objects provide metadata (labels, icons, captions) for widgets in containers like tabs and menus
59
- **Message System**: Event-driven communication using the Lumino messaging system for lifecycle and user interaction events
60
- **Renderer Pattern**: Customizable rendering through renderer interfaces for consistent theming and extensibility
61

62
## Capabilities
63

64
### Widget Foundation
65

66
Core widget system providing the foundational classes for building UI components.
67

68
```typescript { .api }
69
class Widget {
70
  constructor(options?: Widget.IOptions);
71
  readonly node: HTMLElement;
72
  readonly isDisposed: boolean;
73
  readonly isAttached: boolean;
74
  readonly isHidden: boolean;
75
  readonly isVisible: boolean;
76
  readonly title: Title<Widget>;
77
  parent: Widget | null;
78
  layout: Layout | null;
79
  dispose(): void;
80
  show(): void;
81
  hide(): void;
82
  update(): void;
83
  fit(): void;
84
}
85

86
class Title<T> {
87
  constructor(options: Title.IOptions<T>);
88
  readonly owner: T;
89
  label: string;
90
  icon: VirtualElement.IRenderer | undefined;
91
  iconClass: string;
92
  caption: string;
93
  className: string;
94
  closable: boolean;
95
}
96

97
abstract class Layout {
98
  parent: Widget | null;
99
  readonly isDisposed: boolean;
100
  abstract dispose(): void;
101
  abstract widgets(): IterableIterator<Widget>;
102
  fit(): void;
103
  update(): void;
104
}
105
```
106

107
[Widget Foundation](./widget-foundation.md)
108

109
### Layout System
110

111
Flexible layout managers for organizing widgets with different arrangement patterns.
112

113
```typescript { .api }
114
class BoxLayout extends Layout {
115
  constructor(options?: BoxLayout.IOptions);
116
  direction: BoxLayout.Direction;
117
  alignment: BoxLayout.Alignment;
118
  spacing: number;
119
  insertWidget(index: number, widget: Widget): void;
120
  removeWidget(widget: Widget): void;
121
}
122

123
class GridLayout extends Layout {
124
  constructor(options?: GridLayout.IOptions);
125
  readonly rowCount: number;
126
  readonly columnCount: number;
127
  rowSpacing: number;
128
  columnSpacing: number;
129
}
130

131
class SplitLayout extends Layout {
132
  constructor(options: SplitLayout.IOptions);
133
  orientation: SplitLayout.Orientation;
134
  alignment: SplitLayout.Alignment;
135
  spacing: number;
136
  readonly handles: ReadonlyArray<HTMLDivElement>;
137
  setRelativeSizes(sizes: number[], update?: boolean): void;
138
}
139

140
class AccordionLayout extends SplitLayout {
141
  constructor(options?: AccordionLayout.IOptions);
142
  readonly renderer: AccordionLayout.IRenderer;
143
  titleSpace: number;
144
  collapse(index: number): void;
145
  expand(index: number): void;
146
  isExpanded(index: number): boolean;
147
}
148

149
class DockLayout extends Layout {
150
  constructor(options: DockLayout.IOptions);
151
  readonly renderer: DockLayout.IRenderer;
152
  spacing: number;
153
  readonly isEmpty: boolean;
154
  addWidget(widget: Widget, options?: DockLayout.IAddOptions): void;
155
  saveLayout(): DockLayout.ILayoutConfig;
156
  restoreLayout(config: DockLayout.ILayoutConfig): void;
157
}
158
```
159

160
[Layout System](./layouts.md)
161

162
### Panel Widgets
163

164
Container widgets that combine layout managers with widget collections for common UI patterns.
165

166
```typescript { .api }
167
class Panel extends Widget {
168
  constructor(options?: Panel.IOptions);
169
  readonly widgets: ReadonlyArray<Widget>;
170
  addWidget(widget: Widget): void;
171
  insertWidget(index: number, widget: Widget): void;
172
}
173

174
class BoxPanel extends Panel {
175
  constructor(options?: BoxPanel.IOptions);
176
  direction: BoxPanel.Direction;
177
  alignment: BoxPanel.Alignment;
178
  spacing: number;
179
}
180

181
class DockPanel extends Panel {
182
  constructor(options?: DockPanel.IOptions);
183
  readonly isEmpty: boolean;
184
  mode: DockPanel.Mode;
185
  tabsMovable: boolean;
186
  readonly selectedWidgets: ReadonlyArray<Widget>;
187
  readonly tabBars: ReadonlyArray<TabBar<Widget>>;
188
  addWidget(widget: Widget, options?: DockPanel.IAddOptions): void;
189
  saveLayout(): DockPanel.ILayoutConfig;
190
  restoreLayout(config: DockPanel.ILayoutConfig): void;
191
}
192

193
class TabPanel extends Panel {
194
  constructor(options?: TabPanel.IOptions);
195
  currentIndex: number;
196
  readonly currentWidget: Widget | null;
197
  tabsMovable: boolean;
198
  tabPlacement: TabPanel.TabPlacement;
199
  readonly tabBar: TabBar<Widget>;
200
}
201
```
202

203
[Panel Widgets](./panels.md)
204

205
### UI Components
206

207
Interactive UI components for user input and navigation.
208

209
```typescript { .api }
210
class MenuBar extends Widget {
211
  constructor(options?: MenuBar.IOptions);
212
  readonly activeMenu: Menu | null;
213
  activeIndex: number;
214
  readonly menus: ReadonlyArray<Menu>;
215
  addMenu(menu: Menu, update?: boolean): void;
216
  insertMenu(index: number, menu: Menu, update?: boolean): void;
217
  openActiveMenu(): void;
218
}
219

220
class TabBar<T> extends Widget {
221
  constructor(options?: TabBar.IOptions<T>);
222
  tabsMovable: boolean;
223
  titlesEditable: boolean;
224
  allowDeselect: boolean;
225
  currentTitle: Title<T> | null;
226
  currentIndex: number;
227
  orientation: TabBar.Orientation;
228
  readonly titles: ReadonlyArray<Title<T>>;
229
  addTab(value: Title<T> | Title.IOptions<T>): Title<T>;
230
  insertTab(index: number, value: Title<T> | Title.IOptions<T>): Title<T>;
231
}
232

233
class CommandPalette extends Widget {
234
  constructor(options: CommandPalette.IOptions);
235
  readonly commands: CommandRegistry;
236
  addItem(options: CommandPalette.IItemOptions): CommandPalette.IItem;
237
  removeItem(item: CommandPalette.IItem): void;
238
  refresh(): void;
239
}
240

241
class ScrollBar extends Widget {
242
  constructor(options?: ScrollBar.IOptions);
243
  orientation: ScrollBar.Orientation;
244
  value: number;
245
  page: number;
246
  maximum: number;
247
}
248
```
249

250
[UI Components](./components.md)
251

252
### Specialized Features
253

254
Advanced features for focus management, context menus, and other specialized functionality.
255

256
```typescript { .api }
257
class FocusTracker<T> implements IDisposable {
258
  constructor();
259
  readonly currentWidget: T | null;
260
  readonly activeWidget: T | null;
261
  readonly widgets: ReadonlyArray<T>;
262
  add(widget: T): void;
263
  remove(widget: T): void;
264
}
265

266
class ContextMenu {
267
  constructor(options: ContextMenu.IOptions);
268
  readonly menu: Menu;
269
  addItem(options: ContextMenu.IItemOptions): ContextMenu.IItem;
270
  open(event: MouseEvent | KeyboardEvent): boolean;
271
}
272

273
class Menu extends Widget {
274
  constructor(options: Menu.IOptions);
275
  readonly items: ReadonlyArray<Menu.IItem>;
276
  activeItem: Menu.IItem | null;
277
  activeIndex: number;
278
  addItem(options: Menu.IItemOptions): Menu.IItem;
279
  open(x: number, y: number, options?: Menu.IOpenOptions): boolean;
280
}
281
```
282

283
[Specialized Features](./specialized.md)
284

285
## Core Types
286

287
```typescript { .api }
288
namespace Widget {
289
  interface IOptions {
290
    node?: HTMLElement;
291
    tag?: keyof HTMLElementTagNameMap;
292
  }
293

294
  enum HiddenMode {
295
    Display = 0,
296
    Scale = 1,
297
    ContentVisibility = 2
298
  }
299

300
  enum Flag {
301
    IsDisposed = 0x1,
302
    IsAttached = 0x2,
303
    IsHidden = 0x4,
304
    IsVisible = 0x8,
305
    DisallowLayout = 0x10
306
  }
307

308
  class ResizeMessage {
309
    constructor(width: number, height: number);
310
    readonly width: number;
311
    readonly height: number;
312
  }
313

314
  class ChildMessage {
315
    constructor(type: string, child: Widget);
316
    readonly child: Widget;
317
  }
318

319
  // Static utility functions
320
  function attach(widget: Widget, host: HTMLElement, ref?: HTMLElement | null): void;
321
  function detach(widget: Widget): void;
322
}
323

324
namespace Title {
325
  interface IOptions<T> {
326
    owner: T;
327
    label?: string;
328
    mnemonic?: number;
329
    icon?: VirtualElement.IRenderer;
330
    iconClass?: string;
331
    iconLabel?: string;
332
    caption?: string;
333
    className?: string;
334
    closable?: boolean;
335
    dataset?: Dataset;
336
  }
337

338
  type Dataset = { readonly [key: string]: string };
339
}
340
```