70

GitHub - ebpa/tui.el: An experimental text-based UI framework for Emacs modeled...

 5 years ago
source link: https://github.com/ebpa/tui.el
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

README.org

tui.el

images/tui-bird.png

https://img.shields.io/badge/license-GPL_3-green.svg https://travis-ci.org/ebpa/tui.svg https://coveralls.io/repos/ebpa/tui/badge.svg?branch=master&service=github

⚠ Requires emacs version 26.1 or higher ⚠

Introduction

This is an experiment in building purely text-based user interfaces (TUI’s). The ultimate goal is to explore new paradigms for user interface design and development using Emacs. To this end, tui.el implements an API based on the popular React JavaScript framework in order to reduce the demands involved with designing and building complex text-based UI’s.

This is all currently experimental! Expect things to change as I get feedback about what works, what does not!

Installing

The package hasn’t been submitted to Melpa yet. To install the package manually: clone the repository, add the folder to your load path and install the dependencies with the following:

git clone [email protected]:ebpa/tui.el.git
(add-to-list 'load-path "~/path/to/tui.el")

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/") t)

(package-initialize)
(package-refresh-contents)

;; Manually install package dependencies
(package-install 's)
(package-install 'dash-functional)

Getting started

If all goes well you should be able to require the library and render something to the buffer. The following will render a greeting at the point.

(require 'tui)
(tui-render-element "Hello world!")

Overview

Some familiarity with React should prove extremely helpful in using tui.el. I recommend checking out the introductory material on the React website. In particular- be sure to read the short primer on Thinking in React and the component lifecycle model (diagram).

Syntax

Tui offers an terse syntax for expressing content that roughly resembles the form of JSX. For instance, an expander control consists of a header and some content that is hidden when collapsed by the user: 
(tui-expander
  :heading "A label for the following collapsible lorem ipsum content"
  "Curabitur lacinia pulvinar nibh. "
  "Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum leo, quis tempor ligula erat quis odio. "
  "Sed id ligula quis est convallis tempor. ")

Inititial arguments as parsed key-value pairs and are passed as a plist to an element. A non-keyword-symbol following the property list and all following elements are treated as child elements. They are implicitly passed with the preceding plist properties as a value for :children. This avoids unnecessary repetition in typing :children.

(COMPONENT-NAME
  [[KEYWORD-PROP VALUE] ...]
  [CHILD-1 CHILD-2 ...])

The verbose equivalent to this syntax explicitly expresses the :children property. Note that multiple items must be enclosed by a single list or other element to follow the paired plist structure. The resulting content tree is identical to the previous example.

(tui-expander
  :heading "A label for the following collapsible lorem ipsum content"
  :children
  (list
    "Curabitur lacinia pulvinar nibh. "
    "Fusce suscipit, wisi nec facilisis facilisis, est dui fermentum leo, quis tempor ligula erat quis odio. "
    "Sed id ligula quis est convallis tempor. "))

Lists (and nil)

For convenience, lists may be used to arbitrarily group content. All lists are converted to tui-element nodes when the content is mounted. Null values may also be used arbitrarily. They are ignored at render time, so conditional code may return nil. Content is inserted in-order without separation, so while (list "foo" "bar" "baz") and (list (list "foo") nil (list "bar" "baz")) result in different content trees, they both render ~”foobarbaz”~.

The various forms of improper lists are currently not supported and are reserved for future use.

Text properties

To simplify styling, text properties may be applied to elements using the keyword :text-props. This property value should be a plist of text properties and their values. For example: 
(tui-heading
  :text-props '(help-echo "Yup! This is a heading")
  "A heading!")

Comparison with React

ReactJS equivalents

ReactJStui.elReact.Componenttui-componentReact.PureComponentTODOcreateElement()tui-create-elementcreateFactory()tui-define-componentcloneElement()TODOisValidElement()tui-valid-element-pReact.Childrenunnecessary (use tui-child-nodes)

Components

HTML-like components

(tui-div &key children)(tui-heading &key children)(tui-section &key children)(tui-span &key children)

Other components

(tui-link &key target children)(tui-icon &key icon-set icon-name)(tui-buffer &key buffer children)(tui-line &key children)(tui-fixed-width &key children)(tui-expander &key header initially-expanded children)

Future Work

Things I’m currently working on:

  • [ ] Grid layout
  • [ ] TUI Developer tools

Contributing

If you feel inspired by this little library, contact me on Twitter and let me know! The door is wide open for collaboration! If you have ideas for components I’d love to hear them.

Ideas

Here are a few things I have in mind in case you’re looking for an excuse to explore Emacs’ many features:

org-agenda

There are a lot of opportunities for customizing the org-mode agenda view that could be made possible with components designed for org-mode. Org-super-agenda offers striking examples of grouping agenda content into meaningful elements.

Structure editors

Structure editors are an exciting approach for editing source code and structured data. Build a set of components for representing and interacting with a syntax conceivably eliminates syntax errors altogether!

Charts and graphs

It would be very handy to have a variety of charts and graphs to visualize data within Emacs itself. Emacs already has a good start with the built-in chart.el for bar charts (examples). This would be a good application for drawille.el. Fancy animated charts like blessed-contrib anyone?

Virtual windows

There are circumstances where it would be useful to create divisions within a buffer/window without the behavior associated with additional windows. Imagine various tiled/floating window behavior demonstrated by blessed within a single buffer.

Touch-based interfaces

Why not give Emacs some big blocky buttons and sliders, so we can use our pervasive touchscreens with Emacs too? Or even: design progressive Emacs apps?

Feedback

Requesting components

Suggestions

Button
Calendar
Dropdown
GitHub-style punchcard
Graphs/charts
Sparkline
Week

Related Projects


report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK