fxruby-enhancement 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 815c35e0699b8a7cb0bc90b27f21789751af71fd
+  data.tar.gz: c9cc4a024a7493888bc3e27ec96a319e1b8a1a63
+SHA512:
+  metadata.gz: 5e6d8150e9bb259e6bf9b12c63a1e874e6ebcc9ead1594cfc5cf0fd0f12d307e712bdfbe6cd92ba0ec68cfb98c8b0847ddc0430c63fe1337b0c756436a0ce304
+  data.tar.gz: 36efe40ce1f47ab9d7a4623ede142171856c4648e45ba1a7c51bdfb67151774d7d35c615c0d7b57fa833a8fd4f0167f3ff637ed3ae3288cd17fc60e1c9230a41

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "fxruby"]
+	path = fxruby
+	url = git@github.com:larskanis/fxruby.git

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-version

@@ -0,0 +1 @@
+2.4.0

data/.semver

@@ -0,0 +1,6 @@
+---
+:major: 0
+:minor: 0
+:patch: 2
+:special: ''
+:metadata: ''

data/Gemfile

@@ -0,0 +1,22 @@
+source "https://rubygems.org"
+
+gem "semver2", "~> 3"
+gem "fxruby", "~> 1.6"
+gem "awesome_print", ">= 1"
+gem "json", "~> 2.0", ">= 2.0.2"
+gem "queue_ding", "~> 0"
+
+group :development do
+  gem "rspec", "~> 3"
+  gem "yard", "~> 0.7"
+  gem "rdoc", "~> 5"
+  gem "bundler", "~> 1.0"
+  gem "juwelier", "~> 2"
+  gem "simplecov",          ">= 0"
+  gem "pry",                ">= 0"
+  gem "pry-byebug",         ">= 3"
+  gem "pry-doc",            ">= 0"
+  gem "pry-remote",         ">= 0"
+  gem "pry-rescue",         ">= 1"
+  gem "pry-stack_explorer", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,131 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.4.0)
+    aquarium (0.5.1)
+    awesome_print (1.7.0)
+    binding_of_caller (0.7.2)
+      debug_inspector (>= 0.0.1)
+    builder (3.2.2)
+    byebug (9.0.6)
+    coderay (1.1.1)
+    debug_inspector (0.0.2)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    fxruby (1.6.34)
+      mini_portile (~> 0.6)
+    git (1.3.0)
+    github_api (0.14.5)
+      addressable (~> 2.4.0)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.4)
+      oauth2 (~> 1.0)
+    hashie (3.4.6)
+    highline (1.7.8)
+    interception (0.5)
+    json (2.0.2)
+    juwelier (2.3.4)
+      builder
+      bundler (>= 1.13)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      psych (~> 2.2)
+      rake
+      rdoc
+      semver2
+    jwt (1.5.6)
+    method_source (0.8.2)
+    mini_portile (0.6.2)
+    mini_portile2 (2.1.0)
+    multi_json (1.12.1)
+    multi_xml (0.6.0)
+    multipart-post (2.0.0)
+    nokogiri (1.7.0.1)
+      mini_portile2 (~> 2.1.0)
+    oauth2 (1.3.0)
+      faraday (>= 0.8, < 0.11)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (>= 1.2, < 3)
+    pry (0.10.4)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    pry-byebug (3.4.2)
+      byebug (~> 9.0)
+      pry (~> 0.10)
+    pry-doc (0.10.0)
+      pry (~> 0.9)
+      yard (~> 0.9)
+    pry-remote (0.1.8)
+      pry (~> 0.9)
+      slop (~> 3.0)
+    pry-rescue (1.4.4)
+      interception (>= 0.5)
+      pry
+    pry-stack_explorer (0.4.9.2)
+      binding_of_caller (>= 0.7)
+      pry (>= 0.9.11)
+    psych (2.2.2)
+    queue_ding (0.1.5)
+      aquarium (~> 0)
+      json (~> 2.0, >= 2.0.2)
+      semver2 (~> 3)
+    rack (2.0.1)
+    rake (12.0.0)
+    rdoc (5.0.0)
+    rspec (3.5.0)
+      rspec-core (~> 3.5.0)
+      rspec-expectations (~> 3.5.0)
+      rspec-mocks (~> 3.5.0)
+    rspec-core (3.5.4)
+      rspec-support (~> 3.5.0)
+    rspec-expectations (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-mocks (3.5.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.5.0)
+    rspec-support (3.5.0)
+    semver2 (3.4.2)
+    simplecov (0.12.0)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    slop (3.6.0)
+    thread_safe (0.3.5)
+    yard (0.9.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print (>= 1)
+  bundler (~> 1.0)
+  fxruby (~> 1.6)
+  json (~> 2.0, >= 2.0.2)
+  juwelier (~> 2)
+  pry
+  pry-byebug (>= 3)
+  pry-doc
+  pry-remote
+  pry-rescue (>= 1)
+  pry-stack_explorer
+  queue_ding (~> 0)
+  rdoc (~> 5)
+  rspec (~> 3)
+  semver2 (~> 3)
+  simplecov
+  yard (~> 0.7)
+
+BUNDLED WITH
+   1.13.6

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2016 Fred Mitchell
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.org

@@ -0,0 +1,861 @@
+#+OPTIONS: broken-links:mark
+* Table of Contents                                                     :TOC_5_gh:
+ - [[#fxruby-enhancement][fxruby-enhancement]]
+   - [[#introduction][Introduction]]
+   - [[#installation][Installation]]
+   - [[#documentation][Documentation]]
+     - [[#in-general][In General]]
+     - [[#execution-phases-of-fxruby-enhancement][Execution Phases of fxruby-enhancement]]
+       - [[#declarative][Declarative]]
+       - [[#fxruby-instantiation][FXRuby Instantiation]]
+       - [[#fox-toolkit-instantiation][FOX Toolkit instantiation]]
+     - [[#events-from-other-threads][Events from other Threads]]
+       - [[#the-queue_ding-queues][The Queue_Ding Queues]]
+         - [[#enhancementingress][Enhancement.ingress]]
+         - [[#enhancementegress][Enhancement.egress]]
+       - [[#api--dsl][API & DSL]]
+         - [[#ref-refc-and-tagging-your-objects][ref(), refc() and tagging your objects]]
+         - [[#fox_component-and-fox_instance][fox_component and fox_instance]]
+         - [[#fx_app][fx_app]]
+         - [[#instance][instance]]
+         - [[#ingress_handler][ingress_handler]]
+         - [[#deferred_setup][deferred_setup]]
+         - [[#mapping-between-fx_-declarations-and-the-fx-fxruby-objects][Mapping between fx_* declarations and the FX* FXRuby objects]]
+         - [[#bindingfx][binding.fx]]
+     - [[#examples][Examples]]
+       - [[#hello-world-example-full-the-enhancement-way][Hello World example (full) the Enhancement Way]]
+       - [[#hello-world-the-old-fxruby-way][Hello World the old fxruby way:]]
+       - [[#bouncing-ball-example-full][Bouncing Ball example (full):]]
+       - [[#bouncing-ball-the-old-fxruby-way][Bouncing Ball the old fxruby way:]]
+   - [[#release-notes][Release Notes]]
+   - [[#known-issues][Known Issues]]
+   - [[#contributing-to-fxruby-enhancement][Contributing to fxruby-enhancement]]
+   - [[#copyright-and-licensing][Copyright and Licensing]]
+   - [[#the-junkyard--scratchpad][The Junkyard / Scratchpad]]
+     - [[#genesis-of-the-meta-meta-programming-whereby-brain-goes-boom][Genesis of the meta-meta programming, whereby brain goes boom]]
+
+* fxruby-enhancement
+** Introduction
+   The fxruby library is an excellent wrapper for the FOX toolkit.
+   However, it reflects the C++-ness of FOX, rather than being more
+   Ruby-like. As such, creating composed objects with it tends to be
+   rather ugly and cumbersome. For every new component you create with
+   fxruby, you are handed back a reference to that object, which you'll
+   need to store somewhere. And then all the subsequent child objects
+   will need to be passed pointers to the parent objects.
+
+   So, if you need to redo a layout, it becomes a messy exercise.
+
+   fxruby-enhancement makes this a snap to do. You simply declare
+   your GUI arrangement in a nested fashion. fxruby-enhancement will
+   take care of passing parents to the nested children, and other issues
+   as well. You can now focus on creating a good GUI layout that you
+   can change on the fly without much fuss and bother.
+
+   fxruby-enhancement is basically a DSL of sorts, and every effort has
+   been taken to make it intuitive to use. Once you get the hang of it,
+   you should be able to look at the FXRuby API documentation and infer
+   the DSL construct for fxruby-enhancement. Please also see the many
+   [[file:examples][examples]].
+   
+** Installation
+   To install the gem from commandline:
+
+   #+begin_src bash
+   gem install fxruby-enhancement
+   #+end_src
+
+   In your Gemfile:
+
+   #+begin_src ruby
+   gem "fxruby-enhancement", "~> 0"
+   #+end_src
+
+   fxruby-enhacement depends on fxruby version 1.6, and
+   will automatically include it. However fxruby has a c-extension
+   that must compile properly on your system. Normally, this is not
+   a concern, but it is something to be aware of.
+
+** Documentation
+*** In General
+    fxruby-enhancement (which we will refer to as "Enhancement" from time
+    to time) makes use of the singleton pattern in Ruby. There is basically
+    no need to declare subclases off of most FXRuby classes. This is a very
+    C++ish way, and the way the C++ Fox Toolkit works. It will make most
+    hard-core Rubyists gnash their teeth.
+
+    Here, we do away with all of it. Also, the SEL_x variables -- which maps
+    to the C++ #defines of the same -- is replaced with method declarations
+    of the nature of sel_x -- just the lowercase version of the same. For instance,
+    in the straight fxruby, you would have to do something like:
+
+    #+begin_src ruby
+    @canvas.connect(SEL_PAINT) { |sender, sel, evt|
+      FXDCWindow.new(sender, evt) { |dc|
+        dc.drawImage(@backBuffer, 0, 0)
+      }
+    #+end_srcv
+
+    but with Enhancement, you do it thusly:
+
+    #+begin_src ruby
+    instance { |c|
+      c.sel_paint { |sender, sel, event|
+        FXDCWindow.new(sender, event) { |dc|
+          dc.drawImage(ref(:back_buffer), 0, 0)
+        }
+      }
+    }
+    #+end_src
+    
+    And here we illustrate something else, the instance declaration. Why do
+    we do it this way? Because Enhancement is multi-phase. First, we declare
+    the GUI layout with Enhancement. At this time, none of the underlying
+    FXRuby objects exist yet, but need to be referenced anyway. So we defer
+    that part where references need to be resolved to the instance claus,
+    which, as you can well imagine, means the FXRuby object instances have
+    been instantiated.
+
+    You will also note the use of the ref clause, as in:
+    #+begin_src ruby
+    dc.drawImage(ref(:back_buffer), 0, 0)
+    #+end_src
+    
+    When the :back_buffer object was declared, it was done thusly:
+    #+begin_src ruby
+    fx_image(:back_buffer) { opts IMAGE_KEEP }
+    #+end_src
+
+    So when the actual FXImage object is instantiated, it is associated to
+    the :back_buffer tag, which then is found by ref() and can be used
+    anywhere in the instantiation phase.
+*** Execution Phases of fxruby-enhancement
+    This represents the work flow, in the order stated:
+    | State                     | Description                                                                                                                  |
+    |---------------------------+------------------------------------------------------------------------------------------------------------------------------|
+    | Declarative               | The basic GUI layout is declared by the DSL, but it is not instantiated yet.                                                 |
+    | FXRuby instantiation      | All the basic underlying FXRuby object are instantiatied, but the foundational FOX Toolkit Objects are not instantiated yet. |
+    | FOX Toolkit instantiation | The FOX Toolkit C++-level objects are now alive and kicking.                                                                 |
+
+**** Declarative
+     This phase, under the proverbial hood, ceates the component objects,
+     which are just place-holders for the underlying FXRuby objects.
+
+     When the FXRuby object is created, it is assigned to its place holder
+     component object, and can be references as comp.inst. In most cases,
+     you will almost never need to touch the component objects directly.
+**** FXRuby Instantiation
+     During the FXRuby instantiantion stage, all of the FXRuby
+     objects are instantiated and stored in their respective
+     component objects. If they are tagged, the instantiated
+     object may be referenced with ref(), and the component 
+     object itself may be referenced via refc(). There is almost 
+     never a case where you would need to go after the component
+     object directly.
+**** FOX Toolkit instantiation
+     All of the FOX Toolkit C++ objects, resources, etc. that
+     correspond to the FXRuby objects are now set up, and activated.
+     With the all-important "show PLACEMENT_SCREEN" command, the
+     FOX GUI should now be visible.
+*** Events from other Threads
+    In handling interfacing to databases, AMQPs like RabbitMQ,
+    network connections, or just about anything else that might otherwise
+    slow down the GUI (Fox) thread and make it non-responsive, there needs 
+    to be a clean way to get data into and out of the GUI thread.
+
+    Fox provides some mechanisms specifically for sockets or system-level IO,
+    but these are too specific, and would require some awkard workarounds to
+    make them work in the general context.
+
+    And so we provide a means to accomplish that in a clean -- to you, anyway --
+    manner. We make use of queue_ding queues for passing messages into and out of
+    the FXRuby (and therefore FXRuby Enhancement) space. This will allow you to
+    keep the GUI thread responsive and also to maintain a seperation of concerns.
+**** The Queue_Ding Queues
+     [[ttps://github.com/flajann2/queue_ding][Queue Ding]] is an enhancement for doing queing across threads in Ruby,
+     and we offer it here to allow external events to be funneled into and
+     out of the Fox GUI thread. Usage is easy and straightforard. When
+     removing entries from Queue Ding using #next, the queue will block until
+     the next entry arrives. Since Queue Ding is really derived from ::Array,
+     you may also do thing like #empty? to check to see if entries are availabe
+     to avoid blocking.
+***** Enhancement.ingress
+      To get messages objects into fxruby_enhacement, simply #push or #<<
+      it into the queue as shown:
+      #+begin_src ruby
+      Enhancement.ingress << [:some_tag, some_payload]
+      #+end_src
+
+      In the DSL, you must set up a handler for the ingress,
+      #+begin_src ruby
+      ingress_handler :status do |tag, payload|
+        puts "received #{tag} => #{payload}"
+      end
+      #+end_src
+
+      And so your handler will most likely act as a dispatcher
+      for the payloads received. For example:
+      #+begin_src ruby
+      ingress_handler :status do |tag, logline|
+        puts "received #{tag} => #{payload}"
+        case tag
+        when :log_info
+          ref(:logging_info).appendItem logline
+        when :log_error
+          ref(:logging_error).appendItem logline
+        end
+      end
+      #+end_src
+
+***** Enhancement.egress
+      Wnen your Fox application needs to send a message to other
+      listening threads, You simply push your payload onto the egress queue
+      thusly:
+      #+begin_src ruby
+      Enhancement.egress << [:button_clicked, "I was clicked!"]
+      #+end_src
+
+      and your Ruby thread external to Fox would simply do:
+      #+begin_src
+      #+end_src
+
+**** API & DSL
+***** ref(), refc() and tagging your objects
+      In an effort to eliminate the fuss and bother with
+      scoping issues and object reference, ref(:some_tag) will
+      retrive the FXRuby instance object so tagged with :some_tag.
+
+      You may have anonymous, i.e., untagged objects, and those will
+      not be findable by ref(). It is not necessary to tag all objects,
+      either.
+
+      refc() is similar to ref(), except it retrives the underlying 
+      component object insted. Indeed, the following are equivalent
+      operations:
+      #+begin_src ruby
+      ref(:some_tag)
+      refc(:some_tag).inst
+      #+end_src
+
+      There may be some edge cases where you might want to
+      reference the underlying component ahead of FXRuby object
+      instaniation, but in the vast majority of the cases, it should
+      be unnecessary. My goal is to enable to do what you need, not
+      to restrict you. You may need it for debugging, etc.
+
+      Underlying, the component object is really a subclass of OpenScript.
+      While you may like to stuff some additional data there, 
+      this is frowned upon because it might conflict with Enhancement.
+      If you have a need for this, please do a issue in GitHub.
+
+***** fox_component and fox_instance
+      fox_component and fox_instance are roughly the
+      equivalent of refc() and ref(), respecively. The
+      difference mainly being that fox_component does no
+      sanity checking, and is therefore slightly faster.
+
+      At some point, they may be merged, but for now don't 
+      count on it.
+
+      To initialize and run your app, you customairly do the
+      following:
+      #+begin_src ruby
+      fox_component :app do |app|
+        app.launch
+      end
+      #+end_src
+
+      Which presumes your fx_app declaration was tagged with
+      :app as follows:
+      #+begin_src ruby
+      fx_app :app do
+        app_name "Your Amazingly Cool Application"
+        vendor_name "YouDaMan"
+        ...
+      end
+      #+end_src
+
+      This is the only time you will reference the component
+      object directly for the obvious reason that you must start
+      from someonere.
+
+***** fx_app
+      To begin the declaration of your app, you must do the
+      following somewhere:
+      #+begin_src ruby
+      fx_app :app do
+        app_name "The Forbin Project"
+        vendor_name "Colossus"
+        ...
+      end
+      #+end_src
+
+      Typeically you'd do this inside of a module, but you could do it also
+      in a class body. Please see the examples.
+
+***** TODO instance
+***** TODO ingress_handler
+***** TODO deferred_setup
+***** TODO Mapping between fx_* declarations and the FX* FXRuby objects
+***** binding.fx   
+      This is a way to split up your layouts into different .fx "modules", purely for
+      organizational reasons. For example,
+
+      #+begin_src ruby
+      binding.fx "overview"
+      #+end_src
+
+      will load the overview.fx portion of the GUI, which happens to be a tab contents
+      in the tab book, which in our case looks like:
+
+      #+begin_src ruby
+      # Overview Tab
+
+      fx_tab_item { text "&Overview" }
+      fx_horizontal_frame (:overview_info) {
+        opts STD_FRAME|LAYOUT_FILL_Y
+  
+        fx_group_box (:ov_connections_group) {
+          text "Connections"
+          opts STD_GROUPBOX|LAYOUT_FILL_Y
+    
+          fx_vertical_frame {
+            opts LAYOUT_FILL_Y|LAYOUT_FILL_X #|PACK_UNIFORM_HEIGHT
+      
+            fx_group_box (:ov_conn_rabbitmq) {
+      ...
+      #+end_src
+    
+*** Examples
+    Class-based enhancement (this has not been tested yet!!!):
+    #+begin_src ruby
+    class Main < FXMainWindow
+      compose :my_window do
+        title "RubyNEAT Panel"
+        show PLACEMENT_SCREEN
+        width 700
+        height 400
+        fx_tab_book :my_book do |tab_book_ob|
+          x 0
+          y 0
+          width 500
+          height 100
+          pad_bottom 10
+          fx_text :my_text1, :my_window { |text_ob|
+            width 200
+            height 100
+            text_ob.target my_window: :on_click
+          }
+          fx_text :my_text2, :my_window { |text_ob|
+            width 200
+            height 100
+            text_ob { |t| puts "called after object initialization" }
+          }
+        end
+      end
+
+      def on_click
+        ...
+      end
+    end    
+    #+end_src
+
+    Class-free enhancement:
+    #+begin_src ruby
+    mw = fx_main_window :my_window do 
+        title "RubyNEAT Panel"
+        width 700
+        height 400
+        opts DECOR_ALL
+        x 10
+        y 10
+        instance { show PLACEMENT_SCREEN }
+        fx_tab_book :my_book do |tab_book_ob|
+          x 0
+          y 0
+          width 500
+          height 100
+          pad_bottom 10
+          fx_text :my_text1, :my_window { |text_ob|
+            width 200
+            height 100
+            instance my_window: :on_click
+          }
+          fx_text :my_text2, :my_window { 
+            width 200
+            height 100
+            instance { |t| puts "called after object initialization" }
+          }
+        end
+      end
+
+      def mw.on_click
+        ...
+      end
+    end    
+    #+end_src
+
+**** [[file:examples/hello.rb][Hello World]] example (full) the Enhancement Way
+    #+begin_src ruby
+#!/usr/bin/env ruby
+require 'fxruby-enhancement'
+
+include Fox
+include Fox::Enhancement::Mapper
+
+fx_app :app do
+  app_name "Hello"
+  vendor_name "Example"
+
+  fx_main_window(:main) {
+    title "Hello"
+    opts DECOR_ALL
+
+    fx_button {
+      text "&Hello, World"
+      selector FXApp::ID_QUIT
+      
+      instance { |b|
+        b.target = ref(:app)
+      }
+    }
+
+    instance { |w|
+      w.show PLACEMENT_SCREEN
+    }
+  }
+end
+
+# alias for fox_component is fxc
+fox_component :app do |app|
+  app.launch
+end
+    #+end_src
+    
+**** Hello World the old fxruby way:
+    #+begin_src ruby
+#!/usr/bin/env ruby
+
+require 'fox16'
+
+include Fox
+
+application = FXApp.new("Hello", "FoxTest")
+main = FXMainWindow.new(application, "Hello", nil, nil, DECOR_ALL)
+FXButton.new(main, "&Hello, World!", nil, application, FXApp::ID_QUIT)
+application.create()
+main.show(PLACEMENT_SCREEN)
+application.run()
+    #+end_src
+
+    Even though the old way has a slightly smaller line count, you can
+    see how messy it can be assigning each newly-created object to
+    a variable, and then having to pass that variable to the children.
+    Perhaps this example is too small, but perhaps the next one will
+    more illustrative.
+
+**** [[file:examples/bounce.rb][Bouncing Ball]] example (full):
+    #+begin_src ruby
+#!/usr/bin/env ruby
+require 'fxruby-enhancement'
+
+include Fox
+include Fox::Enhancement::Mapper
+
+ANIMATION_TIME = 20
+
+class Ball
+  attr_reader :color
+  attr_reader :center
+  attr_reader :radius
+  attr_reader :dir
+  attr_reader :x, :y
+  attr_reader :w, :h
+  attr_accessor :worldWidth
+  attr_accessor :worldHeight
+
+  
+  def initialize r
+    @radius = r
+    @w = 2*@radius
+    @h = 2*@radius
+    @center = FXPoint.new(50, 50)
+    @x = @center.x - @radius
+    @y = @center.y - @radius
+    @color = FXRGB(255, 0, 0) # red
+    @dir = FXPoint.new(-1, -1)
+    setWorldSize(1000, 1000)
+  end
+  
+  # Draw the ball into this device context
+  def draw(dc)
+    dc.setForeground(color)
+    dc.fillArc(x, y, w, h, 0, 64*90)
+    dc.fillArc(x, y, w, h, 64*90, 64*180)
+    dc.fillArc(x, y, w, h, 64*180, 64*270)
+    dc.fillArc(x, y, w, h, 64*270, 64*360)
+  end
+
+  def bounce_x
+    @dir.x=-@dir.x
+  end
+
+  def bounce_y
+    @dir.y=-@dir.y
+  end
+
+  def collision_y?
+    (y<0 && dir.y<0) || (y+h>worldHeight && dir.y>0)
+  end
+
+  def collision_x?
+    (x<0 && dir.x<0) || (x+w>worldWidth && dir.x>0)
+  end
+
+  def setWorldSize(ww, wh)
+    @worldWidth = ww
+    @worldHeight = wh
+  end
+  
+  def move(units)
+    dx = dir.x*units
+    dy = dir.y*units
+    center.x += dx
+    center.y += dy
+    @x += dx
+    @y += dy
+    if collision_x?
+      bounce_x
+      move(units)
+    end
+    if collision_y?
+      bounce_y
+      move(units)
+    end
+  end
+end
+
+fx_app :app do
+  app_name "Bounce"
+  vendor_name "Example"
+
+  fx_image(:back_buffer) { opts IMAGE_KEEP }
+  
+  fx_main_window(:bounce_window) {
+    title "Bounce Demo"
+    opts DECOR_ALL
+    width 400
+    height 300
+    
+    instance { |w|
+      def w.ball
+        @ball ||= Ball.new(20)
+      end
+      
+      def w.drawScene(drawable)
+        FXDCWindow.new(drawable) { |dc|
+          dc.setForeground(FXRGB(255, 255, 255))
+          dc.fillRectangle(0, 0, drawable.width, drawable.height)
+          ball.draw(dc)
+        }
+      end
+      
+      def w.updateCanvas
+        ball.move(10)
+        drawScene(ref(:back_buffer))
+        ref(:canvas).update
+      end
+      
+      #
+      # Handle timeout events
+      #
+      def w.onTimeout(sender, sel, ptr)
+        # Move the ball and re-draw the scene
+        updateCanvas
+        
+        # Re-register the timeout
+        ref(:app).addTimeout(ANIMATION_TIME, ref(:bounce_window).method(:onTimeout))
+        
+        # Done
+        return 1
+      end
+      
+      w.show PLACEMENT_SCREEN
+      ref(:app).addTimeout(ANIMATION_TIME, w.method(:onTimeout))
+    }
+    
+    fx_canvas(:canvas) {
+      opts LAYOUT_FILL_X|LAYOUT_FILL_Y
+      
+      instance { |c|
+        c.sel_paint { |sender, sel, event|
+          FXDCWindow.new(sender, event) { |dc|
+            dc.drawImage(ref(:back_buffer), 0, 0)
+          }
+        }
+
+        c.sel_configure{ |sender, sel, event|
+          bb = ref(:back_buffer)
+          bb.create unless bb.created?
+          bb.resize(sender.width, sender.height)
+          ref(:bounce_window) do |bw|
+            bw.ball.setWorldSize(sender.width, sender.height)
+            bw.drawScene(bb)
+          end
+        }
+      }
+    }
+  }
+end
+
+if __FILE__ == $0
+  # alias for fox_component is fxc
+  fox_component :app do |app|
+    app.launch
+  end
+end
+    #+end_src
+
+**** Bouncing Ball the old fxruby way:
+    #+begin_src ruby
+require 'fox16'
+
+include Fox
+
+# How long to pause between updates (in milliseconds)
+ANIMATION_TIME = 20
+
+class Ball
+
+  attr_reader :color
+  attr_reader :center
+  attr_reader :radius
+  attr_reader :dir
+  attr_reader :x, :y
+  attr_reader :w, :h
+  attr_accessor :worldWidth
+  attr_accessor :worldHeight
+
+  # Returns an initialized ball
+  def initialize(r)
+    @radius = r
+    @w = 2*@radius
+    @h = 2*@radius
+    @center = FXPoint.new(50, 50)
+    @x = @center.x - @radius
+    @y = @center.y - @radius
+    @color = FXRGB(255, 0, 0) # red
+    @dir = FXPoint.new(-1, -1)
+    setWorldSize(1000, 1000)
+  end
+
+  # Draw the ball into this device context
+  def draw(dc)
+    dc.setForeground(color)
+    dc.fillArc(x, y, w, h, 0, 64*90)
+    dc.fillArc(x, y, w, h, 64*90, 64*180)
+    dc.fillArc(x, y, w, h, 64*180, 64*270)
+    dc.fillArc(x, y, w, h, 64*270, 64*360)
+  end
+
+  def bounce_x
+    @dir.x=-@dir.x
+  end
+
+  def bounce_y
+    @dir.y=-@dir.y
+  end
+
+  def collision_y?
+    (y<0 && dir.y<0) || (y+h>worldHeight && dir.y>0)
+  end
+
+  def collision_x?
+    (x<0 && dir.x<0) || (x+w>worldWidth && dir.x>0)
+  end
+
+  def setWorldSize(ww, wh)
+    @worldWidth = ww
+    @worldHeight = wh
+  end
+
+  def move(units)
+    dx = dir.x*units
+    dy = dir.y*units
+    center.x += dx
+    center.y += dy
+    @x += dx
+    @y += dy
+    if collision_x?
+      bounce_x
+      move(units)
+    end
+    if collision_y?
+      bounce_y
+      move(units)
+    end
+  end
+end
+
+class BounceWindow < FXMainWindow
+
+  include Responder
+
+  def initialize(app)
+    # Initialize base class first
+    super(app, "Bounce", :opts => DECOR_ALL, :width => 400, :height => 300)
+
+    # Set up the canvas
+    @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
+
+    # Set up the back buffer
+    @backBuffer = FXImage.new(app, nil, IMAGE_KEEP)
+
+    # Handle expose events (by blitting the image to the canvas)
+    @canvas.connect(SEL_PAINT) { |sender, sel, evt|
+      FXDCWindow.new(sender, evt) { |dc|
+        dc.drawImage(@backBuffer, 0, 0)
+      }
+    }
+
+    # Handle resize events
+    @canvas.connect(SEL_CONFIGURE) { |sender, sel, evt|
+      @backBuffer.create unless @backBuffer.created?
+      @backBuffer.resize(sender.width, sender.height)
+      @ball.setWorldSize(sender.width, sender.height)
+      drawScene(@backBuffer)
+    }
+
+    @ball = Ball.new(20)
+  end
+
+  #
+  # Draws the scene into the back buffer
+  #
+  def drawScene(drawable)
+    FXDCWindow.new(drawable) { |dc|
+      dc.setForeground(FXRGB(255, 255, 255))
+      dc.fillRectangle(0, 0, drawable.width, drawable.height)
+      @ball.draw(dc)
+    }
+  end
+
+  def updateCanvas
+    @ball.move(10)
+    drawScene(@backBuffer)
+    @canvas.update
+  end
+
+  #
+  # Handle timeout events
+  #
+  def onTimeout(sender, sel, ptr)
+    # Move the ball and re-draw the scene
+    updateCanvas
+
+    # Re-register the timeout
+    getApp().addTimeout(ANIMATION_TIME, method(:onTimeout))
+
+    # Done
+    return 1
+  end
+
+  #
+  # Create server-side resources
+  #
+  def create
+    # Create base class
+    super
+
+    # Create the image used as the back-buffer
+    @backBuffer.create
+
+    # Draw the initial scene into the back-buffer
+    drawScene(@backBuffer)
+
+    # Register the timer used for animation
+    getApp().addTimeout(ANIMATION_TIME, method(:onTimeout))
+
+    # Show the main window
+    show(PLACEMENT_SCREEN)
+  end
+end
+
+if __FILE__ == $0
+  FXApp.new("Bounce", "FXRuby") do |theApp|
+    BounceWindow.new(theApp)
+    theApp.create
+    theApp.run
+  end
+end
+    #+end_src
+    
+    The Ball class is the same, but the actual Fox-related code
+    should clearly illustrate the power of Enhancement.
+
+    More examples can be found [[file:examples][HERE]].
+
+** Release Notes
+   | Version |       Date | Notes           |
+   |---------+------------+-----------------|
+   |   0.0.2 | 2017-01-11 | Initial release |
+
+** Known Issues
+   | Version |       Date | Issues                     |
+   |---------+------------+----------------------------|
+   |   0.0.2 | 2017-01-11 | Not enough example code!!! |
+
+** Contributing to fxruby-enhancement
+ 
+   - Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+   - Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+   - Fork the project.
+   - Start a feature/bugfix branch.
+   - Commit and push until you are happy with your contribution.
+   - Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+   - Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+** Copyright and Licensing
+   Copyright (c) 2016-2017 Fred Mitchell. See [[file:LICENSE.txt][MIT License]] for
+   further details.
+** The Junkyard / Scratchpad
+   These are my personal notes, not meant for anyone else.
+   You may see some interesting tidbits here, but I am not
+   gauranteeing anything to be useful or reliable in this
+   section. YOU HAVE BEEN WARNED.
+*** Genesis of the meta-meta programming, whereby brain goes boom
+    #+begin_src ruby
+    class FXToolBar # monkey patch
+      include Enhancement
+      attr_accessor :_o
+    end
+
+    def fx_tool_bar name, &block # DSL
+      o = OStruct.new
+      o.title = "default title"
+      ...
+
+      def o.title t 
+        @title = t
+      end    
+
+      def o.instance a, &block
+        o.instance_time_block = block
+      end
+      f = FXToolBar.new ...
+      f._o = o
+    end
+
+<% for @class, @details in @api %>
+   #<%= @class %> < <%= @details[:class][1] %>
+   <% unless @details[:initialize].nil? %>
+      <% for @iniparams in @details[:initialize] %>
+         #<%= @iniparams %>   
+      <% end %>
+   <% else %>
+      #No initializer
+   <% end %>
+<% end %>
+    #+end_src
+
+