hotcocoa 0.5.1 → 0.6.0pre

data/lib/hotcocoa/mapping_methods.rb

@@ -1,40 +1,110 @@
-module HotCocoa
-  
-  module MappingMethods
-    
-    def defaults(defaults=nil)
-      if defaults
-        @defaults = defaults
-      else
-        @defaults
-      end
+# -*- coding: utf-8 -*-
+
+##
+# The set of methods that are available when creating a mapping.
+module HotCocoa::MappingMethods
+
+  ##
+  # You can provide a hash of default options in the definition of
+  # your mapping. This is very useful for many Cocoa classes, because
+  # there are so many options to set at initialization.
+  #
+  # Details about how defaults are used can be found in the
+  # {file:docs/Mappings.markdown Mappings} tutorial.
+  #
+  # @overload defaults
+  #   Get the hash of defaults
+  #   @return [Hash,nil]
+  #
+  # @overload defaults key1: value1, key2: value2, ...
+  #   Set the hash of defaults
+  #   @param [Hash]
+  #   @return [Hash]
+  def defaults defaults = nil
+    if defaults
+      @defaults = defaults
+    else
+      @defaults
     end
-    
-    def constant(name, constants)
-      constants_map[name] = constants
-    end
-    
-    def constants_map
-      @constants_map ||= {}
-    end
-    
-    def custom_methods(&block)
-      if block
-        @custom_methods = Module.new
-        @custom_methods.module_eval(&block)
-      else
-        @custom_methods
-      end
-    end
-    
-    def delegating(name, options)
-      delegate_map[name] = options
-    end
-    
-    def delegate_map
-      @delegate_map ||= {}
+  end
+
+  ##
+  # Create a mapping of a constant type to an enumeration of constants.
+  #
+  # A constant mapping allows the use of short symbol names to be used
+  # in place of long constant names in the scope of the wrapped class.
+  #
+  # Details about using this method are in the
+  # {file:docs/Mappings.markdown} tutorial.
+  #
+  # @param [Symbol] name
+  # @param [Hash{Symbol=>Constant}] constants
+  def constant name, constants
+    constants_map[name] = constants
+  end
+
+  ##
+  # A mapping of constant mappings that were created with calls to
+  # {#constant}
+  #
+  # @return [Hash{Symbol=>Hash{Symbol=>Constant}}]
+  attr_reader :constants_map
+
+  ##
+  # Custom methods are modules that are mixed into the class being
+  # mapped; they provide idiomatic Ruby methods for the mapped
+  # Objective-C class instances.
+  #
+  # Custom methods are meant to be used in conjunction with constant
+  # mappings or when the custom method provides something much better
+  # than what is offered by plain Cocoa. Examples are available in the
+  # {file:docs/Mappings.markdown} tutorial.
+  #
+  # @yield A block that will be evaluated in the context of a new module
+  #
+  # @overload custom_methods do ... end
+  #   Create and cache a new module to mix into the mapped class
+  #   @return [Module] return the module that caches the custom methods
+  #
+  # @overload custom_methods
+  #   @return [Module,nil] return the Module if it exists, otherwise nil
+  def custom_methods &block
+    if block
+      @custom_methods = Module.new &block
+    else
+      @custom_methods
     end
-    
   end
-  
-end
+
+  ##
+  # Delegation is a pattern that is used pervasively in Cocoa to
+  # facilitate customization of controls; it is a powerful tool, but
+  # is a little more complex to setup than custom methods.
+  #
+  # You should read the {file:docs/Mappings.markdown Mappings} tutorial
+  # to get an in depth understanding on how to setup delegates in
+  # HotCocoa.
+  #
+  # @param [String,Symbol] name
+  # @param [Hash{:to=>:ruby_name, :parameters=>Array<String>}] options
+  #   the `:to` key must be included, but `:parameters` is optional
+  def delegating name, options
+    delegate_map[name] = options
+  end
+
+  ##
+  # A mapping of delegate mappings that were created with calls to
+  # {#delegating}
+  #
+  # @return [Hash{Symbol=>Hash{Symbol=>SEL}}]
+  attr_reader :delegate_map
+
+  ##
+  # A small hack so that we can have {#delegate_map} and {#constants} as
+  # attributes instead of methods that memoize instance variables.
+  def self.extended klass
+    klass.instance_variable_set :@constants_map, {}
+    klass.instance_variable_set :@delegate_map,  {}
+  end
+
+end

