libui_paradise 0.3.9 → 0.4.13

data/doc/README.gen

@@ -9,12 +9,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
@@ -150,7 +150,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.
@@ -168,7 +168,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
@@ -282,7 +282,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)
 
@@ -428,14 +429,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 ...
@@ -452,8 +458,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
@@ -461,9 +467,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):
@@ -493,6 +499,12 @@ The <b>handlerDraw() function</b> 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">
@@ -517,6 +529,7 @@ label / ui_text widget.
 To create a combo-box in vanilla libui, do this in plain ruby-libui:
 
     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')
@@ -548,11 +561,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,28 @@ To add content to an editable combobox youc an use:
 
     LibUI.append() # .append() adds the named item to the end of the EditableCombobox.
 
-The **source code** to the combo-box in libui, at the least
+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
@@ -608,7 +638,7 @@ just a stub though - we may have to research this with better examples.
 
 ## 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 = LibUI.checkbox('Checkbox')
     checkbox_toggle_callback = proc { |pointer|
@@ -625,8 +655,8 @@ 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 set such a checkbox to the checked-state (that is, as if the
-user clicked on it), use the following method, if you use the
+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)
@@ -635,8 +665,8 @@ To query its state use:
 
     checked = LibUI.checkbox_checked(pointer) == 1
 
-To <b>query</b> whether a checkbox is **active**, use code such as the
-following:
+To <b>query</b> whether a checkbox is <b>active</b>, use code such as
+the following:
 
     checkbox.is_active?
     checkbox.active?
@@ -645,7 +675,7 @@ 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:
@@ -657,23 +687,23 @@ The toggle-event for a checkbox can be triggered via:
       0
     }
 
-To respond to on-toggled events, do:
+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 << 
@@ -741,8 +771,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
@@ -791,6 +821,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
@@ -874,24 +908,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 in libui
+## 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
@@ -901,6 +949,14 @@ 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:
@@ -955,29 +1011,30 @@ In libui the general API for this is:
 
 ## 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 in general
 
-<b>LibUI.new_button</b> allows us to create a new button via
-LibUI.
+<b>LibUI.new_button</b> allows us to create a new button, via
+the LibUI gem maintained by kojix2.
 
-Examples for this:
+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
 
@@ -1123,17 +1180,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.
-
-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
@@ -1141,29 +1187,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.
 
@@ -1171,6 +1219,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
@@ -1220,17 +1272,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">
 
@@ -1537,8 +1593,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
 
@@ -1567,9 +1623,18 @@ Example for this:
 
 ## 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')
 
+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:
@@ -1611,6 +1676,19 @@ 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
@@ -1805,6 +1883,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
 
@@ -1835,10 +1914,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
@@ -1907,12 +1988,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:
 
@@ -2045,6 +2127,14 @@ following simplified method call instead:
                "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/

data/doc/todo/todo.md

@@ -1,3 +1,12 @@
+------------------------------------------------------------------------------------
+- Make sure that each component has a screenshot. It's ok to
+  re-use existing screenshots from other projects.
+  Perhaps also look at the examples again to show how this
+  can be used.
+
+  What is missing still?
+  
+  
 ------------------------------------------------------------------------------------
 - Rewrite the project from the get-go. Also integrate 
   @main_window into the main hash, rather than have it
@@ -6,11 +15,6 @@
   now we'll keep it as-is.
   As we rewrite it, improve the documentation.
 ------------------------------------------------------------------------------------
-- Make sure that each component has a screenshot. It's ok to
-  re-use existing screenshots from other projects.
-  Perhaps also look at the examples again to show how this
-  can be used.
-------------------------------------------------------------------------------------
 - Make sure the project is API compatible to glimmer-libui.
 ------------------------------------------------------------------------------------
 - Re-organize the examples, perhaps starting with another

data/lib/libui_paradise/autoinclude.rb

@@ -6,4 +6,5 @@
 # =========================================================================== #
 require 'libui_paradise/requires/require_the_libui_paradise_project.rb'
 
-include LibuiParadise::Extensions
+include LibuiParadise::BaseModule
+::LibUI.init