gtk_paradise 0.9.120 → 0.12.25

data/lib/gtk_paradise/gtk_classes/entry.rb

@@ -30,12 +30,10 @@ module Gtk
 
 class Entry # === Gtk::Entry
 
-  require 'gtk_paradise/toplevel_methods/allow_only_numbers.rb'
-  require 'gtk_paradise/toplevel_methods/enable_and_disable_warnings.rb'
   require 'gtk_paradise/toplevel_methods/determine_which_gtk_version_is_in_use.rb'
-  require 'gtk_paradise/toplevel_methods/we_use_this_gtk_version.rb'
+  require 'gtk_paradise/toplevel_methods/toplevel_methods.rb'
 
-  Gtk.disable_warnings # ← Explained on top of this file.
+  # Gtk.disable_warnings # ← Explained on top of this file.
 
   # ========================================================================= #
   # === initialize
@@ -45,31 +43,270 @@ class Entry # === Gtk::Entry
   # The first argument is any default entry to be used. The default
   # entry will be an empty '' String.
   # ========================================================================= #
-  def initialize(
-      default_argument = :default
-    )
-    super()
-    case default_argument
-    # ======================================================================= #
-    # === :default
-    # ======================================================================= #
-    when :default
-      default_argument = ''
+  #def initialize(
+  #    default_argument = :default
+  #  )
+  #  super()
+  #  case default_argument
+  #  # ======================================================================= #
+  #  # === :default
+  #  # ======================================================================= #
+  #  when :default
+  #    default_argument = ''
+  #  end
+  #  set_text(default_argument)
+  #end
+  # Gtk.enable_warnings # And re-enable the warnings here.
+
+  alias text? text # === text?
+
+  if ::Gtk.use_gtk4?
+    def set_focus(i = false)
+      # ===================================================================== #
+      # Currently does nothing. set_focus() is possible in ruby-gtk3
+      # but was disabled in ruby-gtk4.
+      # ===================================================================== #
     end
-    set_text(default_argument)
   end
 
-  Gtk.enable_warnings # And re-enable the warnings here.
+  # ========================================================================= #
+  # === <<
+  #
+  # This method name is a slight misnomer, but I want to be able to use
+  # << onto a gtk-entry as well.
+  # ========================================================================= #
+  def <<(i)
+    set_text(i.to_s)
+  end
 
-  alias text? text # === text?
+  # ========================================================================= #
+  # === set_maxsize
+  # ========================================================================= #
+  def set_maxsize(i)
+    set_max_length(i)
+  end
 
   # ========================================================================= #
   # === make_scrollable
+  #
+  # This method allows us to tell a gtk-entry widget to respond to
+  # mouse-scroll events.
   # ========================================================================= #
   def make_scrollable
     add_events(:scroll_mask)
