diff --git a/INSTALL.md b/INSTALL.md
index 1cbf73a1..1b0f9877 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -225,7 +225,7 @@ Two options are available to control the wxRuby3 gem installation process.
#### The `prebuilt` option
-The `prebuilt=none|only|head` option can be used to either prevent binary package matching and installation (`prebuilt=none`)
+The `prebuilt=none|only` option can be used to either prevent binary package matching and installation (`prebuilt=none`)
or make binary package installation mandatory (`prebuilt=only`).
The following command therefor forces a wxRuby3 source installation and will never fail:
@@ -240,15 +240,6 @@ And the following command will force binary package installation and fails if no
gem install wxruby3 -- prebuilt=only
```
-It is also possible to specify installing the, experimental, head (master) wxWidgets binary package version (`prebuilt=head`).
-This package version may not be as readily available as regular release packages depending on the development state of the
-wxWidgets master branch.
-
-> **NOTE**
-> Although wxRuby3 endeavors to keep up to date with the wxWidgets master branch your mileage may vary. Any release
-> binary 'head' package should have basic stability at least but will not have been as extensively tested as regular
-> release packages.
-
#### The `package` option
The `package=URL` option can be used to explicitly specify a binary package to install. This option implies `prebuilt=only`.
@@ -517,6 +508,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).
diff --git a/README.md b/README.md
index 3ccc4850..09695bc8 100644
--- a/README.md
+++ b/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'
@@ -177,13 +178,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
diff --git a/ext/mkrf_conf_ext.rb b/ext/mkrf_conf_ext.rb
index 4d6112ef..4625eaf1 100644
--- a/ext/mkrf_conf_ext.rb
+++ b/ext/mkrf_conf_ext.rb
@@ -24,7 +24,7 @@
options:
- prebuilt=OPT Specifies to either require (OPT == 'only' | 'head') or avoid (OPT == 'none') installing prebuilt
+ prebuilt=OPT Specifies to either require (OPT == 'only') or avoid (OPT == 'none') installing prebuilt
binary packages. If not specified installing a prebuilt package will be attempted reverting
to source install if none found.
@@ -48,8 +48,6 @@
task_args << "'--prebuilt'"
when :none
task_args << "'--no-prebuilt'"
- when :head
- task_args << "'--prebuilt'" << "'head'"
end
end
if OPTIONS[:package]
diff --git a/lib/wx/core/app.rb b/lib/wx/core/app.rb
index d334d701..dca84879 100644
--- a/lib/wx/core/app.rb
+++ b/lib/wx/core/app.rb
@@ -14,6 +14,22 @@
# 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
diff --git a/lib/wx/doc/app.rb b/lib/wx/doc/app.rb
index 3c9c35b3..61d28a0f 100644
--- a/lib/wx/doc/app.rb
+++ b/lib/wx/doc/app.rb
@@ -9,47 +9,79 @@ module Wx
class App
- # Set the menu item id for the About menu item.
- # Default is {Wx::ID_ABOUT}
- # @param [Integer] id
- # @wxrb_require WXOSX
- def set_mac_about_menu_itemid(id) end
- alias :mac_about_menu_itemid= :set_mac_about_menu_itemid
-
- # Get the current menu item id for the About menu item.
- # Default is {Wx::ID_ABOUT}
- # @return [Integer]
- # @wxrb_require WXOSX
- def get_mac_about_menu_itemid(id) end
- alias :mac_about_menu_itemid :get_mac_about_menu_itemid
-
- # Set the menu item id for the Preferences menu item.
- # Default is {Wx::ID_PREFERENCES}
- # @param [Integer] id
- # @wxrb_require WXOSX
- def set_mac_preferences_menu_itemid(id) end
- alias :mac_preferences_menu_itemid= :set_mac_preferences_menu_itemid
-
- # Get the current menu item id for the Preferences menu item.
- # Default is {Wx::ID_PREFERENCES}
- # @return [Integer]
- # @wxrb_require WXOSX
- def get_mac_preferences_menu_itemid(id) end
- alias :mac_preferences_menu_itemid :get_mac_preferences_menu_itemid
-
- # Set the menu item id for the Exit menu item.
- # Default is {Wx::ID_EXIT}
- # @param [Integer] id
- # @wxrb_require WXOSX
- def set_mac_exit_menu_itemid(id) end
- alias :mac_exit_menu_itemid= :set_mac_exit_menu_itemid
-
- # Get the current menu item id for the Exit menu item.
- # Default is {Wx::ID_EXIT}
- # @return [Integer]
- # @wxrb_require WXOSX
- def get_mac_exit_menu_itemid(id) end
- alias :mac_exit_menu_itemid :get_mac_exit_menu_itemid
+ class << self
+
+ # Set the menu item id for the About menu item.
+ # Default is {Wx::ID_ABOUT}
+ # @param [Integer] id
+ # @wxrb_require WXOSX
+ def set_mac_about_menu_itemid(id) end
+ alias :mac_about_menu_itemid= :set_mac_about_menu_itemid
+
+ # Get the current menu item id for the About menu item.
+ # Default is {Wx::ID_ABOUT}
+ # @return [Integer]
+ # @wxrb_require WXOSX
+ def get_mac_about_menu_itemid; end
+ alias :mac_about_menu_itemid :get_mac_about_menu_itemid
+
+ # Set the menu item id for the Preferences menu item.
+ # Default is {Wx::ID_PREFERENCES}
+ # @param [Integer] id
+ # @wxrb_require WXOSX
+ def set_mac_preferences_menu_itemid(id) end
+ alias :mac_preferences_menu_itemid= :set_mac_preferences_menu_itemid
+
+ # Get the current menu item id for the Preferences menu item.
+ # Default is {Wx::ID_PREFERENCES}
+ # @return [Integer]
+ # @wxrb_require WXOSX
+ def get_mac_preferences_menu_itemid; end
+ alias :mac_preferences_menu_itemid :get_mac_preferences_menu_itemid
+
+ # Set the menu item id for the Exit menu item.
+ # Default is {Wx::ID_EXIT}
+ # @param [Integer] id
+ # @wxrb_require WXOSX
+ def set_mac_exit_menu_itemid(id) end
+ alias :mac_exit_menu_itemid= :set_mac_exit_menu_itemid
+
+ # Get the current menu item id for the Exit menu item.
+ # Default is {Wx::ID_EXIT}
+ # @return [Integer]
+ # @wxrb_require WXOSX
+ def get_mac_exit_menu_itemid; end
+ alias :mac_exit_menu_itemid :get_mac_exit_menu_itemid
+
+ # Set the menu title for the Help menu.
+ # Default is '&Help'
+ # @param [String] title
+ # @wxrb_require WXOSX
+ def set_mac_help_menu_title(title) end
+ alias :mac_help_menu_title= :set_mac_help_menu_title
+
+ # Get the current title for the Help menu.
+ # Default is '&Help'
+ # @return [String]
+ # @wxrb_require WXOSX
+ def get_mac_help_menu_title; end
+ alias :mac_help_menu_title :get_mac_help_menu_title
+
+ # Set the menu title for the Window menu.
+ # Default is '&Window'
+ # @param [String] title
+ # @wxrb_require WXOSX
+ def set_mac_window_menu_title(title) end
+ alias :mac_window_menu_title= :set_mac_window_menu_title
+
+ # Get the current title for the Window menu.
+ # Default is '&Window'
+ # @return [String]
+ # @wxrb_require WXOSX
+ def get_mac_window_menu_title; end
+ alias :mac_window_menu_title :get_mac_window_menu_title
+
+ end
end
diff --git a/lib/wx/doc/extra/00_starting.md b/lib/wx/doc/extra/00_starting.md
deleted file mode 100644
index 004a20a2..00000000
--- a/lib/wx/doc/extra/00_starting.md
+++ /dev/null
@@ -1,154 +0,0 @@
-
-
-# 0. Overview of wxRuby
-
-## What is wxRuby?
-
-wxRuby3 is a cross-platform GUI library for Ruby, based on the popular [wxWidgets](https://wxwidgets.org)
-cross platform GUI toolkit for C++. It uses native widgets wherever possible, providing
-the correct look, feel and behaviour to GUI applications on Windows, OS
-X and Linux/GTK. wxRuby aims to provide a comprehensive solution to
-developing professional-standard desktop applications in Ruby.
-
-Like Ruby and wxWidgets, wxRuby is Open Source, which means that it is free for anyone to use and the source code
-is available for anyone to look at and use in any way they like. Also, anyone can contribute (tested) fixes, additions
-and enhancements to the project.
-
-Like wxWidgets wxRuby is a cross platform toolkit. This means that the same program will run on multiple platforms
-without modification. Currently Supported platforms are Microsoft Windows, MacOSX and Linux or other
-unix-like systems with GTK2 or GTK3 libraries. Contributions to achieve support for other wxWidgets supported platforms
-are appreciated.
-
-Since the programming language is Ruby, wxRuby programs are simple and easy to write and understand. To accomplish the
-full Ruby experience wxRuby has not ported the wxWidgets API 1 on 1 to Ruby but has made an effort to make the wxRuby
-API typically Ruby-ish. This means all method signatures (names, arguments) have been transformed to conform to common
-Ruby naming rules as well as other Ruby programming practices. Also does wxRuby introduce iterators in favor of getters
-returning arrays or lists.
-Check out the samples and the documentation for details.
-
-## What is wxRuby3?
-
-The wxRuby3 project is a new, rebooted, implementation of wxRuby (as compared to wxRuby2 and earlier versions) with the
-clear intent to make this implementation better maintainable and extensible.
-
-To this end wxRuby3 adopted much of the approach of the wxPython Phoenix project in that the wxRuby API is generated
-from the wxWidgets XML interface definitions. Unlike the Phoenix project however, wxRuby does not use a home-grown
-interface code generator but rather still relies on SWIG for that (with Ruby tooling to configure and post-process).
-The wxRuby generation process more or less conforms to:
-
-1. build wxWidgets interface XML
-2. parse interface XML
-3. generate SWIG interface definitions
-4. generate Ruby extension code with SWIG
-5. post-process Ruby extension code
-
-As the wxRuby tooling is already parsing the full wxWidgets interface specs (from which wxWidgets generates it's own
-reference documentation) it also uses the parsed information to generate matching reference documentation for the
-wxRuby API. This documentation is not (yet) perfect but should go a long way in helping people using wxRuby to build
-GUI applications.
-
-The wxRuby3 API is largely compatible with the earlier wxRuby incarnations but not 100% mostly due to more
-modularization and more explicit typing of (especially) enums. Also wxRuby3 exclusively targets a lot more modern
-versions of wxWidgets (>= 3.2) and Ruby (>= 2.5) so there are some shifts from that as well. All in all though,
-people that once took a stab at looking at wxRuby(2) should not have much problems getting up to speed again.
-
-## Quick start
-
-To create an application with wxRuby you need to require the wxRuby libraries:
-
-```ruby
-require 'wx'
-```
-
-Next would be the application code and a main entry point. With wxRuby (as with wxWidgets) the entry
-point is mostly just a simple call to start the applications event loop (as we're talking about event
-based GUI applications here).
-In wxRuby the Wx::App class provides some typically Ruby-style magic to make this as easy as possible.
-
-Using this the simplest Hello World application could be:
-
-```ruby
-require 'wx'
-Wx::App.run { puts 'Hello world!' }
-```
-
-As you can see there is no obligation to create an instance of the Wx::App class in wxRuby for
-(admittedly extremely) simple applications. Calling the #run class method with a block will suffice.
-The class method will create an instance of the generic Wx::App class under the hood and use the
-provided block as the #on_init callback. As the code inside the block returns a false-type value (#puts
-returns `nil`) the application will terminate immediately after writing "Hello world!" to standard
-output (actually not even starting the event loop at all).
-
-Of course this is not truly a GUI application so let's elaborate a little to make the GUI element
-more real.
-
-```ruby
-require 'wx'
-Wx::App.run { Wx::Frame.new(nil, title: 'Hello World!').show }
-```
-
-Executing this will create a generic Frame instance in the on_init callback of the application
-and show the frame. As #show returns a true-type when successful the event loop will actually be
-started and keep the application running until the frame is closed.
-
-## The application class
-
-For more complex applications the approach demonstrated above will quickly become insufficient. In those cases
-creating a specialized derived App class is the better option.
-This provides the possibility (as with all Ruby classes) to override the constructor (#initialize) for
-custom initialization, attribute definitions and create customized #on_init and/or #on_exit methods like
-this:
-
-```ruby
-require 'wx'
-
-class MyApp < Wx::App
- def initialize
- super
- @frame = nil
- end
- attr_reader :frame
-
- def on_init
- @frame = Wx::Frame.new(nil, title: 'Hello World!')
- @frame.show
- end
-
- def on_exit
- puts 'Exiting.'
- end
-end
-```
-
-When creating #on_init/#on_exit methods it is important to understand that those would not be overrides (as is the case
-with wxWidgets itself). The base Wx::App class actually does not define these methods so it's also not needed (even not possible)
-to call `super` in the implementation. The wxRuby application class implementation will call the wxWidget OnInit base implementation
-itself and after successful completion check for the existence of an #on_init method (which could also be 'automagicallly'
-created from a block passed to #run) and call that if available or terminate the application if not. The
-exit sequence of executions are similar but reversed (first a possible #on_exit method and than the wxWidgets base OnExit).
-
-What remains though is that for a derived application class it is still not necessary to explicitly create a class instance.
-Simply calling the #run class method will suffice.
-
-```ruby
-MyApp.run
-```
-
-The current application instance (as long as the application is active) can always be retrieved by
-calling `Wx.get_app`.
-
-## wxRuby modules
-
-The toplevel module of the wxRuby library is the `Wx` module and when using `require 'wx'` to load the wxRuby library
-**all** constants and classes are loaded and can be accessed from that scope like `Wx::Frame` or `Wx::RichTextCtrl`
-like previous versions of wxRuby supported.
-
-With the current wxRuby library however a more modular approach has been used similar to wxWidgets itself which
-distributes implementations over various sub-modules. These sub-modules can be loaded separately to provide more control.
-The core module still provides the toplevel `Wx` namespace and all classes and constants declared in that namespace.
-All other modules add to that (and **all** require the core module).
-
-See [here](01_packages.md) for more details on wxRuby sub-modules.
diff --git a/lib/wx/doc/extra/01_packages.md b/lib/wx/doc/extra/01_packages.md
deleted file mode 100644
index fe43aa1b..00000000
--- a/lib/wx/doc/extra/01_packages.md
+++ /dev/null
@@ -1,180 +0,0 @@
-
-
-# 1. wxRuby Modules
-
-## Introduction
-
-Previous wxRuby implementations provided a single toplevel module approach for the wxRuby API with a single loading
-option. Including `require 'wx'` in any application would load the entire wxRuby library and make all classes, module
-methods and constants available under the `Wx` toplevel module.
-
-The wxRuby3 project however implements a more modular approach similar to wxWidgets itself which distributes
-implementations over various sub-modules. These sub-modules can be loaded separately to provide more control.
-The core module still provides the toplevel `Wx` namespace and all classes and constants declared in that namespace.
-All other modules add to that (and **all** require the core module).
-
-## Loading and Naming scopes
-
-The *old* **all-in-one** approach in still supported with the wxRuby3 project. Using
-
-```ruby
-require 'wx'
-```
-
-will load all wxRuby API modules and make all classes and constants available from the `Wx` toplevel module. This
-*global* naming scope approach does **not** extend to class or module methods (including dialog *functors*; see
-[here](03_dialogs.md) for more information).
-
-The *new* sub-module approach however allows for loading only part(s) of the wxRuby library like:
-
-```ruby
-require 'wx/core' # load wxRuby core Wx module
-require 'wx/grid' # load wxRuby Wx::GRID module - provides Grid control
-require 'wx/rtc' # load wxRuby Wx::RTC module - provides RichText control
-```
-
-However, when loading the library like this scoping rules change by default. Specifically the constants and classes
-from the loaded sub-modules will **not** be accessible from the `Wx` scope anymore (like `Wx::Grid`) but must instead be
-explicitly scoped from the sub-module (like `Wx::GRID::Grid`).
-
-It is possible to revert the 'global scope' resolution behaviour by setting the toplevel constant `WX_GLOBAL_CONSTANTS` to
-`true` before the require statements like:
-
-```ruby
-WX_GLOBAL_CONSTANTS=true
-require 'wx/core' # load wxRuby core Wx module
-require 'wx/grid' # load wxRuby Wx::GRID module - provides Grid control
-require 'wx/rtc' # load wxRuby Wx::RTC module - provides RichText control
-```
-
-## Modules
-
-Currently the following modules have been implemented.
-
-### Core
-
-The core wxRuby package providing the toplevel {Wx} module.
-This package includes basic classes like:
-
-- {Wx::Object}
-- {Wx::EvtHandler}
-- {Wx::Event}
-- {Wx::CommandEvent}
-- {Wx::App}
-- {Wx::Window}
-- {Wx::NonOwnedWindow}
-- {Wx::TopLevelWindow}
-- {Wx::Frame}
-- {Wx::Dialog}
-
-as well as most common window classes, control/widget classes, event classes, constant and enum definitions
-and global functions not part of any of the other packages.
-
-### AUI - Advanced User Interface controls and related classes
-
-The wxRuby AUI package providing the {Wx::AUI} module.
-This package includes all classes, constants and enum definitions that are considered part of the
-wxWidgets AUI framework like:
-
-- {Wx::AUI::AuiManager}
-- {Wx::AUI::AuiMDIParentFrame}
-- {Wx::AUI::AuiMDIChildFrame}
-- {Wx::AUI::AuiMDIClientWindow}
-- etc
-
-### GRID - Grid control and related classes
-
-The wxRuby GRID package providing the {Wx::GRID} module.
-This package includes all classes, constants and enum definitions that are associated with the
-wxWidgets wxGrid control like:
-
-- {Wx::GRID::Grid}
-- {Wx::GRID::GridTableBase}
-- {Wx::GRID::GridCellEditor}
-- {Wx::GRID::GridCellRenderer}
-- {Wx::GRID::GridEvent}
-- etc
-
-### HTML - Html framework classes
-
-The wxRuby HTML package providing the {Wx::HTML} module.
-This package includes all classes, constants and enum definitions that are considered part of the
-wxWidgets Html framework like:
-
-- {Wx::HTML::HtmlWindow}
-- {Wx::HTML::HtmlHelpWindow}
-- {Wx::HTML::HtmlPrintout}
-- {Wx::HTML::HtmlHelpController}
-- {Wx::HTML::HtmlListBox}
-- etc
-
-### PG - PropertyGrid control and related classes
-
-The wxRuby PG package providing the {Wx::PG} module.
-This package includes all classes, constants and enum definitions that are associated with the
-wxWidgets wxPropertyGrid control like:
-
-- {Wx::PG::PropertyGrid}
-- {Wx::PG::PropertyGridManager}
-- {Wx::PG::PGCell}
-- {Wx::PG::PGProperty}
-- {Wx::PG::PropertyGridEvent}
-- etc
-
-### PRT - Printing framework classes
-
-The wxRuby PRT package providing the {Wx::PRT} module.
-This package includes all classes, constants and enum definitions that are considered part of the
-wxWidgets Printing framework like:
-
-- {Wx::PRT::PreviewFrame}
-- {Wx::PRT::Printer}
-- {Wx::PRT::PrinterDC}
-- {Wx::PRT::PrintDialog}
-- etc
-
-### RBN - Ribbon framework classes
-
-The wxRuby RBN package providing the {Wx::RBN} module.
-This package includes all classes, constants and enum definitions that are considered part of the
-wxWidgets Ribbon framework like:
-
-- {Wx::RBN::RibbonControl}
-- {Wx::RBN::RibbonGallery}
-- {Wx::RBN::RibbonPanel}
-- {Wx::RBN::RibbonPage}
-- {Wx::RBN::RibbonBar}
-- etc
-
-### RTC - RichText control and related classes
-
-The wxRuby RTC package providing the {Wx::RTC} module.
-This package includes all classes, constants and enum definitions that are associated with the
-wxWidgets wxRichTextCtrl control like:
-
-- {Wx::RTC::RichTextCtrl}
-- {Wx::RTC::RichTextEvent}
-- {Wx::RTC::RichTextBuffer}
-- etc
-
-### STC - StyledText control and related classes
-
-The wxRuby STC package providing the {Wx::STC} module.
-This package includes all classes, constants and enum definitions that are associated with the
-wxWidgets wxStyledTextCtrl control (Scintilla integration) like:
-
-- {Wx::STC::StyledTextCtrl}
-- {Wx::STC::StyledTextEvent}
-
-## Feature dependencies
-
-Availability of wxRuby packages is controlled by the wxWidget feature switches. The default build options will
-include all platform supported features but in case of building wxRuby for customized wxWidgets builds the wxRuby3
-build procedures will take the wxWidgets settings into account.
-
-If for instance wxWidgets was built without Html support (using the configure `--disable-html` switch) the wxRuby
-HTML package will not be available as well.
-This behavior is controlled by the `wxUSE_xxx` macros that wxRuby extracts from the wxWidgets `wx/setup.h` file.
diff --git a/lib/wx/doc/extra/02_lifecycles.md b/lib/wx/doc/extra/02_lifecycles.md
deleted file mode 100644
index 30ce8ae2..00000000
--- a/lib/wx/doc/extra/02_lifecycles.md
+++ /dev/null
@@ -1,166 +0,0 @@
-
-
-# 2. wxRuby Life Cycles
-
-## Introduction
-
-Managing the life cycles of native objects in Ruby extension libraries is tricky business because of the disparity
-between common C++ dynamic memory management and the GC management scheme of the Ruby language and this certainly applies
-to an event based environment like the wxRuby extension for wxWidgets.
-That said, the wxRuby library should provide you with a fairly worry-free API in that respect.
-
-The wxRuby extension manages to provide water-tight GC management for just about all mapped wxWidget objects.
-
-There are just a few, fairly specific, things to take notice of.
-
-## Application instance
-
-Any wxWidgets application typically creates a single application instance and the same goes for wxRuby applications.
-We already saw [here](00_starting.md) how to start a wxRuby application. Important to note is that any reference to the
-(global) application instance will ever only be valid as long as the application is still active.
-In essence this means the reference is valid from the moment the constructor (`#initialize`) is called to the moment
-any available `#on_exit` method has finished.
-
-There are some caveats to that however.
-
-1. Although the application instance is valid in the constructor, the wxWidgets
-framework will only be fully initialized the moment the `#on_init` method starts. This means that all kinds of methods
-requiring initialized GUI resources (like window creation) will fail if called before that moment.
-
-2. The global application instance returned by `Wx.get_app` will only be set from the moment the `#on_init` method
-starts to the moment the `#on_exit` method finishes. Outside that timespan the method will return `nil`.
-
-Also be careful with storing your own application instance variables. Code like
-
-```ruby
-class MyApp < Wx::App
- def initialize
- super
- # ...
- end
- def on_init
- # ...
- end
-end
-$app = MyApp.new
-$app.run
-```
-
-is entirely valid but for the fact that you **should** remember that after the `#run` method returns the `$app` variable
-does **not** reference a valid application instance anymore. Calling methods on that instance may result in unexpected
-behavior.
-It is actually easier and safer to rewrite this code as:
-
-```ruby
-class MyApp < Wx::App
- def initialize
- super
- # ...
- end
- def on_init
- # ...
- end
-end
-MyApp.run # or MyApp.new.run
-```
-
-This way there is no reference to accidentally use after `#run` returns and `Wx.get_app` will return `nil` after that
-moment.
-
-## Framework (re-)initialization
-
-As mentioned above the wxWidgets GUI framework resources will only be fully initialized after the `#on_init` method
-starts. Likewise the framework resources will be de-initialized (deleted) after `#on_exit` method ends which means that
-your application should not attempt to access any of these resources (windows, fonts, colours etc.) after that moment.
-
-Also, largely because of the way the wxWidgets framework is designed but also because of the way this meshes with Ruby
-GC, there is no safe way to re-initialize the framework after an application instance ends it run. This means you
-**cannot** safely attempt to start another application instance after a previous (first) one has ended.
-
-## Windows
-
-Window instances (and it's derivatives) are fully managed by the wxWidget framework and cannot (are not) managed by
-Ruby GC handling. This means on the one hand that a window instances life time is not controlled by any reference
-a Ruby variable may hold and on the other hand that the Ruby object linked to that native window object is kept alive
-(marked in GC) as long as the window instance is alive.
-Generally speaking window lifetimes are dependent on the (toplevel) window (or it's parent) being closed. In case of a
-toplevel window this result in automatic destruction of the window and all it's child windows (controls). There are
-however exceptions to this where explicit calling of a window's `#destroy` method is required to prevent memory leaks
-(when a window is not a child window but also not a toplevel window for example or in case of dialogs; see
-[here](03_dialogs.md)). Please check out the wxWidgets documentation for more detailed information.
-
-This has several consequences you need to be aware of.
-
-First of, in cases where you keep a reference to any window (control) instance in a local or instance variable in Ruby
-(which is fairly common practice) you need to be aware that the reference is only valid as long as the window has not
-been destroyed. In most cases this will not be an issue as most references are kept as instance variables of parent
-windows for child windows where the instance variables will only ever be used as long the parent window is alive itself.
-In other circumstances you should take care to track the lifetime of the window that is referenced.
-
-Secondly, as already indicated above not all window instances will be automatically destroyed. It is for example fairly
-common in more complex applications to create and show other windows as response to events triggered in the toplevel
-window. These windows will not (and should not) be automatically designated as toplevel window but they are also not
-owned (i.e. not child windows). Closing these windows will not automatically destroy them (which is a good thing as
-these are often re-shown after renewed events from the toplevel window) and will also not be automatically destroyed
-when any parent window is destroyed. This means they pose a threat for potential memory leaks.
-In case it concerns a fairly simple application which creates one or two of these sub-windows and needs to keep these
-around for most or all of the lifetime of the application this is not really an issue as the window will be cleaned up
-at application exit eventually. If however it concerns a more complex application which potentially could create a large
-number of these sub windows (probably each only used for limited purposes) it would be advisable to track instances and
-destroy these on a regular basis when not used (closed) possibly re-creating them as needed.
-
-Dialogs are special cases of toplevel windows which are not automatically destroyed when closed. The wxRuby library
-therefor provides special support to ease handling the destruction of these. See [here](03_dialogs.md) for more details.
-
-## Object identities
-
-One of the trickier things to handle correctly in the kind of native extensions like wxRuby is maintaining object
-identities i.e. keeping native instances synced with their Ruby wrapper counter parts.
-
-Whenever a native extension is allowed to call back into Ruby space we encounter the problem that we need to map any
-native object data provided for the call to the right Ruby types and when necessary to the right Ruby instance (object
-identity).
-
-Objects that are considered POD types (*plain old data* types) like numerics, booleans, strings, arrays and hashes do
-not require maintaining *object identity*. For these objects it is enough to map them to the right Ruby type before
-passing them on to Ruby space.
-
-For a lot of other objects though it is essential to not only map to the right **most derived** class type but also to
-the exact Ruby instance which was originally instantiated as wrapper for the native object if any exists (in case no
-Ruby instance existed yet a new instance of the correct **most derived** class should be instantiated at that point).
-The reason this is important is **1.** because the Ruby instance may have been used to identify, link to or otherwise
-reference other data and/or functionality related to that specific Ruby/native pair and **2.** the Ruby instance could
-contain data elements (instance variables) related to that specific Ruby/native pair.
-In the case of wxRuby Window instance for example it is common to derive custom Window classes with custom behaviour and
-corresponding instance variables that drive that behaviour. When an event handler or an overloaded native method is passed
-a native window object we absolutely need to be able to map that native object to the correct Ruby wrapper instance so
-all information stays in sync.
-
-For this purpose wxRuby uses *object tracking* i.e. maintaining hash tables mapping native object pointers to Ruby object
-values. Whenever a tracked object is instantiated it is registered and can from than on be resolved whenever needed to map
-from native object to Ruby object.
-Of course this also means wxRuby has to track object destruction so mappings can be removed when a native object is
-destructed.
-Additionally the tracking tables are also used to mark Ruby objects during the GC marking phase so they do not get garbage
-collected whenever they are not referenced in Ruby space anymore but still functioning in native space (this is for example
-a common situation for many child windows created but not permanently referenced in Ruby space).
-
-Tracking and resolving mappings from tracking tables produces a certain computing overhead but testing has shown this to be
-absolutely acceptable for normal applications.
-
-There are however quite a lot of wrapped native objects in wxRuby for which *object identity* is not essential. For these
-object tracking has been disabled for their classes. This means these kind of classes/object should **not** be derived from
-(if even possible and/or useful) to add functionality/information or their identity used as key to link other information.
-These classes include:
-- classes considered POD types like Wx::Size, Wx::Point, Wx::RealPoint, Wx::Rect, Wx::GBSpan, Wx::GBPosition, Wx::BusyInfoFlags,
-Wx::AboutDialogInfo
-- final non-instantiatable classes like the Wx::DC (Device Context) class family, Wx::GraphicsContext, Wx::WindowsDisabler,
-Wx::EventBlocker, Wx::BusyInfo
-- classes with native singleton objects like Wx::Clipboard
-- the reference counted GDI objects like Wx::Pen, Wx::Brush, Wx::Colour, Wx::Cursor, Wx::Bitmap, Wx::Icon and similar
-reference counted objects like Wx::Font
-
-The reference documentation will note untracked object classes.
diff --git a/lib/wx/doc/extra/03_dialogs.md b/lib/wx/doc/extra/03_dialogs.md
deleted file mode 100644
index 5469b621..00000000
--- a/lib/wx/doc/extra/03_dialogs.md
+++ /dev/null
@@ -1,57 +0,0 @@
-
-
-# 3. wxRuby Dialogs
-
-Dialogs are a special class of window which are never automatically destroyed in wxWidgets.
-In C++ this does not cause a lot of management overhead for application programmers because of the possibility of
-static declaration of dialogs instances where the statically declared object is automatically destructed as execution
-leaves the declaration scope.
-This kind of construct does not exist in Ruby where everything is dynamically allocated and garbage collection normally
-takes care of releasing objects that have gone *'out of scope'*.
-
-Like any non-owned, non-toplevel windows as discussed [here](02_lifecycles.md) this means dialogs should be explicitly
-destroyed in program code as appropriate like:
-
-```ruby
-dlg = Wx::MessageDialog.new(parent, 'Select Yes or No', "Confirmation", Wx::YES_NO)
-if dlg.show_modal == Wx::ID_YES
- # do something
-end
-dlg.destroy
-```
-
-Although this is sometimes useful (for example in cases where a dialog is repeatedly used), most of the time this makes
-for somewhat bothersome programming.
-
-Luckily wxRuby has a solution for this.
-
-For all dialog classes (which includes Wx::Dialog and all it's derivatives, including user defined) the library defines
-a module function which is identically named to the dialog class in the same scope as where the dialog class has been
-first defined. This is similar to the module functions Ruby itself defines for the basic object classes like `Integer`,
-`String`, `Array`, `Hash` and such for the `Kernel` module.
-These dialog *functors* accept the same arguments as the dialog class's constructor with the addition of a block. The
-*functor* will call the class constructor and pass the created dialog instance as argument to the block. After returning
-from the block the dialog instance will automatically be destroyed. So, using this approach we could write the previous
-example like:
-
-```ruby
-Wx.MessageDialog(parent, 'Select Yes or No', "Confirmation", Wx::YES_NO) do |dlg|
- if dlg.show_modal == Wx::ID_YES
- # do something
- end
-end
-```
-
-Even better, if the only purpose is to show the dialog until closed without caring for the result we can leave out the
-block. In that case the *functor* will simply create the dialog instance, call `#show_modal` on it and destroy the
-instance after returning from `#show_modal` like:
-
-```ruby
-Wx.MessageDialog(parent, 'Hello world!', 'Information', Wx::OK)
-```
-
-Regular dialog constructors are still usable for situations where the dialog instance should have a
-prolonged lifetime or where different modeless behavior is required.
diff --git a/lib/wx/doc/extra/04_enums.md b/lib/wx/doc/extra/04_enums.md
deleted file mode 100644
index c0e156c7..00000000
--- a/lib/wx/doc/extra/04_enums.md
+++ /dev/null
@@ -1,143 +0,0 @@
-
-
-# 4. wxRuby Enum values
-
-The wxWidget library liberally mixes integer constants and enum values for things like IDs, style flags
-and option flags and such without much consistency.
-In previous wxRuby versions these were all mapped to integer constants which had 2 distinct disadvantages.
-
-- **loss of scoping**
-Integer constants for enum values would all be declared in the enclosing scope for the enum declaration loosing
-the naming scope which originally existed in C++ (excepting anonymous enums).
-
-- **loss of type-safety**
-Constants for enum values with identical integer values are indistinguishable from each other.
-
-The wxRuby3 project attempts to provide a solution to that by introducing the `Wx::Enum` class which
-is used as a base class for mapping all (named) wxWidget enums to Ruby.
-The reference documentation for the `Wx::Enum` class can be found [here](https://mcorino.github.io/wxRuby3/Wx/Enum.html).
-
-Any named wxWidget enum is mapped to a similarly named (Rubified C++ name) derived Enum class with each enum value
-defined as a constant of the enum class referencing an instance of the enum class with the corresponding
-integer value like for example the 'wxSystemFont' enum which is defined in wxRuby as:
-
-```ruby
-module Wx
- class SystemFont < Wx::Enum
-
- # Original equipment manufacturer dependent fixed-pitch font.
- #
- SYS_OEM_FIXED_FONT = Wx::SystemFont.new(10)
-
- # Windows fixed-pitch (monospaced) font.
- #
- SYS_ANSI_FIXED_FONT = Wx::SystemFont.new(11)
-
- # Windows variable-pitch (proportional) font.
- #
- SYS_ANSI_VAR_FONT = Wx::SystemFont.new(12)
-
- # System font.
- #
- SYS_SYSTEM_FONT = Wx::SystemFont.new(13)
-
- # Device-dependent font.
- #
- SYS_DEVICE_DEFAULT_FONT = Wx::SystemFont.new(14)
-
- # Default font for user interface objects such as menus and dialog boxes.
- #
- SYS_DEFAULT_GUI_FONT = Wx::SystemFont.new(17)
-
- end # SystemFont
-end
-```
-
-or the 'wxBorder' enum which is defined in wxRuby as:
-
-```ruby
-module Wx
- # Border flags for {Wx::Window}.
- class Border < Wx::Enum
-
- # This is different from {Wx::Border::BORDER_NONE} as by default the controls do have a border.
- #
- BORDER_DEFAULT = Wx::Border.new(0)
-
- #
- #
- BORDER_NONE = Wx::Border.new(2097152)
-
- #
- #
- BORDER_STATIC = Wx::Border.new(16777216)
-
- #
- #
- BORDER_SIMPLE = Wx::Border.new(33554432)
-
- #
- #
- BORDER_RAISED = Wx::Border.new(67108864)
-
- #
- #
- BORDER_SUNKEN = Wx::Border.new(134217728)
-
- #
- #
- BORDER_DOUBLE = Wx::Border.new(268435456)
-
- #
- #
- BORDER_THEME = Wx::Border.new(268435456)
-
- #
- #
- BORDER_MASK = Wx::Border.new(522190848)
-
- end # Border
-end
-```
-
-Enum instances are interchangeable with integer constants in wxRuby with respect to arithmetic or logical
-operations. This make it possible to use enum values to construct integer bitflag arguments like:
-
-```ruby
-Wx::TextCtrl.new(pane, Wx::ID_ANY, sample_desc.description, style: Wx::TE_MULTILINE|Wx::TE_READONLY|Wx::BORDER_NONE)
-```
-
-where `Wx::ID_ANY` is a `Wx::StandardID` enum instance passed to provide an integer argument value, `Wx::TE_MULTILINE`
-and `Wx::TE_READONLY` are simple integer constants and `Wx::BORDER_NONE` is a `Wx::Border` enum instance.
-
-In other cases however enum values can provide just the right kind of type safety where explicit enum values are
-expected like for example with:
-
-```ruby
-Wx::Font.new(36, Wx::FONTFAMILY_SWISS, Wx::FONTSTYLE_NORMAL, Wx::FONTWEIGHT_NORMAL)
-```
-
-where the `Wx::Font` constructor definition is:
-
-> initialize(pointSize, family, style, weight, underline = false, faceName = `Wx::EMPTY_STRING`, encoding = `Wx::FONTENCODING_DEFAULT`) ⇒ `Wx::Font`
-
-with the following parameter specification:
-
-> - pointSize (`Integer`)
-> - family (`Wx::FontFamily`)
-> - style (`Wx::FontStyle`)
-> - weight (`Wx::FontWeight`)
-> - underline (`true`, `false`) (defaults to: `false`)
-> - faceName (`String`) (defaults to: `Wx::EMPTY_STRING`)
-> - encoding (`Wx::FontEncoding`) (defaults to: `Wx::FONTENCODING_DEFAULT`)
-
-In this case the constructor explicitly expects specific enum value types for *family*, *style* and *weigth* and
-providing the integer literal value `74` instead of `Wx::FONTFAMILY_SWISS` (or any other constant representing the same
-integer value) will not work (raises an exception) although the integer values for the two are equal.
-
-As you have probably noticed it is not required to use the full naming for an enum instance constant (like
-`Wx::FontFamily::FONTFAMILY_SWISS`). All enum value constants are accessible from the naming scope where the enum class
-to which they belong has been declared.
diff --git a/lib/wx/doc/extra/05_event-handling.md b/lib/wx/doc/extra/05_event-handling.md
deleted file mode 100644
index 9fc72a40..00000000
--- a/lib/wx/doc/extra/05_event-handling.md
+++ /dev/null
@@ -1,191 +0,0 @@
-
-
-# 5. wxRuby Event Handling
-
-## Introduction
-
-Event handling is the core of runtime code execution in event based frameworks like wxWidgets which means it needs to
-be fully supported by wxRuby. Fortunately it is.
-As Ruby is a fully dynamic language though the statically declared event tables typical for wxWidgets application are not.
-Instead wxRuby offers a dynamic solution that is just as easy to use and even offers more flexibility in a typical Ruby-way.
-
-## Event handlers
-
-Instead of the `EVT_XXX` event handler declaration macros used in wxWidgets wxRuby provides similarly named event handler
-definition methods for each of the known event declarations which are inherited by **all** classes derived from {Wx::
-EvtHandler}
-(which includes all window classes, the {Wx::App} class and {Wx::Timer} as well as various other classes).
-
-Naming is (mostly) identical but rubified. So `EVT_MENU` becomes `evt_menu`, `EVT_IDLE` becomes `evt_idle`, `EVT_UPDATE_UI`
-becomes `evt_update_ui` etc.
-
-Like the event handler macros some of these methods require a single (window) id (like `evt_menu`) or a range of of ids
-(specified through a first and last id like for `evt_update_ui_range`) and some require only a handler definition (like
-`evt_idle`).
-
-Event handler setup is typically something done during the initialization of an event handler object (like a window) but
-this is not required. As all event handlers are assigned dynamically in wxRuby you can setup (some) event handlers at a
-later moment. You could also disconnect earlier activated handlers at any time (see {Wx::EvtHandler#disconnect}).
-
-In case of some frame class `MyForm` including a menu a wxWidgets static event handling table like:
-
-```c++
-wxBEGIN_EVENT_TABLE(MyForm, wxFrame)
- EVT_IDLE(MyForm::OnIdle)
- EVT_MOVE(MyForm::OnMove)
- EVT_SIZE(MyForm::OnResize)
-
- EVT_MENU( wxID_ABOUT, MyForm::OnAbout )
- EVT_MENU( wxID_EXIT, MyForm::OnCloseClick )
-wxEND_EVENT_TABLE()
-```
-
-could translate to event handler initializations in wxRuby like this:
-
-```ruby
-class MyForm < Wx::Frame
-
- def initialize(title)
- super(nil, title: title)
-
- # initialize frame elements
- # ...
-
- # setup event handlers
- evt_idle do |evt|
- # do something
- evt.skip
- end
- evt_move :on_move
-
- evt_size method(:on_size)
-
- evt_menu(Wx::ID_ABOUT, Proc.new { on_about })
- evt_menu(Wx::ID_EXIT) { close(false) }
- end
-
- def on_idle(evt)
- #...
- end
-
- def on_move(evt)
- #...
- end
-
- def on_resize(evt)
- #...
- end
-
- def on_about
- #...
- end
-
-end
-```
-
-As you can see there are multiple options for specifying the actual handler. Any event handler definition method will
-accept either a `Symbol` (or `String`) specifying a method of the receiver (the event handler instance), a `Proc` object
-(or lambda) or a `Method` object.
-
-Event handler methods are not required to declare the single event object argument. The event handler definition method
-will take care of checking and handling method arity.
-
-## Custom Events
-
-Custom event definitions are fully supported in wxRuby including the definition of new event types.
-
-New event classes can be registered with {Wx::EvtHandler#register_class} which returns the new event type for the event
-class like this:
-
-```ruby
-# A custom type of event associated with a target control. Note that for
-# user-defined controls, the associated event should inherit from
-# Wx::CommandEvent rather than Wx::Event.
-class ProgressUpdateEvent < Wx::CommandEvent
- # Create a new unique constant identifier, associate this class
- # with events of that identifier and create an event handler definition method 'evt_update_progress'
- # for setting up this handler.
- EVT_UPDATE_PROGRESS = Wx::EvtHandler.register_class(self, nil, 'evt_update_progress', 0)
-
- def initialize(value, gauge)
- # The constant id is the arg to super
- super(EVT_UPDATE_PROGRESS)
- # simply use instance variables to store custom event associated data
- @value = value
- @gauge = gauge
- end
-
- attr_reader :value, :gauge
-end
-```
-
-Check the reference documentation [here](https://mcorino.github.io/wxRuby3/Wx/EvtHandler.html) for more information.
-
-## Event processing
-
-In wxRuby overruling the normal chain of event handling has been limited to being able to override the default
-{Wx::EvtHandler#try_before} and {Wx::EvtHandler#try_after} methods. These are the advised interception points for events
-when you really need to do this.
-Overriding {Wx::EvtHandler#process_event} is not considered to be efficient (or desired)
-for wxRuby applications and has therefor been blocked.
-
-## Event insertion
-
-Use of {Wx::EvtHandler#process_event} or {Wx::EvtHandler#queue_event} and {Wx::EvtHandler#add_pending_event} in wxRuby to
-trigger event processing of user generated (possibly custom) events is fully supported.
-
-As with wxWidgets {Wx::EvtHandler#process_event} will trigger immediate processing of the given event, not returning before
-this has finished.
-{Wx::EvtHandler#queue_event} and {Wx::EvtHandler#add_pending_event} on the other hand will post (append) the given event
-to the event queue and return immediately after that is done. The event will than be processed after any other events in
-the queue. Unlike in wxWidgets in wxRuby there is no practical difference between `queue_event` and `add_pending_event`.
-
-## Asynchronous execution
-
-In addition to {Wx::EvtHandler#queue_event} and {Wx::EvtHandler#add_pending_event} to trigger asynchronous processing
-wxRuby also supports {Wx::EvtHandler#call_after}.
-
-This method provides the means to trigger asynchronous execution of arbitrary code and because it has been rubified is
-easy and powerful to use. Like with event handler definition this method accepts a `Symbol` or `String` (identifying a
-method of the receiver), a `Proc` object (or lambda), a `Method` object or a block. Unlike an event handler method no
-event object will be passed but rather any arguments passed to the `call_after` method in addition to the 'handler'.
-
-Given an event handler object `call_after` could be used like:
-
-```ruby
-# sync call to method of event handler (no args)
-evt_handler.call_after :async_method
-
-# async call of lambda (single arg)
-evt_handler.call_after(->(txt) { Wx.log_info(txt) }, "Hello")
-
-# async call of block
-evt_handler.call_after('Call nr. %d', 1) { |fmt, num| Wx.log_info(fmt, num) }
-```
-
-## Event life cycles!
-
-Like in C++ the wxRuby Event objects passed to the event handlers are (in general) references to **temporary** objects
-which are only safe to access within the execution scope of the event handler that received the reference.
-If you *need* (really?) to store a reference to such an object do so to a cloned version (see {Wx::Event#clone}) and **not**
-to the original object otherwise you **will** run into 'Object already deleted' exceptions.
-
-Only user defined events instantiated in Ruby code (or cloned Event objects) will be subject to Ruby's normal life cycle
-rules (GC).
-This means that when you instantiate a user defined event and pass it to {Wx::EvtHandler#process_event} it would be possible
-to directly store the reference to such an Event object passed to it's event handler. You have to **know** for sure though
-(see below). So, in case of doubt (or to be safe) use {Wx::Event#clone}.
-
-Another 'feature' to be aware of is the fact that when passing an (user instantiated) Event object to {Wx::
-EvtHandler#queue_event}
-or {Wx::EvtHandler#add_pending_event} the Ruby event instance is unlinked from it's C++ counterpart (or in the case of user
-defined events a cloned instance is associated with it's C++ counterpart) before being queued and the C++ side now takes ownership
-(and will delete the Event object when handled).
-As a result this means that even in the case of a user defined Event object any event handler triggered by a asynchronously
-processed event will be handling a temporary Event object.
-Additionally this also means that any Event object passed to {Wx::EvtHandler#queue_event} or {Wx::
-EvtHandler#add_pending_event}
-is essentially invalidated after these methods return and should not be referenced anymore.
diff --git a/lib/wx/doc/extra/06_geometry.md b/lib/wx/doc/extra/06_geometry.md
deleted file mode 100644
index b1465242..00000000
--- a/lib/wx/doc/extra/06_geometry.md
+++ /dev/null
@@ -1,62 +0,0 @@
-
-
-# 6. wxRuby Geometry classes
-
-## Size (Wx::Size) and position (Wx::Point and Wx::RealPoint)
-
-The wxWidgets API has a lot methods that require either `wxSize`, `wxPoint` or both type of value as argument. Although
-this can be specified in C++ still relatively concise like
-```ruby
-new wxFrame(nullptr, -1, "title", wxPoint(0,0), wxSize(500,400))
-```
-in Ruby this expands to the more verbose
-```ruby
-Wx::Frame.new(nil, -1, 'title', Wx::Point.new(0,0), Wx::Size.new(500,400))
-```
-which starts to feel awkward to specify what are in essence just pairs of integers.
-
-To provide a simpler, more compact and more Ruby-like, alternative the wxRuby API therefor supports specifying arrays
-of integer (or float in case of {Wx::RealPoint}) pairs in (almost) all cases where {Wx::Size} or {Wx::Point}
-(or {Wx::RealPoint}) is expected. So the following code is equivalent to the previous code:
-```ruby
-Wx::Frame.new(nil, -1, 'title', [0,0], [500,400])
-```
-
-In addition {Wx::Size}, {Wx::Point} and {Wx::RealPoint} support parallel assignment semantics such that you can write code like
-```ruby
- win.paint do | dc |
- # ...
- x, y = win.get_position
- dc.draw_circle(x, y, 4)
- dc.draw_rectangle(x-4, y-4, 8, 8)
- end
-```
-instead of
-```ruby
- win.paint do | dc |
- # ...
- pos = win.get_position
- dc.draw_circle(pos.x, pos.y, 4)
- dc.draw_rectangle(pos.x-4, pos.y-4, 8, 8)
- end
-```
-
-Instances of these classes can also be converted (back) to arrays with their `#to_ary` methods.
-
-Lastly wxRuby also extends the standard Ruby Array class with conversion methods to explicitly convert
-arrays to {Wx::Size}, {Wx::Point} or {Wx::RealPoint}; respectively the `#to_size`, `#to_point` and `#to_real_point`
-methods.
-
-## Areas (Wx::Rect)
-
-Like {Wx::Size} and {Wx::Point} wxRuby supports parallel assignment for {Wx::Rect} such that you can write code like
-```ruby
-x, y, width, height = win.get_client_rect
-```
-
-Providing arrays of integers as alternative for `Wx::Rect` arguments is not supported as specifying `[0, 0, 20, 40]` is
-ambiguous. This could either mean a rectangle with origin `x=0,y=0` and size `width=20,height=40` (`Wx::Rect.new(0,0,20,40)`)
-or a rectangle from origin top left `x=0,y=0` to point bottom right `x=20,y=40` (`Wx::Rect.new(Wx::Point.new(0,0), Wx::Point.new(20,40))`).
diff --git a/lib/wx/doc/extra/07_colour_and_font.md b/lib/wx/doc/extra/07_colour_and_font.md
deleted file mode 100644
index 448fccf0..00000000
--- a/lib/wx/doc/extra/07_colour_and_font.md
+++ /dev/null
@@ -1,52 +0,0 @@
-
-
-# 6. wxRuby Colour and Font
-
-## Introduction
-
-The wxWidgets API makes use of typical C++ features to support automatic conversion of certain types providing
-user friendly options for argument specifications. This way for example a developer does not need to explicitly
-declare a colour object construction where a colour instance value is expected but rather can specify a simple string
-constant like:
-
-```C++
-wxPen pen;
-pen.SetColour("CYAN"); // instead of pen.SetColour(wxColour("CYAN"));
-```
-
-For the wxRuby API similar support has been achieved for various much used argument types.
-
-## Colour
-
-Wherever a {Wx::Colour} object is expected as an argument wxRuby supports the specification of `String` or `Symbol`
-values as a developer friendly alternative. This way the following code is equivalent:
-
-```ruby
-pen = Wx::Pen.new
-pen.set_colour(Wx::Colour.new("CYAN"))
-
-pen = Wx::Pen.new
-pen.set_colour("CYAN")
-
-pen = Wx::Pen.new
-pen.set_colour(:CYAN)
-```
-
-## Font
-
-Wherever a {Wx::Font} object is expected as an argument wxRuby supports the specification of a {Wx::FontInfo} object.
-This way the following code is equivalent:
-
-```ruby
-title = Wx::StaticText.new(self, -1, "Title")
-title.set_font(Wx::Font.new(18, Wx::FontFamily::FONTFAMILY_SWISS, Wx::FontStyle::FONTSTYLE_NORMAL, Wx::FontWeight::FONTWEIGHT_BOLD))
-
-title = Wx::StaticText.new(self, -1, "Title")
-title.set_font(Wx::FontInfo.new(18)
- .family(Wx::FontFamily::FONTFAMILY_SWISS)
- .style(Wx::FontStyle::FONTSTYLE_NORMAL)
- .bold())
-```
diff --git a/lib/wx/doc/extra/08_extensions.md b/lib/wx/doc/extra/08_extensions.md
deleted file mode 100644
index b88bd31d..00000000
--- a/lib/wx/doc/extra/08_extensions.md
+++ /dev/null
@@ -1,144 +0,0 @@
-
-
-# 8. wxRuby Extensions
-
-## Keyword Constructors
-
-The **Keyword Constructors** extension allows the use of Ruby hash-style
-keyword arguments in constructors of common WxWidgets Windows, Frame,
-Dialog and Control classes.
-
-### Introduction
-
-Building a GUI in WxWidgets involves lots of calls to +new+, but
-these methods often have long parameter lists. Often the default
-values for many of these parameters are correct. For example, if
-you're using a sizer-based layout, you usually don't want to specify a
-size for widgets, but you still have to type
-
- Wx::TreeCtrl.new( parent, -1, Wx::DEFAULT_POSITION, Wx::DEFAULT_SIZE, Wx::NO_BUTTONS )
-
-just to create a standard TreeCtrl with the 'no buttons' style. If you
-want to specify the 'NO BUTTONS' style, you can't avoid all the typing
-of DEFAULT_POSITION etc.
-
-### Basic Keyword Constructors
-
-With keyword_constructors, you could write the above as
-
- TreeCtrl.new(parent, :style => Wx::NO_BUTTONS)
-
-And it will assume you want the default id (-1), and the default size
-and position. If you want to specify an explicit size, you can do so:
-
- TreeCtrl.new(parent, :size => Wx::Size.new(100, 300))
-
-For brevity, this module also allows you to specify positions and
-sizes using a a two-element array:
-
- TreeCtrl.new(parent, :size => [100, 300])
-
-Similarly with position:
-
- TreeCtrl.new(parent, :pos => Wx::Point.new(5, 25))
-
- TreeCtrl.new(parent, :pos => [5, 25])
-
-You can have multiple keyword arguments:
-
- TreeCtrl.new(parent, :pos => [5, 25], :size => [100, 300] )
-
-### No ID required
-
-As with position and size, you usually don't want to deal with
-assigning unique ids to every widget and frame you create - it's a C++
-hangover that often seems clunky in Ruby. The **Event Connectors**
-extension allows you to set up event handling without having to use
-ids, and if no `:id` argument is supplied to a constructor, the default
-(-1) will be passed.
-
-There are occasions when a specific ID does need to be used - for
-example, to tell WxWidgets that a button is a 'stock' item, so that it
-can be displayed using platform-standard text and icon. To do this,
-simply pass an :id argument to the constructor - here, the system's
-standard 'preview' button
-
- Wx::Button.new(parent, :id => Wx::ID_PREVIEW)
-
-### Class-specific arguments
-
-The arguments `:size`, `:pos` and `:style` are common to many WxWidgets
-window classes. The `new` methods of these classes also have
-parameters that are specific to those classes; for example, the text
-label on a button, or the initial value of a text control.
-
- Wx::Button.new(parent, :label => 'press me')
- Wx::TextCtrl.new(parent, :value => 'type some text here')
-
-The keyword names of these arguments can be found by looking at the
-WxRuby documentation, in the relevant class's +new+ method. You can
-also get a string description of the class's +new+ method parameters
-within Ruby by doing:
-
- puts Wx::TextCtrl.describe_constructor()
-
-This will print a list of the argument names expected by the class's
-+new+ method, and the correct type for them.
-
-### Mixing positional and keyword arguments
-
-To support existing code, and to avoid forcing the use of more verbose
-keyword-style arguments where they're not desired, you can mix
-positional and keyword arguments, omitting or including `id`s as
-desired.
-
- Wx::Button.new(parent, 'press me', :style => Wx::BU_RIGHT)
-
-### Handling complex defaults or version differences
-
-To support complex (context dependent) defaults and/or auto conversion
-of arguments for backwards compatibility the keyword constructors
-extension allows the definition of lambdas or procs to be associated
-with a parameter specification.
-
-## Ruby-style accessors
-
-The wxWidgets API, in typical C++ style, has lots of accessor methods like
-
-- `GetPosition()`
-- `SetSize(a_size)`
-- `IsChecked()`
-- `CanUndo()`
-- `HasStyle(a_style)`
-
-which in wxRuby are mapped to Ruby methods like `get_position`, `set_size` etc.
-
-In Ruby however these kind of methods that set, get or query attributes or state are normally simply called
-by the attribute name or, in other cases, by a predicate method like:
-
-```ruby
-pos = frame.position
-frame.size = a_size
-item.checked?
-control.can_undo?
-window.has_style?(a_style)
-```
-
-With wxRuby3 (most of) the API methods that begin with *get_*, *set_*, *is_*, *can_* and *has_* are identified
-and the wxRuby API will have Ruby-style accessor aliases defined for those (appropriately decorated as needed).
-Note that if you are calling a *'setter'* method on `self`, you must explicitly send the message to `self` like:
-
-```ruby
-# set's self size to be 100px by 100px
-self.size = Wx::Size.new(100, 100)
-```
-
-since this will not work as you expect it to:
-
-```ruby
-# only sets the value of a local variable 'size'
-size = Wx::Size.new
-```
diff --git a/lib/wx/doc/extra/09_exceptions.md b/lib/wx/doc/extra/09_exceptions.md
deleted file mode 100644
index ed408421..00000000
--- a/lib/wx/doc/extra/09_exceptions.md
+++ /dev/null
@@ -1,54 +0,0 @@
-
-
-# 9. wxRuby Exception Handling
-
-The wxRuby library should (!) be completely exception safe, i.e. Ruby code raising an exception should not leak into
-the wrapped wxWidgets C++ code and cause unexpected exception handling or (worse) segmentation faults and should be
-handled in ways expected of Ruby applications.
-
-As the wxWidgets library does not use exceptions for it's public API any raised exceptions should come either from the
-wxRuby wrapper code (signalling mostly typical Ruby-ish error situations like ArgumentError, TypeError and such) or from
-your own Ruby application code.
-
-Any exceptions raised from wxRuby wrapper code signal coding errors that need to be rectified.
-
-As far as handling application code exceptions is concerned the same advice applies as for wxWidgets itself; do **NOT**
-let exceptions escape your event handlers meaning that if you can reasonably expect application code to raise exceptions
-you should make sure to catch any such exceptions within the context of the event handler like:
-
-```ruby
-class MyForm < Wx::Frame
-
- def initialize(title)
- super(nil, title: title)
-
- # initialize frame elements
- # ...
-
- # setup event handlers
- evt_menu MY_MENU_ID, :on_my_menu_item
-
- # ...
- end
-
- def on_my_menu_item(evt)
- begin
- # execute some application code
- # ...
- rescue SomeException => ex
- # handle exception
- end
- end
-
- #...
-
-end
-```
-
-In wxRuby event handler code is executed in an exception safe way which will capture any leaking exceptions. As wxRuby
-however has no idea why this exception was raised and how to handle it, the result will be an exit of the main event loop
-of the running {Wx::App} instance and re-raising the exception to be handled by Ruby like any unhandled application
-exception.
diff --git a/lib/wx/doc/extra/10_art.md b/lib/wx/doc/extra/10_art.md
deleted file mode 100644
index 3da08c1d..00000000
--- a/lib/wx/doc/extra/10_art.md
+++ /dev/null
@@ -1,111 +0,0 @@
-
-
-# 10. wxRuby Locating and loading art
-
-## Introduction
-
-With C++ wxWidgets applications art (icons, bitmaps, cursors, images) can be loaded in a variety
-of ways from embedded resources (platform specific binary resources or embedded XPM files) or from
-binary datasets retrieved from some data source.
-
-With wxRuby that is for various reasons not a viable option so we are left with the option to
-load art from files. In and of itself that option is not really too bad but for the issue of locating
-the art files.
-Art that is part of the application's design will preferably be stored with the source code but there
-is not standard for this nor is there any standard support for locating those files from the application
-code like there is for `require`-s of other code modules.
-
-The wxRuby framework provides a convenience module {Wx::ArtLocator} to assist in that respect.
-{Wx::ArtLocator} aims on the one side to standardize folder structures for storing art files and on the
-other side to provide runtime support for locating those files from code.
-
-The main locator method provided is:
-
-```ruby
- module Wx::Locator
- def self.find_art(art_name, art_type: nil, art_path: nil, art_section: nil, bmp_type: nil)
- # ...
- end
- end
-```
-
-The 'art_name' argument should provide the base name for matching art files and can be specified as either
-String or Symbol.
-
-## Storage locations
-
-Wx::ArtLocator defines a standardized directory structure that is assumed to be used for application art
-file storage.
-Working from a certain (application defined) base search path ('art_path' argument) this structure looks like this:
-
-
- \art
- \
- \
-
-Where '' is an application supplied search path, 'art' is the default name for Art folders (this can be overridden by an application specific name),
-'' is an application defined id allowing sub-categorizing art and '' is the type of art indicator
-(which can be 'icon', 'bitmap', 'cursor', 'image').
-Art files can be located at any level in this hierarchy and all sub levels in this hierarchy are optional.
-When locating files the art locator will test a file's existence at all levels starting with the
-deepest level working it's way up returning the absolute path of the first file found this way.
-
-So locating an art file would involve testing for the file at the following paths:
-1. \/art///
-2. \/art//
-3. \/art/
-4. \/
-
-The first location can be skipped by specifying `nil` for 'art_type'.
-
-## Bitmap types
-
-Based on platform and specified '' (and optionally a specific {Wx::BitmapType}) art files with a specific
-range of extensions will be tested in a specific order.
-For example for locating an `:icon` () on platform 'WXGTK' the locator will test the preferred extension
-'.xpm' followed by any of supported extensions of all other supported bitmap types.
-For platform 'WXMSW' however the same search would test only the extensions '.ico' and '.xpm' (in that
-order).
-Specifying a specific {Wx::BitmapType} for a search will restrict the search to testing only the extensions supported
-for the specified {Wx::BitmapType}.
-
-## Search paths
-
-To prevent having to specify base search path for every location request {Wx::Locator} provides 2 options.
-
-When an explicit specification of a base search path ('art_path) is omitted from a location request the locator
-will determine one by using `Kernel#caller_locations` to extract the absolute path for the source file containing
-the caller's code. The result of `File.dirname(src_path)` is than used as base search path.
-If 'art_section' is also omitted the result of `File.basename(src_path, '.*')` will be used instead.
-
-This means that calling {Wx::ArtLocator.find_art} from some code in file `/some/lib/path/to/ruby/code.rb` without
-specifying both 'art_path' and 'art_section' would result in looking for an art file with the base search path
-being `/some/lib/path/to/ruby/` and using `code` as 'art_section'.
-
-It is also possible to add 'application global' search paths with the method {Wx::ArtLocator.add_search_path}.
-Search paths added in this way will be tested after failing to find any matching art file at the initial 'art_path'
-location. The same location steps apply to these search paths as with the initial 'art_path' (see above).
-
-## Convenience methods
-
-Based on the {Wx::ArtLocator} implementation wxRuby additionally provides a number of convenience methods to
-easily create Icons, Bitmaps, Cursors and Images from simple ids (symbols):
-
-- {Wx.Bitmap}
-- {Wx.Cursor}
-- {Wx.Icon}
-- {Wx.Image}
-
-These methods mimic the ease of use of the `wxICON` and `wxBITMAP` macros used with C++ wxWidgets such that
-creating an {Wx::Icon} instance could be as easy as:
-
-```ruby
- frame.icon = Wx.Icon(:sample)
-```
-
-As these methods apply the same search path 'automagic' as `Wx::ArtLocator.find_art` (see [Search paths](#Search-paths))
-this would search for an art file with base name 'sample' and an appropriate extension (like '.xpm' for the 'WXGTK' platform)
-in a location starting at the directory in which the caller's code is stored (applying the steps described above).
diff --git a/lib/wx/doc/extra/11_drawing_and_dc.md b/lib/wx/doc/extra/11_drawing_and_dc.md
deleted file mode 100644
index 5bbeeb27..00000000
--- a/lib/wx/doc/extra/11_drawing_and_dc.md
+++ /dev/null
@@ -1,62 +0,0 @@
-
-
-# 11. wxRuby Drawing and Device Contexts (DC)
-
-In wxRuby the Wx::DC class family provides functionality for drawing to windows, bitmaps, printers etc.
-
-What most of these classes have in common is that actual drawing output is buffered until the time the
-device context object is destroyed.
-For this reason the common practice in wxWidgets C++ code would be to create temporary DC objects on the
-stack and draw on them while they are in scope (for several classes it is even strongly advised to never create
-them any other way and to never keep objects alive out of scope). When leaving the scope these object would than be
-automatically destroyed and any buffered output flushed to the final target.
-
-In Ruby this approach is impossible as Ruby is a purely dynamic language and does not support **this kind** of scope bound
-life cycles. Any DC object created would have to be dynamically created and due to the properties of the GC driven
-life cycles could well be kept alive beyond the scope of it's creation. This will not always cause problems but could
-and does not really have an upside.
-
-To prevent confusion and potential problems wxRuby defines all {Wx::DC} derived classes to be abstract classes that
-cannot be instantiated using `new`. Rather all {Wx::DC} derived classes provide `::draw_on` factory methods to create
-temporary dc objects that will be passed on to blocks given and will only exist for the duration of the execution of
-the block. This will guarantee proper DC cleanup when leaving it's usage scope.
-
-> Note that it is a **BAD** idea to think about storing the dc reference provided to the block for later access!
-
-A typical usage of a `::draw_on` method would be:
-
-```ruby
- myTestBitmap1x = Wx::Bitmap.new(60, 15, 32)
- Wx::MemoryDC.draw_on(myTestBitmap1x) do |mdc|
- mdc.set_background(Wx::WHITE_BRUSH)
- mdc.clear
- mdc.set_pen(Wx::BLACK_PEN)
- mdc.set_brush(Wx::WHITE_BRUSH)
- mdc.draw_rectangle(0, 0, 60, 15)
- mdc.draw_line(0, 0, 59, 14)
- mdc.set_text_foreground(Wx::BLACK)
- mdc.draw_text("x1", 0, 0)
- end
-```
-
-## Windows, Wx::PaintDC and Wx::AutoBufferedPaintDC
-
-The {Wx::PaintDC} and {Wx::AutoBufferedPaintDC} classes provide `::draw_on` methods just like all other DC classes but
-this is mostly to be consistent.
-
-In this case it is recommended to instead use the {Wx::Window#paint} or {Wx::Window#paint_buffered} methods as these
-provide some optimizations with regard to automatically detecting if the methods are called inside `Wx::EVT_PAINT`
-handlers (which should normally be the case) or not.
-
-So the typical way to do buffered painting inside a windows `Wx::EVT_PAINT` handler would be something like:
-
-```ruby
- def on_paint(_event)
- self.paint_buffered do |dc|
- # ... do some drawing ...
- end
- end
-```
diff --git a/lib/wx/doc/extra/12_client_data.md b/lib/wx/doc/extra/12_client_data.md
deleted file mode 100644
index 46b55258..00000000
--- a/lib/wx/doc/extra/12_client_data.md
+++ /dev/null
@@ -1,89 +0,0 @@
-
-
-# 12. Client/User data with wxRuby
-
-## Introduction
-
-The wxWidgets library has widespread support for attaching arbitrary client (or user) data to GUI elements like
-windows (all event handlers actually), window items, sizer items etc.
-To cater to various C++ use cases in most instances this support covers both specific wxWidgets defined types (like
-wxClientData and wxObject instances) and untyped data pointers (represented as `void *`) with subtle but essential
-differences.
-
-wxRuby implements a fully compatible version of this support.
-
-## Everything is an Object
-
-As Ruby does not do untyped data (everything is an Object), and having two different options is confusing anyway,
-wxRuby provides only a single option and more or less unifies the interface across the entire library.
-In Ruby anywhere the original wxWidgets library supports some type of client (or user) data attachment wxRuby will
-support the attachment of any arbitrary Ruby `Object` by either the method `#set_client_object` (where C++ supports
-`SetClientData` and `SetClientObject`) or `#set_user_data` (where C++ supports `SetUserData`). Data retrieval
-is supported by complementary `#get_client_object` or `#get_user_data` methods in all cases.
-Wherever C++ supports `SetClientObject` wxRuby also provides the method aliases `#set_client_data` and `#get_client_data`.
-
-Another difference with C++ is that for typed client data in wxWidgets developers could leverage object destruction as
-callback trigger (through the implementation of virtual destructors) to handle any required 'unlinking' logic. This
-obviously does not apply to untyped data (one of the 'subtle' differences).
-As Ruby does not provide any usable object destruction hooks this does not work there.
-Ruby however has 'Duck-typing' which is what wxRuby uses to provide support for a unlinking callback 'hook' for attached
-client data.
-
-> Any attached Ruby Object implementing (responding to) the method `#client_data_unlinked` will have that method called after the
-> attached object has been detached from the element it was attached to (either because of data replacement or element
-> deletion).
-
-Regard the following example.
-
-```ruby
- frame = Wx::Frame.new(nil, Wx::ID_ANY)
-
- # attach a hash with user data
- frame.set_client_data({ text: 'A string', float: 3.14 })
-
- # ... do something with frame
-
- # replace the user data
- frame.set_client_data([1,2,3,4])
-
- # ... do something else with frame
-```
-
-In this case standard Ruby object are attached. After attachment the object can be retrieved using a call to `get_client_data`
-anywhere access to the frame instance is available.
-
-Using a specially derived (or adapted) object a developer can handle specific logic after the object has been unlinked
-like in this example:
-
-```ruby
- # define a user data class
- class MyUserData
- def initialize(payload)
- @payload = payload
- end
- attr_reader :payload
-
- def client_data_unlinked
- # handle some logic
- end
- end
-
- # ...
-
- # attach data to some window
- win.set_client_data(MyUserData.new(some_payload_data))
-
- # ...
-
- # reset user data for some reason (will call MyUserData#client_data_unlinked after replacement)
- win.set_client_data(nil)
-```
-
-# CommandEvent data
-
-wxRuby also fully supports the propagation of attached client data to Wx::CommandEvent objects (see
-{Wx::CommandEvent#get_client_object} and {Wx::CommandEvent#set_client_object}).
-As mentioned above wxRuby provides the method aliases `#set_client_data` and `#get_client_data` here also.
diff --git a/lib/wx/doc/extra/13_validators.md b/lib/wx/doc/extra/13_validators.md
deleted file mode 100644
index 0e141d12..00000000
--- a/lib/wx/doc/extra/13_validators.md
+++ /dev/null
@@ -1,139 +0,0 @@
-
-
-# 13. Validators and data binding
-
-## Introduction
-
-wxRuby fully supports validator classes offering input validation and/or data binding and/or event filtering.
-
-## Validation
-
-The base Wx::Validator class defines the method {Wx::Validator#validate} which is called when validation of the
-value or content of the associated window is required.
-
-The implementation of this method should (somehow) retrieve the value of the associated window and validate that
-value, returning `true` if valid or `false` otherwise. The default implementation always returns `false`.
-
-An example would be:
-
-```ruby
-# define custom validator
-class MyTextValidator < Wx::Validator
-
- def validate(_parent)
- txt = get_window.value
- # validate that the control text starts with a capital if not empty
- txt.empty? || (?A..?Z).include?(txt[0])
- end
-
-end
-
-# ...
-
-# assign custom validator to text control
-text = Wx::TextCtrl.new(parent, MY_TEXT_ID)
-text.set_validator(MyTextValidator.new)
-```
-
-The derived, specialized, validator classes {Wx::TextValidator}, {Wx::IntegerValidator}, {Wx::IntegerValidator} and
-{Wx::FloatValidator} all have implementations that can be configured through specific options and do not
-normally require an override to be defined.
-
-Examples of using the standard validators would be:
-
-```ruby
-text = Wx::TextCtrl.new(parent, MY_TEXT_ID)
-
-# accept only hexadecimal characters
-text.set_validator(Wx::TextValidator.new(Wx::TextValidatorStyle::FILTER_XDIGITS))
-
-# or only numbers between -20 and 20
-text.set_validator(Wx::IntegerValidator.new(-20, 20))
-```
-
-## Event filtering
-
-All validator classes are event handlers and can have event handling routines defined (see
-[Event Handling](05_event-handling.md)).
-When processing events the core implementation will allow any validator associated with a window to handle an event
-before the associated window itself thereby allowing it to filter events (see {Wx::EvtHandler#process_event} for more
-details).
-
-The standard specialized validators use this functionality to filter entry of allowable characters (by handling
-Wx::EVT_CHAR events).
-
-## Data binding
-
-Data binding concerns the transfer of a validator's associated window's value to or from a user definable storage (a
-variable, memory cache entry, persistent storage ...).
-
-To integrate with the core C++ implementation but allow for Ruby specific differences the scheme implemented for this
-differs somewhat (in naming and functionality) from the original wxWidgets interface.
-
-The responsibilities of the standard wxRuby interface for handling validator data binding is distributed over 2 base
-methods and a mixin module.
-
-- The protected {Wx::Validator#do_transfer_from_window} and {Wx::Validator#do_transfer_to_window} methods are
- responsible for collecting and transferring data from/to the associated window (possibly applying conversions).
-
- These methods have default implementations in all of the derived validator classes and should not be overridden for
- specializations of these as they will be ignored.
- Overriding these methods is necessary to implement data binding for any user defined specialization of the base
- {Wx::Validator} class.
-
-- The methods the {Wx::Validator::Binding} mixin module provide the means to store data after collection from or retrieve data
- before transfer to the associated window.
-
- The methods {Wx::Validator::Binding#on_transfer_from_window} and {Wx::Validator::Binding#on_transfer_to_window} provide
- the means to specify user defined binding handlers for storing the data transferred from the associated window or retrieving the
- data to transfer to the associated window. Like with event handling the handlers can be specified using a `String` or
- `Symbol`, a `Proc` or a `Method`.
-
- The methods {Wx::Validator::Binding#do_on_transfer_from_window} and {Wx::Validator::Binding#do_on_transfer_to_window} by
- default call the binding handlers if defined.
- These methods can be overridden to create derived validator classes with dedicated data binding functionality like
- with {Wx::GenericValidator}.
-
-An example of a custom validator providing data binding would be:
-
-```ruby
-class MyTextValidator < Wx::Validator
-
- def do_transfer_from_window
- get_window.get_value
- end
-
- def do_transfer_to_window(val)
- get_window.set_value(val)
- true
- end
-
-end
-
-# ...
-
-# use custom validator
-@data = nil # attribute to store data
-text.set_validator(MyTextValidator.new)
-text.get_validator.on_transfer_to_window { @data }
-text.get_validator.on_transfer_from_window { |v| @data = v }
-```
-
-All derived, specialized, validators implement a dedicated value cache which can be accessed through the `#value` attribute
-accessor. Through this accessor the data collected from the associated window can get retrieved or the data to be transferred
-to the associated window set.
-With these classes it is therefor not necessary to define binding handlers. Defining binding handlers can however still be
-useful to implement a custom, persistent, storage solution.
-
-### Wx::GenericValidator
-
-The {Wx::GenericValidator} class provides an extendable standard implementation for data binding in combination with a
-large collection of controls (see class documentation).
-The implementation provides a standard accessor {Wx::GenericValidator#value} to get the data value collected
-from the associated window or set the data to transfer to the associated window.
-
-To add support for any control unsupported by the standard implementation the method {Wx::GenericValidator.define_handler}
-is provided (see documentation for an example).
diff --git a/lib/wx/doc/extra/14_config.md b/lib/wx/doc/extra/14_config.md
deleted file mode 100644
index 27f75c62..00000000
--- a/lib/wx/doc/extra/14_config.md
+++ /dev/null
@@ -1,101 +0,0 @@
-
-
-# 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`).
-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).
diff --git a/lib/wx/doc/extra/15_persistence.md b/lib/wx/doc/extra/15_persistence.md
deleted file mode 100644
index 349fc469..00000000
--- a/lib/wx/doc/extra/15_persistence.md
+++ /dev/null
@@ -1,148 +0,0 @@
-
-
-# 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*.
-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
-```
diff --git a/rakelib/gem.rake b/rakelib/gem.rake
index 1f38a455..3b9d289c 100644
--- a/rakelib/gem.rake
+++ b/rakelib/gem.rake
@@ -174,11 +174,6 @@ else # in case of installed source gem the following tasks exist
case switch
when '--prebuilt'
kwargs[:prebuilt_only] = true
- if argv.first == 'head'
- argv.shift # loose it
- # set this config key to make binpkg name come out right
- WXRuby3.config.set_config('with-wxhead', true)
- end
when '--no-prebuilt'
no_prebuilt = true unless kwargs[:package]
when '--package'
diff --git a/rakelib/lib/director/app.rb b/rakelib/lib/director/app.rb
index 84c66810..153bf314 100644
--- a/rakelib/lib/director/app.rb
+++ b/rakelib/lib/director/app.rb
@@ -87,31 +87,47 @@ def setup
}
__HEREDOC
if Config.platform == :macosx
- # add accessor methods for the standard OSX menu items
+ # add static accessor methods for the standard OSX menu items
spec.add_extend_code 'wxApp', <<~__HEREDOC
- void set_mac_about_menu_itemid(long menu_itemid)
+ static void set_mac_about_menu_itemid(long menu_itemid)
{
- $self->s_macAboutMenuItemId = menu_itemid;
+ wxApp::s_macAboutMenuItemId = menu_itemid;
}
- long get_mac_about_menu_itemid(long menu_itemid)
+ static long get_mac_about_menu_itemid(long menu_itemid)
{
- return $self->s_macAboutMenuItemId;
+ return wxApp::s_macAboutMenuItemId;
}
- void set_mac_preferences_menu_itemid(long menu_itemid)
+ static void set_mac_preferences_menu_itemid(long menu_itemid)
{
- $self->s_macPreferencesMenuItemId = menu_itemid;
+ wxApp::s_macPreferencesMenuItemId = menu_itemid;
}
- long get_mac_preferences_menu_itemid(long menu_itemid)
+ static long get_mac_preferences_menu_itemid(long menu_itemid)
{
- return $self->s_macPreferencesMenuItemId;
+ return wxApp::s_macPreferencesMenuItemId;
}
- void set_mac_exit_menu_itemid(long menu_itemid)
+ static void set_mac_exit_menu_itemid(long menu_itemid)
{
- $self->s_macExitMenuItemId = menu_itemid;
+ wxApp::s_macExitMenuItemId = menu_itemid;
}
- long get_mac_exit_menu_itemid(long menu_itemid)
+ static long get_mac_exit_menu_itemid(long menu_itemid)
{
- return $self->s_macExitMenuItemId;
+ return wxApp::s_macExitMenuItemId;
+ }
+ static void set_mac_help_menu_title(const wxString& title)
+ {
+ wxApp::s_macHelpMenuTitleName = title;
+ }
+ static const wxString& get_mac_help_menu_title()
+ {
+ return wxApp::s_macHelpMenuTitleName;
+ }
+ static void set_mac_window_menu_title(const wxString& title)
+ {
+ wxApp::s_macWindowMenuTitleName = title;
+ }
+ static const wxString& get_mac_window_menu_title()
+ {
+ return wxApp::s_macWindowMenuTitleName;
}
__HEREDOC
end