0
# Commands and Shortcuts
1

2
Command system integration providing keyboard shortcuts, menu access, and programmatic control of Visual Python functionality within JupyterLab.
3

4
## Capabilities
5

6
### Toggle Command
7

8
Main command for controlling Visual Python panel visibility.
9

10
```javascript { .api }
11
/**
12
 * Command for toggling Visual Python panel visibility
13
 * ID: 'jupyterlab-visualpython:toggle'
14
 */
15
'jupyterlab-visualpython:toggle': Command;
16
```
17

18
**Command Properties**:
19
- **ID**: `'jupyterlab-visualpython:toggle'`
20
- **Label**: "Toggle Visual Python"
21
- **Category**: "Visual Python"
22
- **Description**: Shows or hides the Visual Python panel in JupyterLab's right sidebar
23

24
**Execution Behavior**:
25
- If panel is visible: Hides the Visual Python panel
26
- If panel is hidden: Shows the Visual Python panel in right sidebar
27
- Automatically manages panel state and UI updates
28

29
**Usage Examples**:
30

31
```javascript
32
// Execute programmatically
33
app.commands.execute('jupyterlab-visualpython:toggle');
34

35
// Check if command is available
36
const isEnabled = app.commands.isEnabled('jupyterlab-visualpython:toggle');
37

38
// Get command label
39
const label = app.commands.label('jupyterlab-visualpython:toggle');
40
```
41

42
### Command Registration
43

44
Commands are registered during extension activation with the JupyterLab command registry.
45

46
```javascript { .api }
47
/**
48
 * Command registration during extension activation
49
 * @param app - JupyterLab application instance
50
 * @param vpPanel - Visual Python panel instance
51
 */
52
app.commands.addCommand('jupyterlab-visualpython:toggle', {
53
  label: 'Toggle Visual Python',
54
  execute: () => void
55
});
56
```
57

58
**Registration Process**:
59
1. Command added to application command registry
60
2. Execute function bound to panel visibility logic
61
3. Label and metadata configured for UI display
62
4. Command becomes available in palette and shortcuts
63

64
## Keyboard Shortcuts
65

66
### Primary Shortcut
67

68
Main keyboard shortcut for accessing Visual Python functionality.
69

70
```javascript { .api }
71
// Keyboard shortcut configuration
72
'Accel Shift V': 'jupyterlab-visualpython:toggle'
73
```
74

75
**Shortcut Details**:
76
- **Keys**: `Accel + Shift + V`
77
- **Platform Mapping**:
78
  - **Windows/Linux**: `Ctrl + Shift + V`
79
  - **macOS**: `Cmd + Shift + V`
80
- **Scope**: Global (works throughout JupyterLab interface)
81
- **Action**: Toggles Visual Python panel visibility
82

83
**Usage**: Press the keyboard combination from anywhere in JupyterLab to show/hide Visual Python panel.
84

85
### Shortcut Configuration
86

87
Keyboard shortcuts are defined in the plugin schema and automatically registered:
88

89
```json
90
{
91
  "shortcuts": [
92
    {
93
      "command": "jupyterlab-visualpython:toggle",
94
      "keys": ["Accel Shift V"],
95
      "selector": "body"
96
    }
97
  ]
98
}
99
```
100

101
## Command Palette Integration
102

103
### Palette Entry
104

105
Commands are automatically added to JupyterLab's command palette for easy access.
106

107
```javascript { .api }
108
/**
109
 * Command palette integration
110
 * @param palette - JupyterLab command palette
111
 */
112
palette.addItem({
113
  command: 'jupyterlab-visualpython:toggle',
114
  category: 'Visual Python'
115
});
116
```
117

118
**Palette Properties**:
119
- **Command**: `'jupyterlab-visualpython:toggle'`
120
- **Category**: "Visual Python"
121
- **Display**: "Toggle Visual Python"
122
- **Search Terms**: ["visual", "python", "toggle", "panel"]
123

