context 0.0.16 → 0.0.22

data/README

@@ -0,0 +1,188 @@
+= Context - Contextual UI Framework
+
+Context is a contextual UI framework.  It is based on the Model View
+Presentor model.  The idea is that you have model objects that
+represent the core data in your application.  You also have views that
+represent the user interface input and output.  Finally you have
+"contexts" that represent a user situation in the application.  The
+logic that ties the models and views resides in the contexts.  The
+main advantages to this model are that you can easily write UI unit
+tests and you can easily create bridge patterns for supporting
+multiple widget sets (although only GTK+ is supported at the moment).
+Context is intended to be extremely minimal.  Only the top level
+abstract classes are included.  It is *not* a widget set!  You have to
+write your own models, views and contexts.
+
+Below you will find some usage examples and a detailed discussion
+of the design rationale.
+
+== Usage Examples
+
+== Design Rationale
+
+Probably the most common design structure for user interface
+design is Model, View, Controller (MVC).  While most people are
+familiar with this idiom, before I discuss Context I will
+explain MVC.  Hopefully this discussion will dispel possible
+sources of confusion.
+
+MVC is a common idiom intended to separate UI objects from
+non-UI objects so as to create a cleaner design that's
+easy to work with.  In MVC there are three main types
+of objects:
+
+* Model - Objects that represent the problem domain abstracted from the UI.
+* View - UI objects that represent how a user will *see* information.
+* Controller - Objects that represent the handling of input from the user.
+
+Exactly how the object model decomposition works, and where functionality
+is put is a source of much confusion amongst programmers.  And in fact,
+many so called MVC widget sets make it impossible to create controller
+objects at all.  The following is a description of my view of good
+MVC practice.  Keep in mind that it may differ from your own experience
+or practice.  But to keep the discussion relevant it helps to have
+a shared understanding of these issues.
+
+The easiest place to start discussing is the view.  The view represents
+the visual representation of the data in the UI.  So if you have
+some text, it is the text pane and the character glyphs that the
+user can see.  But it becomes more confusing when we talk about
+views which contain things like buttons.  What data does a button
+represent?
+
+Let's sidestep that issue for a second and discuss the model.  The
+model contains the problem domain objects.  So, if we have some data,
+the data objects are the model.  For textual data, we can create a
+view consisting of text panes and text that display that data.  The
+situation gets more complicated when we discuss something like a text
+editor.  The text buffer is clearly a model object, but in most widget
+sets there is a text input widget that contains a text buffer.  Can we
+use the widget's text input buffer for our model?  If so, how does
+that affect the separation of model from UI?  Again, let's defer this
+discussion for a few moments.
+
+Finally, we have the controller.  The controller represents the
+input.  I like to think of the controller as a state pattern
+with commands.  The UI sends user input to the controller.
+This creates commands (e.g., delete a character) and the state
+pattern interprets the commands, updating the model and views
+in doing so.  However, as with the view and model we run into
+confusion.  In most widget sets the input is handled by the individual
+widgets (or worse some arbitrary code in the widget library).
+This input can not be funnelled easily to a controller object
+to create commands.  Instead it updates it's own internal model
+and view.
+
+As you can see, in each case there is some confusion that
+can lead to poor separation of model from UI.  But I think there
+is an even greater problem.  Where does the problem domain
+*logic* go in an MVC program?  It might seem obvious that it
+will go into the model.  But from experience I have found this
+is rarely the case.  And with a little thought we can see why.
+
+When we think of model objects, it's quite easy to see where
+the data will go.  And we can also put methods on that data
+to create objects.  But the real user requirements of the
+program (i.e., the problem domain logic) often ends up in the
+controller and views.  Consider a user requirement for
+a fictitious program:
+
+   When the user presses "delete", the user is asked if they
+   really want to delete the record.  If they respond "yes",
+   then the record is deleted.  In this case, the table
+   display turns red and the next record is displayed.  If they
+   respond "no", the next record is displayed.
+
+Where would you write this code?  In the record object (which
+is clearly a model object)?  If so, how would you get the
+record object to create the view asking the user if they
+really want to delete the record? Then the controller receives
+responses from the UI.  How does it interrupt the logic
+of the model to tell it what to do?  And how/when do we update
+the view for the table?
+
+This is virtually impossible.  And keep in mind that the model
+almost certainly shouldn't know about the view and controller,
+since it represents only problem domain information and not UI.
+
+So the reality is that in complex MVC code, the problem domain
+*data* is kept in the model objects, while the *logic* is kept
+in the views and controllers.  So if you wanted, for instance,
+to adapt your program for a different widget library, you're pretty
+much out of luck -- the logic is spread all through the UI
+code.
+
+The thesis of Context is that most problems with MVC arise from
+it's inappropriate use.  MVC works extremely well for simple
+problems that don't contain a lot of logic.  But it scales
+poorly.  Where MVC works exceptionally well is for building
+widgets themselves.
+
+A widget, for example a text input widget, is self contained.
+You can have a model object representing a collection of
+strings.  You can have a view object representing how the
+widget is displayed on the window.  And you can have a
+controller object that takes input and updates the model
+and view.
+
+Context's idea is to implement these UI widgets using MVC
+and use a slightly *different* idiom for problem domain
+logic and data.  The following is Context's design for
+doing this.
+
+There are again 3 different types of objects:
+
+* Model -- These are true problem domain objects that represent the state of the running program.
+* Context -- This describes a user scenario with related UI.  It creates the appropriate Views, handles input, modifies the Model objects appropriatly and generates output.  It contains the user domain logic.
+* View -- Though related, this is not a traditional View at all.  It creates and maintains the MVC widgets for a visual context.  It takes output from the context and updates the widgets.  It takes input from the widgets, and sends it to the context.
+
+Often there is a single View for each context.  However, there is no
+reason that a context can't have several Views, or that several
+contexts can't share a View.  Also, there is usually an abstract View
+(which defines the input and output that it handles) and a concrete
+View (which implements the real widgets).
+
+Model objects are pretty self explanatory.  The only issue is that
+the Model objects should not reference any of the contexts nor
+should they reference any of the Views or widgets.  They are truly
+Model domain objects.
+
+Views are not really like MVC Views at all.  The abstract Views simply
+define the interface for both input and output.  Output is generally
+Model objects that need to be Viewed by the user.  In the concrete
+Views, the data from the Model objects is displayed in widgets.
+Input consists of commands generated from input from the widgets.
+Under no circumstances should the Views update a real Model object.
+Instead they should create a command which it passed back to the
+context which updates the Model.
+
+You can think of the abstract View as the conduit for I/O.  The
+concrete View implements the endpoint for that conduit.  As much
+as possible, the View should contain no problem domain logic.  Anything
+that is a requirement for the user should be implemented in the
+context.  Automated acceptance tests should be written against
+the context without regard to the concrete
+
+The Context contains the problem domain logic.  It is reposonsible for
+creating and destroying the views, sending data for the View to
+display and interpreting commands from the View's input.  However,
+because the Context has references only to the abstract Views, it is
+shielded from the widget library implementation details.  Thus, if you
+wish to port the program to another widget library you simply need to
+rewrite concrete View classes.
+
+Note that the Model should never reference eithe the Context or the
+View.  The View may reference the Model objects to display them, but
+it should not update them directly. If the View needs to update a
+model object, it should create a command and send it to the context.
+The Context can reference both the Model objects (including updating
+them) *and* it can reference the abstract Views.  It should not,
+however, reference the concrete Views.
+
+Note: In practice I rarely make actual command objects for the Views
+to send to the Context.  Instead I have them simply call a method on
+the Context.  In truth this somewhat breaks the model that the View
+know nothing about the Context.  However, since ruby is a message
+passing language, a method call *is* a command of a sort.  So I'll do
+this for efficiency.  In this case, you should implement
+method_missing on the Context object.

