hotcocoa 0.6.0 → 0.6.1

data/.yardopts

@@ -6,9 +6,10 @@
 --readme README.markdown
 lib/**/*.rb
 -
-History.txt
+History.markdown
+docs/Tutorial.markdown
 docs/Contributors.markdown
+docs/Mappings.markdown
 docs/Overview.markdown
 docs/Resources.markdown
-docs/Tutorial.markdown
-docs/Mappings.markdown
+docs/Troubleshooting.markdown

data/History.markdown

@@ -0,0 +1,45 @@
+# Release History
+
+## 0.6.1 2011-12-4
+
+* Enhancements:
+  * Bridgesupport embedding now enabled by default for new projects
+  * Ensure that the short version is set in an app bundles Info.plist
+  * Begin overhauling the documentation
+  * Better error handling for the DelegateBuilder
+  * Document and refactor layout manager internals
+
+* Fixes:
+  * Fixed some UI glitches with the Demo app
+  * The application builder now sets the copyright string in an app bundles Info.plist
+  * DelegateBuilder no longer crashes when parameters were given as Symbols
+
+## 0.6.0 2011-10-14
+
+* 10 enhancements:
+  + New application builder to work with MacRuby 0.11
+  + Old application builder is deprecated
+  + New application templates now use an appspec, similar to a gemspec
+  + config.yml is now deprecated
+  + Lazier loading for mappings (may break custom mappings!)
+  + API documention (~67% coverage so far)
+  + Regression tests (< 67% coverage so far)
+  + Updating and porting of the tutorial documentation (~40% complete)
+  + HotCocoa now works when compiled (HotCocoa will boot ~2.5 faster)
+  + HotCocoa is now leaner
+  + Various bug fixes
+
+* 4 new mappings:
+  + bonjour_service => NSNetService
+  + bonjour_browser => NSNetServiceBrowser
+  + line           => NSBezierPath
+  + tracking_area  => NSTrackingArea
+
+* 2 graphics improvements:
+  + Image class works with more image types
+  + Image class can save images
+
+## 0.0.1 2009-11-07
+
+* 1 major enhancement:
+  + Initial release

data/README.markdown

