hotcocoa 0.6.0 → 0.6.1

data/lib/hotcocoa/delegate_builder.rb

@@ -1,120 +1,149 @@
-##
-# Builds a delegate for a control at runtime by creating a generic object
-# and adding singleton methods for each given delegate method; it then
-# tells the control to delegate to that created object.
-class HotCocoa::DelegateBuilder
-
-  # @return The object that needs a delegate
-  attr_reader :control
-
-  # @return [Array<>] Delegate methods which are assumed to be implemented
-  #    and therefore __MUST__ be given at least a stub
-  attr_reader :required_methods
-
-  # @return [Fixnum] Number of delegate methods that have been added
-  attr_reader :method_count
-
-  # @return [Object] The delegate object
-  attr_reader :delegate
-
-  # @param control the object which needs a delegate
-  # @param [Array<String>] required_methods
-  def initialize control, required_methods
-    @control = control
-    @required_methods = required_methods
-    @method_count = 0
-    @delegate = Object.new
-  end
+module HotCocoa
 
   ##
-  # Add a delegated method for {#control} to {#delegate}
-  def add_delegated_method block, selector_name, *parameters
-    clear_delegate if required_methods.empty?
+  # Builds a delegate for a control at runtime by creating a generic object
+  # and adding singleton methods for each given delegate method; it then
+  # tells the control to delegate to that created object.
+  class DelegateBuilder
+
+    ##
+    # The object that needs a delegate
+    #
+    # @return
+    attr_reader :control
+
+    ##
+    # Delegate methods which are assumed to be implemented and therefore
+    # __MUST__ be given at least a stub
+    #
+    # @return [Array<SEL,String>]
+    attr_reader :required_methods
+
+    ##
+    # The delegate object
+    #
+    # @return [Object]
+    attr_reader :delegate
+
+    # @param control the object which needs a delegate
+    # @param [Array<SEL,String>] required_methods
+    def initialize control, required_methods
+      @control          = control
+      @required_methods = required_methods
+      @delegate         = Object.new
+    end
 
-    @method_count += 1
-    bind_block_to_delegate_instance_variable(block)
-    create_delegate_method(selector_name, parameters)
+    ##
+    # Add a delegated method for {#control} to {#delegate}
+    def add_delegated_method block, selector_name, *parameters
+      clear_delegate if required_methods.empty?
 
-    set_delegate if required_methods.empty?
-  end
+      delegate_method_builder.add_delegated_method block, selector_name, *parameters
 
-  def delegate_to object, *method_names
-    method_names.each do |method_name|
-      control.send(method_name, &object.method(method_name)) if object.respond_to?(method_name)
+      required_methods.delete(selector_name)
+      set_delegate if required_methods.empty?
     end
-  end
 
-  private
+    def delegate_to object, *method_names
+      method_names.each do |method_name|
+        control.send(method_name, &object.method(method_name)) if object.respond_to?(method_name)
+      end
+    end
 
-  def bind_block_to_delegate_instance_variable block
-    delegate.instance_variable_set(block_instance_variable, block)
-  end
 
-  ##
-  # @todo GET RID OF EVAL
-  def create_delegate_method selector_name, parameters
-    required_methods.delete(selector_name)
-    eval %{
-      def delegate.#{parameterize_selector_name(selector_name)}
-        #{block_instance_variable}.call(#{parameter_values_for_mapping(selector_name, parameters)})
-      end
-    }
-  end
+    private
 
-  ##
-  # Reset the delegate for {#control} to `nil`.
-  def clear_delegate
-    control.setDelegate(nil) if control.delegate
-  end
+    ##
+    # Reset the delegate for {#control} to `nil`.
+    def clear_delegate
+      control.setDelegate(nil) if control.delegate
+    end
 
-  ##
-  # Set the delegate for {#control} to {#delegate}
-  def set_delegate
-    control.setDelegate(delegate)
-  end
+    ##
+    # Set the delegate for {#control} to {#delegate}
+    def set_delegate
+      control.setDelegate(delegate)
+    end
+
+    def delegate_method_builder
+      @delegate_method_builder ||= DelegateMethodBuilder.new(@delegate)
+    end
 
