wxruby3 0.9.7 → 1.0.0

data/lib/wx/doc/extra/08_extensions.md

@@ -1,144 +0,0 @@
-<!--
-# @markup markdown
-# @title 8. wxRuby Extensions
--->
-
-# 8. wxRuby Extensions
-
-## Keyword Constructors
-
-The **Keyword Constructors** extension allows the use of Ruby hash-style
-keyword arguments in constructors of common WxWidgets Windows, Frame,
-Dialog and Control classes.
-
-### Introduction
-
-Building a GUI in WxWidgets involves lots of calls to +new+, but
-these methods often have long parameter lists. Often the default
-values for many of these parameters are correct. For example, if
-you're using a sizer-based layout, you usually don't want to specify a
-size for widgets, but you still have to type
-
-    Wx::TreeCtrl.new( parent, -1, Wx::DEFAULT_POSITION, Wx::DEFAULT_SIZE, Wx::NO_BUTTONS )
-
-just to create a standard TreeCtrl with the 'no buttons' style. If you
-want to specify the 'NO BUTTONS' style, you can't avoid all the typing
-of DEFAULT_POSITION etc.
-
-### Basic Keyword Constructors
-
-With keyword_constructors, you could write the above as
-
-    TreeCtrl.new(parent, :style => Wx::NO_BUTTONS)
-
-And it will assume you want the default id (-1), and the default size
-and position. If you want to specify an explicit size, you can do so:
-
-    TreeCtrl.new(parent, :size => Wx::Size.new(100, 300))
-
-For brevity, this module also allows you to specify positions and
-sizes using a a two-element array:
-
-    TreeCtrl.new(parent, :size => [100, 300])
-
-Similarly with position:
-
-    TreeCtrl.new(parent, :pos => Wx::Point.new(5, 25))
-    
-    TreeCtrl.new(parent, :pos => [5, 25])
-
-You can have multiple keyword arguments:
-
-    TreeCtrl.new(parent, :pos => [5, 25], :size => [100, 300] )
-
-### No ID required
-
-As with position and size, you usually don't want to deal with
-assigning unique ids to every widget and frame you create - it's a C++
-hangover that often seems clunky in Ruby. The **Event Connectors**
-extension allows you to set up event handling without having to use
-ids, and if no `:id` argument is supplied to a constructor, the default
-(-1) will be passed.
-
-There are occasions when a specific ID does need to be used - for
-example, to tell WxWidgets that a button is a 'stock' item, so that it
-can be displayed using platform-standard text and icon. To do this,
-simply pass an :id argument to the constructor - here, the system's
-standard 'preview' button
-
-    Wx::Button.new(parent, :id => Wx::ID_PREVIEW)
-
-### Class-specific arguments
-
-The arguments `:size`, `:pos` and `:style` are common to many WxWidgets
-window classes. The `new` methods of these classes also have
-parameters that are specific to those classes; for example, the text
-label on a button, or the initial value of a text control.
-
-    Wx::Button.new(parent, :label => 'press me')
-    Wx::TextCtrl.new(parent, :value => 'type some text here')
-
-The keyword names of these arguments can be found by looking at the
-WxRuby documentation, in the relevant class's +new+ method. You can
-also get a string description of the class's +new+ method parameters
-within Ruby by doing:
-
-    puts Wx::TextCtrl.describe_constructor()
-
-This will print a list of the argument names expected by the class's
-+new+ method, and the correct type for them.
-
-### Mixing positional and keyword arguments
-
-To support existing code, and to avoid forcing the use of more verbose
-keyword-style arguments where they're not desired, you can mix
-positional and keyword arguments, omitting or including `id`s as
-desired.
-
-    Wx::Button.new(parent, 'press me', :style => Wx::BU_RIGHT)
-
-### Handling complex defaults or version differences
-
-To support complex (context dependent) defaults and/or auto conversion
-of arguments for backwards compatibility the keyword constructors
-extension allows the definition of lambdas or procs to be associated
-with a parameter specification.
-
-## Ruby-style accessors
-
-The wxWidgets API, in typical C++ style, has lots of accessor methods like
-
-- `GetPosition()`
-- `SetSize(a_size)`
-- `IsChecked()`
-- `CanUndo()`
-- `HasStyle(a_style)`
-
-which in wxRuby are mapped to Ruby methods like `get_position`, `set_size` etc.
-
-In Ruby however these kind of methods that set, get or query attributes or state are normally simply called
-by the attribute name or, in other cases, by a predicate method like:
-
-```ruby
-pos = frame.position
-frame.size = a_size
-item.checked?
-control.can_undo?
-window.has_style?(a_style)
-```
-
-With wxRuby3 (most of) the API methods that begin with *get_*, *set_*, *is_*, *can_* and *has_* are identified 
-and the wxRuby API will have Ruby-style accessor aliases defined for those (appropriately decorated as needed).
-Note that if you are calling a *'setter'* method on `self`, you must explicitly send the message to `self` like:
-
-```ruby
-# set's self size to be 100px by 100px
-self.size = Wx::Size.new(100, 100)
-```
-
-since this will not work as you expect it to:
-
-```ruby
-# only sets the value of a local variable 'size'
-size = Wx::Size.new
-```

