bowline 0.5.3 → 0.5.4

data/lib/bowline/desktop/app.rb

@@ -1,9 +1,13 @@
 module Bowline
   module Desktop
     module App
-      # Methods:
-      #   busy()
-      #   exit()
+      ##
+      # :singleton-method: busy(bool = true)
+      # Shows a busy cursor (hourglass) on all windows.
+      
+      ##
+      # :singleton-method: exit
+      # Exits the application.
     end
   end
 end

data/lib/bowline/desktop/bridge.rb

@@ -2,12 +2,11 @@ module Bowline
   module Desktop
     module Bridge
       module ClassMethods
-        # Extend you own classes with this
-        # module, and then call js_expose 
-        # to expose your classes' class
-        # variables to JavaScript.
+        ##
+        # Extend you own classes with this module, and then call js_expose 
+        # to expose your classes' class variables to JavaScript.
         #
-        # Ruby Class:
+        # Example:
         #   class FooClass
         #     extend Bowline::Desktop::Bridge::ClassMethods
         #     js_expose
@@ -17,7 +16,7 @@ module Bowline
         #     end
         #   end
         #
-        # JavaScript:
+        # JavaScript Example:
         #   Bowline.invoke("FooClass", "foo", function(res){
         #     console.log(res);
         #   })
@@ -36,7 +35,7 @@ module Bowline
         end
       end
       
-      class Message
+      class Message #:nodoc:
         include Bowline::Logging
         
         def self.from_array(window, arr)
@@ -75,12 +74,12 @@ module Bowline
         end
       end
       
-      def setup
+      def setup #:nodoc:
         Desktop.on_tick(method(:poll))
       end
       module_function :setup
 
-      def poll
+      def poll #:nodoc:
         WindowManager.allocated_windows.each do |window|
           result   = window.run_script("try {Bowline.pollJS()} catch(e) {false}")
           next if result.blank? || result == "false"

data/lib/bowline/desktop/clipboard.rb

@@ -1,8 +1,17 @@
 module Bowline
   module Desktop
+    # The Clipboard module gives you cross-platform access to 
+    # the systems native clipboard. At the moment, you can only
+    # read/write strings. We're planning to extend this to images.
     module Clipboard
-      # Methods:
-      #   write(str)
+      ##
+      # :singleton-method: write(str)
+      # Write a string to the Clipboard.
+      #   write("some text")
+      
+      ##
+      # :singleton-method: write(str)
+      # Read a string from the Clipboard.
       #   read #=> str
     end
   end

data/lib/bowline/desktop/dialog.rb

@@ -1,6 +1,25 @@
 module Bowline
   module Desktop
     module Dialog
+      # Display a dialog box from the main window.
+      # You can ask for a confirmation, or just display some information.
+      # 
+      # Supported options are:
+      #   :yes_no           - Puts Yes and No buttons on the message box *
+      #   :ok               - Puts an Ok button on the message box *
+      #   :cancel           - Puts a Cancel button on the message box
+      #   :icon_exclamation - Displays an exclamation mark symbol
+      #   :icon_error       - Displays an error symbol
+      #   :question         - Displays a question mark symbol
+      #   :information      - Displays an information symbol
+      #   :caption          - Title for the message box
+      #                       * may be combined with :cancel
+      # 
+      # Return values are:
+      #   :yes    - User clicked yes
+      #   :no     - User clicked no
+      #   :ok     - User clicked ok
+      #   :cancel - User clicked cancel, or closed the box
       def message(msg, options = {})
         style = 0
         style |= YES_NO if options[:yes_no]

data/lib/bowline/desktop/dock.rb

@@ -1,9 +1,20 @@
 module Bowline
   module Desktop
+    # The Dock module gives you a few methods to control
+    # the Mac OSX dock. It's platform specific, and on platforms  
+    # other than OSX calling the methods won't do anything.
     module Dock
-      # Methods:
-      #  badge=(str)
-      #  clear_badge
+      # Set the badge number. This is the little numbered red star above
+      # the App's Dock icon. A good example of this is Mail.app incrementing
+      # its icon's star whenever a new mail is received.
+      def badge=(number)
+        self._badge = number.to_s
+      end
+      module_function :badge=
+      
+      ##
+      # :singleton-method: clear_badge
+      # Clear the Icon's badge number
     end
   end
 end

data/lib/bowline/desktop/host.rb

@@ -1,10 +1,19 @@
 module Bowline
   module Desktop
     module Host
