rugui 1.2.0

data/lib/rugui/base_view.rb

@@ -0,0 +1,302 @@
+module RuGUI
+  # A base class for views.
+  #
+  # To use this class create a subclass and reimplement #setup_widgets, if you
+  # want to create your interface by hand. If you want to use a builder file
+  # just call #use_builder and, optionally, call #builder_file passing the
+  # filename to use.
+  #
+  # Each adapter may implement additional features, extending this class, look
+  # for it in adapter classes.
+  #
+  # The view may have ViewHelpers, which works as 'models' for views, i.e., they
+  # have observable properties that can be observed by the view. A default
+  # helper, named as <code>{view_name}Helper</code> is registered if it exists.
+  # For example, for a view named *MyView*, the default view helper should be
+  # named *MyViewHelper*. This helper can be accessed as a <code>helper</code>
+  # attribute. Other helpers may be registered if needed.
+  #
+  # Example (using GTK framework adapter):
+  #   class MyGladeView < RuGUI::BaseView
+  #     builder_file 'my_file.glade' # this is optional, if the glade file was called my_glade_view.glade this wouldn't be needed.
+  #     root :top_window
+  #     use_builder
+  #   end
+  #
+  #   class MyHandView < RuGUI::BaseView
+  #     def setup_widgets
+  #       # do your hand-made code here...
+  #     end
+  #   end
+  class BaseView < BaseObject
+    include RuGUI::LogSupport
+    include RuGUI::PropertyObserver
+    include RuGUI::SignalSupport
+
+    attr_accessor :controllers
+    attr_reader :widgets
+    attr_reader :unnamed_widgets
+    
+    class_inheritable_accessor :configured_builder_file
+    class_inheritable_accessor :configured_builder_file_usage
+    class_inheritable_accessor :configured_builder_file_extension
+    class_inheritable_accessor :configured_root
+    class_inheritable_accessor :configured_display_root
+
+    def initialize
+      @controllers = {}
+      @helpers = {}
+      @unnamed_widgets = []
+      @widgets = {}
+
+      register_default_helper
+      setup_view_helpers
+      build_from_builder_file if use_builder?
+      setup_widgets
+      autoconnect_signals(self)
+    end
+
+    # This is included here so that the initialize method is properly updated.
+    include RuGUI::InitializeHooks
+
+    # Returns the framework_adapter for this class.
+    def framework_adapter
+      framework_adapter_for('BaseView')
+    end
+
+    # Reimplement this method to create widgets by hand.
+    def setup_widgets
+    end
+    
+    # Reimplement this method to setup view helpers.
+    def setup_view_helpers
+    end
+
+    # Adds the given widget to a container widget.
+    def add_widget_to_container(widget, container_widget_or_name)
+      self.framework_adapter.add_widget_to_container(widget, from_widget_or_name(container_widget_or_name))
+    end
+
+    # Adds the given widget to a container widget.
+    def remove_widget_from_container(widget, container_widget_or_name)
+      self.framework_adapter.remove_widget_from_container(widget, from_widget_or_name(container_widget_or_name))
+    end
+
+    # Includes a view root widget inside the given container widget.
+    def include_view(container_widget_name, view)
+      raise RootWidgetNotSetForIncludedView, "You must set a root for views to be included." if view.root_widget.nil?
+      add_widget_to_container(view.root_widget, container_widget_name)
+    end
+
+    # Removes a view root widget from the given container widget.
+    def remove_view(container_widget_name, view)
+      raise RootWidgetNotSetForIncludedView, "You must set a root for views to be removed." if view.root_widget.nil?
+      remove_widget_from_container(view.root_widget, container_widget_name)
+    end
+
+    # Removes all children from the given container widget
+    def remove_all_children(container_widget)
+      self.framework_adapter.remove_all_children(container_widget)
+    end
+
+    # Registers a controller as receiver of signals from the view widgets.
+    def register_controller(controller, name = nil)
+      name ||= controller.class.to_s.underscore
+      autoconnect_signals(controller)
+      @controllers[name.to_sym] = controller
+    end
+
+    # Registers a view helper for the view.
+    def register_helper(helper, name = nil)
+      helper = create_instance_if_possible(helper) if helper.is_a?(String) or helper.is_a?(Symbol)
+      unless helper.nil?()
+        name ||= helper.class.to_s.underscore
+        helper.register_observer(self, name)
+        @helpers[name.to_sym] = helper
+        create_attribute_reader(:helpers, name)
+        helper.post_registration(self)
+      end
+    end
+
+    # Called after the view is registered in a controller.
+    def post_registration(controller)
+    end
+
+    # Returns the root widget if one is set.
+    def root_widget
+      send(root.to_sym) if not root.nil?
+    end
+
+    # Returns the builder file.
+    def builder_file
+      self.configured_builder_file
+    end
+
+    # Returns the builder file extension.
+    def builder_file_extension
+      self.configured_builder_file_extension
+    end
+
+    # Returns true if builder file is being used for this view.
+    def use_builder?
+      self.configured_builder_file_usage
+    end
+
+    # Framework adapters should implement this if they support builder files.
+    def build_from_builder_file
+      filename = get_builder_file
+      raise BuilderFileNotFoundError, "Could not find builder file for view #{self.class.name}. UI file paths: #{RuGUI.configuration.builder_files_paths.join(', ')}." if filename.nil?
+
+      self.framework_adapter.build_widgets_from(filename)
+      self.framework_adapter.register_widgets
+    end
+
+    # Returns the name of the root widget for this view.
+    def root
+      self.configured_root.to_s unless self.configured_root.nil?
+    end
+
+    def display_root?
+      !!self.configured_display_root
+    end
+
+    class << self
+      # Sets the name of the root widget for this view.
+      #
+      # This is specially useful when more than one view uses the same glade
+      # file, but each one uses a diferent widget tree inside that glade file.
+      #
+      # Other use for this is when building a reusable widget, composed of the
+      # contents of a glade file. One could create a window, place a vertical
+      # box, and then place elements inside this vertical box. Later, this glade
+      # file is used to insert the contents of the vertical box inside another
+      # vertical box in other glade file.
+      def root(root_widget_name)
+        self.configured_root = root_widget_name
+      end
+
+      # Sets the builder file to use when creating this view.
+      def builder_file(file)
+        self.configured_builder_file = file
+      end
+
+      # Tells whether we should use a builder file when creating this view.
+      #
+      # By default the root widget will be displayed, but you can pass false to
+      # this method to prevent it for being displayed.
+      def use_builder(display_root = true)
+        self.configured_builder_file_usage = true
+        self.configured_display_root = display_root
+
+        self.configured_builder_file_extension = self.framework_adapter_class.builder_file_extension
+        default_builder_file_path = RuGUI.root.join('app', 'resources', "#{self.configured_builder_file_extension}")
+        RuGUI.configuration.builder_files_paths << default_builder_file_path unless RuGUI.configuration.builder_files_paths.include?(default_builder_file_path)
+      end
+
+      def framework_adapter_class
+        class_adapter_for('BaseView')
+      end
+    end
+
+    protected
+      # Builds a widget of the given type, possibly adding it to a parent
+      # widget, and display it.
+      #
+      # The *args are passed to the widget constructor.
+      def build_widget(widget_type, widget_name = nil, parent = nil, *args)
+        widget = widget_type.new(*args)
+        self.framework_adapter.set_widget_name(widget, widget_name)
+        add_widget(widget, widget_name)
+        add_widget_to_container(widget, parent) unless parent.nil?
+        widget.show
+      end
+
+      # Adds the widget to the view.
+      #
+      # If +widget_name+ is not given one is assumed the widget`s name will be
+      # used instead. If the widget doesn't have a name it will be added as an
+      # unnamed widget (accessible through #unnamed_widgets property.
+      def add_widget(widget, widget_name = nil)
+        widget_name ||= widget.name
+        widget_name = widget_name.to_s
+
+        unless widget_name.nil? || widget_name.empty?
+          create_attribute_for_widget(widget_name)
+          send("#{widget_name}=", widget)
+          @widgets[widget_name] = widget
+        else
+          @unnamed_widgets << widget
+        end
+      end
+
+      def from_widget_or_name(widget_or_name)
+        if widget_or_name.is_a?(String) || widget_or_name.is_a?(Symbol)
+          send(widget_or_name)
+        else
+          widget_or_name
+        end
+      end
+
+      def autoconnect_signals(receiver)
+        receiver.autoconnect_declared_signals(self)
+        self.framework_adapter.autoconnect_signals(receiver)
+      end
+
+    private
+      def get_builder_file
+        filename = (not self.builder_file.nil?) ? self.builder_file : "#{self.class.to_s.underscore}.#{builder_file_extension}"
+
+        # The builder file given may already contain a full path to a glade file.
+        return filename if File.file?(filename)
+
+        filename = "#{filename}.#{builder_file_extension}" unless File.extname(filename) == ".#{builder_file_extension}"
+
+        paths = RuGUI.configuration.builder_files_paths.select do |path|
+          File.file?(File.join(path, filename))
+        end
+        File.join(paths.first, filename) unless paths.empty?
+      end
+
+      # Attempts to register the default helper for the view
+      def register_default_helper
+        register_helper("#{self.class.name}Helper", :helper)
+      end
+
+      def create_attribute_for_widget(widget_name)
+        self.instance_eval <<-instance_eval
+          def #{widget_name}
+            @#{widget_name}
+          end
+
+          def #{widget_name}=(widget)
+            @#{widget_name} = widget
+          end
+        instance_eval
+      end
+
+      # Creates an attribute reader for the some entity.
+      def create_attribute_reader(entity, name)
+        self.class.class_eval <<-class_eval
+          def #{name}
+            @#{entity}[:#{name}]
+          end
+        class_eval
+      end
+
+      # Creates an instance of the given class.
+      def create_instance_if_possible(klass_name, *args)
+        klass_name.to_s.camelize.constantize.new(*args)
+      rescue NameError
+        # Couldn't create instance.
+      end
+  end
+
+  # Exception thrown when the builder file for this view could not be found.
+  class BuilderFileNotFoundError < Exception
+  end
+
+  # Exception thrown when attempting to include a view which don't have a root
+  # set.
+  class RootWidgetNotSetForIncludedView < Exception
+  end
+end

