wxruby3 0.9.7 → 1.0.0

data/lib/wx/doc/extra/14_config.md

@@ -1,101 +0,0 @@
-<!--
-# @markup markdown
-# @title 14. Configuration support
--->
-
-# 14. Configuration support
-
-## Introduction
-
-wxRuby3 fully supports the wxWidgets config classes providing a Ruby-fied interface.
-
-The config classes provide a way to store some application configuration information providing features
-that make them very useful for storing all kinds of small to medium volumes of hierarchically-organized, 
-heterogeneous data.
-In wxWidgets these were especially designed for storing application configuration information and intended to be 
-mostly limited to that. That meant the information to be stored was intended to be:
-
-* Typed, i.e. strings, booleans or numbers for the moment. You cannot store binary data, for example.
-* Small. For instance, it is not recommended to use the Windows registry (which is the default storage medium on 
-  that platform) for amounts of data more than a couple of kilobytes.
-* Not performance critical, neither from speed nor from a memory consumption point of view.
-
-As you will see wxRuby3 extends the support in this area and provides means to forego a lot of these restrictions.
-
-The config classes also are intended to abstract away a lot of platform differences. In this area wxRuby3 extends the
-support also.
-
-## Default configuration support
-
-When the default, global, config instance is used (by using {Wx::ConfigBase.get} with default argument) this will be 
-a platform specific instance. On Windows platforms a Windows registry based implementation is used and on other 
-platforms a text format configuration file.
-
-wxRuby3 provides a single wrapper class for these with {Wx::ConfigWx}. This is an abstract class that cannot be 
-instantiated in Ruby which provides a common, Ruby-fied interface supported by all config classes in wxRuby3.
-
-While wxWidgets does a decent job of abstracting platform differences it is in no way perfect in this area. With the
-text format configuration files for example the stored values loose all type information since everything is stored
-as strings. This also differs from the registry based implementation where some type information is not lost but some
-(like boolean types) is.
-This is not a problem when accessing information for which the structure and types are exactly known as the config
-classes offer type specific readers (as well as writers) which coerce values to their expected types but may offer 
-nasty surprises when more reflectively accessing data of which the exact typing and structure is not known.
-
-In Ruby where we more or less expect to have common API-s that can return or accept any type of object needing to be
-type specific is awkward. wxRuby3 works around this as much as possible for the {Wx::ConfigWx} wrapper class but also
-provides an alternative config class integrated with the wxWidgets framework that does not suffer from these restrictions.
-
-## Enhanced Ruby configuration support
-
-Instead of the default, platform specific, config classes it is also possible to use a custom wxRuby3 extension providing
-a config class which is implemented in pure Ruby and integrated in the wxWidgets configuration framework.
-To use an instance of this class as the global config instance the {Wx::ConfigBase.create} should be called at application
-initialization time with it's `:use_hash_config` keyword argument set to `true` (and possibly, to be sure, it's 
-`forced_create` argument set to `true` also). This would create an instance of {Wx::Config} and install that as the global config instance (if no other instance was
-yet installed or, overruling that condition, if `forced_create` was set to `true`).<br>
-Alternatively a {Wx::Config} (or derivative) instance could be explicitly instantiated in code and assigned as global 
-instance with {Wx::ConfigBase.set}.
-
-As the keyword argument indicates {Wx::Config} is a Ruby `Hash` based config class implementation. 
-
-Value objects are stored Ruby-style as-is into it's internal hash table (maintaining full type information) and are also 
-retrieved as-is by default (to maintain compatibility with the {Wx::ConfigWx} wrapper type coercion options are provided). 
-Grouping is based of nested `Hash` instances.
-
-Because of the `Hash` based implementation and lack of (the need for) type coercion the {Wx::Config} class does have **any**
-restrictions of the type of data stored. The only possible type restrictions to enforce may come from usage contexts:
-
-* In case of value entries shared with wxWidgets framework code (like for example entries save by the persistence 
-framework; see [here](15_persistence.md)) value types should be restricted to those supported by the wxWidget platform
-specific classes and correspond to what the framework code expects.
-* In case of the need to save/restore the configuration data to/from persistent storage which imposes type restrictions these 
-should be applied.
-
-With {Wx::Config} it would be perfectly alright to store arrays or any kind of arbitrary object (only be aware that `Hash`
-instances will always be expected to provide configuration structure by default) as long as these do not conflict with
-expectations of framework code or storage mechanisms.
-
-With the standard Ruby YAML and JSON serialization support this also provides improved platform independent configuration 
-persistence options with full type information maintainability. 
-
-## Differences between default and enhanced configuration support
-
-The major difference is, as described above, the absence of type restrictions in the enhanced Ruby config class {Wx::Config}.
-
-Another difference is that {Wx::Config} will not automatically create missing groups or entries on reading. This will only
-happen when writing configuration values.
-
-A last difference is that the default support is by default backed up by persistent storage (windows registry or file) and
-the wxRuby enhanced support only provides in-memory storage (`Hash` instance) by default. +
-Persisting configuration data from {Wx::Config} will require coding customized storage and retrieval operations (which is
-trivial using standard YAML or JSON support).  
-
-## Differences between wxWidgets config interface and wxRuby
-
-In wxRuby there is no option to provide a default value argument when reading values. The reasoning is that Ruby itself
-provides more than enough options to elegantly provide for defaults with statement options like `var ||= default` or
-`var = get('something') || default`.
-
-As a consequence wxRuby also does not support recording defaults on read operations (and also does not provide the
-corresponding option setter/getter in the interface).

