jrubyfx 0.9.2-java → 1.0.0-java

data/README.md

@@ -1,13 +1,11 @@
 JRubyFX
 =======
-JRubyFX is a pure ruby wrapper for JavaFX 2.x with FXML support
+JRubyFX is a pure ruby wrapper for JavaFX 2.2+ with FXML support
 
 Status
 ------
-JRubyFX should be usable in its current form and able to run FXML apps if used properly (see Issues).
-The syntax of the FXML side of JRubyFX should be fairly stable, but the JavaFX DSL may change.
-At this point in time, no custom ruby controls are supported from FXML, though you
-can certainly create them in code.
+JRubyFX master should be usable in its current form and able to run simple FXML apps if used properly (see Issues).
+FXML syntax in master/1.0 is very different from 0.9 series. Please see the [JRubyFX github wiki](https://github.com/jruby/jrubyfx/wiki/) for more details.
 
 Install
 -----
@@ -17,9 +15,10 @@ gem install jrubyfx
 
 Manual Build and Install
 -----
-Build is done using rake/gem/bundler/rdoc. You obviously need JRuby, Java 1.7 (with JavaFX) also.
+Build is done using rake/gem/bundler/rdoc. You need JRuby >1.7.4 (in 1.9 mode), Java >1.6 with JavaFX 2.2, but Java 7 is recommended. Building native application packages requires JDK 8.
 
 ```text
+gem install jrubyfx-fxmlloader
 rake install
 ```
 Once the gem is installed, just run a ruby file that uses it normally.
@@ -27,6 +26,8 @@ Once the gem is installed, just run a ruby file that uses it normally.
 **NOTE:** If you don't have JRuby installed as the `ruby` command, use `jruby -S rake` instead of `rake`. If
 you are using RVM, this does not apply to you (though make sure you `rvm use jruby`).
 
+**If you are reporting bugs or encountering fxml issues:** please install [master jrubyfx-fxmlloader](https://github.com/byteit101/JRubyFX-FXMLLoader/) instead of from rubygems
+
 Creating a Jar
 --------------
 If you want to distribute your application, you can create a jar with embedded JRuby.
@@ -55,7 +56,9 @@ Example: If my project directory is `Hello`, all my files are in `src`, I have a
 jrubyfx-jarify src --main src/HelloWorldApp.rb dist/HelloWorldApp.jar --native --name "Hello World App" -v
 ```
 
-Sample
+Also note that you can do this in code, see samples/fxml/Demo.rb for the rake task usage.
+
+Samples
 -------
 
 To run sample:
@@ -73,9 +76,11 @@ rake run main_script=samples/fxml/Demo.rb
 To run all samples (a nice quick way to make sure you didn't break anything), run:
 
 ```text
-jruby samples/test_all_the_samples.rb
+jruby -I lib samples/test_all_the_samples.rb
 ```
 
+Several other files that can be used as examples are in the tests/ folder
+
 Creating Application and Controller
 -----------------------------------
 
@@ -83,19 +88,16 @@ Require the 'jrubyfx' file/gem, and subclass JRubyFX::Application (and JRubyFX::
 At the bottom of the file, call _yourFXApplicationClass_.launch().
 Override start(stage) in the application. See samples/fxml/Demo.rb for commented FXML example,
 or the fils in samples/javafx for non-FXML (programatic JavaFX, but you should really
-look into FXML, its better) or see the Getting Started Guide and the Notes.
+look into FXML, its better) or see the [Getting Started Guide](https://github.com/jruby/jrubyfx/wiki/Getting-Started) and the Syntax Notes on the [JRubyFX github wiki](https://github.com/jruby/jrubyfx/wiki/)
 
-If you want rdoc, run `rake rdoc`.
+If you want rdoc, run `rake rdoc`. Please note that there are lots of generated methods and conventions that are not in the RDoc. Please read the Getting Started Guide or the tutorials.
 
 Issues
 ------
-* You must NOT set fx:controller in the FXML files. At the moment, due to JRuby bugs, Java is unable
-  to initialize Ruby objects in this way. See Demo.rb for proper way to set the controller (passing it
-  in to load_fxml())
-* You must use the provided JavaFXImpl::Launcher to launch the app (aka: call _yourFXApplicationClass_.launch()). This is due to the same JRuby bugs
-  as above.
-* Errors loading jfxrt.jar are bugs. Please report if you encounter this issue, tell us your platform,
-  OS, and version of JRuby
+* Use JRubyFX-FxmlLoader's FxmlLoader instead of javafx.fxml.FXMLLoader for maximum Ruby support.
+* FXML support in master for very complex documents is untested. Report bugs against JRubyFX-FxmlLoader with the FXML file if it fails.
+* You must use the provided JavaFXImpl::Launcher to launch the app (aka: call _yourFXApplicationClass_.launch())
+* Errors loading JavaFX are bugs. Please report if you encounter this issue, tell us your platform, OS, and version of JRuby
 * Jarify command needs the `jar` executable in your path.
 * Any other difficulties are bugs. Please report them
 

data/bin/jrubyfx-generator

@@ -18,6 +18,7 @@ limitations under the License.
 
 require 'date'
 require 'jrubyfx/utils'
+require 'pathname'
 
 if ARGV.length < 1
   puts "Please specify the fxml file to parse"
@@ -34,39 +35,54 @@ name_guess = ARGV[2] if ARGV.length > 2
 print "Generating JRubyFX template for #{fxml} into #{rb}... "
 
 File.open(rb, "w") do |output|
-  
+
+  fx_diff_root = ("/" + Pathname.new(File.dirname fxml).relative_path_from(Pathname.new(File.dirname rb)).to_s).inspect
+  fx_diff_root = if fx_diff_root == '"/."'
+    ""
+  else
+    " + #{fx_diff_root}"
+  end
   output << <<END
 # This file was auto-generated by jrubyfx-generator at #{DateTime.now.to_s}
 
 require 'jrubyfx'
+fxml_root File.dirname(__FILE__)#{fx_diff_root}
 
 class #{name_guess}Application < JRubyFX::Application
   def start(stage)
-    with(stage, title: "#{name_guess}", width: 600, height: 400)
-    #{name_guess}Controller.load_fxml("#{File.basename(fxml)}", stage)
-    stage.show()
+    with(stage, title: "#{name_guess}") do
+      fxml #{name_guess}Controller
+      show
+    end
   end
 end
 
-class #{name_guess}Controller < JRubyFX::Controller
+class #{name_guess}Controller
+  include JRubyFX::Controller
+  fxml "#{File.basename(fxml)}"
 END
 
+  fx_ids = []
   File.open(fxml, "r") do |fx|
     handlers = "\n"
+
     fx.each_line do |line|
-      line.scan(/fx:id="([^ "':]+)"/) do |match| 
-        output << "  fx_id :#{match[0]}\n"
+      line.scan(/fx:id="([^ "':]+)"/) do |match|
+        fx_ids << match[0]
       end
       # TODO: may not work with funky non-latin characters
       # Yes, I used regex, yes its xml, yes I now have two problems.
-      line.scan(/on((([A-Z]*[a-z]*)*?)[A-Z]+[a-z]+)="#([^ "':]+)"/) do |match| 
-        handlers << "  fx_#{match[1].snake_case}#{(match[1].length >0 ? "_" : "")}handler :#{match[3]} do |event|\n    # TODO: Auto-generated event handler\n"
+      line.scan(/on((([A-Z]*[a-z]*)*?)[A-Z]+[a-z]+)="#([^ "':]+)"/) do |match|
+        handlers << "  def #{match[3]}(event)\n"
+        handlers << "    # TODO: Auto-generated event handler\n"
         handlers << "    puts \"#{match[0]} event '#{match[3]}' called\"\n  end\n\n"
       end
     end
+    output << "\n  # nodes with ruby method-like fx:ids may be accessed directly"
+    output << "\n  def initialize\n#{fx_ids.map{|x|"    puts \"fx:id=\\\"#{x}\\\" was not injected: check your FXML file '#{File.basename(fxml)}'.\" unless @#{x}"}.join "\n"}\n  end\n"
     output << handlers
   end
-  
+
   output << <<END
 end
 
@@ -76,6 +92,7 @@ END
 end
 
 puts "Done!"
+
 puts "Launching 'jruby #{rb}' ..."
 
-require rb
+require rb

data/lib/jrubyfx.rb

@@ -17,11 +17,15 @@ limitations under the License.
 require 'java' # for java_import
 require 'jruby/core_ext' # for the become_java!
 
+unless File.size? "#{File.dirname(__FILE__)}/jrubyfx/imports.rb"
+  puts "Please run `rake reflect` to generate the imports"
+  exit -1
+end
 # JRubyFX includes
-require_relative 'jrubyfx/jfx_imports'
-require_relative 'jrubyfx/fxml_module'
+require_relative 'jrubyfx/imports'
+require_relative 'jrubyfx/module'
 require_relative 'jrubyfx/dsl'
 JRubyFX::DSL.load_dsl # load it after we require the dsl package to not loop around
-require_relative 'jrubyfx/fxml_application'
-require_relative 'jrubyfx/fxml_controller'
+require_relative 'jrubyfx/application'
+require_relative 'jrubyfx/controller'
 require_relative 'jrubyfx/java_fx_impl'

data/lib/jrubyfx/{fxml_application.rb → application.rb}

@@ -15,8 +15,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 =end
 
-require 'jrubyfx'
-
 ##
 # Inherit from this class for FXML Applications. You must use this class for both
 # raw JavaFX and FXML as it contains the launch method.

data/lib/jrubyfx/controller.rb

@@ -0,0 +1,307 @@
+=begin
+JRubyFX - Write JavaFX and FXML in Ruby
+Copyright (C) 2013 The JRubyFX Team
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+=end
+
+require 'jrubyfx-fxmlloader'
+
+# Special methods for fxml loading
+module Kernel
+  def fxml_root(value=nil)
+    if value
+      @@jrubyfx_fxml_dir = File.expand_path(value)
+    else
+      @@jrubyfx_fxml_dir
+    end
+  end
+end
+
+# Inherit from this class for FXML controllers
+module JRubyFX::Controller
+  include JRubyFX::DSL
+  java_import 'java.net.URL'
+
+  DEFAULT_SETTINGS = {
+    width: -1,
+    height: -1,
+    fill: :white,
+    depth_buffer: false,
+    root_dir: nil,
+    initialized: nil
+  }
+
+  # Controllers usually need access to the stage.
+  attr_writer :stage, :scene
+
+  def self.included(base)
+    base.extend(ClassMethods)
+    base.extend(JRubyFX::FXMLClassUtils)
+    # register ourselves as a control. overridable with custom_fxml_control
+    register_type base if base.is_a? Class
+  end
+  
+  # class methods for FXML controllers
+  module ClassMethods
+    include JRubyFX::DSL
+
+    #nested including, TODO: don't duplicate this
+    def included(base)
+      base.extend(JRubyFX::Controller::ClassMethods)
+      # register ourselves as a control. overridable with custom_fxml_control
+      JRubyFX::DSL::ClassUtils.register_type base if base.is_a? Class
+    end
+
+    # Load given fxml file onto the given stage. `settings` is an optional hash of:
+    # * :initialize => [array of arguments to pass to the initialize function]
+    # * :width => Default width of the Scene
+    # * :height => Default height of the Scene
+    # * :fill => Fill color of the Scene's background
+    # * :depth_buffer => JavaFX Scene DepthBuffer argument (look it up)
+    # * :root_dir =>  filename search for fxml realtive to this file
+    #
+    # === Examples
+    #
+    #   controller = MyFXController.new "Demo.fxml", stage
+    #
+    # === Equivalent Java
+    #   Parent root = FXMLLoader.load(getClass().getResource("Demo.fxml"));
+    #   Scene scene = new Scene(root);
+    #   stage.setScene(scene);
+    #   controller = root.getController();
+
+    def load_into(stage, settings={})
+      # Inherit from default settings
+      settings = DEFAULT_SETTINGS.merge({root_dir: (self.instance_variable_get("@fxml_root_dir") || fxml_root),
+          filename: self.instance_variable_get("@filename")}).merge settings
+
+      # Custom controls don't always need to be pure java, but oh well...
+      become_java!
+
+      # like new, without initialize
+      ctrl = allocate
+
+      # Set the stage so we can reference it if needed later
+      ctrl.stage = stage
+
+      # load the FXML file
+      root = Controller.get_fxml_loader(settings[:filename], ctrl, settings[:root_dir]).load
+
+      # Unless the FXML root node is a scene, wrap that node in a scene
+      if root.is_a? Scene
+        scene = root
+      else
+        scene = Scene.new root, settings[:width], settings[:height], settings[:depth_buffer]
+        scene.fill = settings[:fill]
+      end
+
+      # set the controller and stage scene
+      ctrl.scene = stage.scene = scene
+
+      ctrl.finish_initialization *settings[:initialize].to_a
+    end
+
+    # This is the default override for custom controls
+    # Normal FXML controllers will use Control#new
+    def new(*args, &block)
+      # Custom controls don't always need to be pure java, but oh well...
+      become_java! if @filename
+
+      # like new, without initialize
+      ctrl = allocate
+
+      ctrl.initialize_controller(DEFAULT_SETTINGS.merge({root_dir: @fxml_root_dir || fxml_root,
+            filename: @filename}),
+        *args, &block) if @filename
+
+      # return the controller
+      ctrl
+    end
+
+    #decorator to force becoming java class
+    def become_java
+      @force_java = true
+    end
+
+    # Set the filename of the fxml this control is part of
+    def fxml(fxml=nil, name = nil, root_dir = nil)
+      @filename = fxml
+      # snag the filename from the caller
+      @fxml_root_dir = root_dir
+      register_type(self, name) if name
+    end
+
+    ##
+    # Event Handlers
+    ##
+
+    ##
+    # call-seq:
+    #   on(callback, ...) { |event_info| block } => Method
+    #
+    # Registers a function of name `name` for a FXML defined event with the body in the block.
+    # Note you can also just use normal methods
+    #
+    # === Examples
+    #   on :click do
+    #     puts "button clicked"
+    #   end
+    #
+    #   on :moved, :pressed do |event|
+    #     puts "Mouse Moved or Key Pressed"
+    #     p event
+    #   end
+    #
+    # === Equivalent Java
+    #   @FXML
+    #   private void click(ActionEvent event) {
+    #     System.out.println("button clicked");
+    #   }
+    #
+    #   @FXML
+    #   private void moved(MouseEvent event) {
+    #     System.out.println("Mouse Moved or Key Pressed");
+    #   }
+    #
+    #   @FXML
+    #   private void keypress(KeyEvent event) {
+    #     System.out.println("Key Pressed or Key Pressed");
+    #   }
+    #
+    def on(names, &block)
+      [names].flatten.each do |name|
+        class_eval do
+          # must define this way so block executes in class scope, not static scope
+          define_method name, block
+        end
+      end
+    end
+  end
+
+  #default java ctor, override for arguments
+  def java_ctor(ctor, initialize_arguments)
+    ctor.call
+  end
+
+  # Initialize all controllers
+  def initialize_controller(options={}, *args, &block)
+
+    # JRuby complains loudly (probably broken behavior) if we don't call the ctor
+    java_ctor self.class.superclass.instance_method(:initialize).bind(self), args
+
+    # load the FXML file with the current control as the root
+    load_fxml options[:filename], options[:root_dir]
+
+    finish_initialization *args, &block
+  end
+
+  def load_fxml(filename, root_dir=nil)
+    fx = Controller.get_fxml_loader(filename, self, root_dir)
+    fx.root = self
+    fx.load
+  end
+
+  def finish_initialization(*args, &block)
+    @nodes_by_id = {}
+
+    # custom controls are their own scene
+    self.scene = self unless @scene
+
+    # Everything is ready, call initialize
+    if private_methods.include? :initialize
+      self.send :initialize, *args, &block
+    end
+
+    #return ourself
+    self
+  end
+
+  ##
+  #  Node Lookup Methods
+  ##
+
+  # return first matched node or nil
+  def find(css_selector)
+    @scene.lookup(css_selector)
+  end
+
+  # Return first matched node or throw exception
+  def find!(css_selector)
+    res = find(css_selector)
+    raise "Selector(#{css_selector}) returned no results!" unless res
+    res
+  end
+
+  # return an array of matched nodes
+  def css(css_selector)
+    @scene.get_root.lookup_all(css_selector).to_a
+  end
+  
+  # Loads a controller-less file
+  def self.load_fxml_only(filename, stage, settings={})
+    # Inherit from default settings
+    settings = DEFAULT_SETTINGS.merge({root_dir: fxml_root,
+        filename: filename}).merge settings
+
+    # load the FXML file
+    root = Controller.get_fxml_loader(settings[:filename], nil, settings[:root_dir]).load
+      
+    # TODO: de-duplicate this code
+
+    # Unless the FXML root node is a scene, wrap that node in a scene
+    if root.is_a? Scene
+      scene = root
+    else
+      scene = Scene.new root, settings[:width], settings[:height], settings[:depth_buffer]
+      scene.fill = settings[:fill]
+    end
+
+    # set the controller and stage scene
+    stage.scene = scene
+  end
+
+
+  ##
+  # call-seq:
+  #   get_fxml_loader(filename) => FXMLLoader
+  #   get_fxml_loader(filename, controller_instance) => FXMLLoader
+  #   get_fxml_loader(filename, controller_instance, root_dir) => FXMLLoader
+  #
+  # Load a FXML file given a filename and a controller and return the loader
+  # root_dir is a directory that the file is relative to.
+  # === Examples
+  #   root = JRubyFX::Controller.get_fxml_loader("Demo.fxml").load
+  #
+  #   root = JRubyFX::Controller.get_fxml_loader("Demo.fxml", my_controller).load
+  #
+  # === Equivalent Java
+  #   Parent root = FXMLLoader.load(getClass().getResource("Demo.fxml"));
+  #
+  def self.get_fxml_loader(filename, controller = nil, root_dir = nil)
+    fx = FxmlLoader.new
+    fx.location =
+      if JRubyFX::Application.in_jar?
+      # If we are in a jar file, use the class loader to get the file from the jar (like java)
+      # TODO: should just be able to use URLs
+      JRuby.runtime.jruby_class_loader.get_resource filename
+    else
+      root_dir ||= fxml_root
+      # If we are in the normal filesystem, create a file url path relative to relative_to or this file
+      URL.new "file:#{File.join root_dir, filename}"
+    end
+    # we must set this here for JFX to call our events
+    fx.controller = controller
+    fx
+  end
+end