glimmer-dsl-libui 0.11.7 → 0.11.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07dbccff31a389edf42d2fa69ae2ef9b9542d2117d01dfdb50eb586ebc76306c
-  data.tar.gz: ba4cd480c791257bbbf762e1dd96dff5ab0a04b152ff6c65e4eaf02acc6808e5
+  metadata.gz: fdab64b2358ff1c023582f4a43a9836f40ca6ec416da1c5a2cee53e28292aa4b
+  data.tar.gz: ee871301742d88957411aa4dd106b5a8bc27fe3635db6015d3e7a523b4f0348c
 SHA512:
-  metadata.gz: 6cfdf98cce4e5a8b51abdef7ed0e030314ec580f454897383189140ad01c81be98f1e134422a5e9ca8fd48ee6b96153d595935cbc1b39133c98da20f8e8122e0
-  data.tar.gz: 4b6d53753335cdfad880df26cd6fdc2affa537a101d73ff6d833f2f050fcb0ab24943423ccbd8b08aca9c5c8a063997cb0f43f9731bad3d1eb55fcf92de11182
+  metadata.gz: 27c0c11c786b9d0c3cefaff54f1edb7a23ab1dd9e01ff5e2a29a36495aec1948cf6b522150e3b6fe62fa466eaf700d4bd36fac797b942ca3dbab0834aa3f5703
+  data.tar.gz: 9ac24bfb2892bc1c1ea2fa895e8718e578ca9b56c06dcf0c8028a11424dc414cf505da6b63fb28bd0a537eb0458996eb3cbfe56b932ce71bca0ea90b1eee6201

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Change Log
 
+## 0.11.9
+
+- Support Content Data-Binding to multiple model attributes via `computed_by` option (e.g. `content(@game, :scale, computed_by: [:width, :height])` or `content(@game, computed_by: [:scale, :width, :height])` will rebuild content on changes to `:scale`, `:width`, or `:height`)
+
+## 0.11.8
+
+- Fix issue with applying a `transform` inside a `Glimmer::LibUI::Application`, `Glimmer::LibUI::CustomControl`, `Glimmer::LibUI::CustomWindow`, or `Glimmer::LibUI::CustomShape` (it otherwise worked when using Glimmer GUI DSL in top-level object)
+- Refactor/simplify examples by removing unnecessary `vertical_box`/`horizontal_box` uses
+
 ## 0.11.7
 
 - Fix issue with `table` `checkbox_text_color_column` checkbox edits not working

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2021-2023 Andy Maleh
+Copyright (c) 2021-2024 Andy Maleh
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

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.11.7
+# [<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.8
 ## 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)