-  ##
-  # Returns an instance variable name to be used for the delegate method
-  # currently being built.
-  #
-  # @return [String]
-  def block_instance_variable
-    "@block#{method_count}"
   end
 
-  ##
-  # Take an Objective-C selector and create a parameter list to be used
-  # in creating method's using #eval
-  #
-  # @example
-  #   parameterize_selector_name('myDelegateMethod') # => 'myDeletageMethod'
-  #   parameterize_selector_name('myDelegateMethod:withArgument:') # => 'myDeletageMethod p1, withArgumnet:p2'
-  #
-  # @param [String] selector_name
-  # @return [String]
-  def parameterize_selector_name selector_name
-    return selector_name unless selector_name.include?(':')
-
-    params = selector_name.split(':')
-    result = "#{params.shift} p1"
-    params.each_with_index do |param, i|
-      result << ",#{param}:p#{i + 2}"
+
+  class DelegateMethodBuilder
+
+    def initialize target
+      @target = target
     end
-    result
-  end
 
-  def parameter_values_for_mapping selector_name, parameters
-    return if parameters.empty?
+    def add_delegated_method block, selector_name, *parameters
+      bind_block_to_delegate_instance_variable(selector_name, block)
+      create_delegate_method(selector_name, parameters)
+    end
+
+    def bind_block_to_delegate_instance_variable selector_name, block
+      @target.instance_variable_set(block_instance_variable_for(selector_name), block)
+    end
 
-    result = []
-    selector_params = selector_name.split(':')
-    parameters.each do |parameter|
-      if (dot = parameter.index('.'))
-        result << "p#{selector_params.index(parameter[0...dot]) + 1}#{parameter[dot..-1]}"
-      else
-        result << "p#{selector_params.index(parameter) +  1}"
+    ##
+    # @todo GET RID OF EVAL
+    def create_delegate_method selector_name, parameters
+      eval %{
+        def @target.#{parameterize_selector_name(selector_name)}
+          #{block_instance_variable_for(selector_name)}.call(#{parameter_values_for_mapping(selector_name, parameters)})
+        end
+      }
+    end
+
+    ##
+    # Returns an instance variable name to be used for the delegate method
+    # currently being built.
+    #
+    # @return [String]
+    def block_instance_variable_for selector_name
+      "@block_#{selector_name.gsub(':', "_")}"
+    end
+
+    ##
+    # Take an Objective-C selector and create a parameter list to be used
+    # in creating method's using #eval
+    #
+    # @example
+    #   parameterize_selector_name('myDelegateMethod') # => 'myDeletageMethod'
+    #   parameterize_selector_name('myDelegateMethod:withArgument:') # => 'myDeletageMethod p1, withArgument:p2'
+    #
+    # @param [String] selector_name
+    # @return [String]
+    def parameterize_selector_name selector_name
+      return selector_name unless selector_name.include?(':')
+
+      params = selector_name.split(':')
+      result = "#{params.shift} p1"
+      params.each_with_index do |param, i|
+        result << ",#{param}:p#{i + 2}"
+      end
+      result
+    end
+
+    def parameter_values_for_mapping selector_name, parameters
+      return if parameters.empty?
+
+      result = []
+      selector_params = selector_name.split(':')
+      parameters.each do |parameter|
+        if (dot = parameter.index('.'))
+          result << "p#{selector_params.index(parameter[0...dot]) + 1}#{parameter[dot..-1]}"
+        else
+          parameter = parameter.to_s
+          raise "Error in delegate mapping: '#{parameter}' is not a valid parameter of method '#{selector_name}'" if selector_params.index(parameter).nil?
+          result << "p#{selector_params.index(parameter) +  1}"
+        end
       end
+      result.join(', ')
     end
-    result.join(', ')
+
   end
+
 end

data/lib/hotcocoa/layout_view.rb

@@ -203,8 +203,8 @@ module HotCocoa
     end
 
     def update_layout_views!
-      @view.superview.views_updated! if in_layout_view?
-      @defaults_view.views_updated! if @defaults_view
+      @view.superview.relayout! if in_layout_view?
+      @defaults_view.relayout!  if @defaults_view
     end
 
     private
