glimmer-dsl-libui 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21db2452d3dfbb5c34356de87e7c40380d4e887a25181854321a226cee7640b5
-  data.tar.gz: 5f62aa411e6c890e0c8228d286f273d4ebb056af7b771313a49db0344340a773
+  metadata.gz: effb65102f9db3aa2977bac55edd4f67f91f1eafdae26403b8c044c714048a03
+  data.tar.gz: 3923d80a19afd62a0220026f33720ee953ad166880e17d60883aed53f9977d86
 SHA512:
-  metadata.gz: fabf5fd00b7994fce070e6c200814381c3fbc7df0c38e7742e5d1207d76f0c0e9d1946d5b882ee5c372acd7cc6876e485596d760127a52ada556e6402de2dd31
-  data.tar.gz: 37f4312b11de8d5f2678c2f31e966acfed33617224fcdd4217effdd169bcfd61721b1d1ff64236a4e0957d991f86127fc6c0db55170b3e0b92d5831c5cbc51ec
+  metadata.gz: 6e123f42fd61ce49b126e7f51caf738e0c769eca12b177c879007cedaba6ec38974d16ca864e8d8922546f79cfe2dc8946056935684f0bab9d88892e425c5d79
+  data.tar.gz: 8d0d79d7632e30568f747a3db5d9bbdef387e854f55e0cf6559a4d8d242075bc8c1836e00e2554a30eb5eded934bb23c267a764b127cfe768c39e679ff47671e

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change Log
 
+## 0.11.0
+
+- Control `content` data-binding to generate nested controls dynamically based on a model attribute change
+- `examples/dynamic_form.rb` to demonstrate control `content` data-binding
+
+## 0.10.2
+
+- In Snake example, change snake direction on key press instead of key release to be more responsive for players who are not used to releasing pressed keys quickly
+- In Snake example, fix issue with detecting collision too soon if a snake fills the entire space horizontally or vertically
+- In Snake example, fix issue of hearing beeps on every direction change because of not properly informing LibUI when the area key down event is handled
+- In Snake example, refactor `Snake::Model::Snake` to be more readable like high-level game domain rules (especially `move` method)
+
 ## 0.10.1
 
 - Scaffold custom shape
@@ -8,7 +20,7 @@
 
 ## 0.10.0
 
-- Support Custom Shapes, describing composite shapes/text/image concepts inside an `area`
+- Support Custom Shapes by mixing in `Glimmer::LibUI::CustomShape` to abstract composite shapes/text/image concepts inside an `area`
 - `examples/basic_custom_shape.rb` example
 - Support nesting listeners under a Custom Shape that will automatically get added to its `body_root` control
 - Support nesting listeners under a Custom Control that will automatically get added to its `body_root` control

data/README.md

