glimr 0.1.0

data/lib/glimr.rb

@@ -0,0 +1,2 @@
+require 'glimr/renderer'
+require 'glimr/widgets'

data/lib/glimr/configurable.rb

@@ -0,0 +1,37 @@
+module GlimR
+
+  # Hash-configurable object.
+  # Takes a hash and sets the setters named
+  # by the keys to the values.
+  # Use #default_config to define the default config.
+  #
+  #   class MyConfigurable
+  #     include Configurable
+  #     attr_accessor :x, :y
+  #     def default_config
+  #       { :x => 'default x', :y => 'default y' }
+  #     end
+  #   end
+  #
+  #   mc = MyConfigurable.new :y => 6
+  #   mc.x
+  #   # => 'default x'
+  #   mc.y
+  #   # => 6
+  #
+  module Configurable
+
+    def initialize(config_hash = {}, &optional_config_block)
+      config = default_config.merge(config_hash)
+      config.each{|k,v| instance_variable_set("@#{k}", v) }
+      super
+      yield(self) if block_given?
+    end
+
+    def default_config
+      {}
+    end
+
+  end
+
+end

data/lib/glimr/event.rb

@@ -0,0 +1,41 @@
+require 'ostruct'
+
+module GlimR
+
+  # Implements the <a href="http://www.w3.org/TR/DOM-Level-2-Events">W3C DOM Event model</a>
+  # event interface.
+  #
+  # Much like the ECMAScript API.
+  #
+  class Event < OpenStruct
+
+    attr_reader :type, :cancelled, :stopped
+    attr_accessor :phase, :params
+
+    # Creates a new event of the given type, sets params to param hash.
+    # By default, the event bubbles and is not cancelable.
+    def initialize(type, params={:bubbles => true, :cancelable => false})
+      params = params.clone
+      params[:bubbles] = true if params[:bubbles].nil?
+      params[:cancelable] = false if params[:cancelable].nil?
+      params[:time] ||= Time.now.to_f
+      super(params)
+      @type = type.to_sym
+      @params = params
+      @phase = :capture
+    end
+
+    # Stops the handling of the event.
+    def stop_propagation
+      @stopped = true
+    end
+
+    # Cancels the event's possible default behaviour.
+    def prevent_default
+      @cancelled = true if cancelable
+    end
+
+  end
+
+
+end

data/lib/glimr/eventlistener.rb

