wxruby3 0.9.0.pre.beta.8

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

@@ -0,0 +1,154 @@
+<!--
+# @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 and Linux or other 
+unix-like systems with GTK2 or GTK3 libraries. As wxWidgets also has stable releases for Mac OSX and Linux QT platforms
+it should not be to hard to support these. Contributions to achieve this 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 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. For the
+exit sequence to 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](packages.md) for more details on wxRuby sub-modules.

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

@@ -0,0 +1,179 @@
+<!--
+# @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::HtmlHelpFrame`
+- `Wx::HTML::HtmlHelpController`
+- 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

@@ -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.