data/lib/hotcocoa/mappings/appkit/alert.rb

@@ -0,0 +1,25 @@
+##
+# @note Alerts are shown immediately
+HotCocoa::Mappings.map alert: NSAlert do
+
+  defaults default: 'OK', alternate: nil, other: nil, info: '', show: true
+
+  def alloc_with_options options
+    if options[:message]
+      alert = NSAlert.alertWithMessageText options.delete(:message),
+                            defaultButton: options.delete(:default),
+                          alternateButton: options.delete(:alternate),
+                              otherButton: options.delete(:other),
+                informativeTextWithFormat: options.delete(:info)
+    end
+  end
+
+  custom_methods do
+    def show
+      runModal
+    end
+  end
+
+  delegating 'alertShowHelp:', to: :show_help?
+
+end

data/lib/hotcocoa/mappings/appkit/application.rb

@@ -0,0 +1,112 @@
+HotCocoa::Mappings.map application: NSApplication do
+
+  def alloc_with_options opts
+    NSApplication.sharedApplication
+  end
+
+  def handle_block app
+    app.load_application_menu
+    yield app
+    app.run
+  end
+
+  custom_methods do
+    # @todo Should we really be hardcoded to require lib/menu and should
+    #       it done here?
+    def load_application_menu
+      require 'lib/menu' # hmmm...
+
+      obj = Object.new
+      obj.extend HotCocoa
+
+      setMainMenu obj.application_menu
+    rescue LoadError => e
+    end
+
+    attr_accessor :name
+
+# @todo What is this about?
+=begin
+    def menu(path=nil)
+      if path
+        find_menu(mainMenu, path)
+      else
+        mainMenu
+      end
+    end
+=end
+
+    def menu
+      mainMenu
+    end
+
+    def menu= menu
+      setMainMenu menu
+    end
+
+    def on_hide menu
+      hide menu
+    end
+
+    def on_about menu
+      orderFrontStandardAboutPanel menu
+    end
+
+    def on_hide_others menu
+      hideOtherApplications menu
+    end
+
+    def on_show_all menu
+      unhideAllApplications menu
+    end
+
+    def on_quit menu
+      terminate menu
+    end
+
+
+    private
+
+    def find_menu menu, path
+      key = path.keys.first
+      value = path.values.first
+      menu = menu[key]
+
+      if value.kind_of? Array
+        find_menu menu, value.first
+      else
+        menu[value]
+      end
+    end
+  end
+
+  delegating 'application:delegateHandlesKey:',                       to: :delegate_handles_key?,             parameters: [:delegateHandlesKey]
+  delegating 'application:openFile:',                                 to: :open_file,                         parameters: [:openFile]
+  delegating 'application:openFiles:',                                to: :open_files,                        parameters: [:openFiles]
+  delegating 'application:openFileWithoutUI:',                        to: :open_file_without_ui,              parameters: [:openFileWithoutUI]
+  delegating 'application:openTempFile:',                             to: :open_temp_file,                    parameters: [:openTempFile]
+  delegating 'application:printFile:',                                to: :print_file
+  delegating 'application:printFiles:withSettings:showPrintPanels:',  to: :print_files
+  delegating 'application:willPresentError:',                         to: :will_present_error
+  delegating 'applicationDidBecomeActive:',                           to: :did_become_active
+  delegating 'applicationDidChangeScreenParameters:',                 to: :did_change_screen_parameters
+  delegating 'applicationDidFinishLaunching:',                        to: :did_finish_launching
+  delegating 'applicationDidHide:',                                   to: :did_hide
+  delegating 'applicationDidResignActive:',                           to: :resign_active
+  delegating 'applicationDidUnhide:',                                 to: :did_unhide
+  delegating 'applicationDidUpdate:',                                 to: :did_update
+  delegating 'applicationDockMenu:',                                  to: :dock_menu
+  delegating 'applicationOpenUntitledFile:',                          to: :open_untitled_file
+  delegating 'applicationShouldHandleReopen:hasVisibleWindows:',      to: :should_handle_reopen?,             parameters: [:hasVisibleWindows]
+  delegating 'applicationShouldOpenUntitledFile:',                    to: :should_open_untitled_file?
+  delegating 'applicationShouldTerminate:',                           to: :should_terminate?
+  delegating 'applicationShouldTerminateAfterLastWindowClosed:',      to: :should_terminate_after_last_window_closed?
+  delegating 'applicationWillBecomeActive:',                          to: :will_become_active
+  delegating 'applicationWillFinishLaunching:',                       to: :will_finish_launching
+  delegating 'applicationWillHide:',                                  to: :will_hide
+  delegating 'applicationWillResignActive:',                          to: :will_resign_active
+  delegating 'applicationWillTerminate:',                             to: :will_terminate
+  delegating 'applicationWillUnhide:',                                to: :will_unhide
+  delegating 'applicationWillUpdate:',                                to: :will_update
+
+end

