gtk_paradise 0.9.120 → 0.11.19

data/lib/gtk_paradise/base_module/css.rb

@@ -7,12 +7,58 @@
 module Gtk
 
 module BaseModule
-    
-  require 'gtk_paradise/project/project.rb'
-  require 'gtk_paradise/constants/misc.rb'
-  require 'gtk_paradise/base_module/e.rb'
+
   require 'gtk_paradise/toplevel_methods/css.rb'
 
+  # ========================================================================= #
+  # === use_these_css_classes
+  #
+  # This allows for convenience in regards to using CSS classes.
+  #
+  # It is important to separate these CSS classes via a ' ' character.
+  #
+  # Usage example:
+  #
+  #   @frame.use_these_css_classes('no_box_shadow bblack2 BG_black pad0px mar0px')
+  #
+  # ========================================================================= #
+  def use_these_css_classes(i)
+    if i and i.include?(' ')
+      i.split(' ').each {|this_css_class|
+        css_class(this_css_class)
+      }
+    else
+      css_class(this_css_class)
+    end
+  end; alias use_these_CSS_classes use_these_css_classes # === use_these_CSS_classes
+
+  # ========================================================================= #
+  # === do_apply_the_CSS_rules
+  #
+  # This method will simply apply the defined CSS rules, stored in the
+  # @internal_hash. It depends on class Gtk::CssProvider.
+  # ========================================================================= #
+  def do_apply_the_CSS_rules(
+      _     = Gtk.css_rules?.to_s,
+      debug = debug?
+    )
+    _ = _.to_s.dup # This will be our dataset.
+    if use_gtk3? or use_gtk4? # This is only available for ruby-gtk3 or higher, not for ruby-gtk2.
+      if debug
+        e 'The following CSS rules will be added next:'
+        e '-'*80
+        e _
+        e '-'*80
+      end
+      return Gtk.css_provider(_)
+    end
+  end; alias apply_the_css_string do_apply_the_CSS_rules # === apply_the_css_string
+       alias apply_the_css_rules  do_apply_the_CSS_rules # === apply_the_css_rules
+       alias apply_the_CSS_rules  do_apply_the_CSS_rules # === apply_the_CSS_rules
+       alias apply_the_CSS        do_apply_the_CSS_rules # === apply_the_CSS
+       alias trigger_CSS_addition do_apply_the_CSS_rules # === trigger_CSS_addition
+       alias trigger_CSS          do_apply_the_CSS_rules # === trigger_CSS
+
   # ========================================================================= #
   # === append_gtk_paradise_project_css_file
   # ========================================================================= #
@@ -24,75 +70,42 @@ module BaseModule
     append_these_new_CSS_rules(dataset)
   end; alias add_gtk_paradise_project_css_file append_gtk_paradise_project_css_file # === add_gtk_paradise_project_css_file
        alias append_gtk_paradise_css_rules     append_gtk_paradise_project_css_file # === append_gtk_paradise_css_rules
+       alias use_the_default_css_rules         append_gtk_paradise_project_css_file # === use_the_default_css_rules
 
   # ========================================================================= #
-  # === more_css_then_apply_the_CSS_rules
-  #
-  # This method will simply combine two other method calls - it can be
-  # used to add new CSS rules, and apply them at once (onto the
-  # CSS provider).
+  # === append_the_default_css_rules
   # ========================================================================= #
-  def more_css_then_apply_the_CSS_rules(i)
-    more_css(i)
-    apply_the_CSS_rules
-  end; alias apply_these_CSS_rules              more_css_then_apply_the_CSS_rules # === apply_these_CSS_rules
-       alias add_custom_CSS_rules               more_css_then_apply_the_CSS_rules # === add_custom_CSS_rules
-       alias more_CSS_rules_then_apply_them     more_css_then_apply_the_CSS_rules # === more_CSS_rules_then_apply_them
-       alias more_CSS_then_apply_these_rules    more_css_then_apply_the_CSS_rules # === more_CSS_then_apply_these_rules
-       alias more_CSS_then_apply_it             more_css_then_apply_the_CSS_rules # === more_CSS_then_apply_it
-       alias custom_CSS_then_apply_it           more_css_then_apply_the_CSS_rules # === custom_CSS_then_apply_it
-       alias add_more_CSS_rules_then_apply_them more_css_then_apply_the_CSS_rules # === add_more_CSS_rules_then_apply_them
+  def append_the_default_css_rules(
+      i = :project_internal_files
+    )
+    Gtk.append_css(
+      return_default_CSS_rules(i)
+    )
+  end
 
   # ========================================================================= #