-      # Methods
-      #  ip()
-      #  public_ip()
-      #  host_name()
+      ##
+      # :singleton-method: ip
+      # Returns the computer's local IP address
+
+      ##
+      # :singleton-method: public_ip
+      # Returns the computer's network IP address.
+      # This method doesn't return the computer's Internet IP, 
+      # for that you need a remote server.
+
+      ##
+      # :singleton-method: host_name
+      # Returns the computer's host name
     end
   end
 end

data/lib/bowline/desktop/js.rb

@@ -1,6 +1,6 @@
 module Bowline
   module Desktop
-    module JS    
+    module JS #:nodoc:
       class Script
         include Bowline::Logging
         
@@ -31,7 +31,7 @@ module Bowline
             result
           else
             trace "Pseudo JS eval on #{window}: #{script}"
-            prok.call(nil)
+            prok.call(nil) if prok
           end
         end
         

data/lib/bowline/desktop/misc.rb

@@ -1,9 +1,13 @@
 module Bowline
   module Desktop
     module Misc
-      # Methods:
-      #   launch_browser(url)
-      #   bell()
+      ##
+      # :singleton-method: launch_browser(url)
+      # Launch the computer's default browser
+      
+      ##
+      # :singleton-method: bell
+      # Call the system bell
     end
   end
 end

data/lib/bowline/desktop/network.rb

@@ -1,6 +1,6 @@
 module Bowline
   module Desktop
-    class Network
+    class Network #:nodoc:
       # Implement address polling to see if we're online
     end
   end

data/lib/bowline/desktop/proxy.rb

@@ -1,35 +1,33 @@
 module Bowline
   module Desktop
-    class Proxy      
-      # Use to call out to JavaScript.
-      #
-      # Use the method 'call' if you want 
-      # to call a function, or the method 'res' if you want 
-      # the result of a variable evaluation.
-      #
-      # You can pass a block as the last argument which will
-      # be called with the result of the evaluation.
-      # 
-      # All arguments are serialized by JSON, so you can only pass
-      # the following objects:
-      # * Hash
-      # * Array
-      # * String
-      # * Integer
-      #
-      # Usage:
-      #   proxy.FooObject.messages = [1,2,3] #=> "FooObject.messages = [1,2,3]"
-      #   proxy.FooObject.hi.call #=> "FooObject.hi()"
-      #   proxy.FooObject.hi(1,2,3).bye.call #=> "FooObject.hi(1,2,3).bye()"
-      #   proxy.FooObject.messages.res #=> "FooObject.messages"
-      #   proxy.FooObject.messages.res {|result|
-      #     puts "Messages are: #{result}"
-      #   }
-      #
-      # Reasoning behind this class:
-      #  * JavaScript needs to be called all at once
-      #  * We don't know if it's a method call, or a variable
-      
+    # Use to call out to JavaScript.
+    #
+    # Use the method 'call' if you want  to call a function, 
+    # or the method 'res' if you want  the result of a variable evaluation.
+    #
+    # You can pass a block as the last argument which will
+    # be called with the result of the evaluation.
+    # 
+    # All arguments are serialized by JSON, so you can only pass
+    # the following objects:
+    # * Hash
+    # * Array
+    # * String
+    # * Integer
+    #
+    # Examples:
+    #   proxy.FooObject.messages = [1,2,3] #=> "FooObject.messages = [1,2,3]"
+    #   proxy.FooObject.hi.call #=> "FooObject.hi()"
+    #   proxy.FooObject.hi(1,2,3).bye.call #=> "FooObject.hi(1,2,3).bye()"
+    #   proxy.FooObject.messages.res #=> "FooObject.messages"
+    #   proxy.FooObject.messages.res {|result|
+    #     puts "Messages are: #{result}"
+    #   }
+    #
+    # Reasoning behind this class's call/res API:
+    #  * JavaScript needs to be called all at once
+    #  * We don't know if it's a method call, or a variable
+    class Proxy
       def initialize(win)
         @window = win
         @crumbs = []

data/lib/bowline/desktop/sound.rb

@@ -1,8 +1,9 @@
 module Bowline
   module Desktop
     module Sound
-      # Methods:
-      #   play(wav_file_path)
+      ##
+      # :singleton-method: play(path)
+      # Play a wav file
     end
   end
 end

data/lib/bowline/desktop/window.rb

@@ -1,30 +1,156 @@
 module Bowline
   module Desktop
+    # Use the Window class to create new windows that your
+    # users can interact with.
+    # 
+    # Usually, this class isn't instantiated directly, but rather
+    # used in conjunction with the WindowManager class.
+    # We recommend this approach, otherwise your window won't be
+    # able to call out to Ruby, or use Bowline's binding API.
+    # 
+    # At the moment, these methods need to be called in the main thread.
+    # This is a restriction we're hoping to remove soon.
     class Window
       include WindowMethods
