gtk_paradise 0.9.120 → 0.12.25

data/lib/gtk_paradise/gtk_classes/box.rb

@@ -2,317 +2,171 @@
 # Encoding: UTF-8
 # frozen_string_literal: true
 # =========================================================================== #
+# === Gtk::Box
+#
+# Note that this is for Gtk::Box, which is new since as of ruby-gtk3.
+# =========================================================================== #
 # require 'gtk_paradise/gtk_classes/box.rb'
 # =========================================================================== #
-module Gtk
+require 'gtk_paradise/toplevel_methods/determine_which_gtk_version_is_in_use.rb'
 
-  require 'gtk_paradise/gtk_classes/vbox.rb'
-  require 'gtk_paradise/toplevel_methods/determine_which_gtk_version_is_in_use.rb'
+return if ::Gtk.do_we_use_gtk2?
 
-  # ========================================================================= #
-  # === Gtk.create_paned_hbox
-  #
-  # This method will create a HBox with several widgets inside of it.
-  #
-  # The widgets go into the only parameter for this method, aptly
-  # called *widgets.
-  #
-  # You can pass in a block to specify the (optional) padding.
-  #
-  # An example for this would be:
-  #
-  #   Gtk.create_paned_hbox(widget1, widget2) { 10 }
-  #
-  # Usage examples:
-  #
-  #   Gtk.create_paned_hbox(Gtk::Button.new,Gtk::Button.new, Gtk::Button.new)
-  #   Gtk.create_paned_hbox(widget1, widget2)
-  #   Gtk.paned(a, b, c)
-  #
-  # ========================================================================= #
-  def self.create_paned_hbox(*widgets)
-    widgets.flatten!
-    default_padding = block_given? ? yield : 2
-    if do_we_use_gtk2?
-      hbox = Gtk::HBox.new
-    else
-      hbox = Gtk::Box.new(:horizontal)
-    end
-    if do_we_use_gtk2?
-      widgets.size.times { |entry| # Next batch-add it onto the hbox here.
-        hbox.pack_start(widgets[entry],true,true, default_padding)
-      }
-    else
-      widgets.size.times { |entry| # Next batch-add it onto the hbox here.
-        hbox.pack_start(widgets[entry], expand: true, fill: true, padding: default_padding)
-      }
-    end
-    return hbox.show
-  end; self.instance_eval { alias chbox       create_paned_hbox } # === Gtk.chbox
-       self.instance_eval { alias create_hbox create_paned_hbox } # === Gtk.create_hbox
-       self.instance_eval { alias hbox        create_paned_hbox } # === Gtk.hbox
-       self.instance_eval { alias add_hbox    create_paned_hbox } # === Gtk.add_hbox
-       self.instance_eval { alias hpaned      create_paned_hbox } # === Gtk.hpaned
-       self.instance_eval { alias paned_hbox  create_paned_hbox } # === Gtk.paned_hbox
+# =========================================================================== #
+# We assume only ruby-gtk3 and ruby-gtk4 to be here past this point.
+# =========================================================================== #
+module Gtk
 
-  # ========================================================================= #
-  # === Gtk.event_box
-  #
-  # If an argument is supplied to this method then it is assumed that
-  # the user wants to attach a particular widget to a Gtk::EventBox,
-  # as-is.
-  # ========================================================================= #
-  def self.event_box(
-      optional_argument = nil
-    )
-    if optional_argument
-      ::Gtk::EventBox.new.add(optional_argument)
-    else
-      ::Gtk::EventBox.new
-    end
-  end; self.instance_eval { alias eventbox event_box } # === Gtk.eventbox
+class Box # This is specifically for gtk3 and gtk4.
+
+  if respond_to? :set_spacing
+    alias set_padding set_spacing # === set_padding
+  end
 
   # ========================================================================= #
-  # === Gtk.padded_vbox
+  # === text
   # ========================================================================= #
-  def self.padded_vbox(
-      n_padding_to_use = 8
-    )
-    _ = vbox
-    _.set_border_width(n_padding_to_use)
-    return _
+  def text(i, padding_to_use = 2)
+    minimal(::Gtk::Label.new(i), padding_to_use)
   end
 
   # ========================================================================= #
-  # === Gtk.padded_hbox
+  # === left_aligned_text
   # ========================================================================= #
-  def self.padded_hbox(
-      n_padding_to_use = 8
-    )
-    _ = hbox
-    _.set_border_width(n_padding_to_use)
-    return _
+  def left_aligned_text(i, padding_to_use = 2)
+    text = ::Gtk::Label.new(i)
+    text.left_align
+    minimal(text, padding_to_use)
   end
 
   # ========================================================================= #
