fxruby-enhancement 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b794b2f54a98c4013d5b65dac69a9941ed161e67
-  data.tar.gz: ed4a967374dede324ae343e9db62ee5a0f0c2f9c
+  metadata.gz: ee35871b37b12dab95f43e9e0efe47c4eef62ae9
+  data.tar.gz: 23dad1cd5a49af520b2af586ea7fb11105c73966
 SHA512:
-  metadata.gz: 22536ce016e05481e0ac75d6be53eb04e57298961d42f88e73b6076ae17aed1660d8eaa6389aaa0cac050c581e8ade966b90baf303ac7d5537805e5ad1294a26
-  data.tar.gz: bbd2e87f25028ffc0b9b74ea7c4a17302ff833a0657411634b712cdd11b7383f16bdee6e90c6526a319ec3cd7e302accb4afbca57072d5916bb9d930d9a0254a
+  metadata.gz: e0f580dbe88affcab84a81b8c8ffc669d8a5f46e21c6dc5b59a95bb8d6c28ac4b45f3079dff633caddbeab5a101629b3ee0f76327a8a1702259279e4fef6b6c2
+  data.tar.gz: 8fa2425ff455205357d1cfc8e07073223dcda195a6205b6d953205f4e3a68a3120fc847af4781efcbd58335adc17dce9e0ec258bcf06f4172766ec96fd5cfade

data/.semver

@@ -1,5 +1,5 @@
 ---
 :major: 0
-:minor: 0
-:patch: 4
+:minor: 1
+:patch: 0
 :special: ''

data/Gemfile.lock

@@ -12,7 +12,7 @@ GEM
     debug_inspector (0.0.2)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
-    diff-lcs (1.2.5)
+    diff-lcs (1.3)
     docile (1.1.5)
     faraday (0.9.2)
       multipart-post (>= 1.2, < 3)

data/README.org