data/lib/wx/doc/extra/09_exceptions.md

@@ -1,54 +0,0 @@
-<!--
-# @markup markdown
-# @title 9. wxRuby Exception Handling
--->
-
-# 9. wxRuby Exception Handling
-
-The wxRuby library should (!) be completely exception safe, i.e. Ruby code raising an exception should not leak into
-the wrapped wxWidgets C++ code and cause unexpected exception handling or (worse) segmentation faults and should be 
-handled in ways expected of Ruby applications.
-
-As the wxWidgets library does not use exceptions for it's public API any raised exceptions should come either from the
-wxRuby wrapper code (signalling mostly typical Ruby-ish error situations like ArgumentError, TypeError and such) or from
-your own Ruby application code.
-
-Any exceptions raised from wxRuby wrapper code signal coding errors that need to be rectified.
-
-As far as handling application code exceptions is concerned the same advice applies as for wxWidgets itself; do **NOT**
-let exceptions escape your event handlers meaning that if you can reasonably expect application code to raise exceptions
-you should make sure to catch any such exceptions within the context of the event handler like:
-
-```ruby
-class MyForm < Wx::Frame
-  
-  def initialize(title)
-    super(nil, title: title)
-    
-    # initialize frame elements
-    # ...
-    
-    # setup event handlers
-    evt_menu MY_MENU_ID, :on_my_menu_item
-    
-    # ...
-  end
-  
-  def on_my_menu_item(evt)
-    begin
-      # execute some application code
-      # ...
-    rescue SomeException => ex 
-      # handle exception
-    end
-  end
-  
-  #...
-  
-end
-```
-
-In wxRuby event handler code is executed in an exception safe way which will capture any leaking exceptions. As wxRuby 
-however has no idea why this exception was raised and how to handle it, the result will be an exit of the main event loop
-of the running {Wx::App} instance and re-raising the exception to be handled by Ruby like any unhandled application 
-exception.

data/lib/wx/doc/extra/10_art.md

