0
# Application Core
1

2
The main Application class that orchestrates the entire pluggable application framework. It provides plugin management, service resolution, and application lifecycle control.
3

4
## Capabilities
5

6
### Application Constructor
7

8
Creates a new Application instance with the specified shell widget and configuration options.
9

10
```typescript { .api }
11
/**
12
 * Construct a new application.
13
 * @param options - The options for creating the application
14
 */
15
constructor(options: Application.IOptions<T>);
16

17
interface Application.IOptions<T extends Widget> extends PluginRegistry.IOptions {
18
  /** The shell widget to use for the application */
19
  shell: T;
20
  /** A custom renderer for the context menu */
21
  contextMenuRenderer?: Menu.IRenderer;
22
  /** Application plugin registry (if not provided, a new one will be created) */
23
  pluginRegistry?: PluginRegistry;
24
}
25
```
26

27
**Usage Example:**
28

29
```typescript
30
import { Application } from "@lumino/application";
31
import { Widget } from "@lumino/widgets";
32

33
// Basic application with default plugin registry
34
const shell = new Widget();
35
const app = new Application({ shell });
36

37
// Application with custom plugin registry
38
const customRegistry = new PluginRegistry();
39
const appWithCustomRegistry = new Application({
40
  shell,
41
  pluginRegistry: customRegistry
42
});
43
```
44

45
### Core Properties
46

47
The Application class provides several readonly properties that give access to key application components.
48

49
```typescript { .api }
50
/** The application command registry */
51
readonly commands: CommandRegistry;
52

53
/** The application context menu */
54
readonly contextMenu: ContextMenu;
55

56
/** The application shell widget */
57
readonly shell: T;
58

59
/** The list of all the deferred plugins */
60
readonly deferredPlugins: string[];
61

62
/** A promise which resolves after the application has started */
63
readonly started: Promise<void>;
64

65
/** Application plugin registry (protected - for subclasses) */
66
protected pluginRegistry: PluginRegistry;
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
// Access the command registry to register commands
73
app.commands.addCommand('my-command', {
74
  label: 'My Command',
75
  execute: () => console.log('Command executed!')
76
});
77

78
// Access the context menu to add items
79
app.contextMenu.addItem({
80
  command: 'my-command',
81
  selector: '.my-element'
82
});
83

84
// Wait for application startup
85
await app.started;
86
console.log('Application has started');
87

88
// Check deferred plugins
89
console.log('Deferred plugins:', app.deferredPlugins);
90
```
91

92
### Event Handling
93

94
The Application class implements the DOM EventListener interface to handle application-wide events.
95

96
```typescript { .api }
97
/**
98
 * Handle the DOM events for the application.
99
 * @param event - The DOM event sent to the application
100
 */
101
handleEvent(event: Event): void;
102
```
103

104
**Supported Events:**
105
- `resize`: Updates the shell widget when the window is resized
106
- `keydown`: Processes keyboard shortcuts through the command registry
107
- `keyup`: Processes key release events through the command registry  
108
- `contextmenu`: Opens the application context menu
109

110
**Usage Notes:**
111
- The `handleEvent` method is called automatically by the browser's event system
112
- You should not call this method directly - it's part of the EventListener interface
113
- Event listeners are automatically registered when the application starts
114

115
### Protected Methods
116

117
The Application class provides several protected methods that can be overridden in subclasses for custom behavior.
118

119
```typescript { .api }
120
/**
121
 * Attach the application shell to the DOM.
122
 * @param id - The ID of the host node for the shell, or empty string
123
 */
124
protected attachShell(id: string): void;
125

126
/**
127
 * Add the application event listeners.
128
 */
129
protected addEventListeners(): void;
130

131
/**
132
 * A method invoked on a document 'keydown' event.
133
 * @param event - The keyboard event
134
 */
135
protected evtKeydown(event: KeyboardEvent): void;
136

137
/**
138
 * A method invoked on a document 'keyup' event.  
139
 * @param event - The keyboard event
140
 */
141
protected evtKeyup(event: KeyboardEvent): void;
142

143
/**
144
 * A method invoked on a document 'contextmenu' event.
145
 * @param event - The pointer event
146
 */
147
protected evtContextMenu(event: PointerEvent): void;
148

149
/**
150
 * A method invoked on a window 'resize' event.
151
 * @param event - The resize event
152
 */
153
protected evtResize(event: Event): void;
154
```
155

156
**Customization Example:**
157

158
```typescript
159
class CustomApplication extends Application {
160
  protected attachShell(id: string): void {
161
    // Custom shell attachment logic
162
    console.log(`Attaching shell to ${id || 'document.body'}`);
163
    super.attachShell(id);
164
  }
165
  
166
  protected evtKeydown(event: KeyboardEvent): void {
167
    // Custom keydown handling
168
    if (event.key === 'F1') {
169
      console.log('Help requested');
170
      return;
171
    }
172
    super.evtKeydown(event);
173
  }
174
}
175
```