@@ -0,0 +1,209 @@
+require 'glimr/event'
+
+
+class Array
+
+  def delete_first(item)
+    i = index(item)
+    delete_at i if i
+  end
+
+end
+
+
+
+module GlimR
+
+
+  # The EventListener mixin implements an event listening interface
+  # similar to <a href="http://www.w3.org/TR/DOM-Level-2-Events/">
+  # W3C's ECMAScript DOM event API</a>, with the addition of event multicasting.
+  #
+  # EventListener provides the following methods:
+  # #add_event_listener, #remove_event_listener,
+  # #dispatch_event and #multicast_event.
+  #
+  # The list of event listeners can be modified with #add_event_listener and #remove_event_listener.
+  #
+  # E.g.
+  #   l = event_listener.add_event_listener(:hello){|listener, event|
+  #     puts "Goodbye!"
+  #   }
+  #   event_listener.remove_event_listener(:hello, l)
+  #   event_listener.add_event_listener(:hello){|listener, event|
+  #     puts "Hello, World!"
+  #   }
+  #   another_hello_listener.add_event_listener(:hello){|l, e|
+  #     puts "Hello from me too!"
+  #   }
+  #   event_listener.attach another_hello_listener
+  #
+  # Also provides a method_missing that captures method calls starting with on_ and
+  # parses them as requests to add event listener for the event type.
+  #
+  # E.g. to add a bubbling event listener for the event type :frame, it's possible to do
+  #   obj.on_frame{|o,e| puts 'got frame event'}
+  #
+  # And for a capturing listener
+  #   obj.on_frame(true){|o,e| puts 'got it first!'}
+  #
+  # To send a targeted event to the EventListener, use #dispatch_event.
+  #
+  # E.g.
+  #   event_listener.dispatch_event(Event.new(:hello))
+  #   # Hello, World!
+  #
+  # To broadcast an event to all listeners for the event type in the scene graph, use #multicast_event.
+  #
+  # E.g.
+  #   event_listener.multicast_event(Event.new(:hello))
+  #   # Hello from me too!
+  #   # Hello, World!
+  #
+  module EventListener
+
+    attr_accessor :event_listeners
+    attr_reader :listener_count
+
+    def initialize(*a,&b)
+      @event_listeners = Hash.new{|h,k| h[k] = Hash.new{|h,k| h[k] = []} }
+      @listener_count = Hash.new{|h,k| h[k] = 0 }
+    end
+
+    # Adds an event listener for the given event type. If use_capture is true, listens on capture phase.
+    # Otherwise listens on bubble phase. If listener is nil or false, the given block is used as the listener
+    # instead.
+    def add_event_listener(type, listener=nil, use_capture=false, &block)
+      listener ||= block
+      type = type.to_sym
+      @event_listeners[type][(use_capture ? :capture : :bubble)] << listener
+      increment_listener_count type
+    end
+
+    # Removes the given event listener from the event type. If no listener is given, removes all event listeners
+    # from the event type. If use_capture is true, removes capturing event listener(s), if false, removes bubbling
+    # event listener(s).
+    def remove_event_listener(type, listener=nil, use_capture=false)
+      type = type.to_sym
+      if listener
+        success = @event_listeners[type][(use_capture ? :capture : :bubble)].delete_first(listener)
+        decrement_listener_count type if success
+      else
+        listeners = @event_listeners[type][(use_capture ? :capture : :bubble)]
+        sz = listeners.size
+        if sz > 0
+          listeners.clear
+          decrement_listener_count type, sz
+        end
+      end
+    end
+
+    def method_missing(mn, *a, &b)
+      if mn.to_s[0,3] == "on_"
+        add_event_listener(mn.to_s[3..-1].gsub(/=$/,''), *a, &b)
+      else
+        super
+      end
+    end
+
+    # Sends the Event evt to first the capture listeners,
+    # then down to children, then to bubbling listeners.
+    #
+    # Returns immediately if there are no listeners for
+    # the event type in or below this node.
+    #
+    def multicast_event(evt)
+      return !evt.cancelled if @listener_count[evt.type] <= 0
+      evt.phase = :capture
+      process_event(evt)
+      return !evt.cancelled if evt.stopped
+      if evt.phase == :capture # still going down
+        children.each{|c|
+          c.multicast_event(evt) if c.is_a? EventListener
+          return !evt.cancelled if evt.stopped
+        }
+      end
+      return !evt.cancelled if evt.stopped
+      evt.phase = :bubble
+      process_event(evt)
+      return !evt.cancelled
+    end
+
+    # Sends the Event evt down to self and bubbles it up.
+    def dispatch_event(evt)
+      evt.target = self
+      ancestors = [self]
+      o = self
+      while o.parent and !o.parent.event_root and o.parent != evt.sender
+        ancestors << o.parent
+        o = o.parent
+      end
+      i = ancestors.size
+      ancestors.reverse.each{|a|
+        a.process_event(evt)
+        break if evt.stopped
+        i -= 1
+        break if evt.phase == :bubble
+      }
+      # Now either the event was turned around at i or reached the bottom (i==1).
+      # Continue by setting evt.phase to :bubble and sending it up from i.
+      i += 1 if evt.target == self # bubble already called for self
+      evt.phase = :bubble
+      (ancestors[i..-1] || []).each{|a|
+        break if evt.stopped
+        a.process_event(evt)
+      }
+      return !evt.cancelled
+    end
+
+    def event_root
+      false
+    end
+
+    # Processes the Event evt by calling all listeners on
+    # this object registered to handle the event.
+    def process_event(evt)
+      listeners_for(evt).each{|l|
+        break if evt.stopped
+        case l
+        when Symbol
+          __send__(l, self, evt)
+        else
+          l.call(self, evt)
+        end
+      }
+      !evt.cancelled
+    end
+
+    # Adds count to the subtree total listener count for type.
+    # Sends changes to parent to keep its subtree total listener count correct.
+    def increment_listener_count type, count=1
+      c = @listener_count[type]
+      raise ArgumentError, "Trying to decrement listener count too much." if -count > c
+      @listener_count[type] += count
+      parent.increment_listener_count type, count if parent.is_a? EventListener
+    end
+
+    # Subtracts count from the subtree total listener count for type.
+    # Sends changes to parent to keep its subtree total listener count correct.
+    def decrement_listener_count type, count=1
+      increment_listener_count type, -count
+    end
+
+    private
+
+    def listeners_for(evt)
+      if self == evt.target
+        evt.phase = :at
+        @event_listeners[evt.type].values.flatten
+      elsif evt.phase == :capture
+        @event_listeners[evt.type][:capture]
+      else
+        @event_listeners[evt.type][:bubble]
+      end
+    end
+
+  end
+
+
+end