data/lib/hotcocoa/mappings/{array_controller.rb → appkit/array_controller.rb}

@@ -1,77 +1,75 @@
-HotCocoa::Mappings.map :array_controller => :NSArrayController do
+HotCocoa::Mappings.map array_controller: NSArrayController do
 
-  def init_with_options(array_controller, options)
+  def init_with_options array_controller, options
     result = array_controller.init
-    if options.has_key?(:for)
-      result.addObjects(options.delete(:for))
+    if options.has_key? :for
+      result.addObjects(options.delete :for)
     end
     result
   end
 
   custom_methods do
-    
     def avoids_empty_selection?
       avoidsEmptySelection
     end
-    
+
     def preserves_selection?
       preservesSelection
     end
-    
-    def rearrange_automatically=(value)
-      setAutomaticallyRearrangesObjects(value)
+
+    def rearrange_automatically= value
+      setAutomaticallyRearrangesObjects value
     end
-    
+
     def rearrange_automatically?
       automaticallyRearrangesObjects
     end
-    
-    def selects_inserted=(value)
-      setSelectsInsertedObjects(value)
+
+    def selects_inserted= value
+      setSelectsInsertedObjects value
     end
-    
+
     def selects_inserted?
       selectsInsertedObjects
     end
-    
-    def <<(object)
-      addObject(object)
+
+    def << object
+      addObject object
     end
-    
-    def [](index)
+
+    def [] index
       arrangedObjects[index]
     end
-    
-    def each(&block)
-      arrangedObjects.each(&block)
+
+    def each &block
+      arrangedObjects.each &block
     end
-    
+
     def selected
       selectedObjects.first
     end
-    
-    def sort_by=(sort_descriptors)
-      sort_descriptors = [sort_descriptors] if sort_descriptors.kind_of?(Hash)
+
+    def sort_by= sort_descriptors
+      sort_descriptors = [sort_descriptors] if sort_descriptors.kind_of? Hash
       descriptors = sort_descriptors.collect do |descriptor|
-        selector = descriptor.delete(:selector)
+        selector = descriptor.delete :selector
         ascending = (descriptor.values.first == :ascending)
         if selector
-          NSSortDescriptor.alloc.initWithKey(descriptor.keys.first.to_s, ascending: ascending, selector: selector)
+          NSSortDescriptor.alloc.initWithKey(descriptor.keys.first.to_s, ascending:ascending, selector:selector)
         else
-          NSSortDescriptor.alloc.initWithKey(descriptor.keys.first.to_s, ascending: ascending)
+          NSSortDescriptor.alloc.initWithKey(descriptor.keys.first.to_s, ascending:ascending)
         end
       end
-      setSortDescriptors(descriptors)
+      setSortDescriptors descriptors
     end
-    
   end
 
 end
 
 =begin
-array :avoids_empty_selection => true, 
-      :preserves_selection => false, 
-      :selects_inserted => false, 
+array :avoids_empty_selection => true,
+      :preserves_selection => false,
+      :selects_inserted => false,
       :rearrange_automatically => true,
       :sort_by => {:name => :ascending}
 
@@ -84,4 +82,4 @@ array_controller.setAutomaticallyRearrangesObjects(true)
 
 array_controller.setSortDescriptors(NSArray.arrayWithObject(NSSortDescriptor.alloc.initWithKey("name", ascending: false)))
 array_controller.addObject Icon.new("Rich", image(:file => "rich.jpg"))
