glimmer-dsl-libui 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a37cb8210f604b9307693af84b47ba0e21cf2a2b1059139af1d4ffa2eb727bf8
-  data.tar.gz: 88443d069ff718e8d28c90dbb59fc6ff5e5a05a5f3e9f5be78418d1754868769
+  metadata.gz: effb65102f9db3aa2977bac55edd4f67f91f1eafdae26403b8c044c714048a03
+  data.tar.gz: 3923d80a19afd62a0220026f33720ee953ad166880e17d60883aed53f9977d86
 SHA512:
-  metadata.gz: 1a2e8c3f162744fe2266d66a088bceb7595b04643a141b0dd526309b6155362e24fad6c760cc8eb060030fec35352ab96b9dfad7e601e5a168271e1150aa7789
-  data.tar.gz: 90674bbf9623bcd0e985a94824698c3117a8a70bea79f7ee81d11364054c70d57f260466123717d2f292aa50f113cfb11201580a3f74bc74400a100f9c049d6d
+  metadata.gz: 6e123f42fd61ce49b126e7f51caf738e0c769eca12b177c879007cedaba6ec38974d16ca864e8d8922546f79cfe2dc8946056935684f0bab9d88892e425c5d79
+  data.tar.gz: 8d0d79d7632e30568f747a3db5d9bbdef387e854f55e0cf6559a4d8d242075bc8c1836e00e2554a30eb5eded934bb23c267a764b127cfe768c39e679ff47671e

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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

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.2
+# [<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.2'
+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]"`).
@@ -1591,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).
@@ -3387,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
 
@@ -3573,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.2
+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/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.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Andy Maleh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-28 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