data/lib/glimr/layoutable.rb

@@ -0,0 +1,520 @@
+require 'ostruct'
+require 'glimr/util'
+
+
+module GlimR
+
+
+  # Layoutable is a mixin for creating GlimR nodes that
+  # are suspectible to layout rules.
+  #
+  # Layoutable objects have dimensions, margins, and padding.
+  #
+  # The margins define how much space should be left around the
+  # Layoutable. Padding defines how much distance should be left
+  # between the borders of the Layoutable and its child nodes.
+  #
+  # They also have the following attributes that control their
+  # dynamic resizing behaviour: expand_width, expand_height,
+  # fit_children, min_width, min_height, max_width and max_height.
+  #
+  # Dynamic layout rules:
+  #
+  # An object expands in a dimension if either its corresponding expand
+  # attribute is set to true, or if its fit_children is set to true and one of
+  # its children expands in the dimension.
+  #
+  # If an object neither fits its children nor expands, it is a constant size
+  # object.
+  #
+  # When a layoutable object is attached to the scene graph
+  # it expands to its maximum dimensions if it is an expanding object.
+  #
+  # When a layoutable object changes size, it informs its parent
+  # if the parent is a layoutable. If the object was a constant size object,
+  # or the size change resulted from changing the object's
+  # dimension constraints (min_width, max_width, etc.), the expanding
+  # children of the object are also informed of the size change.
+  #
+  # When computing the dimensions of a Layoutable, dimension
+  # constraints take predecence over expanding, which takes
+  # predecence over fit_children.
+  #
+  # E.g. the final width of a layoutable node is computed as follows:
+  #
+  #   1. set width to max child width if fit_children
+  #   2. set width to the inner width of the parent node if expand_width
+  #   3. clamp the width between min_width and max_width if they're set
+  #
+  module Layoutable
+
+    def self.size_changing_accessor(*mnames)
+      attr_reader *mnames
+      mnames.each{|mn|
+        ivar_name = :"@#{mn}"
+        define_method("#{mn}=") do |value|
+          size_changing{ instance_variable_set(ivar_name, value) }
+        end
+      }
+    end
+
+    size_changing_accessor :width, :height, :depth
+    size_changing_accessor :margin_left, :margin_right,
+                      :margin_top, :margin_bottom,
+                      :margin_front, :margin_back
+    size_changing_accessor :padding_left, :padding_right,
+                      :padding_top, :padding_bottom,
+                      :padding_front, :padding_back
+
+    size_changing_accessor :expand_width, :expand_height, :fit_children,
+                      :min_width, :min_height, :max_width, :max_height
+
+    attr_accessor :align, :valign
+
+    alias_method :fit_children?, :fit_children
+
+    DIMENSIONS = [:left, :right, :top, :bottom] #, :front, :back]
+
+
+    # horiz margin setters modify full_width
+    # vert margin setters  modify full_height
+    # horiz padding setters modify full_width
+    # vert padding setters modify full_height
+
+
+    def default_config
+      super.merge(
+        :expand_width => false, :expand_height => false,
+        :fit_children => true, :align => :left, :valign => :top,
+        :min_width => 0, :min_height => 0,
+        :max_width => 1.0/0.0, :max_height => 1.0/0.0,
+        :width => 0, :height => 0, :depth => 0,
+        :margin_left => 0, :margin_right => 0,
+        :margin_top => 0, :margin_bottom => 0,
+        :margin_front => 0, :margin_back => 0,
+        :padding_left => 0, :padding_right => 0,
+        :padding_top => 0, :padding_bottom => 0,
+        :padding_front => 0, :padding_back => 0
+      )
+    end
+
+    def initialize(*a, &b)
+      super
+      @__resize_handler = lambda{|o,e| o.expand! }
+      self.margin = @margin if @margin
+      self.padding = @padding if @padding
+    end
+
+    # Sets x to the given integer value.
+    def x= nx
+      super nx.to_i
+    end
+
+    # Sets y to the given integer value.
+    def y= ny
+      super ny.to_i
+    end
+
+    # Sets align to a and relayouts.
+    def align= a
+      if @align != a
+        @align = a
+        layout
+      end
+    end
+
+    # Sets valign to v and relayouts.
+    def valign= v
+      if @valign != v
+        @valign = v
+        layout
+      end
+    end
+
+    # Sets min_width to mw and sets width to min_width
+    # if it's smaller than the new min_width.
+    def min_width= mw
+      @min_width = mw
+      self.width = mw if self.width < mw
+      fit_to_children! if fit_children?
+    end
+
+    # Sets min_height to mw and sets height to min_height
+    # if it's smaller than the new min_height.
+    def min_height= mh
+      @min_height = mh
+      self.height = mh if self.height < mh
+      fit_to_children! if fit_children?
+    end
+
+    # Sets max_width to mw and sets width to max_width
+    # if it's larger than the new max_width.
+    def max_width= mw
+      @max_width = mw
+      self.width = mw if self.width > mw
+    end
+
+    # Sets max_height to mw and sets height to max_height
+    # if it's larger than the new max_height.
+    def max_height= mh
+      @max_height = mh
+      self.height = mh if self.height > mh
+    end
+
+    # Returns current margins as an OpenStruct with #left, #right, #top, and #bottom.
+    def margin
+      OpenStruct.new(
+        :left => margin_left, :right => margin_right,
+        :top => margin_top, :bottom => margin_bottom,
+        :front => margin_front, :back => margin_back
+      )
+    end
+
+    # Sets margins to new_margin.
+    # If given a Numeric, sets all margins to the given value.
+    # If given a hash, sets the margins to the corresponding values in the hash.
+    # If given any other object, acts as if it is an OpenStruct returned by #margin.
+    #
+    def margin= new_margin
+      size_changing do
+        case new_margin
+        when Numeric
+          @margin_left = @margin_right = @margin_top = @margin_bottom = new_margin
+          touch!
+        when Hash
+          new_margin.each{|k,v|
+            __send__("margin_#{k}=", v)
+          }
+        else
+          DIMENSIONS.each{|d|
+            __send__("margin_#{d}=", new_margin.__send__(d))
+          }
+        end
+      end
+    end
+
+    # Returns current padding as an OpenStruct with #left, #right, #top, and #bottom.
+    def padding
+      OpenStruct.new(
+        :left => padding_left, :right => padding_right,
+        :top => padding_top, :bottom => padding_bottom,
+        :front => padding_front, :back => padding_back
+      )
+    end
+
+    # Sets padding to new_padding.
+    # If given a Numeric, sets all paddings to the given value.
+    # If given a hash, sets the paddings to the corresponding values in the hash.
+    # If given any other object, acts as if it is an OpenStruct returned by #padding.
+    #
+    def padding= new_padding
+      size_changing do
+        case new_padding
+        when Numeric
+          @padding_left = @padding_right = @padding_top = @padding_bottom = new_padding
+          touch!
+        when Hash
+          new_padding.each{|k,v|
+            __send__("padding_#{k}=", v)
+          }
+        else
+          DIMENSIONS.each{|d|
+            __send__("padding_#{d}=", new_padding.__send__(d))
+          }
+        end
+      end
+    end
+
+    # Returns an Array of all children that respond true to #is_a?(Layoutable).
+    def layoutable_children
+      children.find_all{|c| c.is_a? Layoutable }
+    end
+
+    # Whether the object expands to fill its parent's width or not.
+    #
+    # Returns true if either @expand_width is true or fit_children is true
+    # and any of the layoutable children returns true to #expand_width.
+    def expand_width
+      @expand_width or (fit_children and layoutable_children.any?{|c| c.expand_width })
+    end
+
+    def parent= p
+      super
+      ew = expand_width
+      eh = expand_height
+      viewport_expand = p.is_a?(Viewport) and (ew or eh)
+      constant_expand = (p.is_a?(Layoutable) and !p.fit_children?) and
+        ((ew and !parent.expand_width) or (eh and !parent.expand_height))
+      expand! if (viewport_expand or constant_expand)
+    end
+
+    # Whether the object expands to fill its parent's height or not.
+    #
+    # Returns true if either @expand_height is true or fit_children is true
+    # and any of the layoutable children returns true to #expand_height.
+    def expand_height
+      @expand_height or (fit_children and
+      layoutable_children.any?{|c| c.expand_height })
+    end
+
+    # Whether the Layoutable object expands to fill its parent's width or height.
+    #
+    def expand?
+      expand_width or expand_height
+    end
+
+    # Returns true if the object's size is constant, i.e it does not expand and
+    # does not fit its children.
+    def constant_size?
+      not (expand? or fit_children?)
+    end
+
+    def attach(*a, &b)
+      size_changing{
+        super
+        children_change
+      }
+    end
+
+    def detach(*a, &b)
+      size_changing{
+        super
+        children_change
+      }
+    end
+
+    # Sets dimensions equal to the largest child + padding.
+    def fit_to_children!
+      size_changing do
+        fit_width! unless parent and expand_width
+        fit_height! unless parent and expand_height
+      end
+    end
+
+    # Sets width equal to the largest child + padding.
+    def fit_width!
+      self.width = layoutable_children.map{|c|
+        c.full_width + padding_left + padding_right
+      }.max unless layoutable_children.empty?
+    end
+
+    # Sets height equal to the largest child + padding.
+    def fit_height!
+      self.height = layoutable_children.map{|c|
+        c.full_height + padding_top + padding_bottom
+      }.max unless layoutable_children.empty?
+    end
+
+    # Yields to block and informs relevant parties if size changed during it.
+    #
+    # In detail:
+    #
+    # If the node turns into an expanding one, it is expanded. This may cause a size change.
+    #
+    # If the inner dimensions (caused by padding changes) are altered,
+    # children are told and relayouted.
+    #
+    # If the outer dimensions (caused by dimension changes and margin changes)
+    # are altered, children are told and relayouted and possible Layoutable parent is told
+    # (unless the node is an expanding one, in which case the parent already knows.)
+    #
+    def size_changing(&block)
+      return yield if @__doing_size_changing_operation
+      @__doing_size_changing_operation = true
+      ow, oh, iw, ih = full_width, full_height, inner_width, inner_height
+      cs = constant_size?
+      fc = fit_children?
+      ew = expand_width
+      eh = expand_height
+      rv = yield
+      fit_to_children! if fit_children? and ((!fc and fit_children?) or (ew and !expand_width) or (eh and !expand_height))
+      expand! if (!ew and expand_width) or (!eh and expand_height)
+      @width = [[min_width, width].max, max_width].min
+      @height = [[min_height, height].max, max_height].min
+      dw = (ow != full_width)
+      dh = (oh != full_height)
+      diw = (iw != inner_width)
+      dih = (ih != inner_height)
+      if dw or dh or diw or dih
+        tell_children_of_size_change if diw or dih
+        parent.children_change if parent.is_a?(Layoutable) and (dw or dh)
+        layout
+        dispatch_event(Event.new(:layout)) if respond_to? :dispatch_event
+        @width = [[min_width, width].max, max_width].min
+        @height = [[min_height, height].max, max_height].min
+      end
+      @__doing_size_changing_operation = false
+      rv
+    end
+
+    # Children changed, let's accommodate.
+    def children_change
+      fit_to_children! if fit_children?
+      layout
+    end
+
+    # Expands all expanding children.
+    def tell_children_of_size_change
+      layoutable_children.each{|c| c.expand! if c.expand? }
+    end
+
+    # Expands self to maximum available dimensions.
+    # Brought on by parent size change.
+    #
+    def expand!(given_width=nil,given_height=nil)
+      size_changing{
+        expand_to_max_width!(given_width) if expand_width
+        expand_to_max_height!(given_width) if expand_height
+      }
+    end
+
+    # Expands self, parent and children to
+    # maximum available width if expand_width is true.
+    #
+    # If expand_width is true, expands to
+    # either the given_width, the result of
+    # calling @parent.expand_to_max_width! or
+    # @viewport.width (in this order.)
+    #
+    # If width changes as a result of this
+    # call, calls each Layoutable child's
+    # expand_to_max_width! with the new width.
+    #
+    # Returns free_width.
+    #
+    def expand_to_max_width!(given_width=nil)
+      if expand_width
+        remove_event_listener(:resize, @__resize_handler)
+        if given_width
+          @width = given_width
+        elsif @parent.is_a? Layoutable
+          @width = @parent.expand_to_max_width!
+        elsif @viewport ||= (@parent && @parent.viewport)
+          on_resize(@__resize_handler)
+          @width = @viewport.width
+        end
+      end
+      free_width
+    end
+
+    # Expands self, parent and children to
+    # maximum available height if expand_height is true.
+    #
+    # If expand_height is true, expands to
+    # either the given_height, the result of
+    # calling @parent.expand_to_max_height! or
+    # @viewport.height (in this order.)
+    #
+    # If height changes as a result of this
+    # call, calls each Layoutable child's
+    # expand_to_max_height! with the new height.
+    #
+    # Returns free_height.
+    #
+    def expand_to_max_height!(given_height=nil)
+      if expand_height
+        remove_event_listener(:resize, @__resize_handler)
+        if given_height
+          @height = given_height
+        elsif @parent.is_a? Layoutable
+          @height = @parent.expand_to_max_height!
+        elsif @viewport ||= (@parent && @parent.viewport)
+          on_resize(@__resize_handler)
+          @height = @viewport.height
+        end
+      end
+      free_height
+    end
+
+    def layout
+      @layouted_width = @width
+      @layouted_height = @height
+      layoutable_children.each{|c|
+        case align
+        when :left
+          c.x = padding_left + c.margin_left
+        when :right
+          c.x = width - padding_right - c.full_width
+        when :center
+          c.x = padding_left + c.margin_left + ((inner_width - c.margin_left - c.margin_right) - c.width) / 2.0
+        end
+        case valign
+        when :top
+          c.y = padding_top + c.margin_top
+        when :bottom
+          c.y = height - padding_bottom - c.full_height
+        when :middle
+          c.y = padding_top + c.margin_top + ((inner_height - c.margin_top - c.margin_bottom) - c.height) / 2.0
+        end
+      }
+    end
+
+    # Returns the maximum width an expanding child can expand to.
+    def free_width
+      inner_width
+    end
+
+    # Returns the maximum height an expanding child can expand to.
+    def free_height
+      inner_height
+    end
+
+    # Width sans padding.
+    def inner_width
+      @width - @padding_left - @padding_right
+    end
+
+    # Height sans padding.
+    def inner_height
+      @height - @padding_bottom - @padding_top
+    end
+
+    # Depth sans padding.
+    def inner_depth
+      @depth - @padding_front - @padding_back
+    end
+
+    # Width, scaled, plus margins.
+    def full_width
+      case scale
+      when Numeric
+        width * scale
+      when Array
+        width * scale[0]
+      else
+        width
+      end + @margin_left + @margin_right
+    end
+
+    # Height, scaled, plus margins.
+    def full_height
+      case scale
+      when Numeric
+        height * scale
+      when Array
+        height * scale[1]
+      else
+        height
+      end + @margin_top + @margin_bottom
+    end
+
+    def full_depth
+      case scale
+      when Numeric
+        depth * scale
+      when Array
+        depth * scale[2]
+      else
+        depth
+      end + @margin_front + @margin_back
+    end
+
+    def inspect
+      super[0..-2] + "::w#@width:h#@height>"
+    end
+
+  end
+
+
+end
+