wxruby3 0.9.7 → 1.0.0

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. 

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

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

@@ -1,191 +0,0 @@
-<!--
-# @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) }
-```
-
-## 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.

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

@@ -1,62 +0,0 @@
-<!--
-# @markup markdown
-# @title 6. wxRuby geometry classes
--->
-
-# 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))`).

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

@@ -1,52 +0,0 @@
-<!--
-# @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())
-```