NOTE: This project is still in the design phase and nothing works.  Feel free
to look around, but don't expect any response to inqueries at this time.


|------------------------------------------------------------------------------|

Implementing this framework is simple:

* Create a project directory ~/my_project
* Create a ruby-mvc application file:

   file:  ~/my_project/lib/my_project.rb
   
require 'ruby-gmvc'
class MyProject < RMVC::DevApplication
end

* Run the application: 

Run the application (ruby ~/my_project/lib/my_project.rb).  Since it is
subclassed from RMVC::DevApplication, it will generate any files and
directories that it expects.  Since nothing exists at this point, a project
skeleton will be created.  Since the gtk2 support was required (ruby-gmvc),
support for Ruby-GNOME2 will be included. 

The application will end after building the scafolding as it hasn't been
programmed to do anything yet.

* Add a window:

Create a new glade file and put it in the gtk2/glade directory
(~/my_project/lib/my_project/lib/gtk2/glade/my_window.glade).  Edit the new
glade file and create a new top window.  Add some controls to it.  On the
top level window and/or on the controls defined within, add some signal
handlers.

* Run the application again

Run the application again (ruby ~/my_project/lib/my_project.rb).  Since
MyProject is still subclassed from RMVC::DevApplication, before actually
executing the application code, the framework will detect your new glade file
and automatically create the class files for it.  Specifically, the following
files are created:

 ~/my_project/lib/window/my_window.rb - this is based on the
 name of the glade file.  It is what your application will talk to when its
 ready to open the window and programatically interact with it.
 
 ~/my_project/lib/gtk2/view/my_window_window1.rb - this is based
 on the name of the glade file and the name of the top level window contained
 in it.  If multiple top level windows are defined in the glade file, each
 will get its own file.
 
 ~/my_project/lib/gtk2/controller/my_window_controller.rb - this
 is based on the name of the glade file.  All signal handlers defined in the
 glade file will have signal handlers defined in this file with the same name.
 
 ~/my_project/lib/model/my_window_model.rb - this is based on the
 name of the window, which in this case happens to be based on the name of the
 glade file.  The reason this is not stored in the gtk2 directory is because
 it is not dependant on gtk2.

* Tell your application to open the window

Modify your application file to open the window "my_window" when the
application starts.

   file:  ~/my_project/lib/my_project.rb

require 'ruby-gmvc'
class MyProject < RMVC::DevApplication
  def main
    self.open_window("my_window")
  end
end  If another windowing system like ncurses is used,
 you will want to create a ncmvc/windows/my_window.rb file which should
 implement the same my_window in the style of ncurses.  It will share the same
 my_window_model definition. 

* Once the application is completely written, change the application file so
  the application class is subclassed from RVMC::Application instead of 
  RVMC::DevApplication.  This will prevent the framework for looking for
  changes to integrate before starting up.
  
|------------------------------------------------------------------------------|
DevApplication startup design

* XMVC makes sure basic folder layout exists:
~/my_project
~/my_project/bin
~/my_project/lib
~/my_project/lib/model
~/my_project/lib/window
~/my_project/test

* GMVC makes sure gtk2 folder layout exists:
~/my_project/lib/gtk2
~/my_project/lib/gtk2/controller
~/my_project/lib/gtk2/glade
~/my_project/lib/gtk2/view

* XMVC makes sure project files exist
~/my_project/
~/my_project/Rakefile
~/my_project/README
~/my_project/bin/my_project
~/my_project/test/

* GMVC loops over all glade files (GMVC::GladeFile)
* Ask glade file if its new or changed
* If neither, remove from list of glade files to worry about
* Ask glade file to load its supporting files (if they exist)

** XMVC::WindowFile
* Nothing to double check.  If the file exists, assume it is good
* Module: XMVCApp
* Class: <GladeBaseName>
* Methods: -none-
* File name: project/lib/gtk2/<glade_base_name>.rb

** XMVC::ModelFile
* Nothing to double check.  If the file exists, assume it is good
* Module: XMVCApp
* Class: <WindowClassName>Model
* Methods: -none-
* File name: project/lib/model/<window_base_name>_model.rb

** GMVC::View
* Nothing to double check.  If the file exists, assume it is good
* Module: GMVCApp
* Class: <WindowClassName>View<TopLevelWindowNameInGladeFile>
* Methods: -none-
* File name: project/lib/gtk2/<window_base_name>_<top_level_window_name_in_glade_file>.rb

** GMVC::Controller
* Compare signals defined for window and make sure signal handlers are defined
* Module: GMVCApp
* Class: <WindowClassName>Controller
* Methods: handler method named after handler name listed in glade file
* File name: project/lib/gtk2/<window_base_name>_controller.rb



|------------------------------------------------------------------------------|

gtk notes

* Of of the process of elimination, the controller is responsible for the glade
  file.  Neither the model nor the window are gtk specific and there may be more
  than one view in a single glade file.



|------------------------------------------------------------------------------|

Opening windows:

The application talks to the Window class.

win = MyWindow.new
win[param] = 123
win.show(:modal, :maximized)
app.perform_window_events

The window is responsible for creating the model and the appropriate controller
and views for the current windowing system.  At this point, the model, views,
and controller work independently until the window is closed.  Afterwards, the
app can query the window for values from the window.

puts win.param

Multiple windows can share the same model if needed.

win1 = MyWindow.new
win1.open
win2 = MyWindow.new
win2.model = win1.model
win1.show
win2.show
app.perform_window_events




|------------------------------------------------------------------------------|

A XMVC::Application "talks" to a XMVC::Window.  XMVC::Window has a 1 to 1
relationship with a GMVC::Controller (or a controller from another windowing
system).  The difference is that a GMVC::Controller is specific to a windowing
system.  Also, a GMVC::Controller only handles user input and acts as the glue between
a XMVC::Model and a GMVC::View, where a XMVC::Window "talks" to the XMVC::Model,
allowing you to initialize the state of a window on the screen or to retrieve
information about a window after its closed.

A GMVC::View only displays the current state of the XMVC::Model.  Any input
from the user is handled by the GMVC::Controller, which is responsible for
either initiating a change in state in the XMVC::Model or changing the
GMVC::View (in a way that does not change the state of the XMVC::Model).
Consider this scenario:

# GMVC::Application code:
calc = CalculatorWindow.new
calc.show
app.perform_window_events

## The user selects the menu item View->Scientific

# GMVC::Controller code:
def on_view_scientific
  self.change_view(@views[:scientific])
end