metro-ld25 0.3.3

data/lib/metro/models/properties/options_property/options_property.rb

@@ -0,0 +1,125 @@
+module Metro
+  class Model
+
+    #
+    # An options property is a property that takes scene or view defined values
+    # and converts them into an Options object.
+    #
+    # @see Metro::Model::OptionsProperty::Options
+    #
+    # @example A simple array of option names
+    #
+    #     options: [ 'Start Game', 'Exit' ]
+    #
+    #
+    # @example A set of option names with a selection
+    #
+    #       options:
+    #         selected: 0
+    #         items: [ 'Start Game', 'Exit' ]
+    #
+    # @example A complex set of options
+    #
+    #       options:
+    #         selected: 1
+    #         items:
+    #         -
+    #           model: "metro::ui::label"
+    #           text: "Start Game"
+    #           action: start_game
+    #         -
+    #           model: metro::ui::label
+    #           text: Exit
+    #           action: exit_game
+    #
+    class OptionsProperty < Property
+
+      get do |options|
+        Options.empty
+      end
+
+      # This is the basic set of options
+      get Array do |options|
+        parse_array(options)
+      end
+
+      # This is the complex set of options
+      get Hash do |options|
+        parse(options)
+      end
+
+      # This is setting the options with the basic set of options
+      set Array do |array|
+        array
+      end
+
+      # This is setting the options with the complex options
+      set Hash, HashWithIndifferentAccess do |hash|
+        hash.to_hash
+      end
+
+      private
+
+      def parse_array(array)
+        hash = { items: array }
+        parse(hash)
+      end
+
+      #
+      # Convert the hash of parameters into an Options object which contains the visual
+      # representation of each item within the menu as well as the current selected item.
+      #
+      def parse(hash)
+        hash = hash.with_indifferent_access
+        options = create_options(hash[:items])
+        options.current_selected_index = hash[:selected]
+        options
+      end
+
+      def create_options(items)
+        create_options_with_items convert_simple_items(items)
+      end
+
+      #
+      # As menu options can be defined in many ways, this method will convert the simple
+      # versions of the content to match the full robust version by converting them to a
+      # hash and adding the remaining fields.
+      #
+      def convert_simple_items(items)
+        return items if items.first.is_a?(Hash)
+        items.map { |text| { model: "metro::ui::label", text: text } }
+      end
+
+      #
+      # Generate an Options object with the options specified.
+      #
+      # @see Options
+      #
+      def create_options_with_items(options)
+        Options.new options.map { |option| create_model_from_item(option) }
+      end
+
+      #
+      # From the options provided create the models that will be managed by the Options
+      # object.
+      #
+      def create_model_from_item(options)
+        options = options.symbolize_keys
+        options[:action] = actionize(options[:action] || options[:text])
+        model.create options[:model], options
+      end
+
+      #
+      # @return [Symbol] convert a text string into a name which would be a sane method name.
+      #
+      def actionize(text)
+        text.to_s.downcase.gsub(/\s/,'_').gsub(/^[^a-zA-Z]*/,'').gsub(/[^a-zA-Z0-9\s_]/,'').to_sym
+      end
+
+    end
+
+  end
+end
+
+require_relative 'options'
+require_relative 'no_option'

data/lib/metro/models/properties/position_property.rb

