termgui 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d6f70b10cb11cfc112b4ff9887817ffe36595facee0801121e4ffd1471c9a379
+  data.tar.gz: cec5a76cadece64fa9bd381c43ad1ab207949991c2de1c683a5e5a6cac582c76
+SHA512:
+  metadata.gz: c6b601e0ebd61b28b32ed6740a585b5eb8d3c9f7451ed3615f6bd918646fe7a845e54cb34a091f464625f4790ecaa86f0a54be40c327220c4830e8b612fb310b
+  data.tar.gz: d569497fe644f5d51c91fa6e7e2c50da6abc7a8ce5ea9739198449b34bff01d8ef8ad0a83ee16f4362d1c5b46b1278ea4bc3c46715aee2cd8193de6a5d411623

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+gem 'chunky_png'
+# gem 'justify'
+gem 'rexml'
+gem 'strings'
+
+gem 'filewatcher', group: :development
+gem 'rubocop', require: false, group: :development
+gem 'solargraph', require: false, group: :development
+gem 'test-unit', group: :development
+# gem 'yarn', require: false, group: :development

data/README.md

@@ -0,0 +1,321 @@
+# termgui
+
+Repository: https://github.com/cancerberoSgx/termgui
+
+ * Command line graphical user interface Ruby toolkit.
+ * Create desktop-like interfaces in the command line.
+ * Personal ruby-learning project at the beginning
+ * 100% ruby, no binaries, no dependencies
+ * some ideas taken from npm.org/blessed and my own npm.org/accursed
+ * HTML DOM like high level API with styles, layouts, box-model, cascade styles
+ * xml / edb support for declaring components in XML syntax
+ * rendered optionally supporting a buffer to print out the current screen for testing
+ * very well tested
+ * flexible managers for focus, actions, scroll, keys, input grab, input grab, cursor
+ * event loop supporting set_timeout, wait_for, set_interval 
+ * text-area / editor support
+ * all colors and attributes
+ * some basic high level widgets: Button, Label, InputBox, TextArea, Editor, Select, 
+ * independent low level APIs can be used without the high level overhead for listening stdin, drawing, etc
+ * box drawing, easing, css parser and dom selector 
+
+
+## TODO / Status
+
+See [TODO](TODO.md)
+
+
+## Motivation
+
+ * I don't want to use ncurses based dependencies since is binary
+ * I know there are a couple of initiatives 100% in ruby now, but I didn't knew them when I started this project
+ * I'm the author of npm.org/accursed which is a similar library so I can of already implemented this in JavaScript
+ * Initially a pet project to learn Ruby
+
+## Usage
+
+```
+gem install termgui
+```
+
+### Example
+
+```rb
+require 'termgui'
+screen = Screen.new
+left =  screen.append_child Col.new(width: 0.4, height: 0.99, style: { bg: 'red' })
+(0..8).map { |i| left.append_child Label.new(text: "Label_#{i}") }
+right = screen.append_child Col.new(width: 0.6, height: 0.99, x: 0.4, style: {bg: 'blue'))
+(0..4).map do |i|
+  right.append_child Button.new(
+    text: "Button_#{i}", x: 0.5,
+    style: {focus: {fg: '#ed5525'}},
+    action: proc { open_modal(screen: screen, title: "Button_#{i}") }
+  )
+end
+screen.start
+```
+
+Result:
+
+![readme_screenshot01](readme_screenshot01.jpg)
+
+## Development commands
+
+```sh
+cd termui
+bundler install
+sh bin/test
+sh bin/doc
+sh bin/dev   # rails server
+sh bin/watch # tests in watch mode
+```
+
+## API Reference
+
+TODO
+
+### low level (working) examples
+
+TODO
+
+#### No DOM - just draw
+
+TODO
+
+#### Only Input
+
+TODO
+
+#### Only Renderer
+
+TODO
+
+
+
+
+## Element attributes
+
+Some high level element attributes implemented:
+
+### style-cascade
+
+By default, children inherit parent style. If `element.get_attribute('style-cascade') == 'prevent'` it won't happen - this is the children won't be affected by its parent style and only its own is rendered. 
+
+### focusable, focused and screen.focus.keys, focus, blur
+
+elements with focusable attribute will be able to be focused when user press focus keys (configurable in screen.focus.keys ). By default screen.focus.keys ==  { next: ['tab'], prev: ['S-tab'] }. 
+
+focusable elements will emit "focus" and "blur" events
+
+When focused, the attribute focused will be true and the element is able to receive "action" event (see actionable, action-keys below)
+
+### actionable, action-keys, action
+
+this is useful to implement actionable widgets like buttons that, when focused, can emit "action" events when certain keys are pressed (by default ENTER)
+
+focused elements with attribute "actionable" will emit "action" events if user press action-keys (enter by default) when they are focused. Action keys can be configured globally using screen.action.keys or by element with attribute action-keys. Both could be a string or array. 
+
+
+### action-on-focus
+
+automatically trigger an action event wneh an element is focused. helpful for selectbox so no enter is needed for working
+
+### escape-on-blur
+
+automatically escapes an entered element on blur. helpful for selectbox so no escape is needed for switching focus - so it behaves like buttons
+
+
+### enterable, entered, change, input, escape, escape-keys
+
+This is useful to implement textarea / textinput widgets for which we don't want to trigger focus or action events when user is writing text. When an enterable element (that also should be focusable) receives "action" it is set to "entered" mode. (whey you are writing text, you want TAB S-tab, enter, etc to actually insert characters and don't emit "focus" "action", etc events...)
+
+When an element is on this mode (only one at a time) the rest of the elements will stop receiving common events like focus or action until it leaves the entered mode. . This could happen programmatically or by receiving "escape" event, by default pressing ESC will provoke "escape" event which will set entered = false and enable normal events again (like focus, action, etc). When entered==true, the entered element will listen for input independently and emit "input" events. 
+
+the enter event by default is provoked by "action" (enter) so it can be configured individually using action-keys. 
+
+the escape event by default pressing "escape" can be configurable per element using attribute escape-keys (just like action-keys)
+
+TODO: configure to better play with focus: enter-on-focus to automatically "entered" without "action" and automatically "escape" on "blur" (focus will keep working on this case). Also is not clear how escape plays with change 
+
+
+
+
+## Performance notes
+
+ * disabling renderer buffer speeds up rendering about 30%: `screen.renderer.no_buffer = true`. Genereally don't needed in production.
+
+
+## API example prototypes (WIP)
+
+** initial design stories**
+
+### layout
+
+TODO  / proposal
+
+```
+require 'termgui'
+class AppExplorer < Column
+  def initialize(model)
+    super
+    @model=model
+    @text = append_child(text: Textarea.new model.text, onChange: {|e| print e.key})
+    @text.onChange {|e| print e.key}
+  end
+end
+screen = Screen.new
+main = Row.new
+left = main.append_child(Column.new 0.3)
+right = main.append_child(Column.new 0.7)
+explorer = left.append_child(AppExplorer.new model)
+editor = right.append_child(AppEditor.new model)
+screen start
+```
+
+### structure
+
+TODO  / proposal
+
+```
+class MyWidget < Column
+  def initialize
+    super 0.5
+    append_children [
+      {type: Row, height: 0.6, children: [
+        {type: Input, value: 'edit me', width: 0.5, onChange: {|e|print e} },
+        {type: Label, text: 'edit me'},
+      ]}
+      {type: Button, text: 'click me', onClick: {|e|print e}},
+    ]
+  end
+end
+```
+
+#### aside
+
+```
+{type: Button, text: 'click me', onclick: {|e|print e}},
+vs
+Button.new text: 'click me', onclick: {|e|print e}},
+
+{type: Row, height: 0.6, children: [
+  {type: Input, value: 'edit me', width: 0.5, onChange: {|e|print e} },
+  {type: Label, text: 'hello'},
+]}
+vs
+Row.new height: 0.6, children: [
+  Input.new value: 'edit me', width: 0.5, onChange: {|e|print e},
+  Label new: label: 'hello'
+]
+```
+
+### style
+
+style = {
+  '.primary': {
+    bg: 'red',
+    fg: 'black'
+    bold: true
+  }
+}
+screen.append_child(Column.new children: [
+  Label.new text: 'are you sure?',
+  Button.new
+])
+
+
+### high level no layout
+
+TODO / proposal
+
+```
+s=Screen.new
+b=Button.new(parent: s.document, width: 0.3, height: 0.3, left: 0, top: 0, label: 'click me', onClick: { |e| alert "#{e.target.label} clicked!" })
+s.start
+```
+
+### example low level
+
+(no HTML DOM at all, just drawing)
+```
+screen = Screen.new
+screen.renderer.rect(2,3,9,3,'-', {fg: 'yellow', bg: 'gray'})
+screen.renderer.text(x: 3, y: 4,text; 'click me', style: Style.new(fg: '#ffee11', bg: 'black', bold: true))
+```
+
+### events
+
+```
+screen=Screen.new
+screen.event.add_listener('key', {|e| exit 0 if e.key=='q'})
+renderer.text(text: 'press q to exit')
+```
+
+
+
+## Design
+
+### concepts
+
+Screen: contains document, renderer, buffer, Input
+
+Renderer: responsible of drawing given pixels to the terminal
+
+Buffer: maintains screen as bitmap structure (so users can read the current screen contents like a bitmap)
+
+Document: Node subclass analog to html's (access to parent screen)
+
+Node: DOM like representation analog to html's (children, attributes)
+
+Element: Node subclass analog to html's (border, margin, padding)
+
+Input: responsible of user input - notifies screen - emitter
+
+## Summary
+
+I'm author of npm.org/flor that although has superior terminal support (tput) I would like to re implement a similar library for ruby, writing it from scratch (currently learning ruby).
+
+ * low level html-canvas like to set attributes and write strings
+  * try to stick to html canvas api for Renderer
+  * user is responsible of setting the 'active style' like canvas' stroke-width - this simplifies renderer
+ * renderer of styled strings supporting cursor management,
+  *  responsible of translating user's `{bg: 'red', s: 'hello'}` into a string with ansi codes
+ * screen maintains a virtual Buffer so current drawn screen can be accessed like a bitmap
+ * a DOM like API for children, attributes, box model, style
+  * supports user input events also like html dom EventSource (element.add_listener('key', ...))
+  * basic widget implementations: button,input,textarea
+ * style: fg, bg, ch, bold, etc.
+ * focus management: focused/focusable - element.style.focus
+ * input event loop : set_timeout
+ * easy keyboard event representation and API
+
+## Future
+
+add features from npm.org/flor:
+
+ * scroll (element.scrollX=0.2) - dom support
+ * a xmlish syntax for defining GUI.
+   * support function attributes for event handlers as ruby fragments
+
+## Side projects
+
+ * cli/driver for ruby : for properly testing termgui we need cli-driver for ruby. see probes/stdin.rb for working exec and writing to process stdin async
+
+
+## Design notes
+
+TODO
+
+Screen, renderer, input are responsible of basic terminal styles like bg, fg, bold, etc.
+
+On top of the screen, renderer and input a document object model like HTML DOM is supported. See Node, Element, Style, etc. Some features based on HTML supported are:
+
+ * box model similar
+ * children rendering
+ * text
+ * element query
+ * border
+ * padding
+
+Some high level utilities, like the focus/action management, work on top of this DOM so probably 99% of users will want to go that way for building their GUIs.