data/Rakefile.rb

@@ -1,11 +1,26 @@
 require 'rake'
+require 'rubygems'
 require 'spec/rake/spectask'
+# Debian forces the installation of a very old version of rdoc
+# in /usr/lib/ruby if you install rubygems.  So I need to override
+# it here.
+gem 'rdoc', ">= 2.2"
+require 'rdoc'
 require 'rake/rdoctask'
-require 'rubygems'
 require 'rake/gempackagetask'
 require 'rake/testtask'
+require 'fileutils'
 require 'lib/Context/Version'
 
+#======================== Setup ================================
+
+# Rubyforge details
+rubyforge_project = "jldrill"
+rubyforge_maintainer = "mikekchar@rubyforge.org"
+
+
+# Spec options
+spec_opts = ['-f html:test_results.html']
 spec_files = FileList[
 	'spec/**/*_spec.rb'
 ]
@@ -23,40 +38,34 @@ pkg_files = FileList[
 ]
 
 
-task :default => [:rcov, :rdoc]
+task :default => [:spec]
 
+desc "Run the tests (default).  Output goes to test_results.html"
 st = Spec::Rake::SpecTask.new(:spec) do |t|
 	t.spec_files = spec_files
 	t.ruby_opts = ruby_opts
+    t.spec_opts = spec_opts
 end
 
