bowline 0.5.3 → 0.5.4

data/lib/bowline/desktop/window_manager.rb

@@ -1,5 +1,24 @@
 module Bowline
   module Desktop
+    # This class provides a useful abstraction on the Window class.
+    # It's the usual way of interfacing with your application's windows, 
+    # and all of Bowline's windows normally inherit from it.
+    # 
+    # You'll need to call the setup method, before calling using this class.
+    # If the window is deallocated (i.e. closed), you'll need to call it again.
+    # It's worth not calling the setup method before you need it, since it'll
+    # increase the amount of CPU your application uses.
+    # 
+    # By default, windows are hidden. You'll need to show your custom windows explicitly 
+    # before any user interaction using the show method. You can still load HTML/JavaScript
+    # while the window is hidden.
+    # 
+    # If you don't want to show the window until it's properly loaded, you can use this pattern:
+    #  MyWindow.on_load { MyWindow.show }
+    #  MyWindow.file = :test
+    #
+    # Any undefined methods are delegated to the Window class.
+    # See that class for the full windowing API.
     class WindowManager
       extend Bridge::ClassMethods
       js_expose
@@ -8,21 +27,24 @@ module Bowline
       watch :on_load
       
       class << self
+        # An array of all the application's windows
         def windows
-          subclasses.map(&:constantize)
+          Bowline::Desktop::WindowManager.subclasses.map(&:constantize)
         end
         
+        # An array of all the application's windows that are currently shown
         def shown_windows
           windows.select(&:shown?)
         end
         
+        # An array of all the application's allocated windows
         def allocated_windows
           windows.select(&:allocated?)
         end
         
         # Methods for subclasses:
         
-        def window
+        def window #:nodoc:
           @window
         end
         
@@ -30,6 +52,9 @@ module Bowline
           !!@window
         end
         
+        # Call this method to allocate a new window.
+        # You'll need to do this before using it, 
+        # or after it has been closed.
         def setup
           return unless Desktop.enabled?
           return if @window && !@window.dealocated?
@@ -39,19 +64,42 @@ module Bowline
             @window = Window.new
           end
         end
-                
+        
+        # Evaluate JavaScript in this window. Pass
+        # a block to capture the result. 
+        # Example:
+        #   eval("Bowline.msgs") {|res| puts res }
         def eval(*args, &block)
           JS.eval(window, *args, &block)
         end
         
+        # Window Proxy instance. Use this to evaluate JavaScript
+        # in this window, but in an object orientated way.
+        # Example:
+        #   page.yourFunc.call
+        # 
+        # See Bowline::Desktop::Proxy for full usage.
         def page
-          Proxy.new(window)
+          Proxy.new(self)
+        end
+        
+        def bowline
+          page.Bowline
         end
         
+        # Returns true if the both the HTML and JavaScript in
+        # this window have loaded. Use the on_load event to know
+        # when this window has loaded.
         def loaded?
           @loaded
         end
         
+        ##
+        # :singleton-method: on_load(method = nil, &block)
+        # A Watcher event method that gets called when this window loads.
+        # Example:
+        #   on_load { puts "Window loaded!" }
+        
         def loaded! # :nodoc:
           @loaded = true
           watcher.call(:on_load)
@@ -59,7 +107,7 @@ module Bowline
         end
         
         # Delegate most methods to Window
-        def method_missing(sym, *args)
+        def method_missing(sym, *args) #:nodoc:
           if window && window.respond_to?(sym)
             return window.send(sym, *args)
           end

data/lib/bowline/desktop/window_methods.rb

@@ -1,6 +1,6 @@
 module Bowline
   module Desktop
-    module WindowMethods
+    module WindowMethods #:nodoc:
       def center(direction = nil)
         direction = 
         case direction
@@ -63,7 +63,7 @@ module Bowline
       # The methods won't exist on window
       # if Bowline::Desktop isn't enabled
       def method_missing(sym, *args)
-        Bowline::Desktop.enabled? ? raise : nil
+        Bowline::Desktop.enabled? ? super : nil
       end
     end
   end

data/lib/bowline/ext/object.rb

@@ -1,5 +1,5 @@
 class Object
-  # Aim is to convert the object in:
+  # Aim is to convert the object into:
   #  * A hash or
   #  * An array of hashes
   def to_js

data/lib/bowline/generators.rb

@@ -2,7 +2,7 @@ gem 'templater', '>= 0.3.2'
 require 'templater'
 
 module Bowline
-  module Generators
+  module Generators #:nodoc: all
     extend Templater::Manifold
     
     desc <<-DESC