+  end; alias respond_to_scroll_events make_scrollable # === respond_to_scroll_events
+
+  # ========================================================================= #
+  # === increment_by
+  # ========================================================================= #
+  def increment_by(i = 1)
+    old_value = text?.to_i
+    new_value = old_value + i
+    set_text(new_value.to_s)
+  end
+
+  # ========================================================================= #
+  # === ghost_text
+  #
+  # This is essentially a placeholder text, as a hint, which was added
+  # in gtk3.
+  # ========================================================================= #
+  if ::Gtk.use_gtk3?
+    alias ghost_text   set_placeholder_text # === ghost_text
+    alias ghost_text=  set_placeholder_text # === ghost_text=
+    alias shadow_hint= set_placeholder_text # === shadow_hint=
+    alias shadow_text= set_placeholder_text # === shadow_text=
+    alias ghost=       set_placeholder_text # === shadow_text=
+  else
+    # ======================================================================= #
+    # === ghost_text
+    # ======================================================================= #
+    def ghost_text(i)
+      set_text(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === move_cursor_to_the_most_right_position
+  # ========================================================================= #
+  def move_cursor_to_the_most_right_position
+    self.position = -1
+  end; alias cursor_is_to_the_right move_cursor_to_the_most_right_position # === cursor_is_to_the_right
+       alias cursor_is_right        move_cursor_to_the_most_right_position # === cursor_is_right
+       alias cursor_is_on_the_end   move_cursor_to_the_most_right_position # === cursor_is_on_the_end
+
+  # ========================================================================= #
+  # === align_to_the_right
+  # ========================================================================= #
+  def align_to_the_right
+    self.xalign = 1
+  end
+
+  # ========================================================================= #
+  # === default_styling
+  #
+  # Simply enable the default-entry CSS styling.
+  # ========================================================================= #
+  def default_styling
+    css_class('default_entry')
+  end; alias default_entry  default_styling # === default_entry
+       alias default_values default_styling # === default_values
+
+  # ========================================================================= #
+  # === try_to_remove_the_last_character
+  #
+  # This method will try to remove the last character, if there is
+  # any text. Minimum text will be ''.
+  # ========================================================================= #
+  def try_to_remove_the_last_character(
+      _ = text?
+    )
+    if _.size > 0
+      set_text(_[0 .. -2].to_s)
+    end
+  end
+
+  # ========================================================================= #
+  # === enable_this_action_on_enter_key
+  #
+  # This method only works for actions associated with the entry-widget.
+  # ========================================================================= #
+  def enable_this_action_on_enter_key(this_method)
+    on_key_press_event { |widget, event|
+      send(this_method)
+    }
+  end; alias enable_action_on_enter_key enable_this_action_on_enter_key # === enable_action_on_enter_key
+
+  # ========================================================================= #
+  # === treat_the_last_comment_as_synonymous_for_on_enter_event
+  #
+  # Pass a block to this method.
+  #
+  # Usage example:
+  #
+  #   @entry = entry
+  #   @entry.treat_the_last_comment_as_synonymous_for_on_enter_event {
+  #     run_this_method(@entry)
+  #   }
+  #
+  # ========================================================================= #
+  def treat_the_last_comment_as_synonymous_for_on_enter_event(&block)
+    on_changed {|widget, event| # event is probably nil.
+      new_text = widget.text?
+      if new_text and (new_text[-1, 1] == '#')
+        if block_given?
+          yield
+        end
+        # =================================================================== #
+        # Next we must remove the last character:
+        # =================================================================== #
+        widget.set_text(new_text[0 .. -2])
+        true
+      else
+        false
+      end
+    }
+  end
+
+  # ========================================================================= #
+  # === on_enter_event_select_this
+  # ========================================================================= #
+  def on_enter_event_select_this
+    on_button_press_event { |widget, event|
+      set_focus(true)
+      select_region(0, -1)
+    }
+  end
+
+  # ========================================================================= #
+  # === on_click_colour_change_to_this_colour
+  #
+  # The first argument is the colour to which you want to change the entry
+  # to.
+  #
+  # The second argument (a Hash) may contain the key :duration, which is
+  # used to denote when to revert to the old default.
+  #
+  # Usage example:
+  #
+  #   on_click_colour_change_to_this_colour(:steelblue, { duration: 3 })
+  #
+  # ========================================================================= #
+  def on_click_colour_change_to_this_colour(
+      use_this_colour = :mintcream,
+      hash            = {}
+    )
+    signal_connect(:event) {|widget, event|
+      if ::Gtk.event_left_mouse_button_click?(event)
+        old_name = name # Keep track of the original colour.
+        set_name(use_this_colour.to_s)
+        Thread.new {
+          duration = hash[:duration] # Assume n seconds here.
+          sleep duration
+          set_name(old_name)
+        }.join
+      end
+    }
+  end
+
+  # ========================================================================= #
+  # === deselect_everything
+  # ========================================================================= #
+  def deselect_everything
+    set_focus(false)
+    select_region(0, 0)
   end
 
+  # ========================================================================= #
+  # === allow_only_numbers
+  #
+  # This method accepts one main argument, which should be your Gtk widget.
+  # Usually this will be a Gtk::Entry by default.
+  #
+  # This widget will then only react to NUMBERS input given, such as 1, 3
+  # or 8. Other input will be rejected.
+  #
+  # That way you can make "input-fields" that will only have numbers, and
+  # no other characters allowed. The user then is assisted to provide
+  # only# valid input, and avoid faulty, unwanted input.
+  #
+  # Do note that a specialized Widget also exists, called
+  # NumbersOnly (in the file aptly named numbers_only.rb).
+  # ========================================================================= #
+  def allow_only_numbers(
+      be_not_too_strict = true
+    )
+    case be_not_too_strict
+    # ========================================================================= #
+    # === :default
+    # ========================================================================= #
+    when :default
+      be_not_too_strict = true
+    end
+    signal_connect(:key_press_event) { |widget, event|
+      keyval = Gdk::Keyval.to_name(event.keyval)
+      case keyval
+      when /\d/
+        false
+      else
+        if be_not_too_strict
+          # ================================================================= #
+          # === Only escape BackSpace in this case
+          # ================================================================= #
+          case keyval
+          when 'BackSpace'
+            false
+          else
+            true
+          end
+        else
+          true
+        end
+      end 
+    }
+  end; alias allow_only_numbers_as_input  allow_only_numbers # === allow_only_numbers_as_input
+       alias accept_only_numbers_as_input allow_only_numbers # === accept_only_numbers_as_input
+
   # ========================================================================= #
   # === simple_completion
   #
@@ -93,11 +330,13 @@ class Entry # === Gtk::Entry
   def set_read_only
     self.editable = false
   end; alias may_not_be_modified                set_read_only # === may_not_be_modified
+       alias can_not_be_modified                set_read_only # === can_not_be_modified
        alias disable_user_input                 set_read_only # === disable_user_input
        alias disallow_changes                   set_read_only # === disallow_changes
        alias the_user_may_not_modify_this_entry set_read_only # === the_user_may_not_modify_this_entry
        alias is_read_only                       set_read_only # === is_read_only
        alias read_only                          set_read_only # === read_only
+       alias readonly                           set_read_only # === readonly
 
   # ========================================================================= #
   # === append_text
@@ -113,33 +352,6 @@ class Entry # === Gtk::Entry
     set_text("#{self.text}#{this_text}")
   end
 
-  # ========================================================================= #
-  # === move_cursor_to_the_most_right_position
-  # ========================================================================= #
-  def move_cursor_to_the_most_right_position
-    self.position = -1
-  end; alias cursor_is_to_the_right move_cursor_to_the_most_right_position # === cursor_is_to_the_right
-       alias cursor_is_right        move_cursor_to_the_most_right_position # === cursor_is_right
-
-  # ========================================================================= #
-  # === ghost_text
-  #
-  # This is essentially a placeholder text, as a hint, which was added
-  # in gtk3.
-  # ========================================================================= #
-  if ::Gtk.use_gtk3?
-    alias ghost_text   set_placeholder_text # === ghost_text
-    alias shadow_hint= set_placeholder_text # === shadow_hint=
-    alias shadow_text= set_placeholder_text # === shadow_text=
-  else
-    # ======================================================================= #
-    # === ghost_text
-    # ======================================================================= #
-    def ghost_text(i)
-      set_text(i)
-    end
-  end
-
   # ========================================================================= #
   # === do_upcase_the_first_character
   # ========================================================================= #
@@ -149,6 +361,15 @@ class Entry # === Gtk::Entry
     set_text(_)
   end
 
+  # ========================================================================= #
+  # === do_upcase
+  #
+  # This method will upcase the text of the entry at hand.
+  # ========================================================================= #
+  def do_upcase
+    set_text(text?.to_s.upcase)
+  end
+
   # ========================================================================= #
   # === on_click_highlight_all
   #
@@ -174,8 +395,9 @@ class Entry # === Gtk::Entry
   # ========================================================================= #
   # === enable_search_icon
   # ========================================================================= #
-  def enable_search_icon
-    icon_name = 'system-search-symbolic'
+  def enable_search_icon(
+      icon_name = 'system-search-symbolic'
+    )
     set_icon_from_icon_name(
       ::Gtk::EntryIconPosition::PRIMARY,
       icon_name
@@ -203,24 +425,6 @@ class Entry # === Gtk::Entry
     set_visibility(false)
   end; alias dissappear do_disappear # === dissappear
 
-  # ========================================================================= #
-  # === on_enter_event_select_this
-  # ========================================================================= #
-  def on_enter_event_select_this
-    on_button_press_event { |widget, event|
-      set_focus(true)
-      select_region(0, -1)
-    }
-  end
-
-  # ========================================================================= #
-  # === deselect_everything
-  # ========================================================================= #
-  def deselect_everything
-    set_focus(false)
-    select_region(0, 0)
-  end
-
   # ========================================================================= #
   # === deselect_all_on_click_event
   # ========================================================================= #
@@ -263,33 +467,6 @@ class Entry # === Gtk::Entry
     self.inner_border = ::Gtk::Border.new(i[0], i[1], i[2], i[3])
   end; alias inner_padding= border # === inner_padding=
 
-  # ========================================================================= #
-  # === allow_only_numbers
-  # ========================================================================= #
-  def allow_only_numbers(b = :default)
-    ::Gtk.allow_only_numbers(self, b)
-  end; alias allow_only_numbers_as_input allow_only_numbers # === allow_only_numbers_as_input
-
-  # ========================================================================= #
-  # === on_click_colour_change_to_this_colour
-  # ========================================================================= #
-  def on_click_colour_change_to_this_colour(
-      use_this_colour = :mintcream,
-      hash            = {}
-    )
-    signal_connect(:event) {|widget, event|
-      if ::Gtk.event_left_mouse_button_click?(event)
-        old_name = name # Keep track of the original colour.
-        set_name(use_this_colour.to_s)
-        Thread.new {
-          duration = hash[:duration]
-          sleep duration
-          set_name(old_name)
-        }.join
-      end
-    }
-  end
-
   # ========================================================================= #
   # === return_input
   # ========================================================================= #
@@ -304,13 +481,6 @@ class Entry # === Gtk::Entry
     return_input.empty?
   end
 
-  # ========================================================================= #
-  # === align_to_the_right
-  # ========================================================================= #
-  def align_to_the_right
-    self.xalign = 1
-  end
-
   # ========================================================================= #
   # === default=
   #
@@ -335,17 +505,6 @@ class Entry # === Gtk::Entry
     end
   end
 
-  # ========================================================================= #
-  # === enable_this_action_on_enter_key
-  #
-  # This method only works for actions associated with the entry-widget.
-  # ========================================================================= #
-  def enable_this_action_on_enter_key(this_method)
-    on_key_press_event { |widget, event|
-      send(this_method)
-    }
-  end; alias enable_action_on_enter_key enable_this_action_on_enter_key # === enable_action_on_enter_key
-
   # ========================================================================= #
   # === clear
   #
@@ -372,27 +531,12 @@ class Entry # === Gtk::Entry
     select_region(0, -1)
   end; alias select_everything do_select_everything # === select_everything
 
-  # ========================================================================= #
-  # === try_to_remove_the_last_character
-  #
-  # This method will try to remove the last character, if there is
-  # any text. Minimum text will be ''.
-  # ========================================================================= #
-  def try_to_remove_the_last_character
-    _ = text?
-    if _.size > 0
-      set_text(_[0 .. -2].to_s)
-    end
-  end
-
   # ========================================================================= #
   # === allow_enter
   # ========================================================================= #
   def allow_enter
     set_activates_default(true)
-  end
-
-  alias set_maxsize set_max_length # === set_maxsize
+  end; alias enable_enter_event allow_enter # === enable_enter_event
 
 end
 
@@ -415,10 +559,21 @@ end
 def self.input_field(
     i = :default, &block
   )
-  entry = Gtk::Entry.new(i)
+  entry = Gtk::Entry.new
+  if i
+    case i
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      i = '' 
+    end
+    entry.set_text(i)
+  end
   if block_given?
     yielded = yield
     if yielded.is_a? Hash
+      # === :max_length
       if yielded.has_key? :max_length
         entry.set_max_length(yielded.delete(:max_length))
       end

data/lib/gtk_paradise/gtk_classes/entry_completion.rb

@@ -12,19 +12,15 @@ class EntryCompletion # === Gtk::EntryCompletion
 
   require 'gtk_paradise/gtk_classes/widget.rb'
 
-  # ========================================================================= #
-  # === first_text_column
-  # ========================================================================= #
-  def first_text_column
-    self.text_column = 0
-  end; alias first_text_column_is_active first_text_column # === first_text_column
-
   # ========================================================================= #
   # === populate_with_this_array
   #
   # This method assumes that the input is an Array of Strings.
   # ========================================================================= #
-  def populate_with_this_array(array)
+  def populate_with_this_array(
+      array
+    )
+    array.flatten! # Always keep it flat.
     model = ::Gtk::ListStore.new(String) # This is our model.
     array.each { |word|
       iter = model.append
@@ -34,6 +30,13 @@ class EntryCompletion # === Gtk::EntryCompletion
     first_text_column_is_active
   end; alias set_completion populate_with_this_array # === set_completion
 
+  # ========================================================================= #
+  # === first_text_column
+  # ========================================================================= #
+  def first_text_column
+    self.text_column = 0
+  end; alias first_text_column_is_active first_text_column # === first_text_column
+
   # ========================================================================= #
   # === enable_all_events
   #
@@ -42,6 +45,10 @@ class EntryCompletion # === Gtk::EntryCompletion
   #
   # This currently only works for ruby-gtk3. Not sure if we should enable
   # it for ruby-gtk2 as well.
+  #
+  # Note that this may lead to a few problems, so it is almost always
+  # better to only enable the events that you really really need in
+  # your application.
   # ========================================================================= #
   def enable_all_events(
       i = Gdk::EventMask::ALL_EVENTS_MASK

data/lib/gtk_paradise/gtk_classes/event_box.rb

@@ -8,7 +8,7 @@
 # =========================================================================== #
 module Gtk
 
-class EventBox
+class EventBox # === Gtk::EventBox
 
   # ========================================================================= #
   # === on_click_event
@@ -41,4 +41,23 @@ class EventBox
     y
   end; alias y_coordinate? y_position? # === y_coordinate?
 
-end; end
+end
+
+# =========================================================================== #
+# === 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
+
+end

data/lib/gtk_paradise/gtk_classes/event_button.rb

@@ -8,7 +8,7 @@
 # =========================================================================== #
 module Gdk
 
-class EventButton
+class EventButton # === Gdk::EventButton
 
   # ========================================================================= #
   # === x_position?

data/lib/gtk_paradise/gtk_classes/expander.rb

@@ -9,7 +9,14 @@ module Gtk
 
 class Expander # === Gtk::Expander
 
-  alias attach_to_this_widget add # === attach_to_this_widget 
+  require 'gtk_paradise/toplevel_methods/determine_which_gtk_version_is_in_use.rb'
+
+  # ========================================================================= #
+  # === attach_to_this_widget
+  # ========================================================================= #
+  unless Gtk.do_we_use_gtk4?
+    alias attach_to_this_widget add
+  end
 
   # ========================================================================= #
   # === do_expand

data/lib/gtk_paradise/gtk_classes/file_chooser_dialog.rb

@@ -8,7 +8,7 @@
 # =========================================================================== #
 module Gtk
 
-class FileChooserDialog
+class FileChooserDialog # === Gtk::FileChooserDialog
 
   alias add_directory      add_shortcut_folder # === add_directory
   alias add_this_directory add_shortcut_folder # === add_this_directory

data/lib/gtk_paradise/gtk_classes/file_filter.rb

@@ -6,7 +6,7 @@
 # =========================================================================== #
 module Gtk
 
-class FileFilter
+class FileFilter # === Gtk::FileFilter
 
   # ========================================================================= #
   # === custom_filter
@@ -14,7 +14,9 @@ class FileFilter
   # This method allows us to add a custom-filter, e. g. for all "*.rb"
   # files or other file types.
   # ========================================================================= #
-  def custom_filter(i = nil)
+  def custom_filter(
+      i = nil
+    )
     if i
       i = i.to_s unless i.is_a? String
       i = i.dup if i.frozen?

data/lib/gtk_paradise/gtk_classes/file_selection.rb

@@ -16,15 +16,16 @@ module Gtk
   # main GTK dialog.
   # ========================================================================= #
   def self.file_selection(
-      border_width = 5
+      border_width    = 5,
+      window_position = :mouse
     )
     if do_we_use_gtk2?
       file_selection = ::Gtk::FileSelection.new('file selection dialog')
-      file_selection.window_position = ::Gtk::Window::POS_MOUSE
+      window_position = ::Gtk::Window::POS_MOUSE
     else # else assume we use ruby-gtk3.
       file_selection = ::Gtk::FileChooserDialog.new(title: 'file selection dialog')
-      file_selection.window_position = :mouse
     end
+    file_selection.window_position = window_position
 
     file_selection.border_width = border_width
     return_value = file_selection.run # Run it here.