+desc "Run the tests and find the code coverage.  Test results are in test_results.html.  Coverage is in coverage/index.html"
 rc = Spec::Rake::SpecTask.new(:rcov) do |t|
 	t.spec_files = spec_files
 	t.rcov = true
 	t.rcov_opts = ["--exclude rspec", "--exclude rcov", "--exclude syntax", 
 	    "--exclude _spec"]
-	t.spec_opts = ["--format html:test_results.html"]
-	t.ruby_opts = ruby_opts
+    t.spec_opts = spec_opts
+    t.ruby_opts = ruby_opts
 end
 
-ht = Spec::Rake::SpecTask.new(:heckle) do |t|
-	t.spec_files = spec_files
-	t.spec_opts = ["--heckle Context"]
-	t.ruby_opts = ruby_opts
-end
-
-# Build the RDOC documentation tree.
+desc "Build the RDOC development documentation. output goes to doc/index.html"
 rd = Rake::RDocTask.new(:rdoc) do |t|
 	t.rdoc_dir = 'doc'
 	t.title    = "Context -- Contextual UI Framework"
-	t.options << '--inline-source' <<
-		'--main' << 'Context' <<
+	t.options << '--main' << 'README' <<
 		'--title' <<  "Context -- Contextual UI Framework"
-	t.rdoc_files.include('./lib/**/*.rb')
+	t.rdoc_files.include('README', 'COPYING', 'AUTHORS', './lib/**/*.rb', './spec/**/*.rb')
 end
 
-# Build tar, zip and gem files.
-# NOTE: The name of this task is automatically set to :package
 gem_spec = Gem::Specification.new do |s|
     
 	#### Basic information.
@@ -89,6 +98,10 @@ gem_spec = Gem::Specification.new do |s|
     # Use these for libraries.
 	s.require_path = 'lib'
 
+	#### Dependencies
+    
+    s.add_dependency("gtk2")
+
     #### Documentation and testing.
 	s.has_rdoc = true
 	s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
@@ -98,10 +111,43 @@ gem_spec = Gem::Specification.new do |s|
 	s.author = "Mike Charlton"
 	s.email = "mikekchar@gmail.com"
 	s.homepage = "http://sakabatou.dnsdojo.org"
+    s.rubyforge_project = rubyforge_project
 end
 
+desc "Creates the gem files for context.  Packages are placed in pkg and called context-<version>.gem."
 package_task = Rake::GemPackageTask.new(gem_spec) do |pkg|
