rtml 1.2.2

data/app_generators/rtml/templates/rtml/lib/rtml/errors/widget_accessor_failure.rb

@@ -0,0 +1,9 @@
+class Rtml::Errors::WidgetAccessorFailure < RuntimeError
+  def initialize(widget_alias, widget_name, container_class)
+    @widget_alias, @widget_name, @container_class = widget_alias, widget_name, container_class
+  end
+  
+  def message
+    "Warning: Widget Alias #{@widget_alias.inspect} in class #{@widget_name} for Widget #{@container_class.name} overrides an existing method or object."
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/events/event_handler.rb

@@ -0,0 +1,79 @@
+module Rtml::Events
+  class EventHandler
+    # It's a little faster when we only have to const_get these things once.
+    @@all_event_processors = []
+    Rtml::Events::Processors.constants.each do |konst_name|
+      konst = Rtml::Events::Processors.const_get konst_name
+      @@all_event_processors << konst if konst.respond_to? :is_event_processor?
+    end
+    
+    # The array of event processors associated with this handler.
+    attr_reader :event_processors
+    
+    # The array of instantiated event processors.
+    attr_reader :processor_instances
+    
+    def initialize
+      @event_processors = []
+      @processor_instances = []
+      add_all_event_processors
+    end
+    
+    # Adds all EventProcessor objects which are members of the Events::Processors module
+    # to the event_processors array for this event handler.
+    def add_all_event_processors
+      @@all_event_processors.each do |konst|
+        add_event_processor konst
+      end
+    end
+    
+    # Adds the specified class to the list of event processors.
+    def add_event_processor(klass)
+      event_processors << klass unless event_processor_registered?(klass)
+    end
+    
+    # Removes all instances of the specified class from the event processors list.
+    def remove_event_processor(klass)
+      event_processors.delete klass
+    end
+    
+    # Returns true if the specified class has already been instantiated and added to the
+    # array of event processors.
+    def event_processor_registered?(klass)
+      event_processors.include? klass
+    end
+    
+    # Registers a screen or URL with a specified event. Raises an error if the event
+    # is not a valid TML event type.
+    def register(event_source, target)
+      found = false
+      event_processors.each do |processor|
+        if processor.accepts_event_source? event_source
+          processor_instances << processor.new(event_source, target)
+          found = true
+        end
+      end
+      raise "Could not find suitable event processor for event source #{event_source.inspect}" unless found
+    end
+    
+    # Unregisters a specified event so that no action will occur when this event is fired.
+    # Raises an error if the event is not a valid TML event type.
+    def unregister(event_source)
+      found = false
+      event_processors.each do |processor|
+        if processor.accepts_event_source? event_source
+          processor_instances.select { |i| i.kind_of? processor and i.event_source == event_source }.each do |i|
+            processor_instances.delete i
+            found = true
+          end
+        end
+      end
+      raise "Could not find suitable event processor for event source #{event_source.inspect}" unless found
+    end
+    
+    # Applies all event processors to the specified parent object
+    def process_event_handling_for(parent)
+      processor_instances.each { |ep| ep.process parent }
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/events/event_processor.rb