-  # === Gtk.create_paned_vbox
-  #
-  # This will use a default padding of 2.
+  # === add_space
   #
-  # create_paned_vbox(widget1,widget2)
+  # This is, ultimately for now, just a vertical "spacer". At a later
+  # time we may have to query the orientation of the box, but for
+  # now it just sufficed for my use case to define it as vertical.
   # ========================================================================= #
-  def self.create_paned_vbox(*widgets)
-    default_padding = block_given? ? yield : 2
-    if do_we_use_gtk2?
-      vbox = ::Gtk::VBox.new
-    else # else we assume that ruby-gtk3 is used.
-      vbox = ::Gtk::Box.new(:vertical)
-    end
-    widgets.flatten!
-    widgets.size.times { |t|
-      if do_we_use_gtk2?
-        vbox.pack_start(widgets[t], true, true, default_padding)
-      else
-        vbox.pack_start(widgets[t], expand: true, fill: true, padding: default_padding)
-      end
-    }
-    return vbox.show
-  end; self.instance_eval { alias vbox       create_paned_vbox } # === Gtk.vbox
-       self.instance_eval { alias add_vbox   create_paned_vbox } # === Gtk.add_vbox
-       self.instance_eval { alias paned_vbox create_paned_vbox } # === Gtk.paned_vbox
+  def add_space
+    ::Gtk.vertical_spacer
+  end
+
+end
+
+# =========================================================================== #
+# === Gtk.create_vbox
+#
+# This method can be used to create a vbox, a "vertical box".
+#
+# In the past, up until October 2022, the default parameters for this
+# method were "i = ARGV", but this can create issues when the user
+# passes a String, since this method will then erroneously assume
+# that these Strings constitute widgets to be added - which is not
+# correct. Thus, the parameters were changed towards "*i". 
+# =========================================================================== #
+def self.create_vbox(*i)
+  box = ::Gtk::Box.new(:vertical)
+  [i].flatten.compact.each {|widget_to_be_added|
+    box.add_or_append(widget_to_be_added)
+  }
+  return box
+end; self.instance_eval { alias vbox        create_vbox } # === Gtk.vbox
+     self.instance_eval { alias return_vbox create_vbox } # === Gtk.return_vbox
 
+# =========================================================================== #
+# === Gtk.hbox
+#
+# This method accepts a variable amount of input, which will be
+# the widgets that we will put into this widget.
+#
+# Keep in mind that input to this method may be like this:
+#
+#   hbox = gtk_hbox(
+#      bold_label: 'Merge these images together:',
+#      entry: @gtk_entry_for_merging_images
+#    )
+#
+# Note that since as of September 2022 this is permissive, even for
+# ruby-gtk3, as ruby-gtk2 will specifically only pull in vbox.rb
+# and hbox.rb.
+# =========================================================================== #
+def self.hbox(
+    *boxes, &block
+  )
+  append_mode = :minimal
+  _ = ::Gtk::Box.new(:horizontal)
+  # ========================================================================= #
+  # Handle blocks next
+  # ========================================================================= #
+  if block_given?
+    yielded = yield
+    case yielded
+    when :maximal
+      append_mode = :maximal
+    end
+    if boxes.empty?
+      boxes = [yielded]
+    end
+  end
   # ========================================================================= #
-  # === Gtk.hbox
-  #
-  # This method accepts a variable amount of input, which will be
-  # the widgets that we will put into this widget.
-  #
-  # Keep in mind that input to this method may be like this:
-  #
-  #   hbox = gtk_hbox(
-  #      bold_label: 'Merge these images together:',
-  #      entry: @gtk_entry_for_merging_images
-  #    )
-  #
+  # Handle the "boxes" argument next.
   # ========================================================================= #