-=end
+=end

data/lib/hotcocoa/mappings/appkit/box.rb

@@ -0,0 +1,37 @@
+HotCocoa::Mappings.map box: NSBox do
+
+  defaults frame: CGRectZero, layout: {}
+
+  constant :title_position, {
+    none:           NSNoTitle,
+    above_top:      NSAboveTop,
+    top:            NSAtTop,
+    below_top:      NSBelowTop,
+    above_bottom:   NSAboveBottom,
+    bottom:         NSAtBottom,
+    below_bottom:   NSBelowBottom
+  }
+
+  constant :type, {
+    primary:        NSBoxPrimary,
+    secondary:      NSBoxSecondary,
+    separator:      NSBoxSeparator,
+    old:            NSBoxOldStyle,
+    custom:         NSBoxCustom
+  }
+
+  def init_with_options box, options
+    box.initWithFrame options.delete :frame
+  end
+
+  custom_methods do
+    def type= value
+      setBoxType value
+    end
+
+    def border= value
+      setBorderType value
+    end
+  end
+
+end

data/lib/hotcocoa/mappings/appkit/button.rb

@@ -0,0 +1,88 @@
+HotCocoa::Mappings.map button: NSButton do
+
+  defaults bezel:  :rounded,
+           frame:  CGRectZero,
+           layout: {}
+
+  constant :bezel, {
+    rounded:            NSRoundedBezelStyle,
+    regular_square:     NSRegularSquareBezelStyle,
+    thick_square:       NSThickSquareBezelStyle,
+    thicker_square:     NSThickerSquareBezelStyle,
+    disclosure:         NSDisclosureBezelStyle,
+    shadowless_square:  NSShadowlessSquareBezelStyle,
+    circular:           NSCircularBezelStyle,
+    textured_square:    NSTexturedSquareBezelStyle,
+    help_button:        NSHelpButtonBezelStyle,
+    small_square:       NSSmallSquareBezelStyle,
+    textured_rounded:   NSTexturedRoundedBezelStyle,
+    round_rect:         NSRoundRectBezelStyle,
+    recessed:           NSRecessedBezelStyle,
+    rounded_disclosure: NSRoundedDisclosureBezelStyle
+  }
+
+  constant :type, {
+    momentary_light:    NSMomentaryLightButton,
+    push_on_push_off:   NSPushOnPushOffButton,
+    toggle:             NSToggleButton,
+    switch:             NSSwitchButton,
+    radio:              NSRadioButton,
+    momentary_change:   NSMomentaryChangeButton,
+    on_off:             NSOnOffButton,
+    momentary_push_in:  NSMomentaryPushInButton,
+    momentary_push:     NSMomentaryPushButton
+  }
+
+  constant :state, {
+    on:                 NSOnState,
+    off:                NSOffState,
+    mixed:              NSMixedState
+  }
+
+  constant :image_position, {
+    text_only:          NSNoImage,
+    image_only:         NSImageOnly,
+    overlaps:           NSImageOverlaps,
+    left:               NSImageLeft,
+    right:              NSImageRight,
+    below:              NSImageBelow,
+    above:              NSImageAbove
+  }
+
+  def init_with_options button, options
+    button.initWithFrame options.delete :frame
+  end
+
+  custom_methods do
+    def bezel= value
+      setBezelStyle value
+    end
+
+    def type= value
+      setButtonType value
+    end
+
+    def state= value
+      value = case value
+              when :on    then NSOnState
+              when :off   then NSOffState
+              when :mixed then NSMixedState
+              else value
+              end
+      setState value
+    end
+
+    def on?
+      state == NSOnState
+    end
+
+    def off?
+      state == NSOffState
+    end
+
+    def mixed?
+      state == NSMixedState
+    end
+  end
+
+end

data/lib/hotcocoa/mappings/appkit/collection_view.rb