-	pkg.need_zip = true
-	pkg.need_tar = true
+	pkg.need_zip = false
+	pkg.need_tar = false
+end
+
+desc "Cleans the debian tree."
+task :clean_debian do
+    FileUtils.rm_rf "debian/libcontext-ruby"
+    FileUtils.rm_rf Dir.glob("debian/*debhelper*")
+    FileUtils.rm_rf "debian/files"
+    FileUtils.rm_rf "configure-stamp"
+    FileUtils.rm_rf "build-stamp"
+end
+
+desc "Cleans everything for a pristine source directory."
+task :clean => [:clobber_rcov, :clobber_rdoc, :clobber_package, :clean_debian]
+
+desc "Create the debian source tree and copy the required files over.  The files will end up in debian/libcontext-ruby"
+task :debian_dir => [:clean_debian, :rdoc] do
+    # Create the new directory structure
+    FileUtils.mkdir_p "debian/libcontext-ruby/usr/lib/ruby/1.8"
+    FileUtils.mkdir_p "debian/libcontext-ruby/usr/share/doc/libcontext-ruby/html"
+    
+    # Copy the libcontext-ruby files
+    FileUtils.cp_r Dir.glob("lib/*"), "debian/libcontext-ruby/usr/lib/ruby/1.8"
+    FileUtils.cp_r Dir.glob("doc/*"), "debian/libcontext-ruby/usr/share/doc/libcontext-ruby/html"    
+end
+
+desc "Clean everything, run tests, and build all the documentation."
+task :build => [:clean, :rcov, :rdoc]
+
+desc "Build a debian package. Note: This will *not* make a source package.  Also, the .deb and .changes file will be put in the parent directory."
+task :deb => [:clean_debian] do
+    sh "dpkg-buildpackage -b -tc -rfakeroot -i.bzr"
 end
 

data/lib/Context/Bridge.rb

@@ -1,5 +1,3 @@
-require 'Context/ExecutionProxy'
-
 module Context
 
     # This class is used to specify the namespace for a symbol
@@ -31,11 +29,14 @@ module Context
 		# Evaluate the module and symbol, returning the class.
 		# If it doesn't exist, return nil
 		def evalClass(mod, symbol)
-		    begin
-    		    mod.unless_nil do class_eval(symbol.to_s) end
-    		rescue
-    		    nil
+            retVal = nil
+            if !mod.nil?
+                begin
+                    retVal = mod.class_eval(symbol.to_s)
+                rescue
+                end
     		end
+            return retVal
 		end
 		
 		# Returns true if the mod and symbol evaluate to a class in the system.

data/lib/Context/Context.rb

@@ -1,5 +1,3 @@
-require 'Context/KeyMap'
-require 'Context/ExecutionProxy'
 
 module Context
 
@@ -18,7 +16,7 @@ module Context
     # is called on enter(), not on Context creation.  However, there is
     # no requirement for this.
 	class Context
-		attr_reader :parent, :mainView
+		attr_reader :parent, :mainView, :viewBridge
 		attr_writer :mainView
 
         # Create a new Context.  Takes a Bridge that is used to
@@ -27,8 +25,8 @@ module Context
 			@parent = nil
 			@mainView = nil
 			@viewBridge = viewBridge
-			@keyMap = KeyMap.new
 			@entered = false
+            @onExitBlock = nil
 		end
 
         # Creates the views for the context.  This method is called
@@ -95,6 +93,15 @@ module Context
 		def isEntered?
 		    @entered
 		end
+
+        # Set a block to be called when the context exits.
+        # Often a context is exited by the result of some UI activity
+        # at some unknown point in the future.  The caller of the context
+        # may want to do something after the context exits.  This block
+        # will be called at the end of the exit method.
+        def onExit(&block)
+            @onExitBlock = block
+        end
 		
 		# Exits the Context.  After it is called, the context is no longer
 		# active and can't be interacted with.  This method automatically
@@ -109,38 +116,10 @@ module Context
                 @parent.mainView.removeView(@mainView) unless @mainView.nil?
             end
             destroyViews
+            if !@onExitBlock.nil?
+                @onExitBlock.call
+            end
 		end
 		    