data/lib/rugui/base_view_helper.rb

@@ -0,0 +1,23 @@
+module RuGUI
+  # A base class for view helpers.
+  class BaseViewHelper < BaseObject
+    include RuGUI::ObservablePropertySupport
+    include RuGUI::LogSupport
+    
+    def initialize(observable_properties_values = {})
+      initialize_observable_property_support(observable_properties_values)
+    end
+
+    # This is included here so that the initialize method is properly updated.
+    include RuGUI::InitializeHooks
+
+    # Returns the framework_adapter for this class.
+    def framework_adapter
+      framework_adapter_for('BaseViewHelper')
+    end
+
+    # Called after the view helper is registered in a view.
+    def post_registration(view)
+    end
+  end
+end

data/lib/rugui/configuration.rb

@@ -0,0 +1,136 @@
+# Defines the environment to be used by the application.
+RUGUI_ENV = (ENV['RUGUI_ENV'] || 'development').dup unless defined?(RUGUI_ENV)
+
+module RuGUI
+  # Defines configurations for a RuGUI application.
+  class Configuration
+    # The application root path, defined by ::APPLICATION_ROOT
+    attr_reader :root_path
+
+    # The environment for this application.
+    attr_accessor :environment
+
+    # The framework adapter to be used for this application. Defaults to GTK.
+    # For now it can only be GTK.
+    attr_accessor :framework_adapter
+
+    # The specific logger to use. By default, a logger will be created and
+    # initialized using #log_path and #log_level, but a programmer may
+    # specifically set the logger to use via this accessor and it will be
+    # used directly.
+    attr_accessor :logger
+
+    # An array of paths for builder files.
+    attr_accessor :builder_files_paths
+
+    # An array of paths which should be automaticaly loaded.
+    attr_accessor :load_paths
+
+    # An array of paths which should be searched for gtkrc styles files.
+    #
+    # It searchs for files which have the '.rc' extension or files which have
+    # the string 'gtkrc' in its filename.
+    #
+    # The order in which the files are loaded is random, so do not rely on it.
+    #
+    # If you need to use absolute paths in a gtkrc file, such as set the pixmap
+    # path, you can use "{ROOT_PATH}", which will be substituted by the
+    # application root path when the file is read.
+    attr_accessor :styles_paths
+
+    # The timeout for queued calls. Useful when performing long tasks.
+    attr_accessor :queue_timeout
+
+    # A hash of application specific configurations.
+    attr_accessor :application
+
+    # An array of gems that this RuGUI application depends on.  RuGUI will automatically load
+    # these gems during installation, and allow you to install any missing gems with:
+    #
+    #   rake gems:install
+    #
+    # You can add gems with the #gem method.
+    attr_accessor :gems
+    
+    def initialize
+      set_root_path!
+
+      self.environment = default_environment
+      self.framework_adapter = default_framework_adapter
+      self.load_paths = default_load_paths
+      self.builder_files_paths = default_builder_files_paths
+      self.styles_paths = default_styles_paths
+      self.queue_timeout = default_queue_timeout
+      self.gems = default_gems
+      self.logger = {}
+      self.application = {}
+    end
+
+    # The path to the current environment's file (<tt>development.rb</tt>, etc.). By
+    # default the file is at <tt>config/environments/#{environment}.rb</tt>.
+    def environment_path
+      root_path.join('config', 'environments', "#{environment}.rb")
+    end
+
+    def set_root_path!
+      raise 'APPLICATION_ROOT is not set' unless defined?(::APPLICATION_ROOT)
+      raise 'APPLICATION_ROOT is not a directory' unless File.directory?(::APPLICATION_ROOT)
+
+      @root_path = Pathname.new(File.expand_path(::APPLICATION_ROOT))
+    end
+
+    # Adds a single Gem dependency to the RuGUI application. By default, it will require
+    # the library with the same name as the gem. Use :lib to specify a different name.
+    #
+    #   # gem 'aws-s3', '>= 0.4.0'
+    #   # require 'aws/s3'
+    #   config.gem 'aws-s3', :lib => 'aws/s3', :version => '>= 0.4.0', \
+    #     :source => "http://code.whytheluckystiff.net"
+    #
+    # To require a library be installed, but not attempt to load it, pass :lib => false
+    #
+    #   config.gem 'qrp', :version => '0.4.1', :lib => false
+    def gem(name, options = {})
+      @gems << RuGUI::GemDependency.new(name, options)
+    end
+
+    private
+      def default_environment
+        ::RUGUI_ENV
+      end
+
+      def default_framework_adapter
+        'GTK'
+      end
+
+      def default_load_paths
+        paths = []
+
+        paths.concat %w(
+          app
+          app/models
+          app/controllers
+          app/views
+          app/views/helpers
+          config
+          lib
+        ).map { |dir| root_path.join(dir) }.select { |dir| File.directory?(dir) }
+      end
+
+      def default_builder_files_paths
+        []
+      end
+
+      def default_styles_paths
+        [root_path.join('app', 'resources', 'styles')]
+      end
+
+      def default_queue_timeout
+        50
+      end
+
+      def default_gems
+        []
+      end
+  end
+end