@@ -0,0 +1,90 @@
+module Metro
+  class Model
+
+    #
+    # A position property maintains a 2D Point.
+    #
+    # A position property also defines an `x` property and a `y` property which allows a
+    # more direct interface.
+    #
+    # A position is stored as a string in the properties and retrieved as a Point object.
+    #
+    # @example Defining a position property, using the x, y and z_order properties
+    #
+    #     class Enemy < Metro::Model
+    #       property :position
+    #
+    #       def draw
+    #         # image.draw position.x, position.y, z_order, x_factor, y_factor, color, :add)
+    #         image.draw x, y, z_order, x_factor, y_factor, color, :add)
+    #       end
+    #     end
+    #
+    # @example Defining a position property providing a default
+    #
+    #     class Enemy < Metro::Model
+    #       property :position, default: Point.at(44,66)
+    #     end
+    #
+    # @example Using a position property with a different property name
+    #
+    #     class Hero < Metro::Model
+    #       property :pos, type: :position, default: Point.zero
+    #
+    #       def draw
+    #         # image.draw pos.x, pos.y, pos.z_order, x_factor, y_factor, color, :add)
+    #         image.draw pos_x, pos_y, pos_z_order, x_factor, y_factor, color, :add)
+    #       end
+    #     end
+    #
+    class PositionProperty < Property
+
+      # Define an x position property
+      define_property :x
+
+      # Define a y position property
+      define_property :y
+
+      # Define a z position property which is used for the z order
+      define_property :z
+      define_property :z_order
+
+      # When no getters match the specified value return the default point
+      get do
+        default_point
+      end
+
+      # When getting a point, then simply send that point on. This is often
+      # the case when the property is initailized by a scene.
+      get Point do |point|
+        point
+      end
+
+      # When getting a string convert it to a point.
+      get String do |value|
+        Point.parse(value)
+      end
+
+      # When no setters match save the default point.
+      set do
+        default_point.to_s
+      end
+
+      # When given a string, it is assumed to be a well formated point
+      set String do |value|
+        Point.parse(value).to_s
+      end
+
+      # When given a point save the the string value of it.
+      set Point do |value|
+        value.to_s
+      end
+
+      def default_point
+        Point.parse(options[:default])
+      end
+
+    end
+
+  end
+end

data/lib/metro/models/properties/property.rb

