trial.terminal

Ignore coverage Module for interacting with the user's terminal, including color output, cursor manipulation, and full-featured real-time mouse and keyboard input. Also includes high-level convenience methods, like Terminal.getline, which gives the user a line editor with history, completion, etc. See the examples.

More...

Members

Classes

FileLineGetter class FileLineGetter: This is a line getter that customizes the tab completion to fill in file names separated by spaces, like a command line thing.
HangupException class HangupException: Undocumented in source.
LineGetter class LineGetter: FIXME: support lines that wrap FIXME: better controls maybe
UserInterruptionException class UserInterruptionException: Undocumented in source.

Enums

Color enum Color: Defines the list of standard colors understood by Terminal.
ConsoleInputFlags enum ConsoleInputFlags: When capturing input, what events are you interested in?
ConsoleOutputType enum ConsoleOutputType: Defines how terminal output should be handled.
ForceOption enum ForceOption: Some methods will try not to send unnecessary commands to the screen. You can override their judgement using a ForceOption parameter, if present
ModifierState enum ModifierState: Undocumented in source.
ModifierState enum ModifierState: Undocumented in source.
ModifierState enum ModifierState

Functions

SHGetFolderPathA HRESULT SHGetFolderPathA(HWND , int , HANDLE , DWORD , LPSTR ): Undocumented in source but is binding to Windows. You might be able to learn more by searching the web for its name.
approximate16Color int approximate16Color(RGB color): Undocumented in source. Be warned that the author may not have intended to support it.
colorToXTermPaletteIndex ubyte colorToXTermPaletteIndex(RGB color): Undocumented in source. Be warned that the author may not have intended to support it.
hangupSignalHandler void hangupSignalHandler(int sigNumber): Undocumented in source. Be warned that the author may not have intended to support it.
interruptSignalHandler void interruptSignalHandler(int sigNumber): Undocumented in source. Be warned that the author may not have intended to support it.
ioctl int ioctl(int , int , ...): Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
ioctl int ioctl(int , c_ulong , ...): Undocumented in source but is binding to C. You might be able to learn more by searching the web for its name.
sizeSignalHandler void sizeSignalHandler(int sigNumber): Undocumented in source. Be warned that the author may not have intended to support it.
xtermPaletteIndexToColor RGB xtermPaletteIndexToColor(int paletteIdx): Undocumented in source. Be warned that the author may not have intended to support it.

Interfaces

CustomEvent interface CustomEvent: Undocumented in source.

Manifest constants

Bright enum Bright;: Undocumented in source.
CSIDL_APPDATA enum CSIDL_APPDATA;: Undocumented in source.
SIGWINCH enum SIGWINCH;: Undocumented in source.
TIOCGWINSZ enum TIOCGWINSZ;: Undocumented in source.

Mixin templates

LineGetterConstructors mixintemplate LineGetterConstructors(): Adds default constructors that just forward to the superclass

Static variables

hangedUp bool hangedUp;: similar to interrupted.
interrupted bool interrupted;: you might periodically check this in a long operation and abort if it is set. Remember it is volatile. It is also sent through the input event loop via RealTimeConsoleInput
windowSizeChanged bool windowSizeChanged;: Undocumented in source.

Structs

CharacterEvent struct CharacterEvent
EndOfFileEvent struct EndOfFileEvent: Sent upon receiving end-of-file from stdin.
HangupEvent struct HangupEvent: If the user hangs up (for example, closes the terminal emulator without exiting the app), this is sent. If you receive it, you should generally cleanly exit.
InputEvent struct InputEvent: RealTimeConsoleInput.nextEvent returns one of these. Check the type, then use the get method to get the more detailed information about the event.
KeyboardEvent struct KeyboardEvent: The new style of keyboard event
MouseEvent struct MouseEvent: .
NonCharacterKeyEvent struct NonCharacterKeyEvent
PasteEvent struct PasteEvent: .
RGB struct RGB: Represents a 24-bit color.
RealTimeConsoleInput struct RealTimeConsoleInput: Encapsulates the stream of input events received from the terminal input.
ScrollbackBuffer struct ScrollbackBuffer: Undocumented in source.
SignalFired struct SignalFired: Undocumented in source.
SizeChangedEvent struct SizeChangedEvent: When you get this, check terminal.width and terminal.height to see the new size and react accordingly.
Terminal struct Terminal: Encapsulates the I/O capabilities of a terminal.
UserInterruptionEvent struct UserInterruptionEvent: the user hitting ctrl+c will send this You should drop what you're doing and perhaps exit when this happens.
winsize struct winsize: Undocumented in source.

Variables

TIOCGWINSZ enum int TIOCGWINSZ;: Undocumented in source.
builtinTermcap enum string builtinTermcap;: Undocumented in source.

Detailed Description

The main interface for this module is the Terminal struct, which encapsulates the output functions and line-buffered input of the terminal, and RealTimeConsoleInput, which gives real time input.

Creating an instance of these structs will perform console initialization. When the struct goes out of scope, any changes in console settings will be automatically reverted.

Note: on Posix, it traps SIGINT and translates it into an input event. You should keep your event loop moving and keep an eye open for this to exit cleanly; simply break your event loop upon receiving a UserInterruptionEvent. (Without the signal handler, ctrl+c can leave your terminal in a bizarre state.)

As a user, if you have to forcibly kill your program and the event doesn't work, there's still ctrl+\

On Mac Terminal btw, a lot of hacks are needed and mouse support doesn't work. Most functions basically work now though.

Future Roadmap

The CharacterEvent and NonCharacterKeyEvent types will be removed. Instead, use KeyboardEvent on new programs.
The ScrollbackBuffer will be expanded to be easier to use to partition your screen. It might even handle input events of some sort. Its API may change.
getline I want to be really easy to use both for code and end users. It will need multi-line support eventually.
I might add an expandable event loop and base level widget classes. This may be Linux-specific in places and may overlap with similar functionality in simpledisplay.d. If I can pull it off without a third module, I want them to be compatible with each other too so the two modules can be combined easily. (Currently, they are both compatible with my eventloop.d and can be easily combined through it, but that is a third module.)
More advanced terminal features as functions, where available, like cursor changing and full-color functions.
The module will eventually be renamed to arsd.terminal.
More documentation.

WHAT I WON'T DO:

support everything under the sun. If it isn't default-installed on an OS I or significant number of other people might actually use, and isn't written by me, I don't really care about it. This means the only supported terminals are:
- xterm (and decently xterm compatible emulators like Konsole)
- Windows console
- rxvt (to a lesser extent)
- Linux console
- My terminal emulator family of applications https://github.com/adamdruppe/terminal-emulator
Anything else is cool if it does work, but I don't want to go out of my way for it.
Use other libraries, unless strictly optional. terminal.d is a stand-alone module by default and always will be.
Do a full TUI widget set. I might do some basics and lay a little groundwork, but a full TUI is outside the scope of this module (unless I can do it really small.)