0
# Terminal Control
1

2
Terminal control capabilities provide low-level access to cursor positioning, screen manipulation, scrolling, and display area management. All methods are chainable and return the Terminal instance.
3

4
## Cursor Positioning
5

6
### Absolute Positioning
7

8
```javascript { .api }
9
terminal.moveTo(x: number, y: number): Terminal;
10
```
11

12
Move cursor to absolute position (1-based coordinates).
13

14
```javascript
15
term.moveTo(10, 5).cyan('Text at column 10, row 5');
16
```
17

18
### Relative Movement
19

20
```javascript { .api }
21
terminal.move(x: number, y: number): Terminal;
22
terminal.up(n?: number): Terminal;
23
terminal.down(n?: number): Terminal;
24
terminal.left(n?: number): Terminal;
25
terminal.right(n?: number): Terminal;
26
```
27

28
Move cursor relative to current position. Default movement is 1 unit.
29

30
```javascript
31
term.up(3).right(5).red('Moved up 3, right 5');
32
```
33

34
### Line Navigation
35

36
```javascript { .api }
37
terminal.nextLine(n?: number): Terminal;
38
terminal.previousLine(n?: number): Terminal;
39
terminal.column(x: number): Terminal;
40
```
41

42
Move to beginning of next/previous line or specific column.
43

44
```javascript
45
term.nextLine(2).column(1).green('Two lines down, column 1');
46
```
47

48
### Cursor Information
49

50
```javascript { .api }
51
terminal.getCursorLocation(callback: (error: Error | null, x: number, y: number) => void): void;
52
```
53

54
Get current cursor position asynchronously.
55

56
```javascript
57
term.getCursorLocation((error, x, y) => {
58
  if (!error) {
59
    console.log(`Cursor at ${x}, ${y}`);
60
  }
61
});
62
```
63

64
## Screen Control
65

66
### Screen Clearing
67

68
```javascript { .api }
69
terminal.clear(): Terminal;
70
terminal.eraseDisplayBelow(): Terminal;
71
terminal.eraseDisplayAbove(): Terminal;
72
terminal.eraseEntireDisplay(): Terminal;
73
```
74

75
Clear entire screen or specific display areas.
76

77
```javascript
78
term.clear(); // Clear entire screen
79
term.eraseDisplayBelow(); // Clear from cursor down
80
```
81

82
### Line Clearing
83

84
```javascript { .api }
85
terminal.eraseLineAfter(): Terminal;
86
terminal.eraseLineBefore(): Terminal;
87
terminal.eraseEntireLine(): Terminal;
88
```
89

90
Clear parts of current line.
91

92
```javascript
93
term.eraseLineAfter(); // Clear from cursor to end of line
94
term.eraseEntireLine(); // Clear entire current line
95
```
96

97
## Scrolling and Regions
98

99
### Screen Scrolling
100

101
```javascript { .api }
102
terminal.scrollUp(n?: number): Terminal;
103
terminal.scrollDown(n?: number): Terminal;
104
```
105

106
Scroll the entire screen or current scrolling region.
107

108
```javascript
109
term.scrollUp(3); // Scroll up 3 lines
110
term.scrollDown(); // Scroll down 1 line
111
```
112

113
### Scrolling Regions
114

115
```javascript { .api }
116
terminal.scrollingRegion(top: number, bottom: number): Terminal;
117
terminal.resetScrollingRegion(): Terminal;
118
```
119

120
Set or reset the scrollable region of the screen.
121

122
```javascript
123
term.scrollingRegion(5, 20); // Set scrolling region from line 5 to 20
124
term.resetScrollingRegion(); // Reset to full screen scrolling
125
```
126

127
## Line and Character Manipulation
128

129
### Line Operations
130

131
```javascript { .api }
132
terminal.insertLine(n?: number): Terminal;
133
terminal.deleteLine(n?: number): Terminal;
134
```
135