-		# Sets a binding for a key.
-		# Whenever a key is pressed, the context is notified.  This
-		# sets up a binding between the key and the block passed in.
-		# After that point, the block will be called everytime the
-		# key is pressed.
-		#
-		# Warning: This key binding mechanism is likely to be
-		# depracated, or at least heavily modified soon.
-		def setKeyBinding(key, &binding)
-		    a = KeyAssignment.new(key, &binding)
-		    @keyMap.add(a)
-		end
-		
-		# Returns the existing binding for a key.
-		#
-		# Warning: This key binding mechanism is likely to be
-		# depracated, or at least heavily modified soon.
-		def getKeyBinding(key)
-		    a = @keyMap.findKey(key)
-		    a.unless_nil.action
-		end
-		
-		# Called by the view to indicated that a key has been pressed.
-		# Runs the binding in the keymap, or returns nil if there
-		# isn't one.
-		#
-		# Warning: This key binding mechanism is likely to be
-		# depracated, or at least heavily modified soon.
-		def notifyKey(view, key)
-		    @keyMap.unless_nil do press(key) end
-		end
 	end
 end

data/lib/Context/Gtk/Widget.rb

@@ -1,57 +1,163 @@
 require 'Context/Widget'
+require 'Context/Log'
 require 'gtk2'
 
 module Context::Gtk
+    include Context::Widget
 
-	class Widget < Context::Widget
-	    attr_reader :mainWindow, :expandHeight, :expandWidth
-	    attr_writer :mainWindow, :expandHeight, :expandWidth
-	    
-	    class << self
-	        # Redefine this in tests so that the widgets don't get displayed
-	        # on the screen.
-	        def inTests
-	            false
-	        end
-	    end
+    # This is a set of routines for translating the requests
+    # from Context to the specific widgit set.
+    #
+    # Note: If you wish your widget to be able to add and removed
+    #       other widgets (i.e. if it can act as a container), then
+    #       please define the following two methods on your object.
+    #
+    #       gtkAddWidget(widget) -- simply adds the passed widget to
+    #                               the correct Gtk container.  Normally
+    #                               this can be implemented using add().
+    #                               However, for some things like tables
+    #                               you will have to use other methods.
+    #       gtkRemoveWidget(widget) -- removes the passed widget from
+    #                                  the correct Gtk container.  Again
+    #                                  you will normally implement this
+    #                                  with remove().
+    #
+    #       The following also need to be defined if your widget is
+    #       not derived from a Gtk:Widget.
+    #
+    #       show_all() -- Displays the widgets.
+
+	module Widget
+	    attr_reader :gtkWidgetMainWindow
+	    attr_writer :gtkWidgetMainWindow
 	    
-	    def initialize(delegate)
-	        super(delegate)
-	        @mainWindow = nil
+	    def setupWidget
+	        @gtkWidgetMainWindow = nil
 	        # Packing hints for the container
-	        @expandHeight = false
-	        @expandWidth = false
+	        @gtkWidgetExpandHeight = false
+	        @gtkWidgetExpandWidth = false
+            @gtkWidgetAddedToCallback = nil
+            @gtkWidgetRemovedFromCallback = nil
 	    end
 	    
+        # Declares that this widget is a main Window
+        # Normally, this will get set for you if the widget you are
+        # adding is derived from Gtk::Window.  But you can set it
+        # explicitly for certain effects if you know what you are doing.
 	    def isAMainWindow
-	        @mainWindow = @delegate
+	        @gtkWidgetMainWindow = self
 	    end
+
+        # When adding the widget, expand it to take up all the allocated
+        # vertical height.
+        def expandWidgetHeight
+	        @gtkWidgetExpandHeight = true
+        end
+
+        # Returns true when the the widget should take up all the allocated
+        # vertical height.
+        def expandWidgetHeight?
+            @gtkWidgetExpandHeight
+        end
+
+        # When adding the widget, expand it to take up all the allocated
+        # horizontal width.
+        def expandWidgetWidth
+	        @gtkWidgetExpandWidth = true
+        end
 	
