libui_paradise 0.1.49

data/doc/README.gen

@@ -0,0 +1,1252 @@
+GOBOLINUX_IS_GREAT
+ADD_LAST_UPDATE
+
+## The libui_paradise project
+
+<img src="https://i.imgur.com/hYf3sum.png" style="margin: 1em; padding: 8px">
+
+(This image has been partially auto-generated via **cfdg**, then modified
+by me via **gimp** and ImageMagick - the rounded borders were
+done via ImageMagick. You can re-use this image if you want 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/)
+
+The **libui_paradise project** aims to enhance the official (upstream)
+ruby-libui bindings a little bit.
+
+You can find the upstream ruby-libui bindings, maintained by **kojix2**,
+here:
+
+https://rubygems.org/gems/libui
+
+(Or visit the github page for ruby-libui here via this link:
+https://github.com/kojix2/LibUI )
+
+(Be wary of the name that I use on this page - the currently maintained gem is
+called **libui**; the older gem, which was called **libui-ruby**, is no longer
+maintained since as of **2019**. In the document here I may call kojix2' gem
+**ruby-libui**, but the official name is simply **libui**, which refers to the
+gem mentioned above: https://rubygems.org/gems/libui - I understand that I
+am using a misnomer when I refer to this as **ruby-libui**, but it helps
+me remember, so ...)
+
+Aside from this mentioned goal of **trying to enhance** the upstream ruby-bindings,
+the **libui_paradise** project also attempts to demonstrate how we could **try to
+use a DSL** to write less code in the long run; at the least less syntax.
+
+Less syntax is not automatically a win-win situation, but often it can
+be very useful.
+
+Example for this:
+
+    _ = button('Hello world!') # for libui
+
+You can use a similar variant in ruby-gtk3, for example:
+
+    _ = Gtk::Button.new('Hello world!')
+
+Or, if you want to use "toplevel-methods", like the above, identical to the
+first variant:
+
+    _ = button('Hello world!') # for ruby-gtk
+
+In fact: if you notice the above three lines of code then there is indeed no
+difference between which toolkit to use between the first variant and
+the last variant. We could then, in theory, "plug in" different toolkits,
+be it ruby-gtk, ruby-tk, ruby-libui and so forth. The **glimmer** project
+is doing this to some extent, as a general DSL wrapper over GUI-related
+functionality, including the www - see here: https://github.com/AndyObtiva/glimmer
+
+We could even extend this to the www and generate the appropriate 
+tags that way, by treating HTML tags as "objects". Note that this is
+"in theory"; in practice there are some shortcomings, or limitations,
+such as different toolkits not supporting the same widgets or
+functionality. The old ruby-qt toolkit, for example, required you to
+connect slots to signals, due to qt requiring this. I do not know if
+this is still the case or not, but back in the days this was 
+necessary and it complicated using ruby-qt a little bit.
+
+The **libui_paradise gem** here is highly experimental at this stage
+and may not work for all use cases, or may have bugs - I am still
+learning myself here. I want to see which API calls make the most sense
+in the long run, ideally even across different GUIs as well as the
+www. (For those of you who have some experience with ruby-gtk this may
+seem familiar, as pointed out above - API elements such as **.set_text()**
+or **widget1.add(widget2)**; I kind of learned GUIs first via
+**ruby-gtk**, which evidently shaped my opinion on GUI layouts
+to some extent.)
+
+The official ruby-libui project maintained by kojix2 comes with
+**13 examples** (August 2021) so far. I assume that more examples
+may be added over the coming months and years depending on use
+case, time availability, motivation and so forth. Have a look at
+the code provided on the github page to understand what is going
+on - in particular the **histogram** example is really nifty if
+you want to play around with it **interactively**. It is probably the
+best example in this regard, because it features interactive and
+dynamic use in a visual way - you can choose the colours, for
+example. A spin-button allows for visual change too, but I think 
+colours are more impressive than simple up-and-down counters.
+
+On windows this may look like so (via kotlin-libui):
+
+<img src="https://raw.githubusercontent.com/msink/kotlin-libui/master/samples/histogram/histogram-windows7.png" style="margin-left: 2em">
+
+Also check out kojix2' other examples in ruby-gtk - would be great
+if we could have the same in libui one day, but this also depends
+on what upstream libui makes available, unless it is somehow
+possible to connect multiple shared libraries into libui; then
+we could perhaps extend libui.
+
+I am trying to think about ways to simplify the code in these
+examples as well, so that we can "do more by writing less". But as
+stated before: this is all **highly experimental** and subject
+to change. I am going via slow, tiny babysteps here! Constant
+wins the race in the long run, just remember the turtle versus
+the rabbit. The rabbit always believed that he would win the
+race ...
+
+**kojix2** pointed out that a half-baked or incomplete OOP design may
+not make a lot of sense in regards to ruby-libui - we have to think a
+bit about **Fiddle::Pointer** which not everyone may have done before.
+
+Otherwise you may end up segfaulting everything all over the place
+(which I did run into already - but it is both scary and fun at the
+same time!). Subclassing is also difficult to do properly - which
+functions should be called to create a "proper" subclass? May there
+be problems as a consequence of trying this? I have no idea right
+now. This is definitely more related to the C API of ruby than
+"pure", plain ruby as such. You kind of have to understand the 
+underlying C code to some extent.
+
+I do not really know C very well; **pointers** are way above my 
+level of understanding, so **kojix2's** point is a fair one
+to make, since someone may have to maintain a growing code base -
+this may well be the case here too, so 'defensive programming'
+is a viable strategy. There are examples where one has to work
+around ruby's GC too, for instance - this all makes this a little
+bit more complicated than plain, "pure" ruby code.
+
+**However had**, at the same I still want to **experiment** and see
+what may happen with the code in general - which pitfalls may happen
+or which things could be improved upon. I think the more people use
+libui and ruby-libui, the better this may become in the long run.
+Imagine we could almost create a full desktop system based on
+libui! Even if the original scope never was aimed towards that. :D
+
+This may then be fast enough for ruby-on-the-desktop, and simple
+enough to do that, too. Right now this has too many shortcomings;
+I miss CSS styling in particular. But, in theory, we could do
+this. Anyone feels clever enough to use ruby as a desktop-UI
+language via libui? I suppose it still requires some decent
+knowledge of C ...
+
+Lots of different people could create widgets and add-ons when
+this were possible ... but I digress.
+
+**Write a GUI once, run everywhere** (well ... at the least in
+theory). This is an excellent idea, even if libui may not be
+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
+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.
+
+On Linux this is much, much easier to do ... I literally just
+compile GTK, after its dependencies are properly installed (glib,
+pango, atk, and so forth), and then the ruby bindings maintained
+largely by kou (and others), and ... it works! At the least
+on linux.
+
+(I used to be able to run ruby-gtk2 on windows in the past,
+a long time ago, using the provided binaries, but sadly upstream
+GTK developers no longer provide binaries as-is, and there are
+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,
+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
+that it makes sense to use libui and ruby-libui. The reason it
+works is because the ruby-libui gem (just called **libui**)
+bundles the respective binaries, and it is quite small. This
+would be much harder to do with ruby-gtk.
+
+Now I am trying to find more awesome examples to showcase
+what can be done. Who knows - perhaps even CSS may be supported
+one day (perhaps only on linux though, which limits the 
+benefit of it; ruby-gtk3 does allow for CSS though). A
+font example has also been provided, so we can upscale,
+downscale, use different fonts, bold, in colours and so
+on and so forth now.
+
+Check out the colours in the file **basic_draw_text.rb**,
+as courtesy provided by kojix2. That way you can style
+the content of a widget more easily - only the fiddle-protection
+against segfault parts is a bit strange, but that's a detail.
+
+There currently is quite a bit of code to make this work;
+in the long run I plan to simplify this if possible. **The
+less code we have to write, the better** - as long as the
+end code is still **readable**.
+
+Note that the subclass situation may change eventually; see
+upstream kojix2 and related discussion for fiddle. For
+the time being, though, I'll retain my old approach until
+I am sufficiently content with the project as-is. Right now
+libui_paradise has way too much undocumented and untested
+code and I still have not added all examples either (coloured
+text, for instance, still has to be added; and more image-related
+examples that are smaller). Stay tuned.
+
+## How to require the libui_paradise project
+
+In order to **require the libui_paradise project**, use
+something like the following:
+
+    require 'libui_paradise'
+
+More frequently if you look at the **examples/** subdirectory, the
+following is used instead:
+
+    require 'libui_paradise/autoinclude'
+
+Note that this particular require call does a few things automatically,
+which may not always be what you may want to use. So, again - check
+out the official ruby-libui repository first, including the examples,
+before having a look at **libui_paradise**. This project here is a
+tinker-project, very unstable, subject to change - don't use it in
+production yet.
+
+In my own projects I tend to use the above autoinclude variant
+most of the time, because that way I can write less code (omit
+a few lines).
+
+## How to get started with ruby-libui and the libui_paradise project?
+
+Well - as stated elsewhere, I first recommend to you that you look directly
+at ruby-libui provided by kojix2, in particular the examples that he 
+distributes in the gem. Work through the examples step-by-step, possibly
+starting with the smallest example, see whether they work (they do,
+or should) and have a look at how things work - just to get an
+overview.
+
+Have a look at the code as well, in order to understand how it
+works roughly; after some minutes or perhaps a very few hours of tinker-time
+you should understand quite a bit already, if you already know ruby. Even
+more so if you did work with GUIs before, including GUIs via a www-interface.
+
+Then you are recommended to look at the libui_paradise project and look to 
+see what has been added on top of what kojix2 provides. Look at the examples 
+of the libui_paradise project as well (they are a bit simplified compared
+to the upstream examples; unfortunately a few of them currently do not 
+work), then consider using **libui_paradise/prototype/prototype.rb** in
+particular. Copy it and adjust it to your project and use case, as-is. You
+may want to remove the grid that is inside there and use a hbox or a vbox
+instead, or a padded_hbox and padded_vbox. It's all quite simple actually
+once you understand the basic API: windows, widgets, buttons, entries.
+
+For example, a button can be added in this way to a vbox, if you use
+the libui_paradise gem:
+
+    outer_vbox = padded_vbox # padded means that it will have some padding to the sides
+    button = ui_button('Hello world!') # You can drop the ui_ prefix if you'd like to
+    button.on_clicked {
+      puts 'Hello world!'
+    }
+    outer_vbox.minimal(button) # Use minimal space if possible. Or use .add().
+
+That's it! Inside of the **.on_clicked {}** block you can run the ruby code
+that you want to use. A button that is in a container (such as **vbox**) that
+outputs hello world when clicked. Can't get much simpler than that. \o/
+
+You can omit the **ui_** part above. I just use it to point out the difference;
+and because I'd otherwise may have to use "button = button" aka "button = button()"
+which may be confusing, so I use **ui_button()** instead.
+
+## Fiddle::Pointer and playing with pointers
+
+The **ruby-libui bindings** make use of **Fiddle::Pointer** a lot -
+see the file called **ffi.rb** in the ruby-libui gem ("gem install libui").
+It's like **magic** to me - scary and awesome at the same time.
+
+As a consequence the libui_paradise project has to 'handle' pointers
+as well, indirectly so, via whatever ruby-libui makes available.
+
+I decided that, at the least for the time being, we will add
+**ad-hoc code** straight to Fiddle::Pointer. This is not the
+optimal solution and I do not recommend doing so, even more so as 
+we modify Fiddle::Pointer directly which I don't think is a good
+idea; it may be better to have some proper data structures and
+perhaps **subclass** from Fiddle::Pointer instead, and then modify
+that subclass instead. That may be better. But for the time being,
+the code here will remain as it is, until we can come up with
+better ways to deal with the situation. For now **simplicity**
+rules.
+
+Some of the examples used require assigment to local variables
+to avoid the GC to kick in and cause the program to end. This
+is presently not very elegant - see a discussion between kojix2
+and kou to improve on this part. For the time being, though,
+some of the examples require 'boilerplate' assignment to 
+variabless. Stay tuned for improvements in this regard; ideally
+we can use libui without having to play with pointers ever.
+
+## Constraints of the libui_paradise gem
+
+The libui_paradise gem comes with some **constraints**.
+
+For example, many of the ad-hoc methods on **Fiddle::Pointer**
+will only work after you called e. g. **ui_vbox** or a 
+similar constructor where we registered which widgets are
+created (aka the **new_** methods that are available on
+the **LibUI** 'namespace'). Only when this has happened
+will that widget become registered in the main Hash.
+
+That then means, logically, that if you use a method such as:
+
+    check_button = ui_check_button
+    check_button.is_active?
+
+This will only work if that widget was created already prior
+to that "method call".
+
+What this means in practice is that it is best if you
+**create all the skeleton** (the **basic UI elements**) **before**
+calling any other code, including on-clicked or on-toggle
+events. Otherwise you may find nil values and don't
+know why that is the case so. If this seems too complicated
+for you, don't worry - the examples distributed via the
+libui_paradise gem should work fine (except two buggy ones), so
+the point of this subsection here is to keep your attention to
+the fact that, as of right now, if you use libui_paradise, the
+**proper-order-of-elements is important**. Ideally create all
+the widgets first, before you add additional functionality to them.
+
+This is admittedly not a very elegant limitation right
+now, and one day this restrictions may be removed or
+lifted - but for now, it is a limitation that requires
+a tiny bit of discipline to work around, for the time being.
+So, again - it is best to split up the skeleton UI from
+the function.
+
+## How to use an 'Open File' button
+
+I came up with the following solution for now:
+
+    outer_vbox = padded_vbox
+    button_open_file = button('Open file')
+    button_open_file.on_clicked {
+      filename = open_file(window).to_s # This is the part that will open a local file.
+    }
+    outer_vbox << button_open_file # Add the button to the outer-vbox.
+
+Calling the **.to_s** method on the Fiddle::Pointer yields the actual
+filename. You can then add more code to deal with this.
+
+**window** above refers to the **main_window**. See the example
+**019_open_file_button_example.rb** for how this actually works.
+
+In the future this may be even further simplified a little, as
+opening local files is a very common task in most GUIs. A
+single method probably should suffice for using such a
+specialized button.
+
+## How to quit from a ruby-libui widget
+
+I found that:
+
+    UI.quit
+
+Works best overall. And seems to suffice as well.
+
+There are some other calls, such as destroy-control and similar
+actions, which are probably clean-up related - but by and large
+**UI.quit** seems to be the main part how to exit from a
+libui-application.
+
+I document this here in the event that I forget it in a few
+months.
+
+If you use the libui_paradise gem then you can use the
+following method to use a quit button:
+
+    a_quit_button = ui_quit_button
+
+If you want another textual description then you can do the
+following:
+
+    a_quit_button = ui_quit_button(text: 'Open a local file') # That text description would be confusing though
+    a_quit_button = ui_quit_button(text: 'Exit the application') # Much better now! \o/
+
+## UI.new_button()
+
+UI.new_button allows us to create a new button.
+
+Examples:
+
+    button1 = UI.new_button('Text')
+    button2 = UI.new_button('▶')
+  
+## 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
+but also has methods that allow 'OOP behaviour'. Has anyone tried
+this yet? I am scared to try considering I already got segfaults ...
+
+Eventually I may figure this out - or someone else with more knowledge
+will make this available. We can probably 'fake' subclassing to
+a pointer somehow ... after all ruby internally has to figure it
+out as well and probably did so already, on the C-level side.
+
+## Quickly adding text to a widget
+
+You can use something like this:
+
+    outer_vbox = ui_vbox
+    outer_vbox.text(
+      'This widget can be used to do xyz.'
+    )
+
+Again - this modifies **Fiddle::Pointer** so be wary. The second
+argument is the default one for use in a label / ui_text widget.
+
+## Working with combo-boxes
+
+To create a combo-box, do:
+
+    combo_box = ui_combo_box
+
+You can fill it with an array of entries **on creation-time** via:
+
+    combo_box = ui_combo_box([1,2,3,4])
+
+This will also focus on the very first element when doing so.
+
+If you need to do so manually, and focus on another element,
+you can use the following toplevel method:
+
+    UI.combobox_set_selected()
+
+To query the currently selected value, use:
+
+    UI.combobox_selected(pointer)
+
+This is usually done via a **proc {}** object. See kojix2' examples.
+
+In LibuiParadise a few custom methods were added, such as 
+**.ui_sync_connect()**. This method was added to connect a
+combo-box to a entry and automatically sync that entry whenever
+the combo box is changed. See the example **007_combo_box_example.rb**
+for how this works.
+
+The **source code** 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 
+
+## Error messages and ui_error_message
+
+In LibUI respectively ruby-libui you can display error messages
+via a popup window.
+
+The API is something like this:
+
+    UI.msg_box(main_window, 'Information', 'You clicked the button')
+    UI.msg_box_error(main_window, 'Information', 'You clicked the button')
+
+The first line shows a normal message box; the second line shows how to
+use a message box specifically 'adapted' for displaying errors to the
+end user.
+
+LibuiParadise makes this available via **ui_msg_box** and **ui_msg_box_error**
+respectively.
+
+## Libui Form
+
+**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
+
+A simple checkbox example in **plain** 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})")
+    }
+
+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:
+
+    checkbox.is_active?
+    checkbox.active?
+
+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
+it works (for the most part).
+
+## Adding a widget into another widget
+
+I chose the following **API** 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 ... :-)
+
+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.
+
+(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 << 
+box3 versus box1.add(box2).add(box3) - the latter is a bit more
+resilient syntax-wise.)
+
+As stated, **<<** was added as an alias to **.add()** but I am not yet sure
+if this is a very good idea. It's super-nifty to use << everywhere, but it
+also changes the syntax of the whole .rb file ... on the other hand, using
+<< is easier than .add() so ... I'll go with that as well. Remember
+there is more than one way to do something in ruby - you need to 
+select the variant(s) that work best for you and possibly ignore the
+other variants.
+
+Since a while the above can be simplified a bit, as will be shown
+next.
+
+Rather than use:
+
+    box1.add(box2, 1)
+
+You can now do this instead:
+
+    box1.maximal(box2)
+
+This is a tiny bit longer, but you can omit the ", 1" part, which is
+nice. The alternative is .minimal(), which defaults to:
+
+    add(second_widget, 0)
+
+So the only difference between .maximal() and .minimal() will be
+whether you pass 0 or 1 to the method. See the upstream libui
+API to understand the difference.
+
+## Libui Tabs
+
+The notebook-tab may look like this:
+
+<img src="https://i.imgur.com/olWQAIJ.png" style="margin-left: 2em">
+
+## Create a vertical box:
+
+Use code like this:
+
+    vbox = UI.new_vertical_box
+
+If you use the libui_paradise gem, you can use this:
+
+    vbox = ui_vbox # or
+    vbox = padded_vbox
+
+## Adding a horizontal separator
+
+The method **UI.new_horizontal_separator** can be used to add (or rather
+first create) a horizontal separator.
+
+You can then add it via .add() or << if you use the libui_paradise
+project. Alternatively you can use the toplevel method provided by
+ruby-libui, since that is what the libui_paradise project is doing anyway.
+
+To simplify this further, you can do something like this:
+
+    outer_vbox = ui_vbox # I call the most-outer vbox usually outer-vbox
+    outer_vbox.add_hsep
+    # outer_vbox.add_horizontal_separator # Or this variant if you prefer some verbosity instead.
+
+Or, perhaps better, use a padded vbox:
+
+    outer_vbox = padded_vbox # note that "ui_" is not used here
+    outer_vbox.add_hsep
+
+I needed this functionality to quickly add horizontal separators for some
+visual cue in the **User Interface**. Using **.add_hsep** is very
+convenient and fast to write/type. If you want more verbosity then remember
+that you can always use the upstream API as-is.
+
+## Entries in LibUI (ui_entry)
+
+The official source for an ui_entry for Unix (including Linux) can be read
+here:
+
+https://github.com/andlabs/libui/blob/master/unix/entry.c
+
+Personally I tend to create a new entry element in this way:
+
+    entry = ui_entry
+
+To set new content to it, do:
+
+    entry.set_text('foobar') # Make sure it is a String; that seems to work better.
+
+To respond to events look at **OnChanged**.
+
+It can be set read only via:
+
+    entry.read_only # This has not been added into libui-paradise yet.
+
+To respond to on-changed events, you can use:
+
+   UI.entry_on_changed()
+
+Complete example:
+
+    text_changed_callback = proc { |ptr|
+      puts "Current textbox data: '#{UI.entry_text(ptr)}'"
+    }
+
+    text_entry = ui_entry
+    text_entry.set_text('Please enter a command')
+    text_entry.on_changed {
+      text_changed_callback
+    }
+
+The Proc object has to be passed into the {} block variation.
+
+The latter uses:
+
+    UI.entry_on_changed(text_entry, text_changed_callback, nil)
+
+## Grids in LibUI
+
+The API is quite complex and hard to remember:
+
+    UI.grid_append(grid, entry1, 0, 0, 2, 1, 0, 0, 1, 0)
+
+Who can remember offhand what these values mean?
+
+The upstream struct is this:
+
+    struct gridChild {
+	    uiControl *c;
+	    int left;
+	    int top;
+	    int xspan;
+	    int yspan;
+	    int hexpand;
+	    uiAlign halign;
+	    int vexpand;
+	    uiAlign valign;
+
+	    // have these here so they don't need to be reallocated each relayout
+	    int finalx, finaly;
+	    int finalwidth, finalheight;
+	    int minwidth, minheight;
+    };
+
+The documentation for Go has this signature:
+
+    func (g *Grid) Append(child Control, left, top int, xspan, yspan int, hexpand bool, halign Align, vexpand bool, valign Align)
+
+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 **()**:
+
+    # left, top, xspan, yspan, hexpand, halign, vexpand, valign
+    #  0,    0,    2,     1,      0,      0,       1,      0
+
+xspan and yspan refer to width; left and top refer to the position
+in the grid. hexpand and vexpand means whether the grid-cell will
+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.
+
+The 'raw' 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)
+
+This led to the following 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.
+
+## Margins in LibUI
+
+The **margin** property specifies if the window content should have a
+margin or not. The default value is false, meaning that there will
+be no margin.
+
+In order to understand the difference, a visual image may be
+best - the first image that is shown next shows **no margin**,
+whereas the second image **shows** a margin.
+
+<img src="https://cloud.githubusercontent.com/assets/11197111/16465935/804a30d4-3e41-11e6-8189-150e8cddc152.png" style="margin-left: 2em"><br>
+<img src="https://cloud.githubusercontent.com/assets/11197111/16465906/68304cfe-3e41-11e6-8ae0-3123205ee136.png" style="margin-left: 2em"><br>
+
+Note that the API name is **margined** rather than **margin** - 
+got me a little while to get used to that name.
+
+The API in Go is: __func (*Group) SetMargined__ respectively
+__func (g *Group) SetMargined(margined bool)__. When **true**
+then the group has margins around the child widgets, as mentioned
+already.
+
+The **size** of the margins in use, is, unfortunately, determined
+automatically by the OS - we currently (2021) do not have control
+over the size of the margin at hand via **libui**.
+
+Code examples for 'raw' **ruby-libui** are these:
+
+    UI.window_set_margined(MAIN_WINDOW, 1)
+    UI.group_set_margined(group, 1)
+
+Because I prefer calling methods on objects, I added this instead:
+
+    MAIN_WINDOW.is_margined
+    MAIN_WINDOW.uses_a_margin # Or this variant.
+
+Note that we are here faking method-calls on a Fiddle::Pointer, but
+if we don't pay attention then it looks like **OOP**! If it walks
+like a duck, quacks like a duck then ... it may be a
+**Fiddle::Pointer:Duck**!!!
+
+## Entry
+
+An entry can be set read only (readOnly: Boolean, aka true or false).
+
+An entry in libui may look like this:
+
+<img src="https://raw.githubusercontent.com/parro-it/libui-node/master/docs/media/UiEntry.png" style="margin-left:1em">
+
+## Borderless windows
+
+A window that is **borderless: true** will not show any title or
+outside frame. This may be useful for games and what not.
+
+## Spinbutton / Spinbox
+
+You can use:
+
+    UI.new_spinbox
+
+To create a new spinbox.
+
+To specify the min and max range, pass them as parameters:
+
+    UI.new_spinbox(0, 100)
+
+If you use the extensions then you can do this instead:
+
+    ui_spinbox
+    spinbox # this is the simplest variant
+
+You should be able to set a value via set_value but I have
+not yet added an example for this.
+
+Relevant methods are:
+
+    UI.spinbox_on_changed()
+    UI.spinbox_set_value()
+    UI.spinbox_value() 
+
+To set a value:
+
+    spinbox.set_value(42)
+    spinbox.value = 42 # this works as well
+
+## Create a text-view widget
+
+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
+
+## Control Gallery
+
+Here is an image, from kotlin-libui, 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">
+
+## Enabling / Disabling buttons in libui
+
+This is, assumingly, already possible via:
+
+    libui/ui.h
+
+    Lines 105 to 107 in a0a9807
+     _UI_EXTERN int uiControlEnabled(uiControl *); 
+     _UI_EXTERN void uiControlEnable(uiControl *); 
+     _UI_EXTERN void uiControlDisable(uiControl *); 
+
+In ruby-libui this should be possible via:
+
+    LibUI.control_enable()
+    UI.control_enable()
+
+    LibUI.control_disable()
+    UI.control_disable()
+
+See the example **029_two_buttons_showing_how_to_enable_and_disable_them.rb**
+in how this works.
+
+## libui and ruby-libui internals
+
+This is an incomplete subsection. I know almost nothing at all about
+C; kojix2 knows more, so I refer you to the homepage of ruby-libui
+respectively.
+
+Most of the code for ruby-libui resides under **ffi.rb**. In August 2021
+this file contains almost 1000 lines, including newlines. Still quite
+some code. If you want to look at the raw content, have a look at
+the following link for **ffi.rb**:
+
+https://raw.githubusercontent.com/kojix2/LibUI/main/lib/libui/ffi.rb
+
+The two most important components there, as far as I understand it,
+are **try_extern** and **structs**.
+
+For instance:
+
+    try_extern 'void uiOnShouldQuit(int (*f)(void *data), void *data)'
+
+    Control = struct [
+
+I assume that any support made available for ruby **must** have a
+corresponding entry in **ffi.rb**. At the least this is how I
+understood it.
+
+If it is not in **ffi.rb** then support for that was not (yet) added.
+
+Individual enum entries can also be seen. For instance, for font-related
+data the following attributes are in use: 
+
+    AttributeTypeFamily         = 0
+    AttributeTypeSize           = 1
+    AttributeTypeWeight         = 2
+    AttributeTypeItalic         = 3
+    AttributeTypeStretch        = 4
+    AttributeTypeColor          = 5
+    AttributeTypeBackground     = 6
+    AttributeTypeUnderline      = 7
+    AttributeTypeUnderlineColor = 8
+    AttributeTypeFeatures       = 9
+
+You can probably use the rubygems features of comparing old gem 
+releases with one another to see which support has been added to
+ruby-libui over the past months or so. Most work was probably done
+in 2020 or even before that (there are some older ruby bindings
+to libui, but these work differently as kojix2 explained).
+
+## Limitations of/in LibUI
+
+LibUI is not perfect - it is missing many things that should work just fine
+on the main operating systems. On top of that I'd love to support specific
+features on a given operating system even if it is NOT cross-platform. But
+this is not possible via LibUI.
+
+The following subsection mentions a few constraints of LibUI in varying 
+degrees of complexity/importance:
+
+- No CSS support. I miss this. On ruby-gtk3 this is possible. In LibUI I can't.
+- Unable to set different fonts for an application other than using FontButton.
+
+## Structure of the project
+
+In **September 2021** the libui_paradise project was re-arranged slightly. There
+is now a dedicated **libui_classes/** directory that "simulates" separate classes.
+For example, libui_button now resides in **button.rb**. I use the same directory
+layout in the **gtk_paradise** gem and I think it makes a lot of sense - at the
+least I can quickly find the code that I may want to modify or extend. If I
+want to extend buttons, then I modify **buttons.rb**. That's simple, right?
+
+Another reason why the project was re-structured was so that we can use a
+**unified DSL** for the GUI elements in the long run.
+
+For example, code such as the following:
+
+    _ = button
+    _.on_clicked {
+      puts 'Hello world!'
+    }
+
+Should work on ruby-gtk3, libui and all the other toolkits one day - even on
+the www. But the different toolkits do not implement the same functionality.
+Libui only offers a reduced functionality, for instance. Thus, the DSL that
+we may then use **can only support a subset of functionality**, whereas other
+toolkits are more useful in this regard. This was an additional reason why files
+such as button.rb were created - it makes it easier to know which functionality
+has to be changed in order for libui_paradise to enable such a unified
+DSL approach. This currently does not yet work fine in 2021, but one day it
+should work just fine.
+
+Note that the older l**ibui_paradise gem** will be made available at the
+least for three months (so until end of December 2021 at the least). It used
+a different directory layout.
+
+You may ask why the main module is called **LibuiParadise::Extensions**.
+Why not modify LibUI directly? After all the gtk_paradise gem does the
+same, by modifying **module Gtk** directly.
+
+That is a good question, and the main reason for this is because I was
+not sure whether I can actually get away with modifying the LibUI
+namespace directly. Fiddle::Pointer still scares me, so I am experimenting.
+
+For now I thought it best to create a separate module, that is then included
+and modified - see the **included hook** that is presently used. This seems
+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.
+
+EMBED_THIS_FILE /home/x/programming/ruby/src/libui_paradise/doc/SNIPPETS.md
+
+--------------------------------------------------------------------------------
+
+## Advantages and Disadvantages of the libui project
+
+It would be unfair to only selectively name advantages but not talk about
+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:
+
+- Works on windows out-of-the-box after you installed the libui-gem.
+- 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.
+- Works cross-platform.
+
+(b) Disadvantage:
+
+- 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.
+- No way to use different fonts in the same application and choosing a font
+is needlessly complicated.
+
+Some more disadvantages relate to Fiddle::Pointer. 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.
+
+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.
+
+## LibuiParadise.parse_this_config_file()
+
+This method can be used to parse a .config file. This file should
+describe the main window, such as:
+
+     width:                                      1000
+     height:                                      150
+     title:                 Parse Config File Example
+
+I have been using this in gtk_paradise and I think it may be convenient
+if you create lots of small windows and widgets that you don't want
+to hardcode values for directly into the .rb file at hand.
+
+To create a toplevel window from this use code such as the following:
+
+    use_this_config_file = '023_parse_config_file_example.config'
+    window = LibuiParadise.parse_this_config_file(use_this_config_file)
+
+In fact, the example **023_parse_config_file_example.rb** shows how
+this is used. The width of the main window will be 1000 and the
+height only 150.
+
+This functionality may be extended in the future. For example, we
+could enable to automatically parse such a .config file if it 
+exists, thus not even requiring that method call in the future.
+
+For now, though, you have to explicitely use that method if you
+want to instantiate such a window from a .config file. It will
+be evaluated at a later time (past September 2021) how useful this
+really is.
+
+## Width and Height of the main window
+
+Different computers have different display values (their monitor).
+
+I use a wide-screen LCD monitor, but I also have smaller laptops,
+and I want libui to work there just as well.
+
+The following API can be used to set the width and height of the
+main window:
+
+    set_height()
+    set_width()
+
+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).
+
+The following example shows how to use a percentage value:
+
+    set_height('80%')
+
+## Coloured Text
+
+At this point I only show how this may look on Win7, re-using
+the picture the kotlin-libui developers made available:
+
+<img src="https://raw.githubusercontent.com/msink/kotlin-libui/master/samples/drawtext/drawtext-windows7.png" style="margin-left: 2em">
+
+Doesn't look that bad, right? May not be the prettiest GUI of all
+times, but it is functional - and simple.
+
+## Status of the libui_paradise project
+
+I am still, as of 2021, experimenting somewhat randomly. While I intend to
+improve libui_paradise, it is a hobby project that is not as important
+as, say, the gtk_paradise project (which contains custom ruby-gtk
+related addons; ruby-gtk has a LOT more functionality than libui has).
+
+I can not promise to work reliably on libui_paradise, but every now and
+then, say every some weeks, I will try to add more code to it, in 
+particular examples and documentation. However had, keep in mind that
+the project is not one of my most important projects, so it may not
+receive as many updates as other projects. See also the next subsection,
+the "Todo List".
+
+## DSLs for libui (in ruby)
+
+kojix2 pointed out that glimmer has support for libui; check it out
+here:
+
+https://github.com/AndyObtiva/glimmer-dsl-libui
+
+libui_paradise will support the same syntax (in the long run) as
+glimmer does, either directly, or via a module and a way to
+require it specifically. But stay tuned for this - right now as
+of late 2021 this is not yet guaranteed. (If anyone needs quick
+API changes, let me know and I'll change libui_paradise. Other
+than that, the libui_paradise project is in a slow maintenance
+mode right now, so again, stay tuned. \o/ )
+
+## Todo List and Goals related to libui
+
+Here I will list some todo entries and related goals for libui or the
+libui_paradise gem - if anyone finds out how to solve some of these
+limitations, you are welcome to share!
+
+- Add more small, **standalone examples** showcasing how to use (and
+combine) different functionality, in particular colourized text and use
+of (embedded) images if applicable. Ideally we should be able to combine
+both freely, if possible.
+
+- Find out how to create "proper" subclasses to Fiddle::Pointer, simulating
+a subclass to it.
+
+- Find out how halign and valign work in Libui-Grid. Somehow I can not easily reposition it ...
+or perhaps I have been able to, and just have not noticed this (may have to embed one
+widget in another widget in order for this to come into effect)
+
+- Find out how to do ad-hoc calls on linux to gtk, so that we can use CSS.
+Perhaps some extension mechanism could be used, similar to how ffi works
+in general. Unfortunately this probably requires knowledge of C, so this
+is an obstacle for me. I should have learned C before ruby ... :P
+
+- Get more people to learn about libui and use them in their projects,
+in particular for simple applications. I think this is the most important
+goal: we need more people to learn about libui and begin to use it. 
+Contribute to upstream as well. If we have a sufficiently large user
+base then it should be easier to add new possibilities onto libui,
+which in turn will "cascade" downwards to all the other bindings 
+to libui, be it in kotlin, python, ruby and so forth.
+
+## DateTime Widget
+
+Only an image is shown how it may look on windows:
+
+<img src="https://raw.githubusercontent.com/msink/kotlin-libui/master/samples/datetime/datetime-windows7.png" style="margin-left: 2em">
+
+## Password entries in LibUI
+
+If you use the libui_paradise gem then you can create a new password entry
+in using any of the following variants:
+
+    entry = ui_password_entry
+    entry = password_entry
+
+For "raw" libui, use this:
+
+    LibUI.new_password_entry
+
+## Progress Bars in LibUI
+
+Here an image how this may look:
+
+<img src="https://i.imgur.com/i1i4ppZ.png" style="margin-left: 2em">
+
+## Tables in LibUI
+
+You may be able to create a new table via:
+
+    table = LibUI.new_table
+    
+    model = LibUI.new_table_model(model_handler)
+
+    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)
+
+The table header is an array that contains the following attributes:
+
+    1. editable, bool type, the column is whether 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.
+
+In the end, this is possible though:
+
+<img src="https://raw.githubusercontent.com/msink/kotlin-libui/master/samples/table/table-windows7.png" style="margin-left: 2em">
+
+## Form example in LibuiParadise
+
+Inspired by **glimmer-libui**, I ported the form example, into
+**027_form_example.rb**. Unfortunately it does not look 
+as good as it does in **glimmer-libui**, and the code I use for
+it is too verbose right now.
+
+Still, if you are curious, this is how it looks on icewm
+in October 2021:
+
+<img src="https://i.imgur.com/FkU6aWd.png" style="margin-left: 2em">
+
+I may improve this eventually a bit, so that the alignment looks
+as good as it does on glimmer-dsl; the code of 27_form_example.rb
+may also be cleaned up in the future (the glimmer-libui code 
+looks better). But for now this is how it is; Andy is very
+actively improving **glimmer-libui** right now.
+
+Available "new"-widgets in LibUI:
+
+    LibUI.new_area
+    LibUI.new_attributed_string
+    LibUI.new_group
+    LibUI.new_spinbox
+    LibUI.new_stretch_attribute
+    LibUI.new_background_attribute
+    LibUI.new_button                               # this is a simple button
+    LibUI.new_checkbox                             # this is a simple checkbox
+    LibUI.new_color_attribute
+    LibUI.new_color_button
+    LibUI.new_combobox                             # this is a combobox
+    LibUI.new_date_picker
+    LibUI.new_date_time_picker
+    LibUI.new_editable_combobox
+    LibUI.new_grid
+    LibUI.new_horizontal_box
+    LibUI.new_horizontal_separator                 # this is a simple horizontal separator
+    LibUI.new_image                                # this is a simple image
+    LibUI.new_italic_attribute                     # this is basically italic font-style
+    LibUI.new_label
+    LibUI.new_tab
+    LibUI.new_table                                # this is a simple table
+    LibUI.new_table_model
+    LibUI.new_table_value_image
+    LibUI.new_table_value_int
+    LibUI.new_table_value_color
+    LibUI.new_table_value_string
+    LibUI.new_time_picker
+    LibUI.new_menu
+    LibUI.new_multiline_entry                      # this is a textview
+    LibUI.new_non_wrapping_multiline_entry
+    LibUI.new_open_type_features
+    LibUI.new_password_entry
+    LibUI.new_underline_attribute
+    LibUI.new_entry
+    LibUI.new_progress_bar                         # this is a progress_bar
+    LibUI.new_underline_color_attribute
+    LibUI.new_family_attribute
+    LibUI.new_radio_buttons
+    LibUI.new_vertical_box
+    LibUI.new_features_attribute
+    LibUI.new_scrolling_area                       # this is a scrolling area
+    LibUI.new_vertical_separator
+    LibUI.new_font_button
+    LibUI.new_search_entry                         # this is a search entry
+    LibUI.new_weight_attribute
+    LibUI.new_form                                 # this is a form
+    LibUI.new_size_attribute
+    LibUI.new_window
+    LibUI.new_slider
+
+## Links related to libui or libui-based projects
+
+This subsection may contain a few links, in the event that other
+people want to see useful entries.
+
+I will try to explain what is to be seen by these various pages.
+
+(1) https://wiki.call-cc.org/eggref/4/libui
+
+This is using chicken-egg scheme for bindings to libui. I like the
+simplicity and overview - it's really nice to read and use. I'd
+wish we would have this for ruby too. :)
+
+Note that the documentation is outdated as of 2021, though. A fate
+shared with a lot of documentation in general out there ...
+
+(2) https://pkg.go.dev/github.com/andlabs/ui
+
+This is andlabs' documentation for libui, from the point of view of
+**Go**. It is probably the biggest, most complete documentation for
+libui. While it is specific to Go, as it was written by the same
+author you can expect the documentation to be quite decent.
+
+(Note that some other bindings contain good documentation too,
+such as kotlin libui bindings and others.)
+
+(3) http://api.call-cc.org/4/doc/libui
+
+Similar to the first one, but uses a different layout, which
+may be helpful.
+
+ADD_CONTACT_INFORMATION