data/lib/termgui.rb

@@ -0,0 +1 @@
+require_relative '../src/termgui'

data/src/action.rb

@@ -0,0 +1,58 @@
+require_relative 'event'
+require_relative 'emitter'
+require_relative 'util'
+
+module TermGui
+  # action manager - it notifies focused elements on user input
+  # WIP
+  # defines action concept semantics like "action", "input"
+  # "focus": user press tab and it set focus on the next focusable element
+  # "enter": user focus a button and press enter or space. The button will receive an "action" event.
+  # "input": user focus a textarea, press enter ("action") and this enters in the "edit" mode
+  # meaning all user input now it's being notified ONLY to the textarea. Nor even the focus manager or
+  # others will be notified.
+  # "escape": when in a textarea "edit" mode, user press ESCAPE to exit it, meaning now user input will
+  # be notified to all listeners. Example: when in edit mode, pressing TAB will just print a tab in the
+  # textarea and it won't change focus as usual. For that to happen user presses escape to exit the "edit" mode.
+  # Attributes enabling each action:
+  # "enterable"
+  # "focusable"
+  # in the case of scape it will be enabled iff enterable is true
+  # For example a Label is not focusable or enterable. A Button is focusable but not enterable. A textatra is focusable and enterable.
+  class ActionManager < Emitter
+    attr_accessor :keys
+
+    def initialize(event: nil, focus: nil)
+      super()
+      @event = event
+      @focus = focus
+      @event.add_any_key_listener { |e| handle_key e }
+      install(:action)
+      @keys = ['enter']
+    end
+
+    def handle_key(e)
+      focused = @focus.focused
+      return unless focused && !focused.get_attribute('entered')
+
+      action_keys = to_array(focused.get_attribute('action-keys') || keys)
+      if action_keys.include?(e.key) && focused.get_attribute('focusable')
+        event = ActionEvent.new focused, e
+        focused_action = focused.get_attribute('action')
+        focused_action&.call(event)
+        trigger event.name, event
+        focused.trigger event.name, event
+      end
+    end
+  end
+
+  # An event representing an action, like a button "clicked"
+  class ActionEvent < NodeEvent
+    def initialize(target, original_event = nil)
+      super 'action', target, original_event
+    end
+  end
+end
+
+ActionEvent = TermGui::ActionEvent
+ActionManager = TermGui::ActionManager

