This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
api:term [2015/01/14 23:40] 127.0.0.1 external edit |
api:term [2018/11/15 17:37] (current) payonel |
||
|---|---|---|---|
| Line 4: | Line 4: | ||
| - `term.isAvailable(): boolean` | - `term.isAvailable(): boolean` | ||
| - | Returns whether the term API is available for use, i.e. whether a primary GPU an screen are present. In other words, whether `term.read` and `term.write` will actually do something. | + | Returns whether the term API is available for use, i.e. whether a primary GPU and screen are present. In other words, whether `term.read` and `term.write` will actually do something. |
| + | - `term.getViewport(): number, number, number, number, number, number` | ||
| + | (new in OpenOS 1.6) | ||
| + | |||
| + | Gets the width, height, x offset, y offset, relative x, and relative y values. | ||
| + | - `term.gpu(): table` | ||
| + | (new in OpenOS 1.6) | ||
| + | |||
| + | Gets the gpu proxy used by the term api. | ||
| + | - `term.pull([...]): ...` | ||
| + | (new in OpenOS 1.6) | ||
| + | |||
| + | Acts exactly like `event.pull` taking the same parameters and returning the same results. This method is used to blink the cursor while waiting for an event result. | ||
| - `term.getCursor(): number, number` | - `term.getCursor(): number, number` | ||
| Gets the current position of the cursor. | Gets the current position of the cursor. | ||
| Line 19: | Line 31: | ||
| - `term.read([history: table[, dobreak:boolean[, hint:table or function[, pwchar:string]]]]): string` | - `term.read([history: table[, dobreak:boolean[, hint:table or function[, pwchar:string]]]]): string` | ||
| Read some text from the terminal, i.e. allow the user to input some text. For example, this is used by the shell and Lua interpreter to read user input. This will make the rest of the current line, starting at the current cursor position, an editable area. It allows input, deletion and navigating to the left and right via the arrow keys and home/end keys. | Read some text from the terminal, i.e. allow the user to input some text. For example, this is used by the shell and Lua interpreter to read user input. This will make the rest of the current line, starting at the current cursor position, an editable area. It allows input, deletion and navigating to the left and right via the arrow keys and home/end keys. | ||
| + | | ||
| + | ***since OpenOS 1.6** the parameter list as specified here is considered deprecated. The first parameter is an `options` argument. The indexed array values are treated as `history`, named keys take the place of legacy arguments. For compatibility, OpenOS 1.6 will respect the previous usage, i.e. parameter list. | ||
| + | *The new `ops` parameter supports a new key, `nowrap`. The default behavior of term.read wrap the cursor and input vertically. Legacy behavior scrolled the input horizontally, i.e. `term.read({nowrap=true})` | ||
| + | |||
| The optional `history` table can be used to provide predefined text that can be cycled through via the up and down arrow keys. It must be a sequence (i.e. the keys must be a gap-less integral interval starting at 1). This is used for the command history in shell and Lua interpreter, for example. If text is entered and confirmed with enter, it will be added to the end of this table. | The optional `history` table can be used to provide predefined text that can be cycled through via the up and down arrow keys. It must be a sequence (i.e. the keys must be a gap-less integral interval starting at 1). This is used for the command history in shell and Lua interpreter, for example. If text is entered and confirmed with enter, it will be added to the end of this table. | ||
| The `dobreak` parameter, when set to `false` (**`nil` defaults to `true`!**) will not enter a new line after input was completed (e.g. by the user pressing enter). | The `dobreak` parameter, when set to `false` (**`nil` defaults to `true`!**) will not enter a new line after input was completed (e.g. by the user pressing enter). | ||
| The `hint` parameter is used for tab completion. It can either be a table with strings or a function that returns a table of strings and takes two parameters, the current text and the position in that text, i.e. the signature of the callback is `function(line:string, pos:number):table`. | The `hint` parameter is used for tab completion. It can either be a table with strings or a function that returns a table of strings and takes two parameters, the current text and the position in that text, i.e. the signature of the callback is `function(line:string, pos:number):table`. | ||
| The `pwchar` parameter, when given, causes input to be masked using the first char of the given string. For example, providing `"*"` will make all entered characters appear as stars. The returned value will still be the actual text inserted, of course. | The `pwchar` parameter, when given, causes input to be masked using the first char of the given string. For example, providing `"*"` will make all entered characters appear as stars. The returned value will still be the actual text inserted, of course. | ||
| - | The function will return a string if input was successful, or `nil` if there was no more input (user pressed Ctrl+D or Ctrl+C or the terminal became unavailable). | + | The function will return a string if input was successful, `nil` if the pipe was closed (^d), or `false` if the pipe was interrupted (^c) |
| //Note//: `io.stdin:read()` uses this function. | //Note//: `io.stdin:read()` uses this function. | ||
| - | //Note 2//: This will return the entered string with the \n (new line character). If you want only the entered string to be returned, use `io.read()`. | + | //Note 2//: This will return the entered string with the \n (new line character). If you want only the entered string to be returned, use `io.read()`. |
| - `term.write(value: string[, wrap: boolean])` | - `term.write(value: string[, wrap: boolean])` | ||
| Allows writing optionally wrapped text to the terminal starting at the current cursor position, updating the cursor accordingly. It automatically converts tab characters to spaces using `text.detab`. If `wrap` is true, it will automatically word-wrap the text. It will scroll the displayed buffer if the cursor exceeds the bottom of the display area, but *not* if it exceeds the right of the display area (when `wrap` is false). | Allows writing optionally wrapped text to the terminal starting at the current cursor position, updating the cursor accordingly. It automatically converts tab characters to spaces using `text.detab`. If `wrap` is true, it will automatically word-wrap the text. It will scroll the displayed buffer if the cursor exceeds the bottom of the display area, but *not* if it exceeds the right of the display area (when `wrap` is false). | ||
| - | //Note//: `io.stdout:write()` uses this function. | + | //Note//: This method respects io redirection. That is to say, `term.write` writes to the same stream as io.stdout |
| + | |||
| + | - `term.bind(gpu)` | ||
| + | |||
| + | (new in OpenOS 1.6) | ||
| + | |||
| + | Binds a `gpu` proxy (not address) to the terminal. This method is called automatically during boot when the gpu and screen become available. Note that if manually rebinding a terminal to a screen with different width and height, the terminal draw area will be truncated and not maximized. This changes the gpu used in all terminal output, not just via the term api, i.e. `io.write`, `print`, `io.stdout:write`, etc all use the same output stream, and term.bind is used to change the `gpu` used. | ||
| + | - `term.screen(): string` | ||
| + | (new in OpenOS 1.6) | ||
| + | |||
| + | Convenience method, simply calls `getScreen` on the terminal's bound gpu (see `term.bind`) | ||
| + | - `term.keyboard(): string` | ||
| + | (new in OpenOS 1.6) | ||
| + | |||
| + | Gets the address of the keyboard the terminal is accepting key events from. | ||
| Contents | Contents | ||
| ----------- | ----------- | ||
| {{page>api:contents&noheader&noeditbutton&nouser&nofooter}} | {{page>api:contents&noheader&noeditbutton&nouser&nofooter}} | ||
| + | |||