-      # Methods:
-      #  new()
-      #  center(direction = :both)
-      #  close
-      #  chrome=
-      #  disable
-      #  enable
-      #  file=      
-      #  id 
-      #  modal(flag = true)
-      #  name=
-      #  run_script(str) #=> str
-      #  raise
-      #  show
-      #  hide
-      #  set_size(width, height)
-      #  set_position(x, y)
-      #  select_dir(
-      #  )
-      #  shown?
+      ##
+      # :singleton-method: center(direction = :both)
+      # Center the window in a given direction.
+      # Supports the following directions:
+      #   :both       - both horizontal and vertical to the app
+      #   :horizontal - horizontal to the app
+      #   :vertical   - vertical to the app
+      #   :center     - center of the screen
+      #
+      # :call-seq:
+      #   my_method(Range)
+      #   my_method(offset, length)
+      
+      ##
+      # :singleton-method: close
+      # Close the window.
+      
+      ##
+      # :singleton-method: disable
+      # Disable user input to the window.
+      
+      ##
+      # :singleton-method: enable
+      # Enable user input to the window.
+      
+      ##
+      # :singleton-method: chome=(bool)
+      # Enable/disable window's chrome, 
+      # i.e. the buttons & frame
+      
+      ##
+      # :singleton-method: file=(path)
+      # Load HTML file. You can pass an absolute path, a path
+      # relative to the apps root, or a symbol, like so:
+      #   window.file = :about
+      # Passing a symbol will load the corrosponding HTML file
+      # in the public directory. In this case, it'll load about.html
+      
+      ##
+      # :singleton-method: id
+      # Internal ID for the window. 
+      
+      ##
+      # :singleton-method: dealocated?
+      # Returns true if the window has been dealocated. 
+      # Calling methods on dealocated windows has no effect. 
+      # Instead, you'll need to create a new instance.
+      
+      ##
+      # :singleton-method: modal(flag = true)
+      # Disable/Enable user interaction with other windows.
+
+      ##
+      # :singleton-method: name=(str)
+      # Set windows name (shown in the window's title bar)
+      
+      ##
+      # :singleton-method: run_script(str)
+      # Run JavaScript in this window.
+      #
+      # The return result types are very limited, 
+      # only the following are supported:
+      #   - Booleans
+      #   - Integers
+      #   - Strings
+      # These all then get converted into strings.
+      #
+      # This API is very low level. We recommend you use the abstractions
+      # provided by the WindowManager class, such as the 'page' method.
+
+      ##
+      # :singleton-method: raise
+      # Raise this window above all other ones.
+      
+      ##
+      # :singleton-method: show
+      # Show this window. By default, windows are hidden.
+      
+      ##
+      # :singleton-method: hide
+      # Hide this window.
+      
+      ##
+      # :singleton-method: close
+      # Close this window. Once a window is closed, either by a user or 
+      # by calling this method, it has been deallocated and may not be opened again. 
+      #
+      # You'll need to create a new instance of this class for a new window.
+      # Calling any methods on a dealocated window won't have any effect.
+      
+      ##
+      # :singleton-method: set_size(width, weight)
+      # Set the window's width & height in pixels.
+      
+      ##
+      # :singleton-method: height=(int)
+      # Helper to set the window's height.
+
+      ##
+      # :singleton-method: width=(int)
+      # Helper to set the window's width.
+      
+      ##
+      # :singleton-method: set_position(x, y)
+      # Set the window's position on the screen.
+      
+      ##
+      # :singleton-method: select_dir(options = {})
+      # Prompt the user to select a folder.
+      #
+      # Supported options are:
+      #   :message
+      #   :default_path
+      
+      ##
+      # :singleton-method: select_file(options = {})
+      # Prompt the user to select a file.
+      #
+      # Supported options are:
+      #   :message
+      #   :default_path
+      #   :default_filename
+      #   :default_extension
+      #   :wildcard           - defaults to *.*
+      #   :open               - show open button
+      #   :save               - show save button
+      #   :overwrite_prompt   - prompt if file already exists
+      #   :file_must_exist
+      # 
+      # The :wildcard options may be a specification for multiple 
+      # types of file with a description for each, such as:
+      #   "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
+      
+      ##
+      # :singleton-method: shown?
+      # Is this window currently shown?
     end
     
-    class MainWindow
+    class MainWindow #:nodoc:
       include WindowMethods
     end
   end