@@ -0,0 +1,221 @@
+module Metro
+  class Model
+
+    #
+    # A property is a value filter that allows you to specify filtering options
+    # both on the setting and the getting of a value. The property itself does
+    # not maintain any of these values but keeps in mind the particular model
+    # and options that it is created when applying the filtering.
+    #
+    # @note Property is intented to be subclassed to provide filtering of particular types.
+    #
+    class Property
+      include Units
+
+      attr_reader :model, :options, :block
+
+      #
+      # @param [Model] model the model associated with this property.
+      # @param [Types] options the additional options that may be set with
+      #   this property. This may be default values or options on how
+      #   this properby should behave.
+      #
+      def initialize(model,options={},&block)
+        @model = model
+        @options = options
+        @block = block
+      end
+
+      # Define a filter block for getting a value of that type.
+      def self.get(*types,&block)
+        types = [ NilClass ] if types.empty?
+        types.each do |type|
+          gets[type.to_s] = block
+        end
+      end
+
+      # All get filter blocks defined
+      def self.gets
+        @gets ||= hash_with_default_to_nil
+      end
+
+      # Perform a get of the value, running it through the get
+      # filter block that matches the type.
+      def get(value)
+        get_block = self.class.gets[value.class.to_s]
+        instance_exec(value,&get_block)
+      end
+
+      # Define a filter block for setting a value of the type.
+      def self.set(*types,&block)
+        types = [ NilClass ] if types.empty?
+        types.each do |type|
+          sets[type.to_s] = block
+        end
+      end
+
+      # All set filter blocks defined
+      def self.sets
+        @sets ||= hash_with_default_to_nil
+      end
+
+      # Perform a set of the value, running it through the set
+      # filter block that matches the type.
+      def set(value)
+        set_block = self.class.sets[value.class.to_s]
+        instance_exec(value,&set_block)
+      end
+
+      # Define a filter block that applies to both the setting and getting of a property.
+      def self.get_or_set(type=NilClass,&block)
+        gets[type.to_s] = block
+        sets[type.to_s] = block
+      end
+
+      #
+      # Allow a property to define a sub-property.
+      #
+      # A sub-property that is defined can be any type of exiting properties. Which
+      # may also define more sub-properties. These sub-properties will be available as properties
+      # through the names provided.
+      #
+      # @example DimensionProperty defining two numeric sub-properties for height and width
+      #
+      #     class DimensionsProperty < Property
+      #       define_property :width
+      #       define_property :height
+      #     end
+      #
+      #     class Frogger < Metro::Model
+      #       property :dimensions
+      #
+      #       def after_initialize
+      #         puts "Frog dimensions are #{dimensions}"
+      #         puts "(#{dimensions.width},#{dimensions.height}) == (#{width},#{height})"
+      #       end
+      #     end
+      #
+      # The sub-properties can also be prefixed with the parent property name:
+      #
+      # @example FontProperty defines sub-properties which include the parent propery prefix
+      #
+      #     class FontProperty < Property
+      #       define_property :size, prefix: true
+      #       define_property :name, type: :text, prefix: true
+      #     end
+      #
+      #     class MyLabel < Metro::Model
+      #       property :font
+      #
+      #       def after_initialize
+      #         puts "Font is: #{font} - #{font_name}:#{font_size}"
+      #       end
+      #     end
+      #
+      # If you define a property with the non-default name it will automatically add the prefix
+      # to all the sub-properties. This is to prevent any getter/setter method name collisions.
+      #
+      # @example DimensionProperty defining two numeric sub-properties for height and width
+      #
+      #     class DimensionsProperty < Property
+      #       define_property :width
+      #       define_property :height
+      #     end
+      #
+      #     class Frogger < Metro::Model
+      #       property :dims, type: :dimensions
+      #
+      #       def after_initialize
+      #         puts "Frog dimensions are #{dims}"
+      #         puts "(#{dims.width},#{dims.height}) == (#{dims_width},#{dims_height})"
+      #       end
+      #     end
+      #
+      def self.define_property(name,options = {})
+        defined_properties.push PropertyDefinition.new name, options
+      end
+
+      #
+      # @return an array of all the defined properties.
+      #
+      def self.defined_properties
+        @defined_properties ||= []
+      end
+
+      #
+      # Capture all the subclassed properties and add them to the availble list of
+      # properties.
+      #
+      def self.inherited(subclass)
+        property_name = subclass.to_s.gsub(/Property$/,'').split("::").last.underscore
+        properties_hash[property_name] = subclass.to_s
+      end
+
+      def self.properties
+        @properties ||= []
+      end
+
+      #
+      # @return a Property Class that matches the specified name.
+      #
+      def self.property(name)
+        property_classname = properties_hash[name]
+        property_classname.constantize
+      end
+
+      #
+      # Generate a properties hash. This properties will default to the numeric key when the property
+      # type cannot be found.
+      #
+      def self.properties_hash
+        @properties_hash ||= HashWithIndifferentAccess.new { |hash,key| hash[:numeric] }
+      end
+
+      #
+      # Generate a hash that will default all missing keys to the NilClass key and the NilClass key will
+      # return a cource of action that will raise an exception. This means by default that if it is not
+      # overridden an error is generated.
+      #
+      def self.hash_with_default_to_nil
+        hash = HashWithIndifferentAccess.new { |hash,key| hash["NilClass"] }
+        hash["NilClass"] = lambda { |value| raise "#{self} is not able to translate the #{value} (#{value.class})" }
+        hash
+      end
+
+    end
+
+  end
+
+  #
+  # A property definition contains the name of the property and the options specified with it.
+  # This is used internally to define properties and sub-properties.
+  #
+  class PropertyDefinition
+
+    attr_reader :name, :options
+
+    def initialize(name,options)
+      @name = name
+      @options = options
+    end
+  end
+
+end
+
+require_relative 'property_owner'
+
+require_relative 'numeric_property'
+require_relative 'text_property'
+require_relative 'boolean_property'
+require_relative 'array_property'
+require_relative 'animation_property'
+require_relative 'color_property'
+require_relative 'dimensions_property'
+require_relative 'font_property'
+require_relative 'image_property'
+require_relative 'position_property'
+require_relative 'scale_property'
+require_relative 'song_property'
+require_relative 'sample_property'
+require_relative 'options_property/options_property'
+require_relative 'model_property'

data/lib/metro/models/properties/property_owner.rb