-  # === append_onto_the_CSS_rules                                (append tag)
+  # === apply_the_default_CSS_rules
   #
-  # Use this method when you wish to append more CSS rules.
-  # ========================================================================= #
-  def append_onto_the_CSS_rules(i)
-    if debug?
-      e 'Adding the following CSS rule:'
-      e '-' * 80
-      e i
-      e '-' * 80
-    end
-    if i and i.is_a?(String) and File.exist?(i)
-      i = File.read(i)
-    end
-    if @internal_hash.has_key? :css_rules_to_apply
-      @internal_hash[:css_rules_to_apply] << i
-    else
-      e 'No key called :css_rules_to_apply - was '\
-        '.reset_the_internal_variables() called?'
-    end
-  end; alias append_css                           append_onto_the_CSS_rules # === append_css
-       alias add_to_the_css_string                append_onto_the_CSS_rules # === add_to_the_css_string
-       alias append_these_CSS_rules               append_onto_the_CSS_rules # === append_these_CSS_rules
-       alias append_these_custom_CSS_rules        append_onto_the_CSS_rules # === append_these_custom_CSS_rules
-       alias add_and_apply_these_custom_CSS_rules append_onto_the_CSS_rules # === add_and_apply_these_custom_CSS_rules
-       alias add_this_css                         append_onto_the_CSS_rules # === add_this_css
-       alias add_css                              append_onto_the_CSS_rules # === add_this_css
-       alias more_css                             append_onto_the_CSS_rules # === more_css
-       alias more_CSS                             append_onto_the_CSS_rules # === more_CSS
-       alias more_CSS_from                        append_onto_the_CSS_rules # === more_CSS_from
-       alias append_these_new_CSS_rules           append_onto_the_CSS_rules # === append_these_new_CSS_rules
-       alias add_custom_CSS_rules                 append_onto_the_CSS_rules # === add_custom_CSS_rules
-       alias add_these_custom_CSS_rules           append_onto_the_CSS_rules # === add_these_custom_CSS_rules
-       alias adhoc_css                            append_onto_the_CSS_rules # === adhoc_css
-       alias in_file_css                          append_onto_the_CSS_rules # === in_file_css
+  # This variant will first load the project-specific CSS rules.
+  # ========================================================================= #
+  def apply_the_default_CSS_rules(
+      i = return_default_CSS_rules
+    )
+    # @internal_hash[:css_rules_to_apply] = dataset
+    append_these_CSS_rules(i)
+    do_apply_the_CSS_rules
+  end; alias apply_the_default_css_rules apply_the_default_CSS_rules # === apply_the_default_css_rules
+       alias load_default_css                                                               apply_the_default_CSS_rules # === load_default_css
+       alias read_in_from_this_css_file_and_apply_the_content_as_the_new_rules_to_adhere_to apply_the_default_CSS_rules # === read_in_from_this_css_file_and_apply_the_content_as_the_new_rules_to_adhere_to
+       alias load_dataset_from_this_css_file                                                apply_the_default_CSS_rules # === load_dataset_from_this_css_file
 
   # ========================================================================= #
-  # === use_lean_CSS_rules
-  #
-  # Use only the registered CSS classes here.
-  # ========================================================================= #
-  def use_lean_CSS_rules
-    _ = ::Gtk.css_classes_in_use?
-pp _.class
-pp _
-e '^^^ This method called .use_lean_CSS_rules() is currently unfinished.'
-e 'The idea was that we would only use registered CSS classes and skip'
-e 'loading the rest. This should speed up the gtk-application '\
-  'a little bit.'
+  # === return_default_CSS_rules
+  # ========================================================================= #
+  def return_default_CSS_rules(
+      i = :project_internal_files
+    )
+    return ::Gtk.return_default_CSS_rules(i)
   end
 
   # ========================================================================= #