data/src/box.rb

@@ -0,0 +1,90 @@
+BOXES = {
+  single: {
+    topLeft: '┌',
+    topRight: '┐',
+    bottomRight: '┘',
+    bottomLeft: '└',
+    vertical: '│',
+    horizontal: '─'
+  },
+  double: {
+    topLeft: '╔',
+    topRight: '╗',
+    bottomRight: '╝',
+    bottomLeft: '╚',
+    vertical: '║',
+    horizontal: '═'
+  },
+  round: {
+    topLeft: '╭',
+    topRight: '╮',
+    bottomRight: '╯',
+    bottomLeft: '╰',
+    vertical: '│',
+    horizontal: '─'
+  },
+  bold: {
+    topLeft: '┏',
+    topRight: '┓',
+    bottomRight: '┛',
+    bottomLeft: '┗',
+    vertical: '┃',
+    horizontal: '━'
+  },
+  single_double: {
+    topLeft: '╓',
+    topRight: '╖',
+    bottomRight: '╜',
+    bottomLeft: '╙',
+    vertical: '║',
+    horizontal: '─'
+  },
+  double_single: {
+    topLeft: '╒',
+    topRight: '╕',
+    bottomRight: '╛',
+    bottomLeft: '╘',
+    vertical: '│',
+    horizontal: '═'
+  },
+  classic: {
+    topLeft: '+',
+    topRight: '+',
+    bottomRight: '+',
+    bottomLeft: '+',
+    vertical: '|',
+    horizontal: '-'
+  }
+}.freeze
+
+def boxes
+  BOXES
+end
+
+def draw_box(width: 0, height: 0, style: :single, content: ' ')
+  box = BOXES[style ? style.to_sym : :single]
+  lines = []
+
+  (0..height - 1).each do |y|
+    line = []
+    (0..width - 1).each do |x|
+      line .push(if y.zero? && x.zero?
+                   box[:topLeft]
+                 elsif y == height - 1 && x.zero?
+                   box[:bottomLeft]
+                 elsif y.zero? && x == width - 1
+                   box[:topRight]
+                 elsif y == height - 1 && x == width - 1
+                   box[:bottomRight]
+                 elsif y == height - 1 || y.zero?
+                   box[:horizontal]
+                 elsif x == width - 1 || x.zero?
+                   box[:vertical]
+                 else
+                   content
+              end)
+    end
+    lines.push(line.join(''))
+  end
+  lines
+end