@@ -31,7 +31,7 @@ The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/gl
 - [Custom Component](#custom-components) support (Custom Controls, Custom Windows, and Custom Shapes), including external Ruby gems (e.g. [Graphs and Charts](https://github.com/AndyObtiva/glimmer-libui-cc-graphs_and_charts))
 - [Bidirectional/Unidirectional Data-Binding](#data-binding) to declaratively wire and automatically synchronize GUI Views with Models
 - [Scaffolding](#scaffold-application) for new custom windows/controls, apps, and gems
-- [Far Future Plan] Native-Executable packaging on Mac, Windows, and Linux.
+- [Far Future Plan] Native-Executable [packaging](#packaging) on Mac, Windows, and Linux.
 
 Hello, World!
 
@@ -431,7 +431,8 @@ Learn more about the differences between various [Glimmer](https://github.com/An
     - [RubyCrumbler](#rubycrumbler)
     - [Rubio-Radio](#rubio-radio)
     - [PMV Calc](#pmv-calc)
-  - [Process](#process)
+  - [Design Principles](#design-principles)
+  - [Glimmer Process](#glimmer-process)
   - [Resources](#resources)
   - [Help](#help)
     - [Issues](#issues)
@@ -444,6 +445,8 @@ Learn more about the differences between various [Glimmer](https://github.com/An
 
 ## Setup
 
+Note: the newest Ruby 3.3 is not fully supported yet.
+
 Install [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) gem directly into a [maintained Ruby version](https://www.ruby-lang.org/en/downloads/):
 
 ```
@@ -453,7 +456,7 @@ gem install glimmer-dsl-libui
 Or install via Bundler `Gemfile`:
 
 ```ruby
-gem 'glimmer-dsl-libui', '~> 0.11.7'
+gem 'glimmer-dsl-libui', '~> 0.11.8'
 ```
 
 Test that installation worked by running the [Glimmer Meta-Example](#examples):
@@ -485,7 +488,7 @@ Afterwards, to access the Glimmer GUI DSL:
 
 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. Alternatively, beginners can learn from the RubyConf 2023 workshop ["How To Build Desktop Applications in Ruby"](https://github.com/AndyObtiva/how-to-build-desktop-applications-in-ruby), which includes 27 step-by-step exercises. You may refer to the [API](#api) once you have gotten your feet wet with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) and need a more detailed reference.
+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 Style Guide](#glimmer-style-guide), [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. Alternatively, beginners can learn from the RubyConf 2023 workshop ["How To Build Desktop Applications in Ruby"](https://github.com/AndyObtiva/how-to-build-desktop-applications-in-ruby), which includes 27 step-by-step exercises. You may refer to the [API](#api) once you have gotten your feet wet with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) and need a more detailed reference.
 
 If you encounter any issues with the documentation, get stuck with code you do not understand, or notice some out-of-date information, you may contact the project maintainers on the [Glimmer Gitter Chat](https://app.gitter.im/#/room/#AndyObtiva_glimmer:gitter.im). Also, this could be your opportunity to be a good steward of Open-Source Software by contributing a documentation fix in a GitHub Pull Request or reporting a GitHub Issue at least.
 
@@ -660,7 +663,7 @@ Mac | Windows | Linux
 
 Application scaffolding enables automatically generating the directories/files of a new desktop GUI application that follows the MVC architecture and can be packaged as a Ruby gem that includes an executable script for running the app conveniently. It also ensures that software engineers follow the recommended Glimmer DSL for LibUI conventions and best practices. Application Scaffolding greatly improves software engineering productivity when building desktop applications with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui).
 
-Application Scaffolding relies on the juwelier Ruby gem, which expects a local Git config of [`user.name`](https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git#setting-your-git-username-for-every-repository-on-your-computer) (git config --global user.name "FirstName LastName") and `github.user` (`git config --global github.user githubusername`). 
+Application Scaffolding relies on the juwelier Ruby gem, which expects a local Git config of [`user.name`](https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git#setting-your-git-username-for-every-repository-on-your-computer) (git config --global user.name "FirstName LastName") and `github.user` (`git config --global github.user githubusername`).
 
 Scaffold Glimmer DSL for LibUI application with this command:
 
@@ -1663,7 +1666,51 @@ form {
 }
 ```
 
-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.
+The form above will only display fields for a model's customizable attributes, so if they change, the form content will change too.
+
+If you need to rebuild (re-render) content upon changes to multiple model attributes, you can use the `computed_by` option.
+
+Example:
+
+```ruby
+form {
+  stretchy false
+  
+  content(@user, :address, computed_by: [:street, :city, :zipcode]) {
+    @user.address_attributes.each do |attribute|
+      entry {
+        label attribute.to_s.split('_').map(&:capitalize).join(' ')
+        text <=> [@user, attribute]
+      }
+    end
+  }
+}
+```
+
+Now, the content block will get called when changes occur to any of `User` `address` ,`street`, `city`, or `zipcode`.
+
+If you do not have a main attribute that is computed by other attributes, you can leave the main attribute out while using `computed_by`.
+
+Example:
+
+```ruby
+form {
+  stretchy false
+  
+  content(@user, computed_by: [:street, :city, :zipcode]) {
+    @user.address_attributes.each do |attribute|
+      entry {
+        label attribute.to_s.split('_').map(&:capitalize).join(' ')
+        text <=> [@user, attribute]
+      }
+    end
+  }
+}
+```
+
+Now, the content block will get called (rerendered) when changes occur to any of `User` `street`, `city`, or `zipcode`.
+
+Learn more about Content Data-Binding 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.
 
@@ -1743,6 +1790,9 @@ window('hello world', 300, 200) {
   end
 }.show
 ```
+
+Make sure that you follow the [Glimmer Style Guide](#glimmer-style-guide) when writing any Glimmer GUI DSL code.
+
 ## API
 
 Any control returned by a [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) keyword declaration can be introspected for its properties and updated via object-oriented attributes (standard Ruby `attr`/`attr=` or `set_attr`).
@@ -2141,6 +2191,8 @@ The `area` control is a canvas-like control for drawing paths that can be used i
 
 Note that when nesting an `area` directly underneath `window` (without a layout control like `vertical_box`), it is automatically reparented with `vertical_box` in between the `window` and `area` since it would not show up on Linux otherwise.
 
+Also, note that Canvas graphics performance is a bit slow today due to the Ruby LibUI binding making Canvas drawing calls with FFI. There is currently work under way to re-implement the Canvas drawing calls with C Native Extensions, which should speed up performance by 10x-100x once fully implemented. Still, if the `area` control is needed to paint simple or mostly static graphics that do not change much (not updating more than once a second), then current `area` performance should be more than fast enough for those needs.
+
 Here is an example of a declarative `area` with a stable path (you may copy/paste in [`girb`](#girb-glimmer-irb)):
 
 ```ruby
@@ -3786,20 +3838,25 @@ To learn more about the [LibUI](https://github.com/kojix2/LibUI) API exposed thr
 
 ## Packaging
 
-I am documenting options for packaging, which I have not tried myself, but figured they would still be useful to add to the README.md until I can expand further effort into supporting packaging.
+If you are building a productivity tool to help with your work, then packaging the app as a Ruby gem would be a good enough solution (already supported via [Application Scaffolding](#scaffold-application)). Otherwise, I am documenting options for native executable packaging, which I have not tried myself, but figured they would still be useful to add to the README.md until I can expand further effort into supporting packaging.
 
-For Windows, the [LibUI](https://github.com/kojix2/LibUI) project recommends [OCRA](https://github.com/larsch/ocra) (One-Click Ruby Application), which builds Windows executables from Ruby source. And, there is a newer fork of the project that supports newer versions of Ruby called [OCRAN](https://github.com/Largo/ocran).
+For Windows, [OCRAN](https://github.com/Largo/ocran) can build Windows executables from Ruby source code. It is a new maintained alternative version of [OCRA](https://github.com/larsch/ocra) (One-Click Ruby Application).
 
-For Mac, consider [Platypus](https://github.com/sveinbjornt/Platypus) (builds a native Mac app from a Ruby script)
+For Mac, you can consider [Platypus](https://github.com/sveinbjornt/Platypus) (builds a native Mac app from a Ruby script) by following the tutorial ["Create a MacOS desktop application with pure Ruby"](https://dev.to/josephschito/create-macos-application-desktop-with-pure-ruby-tutorial-36io) by Joseph Schito.
 
 For Linux, simply package your app as a [Ruby Gem](https://guides.rubygems.org/what-is-a-gem/) and [build rpm package from Ruby Gem](https://www.redpill-linpro.com/sysadvent/2015/12/07/building-rpms-from-gems.html) or [build deb package from Ruby Gem](https://openpreservation.org/blogs/building-debian-package-ruby-program/).
 
 Also, there is a promising project called [ruby-packer](https://github.com/pmq20/ruby-packer) that supports all platforms.
 
-Last but not least, Ruby recently supported WASM, including the ability to [package a Ruby application as a WASI application](https://github.com/ruby/ruby.wasm#quick-example-how-to-package-your-ruby-application-as-a-wasi-application).
+One more thing to note is that Ruby recently supported WASM, including the ability to [package a Ruby application as a WASI application](https://github.com/ruby/ruby.wasm#quick-example-how-to-package-your-ruby-application-as-a-wasi-application). You can explore combining that with [wasm2native](https://github.com/vshymanskyy/wasm2native) to produce cross-platform native executables.
+
+Otherwise, if you really need comprehensive cross-platform native executable packaging support, consider using [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt), which does offer [cross-platform packaging support](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/docs/reference/GLIMMER_PACKAGING_AND_DISTRIBUTION.md) for apps as MSI/EXE on Windows, APP/DMG/PKG on Mac, and DEB/RPM on Linux out of the box.
+
 
 ## Glimmer Style Guide
 
+The code of the Glimmer GUI DSL is not standard imperative Ruby code because it represents a declarative Domain Specific Language for describing the hierarchical structure of a Graphical User Interface, meaning a language embedded within Ruby that is slightly separate from Ruby. So, it is important that it has a declarative style that helps Software Engineers focus on the visual aspect of the Graphical User Interface in a highly productive manner. As such, multi-line blocks intentionally do not use imperative words like `do; end` that slow readability down, yet the declarative `{}` style that helps give a quick visual view of GUI component nesting at a glance. However, MVC Views are observed for changes by listeners that then invoke imperative logic in Models, so listener multi-line blocks do have the `do; end` style to clearly distinguish imperative code from declarative code in Views. In summary, the Ruby Style Guide is not applicable when writing Glimmer GUI DSL code. Software Engineers must adhere to the Glimmer Style Guide for View code instead to cater to the style requirements of both declarative DSL code and imperative Ruby code.
+
 **1 - Control arguments are always wrapped by parentheses.**
 
 Example:
@@ -4224,13 +4281,25 @@ This is built as an exploratory software prototype by [Ari Brown](https://github
 
 ### Adamantite
 
-A local password manager written in Ruby (closed source software):
+A local password manager written in Ruby:
 
 https://rubygems.org/gems/adamantite
 
 ![Adamantite password manager](/images/glimmer-dsl-libui-mac-application-adamantite.png)
 
-## Process
+## Design Principles
+
+- The Ruby Way (including TIMTOWTDI: There Is More Than One Way To Do It)
+- Requiring the least amount of syntax possible to build GUI (Graphical User Interface)
+- Declarative syntax  that visually maps to the GUI control hierarchy
+- Ability to mix declarative and imperative code conveniently without needing awkward & verbose technologies (e.g. no XML, HTML, ERB scriptlets, JSX)
+- Computers serve Software Engineers (not Software Engineers serve Computers)
+- Think only about real world concepts directly relevant to the GUI and interacting with it (no weird non-real-world irrelevant concepts like hooks/effects/immutability)
+- The Rails Way Convention over Configuration via smart defaults and automation of low-level details
+- Modular Software Design (e.g. support for Components)
+- No premature optimizations
+
+## Glimmer Process
 
 [Glimmer Process](https://github.com/AndyObtiva/glimmer/blob/master/PROCESS.md)
 
@@ -4292,7 +4361,7 @@ Note that the latest development sometimes takes place in the [development](http
 
 [MIT](LICENSE.txt)
 
-Copyright (c) 2021-2023 Andy Maleh
+Copyright (c) 2021-2024 Andy Maleh
 
 --
 

data/VERSION

@@ -1 +1 @@
-0.11.7
+0.11.9

data/bin/girb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-# Copyright (c) 2021-2023 Andy Maleh
+# Copyright (c) 2021-2024 Andy Maleh
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the

data/bin/girb_runner.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2021-2023 Andy Maleh
+# Copyright (c) 2021-2024 Andy Maleh
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the

data/bin/glimmer

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-# Copyright (c) 2021-2023 Andy Maleh
+# Copyright (c) 2021-2024 Andy Maleh
 #
 # Permission is hereby granted, free of charge, to any person obtaining
 # a copy of this software and associated documentation files (the

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

@@ -3015,7 +3015,7 @@ class Tetris
   
   def show_about_dialog
     Glimmer::LibUI.queue_main do
-      msg_box('About', 'Glimmer Tetris - Glimmer DSL for LibUI Example - Copyright (c) 2021-2023 Andy Maleh')
+      msg_box('About', 'Glimmer Tetris - Glimmer DSL for LibUI Example - Copyright (c) 2021-2024 Andy Maleh')
     end
   end
 end