wxruby3 0.9.8 → 1.0.0

data/lib/wx/doc/extra/00_starting.md

@@ -1,154 +0,0 @@
-<!--
-# @markup markdown
-# @title 0. Overview of wxRuby
--->
-
-# 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.<br>
-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.

data/lib/wx/doc/extra/01_packages.md

@@ -1,180 +0,0 @@
-<!--
-# @markup markdown
-# @title 1. wxRuby Modules
--->
-
-# 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.

data/lib/wx/doc/extra/02_lifecycles.md

@@ -1,166 +0,0 @@
-<!--
-# @markup markdown
-# @title 2. wxRuby Life Cycles
--->
-
-# 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.<br>
-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.<br>
-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.<br>
-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.<br>
-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.<br>
-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.<br>
-Of course this also means wxRuby has to track object destruction so mappings can be removed when a native object is 
-destructed.<br>
-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.<br>
-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.

data/lib/wx/doc/extra/03_dialogs.md

@@ -1,57 +0,0 @@
-<!--
-# @markup markdown
-# @title 3. wxRuby Dialogs
--->
-
-# 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.<br>
-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.<br>
-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.