data/src/color.rb

@@ -0,0 +1,174 @@
+# # # fast acceptable color comparision by myself
+# # def color_distance1(c1, c2)
+# #   sum = 0
+# #   c1.each_index do |i|
+# #     sum += (c1[i].abs2 - c2[i].abs2).abs
+# #   end
+# #   sum
+# # end
+
+# def color_distance3(c1, c2)
+#   sum = 0
+#   coef = [1, 1, 1]
+#   c1.each_index do |i|
+#     sum += ((c1[i] - c2[i]) * coef[i]).abs2
+#   end
+#   sum
+# end
+
+# # // As it happens, comparing how similar two colors are is really hard. Here is
+# # // one of the simplest solutions, which doesn't require conversion to another
+# # // color space, posted on stackoverflow[1]. Maybe someone better at math can
+# # // propose a superior solution.
+# # // [1] http://stackoverflow.com/questions/1633828
+# def color_distance2(c1, c2)
+#   # function colorDistance(r1, g1, b1, r2, g2, b2) {
+#   #   return Math.pow(30 * (r1 - r2), 2)
+#   #     + Math.pow(59 * (g1 - g2), 2)
+#   #     + Math.pow(11 * (b1 - b2), 2);
+#   # }
+#   (30 * (c1[0] - c2[0])).abs2 + (59 * (c1[1] - c2[1])).abs2 + (11 * (c1[2] - c2[2])).abs2
+# end
+
+# # // This might work well enough for a terminal's colors: treat RGB as XYZ in a
+# # // 3-dimensional space and go midway between the two points.
+# # exports.mixColors = function(c1, c2, alpha) {
+# #   // if (c1 === 0x1ff) return c1;
+# #   // if (c2 === 0x1ff) return c1;
+# #   if (c1 === 0x1ff) c1 = 0;
+# #   if (c2 === 0x1ff) c2 = 0;
+# #   if (alpha == null) alpha = 0.5;
+
+# #   c1 = exports.vcolors[c1];
+# #   var r1 = c1[0];
+# #   var g1 = c1[1];
+# #   var b1 = c1[2];
+
+# #   c2 = exports.vcolors[c2];
+# #   var r2 = c2[0];
+# #   var g2 = c2[1];
+# #   var b2 = c2[2];
+
+# #   r1 += (r2 - r1) * alpha | 0;
+# #   g1 += (g2 - g1) * alpha | 0;
+# #   b1 += (b2 - b1) * alpha | 0;
+
+# #   return exports.match([r1, g1, b1]);
+# # };
+
+# # the rest is obsoleted by src/tco
+
+# # color enumerations and utilities. See http://ascii-table.com/ansi-escape-sequences.phpsss
+# require_relative 'key'
+
+# # obsolete
+# COLORS = {
+#   black: 0,
+#   red: 1,
+#   green: 2,
+#   yellow: 3,
+#   blue: 4,
+#   magenta: 5,
+#   cyan: 6,
+#   white: 7
+# }.freeze
+
+# # obsolete
+# def color_names
+#   %w[black red green yellow blue magenta cyan white]
+# end
+
+# # obsolete
+# def random_color
+#   color_names.sample
+# end
+
+# # obsolete
+# def color_text(content, fg = nil, bg = nil)
+#   colored = color(fg, bg)
+#   colored << content
+#   colored << "#{CSI}0m"
+# end
+
+# # obsolete
+# def color(fg = nil, bg = nil)
+#   colored = ''
+#   colored << color_to_escape(fg, 30) if fg
+#   colored << color_to_escape(bg, 40) if bg
+# end
+
+# # obsolete
+# def color_to_escape(name, layer)
+#   short_name = name.to_s.sub(/\Abright_/, '')
+#   color = COLORS.fetch(short_name.to_sym)
+#   escape = "#{CSI}#{layer + color}"
+#   escape << ';1' if short_name.size < name.size
+#   escape << 'm'
+#   escape
+# end
+
+# # # https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
+# # ATTRIBUTES = {
+# #   normal: 0,
+
+# #   bold: 1,
+# #   boldOff: 22,
+
+# #   faint: 2,
+# #   faintOff: 22,
+
+# #   italic: 3,
+# #   italicOff: 23,
+
+# #   underline: 4,
+# #   underlineOff: 24,
+
+# #   blink: 5,
+# #   slowBlink: 5,
+# #   rapidBlink: 6,
+# #   blinkOff: 25,
+# #   slowBlinkOff: 25,
+# #   rapidBlinkOff: 25,
+
+# #   inverse: 7,
+# #   inverseOff: 27,
+
+# #   defaultForeground: 39,
+# #   defaultBackground: 49,
+
+# #   invisible: 8,
+# #   invisibleOff: 28,
+
+# #   fraktur: 20,
+# #   frakturOff: 23,
+
+# #   framed: 51,
+# #   encircled: 52,
+# #   overlined: 53,
+
+# #   framedOff: 54,
+# #   encircledOff: 54
+# # }.freeze
+
+# # # Usage: screen.write attributes(blink: true).
+# # # Attributes supported: bold, inverse, blink, slowBlink, rapidBlink, invisible, fraktur, framed, encircled, normal,
+# # # italic, underline, faint
+# # #
+# # # Esc[Value;...;Valuem  Set Graphics Mode:
+# # # Calls the graphics functions specified by the following values.
+# # # These specified functions remain active until the next occurrence of this escape sequence. Graphics mode changes the
+# # # colors and attributes of text (such as bold and underline) displayed on the screen
+# # def attributes(**args)
+# #   output = []
+# #   args.keys.each do |key|
+# #     if args[key] == true
+# #       output.push ATTRIBUTES[key].to_s
+# #     elsif args[key] == false
+# #       output.push ATTRIBUTES[:blinkOff].to_s if key == :blink
+# #       output.push "#{CSI}#{ATTRIBUTES[:boldOff]}" if key == :bold
+# #       # TODO: the rest
+# #     end
+# #   end
+# #   # p output
+# #   !output.empty? ? "#{CSI}#{output.join(';')}m" : ''
+# # end