libui_paradise 0.3.9 → 0.4.13

data/lib/libui_paradise/base_module/base_module.rb

@@ -0,0 +1,1514 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === LibuiParadise::BaseModule
+#
+# The module defined in this .rb file is primarly used to "extend"
+# libui in a convenient way. Upon this file being required, several
+# additional actions are performed or made available, such as "alias
+# e puts". That way we only have to require this file and the rest
+# will be set up correctly for us automatically, for reasons of
+# convenience.
+# =========================================================================== #
+# require 'libui_paradise/base_module/base_module.rb'
+# include LibuiParadise::BaseModule
+# =========================================================================== #
+module LibuiParadise
+
+require 'libui' # Mandatory require-call.
+
+# =========================================================================== #
+# === LibuiParadise.initializer
+# =========================================================================== #
+def self.initializer
+  ::LibuiParadise.register_sigint
+  Object.const_set('UI', LibUI) # This is equal to: UI = LibUI
+  ::LibUI.extend(LibuiParadise::BaseModule) # This call will also trigger the extended-hook.
+end
+
+module BaseModule # === LibuiParadise::BaseModule
+
+  alias e puts
+
+  require 'yaml'  # Yaml is really useful, so we'll load it up here as well.
+
+  require 'fileutils' # A useful require-call.
+  require 'libui_paradise/project/project.rb'
+  require 'libui_paradise/colours/colours.rb'
+  require 'libui_paradise/fiddle/fiddle.rb'
+  require 'libui_paradise/toplevel_methods/add_to_the_registered_widgets.rb'
+  require 'libui_paradise/toplevel_methods/hash_fiddle_pointer_widgets.rb'
+  require 'libui_paradise/toplevel_methods/toplevel_methods.rb'
+  require 'libui_paradise/libui_classes/libui_classes.rb'
+  require 'libui_paradise/libui_classes/button.rb'
+  require 'libui_paradise/libui_classes/entry.rb'
+  require 'libui_paradise/libui_classes/msg_box.rb'
+  require 'libui_paradise/libui_classes/msg_box_error.rb'
+  require 'libui_paradise/libui_classes/grid.rb'
+  require 'libui_paradise/libui_classes/hbox.rb'
+  require 'libui_paradise/libui_classes/slider.rb'
+  require 'libui_paradise/libui_classes/spinbox.rb'
+  require 'libui_paradise/libui_classes/vbox.rb'
+
+  # ========================================================================= #
+  # Add support for fiddle next:
+  # ========================================================================= #
+  require 'libui_paradise/fiddle/fiddle.rb'
+
+  # ========================================================================= #
+  # === WIDTH
+  #
+  # Define a default value for the WIDTH constant.
+  # ========================================================================= #
+  WIDTH = 1024
+
+  # ========================================================================= #
+  # === HEIGHT
+  # ========================================================================= #
+  HEIGHT = 680
+
+  # ========================================================================= #
+  # === reset
+  # ========================================================================= #
+  def reset
+    reset_the_internal_hash
+  end
+
+  # ========================================================================= #
+  # === reset_the_internal_hash
+  # ========================================================================= #
+  def reset_the_internal_hash
+    @internal_hash = {}
+  end
+
+  # ========================================================================= #
+  # === create_grid
+  # ========================================================================= #
+  def create_grid
+    ::LibuiParadise.create_grid
+  end; alias grid                create_grid # === grid
+       alias ui_grid             create_grid # === ui_grid
+       alias create_default_grid create_grid # === create_default_grid
+
+  # ========================================================================= #
+  # === register_this_fiddle_pointer_widget
+  #
+  # This method will simply delegate towards:
+  #
+  #   LibuiParadise.register_this_fiddle_pointer_widget()
+  #
+  # ========================================================================= #
+  def register_this_fiddle_pointer_widget(
+      the_fiddle_pointer_widget,
+      the_type_of_the_widget = nil
+    )
+    ::LibuiParadise.register_this_fiddle_pointer_widget(
+      the_fiddle_pointer_widget,
+      the_type_of_the_widget
+    )
+  end; alias add_to_the_registered_widgets register_this_fiddle_pointer_widget # === add_to_the_registered_widgets
+
+  # ========================================================================= #
+  # === button                                                   (button tag)
+  #
+  # This method will create a libui-button. Note that the alias
+  # create_button() is an important alias to this method.
+  # ========================================================================= #
+  def button(
+      text = '',
+      &block
+    )
+    return ::LibuiParadise.button(text, &block)
+  end; alias ui_button     button # === ui_button
+       alias create_button button # === create_button
+
+  # ========================================================================= #
+  # === sfile
+  # ========================================================================= #
+  def sfile(i = '')
+    ::Colours.sfile(i)
+  end
+
+  # ========================================================================= #
+  # === sfancy
+  # ========================================================================= #
+  def sfancy(i = '')
+    ::Colours.sfancy(i)
+  end
+
+  # ========================================================================= #
+  # === hbox                                                       (hbox tag)
+  # ========================================================================= #
+  def hbox(*optional_widgets)
+    ::LibuiParadise.hbox(optional_widgets)
+  end; alias ui_hbox        hbox # === ui_hbox
+       alias horizontal_box hbox # === horizontal_box
+       alias create_hbox    hbox # === create_hbox
+       alias libui_hbox     hbox # === libui_hbox
+
+  # ========================================================================= #
+  # === ui_padded_hbox
+  #
+  # This method will call .is_padded on the hbox after it has been
+  # initialized.
+  # ========================================================================= #
+  def ui_padded_hbox(*optional_widgets)
+    return ::LibuiParadise.ui_padded_hbox(optional_widgets)
+  end; alias padded_hbox        ui_padded_hbox # === padded_hbox
+       alias create_padded_hbox ui_padded_hbox # === create_padded_hbox
+
+  # ========================================================================= #
+  # === vbox
+  #
+  # Note that the alias gtk_box is just a helper-method for ruby-gtk3
+  # compatibility.
+  # ========================================================================= #
+  def vbox(*optional_widgets)
+    return ::LibuiParadise.vbox(optional_widgets)
+  end; alias ui_vbox      vbox # === ui_vbox
+       alias vertical_box vbox # === vertical_box
+       alias create_vbox  vbox # === create_vbox
+       alias libui_vbox   vbox # === libui_vbox
+       alias gtk_box      vbox # === gtk_box
+
+  # ========================================================================= #
+  # === tab
+  #
+  # This could be also called "notebook_tab".
+  # ========================================================================= #
+  def tab
+    ::LibuiParadise.tab
+  end; alias ui_tab       tab # === ui_tab
+       alias ui_tabs      tab # === ui_tabs
+       alias notebook     tab # === notebook
+       alias ui_notebook  tab # === ui_notebook
+       alias notebook_tab tab # === notebook_tab
+
+  # ========================================================================= #
+  # === password_entry
+  #
+  # Usage example:
+  #
+  #   entry = ui_password_entry
+  #
+  # ========================================================================= #
+  def password_entry
+    ::LibuiParadise.password_entry
+  end; alias ui_password_entry password_entry # === ui_password_entry
+
+  # ========================================================================= #
+  # === text_layout
+  #
+  # Wrapper-method towards LibuiParadise.text_layout().
+  # ========================================================================= #
+  def text_layout(
+      i = ''
+    )
+    ::LibuiParadise.text_layout(i)
+  end
+
+  # ========================================================================= #
+  # === free_table_model
+  # ========================================================================= #
+  def free_table_model(model)
+    ::LibUI.free_table_model(model)
+  end
+
+  # ========================================================================= #
+  # === multiline_entry
+  #
+  # Wrapper-method towards LibuiParadise.multiline_entry().
+  # ========================================================================= #
+  def multiline_entry(
+      optional_content = nil
+    )
+    ::LibuiParadise.multiline_entry(optional_content)
+  end; alias ui_multiline_entry multiline_entry # === ui_multiline_entry
+       alias textview           multiline_entry # === textview
+       alias text_view          multiline_entry # === text_view
+       alias ui_text_view       multiline_entry # === ui_text_view
+       alias ui_textview        multiline_entry # === ui_textview
+       alias ui_text_buffer     multiline_entry # === ui_text_buffer
+       alias input_field        multiline_entry # === input_field
+       alias input              multiline_entry # === input
+
+  # ========================================================================= #
+  # === colour_button
+  # ========================================================================= #
+  def colour_button
+    ::LibuiParadise.new_colour_button
+  end; alias color_button     colour_button # === color_button
+       alias ui_colour_button colour_button # === ui_color_button
+
+  # ========================================================================= #
+  # === area
+  #
+  # AreaHandler defines the functionality needed for handling events
+  # from an Area.
+  #
+  # Upstream documentation, at the least for Go, can be found here:
+  #
+  #   https://github.com/andlabs/ui/blob/master/areahandler.go
+  #
+  # ========================================================================= #
+  def area(
+      i = :use_new_area_handler
+    )
+    return ::LibuiParadise.area(i)
+  end; alias area_handler area # === area_handler
+
+  # ========================================================================= #
+  # === editable_combobox
+  # ========================================================================= #
+  def editable_combobox(
+      optional_array = nil, &block
+    )
+    return ::LibuiParadise.editable_combobox(optional_array, &block)
+  end; alias editable_combo_box    editable_combobox # === editable_combo_box
+       alias ui_editable_combo_box editable_combobox # === ui_editable_combo_box
+
+  # ========================================================================= #
+  # === ui_margined_main_window
+  #
+  # This variant is like ui_main_window() but it will automatically
+  # put a margin on the window, via .is_margined().
+  #
+  # Note that the variant name "ui_padded_main_window" is a misnomer,
+  # since it is a margin rather than padding - but I found that it
+  # is easier to not care about this, so for the time being (September
+  # 2021) this is how it is. It may be subject to change in the future,
+  # though.
+  # ========================================================================= #
+  def ui_margined_main_window(
+      the_title   = '',  # Pick a title for the window here.
+      width       = 500, # width  in n pixels.
+      height      = 300, # height in n pixels.
+      has_menubar =   1  # hasMenubar or has not.
+    )
+    _ = ::LibuiParadise.window(the_title, width, height, has_menubar)
+    _.is_margined
+    #_.intelligent_exit # This does not work right now.
+    return _
+  end; alias ui_margined_window        ui_margined_main_window # === ui_margined_window
+       alias ui_padded_main_window     ui_margined_main_window # === ui_padded_main_window
+       alias padded_main_window        ui_margined_main_window # === padded_main_window
+       alias margined_window           ui_margined_main_window # === margined_window
+       alias padded_window             ui_margined_main_window # === padded_window
+       alias ui_padded_window          ui_margined_main_window # === ui_padded_window
+       alias ui_main_window            ui_margined_main_window # === ui_main_window
+       alias ui_window                 ui_margined_main_window # === ui_window
+       alias window_or_vbox            ui_margined_main_window # === window_or_vbox
+       alias margined_main_window      ui_margined_main_window # === margined_main_window
+       alias create_padded_main_window ui_margined_main_window # === create_padded_main_window
+
+  # ========================================================================= #
+  # === vertical_separator
+  # ========================================================================= #
+  def vertical_separator
+    ::LibuiParadise.vertical_separator
+  end; alias ui_vseparator   vertical_separator # === ui_vseparator
+       alias ui_vsep         vertical_separator # === ui_vsep
+       alias vertical_spacer vertical_separator # === vertical_spacer
+       alias vspacer         vertical_separator # === vspacer
+       alias vsep            vertical_separator # === vsep
+
+  # ========================================================================= #
+  # === ui_padded_vbox
+  # ========================================================================= #
+  def ui_padded_vbox(*optional_widgets)
+    return ::LibuiParadise.ui_padded_vbox(optional_widgets)
+  end; alias padded_vbox        ui_padded_vbox # === padded_vbox
+       alias create_padded_vbox ui_padded_vbox # === create_padded_vbox
+
+  # ========================================================================= #
+  # === horizontal_separator
+  # ========================================================================= #
+  def horizontal_separator
+    ::LibuiParadise.new_horizontal_separator
+  end; alias ui_hseparator     horizontal_separator # === ui_hseparator
+       alias ui_hsep           horizontal_separator # === ui_hsep
+       alias hspacer           horizontal_separator # === hspacer
+       alias horizontal_spacer horizontal_separator # === horizontal_spacer
+       alias hsep              horizontal_separator # === hsep
+       alias libui_hsep        horizontal_separator # === libui_hsep
+
+  # ========================================================================= #
+  # === search_entry
+  # ========================================================================= #
+  def search_entry
+    ::LibuiParadise.search_entry
+  end; alias ui_search_entry     search_entry # === ui_search_entry
+       alias create_search_entry search_entry # === create_search_entry
+
+  # ========================================================================= #
+  # === two_elements_hbox
+  #
+  # This method will return a horizontal box (hbox) that is accepting
+  # two arguments (two widgets) that will be embedded onto that hbox.
+  # Then the result is returned.
+  # ========================================================================= #
+  def two_elements_hbox(
+      widget1,
+      widget2,
+      options = {
+        layout_to_use: :maximal # This is the default.
+      }
+    )
+    _ = create_hbox
+    # ======================================================================= #
+    # === Handle :layout_to_use
+    #
+    # This is mostly done to distinguish between maximal() and minimal()
+    # for widgets.
+    # ======================================================================= #
+    if options.is_a?(Hash) and options.has_key?(:layout_to_use)
+      case options[:layout_to_use]
+      # ===================================================================== #
+      # === :maximal
+      # ===================================================================== #
+      when :maximal
+        _.maximal(widget1)
+        _.maximal(widget2)
+      # ===================================================================== #
+      # === :minimal
+      # ===================================================================== #
+      when :minimal
+        _.minimal(widget1)
+        _.minimal(widget2)
+      end
+    else
+      _.minimal(widget1)
+      _.minimal(widget2)
+    end
+    return _
+  end
+
+  # ========================================================================= #
+  # === entry                                                     (entry tag)
+  #
+  # This method is tapping into LibUI.new_entry.
+  #
+  # An alias exists to this method, called hcentered_entry. This currently
+  # does not work for libui, and is thus only added for compatibility
+  # reasons.
+  #
+  # Usage example:
+  #
+  #   entry1 = ui_entry('ATG')
+  #
+  # ========================================================================= #
+  def entry(
+      optional_text = ''
+    )
+    ::LibuiParadise.entry(optional_text)
+  end; alias ui_entry        entry # === ui_entry
+       alias hcentered_entry entry # === hcentered_entry
+       alias create_entry    entry # === create_entry
+
+  # ========================================================================= #
+  # === ui_padded_grid
+  # ========================================================================= #
+  def ui_padded_grid
+    _ = create_grid # This is defined in the method above ^^^ this method.
+    _.is_padded
+    return _
+  end; alias padded_grid  ui_padded_grid # === padded_grid
+       alias default_grid ui_padded_grid # === default_grid
+
+  # ========================================================================= #
+  # === create_table
+  # ========================================================================= #
+  def create_table(model)
+    ::LibuiParadise.table(model)
+  end
+
+  # ========================================================================= #
+  # === text?
+  #
+  # This method will guarantee a String to be returned.
+  #
+  # This is a bit weird, though. We may have to remove this method one
+  # day. I forgot why I added it to entry.rb specifically. After all
+  # other widgets also should respond to .text?.
+  # ========================================================================= #
+  def text?(from_this_pointer)
+    _ = ::LibUI.entry_text(from_this_pointer).to_s # Here we ensure a String will be returned.
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end
+
+  # ========================================================================= #
+  # === ui_text_then_entry
+  #
+  # This method must return an Array containing three elements.
+  #
+  # Note that :padding specifies whether we will use padding or not in
+  # libui. In ruby-gtk3 we can pass the pixels here; I am not sure
+  # whether this is possible via libui as such.
+  # ========================================================================= #
+  def ui_text_then_entry(
+      text = '',
+      hash = {
+        padding: 0
+      }
+    )
+    hbox = padded_hbox   # First element.
+    text = ui_text(text) # Second element.
+    hbox.minimal(text,  hash[:padding])
+    entry = ui_entry     # Third element.
+    hbox.minimal(entry, hash[:padding])
+    return [hbox, text, entry]
+  end; alias text_then_entry ui_text_then_entry # === text_then_entry
+
+  # ========================================================================= #
+  # === window
+  # ========================================================================= #
+  def window(
+      the_title   = '',  # Pick a title for the window here.
+      width       = 500, # width  in n pixels.
+      height      = 300, # height in n pixels.
+      has_menubar =   1  # hasMenubar or has not.
+    )
+    ::LibuiParadise.window(
+      the_title,
+      width,
+      height,
+      has_menubar
+    )
+  end; alias create_main_window   window # === main_window
+       alias create_window        window # === create_window
+
+  # ========================================================================= #
+  # === window?
+  # ========================================================================= #
+  def window?
+    ::LibuiParadise.main_window?
+  end; alias main_window? window? # === main_window?
+       alias main_window  window? # === main_window
+
+  # ========================================================================= #
+  # === return_the_resolution_using_xrandr
+  #
+  # This method will only work on e. g. Linux.
+  #
+  # It will then return a String such as "1920x1080".
+  # ========================================================================= #
+  def return_the_resolution_using_xrandr
+    _ = '800x600' # This is a generic failsafe value.
+    begin
+      xrandr_result = `xrandr`
+      _ = xrandr_result.split("\n").select {|line|
+        line.include? '*'
+      }.first.strip.squeeze(' ').split(' ').first.to_s
+    rescue Errno::ENOENT # Rescue for Windows systems.
+    end
+    return _ # This will yield e. g. "1920x1080"
+  end
+
+  # ========================================================================= #
+  # === set_title
+  # ========================================================================= #
+  def set_title(i)
+    @internal_hash[:title] = i
+  end
+
+  # ========================================================================= #
+  # === title?
+  # ========================================================================= #
+  def title?
+    @internal_hash[:title]
+  end
+
+  # ========================================================================= #
+  # === height?
+  # ========================================================================= #
+  def height?
+    @internal_hash[:height]
+  end
+
+  # ========================================================================= #
+  # === is_on_roebe?
+  #
+  # This is only useful on my home system.
+  # ========================================================================= #
+  def is_on_roebe?
+    ENV['IS_ROEBE'].to_s == '1'
+  end
+
+  # ========================================================================= #
+  # === radio_buttons
+  # ========================================================================= #
+  def radio_buttons(optional_array = [])
+    return ::LibuiParadise.radio_buttons(optional_array)
+  end; alias ui_radio_buttons radio_buttons # === ui_radio_buttons
+
+  # ========================================================================= #
+  # === bold_button
+  #
+  # This currently does not work. We have to wait until upstream libui
+  # supports bold font text.
+  # ========================================================================= #
+  def bold_button(i)
+    button(i)
+  end
+
+  # ========================================================================= #
+  # === quit_button                                                (quit tag)
+  #
+  # This method can be used to, by default, implement a quit button
+  # that, upon a click-event, will cause the application to exit
+  # and close/quit.
+  # ========================================================================= #
+  def quit_button(
+      optional_arguments = {}
+    )
+    use_this_text = 'Quit'
+    if optional_arguments and optional_arguments.is_a?(Hash)
+      # ===================================================================== #
+      # === :text
+      # ===================================================================== #
+      if optional_arguments.has_key? :text
+        use_this_text = optional_arguments.delete(:text)
+      end
+    end
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :with_emoji
+      # ===================================================================== #
+      when :with_emoji,
+           :with_icon
+        use_this_text = use_this_text.to_s.dup
+        use_this_text << ' 🛑'
+      end
+    end
+    quit_button = button(use_this_text)
+    quit_button.on_clicked {
+      ::LibUI.quit
+      0
+    }
+    return quit_button
+  end; alias ui_quit_button quit_button # === ui_quit_button
+
+  # ========================================================================= #
+  # === selected?
+  #
+  # Unsure whether this works. It appears to work, but I am not even
+  # certain as to why.
+  # ========================================================================= #
+  def selected?(pointer)
+    ::LibUI.combobox_selected(pointer).to_s
+  end
+
+  # ========================================================================= #
+  # === combobox
+  #
+  # The first argument can be an Array.
+  # ========================================================================= #
+  def combobox(
+      optional_array = nil,
+      &block
+    )
+    return ::LibuiParadise.combobox(optional_array, &block)
+  end; alias ui_combo_box     combobox # === ui_combo_box
+       alias ui_combobox      combobox # === ui_combobox
+       alias libui_combo_box  combobox # === libui_combo_box
+       alias combo_box_entry  combobox # === combo_box_entry
+       alias combo_box        combobox # === combo_box
+       alias create_combo_box combobox # === create_combo_box
+
+  # ========================================================================= #
+  # === wrapper_new_progress_bar
+  # ========================================================================= #
+  def wrapper_new_progress_bar
+    return ::LibuiParadise.wrapper_new_progress_bar
+  end; alias progress_bar wrapper_new_progress_bar # === progress_bar
+
+  # ========================================================================= #
+  # === font
+  #
+  # Wrapper-method towards LibuiParadise.font().
+  # ========================================================================= #
+  def font(&block)
+    ::LibuiParadise.font(&block)
+  end; alias ui_font         font # === ui_font
+       alias font_descriptor font # === font_descriptor
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(
+      title = ''
+    )
+    return ::LibuiParadise.menu(title)
+  end; alias ui_menu menu # === ui_menu
+
+  # ========================================================================= #
+  # === non_wrapping_multiline_entry
+  #
+  # Delegate towards LibuiParadise.non_wrapping_multiline_entry() here.
+  # ========================================================================= #
+  def non_wrapping_multiline_entry
+    return ::LibuiParadise.non_wrapping_multiline_entry
+  end
+
+  # ========================================================================= #
+  # === table
+  # ========================================================================= #
+  def table(i)
+    ::LibuiParadise.table(i)
+  end; alias ui_table table # === ui_table
+
+  # ========================================================================= #
+  # === scrolling_area
+  #
+  # It seems as if scrolling is not yet easily available in libui.
+  #
+  # The upstream API is like this:
+  #
+  #   uiArea *area = uiNewScrollingArea(&handler, 400, 400);
+  #
+  # ========================================================================= #
+  def scrolling_area(
+      optional_widget = nil
+    )
+    ::LibuiParadise.scrolling_area(optional_widget)
+  end; alias ui_scrolling_area  scrolling_area # === ui_scrolling_area
+       alias ui_scrolled_window scrolling_area # === ui_scrolling_window
+
+  # ========================================================================= #
+  # === spinbox
+  #
+  # This method will return a spin-button, also called a spin-box.
+  # ========================================================================= #
+  def spinbox(
+      start_point =   0,
+      end_point   = 100
+    )
+    ::LibuiParadise.spinbox(start_point, end_point)
+  end; alias ui_spinbox           spinbox # === ui_spinbox
+       alias ui_spinbutton        spinbox # === ui_spinbutton
+       alias create_spinbox       spinbox # === create_spinbox
+       alias up_and_down_counter  spinbox # === up_and_down_counter
+       alias spinbutton           spinbox # === spinbutton
+       alias centered_spin_button spinbox # === centered_spin_button
+
+  # ========================================================================= #
+  # === try_to_parse_this_config_file
+  #
+  # This method can be used to parse a .config file for data it stores.
+  #
+  # The .config file must have "width:", "height:" and "title:" settings.
+  # ========================================================================= #
+  def try_to_parse_this_config_file(i)
+    if File.exist? i
+      dataset = File.readlines(i)
+      # ===================================================================== #
+      # Next check for width, height and title:
+      # ===================================================================== #
+      width  = dataset.select {|line| line.include? 'width:' }.first.
+               split(':').last.strip.to_i
+      height = dataset.select {|line| line.include? 'height:' }.first.
+               split(':').last.strip.to_i
+      title  = dataset.select {|line| line.include? 'title:' }.first.
+               split(':').last.strip
+      window = LibuiParadise.window(title, width, height)
+      return window
+    else
+      e 'No file exists at `'+i+'`.'
+    end
+  end; alias parse_this_config_file try_to_parse_this_config_file # === parse_this_config_file
+
+  # ========================================================================= #
+  # === set_main_window
+  # ========================================================================= #
+  def set_main_window(i)
+    ::LibuiParadise.set_main_window(i)
+    return ::LibuiParadise.main_window?
+  end
+
+  # ========================================================================= #
+  # === bold_text_left_aligned
+  # ========================================================================= #
+  def bold_text_left_aligned(i = '')
+    return label(i)
+  end; alias left_aligned_bold_label bold_text_left_aligned # === left_aligned_bold_label
+
+  # ========================================================================= #
+  # === is_on_windows?
+  # ========================================================================= #
+  def is_on_windows?
+    Gem.win_platform?
+  end
+
+  # ========================================================================= #
+  # === checkbox
+  #
+  # Delegate towards LibuiParadise.checkbox().
+  # ========================================================================= #
+  def checkbox(
+      i = ''
+    )
+    ::LibuiParadise.checkbox(i)
+  end; alias ui_checkbox      checkbox # === ui_checkbox
+       alias ui_check_button  checkbox # === ui_check_button
+       alias create_checkbox  checkbox # === create_checkbox
+       alias create_check_box checkbox # === create_check_box
+
+  # ========================================================================= #
+  # === checked_checkbox
+  # ========================================================================= #
+  def checked_checkbox(i = '')
+    _ = checkbox(i)
+    _.is_active
+    return _
+  end
+
+  # ========================================================================= #
+  # === ui_open_file
+  #
+  # This method can be used as a wrapper towards an "open local file"
+  # functionality.
+  # ========================================================================= #
+  def ui_open_file(
+      main_window = ::LibuiParadise.main_window?
+    )
+    return ::LibuiParadise.open_file(main_window)
+  end
+
+  # ========================================================================= #
+  # === fancy_text
+  #
+  # This text variant can be styled.
+  # ========================================================================= #
+  def fancy_text(i = '')
+    _ = LibUI.new_attributed_string(i.to_s)
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; alias attributed_string fancy_text # === attributed_string
+
+  # ========================================================================= #
+  # === bold_label
+  #
+  # This currently does NOT make the text bold - the method exists solely
+  # as a placeholder, until upstream libui supports bold text as such.
+  #
+  # Actually libui already supports this; I just don't know how to use
+  # it.
+  # ========================================================================= #
+  def bold_label(i = '')
+    return label(i)
+  end; alias bold_text bold_label # === bold_text
+
+  # ========================================================================= #
+  # === parse_this_file_into_a_table
+  #
+  # Note that Gtk::Table has been deprecated. Use GtkGrid instead. It
+  # provides the same capabilities as GtkTable for arranging widgets
+  # in a rectangular grid, but does support height-for-width geometry
+  # management.
+  #
+  # Usage example:
+  #
+  #   parse_into_table '/Depot/j/animals.yml'
+  #
+  # ========================================================================= #
+  def parse_this_file_into_a_table(this_file)
+    if this_file and File.exist?(this_file)
+      table = create_grid
+      table.uniform_spacing(8)
+      table.pad8px
+      if this_file.end_with?('.yml')
+        dataset = YAML.load_file(this_file)
+      else
+        dataset = File.readlines(this_file)
+      end
+      if dataset.is_a? Hash
+        dataset = dataset.to_a.flatten
+      end
+      dataset.flatten! if dataset.respond_to?(:flatten!)
+      dataset.each_with_index {|entry, index|
+        entry = entry.to_s
+        case index % 2
+        when 0
+          table.left(text(entry))
+        when 1
+          table.right(text(entry))
+        end
+      }
+      return table
+    end
+  end; alias parse_into_table parse_this_file_into_a_table # === parse_into_table
+
+  # ========================================================================= #
+  # === label
+  #
+  # The last two aliases, left_aligned_label, should be different, but
+  # right now I don't know how to do this in libui.
+  # ========================================================================= #
+  def label(
+      i = ''
+    )
+    ::LibuiParadise.label(i)
+  end; alias text               label # === text
+       alias ui_text            label # === ui_text
+       alias ui_label           label # === ui_label
+       alias left_aligned_label label # === left_aligned_label
+       alias left_aligned_text  label # === left_aligned_text
+
+  # ========================================================================= #
+  # === left_arrow?
+  #
+  # This is simply a unicode left arrow, a text (label) widget.
+  # ========================================================================= #
+  def left_arrow?
+    text('→')
+  end
+
+  # ========================================================================= #
+  # === main_then_quit
+  # ========================================================================= #
+  def main_then_quit
+    ::LibUI.main
+    do_quit
+  end
+
+  # ========================================================================= #
+  # === do_quit
+  # ========================================================================= #
+  def do_quit
+    ::LibUI.quit
+  end
+
+  # ========================================================================= #
+  # === copy
+  # ========================================================================= #
+  def copy(from, to)
+    require 'fileutils'
+    FileUtils.cp(from, to)
+  end
+
+  # ========================================================================= #
+  # === exit_from
+  #
+  # This method essentially combines UI.control_destroy() and UI.quit(
+  # into one method.
+  # ========================================================================= #
+  def exit_from(
+      main_window = main_window?
+    )
+    LibUI.control_destroy(main_window)
+    LibUI.quit
+    0
+  end
+
+  # ========================================================================= #
+  # === use_gtk?
+  # ========================================================================= #
+  def use_gtk?
+    false
+  end; alias uses_gtk4? use_gtk? # === uses_gtk4?
+
+  # ========================================================================= #
+  # === use_libui?
+  # ========================================================================= #
+  def use_libui?
+    true
+  end
+
+  # ========================================================================= #
+  # === return_pwd
+  # ========================================================================= #
+  def return_pwd
+    "#{Dir.pwd}/".squeeze('/')
+  end
+
+  # ========================================================================= #
+  # === try_to_use_this_font
+  #
+  # This is currently not in use - once libui supports setting
+  # a font then this can be enabled.
+  #
+  # Actually this should in theory already work as-is - I just don't
+  # understand the toplevel API to be used here.
+  # ========================================================================= #
+  def try_to_use_this_font(i = nil); end
+    alias use_this_font=    try_to_use_this_font # === use_this_font=
+    alias set_use_this_font try_to_use_this_font # === set_use_this_font
+
+  # ========================================================================= #
+  # === use_gtk3?
+  # ========================================================================= #
+  def use_gtk3?
+    Object.const_defined?(:Gtk)
+  end
+
+  # ========================================================================= #
+  # === gtk3?
+  # ========================================================================= #
+  def gtk3?
+    false
+  end; alias is_on_gtk? gtk3? # === is_on_gtk?
+       alias uses_gtk3? gtk3? # === uses_gtk3?
+
+  # ========================================================================= #
+  # === append_this_array_to_that_combobox
+  # ========================================================================= #
+  def append_this_array_to_that_combobox(
+      this_array,
+      that_combobox
+    )
+    this_array.each {|this_entry|
+      ::LibUI.combobox_append(that_combobox, this_entry)
+    }
+  end
+
+  # ========================================================================= #
+  # === new_brush
+  # ========================================================================= #
+  def new_brush
+    ::LibUI::FFI::DrawBrush.malloc
+  end
+
+  # ========================================================================= #
+  # === ui_draw_text_layout_params
+  # ========================================================================= #
+  def ui_draw_text_layout_params
+    ::LibUI::FFI::DrawTextLayoutParams.malloc
+  end
+
+  # ========================================================================= #
+  # === slider                                                   (slider tag)
+  # ========================================================================= #
+  def slider(
+      start_value =   0,
+      end_value   = 100
+    )
+    return ::LibuiParadise.slider(start_value, end_value)
+  end; alias ui_slider     slider # === ui_slider
+       alias create_slider slider # === create_slider
+
+  # ========================================================================= #
+  # === ui_table_params_malloc
+  #
+  # This will basically wrap over LibUI::FFI::TableParams.malloc().
+  # ========================================================================= #
+  def ui_table_params_malloc(
+      optional_model = nil
+    )
+    _ = ::LibUI::FFI::TableParams.malloc
+    if optional_model
+      _.to_ptr.free = Fiddle::RUBY_FREE
+      _.Model = optional_model
+      _.RowBackgroundColorModelColumn = -1
+    end
+    return _
+  end
+
+  # ========================================================================= #
+  # === ui_font_descriptor
+  #
+  # This method will return a new font-descriptor pointer.
+  #
+  # Usage example:
+  #
+  #   ui_font_descriptor('Hack')
+  #
+  # ========================================================================= #
+  def ui_font_descriptor(
+      use_this_font_family      = 'Hack',
+      use_this_size             = 25,
+      use_this_weight           = 500,
+      is_in_italic_font_variant = :no,
+      stretch_factor            = 4
+    )
+    case is_in_italic_font_variant
+    when :yes
+      is_in_italic_font_variant = 1 # true
+    when :no
+      is_in_italic_font_variant = 0 # false
+    end
+    font_descriptor = UI::FFI::FontDescriptor.malloc
+    font_descriptor.to_ptr.free = Fiddle::RUBY_FREE
+    font_descriptor.Family = use_this_font_family
+    font_descriptor.Size = use_this_size
+    font_descriptor.Weight = use_this_weight
+    font_descriptor.Italic = is_in_italic_font_variant
+    font_descriptor.Stretch = stretch_factor
+    return font_descriptor
+  end; alias font_descriptor ui_font_descriptor # === font_descriptor
+
+  # ========================================================================= #
+  # === current_widget_pointer_type?
+  # ========================================================================= #
+  def current_widget_pointer_type?
+    LibuiParadise.hash_fiddle_pointer_widgets?.values.last.last
+  end
+
+  # ========================================================================= #
+  # === esystem
+  #
+  # This method can be used to run system(), with output. Thread.new is
+  # used because that seems to work better in a GUI setup.
+  # ========================================================================= #
+  def esystem(i)
+    e i
+    Thread.new { system i }
+  end
+
+  # ========================================================================= #
+  # === create_directory
+  # ========================================================================= #
+  def create_directory(i)
+    FileUtils.mkdir_p(i)
+  end; alias mkdir create_directory # === mkdir
+
+  # ========================================================================= #
+  # === abort_on_exception
+  # ========================================================================= #
+  def abort_on_exception
+    Thread.abort_on_exception
+  end
+
+  # ========================================================================= #
+  # === chdir                                             (cd tag, chdir tag)
+  # ========================================================================= #
+  def chdir(i)
+    if i and File.directory?(i)
+      Dir.chdir(i)
+    end
+  end; alias cd chdir # === cd
+
+  # ========================================================================= #
+  # === create_skeleton_then_connect_skeleton
+  # ========================================================================= #
+  def create_skeleton_then_connect_skeleton
+    create_skeleton
+    connect_skeleton
+  end
+
+  # ========================================================================= #
+  # === connect_skeleton
+  #
+  # This is a stub method, because we want to allow the user to modify it.
+  # ========================================================================= #
+  def connect_skeleton
+  end
+
+  # ========================================================================= #
+  # === title_width_height_font
+  #
+  # The font-argument is presently not handled. Perhaps one day in the
+  # future.
+  # ========================================================================= #
+  def title_width_height_font(
+      title  = '',
+      width  = WIDTH,
+      height =  800,
+      font   = :currently_not_handled
+    )
+    title_width_height(title, width, height)
+  end
+
+  # ========================================================================= #
+  # === title_width_height
+  # ========================================================================= #
+  def title_width_height(
+      title,
+      width  = WIDTH,
+      height =  800
+    )
+    set_title(title)
+    set_width(width)
+    set_height(height)
+  end; alias set_title_width_height title_width_height # === title_width_height
+
+  # ========================================================================= #
+  # === font_button
+  #
+  # Create a new font button via this method.
+  # ========================================================================= #
+  def font_button
+    return ::LibuiParadise.font_button
+  end; alias ui_font_button font_button # === ui_font_button
+
+  # ========================================================================= #
+  # === image                                                     (image tag)
+  #
+  # This is currently limited to .png files only, due to ChunkyPNG.
+  #
+  # At some later point in the future this limitation may be lifted. For
+  # now it has to remain in place.
+  # ========================================================================= #
+  def image(
+      this_file,
+      width  = :try_to_infer_automatically,
+      height = :infer_automatically
+    )
+    Libuiparadise.image(
+      this_file,
+      width,
+      height
+    )
+  end; alias ui_image image # === ui_image
+
+  # ========================================================================= #
+  # === run
+  # ========================================================================= #
+  def run
+    create_skeleton_then_connect_skeleton
+  end
+
+  # ========================================================================= #
+  # === create_the_skeleton
+  # ========================================================================= #
+  def create_the_skeleton
+  end; alias create_skeleton create_the_skeleton # === create_skeleton
+
+  # ========================================================================= #
+  # === run_main
+  # ========================================================================= #
+  def run_main
+  end
+
+  # ========================================================================= #
+  # === set_commandline_arguments
+  # ========================================================================= #
+  def set_commandline_arguments(i = ARGV)
+    @commandline_arguments = [i].flatten.compact
+  end
+
+  # ========================================================================= #
+  # === commandline_arguments?
+  # ========================================================================= #
+  def commandline_arguments?
+    @commandline_arguments
+  end
+
+  # ========================================================================= #
+  # === set_height
+  # ========================================================================= #
+  def set_height(
+      i = 800
+    )
+    case i
+    # ======================================================================= #
+    # === :max_width
+    # ======================================================================= #
+    when :max_height
+      i = assumed_max_height?
+    end
+    if i.is_a?(String) and i.include?('%')
+      # ===================================================================== #
+      # In this case we have to modify this a bit.
+      # ===================================================================== #
+      max_height = assumed_max_height?
+      i = (max_height.to_f * i.to_i) / 100.0
+    end
+    i = i.to_i
+    @internal_hash[:height] = i
+  end
+
+  # ========================================================================= #
+  # === copy_file
+  # ========================================================================= #
+  def copy_file(from, to)
+    FileUtils.cp(from, to)
+  end; alias cp_file copy_file # === cp_file
+
+  # ========================================================================= #
+  # === assumed_height?
+  # ========================================================================= #
+  def assumed_height?
+    return_the_resolution_using_xrandr.split('x').last.to_i
+  end; alias assumed_max_height? assumed_height? # === assumed_max_height?
+
+  # ========================================================================= #
+  # === without_trailing_comment
+  # ========================================================================= #
+  def without_trailing_comment(i)
+    i = i.dup
+    if i and i.end_with?('#')
+      i = i[0 .. -2]
+    end
+    return i
+  end
+
+  # ========================================================================= #
+  # === assumed_width?
+  # ========================================================================= #
+  def assumed_width?
+    return_the_resolution_using_xrandr.split('x').first.to_i
+  end; alias assumed_max_width? assumed_width? # === assumed_max_width?
+
+  # ========================================================================= #
+  # === set_width
+  # ========================================================================= #
+  def set_width(
+      i = 1024
+    )
+    case i
+    # ======================================================================= #
+    # === :max_width
+    # ======================================================================= #
+    when :max_width
+      i = assumed_max_width?
+    end
+    if i.is_a?(String) and i.include?('%')
+      # ===================================================================== #
+      # In this case we have to modify this a bit.
+      # ===================================================================== #
+      max_width = assumed_max_width?
+      i = (max_width.to_f * i.to_i) / 100.0
+    end
+    i = i.to_i
+    @internal_hash[:width] = i
+  end
+
+  # ========================================================================= #
+  # === width?
+  # ========================================================================= #
+  def width?
+    @internal_hash[:width]
+  end
+
+  # ========================================================================= #
+  # === delete_file
+  #
+  # This method can be used if you want to quickly delete a (local) file.
+  # ========================================================================= #
+  def delete_file(i)
+    if i and File.file?(i)
+      File.delete(i)
+    else
+      e "Not a file: #{i}"
+    end
+  end
+
+  # ========================================================================= #
+  # === colour_to_rgb
+  # ========================================================================= #
+  def colour_to_rgb(
+      colour = :steelblue
+    )
+    array = Colours.colour_to_rgb(colour)
+    return array
+  end
+
+  # ========================================================================= #
+  # === last_pointer?
+  #
+  # This used to return the "current" widget pointer, but past September
+  # 2021 this is rarely in use anymore. Use current_widget_pointer? 
+  # instead, based on the main Hash that keeps all widgets registered.
+  # ========================================================================= #
+  def last_pointer?
+    LibuiParadise.current_widget_pointer?
+  end; alias current_pointer?        last_pointer? # === current_pointer?
+       alias current_widget_pointer? last_pointer? # === current_widget_pointer?
+
+  # ========================================================================= #
+  # === ui_sync_connect
+  #
+  # This method can connect two widgets: the first one should be a
+  # combo-box, and the second one a ui-entry.
+  # ========================================================================= #
+  def ui_sync_connect(
+      widget1,
+      widget2,
+      optional_array = nil
+    )
+    combobox_selected_callback = proc { |pointer|
+      selected_value = selected?(pointer)
+      if optional_array and optional_array.is_a?(Array)
+        selected_value = optional_array[selected_value.to_i]
+      end
+      widget2.set_text(
+        selected_value
+      )
+    }
+    ::LibUI.combobox_on_selected(
+      widget1, combobox_selected_callback, nil
+    )
+  end; alias sync_connect ui_sync_connect # === sync_connect
+
+  # ========================================================================= #
+  # === main_hash?
+  #
+  # Access the main hash defined above.
+  # ========================================================================= #
+  def main_hash?
+    ::LibuiParadise.hash_fiddle_pointer_widgets?
+  end; alias toplevel_hash? main_hash? # === toplevel_hash?
+
+  # ======================================================================= #
+  # === return_default_window
+  # ======================================================================= #
+  def return_default_window(
+      title  = title?,
+      width  = width?,
+      height = height?
+    )
+    return padded_main_window(title, width, height, 0)
+  end
+
+  # ========================================================================= #
+  # === set_window
+  #
+  # Simply assign to @window here.
+  # ========================================================================= #
+  def set_window(i = return_default_window)
+    ::LibuiParadise.set_window(i)
+  end
+
+  # ========================================================================= #
+  # === close_properly
+  # ========================================================================= #
+  def close_properly(
+      main_window = LibuiParadise.main_window?
+    )
+    LibUI.window_on_closing(main_window) {
+      LibUI.exit_from(main_window)
+    }
+  end; alias simple_exit close_properly # === simple_exit
+
+  # ========================================================================= #
+  # === return_button_for_opening_a_local_file
+  #
+  # This method will return a button, which can be used for opening a
+  # local file.
+  #
+  # It is recommended to passs a libui-widget into this method, so that
+  # the "open-file" functionality can have a callback. Usually that
+  # callback should be a libui-entry, so that we can fill it with
+  # the file path that we chose.
+  # ========================================================================= #
+  def return_button_for_opening_a_local_file(
+      connect_this_button_with_that_widget = nil
+    )
+    button_open_file = create_button('Open file')
+    button_open_file.on_clicked {
+      begin
+        # filename = ui_open_file(window).to_s
+        filename = LibUI.open_file(main_window).to_s
+        # e "The filename was: #{filename}" # This line is for debugging.
+        if connect_this_button_with_that_widget # This widget is usually an entry.
+          filename = File.absolute_path(filename) # We need the full path here.
+          connect_this_button_with_that_widget.set_text(filename) if connect_this_button_with_that_widget.respond_to?(:set_text)
+        end
+      rescue ArgumentError => error # Rescue from "NULL pointer given"
+        pp error
+      end
+    }
+    return button_open_file # Always return that button here.
+  end; alias return_the_default_open_file_button return_button_for_opening_a_local_file # === return_the_default_open_file_button
+
+  ::LibuiParadise.initializer # Make LibUI known here.
+
+  # ========================================================================= #
+  # === open_file
+  #
+  # This here creates a problem, because ::Libui.open_file is already
+  # defined. We'd have to use an alias to make this work.
+  # ========================================================================= #
+  # def open_file(
+  #     main_window = LibuiParadise::Extensions.main_window?
+  #   )
+  #   return ::LibuiParadise::Extensions.open_file(main_window)
+  # end; alias ui_open_file open_file # === ui_open_file
+
+  # ========================================================================= #
+  # === error_msg
+  # ========================================================================= #
+  def error_msg(text)
+    message_box_error(:default, text)
+  end
+
+  # ========================================================================= #
+  # === message_box_error
+  #
+  # This is specifically for displaying an error-message to the user.
+  # ========================================================================= #
+  def message_box_error(
+      main_window  = main_window?,
+      title_to_use = '',
+      whatever     = ''
+    )
+    return ::LibuiParadise.message_box_error(
+      main_window,
+      title_to_use,
+      whatever
+    )
+  end; alias ui_msg_box_error          message_box_error # === ui_msg_box_error
+       alias ui_error_message          message_box_error # === ui_error_message
+       alias ui_error_msg              message_box_error # === ui_error_msg
+       alias error_message_to_the_user message_box_error # === error_message_to_the_user
+
+  # ========================================================================= #
+  # === ui_msg_box
+  #
+  # This method is a convenience-wrapper over UI.msg_box().
+  # ========================================================================= #
+  def ui_msg_box(
+      main_window        = :default_window,
+      title_to_use       = '',
+      description_to_use = nil # This could be a widget, but for now it is not in use.
+    )
+    ::LibuiParadise.msg_box(
+      main_window,
+      title_to_use,
+      description_to_use
+    )
+  end; alias message_to_the_user    ui_msg_box # === message_to_the_user
+       alias message_box            ui_msg_box # === message_box
+       alias popup_over_this_widget ui_msg_box # === popup_over_this_widget
+       alias popup_message          ui_msg_box # === popup_message
+       alias create_message_box     ui_msg_box # === create_message_box
+       # alias msg_box                ui_msg_box # === msg_box
+       # ^^^ this would lead to an error.
+
+  # ========================================================================= #
+  # === popover_message
+  # ========================================================================= #
+  def popover_message(
+      title_to_use,
+      description_to_use
+    )
+    create_message_box(
+      :default_window,
+      title_to_use,
+      description_to_use
+    )
+  end
+
+end
+
+# =========================================================================== #
+# === LibuiParadise.extended
+#
+# This method taps into the extended-hook - see the code in the method
+# shown above this method.
+#
+# The purpose of this hook is to automatically call .init on LibUI. This
+# saves us one line of code.
+#
+# In regular LibUI code this is equal to:
+#
+#   LibUI.init
+#
+# =========================================================================== #
+def self.extended(i)
+  if i.respond_to? :init
+    i.init
+  else
+    ::LibUI.init
+  end
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  include LibuiParadise::BaseModule
+end # base_module