@@ -0,0 +1,106 @@
+module Rtml::Events
+  # Parent class of all RTML event processors.
+  class EventProcessor
+    include Rtml::Core
+    include Rtml::Widgets
+    
+    # A Symbol or String representing the actual event to be triggered,
+    # i.e. :menu, :cancel, and so on.
+    attr_reader :event_source
+    
+    # The destination screen when this event has been triggered
+    attr_reader :target
+    
+    def initialize(event_source, target)
+      @event_source, @target = event_source, target
+    end
+    
+    # Must always return true.
+    def self.is_event_processor?; true; end
+
+    # Returns all event sources which can be associated with this event processor.
+    # An event source is a Symbol or a String representing the TML-level event that
+    # is fired -- for instance, a KeyEventProcessor might have event sources including
+    # :menu, :cancel, :f1, '00', and so on. Consult the TML development guidelines for
+    # more information on these types.
+    def self.acceptable_event_sources
+      @acceptable_event_sources ||= []
+    end
+    
+    # Adds the specified event source(s) to the list of acceptable sources.
+    def self.accepts_event_source(*sources)
+      sources.each { |source| acceptable_event_sources << source }
+    end
+    
+    # Removes the specified event source(s) from the list of acceptable sources.
+    def self.rejects_event_source(*sources)
+      sources.each { |source| acceptable_event_sources.delete source }
+    end
+    
+    # Returns true if the specified event source is accepted by this processor.
+    def self.accepts_event_source?(source)
+      acceptable_event_sources.collect { |i| i.to_s }.include? source.to_s
+    end
+    
+    # Simply wraps the specified block in a condition, so you don't have to type
+    # quite as much. Equates to:
+    #
+    #  if parent_object.kind_of? parent_type
+    #    [block]
+    #  end
+    #
+    def for_parent_type(parent_type, parent_object, &block)
+      yield if parent_object.kind_of? parent_type
+    end
+    
+    # Applies the registered events and their associated screens to the
+    # object in question. This method is expected to be overridden by your
+    # subclass.
+    def apply_to(parent)
+      raise "Override this method."
+    end
+    
+    # Validates that the object argument is of an accepted type.
+    # The default accepted types are TMLDocument, Screen and Widget.
+    def validate(parent)
+      unless self.class.instance_variable_get("@acceptable_parents").include? parent.class
+        raise "Argument (#{parent.class}) must be one of [#{self.class.instance_variable_get("@acceptable_parents").join(", ")}]"
+      end
+    end
+    
+    # Validates and then applies self to the specified parent object.
+    def process(parent)
+      validate(parent)
+      apply_to(parent)
+    end
+    
+    # Returns true if the specified object's class is in the list of acceptable arguments for
+    # #apply_to.
+    def accepts?(parent)
+      self.class.accepts? parent.class
+    end
+    
+    # Returns true if the specified class is in the list of acceptable arguments for
+    # #apply_to.
+    def self.accepts?(klass)
+      acceptable_parents.include? klass
+    end
+    
+    # Causes the default apply_to implementation to raise an error if this object
+    # type is given.
+    def self.rejects_parent(*klasses)
+      klasses.each { |klass| acceptable_parents.delete klass }
+    end
+    
+    # Causes the default apply_to implementation to allow this object type to be
+    # specified.
+    def self.accept_parent(*klasses)
+      klasses.each { |klass| acceptable_parents << klass }
+    end
+
+    # Returns the classes of potential parent objects this processor can be applied to.
+    def self.acceptable_parents
+      @acceptable_parents ||= [ TMLDocument, Screen, Widget ]
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/events/processors.rb

@@ -0,0 +1,10 @@
+module Rtml::Events::Processors
+  # Finds all of the filenames in the ./processors/ directory, camelizes
+  # the filenames and then constantizes them. This causes Rails to take 
+  # care of the autoloading.
+  path = File.join(File.dirname(__FILE__), "processors", "")
+  Dir.glob(File.join(path, "*.rb")).each do |file|
+    camel = File.basename(file).sub(/(.*)\.rb$/, '\1').camelize
+    "Rtml::Events::Processors::#{camel}".constantize
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/events/processors/defaults_processor.rb

@@ -0,0 +1,18 @@
+module Rtml::Events::Processors
+  # Processes the MENU and CANCEL buttons for TMLDocument and Screen
+  # as well as the default ERROR screen for TMLDocument.
+  class DefaultsProcessor < Rtml::Events::EventProcessor
+    accepts_event_source :menu, :cancel, :error
+    rejects_parent Rtml::Widgets::Widget
+    
+    def apply_to(parent)
+      for_parent_type TMLDocument, parent do
+        parent["on_#{event_source}"] = target
+      end
+      
+      for_parent_type Screen, parent do
+        parent[event_source] = target
+      end
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/events/processors/key_processor.rb