@@ -104,8 +117,10 @@ e 'loading the rest. This should speed up the gtk-application '\
   # projects, but other users may find some CSS rules used therein
   # useful as well.
   # ========================================================================= #
-  def use_gtk_paradise_project_css_file
-    apply_the_default_css_rules(:project_internal_files)
+  def use_gtk_paradise_project_css_file(
+      i = :project_internal_files
+    )
+    append_the_default_css_rules(i)
   end; alias use_gtk_paradise_css_file         use_gtk_paradise_project_css_file # === use_gtk_paradise_css_file
        alias use_gtk_project_css_file          use_gtk_paradise_project_css_file # === use_gtk_project_css_file
        alias gtk_paradise_project_file         use_gtk_paradise_project_css_file # === gtk_paradise_project_file
@@ -115,90 +130,122 @@ e 'loading the rest. This should speed up the gtk-application '\
        alias use_the_gtk_paradise_css_file     use_gtk_paradise_project_css_file # === use_the_gtk_paradise_css_file
 
   # ========================================================================= #
-  # === append_project_css_file
+  # === css_rules_to_apply?
+  # ========================================================================= #
+  def css_rules_to_apply?
+    # @internal_hash[:css_rules_to_apply]
+    return ::Gtk.css_rules_to_apply?
+  end; alias css_string? css_rules_to_apply? # === css_string?
+       alias css_rules?  css_rules_to_apply? # === css_rules?
+
+  # ========================================================================= #
+  # === css_background1
   #