124
**Access Method**:
125
1. Open command palette (`Ctrl/Cmd + Shift + C`)
126
2. Type "visual python" or "toggle"
127
3. Select "Toggle Visual Python" command
128
4. Press Enter to execute
129

130
## Toolbar Integration
131

132
### Notebook Toolbar
133

134
Visual Python integrates with the notebook toolbar for easy access during notebook editing.
135

136
```javascript { .api }
137
// Toolbar button configuration
138
{
139
  "command": "show-visualpython",
140
  "name": "show-visualpython"
141
}
142
```
143

144
**Toolbar Integration**:
145
- **Command**: "show-visualpython" (mapped to toggle command)
146
- **Button Label**: Shows Visual Python panel
147
- **Icon**: Visual Python logo/icon
148
- **Placement**: Notebook toolbar alongside other tools
149

150
**Usage**: Click the Visual Python toolbar button in notebooks to open the visual programming interface.
151

152
## Menu Integration
153

154
### Context Menus
155

156
Visual Python commands can be accessed through various context menus in JupyterLab.
157

158
```javascript { .api }
159
// Context menu integration (when applicable)
160
contextMenu.addItem({
161
  command: 'jupyterlab-visualpython:toggle',
162
  selector: '.jp-Notebook'
163
});
164
```
165

166
## Command Execution Context
167

168
### Panel State Management
169

170
Commands automatically manage Visual Python panel state:
171

172
```javascript { .api }
173
// Command execution logic
174
execute: () => {
175
  if (vpPanel.isVisible) {
176
    vpPanel.hide();
177
    app.shell.remove(vpPanel);
178
  } else {
179
    app.shell.add(vpPanel, 'right');
180
    vpPanel.show();
181
  }
182
}
183
```
184

185
**State Management**:
186
- **Show Panel**: Adds panel to right sidebar and makes visible
187
- **Hide Panel**: Removes panel from sidebar and hides interface
188
- **State Persistence**: Panel state maintained across JupyterLab sessions
189
- **UI Updates**: Toolbar and menu items reflect current panel state
190

191
### Error Handling
192

193
Commands include error handling for various failure scenarios:
194

195
```javascript
196
execute: () => {
197
  try {
198
    // Panel toggle logic
199
  } catch (error) {
200
    console.error('Failed to toggle Visual Python panel:', error);
201
    // User notification of error
202
  }
203
}
204
```
205

206
**Error Scenarios**:
207
- Panel creation failures
208
- DOM manipulation errors
209
- Resource loading issues
210
- Extension dependency problems
211

212
## Customization
213

214
### Command Extension
215

216
Developers can extend Visual Python commands:
217

218
```javascript { .api }
219
// Adding custom Visual Python commands
220
app.commands.addCommand('jupyterlab-visualpython:custom-action', {
221
  label: 'Custom Visual Python Action',
222
  execute: () => {
223
    // Custom functionality
224
  }
225
});
226
```
227

228
### Shortcut Customization
229

230
Users can customize keyboard shortcuts through JupyterLab settings:
231

232
```json
233
{
234
  "shortcuts": [
235
    {
236
      "command": "jupyterlab-visualpython:toggle",
237
      "keys": ["Ctrl Alt V"],
238
      "selector": "body"
239
    }
240
  ]
241
}
242
```
243

244
## Types
245

246
```typescript { .api }
247
// Command-related types
248
interface Command {
249
  execute(args?: any): Promise<any> | any;
250
  label?: string;
251
  caption?: string;
252
  usage?: string;
253
  iconClass?: string;
254
  iconLabel?: string;
255
  className?: string;
256
  isEnabled?(args?: any): boolean;
257
  isVisible?(args?: any): boolean;
258
  isToggled?(args?: any): boolean;
259
}
260

261
interface ICommandPalette {
262
  addItem(options: IPaletteItem): IDisposable;
263
}
264

265
interface IPaletteItem {
266
  command: string;
267
  category?: string;
268
  args?: any;
269
  rank?: number;
270
}
271
```