wxruby3 0.9.0.pre.beta.8-x64-mingw-ucrt

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

@@ -0,0 +1,116 @@
+<!--
+# @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 that 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.

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

@@ -0,0 +1,57 @@
+<!--
+# @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. 

data/lib/wx/doc/extra/04_enums.md

@@ -0,0 +1,143 @@
+<!--
+# @markup markdown
+# @title 4. wxRuby Enum values
+-->
+
+# 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.<br>
+In previous wxRuby versions these were all mapped to integer constants which had 2 distinct disadvantages.
+
+- **loss of scoping**<br>
+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**<br>
+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.

data/lib/wx/doc/extra/05_event-handling.md

@@ -0,0 +1,166 @@
+<!--
+# @markup markdown
+# @title 5. wxRuby Event Handling
+-->
+
+# 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.<br>
+As Ruby is a fully dynamic language though the statically declared event tables typical for wxWidgets application are not.<br>
+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).<br>
+
+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.<br>
+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.<br>
+`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) }
+```

data/lib/wx/doc/extra/06_geometry.md

@@ -0,0 +1,56 @@
+<!--
+# @markup markdown
+# @title 6. wxRuby geometry classes
+-->
+
+# 6. wxRuby Geometry classes
+
+## Size (Wx::Size) and position (Wx::Point)
+
+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 pairs in (almost) all cases where `Wx::Size` or `Wx::Point` 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` and `Wx::Point` 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
+```
+
+## 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))`).

data/lib/wx/doc/extra/07_colour_and_font.md

@@ -0,0 +1,52 @@
+<!--
+# @markup markdown
+# @title 7. wxRuby Colour and Font
+-->
+
+# 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())
+```