@@ -0,0 +1,42 @@
+HotCocoa::Mappings.map collection_view: NSCollectionView do
+
+  defaults layout: {}, frame: [0,0,100,100]
+
+  def init_with_options collection_view, options
+    collection_view.initWithFrame options.delete :frame
+  end
+
+  custom_methods do
+    def item_prototype
+      itemPrototype
+    end
+
+    def item_view
+      item_prototype if item_prototype.view
+    end
+
+    def item_view= view
+      item = NSCollectionViewItem.alloc.init
+      item.setView view
+      view.collection_item = item if view.respond_to? :collection_item=
+      setItemPrototype item
+    end
+
+    def rows= value
+      setMaxNumberOfRows value
+    end
+
+    def rows
+      maxNumberOfRows
+    end
+
+    def columns= value
+      setMaxNumberOfColumns value
+    end
+
+    def columns
+      maxNumberOfColumns
+    end
+  end
+
+end

data/lib/hotcocoa/mappings/appkit/color.rb

@@ -0,0 +1,40 @@
+##
+# @todo Allow aliasing of mappings (so we can have :coloUr as well)
+#
+# @cocoa NSColor
+#
+HotCocoa::Mappings.map color: NSColor do
+
+  def alloc_with_options options
+    if options.has_key? :name
+      color = NSColor.send "#{options.delete :name}Color"
+      color = color.colorWithAlphaComponent(options.delete :alpha) if options.has_key? :alpha
+      return color
+
+    elsif options.has_key? :rgb
+      calibrated = !options.delete(:device)
+
+      rgb = options.delete :rgb
+      red   = ((rgb >> 16) & 0xff) / 255.0
+      green = ((rgb >> 8) & 0xff) / 255.0
+      blue  = (rgb & 0xff) / 255.0
+      alpha = options.delete(:alpha) || 1.0
+
+      if calibrated
+        return NSColor.colorWithCalibratedRed red, green: green, blue: blue, alpha: alpha
+      else
+        return NSColor.colorWithDeviceRed red, green: green, blue: blue, alpha: alpha
+      end
+
+    elsif (options.keys & [:red, :green, :blue]).size == 3
+      alpha = (options.delete(:alpha) or 1.0)
+      return NSColor.colorWithCalibratedRed options.delete(:red),
+                                     green: options.delete(:green),
+                                      blue: options.delete(:blue),
+                                     alpha: alpha
+    else
+      raise 'Cannot create color with the provided options'
+    end
+  end
+
+end

data/lib/hotcocoa/mappings/appkit/column.rb

@@ -0,0 +1,19 @@
+HotCocoa::Mappings.map  column: NSTableColumn do
+
+  defaults title: 'Column'
+
+  def init_with_options column, options
+    column.initWithIdentifier options.delete :id
+  end
+
+  custom_methods do
+    def title
+      headerCell.stringValue
+    end
+
+    def title= newTitle
+      headerCell.stringValue = newTitle
+    end
+  end
+
+end

data/lib/hotcocoa/mappings/appkit/combo_box.rb

@@ -0,0 +1,22 @@
+HotCocoa::Mappings.map combo_box: NSComboBox do
+
+  defaults selectable: true, editable: true, completes: true, layout: {}
+
+  def init_with_options combo_box, options
+    combo_box.initWithFrame options.delete :frame
+  end
+
+  custom_methods do
+    def data= data_source
+      setUsesDataSource true
+      data_source = HotCocoa::ComboBoxDataSource.new data_source if data_source.kind_of? Array
+      setDataSource data_source
+    end
+  end
+
+  delegating 'comboBoxSelectionDidChange:',   to: :selection_did_change
+  delegating 'comboBoxSelectionIsChanging:',  to: :selection_is_changing
+  delegating 'comboBoxWillDismiss:',          to: :will_dismiss
+  delegating 'comboBoxWillPopUp:',            to: :will_pop_up
+
+end

data/lib/hotcocoa/mappings/appkit/control.rb

@@ -0,0 +1,31 @@
+HotCocoa::Mappings.map control: NSControl do
+
+  constant :alignment, {
+    left:      NSLeftTextAlignment,
+    right:     NSRightTextAlignment,
+    center:    NSCenterTextAlignment,
+    justified: NSJustifiedTextAlignment,
+    natural:   NSNaturalTextAlignment
+  }
+
+  custom_methods do
+    include HotCocoa::Mappings::TargetActionConvenience
+
+    def text= text
+      setStringValue text
+    end
+
+    def to_i
+      intValue
+    end
+
+    def to_f
+      doubleValue
+    end
+
+    def to_s
+      stringValue
+    end
+  end
+
+end