1
2.. image:: https://travis-ci.org/peterbrittain/asciimatics.svg?branch=master
3 :target: https://travis-ci.org/peterbrittain/asciimatics
4 :alt: Linux build status
5
6.. image:: https://ci.appveyor.com/api/projects/status/n68nk47ku35pafru/branch/master?svg=true&passingText=Windows%20-%20passing
7 :target: https://ci.appveyor.com/project/peterbrittain/asciimatics
8 :alt: Windows build status
9
10.. image:: https://api.codacy.com/project/badge/Grade/486232c340c644b9a676a66da946970d
11 :target: https://app.codacy.com/project/pab/asciimatics/dashboard
12 :alt: Code Health
13
14.. image:: https://coveralls.io/repos/github/peterbrittain/asciimatics/badge.svg?branch=master
15 :target: https://coveralls.io/github/peterbrittain/asciimatics?branch=master
16 :alt: Code Coverage
17
18.. image:: https://img.shields.io/pypi/v/asciimatics.svg
19 :target: https://pypi.python.org/pypi/asciimatics
20 :alt: Latest stable version
21
22.. image:: https://badges.gitter.im/asciimatics/Lobby.svg
23 :alt: Join the chat at https://gitter.im/asciimatics/Lobby
24 :target: https://gitter.im/asciimatics/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
25
26ASCIIMATICS
27===========
28
29Asciimatics is a package to help people create full-screen text UIs (from interactive forms to
30ASCII animations) on any platform. It is licensed under the Apache Software Foundation License 2.0.
31
32Why?
33----
34
35Why not? It brings a little joy to anyone who was programming in the 80s... Oh and it provides a
36single cross-platform Python class to do all the low-level console function you could ask for,
37including:
38
39* Coloured/styled text - including 256 colour terminals and unicode characters (even CJK languages)
40* Cursor positioning
41* Keyboard input (without blocking or echoing) including unicode support
42* Mouse input (terminal permitting)
43* Detecting and handling when the console resizes
44* Screen scraping
45
46In addition, it provides some simple, high-level APIs to provide more complex features including:
47
48* Anti-aliased ASCII line-drawing
49* Image to ASCII conversion - including JPEG and GIF formats
50* Many animation effects - e.g. sprites, particle systems, banners, etc.
51* Various widgets for text UIs - e.g. buttons, text boxes, radio buttons, etc.
52
53Currently this package has been proven to work on CentOS 6 & 7, Raspbian (i.e. Debian wheezy),
54Ubuntu 14.04, Windows 7, 8 & 10, OSX 10.11 and Android Marshmallow (courtesy of https://termux.com),
55though it should also work for any other platform that provides a working curses implementation.
56
57It should be implementation agnostic and has been successfully tested on CPython and PyPy2.
58
59(Please let me know if you successfully verified it on other platforms so that I can update this
60list).
61
62Installation
63------------
64
65Asciimatics supports Python versions 2 & 3. For the precise list of tested versions,
66refer to `pypi <https://pypi.python.org/pypi/asciimatics>`_.
67
68To install asciimatics, simply install with `pip` as follows:
69
70.. code-block:: bash
71
72 $ pip install asciimatics
73
74This should install all your dependencies for you. If you don't use pip or it fails to install
75them, you can install the dependencies directly using the packages listed in `requirements.txt
76<https://github.com/peterbrittain/asciimatics/blob/master/requirements.txt>`_.
77Additionally, Windows users (who aren't using `pip`) will need to install `pywin32`.
78
79How to use it?
80--------------
81To use the low-level API, simply create a Screen and use it to print coloured text at any location,
82or get mouse/keyboard input. For example, here is a variant on the classic "hello world":
83
84.. code-block:: python
85
86 from random import randint
87 from asciimatics.screen import Screen
88
89 def demo(screen):
90 while True:
91 screen.print_at('Hello world!',
92 randint(0, screen.width), randint(0, screen.height),
93 colour=randint(0, screen.colours - 1),
94 bg=randint(0, screen.colours - 1))
95 ev = screen.get_key()
96 if ev in (ord('Q'), ord('q')):
97 return
98 screen.refresh()
99
100 Screen.wrapper(demo)
101
102That same code works on Windows, OSX and Linux and paves the way for all the higher level features.
103These still need the Screen, but now you also create a Scene using some Effects and then get the
104Screen to play it. For example, this code:
105
106.. code-block:: python
107
108 from asciimatics.effects import Cycle, Stars
109 from asciimatics.renderers import FigletText
110 from asciimatics.scene import Scene
111 from asciimatics.screen import Screen
112
113 def demo(screen):
114 effects = [
115 Cycle(
116 screen,
117 FigletText("ASCIIMATICS", font='big'),
118 int(screen.height / 2 - 8)),
119 Cycle(
120 screen,
121 FigletText("ROCKS!", font='big'),
122 int(screen.height / 2 + 3)),
123 Stars(screen, 200)
124 ]
125 screen.play([Scene(effects, 500)])
126
127 Screen.wrapper(demo)
128
129should produce something like this:
130
131.. image:: https://asciinema.org/a/18756.png
132 :alt: asciicast
133 :target: https://asciinema.org/a/18756?autoplay=1
134
135Or maybe you're looking to create a TUI? In which case this
136`simple code <https://github.com/peterbrittain/asciimatics/blob/master/samples/contact_list.py>`__
137will give you this:
138
139.. image:: https://asciinema.org/a/45946.png
140 :alt: contact list sample
141 :target: https://asciinema.org/a/45946?autoplay=1
142
143Documentation
144-------------
145
146Full documentation of all the above (and more!) is available at http://asciimatics.readthedocs.org/
147
148More examples
149-------------
150
151More examples of what you can do are available in the project samples directory, hosted on GitHub.
152See https://github.com/peterbrittain/asciimatics/tree/v1.13/samples.
153
154To view them, simply download these files and then simply run them directly with `python`.
155Alternatively, you can browse recordings of many of the samples in the gallery at
156https://github.com/peterbrittain/asciimatics/wiki.
157
158Bugs and enhancements
159---------------------
160
161If you have a problem, please check out the troubleshooting guide at
162http://asciimatics.readthedocs.io/en/latest/troubleshooting.html. If this doesn't solve your
163problem, you can report bugs (or submit enhancement requests) at
164https://github.com/peterbrittain/asciimatics/issues.
165
166Alternatively, if you just have some questions, feel free to drop in at
167https://gitter.im/asciimatics/Lobby.
168
169Contributing to the project
170---------------------------
171
172If you'd like to take part in this project (and see your name in the credits!), check out the
173guidance at http://asciimatics.readthedocs.org/en/latest/contributing.html
174
175