@@ -214,36 +214,62 @@ module HotCocoa
     end
   end
 
+  ##
+  # @todo Why aren't we mixing in {HotCocoa::Behaviors}?
+  #
+  # HotCocoa layout managing class. This class is responsible for keeping
+  # track of your UI layout, including adding, removing, and updating
+  # subviews.
   class LayoutView < NSView
-    attr_accessor :frame_color
 
+    ##
+    # Set some default values and call the super class initializer.
+    #
+    # @param [CGRect, Array<Number, Number, Number, Number>]
     def initWithFrame frame
       super
-      @mode = :vertical
-      @spacing = 10.0
-      @margin = 10.0
+      @mode    = :vertical
+      @spacing = 10
+      @margin  = 10
       self
     end
 
+    # @return [NSColor]
+    attr_accessor :frame_color
+
+    ##
+    # Whether or not the layout mode is vertical.
     def vertical?
       @mode == :vertical
     end
 
+    ##
+    # Whether or not the layout mode is horizontal.
     def horizontal?
       @mode == :horizonal
     end
 
-    def mode= mode
-      unless [:horizontal, :vertical].include?(mode)
-        raise ArgumentError, "invalid mode value #{mode}"
+    ##
+    # Set the layout mode. The default value is `:vertical`, you can
+    # change it to be `:horizontal` if you want.
+    #
+    # @param [Symbol]
+    def mode= new_mode
+      unless [:horizontal, :vertical].include?(new_mode)
+        raise ArgumentError, "invalid mode value #{new_mode}"
       end
 
-      if mode != @mode
-        @mode = mode
+      if new_mode != @mode
+        @mode = new_mode
         relayout!
       end
     end
 
+    ##
+    # Set the default layout options. The options should follow the format
+    # that would be given to {HotCocoa::LayoutOptions}.
+    #
+    # @param [Hash]
     def default_layout= options
       options[:defaults_view] = self
       @default_layout = LayoutOptions.new(nil, options)
@@ -251,74 +277,73 @@ module HotCocoa
     end
 
     def default_layout
-      @default_layout ||= LayoutOptions.new(nil, :defaults_view => self)
+      @default_layout ||= LayoutOptions.new(nil, defaults_view: self)
     end
 
-    def spacing
-      @spacing
-    end
+    # @return [Fixnum]
+    attr_reader :spacing
 
-    def spacing= spacing
-      if spacing != @spacing
-        @spacing = spacing.to_i
+    ##
+    # Change the spacing between subviews.
+    #
+    # @param [Number]
+    def spacing= new_spacing
+      if new_spacing != @spacing
+        @spacing = new_spacing.to_i
         relayout!
       end
     end
 
-    def frame= frame
-      setFrame(frame)
-    end
-
-    def size= size
-      setFrameSize(size)
-    end
-
-    def margin
-      @margin
-    end
+    # @return [Fixnum]
+    attr_reader :margin
 
-    def margin= margin
-      if margin != @margin
-        @margin = margin.to_i
+    ##
+    # Change the margin size for the view.
+    #
+    # @param [Fixnum]
+    def margin= new_margin
+      if new_margin != @margin
+        @margin = new_margin.to_i
         relayout!
       end
     end
 
-    def << view
-      addSubview(view)
-    end
-
-    def remove subview, options = {}
-      raise ArgumentError, "#{subview} is not a subview of #{self} and cannot be removed." unless subview.superview == self
-      options[:needs_display] == false ? subview.removeFromSuperviewWithoutNeedingDisplay : subview.removeFromSuperview
-    end
-
-    def addSubview(view)
+    ##
+    # Add a new subview to the layout view.
+    #
+    # @param [NSView]
+    def addSubview view
       super
-      if view.respond_to?(:layout)
+      if view.respond_to? :layout
         relayout!
       else
         raise ArgumentError, "view #{view} does not support the #layout method"
       end
     end
+    alias_method :<<, :addSubview
 
-    def views_updated!
-      relayout!
-    end
-
+    ##
+    # Remove a subview from the layout.
+    #
+    # @param [NSView]
     def remove_view view
