# tcod-ansi-terminal
Minimal true colour ANSI terminal support for Python TCOD (`tcod`).
This doesn't try to support everything or be very compatible, just to cover
basic functionality on common terminals with true colour support. Note that
TCOD itself [may eventually get terminal
support](https://github.com/libtcod/libtcod/issues/78), so check it before
committing to using this.
This is currently all in Python code and may not be very performant.
There is an example included in [`example/`](example/). It also serves for
basic testing of features.
## Compatibility
Operating systems:
- Linux, MacOS X, probably other Unixes: somewhat tested, works
- Windows: totally untested, almost certainly doesn't work yet
Terminal emulators (without exploring their options much):
- xterm: working (all supported features)
- urxvt: mostly working (poor colour handling)
- gnome-terminal: working (doesn't honour pixel size or position requests;
reserves some function keys)
- konsole: mostly working (may read initial size wrong if size was requested;
doesn't honour any size or position requests; doesn't honour title; reserves
some function keys)
- kitty: working (doesn't honour any size or position requests)
- alacritty: working (doesn't honour any size of position requests)
- MacOS X default terminal: not working (no true colour support; some other
features don't work)
- iterm2: working (does not respect any position or size requests, insert key
seemingly not supported; reserves some function keys)
Only uses true colour mode, and won't support consoles that don't handle it.
## Features
Supported TCOD features (at least for some terminals):
- Basic letter, digit, punctuation, and enter keys (anything received as an
unescaped character; this set is safest for compatibility with untested
terminals).
- Shift modifier for letter keys (but not digits etc.).
- Arrow, function, home, end, insert, delete, page up, page down keys.
- Keysyms for the above keys.
- Key down and key up events in immediate succession for the above keys, based
on terminal input.
- Text input events for letter etc. keys.
- Terminal size checks for `recommended_console_size()` and `new_console()`.
- Window position, pixel size, and character size as requests. The choice to
honour them or not is up to the terminal and/or window manager.
- Window resize events for terminal resizes.
- Mouse motion, button, and wheel events.
- Window focus gained and lost events.
- Window title.
- Quit event on hangup and other exit signals. If in a windowing system, this
might get produced when the window is closed but isn't guaranteed.
Other features:
- The terminal will be reset cleanly on exit.
- The cursor position can be set.
- Cursor visibility can be set.
Unsupported TCOD features:
- Shift modifier for non-letter key.
- Modifiers other than shift.
- Key scancodes (are all `K_UNKNOWN`).
- Correct timing for key down/up events.
- `tcod.event.get()`.
- Basically any other input/output feature that isn't mentioned above,
especially things in `tcod.context` and `tcod.event`.
Features that are not supported but could be later:
- Some support for other colour modes.
- Screenshots (with separate interface) to text files.
## Usage
Use `tcod_ansi_terminal.context.new()` to get a context object which manages an
ANSI terminal and can `present()` Python TCOD consoles to it. Use
`tcod_ansi_terminal.event.wait()` to get events.
### Targeting terminals
Not all features will be supported in all terminals, so if you want broad
compatibly you should not assume that any particular feature will be available.
The context will request the terminal size asked for (if any), but the calling
code must treat this as a request, and not assume that the request will be
honoured or that the size will remain the same during the run. Use the
context's `recommended_console_size()` to get the actual size, or
`new_console()` to get a correctly sized console, and use the `WindowResized`
event (or re-checking the size) to catch resizes.
The terminal context `tcod_ansi_terminal.context.TerminalContext` may support
operations that are not part of the regular TCOD interface, currently just
cursor controls.
### Targeting either terminals or regular tcod
If you want to support both regular TCOD and terminals in your program,
parameterize your core code using these interfaces:
- For rendering, the `tcod_ansi_terminal.context.TerminalCompatibleContext` protocol.
- For input, the `tcod_ansi_terminal.event.TerminalCompatibleEventWait` protocol.
The included example covers handling both a terminal or regular TCOD.
### Presenters
`tcod_ansi_terminal.context` provides two presenters which manage how a TCOD
console is written to a terminal on a context `present()` call.
`NaivePresenter` always writes the entire console. `SparsePresenter` writes only
the character cells which changed since the last `present()` call. If the
calling code tends to update only small parts of the console between frames,
`SparsePresenter` will likely be much faster.
Raw data
{
"_id": null,
"home_page": "",
"name": "tcod-ansi-terminal",
"maintainer": "",
"docs_url": null,
"requires_python": ">3.8",
"maintainer_email": "",
"keywords": "roguelike,libtcod,terminal,ansi",
"author": "",
"author_email": "Max Whitney <mwhitney@alumni.sfu.ca>",
"download_url": "https://files.pythonhosted.org/packages/7b/f2/6e375fb0c700504cf2adc6c55ca6e04f210cbd6ef9a553e29d44d600d005/tcod-ansi-terminal-0.1.0.tar.gz",
"platform": null,
"description": "# tcod-ansi-terminal\n\nMinimal true colour ANSI terminal support for Python TCOD (`tcod`).\n\nThis doesn't try to support everything or be very compatible, just to cover\nbasic functionality on common terminals with true colour support. Note that\nTCOD itself [may eventually get terminal\nsupport](https://github.com/libtcod/libtcod/issues/78), so check it before\ncommitting to using this.\n\nThis is currently all in Python code and may not be very performant.\n\nThere is an example included in [`example/`](example/). It also serves for\nbasic testing of features.\n\n## Compatibility\n\nOperating systems:\n- Linux, MacOS X, probably other Unixes: somewhat tested, works\n- Windows: totally untested, almost certainly doesn't work yet\n\nTerminal emulators (without exploring their options much):\n- xterm: working (all supported features)\n- urxvt: mostly working (poor colour handling)\n- gnome-terminal: working (doesn't honour pixel size or position requests;\n reserves some function keys)\n- konsole: mostly working (may read initial size wrong if size was requested;\n doesn't honour any size or position requests; doesn't honour title; reserves\n some function keys)\n- kitty: working (doesn't honour any size or position requests)\n- alacritty: working (doesn't honour any size of position requests)\n- MacOS X default terminal: not working (no true colour support; some other\n features don't work)\n- iterm2: working (does not respect any position or size requests, insert key\n seemingly not supported; reserves some function keys)\n\nOnly uses true colour mode, and won't support consoles that don't handle it.\n\n## Features\n\nSupported TCOD features (at least for some terminals):\n- Basic letter, digit, punctuation, and enter keys (anything received as an\n unescaped character; this set is safest for compatibility with untested\n terminals).\n- Shift modifier for letter keys (but not digits etc.).\n- Arrow, function, home, end, insert, delete, page up, page down keys.\n- Keysyms for the above keys.\n- Key down and key up events in immediate succession for the above keys, based\n on terminal input.\n- Text input events for letter etc. keys.\n- Terminal size checks for `recommended_console_size()` and `new_console()`.\n- Window position, pixel size, and character size as requests. The choice to\n honour them or not is up to the terminal and/or window manager.\n- Window resize events for terminal resizes.\n- Mouse motion, button, and wheel events.\n- Window focus gained and lost events.\n- Window title.\n- Quit event on hangup and other exit signals. If in a windowing system, this\n might get produced when the window is closed but isn't guaranteed.\n\nOther features:\n- The terminal will be reset cleanly on exit.\n- The cursor position can be set.\n- Cursor visibility can be set.\n\nUnsupported TCOD features:\n- Shift modifier for non-letter key.\n- Modifiers other than shift.\n- Key scancodes (are all `K_UNKNOWN`).\n- Correct timing for key down/up events.\n- `tcod.event.get()`.\n- Basically any other input/output feature that isn't mentioned above,\n especially things in `tcod.context` and `tcod.event`.\n\nFeatures that are not supported but could be later:\n- Some support for other colour modes.\n- Screenshots (with separate interface) to text files.\n\n## Usage\n\nUse `tcod_ansi_terminal.context.new()` to get a context object which manages an\nANSI terminal and can `present()` Python TCOD consoles to it. Use\n`tcod_ansi_terminal.event.wait()` to get events.\n\n### Targeting terminals\n\nNot all features will be supported in all terminals, so if you want broad\ncompatibly you should not assume that any particular feature will be available.\n\nThe context will request the terminal size asked for (if any), but the calling\ncode must treat this as a request, and not assume that the request will be\nhonoured or that the size will remain the same during the run. Use the\ncontext's `recommended_console_size()` to get the actual size, or\n`new_console()` to get a correctly sized console, and use the `WindowResized`\nevent (or re-checking the size) to catch resizes.\n\nThe terminal context `tcod_ansi_terminal.context.TerminalContext` may support\noperations that are not part of the regular TCOD interface, currently just\ncursor controls.\n\n### Targeting either terminals or regular tcod\n\nIf you want to support both regular TCOD and terminals in your program,\nparameterize your core code using these interfaces:\n- For rendering, the `tcod_ansi_terminal.context.TerminalCompatibleContext` protocol.\n- For input, the `tcod_ansi_terminal.event.TerminalCompatibleEventWait` protocol.\n\nThe included example covers handling both a terminal or regular TCOD.\n\n### Presenters\n\n`tcod_ansi_terminal.context` provides two presenters which manage how a TCOD\nconsole is written to a terminal on a context `present()` call.\n`NaivePresenter` always writes the entire console. `SparsePresenter` writes only\nthe character cells which changed since the last `present()` call. If the\ncalling code tends to update only small parts of the console between frames,\n`SparsePresenter` will likely be much faster.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "ANSI terminal support for Python TCOD.",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"roguelike",
"libtcod",
"terminal",
"ansi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b1d43196fc7f6ef0443a9b9482ba15c1cd58ca1711dcd46762e3d054c4e1cccd",
"md5": "9fe86ac6128494f486f463bf33e99e03",
"sha256": "0ccb1ff2ce11e29531db53f9a52f634debbae1dfc1a2a0971911d1c0904dcdc6"
},
"downloads": -1,
"filename": "tcod_ansi_terminal-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9fe86ac6128494f486f463bf33e99e03",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.8",
"size": 17842,
"upload_time": "2023-10-17T07:11:13",
"upload_time_iso_8601": "2023-10-17T07:11:13.000032Z",
"url": "https://files.pythonhosted.org/packages/b1/d4/3196fc7f6ef0443a9b9482ba15c1cd58ca1711dcd46762e3d054c4e1cccd/tcod_ansi_terminal-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7bf26e375fb0c700504cf2adc6c55ca6e04f210cbd6ef9a553e29d44d600d005",
"md5": "96d71bc90d097c2a794e379f3b76a28e",
"sha256": "68cb5a9b6c66ec59424a8315621977080fe250e7e980f56cbf9f327ebc28b366"
},
"downloads": -1,
"filename": "tcod-ansi-terminal-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "96d71bc90d097c2a794e379f3b76a28e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.8",
"size": 15697,
"upload_time": "2023-10-17T07:11:14",
"upload_time_iso_8601": "2023-10-17T07:11:14.629088Z",
"url": "https://files.pythonhosted.org/packages/7b/f2/6e375fb0c700504cf2adc6c55ca6e04f210cbd6ef9a553e29d44d600d005/tcod-ansi-terminal-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-17 07:11:14",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "tcod-ansi-terminal"
}
JSON