@@ -0,0 +1,21 @@
+module Rtml::Events::Processors
+  # Processes all possible button press events at the Screen level.
+  # Possible event sources are:
+  #
+  #  0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 00, f1, f2, f3, f4, f5,
+  #  f6, f7, f8, f9, down, up, stop, enter
+  #
+  # Note that while "menu" and "cancel" are technically button
+  # events, these are handled by the DefaultsProcessor.
+  class KeyProcessor < Rtml::Events::EventProcessor
+    0.upto(9) { |i| accepts_event_source(i, "f#{i}") } # 0..9, f0..f9
+    accepts_event_source '00', :down, :up, :stop, :enter
+
+    rejects_parent Widget, TMLDocument
+    
+    def apply_to(parent)
+      # parent is a screen
+      parent.next_screen target, :key => event_source
+    end
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/feature.rb

@@ -0,0 +1,32 @@
+class Rtml::Feature
+  attr_accessor :document
+  alias rtml_document document
+  
+  [ :entry_point ].each { |m| eval("def #{m}; self.class.#{m}; end", binding, __FILE__, __LINE__) }
+
+  def config; self.class.config; end
+  def self.config; @config; end
+  def self.config=(a); @config = a; end
+  
+  def add_to(document)
+    self.document = document
+    to_tml
+  end
+  
+  def to_tml
+    raise "Expected Feature#to_tml to be overridden"
+  end
+  
+  def self.entry_point(id = nil)
+    unless id
+      raise "Expected #{self.name} to define an entry_point" unless @entry_point
+      return @entry_point
+    end
+    @entry_point = id
+  end
+  
+  protected
+  def restart_app
+    document.default_screen
+  end
+end

data/app_generators/rtml/templates/rtml/lib/rtml/feature_config.rb

