libui_paradise 0.3.9 → 0.4.13

data/lib/libui_paradise/toplevel_methods/toplevel_methods.rb

@@ -0,0 +1,792 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'libui_paradise/toplevel_methods/toplevel_methods.rb'
+# =========================================================================== #
+module LibuiParadise
+
+  # ========================================================================= #
+  # === @main_window
+  #
+  # This variable can be used to keep track of the main window in use.
+  # ========================================================================= #
+  @main_window = nil
+
+  # ========================================================================= #
+  # === LibuiParadise.main_window?
+  # ========================================================================= #
+  def self.main_window?
+    @main_window
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.set_main_window
+  # ========================================================================= #
+  def self.set_main_window(i)
+    @main_window = i
+  end; self.instance_eval { alias set_window set_main_window } # === LibuiParadise.set_window
+
+  # ========================================================================= #
+  # === LibuiParadise.window                                     (window tag)
+  #
+  # This method will create a new main-window.
+  #
+  # It will also call UI.simple_exit(). This is done mostly so that we
+  # can omit that line whenever we use e. g. ui_main_window().
+  # ========================================================================= #
+  def self.window(
+      the_title   = '',     # Pick a title for the window here.
+      width       = WIDTH,  # width  in n pixels.
+      height      = HEIGHT, # height in n pixels.
+      has_menubar =   1,    # hasMenubar or has not.
+      &block
+    )
+    case width
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      width = WIDTH
+    end
+    case the_title
+    # ======================================================================= #
+    # === :filename
+    # ======================================================================= #
+    when :filename,
+         :file_name
+      # ===================================================================== #
+      # __FILE__ contains the desired name. We only need the raw name, though.
+      # Well, in 2022 it was realized that the real filename is stored in
+      # $PROGRAM_NAME, so here we go.
+      # ===================================================================== #
+      the_title = File.basename($PROGRAM_NAME)
+    end
+    raw_has_menubar = 0
+    if has_menubar.is_a? Numeric
+      raw_has_menubar = has_menubar
+    end
+    # ======================================================================= #
+    # Instantiate a new main-window next:
+    # ======================================================================= #
+    main_window = ::LibUI.new_window(
+      the_title,
+      width,
+      height,
+      raw_has_menubar
+    )
+    set_main_window(main_window) # Keep a reference stored here.
+    # ======================================================================= #
+    # Since as of 30.08.2021 we will also register the main-window.
+    #
+    # In the long run we may obsolete and deprecate @main_window, since
+    # it is no longer needed - but for now we will retain that variable.
+    # ======================================================================= #
+    add_to_the_registered_widgets(main_window, __method__)
+    if has_menubar and has_menubar.is_a?(Hash)
+      if has_menubar.has_key? :margin
+        if has_menubar[:margin] == true
+          main_window.has_margin
+        end
+      end
+    end
+    ::LibUI.simple_exit(main_window)
+    if block_given?
+      yield
+    end
+    return main_window # Always return it here.
+  end; self.instance_eval { alias main_window           window } # === LibuiParadise.main_window
+       self.instance_eval { alias ui_main_window        window } # === LibuiParadise.ui_main_window
+       self.instance_eval { alias margined_window       window } # === LibuiParadise.margined_window
+       self.instance_eval { alias ui_window             window } # === LibuiParadise.ui_window
+       self.instance_eval { alias window_or_vbox        window } # === LibuiParadise.window_or_vbox
+       self.instance_eval { alias ui_padded_main_window window } # === LibuiParadise.margined_window
+       self.instance_eval { alias padded_window         window } # === LibuiParadise.padded_window
+       self.instance_eval { alias padded_main_window    window } # === LibuiParadise.padded_main_window
+  
+  # ========================================================================= #
+  # === LibuiParadise.string_length
+  #
+  # This method is specifically for attributed-Strings.
+  # ========================================================================= #
+  def self.string_length(i = self)
+    return ::LibUI.attributed_string_len(i)
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.init
+  # ========================================================================= #
+  def self.init
+    ::LibUI.init
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.string
+  #
+  # This is a wrapper over LibUI.new_attributed_string().
+  # ========================================================================= #
+  def self.string(i = '')
+    return ::LibUI.new_attributed_string(i)
+  end; self.instance_eval { alias fancy_text string } # === LibuiParadise.fancy_text
+
+  # ========================================================================= #
+  # === LibuiParadise.label                             (text tag, label tag)
+  #
+  # Add text to the widget at hand. This is actually called a "label".
+  # ========================================================================= #
+  def self.label(
+      i = ''
+    )
+    if i.include? '</'
+      # ===================================================================== #
+      # For now we must remove "HTML tags" from the given input. Perhaps
+      # at some later point in time we can retain them.
+      # ===================================================================== #
+      i = i.dup if i.frozen?
+      i.gsub!(%r{<[^>]+>}, '')
+    end
+    _ = ::LibUI.new_label(i.to_s)
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias text     label } # === LibuiParadise.text
+       self.instance_eval { alias ui_text  label } # === LibuiParadise.ui_text
+       self.instance_eval { alias ui_label label } # === LibuiParadise.ui_label
+
+  # ========================================================================= #
+  # === LibuiParadise.radio_buttons
+  #
+  # This method will create some radio buttons.
+  #
+  # You can pass an Array into this method, which should be an Array of
+  # Strings. This is optional. If such an Array is given, though, then
+  # these entries will become radio-buttons, with the associated label
+  # (the text they display) becoming the label right next to the radio
+  # button element (that round circle that the user can select via
+  # the mouse cursor).
+  # ========================================================================= #
+  def self.radio_buttons(
+      optional_array = []
+    )
+    _ = ::LibUI.new_radio_buttons
+    if optional_array and optional_array.is_a?(Array) and !optional_array.empty?
+      optional_array.each {|this_element|
+        ::LibUI.radio_buttons_append(_, this_element)
+      }
+    end
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias ui_radio_buttons radio_buttons } # === LibuiParadise.ui_radio_buttons
+
+  # ========================================================================= #
+  # === LibuiParadise.text_layout
+  # ========================================================================= #
+  def self.text_layout(
+      i = ''
+    )
+    _ = ::LibUI.draw_new_text_layout(i.to_s)
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.menu                                         (menu tag)
+  # ========================================================================= #
+  def self.menu(
+      title = ''
+    )
+    _ = ::LibUI.new_menu(title)
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias ui_menu menu } # === ui_menu
+
+  # ========================================================================= #
+  # === LibuiParadise.table
+  #
+  # The argument to this method should be of type table_params.
+  #
+  # Example for this:
+  #
+  #   table_params = LibUI::FFI::TableParams.malloc
+  #   table_params.Model = model
+  #   table_params.RowBackgroundColorModelColumn = -1
+  #
+  # ========================================================================= #
+  def self.table(i)
+    _ = ::LibUI.new_table(i)
+    register_this_fiddle_pointer_widget(_, __method__)
+    return _
+  end; self.instance_eval { alias ui_table table } # === LibuiParadise.ui_table
+
+  # ========================================================================= #
+  # === LibuiParadise.vertical_separator
+  #
+  # This method will add a new vertical separator.
+  # ========================================================================= #
+  def self.vertical_separator
+    ::LibUI.new_vertical_separator
+  end; self.instance_eval { alias ui_vseparator     vertical_separator } # === LibuiParadise.ui_verticalseparator
+       self.instance_eval { alias ui_vsep           vertical_separator } # === LibuiParadise.ui_vsep
+       self.instance_eval { alias vspacer           vertical_separator } # === LibuiParadise.vspacer
+       self.instance_eval { alias vertical_spacer   vertical_separator } # === LibuiParadise.vertical_spacer
+       self.instance_eval { alias vsep              vertical_separator } # === LibuiParadise.vsep
+
+  # ========================================================================= #
+  # === Libuiparadise.image
+  #
+  # 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 self.image(
+      this_file,
+      width  = :try_to_infer_automatically,
+      height = :infer_automatically
+    )
+    if (width  == :infer_automatically) or
+       (height == :infer_automatically)
+      unless Object.const_defined? :ChunkyPNG
+        begin
+          require 'chunky_png'
+        rescue LoadError; end
+      end
+      canvas = ChunkyPNG::Canvas.from_file(this_file)
+      data   = canvas.to_rgba_stream
+      width  = canvas.width
+      height = canvas.height
+      _ = ::LibUI.new_image(width, height) # Create the image here.
+      add_to_the_registered_widgets(_, __method__)
+      ::LibUI.image_append(
+        _,
+        data,
+        width,
+        height,
+        width
+      )
+      return _
+    end
+    nil
+  end; self.instance_eval { alias ui_image image } # === LibuiParadise.ui_image
+
+  # ========================================================================= #
+  # === LibuiParadise.font_button
+  #
+  # Create a new font button via this method.
+  # ========================================================================= #
+  def self.font_button
+    _ = ::LibUI.new_font_button
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias ui_font_button font_button } # === LibuiParadise.ui_font_button
+
+  # ========================================================================= #
+  # === LibuiParadise.multiline_entry                   (multiline_entry tag)
+  #
+  # The upstream code for the linux-variant for a multiline-entry can
+  # be found here:
+  #
+  #   https://raw.githubusercontent.com/andlabs/libui/master/unix/multilineentry.c
+  #
+  # A multiline-entry, also known more traditionally as a "textview",
+  # is a widget that allows the user to input text and modify that
+  # text as well.
+  # ========================================================================= #
+  def self.multiline_entry(
+      optional_content = nil
+    )
+    _ = ::LibUI.new_multiline_entry
+    add_to_the_registered_widgets(_, __method__)
+    if optional_content and optional_content.is_a?(String) and !optional_content.empty?
+      _.set_text(optional_content) # Set the text here, if the user provided a non-empty String.
+    end
+    return _
+  end; self.instance_eval { alias ui_multiline_entry multiline_entry } # === LibuiParadise.ui_multiline_entry
+       self.instance_eval { alias textview           multiline_entry } # === LibuiParadise.textview
+       self.instance_eval { alias text_view          multiline_entry } # === LibuiParadise.text_view
+       self.instance_eval { alias ui_text_view       multiline_entry } # === LibuiParadise.ui_text_view
+       self.instance_eval { alias ui_textview        multiline_entry } # === LibuiParadise.ui_textview
+       self.instance_eval { alias ui_text_buffer     multiline_entry } # === LibuiParadise.ui_text_buffer
+       self.instance_eval { alias input_field        multiline_entry } # === LibuiParadise.input_field
+       self.instance_eval { alias input              multiline_entry } # === LibuiParadise.input
+       self.instance_eval { alias create_text_view   multiline_entry } # === LibuiParadise.create_text_view
+
+  # ========================================================================= #
+  # === LibuiParadise.checkbox                                 (checkbox tag)
+  # ========================================================================= #
+  def self.checkbox(i = '')
+    _ = ::LibUI.new_checkbox(i)
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias create_checkbox checkbox } # === LibuiParadise.create_checkbox
+
+  # ========================================================================= #
+  # === LibuiParadise.password_entry
+  #
+  # This method will create and returns a new password entry widget. This
+  # means that input will be "disguised" via the '*' character.
+  #
+  # Usage example:
+  #
+  #   entry = LibuiParadise.password_entry
+  #
+  # ========================================================================= #
+  def self.password_entry
+    entry = ::LibUI.new_password_entry
+    add_to_the_registered_widgets(entry, __method__)
+    return entry
+  end; self.instance_eval { alias ui_password_entry password_entry } # === LibuiParadise.ui_password_entry
+
+  # ========================================================================= #
+  # === LibuiParadise.wrapper_new_progress_bar
+  #
+  # The name of this method contains "wrapper_" because there already
+  # exists a method called LibUI.new_progress_bar().
+  #
+  # The upstream C API for the libui-progressbar can be found here:
+  #
+  #   https://github.com/andlabs/libui/blob/master/unix/progressbar.c
+  #
+  # ========================================================================= #
+  def self.wrapper_new_progress_bar
+    _ = ::LibUI.new_progress_bar
+    add_to_the_registered_widgets(_, :new_progress_bar)
+    return _
+  end; self.instance_eval { alias new_progress_bar wrapper_new_progress_bar } # === LibuiParadise.new_progress_bar
+
+  # ========================================================================= #
+  # === LibuiParadise.tab
+  #
+  # This could be also called "notebook_tab" - see the alias on the
+  # bottom.
+  # ========================================================================= #
+  def self.tab
+    _ = ::LibUI.new_tab # Create a new notebook-tab here.
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias ui_tab       tab } # === LibuiParadise.ui_tab
+       self.instance_eval { alias ui_tabs      tab } # === LibuiParadise.ui_tabs
+       self.instance_eval { alias notebook     tab } # === LibuiParadise.notebook
+       self.instance_eval { alias ui_notebook  tab } # === LibuiParadise.ui_notebook
+       self.instance_eval { alias notebook_tab tab } # === LibuiParadise.notebook_tab
+       self.instance_eval { alias create_tab   tab } # === LibuiParadise.create_tab
+
+  # ========================================================================= #
+  # === LibuiParadise.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 self.area(
+      i = :use_new_area_handler
+    )
+    case i
+    # ======================================================================= #
+    # === :use_new_area_handler
+    # ======================================================================= #
+    when :use_new_area_handler,
+         :default
+      # ===================================================================== #
+      # malloc a new area-handled next:
+      # ===================================================================== #
+      i = ::LibUI::FFI::AreaHandler.malloc
+      i.to_ptr.free = Fiddle::RUBY_FREE # This one is done in upstream LibUI as well.
+    end
+    _ = ::LibUI.new_area(i) # Our new area, with the given handler.
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias area_handler area } # === LibuiParadise.area_handler
+
+  # ========================================================================= #
+  # === LibuiParadise.font                              (font tag, fonts tag)
+  # ========================================================================= #
+  def self.font(&block)
+    use_this_font = ::LibUI::FFI::FontDescriptor.malloc
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      if yielded.is_a? Hash
+        # =================================================================== #
+        # === :font_size
+        # =================================================================== #
+        if yielded.has_key? :font_size
+          use_this_font.Size = yielded.delete(:font_size)
+        end
+        # =================================================================== #
+        # === :font_family
+        # =================================================================== #
+        if yielded.has_key? :font_family
+          use_this_font.Family = yielded.delete(:font_family)
+        end
+        # =================================================================== #
+        # === :stretch
+        # =================================================================== #
+        if yielded.has_key? :stretch
+          use_this_font.Stretch = yielded.delete(:stretch)
+        end
+        # =================================================================== #
+        # === :weight
+        # =================================================================== #
+        if yielded.has_key? :weight
+          use_this_font.Weight = yielded.delete(:weight)
+        end
+        # =================================================================== #
+        # === :italic
+        # =================================================================== #
+        if yielded.has_key? :italic
+          _ = yielded.delete(:italic_family)
+          if _ == true
+            _ = 1
+          elsif _ == false
+            _ = 0
+          end
+          use_this_font.Italic = _
+        end
+      end
+    end
+    return use_this_font
+  end; self.instance_eval { alias ui_font         font } # === LibuiParadise::Extensions.ui_font
+       self.instance_eval { alias font_descriptor font } # === LibuiParadise::Extensions.font_descriptor
+
+  # ========================================================================= #
+  # === LibuiParadise.hello_world
+  #
+  # This is merely an ad-hoc test.
+  # ========================================================================= #
+  def self.hello_world
+    e 'Hello world!'
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.register_sigint
+  # ========================================================================= #
+  def self.register_sigint
+    Signal.trap('SIGINT') { exit }
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.run_in_the_background
+  # ========================================================================= #
+  def self.run_in_the_background
+    Process.daemon
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.open_file
+  #
+  # This method can be used to open a local file, via a button, the
+  # "open-file" button. Furthermore a begin/rescue clause is used to
+  # avoid "NULL pointer given" errors. At a later time we may
+  # have to fine-tune this, but for now this shall suffice.
+  # ========================================================================= #
+  def self.open_file(
+      main_window = main_window?
+    )
+    begin
+      _ = ::LibUI.open_file(main_window)
+      add_to_the_registered_widgets(_, __method__)
+      return _
+    rescue ArgumentError => _error # Rescue #<ArgumentError: NULL pointer given> here.
+      # pp _error
+      return nil
+    end
+  end; self.instance_eval { alias ui_open_file open_file } # === LibuiParadise.ui_open_file
+
+  # ========================================================================= #
+  # === LibuiParadise.search_entry
+  # ========================================================================= #
+  def self.search_entry
+    _ = ::LibUI.new_search_entry
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias ui_search_entry search_entry } # === LibuiParadise.ui_search_entry
+
+  # ========================================================================= #
+  # === LibuiParadise.non_wrapping_multiline_entry
+  #
+  # The upstream C API for the non-wrapping multiline edit can be found here:
+  #
+  #   https://raw.githubusercontent.com/andlabs/libui/master/unix/multilineentry.c
+  #
+  # ========================================================================= #
+  def self.non_wrapping_multiline_entry
+    _ = ::LibUI.new_non_wrapping_multiline_entry
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.draw_rectangle
+  #
+  # This method can be used to draw a rectangle.
+  #
+  # The third argument to this method should be a HTML colour, as a Symbol.
+  # ========================================================================= #
+  def self.draw_rectangle(
+      width  = :default,
+      height = :default,
+      colour = :orange
+    )
+    unless ::LibuiParadise.respond_to?(:padded_vbox)
+      require 'libui_paradise/libui_classes/vbox.rb'
+    end
+    unless Object.const_defined? :Colours
+      begin
+        require 'colours'
+      rescue LoadError; end
+    end
+    case width
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      width = 25
+    end
+    case height
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      height = 25
+    end
+    handler = LibUI::FFI::AreaHandler.malloc
+    handler.to_ptr.free = Fiddle::RUBY_FREE
+    area    = LibUI.new_area(handler)
+    brush   = LibUI::FFI::DrawBrush.malloc
+    brush.to_ptr.free = Fiddle::RUBY_FREE
+
+    handler_draw_event = Fiddle::Closure::BlockCaller.new(0, [1, 1, 1]) { |_, _, area_draw_params|
+      path = LibUI.draw_new_path(0)
+      LibUI.draw_path_add_rectangle(path, 0, 0, width, height)
+      LibUI.draw_path_end(path)
+      brush.Type = 0
+      # ===================================================================== #
+      # Need to find out the true RGB values. For now we divide by 255.
+      #
+      # See here:
+      #
+      #   https://stackoverflow.com/questions/10848990/rgb-values-to-0-to-1-scale
+      #
+      # ===================================================================== #
+      array = Colours.colour_to_rgb(colour)
+      brush.R = array[0] / 255.0 # 0.4
+      brush.G = array[1] / 255.0 # 0.4
+      brush.B = array[2] / 255.0 # 0.8
+      brush.A = 1.0 # Hardcoded for now.
+      area_draw_params = LibUI::FFI::AreaDrawParams.new(area_draw_params)
+      LibUI.draw_fill(area_draw_params.Context, path, brush.to_ptr)
+      LibUI.draw_free_path(path)
+    }
+
+    do_nothing = Fiddle::Closure::BlockCaller.new(0, [0]) {}
+    key_event  = Fiddle::Closure::BlockCaller.new(1, [0]) { 0 }
+
+    handler.Draw         = handler_draw_event
+    handler.MouseEvent   = do_nothing
+    handler.MouseCrossed = do_nothing
+    handler.DragBroken   = do_nothing
+    handler.KeyEvent     = key_event
+
+    vbox = ::LibuiParadise.padded_vbox # Create our vbox here.
+    vbox.maximal(area)
+    return vbox
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.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);
+  #
+  # The two numbers are width and height, as integers, respectively.
+  # In total three arguments are required. The first argument is
+  # a so-called "AreaHandler".
+  #
+  # The code may be found here:
+  #
+  #   https://github.com/andlabs/libui/blob/master/windows/areascroll.cpp
+  #
+  # ========================================================================= #
+  def self.scrolling_area(
+      widget,
+      width   = :default,
+      height  = :default
+    )
+    case width
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default, nil
+      width = 400
+    end
+    case height
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default, nil
+      height = 400
+    end
+    _ = ::LibUI.new_scrolling_area(widget, width, height)
+    # ======================================================================= #
+    # The next part does not yet work - is it even possible to add widgets
+    # to a scrolling area in libui?
+    # if optional_widget
+    #   _.add(optional_widget)
+    # end
+    # ======================================================================= #
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias ui_scrolling_area  scrolling_area } # === LibuiParadise::Extensions.ui_scrolling_area
+       self.instance_eval { alias ui_scrolled_window scrolling_area } # === LibuiParadise::Extensions.ui_scrolling_window
+
+  # ========================================================================= #
+  # === LibuiParadise.colour_button
+  #
+  # The upstream API for a colour-button (in C) can be found here:
+  #
+  #   https://github.com/andlabs/libui/blob/master/unix/colorbutton.c
+  #
+  # ========================================================================= #
+  def self.colour_button
+    _ = ::LibUI.new_color_button
+    ::LibuiParadise.register_this_fiddle_pointer_widget(_, __method__)
+    return _
+  end; self.instance_eval { alias color_button      colour_button } # === LibuiParadise.color_button
+       self.instance_eval { alias new_color_button  colour_button } # === LibuiParadise.new_color_button
+       self.instance_eval { alias new_colour_button colour_button } # === LibuiParadise.new_colour_button
+       self.instance_eval { alias ui_colour_button  colour_button } # === LibuiParadise.ui_colour_button
+
+  # ========================================================================= #
+  # === LibuiParadise.generic_window
+  #
+  # Usage example:
+  #
+  #   x = LibuiParadise.generic_window(LibuiParadise.button('1'), LibuiParadise.button('2'))
+  #   x = LibuiParadise.generic_window(LibuiParadise.button('1'), LibuiParadise.button('2')) {{ height: 50 }}
+  #   x = LibuiParadise.generic_window(LibuiParadise.button('1'), LibuiParadise.button('2')) {{ height: 50, width: 120 }}
+  #
+  # ========================================================================= #
+  def self.generic_window(
+      *use_these_widgets,
+      &block
+    )
+    unless LibuiParadise.respond_to?(:GenericWindow)
+      require 'libui_paradise/generic_window/generic_window.rb'
+    end
+    generic_window = LibuiParadise::GenericWindow.new { :do_not_run_yet }
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      if yielded.is_a? Hash
+        # =================================================================== #
+        # === :height
+        # =================================================================== #
+        if yielded.has_key?(:height)
+          generic_window.set_height(
+            yielded[:height]
+          )
+          generic_window.update_the_main_window
+        end
+        # =================================================================== #
+        # === :width
+        # =================================================================== #
+        if yielded.has_key?(:width)
+          generic_window.set_width(
+            yielded[:width]
+          )
+          generic_window.update_the_main_window
+        end
+        # =================================================================== #
+        # === :title
+        # =================================================================== #
+        if yielded.has_key?(:title)
+          generic_window.set_title(
+            yielded[:title]
+          )
+          generic_window.update_the_main_window
+        end
+      end
+    end
+    # ======================================================================= #
+    # Next prepare adding more widgets to this generic window:
+    # ======================================================================= #
+    use_these_widgets.flatten!
+    use_these_widgets.compact!
+    if use_these_widgets.is_a?(Array) and !use_these_widgets.empty?
+      generic_window.add_these_widgets(use_these_widgets)
+    end
+    return generic_window
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise.combobox
+  # ========================================================================= #
+  def self.combobox(
+      optional_array = nil, &block
+    )
+    combobox = ::LibUI.new_combobox
+    # ======================================================================= #
+    # Register it at once:
+    # ======================================================================= #
+    add_to_the_registered_widgets(combobox, __method__)
+    if block_given?
+      optional_array = yield
+    end
+    if optional_array and optional_array.is_a?(Array)
+      # append_this_array_to_that_combobox(optional_array, combobox)
+      combobox.append_this_array(optional_array)
+    end
+    return combobox
+  end; self.instance_eval { alias combo_box    combobox } # === LibuiParadise.combo_box
+       self.instance_eval { alias ui_combo_box combobox } # === LibuiParadise.ui_combo_box
+       self.instance_eval { alias ui_combobox  combobox } # === LibuiParadise.ui_combobox
+
+  # ========================================================================= #
+  # === LibuiParadise.editable_combobox
+  #
+  # This is a combo-box that the user can modify.
+  # ========================================================================= #
+  def self.editable_combobox(
+      optional_array = nil,
+      &block
+    )
+    _ = ::LibUI.new_editable_combobox
+    if block_given?
+      optional_array = yield
+    end
+    if optional_array and optional_array.is_a?(Array)
+      append_this_array_to_that_combobox(optional_array, _)
+    end
+    add_to_the_registered_widgets(_, __method__)
+    return _
+  end; self.instance_eval { alias editable_combo_box    editable_combobox } # === LibuiParadise.editable_combo_box
+       self.instance_eval { alias ui_editable_combo_box editable_combobox } # === LibuiParadise.ui_editable_combo_box
+
+  # ========================================================================= #
+  # === LibuiParadise.set_title
+  #
+  # Simpler window-set-title functionality.
+  # ========================================================================= #
+  def self.set_title(
+      this_title,
+      main_window = main_window?
+    )
+    ::LibUI.window_set_title(main_window, this_title)
+  end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  LibuiParadise.hello_world
+end