gtkbuilder 0.1 → 0.2

data/lib/gtkbuilder.rb

@@ -2,6 +2,9 @@ module Builder
 
   module Gtk
 
+    ## Defines a new Gtk window
+    # @param block A block that will be passed a builder proxy object
+    # @return the created window
     def self.new(*args, &block)
       proxy = Builder::Gtk::WindowProxy.new(*args)
       block.call(proxy) if block

data/lib/proxies/box.rb

@@ -2,10 +2,13 @@ require 'proxies/layout.rb'
 
 module Builder::Gtk
 
+  ## Proxies both VBox and HBox
   class BoxProxy
 
     include LayoutProxy
 
+    ## Creates a new proxy for the given VBox or HBox widget
+    # The default packing is @pack_start(widget, false, false, 0)@.
     def initialize(widget)
       @widget = widget
       @data = {
@@ -14,16 +17,25 @@ module Builder::Gtk
       }
     end
 
+    ## Sets the pack mode to pack_start.
+    # The arguments are passed to pack_start for every
+    # following widget definition.
     def start(*args, &block)
       return _pack(:start, args, block)
     end
 
+    ## Sets the pack mode to pack_end
+    # The arguments are passed to pack_end for every
+    # following widget definition.
     def end(*args, &block)
       return _pack(:end, args, block)
     end
 
     private
 
+    ## Common function for both pack modes.
+    # The arguments are passed to the pack function for every
+    # following widget definition.
     def _pack(position, args, block)
       @data = {
         :position => position,
@@ -33,6 +45,7 @@ module Builder::Gtk
       return self
     end
 
+    ## Actually packs the given widget using the saved position and arguments.
     def _pack_widget(widget)
       @widget.send("pack_#{@data[:position]}", widget, *@data[:args])
     end

data/lib/proxies/layout.rb

@@ -2,13 +2,32 @@ require 'gtk2'
 
 module Builder::Gtk
 
+  ## Base class for all widgets that can have children
   module LayoutProxy
 
+    ## The widget that is being proxied
     attr_accessor :widget
 
+    ## Handles constructing Gtk widgets
+    #
+    # Example:
+    #
+    #   proxy.entry --> Gtk::Entry.new
+    #   proxy.vbox(true, 10) --> Gtk::VBox.new(true, 10)
+    #   proxy.drawing_area --> Gtk::DrawingArea.new
+    #
+    # @param name The name of the widget in snake case
+    # @param args The arguments to pass to the constructor of
+    #     the Gtk widget
+    # @param block A block that will be executed with the created widget
+    #     or a proxy if one is available.
     def method_missing(name, *args, &block)
-      widget = _get_widget(name, args, &block)
-      proxy = _get_proxy(name, widget) || widget
+      if @widget.respond_to?(name)
+        return @widget.__send__(name, *args, &block)
+      end
+
+      widget = _get_widget(name, args)
+      proxy = _get_proxy(name, widget)
       block.call(proxy) if block
       _pack_widget(widget)
       return self
@@ -16,13 +35,17 @@ module Builder::Gtk
 
     private
 
-    def _get_widget(name, args, &block)
+    ## Tries to create a Gtk widget with the given name.
+    # All arguments are forwarded to the widget.
+    def _get_widget(name, args)
         class_name = _find_gtk_class(name)
-        raise RuntimeError.new("no widget found for name #{name}") unless class_name
+        raise RuntimeError.new("no widget found for name `#{name}'") unless class_name
         klass = ::Gtk.const_get(class_name)
-        return klass.new(*args, &block)
+        return klass.new(*args)
     end
 
+    ## Tries to find a Gtk widget for the given name
+    # @return the found widget class or nil.
     def _find_gtk_class(name)
       name = name.to_s.gsub("_", "").downcase
       return ::Gtk.constants.find do |constant|
@@ -30,17 +53,22 @@ module Builder::Gtk
       end
     end
 
+    ## Creates a proxy for the given widget with the given name.
+    # If no proxy can be created, returns the widget itself.
     def _get_proxy(name, widget)
       case name.to_s
-      when "winodw" then return WindowvboxProxy.new(widget)
+      when "window" then return WindowvboxProxy.new(widget)
       when "vbox" then return BoxProxy.new(widget)
       when "hbox" then return BoxProxy.new(widget)
-      else return nil
+      else return widget
       end
     end
 
+    ## Must be reimplemented by subclasses to actually pack the
+    # given widget.
+    # Raises an exception by default.
     def _pack_widget(widget)
-      raise RuntimeError.new("cannot pack inside this widget")
+      raise RuntimeError.new("cannot pack inside this widget. This is a bug in the gtkbuilder implementation")
     end
 
   end

data/lib/proxies/window.rb

@@ -2,16 +2,19 @@ require 'proxies/layout.rb'
 
 module Builder::Gtk
 
+    ## Proxies a window.
     class WindowProxy
 
       include LayoutProxy
 
+      ## Creates a new window proxy and a new window.
       def initialize(*args)
         @widget = ::Gtk::Window.new(*args)
       end
 
       private
 
+      ## Packs the given widget into the window.
       def _pack_widget(widget)
         @widget.add(widget)
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gtkbuilder
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
   prerelease: 
 platform: ruby
 authors:
@@ -9,9 +9,9 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-20 00:00:00.000000000 Z
+date: 2012-11-21 00:00:00.000000000 Z
 dependencies: []
-description: Builder::Gtk provides a DSL for generating Gtk2 windows.
+description: Builder::Gtk let's you build Gtk windows using a simple DSL
 email:
 - github@rottenrei.be
 executables: []
@@ -47,5 +47,5 @@ rubyforge_project:
 rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
-summary: Easy creation of Gtk windows
+summary: Easy way to generate simple Gtk GUIs
 test_files: []