-		def add(widget)
-   		    if !widget.delegate.class.ancestors.include?(Gtk::Window)
-    		    widget.mainWindow = @mainWindow
-    			@delegate.add(widget.delegate)
-    			if !Widget.inTests
-            		@delegate.show_all
+        # Returns true when the the widget should take up all the allocated
+        # horizontal width.
+        def expandWidgetWidth?
+            @gtkWidgetExpandWidth
+        end
+
+        # Use this widget as a container for the passed widget.
+        # Calls gtkAddWidget, which you must define on the object.
+        # Normally this will simply call add() in the correct container.
+        # Also calls show_all, which you must define on the object
+        # (if it isn't already).
+		def addToThisWidget(widget)
+   		    if !widget.class.ancestors.include?(Gtk::Window)
+    		    widget.gtkWidgetMainWindow = @gtkWidgetMainWindow
+    			gtkAddWidget(widget)
+    			if !isInTests?
+            		show_all
                 end
     	    else
     	        widget.isAMainWindow
-    	        widget.delegate.set_transient_for(@mainWindow)
-    	        if !Widget.inTests
-        		    widget.delegate.show_all
+    	        widget.set_transient_for(@gtkWidgetMainWindow)
+    	        if !isInTests?
+        		    widget.show_all
         		end
     	    end
 		end
 
-        def remove(widget)
-            widget.mainWindow = nil
-   		    if !widget.delegate.class.ancestors.include?(Gtk::Window)   
-                @delegate.remove(widget.delegate)
-                if !Widget.inTests
-                    @delegate.show_all
+        # Remove the passed widget from this object.
+        # Calls gtkRemoveWidget, which you must define on the object.
+        # Normally this will simply call remove().
+        # Also calls show_all, which you must define on the object
+        # (if it isn't already).
+        def removeFromThisWidget(widget)
+            widget.gtkWidgetMainWindow = nil
+   		    if !widget.class.ancestors.include?(Gtk::Window)   
+                gtkRemoveWidget(widget)
+                if !isInTests?
+                    show_all
                 end
             end
-            @delegate.grab_focus
+        end
+
+        # Set a closure to be run when the widget has been
+        # added.  The block must accept the container widget
+        # as a parameter.
+        def afterWidgetIsAdded(&block)
+            @gtkWidgetAddedToCallback = block
+        end
+
+        # Set a closure to be run when the widget has been
+        # removed.  The block must accept the container widget
+        # as a parameter.
+        def afterWidgetIsRemoved(&block)
+            @gtkWidgetRemovedFromCallback = block
+        end
+
+		# This method is called after the widget has been
+		# successfully added to another widget
+		def widgetWasAddedTo(widget)
+            if !@gtkWidgetAddedToCallback.nil?
+                @gtkWidgetAddedToCallback.call(widget)
+            end
+		end
+		
+		# This method is called after the widget has been
+		# successfully removed from another widget
+		def widgetWasRemovedFrom(widget)
+            if !@gtkWidgetRemovedFromCallback.nil?
+                @gtkWidgetRemovedFromCallback.call(widget)
+            end
+		end
+
+        # Helper method for testing.  If this method is redefined to
+        # return true, then the items will not be shown on the screen.
+        def isInTests?
+            false
+        end
+
+        # Default method for adding a widget.  Simply logs an warning.
+        # It does not add the widget.
+        def gtkAddWidget(widget)
+            Context::Log::warning("Context::Widget", 
+                                  "Attempted to add a widget " +
+                                  "to #{self.class} which doesn't define " +
+                                  "gtkAddWidget(). Ignoring addition.")
+        end
+
+        def gtkRemoveWidget(widget)
+            Context::Log::warning("Context::Widget", 
+                                  "Attempted to remove a widget " +
+                                  "from #{self.class} which doesn't define " +
+                                  "gtkRemoveWidget(). Ignoring removal.")
         end
 	end
 end