-  def self.hbox(*boxes, &block)
-    if do_we_use_gtk2?
-      _ = ::Gtk::HBox.new
-    else # else we are using gtk3, most likely.
-      _ = ::Gtk::Box.new(:horizontal, 0)
-    end
-    # ======================================================================= #
-    # Handle blocks next
-    # ======================================================================= #
-    if block_given?
-      yielded = yield
-      if boxes.empty?
-        boxes = [yielded]
-      end
+  boxes.flatten.each {|box|
+    if box.is_a? String
+      box = ::Gtk.text(box)
     end
     # ======================================================================= #
-    # Handle the "boxes" argument next.
+    # === Handle Hashes next
     # ======================================================================= #
-    boxes.flatten.each {|box|
+    if box.is_a? Hash
       # ===================================================================== #
-      # === Handle Hashes next
+      # We must iterate through this Hash now, via .each_pair, to retain
+      # the original structure. Otherwise the gtk-entry may appear on
+      # the left side, whereas it was specified last in that Hash.
       # ===================================================================== #
-      if box.is_a? Hash
+      box.each_pair {|key, value|
+        case key
         # =================================================================== #
-        # We must iterate through this Hash now, via .each_pair, to retain
-        # the original structure. Otherwise the gtk-entry may appear on
-        # the left side, whereas it was specified last in that Hash.
+        # === hbox = gtk_hbox {{ spacing: 10 }}
         # =================================================================== #
-        box.each_pair {|key, value|
-          case key
-          # ================================================================= #
-          # === hbox = gtk_hbox {{ spacing: 10 }}
-          # ================================================================= #
-          when :spacing
-            _.set_spacing(value)
-          # ================================================================= #
-          # === entry
-          #
-          # This entry point assumes that the user provided a Gtk::Entry
-          # to this method.
-          # ================================================================= #
-          when :entry
+        when :spacing
+          _.set_spacing(value)
+        # =================================================================== #
+        # === entry
+        #
+        # This entry point assumes that the user provided a Gtk::Entry
+        # to this method.
+        # =================================================================== #
+        when :entry
+          if append_mode == :maximal
+            _.maximal(value) # Add the widget here at once.
+          else
             _.minimal(value) # Add the widget here at once.
-          # ================================================================= #
-          # === :bold_label
-          # ================================================================= #
-          when :bold_label
-            _.minimal(gtk_label(value).make_bold)
+          end
+        # =================================================================== #
+        # === :bold_label
+        # =================================================================== #
+        when :bold_label
+          if append_mode == :maximal
+            _.maximal(gtk_label(value).make_bold)
           else
-            # =============================================================== #
-            # At this point we should check whether the key is unhandled.
-            # =============================================================== #
-            puts 'Unhandled keys in the Hash: '+key.to_s
+            _.minimal(gtk_label(value).make_bold)
           end
-        }
+        else
+          # ================================================================= #
+          # At this point we should check whether the key is unhandled.
+          # ================================================================= #
+          puts 'Unhandled keys in the Hash: '+key.to_s
+        end
+      }
+    else
+      if append_mode == :maximal
+        _.maximal(box)
       else
         _.minimal(box)
       end
-    }
-    _ # And return our widget here.
-  end
-
-if do_we_use_gtk2?
-
-  # ========================================================================= #
-  # === Gtk::HBox
-  # ========================================================================= #
-  class HBox
-
-    alias pack pack_start # === pack
-
-  end
-
-  # ========================================================================= #
-  # === Add an "alias" to HBox if we use ruby-gtk2.
-  # ========================================================================= #
-  Hbox = ::Gtk::HBox
-
-  # ========================================================================= #
-  # === Gtk.return_hbox
-  # ========================================================================= #
-  def self.return_hbox
-    ::Gtk::HBox.new
-  end
-
-  # ========================================================================= #
-  # === Gtk.create_paned_hbox_first_big
-  #
-  # First widget takes up most space here.
-  #
-  #   Gtk.create_paned_hbox_first_big(Gtk::Button.new, Gtk::Button.new, Gtk::Button.new)
-  #
-  # ========================================================================= #
-  def self.create_paned_hbox_first_big(*widgets)
-    widgets.flatten! # Don't forget to flatten here.
-    hbox = ::Gtk::HBox.new
-    widgets.size.times { |t|
-      if t == 0
-        hbox.pack_start(widgets[t], true, true,1)
-      else
-        hbox.pack_start(widgets[t], false, true,1)
-      end
-    }
-    return hbox.show
-  end
-
-  # ========================================================================= #
-  # === Gtk.create_paned_vbox_last_big
-  #
-  # For this method, the first widget passed in (aka the first argument)
-  # will take up most space here. This may fit if you want to use a 
-  # large image on the left-hand side, and then some label on the right
-  # hand side describing when this picture was taken, or a similar
-  # use case.
-  #
-  # Usage example:
-  #
-  #   create_paned_vbox_last_big(Gtk::Button.new, Gtk::Button.new, Gtk::Button.new)
-  #
-  # ========================================================================= #
-  def self.create_paned_vbox_last_big(*widgets)
-    widgets.flatten!
-    how_many_slots = widgets.size
-    vbox = ::Gtk::VBox.new
-    how_many_slots.times { |entry|
-      case entry
-      when 0
-        vbox.pack_start(widgets[entry], false, true, 1)
-      else
-        vbox.maximal(widgets[entry], 1)
-      end
-    }
-    return vbox.show
-  end
-
-  # ========================================================================= #
-  # === Gtk.create_paned_hbox_last_big
-  #
-  # First widget takes up most space here. hbox means "horizontal box".
-  #
-  # Usage example via the gtk-paradise gem:
-  #
-  #   Gtk.create_paned_hbox_last_bigg(gtk_button, gtk_button, gtk_button)
-  #
-  # ========================================================================= #
-  def self.create_paned_hbox_last_big(*widgets)
-    how_many_slots = widgets.size
-    hbox = ::Gtk::HBox.new
-    how_many_slots.times { |t|
-      case t
-      when 0
-        hbox.pack_start(widgets[t],false,true,1)
-      else
-        hbox.pack_start(widgets[t],true,true,1)
-      end
-    }
-    return hbox.show
-  end
-
-else # else assume ruby-gtk3 here.
-
-  class Box # This is specifically for gtk3.
-
-    alias set_padding set_spacing # === set_padding
-
-    # ======================================================================= #
-    # === add_space
-    #
-    # This is, ultimately for now, just a vertical "spacer". At a later
-    # time we may have to query the orientation of the box, but for
-    # now it just sufficed for my use case to define it as vertical.
-    # ======================================================================= #
-    def add_space
-      ::Gtk.vertical_spacer
     end
-
-  end
-
+  }
+  _ # And return our widget here.
 end
 
 end