136
Insert or delete lines at cursor position.
137

138
```javascript
139
term.insertLine(2); // Insert 2 blank lines
140
term.deleteLine(); // Delete current line
141
```
142

143
### Character Operations
144

145
```javascript { .api }
146
terminal.insert(n?: number): Terminal;
147
terminal.delete(n?: number): Terminal;
148
terminal.backDelete(n?: number): Terminal;
149
```
150

151
Insert spaces, delete characters forward, or delete characters backward.
152

153
```javascript
154
term.insert(5); // Insert 5 spaces
155
term.delete(3); // Delete 3 characters forward
156
term.backDelete(2); // Delete 2 characters backward
157
```
158

159
## Advanced Control
160

161
### Column Wrapping
162

163
```javascript { .api }
164
terminal.wrapColumn(x: number): Terminal;
165
```
166

167
Set the column where text wrapping occurs.
168

169
```javascript
170
term.wrapColumn(80); // Wrap text at column 80
171
```
172

173
### Input Control
174

175
```javascript { .api }
176
terminal.grabInput(options?: GrabInputOptions): void;
177
terminal.releaseInput(): void;
178
```
179

180
Enable or disable input grabbing for keyboard and mouse events.
181

182
```javascript { .api }
183
interface GrabInputOptions {
184
  mouse?: boolean | string;
185
  focus?: boolean;
186
}
187
```
188

189
```javascript
190
// Enable input grabbing with mouse support
191
term.grabInput({ mouse: 'button' });
192

193
// Handle key events
194
term.on('key', (name, matches, data) => {
195
  if (name === 'CTRL_C') {
196
    term.releaseInput();
197
    process.exit();
198
  }
199
});
200

201
// Release input when done
202
term.releaseInput();
203
```
204

205
## Terminal Properties
206

207
```javascript { .api }
208
// Terminal dimensions
209
terminal.width: number;
210
terminal.height: number;
211

212
// Terminal identification
213
terminal.appName: string;
214
terminal.appId: string;
215
terminal.generic: string;
216
```
217

218
Access terminal dimensions and identification information.
219

220
```javascript
221
console.log(`Terminal size: ${term.width}x${term.height}`);
222
console.log(`Terminal type: ${term.generic}`);
223
```
224

225
## Usage Examples
226

227
### Complex Cursor Control
228

229
```javascript
230
const term = require('terminal-kit').terminal;
231

232
// Draw a box using cursor control
233
term.clear()
234
  .moveTo(10, 5).cyan('+')
235
  .move(10, 0).cyan('+')
236
  .move(0, 5).cyan('+')
237
  .move(-10, 0).cyan('+')
238
  .moveTo(11, 5).cyan('─'.repeat(9))
239
  .moveTo(11, 10).cyan('─'.repeat(9))
240
  .moveTo(10, 6).cyan('│')
241
  .moveTo(10, 7).cyan('│')
242
  .moveTo(10, 8).cyan('│')
243
  .moveTo(10, 9).cyan('│')
244
  .moveTo(20, 6).cyan('│')
245
  .moveTo(20, 7).cyan('│')
246
  .moveTo(20, 8).cyan('│')
247
  .moveTo(20, 9).cyan('│')
248
  .moveTo(12, 7).white('Hello Box!')
249
  .moveTo(1, 12);
250
```
251

252
### Interactive Cursor Positioning
253

254
```javascript
255
const term = require('terminal-kit').terminal;
256

257
term.grabInput({ mouse: 'button' });
258

259
term.on('mouse', (name, data) => {
260
  if (name === 'MOUSE_LEFT_BUTTON_PRESSED') {
261
    term.moveTo(data.x, data.y)
262
      .bgRed('  ')
263
      .moveTo(1, term.height);
264
  }
265
});
266

267
term.on('key', (name) => {
268
  if (name === 'CTRL_C') {
269
    term.releaseInput();
270
    process.exit();
271
  }
272
});
273
```