data/lib/bowline/generators/binder.rb

@@ -9,7 +9,7 @@ module Bowline::Generators
       super + "Binder < Bowline::Binders::Base"
     end
     
-    def expose_name
+    def bind_name
       plain_class_name.singularize
     end
     

data/lib/bowline/helpers.rb

@@ -1,4 +1,4 @@
 module Bowline
-  module Helpers
+  module Helpers #:nodoc:
   end
 end

data/lib/bowline/initializer.rb

@@ -7,7 +7,7 @@ module Bowline
       @@configuration
     end
 
-    def configuration=(configuration)
+    def configuration=(configuration) #:nodoc:
       @@configuration = configuration
     end
     
@@ -15,10 +15,12 @@ module Bowline
       @initialized || false
     end
 
-    def initialized=(initialized)
+    def initialized=(initialized) #:nodoc:
       @initialized ||= initialized
     end
 
+    # The default Bowline logger. 
+    # Also see the Bowline::Logging class.
     def logger
       if defined?(BOWLINE_LOGGER)
         BOWLINE_LOGGER
@@ -27,12 +29,13 @@ module Bowline
       end
     end
     
+    # The application's root
     def root
       Pathname.new(APP_ROOT) if defined?(APP_ROOT)
     end
   end
   
-  class Initializer
+  class Initializer #:nodoc:
     # The Configuration instance used by this Initializer instance.
     attr_reader :configuration
     
@@ -58,6 +61,7 @@ module Bowline
       @loaded_plugins = []
     end
     
+    # Add all of Ruby's stdlib to the load path
     def initialize_ruby
       return unless Bowline::Desktop.enabled?
       ruby_path = Bowline::Library.local_rubylib_path
@@ -65,6 +69,10 @@ module Bowline
         ruby_path = Bowline::Library.rubylib_path
         return unless File.directory?(ruby_path)
       end
