wxruby3 0.9.8 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c45580184f8f7ee466f9ec158bcb9f28702f6674ab42abc735f7235cc3482bd
-  data.tar.gz: f22f78e25c135b2583bfd60a7712c1084b8be8b3550d695e1acf65eac19b2223
+  metadata.gz: d56d06b3a74584ca43ec7314bc816c34175dbb7c68d722dfb88f2d1702dc295b
+  data.tar.gz: 60d6432e98d834f8eaea4e0e13c8a2bed3fd8a9419cc6331d74c945f9695d223
 SHA512:
-  metadata.gz: 401ff95651f766ac947eba8a1a58a77be718182a473549f49eeee5b361a019051da88f529aec58bfe88dd46b5104dbae64a96eba5fa14d6a3e446fcece35c6f0
-  data.tar.gz: fe9f01627e61ddc1ff5c18936dbf71f1cf09fd7d6ce372b6cc25062051a3807b3e6a0fe59179753ce0a1f9577f856eefca58c0564d0860a6e607d14bba428606
+  metadata.gz: ef773e93094cfad19757c3d7ecfed29135d920a9f4e810521eadd6b226b8e13a10a735763853c1061d0256ce5fc84a2d5b0c28810874c99443c2a3e2548b753d
+  data.tar.gz: 92df4dfe100a6ec2c4353451d237a1a1819ac2777ac1fdbc9a4a8e6cb4996e8fc3254454582a5465e97c7613eaebca4a29e26935c87286798c24c5d235ef2d36

data/INSTALL.md

@@ -334,6 +334,21 @@ wxruby setup --with-wxwin
 
 This will force the setup procedure to build and install an embedded wxWidgets version for wxRuby3.
 