data/lib/gtk_paradise/gtk_classes/button.rb

@@ -10,10 +10,41 @@
 # =========================================================================== #
 module Gtk
 
-class Button
+class Button # === Gtk::Button
 
+  # ========================================================================= #
+  # The next line is necessary to determine which functionality works
+  # for the different gtk-variants.
+  # ========================================================================= #
   require 'gtk_paradise/toplevel_methods/determine_which_gtk_version_is_in_use.rb'
 
+  # ========================================================================= #
+  # === set_halign
+  # ========================================================================= #
+  unless Gtk.do_we_use_gtk4?
+    alias set_halign set_xalign # === set_halign
+  end
+
+  # ========================================================================= #
+  # === no_border
+  # ========================================================================= #
+  def no_border
+    set_relief(Gtk::ReliefStyle::NONE) # At the least for gtk3.
+  end
+
+  # ========================================================================= #
+  # === align_to_the_left_side
+  #
+  # This will focus the text on the button towards the left side.
+  # ========================================================================= #
+  def align_to_the_left_side
+    self.xalign = 0.0
+  end; alias align_to_the_left        align_to_the_left_side # === align_to_the_left
+       alias text_is_on_the_left_side align_to_the_left_side # === text_is_on_the_left_side
+       alias text_is_left             align_to_the_left_side # === text_is_left
+       alias left_align               align_to_the_left_side # === left_align
+       alias align_towards_the_left   align_to_the_left_side # === align_towards_the_left
+
   # ========================================================================= #
   # === hover_colour=
   #
@@ -23,7 +54,9 @@ class Button
   # The argument to this method should be the colour that you want to
   # use, ideally as a symbol.
   # ========================================================================= #
