libui_paradise 0.2.49 → 0.3.9

data/doc/README.gen

@@ -1,5 +1,4 @@
-GOBOLINUX_IS_GREAT
-ADD_LAST_UPDATE
+DEFAULT_HEADER
 
 ## The libui_paradise project
 
@@ -475,7 +474,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)
     {
@@ -515,9 +514,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')
@@ -575,6 +574,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:
 
@@ -603,21 +606,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?
@@ -630,6 +648,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:
@@ -683,6 +714,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:
@@ -829,7 +874,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:
 
@@ -841,6 +886,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
@@ -854,14 +905,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:
@@ -881,9 +932,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:
 
@@ -900,7 +951,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
 
@@ -908,17 +959,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:
 
@@ -1289,9 +1342,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';
@@ -1326,26 +1379,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:
 
@@ -1424,7 +1518,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
@@ -1471,9 +1565,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
@@ -1481,12 +1580,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
@@ -1499,7 +1605,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:
 
@@ -1567,7 +1673,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.
@@ -1743,26 +1849,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:
 
@@ -1897,9 +2004,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:
 
@@ -1928,4 +2036,31 @@ 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
+
 ADD_CONTACT_INFORMATION

data/doc/SNIPPETS.md

@@ -26,27 +26,6 @@
   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)
@@ -78,17 +57,9 @@
   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')
 

data/doc/todo/todo.md

@@ -1,16 +1,21 @@
-- Make sure that each component has a screenshot. It's ok to
-  re-use existing screenshots from other projects.
-
-- Make sure the project is API compatible to glimmer-libui.
-
+------------------------------------------------------------------------------------
 - Rewrite the project from the get-go. Also integrate 
   @main_window into the main hash, rather than have it
   standalone. ^^^ this should be fixed ASAP - it is not
   elegant to have a separate @main_window ... but for
   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
   one.
-
+------------------------------------------------------------------------------------
 - Check for image and font support again. Something isn't
-  working!
+  working there!
+------------------------------------------------------------------------------------

data/lib/libui_paradise/base/base.rb

@@ -3,6 +3,11 @@
 # frozen_string_literal: true
 # =========================================================================== #
 # === LibuiParadise::Base
+#
+# Usage example:
+#
+#   LibuiParadise::Base.new(ARGV)
+#
 # =========================================================================== #
 # require 'libui_paradise/base/base.rb'
 # < LibuiParadise::Base
@@ -13,7 +18,7 @@ class Base # === LibuiParadise::Base
 
   alias e puts
 
-  require 'libui_paradise'
+  require 'libui_paradise/extensions/extensions.rb'
   include LibuiParadise::Extensions
 
   # ========================================================================= #
@@ -23,28 +28,15 @@ class Base # === LibuiParadise::Base
 
   # ========================================================================= #
   # === WIDTH
+  #
+  # The default width.
   # ========================================================================= #
-  WIDTH  = 800
+  WIDTH  = 880
 
   # ========================================================================= #
   # === HEIGHT
   # ========================================================================= #
-  HEIGHT = 640
-
-  # ========================================================================= #
-  # === default_title_width_height
-  # ========================================================================= #
-  def default_title_width_height(
-      title  = TITLE,
-      width  = WIDTH,
-      height = HEIGHT
-    )
-    title_width_height(
-      title,
-      width,
-      height
-    )
-  end
+  HEIGHT = 680
 
   # ========================================================================= #
   # === reset                                                     (reset tag)
@@ -79,13 +71,28 @@ class Base # === LibuiParadise::Base
     return ui_padded_main_window(title, width, height, 0)
   end
 
-  # ======================================================================= #
+  # ========================================================================= #
   # === set_window
   #
   # Simply assign to @window here.
-  # ======================================================================= #
+  # ========================================================================= #
   def set_window(i = return_default_window)
-    @window = i
+    ::LibuiParadise::Extensions.set_window(i)
+  end
+
+  # ========================================================================= #
+  # === default_title_width_height
+  # ========================================================================= #
+  def default_title_width_height(
+      title  = TITLE,
+      width  = WIDTH,
+      height = HEIGHT
+    )
+    title_width_height(
+      title,
+      width,
+      height
+    )
   end
 
   # ========================================================================= #
@@ -125,7 +132,7 @@ class Base # === LibuiParadise::Base
       end
       outer_vbox.minimal(this_widget)
     }
-    @window.add(outer_vbox)
+    window?.add(outer_vbox)
     if i.size > 0
       Thread.new {
         sleep 5
@@ -134,9 +141,16 @@ class Base # === LibuiParadise::Base
         exit
       }
     end
-    @window.intelligent_exit
+    window?.intelligent_exit
   end; alias add_these_widgets add_these_widgets_to_the_main_window # === add_these_widgets
 
+  # ========================================================================= #
+  # === window?
+  # ========================================================================= #
+  def window?
+    ::LibuiParadise::Extensions.window?
+  end; alias main_window? window? # === main_window?
+
   # ========================================================================= #
   # === run_in_the_background
   # ========================================================================= #
@@ -145,10 +159,35 @@ class Base # === LibuiParadise::Base
   end
 
   # ========================================================================= #
-  # === run
+  # === run                                                         (run tag)
   # ========================================================================= #
   def run
     create_skeleton_then_connect_skeleton
   end
 
-end; end
+  # ========================================================================= #
+  # === create_table
+  # ========================================================================= #
+  def create_table(model)
+    LibuiParadise::Extensions.table(model)
+  end
+
+  # ========================================================================= #
+  # === free_table_model
+  # ========================================================================= #
+  def free_table_model(model)
+    ::LibUI.free_table_model(model)
+  end
+
+  # ========================================================================= #
+  # === LibuiParadise::Base[]
+  # ========================================================================= #
+  def self.[](i = ARGV)
+    new(i)
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  LibuiParadise::Base.new(ARGV)
+end # base.rb

data/lib/libui_paradise/colours/colours.rb

@@ -8,7 +8,19 @@ module LibuiParadise
 
   # ========================================================================= #
   # === COLOR_BLUE
+  #
+  # This is actually dodgerblue.
   # ========================================================================= #
   COLOR_BLUE = 0x1E90FF
 
+  # ========================================================================= #
+  # === COLOR_MIDNIGHTBLUE
+  # ========================================================================= #
+  COLOR_MIDNIGHTBLUE = 0x191970
+
+  # ========================================================================= #
+  # === COLOR_LIGHTSEAGREEN
+  # ========================================================================= #
+  COLOR_LIGHTSEAGREEN = 0x20b2aa
+
 end