data/lib/wx/doc/extra/15_persistence.md

@@ -1,148 +0,0 @@
-<!--
-# @markup markdown
-# @title 15. Persistence support
--->
-
-# 15. Persistence support
-
-## Introduction
-
-wxRuby3 fully supports the wxWidgets persistence framework.
-
-This framework provides the means to persist window (and other object) states which can than be restored when
-re-creating these objects.
-
-The persistence framework depends on the configuration framework (see [here](14_config.md)).
-
-The persistence framework includes the following components:
-
-* {Wx::PersistenceManager} which all persistent objects register themselves with. This class handles actual saving 
-  and restoring of persistent data.
-* Persistent object adapters for persistent objects. These adapters provide a bridge between the associated class – 
-which has no special persistence support – and {Wx::PersistenceManager}. All Persistent object adapters need to derive 
-from {Wx::PersistentObject} (like {Wx::PersistentWindowBase} and it's derivatives).
-* The {Wx.create_persistent_object} and {Wx.persistent_register_and_restore} methods (mainly convenience methods for 
-wxWidgets compatibility).
-
-## Persistence manager
-
-By default a global singleton manager instance is available through {Wx::PersistenceManager.get} which will be used
-by all available persistent object adapters for saving/restoring state values.
-
-An alternate (possibly customized) manager instance can be installed through {Wx::PersistenceManager.set}.
-
-## Persistent object adapters
-
-All persistent object adapters must be derived from {Wx::PersistentObject}. This class provides common methods for
-saving and restoring state values connecting to the persistence manager for actual writing and reading.
-
-All windows/objects to be persisted need to be registered with the persistence manager. Creating the correct persistent
-object adapter instance for an object to persist is abstracted away in wxWidgets by using template methods allowing
-to simply only provide the object to persist instead of having to explicitly instantiate an adapter instance and provide
-both to the persistence manager (which is however still possible).
-
-wxRuby3 replaces this convenience interface (incompatible with Ruby) by a Ruby-fied approach which relies on Rubies 
-trusted *duck typing*.<br>
-In wxRuby3 any class supported by a specific persistent object adapter class should implement the method 
-`#create_persistent_object` which should return a unique adapter instance for the object instance to be persisted 
-like this:
-
-```ruby
-class MyPersistentObject < Wx::PersistentObject
-
-  # Save the object properties.
-  # The implementation of this method should use {Wx::PersistentObject#save_value}.
-  # @return [void]
-  def save
-    # ...
-  end
-
-  # Restore the object properties.
-  # The implementation of this method should use {Wx::PersistentObject#restore_value}.
-  # @return [Boolean]
-  def restore
-    # ...
-  end
-
-  # Returns the string uniquely identifying the objects supported by this adapter.
-  # This method has default implementations in any of the built-in derived adapter classes.
-  # @return [String]
-  def get_kind
-    'MyObject'
-  end
-
-  # Returns the string uniquely identifying the object we're associated with among all the other objects of the same type.
-  # This method has a default implementation in Wx::PersistentWindowBase returning the window name.
-  # @return [String]
-  def get_name
-    'object_1'
-  end
-
-end
-
-class MyObject
-  
-  # ...
-  
-  def create_persistent_object
-    MyPersistentObject.new(self)
-  end
-  
-  # ...
-  
-end
-```
-
-## Persistent windows
-
-A number of classes provide built-in support for persistence of a number of windows or controls:
-
-* {Wx::PersistentTLW} supports top level windows (including {Wx::Frame} and {Wx::Dialog}).
-* {Wx::PersistentBookCtrl} supports the book controls {Wx::Notebook}, {Wx::Listbook}, {Wx::Toolbook} and {Wx::Choicebook}.
-* {Wx::PersistentTreeBookCtrl} supports {Wx::Treebook}
-
-All persistent window adapters are derived from {Wx::PersistentWindowBase}. This class makes sure that any window 
-registered for persisting gets automatically saved when the window is destroyed. Intermittently explicit saving still
-remains possible of course.
-
-User defined persistent window adapters can be derived from this class or any of the built-in derivatives to support
-otherwise unsupported or custom windows/controls like this:
-
-```ruby
-class PersistentButton < Wx::PersistentWindowBase
-
-  def get_kind
-    'Button'
-  end
-    
-  def save
-    save_value('w', get.size.width)
-    save_value('h', get.size.height)
-    save_value('label', get.label)
-    save_value('my_custom_value', get.my_custom_value)
-  end
-    
-  def restore
-    get.size = [Integer(restore_value('w')), Integer(restore_value('h'))]
-    get.label = restore_value('label')
-    get.my_custom_value = Float(restore_value('my_custom_value'))
-    true
-  end
-
-end
-
-class MyButton < Wx::Button
-
-  def initialize(parent=nil, name)
-    super(parent, label: '', name: name)
-    @my_custom_value = ''
-  end
-
-  attr_accessor :my_custom_value
-
-  def create_persistent_object
-    PersistentButton.new(self)
-  end
-
-end
-```

data/rakefile

@@ -1,14 +0,0 @@
-###
-# wxRuby3 rake file
-# Copyright (c) M.J.N. Corino, The Netherlands
-###
-
-# Influential environment variables
-# WXRUBY_VERBOSE    : define verbosity for (rake) build scripts
-# WXRUBY_VERSION    : define the version info (x.x.x) for this tree
-# WXRUBY_EXCLUDED   : exclude certain classes from being compiled, even if present
-#
-# WXWIN             : install folder of wxWidgets library if not system default
-# WXXML             : folder containing doxygen generated wxWidgets XML interface specs if not using wxRuby bootstrap
-
-task :default => 'wxruby:help'

data/rakelib/lib/config/pkgman/arch.rb

@@ -1,53 +0,0 @@
-# Copyright (c) 2023 M.J.N. Corino, The Netherlands
-#
-# This software is released under the MIT license.
-
-###
-# wxRuby3 buildtools platform pkg manager for Arch Linux type systems
-###
-
-module WXRuby3
-
-  module Config
-
-    module Platform
-
-      module PkgManager
-
-        PLATFORM_DEPS = %w[pkg-config gtk3 webkit2gtk gspell libunwind gstreamer curl libsecret libnotify libpng12]
-
-        class << self
-
-          private
-
-          def do_install(distro, pkgs)
-            run_pacman(make_install_cmd(pkgs))
-          end
-
-          def add_platform_pkgs(pkgs)
-            if pkgs.include?('g++')
-              pkgs.delete('g++')
-              pkgs << 'gcc'
-            end
-            # find pkgs we need
-            PLATFORM_DEPS.inject(pkgs) { |list, pkg| list << pkg unless system("pacman -Qq #{pkg} >/dev/null 2>&1"); list }
-          end
-
-          def run_pacman(cmd)
-            run("pacman -q --noconfirm #{cmd}")
-          end
-
-          def make_install_cmd(pkgs)
-            # create install command
-            "-S --needed #{ pkgs.join(' ') }"
-          end
-
-        end
-
-      end
-
-    end
-
-  end
-
-end

data/rakelib/lib/config/pkgman/debian.rb

@@ -1,66 +0,0 @@
-# Copyright (c) 2023 M.J.N. Corino, The Netherlands
-#
-# This software is released under the MIT license.
-
-###
-# wxRuby3 buildtools platform pkg manager for Debian type systems
-###
-
-module WXRuby3
-
-  module Config
-
-    module Platform
-
-      module PkgManager
-
-        PLATFORM_DEPS = %w[libgtk-3-dev libwebkit2gtk-4.0-dev libgspell-1-dev libunwind-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libcurl4-openssl-dev libsecret-1-dev libnotify-dev]
-
-        class << self
-
-          private
-
-          def do_install(distro, pkgs)
-            run_apt(make_install_cmd(pkgs))
-          end
-
-          def add_platform_pkgs(pkgs)
-            # get architecture
-            arch = expand('dpkg --print-architecture').strip
-            # find pkgs we need
-            PLATFORM_DEPS.inject(pkgs) do |list, pkg|
-              list << pkg unless (system("dpkg-query -s \"#{pkg}:#{arch}\" >/dev/null 2>&1") ||
-                                    system("dpkg-query -s \"#{pkg}:all\" >/dev/null 2>&1") ||
-                                    (expand("dpkg-query -s \"#{pkg}\" 2>/dev/null").strip =~ /Architecture: (#{arch}|all)/))
-              list
-            end
-          end
-
-          def run_apt(cmd)
-            run("DEBIAN_FRONTEND=noninteractive apt-get -q -o=Dpkg::Use-Pty=0 #{cmd}")
-          end
-
-          def update_pkgs
-            run_apt('update')
-          end
-
-          def make_install_cmd(pkgs)
-            # update cache
-            update_pkgs
-            # get list of available packages
-            apt_cache = `apt-cache pkgnames`.chomp.split("\n").collect { |s| s.strip }
-            # remove un-installables
-            pkgs = pkgs.select { |pkg| apt_cache.include?(pkg) }
-            # create install command
-            "install -y #{ pkgs.join(' ') }"
-          end
-
-        end
-
-      end
-
-    end
-
-  end
-
-end

data/rakelib/lib/config/pkgman/rhel.rb

@@ -1,54 +0,0 @@
-# Copyright (c) 2023 M.J.N. Corino, The Netherlands
-#
-# This software is released under the MIT license.
-
-###
-# wxRuby3 buildtools platform pkg manager for RHEL type systems
-###
-
-module WXRuby3
-
-  module Config
-
-    module Platform
-
-      module PkgManager
-
-        PLATFORM_DEPS = %w[expat-devel findutils gspell-devel gstreamer1-plugins-base-devel gtk3-devel libcurl-devel libjpeg-devel libnotify-devel libpng-devel libSM-devel libsecret-devel libtiff-devel SDL-devel webkit2gtk4.1-devel zlib-devel]
-
-        class << self
-
-          private
-
-          def do_install(distro, pkgs)
-            run_dnf(make_install_cmd(pkgs))
-          end
-
-          def add_platform_pkgs(pkgs)
-            # add build tools
-            if pkgs.include?('git')
-              pkgs.delete('git')
-              pkgs << 'git-core'
-            end
-            # find pkgs we need
-            PLATFORM_DEPS.inject(pkgs) { |list, pkg| list << pkg unless system("dnf list installed #{pkg} >/dev/null 2>&1"); list }
-          end
-
-          def run_dnf(cmd)
-            run("dnf #{cmd}")
-          end
-
-          def make_install_cmd(pkgs)
-            # create install command
-            "install -y #{ pkgs.join(' ') }"
-          end
-
-        end
-
-      end
-
-    end
-
-  end
-
-end

data/rakelib/lib/config/pkgman/suse.rb

@@ -1,54 +0,0 @@
-# Copyright (c) 2023 M.J.N. Corino, The Netherlands
-#
-# This software is released under the MIT license.
-
-###
-# wxRuby3 buildtools platform pkg manager for SuSE type systems
-###
-
-module WXRuby3
-
-  module Config
-
-    module Platform
-
-      module PkgManager
-
-        PLATFORM_DEPS = %w[gtk3-devel webkit2gtk3-devel gspell-devel gstreamer-devel gstreamer-plugins-base-devel libcurl-devel libsecret-devel libnotify-devel libSDL-devel zlib-devel libjpeg-devel libpng-devel]
-
-        class << self
-
-          private
-
-          def do_install(distro, pkgs)
-            run_zypper(make_install_cmd(pkgs))
-          end
-
-          def add_platform_pkgs(pkgs)
-            # add build tools
-            if pkgs.include?('g++')
-              pkgs.delete('g++')
-              pkgs << 'gcc-c++'
-            end
-            # find pkgs we need
-            PLATFORM_DEPS.inject(pkgs) { |list, pkg| list << pkg unless system("rpm -q --whatprovides #{pkg} >/dev/null 2>&1"); list }
-          end
-
-          def run_zypper(cmd)
-            run("zypper -t -i #{cmd}")
-          end
-
-          def make_install_cmd(pkgs)
-            # create install command
-            "install -y #{ pkgs.join(' ') }"
-          end
-
-        end
-
-      end
-
-    end
-
-  end
-
-end

data/samples/sampler/back.xpm

@@ -1,21 +0,0 @@
-/* XPM */
-static const char *const back_xpm[] = {
-"16 15 3 1",
-" 	c None",
-".	c Black",
-"X	c Gray100",
-"                ",
-"                ",
-"      .         ",
-"     ..         ",
-"    .X.         ",
-"   .XX........  ",
-"  .XXXXXXXXXX.  ",
-" .XXXXXXXXXXX.  ",
-" .XXXXXXXXXXX.  ",
-"  .XXXXXXXXXX.  ",
-"   .XX........  ",
-"    .X.         ",
-"     ..         ",
-"      .         ",
-"                "};

data/samples/sampler/copy.xpm

@@ -1,44 +0,0 @@
-/* XPM */
-static const char *const copy_xpm[] = {
-/* columns rows colors chars-per-pixel */
-"16 15 23 1",
-"o c #97C4E7",
-"* c #FFFFFF",
-"@ c #60A9DA",
-"= c #D1E5F5",
-"& c #C3DDF1",
-". c #7EA6C0",
-"  c None",
-"X c #2F93CD",
-"O c #85BBE2",
-", c #EFF6FC",
-"; c #DEEDF8",
-"+ c #72B2DD",
-"3 c #F7FBFD",
-"4 c #FAFCFE",
-": c #DAEAF7",
-"< c #E9F3FA",
-"1 c #E2EFF8",
-"- c #FDFDFE",
-"% c #B6D5EE",
-"$ c #A5CCEA",
-"> c #E5F0F9",
-"# c #AFD1EC",
-"2 c #F4F9FD",
-/* pixels */
-" .....XX        ",
-" .oO+@X#X       ",
-" .$oO+X##X      ",
-" .%$o........   ",
-" .&%$.*=&#o.-.  ",
-" .=&%.*;=&#.--. ",
-" .:=&.*>;=&.... ",
-" .>:=.*,>;=&#o. ",
-" .<1:.*2,>:=&#. ",
-" .2<1.*32,>:=&. ",
-" .32<.*432,>:=. ",
-" .32<.*-432,>:. ",
-" .....**-432,>. ",
-"     .***-432,. ",
-"     .......... "
-};

data/samples/sampler/cut.xpm

@@ -1,46 +0,0 @@
-/* XPM */
-static const char *const cut_xpm[] = {
-/* columns rows colors chars-per-pixel */
-"16 15 25 1",
-"6 c #D8BDC0",
-": c #C3C3C4",
-"- c #FFFFFF",
-". c #6C6D70",
-"2 c #AD3A45",
-"o c #DBDBDB",
-"# c #939495",
-"< c #E42234",
-"& c #C3C5C8",
-"; c #C6CCD3",
-"% c #B7B7B8",
-"  c None",
-"* c #DFE0E2",
-"5 c #B69596",
-"3 c #9C2A35",
-"1 c #CFCFD0",
-", c #AB5C64",
-"+ c #D2D3D4",
-"$ c #BCBDBE",
-"@ c #C6C8CA",
-"> c #CDC0C1",
-"O c #826F72",
-"X c #979BA0",
-"4 c #9B8687",
-"= c #9FA0A0",
-/* pixels */
-"   .X     .o    ",
-"   O.+   @.     ",
-"    O.   ..     ",
-"    O#$ %.&     ",
-"     O.*..      ",
-"     #%#..      ",
-"     O=-..      ",
-"     #%#;.      ",
-"     OO:=O      ",
-"  >,,<, ,<,,1   ",
-" ><23<1 1<32<1  ",
-" ,2 4<   <5 2,  ",
-" <, ,2   2, ,<  ",
-" 23,<5   5<,32  ",
-" 6225     522>  "
-};

data/samples/sampler/filesave.xpm

@@ -1,42 +0,0 @@
-/* XPM */
-static const char *const filesave_xpm[] = {
-/* columns rows colors chars-per-pixel */
-"16 15 21 1",
-"O c #FFFFFF",
-"> c #D5D6D8",
-"; c #446A8C",
-"1 c #CAD2DC",
-": c #C0C7D1",
-"  c #5F666D",
-"% c #A5B0BA",
-"o c #65839D",
-", c #DCE2EA",
-"< c #C3C5C8",
-"- c #E1E6EE",
-"* c #C6CCD3",
-". c None",
-"$ c #305F81",
-"2 c #D6DFE7",
-"= c #D2D9E0",
-"& c #B7BFC7",
-"X c #1B4467",
-"# c #BCBDBE",
-"@ c #7A90AC",
-"+ c #5D7C93",
-/* pixels */
-"               .",
-" XoOOOOOOOOO+X .",
-" @oO#######O+@ .",
-" @oOOOOOOOOO+@ .",
-" @oO#######O+@ .",
-" @oOOOOOOOOO+@ .",
-" @@+++++++++@@ .",
-" @@@@@@@@@@@@@ .",
-" @@@$$$$$$$$@@ .",
-" @@$%%%&*=-O$@ .",
-" @@$%X;;*=-O$@ .",
-" @@$%X;;:>,O$@ .",
-" @@$%X;;<12O$@ .",
-" @@$<<2OOOOO$@ .",
-".             .."
-};