@@ -1,4 +1,4 @@
-# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.10.1
+# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for LibUI 0.11.0
 ## Prerequisite-Free Ruby Desktop Development Cross-Platform Native GUI Library  ([Fukuoka Award Winning](http://www.digitalfukuoka.jp/topics/187?locale=ja))
 ### The Quickest Way From Zero To GUI
 [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-libui.svg)](http://badge.fury.io/rb/glimmer-dsl-libui)
@@ -431,7 +431,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.10.1'
+gem 'glimmer-dsl-libui', '~> 0.11.0'
 ```
 
 Test that installation worked by running the [Glimmer Meta-Example](#examples):
@@ -452,8 +452,19 @@ Mac | Windows | Linux
 
 ## Usage
 
-Require [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) (whether through a Ruby `require` statement or `Bundler`) and then include the `Glimmer` or `Glimmer::LibUI::Application` module to enable access to the Glimmer GUI DSL in one of multiple approaches.
- 
+Start by requiring the [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) Ruby gem, whether through a Ruby `require 'glimmer-dsl-libui` statement or `Bundler`.
+
+Afterwards, to access the Glimmer GUI DSL:
+- If you are learning/experimenting/prototyping with Glimmer DSL for LibUI, include the `Glimmer` module into the top-level scope or a Ruby class.
+- If you are building a serious application, include `Glimmer::LibUI::Application` into the main view Ruby class
+- If you are building a custom control, include [`Glimmer::LibUI::CustomControl`](#custom-components) into a Ruby class
+- If you are building a cusotm window, include [`Glimmer::LibUI::CustomWindow`](#custom-components) into a Ruby class
+- If you are building a custom shape, include [`Glimmer::LibUI::CustomShape`](#custom-components) into a Ruby class.
+
+You may learn more about the different options above with basic examples in the following subsections: [Experimentation Usage](#experimentation-usage), [Prototyping Usage](#prototyping-usage), [Serious Usage](#serious-usage).
+
+If you are new to [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) (beginner), after going through the subsections below, check out the RubyConf 2022 talk ["Building Native GUI Apps in Ruby"](https://andymaleh.blogspot.com/2023/02/rubyconf-2022-talk-video-for-building.html), [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts), [Glimmer Command](#glimmer-command) (just the basics, how to run an app, and how to run examples to start), [Girb](#girb-glimmer-irb) and [Examples](#examples) to quickly learn through copy/paste. It is very important for beginners to go through all the [Examples](#examples) from the most basic to the most advanced while reading the README topics that relate to the examples. You may refer to the [API](#api) on once you have gotten your feet wet with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) and need more detailed reference information.
+
 ### Experimentation Usage
  
 For experimenting and learning, add `include Glimmer` into the top-level main object and start using the Glimmer GUI DSL directly.
@@ -534,9 +545,6 @@ SomeGlimmerApp.launch
 
 (note: `Glimmer::LibUI::Application` is an alias for `Glimmer::LibUI::CustomWindow` since that is what it represents)
 
-If you are new to [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui), check out the [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts), [Glimmer Command](#glimmer-command), [Girb](#girb-glimmer-irb) and [Examples](#examples) to quickly learn through copy/paste. You may refer to the [API](#api) later on once you have gotten your feet wet with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) and need more detailed reference information.
-
-
 ## Glimmer Command
 
 The `glimmer` command allows you to conveniently run applications (`glimmer app_path`), run examples (`glimmer examples`), and scaffold applications (`glimmer "scaffold[app_name]"`).
@@ -548,7 +556,6 @@ glimmer
 ```
 
 ```
-% bin/glimmer
 Glimmer DSL for LibUI (Prerequisite-Free Ruby Desktop Development Cross-Platform Native GUI Library) - Ruby Gem: glimmer-dsl-libui v0.8.0
 
 Usage: glimmer [--bundler] [--pd] [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-ruby-option]...] (application.rb or task[task_args])
@@ -1592,6 +1599,43 @@ button('greet') { |b|
 }
 ```
 
+If there is ever a need to add more content to a control, you can re-open its content with the `control.content { ... }` method.
+
+Example:
+
+```ruby
+box1 = vertical_box {
+  label('First Name')
+}
+# re-open content of box1 and add another control
+box1.content {
+  entry {
+    text 'fill in your first name'
+  }
+}
+```
+
+You can also use [data-binding](#data-binding) with content blocks to generate content dynamically based on changes in a model attribute. The only difference in syntax in this case would be to wrap the content with an explicit `content(*binding_args) { ... }` block that includes data-binding arguments for a model attribute.
+
+Example:
+
+```ruby
+form {
+  stretchy false
+  
+  content(@user, :customizable_attributes) {
+    @user.customizable_attributes.each do |attribute|
+      entry {
+        label attribute.to_s.split('_').map(&:capitalize).join(' ')
+        text <=> [@user, attribute]
+      }
+    end
+  }
+}
+```
+
+The form above will only display fields for a model's customizable attributes, so if they change, the form content will change too. Learn more at the [Dynamic Form](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#dynamic-form) example.
+
 **Property**: Control properties may be declared inside keyword blocks with lower-case underscored name followed by property value args (e.g. `title "hello world"` inside `group`). Behind the scenes, properties correspond to `LibUI.control_set_property` methods.
 
 **Listener**: Control listeners may be declared inside keyword blocks with listener lower-case underscored name beginning with `on_` and receiving required block handler (always followed by a `do; end` style block to signify logic).
@@ -3388,11 +3432,11 @@ Another example of bidirectional data-binding with an option:
 
 ```ruby
 entry {
-  text <=> [self, :entered_text, after_write: ->(text) {puts text}]
+  text <=> [model, :entered_text, after_write: ->(text) {puts text}]
 }
 ```
 
-That is data-binding `entered_text` attribute on `self` to `entry` `text` property and printing text after write to the model.
+That is data-binding `entered_text` attribute on `model` to `entry` `text` property and printing text after write to the model.
 
 ##### Table Data-Binding
 
@@ -3574,6 +3618,27 @@ window {
 
 That is data-binding the `window` `title` property to the `score` attribute of a `@game`, but converting on read from the Model to a `String`.
 
+You can also use unidirectional [data-binding](#data-binding) with content blocks to generate content dynamically based on changes in a model attribute. The only difference in syntax in this case would be to wrap the content with an explicit `content(*binding_args) { ... }` block that includes data-binding arguments for a model attribute.
+
+Example:
+
+```ruby
+form {
+  stretchy false
+  
+  content(@user, :customizable_attributes) {
+    @user.customizable_attributes.each do |attribute|
+      entry {
+        label attribute.to_s.split('_').map(&:capitalize).join(' ')
+        text <=> [@user, attribute]
+      }
+    end
+  }
+}
+```
+
+The form above will only display fields for a model's customizable attributes, so if they change, the form content will change too. Learn more at the [Dynamic Form](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#dynamic-form) example.
+
 #### Data-Binding API
 
 To summarize the data-binding API:

data/VERSION

@@ -1 +1 @@
-0.10.1
+0.11.0

data/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md

@@ -8,6 +8,7 @@
   - [CPU Percentage](#cpu-percentage)
   - [Custom Draw Text](#custom-draw-text)
   - [Dynamic Area](#dynamic-area)
+  - [Dynamic Form](#dynamic-form)
   - [Editable Column Table](#editable-column-table)
   - [Editable Table](#editable-table)
   - [Form Table](#form-table)
@@ -211,6 +212,33 @@ Version 4 (declarative stable `path` approach without [data-binding](#data-bindi
 
 [examples/dynamic_area4.rb](/examples/dynamic_area4.rb)
 
+
+## Dynamic Form
+
+[examples/dynamic_form.rb](/examples/dynamic_form.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/dynamic_form.rb
+```
+
+Run with this command if you installed the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui):
+
+```
+ruby -r glimmer-dsl-libui -e "require 'examples/dynamic_form'"
+```
+
+![glimmer-dsl-libui-mac-dynamic-form.png](/images/glimmer-dsl-libui-mac-dynamic-form.png)
+
+![glimmer-dsl-libui-mac-dynamic-form-filled.png](/images/glimmer-dsl-libui-mac-dynamic-form-filled.png)
+
+![glimmer-dsl-libui-mac-dynamic-form-summarized.png](/images/glimmer-dsl-libui-mac-dynamic-form-summarized.png)
+
+![glimmer-dsl-libui-mac-dynamic-form-without-some-fields.png](/images/glimmer-dsl-libui-mac-dynamic-form-without-some-fields.png)
+
+![glimmer-dsl-libui-mac-dynamic-form-without-some-fields-summarized.png](/images/glimmer-dsl-libui-mac-dynamic-form-without-some-fields-summarized.png)
+
 ## Editable Column Table
 
 [examples/editable_column_table.rb](/examples/editable_column_table.rb)

data/examples/button_counter.rb

@@ -1,28 +1,35 @@
 require 'glimmer-dsl-libui'
 
-class ButtonCounter
-  include Glimmer
-
+class Counter
   attr_accessor :count
-
+  
   def initialize
     self.count = 0
   end
+end
 
-  def launch
+class ButtonCounter
+  include Glimmer::LibUI::Application
+
+  before_body do
+    @counter = Counter.new
+  end
+
+  body {
     window('Hello, Button!', 190, 20) {
       vertical_box {
         button {
-          # data-bind button text to self count, converting to string on read.
-          text <= [self, :count, on_read: ->(count) {"Count: #{count}"}]
+          # data-bind button text to @counter count, converting to string on read from model.
+          text <= [@counter, :count, on_read: ->(count) {"Count: #{count}"}]
           
           on_clicked do
-            self.count += 1
+            # This change will automatically propagate to button text through data-binding above
+            @counter.count += 1
           end
         }
       }
-    }.show
-  end
+    }
+  }
 end
 
-ButtonCounter.new.launch
+ButtonCounter.launch

data/examples/dynamic_form.rb

@@ -0,0 +1,69 @@
+require 'glimmer-dsl-libui'
+
+class User
+  ALL_ATTRIBUTES = [:first_name, :last_name, :email, :street, :city, :state, :zip_code, :country]
+  
+  attr_accessor :customizable_attributes, *ALL_ATTRIBUTES
+  
+  def initialize
+    # allow customizing all attributes by default
+    self.customizable_attributes = ALL_ATTRIBUTES.dup
+  end
+end
+
+class DynamicForm
+  include Glimmer::LibUI::Application
+  
+  before_body do
+    @user = User.new
+  end
+  
+  body {
+    window('Dynamic Form') {
+      margined true
+      
+      vertical_box {
+        horizontal_box {
+          User::ALL_ATTRIBUTES.each do |attribute|
+            checkbox(attribute.to_s) {
+              checked <=> [@user, :customizable_attributes,
+                           on_read: -> (attributes) { @user.customizable_attributes.include?(attribute) },
+                           on_write: -> (checked_value) {
+                             if checked_value
+                               @user.customizable_attributes.push(attribute)
+                             else
+                               @user.customizable_attributes.delete(attribute)
+                             end
+                             @user.customizable_attributes.sort_by {|attribute| User::ALL_ATTRIBUTES.index(attribute)}
+                           },
+                          ]
+            }
+          end
+        }
+        
+        form {
+          stretchy false
+          
+          # Control content data-binding allows dynamically changing content based on changes in a model attribute
+          content(@user, :customizable_attributes) {
+            @user.customizable_attributes.each do |attribute|
+              entry {
+                label attribute.to_s.split('_').map(&:capitalize).join(' ')
+                text <=> [@user, attribute]
+              }
+            end
+          }
+        }
+
+        button('Summarize') {
+          on_clicked do
+            summary = @user.customizable_attributes.map { |attribute| @user.send(attribute) }.join(', ')
+            msg_box('Summary', summary)
+          end
+        }
+      }
+    }
+  }
+end
+
+DynamicForm.launch

data/examples/snake/model/snake.rb

@@ -47,10 +47,33 @@ class Snake
         self.joins.clear
       end
       
+      def turn_right
+        head.orientation = RIGHT_TURN_MAP[head.orientation]
+      end
+      
+      def turn_left
+        head.orientation = LEFT_TURN_MAP[head.orientation]
+      end
+      
       def move
-        @old_tail = tail.dup
+        create_new_head
+        remove_old_tail
+        if detect_collision?
+          collide_and_die
+        else
+          append_new_head
+          eat_apple if detect_apple?
+        end
+      end
+      
+      def remove_old_tail
+        @old_tail = tail.dup # save in case of growing and keeping old tail
+        @vertebrae.delete(tail)
+      end
+      
+      def create_new_head
         @new_head = head.dup
-        case @new_head.orientation
+        case head.orientation
         when :east
           @new_head.column = (@new_head.column + 1) % @game.width
         when :west
@@ -60,25 +83,28 @@ class Snake
         when :north
           @new_head.row = (@new_head.row - 1) % @game.height
         end
-        if @vertebrae.map {|v| [v.row, v.column]}.include?([@new_head.row, @new_head.column])
-          self.collided = true
-          @game.over = true
-        else
-          @vertebrae.append(@new_head)
-          @vertebrae.delete(tail)
-          if head.row == @game.apple.row && head.column == @game.apple.column
-            grow
-            @game.apple.generate
-          end
-        end
       end
       
-      def turn_right
-        head.orientation = RIGHT_TURN_MAP[head.orientation]
+      def append_new_head
+        @vertebrae.append(@new_head)
       end
       
-      def turn_left
-        head.orientation = LEFT_TURN_MAP[head.orientation]
+      def detect_collision?
+        @vertebrae.map {|v| [v.row, v.column]}.include?([@new_head.row, @new_head.column])
+      end
+      
+      def collide_and_die
+        self.collided = true
+        @game.over = true
+      end
+      
+      def detect_apple?
+        head.row == @game.apple.row && head.column == @game.apple.column
+      end
+      
+      def eat_apple
+        grow
+        @game.apple.generate
       end
       
       def grow

data/examples/snake.rb

@@ -72,12 +72,16 @@ class Snake
                   fill <= [@grid.cells[row][column], :color] # data-bind square fill to grid cell color
                 }
                 
-                on_key_up do |area_key_event|
+                on_key_down do |area_key_event|
+                  handled = true # assume we will handle the event
                   if area_key_event[:key] == ' '
                     @game.toggle_pause
-                  else
+                  elsif %i[up right down left].include?(area_key_event[:ext_key])
                     @keypress_queue << area_key_event[:ext_key]
+                  else
+                    handled = false # we won't handle the event after all
                   end
+                  handled
                 end
               }
             end

data/lib/glimmer/dsl/libui/content_expression.rb

@@ -0,0 +1,41 @@
+# Copyright (c) 2021-2023 Andy Maleh
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require 'glimmer/dsl/static_expression'
+
+module Glimmer
+  module DSL
+    module Libui
+      class ContentExpression < StaticExpression
+        def can_interpret?(parent, keyword, *args, &block)
+          keyword == 'content' &&
+            block_given? &&
+            args.size > 0 &&
+            parent&.respond_to?(:bind_content)
+        end
+  
+        def interpret(parent, keyword, *args, &block)
+          parent.bind_content(*args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/glimmer/dsl/libui/dsl.rb

@@ -40,6 +40,7 @@ module Glimmer
           data_binding
           shine_data_binding
           property
+          content
           string
           operation
           control

data/lib/glimmer/libui/control_proxy.rb

@@ -384,6 +384,19 @@ module Glimmer
         Glimmer::DSL::Engine.add_content(self, Glimmer::DSL::Libui::ControlExpression.new, @keyword, {post_add_content: @content_added}, &block)
       end
       
+      # Data-binds the generation of nested content to a model/property (in binding args)
+      # consider providing an option to avoid initial rendering without any changes happening
+      def bind_content(*binding_args, &content_block)
+        # TODO in the future, consider optimizing code by diffing content if that makes sense
+        content_binding_work = proc do |*values|
+          children.dup.each { |child| child.destroy }
+          content(&content_block)
+        end
+        content_binding_observer = Glimmer::DataBinding::Observer.proc(&content_binding_work)
+        content_binding_observer.observe(*binding_args)
+        content_binding_work.call # TODO inspect if we need to pass args here (from observed attributes) [but it's simpler not to pass anything at first]
+      end
+      
       private
       
       def build_control

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glimmer-dsl-libui
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Andy Maleh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-27 00:00:00.000000000 Z
+date: 2023-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: glimmer
@@ -437,6 +437,7 @@ files:
 - examples/dynamic_area2.rb
 - examples/dynamic_area3.rb
 - examples/dynamic_area4.rb
+- examples/dynamic_form.rb
 - examples/editable_column_table.rb
 - examples/editable_table.rb
 - examples/font_button.rb
@@ -500,6 +501,7 @@ files:
 - lib/glimmer-dsl-libui/ext/rouge/theme/glimmer.rb
 - lib/glimmer/Rakefile
 - lib/glimmer/dsl/libui/bind_expression.rb
+- lib/glimmer/dsl/libui/content_expression.rb
 - lib/glimmer/dsl/libui/control_expression.rb
 - lib/glimmer/dsl/libui/custom_control_expression.rb
 - lib/glimmer/dsl/libui/custom_shape_expression.rb