+      # Remove old stdlib load paths
+      $:.delete_if {|path| path =~ /^\/usr\// }
+      
+      # Add new stdlib load paths
       version   = Library::RUBY_LIB_VERSION
       platform  = Library::RUBY_ARCHLIB_PLATFORM
       $: << File.join(ruby_path, version)                           # RUBY_LIB
@@ -75,9 +83,10 @@ module Bowline
       $: << File.join(ruby_path, "vendor_ruby")                     # RUBY_VENDOR_LIB
       $: << File.join(ruby_path, "vendor_ruby", version)            # RUBY_VENDOR_LIB2
       $: << File.join(ruby_path, "vendor_ruby", version, platform)  # RUBY_VENDOR_ARCHLIB
+      
+      # These two need to be required to fully setup internationalization 
       require File.join(*%w[enc encdb])
       require File.join(*%w[enc trans transdb])
-      $:.uniq!
     end
         
     def require_frameworks
@@ -119,6 +128,7 @@ module Bowline
       $LOAD_PATH.uniq!
     end
     
+    # Initializes ActiveRecord databases
     def initialize_database
       if defined?(ActiveRecord)
         ActiveRecord::Base.establish_connection(configuration.database_configuration)
@@ -268,6 +278,8 @@ module Bowline
       silence_warnings { Object.const_set "APP_NAME", configuration.name }
     end
     
+    # Creates a class called AppConfig from configuration
+    # variables found in config/application.yml
     def load_app_config
       app_config = configuration.app_config
       return unless app_config
@@ -446,13 +458,34 @@ module Bowline
      
      attr_accessor :initializer_glob
      
+     # Set the path that MainWindow will load
+     # when the application starts.
      attr_accessor :index_path
      
+     # Set the application's name.
+     # This is required.
      attr_accessor :name
+     
+     # Set the application's globally unique id.
+     # This is required.
+     # Example:
+     #    config.id = "com.maccman.bowline"
      attr_accessor :id
+     
+     # Set the application's version.
+     # Example:
+     #    config.version = "0.1.2"
      attr_accessor :version
+     
      attr_accessor :description
      attr_accessor :url
+     
+     # Set the application's icon. 
+     # Point this variable to the icons path.
+     #
+     # If this isn't specified, Bowline's default one will be used.
+     # 
+     # Supported icon files are PNGs and JPGs, preferably 512px x 512px.
      attr_accessor :icon
 
      attr_accessor :publisher

data/lib/bowline/library.rb

@@ -1,4 +1,5 @@
 module Bowline
+  # Provides paths to Bowline's required libraries.
   module Library
     RUBY_LIB_VERSION      = "1.9.1"
     RUBY_ARCHLIB_PLATFORM = "i386-darwin9.8.0"
@@ -6,6 +7,8 @@ module Bowline
     DESKTOP_URL  = "#{PROJECT_URL}/bowline-desktop"
     RUBYLIB_URL  = "#{PROJECT_URL}/rubylib.zip"
     
+    # Path to a folder stored under the users
+    # home directory containing the downloaded libraries.
     def path
       File.expand_path(
         File.join(home_path, ".bowline")
@@ -13,11 +16,13 @@ module Bowline
     end
     module_function :path
     
+    # Path to the bowline-desktop binary
     def desktop_path
       File.join(path, "bowline-desktop")
     end
     module_function :desktop_path
     
+    # Path to Ruby's stdlib
     def rubylib_path
       File.join(path, "rubylib")
     end
@@ -33,6 +38,12 @@ module Bowline
     end
     module_function :local_rubylib_path
     
+    def local_build_path
+      File.join(APP_ROOT, "build")
+    end
+    module_function :local_build_path
+    
+    # Returns true if all required libraries exist.
     def ready?
       File.exist?(desktop_path) && 
         File.directory?(rubylib_path) && 

data/lib/bowline/local_model.rb

@@ -1,4 +1,12 @@
 module Bowline
+  # The LocalModel class mirrors ActiveRecord's api, and is used for 
+  # models you want to hold in memory. 
+  # 
+  # You can also use this class in conjunction with Bowline's binders.
+  # 
+  # All normal ActiveRecord callbacks are supported, such as before_save and after_save.
+  # 
+  # Associations are not currently supported.
   class LocalModel
     extend Watcher::Base
     
@@ -6,47 +14,60 @@ module Bowline
           :before_create,  :after_create,
           :before_update,  :after_update,
           :before_destroy, :after_destroy
-  
-    @@records = []
-  
+    
     class << self
+      def records
+        @records ||= []
+      end
+      
+      # Populate the model with the array argument.
+      # This doesn't replace the model's existing records.
+      # Create callbacks are still executed.
       def populate(array)
         array.each {|r| create(r) }
       end
-    
+      
+      # Find record by ID, or raise.
       def find(id)
-        @@records.find {|r| r.id == id } || raise('Unknown Record')
+        records.find {|r| r.id == id } || raise('Unknown Record')
       end
       alias :[] :find
     
       def first
-        @@records[0]
+        records[0]
       end
       
       def last
-        @@records[-1]
+        records[-1]
       end
       
       def count
-        @@records.length
+        records.length
       end
     
       def all
-        @@records
+        records
       end
-    
+      
       def destroy(id)
         find(id).destroy
       end
       
+      # Removes all records and executes 
+      # destory callbacks.
       def destroy_all
-        @@records.dup.each {|r| r.destroy }
+        records.dup.each {|r| r.destroy }
       end
       
+      # Removes all records without executing
+      # destroy callbacks.
       def delete_all
-        @@records.clear
+        records.clear
       end
-    
+      
+      # Create a new record.
+      # Example:
+      #   create(:name => "foo", :id => 1)
       def create(atts = {})
         rec = self.new(atts)
         rec.save && rec
@@ -54,7 +75,11 @@ module Bowline
     end
   
     attr_reader :attributes
-  
+    
+    # Initialize the record with an optional
+    # hash of attributes. If a :id attribute
+    # isn't passed, the instance's object id 
+    # is used instead.
     def initialize(atts = {})
       @attributes = {}.with_indifferent_access
       @attributes.replace(atts)
@@ -66,7 +91,8 @@ module Bowline
     def id
       @attributes[:id]
     end
-  
+    
+    # Update record with a hash of new attributes.
     def update(atts)
       run_callbacks(:before_save)
       run_callbacks(:before_update)
@@ -75,12 +101,12 @@ module Bowline
       run_callbacks(:after_update)
       true
     end
-  
+
     def save
       run_callbacks(:before_save)
       if @new_record
         run_callbacks(:before_create)
-        @@records << self
+        self.class.records << self
         run_callbacks(:after_create)
         @new_record = false
       end
@@ -90,7 +116,7 @@ module Bowline
   
     def destroy
       run_callbacks(:before_destroy)
-      @@records.delete(self)
+      self.class.records.delete(self)
       run_callbacks(:after_destroy)
       true
     end
@@ -110,7 +136,7 @@ module Bowline
     
     private
       def run_callbacks(callback)
-        self.class.watcher.call(callback)
+        self.class.watcher.call(callback, self)
       end
   end
 end