2015-07-08 07:06:43 +03:00
|
|
|
brick
|
|
|
|
-----
|
|
|
|
|
2015-07-09 21:02:24 +03:00
|
|
|
[![Build Status](https://travis-ci.org/jtdaugherty/brick.png)](https://travis-ci.org/jtdaugherty/brick)
|
|
|
|
|
2015-07-08 07:06:43 +03:00
|
|
|
`brick` is a terminal user interface programming
|
|
|
|
library written in Haskell, in the style of
|
|
|
|
[gloss](http://hackage.haskell.org/package/gloss). This means you write
|
|
|
|
a function that describes how your user interface should look, but the
|
|
|
|
library takes care of a lot of the book-keeping that so commonly goes
|
|
|
|
into writing such programs.
|
|
|
|
|
2015-07-22 05:45:17 +03:00
|
|
|
`brick` exposes a declarative API. Unlike most GUI toolkits which
|
|
|
|
require you to write a long and tedious sequence of "create a widget,
|
|
|
|
now bind an event handler", `brick` just requires you to describe
|
|
|
|
your interface -- even the bits that are stateful -- using a set of
|
|
|
|
declarative combinators and it does the rest. All you have to do is
|
|
|
|
provide functions to transform your own application state when input (or
|
|
|
|
other kinds of) events arrive.
|
2015-07-08 07:06:43 +03:00
|
|
|
|
2015-07-08 07:49:01 +03:00
|
|
|
Under the hood, this library uses [vty](http://hackage.haskell.org/package/vty).
|
|
|
|
|
2015-07-08 07:38:54 +03:00
|
|
|
This library deprecates [vty-ui](https://github.com/jtdaugherty/vty-ui).
|
|
|
|
|
2015-07-21 05:02:53 +03:00
|
|
|
Feature Overview
|
|
|
|
----------------
|
|
|
|
|
2015-07-21 05:07:33 +03:00
|
|
|
`brick` comes with a bunch of widget types to get you started:
|
2015-07-21 05:02:53 +03:00
|
|
|
|
|
|
|
* Vertical and horizontal box layout widgets
|
|
|
|
* Basic single- and multi-line text editor widgets
|
|
|
|
* List widget
|
|
|
|
* Progress bar widget
|
|
|
|
* Simple dialog box widget
|
|
|
|
* Border-drawing widgets (put borders around or in between things)
|
2015-07-21 23:08:19 +03:00
|
|
|
* Generic scrollable viewports
|
2015-07-22 04:30:33 +03:00
|
|
|
* Extensible widget-building API
|
2015-07-22 05:37:55 +03:00
|
|
|
* (And many more general-purpose layout control combinators)
|
2015-07-21 05:02:53 +03:00
|
|
|
|
|
|
|
In addition, some of `brick`'s more powerful features may not be obvious
|
|
|
|
right away:
|
|
|
|
|
|
|
|
* All widgets can be arranged in predictable layouts so you don't have
|
|
|
|
to worry about terminal resizes.
|
|
|
|
* Most widgets can be made scrollable *for free*.
|
2015-07-24 09:14:44 +03:00
|
|
|
* Attribute management is flexible and can be customized at runtime on
|
|
|
|
a per-widget basis.
|
2015-07-21 05:02:53 +03:00
|
|
|
|
2015-07-22 05:45:17 +03:00
|
|
|
`brick` exports [lens](http://github.com/ekmett/lens) and non-`lens`
|
|
|
|
interfaces for most things, so you can get the full power of `lens` if
|
|
|
|
you want it or use plain Haskell if you don't. If a `brick` library
|
2015-07-22 19:41:51 +03:00
|
|
|
function named `thing` has a `lens` version, the `lens` version is named
|
|
|
|
`thingL`.
|
2015-07-22 05:45:17 +03:00
|
|
|
|
2015-07-08 07:38:54 +03:00
|
|
|
Getting Started
|
|
|
|
---------------
|
|
|
|
|
2015-07-24 09:11:49 +03:00
|
|
|
TLDR:
|
2015-07-08 07:08:54 +03:00
|
|
|
|
2015-07-08 07:38:54 +03:00
|
|
|
```
|
|
|
|
$ cabal sandbox init
|
2015-07-13 08:34:09 +03:00
|
|
|
$ cabal install -j -f demos
|
2015-07-08 07:38:54 +03:00
|
|
|
$ .cabal-sandbox/bin/brick-???-demo
|
|
|
|
```
|
2015-07-08 07:56:28 +03:00
|
|
|
|
2015-07-24 09:11:49 +03:00
|
|
|
To get started, see the [first few sections of the brick
|
|
|
|
manual](docs/index.rst).
|
|
|
|
|
|
|
|
Documentation
|
|
|
|
-------------
|
|
|
|
|
|
|
|
Your documentation options, in recommended order, are:
|
|
|
|
|
|
|
|
* [The brick manual](docs/index.rst)
|
|
|
|
* Haddock (all modules)
|
|
|
|
|
2015-07-08 07:56:28 +03:00
|
|
|
Status
|
|
|
|
------
|
|
|
|
|
|
|
|
`brick` is experimental. It does not yet support many of the features
|
|
|
|
of, say, `vty-ui`. And there are some places were I have deliberately
|
|
|
|
chosen to worry about performance later, for the sake of spending more
|
|
|
|
time on the design. For a while my goal with `brick` will be to develop
|
2015-07-22 05:45:17 +03:00
|
|
|
a very solid core library with minimal features. `brick` exports an
|
|
|
|
extension API that makes it possible to make your own packages and
|
|
|
|
widgets. If you do that, you'll also be helping me by testing whether
|
|
|
|
the exported interface is usable and complete!
|
2015-07-08 07:56:28 +03:00
|
|
|
|
2015-07-24 09:12:35 +03:00
|
|
|
The development of this library has revealed some bugs in `vty`, and
|
|
|
|
I've tried to report those as I go. If they haven't been resolved,
|
2015-07-08 07:57:29 +03:00
|
|
|
you'll see them arise when using `brick`.
|
|
|
|
|
2015-07-09 21:15:21 +03:00
|
|
|
Reporting bugs
|
|
|
|
--------------
|
|
|
|
|
|
|
|
Please file bug reports as GitHub issues. For best results:
|
|
|
|
|
|
|
|
- Include the versions of relevant software packages: `brick`, `ghc`,
|
|
|
|
and `vty` will be the most important ones. Even better, the output
|
|
|
|
of `cabal freeze` would probably be helpful in making the problem
|
|
|
|
reproducible.
|
|
|
|
|
|
|
|
- Clearly describe the behavior you expected ...
|
|
|
|
|
|
|
|
- ... and include a mininal demonstration program that exhibits the
|
|
|
|
behavior you actually observed.
|
|
|
|
|
2015-07-08 07:56:28 +03:00
|
|
|
Contributing
|
|
|
|
------------
|
|
|
|
|
|
|
|
If you decide to contribute, that's great! Here are some guidelines you
|
|
|
|
should consider to make submitting patches easier for all concerned:
|
|
|
|
|
|
|
|
- If you want to take on big things, talk to me first; let's have a
|
2015-07-08 07:57:29 +03:00
|
|
|
design/vision discussion before you start coding. Create a GitHub
|
|
|
|
issue and we can use that as the place to hash things out.
|
2015-07-08 07:56:28 +03:00
|
|
|
- If you make changes, try to make them consistent with the syntactic
|
|
|
|
conventions I've used in the codebase.
|
2015-07-22 05:45:17 +03:00
|
|
|
- Please provide Haddock documentation for any changes you make.
|