data/lib/rugui/framework_adapters/GTK.rb

@@ -0,0 +1,233 @@
+require 'gtk2'
+require 'libglade2'
+
+# See the discussion here: http://eigenclass.org/hiki.rb?instance_exec
+class Object
+  module InstanceExecHelper; end
+  include InstanceExecHelper
+  def instance_exec(*args, &block)
+    begin
+      old_critical, Thread.critical = Thread.critical, true
+      n = 0
+      n += 1 while respond_to?(mname="__instance_exec#{n}")
+      InstanceExecHelper.module_eval{ define_method(mname, &block) }
+    ensure
+      Thread.critical = old_critical
+    end
+    begin
+      ret = send(mname, *args)
+    ensure
+      InstanceExecHelper.module_eval{ remove_method(mname) } rescue nil
+    end
+    ret
+  end
+end
+
+module Gtk
+  GTK_PENDING_BLOCKS = []
+  GTK_PENDING_BLOCKS_LOCK = Monitor.new
+
+  def Gtk.queue(&block)
+    if Thread.current == Thread.main
+      block.call
+    else
+      GTK_PENDING_BLOCKS_LOCK.synchronize do
+        GTK_PENDING_BLOCKS << block
+      end
+    end
+  end
+
+  # Adds a timeout to execute pending blocks in a queue.
+  def Gtk.queue_timeout(timeout)
+    Gtk.timeout_add timeout do
+      GTK_PENDING_BLOCKS_LOCK.synchronize do
+        GTK_PENDING_BLOCKS.each do |block|
+          block.call
+        end
+        GTK_PENDING_BLOCKS.clear
+      end
+      true
+    end
+  end
+
+  def Gtk.load_style_paths
+    styles_paths = RuGUI.configuration.styles_paths.select { |path| File.directory?(path) }
+    styles_paths.each do |path|
+      Dir.new(path).each do |entry|
+        Gtk::RC.parse_string(get_style_file_contents(path, entry)) if is_style_file?(path, entry)
+      end
+    end
+  end
+
+  def Gtk.is_style_file?(path, filename)
+    File.extname(filename) == '.rc' or /gtkrc/.match(filename) if File.file?(File.join(path, filename))
+  end
+
+  def Gtk.get_style_file_contents(path, filename)
+    IO.read(File.join(path, filename)).sub('{ROOT_PATH}', RuGUI.configuration.root_path)
+  end
+end
+
+Gtk.load_style_paths
+
+module RuGUI
+  module FrameworkAdapters
+    module GTK
+      class BaseController < RuGUI::FrameworkAdapters::BaseFrameworkAdapter::BaseController
+        def queue(&block)
+          Gtk.queue(&block)
+        end
+      end
+
+      class BaseMainController < RuGUI::FrameworkAdapters::GTK::BaseController
+        def run
+          Gtk.queue_timeout(RuGUI.configuration.queue_timeout)
+          Gtk.main
+        end
+
+        def quit
+          Gtk.main_quit
+        end
+      end
+
+      class BaseView < RuGUI::FrameworkAdapters::BaseFrameworkAdapter::BaseView
+        # Queues the block call, so that it is only gets executed in the main thread.
+        def queue(&block)
+          Gtk.queue(&block)
+        end
+
+        # Adds a widget to the given container widget.
+        def add_widget_to_container(widget, container_widget)
+          container_widget.add(widget)
+        end
+
+        # Removes a widget from the given container widget.
+        def remove_widget_from_container(widget, container_widget)
+          container_widget.remove(widget)
+        end
+
+        # Removes all children from the given container widget.
+        def remove_all_children(container_widget)
+          container_widget.children.each do |child|
+            container_widget.remove(child)
+          end
+        end
+
+        # Sets the widget name for the given widget if given.
+        def set_widget_name(widget, widget_name)
+          widget.name = widget_name.to_s unless widget_name.nil?
+        end
+
+        # Autoconnects signals handlers for the view. If +other_target+ is given
+        # it is used instead of the view itself.
+        def autoconnect_signals(other_target = nil)
+          if self.adapted_object.use_builder?
+            self.adapted_object.glade.signal_autoconnect_full do |source, target, signal_name, handler_name, signal_data, after|
+              target ||= other_target
+              self.adapted_object.glade.connect(source, target, signal_name, handler_name, signal_data) if target.respond_to?(handler_name)
+            end
+          end
+        end
+
+        # Connects the signal from the widget to the given receiver block.
+        # The block is executed in the context of the receiver.
+        def connect_declared_signal_block(widget, signal, receiver, block)
+          widget.signal_connect(signal) do |*args|
+            receiver.instance_exec(*args, &block)
+          end
+        end
+
+        # Connects the signal from the widget to the given receiver method.
+        def connect_declared_signal(widget, signal, receiver, method)
+          widget.signal_connect(signal) do |*args|
+            receiver.send(method, *args)
+          end
+        end
+
+        # Builds widgets from the given filename, using the proper builder.
+        def build_widgets_from(filename)
+          self.adapted_object.glade = GladeXML.new(filename, self.adapted_object.root, nil, nil, GladeXML::FILE)
+
+          self.adapted_object.glade.widget_names.each do |widget_name|
+            self.adapted_object.send(:create_attribute_for_widget, widget_name) unless self.adapted_object.glade[widget_name].nil?
+          end
+          self.adapted_object.root_widget.show if self.adapted_object.display_root? and not self.adapted_object.root_widget.nil?
+        end
+
+        # Registers widgets as attributes of the view class.
+        def register_widgets
+          self.adapted_object.glade.widget_names.each do |widget_name|
+            unless self.adapted_object.glade[widget_name].nil?
+              self.adapted_object.send("#{widget_name}=".to_sym, self.adapted_object.glade[widget_name])
+              self.adapted_object.widgets[widget_name] = self.adapted_object.glade[widget_name]
+            end
+          end
+        end
+
+        class << self
+          # Returns the builder file extension to be used for this view class.
+          def builder_file_extension
+            'glade'
+          end
+        end
+      end
+    end
+  end
+end
+
+module RuGUI
+  class BaseView < BaseObject
+    class_inheritable_accessor :configured_glade_usage
+
+    attr_accessor :glade
+
+    # Adds a signal handler for all widgets of the given type.
+    def add_signal_handler_for_widget_type(widget_type, signal, &block)
+      widgets = []
+      widgets.concat(@widgets.values.select { |widget| widget.kind_of?(widget_type) }) unless @widgets.empty?
+      widgets.concat(@unnamed_widgets.select { |widget| widget.kind_of?(widget_type) }) unless @unnamed_widgets.empty?
+
+      widgets.each do |widget|
+        widget.signal_connect(signal, &block)
+      end
+    end
+
+    # Changes the widget style to use the given widget style.
+    #
+    # This widget style should be declared in a gtkrc file, by specifying a
+    # style using a widget path, such as:
+    #
+    #   widget "main_window" style "main_window_style"
+    #   widget "main_window_other" style "main_window_other_style"
+    #
+    # In this example, if you called this method like this:
+    #
+    #   change_widget_style(:main_window, 'main_window_other')
+    #   change_widget_style(self.main_window, 'main_window_other')     # or, passing the widget instance directly
+    #
+    # The widget style would be set to "main_window_other_style".
+    #
+    # NOTE: Unfortunately, gtk doesn't offer an API to get declared styles, so
+    # you must set a style to a widget. Since the widget name set in the style
+    # definition doesn't need to point to an existing widget we can use this
+    # to simplify the widget styling here.
+    def change_widget_style(widget_or_name, widget_path_style)
+      if widget_or_name.is_a?(Gtk::Widget)
+        widget = widget_or_name
+      else
+        widget = @glade[widget_or_name.to_s]
+      end
+      style = Gtk::RC.get_style_by_paths(Gtk::Settings.default, widget_path_style.to_s, nil, nil)
+      widget.style = style
+    end
+
+    class << self
+      # Call this method at class level if the view should be built from a glade
+      # file.
+      def use_glade
+        self.logger.warn('DEPRECATED - Call use_builder class method instead in your view.')
+        use_builder
+      end
+    end
+  end
+end