@@ -1,111 +0,0 @@
-<!--
-# @markup markdown
-# @title 10. wxRuby Locating and loading art
--->
-
-# 10. wxRuby Locating and loading art
-
-## Introduction
-
-With C++ wxWidgets applications art (icons, bitmaps, cursors, images) can be loaded in a variety 
-of ways from embedded resources (platform specific binary resources or embedded XPM files) or from
-binary datasets retrieved from some data source.  
-
-With wxRuby that is for various reasons not a viable option so we are left with the option to
-load art from files. In and of itself that option is not really too bad but for the issue of locating 
-the art files.
-Art that is part of the application's design will preferably be stored with the source code but there
-is not standard for this nor is there any standard support for locating those files from the application
-code like there is for `require`-s of other code modules.
-
-The wxRuby framework provides a convenience module {Wx::ArtLocator} to assist in that respect.
-{Wx::ArtLocator} aims on the one side to standardize folder structures for storing art files and on the
-other side to provide runtime support for locating those files from code.
-
-The main locator method provided is:
-
-```ruby
-  module Wx::Locator
-    def self.find_art(art_name, art_type: nil, art_path: nil, art_section: nil, bmp_type: nil)
-      # ...
-    end
-  end
-```
-
-The 'art_name' argument should provide the base name for matching art files and can be specified as either
-String or Symbol.
-
-## Storage locations
-
-Wx::ArtLocator defines a standardized directory structure that is assumed to be used for application art
-file storage.
-Working from a certain (application defined) base search path ('art_path' argument) this structure looks like this:
-
-    <art_path>
-              \art
-                  \<art_section>
-                                \<art_type>
-
-Where '<art_path>' is an application supplied search path, 'art' is the default name for Art folders (this can be overridden by an application specific name),
-'<art_section>' is an application defined id allowing sub-categorizing art and '<art_type>' is the type of art indicator 
-(which can be 'icon', 'bitmap', 'cursor', 'image').
-Art files can be located at any level in this hierarchy and all sub levels in this hierarchy are optional. 
-When locating files the art locator will test a file's existence at all levels starting with the
-deepest level working it's way up returning the absolute path of the first file found this way.
-
-So locating an art file would involve testing for the file at the following paths:
-1. \<art_path>/art/<art_section>/<art_type>/
-2. \<art_path>/art/<art_section>/
-3. \<art_path>/art/
-4. \<art_path>/
-
-The first location can be skipped by specifying `nil` for 'art_type'.
-
-## Bitmap types
-
-Based on platform and specified '<art_type>' (and optionally a specific {Wx::BitmapType}) art files with a specific
-range of extensions will be tested in a specific order.
-For example for locating an `:icon` (<art_type>) on platform 'WXGTK' the locator will test the preferred extension
-'.xpm' followed by any of supported extensions of all other supported bitmap types.
-For platform 'WXMSW' however the same search would test only the extensions '.ico' and '.xpm' (in that
-order).
-Specifying a specific {Wx::BitmapType} for a search will restrict the search to testing only the extensions supported
-for the specified {Wx::BitmapType}.
-
-## Search paths
-
-To prevent having to specify base search path for every location request {Wx::Locator} provides 2 options.
-
-When an explicit specification of a base search path ('art_path) is omitted from a location request the locator
-will determine one by using `Kernel#caller_locations` to extract the absolute path for the source file containing
-the caller's code. The result of `File.dirname(src_path)` is than used as base search path.
-If 'art_section' is also omitted the result of `File.basename(src_path, '.*')` will be used instead.
-
-This means that calling {Wx::ArtLocator.find_art} from some code in file `/some/lib/path/to/ruby/code.rb` without 
-specifying both 'art_path' and 'art_section' would result in looking for an art file with the base search path
-being `/some/lib/path/to/ruby/` and using `code` as 'art_section'.
-
-It is also possible to add 'application global' search paths with the method {Wx::ArtLocator.add_search_path}.
-Search paths added in this way will be tested after failing to find any matching art file at the initial 'art_path'
-location. The same location steps apply to these search paths as with the initial 'art_path' (see above).
-
-## Convenience methods
-
-Based on the {Wx::ArtLocator} implementation wxRuby additionally provides a number of convenience methods to
-easily create Icons, Bitmaps, Cursors and Images from simple ids (symbols):
-
-- {Wx.Bitmap} 
-- {Wx.Cursor} 
-- {Wx.Icon} 
-- {Wx.Image}
-
-These methods mimic the ease of use of the `wxICON` and `wxBITMAP` macros used with C++ wxWidgets such that
-creating an {Wx::Icon} instance could be as easy as:
-
-```ruby
-    frame.icon = Wx.Icon(:sample)
-```
-
-As these methods apply the same search path 'automagic' as `Wx::ArtLocator.find_art` (see [Search paths](#Search-paths))
-this would search for an art file with base name 'sample' and an appropriate extension (like '.xpm' for the 'WXGTK' platform)
-in a location starting at the directory in which the caller's code is stored (applying the steps described above).

data/lib/wx/doc/extra/11_drawing_and_dc.md

@@ -1,62 +0,0 @@
-<!--
-# @markup markdown
-# @title 11. wxRuby Drawing and Device Contexts
--->
-
-# 11. wxRuby Drawing and Device Contexts (DC)
-
-In wxRuby the Wx::DC class family provides functionality for drawing to windows, bitmaps, printers etc.
-
-What most of these classes have in common is that actual drawing output is buffered until the time the 
-device context object is destroyed.
-For this reason the common practice in wxWidgets C++ code would be to create temporary DC objects on the
-stack and draw on them while they are in scope (for several classes it is even strongly advised to never create
-them any other way and to never keep objects alive out of scope). When leaving the scope these object would than be 
-automatically destroyed and any buffered output flushed to the final target.
-
-In Ruby this approach is impossible as Ruby is a purely dynamic language and does not support **this kind** of scope bound
-life cycles. Any DC object created would have to be dynamically created and due to the properties of the GC driven
-life cycles could well be kept alive beyond the scope of it's creation. This will not always cause problems but could
-and does not really have an upside.
-
-To prevent confusion and potential problems wxRuby defines all {Wx::DC} derived classes to be abstract classes that
-cannot be instantiated using `new`. Rather all {Wx::DC} derived classes provide `::draw_on` factory methods to create 
-temporary dc objects that will be passed on to blocks given and will only exist for the duration of the execution of
-the block. This will guarantee proper DC cleanup when leaving it's usage scope.
-
-> Note that it is a **BAD** idea to think about storing the dc reference provided to the block for later access!
-
-A typical usage of a `::draw_on` method would be:
-
-```ruby
-    myTestBitmap1x = Wx::Bitmap.new(60, 15, 32)
-    Wx::MemoryDC.draw_on(myTestBitmap1x) do |mdc|
-      mdc.set_background(Wx::WHITE_BRUSH)
-      mdc.clear
-      mdc.set_pen(Wx::BLACK_PEN)
-      mdc.set_brush(Wx::WHITE_BRUSH)
-      mdc.draw_rectangle(0, 0, 60, 15)
-      mdc.draw_line(0, 0, 59, 14)
-      mdc.set_text_foreground(Wx::BLACK)
-      mdc.draw_text("x1", 0, 0)
-    end
-```
-
-## Windows, Wx::PaintDC and Wx::AutoBufferedPaintDC
-
-The {Wx::PaintDC} and {Wx::AutoBufferedPaintDC} classes provide `::draw_on` methods just like all other DC classes but
-this is mostly to be consistent.
-
-In this case it is recommended to instead use the {Wx::Window#paint} or {Wx::Window#paint_buffered} methods as these
-provide some optimizations with regard to automatically detecting if the methods are called inside `Wx::EVT_PAINT` 
-handlers (which should normally be the case) or not.
-
-So the typical way to do buffered painting inside a windows `Wx::EVT_PAINT` handler would be something like:
-
-```ruby
-  def on_paint(_event)
-    self.paint_buffered do |dc|
-      # ... do some drawing ...
-    end
-  end
-```

data/lib/wx/doc/extra/12_client_data.md

@@ -1,89 +0,0 @@
-<!--
-# @markup markdown
-# @title 12. Client/User data with wxRuby
--->
-
-# 12. Client/User data with wxRuby
-
-## Introduction
-
-The wxWidgets library has widespread support for attaching arbitrary client (or user) data to GUI elements like
-windows (all event handlers actually), window items, sizer items etc.
-To cater to various C++ use cases in most instances this support covers both specific wxWidgets defined types (like
-wxClientData and wxObject instances) and untyped data pointers (represented as `void *`) with subtle but essential
-differences.
-
-wxRuby implements a fully compatible version of this support.    
-
-## Everything is an Object
-
-As Ruby does not do untyped data (everything is an Object), and having two different options is confusing anyway, 
-wxRuby provides only a single option and more or less unifies the interface across the entire library.
-In Ruby anywhere the original wxWidgets library supports some type of client (or user) data attachment wxRuby will 
-support the attachment of any arbitrary Ruby `Object` by either the method `#set_client_object` (where C++ supports 
-`SetClientData` and `SetClientObject`) or `#set_user_data` (where C++ supports `SetUserData`). Data retrieval
-is supported by complementary `#get_client_object` or `#get_user_data` methods in all cases.
-Wherever C++ supports `SetClientObject` wxRuby also provides the method aliases `#set_client_data` and `#get_client_data`.
-
-Another difference with C++ is that for typed client data in wxWidgets developers could leverage object destruction as 
-callback trigger (through the implementation of virtual destructors) to handle any required 'unlinking' logic. This
-obviously does not apply to untyped data (one of the 'subtle' differences).
-As Ruby does not provide any usable object destruction hooks this does not work there.
-Ruby however has 'Duck-typing' which is what wxRuby uses to provide support for a unlinking callback 'hook' for attached
-client data.
-
-> Any attached Ruby Object implementing (responding to) the method `#client_data_unlinked` will have that method called after the 
-> attached object has been detached from the element it was attached to (either because of data replacement or element 
-> deletion).
-
-Regard the following example.
-
-```ruby
-    frame = Wx::Frame.new(nil, Wx::ID_ANY)
-    
-    # attach a hash with user data  
-    frame.set_client_data({ text: 'A string', float: 3.14 })
-    
-    # ... do something with frame
-    
-    # replace the user data
-    frame.set_client_data([1,2,3,4])
-
-    # ... do something else with frame
-```
-
-In this case standard Ruby object are attached. After attachment the object can be retrieved using a call to `get_client_data`
-anywhere access to the frame instance is available.
-
-Using a specially derived (or adapted) object a developer can handle specific logic after the object has been unlinked 
-like in this example:
-
-```ruby
-    # define a user data class
-    class MyUserData
-      def initialize(payload)
-        @payload = payload
-      end
-      attr_reader :payload
-      
-      def client_data_unlinked
-        # handle some logic
-      end
-    end
-
-    # ...
-
-    # attach data to some window
-    win.set_client_data(MyUserData.new(some_payload_data)) 
-
-    # ...
-    
-    # reset user data for some reason (will call MyUserData#client_data_unlinked after replacement)
-    win.set_client_data(nil)
-```
-
-# CommandEvent data
-
-wxRuby also fully supports the propagation of attached client data to Wx::CommandEvent objects (see
-{Wx::CommandEvent#get_client_object} and {Wx::CommandEvent#set_client_object}).
-As mentioned above wxRuby provides the method aliases `#set_client_data` and `#get_client_data` here also. 

data/lib/wx/doc/extra/13_validators.md

@@ -1,139 +0,0 @@
-<!--
-# @markup markdown
-# @title 13. Validators and data binding
--->
-
-# 13. Validators and data binding
-
-## Introduction
-
-wxRuby fully supports validator classes offering input validation and/or data binding and/or event filtering. 
-
-## Validation
-
-The base Wx::Validator class defines the method {Wx::Validator#validate} which is called when validation of the
-value or content of the associated window is required.
-
-The implementation of this method should (somehow) retrieve the value of the associated window and validate that
-value, returning `true` if valid or `false` otherwise. The default implementation always returns `false`.
-
-An example would be:
-
-```ruby
-# define custom validator
-class MyTextValidator < Wx::Validator
-
-  def validate(_parent)
-    txt = get_window.value
-    # validate that the control text starts with a capital if not empty
-    txt.empty? || (?A..?Z).include?(txt[0])
-  end
-
-end
-
-# ...
-
-# assign custom validator to text control
-text = Wx::TextCtrl.new(parent, MY_TEXT_ID)
-text.set_validator(MyTextValidator.new)
-```
-
-The derived, specialized, validator classes {Wx::TextValidator}, {Wx::IntegerValidator}, {Wx::IntegerValidator} and 
-{Wx::FloatValidator} all have implementations that can be configured through specific options and do not 
-normally require an override to be defined.
-
-Examples of using the standard validators would be:
-
-```ruby
-text = Wx::TextCtrl.new(parent, MY_TEXT_ID)
-
-# accept only hexadecimal characters
-text.set_validator(Wx::TextValidator.new(Wx::TextValidatorStyle::FILTER_XDIGITS))
-
-# or only numbers between -20 and 20
-text.set_validator(Wx::IntegerValidator.new(-20, 20))
-```
-
-## Event filtering
-
-All validator classes are event handlers and can have event handling routines defined (see 
-[Event Handling](05_event-handling.md)).
-When processing events the core implementation will allow any validator associated with a window to handle an event
-before the associated window itself thereby allowing it to filter events (see {Wx::EvtHandler#process_event} for more 
-details).
-
-The standard specialized validators use this functionality to filter entry of allowable characters (by handling 
-Wx::EVT_CHAR events).
-
-## Data binding
-
-Data binding concerns the transfer of a validator's associated window's value to or from a user definable storage (a 
-variable, memory cache entry, persistent storage ...).
-
-To integrate with the core C++ implementation but allow for Ruby specific differences the scheme implemented for this
-differs somewhat (in naming and functionality) from the original wxWidgets interface.
-
-The responsibilities of the standard wxRuby interface for handling validator data binding is distributed over 2 base 
-methods and a mixin module.  
-
-- The protected {Wx::Validator#do_transfer_from_window} and {Wx::Validator#do_transfer_to_window} methods are 
-  responsible for collecting and transferring data from/to the associated window (possibly applying conversions).<br>
-  <br>
-  These methods have default implementations in all of the derived validator classes and should not be overridden for
-  specializations of these as they will be ignored.<br>
-  Overriding these methods is necessary to implement data binding for any user defined specialization of the base 
-  {Wx::Validator} class.<br>
-  <br>
-- The methods the {Wx::Validator::Binding} mixin module provide the means to store data after collection from or retrieve data 
-  before transfer to the associated window.<br>
-  <br>
-  The methods {Wx::Validator::Binding#on_transfer_from_window} and {Wx::Validator::Binding#on_transfer_to_window} provide
-  the means to specify user defined binding handlers for storing the data transferred from the associated window or retrieving the
-  data to transfer to the associated window. Like with event handling the handlers can be specified using a `String` or
-  `Symbol`, a `Proc` or a `Method`.<br>
-  <br>
-  The methods {Wx::Validator::Binding#do_on_transfer_from_window} and {Wx::Validator::Binding#do_on_transfer_to_window} by
-  default call the binding handlers if defined.
-  These methods can be overridden to create derived validator classes with dedicated data binding functionality like 
-  with {Wx::GenericValidator}.
-
-An example of a custom validator providing data binding would be:
-
-```ruby
-class MyTextValidator < Wx::Validator
-
-  def do_transfer_from_window
-    get_window.get_value
-  end
-
-  def do_transfer_to_window(val)
-    get_window.set_value(val)
-    true
-  end
-  
-end
-
-# ...
-
-# use custom validator
-@data = nil # attribute to store data
-text.set_validator(MyTextValidator.new)
-text.get_validator.on_transfer_to_window { @data }
-text.get_validator.on_transfer_from_window { |v| @data = v }
-```
-
-All derived, specialized, validators implement a dedicated value cache which can be accessed through the `#value` attribute
-accessor. Through this accessor the data collected from the associated window can get retrieved or the data to be transferred
-to the associated window set.
-With these classes it is therefor not necessary to define binding handlers. Defining binding handlers can however still be 
-useful to implement a custom, persistent, storage solution.
-
-### Wx::GenericValidator
-
-The {Wx::GenericValidator} class provides an extendable standard implementation for data binding in combination with a 
-large collection of controls (see class documentation).
-The implementation provides a standard accessor {Wx::GenericValidator#value} to get the data value collected
-from the associated window or set the data to transfer to the associated window.
-
-To add support for any control unsupported by the standard implementation the method {Wx::GenericValidator.define_handler}
-is provided (see documentation for an example).