glimmer-dsl-libui 0.9.7 → 0.10.0

data/VERSION

@@ -1 +1 @@
-0.9.7
+0.10.0

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

@@ -1271,11 +1271,11 @@ window('Login') {
 
 ## Method-Based Custom Controls
 
-[Custom keywords](#custom-keywords) can be defined to represent custom controls (components) that provide new features or act as composites of existing controls that need to be reused multiple times in an application or across multiple applications. Custom keywords save a lot of development time, improving productivity and maintainability immensely.
+[Custom components](#custom-components) can be defined to represent custom controls (components) that provide new features or act as composites of existing controls that need to be reused multiple times in an application or across multiple applications. Custom components save a lot of development time, improving productivity and maintainability immensely.
   
 This example defines `form_field`, `address_form`, `label_pair`, and `address` as custom controls (keywords).
 
-The custom keywords are defined via methods (thus are "method-based").
+The Custom components are defined via methods (thus are "method-based").
 
 [examples/method_based_custom_controls.rb](/examples/method_based_custom_controls.rb)
 
@@ -1494,11 +1494,11 @@ window('Method-Based Custom Controls') {
 
 ## Class-Based Custom Controls
 
-[Custom keywords](#custom-keywords) can be defined to represent custom controls (components) that provide new features or act as composites of existing controls that need to be reused multiple times in an application or across multiple applications. Custom keywords save a lot of development time, improving productivity and maintainability immensely.
+[Custom components](#custom-components) can be defined to represent custom controls (components) that provide new features or act as composites of existing controls that need to be reused multiple times in an application or across multiple applications. Custom components save a lot of development time, improving productivity and maintainability immensely.
   
 This example defines `form_field`, `address_form`, `label_pair`, and `address` as custom controls (keywords).
 
-The custom keywords are defined via classes that include `Glimmer::LibUI::CustomControl` (thus are "class-based"), thus enabling offloading each custom control into its own file when needed for better code organization.
+The Custom components are defined via classes that include `Glimmer::LibUI::CustomControl` (thus are "class-based"), thus enabling offloading each custom control into its own file when needed for better code organization.
 
 [examples/class_based_custom_controls.rb](/examples/class_based_custom_controls.rb)
 
@@ -1646,7 +1646,7 @@ ClassBasedCustomControls.launch
 
 ## Area-Based Custom Controls
 
-[Custom keywords](#custom-keywords) can be defined for graphical custom controls (components) built completely from scratch as vector-graphics on top of the [`area`](#area-api) control while leveraging keyboard and mouse listeners.
+[Custom components](#custom-components) can be defined for graphical custom controls (components) built completely from scratch as vector-graphics on top of the [`area`](#area-api) control while leveraging keyboard and mouse listeners.
 
 This example defines `text_label` and `push_button` as [`area`](#area-api)-based graphical custom controls that can have width, height, font, fill, stroke, border, and custom text location.
       

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

@@ -26,6 +26,7 @@
   - [Basic Draw Text](#basic-draw-text)
   - [Basic Code Area](#basic-code-area)
   - [Basic Composite Shape](#basic-composite-shape)
+  - [Basic Custom Shape](#basic-custom-shape)
 
 ## Basic Window
 
@@ -2347,6 +2348,8 @@ New [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) Version
 
 ## Basic Composite Shape
 
+(this is the method-based custom shape version of Basic Custom Shape)
+
 [examples/basic_composite_shape.rb](/examples/basic_composite_shape.rb)
 
 Run with this command from the root of the project if you cloned the project:
@@ -2362,3 +2365,23 @@ ruby -r glimmer-dsl-libui -e "require 'examples/basic_composite_shape.rb'"
 ```
 
 ![glimmer-dsl-libui-mac-basic-composite-shape.gif](/images/glimmer-dsl-libui-mac-basic-composite-shape.gif)
+
+## Basic Custom Shape
+
+(this is the class-based custom shape version of Basic Composite Shape)
+
+[examples/basic_custom_shape.rb](/examples/basic_custom_shape.rb)
+
+Run with this command from the root of the project if you cloned the project:
+
+```
+ruby -r './lib/glimmer-dsl-libui' examples/basic_custom_shape.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/basic_custom_shape.rb'"
+```
+
+![glimmer-dsl-libui-mac-basic-custom-shape.gif](/images/glimmer-dsl-libui-mac-basic-composite-shape.gif)

data/examples/basic_composite_shape.rb

@@ -1,5 +1,7 @@
 require 'glimmer-dsl-libui'
 
+# This is the method-based custom shape version of basic_custom_shape
+
 class BasicCompositeShape
   include Glimmer::LibUI::Application
   

data/examples/basic_custom_shape.rb

@@ -0,0 +1,168 @@
+require 'glimmer-dsl-libui'
+
+# This is the class-based custom shape version of basic_composite_shape
+
+# class-based custom shape using Glimmer::LibUI::CustomShape mixin, which automatically
+# augments the Glimmer GUI DSL with the underscored version of the class name: `cube`
+# while accepting hash options matching the options declared on the class.
+# (e.g. `cube(location_x: 50, location_y: 100)` )
+class Cube
+  include Glimmer::LibUI::CustomShape
+  
+  DEFAULT_SIZE = 28
+  
+  option :location_x, default: 0
+  option :location_y, default: 0
+  option :rectangle_width, default: nil
+  option :rectangle_height, default: nil
+  option :cube_height, default: 75
+  option :background_color, default: :brown
+  option :foreground_color
+  option :line_thickness, default: 1
+    
+  # The before_body block executes before building the body
+  before_body do
+    self.rectangle_width ||= rectangle_height || cube_height || DEFAULT_SIZE
+    self.rectangle_height ||= rectangle_width || cube_height || DEFAULT_SIZE
+    self.cube_height ||= rectangle_width || rectangle_height || DEFAULT_SIZE
+    if foreground_color
+      self.foreground_color = Glimmer::LibUI.interpret_color(foreground_color)
+      self.foreground_color[:thickness] ||= line_thickness
+    else
+      self.foreground_color = [0, 0, 0, thickness: line_thickness]
+    end
+  end
+  
+  # Optionally, after_body could be defined to perform operations after building the body
+  # like setting up observers.
+  #
+  # after_body do
+  # end
+  
+  body {
+    # the shape keyword (alias for composite_shape) enables building a composite shape that is treated as one shape
+    # like a cube containing polygons, a polyline, a rectangle, and a line
+    # with the fill and stroke colors getting inherited by all children that do not specify them
+    shape(location_x, location_y) {
+      fill background_color
+      stroke foreground_color
+    
+      bottom = polygon(0, cube_height + rectangle_height / 2.0,
+              rectangle_width / 2.0, cube_height,
+              rectangle_width, cube_height + rectangle_height / 2.0,
+              rectangle_width / 2.0, cube_height + rectangle_height) {
+        # inherits fill property from parent shape if not set
+        # inherits stroke property from parent shape if not set
+      }
+      body = rectangle(0, rectangle_height / 2.0, rectangle_width, cube_height) {
+        # inherits fill property from parent shape if not set
+        # stroke is overridden to ensure a different value from parent
+        stroke thickness: 0
+      }
+      polyline(0, rectangle_height / 2.0 + cube_height,
+               0, rectangle_height / 2.0,
+               rectangle_width, rectangle_height / 2.0,
+               rectangle_width, rectangle_height / 2.0 + cube_height) {
+        # inherits stroke property from parent shape if not set
+      }
+      top = polygon(0, rectangle_height / 2.0,
+              rectangle_width / 2.0, 0,
+              rectangle_width, rectangle_height / 2.0,
+              rectangle_width / 2.0, rectangle_height) {
+        # inherits fill property from parent shape if not set
+        # inherits stroke property from parent shape if not set
+      }
+      line(rectangle_width / 2.0, cube_height + rectangle_height,
+           rectangle_width / 2.0, rectangle_height) {
+        # inherits stroke property from parent shape if not set
+      }
+    }
+  }
+end
+
+class BasicCustomShape
+  include Glimmer::LibUI::Application
+  
+  body {
+    window {
+      title 'Basic Custom Shape'
+      content_size 200, 225
+    
+      @area = area {
+        rectangle(0, 0, 200, 225) {
+          fill :white
+        }
+        
+        7.times do |n|
+          x_location = (rand*125).to_i%200 + (rand*15).to_i
+          y_location = (rand*125).to_i%200 + (rand*15).to_i
+          shape_color = [rand*125 + 130, rand*125 + 130, rand*125 + 130]
+          shape_size = 20+n
+
+          cube(
+            location_x: x_location,
+            location_y: y_location,
+            rectangle_width: shape_size*2,
+            rectangle_height: shape_size,
+            cube_height: shape_size*2,
+            background_color: shape_color,
+            line_thickness: 2
+          ) { |the_shape|
+            on_mouse_up do |area_mouse_event|
+              # Change color on mouse up without dragging
+              if @drag_shape.nil?
+                background_color = [rand(255), rand(255), rand(255)]
+                the_shape.fill = background_color
+              end
+            end
+
+            on_mouse_drag_start do |area_mouse_event|
+              @drag_shape = the_shape
+              @drag_x = area_mouse_event[:x]
+              @drag_y = area_mouse_event[:y]
+            end
+
+            on_mouse_drag do |area_mouse_event|
+              if @drag_shape && @drag_x && @drag_y
+                drag_distance_width = area_mouse_event[:x]  - @drag_x
+                drag_distance_height = area_mouse_event[:y] - @drag_y
+                @drag_shape.x += drag_distance_width
+                @drag_shape.y += drag_distance_height
+                @drag_x = area_mouse_event[:x]
+                @drag_y = area_mouse_event[:y]
+              end
+            end
+
+            on_mouse_drop do |area_mouse_event|
+              @drag_shape = nil
+              @drag_x = nil
+              @drag_y = nil
+            end
+          }
+        end
+        
+        # this general area on_mouse_drag listener is needed to ensure that dragging a shape
+        # outside of its boundaries would still move the dragged shape
+        on_mouse_drag do |area_mouse_event|
+          if @drag_shape && @drag_x && @drag_y
+            drag_distance_width = area_mouse_event[:x]  - @drag_x
+            drag_distance_height = area_mouse_event[:y] - @drag_y
+            @drag_shape.x += drag_distance_width
+            @drag_shape.y += drag_distance_height
+            @drag_x = area_mouse_event[:x]
+            @drag_y = area_mouse_event[:y]
+          end
+        end
+        
+        on_mouse_drop do |area_mouse_event|
+          @drag_shape = nil
+          @drag_x = nil
+          @drag_y = nil
+        end
+      }
+    }
+  }
+end
+
+BasicCustomShape.launch
+        

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

@@ -0,0 +1,58 @@
+# 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'
+require 'glimmer/dsl/expression'
+require 'glimmer/dsl/parent_expression'
+require 'glimmer/dsl/top_level_expression'
+require 'glimmer/libui/custom_shape'
+
+module Glimmer
+  module DSL
+    module Libui
+      class CustomShapeExpression < Expression
+        # TODO Consider making custom shapes automatically generate static expressions
+        include ParentExpression
+        include TopLevelExpression
+
+        def can_interpret?(parent, keyword, *args, &block)
+          LibUI::CustomShape.for(keyword)
+        end
+  
+        def interpret(parent, keyword, *args, &block)
+          options = args.last.is_a?(Hash) ? args.pop : {}
+          LibUI::CustomShape.for(keyword).new(keyword, parent, args, options, &block)
+        end
+  
+        def add_content(custom_shape, keyword, *args, &block)
+          options = args.last.is_a?(Hash) ? args.last : {post_add_content: true}
+          # TODO consider avoiding source_location
+          if block.source_location == custom_shape.content&.__getobj__&.source_location
+            custom_shape.content.call(custom_shape) unless custom_shape.content.called?
+          else
+            super
+          end
+          custom_shape.post_add_content if options[:post_add_content]
+        end
+      end
+    end
+  end
+end

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

@@ -45,6 +45,7 @@ module Glimmer
           control
           custom_control
           shape
+          custom_shape
         ]
       )
     end

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

@@ -27,7 +27,12 @@ module Glimmer
     module Libui
       class ListenerExpression < Expression
         def can_interpret?(parent, keyword, *args, &block)
-          (parent.is_a?(Glimmer::LibUI::ControlProxy) or parent.is_a?(Glimmer::LibUI::Shape)) and
+          (
+            parent.is_a?(Glimmer::LibUI::ControlProxy) or
+            parent.is_a?(Glimmer::LibUI::Shape) or
+            parent.is_a?(Glimmer::LibUI::CustomControl) or
+            parent.is_a?(Glimmer::LibUI::CustomShape)
+          ) and
             block_given? and
             parent.can_handle_listener?(keyword)
         end

data/lib/glimmer/launcher.rb

@@ -100,11 +100,9 @@ module Glimmer
       def launch(application, ruby_options: [], env_vars: {}, glimmer_options: {})
         ruby_options_string = ruby_options.join(' ') + ' ' if ruby_options.any?
         env_vars = env_vars.merge(glimmer_option_env_vars(glimmer_options))
-        env_vars.each do |k,v|
-          ENV[k] = v
-        end
+        load_env_vars(env_vars)
         the_glimmer_lib = glimmer_lib
-        require 'puts_debuggerer' if the_glimmer_lib == GLIMMER_LIB_LOCAL
+        require 'puts_debuggerer' if (ENV['PD'] || ENV['pd']).to_s.downcase == 'true' || the_glimmer_lib == GLIMMER_LIB_LOCAL
         is_rake_task = !application.end_with?('.rb')
         rake_tasks = []
         if is_rake_task
@@ -117,7 +115,6 @@ module Glimmer
           rake_task_args = potential_rake_task_parts[2].split(',')
         end
         if rake_tasks.include?(application)
-          load_env_vars(glimmer_option_env_vars(glimmer_options))
           rake_task = "glimmer:#{application}"
           puts "Running Glimmer rake task: #{rake_task}" if ruby_options_string.to_s.include?('--debug')
           Rake::Task[rake_task].invoke(*rake_task_args)

data/lib/glimmer/libui/custom_control.rb

@@ -31,11 +31,34 @@ module Glimmer
     module CustomControl
       include SuperModule
       include DataBinding::ObservableModel
-
+      
+      # This module was only created to prevent Glimmer from checking method_missing first
+      module GlimmerSupersedable
+        def method_missing(method_name, *args, &block)
+          # TODO Consider supporting a glimmer error silencing option for methods defined here
+          # but fail the glimmer DSL for the right reason to avoid seeing noise in the log output
+          if block && can_handle_listener?(method_name)
+            handle_listener(method_name, &block)
+          elsif @body_root.respond_to?(method_name, true)
+            @body_root.send(method_name, *args, &block)
+          else
+            super
+          end
+        end
+      
+        def respond_to?(method_name, *args, &block)
+          result = false
+          result ||= super
+          result ||= can_handle_listener?(method_name)
+          result ||= @body_root.respond_to?(method_name, *args, &block)
+        end
+      end
+      
       super_module_included do |klass|
-        # TODO clear memoization of WidgetProxy.libui_class_for for a keyword if a custom control was defined with that keyword
+        # TODO clear memoization of ControlProxy.libui_class_for for a keyword if a custom control was defined with that keyword
         unless klass.name.include?('Glimmer::LibUI::CustomWindow')
           klass.include(Glimmer)
+          klass.include(GlimmerSupersedable) # prevent Glimmer from running method_missing first
           Glimmer::LibUI::CustomControl.add_custom_control_namespaces_for(klass)
         end
       end
@@ -220,23 +243,6 @@ module Glimmer
           @content
         end
       end
-
-      def method_missing(method_name, *args, &block)
-        # TODO Consider supporting a glimmer error silencing option for methods defined here
-        # but fail the glimmer DSL for the right reason to avoid seeing noise in the log output
-        if block && can_handle_listener?(method_name)
-          handle_listener(method_name, &block)
-        else
-          @body_root.send(method_name, *args, &block)
-        end
-      end
-
-      def respond_to?(method_name, *args, &block)
-        result = false
-        result ||= super
-        result ||= can_handle_listener?(method_name)
-        result ||= @body_root.respond_to?(method_name, *args, &block)
-      end
       
       private