This gem is meant to make GUI development in Ruby apps trivial, 
and easy to wrap your head around.  It attempts to do what YAML
did to XML.  Make it easier.

Basically it allows you to design your window GUI layout using 
ASCII art-like text:

---------------My Window Title--------------------------
| [Click this button      :button1]                    |
| [Click this button too! :button2]                    |
--------------------------------------------------------

And then bind actions to ruby code, like this:

  elements[:button1].on_clicked { puts 'you clicked button1' }

This makes the design part of the GUI much easier than trying to figure
it out by trial and error, or "guessing" what swing or shoes are going to actually
give for you in the end.  It comes with its own experimental "GUI Editor" for
trying out designs on the fly.

How to get it:

# if you don't have jruby yet installed, for OS X or linux users (windows users use the jruby installer exe):
$ rvm install jruby
$ rvm use jruby

# now install the gem.
$ gem install simple_gui_creator

# now run the GUI design editor
$ jruby -S simple_gui_creator

Here's how to code it:

>> frame = SimpleGuiCreator::ParseTemplate.new # or optionally subclass this instead, and make sure to call super() in your constructor
>> frame.parse_setup_filename 'some_filename'

Set behaviors like this:

>> frame.elements['button1'].on_clicked { 
  SimpleGuiCreator.show_blocking_message_dialog "you clicked button1!" 
}  

Having the layout as ASCII text separates views from controllers, in this case, because you can store the layouts in
an entirely separate file (or embedded in the code).  "Normal humans" can then edit the design layout files, for instance.
It has proven quite nice at separating concerns.

More complicated example:

---------- Window Title ----------------------------------
| [a button:button1]   [button text:button2]             |
| "some text2:text1"                                     |
| [Editable Text Area with 4 rows  :text_area_name]      |
| [                                              ]       |
| [                                              ]       |
| [                                              ]       |
| [Dropdown Default \/ :dropdown_name]                   |
| [✓:checkbox_name] "Some text"                         |
----------------------------------------------------------

See the file spec/parse_template.spec.rb for examples of how to use the various elements.
The window borders along the edge are optional.

The library also has helper methods for common GUI tasks, like:

SimpleGuiCreator.show_blocking_message_dialog "A message box"
SimpleGuiCreator.new_nonexisting_filechooser_and_go # select file or filename for a "new file" (not yet existing)
SimpleGuiCreator.new_existing_dir_chooser_and_go # select pre-existing directory
SimpleGuiCreator.show_in_explorer(filename) # reveals file in Explorer for windows, Finder for OS X
text_from_user = SimpleGuiCreator.get_user_input "Input your name:" # these raise an exception if the user cancels the dialog,

Select-button prompt dialog:
if(SimpleGuiCreator.show_select_buttons_prompt("message title", :yes => 'text for the yes button', :no => 'text for the no button', :cancel => 'text for the cancel button') == :yes)
  # they chose the "yes" equivalent button...
end

etc. ...

It provies a few helper methods to the SimpleGuiCreator::ParseTemplate (and JFrame) classes, like:

#bring_to_front
#minimize
#maximize
#restore
#after_closed { ... }
#after_minimized { ... }

See the files lib/simple_gui_creator/swing_helpers.rb and lib/simple_gui_creator/jframe_helper_methods.rb.

It has helpers to playback/control audio files, like mp3's or wave's, starting/stopping asynchronously (see the files in the 'lib/simple_gui_creator/*' directory.
It has helpers to set/get system clipboard contents.
It has helpers to control/query the system mouse.
It has helpers to query the current system for its DVD drives, be notified when disks are inserted/changed, etc.


Even more complicated example:

---------- Optional Window Title -------------------------
| [a button:button1]   [button text:button2]             |
| "some text2:text1"                                     |
| [Editable Text Area with 4 rows   :text_area]          |
| [                                           ]          |
| [                                           ]          |
| [                                           ]          |
  "you can use height/width like 700, 700px, 1char, 3chars:"
| [Editable Text Field with 1 row and fixed spacing chars  :width=700px, height=1char, font=fixed_width]          
| [                                                                                                    ]          
| [Dropdown Default \/ :dropdown_name]                   |
| [Dropdown Default ▼  :dropdown_name2]                  |
| [✓:checkbox_name] "Some text"                         |
| [/:checkbox_name2] "You don't have to use unicode"     |
| [Start/Stop:start_stop_button,width=50chars]           |
| "How to end text that has a colon (:) with a colon:unused_name"
----------------------------------------------------------

An example that "grows" dynamically:
frame = SimpleGuiCreator::ParseTemplate.new "----my window title---"
frame.add_setup_string_at_bottom "[✓:button_1]"
frame.elements[:button_1].after_checked {
  puts 'you checked me'
}
frame.add_setup_string_at_bottom "[button 1:button_2]"
frame.elements[:button_2].after_unchecked {
  puts 'you unchecked me'
}

frame.elements[:button_2].set_unchecked! # default is to start checked, but always set them either way, just to be sure...

How to add your own spacing:
---------- Optional Window Title --------------------------------------
| "some text2:text1"                                                  |
| "          " "this text will be spaced to the right of the above"   |



Feedback/feature requests welcome.
http://groups.google.com/group/roger-projects,  roger-projects@googlegroups.com
I'd even be happy to wrap other gui frameworks (currently jruby/swing only) with the same functionality, 
if anybody wanted it.

== GUI Editor ==

It also comes with its own "test as you go" design builder helper GUI, programmed, appropriately enough, using simple gui creator.
$ jruby -S simple_gui_creator

This pulls up a window with some demo code, and some links that let you save it.  
It's almost more of a "demo of how using it looks like" (the bin/simple_gui_creator file) than a
real editing tool, but feature requests/suggestions wanted!

== Documentation ==

Basically, see this README file, the examples folder, the "bin/*" file, and also the specs and lib files themselves.
https://github.com/rdp/ruby_simple_gui_creator

== Known problems ==

Only Jruby today, which can make load times painful (hint: use splash screen).

= License ==

MIT license (which is quite open), see accompanying file license.mit.txt.
(C) 2012 Roger Pack