+#### Force embedded wxWidgets head installation
+
+To force the setup procedure to build and install an embedded wxWidgets head (master) version the setup procedure can 
+be started with the `--with-wxhead` option like this:
+
+```shell
+wxruby setup --with-wxhead
+```
+
+> **NOTE**<br>
+> Although wxRuby3 endeavors to keep up to date with the wxWidgets master branch your mileage may vary depending on
+> the development state of the wxWidgets master branch. You can check the latest results of the wxRuby3 CI master build 
+> workflows of the [wxRuby3 Github Actions](https://github.com/mcorino/wxRuby3/actions) to get a feel of the current 
+> integration state. 
+
 #### Setup with user installed wxWidgets
 
 In case of a (custom) user installation of wxWidgets the `--wxwin` (and optionally `--wxxml`) option(s) can be used to
@@ -357,6 +372,13 @@ wxruby setup --wxwin=/my/custom/wxWidgets --wxxml=/my/alternate/wxWidgets/xml
 > responsible for making sure the wxRuby3 extension library can find the wxWidgets libraries at runtime (normally this
 > requires updating the standard shared library search path for the platform).
 
+> **NOTE 2**<br>
+> Please be aware that when building a user installation of wxWidgets on Windows this has to be done using the exact
+> same compiler suite as used for building Ruby (and it's standard native extensions) itself.<br>
+> Currently only RubyInstaller versions are supported which use the MingW64 compiler.
+> Do **NOT** install a separate MSYS2/MingW64 release but rather use a RubyInstaller version with integrated DevKit 
+> installation (which includes MSYS2 and the right MingW64 compiler suite).
+
 #### Setup with customized tool paths
 
 If for whatever reason the required development tools `doxygen`, `swig` and/or `git` have been installed in a location
@@ -493,6 +515,6 @@ commands are executed using parallel task execution by default.
 When the build has finished without errors the regression tests can be run by calling `rake test`.
 
 After successfully building the wxRuby3 extension libraries (and possibly embedded wxWidgets libraries) a binary package
-can be created by call `rake binpkg`.
+can be created by calling `rake binpkg`.
 
 For more details concerning the wxRuby3 development strategy and build options see [here](TODO). 

data/README.md

@@ -41,7 +41,8 @@ end
 
 Anyone who is familiar with wxWidgets should feel right at home since the API may be Ruby-fied, it is still easily 
 recognizable (but being Ruby-fied allowing for elegant and compact coding). And for those that do not have previous 
-experience, do not fear, wxRuby3 comes with detailed [documentation](https://mcorino.github.io/wxRuby3/file.00_starting.html) and lots of examples and tests.    
+experience, do not fear, wxRuby3 comes with an extensive [User Guide](https://github.com/mcorino/wxRuby3/wiki/User-Guide-%3A-Introduction) 
+and detailed [reference documentation](https://mcorino.github.io/wxRuby3) and lots of examples and tests.    
 
 ```ruby
 require 'wx'
@@ -90,7 +91,9 @@ README and license files for details.
 See [here](CREDITS.md) for more details on and acknowledgement of the developers 
 of these products.
 
-## FAQ
+## (Some of the) Most Frequently Asked Questions
+
+(see the extended [FAQ](https://github.com/mcorino/wxRuby3/wiki/Frequently-Asked-Questions) in the [Wiki](https://github.com/mcorino/wxRuby3/wiki) for more information)
  
 ### What platforms and operating systems are supported in wxRuby3?
 
@@ -98,7 +101,7 @@ Currently the following are fully supported:
 
 | Platform                                                                                                                           | Ruby version(s)                                     | wxWidgets version(s) |
 |------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|----------------------|
-| Windows 10 (tested)<br>(most likely also Windows 11)                                                                               | Ruby >= 2.5<br>(RubyInstaller MSYS2-DevKit)         | wxWidgets >= 3.2     |
+| Windows >= 10                                                                                                                      | Ruby >= 2.5<br>(RubyInstaller MSYS2-DevKit)         | wxWidgets >= 3.2     |
 | Linux (tested; all major AMD64 and ARM64 distributions: Ubuntu, Debian, Fedora, OpenSuSE and ArchLinux)<br>(most likely also i686) | Ruby >= 2.5                                         | wxWidgets >= 3.2     |
 | MacOS >= 10.10 using Cocoa (tested on AMD64 and ARM64 M1/M2 Chip)                                                                  | Ruby >= 2.5 (MacPorts, Homebrew, ruby-install, RVM) | wxWidgets >= 3.2     |
 
@@ -158,10 +161,10 @@ Use GitHUb Issues.
 
 When asking a question, if something is not working as you expect,
 please provide a *minimal*, *runnable* sample of code that demonstrates
-the problem, and say what you expected to happen, and what actually
+the problem, and describe clearly what you expected to happen and what actually
 happened. Please also provide basic details of your platform, Ruby,
 wxRuby and wxWidgets version, and make a reasonable effort to find answers 
-in the archive and documentation before posting. People are mostly happy
+in the archive, wiki and/or documentation before posting. People are mostly happy
 to help, but it's too much to expect them to guess what you're trying to
 do, or try and debug 1,000 lines of your application.
 Very important also; do not use offensive language and be **polite**.
@@ -177,13 +180,17 @@ some use a more modern coding style than others. Use the bundled `wxruby`
 CLI to access the samples (see the section **Bundled CLI** in 
 the [INSTALL](INSTALL.md) document for more details).
 
+An extensive [User Guide](https://github.com/mcorino/wxRuby3/wiki/User-Guide-%3A-Introduction) 
+is available at the [wxRuby3 Wiki](https://github.com/mcorino/wxRuby3/wiki) providing detailed
+information about how to build desktop applications with wxRuby3. 
+
 Complete (more or less) wxRuby API documentation should be part of any
 complete wxRuby3 build. This tends to focus on providing a reference
 of all available modules, classes and methods and how to use specific 
 classes and methods, rather than on how to construct an application 
 overall.
 This documentation (for the latest release) is also available online
-[here](https://mcorino.github.io/wxRuby3/file.00_starting.html).
+[here](https://mcorino.github.io/wxRuby3).
 
 One of the advantages of wxRuby3 is the much larger ecosystem of
 wxWidgets and wxPython resources out there. There is a book for
@@ -199,18 +206,6 @@ example, if you wanted answers about the "Grid" class, try searching for
 "wxGrid" as this will turn up results relating to wxWidgets and wxPython
 which may be relevant.
 
-### What wxWidgets features are supported by wxRuby3?
-
-wxRuby supports almost all of the wxWidgets 3.2+ GUI API, providing over
-600 classes in total. wxWidgets classes that provide general and/or non-GUI 
-programming support features, such as strings, networking, threading, database
-access and such are not and will never be ported, as it's assumed that 
-in all these cases it's preferable to use pure Ruby features.
-
-If you know of a feature in wxWidgets that you would like to see
-supported in wxRuby3 you are free to ask but do not **EXPECT** unconditional 
-agreement or immediate response. 
-
 ### How does wxRuby3 relate to the wxRuby 2.0 (and even older 0.6.0) release?
 
 wxRuby 0.6.0 was the last in a series of releases developed using a
@@ -231,12 +226,3 @@ maintainable solution.
 
 Please double-check the instructions above and in the [INSTALL](INSTALL.md) document and search issue archives. If 
 this doesn't help, please post your question using GitHub Issues.
-
-### Is there another, more declarative way, for writing wxRuby3 desktop GUI applications?
-
-Yes. [Glimmer DSL for WX](https://github.com/AndyObtiva/glimmer-dsl-wx) enables software engineers to build GUI 
-using wxruby3 following the Ruby way with the least amount of code possible. That is by offering a minimalistic 
-declarative high-level DSL that maps visually to the way software engineers think about the GUI hierarchy in addition 
-to adopting Rails' strategy of Convention over Configuration via smart defaults and automation of wxruby3 low-level 
-details. You can check out the [Glimmer DSL for WX README "Coming From wxruby3" section](https://github.com/AndyObtiva/glimmer-dsl-wx#coming-from-wxruby3) for more information on 
-how to translate wxruby3 apps to [Glimmer DSL for WX](https://github.com/AndyObtiva/glimmer-dsl-wx) syntax.

data/ext/mkrf_conf_ext.rb

@@ -12,8 +12,8 @@ OPTIONS = {
 until ARGV.empty?
   switch = ARGV.shift
   case switch
-  when /^prebuilt=(none|only)$/
-    OPTIONS[:prebuilt] = $1 == 'only'
+  when /^prebuilt=(none|only|head)$/
+    OPTIONS[:prebuilt] = $1.to_sym
   when /^package=(.+)$/
     OPTIONS[:package] = $1
   when 'help'
@@ -41,14 +41,18 @@ until ARGV.empty?
   end
 end
 
-task_args = ''
+task_args = []
 unless OPTIONS[:prebuilt].nil?
-  task_args << "'#{(OPTIONS[:prebuilt] ? '--prebuilt' : '--no-prebuilt')}'"
+  case OPTIONS[:prebuilt]
+  when :only
+    task_args << "'--prebuilt'"
+  when :none
+    task_args << "'--no-prebuilt'"
+  end
 end
 if OPTIONS[:package]
-  task_args << ', ' unless task_args.empty?
   pkg = RUBY_PLATFORM =~ /mingw/ ? OPTIONS[:package].gsub('\\', '/') : OPTIONS[:package] # make sure the path is URI compatible
-  task_args << "'--package', " << "'#{pkg}'"
+  task_args << "'--package'" << "'#{pkg}'"
 end
 
 # generate new rakefile with appropriate default task (calls actual task in rakelib)
@@ -61,7 +65,7 @@ File.open('../Rakefile', 'w') do |f|
 
 unless File.file?(File.join('lib', 'wx', 'wxruby_core.so'))
   task :default do
-    Rake::Task['wxruby:gem:install'].invoke(#{task_args})
+    Rake::Task['wxruby:gem:install'].invoke(#{task_args.join(', ')})
   end
 end
 EOF__

data/lib/wx/core/app.rb

@@ -14,6 +14,22 @@ require_relative './ext'
 # Controller class which creates and manages all windows.
 class Wx::App
 
+  if Wx::PLATFORM == 'WXOSX'
+    class << self
+      # provide aliases for macosx specials
+      alias :mac_about_menu_itemid= :set_mac_about_menu_itemid
+      alias :mac_about_menu_itemid :get_mac_about_menu_itemid
+      alias :mac_preferences_menu_itemid= :set_mac_preferences_menu_itemid
+      alias :mac_preferences_menu_itemid :get_mac_preferences_menu_itemid
+      alias :mac_exit_menu_itemid= :set_mac_exit_menu_itemid
+      alias :mac_exit_menu_itemid :get_mac_exit_menu_itemid
+      alias :mac_help_menu_title= :set_mac_help_menu_title
+      alias :mac_help_menu_title :get_mac_help_menu_title
+      alias :mac_window_menu_title= :set_mac_window_menu_title
+      alias :mac_window_menu_title :get_mac_window_menu_title
+    end
+  end
+
   # convenience method to retrieve global Wx::App instance
   def self.the_app
     if Wx::const_defined?(:THE_APP) and Wx::THE_APP.is_running

data/lib/wx/core/colour.rb

@@ -6,37 +6,45 @@
 # Copyright 2004-2007, wxRuby development team
 # released under the MIT-like wxRuby2 license
 
-class Wx::Colour
-  # Redefine the initialize method so it raises an exception if an
-  # invalid colour value is given. This might be an unknown colour
-  # string (eg 'dark blue') or out-of-bounds integer values (<0 or >255)
-  wx_init = self.instance_method(:initialize)
-  define_method(:initialize) do | *args |
-    begin
-      wx_init.bind(self).call(*args)
-    # Invalid integer values raise SWIG 'no matching func'
-    rescue ArgumentError, TypeError
-      Kernel.raise ArgumentError, "Invalid colour values #{args.inspect}"
+require_relative 'ext'
+
+module Wx
+
+  Wx.add_delayed_constant(self, :TRANSPARENT_COLOUR, 'Wx::Colour.new(0, 0, 0, Wx::ALPHA_TRANSPARENT)') { Wx::Colour.new(0, 0, 0, Wx::ALPHA_TRANSPARENT) }
+
+  class Colour
+    # Redefine the initialize method so it raises an exception if an
+    # invalid colour value is given. This might be an unknown colour
+    # string (eg 'dark blue') or out-of-bounds integer values (<0 or >255)
+    wx_init = self.instance_method(:initialize)
+    define_method(:initialize) do | *args |
+      begin
+        wx_init.bind(self).call(*args)
+      # Invalid integer values raise SWIG 'no matching func'
+      rescue ArgumentError, TypeError
+        Kernel.raise ArgumentError, "Invalid colour values #{args.inspect}"
+      end
     end
-  end
 
-  # Missing Standard colour
-  Wx::MAGENTA = new(255, 0, 255)
-
-  # Colours are equal to one another if they have the same red, green
-  # and blue intensity, and the same alpha
-  def ==(other)
-    case other
-    when Wx::Colour
-      [  self.red,  self.green,  self.blue,  self.alpha ] == 
-      [ other.red, other.green, other.blue, other.alpha ]
-    else
-      false
+    # Missing Standard colour
+    Wx::MAGENTA = new(255, 0, 255)
+
+    # Colours are equal to one another if they have the same red, green
+    # and blue intensity, and the same alpha
+    def ==(other)
+      case other
+      when Wx::Colour
+        [  self.red,  self.green,  self.blue,  self.alpha ] ==
+        [ other.red, other.green, other.blue, other.alpha ]
+      else
+        false
+      end
     end
-  end
 
-  # More informative output for inspect etc
-  def to_s
-    "#<Wx::Colour: (#{red}, #{green}, #{blue} *#{alpha})>"
+    # More informative output for inspect etc
+    def to_s
+      "#<Wx::Colour: (#{red}, #{green}, #{blue} *#{alpha})>"
+    end
   end
+
 end

data/lib/wx/core/const.rb

@@ -68,8 +68,14 @@ module Wx
   TREE_LIST_CTRL_NAME_STR = 'wxTreeListCtrl'
   HTML_LIST_BOX_NAME_STR = 'htmlListBox'
   SIMPLE_HTML_LIST_BOX_NAME_STR = 'simpleHtmlListBox'
+  HTML_WINDOW_NAME_STR = 'htmlWindow'
   EDITABLE_LIST_BOX_NAME_STR = 'editableListBox'
   V_LIST_BOX_NAME_STR = 'wxVListBox'
+  ACTIVITY_INDICATOR_NAME_STR = 'activityindicator'
+  TIME_PICKER_CTRL_NAME_STR = 'timectrl'
+  DATE_PICKER_CTRL_NAME_STR = 'datectrl'
+  CALENDAR_NAME_STR = 'CalendarCtrl'
+  SPIN_BUTTON_NAME_STR = 'wxSpinButton'
 
   if Wx::PLATFORM == 'WXMSW'
     # wxMSW only
@@ -80,4 +86,17 @@ module Wx
   PROPERTY_GRID_NAME_STR = 'wxPropertyGrid'
   STC_NAME_STR = 'stcwindow'
 
+  # custom wxRuby addition
+  MEDIA_CTRL_NAME_STR = 'mediaCtrl'
+  SPIN_CTRL_NAME_STR = 'wxSpinCtrl'
+  SPIN_CTRL_DOUBLE_NAME_STR = 'wxSpinCtrlDouble'
+  SPLITTER_WINDOW_NAME_STR = 'splitter'
+  CHOICEBOOK_NAME_STR = 'choicebook'
+  LISTBOOK_NAME_STR = 'listbook'
+  TOOLBOOK_NAME_STR = 'toolbook'
+  TREEBOOK_NAME_STR = 'treebook'
+  SASH_WINDOW_NAME_STR = 'sashWindow'
+  SASH_LAYOUT_WINDOW_NAME_STR = 'layoutWindow'
+  SCROLLED_NAME_STR = 'SCROLLED_WINDOW'
+
 end

data/lib/wx/core/enum.rb

@@ -48,8 +48,24 @@ class Wx::Enum
     @value.hash
   end
 
+  def bitmask_to_s
+    return '' if to_i == 0
+    enums = []
+    mask = to_i
+    self.class.values.each_value do |enum|
+      if enum != 0 && mask.allbits?(enum)
+        enums << enum.to_s
+        mask &= ~enum
+        break if mask == 0
+      end
+    end
+    enums << mask.to_s if mask != 0
+    enums.join('|')
+  end
+  private :bitmask_to_s
+
   def to_s
-    to_i.to_s
+    self.class.values.has_key?(to_i) ? "#{self.class.name}::#{self.class.names_by_value[self]}" : bitmask_to_s
   end
 
 end

data/lib/wx/core/geometry.rb

@@ -0,0 +1,121 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+
+module Wx
+
+  def self.deg_to_rad(deg)
+    (deg * Math::PI) / 180.0
+  end
+
+  def self.rad_to_deg(rad)
+    (rad * 180.0) / Math::PI
+  end
+
+  class Point2DInt
+
+    alias :x :get_x
+    alias :x= :set_x
+    alias :y :get_y
+    alias :y= :set_y
+
+    # make wrappers private
+    private :add, :sub, :mul, :div
+
+    wx_assign = instance_method :assign
+    define_method :assign do |pt|
+      wx_assign.bind(self).call(pt)
+      self
+    end
+
+    def add!(pt)
+      add(pt)
+      self
+    end
+
+    def sub!(pt)
+      sub(pt)
+      self
+    end
+
+    def mul!(v)
+      mul(v)
+      self
+    end
+
+    def div!(v)
+      div(v)
+      self
+    end
+
+    def +(pt)
+      Point2DInt.new(self).add!(pt)
+    end
+
+    def -(pt)
+      Point2DInt.new(self).sub!(pt)
+    end
+
+    def *(v)
+      Point2DInt.new(self).mul!(v)
+    end
+
+    def /(v)
+      Point2DInt.new(self).div!(v)
+    end
+
+  end
+  class Point2DDouble
+
+    alias :x :get_x
+    alias :x= :set_x
+    alias :y :get_y
+    alias :y= :set_y
+
+    # make wrappers private
+    private :add, :sub, :mul, :div
+
+    wx_assign = instance_method :assign
+    define_method :assign do |pt|
+      wx_assign.bind(self).call(pt)
+      self
+    end
+
+    def add!(pt)
+      add(pt)
+      self
+    end
+
+    def sub!(pt)
+      sub(pt)
+      self
+    end
+
+    def mul!(v)
+      mul(v)
+      self
+    end
+
+    def div!(v)
+      div(v)
+      self
+    end
+
+    def +(pt)
+      Point2DDouble.new(self).add!(pt)
+    end
+
+    def -(pt)
+      Point2DDouble.new(self).sub!(pt)
+    end
+
+    def *(v)
+      Point2DDouble.new(self).mul!(v)
+    end
+
+    def /(v)
+      Point2DDouble.new(self).div!(v)
+    end
+
+  end
+end

data/lib/wx/core/graphics_pen_info.rb

@@ -0,0 +1,18 @@
+# Copyright (c) 2023 M.J.N. Corino, The Netherlands
+#
+# This software is released under the MIT license.
+# 
+# Some parts are
+# Copyright 2004-2007, wxRuby development team
+# released under the MIT-like wxRuby2 license
+
+class Wx::GraphicsPenInfo
+
+  # make Wx::GraphicsPenInfo#dashes return self
+  wx_dashes = instance_method :dashes
+  define_method :dashes do |*args|
+    wx_dashes.bind(self).call(*args)
+    self
+  end
+
+end

data/lib/wx/core/image.rb

@@ -108,6 +108,55 @@ module Wx
       hist_hash.extend Histogram
       hist_hash
     end
+
+    # import flattened nested classes
+    HSVValue = Wx::HSVValue
+    RGBValue = Wx::RGBValue
+
+  end
+
+  class HSVValue
+
+    # More informative output when converted to string
+    def to_s
+      "#<Wx::Image::HSVValue: (#{self.hue}, #{self.saturation}, #{self.value})>"
+    end
+
+    def inspect
+      to_s
+    end
+
+    # make HSVValue usable for parallel assignments like `x, y = pt`
+    def to_ary
+      [self.hue, self.saturation, self.value]
+    end
+
+    def to_rgb
+      Image::hsv_to_rgb(self)
+    end
+
+  end
+
+  class RGBValue
+
+    # More informative output when converted to string
+    def to_s
+      "#<Wx::Image::RGBValue: (#{self.red}, #{self.green}, #{self.blue})>"
+    end
+
+    def inspect
+      to_s
+    end
+
+    # make RGBValue usable for parallel assignments like `x, y = pt`
+    def to_ary
+      [self.red, self.green, self.blue]
+    end
+
+    def to_hsv
+      Image::rgb_to_hsv(self)
+    end
+
   end
 
   def self.Image(name, bmp_type = nil, *rest, art_path: nil, art_section: nil)

data/lib/wx/core/menu_bar.rb

@@ -12,6 +12,17 @@ class Wx::MenuBar
 
   def initialize(*args, &block)
     wx_initialize(*args)
+    if Wx::PLATFORM == 'WXOSX'
+      # OSX's standard Apple/Application menu gets titled with the executables name by default
+      # which is 'ruby' for wxRuby and this title is near impossible to reliably change.
+      # Therefor we implemented (a little stunted) workaround here to deal with Apple's crap.
+      # We insert a disabled item at the start of this menu with the AppDisplayName and follow
+      # it up with a nice separator. This way at least we will always be able to see which wxRuby
+      # app the visible menu belongs to.
+      apple_menu = osx_get_apple_menu
+      apple_menu.insert(0, Wx::ID_NONE, Wx.get_app.get_app_display_name).enable(false)
+      apple_menu.insert_separator(1)
+    end
     if block
       if block.arity == -1 or block.arity == 0
         self.instance_eval(&block)

data/lib/wx/core/paintdc.rb

@@ -6,10 +6,16 @@
 # Copyright 2004-2007, wxRuby development team
 # released under the MIT-like wxRuby2 license
 
-class Wx::PaintDC
+module Wx
+
+  class PaintDC
+
+    def self.draw_on(win, &block)
+      win.paint(&block) if block
+    end
 
-  def self.draw_on(win, &block)
-    win.paint(&block) if block
   end
 
+  AutoBufferedPaintDC = PaintDC.has_native_double_buffer ? Wx::PaintDC : Wx::BufferedPaintDC
+
 end