Input Reader
May I read what you've written, please?
This functionality is an important part of any interactive console application, because it gives users a chance to input what they want to write to the console.
In case you want to listen to mouse events, you can consult the below page:
Pointer EventsIn case you want to use something other than the reader, you can consult the other input tools defined in the below page:
Other InputYou can easily use this feature in any interactive console application that uses Terminaux. Just use the Terminaux.Reader.TermReader
class that contains the Read()
functions and their overloaded versions.
The reader not only provides the static text version for input prompts, but also the dynamic text version. Just create a simple function delegate that generates a string as the first argument, like this:
Please note that they are interruptible by default. If you want the input to be non-interruptible, you can set the interruptible
argument to false.
You can access the global reader settings by referencing the GlobalReaderSettings
found in the TermReader
class.
Each one of these functions creates a reader state, TermReaderState
, that contains essential information about the current reader state, including, but not limited to:
Current text
Input prompt text
Current text position
Kill buffer
Reader settings
If you're making your own mod in Nitrocid KS, it's best to use its own Input
class instead of Terminaux's TermReader
, as the class there actually deals with the screensaver in most circumstances.
You can use the Read()
function with a generic type that resembles a simple type, such as integers, characters, and strings. This is to simplify type conversion that may be needed for certain inputs, such as entering a number or a fractional number. The below example demonstrates how to use this feature:
You can't use complex types as a generic type, such as JSON nodes.
Keybindings
The terminal reader contains main keybindings, as well as customizable keybindings that you can define to your accord.
Built-in keybindings
Any key will append the selected characters to the current text input, and RETURN
will accept the input. You can also override the keybindings of one of the below actions, as long as they're not listed in red. The below keybindings are available:
Keybinding | Action |
---|---|
| Accepts input |
| Cancels reading (if |
| Beginning of line |
| End of line |
| Backward one character |
| Forward one character |
| Remove one character from the left |
| Get the older input |
| Get the newer input |
| Remove one character in current position |
| One word backward |
| One word forward |
| Next auto-completion entry (if there is one) |
Insert four spaces (if no autocompletions) | |
| Previous auto-completion entry |
| Cut to the start of the line |
| Cut to the end of the line |
| Cut to the end of the previous word |
| Cut to the end of the next word |
| Yank the cut content |
| Make word lowercase |
| Make word UPPERCASE |
| Make input lowercase |
| Make input UPPERCASE |
| Make character uppercase and move to the end of word |
| Make character lowercase and move to the end of word |
| Shows all suggestions in the style akin to the Bourne Again SHell (bash) |
| Refreshes the prompt, the text input, and the current cursor position. |
| Text append mode (Insert or append) |
| Clears the screen and refreshes the prompt. |
| Cut the whitespaces before and after the character. |
| Substitutes two characters |
| Substitutes two words |
| Makes your current input text a comment (visual only, but ignores your text on submit) |
| Forces the tab character to be written. Writes as spaces. |
| Temporarily conceals or reveals the whole input in normal prompts. |
| Goes to the first history entry |
| Goes to the last history entry |
| Undos a change |
| Undos all changes |
Warning: Some of the keys conflict with the terminal emulator and/or the operating system keybindings.
Custom bindings
The input reader supports custom bindings, which you can assign your BaseBinding
class containing the following functions you must override:
BoundKeys
This holds all the keys to bind your custom action to.
DoAction(TermReaderState)
This is the heart of your key binding. You can do anything with the text using the current terminal reader state.
You can also override these:
IsExit
If
true
, causes TermRead to assume that the input is done after executing the action that this binding implements.
BindMatched(ConsoleKeyInfo)
Specify your own method on how to check to see if the input key matched all the bound keys (
BoundKeys
) in your custom key binding.
ResetSuggestionsTextPos
Specifies whether to reset the text position saved for the suggestions. This is usually enabled for custom bindings that have to do with the suggestions.
IsBindingOverridable
Specifies whether applications can override the keybinding with custom keybindings or not. You can call
Override()
andRemoveOverride()
to perform this action.
AppendsChangesList
Specifies whether the keybinding appends the changes to the list of changes from the reader state. Even if this is true, if there are no changes to the input, it will not be added to the changes list.
Principles
Your keybinding must follow the below principles:
For text positioning, you must use any function in the
PositioningTools
class.For manual console manipulation, you must use any function in the
ConsoleWrapper
class.Your bound key must not be already bound to a key that was already bound by either a base or another custom binding, or two bindings execute at the same time, potentially causing conflict.
To manipulate with text, you must use the
state.CurrentText
property. You must refresh the prompt thereafter.To refresh the prompt, you must use the
TermReaderTools.Refresh()
function.
At the end, your base class must look like this at minimum:
where:
ConsoleKey.Key
Any console key. Consult the documentation for more info.
\0
A character that must match the corresponding
ConsoleKey.Key
.
If you're assigning a key containing CTRL
, you must assign a character number starting from 0x0
. For example, CTRL+Y
is \u0019
.
How to bind
Once you created a base class as mentioned above, you can finally use the BindingsTools
class to call the Bind(BaseBinding)
function to add your own binding to the custom binding store, like this:
Warning: You must call this function once. It does nothing if your binding is already installed.
To remove binding, you must use the Unbind(ConsoleKeyInfo)
command.
Positioning tools
Your custom bindings can now change the cursor positioning when manipulating with text so that it becomes easier to make your custom bindings that use positioning tools.
Here are the functions you can use:
GoLeftmost()
: Changes the word position to the leftmost position, that is, the first letter.GoRightmost()
: Changes the word position to the rightmost position, that is, the last letter.GoForward()
: Changes the word position a step or a specified number of steps closer to the end of the text.GoBack()
: Changes the word position a step or a specified number of steps closer to the beginning of the text.SeekTo()
: Changes the word position to the selected zero-based position
Once you're done changing positions, if you need to verify that you've changed the position to the correct position, you can use the Commit()
function.
It's not necessary to use the Commit()
function at the end of each custom binding, because the reader uses this function automatically based on whether to update the position or not.
Writers and Writing
You can use the text writers with the current reader settings by using TextWriterColor
's WriteForReader()
and its siblings, passing it the reader settings to take care of the margins.
Writing tools
You can also append or remove a string in the TermReaderTools
class. This means that you can either append text to the end of the input, insert text to the current position, or remove text from either the current position or from a specific character index from the input string. These are the functions that you can use:
GetMaximumInputLength()
InsertNewText()
RemoveText()
Conditionals
In addition to all the above features, you can also make your key binding beep under certain circumstances, such as if the current text position is at the start of the text and we're trying to move left, using one of the two conditional functions from the ConditionalTools
class:
ShouldNot()
: Specifies that the specified condition should not be trueShould()
: Specifies that the specified condition should not be false
If either of these functions' assertions have failed, either your computer or your speakers emits a beep sound upon going back to the input mode.
History tools
You can now set the history entry list with your array of history entries or clear the history list using the following functions:
SetHistory(List<string> History)
Sets the history to the chosen history list
ClearHistory()
Clears all history entries
State tools
You can also check to see if the console reader facility is busy getting input or not. The property, Busy
, indicates this by returning true
if there is input to be entered by the user.
If you want to wait for user input to finish, you can call the WaitForInput()
function in the TermReaderTools
class.
Last updated