less_curse 0.6.0

data/README.md

@@ -0,0 +1,106 @@
+# LessCurse
+
+Simple terminal-based ncurses UIs.
+
+LessCurse is a work-in-progress, but it's unclear how much work and how much progress will happen/is needed.
+
+It will probably just be developed enough to serve as a dead-simple TUI for the trackt time-tracking system.
+
+I'm happy about bug reports and ideas, but chances are high that I cannot react in the way I wish others would do.
+
+## License
+
+LessCurse is released under the GPL, Version 3 or any later version and Copyright 2016 by Felix Wolfsteller.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'lesscurse'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install lesscurse
+
+## Usage
+
+See the examples folder for now.  Note that executing the examples creates a log file next to it (e.g. examples/list.rb.log).
+It boils down to initialize a Screen, populate it with Widgets and create lambdas to react to events (like a list item was selected) or key-presses.
+
+## Concepts
+
+### Screen
+
+There is only one screen and it will fill up your terminal.  Access it via `LessCurse::screen` (or `LessCurse.screen`).
+
+The screen can and should be populated by widgets.  You cannot decide on exact positioning of widgets, as a *tiling*-approach is used.  By default, the screen will split vertically and each widget will take up an equal amount of space.  However, slightly more complex `Grid`-layouts are possible (see below).
+
+Always one widget is focused.
+
+The screen can handle global keyboard input (shortcuts, in LessCurse#actions).  Currently, the TAB key is used to switch the focus of widgets.  CTRL_Q will quit the application.
+
+### The Grid
+
+A Grid can be used if the screen is to be tiled not only vertically, but also horizontally.  Each row will take up an equal amount of space, where each widget in a row shares the space within that row equally.
+
+### Widgets
+
+All (four... :)) widgets inherit from `LessCurse::Widgets::Base` and provide following methods:
+
+  - `new(title: "Shows on top", data: "Shows somewhere")` [creates instance]
+  - `set_default_actions` [populates the @action map (keys to lambdas)]
+  - `draw` [(re)draws the widget]
+  - `handle_input(key)` [deals with input, that will be handed on from main module if focused]
+    has to return true if key press was dealt with
+
+The default look of a widget has a box drawn around it, with an optional title at the top.
+
+#### List
+
+Shows a list where a single item can be selected with the UP and DOWN array keys.
+The list is thought to be able to gobble up **Lists of Objects** which can be selected and are then represented as `List.selected_data`.
+The text which is shown per Object defaults to `object.to_s` but can be overridden by passing a lambda into `List.display_func`.
+
+#### TextView
+
+Shows text.  Doesnt even scroll yet.
+
+#### TextArea
+
+Allows creepy text input.
+
+#### Buttons
+
+Buttons do not look very much like buttons yet, but can execute a lambda on keypress (typically `RETURN`) when focused.
+
+### Popups
+
+
+## Development
+
+After checking out the repo, run `bundle` to install dependencies. You can also run `bundle console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Design goals and decisions
+
+LessCurse aims to solve a specific problem and the library user (me) should be able to hack a UI with ease and without caring too much about configuration.
+
+Thus, LessCurse is **very** oppinionated.
+
+  - No complex layouts, only screen-tiling.
+  - Few options.
+  - No way to get lost in visual design decisions.
+
+Widgets are for now not directly aware of the underlying (ncurses) window, this is a design decision workaround and yet on purpose.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/econya/less_curse.
+

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "lesscurse"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/3col.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# Released under the GPLv3+, Copyright 2016 Felix Wolfsteller
+
+require 'less_curse'
+
+LessCurse.log_to! $PROGRAM_NAME + ".log"
+
+def list_ui
+  simple_list = [1, 2, 3, 4, 5, 6, 7]
+
+  list_ui = LessCurse::Widgets::List.new
+  list_ui.data = simple_list
+  list_ui.on_select = LessCurse::Actions::QUIT
+  list_ui
+end
+
+def hash_ui
+  simple_hash = {rainbows: "fabolous",
+                 unicorns: "magnificient",
+                 sunrise:  "fantastic",
+                 sunset:   "marvellous"}
+  LessCurse::Widgets::List.new data: simple_hash, title: "Hash keys"
+end
+
+def textview_ui
+  LessCurse::Widgets::TextView.new title: 'TextView',
+                                   data: "Showing Text Data\nSecond Line of Text Data"
+end
+
+begin
+  # Display list items
+  LessCurse.screen.add list_ui
+
+  # Display hash items
+  LessCurse.screen.add hash_ui
+
+  # Display important information
+  LessCurse.screen.add textview_ui
+
+  # Display it, really
+  LessCurse.show_screen
+
+  # Deal with keyboard input and keep us living
+  LessCurse.enter_loop!
+
+  # Try to debug
+  LessCurse.screen.windows.each do |widget, window|
+    puts "#{widget} -> #{window}"
+  end
+ensure
+  LessCurse.close_screen
+end

data/examples/file_browser.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# Released under the GPLv3+, Copyright 2016 Felix Wolfsteller
+
+require 'less_curse'
+
+viewer = LessCurse::Widgets::TextView.new title: 'File Content',
+                                          data:  'Use TAB to change focus\n'\
+                                                 'UP/DOWN to select file\n'\
+                                                 'CTRL+Q to quit.'
+
+file_list_ui = LessCurse::Widgets::List.new title: 'Files:',
+                                            data:  Dir['*']
+file_list_ui.on_select = lambda do |selected_file|
+  viewer.title = selected_file
+  if File.file? selected_file
+    viewer.data = File.new(selected_file).readlines
+  else
+    viewer.data = "[Probably a directory]"
+  end
+end
+
+begin
+  # Display file list
+  LessCurse.screen.add file_list_ui
+
+  # Display file content (once file selected)
+  LessCurse.screen.add viewer
+
+  # Show off with header and footer
+  LessCurse.screen.header = "-- ** filebrowser ** --"
+  LessCurse.screen.footer = "[CTRL_Q to quit]"
+
+  # Display it, really
+  LessCurse.show_screen
+
+  # Deal with keyboard input and keep us living
+  LessCurse.enter_loop!
+ensure
+  LessCurse.close_screen
+end

data/examples/grid.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# Released under the GPLv3+, Copyright 2016 Felix Wolfsteller
+
+require 'less_curse'
+
+LessCurse.log_to! $PROGRAM_NAME + ".log"
+
+def list_ui
+  simple_list = [1, 2, 3, 4, 5, 6, 7]
+
+  list_ui = LessCurse::Widgets::List.new
+  list_ui.data = simple_list
+  list_ui.on_select = LessCurse::Actions::QUIT
+  list_ui
+end
+
+def hash_ui
+  simple_hash = {rainbows: "fabolous",
+                 unicorns: "magnificient",
+                 sunrise:  "fantastic",
+                 sunset:   "marvellous"}
+  LessCurse::Widgets::List.new data: simple_hash, title: "Hash keys"
+end
+
+def textview_ui
+  LessCurse::Widgets::TextView.new title: 'TextView',
+                                   data: "Showing Text Data\nSecond Line of Text Data"
+end
+
+begin
+  grid = LessCurse::Grid.new [[list_ui, hash_ui],
+                              [textview_ui]]
+  # Set grid
+  LessCurse.screen.add grid
+
+  # Display it, really
+  LessCurse.show_screen
+
+  # Deal with keyboard input and keep us living
+  LessCurse.enter_loop!
+
+  # Try to debug
+  LessCurse.screen.windows.each do |widget, window|
+    puts "#{widget} -> #{window}"
+  end
+ensure
+  LessCurse.close_screen
+end
+

data/examples/list.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# Released under the GPLv3+, Copyright 2016 Felix Wolfsteller
+
+require 'less_curse'
+
+LessCurse.log_to! $PROGRAM_NAME + ".log"
+
+begin
+# Display list items
+simple_list = [1, 2, 3, 4, 5, 6, 7]
+
+list_ui = LessCurse::Widgets::List.new
+list_ui.data = simple_list
+list_ui.on_select = LessCurse::Actions::QUIT
+
+LessCurse.screen.add list_ui
+LessCurse.show_screen
+LessCurse.enter_loop!
+
+# Display hash items
+simple_hash = {rainbows: "fabolous",
+               unicorns: "magnificient",
+               sunrise:  "fantastic",
+               sunset:   "marvellous"}
+
+list_ui.data = simple_hash
+list_ui.title = "Hash keys"
+
+textview_ui = LessCurse::Widgets::TextView.new title: 'TextView',
+                                               data: "Showing Text Data\nSecond Line of Text Data"
+
+list_ui.on_select = lambda do |selected_item|
+  textview_ui.data = "Selected: #{selected_item}"
+end
+
+LessCurse.screen.add textview_ui
+LessCurse.show_screen
+LessCurse.enter_loop!
+
+LessCurse.screen.windows.each do |widget, window|
+  puts "#{widget} -> #{window}"
+end
+
+ensure
+LessCurse.close_screen
+end

data/examples/list_with_display_func.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# Released under the GPLv3+, Copyright 2016 Felix Wolfsteller
+
+require 'less_curse'
+
+LessCurse.log_to! $PROGRAM_NAME + ".log"
+
+begin
+  # Display hash items
+  list_ui = LessCurse::Widgets::List.new
+  simple_hash = {rainbows: "fabolous",
+                 unicorns: "magnificient",
+                 sunrise:  "fantastic",
+                 sunset:   "marvellous"}
+
+  list_ui.data = simple_hash
+  list_ui.title = "Hash keys"
+
+  list_ui.display_func = lambda {|i| i[0].to_s}
+
+  LessCurse.screen.add list_ui
+  LessCurse.show_screen
+  LessCurse.enter_loop!
+ensure
+  LessCurse.close_screen
+end

data/examples/long_list.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# Released under the GPLv3+, Copyright 2016 Felix Wolfsteller
+
+require 'less_curse'
+
+LessCurse.log_to! $PROGRAM_NAME + ".log"
+
+begin
+  # Display list items
+  simple_list = (1..200).to_a
+
+  list_ui = LessCurse::Widgets::List.new
+  list_ui.data = simple_list
+  list_ui.on_select = LessCurse::Actions::QUIT
+
+  LessCurse.screen.add list_ui
+  LessCurse.show_screen
+  LessCurse.enter_loop!
+ensure
+  LessCurse.close_screen
+end

data/examples/popup.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# Released under the GPLv3+, Copyright 2016 Felix Wolfsteller
+
+require 'less_curse'
+
+LessCurse.log_to! $PROGRAM_NAME + ".log"
+
+begin
+  # Initialize Widgets
+  list_ui = LessCurse::Widgets::List.new
+  list_ui.data = [1, 2, 3, 4, 5, 6, 7]
+
+  button = LessCurse::Widgets::Button.new title: "Square that number in a popup"
+  button.on_press = lambda do |b|
+    selection_square = list_ui.selected_data * list_ui.selected_data
+    LessCurse.screen.show_popup :info, "#{selection_square}!"
+  end
+
+  # Display list items
+  LessCurse.screen.add list_ui
+
+  # Display button
+  LessCurse.screen.add button
+
+  # Display it, really
+  LessCurse.show_screen
+
+  # Deal with keyboard input and keep us living
+  LessCurse.enter_loop!
+ensure
+  LessCurse.close_screen
+end

data/less_curse.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'less_curse/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "less_curse"
+  spec.version       = LessCurse::VERSION
+  spec.authors       = ["Felix Wolfsteller"]
+  spec.email         = ["felix.wolfsteller@gmail.com"]
+
+  spec.summary       = %q{ncurses abstraction layer for terminal-based applications.}
+  spec.description   = %q{LessCurse is a ncurses abstraction layer for terminal-based user interfaces.}
+  spec.homepage      = "https://github.com/econya/less_curse"
+  spec.license       = "GPLv3+"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ffi-ncurses", '~> 0.4'
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/lib/less_curse.rb

@@ -0,0 +1,76 @@
+require 'logger'
+require 'ffi-ncurses'
+
+require 'less_curse/version'
+require 'less_curse/geometry'
+require 'less_curse/screen'
+require 'less_curse/grid'
+require 'less_curse/actions'
+require 'less_curse/null_logger'
+
+require "less_curse/renderer"
+
+require "less_curse/widgets"
+
+# The LessCurse module which gives you static access to your "Screen" and
+# all the UI glory within it.
+module LessCurse
+  @@actions = {
+    FFI::NCurses::KEY_TAB  => lambda { screen.focus_next },
+    FFI::NCurses::KEY_BTAB => lambda { screen.focus_previous }
+    }
+
+  def self.screen
+    @@screen ||= Screen.new
+  end
+
+  def self.show_screen
+    @@screen.show
+  end
+
+  def self.close_screen
+    FFI::NCurses.endwin
+    # flushinp, delwin?
+  end
+
+  def self.window rectangle
+    FFI::NCurses.newwin rectangle.size.height, rectangle.size.width,
+      rectangle.position.y, rectangle.position.x
+  end
+
+  def self.enter_loop!
+    loop do
+      break if !handle_input
+      screen.repaint
+    end
+  end
+
+  # Read from keyboard, handle keypress oneself or dispatch
+  # to focused widget.
+  def self.handle_input
+    key = FFI::NCurses.wgetch FFI::NCurses::stdscr
+    debug_msg "key press: #{key} / keyname: #{FFI::NCurses::keyname key} / #{FFI::NCurses::KEY_CTRL_Q}"
+
+    # That will let us break out of the loop
+    return false if key == FFI::NCurses::KEY_CTRL_Q
+
+    if @@actions[key]
+      # Global actions first
+      @@actions[key].call
+    else
+      screen.focused_widget.handle_input key
+    end
+  end
+
+  def self.debug_msg msg
+    logger.debug msg
+  end
+
+  def self.logger
+    @@logger ||= LessCurse::NullLogger.new
+  end
+
+  def self.log_to! file
+    @@logger = Logger.new(file)
+  end
+end