-  # This will find the file called project.css and then append it
-  # onto the main CSS in use.
-  # ========================================================================= #
-  def append_project_css_file(
-      project_internal_css_file = 
-        Gtk.ruby_sitedir?+
-        Gtk.infer_the_name_of_the_project_based_on_this_directory(configuration?[1])+
-        '/css/project.css'
-    )
-    if File.exist? project_internal_css_file
-      dataset = File.read(project_internal_css_file)
-      append_these_new_CSS_rules(dataset)
+  # Hardcoded background for now. One day we should split this into a
+  # separate page.
+  # ========================================================================= #
+  def css_background1
+    'background: linear-gradient(153deg, #151515, #151515 5px, transparent 5px) 0 0,
+                 linear-gradient(333deg, #151515, #151515 5px, transparent 5px) 10px 5px,
+                 linear-gradient(153deg, #222, #222 5px, transparent 5px) 0 5px,
+                 linear-gradient(333deg, #222, #222 5px, transparent 5px) 10px 10px,
+                 linear-gradient(90deg, #1b1b1b, #1b1b1b 10px, transparent 10px),
+                 linear-gradient(#1d1d1d, #1d1d1d 25%, #1a1a1a 25%, #1a1a1a 50%, transparent 50%, transparent 75%, #242424 75%, #242424);
+     background-color: #131313;
+     background-size: 20px 20px;'
+  end
+
+  # ========================================================================= #
+  # === store_the_CSS_rules_into_a_local_file
+  #
+  # This method can be used to store the CSS rules into a local file. It is
+  # mostly meant as a debug-helper.
+  # ========================================================================= #
+  def store_the_CSS_rules_into_a_local_file
+    require 'fileutils'
+    begin
+      require 'save_file'
+    rescue LoadError; end
+    if Object.const_defined? :SaveFile
+      use_this_css_file = '/tmp/gtk_paradise/css_rules.css'
+      FileUtils.mkdir_p('/tmp/gtk_paradise/')
+      ::SaveFile.write_what_into(css_rules_to_apply?, use_this_css_file)
+      e 'Saving into the following file: '+use_this_css_file
     else
-      e 'No file exists at '+project_internal_css_file+'.'
+      e 'SaveFile is not available.'
     end
-  end; alias use_project_css_file    append_project_css_file # === use_project_css_file
-       alias append_project_CSS_file append_project_css_file # === append_project_CSS_file
+  end
 
   # ========================================================================= #
-  # === apply_the_default_css_rules
+  # === generate_css_class
   #
-  # This variant will first load the project-specific CSS rules.
+  # This can be used to quickly, ad-hoc, generate CSS rules.
   # ========================================================================= #
-  def apply_the_default_css_rules(
-      i = :project_internal_files
-    )
-    dataset = ''.dup
+  def generate_css_class(i)
     case i
     # ======================================================================= #
-    # === :project_internal_files
+    # === :bblack1
     # ======================================================================= #
-    when :project_internal_files,
-         :default
-      i = [
-            "#{::Gtk.project_base_directory?}css_files/project.css",
-            "#{::Gtk.project_base_directory?}css_files/colours.css"
-          ]
-    end
+    when :bblack1
+      i = '.bblack1 { border: 1px solid black; }'
     # ======================================================================= #
-    # Operate on an Array always.
+    # === :bblack3
     # ======================================================================= #
-    [i].flatten.compact.each {|this_css_file|
-      dataset << File.read(this_css_file)
-      dataset << "\n"
-    }
-    # @internal_hash[:css_rules_to_apply] = dataset
-    append_these_CSS_rules(dataset)
-    do_apply_the_CSS_rules
-  end; alias load_default_css                                                               apply_the_default_css_rules # === load_default_css
-       alias apply_the_default_CSS_rules                                                    apply_the_default_css_rules # === apply_the_default_CSS_rules
-       alias read_in_from_this_css_file_and_apply_the_content_as_the_new_rules_to_adhere_to apply_the_default_css_rules # === read_in_from_this_css_file_and_apply_the_content_as_the_new_rules_to_adhere_to
-       alias load_dataset_from_this_css_file                                                apply_the_default_css_rules # === load_dataset_from_this_css_file
+    when :bblack2
+      i = '.bblack2 { border: 2px solid black; }'
+    # ======================================================================= #
+    # === :bblack3
+    # ======================================================================= #
+    when :bblack3
+      i = '.bblack3 { border: 3px solid black; }'
+    end
+    ::Gtk.css_provider(i)
+  end; alias generate_css_rule generate_css_class # === generate_css_rule
 
   # ========================================================================= #
-  # === do_apply_the_CSS_rules
+  # === css_provider?
+  # ========================================================================= #
+  def css_provider?
+    ::Gtk.css_provider?
+  end
+
+  # ========================================================================= #
+  # === read_in_from_this_css_theme
+  #
+  # Usage example:
+  #
+  #   read_in_from_this_css_theme(:rainbow_theme)
   #
-  # This method will simply apply the defined CSS rules, stored in the
-  # @internal_hash. It depends on class Gtk::CssProvider.
   # ========================================================================= #
-  def do_apply_the_CSS_rules(
-      _ = @internal_hash[:css_rules_to_apply]
+  def read_in_from_this_css_theme(
+      i = :rainbow_theme
     )
-    if use_gtk3? # This is only available for ruby-gtk3 or higher, not for ruby-gtk2.
-      provider = Gtk::CssProvider.new
-      if debug?
-        e 'The following CSS rules will be added next:'
-        e '-'*80
-        e _
-        e '-'*80
+    case i
+    # ======================================================================= #
+    # === :rainbow_theme
+    # ======================================================================= #
+    when :rainbow_theme
+      i = Gtk.return_path_to_the_sitelibdir+
+          'gtk_paradise/css_files/themes/rainbow_theme.css'
+      if File.exist? i
+        append_these_CSS_rules(File.read(i))
       end
-      provider.load(data: _)
-      Gtk::StyleContext.add_provider_for_screen(
-        Gdk::Screen.default,
-        provider,
-        Gtk::StyleProvider::PRIORITY_APPLICATION
-      )
-      return provider
     end
-  end; alias apply_the_css_string do_apply_the_CSS_rules # === apply_the_css_string
-       alias apply_the_CSS_rules  do_apply_the_CSS_rules # === apply_the_CSS_rules
-       alias apply_the_css_rules  do_apply_the_CSS_rules # === apply_the_css_rules
-       alias apply_the_CSS        do_apply_the_CSS_rules # === apply_the_CSS
+  end
+
+  # ========================================================================= #
+  # === return_the_path_to_the_file_called_project_css
+  # ========================================================================= #
+  def return_the_path_to_the_file_called_project_css(i)
+    ::Gtk.return_the_path_to_the_file_called_project_css(i)
+  end
+
+  # ========================================================================= #
+  # === add_css_rules
+  # ========================================================================= #
+  def add_css_rules(i)
+    ::Gtk.css_provider(i)
+  end
 
   # ========================================================================= #
   # === return_scrollable_CSS_in_use_widget
@@ -217,13 +264,31 @@ e 'loading the rest. This should speed up the gtk-application '\
     text_view   = gtk_text_view(text_buffer)
     _ = gtk_scrolled_window(text_view) { :only_up_and_down }
     _.pad10px
-    _.css_class('mar8px')
+    _.mar8px
     _.bblack1
     _.set_size_request(240, 300)
     _.set_border_width(20)
     return _
   end
 
+  # ========================================================================= #
+  # === more_css_then_apply_the_CSS_rules
+  #
+  # This method will simply combine two other method calls - it can be
+  # used to add new CSS rules, and apply them at once (onto the
+  # CSS provider).
+  # ========================================================================= #
+  def more_css_then_apply_the_CSS_rules(i)
+    more_css(i)
+    # apply_the_CSS_rules
+  end; alias apply_these_CSS_rules              more_css_then_apply_the_CSS_rules # === apply_these_CSS_rules
+       alias add_custom_CSS_rules               more_css_then_apply_the_CSS_rules # === add_custom_CSS_rules
+       alias more_CSS_rules_then_apply_them     more_css_then_apply_the_CSS_rules # === more_CSS_rules_then_apply_them
+       alias more_CSS_then_apply_these_rules    more_css_then_apply_the_CSS_rules # === more_CSS_then_apply_these_rules
+       alias more_CSS_then_apply_it             more_css_then_apply_the_CSS_rules # === more_CSS_then_apply_it
+       alias custom_CSS_then_apply_it           more_css_then_apply_the_CSS_rules # === custom_CSS_then_apply_it
+       alias add_more_CSS_rules_then_apply_them more_css_then_apply_the_CSS_rules # === add_more_CSS_rules_then_apply_them
+
   # ========================================================================= #
   # === display_the_CSS_rules
   # ========================================================================= #
@@ -245,7 +310,7 @@ e 'loading the rest. This should speed up the gtk-application '\
         'Number of newlines in this assumed .css file was: '
       )+
       ::Colours.royalblue(i.count("\n"))
-    registered_CSS_classes = Gtk.css_classes_in_use?
+    registered_CSS_classes = ::Gtk.css_classes_in_use?
     e 'The registered CSS classes are ('+registered_CSS_classes.size.to_s+'):'
     e
     pp registered_CSS_classes
@@ -260,139 +325,6 @@ e 'loading the rest. This should speed up the gtk-application '\
        alias show_CSS?                 display_the_CSS_rules # === show_CSS?
        alias show_CSS                  display_the_CSS_rules # === show_CSS
        alias show_CSS_in_use           display_the_CSS_rules # === show_CSS_in_use
-
-  # ========================================================================= #
-  # === use_these_css_classes
-  #
-  # This allows for convenience in regards to using CSS classes.
-  #
-  # It is important to separate these CSS classes via a ' ' character.
-  #
-  # Usage example:
-  #
-  #   @frame.use_these_css_classes('no_box_shadow bblack2 BG_black pad0px mar0px')
-  #
-  # ========================================================================= #
-  def use_these_css_classes(i)
-    i.split(' ').each {|this_css_class|
-      css_class(this_css_class)
-    }
-  end; alias use_these_CSS_classes use_these_css_classes # === use_these_CSS_classes
-
-  # ========================================================================= #
-  # === css_rules_to_apply?
-  # ========================================================================= #
-  def css_rules_to_apply?
-    @internal_hash[:css_rules_to_apply]
-  end; alias css_string? css_rules_to_apply? # === css_string?
-       alias css_rules?  css_rules_to_apply? # === css_rules?
-
-  # ========================================================================= #
-  # === read_in_from_this_css_theme
-  #
-  # Usage example:
-  #
-  #   read_in_from_this_css_theme(:rainbow_theme)
-  #
-  # ========================================================================= #
-  def read_in_from_this_css_theme(
-      i = :rainbow_theme
-    )
-    case i
-    # ======================================================================= #
-    # === :rainbow_theme
-    # ======================================================================= #
-    when :rainbow_theme
-      i = Gtk.return_path_to_the_sitelibdir+
-          'gtk_paradise/css_files/themes/rainbow_theme.css'
-      if File.exist? i
-        append_these_CSS_rules(File.read(i))
-      end
-    end
-  end
-
-  # ========================================================================= #
-  # === return_the_path_to_the_file_called_project_css
-  # ========================================================================= #
-  def return_the_path_to_the_file_called_project_css(i)
-    ::Gtk.return_the_path_to_the_file_called_project_css(i)
-  end
-
-  # ========================================================================= #
-  # === add_css_rules
-  # ========================================================================= #
-  def add_css_rules(i)
-    ::Gtk.css_provider(i)
-  end
-
-  # ========================================================================= #
-  # === generate_css_class
-  #
-  # This can be used to quickly, ad-hoc, generate CSS rules.
-  # ========================================================================= #
-  def generate_css_class(i)
-    case i
-    # ======================================================================= #
-    # === :bblack1
-    # ======================================================================= #
-    when :bblack1
-      i = '.bblack1 { border: 1px solid black; }'
-    # ======================================================================= #
-    # === :bblack3
-    # ======================================================================= #
-    when :bblack2
-      i = '.bblack2 { border: 2px solid black; }'
-    # ======================================================================= #
-    # === :bblack3
-    # ======================================================================= #
-    when :bblack3
-      i = '.bblack3 { border: 3px solid black; }'
-    end
-    ::Gtk.css_provider(i)
-  end; alias generate_css_rule generate_css_class # === generate_css_rule
-
-  # ========================================================================= #
-  # === css_provider?
-  # ========================================================================= #
-  def css_provider?
-    ::Gtk.css_provider?
-  end
-
-  # ========================================================================= #
-  # === css_background1
-  #
-  # Hardcoded background for now. One day we should split this into a
-  # separate page.
-  # ========================================================================= #
-  def css_background1
-    'background: linear-gradient(153deg, #151515, #151515 5px, transparent 5px) 0 0,
-                 linear-gradient(333deg, #151515, #151515 5px, transparent 5px) 10px 5px,
-                 linear-gradient(153deg, #222, #222 5px, transparent 5px) 0 5px,
-                 linear-gradient(333deg, #222, #222 5px, transparent 5px) 10px 10px,
-                 linear-gradient(90deg, #1b1b1b, #1b1b1b 10px, transparent 10px),
-                 linear-gradient(#1d1d1d, #1d1d1d 25%, #1a1a1a 25%, #1a1a1a 50%, transparent 50%, transparent 75%, #242424 75%, #242424);
-     background-color: #131313;
-     background-size: 20px 20px;'
-  end
-
-  # ========================================================================= #
-  # === store_the_CSS_rules_into_a_local_file
-  #
-  # This method can be used to store the CSS rules into a local file.
-  # ========================================================================= #
-  def store_the_CSS_rules_into_a_local_file
-    require 'fileutils'
-    begin
-      require 'save_file'
-    rescue LoadError; end
-    if Object.const_defined? :SaveFile
-      use_this_css_file = '/tmp/gtk_paradise/css_rules.css'
-      FileUtils.mkdir_p('/tmp/gtk_paradise/')
-      ::SaveFile.write_what_into(css_rules_to_apply?, use_this_css_file)
-      e 'Saving into the following file: '+use_this_css_file
-    else
-      e 'SaveFile is not available.'
-    end
-  end
+       alias show_CSS_rules            display_the_CSS_rules # === show_CSS_rules
 
 end; end

data/lib/gtk_paradise/base_module/experimental.rb

@@ -0,0 +1,119 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'gtk_paradise/base_module/experimental.rb'
+# =========================================================================== #
+module Gtk
+
+module BaseModule
+
+  # ========================================================================= #
+  # === automatically_created_widgets?
+  # ========================================================================= #
+  def automatically_created_widgets?
+    @internal_hash[:automatically_created_widgets]
+  end
+
+  # ========================================================================= #
+  # === automatically_create_widgets_based_on_this_dataset
+  #
+  # This method can be specifically used to create some widgets
+  # "automatically", based on a description provided by a yaml
+  # file (or some other text file).
+  #
+  # The input to this method should be a Hash, though.
+  # ========================================================================= #
+  def automatically_create_widgets_based_on_this_dataset(
+      i,
+      be_verbose = true # Whether to report anything to the user or not.
+    )
+    # ======================================================================= #
+    # Always reset the main pointer, at the least for now:
+    # ======================================================================= #
+    @internal_hash[:automatically_created_widgets] = {}
+    if i.is_a? Hash
+      i.each_pair {|key, value|
+        case key # case tag
+        # =================================================================== #
+        # === entries
+        # =================================================================== #
+        when 'entries'
+          entries = {}
+          value.each_pair {|inner_key, inner_value|
+            use_this_as_the_id = inner_key.to_s
+            an_entry = entry
+            an_entry.clear_background
+            # =============================================================== #
+            # === text
+            # =============================================================== #
+            if inner_value.has_key? 'text'
+              an_entry.set_text(inner_value['text'])
+            end
+            # =============================================================== #
+            # === css_class
+            # =============================================================== #
+            if inner_value.has_key? 'css_class'
+              an_entry.use_these_css_classes(
+                inner_value['css_class']
+              )
+            end
+            entries[use_this_as_the_id.to_sym] = an_entry
+          }
+          @internal_hash[:automatically_created_widgets][:entries] = entries
+        # =================================================================== #
+        # === buttons
+        #
+        # Handle buttons here.
+        # =================================================================== #
+        when 'buttons'
+          buttons = {}
+          value.each_pair {|inner_key, inner_value|
+            use_this_as_the_id = inner_key.to_s
+            a_button = button
+            a_button.clear_background
+            # =============================================================== #
+            # === text
+            # =============================================================== #
+            if inner_value.has_key? 'text'
+              a_button.set_text(inner_value['text'])
+            end
+            # =============================================================== #
+            # === css_class
+            # =============================================================== #
+            if inner_value.has_key? 'css_class'
+              a_button.use_these_css_classes(
+                inner_value['css_class']
+              )
+            end
+            # =============================================================== #
+            # Buttons always respond to on-clicked events.
+            # =============================================================== #
+            perform_this_action_on_clicked_event = inner_value['on_clicked'].to_sym
+            a_button.on_clicked {
+              if respond_to?(perform_this_action_on_clicked_event)
+                send(perform_this_action_on_clicked_event)
+              else
+                if be_verbose
+                  e "#{rev}No method called "\
+                    "#{tomato(perform_this_action_on_clicked_event)}"\
+                    "#{tomato('()')}"\
+                    " is defined."
+                end
+              end
+            }
+            # buttons[a_button.object_id] = a_button
+            buttons[use_this_as_the_id.to_sym] = a_button
+          }
+          @internal_hash[:automatically_created_widgets][:buttons] = buttons
+        else
+          e "Unhandled key: #{steelblue(key.to_s)}"
+        end
+      }
+    else
+      e 'Please supply a Hash to this method.'
+      e 'Presently only a Hash is supported.'
+    end
+  end
+
+end; end