Cheri::Swing -- Cheri: A Builder Framework for (J)Ruby and Java

::Swing

Cheri::Swing

To include:

require 'rubygems'
require 'cheri/swing'
...
include Cheri::Swing

Note that inclusion at the top level is not recommended.

Options:

swing[:auto]       #=> Enables auto mode
swing[:auto=>true] #=> (no swing/cheri block required)

Cheri::Swing (which includes Cheri::AWT) includes methods (Ruby-cased class names) for all javax.swing, javax.swing.border and java.awt classes, plus many in javax.swing.table, javax.swing.tree, java.awt.image and java.awt.geom. You can extend Cheri::Swing with other classes/packages (including 3rd party, or your own!) using the Cheri builder-builder's build_package method.

Cheri::Swing (and any other builder based on Cheri::Java) also provides easy-to-use on_xxx methods to implement event listeners. Any event listener supported by a class (through an addXxxListener method) can be accessed from Cheri::Swing using an on_xxx method (where xxx is the Ruby-cased event-method name). Because it is so widely used in Swing, the ActionListener#actionPerformed event method is aliased as on_click:

@frame = swing.frame('Hello') {
  size 500,500
  flow_layout
  on_window_closing {|event| @frame.dispose}
  button('Hit me') {
    on_click { puts 'button clicked' }
  }
}

The cherify and cheri_yield methods can be used to incorporate objects created outside the Cheri::Swing framework (cherify), or to re-introduce objects created earlier within the framework (cheri_yield):

class MyButton < javax.swing.JButton
...
end
...
a_button = MyButton.new
...
@frame = swing.frame('Hello') {
  size 500,500
  flow_layout
  cherify(a_button) {
    on_click { puts 'button clicked' }
  }  
}
  
@frame = swing.frame('Hello') {
  menu_bar {
    @file_menu = menu('File') {
      menu_item('Exit') {on_click {@frame.dispose } }
    }
  }  
}
# => add a new item later:
cheri_yield(@file_menu) {
  menu_item('Open...') {
    on_click { ... }
  }
}

The Cheri builder-builder can be used to extend Cheri::Swing in a couple of ways. Individual classes can be included using the build statement, while entire packages can be included using the build_package statement. Note that you may need to supply connection logic if the incorporated classes use methods other than add to connect child objects to parent objects; see file /lib/cheri/builder/swing/connecter.rb for many examples.

// Java:
package my.pkg;
public class MyParent extends javax.swing.JComponent {
  ...
  public void addChild(MyChild child) {
    ...
  }  
}
...
public class MyChild {
...
}
  
# JRuby:
require 'cheri/swing'
...
include Cheri::Swing
...
# easy-to-reference names; could use include_package instead
MyParent = Java::my.pkg.MyParent
MyChild = Java::my.pkg.MyChild
  
# example specifying each class; 'custom' names may be specified
MyBuilder = Cheri::Builder.new_builder do
  extend_builder Cheri::Swing
  build MyParent,:pappy
  build MyChild,:kiddo
  type MyParent do
    connect MyChild,:addChild
  end
end
  
include MyBuilder
@frame = swing.frame('My test') {
  ...
  panel {
    pappy {
      kiddo { ... }
    }
  }  
}
  
# example specifying package; default naming
MyBuilder = Cheri::Builder.new_builder do
  extend_builder Cheri::Swing
  build_package 'my.pkg'
  type MyParent do
    connect MyChild,:addChild
  end
end
  
include MyBuilder
@frame = swing.frame('My test') {
  ...
  panel {
    my_parent {
      my_child { ... }
    }
  }  
}

You can also use the builder-builder just to add conection logic to Cheri::Swing, as not every possible connection type is defined.

A Cheri::Swing examples section will be available soon. Until then, see the Cheri::JRuby::Explorer (CJX) code (under lib/cheri/jruby/explorer) for extensive examples of Cheri::Swing usage.