@@ -13,12 +13,15 @@
        - [[#the-queue_ding-queues][The Queue_Ding Queues]]
          - [[#enhancementingress][Enhancement.ingress]]
          - [[#enhancementegress][Enhancement.egress]]
+     - [[#reusable-components-and-dynamic-creation-and-the-reuse-flag][Reusable components and dynamic creation, and the 'reuse' flag]]
      - [[#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]]
+       - [[#fx_data_target][fx_data_target]]
        - [[#instance][instance]]
        - [[#ingress_handler][ingress_handler]]
+       - [[#starten-and-stoppen-with-resuable-components][#starten and #stoppen with resuable components]]
        - [[#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]]
@@ -27,12 +30,15 @@
        - [[#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:]]
+       - [[#datatarget-example][DataTarget Example]]
    - [[#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]]
+     - [[#junkyard-genesis-of-the-meta-meta-programming-whereby-brain-goes-boom][JUNKYARD Genesis of the meta-meta programming, whereby brain goes boom]]
+     - [[#junkyard-resuable-components-and-data-targets][JUNKYARD Resuable components and data targets]]
+       - [[#junkyard-data-targets][JUNKYARD Data Targets]]
 
 * fxruby-enhancement
 ** Introduction
@@ -49,14 +55,23 @@
    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
+   as well. You can now focus on creating your great 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]].
+   fxruby-enhancement (also referred to as "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]].
+   
+   Enhancement basically leverages Ruby's singleton feature, and eliminates
+   the need to "subclass" the FXRuby objects and the like. In fact, you might
+   even consider this Enhancement's own "paradigm" for doing GUI programming.
+
+   Your input and criticisms are more than welcome. Feel free to raise
+   issues on GitHub. I have not anticipated all the ways someone might try
+   to use Enhancement. I am making heavy use of Enhancement in my RubyNEAT
+   project -- which is why I created it.
    
 ** Installation
    To install the gem from commandline:
@@ -196,7 +211,7 @@
       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|
+      ingress_handler :log_info, :log_error do |tag, logline|
         puts "received #{tag} => #{payload}"
         case tag
         when :log_info
@@ -207,6 +222,14 @@
       end
       #+end_src
 
+      Note that this ingress handler is responding to two tags. You can have
+      as many tags as you like for your ingress handler, and as many
+      ingress handlers as you like. 
+      
+      Currently, all the tags should be unique. Later we may support having 
+      multiple blocks associated with the same tag. Please feel free to generate
+      an issue if you want this!!!
+
 ***** Enhancement.egress
       Wnen your Fox application needs to send a message to other
       listening threads, You simply push your payload onto the egress queue
@@ -216,9 +239,56 @@
       #+end_src
 
       and your Ruby thread external to Fox would simply do:
-      #+begin_src
+      #+begin_src ruby
+      ...
+      message = Enhancement.egress.next
+      ...
+      #+end_src
+      
+      where you'll block pending the arrival of the next message. If you
+      do not wish to block, you may do:
+      #+begin_src ruby
+      ...
+      unless Enhancement.egress.empty?
+        message = Enhancement.egress.next 
+      else
+        # some action to take
+      end
+      ...
       #+end_src
 
+*** Reusable components and dynamic creation, and the 'reuse' flag
+    There are times you may want to be able to create, and popup, say, a dialog
+    box, or perhaps you want to create on the fly child components on an
+    existing window.
+
+    This is made possible with the "reuse: true" flag. For example:
+    #+begin_src ruby
+    fx_dialog_box(:dialog, reuse: true) {
+      title "I am a Dialog!"
+      opts DECOR_ALL
+      
+      fx_button {
+        text "&It Works!"
+        instance { |dia|
+          dia.sel_command {
+            refc(:dialog).stoppen
+          }
+        }
+      }      
+      instance { |dia| dia.show PLACEMENT_OWNER  }
+    }
+    #+end_src
+
+    This code snippet can be run in the context of the app or a window. 
+    If you do it in a window context, that window will become the "owner",
+    and will initially be placed hovering over it.
+
+    With reusable components, you will use the #starten and #stoppen methods
+    to create and destroy the component. Please see
+    the [[file:examples/dialog_box.rb][Dialog Box]] for a full example, and also
+    the docs for #starten and #stoppen.
+
 *** API & DSL
 **** ref(), refc() and tagging your objects
      In an effort to eliminate the fuss and bother with
@@ -237,12 +307,25 @@
      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.
-
+     Where might you want to use refc() instead of ref()? In cases
+     where the underlying FXRuby object have not been instantiated yet,
+     you'd use refc() instead of ref(), almost always during the component
+     configuration. For example:
+     #+begin_src ruby
+     fx_app :app do
+     ...
+       fx_button {
+         text "&See Ya!"
+         selector FXApp::ID_QUIT
+         target refc(:app)
+       }
+     ...
+     #+end_src
+     
+     Here, we set the button to exit the application by sending the FXApp object the ID_QUIT
+     message. But at the time we set the configuration, the FXApp object has not been instantiated
+     yet. So we use refc() instead of ref().
+     
      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.
@@ -293,6 +376,37 @@
      Typeically you'd do this inside of a module, but you could do it also
      in a class body. Please see the examples.
 
+**** fx_data_target
+     FOX (and therefor FXRuby) supports data synchronization among components.
+     fx_data_target encapsulates the FXDataTarget class, just like all the
+     other fx_* directives do. However, in this case, some special treatment
+     is necessary since it is referenced at a time the underlying FXRuby
+     object has not been created yet.
+
+     Enter refc(). You use refc(), instead of ref(), to use it when you are
+     configuring the component (really, specifying the initial parameters
+     to the underlying FXRuby class!) We illustrate here:
+     #+begin_src ruby
+     ...
+     fx_data_target (:mydata) { value "initial value"  }
+     ...
+     fx_text (:text_3) {
+       target refc(:mydata)
+       selector FXDataTarget::ID_VALUE
+     }
+     fx_text (:text_4) {
+       target refc(:mydata)
+       selector FXDataTarget::ID_VALUE
+     }
+     #+end_src
+
+     And so the two text components  -- or widgets -- are initially
+     set to the value of "initial value", and when one changes, the
+     other is instantly updated.
+
+     Otherwise, you can deal with fx_data_target as expected. See
+     the [[#datatarget-example][DataTarget Example]].
+
 **** instance
      Inside of your component declaration, you will undoubtly
      want to specify what you want to do once the FXRuby object
@@ -379,6 +493,30 @@
 
      The same block is assigned to all the given tags of :warn, :info, and :error.
 
+**** #starten and #stoppen with resuable components
+     To designate a component as reusable, declare it with "reuse: true"
+     as in the example:
+     #+begin_src ruby
+     fx_dialog_box(:dialog, reuse: true) { ... }
+     #+end_src
+
+     Then in the instance clause or to the response to an event,
+     you would do:
+     #+begin_src ruby
+     refc(:dialog).starten
+     #+end_src
+
+     to activate it, and
+     #+begin_src ruby
+     refc(:dialog).stoppen
+     #+end_src
+
+     to deactive it (and remove the 'server'-side FOX components!)
+
+     Note that you call refc(), not ref() in this case, because the
+     functionality lies in the component object holder for the actual
+     FOX component, not within the FXRuby object itself.
+
 **** TODO deferred_setup
 **** TODO Mapping between fx_* declarations and the FX* FXRuby objects
 **** binding.fx   
@@ -418,7 +556,7 @@
 
     https://github.com/flajann2/rubyneat-panel/tree/master/lib/rubyneat-panel
 
-    Class-based enhancement (this has not been tested yet!!!):
+    Class-based Enhancement (this is currently not supported!!!):
     #+begin_src ruby
     class Main < FXMainWindow
       compose :my_window do
@@ -451,7 +589,7 @@
     end    
     #+end_src
 
-    Class-free enhancement:
+    Class-free Enhancement (strongly recommended):
     #+begin_src ruby
     mw = fx_main_window :my_window do 
         title "RubyNEAT Panel"
@@ -886,18 +1024,87 @@ end
 
     More examples can be found [[file:examples][HERE]].
 
+**** DataTarget Example
+     fx_data_target (:some_name) must be referenced as refc(:some_name) and
+     not ref(...). See the example below.
+
+     #+begin_src ruby
+#!/usr/bin/env ruby
+require 'fxruby-enhancement'
+
+include Fox
+include Fox::Enhancement::Mapper
+
+fx_app :app do
+  app_name "DataTarget"
+  vendor_name "Example"
+
+  fx_data_target (:textx) { value "x marks the spot!"  }
+  fx_data_target (:texty) { value "y do it?"  }
+  
+  fx_main_window(:main) {
+    title "fx_data_target example"
+    opts DECOR_ALL
+    width 300
+    x 100
+    y 200
+
+    fx_text_field (:text_1) {
+      ncols 40
+      target refc(:textx)
+      selector FXDataTarget::ID_VALUE
+    }
+    fx_text_field (:text_2) {
+      ncols 40
+      target refc(:textx)
+      selector FXDataTarget::ID_VALUE
+    }
+    fx_text (:text_3) {
+      opts LAYOUT_FILL_X
+      target refc(:texty)
+      selector FXDataTarget::ID_VALUE
+    }
+    fx_text (:text_4) {
+      opts LAYOUT_FILL_X
+      target refc(:texty)
+      selector FXDataTarget::ID_VALUE
+    }
+    fx_button {
+      text "&See ya!"
+      selector FXApp::ID_QUIT
+      opts BUTTON_NORMAL|LAYOUT_CENTER_X
+      
+      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
+
 ** Release Notes
-   | Version |       Date | Notes                                                   |
-   |---------+------------+---------------------------------------------------------|
-   |   0.0.2 | 2017-01-11 | Initial release                                         |
-   |   0.0.3 | 2017-01-15 | Needed to require fox16/colors for FXColor to be loaded |
-   |   0.0.4 | 2017-01-16 | ingress_handler now handles multiple tags.              |
+   | Version |       Date | Notes                                                       |
+   |---------+------------+-------------------------------------------------------------|
+   |   0.0.2 | 2017-01-11 | Initial release                                             |
+   |   0.0.3 | 2017-01-15 | Needed to require fox16/colors for FXColor to be loaded     |
+   |   0.0.4 | 2017-01-16 | ingress_handler now handles multiple tags.                  |
+   |   0.1.0 | 2017-01-18 | special handling for fx_data_target and resuable components |
 
 ** Known Issues
-   | Version |       Date | Issues                                                |
-   |---------+------------+-------------------------------------------------------|
-   |   0.0.2 | 2017-01-11 | Not enough example code!!! Need more documentation!!! |
-
+   | Version |                   Date | Issues                                                             |
+   |---------+------------------------+--------------------------------------------------------------------|
+   |   0.0.2 |             2017-01-11 | Not enough example code!!! Need more documentation!!!              |
+   |   0.1.0 | Trump Inaguration Day, | deferred_setup not fully implemented, and may go away.             |
+   |         |             2017-01-20 | compose is not really needed, and is not fully implemented anyway. |
 
 ** Contributing to fxruby-enhancement
  
@@ -917,7 +1124,7 @@ end
    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
+*** JUNKYARD Genesis of the meta-meta programming, whereby brain goes boom
     #+begin_src ruby
     class FXToolBar # monkey patch
       include Enhancement
@@ -953,3 +1160,19 @@ end
     #+end_src
 
 
+*** JUNKYARD Resuable components and data targets
+    We have an issue with needing to have reusable components
+    (dialog boxes, say), and ṕroperly handling data targets designations.
+**** JUNKYARD Data Targets
+     Data targets cannot be done the same way we are doing the other
+     fxruby components, because they have a different workflow. Basically,
+     they need to be instantiated before the other comonents that uses
+     them, and they are not really "child" objects, either. Referring to them
+     using the ref() or refc() approach simply fails, because they won't
+     be instantiated in time.
+
+     We have ameroliated this problem by checking in the parameter list
+     for an OpenStruct object, and calling #inst on it to pass in the instance,
+     rather than the object itself. So now you simply use refc()
+     in those cases.
+     

data/examples/data_target.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+require 'fxruby-enhancement'
+
+include Fox
+include Fox::Enhancement::Mapper
+
+fx_app :app do
+  app_name "DataTarget"
+  vendor_name "Example"
+
+  fx_data_target (:textx) { value "x marks the spot!"  }
+  fx_data_target (:texty) { value "y do it?"  }
+  
+  fx_main_window(:main) {
+    title "fx_data_target example"
+    opts DECOR_ALL
+    width 300
+    x 100
+    y 200
+
+    fx_text_field (:text_1) {
+      ncols 40
+      target refc(:textx)
+      selector FXDataTarget::ID_VALUE
+    }
+    fx_text_field (:text_2) {
+      ncols 40
+      target refc(:textx)
+      selector FXDataTarget::ID_VALUE
+    }
+    fx_text (:text_3) {
+      opts LAYOUT_FILL_X
+      target refc(:texty)
+      selector FXDataTarget::ID_VALUE
+    }
+    fx_text (:text_4) {
+      opts LAYOUT_FILL_X
+      target refc(:texty)
+      selector FXDataTarget::ID_VALUE
+    }
+    fx_button {
+      text "&See ya!"
+      selector FXApp::ID_QUIT
+      opts BUTTON_NORMAL|LAYOUT_CENTER_X
+      
+      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