README.md
1
2
3`brick` is a Haskell terminal user interface (TUI) programming toolkit.
4To use it, you write a pure function that describes how your user
5interface should look based on your current application state and you
6provide a state transformation function to handle events.
7
8`brick` exposes a declarative API. Unlike most GUI toolkits which
9require you to write a long and tedious sequence of "create a widget,
10now bind an event handler", `brick` just requires you to describe your
11interface using a set of declarative layout combinators.
12
13Under the hood, this library builds upon
14[vty](http://hackage.haskell.org/package/vty), so some knowledge of Vty
15will be helpful in using this library.
16
17Example
18-------
19
20Here's an example interface (see `programs/ReadmeDemo.hs`):
21
22```
23withBorderStyle unicode $
24borderWithLabel (str "Hello!") $
25(center (str "Left") <+> vBorder <+> center (str "Right"))
26```
27
28Result:
29
30```
31┌─────────Hello!─────────┐
32│ │ │
33│ │ │
34│ Left │ Right │
35│ │ │
36│ │ │
37└────────────────────────┘
38```
39
40Featured Projects
41-----------------
42
43To get an idea of what some people have done with `brick`, take a look
44at these projects. If you have made something and would like me to
45include it, get in touch!
46
47| Project | Description |
48| ------- | ----------- |
49| [`tetris`](https://github.com/SamTay/tetris) | An implementation of the Tetris game |
50| [`gotta-go-fast`](https://github.com/callum-oakley/gotta-go-fast) | A typing tutor |
51| [`haskell-player`](https://github.com/potomak/haskell-player) | An `afplay` frontend |
52| [`mushu`](https://github.com/elaye/mushu) | An `MPD` client |
53| [`matterhorn`](https://github.com/matterhorn-chat/matterhorn) | A client for [Mattermost](https://about.mattermost.com/) |
54| [`viewprof`](https://github.com/maoe/viewprof) | A GHC profile viewer |
55| [`tart`](https://github.com/jtdaugherty/tart) | A mouse-driven ASCII art drawing program |
56| [`silly-joy`](https://github.com/rootmos/silly-joy) | An interpreter for Joy |
57| [`herms`](https://github.com/jackkiefer/herms) | A command-line tool for managing kitchen recipes |
58| [`purebred`](https://github.com/purebred-mua/purebred) | A mail user agent |
59| [`2048Haskell`](https://github.com/8Gitbrix/2048Haskell) | An implementation of the 2048 game |
60| [`bhoogle`](https://github.com/andrevdm/bhoogle) | A [Hoogle](https://www.haskell.org/hoogle/) client |
61| [`clifm`](https://github.com/pasqu4le/clifm) | A file manager |
62| [`towerHanoi`](https://github.com/shajenM/projects/tree/master/towerHanoi) | Animated solutions to The Tower of Hanoi |
63| [`VOIDSPACE`](https://github.com/ChrisPenner/void-space) | A space-themed typing-tutor game |
64| [`solitaire`](https://github.com/ambuc/solitaire) | The card game |
65| [`sudoku-tui`](https://github.com/evanrelf/sudoku-tui) | A Sudoku implementation |
66| [`summoner-tui`](https://github.com/kowainik/summoner/tree/master/summoner-tui) | An interactive frontend to the Summoner tool |
67| [`wrapping-editor`](https://github.com/ta0kira/wrapping-editor) | An embeddable editor with support for Brick |
68| [`git-brunch`](https://github.com/andys8/git-brunch) | A git branch checkout utility |
69| [`hascard`](https://github.com/Yvee1/hascard) | A program for reviewing "flash card" notes |
70| [`ttyme`](https://github.com/evuez/ttyme) | A TUI for [Harvest](https://www.getharvest.com/) |
71| [`ghcup`](https://www.haskell.org/ghcup/) | A TUI for `ghcup`, the Haskell toolchain manager |
72| [`cbookview`](https://github.com/mlang/chessIO) | A TUI for exploring polyglot chess opening book files |
73| [`thock`](https://github.com/rmehri01/thock) | A modern TUI typing game featuring online racing against friends |
74| [`fifteen`](https://github.com/benjaminselfridge/fifteen) | An implementation of the [15 puzzle](https://en.wikipedia.org/wiki/15_puzzle) |
75| [`maze`](https://github.com/benjaminselfridge/maze) | A Brick-based maze game |
76| [`pboy`](https://github.com/2mol/pboy) | A tiny PDF organizer |
77| [`hyahtzee2`](https://github.com/DamienCassou/hyahtzee2#readme) | Famous Yahtzee dice game |
78
79These third-party packages also extend `brick`:
80
81| Project | Description |
82| ------- | ----------- |
83| [`brick-filetree`](https://github.com/ChrisPenner/brick-filetree) [[Hackage]](http://hackage.haskell.org/package/brick-filetree) | A widget for exploring a directory tree and selecting or flagging files and directories |
84
85Release Announcements / News
86----------------------------
87
88Find out about `brick` releases and other news on Twitter:
89
90https://twitter.com/brick_haskell/
91
92Getting Started
93---------------
94
95Check out the many demo programs to get a feel for different aspects of
96the library:
97
98```
99$ cabal new-build -f demos
100$ find dist-newstyle -type f -name \*-demo
101```
102
103To get started, see the [user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst).
104
105Documentation
106-------------
107
108Documentation for `brick` comes in a variety of forms:
109
110* [The official brick user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst)
111* [Samuel Tay's brick tutorial](https://github.com/jtdaugherty/brick/blob/master/docs/samtay-tutorial.md)
112* Haddock (all modules)
113* [Demo programs](https://github.com/jtdaugherty/brick/blob/master/programs) ([Screenshots](https://github.com/jtdaugherty/brick/blob/master/docs/programs-screenshots.md))
114* [FAQ](https://github.com/jtdaugherty/brick/blob/master/FAQ.md)
115
116Feature Overview
117----------------
118
119`brick` comes with a bunch of batteries included:
120
121 * Vertical and horizontal box layout widgets
122 * Basic single- and multi-line text editor widgets
123 * List widget
124 * Progress bar widget
125 * Simple dialog box widget
126 * Border-drawing widgets (put borders around or in between things)
127 * Generic scrollable viewports
128 * General-purpose layout control combinators
129 * Extensible widget-building API
130 * User-customizable attribute themes
131 * Type-safe, validated input form API (see the `Brick.Forms` module)
132 * A filesystem browser for file and directory selection
133 * Borders can be configured to automatically connect!
134
135Brick-Users Discussion
136----------------------
137
138The `brick-users` Google Group / e-mail list is a place to discuss
139library changes, give feedback, and ask questions. You can subscribe at:
140
141[https://groups.google.com/group/brick-users](https://groups.google.com/group/brick-users)
142
143Status
144------
145
146There are some places were I have deliberately chosen to worry about
147performance later for the sake of spending more time on the design
148(and to wait on performance issues to arise first). `brick` is also
149something of an experimental project of mine and some aspects of the
150design involve trade-offs that might not be right for your application.
151Brick is not intended to be all things to all people; rather, I want it
152to provide a good foundation for building complex terminal interfaces
153in a declarative style to take away specific headaches of building,
154modifying, and working with such interfaces, all while seeing how far we
155can get with a pure function to specify the interface.
156
157`brick` exports an extension API that makes it possible to make your own
158packages and widgets. If you use that, you'll also be helping to test
159whether the exported interface is usable and complete!
160
161Reporting bugs
162--------------
163
164Please file bug reports as GitHub issues. For best results:
165
166 - Include the versions of relevant software packages: your terminal
167 emulator, `brick`, `ghc`, and `vty` will be the most important
168 ones.
169
170 - Clearly describe the behavior you expected ...
171
172 - ... and include a minimal demonstration program that exhibits the
173 behavior you actually observed.
174
175Contributing
176------------
177
178If you decide to contribute, that's great! Here are some guidelines you
179should consider to make submitting patches easier for all concerned:
180
181 - If you want to take on big things, talk to me first; let's have a
182 design/vision discussion before you start coding. Create a GitHub
183 issue and we can use that as the place to hash things out.
184 - Please make changes consistent with the conventions I've used in the
185 codebase.
186 - Please adjust or provide Haddock and/or user guide documentation
187 relevant to any changes you make.
188 - New commits should be `-Wall` clean.
189 - Please do NOT include package version changes in your patches.
190 Package version changes are only done at release time when the full
191 scope of a release's changes can be evaluated to determine the
192 appropriate version change.
193
