- [x] All tools from MS Paint: Free-Form Select, Select, Eraser/Color Eraser, Fill With Color, Pick Color, Magnifier, Pencil, Brush, Airbrush, Text, Line, Curve, Rectangle, Polygon, Ellipse, and Rounded Rectangle
Many file formats are supported, including ANSI art, raster images, SVG and HTML.
To choose a file format when saving, type its file extension. For example, to save a PNG, add `.png` to the end of the filename. The default is `.ans`.
| Format | Notes |
| --- | --- |
| **ANSI** (.ans) | Note that while it handles many more ANSI control codes when loading than those that it uses to save files, you may have limited success loading other ANSI files that you find on the web, or create with other tools. ANSI files can vary a lot and even encode animations! |
| **mIRC codes** (.irc, .mirc) | invented file extensions, and not to be confused with .mrc mIRC script files |
| **Plain Text** (.txt) | |
| **SVG** (.svg) | can open SVGs saved by Textual Paint, which embed ANSI data; can also open some other SVGs that consist of a grid of rectangles and text elements. For fun, as a challenge, I made it quite flexible; it can handle uneven grids of unsorted rectangles. But that's only used as a fallback, because it's not perfect. |
| **HTML** (.htm, html) | write-only (opening not supported) |
| **PNG** (.png) | opens first frame of an APNG file |
| **Bitmap** (.bmp) | |
| **GIF** (.gif) | opens first frame |
| **TIFF** (.tiff) | opens first frame |
| **WebP** (.webp) | opens first frame |
| **JPEG** (.jpg, .jpeg) | saving disabled because it's lossy (it would destroy your pixel art) |
| **Windows Icon** (.ico) | opens largest size in the file |
| **Mac OS Icon** (.icns) | opens largest size in the file; saving disabled because it requires specific sizes |
| **Windows Cursor** (.cur) | opens largest size in the file; saving not supported by Pillow (and it would need a defined hot spot) |
See [Pillow's documentation](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html) for more supported formats.
Note that metadata is not preserved when opening and saving image files. This is however common for many image editors.
To preview ANSI art files in file managers like Nautilus, Thunar, Nemo, or Caja, you can install the [ansi-art-thumbnailer](https://github.com/1j01/ansi-art-thumbnailer) program I made to go along with this project.
- Undo/Redo doesn't work inside the Text tool's textbox. <kbd>Ctrl</kbd>+<kbd>Z</kbd> will delete the textbox. (Also note that the Text tool works differently from MS Paint; it will overwrite characters and the cursor can move freely, which makes it better for ASCII art, but worse for prose.)
- The selection box border appears inside instead of outside (and lacks dashes). For the text box, I hid the border because it was too visually confusing, but it should also have an outer border.
- Pressing both mouse buttons stops the current tool, but doesn't undo the current action. Also Pick Color can't be cancelled (with <kbd>Esc</kbd> or by pressing both mouse buttons), since it samples the color continuously.
- Due to limitations of the terminal, shortcuts using <kbd>Shift</kbd> or <kbd>Alt</kbd> might not work. Menus are not keyboard navigable, because I can't detect <kbd>Alt</kbd>+<kbd>F</kbd>, etc.
- Clicking Save As menu item scrolls down menu instead of activating it if there's not enough space to show the whole menu. (It seems to be scrolling the menu item to the top when it becomes focused during the click.)
- Extraneous undo states may be created in some cases. In particular, I noticed when undoing/redoing with free-typing mode, the last state had no cursor but was otherwise identical.
- ANSI files (.ans) are treated as UTF-8 when saving and loading, rather than CP437 or Windows-1252 or any other encodings. Unicode is nice and modern terminals support it, but it's not the standard for ANSI files. There isn't really a standard for ANSI files.
- ANSI files are loaded with a white background. This may make sense as a default for text files, but ANSI files either draw a background or assume a black background, being designed for terminals.
- Hitting Enter in View Bitmap mode may trigger a menu item while exiting the mode. Menu items ought to be disabled when hidden, and View Bitmap should also prevent the key event from taking other actions if possible.
- Closing dialogs focuses the character input which is undesirable as it prevents typing in the canvas or copying the selection with <kbd>Ctrl</kbd>+<kbd>C</kbd> etc. (You can use <kbd>Esc</kbd> to reset focus.)
- Can show two cells as selected, instead of one across both grids
- Custom colors order X/Y is different from MS Paint
- Pressing enter in color grid should select color and close
- Selection ring is hard to see in dark mode
- Focus ring is invisible on a black color cell
- When dragging on the color field or luminosity slider, the cursor can be seen to jump back to earlier places where the mouse was, before settling at the current position. (This may only be visible when the program is running slowly, such while debugging. I haven't observed this on the canvas, so maybe it has something to do with the dialog being on a separate layer.)
- When opening the Edit Colors dialog, it may immediately close, if the mouse lines up with the "OK" or "Cancel" buttons. (This doesn't seem to currently happen, but I haven't knowingly fixed it. A git bisect turned up a bogus commit, possibly due to reproducing the behavior being unreliable. It also seems like it might depend on the specific layout of the dialog, which changed during development, and maybe even the terminal size.)
The default Terminal has missing characters, causing misalignment of everything to the right of them, plus borders are not rendered nicely, giving it a sort of *frayed fabric* look, and it's limited to 256 colors.
[<kbd>Ctrl</kbd>+<kbd>V</kbd> does not work](https://github.com/microsoft/terminal/issues/11267) to paste by default, but **Edit > Paste** does work.
You can unbind <kbd>Ctrl</kbd>+<kbd>V</kbd> to fix this:
- Open Windows Terminal's Settings (<kbd>Ctrl</kbd>+<kbd>,</kbd>)
- Click "Open JSON file"
- Disable the paste binding by adding `//` to the beginning of the lines:
```json
// {
// "command": "paste",
// "keys": "ctrl+v"
// },
```
- Save the file, and the behavior should update immediately.
Alternatively, you can use the Actions tab of the Settings UI to remove the binding for <kbd>Ctrl</kbd>+<kbd>V</kbd>.
If you're wondering why *removing* the Paste binding fixes it, it's because Textual Paint needs to receive the literal <kbd>Ctrl</kbd>+<kbd>V</kbd> key presses in order to trigger its own Paste command.
Running in Powershell, you may run into a bug where the powershell prompt becomes active at the same time as the TUI.
Moving the mouse will redraw parts of the TUI, and it becomes hard to click on things, but still possible.
Commands can be entered, and the output will be interwoven with the TUI, including if you run a second instance of the program, in which case the two instances will vie for the screen.
If this happens, I would recommend first messing around with it, since it's a fun glitch, then opening a new tab in Windows Terminal with the **Command Prompt profile**, available in the new tab dropdown menu.
This program is commonly thought of as the "Command Prompt", but the Command Prompt (`cmd.exe`) is actually a *shell* (like `bash`) that can run in either the old console or the new Windows Terminal, which are both *terminal emulators*.
You can run with `--ascii-only` to limit the characters used in the UI to ASCII, but colors will still be limited and similar colors will appear confusingly identical.
Note that VS Code's integrated terminal tries to fix the contrast of text, including in the canvas, which is entirely inappropriate for an ANSI art editor, as it obscures the colors, and can indeed *harm* the contrast of the resulting document, by tricking you into thinking there's more contrast than there actually is.
To disable this, you can add this to your settings.json:
`--clear-screen` is useful for development, because it's sometimes jarring or perplexing to see error messages that have actually been fixed, when exiting the program.
`--inspect-layout` enables a DOM inspector accessible with F12, which I built. It also lets you apply a rainbow highlight and labels to all ancestors under the mouse with middle click, but this is mostly obsolete/redundant with the DOM inspector now. The labels affect the layout, so you can also hold Ctrl to only colorize, and you can remember how the colors correspond to the labels, to build a mental model of the layout.
`--restart-on-changes` automatically restarts the program when any Python files change. This works by the program restarting itself directly. (Programs like `modd` or `nodemon` that run your program in a subprocess don't work well with a TUI's escape sequences.)
- Upload to TestPyPI: (updating version numbers) `python -m twine upload --repository testpypi dist/textual_paint-0.3.0rc1-py3-none-any.whl dist/textual_paint-0.3.0rc1.tar.gz`
- Test installing from TestPyPI with: (outside the venv, updating the version number) `pipx uninstall textual-paint; pipx install textual-paint==0.3.0rc1 --pip-args "--index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple textual-paint"`
- If all is good, update version numbers to remove `-pre.N` suffixes
- Amend commit (`git commit --amend --no-edit`)
- Rebuild: `python -m build --sdist --wheel`
- Upload to PyPI: `python -m twine upload dist/textual_paint-0.3.0-py3-none-any.whl dist/textual_paint-0.3.0.tar.gz`
- Push `main` branch (`git push origin main`)
- Tag and push tag (e.g. `git tag v0.3.0 && git push origin v0.3.0`)
The first thing I did in this project was to collect possible characters to represent all the tool icons in MS Paint, to gauge how good of a recreation it would be possible to achieve, starting from looks.
A crosshair cursor could use one of `+✜✛⊹✚╋╬⁘⁛𖥔⌖⯐`, but it might be better to show the pixel under the cursor, i.e. character cell, surrounded by dashes, like this:
- [Playscii](http://vectorpoem.com/playscii/), a beautiful ASCII/ANSI art editor. This is also written in Python and MIT licensed, so I might take some code from it, for converting images to ANSI, for example. Who knows, maybe I could even try to support its file format.