-      unless subviews.include?(view)
+      unless subviews.include? view
         raise ArgumentError, "view #{view} not a subview of this LayoutView"
       end
       view.removeFromSuperview
       relayout!
     end
+    alias_method :remove, :remove_view
 
+    ##
+    # Remove all the subviews from the layout view.
     def remove_all_views
       subviews.each { |view| view.removeFromSuperview }
       relayout!
     end
 
+    ##
+    # This is a callback, you don't need to worry about it.
     def drawRect frame
       if frame_color
         frame_color.set
@@ -326,59 +351,37 @@ module HotCocoa
       end
     end
 
+    ##
+    # This is a callback, you don't need to worry about it.
     def setFrame frame
       super(frame, &nil)
       relayout!
     end
+    alias_method :frame=, :setFrame
 
+    ##
+    # This is a callback, you don't need to worry about it.
     def setFrameSize size
       super(size, &nil)
       relayout!
     end
+    alias_method :size=, :setFrameSize
 
-    private
-
-    def calc_expandable_size end_dimension
-      expandable_size = end_dimension
-      expandable_views = 0
-
-      subviews.each do |view|
-        next unless can_layout?(view)
-
-        if vertical?
-          size = view.frameSize.height
-          expand = view.layout.expand_height?
-          padding = view.layout.top_padding + view.layout.bottom_padding
-        else
-          size = view.frameSize.width
-          expand = view.layout.expand_width?
-          padding = view.layout.left_padding + view.layout.right_padding
-        end
-
-        if expand
-          expandable_views += 1
-        else
-          expandable_size -= size
-          expandable_size -= @spacing
-        end
-
-        expandable_size -= padding
-      end
-
-      expandable_size /= expandable_views
-      expandable_size
-    end
-
+    ##
+    # @todo This method could be optimized quite a bit, I think.
+    #
+    # Figure out how to layout all the subviews. This is the meat of the
+    # class.
     def relayout!
-      view_size = frameSize
-      end_dimension = vertical? ? view_size.height : view_size.width
+      view_size      = frameSize
+      end_dimension  = vertical? ? view_size.height : view_size.width
       end_dimension -= (@margin * 2)
-      dimension = @margin
+      dimension      = @margin
 
       expandable_size = calc_expandable_size(end_dimension)
 
       subviews.each do |view|
-        next unless can_layout?(view)
+        next unless can_layout? view
 
         options = view.layout
         subview_size = view.frameSize
@@ -386,27 +389,27 @@ module HotCocoa
         subview_dimension = vertical? ? subview_size.height : subview_size.width
 
         if vertical?
-          primary_dimension = 'height'
-          secondary_dimension = 'width'
-          primary_axis = 'x'
-          secondary_axis = 'y'
-          expand_primary = 'expand_height?'
-          expand_secondary = 'expand_width?'
-          padding_first = 'left_padding'
-          padding_second = 'right_padding'
-          padding_third = 'bottom_padding'
-          padding_fourth = 'top_padding'
+          primary_dimension   = HEIGHT
+          secondary_dimension = WIDTH
+          primary_axis        = X
+          secondary_axis      = Y
+          expand_primary      = EXPAND_HEIGHT
+          expand_secondary    = EXPAND_WIDTH
+          padding_first       = LEFT_PADDING
+          padding_second      = RIGHT_PADDING
+          padding_third       = BOTTOM_PADDING
+          padding_fourth      = TOP_PADDING
         else
-          primary_dimension = 'width'
-          secondary_dimension = 'height'
-          primary_axis = 'y'
-          secondary_axis = 'x'
-          expand_primary = 'expand_width?'
-          expand_secondary = 'expand_height?'
-          padding_first = 'top_padding'
-          padding_second = 'bottom_padding'
-          padding_third = 'left_padding'
-          padding_fourth = 'right_padding'
+          primary_dimension   = WIDTH
+          secondary_dimension = HEIGHT
+          primary_axis        = Y
+          secondary_axis      = X
+          expand_primary      = EXPAND_WIDTH
+          expand_secondary    = EXPAND_HEIGHT
+          padding_first       = TOP_PADDING
+          padding_second      = BOTTOM_PADDING
+          padding_third       = LEFT_PADDING
+          padding_fourth      = RIGHT_PADDING
         end
 
         view_frame.origin.send("#{primary_axis}=", @margin)
