swing_paradise 0.1.46

data/doc/README.gen

@@ -0,0 +1,1510 @@
+DEFAULT_HEADER
+
+## Introduction to the swing_paradise project and its different goals
+
+In the last some months of the year 2023/2024 I thought about the
+goals of this project. This made me re-arrange the introductionary
+section here. I will keep a numbered list of the goals of the
+swing_paradise project.
+
+(1) This gem contains some add-on bindings to jruby-Swing. This
+is the primary goal.
+
+<b>Swing</b> is an extension of the <b>Abstract Window Toolkit</b> (AWT),
+a GUI (graphical user interface).
+
+As Swing depends on Java, this project here really only makes
+sense for use via <b>jruby</b>.
+
+At present the project is fairly incomplete, but over the
+coming months this should be improved. Right now this project
+is beta-quality and I do not recommend anyone to use this
+project. However had, for some limited scope, this project may
+be fairly useful even if incomplete.
+
+(2) Note that while the primary focus of this project will be on
+Swing-based applications and add-on improvements, to make working
+with jruby and Swing suck less, there is a secondary focus for
+this project as well, in that I will attempt to create as many
+Swing-based applications as possible, to make working on Windows
+suck less. Most of these add-ons will reside under
+<b>swing_paradise/widget_collection/</b>, but some may be grouped
+into different gems, under either gui/jruby/ or gui/universal_widgets.
+The latter will probably become more relevant in the future,
+whereas for now, gui/jruby/ will be where most of the gui-relevant
+bindings reside under.
+
+With "Swing-based applications" I specifically mean being able to
+use custom, ad-hoc widgets that solve certain problems, such
+as "I want to delete the first page of this .pdf file,
+via a GUI", on windows. In fact, that has been one major use
+case why I intensified code for this project in October 
+2023 - I had to use windows as primary operating system
+every now and then, and it always annoyed me compared
+to Linux, so I decided to create widgets (and describe
+them, too) that will help me on windows. Also note that
+this is an ongoing effort - I can not predict how useful
+and extensive this will be. Stay tuned nonetheless.
+
+(3) Another focus of this project is to provide useful documentation
+in regards to Swing, as well as jruby. This helps me as a mnemonic,
+but it may also be helpful to new users, in what they can do
+with the project here in the long run. When I started this
+project there was next to no project that documented
+Swing + jruby. So one aim of this project has been to
+polish the documentation as much as possible.
+
+## Terminology
+
+In Java-Swing, a window is called a <b>frame</b>, which is represented
+by class <b>JFrame</b>.
+
+The default layout for Java-Swing components is a border layout.
+
+## SwingParadise::BaseModule
+
+SwingParadise::BaseModule is the core helper module of
+this gem.
+
+You can include it, since it is a module, via:
+
+    require 'swing_paradise/base_module/base_module.rb'
+    include SwingParadise::BaseModule
+
+See also the distributed examples if you want to know
+more about how to use this in practice.
+
+Since as of 29th October 2023, this will also automatically
+pull in most of the important java-swing methods. I found
+this easier to work with, than have to remember which
+widgets I need.
+
+This is done via java_import statements, such as:
+
+    java_import javax.swing.JPasswordField
+
+So basically you can omit a few lines in your application
+by tapping into the BaseModule module.
+
+## Simplified quitting
+
+Use the following method to <b>quit</b> easily:
+
+    do_quit
+
+For instance, a <b>quit button</b> could then be done in this
+manner:
+
+    quit_button.on_clicked {
+      do_quit
+    }
+
+## Useful java_import headers
+
+    include Java
+
+    java_import javax.swing.JButton
+    java_import javax.swing.JFrame
+    java_import javax.swing.JLabel
+    java_import javax.swing.JPanel
+    java_import javax.swing.JTextArea
+    java_import javax.swing.JScrollBar
+    java_import javax.swing.JTextField
+    java_import javax.swing.JSpinner
+    java_import javax.swing.SpinnerNumberModel
+    java_import java.lang.System
+    java_import java.awt.Font
+
+## Usage example for setBounds
+
+    _.setBounds(10, 20, 200, 40)  /* is: x-coordinate, y-coordinate, width, height) */
+    _.set_bounds(10, 20, 200, 40) /* is: x-coordinate, y-coordinate, width, height) */
+
+Note that both variants work. I prefer <b>.set_bounds()</b>.
+
+<!---
+
+https://www.rubydoc.info/gems/swing_paradise/0.1.13#jtextarea
+
+-->
+## JTextArea
+
+First, let's have a look as to how a JTextArea may look like (on Windows):
+
+<img src="https://i.imgur.com/CWVYskn.png" style="margin: 1em">
+
+The <b>JTextArea class</b> provides a component that displays multiple lines of
+text.
+
+If only one line of input is required from the user, then a <b>text field</b>
+should be used rather than JTextArea.
+
+In <b>raw Java</b>, the code for instantiating a new JTextArea goes like this:
+
+    text_area = new JTextArea(5, 20);
+    JScrollPane scroll_pane = new JScrollPane(text_area); 
+    text_area.setEditable(false);
+
+In the code above, the API for JTextArea() follows this
+signature: <b>JTextArea(int rows, int columns)</b> - so you first
+pass in the number of rows, and then pass in the number of columns.
+
+In Java, you can set the background colour to a colour of your choosing via:
+
+    import java.awt.Color;
+    Color color = new Color(255,0,0); /* This is red. */
+    text_area.setBackground(color);
+
+The textarea is quite flexible. For instance, you can force it to
+ignore newlines entered by the user, thus making it essentially
+a single-line input entry:
+
+    textview = create_textarea
+    textview.getDocument.putProperty('filterNewlines', true)
+
+As this is a bit annoying to remember, I added this method:
+
+    textview.filter_newlines
+
+As always, you need to include SwingParadise::BaseModule for
+this add-on functionality.
+
+Most of the time you probably don't want this behaviour though.
+
+To set to a different background colour, use something like this:
+
+    textview.setBackground(Color::GREEN)
+
+Line-wrapping and wrap-style can also be set:
+
+    textview.setLineWrap(true)
+    textview.setWrapStyleWord(false)
+
+## JComboBox - working with combo-boxes in Java swing and jruby
+
+You can instantiate a new combo box via:
+
+    combo_box = JComboBox.new
+
+Now, in order to fill it up, you can use something like this:
+
+    array = %w( apple bird cat dog eagle ferret )
+    array.each {|this_item|
+      combo_box.addItem(this_item)
+    }
+
+So .addItem() can be used to add more elements to the combo-box.
+
+As the above is a bit cumbersome, if you make use of
+<b>SwingParadise::BaseModule</b>, you can use the following API
+instead:
+
+    array = %w( apple bird cat dog eagle ferret )
+    combo_box(array) # So you can simply pass in the full Array here
+
+To select a specific index, that is, a specific entry on that
+combo box, you can use the method <b>.setSelectedIndex()</b>:
+
+    combo_box.setSelectedIndex(2) # For the third entry.
+
+To query which index is the currently selected one on a
+combo-box, use the method <b>.selected_index</b>, as in:
+
+    combo_box.selected_index
+
+To obtain the selected entry, use <b>.selected_item</b>,
+as in:
+
+    combo_box.selected_item
+
+## Java::JavaAwtEvent::ActionEvent
+
+Events in java can be found under <b>java.awt.events.*</b>.
+
+<b>class Java::JavaAwtEvent::ActionEvent</b> is the base class for
+when Java Swing fires an event, such as when the user changes the
+content of a combo-box.
+
+The syntax to use it, from <b>jruby</b>, goes like this:
+
+    widget.add_action_listener { |event|
+    }
+
+So you designate a block variable; I recommend to consistently call
+it <b>event</b>, as that should simplify things.
+
+How can you find out the specific event?
+
+One way goes via the method <b>.get_action_command()</b>,
+such as in:
+
+    event.get_action_command
+
+    action_command = event.get_action_command
+
+For the changed content of a combo-box, the result
+would <b>comboBoxChanged</b>.
+
+To respond to this, you can use the following snippet:
+
+    case event.get_action_command
+    when /comboBoxChanged/
+    end
+
+I needed this functionality for a widget that, when the user changes
+the combo-box content, another entry is also changed, reflecting the
+currently selected entry there.
+
+## Available colours
+
+Just a simple listing of available colours in a java swing
+application:
+
+    Color::RED
+    Color::BLUE
+    Color::GREEN
+    Color::BLACK
+
+## Obtaining the height and width of a widget
+
+  Use .getBounds as in:
+
+    frame.getBounds()
+    height = r.height
+    width  = r.width
+
+## The GridLayout
+
+A GridLayout in java-swing looks like this:
+
+<img src="https://docs.oracle.com/javase/tutorial/figures/uiswing/layout/GridLayoutDemo.png" style="margin: 1em">
+
+In other words: you arrange elements (widgets) in a 2D-like matrix. This
+is also called <b>a grid of cells</b>. Each component in the grid
+is <b>exactly</b> the same size.
+
+To create a new GridLayout, in raw Java, use this:
+
+    /* API: GridLayout(int rows, int cols) */
+    GridLayout x = new GridLayout(3, 3); /* A 3x3 grid */
+
+You can then add new elements to it via:
+
+    .add(new JButton("Button 1"));
+    .add(new JButton("Button 2"));
+
+And so forth.
+
+If you use SwingParadise::BaseModule then you can also make
+use of the .create_grid() method.
+
+    grid = create_grid('2x2')
+    grid.add(button('Button 1'))
+    grid.add(button('Button 2'))
+
+This should be equivalent to the above mentioned Java code.
+
+## JCheckBox and checkboxes in Java swing
+
+Let's first look at an image how checkboxes look in Java swing:
+
+<img src="https://i.imgur.com/E5gugWY.png" style="margin: 1em">
+
+Let's next have a look at how we <b>add checkboxes in raw Java swing</b>:
+
+    JPanel panel = new JPanel();
+    panel.add(label);
+
+    JCheckBox one = new JCheckBox("one");
+    JCheckBox two = new JCheckBox("two");
+
+    panel.add(one);
+    panel.add(two);
+
+So, we make use of <b>JCheckBox</b>. A second argument can be passed,
+to determine whether the check-box is checked or whether it is not:
+
+    JCheckBox.new("Foobar", true)
+    JCheckBox.new("Foobar", false)
+
+To determine whether a JCheckBox is <b>checked</b> - aka selected, the
+following method can be used:
+
+    checkbox.isSelected()
+
+Or, if you use the swing_paradise gem, you can also use:
+
+    checkbox.is_selected?
+
+To mark the checkbox as checked, use:
+
+    checkbox.setSelected(true)
+
+## JFrame
+
+To create a new frame, aka a new JFrame, from jruby, use:
+
+    frame = JFrame.new # This would be an untitled frame.
+    frame = JFrame.new("Frame Title") # And this would set the title to "Frame Title".
+
+If you'd like to you could also use the full qualifier (full name),
+which is:
+
+    frame = javax.swing.JFrame.new
+    # panel = Java::javax::swing::JFrame.new # This variant may also work, but is not as elegant as the one above.
+
+However had, note that both variants shown above are more verbose, so
+it may not be worth the extra time to type; nonetheless, should you
+ever have a use case to scope specifically to a particular class,
+you can preface it via <b>javax.swing</b> (or wherever else that
+particular swing-class resides at).
+
+To set a grid layout you can use the method called <b>.set_layout()</b>,
+as seen in the following example:
+
+    frame.set_layout(
+      java.awt.GridLayout.new(2, 2, 2, 2)
+    )
+
+This is especially useful for any 2D layouts.
+
+To <b>exit a JFrame</b>, as the main pane, Java Swing usually
+requires that you use something like this:
+
+    frame.setDefaultCloseOperation(JFrame::EXIT_ON_CLOSE)
+
+I found this a bit cumbersome to type and difficult to
+remember, so the SwingParadise::BaseModule allows you
+to use this method instead:
+
+    default_close
+
+This one is easier for me to remember, and less to type, too.
+
+Note that you can not add a JFrame to another JFrame. I ran into
+this issue in December 2023, so I had to note this down here.
+
+The explanation I found stated this:
+
+"JFrame is a <b>top level container</b> and as such it cannot
+be <b>added</b> to any other container."
+
+Typically a JFrame contains two parts: a space area on top for
+the menu bar, and the content pane below the menu bar. Often
+the menu bar is missing, though, so the content pane is
+ultimately more important than the menu bar.
+
+Further methods for the JFrame include these (as a sample):
+
+   .setVisible(boolean b)
+   .setTitle(String title)
+   .setSize(int width, int height)
+   .setLocation(int horizontal, int vertical)
+   .pack()
+   .setDefaultCloseOperation(int operation)
+
+By default a JFrame is not visible, so we have to use:
+
+   frame.setVisible(true)
+
+To make it visible.
+
+You can designate the size of the main JFrame via .setSize():
+
+    .setSize(int width, int height)
+    .setSize(600, 420)
+
+Note that calling the method .pack() will resize the frame so that
+it tightly fits around components embedded into its content
+pane.
+
+To make the whole application quit when the close-action is
+triggered, use:
+
+    frame.setDefaultCloseOperation(JFrame::EXIT_ON_CLOSE)
+
+## JPanel
+
+In raw jruby, you can create a new instance of JPanel by issuing
+this:
+
+    panel = JPanel.new
+
+You can then assign different layouts to be used. For instance,
+to keep the panel left-aligned, meaning you will see new elements
+all appear in a linear left-to-right fashion, you can use a
+FlowLayout like this:
+
+    panel.layout = FlowLayout.new(FlowLayout::LEFT)
+
+This would look similar to the following image:
+
+<img src="https://i.imgur.com/Yr7t7hJ.png" style="margin: 1em">
+
+This seems quite convenient and easy to use, so the swing_paradise
+gem tries to make this even easier. Here is the proposed API
+for the above two lines:
+
+    panel = create_panel { :left }
+
+This is <b>exactly</b> the same as:
+
+    panel = JPanel.new
+    panel.layout = FlowLayout.new(FlowLayout::LEFT)
+
+Note that FlowLayout is the default layout manager for
+every JPanel. The components will be laid out in a single
+row one after the other.
+
+Here is another picture how this would look:
+
+<img src="https://www.guru99.com/images/uploads/2012/06/java-flow-layout-manager.jpg" style="margin: 1em">
+
+JPanel can also be used to draw onto, via the method called
+<b>paintComponent</b>. Whenever the GUI is resized, this
+method will be automatically called.
+
+Take note that .paintComponent() should not be called directly;
+instead, use the .repaint() method in the event you wish to
+draw onto the panel.
+
+The API for paintComponent in raw Java Swing goes as follows:
+
+    public void paintComponent(Graphics g)
+
+Graphics here belongs to AWT.
+
+## Working with colours in SWING and jruby
+
+The generic way to handle colours in java-swing goes like this:    
+    
+    import java.awt.Color;
+    Color color = new Color(255,0,0); /* This is red. */
+
+## Using no specific layout
+
+Via:
+
+    frame.setLayout(nil)
+
+You can avoid using any specific layout.
+
+## GridBagLayout
+
+GridBagLayout aligns components by placing them within a grid
+of cells, allowing components to span more than one cell.
+
+The following image shows how this may look like:
+
+<img src="https://www.guru99.com/images/uploads/2012/06/java-grid-bag-layout.jpg" style="margin: 1em">
+
+## JButton and buttons in swing
+
+Java-Swing calls a button JButton. JButton is not the only button
+available in Java-Swing: we can also use JCheckBox, JRadioButton,
+JMenuItem, JCheckBoxMenuItem, JRadioButtonMenuItem or JToggleButton.
+
+An example for a widget that uses three buttons will be shown
+next (on Windows XP):
+
+<img src="https://i.imgur.com/xBvl7Fq.png" style="margin: 1em">
+
+You can add an icon to a button in swing.
+
+First, let's show the Java version for this:
+
+    JButton button = new JButton(new ImageIcon("foobar.jpg"));
+
+<b>ImageIcon</b> can be used for <b>pixel graphics</b>.
+
+Next, the equivalent ruby code:
+
+    button = JButton.new(ImageIcon.new('foobar.jpg'))
+
+If you use the swing_paradise gem, the above can be simplified a
+little bit further:
+
+    button = button(ImageIcon.new('foobar.jpg'))
+
+I may extend this API to simplify this further, such as
+<b>button_with_image()</b> or something like that. In fact, in
+February 2024 this was indeed extended: if you use SwingParadise::BaseModule
+then you can use the method called <b>button_with_image()</b> to add
+a button with an image. There are two ways to call this: one is by simply
+passing the path to a local image. The second way is to also pass an
+optional text that is displayed next to the image.
+
+To change the background colour for a button, use the following API:
+
+    button.setBackground(Color.green) # This would make it green.
+
+To let a JButton respond to on-click events, one has to
+attach a listener, via the following API:
+
+    button.addActionListener(ActionListener listener)
+
+In jruby this is implemented via a block form, that is via:
+
+    {
+    }
+
+To <b>focus</b> on a button, use:
+
+    button.requestFocusInWindow(); 
+
+To obtain the text (label) if a JButton, use the method
+<b>.getText</b>.
+
+If you make use of the swing-paradise gem then you can
+simply call the .on_clicked {} method on a button,
+such as via:
+
+    button = JButton.new('Please click me.')
+    button.on_clicked {
+      puts 'I was clicked.'
+    }
+
+There is, interestingly enough, another way possible for
+achieving the above, in that you specify a distinct
+class that will be invoked when the button is called.
+
+So, the code for the button at hand would then look like
+this:
+
+    button = JButton.new('Please click me.')
+    button.addActionListener(ClickAction.new)
+
+And you also need to define class ClickAction, like this:
+
+    class ClickAction
+
+      include ActionListener
+
+      def actionPerformed(event) # you can also use: "def action_performed" instead
+        puts 'This time the button was called from within clas ClickAction.'
+      end
+
+    end
+
+This solution is not quite as convenient as the .on_clicked {} variant,
+but perhaps there may be times when this is needed, so it is mentioned
+here in the documentation. Personally I will continue to prefer
+the <b>.on_clicked {} method variant</b> though - my brain has an
+easier time remembering that variant.
+
+You can also use tooltips for a button.
+
+Examples:
+
+    button.setToolTipText('Press Alt+H to trigger this button.')
+    button.hint = 'Press Alt+H to trigger this button.'
+
+If you need to obtain the tooltip-text, you can use:
+
+    puts button.getToolTipText
+
+The location where the tooltip will be shown, can be obtained via:
+
+    puts button.getToolTipLocation(MouseEvent)
+
+If you want to make the button have a flat-style look, use:
+
+    button.setBorderPainted(false)
+    button.setFocusPainted(false)
+    button.setContentAreaFilled(false)
+
+The full <b>API documentation</b> for JButton can be found here:
+
+https://docs.oracle.com/javase/8/docs/api/javax/swing/JButton.html
+
+## JLabel and text
+
+You can right-align a JLabel widget via:
+
+    JLabel(String text, int horizontalAlignment) 
+    JLabel label = new JLabel("Telephone", SwingConstants.RIGHT);
+
+In jruby-swing this would look like this:
+
+    label = JLabel.new('Telephone', SwingConstants::RIGHT)
+
+After you created a label, you can call several methods on it.
+
+For instance, to change the foreground colour, use:
+
+    label.setForeground(Color c)
+
+For the background colour use:
+
+    label.setBackground(Color c)
+
+You can also set the label to be opaque, via:
+
+    label.setOpaque(boolean b)
+    label.setOpaque(true)
+    label.setOpaque(false)
+
+If true is passed to the latter method then the label
+will be transparent; if it is false, then the label will be
+non-transparent.
+
+Interestingly you can also use HTML markup in a JLabel. The
+following example shows how this can be done:
+
+    label = JLabel.new("<html><span>This is your text</span></html>");
+
+## JColorChooser (javax.swing.colorchooser)
+
+<b>JColorChooser</b> can be used to pick a certain colours.
+
+Let's have a look at an image, to find out how this may actually look:
+
+<img src="https://docs.oracle.com/javase/tutorial/figures/uiswing/components/ColorChooserDemoMetal.png" style="margin: 1em">
+
+In raw Java, we would use the following to create a new JColorChooser instance:
+
+    banner = new JLabel("Some text.", JLabel.CENTER);
+    banner.setForeground(Color.yellow);
+    jcolorchooser = new JColorChooser(banner.getForeground());
+    add(jcolorchooser, BorderLayout.PAGE_END);
+
+If you want to create a dialog, for the user to make a choice, you can
+use the <b>.createDialog()</b> method:
+
+    jcolorchooser.createDialog()
+    jcolorchooser.createDialog # Remember, in ruby you can omit the ().
+
+## JOptionPane
+
+<b>JOptionPane</b> can be used to ask the user about confirmation about
+certain actions, such as <b>Do you really want to delete this
+file?</b>.
+
+## BorderLayout
+
+A BorderLayout places components in up to five areas:
+
+<b>top</b>, <b>bottom</b>, <b>left</b>, <b>right</b>,
+and <b>center</b>.
+
+It is <b>the default layout manager</b> for every java JFrame.
+
+It looks like this:
+
+<img src="https://www.guru99.com/images/uploads/2012/06/java-border-layout-manager.jpg" style="margin: 1em">
+
+## BorderFactory
+
+BorderFactory can be used to create a frame with a label.
+
+Usage example in jruby:
+
+    _ = BorderFactory.createTitledBorder(' Shell ')
+    _.setTitleFont(Font.new('Tahoma', Font::PLAIN, 50)) # This here can be used to set the font that is used.
+
+Many variants exist for BorderFactory.
+
+For instance, to set a matte-border, you can use:
+
+    ImageIcon icon = createImageIcon("images/wavy.gif", "wavy-line border icon"); # 20x22
+    BorderFactory.createMatteBorder(-1, -1, -1, -1, icon));
+
+## ImageIcon
+
+The name icon is a slight misnomer for this class, as it can also deal with
+large images.
+
+As argument to this class the path to a local filename should be supplied,
+as a String.
+
+Example:
+
+    image_icon = ImageIcon.new('/tmp/foobar.png')
+
+You can also supply an URL instead of a String to a local path.
+
+You can query the height and width of this image via:
+
+    image_icon.getImageHeight() # returns the image height, in n pixels.
+    image_icon.getImageWidth()  # returns the image width,  in n pixels.
+
+Keep in mind that instances of class ImageIcon are non-graphical components.
+This means that they have to be put into some container, such as
+JLabel, e. g.:
+
+    JLabel.new(ImageIcon picture)
+    JLabel.new(image_icon) # re-using the variable defined above ^^^
+
+You can also load images <b>asynchronously</b>. This can be done via
+<b>Toolkit</b> from the AWT library.
+
+Example in Java-Swing:
+
+    Image picture = Toolkit.getDefaultToolkit.getImage(String filename);
+    Image picture = Toolkit.getDefaultToolkit.getImage(String url);
+
+In jruby-Swing:
+
+    picture = Toolkit.getDefaultToolkit.getImage(String filename)
+    picture = Toolkit.getDefaultToolkit.getImage('foobar.png')
+
+If you need to load multiple images, possibly distributed on
+various servers on the internet, you may want to make use
+of class <b>MediaTracker</b>, which is part of the AWT
+library. MediaTracker can monitor the loading process of many
+images. Interestingly MediaTracker makes use of an id,
+such as via the following method call:
+
+    .addImage(Image picture, int id)
+
+## Java::JavaAwtEvent::ActionEvent and events in general
+
+An event in a SWING application is typically of class
+<b>Java::JavaAwtEvent::ActionEvent</b>, as far as Ruby is
+concerned.
+
+## JTextField
+
+<b>JTextField</b> is a lightweight component that allows the
+editing of a single line of text. 
+
+A <b>JTextField</b> - also known as an <b>entry</b> - is
+a <b>subclass</b> of the <b>JTextComponent</b> class.
+
+<b>Padding</b> can be added to a JTextField via the method
+.setMargin() and passing proper insets to it.
+
+Example:
+
+    setMargin(Insets m)
+    
+    text_field = new JTextField("A text field example.");
+    text_field.setMargin(new Insets(10, 10, 10, 10));
+
+JTextField can also be instantiated in this manner:
+
+    JTextField(String text, int columns)
+
+So the second argument means how many columns this entry
+should have.
+
+Documentation for JTextField can be seen here:
+
+https://docs.oracle.com/javase/8/docs/api/javax/swing/JTextField.html
+
+## Textfields in Java-SWING via JFormattedTextField
+
+If you have a need to hide certain input elements, such as
+via a user-password, you could use the following code, in
+Java-SWING:
+
+    import javax.swing.text.MaskFormatter;
+    MaskFormatter mask_formatter = new MaskFormatter("###-##-####");
+
+JFormattedTextField has three preconfigured format types:
+
+    numbers
+    dates
+    strings
+
+## JScrollBar
+
+First, before this subsection explains some things about a <b>JScollBar</b>, let us state
+that in many cases a developer may want to use <b>JScrollPane</b> instead.
+
+<b>JScrollBar</b> is used to create a scrolling widget. This refers to
+a widget that has a vertical and a horizontal bar - both of which
+can be optional - allowing the mouse pointer to click and drag
+the child-widget, to the right, left, up or down. This is especially
+useful for a text-buffer widget, where regular text is displayed
+that overflows to the right hand side (or somewhere else).
+
+The following image shows how this looked on Windows XP:
+
+<img src="https://i.imgur.com/6AEwGR7.png" style="margin: 1em">
+
+So, to summarize: the scroll bar is used to determine the
+viewing area of the component (the child-widget).
+
+The scroll bar involves a knob that can be adjusted by the
+user. This is meant for use with the mouse pointer.
+
+How to create a new instance for a scroll bar in Java?
+
+The following code example (<b>ScrollBarExample.java</b>) shows this:
+
+    import javax.swing.*;
+    import java.awt.*;
+
+    class ScrollBarExample {
+
+      public static void main(String[] args) {
+        final JFrame frame = new JFrame("ScrollBarExample");
+
+        JScrollBar scrollBarH = new JScrollBar(JScrollBar.HORIZONTAL, 30, 20, 0, 500);
+        JScrollBar scrollBarV = new JScrollBar(JScrollBar.VERTICAL,   30, 40, 0, 500);
+
+        frame.setSize(300,200);
+        frame.getContentPane().add(scrollBarH, BorderLayout.SOUTH);
+        frame.getContentPane().add(scrollBarV, BorderLayout.EAST);
+        frame.setVisible(true);
+      }
+
+    }
+
+Which relevant properties does the scroll bar have?
+
+    orientation: This indicates a horizontal or a vertical Scrollbar.
+    value:       This indicates the model's current value. The upper
+                 limit on the model's value is maximum - extent and the
+                 lower limit is minimum.
+    extent:      This indicates the width of the knob of the scrollbar.
+    minimum:     This indicates the minimum width of the track on which the scrollbar moves.
+    maximum:     This indicates the maximum width of the track on which the scrollbar moves.
+
+If you instantiate a new scrollbar in jruby, using this syntax:
+
+    JScrollBar.new
+
+then the following initial values are used:
+
+    minimum =   0
+    maximum = 100
+    value   =   0
+    extent  =  10
+
+The first argument is orientation (as Integer).
+
+Example:
+
+    JScrollBar.new(int orientation)
+    JScrollBar.new(1)
+
+In other words: you can use this to determine the orientation
+of the scrollbar. The value <b>orientation=0</b> means we will
+make use of a horizontal scroll bar, whereas the value
+<b>orientation=1</b> means we will get a vertical scroll bar.
+Most commonly a horizontal scroll bar is used.
+
+The most commonly used methods of the JScrollBar class are
+as follows:
+
+    - The addAdjustmentListener(AdjustmentListener l) method adds a
+      listener to the specified JScrollBar instance. The listener
+      will be notified every time a change to the model of the
+      scroll bar is detected.
+    - The getModel() method returns the model of the scroll bar.
+    - The getMaximum() method returns the maximum value (maximum -
+      extent) of the scrollbar.
+    - The getMinimum() method returns the minimum value of the scroll
+      bar.
+    - The getOrientation() method returns the orientation of the
+      scroll bar.
+    - The getValue() method returns the scrollbar’s value.
+    - The setMaximum() method is used to set the maximum value
+      of the scrollbar.
+    - The setMinimum() method is used to set the minimum value of the scroll bar.
+    - The setOrientation() method is used to set the orientation of the scroll bar.
+    - The setValue() method is used to set the scrollbar’s value.
+
+If you want to set inner padding, you have to make use of
+a border:
+
+    scroll_bar.setBorder(BorderFactory.createEmptyBorder(10, 10, 10, 10))
+
+## Checking for the escape-key being pressed
+
+In raw Java SWING, we can use the following line of code to check whether
+the user has pressed the escape-key:
+
+    if (event.getKeyCode() == KeyEvent.VK_ESCAPE) {
+    }
+
+In jruby SWING, this would be:
+
+    if (event.getKeyCode() == KeyEvent::VK_ESCAPE) {
+    }
+
+Note that <b>KeyEvent::VK_ESCAPE</b> returns a number; in this case
+that number is <b>27</b>.
+
+## The Graphics class
+
+Available methods include:
+
+    drawLine(int xstart, int ystart, int xend, int yend)
+    drawRect(int xleft, int ytop, int width, int height)
+    drawOval(int xleft, int ytop, int width, int height)
+    drawString(String text, int xleft, int ybottom)
+    fillRect(int xleft, int ytop, int width, int height)
+    fillOval(int xleft, int ytop, int width, int height)
+    setColor(Color col)
+
+All these int-arguments refer to <b>pixels</b>.
+
+<b>.drawLine(xstart,ystart,xend,yend)</b> draws a line segment
+between the points with coordinates (xstart, ystart) and
+(xend, yend).
+
+Note that .setColor(col) sets the colour of the drawing to col.
+This colour is used until the setColor command is used again.
+
+## The mouse and mouse-events
+
+A mouse event in jruby is of class <b>Java::JavaAwtEvent::MouseEvent</b>.
+
+In Java-Swing two interfaces process mouse events:
+
+1) MouseListener
+2) MouseMotionListener
+
+Note that key listeners react to key strokes (aka key press events).
+
+## JScrollPane
+
+First, let's have a look how a JScrollPane may look like:
+
+<img src="https://i.imgur.com/sGd0NN6.png" style="margin: 1em">
+
+JScrollPane is the primary widget to be used when scrolling
+should be used (in Swing).
+
+Next, let's look at a raw Java example for how to work with a <b>JScrollPane</b>:
+
+    import java.awt.FlowLayout;  
+    import javax.swing.JFrame;  
+    import javax.swing.JScrollPane; /* This is where it resides. */  
+    import javax.swing.JtextArea;  
+
+    public class JScrollPaneExample {  
+      private static final long serialVersionUID = 1L;  
+  
+      private static void createAndShowGUI() {  
+  
+        // Create and set up the window.  
+        final JFrame frame = new JFrame("Scroll Pane Example");  
+  
+        // Display the window.  
+        frame.setSize(500, 500);  
+        frame.setVisible(true);  
+        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);  
+  
+        // set flow layout for the frame  
+        frame.getContentPane().setLayout(new FlowLayout());  
+  
+        JTextArea textArea = new JTextArea(20, 20);  
+        JScrollPane scrollableTextArea = new JScrollPane(textArea);  
+  
+        scrollableTextArea.setHorizontalScrollBarPolicy(JScrollPane.HORIZONTAL_SCROLLBAR_ALWAYS);  
+        scrollableTextArea.setVerticalScrollBarPolicy(JScrollPane.VERTICAL_SCROLLBAR_ALWAYS);  
+  
+        frame.getContentPane().add(scrollableTextArea);  
+      }  
+      public static void main(String[] args) {  
+  
+        javax.swing.SwingUtilities.invokeLater(new Runnable() {  
+          public void run() {  
+            createAndShowGUI();  
+          }  
+        });  
+      }  
+    }
+
+In jruby this may look like so:
+
+    text_area = JTextArea.new(20, 20)  
+    scrollable_text_area = JScrollPane.new(text_area) # Add the scroll-pane here.  
+    scrollable_text_area.setHorizontalScrollBarPolicy(JScrollPane::HORIZONTAL_SCROLLBAR_ALWAYS)  
+    scrollable_text_area.setVerticalScrollBarPolicy(JScrollPane::VERTICAL_SCROLLBAR_ALWAYS)  
+
+In other words: you pass the widget that you want to see scroll-bars for,
+into JScrollPane.new() - in that case, the variable text_area.
+
+The viewport that you see will display the content of the JTextArea then.
+
+If the whole component fits into the viewport then the default behaviour is
+that the scroll bars disappear. This behaviour can be changed, though, via
+the horizontal and vertical policy.
+
+## Using mnemonics for JButton
+
+You can use shortcut-keys, aka mnemonics, for buttons.
+
+This is done in general via the method called <b>.setMnemonic()</b>.
+
+Example for this:
+
+    button.setMnemonic(KeyEvent::VK_H)
+
+VK_H means Alt+H. Alt here refers to the Alt-key. H is simply the letter
+H on the keyboard, so this means "press the alt-key as well as the h
+key".
+
+If you instead want to enable Akt+H, use:
+
+    button.setMnemonic(KeyEvent::VK_A)
+
+You can also use numbers instead. For instance:
+
+    button.setMnemonic(KeyEvent::VK_1)
+
+This would allow you to respond to "Alt+1" key combinations. You can
+find examples related to this in the file at <b>examples/017_button_example.rb</b>.
+That file will, in the long run, contain all useful button-related 
+activities that may be useful when designing applications via jruby-SWING.
+
+As I find this a bit cumbersome to remember (I can't remember VK_1 or
+similar crypt names), I decided to add an API that simplifies this.
+
+Usage example:
+
+    button.keycombo('Alt+1') # respond to alt+1
+    button.keycombo('Alt+W') # respond to alt+W
+
+Note that this currently (<b>January 2024</b>) only works for Alt-key
+combinations. At a later time I may extend this for more key-combinations.
+
+## Working with JTable
+
+A new table can be created via:
+
+    JTable(int rows, int cols): Creates a table of size rows * cols.
+
+Like a table with (2, 3), 2 rows, and 3 columns.
+
+You can also simplify it a bit, by using
+<b>javax.swing.table.DefaultTableModel</b> via:
+
+    m = javax.swing.table.DefaultTableModel.new
+    m.add_column("id")
+    m.add_column("name")
+    m.add_row(['1', "jimmy"].to_java)
+    m.add_row(['2', "robert"].to_java)
+
+    table = JTable.new(m)
+    # The fulle qualifier for JTable is javax.swing.JTable, by the way.
+
+You can add java-specific objects, such as a vector, via:
+
+    m.add_row java.util.Vector.new('"ト', 'あ', 'い'])
+
+You can also pass the columns by calling DefaultTableModel.new,
+like this:
+
+    m = DefaultTableModel.new(nil, ["No.", "Name", "Path"].to_java)
+
+The <b>API documentation</b> for JTable can be found here:
+
+https://docs.oracle.com/javase/8/docs/api/javax/swing/JTable.html
+
+## Converting an Array into Java::JavaLang:Object:
+
+This can be done by calling .to_java.
+
+Example for this:
+
+    pp ["1", "jimmy"].to_java # => #<Java::JavaLang::Object[2]: ["1", "jimmy"]>
+
+## JEditorPane()
+
+<b>JEditorPane()</b> can be used to <b>display text via java-swing</b>.
+
+Let's have a look at an image, how this may look:
+
+<img src="https://i.imgur.com/aVioB68.png" style="margin: 1em">
+
+If you need to obtain the current text stored in a JEditorPane,
+you can use the method called <b>.getText()</b>.
+
+## JComponent
+
+Every <b>JComponent</b> can have one or more <b>borders</b>.
+
+You can put a border around a JComponent. This is done via
+the <b>.setBorder()</b> method.
+
+This method is usually combined with the <b>BorderFactory class</b>.
+
+In raw Java swing, the code would look like this:
+
+    JPanel pane = new JPanel();
+    pane.setBorder(BorderFactory.createLineBorder(Color.black));
+
+## javax.swing.border
+
+This subsection may eventually contain some information about
+borders in java-swing applications.
+
+## JTextPane
+
+<b>JTextPane</b> can be used to render HTML content.
+
+The full scope of JTextPane is <b>javax.swing.JTextPane</b>.
+
+## Creating a MenuBar via JMenu
+
+First, let's look at how a Menu (JMenu) looks in Java-Swing:
+
+<img src="https://i.imgur.com/PNlkIfK.png" style="margin: 1em">
+
+The primary menu bar is called <b>JMenuBar</b> in Java-Swing.
+
+To then create a menu, in raw Java-Swing, the following code
+could be used:
+
+    JMenuBar menu_bar = new JMenuBar(); # Create a new menubar here.
+    JMenu m1 = new JMenu("FILE");
+    menu_bar.add(m1);
+    JMenu m2 = new JMenu("Help");
+    menu_bar.add(m2);
+
+Or in jruby code:
+
+    menu_bar = JMenuBar.new
+    m1 = JMenu.new("FILE")
+    menu_bar.add(m1)
+    m2 = JMenu.new("Help")
+    menu_bar.add(m2)
+
+If you use the swing_paradise gem then you can also use <<
+rather than .add(). Example:
+
+    menu_bar << m1
+    menu_bar << m2
+
+This is a bit shorter to type.
+
+Take note that the constructor for <b>JMenu</b> is this:
+
+    JMenu(String menuTitle);
+    JMenu.new(menuTitle) # This for jruby.
+
+So the name of the menu entry should be given, as a <b>String</b>.
+
+You can also attach mnemonics to this, such as via:
+
+    menu = JMenu.new('A Menu')
+    menu.setMnemonic(KeyEvent.VK_A)
+
+As can be seen from the above code, we first need to create a new
+<b>JMenuBar</b> - this is the first step.
+
+Then, now that we have a menu-bar, we can add new menus to
+it, of class JMenu. We use the method called .add() to
+add menu-entries there.
+
+Once you are done with the menu, it is time to add it. The menu
+is typically added to a <b>JFrame</b>, via the following
+API:
+
+    setJMenuBar(JMenuBar menuBar)
+    frame.setJMenuBar(menuBar)
+
+Take note that there are two distinct methods that are rather
+similar: one is called <b>.setJMenuBar</b> and the other one is
+called <b>.setMenuBar</b>. JMenuBar() is for Swing and MenuBar()
+is for AWT.
+
+Individual Menu items behave like buttons.
+
+If you have a need to disable an individual menu item then you
+can do so via:
+
+    setEnabled(boolean b)
+
+Example in jruby-Swing for disabling a menu item:
+
+    menu_item.setEnabled(false)
+
+To then bind an event to a menu-item, use <b>.addActionListener</b>.
+
+Example for this:
+
+    first = JMenuItem.new('Item 1')
+    m1.add(first)
+    first.addActionListener {|event|
+      puts 'Hello world!'
+    }
+    # Or, to exit, use this:
+    first.add_action_listener { |event|
+      System.exit(0) # or just exit, should be fine too.
+    }
+
+If you have a need to repaint the menu bar, you can use .revalidate()
+as in:
+
+    menu_bar.revalidate()
+    menu_bar.revalidate # or this one, as ruby allows you to omit ()
+
+Once you created your menu, you have to fill the submenus with
+JMenuItem entries. The following shows such an example I was
+using in January 2024:
+
+    open_a_local_file_entrypoint = JMenuItem.new('Open a local file', KeyEvent::VK_T)
+    open_a_local_file_entrypoint.use_this_font = :hack_26
+    open_a_local_file_entrypoint.addActionListener {|event|
+      do_choose_a_local_file_then_read_it_in
+    }
+    m1.add(open_a_local_file_entrypoint)
+
+So, to respond to the on-selected event, make use of .addActionListenere.
+
+## Working with JSplitPane
+
+Via JSplitPane - to be found under <b>javax.swing.JSplitPane</b> - you can
+split a pane, such as splitting into a left and a right component.
+
+Let's look at two images as to how <b>JSplitPane</b> looks like:
+
+<img src="https://i.imgur.com/zDe6NHK.png" style="margin: 1em">
+<img src="https://i.imgur.com/ucVpEcj.png" style="margin: 1em">
+
+To create a new <b>split-pane</b>, you would use the following code:
+
+    split_pane = JSplitPane.new(JSplitPane::VERTICAL_SPLIT)
+
+You can then modify its layout, or whether it allows one-touch
+expendable behaviour:
+
+    split_pane.setContinuousLayout(true)
+    split_pane.setOneTouchExpandable(true)
+
+You can then put other widgets into it, such as a button on top:
+
+    button_on_top = JButton.new('A')
+    split_pane.setTopComponent(button_on_top)
+
+And a button on bottom:
+
+    button_on_bottom =JButton.new('B')
+    split_pane.setBottomComponent(button_on_bottom)
+
+## Assigning Enter as the trigger key for all JButtons in a Java-Swing application
+
+    UIManager.put("Button.defaultButtonFollowsFocus", Boolean::TRUE)
+
+## Font, working with fonts and using fonts in a java-swing application
+
+Working with fonts in a java-swing application (or jruby-swing application)
+can be a bit tricky. This paragraph here tries to gather useful information
+pertaining to this.
+
+The raw Java code for creating a new font, goes like this:
+
+    Font use_this_font = new Font("SansSerif", Font.PLAIN, 20);
+
+In jruby this would be equivalent to the following code:
+
+    use_this_font = Font.new('SansSerif', Font::Plain, 20)
+
+Next follows a list, as example, how to handle different fonts - first
+in java-swing, then in jruby-swing:
+
+    widget.setFont(new Font("Times New Roman", Font.PLAIN, 12))
+    widget.setFont(new Font("Hack", Font.PLAIN, 40))
+
+    # now in jruby:
+    widget.setFont(Font.new("Times New Roman", Font::PLAIN, 12))
+    widget.setFont(Font.new("Hack", Font::PLAIN, 40))
+
+## Choosing files via a GUI, through JFileChooser - file-chooser functionality
+
+Let's first have a look how JFileChooser may look on WinXP:
+
+<img src="https://i.imgur.com/pkEoG6T.png" style="margin: 1em">
+
+You can use something like the following to get a file-chooser
+in jruby-swing:
+
+    file_chooser = JFileChooser.new
+    # file_chooser.setFileSelectionMode(JFileChooser::DIRECTORIES_ONLY)
+
+    result = file_chooser.showOpenDialog(nil) # or pass true here, to show the open dialog.
+    case result
+    when JFileChooser::APPROVE_OPTION
+      this_file = file_chooser.getSelectedFile.getAbsoluteFile.to_s
+      # this_file = File.absolute_path(this_file)
+      main_entry?.set_text(this_file)
+    end
+
+Adjust accordingly to your use case. Keep in mind that on closing, a
+file selection dialogue returns an integer value which is one of
+the following integer constants:
+
+    APPROVE_OPTION: indicates that the ‘Open’ or ‘Save’, in case of a
+                    save dialogue button of the dialogue has been
+                    clicked.
+    CANCEL_OPTION:  indicates that the ‘Cancel’ button of the dialogue
+                    has been clicked.
+
+Note that <b>JFileChooser::APPROVE_OPTION</b> returns <b>0</b>.
+
+To obtain the file that was selected, the method <b>.getSelectedFile</b>
+can be used, as shown in the code example above.
+
+Since as of January 2024 you can also use UniversalWidgets.main_file?
+and UniversalWidgets.set_main_file() to keep track of the chosen file.
+
+## JDialog and dialogues in jruby-SWING
+
+First, what is a dialogue?
+
+A dialogue is basically a simple means, via a widget, to obtain
+information from the user. This can then be of help for user-program
+interaction.
+
+Dialogues - that is, the widgets - are used when the application needs
+information from the user in order to proceed with a task or some
+other event.
+
+In jruby-SWING, the primary use of dialogues happens via
+<b>JDialog</b>:
+
+<b>JDialog</b> can be thought of to be <b>a pop-up window</b> that pops out
+when a message has to be displayed to the user.
+
+The namespace for <b>JDialog</b> is <b>javax.swing.JDialog</b>.
+
+Some dialoguses are pre-defined. For instance, a message dialogue
+can be invoked via:
+
+    JOptionPane.showMessageDialog(
+      Component parent,
+      String title,
+      String message,
+      int type
+    );
+
+More documentation pertaining to JDialog, in particular its API,
+can be seen here:
+
+https://docs.oracle.com/javase/8/docs/api/javax/swing/JDialog.html
+
+## Working with JRadioButton
+
+First, let's look at <b>two images</b> to see how a JRadioButton
+may look like:
+
+<img src="https://i.imgur.com/E4S1VWL.png" style="margin-right: 1em">
+<img src="https://i.imgur.com/hSrhzWz.jpg" style="margin: 1em">
+
+<b>JRadioButton</b>'s fully qualified namespace is
+<b>javax.swing.JRadioButton</b>. Its superclass is
+a <b>JToggleButton</b>.
+
+To create a new JRadioButton via java-swing, use:
+
+    JRadioButton x = new JRadioButton("Foobar"); 
+
+<b>Radio buttons</b> can be pressed and they can be grouped. They
+will stay pressed until another radio button of the group is
+pressed. A black dot appears inside the circular area if
+the button is pressed, as can be seen on the above image.
+
+The text that is displayed on a radio-button can be defined
+via passing a String as the first argument, as seen in the
+above example. For sake of completion we will show how this
+is done in jruby too:
+
+    radio_button = JRadioButton.new('Foobar')
+
+If you have a need to programmatically set that radio button
+selected or de-selected, use this method:
+
+    radio_button.setSelected(true)  # It is now selected.
+    radio_button.setSelected(false) # It is now de-selected.
+
+.setActionCommand(String command) assigns the string command
+as the action command to the button. Radio buttons are not
+automatically assigned an action command. This is because
+their label is often not a text but a picture. The action
+command can be set via this method.
+
+<b>.getActionCommand()</b> returns the action command
+assigned to the button.
+
+Normally radio buttons are put into a <b>ButtonGroup</b>. This
+has the effect that if the user selects one radio button,
+all other radio buttons are de-selected. In other words:
+this achieves that only one radio button is actively
+selected at any given moment in time.
+
+In order to group radio-buttons into a button group, we should
+first create a new instance of ButtonGroup, such as via:
+
+    button_group = ButtonGroup.new
+
+Next, use the method <b>.add()</b> to add radio_buttons into that
+button group:
+
+    button_group.add(radio_button1)
+    button_group.add(radio_button2)
+
+The <b>API documentation</b> for <b>JRadioButton</b> can be seen here:
+
+https://docs.oracle.com/javase/8/docs/api/javax/swing/JRadioButton.html
+
+## Java Swing Plaf
+
+The javax.swing.plaf package contains several subpackages and related packages.
+
+<b>Plaf</b> stands for <b>pluggable look and feel</b>.
+
+## Swing versus AWT
+
+<b>Swing component</b> class names begin with a J. AWT components do
+not.
+
+For instance, JButton is a swing-component whereas Button is an
+AWT component.
+
+This distinction holds true for most components, but one exception
+is the <b>JComboBox</b>, which replaces the AWT Choice component.
+
+The following table shows the AWT component and the nearest
+swing replacement:
+
+AWT Component               | Nearest Swing Replacement
+-------------------------------------------------
+Button                      | JButton
+Canvas                      | JPanel
+Checkbox                    | JCheckBox
+Checkbox in CheckboxGroup   | JRadioButton in ButtonGroup
+Choice                      | JComboBox
+Component                   | JComponent
+Container                   | JPanel
+Label                       | JLabel
+List                        | JList
+Menu                        | JMenu
+MenuBar                     | JMenuBar
+MenuItem                    | JMenuItem
+Panel                       | JPanel
+PopupMenu                   | JPopupMenu
+Scrollbar                   | JScrollBar
+ScrollPane                  | JScrollPane
+TextArea                    | JTextArea
+TextField                   | JTextField
+Applet                      | JApplet
+Dialog                      | JDialog
+FileDialog                  | JFileChooser
+Frame                       | JFrame
+Window                      | JWindow
+
+## JPasswordField
+
+JPasswordField is a specialized text field that can be used for inputting
+a password into a Swing-Application.
+
+Cut and copy operations are not possible within this
+component, but text can be pasted into it.
+
+On Windows it may look like this:
+
+<img src="https://static.javatpoint.com/java/swing/images/java-jpasswardfield1.png" style="margin: 1em">
+
+## Potentially useful links pertaining to Java-Swing
+
+https://web.mit.edu/6.005/www/sp14/psets/ps4/java-6-tutorial/components.html
+https://www.javatpoint.com/java-swing
+
+CONTACT_INFORMATION