@@ -0,0 +1,137 @@
+module Metro
+
+  module PropertyOwner
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    #
+    # The raw properties of the model. Most properties defined through the `property`
+    # class method will have getters/setters that will do the appropriate translation
+    # so this should in cases when you need access to the raw properties or there
+    # is not a property accessors defined.
+    #
+    # @return [Hash] the raw properties of the model.
+    #
+    def properties
+      @properties ||= {}
+    end
+
+    module ClassMethods
+
+      #
+      # Define a property for the model. A property has a name and then can optionally specify
+      # a property type which will receive additional options.
+      #
+      # @example Defining various propertys for a model
+      #
+      #     class Player
+      #       property :position
+      #       property :angle, default: 0.0
+      #       property :turn_amount, default: 4.5
+      #       property :image, path: "player.png"
+      #       property :motto, type: :text, default: 'Hometown Heroes!'
+      #     end
+      #
+      # When the property name matches a property definition with that name they will be used. This is what
+      # happens for the 'position' and 'image' properties defined above. Both of those map to respective
+      # properties with matching names.
+      #
+      # Properties by default are assumed to be numeric properties so the types does not have to be stated.
+      # This is the case for 'angle' and 'turn_amount' properties.
+      #
+      # You may use any particular name for your properties as long as you specify the type. This is the case
+      # for the 'motto' property.
+      #
+      def property(name,options={},&block)
+
+        # Use the name as the property type if one has not been provided.
+
+        property_type = options[:type] || name
+
+        property_class = Model::Property.property(property_type)
+
+        define_method name do
+          raw_value = properties[name]
+
+          unless parsed_value = instance_variable_get("@_property_parsed_#{name}")
+            parsed_value = property_class.new(self,options,&block).get(raw_value)
+            instance_variable_set("@_property_parsed_#{name}",parsed_value)
+          end
+
+          parsed_value
+        end
+
+        define_method "#{name}=" do |value|
+          instance_variable_set("@_property_parsed_#{name}",nil)
+          prepared_value = property_class.new(self,options).set(value)
+          send("#{name}_changed",prepared_value) if respond_to? "#{name}_changed"
+          properties[name] = prepared_value
+        end
+
+        # Define any sub-properties defined on this property
+
+        # When the name does not match the property type then we want to force
+        # the prefixing to be on for our sub-properties. This is to make sure
+        # that when people define multiple fonts and colors that they do not
+        # overlap.
+
+        override_prefix = !(name == property_type)
+
+        property_class.defined_properties.each do |subproperty|
+          sub_options = { prefix: override_prefix }.merge(subproperty.options)
+          sub_options = sub_options.merge(parents: (Array(sub_options[:parents]) + [name]))
+          _sub_property subproperty.name, sub_options
+        end
+
+      end
+
+      #
+      # Defines the sub-properties defined within the property. This is to be used internally
+      # by the #property method.
+      #
+      def _sub_property(name,options={},&block)
+
+        # Use the name as the property type if one has not been provided.
+
+        property_type = options[:type] || name
+
+        property_class = Model::Property.property(property_type)
+
+        parents = Array(options[:parents])
+
+        method_name = name
+
+        if options[:prefix]
+          method_name = (parents + [name]).join("_")
+        end
+
+        # Define a getter for the sub-property that will traverse the
+        # parent properties, finally returning the filtered value
+
+        define_method method_name do
+          raw_value = (parents + [name]).inject(self) {|current,method| current.send(method) }
+          property_class.new(self,options).get raw_value
+        end
+
+        # Define a setter for the sub-property that will find the parent
+        # value and set itself on that with the filtered value. The parent
+        # is then set.
+        #
+        # @TODO: If getters return dups and not instances of the original object then a very
+        #   deep setter will not be valid.
+        #
+        define_method "#{method_name}=" do |value|
+          parent_value = parents.inject(self) {|current,method| current.send(method) }
+
+          prepared_value = property_class.new(self,options,&block).set(value)
+          parent_value.send("#{name}=",prepared_value)
+
+          send("#{parents.last}=",parent_value)
+        end
+      end
+    end
+
+  end
+end