@@ -0,0 +1,195 @@
+class Rtml::FeatureConfig
+  @@num_feature_configs = 0
+  
+  attr_reader :feature_class, :feature_config_id
+  
+  def root
+    @parent.nil? ? self : @parent.root
+  end
+
+  def initialize(feature = nil, parent = nil)
+    @parent = parent
+    @feature_config_id = (@@num_feature_configs += 1)
+    if feature.nil? then Rtml::Features.each { |f| add_subfeature(f) }
+    else
+      @feature_class = feature
+      if feature and not feature.ancestors.include? Rtml::Feature and false
+        config = self
+        @feature_class = Class.new(Feature) do
+          @name = "#{feature.name.titleize}"
+          def self.name; @name; end
+          entry_point("feat_menu_#{config.feature_config_id}".underscore)
+          
+          def add_to(document)
+            content = config.to_menu(document)
+            
+            document.screen entry_point do |scr|
+              scr.on config.events unless config.events.empty?
+              scr.display content
+            end
+          end
+        end
+        
+        feature.constants.each do |konst_name|
+          konst = feature.const_get(konst_name)
+          #if konst.respond_to? :entry_point # it's a Feature
+          add_subfeature(konst)
+          #end
+        end
+      end
+      @feature_class.config = self
+      @feature_class.configure if @feature_class.respond_to? :configure
+    end
+    
+    defaults
+  end
+  
+  def events(rtml_document, *items)
+    opts = items.extract_options!
+    create_menu_items(rtml_document)
+    values = (subfeatures.values || []).select { |v| v.menu }
+    items = values.collect { |a| a.entry_point } if items.empty?
+    items = opts[:only] if opts[:only]
+    items = items - (opts[:except] || [])
+    
+    events = HashWithIndifferentAccess.new
+    count = 0
+    rtml_document.controller.render_menu_items(*items) do |item, default|
+      count += 1
+      events[count] = item[:next_screen]
+      default
+    end
+    
+    events
+  end
+  
+  def to_menu(rtml_document, *items, &block)
+    opts = items.extract_options!
+    create_menu_items(rtml_document, &block)
+    values = (subfeatures.values || []).select { |v| v.menu }
+    
+    items = values.collect { |a| a.entry_point } if items.empty?
+    items = opts[:only] if opts[:only]
+    items = items - (opts[:except] || [])
+    
+    ret = "<table width='100%'>"
+    count = 0
+    ret.concat(rtml_document.controller.render_menu_items(*items) do |item, default|
+      count += 1
+      "<tr><td align='left'>#{count}. </td><td align='left'>#{default}</td></tr>"
+    end)
+    ret.concat "</table>"
+    
+    ret
+  end
+  
+  def entry_point
+    feature_class.nil? ? nil : feature_class.entry_point
+  end
+  
+  def to_instances
+    return @instances if @instances
+    r = ([to_instance] + subfeatures.collect { |name,config| config.to_instances }) - [nil]
+    @instances = Rtml::Features::ArrayOfFeatureInstances.new(r)
+  end
+  
+  def to_instance
+    return nil unless enabled and feature_class
+    feature_class.new
+  end
+  
+  def subfeatures
+    @subfeatures ||= ActiveSupport::OrderedHash.new#{}.with_indifferent_access
+  end
+  
+  def add_subfeature(feature)
+    fname = File.basename(feature.name.underscore)
+
+    subfeatures[fname] = self.class.new(feature, self)
+    eval "def self.#{fname}; subfeatures[#{fname.inspect}]; end", binding, __FILE__, __LINE__
+  end
+  
+  def option(*options)
+    options.each do |option|
+      if option.kind_of? Hash
+        option(*option.keys)
+        option.each do |key, value|
+          unless self.options.keys.include? key
+            self.set_option(key, value)
+          end
+        end
+      elsif option.kind_of? Array
+        self.option(*option)
+      else
+        eval "def self.#{option}=(a); set_option(#{option.inspect}, a); end", binding, __FILE__, __LINE__
+        eval "def self.#{option}; get_option(#{option.inspect}); end", binding, __FILE__, __LINE__
+      end
+    end
+  end
+  
+  def self.option(*options)
+    options.each do |option|
+      if option.kind_of? Hash
+        self.option(*option.keys)
+        option.each do |key, value|
+          configure { |config| config.send("#{key}=", value) }
+        end
+      elsif option.kind_of? Array
+        self.option(*option)
+      else
+        eval "def #{option}=(a); set_option(#{option.inspect}, a); end", binding, __FILE__, __LINE__
+        eval "def #{option}; get_option(#{option.inspect}); end", binding, __FILE__, __LINE__
+      end
+    end
+  end
+  
+  def options
+    @options ||= {}.with_indifferent_access
+  end
+  
+  def set_option(option_name, value)
+    options[option_name] = value
+  end
+  
+  def get_option(option_name)
+    options[option_name]
+  end
+  
+  def self.configure_blocks
+    @configure_blocks ||= []
+  end
+  
+  def self.configure(&block)
+    raise ArgumentError.new("Expected a block") unless block_given?
+    configure_blocks << block
+  end
+  
+  option :caption, :enabled, :order, :image, :menu
+  
+  protected
+  def create_menu_items(rtml_document, &block) #:nodoc:
+    create_menu_item(rtml_document, &block)
+    subfeatures.each { |name,config| config.create_menu_items(rtml_document, &block) }
+  end
+  
+  def create_menu_item(rtml_document, &block) #:nodoc:
+    return '' if feature_class.nil?
+    rtml_document.controller.menu_item feature_class.entry_point,
+                            :label => caption,
+                            :position => order,
+                            :image => image,
+                            &block
+  end
+  
+  private
+  def defaults
+    set_option :enabled, true
+    set_option :menu, true
+    set_option :order, @feature_config_id
+    
+    if feature_class
+      set_option :caption, File.basename(feature_class.name.underscore).titleize
+      self.class.configure_blocks.each { |block| block.call(self) }
+    end
+  end
+end