libui_paradise 0.2.49 → 0.3.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9528e8e24fd9d17b6b3f015f823eea8be4173db8541e2452d496ce652928b392
-  data.tar.gz: 196e18b8f4856782b94b4de7ff4befbb25d44b14d96f04f007097072cd271f32
+  metadata.gz: 9cacc003686df08d02f1de8ff360f704eae2c1b4a678bb5040ffc6e193d3e0b3
+  data.tar.gz: fd46f7096a785932ba3806ab82e31df87f902a7fa969c703542e74100710a34a
 SHA512:
-  metadata.gz: beecfb571540f75293225af134413c6e936b205fb51bdd8d55e369a5407faa5cf4397267ee835f3113cc3d9509143b25765760117eb4c7419dc37e36d313e195
-  data.tar.gz: bdd7a18479944cc4a1f5c5400b9099d3e86f802bce88f66fefec568b25775ca2e0387b071289536a9bd00a351b9b7769c138c1f1b296c98a80d640b114ae49fd
+  metadata.gz: b0940f2cc4cd87f2bb28d568ad2ee41b8f5fb552463daeeb8717487e7934beca29670296cc1fc768240da0ae89ef2e28ee16ba580c926815466cfc4c37f44336
+  data.tar.gz: 108d2613bfacb5945285f31ce6827150863bc98cd887dfe4b3b2d4174e3795fe5d4dacb416dcb1eede79498d4f34d75c7fc5cbab570fb8b12cea049551ce576f

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">12.12.2023</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">14:47:37</span> o'clock.
 
 ## The libui_paradise project
 
@@ -478,7 +478,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)
     {
@@ -518,9 +518,9 @@ 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.
     LibUI.combobox_append(alignment, 'Left')
     LibUI.combobox_append(alignment, 'Center')
     LibUI.combobox_append(alignment, 'Right')
@@ -578,6 +578,10 @@ So:
 There are probably more elegant ways to solve this, but I only
 wanted to solve this quickly and move on.
 
+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
 for UNIX/Linux, can be seen here:
 
@@ -606,21 +610,36 @@ 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:
 
-    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
+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
+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 **active**, use code such as the
 following:
 
     checkbox.is_active?
@@ -633,6 +652,19 @@ registered in a main, toplevel Hash in the
 **libui_paradise project**. 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 on-toggled events, do:
+
+    LibUI.checkbox_on_toggled(checkbox, checkbox_toggle_callback, nil)
+
 ## Adding a widget into another widget
 
 I chose the following **API** for this:
@@ -686,6 +718,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:
@@ -832,7 +878,7 @@ 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
+## Entry in libui
 
 An entry in libui may look like this:
 
@@ -844,6 +890,12 @@ The upstream C code for libui-entry, for **unix/**, can be seen here:
 
 https://github.com/andlabs/libui/blob/master/unix/entry.c
 
+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')
+
 ## Borderless windows and fullscreen windows
 
 A window that is **borderless: true** will not show any title or
@@ -857,14 +909,14 @@ To set the main window to full screen (occupy the whole monitor) do:
 
 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 +936,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,7 +955,7 @@ 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
 
@@ -911,17 +963,19 @@ 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">
 
-## 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
+LibUI.
 
-Examples:
+Examples for this:
 
     button1 = LibUI.new_button('Text')
     button2 = LibUI.new_button('▶')
+    button3 = LibUI.new_button('■') # You can use Unicode / Emojis here just fine.
 
-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 "tell" this button what to do when it is clicked.
+This is done via Libui.button_on_clicked().
 
 Example:
 
@@ -1110,27 +1164,6 @@ subsequently removed one day.
   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)
@@ -1162,19 +1195,11 @@ subsequently removed one day.
   UI.combobox_on_selected(cbox, combobox_selected_callback, nil)
 
   # Or more concise:
-  combo_box = UI.combobox {
+  combo_box = LibUI.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>
@@ -1390,9 +1415,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 +1452,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 +1591,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
@@ -1572,9 +1638,14 @@ Example for this:
     width = canvas.width
     height = canvas.height
 
-## Creating a new drawing area
+## How to to build a menu-interface (menu tag):
 
-This should suffice:
+    help_menu = LibUI.new_menu('Help')
+    version_item = LibUI.menu_append_item(help_menu, 'Version')
+
+## 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 +1653,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,7 +1678,7 @@ 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:
 
@@ -1668,7 +1746,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.
@@ -1844,26 +1922,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:
 
@@ -1998,9 +2077,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 +2109,35 @@ 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}"
+    )
+
+## 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 +2145,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.
 

data/bin/libui_message

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'libui_paradise'
+
+LibuiParadise::Extensions.message_box(text: ARGV)