@@ -419,14 +422,13 @@ module HotCocoa
 
         if options.send(expand_secondary)
           view_frame.size.send("#{secondary_dimension}=",
-                  view_size.send("#{secondary_dimension}") - (2 * @margin) -
+                  view_size.send(secondary_dimension) - (2 * @margin) -
                                     options.send(padding_first) - options.send(padding_second))
         else
 
           case options.align
           when :left, :bottom
             # Nothing to do
-
           when :center
             view_frame.origin.send("#{primary_axis}=", (view_size.send(secondary_dimension) / 2.0) - (subview_size.send(secondary_dimension) / 2.0))
 
@@ -456,8 +458,72 @@ module HotCocoa
       end
     end
 
+
+    private
+
+    # @private
+    HEIGHT         = 'height'
+    # @private
+    WIDTH          = 'width'
+    # @private
+    X              = 'x'
+    # @private
+    Y              = 'y'
+    # @private
+    EXPAND_HEIGHT  = 'expand_height?'
+    # @private
+    EXPAND_WIDTH   = 'expand_width?'
+    # @private
+    LEFT_PADDING   = 'left_padding'
+    # @private
+    RIGHT_PADDING  = 'right_padding'
+    # @private
+    BOTTOM_PADDING = 'bottom_padding'
+    # @private
+    TOP_PADDING    = 'top_padding'
+
+    ##
+    # Calculate the maximum size that a subview can take up in the layout.
+    def calc_expandable_size end_dimension
+      expandable_size  = end_dimension
+      expandable_views = 0
+
+      subviews.each do |view|
+        next unless can_layout? view
+
+        if vertical?
+          size    = view.frameSize.height
+          expand  = view.layout.expand_height?
+          padding = view.layout.top_padding + view.layout.bottom_padding
+        else
+          size    = view.frameSize.width
+          expand  = view.layout.expand_width?
+          padding = view.layout.left_padding + view.layout.right_padding
+        end
+
+        if expand
+          expandable_views += 1
+        else
+          expandable_size  -= size
+          expandable_size  -= @spacing
+        end
+
+        expandable_size -= padding
+      end
+
+      expandable_size /= expandable_views
+      expandable_size
+    end
+
+    ##
+    # @note NSView defines `#layout` in Lion for AutoLayout, and so this
+    #       will almost always return true on Lion, even if it should
+    #       not. THIS IS A BUG.
+    #
+    # Whether or not the view can be used
     def can_layout? view
       view.respond_to?(:layout) && !view.layout.nil?
     end
+
   end
 end

data/lib/hotcocoa/version.rb

@@ -1,3 +1,3 @@
 module HotCocoa
-  VERSION = '0.6.0'
+  VERSION = '0.6.1'
 end

data/template/__APPLICATION_NAME__.appspec

@@ -12,6 +12,13 @@ Application::Specification.new do |s|
   s.resources  = Dir.glob('resources/**/*.*')
   s.sources    = Dir.glob('lib/**/*.rb')
 
+  # BridgeSupport is required if you need to run your app under OS X 10.6 (Snow Leopard)
+  # set this option to false if you do not wish to embed the BridgeSupport files during deployment
+  # (i.e. you are targeting Lion only)
+  # Information about BridgeSupport: http://www.macruby.org/documentation/tutorial.html
+  # Latest Preview of BridgeSupport: http://www.macruby.org/files/BridgeSupport%20Preview%203.zip
+  s.embed_bridgesupport = true
+
   # optional copyright
   # s.copyright = "2011, Your Company"
 
@@ -27,10 +34,6 @@ Application::Specification.new do |s|
   # hotcocoa is automatically bundled and doesn't need to be specified here
   # s.gems     = ['rest-client']
 
-  # uncomment if you wish to embed the BridgeSupport files during deployment
-  # useful if you need to deploy the app to OS X 10.6.
-  # s.embed_bs = true
-
   # uncomment to always make a clean build of the app
   # s.overwrite = true