-  def hover_colour=(i = :paleturquoise)
+  def hover_colour=(
+      i = :paleturquoise
+    )
     prelight = :prelight # Assume ruby-gtk3 by default.
     prelight = ::Gtk::STATE_PRELIGHT if ::Gtk.use_gtk2?
     modify_bg(
@@ -98,28 +131,11 @@ class Button
     signal_emit(:clicked)
   end
 
-  # ========================================================================= #
-  # === set_halign
-  # ========================================================================= #
-  alias set_halign set_xalign # === set_halign
-
   # ========================================================================= #
   # === text?
   # ========================================================================= #
   alias text? label
 
-  # ========================================================================= #
-  # === align_to_the_left_side
-  #
-  # This will focus the text on the button towards the left side.
-  # ========================================================================= #
-  def align_to_the_left_side
-    self.xalign = 0.0
-  end; alias align_to_the_left        align_to_the_left_side # === align_to_the_left
-       alias text_is_on_the_left_side align_to_the_left_side # === text_is_on_the_left_side
-       alias text_is_left             align_to_the_left_side # === text_is_left
-       alias left_align               align_to_the_left_side # === left_align
-
   # ========================================================================= #
   # === apply_mnemonic
   # ========================================================================= #
@@ -149,22 +165,6 @@ class Button
     self.use_underline = true
   end; alias enable_markup do_use_underline # === enable_markup
 
-  require 'gtk_paradise/gtk_classes/label.rb' # ← Necessary for .make_bold() below.
-  # ========================================================================= #
-  # === make_bold
-  #
-  # This method will make the text of the button at hand bold.
-  # ========================================================================= #
-  def make_bold(
-      retain_mnemonic = :default
-    )
-    child = self.children.first
-    child.make_bold(
-      :use_the_default_text,
-      retain_mnemonic
-    ) # ← ^^^ This will delegate to Gtk::Label, and calls .make_bold() there.
-  end
-
   # ========================================================================= #
   # === relief_none
   # ========================================================================= #
@@ -205,14 +205,14 @@ class Button
   # ========================================================================= #
   def enable_the_button
     set_sensitive(true)
-  end
+  end; alias is_active enable_the_button # === is_active
 
   # ========================================================================= #
   # === disable_the_button
   # ========================================================================= #
   def disable_the_button
     set_sensitive(false)
-  end
+  end; alias is_inactive disable_the_button # === is_inactive
 
   # ========================================================================= #
   # === background_colours
@@ -264,11 +264,29 @@ class Button
     end
   end
 
+  # ========================================================================= #
+  # === make_bold
+  #
+  # This method will make the text of the button at hand bold.
+  # ========================================================================= #
+  def make_bold(
+      retain_mnemonic = :default
+    )
+    child = self.children.first
+    unless child.respond_to?(:make_bold)
+      require 'gtk_paradise/gtk_classes/label.rb' # ← Necessary for .make_bold() below.
+    end
+    child.make_bold(
+      :use_the_default_text,
+      retain_mnemonic
+    ) # ← ^^^ This will delegate to Gtk::Label, and calls .make_bold() there.
+  end
+
   # ========================================================================= #
   # === attach_this_image
   # ========================================================================= #
   # def attach_this_image(i)
-  #   cmd('  @button.set_image(@image)')+
+  #   @button.set_image(@image)
   # end
   # alias attach_this_image set_image # === attach_this_image
 
@@ -332,13 +350,16 @@ def self.create_button(
   # ========================================================================= #
   if block_given?
     yielded = yield
+    # ======================================================================= #
+    # === Symbols passed as blocks are treated in a special way
+    # ======================================================================= #
     if yielded.is_a? Symbol
       case yielded
-      # ======================================================================= #
+      # ===================================================================== #
       # === :on_click_exit
       #
       # This entry point is used to exit, on clicking that button.
-      # ======================================================================= #
+      # ===================================================================== #
       when :on_click_exit,
            :exit_on_click_event
         button.on_clicked {

data/lib/gtk_paradise/gtk_classes/button_box.rb

@@ -3,9 +3,15 @@
 # frozen_string_literal: true
 # =========================================================================== #
 # === Gtk::ButtonBox
+#
+# This seems to no longer exist in ruby-gtk4.
 # =========================================================================== #
 # require 'gtk_paradise/gtk_classes/button_box.rb'
 # =========================================================================== #
+require 'gtk_paradise/toplevel_methods/determine_which_gtk_version_is_in_use.rb'
+
+unless Gtk.use_gtk4?
+
 module Gtk
 
 class ButtonBox # === Gtk::ButtonBox
@@ -35,4 +41,6 @@ class ButtonBox # === Gtk::ButtonBox
     self.layout = :center
   end; alias do_center center # === do_center
     
-end; end
+end; end
+
+end

data/lib/gtk_paradise/gtk_classes/cell_renderer_text.rb

@@ -2,6 +2,8 @@
 # Encoding: UTF-8
 # frozen_string_literal: true
 # =========================================================================== #
+# === Gtk::CellRendererText
+# =========================================================================== #
 # require 'gtk_paradise/gtk_classes/cell_renderer_text.rb'
 # =========================================================================== #
 module Gtk
@@ -40,9 +42,9 @@ end; self.instance_eval { alias cell_renderer_text create_cell_renderer_text } #
 # get go.
 # =========================================================================== #
 def self.return_editable_cell_renderer_text
-  renderer = ::Gtk::CellRendererText.new
-  renderer.editable = true
-  return renderer
+  _ = ::Gtk::CellRendererText.new
+  _.editable = true
+  return _
 end
 
 # =========================================================================== #