libui_paradise 0.2.49 → 0.4.13

data/README.md

@@ -2,7 +2,7 @@
 [![forthebadge](https://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
 [![Gem Version](https://badge.fury.io/rb/libui_paradise.svg)](https://badge.fury.io/rb/libui_paradise)
 
-This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">09.10.2022</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">16:36:45</span> o'clock.
+This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">28.12.2023</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">22:23:45</span> o'clock.
 
 ## The libui_paradise project
 
@@ -13,12 +13,12 @@ by me via **gimp** and ImageMagick - the rounded borders were
 done via ImageMagick. You can re-use this image if you would like to,
 including the colour-pattern, via a **CC BY 3.0** licence. See the following
 link for that licence: https://creativecommons.org/licenses/by/3.0/. For
-**cfdg** itself, have a look at: https://www.contextfreeart.org/gallery/)
+<b>cfdg</b> itself, have a look at: https://www.contextfreeart.org/gallery/)
 
-The **libui_paradise project** aims to enhance the official (upstream)
+The <b>libui_paradise project</b> aims to enhance the official (upstream)
 ruby-libui bindings a little bit.
 
-You can find the upstream ruby-libui bindings, maintained by **kojix2**,
+You can find the upstream ruby-libui bindings, maintained by <b>kojix2</b>,
 here:
 
 https://rubygems.org/gems/libui
@@ -154,7 +154,7 @@ around one day, that idea should be retained for other GUIs
 in the future.
 
 It's quite difficult to get GTK and ruby-gtk to work on
-**windows** - I tried to compile it some weeks ago but I
+<b>windows</b> - I tried to compile it some weeks ago but I
 ended up having "missing symbols" error messages afterwards.
 I managed to get the hello-world.c example working, but the
 more complicated examples did not work for me.
@@ -172,7 +172,7 @@ no binary bundles for ruby-gtk on windows anymore either. I
 assume it is possible if you know msys2, and the windows 
 platform, but I am no expert on either, so ...)
 
-**libui** is so much simpler to use on windows than GTK,
+<b>libui</b> is so much simpler to use on windows than GTK,
 though - just do **gem install libui** and it'll work,
 as-is. Literally. That's it. I tried it on my windows
 laptop and it **does** indeed work. That convinced me
@@ -286,7 +286,8 @@ sense in this regard.
 
 ## How to add a margin in LibUI
 
-Use something like:
+Use the following API if you wish to have your main window
+use a margin:
 
     LibUI.window_set_margined(MAIN_WINDOW, 1)
 
@@ -432,14 +433,19 @@ Or just:
 
 Since as of 2022 I prefer the longer variant, e. g. **LibUI**init. The
 old UI constant ("alias") will be retained, but new code added to the
-libui_paradise gem will not use **UI** - instead the slightly longer
-**LibUI** is used.
-  
+libui_paradise gem will not use <b>UI</b> - instead the slightly longer
+<b>LibUI</b> is used.
+
+Note that since as of <b>December 2023</b>, whenever the libui_paradise
+gem is required, <b>LibuiParadise.init</b> is automatically called,
+which in turn invokes LibUI.init. The reason as to why this is
+the new default is so that we can omit one line of code.
+
 ## Subclassing
 
 Currently subclassing from LibUI elements does not work - I simply
-have no idea how to "subclass" from a **Fiddle::Pointer**. Perhaps we
-have to build up a data structure that behaves like **Fiddle::Pointer**
+have no idea how to "subclass" from a <b>Fiddle::Pointer</b>. Perhaps we
+have to build up a data structure that behaves like <b>Fiddle::Pointer</b>
 but also has methods that allow for a more direct 'OOP behaviour'. Has
 anyone tried this yet? I am scared to try considering I already got
 segfaults everywhere ...
@@ -456,8 +462,8 @@ The following API can be used to create a new scrolling area:
 
     LibUI.new_scrolling_area
 
-Scrolling areas have horziontal and vertical scrollbars. The
-amount that can be scrolled is determined by the area's
+<b>Scrolling areas</b> may contain horizontal and vertical scrollbars.
+The amount that can be scrolled is determined by the area's
 size, which is decided by the programmer (both when creating
 the Area and by a call to SetSize). Only a portion of the
 Area is visible at any time; drawing and mouse events are
@@ -465,9 +471,9 @@ automatically adjusted to match what portion is visible,
 so you do not have to worry about scrolling in your
 event handlers.
 
-The method LibUI.new_scrolling_area() accepts three arguments.
+The method <b>LibUI.new_scrolling_area()</b> accepts <b>three arguments</b>.
 The second and third are width and height, respectively
-(as **integers**).
+(as <b>integers</b>).
 
 The first argument is the area handle. It has the following
 pointer types (struct):
@@ -478,7 +484,7 @@ pointer types (struct):
     .DragBroken
     .KeyEvent
 
-The handlerDraw() function in C looks like this:
+The <b>handlerDraw() function</b> in C looks like this:
 
     static void handlerDraw(uiAreaHandler *a, uiArea *area, uiAreaDrawParams *p)
     {
@@ -497,6 +503,12 @@ The handlerDraw() function in C looks like this:
 	    uiFreeFontButtonFont(&defaultFont);
     }
 
+This means that you will have to pass three arguments to
+this method - all are mandatory. Failure to do so may yield an
+error message, such as:
+
+    gems/libui-0.1.2.pre/lib/libui/ffi.rb:20:in `call': wrong number of arguments (given 0, expected 3) (ArgumentError)
+
 The scrollable area may look like this:
 
 <img src="https://raw.githubusercontent.com/msink/kotlin-libui/master/samples/hello/hello-windows.png">
@@ -518,9 +530,10 @@ label / ui_text widget.
 
 ## Working with combo-boxes
 
-To create a combo-box in vanilla libui, do this:
+To create a combo-box in vanilla libui, do this in plain ruby-libui:
 
-    alignment = LibUI.new_combobox
+    alignment = LibUI.new_combobox # Here we actually create the combobox.
+    # Next, we show how to append to a combobox:
     LibUI.combobox_append(alignment, 'Left')
     LibUI.combobox_append(alignment, 'Center')
     LibUI.combobox_append(alignment, 'Right')
@@ -552,11 +565,11 @@ For instance:
 
     LibUI.combobox_set_selected(combobox, 0) # The first one will be active too.
   
-To **query the currently selected value**, use:
+To <b>query the currently selected value</b>, use:
 
     LibUI.combobox_selected(pointer)
 
-This is usually done via a **proc {}** object. See kojix2' examples.
+This is usually done via a <b>proc {}</b> object. See kojix2' examples.
 
 In LibuiParadise a few custom methods were added, such as 
 **.ui_sync_connect()**. This method was added to connect a
@@ -578,11 +591,32 @@ So:
 There are probably more elegant ways to solve this, but I only
 wanted to solve this quickly and move on.
 
-The **source code** to the combo-box in libui, at the least
+To add content to an editable combobox youc an use:
+
+    LibUI.append() # .append() adds the named item to the end of the EditableCombobox.
+
+A more concise example for populating a combobox may be
+this one here:
+
+    combo_box = LibUI.combobox {
+      ['combobox Item 1', 'combobox Item 2', 'combobox Item 3']
+    }
+
+The <b>source code</b> to the combo-box in libui, at the least
 for UNIX/Linux, can be seen here:
 
 https://github.com/andlabs/libui/blob/master/unix/combobox.c 
 
+## How to add a libui-widget to the main window - how to designate a child widget:
+
+    LibUI.window_set_child(main_window, button) # Both these widgets have to be created first, of course.
+
+## LibUI.control_show
+
+No clue what this does so far.
+
+    LibUI.control_show(main_window)
+
 ## Error messages and ui_error_message
 
 In LibUI respectively ruby-libui you can display error messages
@@ -606,22 +640,37 @@ respectively.
 **Form** is a container that takes labels for its contents. This is currently
 just a stub though - we may have to research this with better examples.
 
-## Libui Checkbox
+## Checkboxes in Libui-ng
 
-A simple checkbox example in **plain** ruby-libui follows:
+A simple checkbox example in <b>plain</b> ruby-libui follows:
 
-    checkbox = UI.checkbox('Checkbox')
-    checkbox_toggle_callback = proc { |ptr|
-      checked = UI.checkbox_checked(ptr) == 1
-      UI.checkbox_set_text(ptr, "I am the checkbox (#{checked})")
+    checkbox = LibUI.checkbox('Checkbox')
+    checkbox_toggle_callback = proc { |pointer|
+      checked = LibUI.checkbox_checked(pointer) == 1
+      LibUI.checkbox_set_text(ptr, "I am the checkbox (#{checked})")
     }
 
+Or:
+
+    checkbox = LibUI.new_checkbox('Checkbox')
+    # ui_checkbox can be used if you use the libui_paradise gem.
+
 This may look like so on Linux:
 
 <img src="https://i.imgur.com/d7qWalZ.png" style="margin-left: 2em; padding: 4px; border: 1px solid black;">
 
-To query whether a checkbox is **active**, use code such as the
-following:
+To set such a checkbox to the <b>checked-state</b> (that is, as if
+the user clicked on it), use the following method, if you use the
+libui_paradise gem:
+
+    checkbox.set_checked(1)
+
+To query its state use:
+
+    checked = LibUI.checkbox_checked(pointer) == 1
+
+To <b>query</b> whether a checkbox is <b>active</b>, use code such as
+the following:
 
     checkbox.is_active?
     checkbox.active?
@@ -630,22 +679,35 @@ This depends on the modifications to Fiddler::Pointer, so
 be wary when you use this - there be dragons (perhaps). Most
 of these modifications are based on **.object_id**, which is
 registered in a main, toplevel Hash in the 
-**libui_paradise project**. Not very elegant, but simple, and
+<b>libui_paradise project</b>. Not very elegant, but simple, and
 it works (for the most part).
 
+The toggle-event for a checkbox can be triggered via:
+
+    checkbox_toggle_callback = proc { |pointer|
+      checked = LibLibUI.checkbox_checked(pointer) == 1
+      LibUI.window_set_title(MAIN_WINDOW, "Checkbox is #{checked}")
+      LibUI.checkbox_set_text(pointer, "I am the checkbox (#{checked})")
+      0
+    }
+
+To respond to <b>on-toggled events</b>, do use:
+
+    LibUI.checkbox_on_toggled(checkbox, checkbox_toggle_callback, nil)
+
 ## Adding a widget into another widget
 
-I chose the following **API** for this:
+I chose the following <b>API</b> for this:
 
     box1.add(box2, 1)
 
-Note that this is "cheating" a bit because the method **.add()** is defined
-on **Fiddle::Pointer**. That's scary! Segfaults coming your way. But it
-also seems to work to some extent. Which is amazing ... :-)
+Note that this is "cheating" a bit because the method <b>.add()</b> is
+defined on <b>Fiddle::Pointer</b>. That's scary! Segfaults coming your
+way. But it also seems to work to some extent. Which is amazing ... :-)
 
 In ruby-gtk it is quite common to use **.add()**. While **.pack_start()**
 and **.pack_end()** are available in ruby-gtk as well, I think .add() is
-the simpler name. We just **add a widget to another widget** - job done.
+the simpler name. We just <b>add a widget to another widget</b> - job done.
 
 (I may also use << as alias to .add() and while << is great, remember
 that it can not easily be used all the time, e. g. box1 << box2 << 
@@ -686,6 +748,20 @@ The notebook-tab may look like this:
 
 <img src="https://i.imgur.com/olWQAIJ.png" style="margin-left: 2em">
 
+A new tab can be created via:
+
+    tab = LibUI.new_tab
+
+To populate the notebook-tab you can use .tab_append() such as
+shown next:
+
+    hbox1 = LibUI.new_horizontal_box
+    hbox2 = LibUI.new_horizontal_box
+    LibUI.tab_append(tab, 'Page 1', hbox1)
+    LibUI.tab_append(tab, 'Page 2', hbox2)
+    LibUI.tab_append(tab, 'Page 3', UI.new_horizontal_box)
+    LibUI.box_append(inner2, tab, 1)
+
 ## Create a vertical box:
 
 Use code like this:
@@ -699,8 +775,8 @@ If you use the libui_paradise gem, you can use this:
 
 ## Adding a horizontal separator or a vertical separator
 
-The method **UI.new_horizontal_separator** can be used to add (or rather
-first create) a horizontal separator.
+The method <b>LibUI.new_horizontal_separator</b> can be used to add (or
+rather first create) <b>a horizontal separator</b>.
 
 You can then add it via .add() or << if you use the libui_paradise
 project. Alternatively you can use the toplevel method provided by
@@ -749,6 +825,10 @@ not necessarily recommending this be done, but **if** you ever have
 such a use case then you can use it - which is another reason why
 I added this screenshot, so that I don't forget. :)
 
+The toplevel method <b>LibuiParadise.horizontal_separator()</b>
+has also been added; it is simply a wrapper towards
+<b>LibUI.new_horizontal_separator()</b>.
+    
 ## Padding elements in LibUI
 
 The general API for setting padding to a container in LibUI
@@ -832,18 +912,38 @@ hand. Only the raw filename will be used, so if you
 have a file at **/tmp/foo/bar.rb** then the title
 of the window will be **bar.rb**.
 
-## Entry
+## Entries in libui (libui-entry)
 
-An entry in libui may look like this:
+Let's first show how an <b>entry</b> in libui may look like:
 
 <img src="https://raw.githubusercontent.com/parro-it/libui-node/master/docs/media/UiEntry.png" style="margin-left:1em">
 
-Such an entry can be set to be **read only** (readOnly: Boolean, aka true or false).
+Such an entry can be set to be <b>read only</b> (readOnly: Boolean, aka true or false).
+This means that it can not be changed by the user; it is then only used to
+display some content.
 
-The upstream C code for libui-entry, for **unix/**, can be seen here:
+The upstream C code for libui-entry, for <b>unix/</b>, can be seen here:
 
 https://github.com/andlabs/libui/blob/master/unix/entry.c
 
+To create a new libui-entry, in raw libui-code, use this method:
+
+    LibUI.new_entry
+    entry = LibUI.new_entry # or better, this variant
+
+In ruby, for the LibUI namespace, you can set text on an entry
+by calling <b>LibUI.entry_set_text()</b>, such as shown in
+the following example:
+
+    LibUI.entry_set_text(entry, 'Please enter your feelings')
+
+If you use the libui_paradise gem, a modification in Fiddle
+is to allow the method calls called .is_read_only and its
+alias name, .readonly. This can be called on the entry,
+such as:
+
+    entry.readonly
+
 ## Borderless windows and fullscreen windows
 
 A window that is **borderless: true** will not show any title or
@@ -853,18 +953,26 @@ To set the main window to full screen (occupy the whole monitor) do:
 
    LibUI.window_set_fullscreen(main_window, 1)
 
+## How to add a new main window:
+                                   # width, height, hasMenubar
+    main_window = LibUI.new_window('hello world', 300, 200, 1)
+
+The source code for this method can be seen here:
+
+https://raw.githubusercontent.com/libui-ng/libui-ng/master/unix/window.c
+
 ## Spinbutton / Spinbox
 
 You can use the following API for a spinbox:
 
-    UI.new_spinbox
+    LibUI.new_spinbox
 
 To create a new spinbox.
 
 To specify the **min** and **max** range, pass them as parameters
 on creation-time:
 
-    UI.new_spinbox(0, 100)
+    LibUI.new_spinbox(0, 100)
 
 If you use the extensions found in the libui_paradise gem then
 you can do this instead:
@@ -884,9 +992,9 @@ to see how this works.
 
 Relevant methods in regard to the spinbox in libui are as follows:
 
-    UI.spinbox_on_changed()
-    UI.spinbox_set_value()
-    UI.spinbox_value() 
+    LibUI.spinbox_on_changed()
+    LibUI.spinbox_set_value()
+    LibUI.spinbox_value() 
 
 To **set** a value use either of the following two methods:
 
@@ -903,31 +1011,34 @@ A text-view widget shows content, such as the content of a local file.
 
 In libui the general API for this is:
 
-    UI.new_multiline_entry                      # this is a textview
+    LibUI.new_multiline_entry                      # this is a textview
 
 ## Control Gallery
 
-Here is an image, from kotlin-libui, how this may look on windows:
+Here is an image, from <b>kotlin-libui</b>, how this may look on windows:
 
 <img src="https://raw.githubusercontent.com/msink/kotlin-libui/master/samples/controlgallery/controlgallery-windows7.png" style="margin-left: 2em">
 
-## LibUI.new_button() - how to work with buttons in LibUI
+## LibUI.new_button() - how to work with buttons in LibUI in general
 
-<b>LibUI.new_button</b> allows us to create a new button.
+<b>LibUI.new_button</b> allows us to create a new button, via
+the LibUI gem maintained by kojix2.
 
-Examples:
+Examples for this, syntax-wise, follow:
 
     button1 = LibUI.new_button('Text')
     button2 = LibUI.new_button('▶')
+    button3 = LibUI.new_button('■') # You can use Unicode / Emojis here just fine.
+    button3 = LibUI.new_button('♥') # This also gives you a way to do simple GUI elements, thanks to Unicode / Emoji.
 
-Now, we need to "tell" this button what to do when it is
-clicked. This is done via Libui.button_on_clicked().
+Now, we need to "<i>tell</i>" this button what to do when it is clicked
+by the user. This is done via the method <b>LibUI.button_on_clicked()</b>.
 
-Example:
+Usage example:
 
-    LibUI.button_on_clicked(button) do
-      LibUI.msg_box(MAIN_WINDOW, 'Information', 'You clicked the button')
-    end
+    LibUI.button_on_clicked(button) {
+      LibUI.msg_box(MAIN_WINDOW, 'Information', 'You clicked the button') # Show a message-box upon clicking this button.
+    }
 
 ## Enabling / Disabling buttons in libui
 
@@ -1073,115 +1184,6 @@ to be simpler for the time being. I may plan to change a lot more one day,
 if I ever manage to find out how to simulate proper subclasses via
 Fiddle::Pointer ... :) 
 
---------------------------------------------------------------------------------
-## SNIPPETS.md
-
-Next, the content of the file called **SNIPPETS.md** will be shown. Note
-that this file will eventually be integreated into this file, and then
-subsequently removed one day.
-
-
-<pre>
-# How to add a new main window:
-                                             # width, height, hasMenubar
-  main_window = UI.new_window('hello world', 300, 200, 1)
-
-  Source code:
-
-    https://raw.githubusercontent.com/andlabs/libui/master/unix/window.c
-
-# How to add a libui-widget to the main window / Designate a child widget:
-
-  UI.window_set_child(main_window, button)
-
-# Act on closing-event (on quit tag):
-
-  UI.window_on_closing(main_window) {
-    puts 'Bye Bye'
-    UI.control_destroy(main_window)
-    UI.quit
-    0
-  }
-  # Or simpler:
-  close_properly(main_window)
-
-# Add the window to the main UI:
-
-  UI.control_show(main_window)
-  main_window.show_the_controls # Or use this one here.
-
-
-# Add a checkbox (checkbox tag, checkbutton)
-
-  checkbox = UI.new_checkbox('Checkbox') # or ui_checkbox
-  checkbox_toggle_callback = proc { |pointer|
-    checked = UI.checkbox_checked(pointer) == 1
-    UI.window_set_title(MAIN_WINDOW, "Checkbox is #{checked}")
-    UI.checkbox_set_text(pointer, "I am the checkbox (#{checked})")
-    0
-  }
-  UI.checkbox_on_toggled(checkbox, checkbox_toggle_callback, nil)
-  UI.box_append(inner, checkbox, 0)
-
-  To set it checked:
-
-  checkbox.set_checked(1)
-
-  To query its state:
-
-    checked = UI.checkbox_checked(pointer) == 1
-
-# And the control:
-
-  UI.control_show(main_window)
-
-# Using a text-entry (ui entry tag):
-
-  text_entry = UI.new_entry
-  UI.entry_set_text(text_entry, 'Please enter your feelings')
-  UI.entry_on_changed(text_entry, text_changed_callback, nil)
-
-  # To set this on a "multiline entry", aka spanning several
-  # rows, do use:
-  UI.multiline_entry_set_text(entry1, 'Yo there')
-  ui_text_view # an alias used in libui_paradise
-
-  text1 = UI.entry_text(entry1) # Obtain text. You may have to call .to_s on it, to guarantee the String.
-  UI.multiline_entry_text # Obtain the text from a multiline entry.
-
-# Create a combobox (combo tag, combobox tag):
-
-  combobox_selected_callback = proc { |ptr|
-    puts "New combobox selection: #{UI.combobox_selected(ptr)}"
-  }
-  cbox = UI.new_combobox
-  UI.combobox_append(cbox, 'combobox Item 1')
-  UI.combobox_append(cbox, 'combobox Item 2')
-  UI.combobox_append(cbox, 'combobox Item 3')
-  UI.box_append(inner, cbox, 0)
-  UI.combobox_on_selected(cbox, combobox_selected_callback, nil)
-
-  # Or more concise:
-  combo_box = UI.combobox {
-    ['combobox Item 1', 'combobox Item 2', 'combobox Item 3']
-  }
-
-
-# Add content to an editable combox:
-
-  UI.append() # .append() adds the named item to the end of the EditableCombobox.
-
-# How to build a menu-interface (menu tag):
-
-  help_menu = UI.new_menu('Help')
-  version_item = UI.menu_append_item(help_menu, 'Version')
-
-
-</pre>
-
-
---------------------------------------------------------------------------------
-
 ## Advantages and Disadvantages of the libui project
 
 It would be unfair to only selectively name advantages but not talk about
@@ -1189,29 +1191,31 @@ disadvantages, so this subsection will show some limitations, trade-offs,
 constraints and opportunities. This is not complete, but it may become
 somewhat more complete over time. Stay tuned.
 
-(a) Advantages:
+(a) Advantages of LibUI:
 
-- Works on windows out-of-the-box after you installed the libui-gem.
+- Works on the windows platform, out-of-the-box, after the libui-gem has been installed.
 - Is super-simple to use compared to other toolkits, including ruby-gtk.
-- Super-simple to build up a prototype for a GUI, buttons that work,
-spin-boxes, text-views and so forth. Faster than any other toolkit
-IMO.
+- Super-simple to build up a prototype for a GUI, buttons that work, spin-boxes, text-views
+and so forth. Faster than any other toolkit, IMO.
 - Works cross-platform.
 
-(b) Disadvantage:
+(b) Disadvantage of LibUI:
 
 - Limited ability to control the layout and size of widgets.
-- May look like utter crap ... :-)
-- Some functionality is missing, such as a scrolled-window for every widget.
+- May look like utter crap on some platforms ... :-)
+- Some functionality is flat-out missing, such as a scrolled-window for every widget
+or tooltips for every widget.
 - No way to use different fonts in the same application and choosing a font
 is needlessly complicated. (This may not be completely correct, though -
-the glimmer-dsl-libui has example that seem to work. But if you ask me
+the glimmer-dsl-libui has examples that seem to work. But if you ask me
 right now in 2021 how this works via a standalone example then I can
 happily tell you I have absolutely no idea. Which brings me to the
-next problem...)
-- Lack of documentation. This part is REALLY annoying ...
+next problem ...)
+- Lack of documentation overall. This part is REALLY annoying, because there
+are only few users, so asking others about documentation when there is nobody
+else using it, plan sucks ...
 
-Some more disadvantages relate to Fiddle::Pointer. You kind of need to
+Some more disadvantages relate to <b>Fiddle::Pointer</b>. You kind of need to
 know C fairly well as well as the GC in ruby, in order to understand
 what is going on. Since I don't, I hit a dead end, kind of.
 
@@ -1219,6 +1223,10 @@ This is so far in September 2021. Let's see what the future brings.
 Perhaps other toolkits will learn from libui and implement the good
 parts for **their own** widget set.
 
+Update in December 2023: things improved a bit, so the above is not
+100% correct anymore. In particular libui-ng may receive some more
+usability-centric updates in the next months.
+
 ## LibuiParadise.parse_this_config_file()
 
 This method can be used to parse a .config file. This file should
@@ -1268,17 +1276,21 @@ You can also use something like '95%' as input. In that case the
 desired value will be calculated depending on the max-resolution
 of the current display. This presently only works on **linux**; if
 someone knows how to make this work on windows and Mac OSX let
-me know. (On these systems it will instead default to a hardcoded
-value of 1024 for width and 800 for height).
+me know. (On these two systems the method will instead default
+to a hardcoded value of 1024 for width and 800 for height; these
+values, I think, are probably fairly safe, to also support older
+laptops. Evidently for smartphone devices this won't work, so 
+if anyone has an idea how to handle this differently let me 
+know).
 
 The following example shows how to use a percentage value:
 
-    set_height('80%')
+    set_height('80%') # 80% of the max-height.
 
 ## Coloured Text
 
 At this point I only show how this may look on Win7, re-using
-the picture the **kotlin-libui developers** made available:
+the picture the <b>kotlin-libui developers</b> made available:
 
 <img src="https://raw.githubusercontent.com/msink/kotlin-libui/master/samples/drawtext/drawtext-windows7.png" style="margin-left: 2em">
 
@@ -1390,9 +1402,9 @@ shows how this may look (on icewm):
 The syntax goes something like this:
 
     rb = ui_radio_buttons
-    UI.radio_buttons_append(rb, 'Radio Button 1')
-    UI.radio_buttons_append(rb, 'Radio Button 2')
-    UI.radio_buttons_append(rb, 'Radio Button 3')
+    LibUI.radio_buttons_append(rb, 'Radio Button 1')
+    LibUI.radio_buttons_append(rb, 'Radio Button 2')
+    LibUI.radio_buttons_append(rb, 'Radio Button 3')
     outer_vbox.minimal(rb) # add the radio-button control to the box.
 
 In other words: you instantiate a new rb-radio-button 'pointer';
@@ -1427,26 +1439,67 @@ For "raw" libui, use this:
 
 ## Tables in LibUI
 
-You may be able to create a new table via:
+The API for creating a new table in <b>LibUI</b> is this:
 
     table = LibUI.new_table
-    
-    model = LibUI.new_table_model(model_handler)
+    table = LibUI.new_table(table_model)
+
+You need to use a model for the table, and pass it as
+its first argument. The next line of code shows how
+this is done:
+
+    model = LibUI.new_table_model(model_handler) # create the model here
+
+Next you have to prevent segfaults by .malloc-ating the
+table params. This can be done in the following manner:
 
     table_params = LibUI::FFI::TableParams.malloc
     table_params = Fiddle::RUBY_FREE
     table_params.Model = model
     table_params.RowBackgroundColorModelColumn = -1
-    table = LibUI.new_table(table_params)
+    table = LibUI.new_table(table_params) # And pass it here.
 
-The table header is an array that contains the following attributes:
+The <b>table header</b> is an array that contains the following attributes:
 
-    1. editable, bool type, the column is whether editable
+    1. editable, bool type: determines whether column is editable
     2. textColor
     3. title
     4. type, specify value of button, image, imgtext, progress, checkbox, checkboxtext, color, text
 
-Note that this is incomplete; it's a bit complicated.
+See the example distributed in this gem, in the file at
+<b>examples/simple/012_table_example.rb</b>.
+
+This will yield the following result - at the least on Linux and IceWM:
+
+<img src="https://i.imgur.com/Y7m58DH.png" style="margin: 1em">
+
+You can append a new text column via:
+
+    ::LibUI.table_append_text_column(table, 'Header goes in here', 0, -1)
+
+As this is a bit cumbersome to type, libui_paradise simplifies this
+a tiny bit into:
+
+    table.append_text_column('Header goes in here', 0, -1)
+
+Be careful to <b>only</b> append entries there if the underlying
+dataset - our Array - also contains these entries; otherwise the
+application would segfault. The example at
+<b>examples/complex/010_table_example.rb</b> shows this - look
+at the commented out example to test it.
+
+In November 2023 the API was a bit simplified, towards this:
+
+    table.append_text_column('Header goes in here', 0)
+    table.append_text_column('Another header goes in here', 1)
+    table.append_text_column('And this is yet another header', 2)
+
+So you can now omit the last -1 part. Expect more simplifications
+in the future - all that malloc stuff should be handled by
+libui_paradise, rather than in the downstream application
+code.
+
+Note that this section is incomplete; it's a bit complicated.
 
 In the end, this is possible though:
 
@@ -1525,7 +1578,7 @@ Available "**new**"-widgets in LibUI:
     LibUI.new_table_value_color
     LibUI.new_table_value_string
     LibUI.new_time_picker
-    LibUI.new_menu
+    LibUI.new_menu                                 # this is a menu, appearing on the upper area
     LibUI.new_multiline_entry                      # this is a textview
     LibUI.new_non_wrapping_multiline_entry
     LibUI.new_open_type_features
@@ -1544,8 +1597,8 @@ Available "**new**"-widgets in LibUI:
     LibUI.new_weight_attribute
     LibUI.new_form                                 # this is a form
     LibUI.new_size_attribute
-    LibUI.new_window
-    LibUI.new_slider                               # this is a slider
+    LibUI.new_window                               # this will create a new window, such as a gtk-window on linux
+    LibUI.new_slider                               # this is a slider, allowing the user to set a value via a small GUI-handle
 
 ## A search entry in LibUI
 
@@ -1572,9 +1625,23 @@ Example for this:
     width = canvas.width
     height = canvas.height
 
-## Creating a new drawing area
+## How to to build a menu-interface (menu tag):
+
+Building a menu in libui is possible by using the method
+<b>LibUI.new_menu()</b>.
+
+A more complete example follows:
+
+    help_menu = LibUI.new_menu('Help')
+    version_item = LibUI.menu_append_item(help_menu, 'Version')
 
-This should suffice:
+On IceWM this may look like this:
+
+<img src="https://i.imgur.com/1rWYcZM.png" style="margin: 1em">
+
+## Creating a new drawing area in LibUI
+
+The following code should suffice:
 
     handler             = LibUI::FFI::AreaHandler.malloc
     handler.to_ptr.free = Fiddle::RUBY_FREE
@@ -1582,12 +1649,19 @@ This should suffice:
 
 ## Horizontal boxes
 
-A HBox represents a horizontal box. The API for putting 
-something into a hbox goes as follows, such as when you
-wish to put a text-entry into the hbox:
+A <b>HBox</b> represents a <b>horizontal box</b>.
+
+In pure ruby-libui a new horizontal box (hbox) can be created via:
+
+    hbox = LibUI.new_horizontal_box
+
+The API for putting something into a hbox goes as follows, such as
+when you wish to put a text-entry into the hbox:
 
     LibUI.box_append(hbox1, text_entry, 1)
 
+If you use libui_paradise then you can also use << instead.
+
 ## The slider widget
 
 If you use the LibuiParadise gem then you can create and use a new slider
@@ -1600,12 +1674,25 @@ like this:
       puts "New Slider value: #{UI.slider_value(ptr)}"
       0
     }
-    UI.slider_on_changed(slider, slider_changed_callback) # last element is nil, but it seems we can omit it
+    LibUI.slider_on_changed(slider, slider_changed_callback) # last element is nil, but it seems we can omit it
 
 This may look like so on Linux:
 
 <img src="https://i.imgur.com/GVKPMS7.png" style="margin-left: 3em">
 
+In raw-libui you instantiate a new slider in this way:
+
+    slider = LibUI.new_slider(0, 10)
+
+The two values here, 0 and 10, specify start and end position.
+
+Note that you can also use the block-form rather than use
+a proc-callback. Example for this:
+
+    LibUI.slider_on_changed(slider1) {|widget|
+      puts 'The value of the slider was changed.'
+    }
+
 ## Create a new tabbed notebook:
 
    ui_tabs
@@ -1668,7 +1755,7 @@ For instance, the text-weight part accepts these values
     maximum
     # or  any number between minimum and maximum
 
-To create an attributed String you can use the following API:
+To create an <b>attributed String</b> you can use the following API:
 
     string = LibUI.new_attributed_string
     attributes = LibUI.new_family_attribute("Courier New 30") # Specify a certain font.
@@ -1800,6 +1887,7 @@ may be helpful.
 The API for creating a new grid in libui is quite complex and
 hard to remember:
 
+    #                       gtk-widget,  left, top, xspan, yspan, hexpand, halign, vexpand, valign
     LibUI.grid_append(grid, entry1,      0, 0, 2, 1, 0, 0, 1, 0)
     LibUI.grid_append(grid, text('Yo2'), 1, 0, 1, 1, 0, 0, 1, 0) # text() can be used if you use the libui_paradise gem
 
@@ -1830,10 +1918,12 @@ The documentation for Go has this signature:
 
 Append adds the given control to the Grid, at the given coordinate. 
 
-I assume that **uiControl c** refers to the widget that is to be embedded
-into the grid, so the numbers that follow afterwards are the ones
-that are important. Let's have a look at them, based on the above API
-call, and only list these again, without the **()**:
+The element called <b>uiControl c</b> refers to the widget that is to be embedded
+into the grid-widget, so the numbers that follow afterwards are the ones
+that are important.
+
+Let's have a look at these numbers, based on the above API call, and only
+list these again, without the <b>()</b> this time, to simplify reading:
 
     # left, top, xspan, yspan, hexpand, halign, vexpand, valign
     #  0,    0,    2,     1,      0,      0,       1,      0
@@ -1844,26 +1934,27 @@ expand horizontally or vertically. halign and valign, I think,
 are used to align the grid-cell horizontally and vertically, so you
 can position them exactly in the middle.
 
-Recently (August 2021) I discovered that you can actually put 
-a button-in-a-button. I don't know whether this is a bug or
-a feature, but it is hilarious.
+Recently (in <b>August 2021</b>) I discovered that you can actually
+put a button-in-a-button. I don't know whether this is a bug or
+a feature, but it is hilarious nonetheless.
 
-The 'raw' code I used for this was the following:
+The '<b>raw</b>' code I used for this was the following:
 
-    UI.grid_append(grid, UI.new_button('3'),0,1,1,1,1,1,1,1)
-    UI.grid_append(grid, UI.new_button('4'),1,1,1,1,1,1,1,1)
-    UI.grid_append(grid, UI.new_button('5'),0,1,1,1,1,0,1,0)
-    UI.grid_append(grid, UI.new_button('6'),1,1,1,1,1,0,1,0)
+    LibUI.grid_append(grid, UI.new_button('3'),0,1,1,1,1,1,1,1)
+    LibUI.grid_append(grid, UI.new_button('4'),1,1,1,1,1,1,1,1)
+    LibUI.grid_append(grid, UI.new_button('5'),0,1,1,1,1,0,1,0)
+    LibUI.grid_append(grid, UI.new_button('6'),1,1,1,1,1,0,1,0)
 
-This led to the following image:
+This led to the following widget setup, as shown in this
+image:
 
 <img src="https://i.imgur.com/6sWwWKh.png" style="margin-left: 1em">
 
 The smaller buttons and the larger buttons can be clicked. They
-reside in the same grid-cell. I don't know whether this is a 
-bug or a feature really, but this was quite hilarious to see.
-In the event that I may forget this, I'll keep this here as
-a reference.
+reside in the same grid-cell. As stated I do not know whether this is
+a bug or a feature really, but this was quite hilarious to see.
+In the event that I may forget this, I'll keep this here as a
+<b>reference</b>.
 
 If you want to pad the grid you can use the following method:
 
@@ -1901,12 +1992,13 @@ Usage example for the new API:
       { left: 2, top: 3, xspan: 3, yspan: 3, hexpand: 0, halign: 0, vexpand: 0, valign: 0 }
     )
 
-In the closing days of <b>August 2022</b> I went on
-to improve the above. Three new methods were "added"
-to grid (actually Fiddle::Pointer, but hopefully one
-day I can find out how to work on a grid directly
-in libui; right now I seem to only have to work with
-raw pointers, which confuses me).
+This again requires more argument, but on the plus side it allows you complete
+control over each positional argument.
+
+In the closing days of <b>August 2022</b> I went on to improve the above. Three
+new methods were "added" to grid (actually Fiddle::Pointer, but hopefully one
+day I can find out how to work on a grid directly in libui; right now I seem
+to only have to work with raw pointers, which confuses me).
 
 These three methods are:
 
@@ -1998,9 +2090,10 @@ An entry can be <b>set read only</b> via:
 
     entry.read_only # This has not been added into libui-paradise yet.
 
-To <b>respond</b> to <b>on-changed events</b>, you can use:
+To <b>respond</b> to <b>on-changed events</b>, you can use the following
+toplevel API:
 
-   LibUI.entry_on_changed()
+    LibUI.entry_on_changed()
 
 A more complete example of this:
 
@@ -2029,8 +2122,43 @@ following simplified method call instead:
       puts 'The text is now: '+entry.text?
     }
 
+## Using a pop-up message box in plain libui:
+
+    LibUI.msg_box(MAIN_WINDOW, 'Information', 'You clicked the button')
+    LibUI.msg_box(main_window,
+               'Tiny Midi Player',
+               "Written in Ruby\n" \
+               "https://github.com/kojix2/libui\n Version #{VERSION}"
+    )
+
+## LibUI.attributed_string_len()
+
+The method LibUI.attributed_string_len() will return an Integer value.
+
+A usage example follows:
+
+    start_position = LibUI.attributed_string_len(self)
+
+## How to create an .exe file on Windows via libui
+
+First check: https://github.com/larsch/ocra/
+
+In order to build an .exe file with Ocra, include 3 DLLs from ruby_builtin_dlls
+folder:
+
+    ocra examples/control_gallery.rb --dll ruby_builtin_dlls/libssp-0.dll --dll ruby_builtin_dlls/libgmp-10.dll --dll ruby_builtin_dlls/libffi-7.dll --gem-all=fiddle
+
+Add additional options below if necessary.
+
+    --window
+    --add-all-core
+    --chdir-first
+    --icon assets\app.ico
+    --verbose
+    --output out\gallery.exe
+
 
-## Contact information and mandatory 2FA coming up in 2022
+## Contact information and mandatory 2FA (no longer) coming up in 2022 / 2023
 
 If your creative mind has ideas and specific suggestions to make this gem
 more useful in general, feel free to drop me an email at any time, via:
@@ -2038,35 +2166,53 @@ more useful in general, feel free to drop me an email at any time, via:
     shevy@inbox.lt
 
 Before that email I used an email account at Google gmail, but in **2021** I
-decided to slowly abandon gmail for various reasons. In order to limit this
+decided to slowly abandon gmail, for various reasons. In order to limit the
 explanation here, allow me to just briefly state that I do not feel as if I
-want to promote any Google service anymore, for various reasons.
-
-Do keep in mind that responding to emails may take some time, depending on
-the amount of work I may have at that moment.
-
-In 2022 rubygems.org decided to make 2FA mandatory for every gem owner:
-see https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
-
-As I can not use 2FA, for reasons I will skip explaining here (see
-various github issue discussions in the past), this effectively means that
-Betty Li and others who run the show at rubygems.org will perma-ban me
-from using rubygems as a developer.
-
-As I disagree with that decision completely, this will mean that all my
-gems will be removed from rubygems.org prior to that sunset date, e. g.
-before they permanently lock me out from the code that I used
-to maintain. It is pointless to want to discuss this with them anymore -
-they have made up their minds and decided that you can only use
-the code if 2FA is in place, even though the code itself works just
-fine. If you don't use 2FA you are effectively locked out from your
-own code; I consider this a malicious attack. See also how they limited
-discussions to people with mandatory 2FA on the ruby-bugtracker, thus
-banning everyone permanently without 2FA:  
-
-https://bugs.ruby-lang.org/issues/18800
-
-Guess it may indeed be time to finally abandon ruby - not because
-ruby is a bad language, but there are people now in charge who
-really should not be part of ruby in the first place.
+want to promote any Google service anymore when the user becomes the end
+product (such as via data collection by upstream services, including other
+proxy-services). My feeling is that this is a hugely flawed business model
+to begin with, and I no longer wish to support this in any way, even if
+only indirectly so, such as by using services of companies that try to
+promote this flawed model.
+
+In regards to responding to emails: please keep in mind that responding 
+may take some time, depending on the amount of work I may have at that
+moment. So it is not that emails are ignored; it is more that I have not
+(yet) found the time to read and reply. This means there may be a delay
+of days, weeks and in some instances also months. There is, unfortunately,
+not much I can do when I need to prioritise my time investment, but I try
+to consider <b>all</b> feedback as an opportunity to improve my projects
+nonetheless.
+
+In <b>2022</b> rubygems.org decided to make 2FA mandatory for every
+gem owner eventually:
+
+see
+https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+Mandatory 2FA will eventually be extended to all rubygems.org developers and
+maintainers. As I can not use 2FA, for reasons I will skip explaining here,
+this means that my projects will eventually be removed, as I no longer
+have any control over my projects hosted on rubygems.org (because I
+can not use 2FA).
+
+At that point, I no longer have any control what is done to my projects
+since whoever is controlling the gems ecosystem took away our control
+here. I am not sure at which point ruby became corporate-controlled -
+that was not the case several years ago, so something has
+changed.
+
+Ruby also only allows 2FA users to participate on the issue tracker these
+days:
+
+  https://bugs.ruby-lang.org/issues/18800
+
+But this has been reverted some months ago, so it is no longer applicable.
+Suffice to say that I do not think that we should only be allowed to
+interact on the world wide web when some 'authority' authenticated us,
+such as via mandatory 2FA, so I hope this won't come back again.
+
+Fighting spam is a noble goal, but when it also means you lock out
+real human people then this is definitely NOT a good situation
+to be had.