@@ -1,63 +1,63 @@
-# hotcocoa
-
-* [http://github.com/ferrous26/hotcocoa](http://github.com/ferrous26/hotcocoa)
-* [Documentation](http://rdoc.info/github/ferrous26/hotcocoa/master/frames)
-
-## Description
+# HotCocoa
 
 HotCocoa is a thin, idiomatic Ruby layer that sits above Cocoa and
 other frameworks. The goal of the project is to simplify the process of creating
-and configuring Cocoa objects used when building native Mac apps. To get more
-information on HotCocoa (including tutorials) see
-[http://macruby.org](http://macruby.org).
-
-## Note
-
-HotCocoa has ambitious goals that are difficult to accomplish with the input of
-only a few people. Feedback is the easiest way to contribute and goes a long way
-to making sure HotCocoa is on the right path to accomplishing those goals.
-
-There are still some APIs that need documentation, regression tests that need to
-be written, and tutorials to be updated; but new features and improved performance
-will also be coming in the not too distant future. If you find issues with
-HotCocoa, don't hesitate to open tickets on Github (or try to fix it yourself and
-send in the patch :)).
+and configuring Cocoa objects used when building native Mac apps.
 
-There are a list of
-[gotchas](https://github.com/ferrous26/hotcocoa/wiki/Gotchas) in the
-wiki.
+## Using
 
-## Install
+### Installation
 
 From rubygems:
 
-    sudo macgem install hotcocoa --pre
+    $ sudo macgem install hotcocoa
+
+Or to get the bleeding edge, you can clone the repository on Github and install from there:
 
-You need to add the `--pre` flag since HotCocoa 0.6 is not officially released yet.
-Or you can clone the repository on Github and install from there:
+    $ git clone git://github.com/ferrous26/hotcocoa
+    $ cd hotcocoa
+    $ sudo macrake install
 
-    git clone git://github.com/ferrous26/hotcocoa
-    cd hotcocoa
-    sudo macrake install
+__Note__: You will need the Mac OS X developer tools in order
+to build apps. Xcode is not required, but the compiler toolchain is
+needed.
 
-__Note__: If you are on Snow Leopard, you will also need the
+__Note 2__: If you are on Snow Leopard, you will also need the
 [Bridge Support Preview](http://www.macruby.org/files/BridgeSupport%20Preview%203.zip)
 in order to run HotCocoa. Read about it on the
 [MacRuby Blog](http://www.macruby.org/blog/2010/10/08/bridgesupport-preview.html).
 
-__Note 2__: You will also need the Mac OS X developer tools in order
-to build apps. Xcode is not required, but the compiler toolchain is
-needed.
+### Documentation
+
+The documentation can be found on [rdoc.info](http://rdoc.info/github/ferrous26/hotcocoa/master/frames).
+
+The most important pages are:
+
+* [the overview](http://rubydoc.info/github/ferrous26/hotcocoa/master/file/docs/Overview.markdown)
+* [a guide to the mappings](http://rubydoc.info/github/ferrous26/hotcocoa/master/file/docs/Mappings.markdown)
+* [troubleshooting](http://rubydoc.info/github/ferrous26/hotcocoa/master/file/docs/Troubleshooting.markdown)
+
+The documentation currently does not cover the shipped mappings right now due to the
+way that mappings are implemented; a YARD plug-in or new YARD features
+will be needed (stay tuned).
+
+### Examples
+
+Have a look in the [examples folder](https://github.com/ferrous26/hotcocoa/tree/master/examples) to see some sample apps which use HotCocoa.
 
-## Documentation
+## Contributing
 
-Documentation is a work in progress; some of the documentation is
-being ported from the MacRuby website and you can still view it there.
+HotCocoa has ambitious goals that are difficult to accomplish with the input of
+only a few people. Feedback is the easiest way to contribute and goes a long way
+to making sure HotCocoa is on the right path to accomplishing those goals.
 
-The documentation currently does not include the mappings right now due to the
-way that mappings are implemented; a YARD plug-in will be needed for thatv
+There are still some APIs that need documentation, regression tests that need to
+be written, and tutorials to be updated; but new features and improved performance
+will also be coming in the not too distant future. If you find issues with
+HotCocoa, don't hesitate to open tickets on Github (or try to fix it yourself and
+send in the patch :)).
 
-## Contributing to HotCocoa
+### Submitting patches
 
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it

data/docs/HeatingUpWithHotCocoa-part1.markdown

@@ -0,0 +1,189 @@
+Originally written by Dan Sinclair, this tutorial has been updated for
+newer HotCocoa features.
+
+I've had my eye on giving HotCocoa a test run for a while now. Other
+things have conspired to come up over the last few months so I haven't
+had a chance to give it a spin. That is, until now. I started poking
+at it the other day, a few things still confuse me, but I'm getting
+there.
+
+I figured I'd write stuff down as I plow my way through the code and
+create a simple little application. The application is nothing fancy,
+I'm going to query [PostRank](http://www.postrank.com) and pull back
+engagement information on a feed entered into a text box. This will be
+a multi-part tutorial.
+
+In the usual fashion, let's start at the start. What is HotCocoa?
+Well, HotCocoa is a layer of Ruby code that sits on top of the Mac OS
+X frameworks including
+[Cocoa](http://developer.apple.com/cocoa/). HotCocoa is part of the
+[MacRuby](http://www.macruby.org) distribution which will ship with
+figure versions of OS X. MacRuby is a port of Ruby 1.9 to run on top
+of Objective-C.
+
+I'm going to assume you have MacRuby installed for this tutorial.
+
+The HotCocoa developers make life easy to get started developing your
+application. There is a `hotcocoa` command that is installed when you
+install MacRuby. This will create the basic application structure and
+Rakefile to get you up and running.
+
+    titania:Development dj2$ hotcocoa Postie
+
+We can then execute our application by changing into the `Postie`
+directory and executing `macrake`. *Note*, this uses `mac`rake and not
+regular rake. MacRuby installs alongside the normal Ruby runtime on OS
+X. You'll need to make sure you use `macrake`, `macirb`, `macgem` and
+`macruby` to work with the MacRuby versions.  You should see a `Hello
+from HotCooca` window if everything worked correctly.
+
+![Hello from HotCocoa](images/hello_from_hotcocoa.png)
+
+You'll notice that you now have a Postie.app in your root
+directory. This application can be executed by double clicking like
+any other Mac application, although, you'll need MacRuby installed for
+it to execute. You can also execute `macruby lib/application.rb` to
+execute the application. This allows passing flags to `macruby` for
+things like enabling debug mode.
+
+Let's take a quick look at the files generated by the `hotcocoa`
+command.
+
+```sh
+./Rakefile
+./config/build.yml
+./resources/HotCocoa.icns
+./lib/application.rb
+./lib/menu.rb
+```
+
+The `build.yml` file contains information used by `hotcocoa` to build
+your application. This includes things like the name, version, icon
+and source files. The icon, by default, is `HotCocoa.icns`. The main
+files we're interested in are `application.rb` and `menu.rb`.
+
+```ruby
+module HotCocoa
+  def application_menu
+    menu do |main|
+      main.submenu :apple do |apple|
+        apple.item :about, :title => "About #{NSApp.name}"
+        apple.separator
+        apple.item :preferences, :key => ","
+        apple.separator
+        apple.submenu :services
+        apple.separator
+        apple.item :hide, :title => "Hide #{NSApp.name}", :key => "h"
+        apple.item :hide_others, :title => "Hide Others", :key => "h", :modifiers => [:command, :alt]
+        apple.item :show_all, :title => "Show All"
+        apple.separator
+        apple.item :quit, :title => "Quit #{NSApp.name}", :key => "q"
+      end
+      main.submenu :file do |file|
+        file.item :new, :key => "n"
+        file.item :open, :key => "o"
+      end
+      main.submenu :window do |win|
+        win.item :minimize, :key => "m"
+        win.item :zoom
+        win.separator
+        win.item :bring_all_to_front, :title => "Bring All to Front", :key => "o"
+      end
+      main.submenu :help do |help|
+        help.item :help, :title => "#{NSApp.name} Help"
+      end
+    end
+  end
+end
+```
+
+The `menu.rb` file contains information about the menu for our
+applcation. This includes the menu names, hot keys, modifiers and
+general layout.
+
+The `:apple` submenu is special and will appear with a menu title
+based on your application name, as is typical for OS X
+applications. For the other submenus, by default, the menu title will
+be the capitalized version of the symbol name converted to a
+string. You can also provide a `:title => 'foo'` option to specify a
+different name. `menu.submenu :postrank, :title => 'PostRank'`.
+
+The symbol provided to each submenu `item`, e.g. `file.item :new` will
+be used to form the name of the method invoked in your application
+delegate. The methods are named `on_<key>`. For our `:new` item the
+`on_new` menu item will be invoked. If there is no `on_<key>` method
+the menu item will be disabled. As you can see above you can also
+specify `:modifiers` and `:key` equivalents for your items.
+
+As with the menu titles, the items names will be formed from
+capitalizing the symbol provided unless a `:title` is provided.
+
+In the case of `Postie` I've erased everything but the `:apple`
+submenu for now. I don't need any extra menu items at the moment. This
+also means all of the `on_*` methods can be removed from
+`application.rb`.
+
+The default `application.rb` provided by the `hotcocoa` command is
+pretty short.
+
+```ruby
+require 'hotcocoa'
+
+class Application
+  include HotCocoa
+
+  def start
+    application(:name => "Postie") do |app|
+      app.delegate = self
+      window(:frame => [100, 100, 500, 500], :title => "Postie") do |win|
+        win << label(:text => "Hello from HotCocoa", :layout => {:start => false})
+        win.will_close { exit }
+      end
+    end
+  end
+end
+
+Application.new.start
+```
+
+Let's take a quick look and see if we can figure out what's going
+on. We need to `require hotcocoa'` to get access to the needed
+HotCocoa classes. We then `include HotCocoa` into our `Application`
+class to make everything shorter. Feel free to rename `Application`
+just do it in the class definition and at the bottom of the file.
+
+Jumping to the bottom, you can see we're calling
+`Application.new.start` so the  `Application#start` method will be
+invoked. It's worth noting, the application will not return from
+`Application#start`.
+
+Going back to `Application#start` we call `application` to create our
+application, setting the title as desired. We then set ourselves as
+the application delegate. This means that our class will receive all
+of the callbacks that are called on the Cocoa application. This
+includes the menu `on_*`callbacks we talked about earlier.
+
+We then proceed to create a `window`. We're setting a `:frame` on the
+window to position it at X 100, Y 100 (from the bottom left) with a
+width of 500 and height of 500. We `:title` the window as `Postie`.
+If you don't want to specify the entire frame of the window you can
+specify just the `:size => [500, 500]` of the window. You can also
+specify `:center => true` to center the window on the desktop. If you
+look at the Objective-C documentation for NSWindow the options
+available in Obj-C are available in the HotCocoa layer.
+
+Once the window is created we add a `label` to the window and set the
+`will_close` handler to `exit` when executed.
+
+The `will_close` callback is the HotCocoa name for the Cocoa
+`windowWillClose:`. Many of the Cocoa callbacks have been remapped to
+make the names more Ruby like.  You can view all the HotCocoa mappings
+for windows at the bottom of the
+[NSWindow mapping file](https://github.com/ferrous26/hotcocoa/blob/master/lib/hotcocoa/mappings/appkit/window.rb).
+
+That's it for part I. We've now setup with our basic application
+structure and have an idea of what we're working with. In the next
+installment, we'll work on getting our application views setup as we
+want.
+
+[Read the next article: “Application Layout”](https://github.com/ferrous26/hotcocoa/wiki/Application-Layout)

data/docs/Mappings.markdown

@@ -1,4 +1,4 @@
-## Introduction
+## Introduction to HotCocoa's Mappings
 
 A HotCocoa mapping defines a structure that sits on top of a
 particular Objective-C class and simplifies its usage in MacRuby.

data/docs/Resources.markdown

@@ -4,12 +4,18 @@ This page is an informal index to HotCocoa resources.
 
 ## Articles
 
-* Isaac Kearse
+* Gary Weaver (articles from Feb, Mar 2010)
+ + [HotCocoa App to track Time on Tasks](http://stufftohelpyouout.blogspot.com/2010/02/hotcocoa-app-to-track-time-on-tasks.html)
+ + [Create a Custom Icon for Your HotCocoa App](http://stufftohelpyouout.blogspot.com/2010/02/create-custom-icon-of-your-hotcocoa-app.html)
+ + [Create a MacRuby HotCocoa App](http://stufftohelpyouout.blogspot.com/2010/02/create-macruby-hotcocoa-app.html)
+ + [HotCocoa/MacRuby Links](http://stufftohelpyouout.blogspot.com/2010/03/hotcocoamacruby-links.html)
+
+* [Isaac Kearse](https://github.com/isaac) (articles from Jan, Feb 2010)
  + [Stopwatch - A HotCocoa Status Bar Timer](http://isaac.kearse.co.nz/2010/01/31/stopwatch/)
  + [Packaging A HotCocoa Application](http://isaac.kearse.co.nz/2010/02/01/packaging-hotcocoa/)
  + [SafariRSS - HotCocoa Safari RSS Handler](http://isaac.kearse.co.nz/2010/02/07/safarirss/)
 
-* Dan Sinclair
+* [Dan Sinclair](https://github.com/dj2) (articles from May, June 2009)
  + [Heating up with HotCocoa Part I](http://everburning.com/news/heating-up-with-hotcocoa-part-i/)
  + [Heating up with HotCocoa Part II](http://everburning.com/news/heating-up-with-hotcocoa-part-ii/)
  + [Heating up with HotCocoa Part III](http://everburning.com/news/heating-up-with-hotcocoa-part-iii/)
@@ -17,9 +23,3 @@ This page is an informal index to HotCocoa resources.
  + [Download and XML parsing with HotCocoa](http://everburning.com/news/download-and-xml-parsing-with-hotcocoa/)
  + [Toolbars with HotCocoa](http://everburning.com/news/toolbars-with-hotcocoa/)
  + [HotCocoa and Core Data](http://everburning.com/news/hotcocoa-and-core-data/)
-
-* Gary Weaver
- + [HotCocoa App to track Time on Tasks](http://stufftohelpyouout.blogspot.com/2010/02/hotcocoa-app-to-track-time-on-tasks.html)
- + [Create a Custom Icon for Your HotCocoa App](http://stufftohelpyouout.blogspot.com/2010/02/create-custom-icon-of-your-hotcocoa-app.html)
- + [Create a MacRuby HotCocoa App](http://stufftohelpyouout.blogspot.com/2010/02/create-macruby-hotcocoa-app.html)
- + [HotCocoa/MacRuby Links](http://stufftohelpyouout.blogspot.com/2010/03/hotcocoamacruby-links.html)

data/docs/Troubleshooting.markdown

@@ -0,0 +1,15 @@
+#Troubleshooting
+
+## App crashes upon start up
+
+If the app crashes with the following error:
+
+    LSOpenURLsWithRole() failed with error -10810 for the file ...
+
+This is a very general error and can be caused by a number of things. Known root causes are:
+
+1. Missing [bridge support](http://macruby.org/blog/2010/10/08/bridgesupport-preview.html) files (for Snow Leopard users)
+2. Bug in the app you are launching
+3. Bug in HotCocoa
+
+Sometimes debug information will be available in the Console (/Applications/Utilities/Console.app), so you should check in there first. Failing that, you will need to rely on your general debugging skills to find the reason.

data/docs/Tutorial.markdown

@@ -1,3 +1,3 @@
 # HotCocoa Tutorial
 
-This still needs to be ported from the wiki on Github.
+Coming soon!

data/lib/hotcocoa/application/builder.rb

@@ -83,7 +83,7 @@ module Application
     def deploy_options
       options = []
       spec.gems.each { |g| options << "--gem #{g}" }
-      options << '--bs'        if spec.embed_bs?
+      options << '--bs'        if spec.embed_bridgesupport?
       options << '--compile'   if spec.compile?
       options << '--no-stdlib' unless spec.stdlib
       if spec.stdlib.respond_to? :each
@@ -187,6 +187,8 @@ module Application
       }
       info[:CFBundleIconFile] = File.basename(spec.icon) if spec.icon_exists?
       info[:CFBundleDocumentTypes] = spec.doc_types.map(&:info_plist_representation) unless spec.doc_types.empty?
+      info[:CFBundleShortVersionString] = spec.short_version unless spec.short_version.nil?
+      info[:NSHumanReadableCopyright] = spec.copyright unless spec.copyright.nil?
       info.merge! spec.plist # should always be done last
       info.to_plist
     end

data/lib/hotcocoa/application/specification.rb

@@ -260,8 +260,9 @@ module Application
     # OS X 10.6.
     #
     # @return [Boolean]
-    attr_accessor :embed_bs
-    alias_method :embed_bs?, :embed_bs
+    attr_accessor :embed_bridgesupport
+    alias_method :embed_bridgesupport?, :embed_bridgesupport
+    alias_method :embed_bs=, :embed_bridgesupport=
 
     ##
     # Whether or not to always make a clean build of the app.
@@ -324,7 +325,7 @@ module Application
         agent:       false,
         compile:     true,
         overwrite:   false,
-        embed_bs:    false
+        embed_bridgesupport: true
       }
     end