wxruby3 0.9.0.pre.beta.10 → 0.9.0.pre.beta.13

data/lib/wx/doc/const.rb

@@ -0,0 +1,77 @@
+module Wx
+
+=begin
+  These constants are not documented in the wxWidgets interface headers
+  although they are referenced in various argument defaults which *are*
+  in the interface header declarations so we do want them included the
+  wxRuby docs so the doc links work but we do not need them in the
+  wxRuby implementation since these are internal to the C++ wrappers.
+=end
+
+  DefaultDateTimeFormat = '%c'
+  DefaultTimeSpanFormat = '%H:%M:%S'
+
+  ChoiceNameStr = 'choice'
+  ColourPickerCtrlNameStr = 'colourpicker'
+  ColourPickerWidgetNameStr = 'colourpickerwidget'
+  HyperlinkCtrlNameStr = 'hyperlink'
+  PanelNameStr = 'panel'
+  ListBoxNameStr = 'listBox'
+  FrameNameStr = 'frame'
+  StatusLineNameStr = 'status_line'
+  StaticBitmapNameStr = 'staticBitmap'
+  WebViewNameStr = 'wxWebView'
+  AnimationCtrlNameStr = 'animationctrl'
+  ToolBarNameStr = 'toolbar'
+  TextCtrlNameStr = 'text'
+  ListCtrlNameStr = 'listCtrl'
+  FilePickerCtrlNameStr = 'filepicker'
+  FilePickerWidgetNameStr = 'filepickerwidget'
+  DirPickerCtrlNameStr = 'dirpicker'
+  DirPickerWidgetNameStr = 'dirpickerwidget'
+  FileCtrlNameStr = 'wxfilectrl'
+  StaticBoxNameStr = 'groupBox'
+  ButtonNameStr = 'button'
+  RadioBoxNameStr = 'radioBox'
+  StaticLineNameStr = 'staticLine'
+  RadioButtonNameStr = 'radioButton'
+  BitmapRadioButtonNameStr = 'radioButton'
+  GaugeNameStr = 'gauge'
+  DataViewCtrlNameStr = 'dataviewCtrl'
+  FontPickerCtrlNameStr = 'fontpicker'
+  FontPickerWidgetNameStr = 'fontpickerwidget'
+  RearrangeListNameStr = 'wxRearrangeList'
+  RearrangeDialogNameStr = 'wxRearrangeDlg'
+  NotebookNameStr = 'notebook'
+  ControlNameStr = 'control'
+  ScrollBarNameStr = 'scrollBar'
+  StatusBarNameStr = 'statusBar'
+  SliderNameStr = 'slider'
+  HeaderCtrlNameStr = 'wxHeaderCtrl'
+  BitmapComboBoxNameStr = 'bitmapComboBox'
+  CheckBoxNameStr = 'check'
+  FileDialogNameStr = 'filedlg'
+  AddRemoveCtrlNameStr = 'wxAddRemoveCtrl'
+  StaticTextNameStr = 'staticText'
+  ComboBoxNameStr = 'comboBox'
+  SearchCtrlNameStr = 'searchCtrl'
+  DirDialogNameStr = 'wxDirCtrl'
+  TreeCtrlNameStr = 'treeCtrl'
+  DialogNameStr = 'dialog'
+  CollapsibleHeaderCtrlNameStr = 'collapsibleHeader'
+  CollapsiblePaneNameStr = 'collapsiblePane'
+  BannerWindowNameStr = 'bannerwindow'
+  GridNameStr = 'grid'
+  TreeListCtrlNameStr = 'wxTreeListCtrl'
+  HtmlListBoxNameStr = 'htmlListBox'
+  SimpleHtmlListBoxNameStr = 'simpleHtmlListBox'
+  EditableListBoxNameStr = 'editableListBox'
+  VListBoxNameStr = 'wxVListBox'
+  CollapsiblePaneNameStr = 'collapsiblePane'
+  MSWHeaderCtrlNameStr = 'wxMSWHeaderCtrl'
+  PropertyGridManagerNameStr = 'wxPropertyGridManager'
+  PropertyGridNameStr = 'wxPropertyGrid'
+  STCNameStr = 'stcwindow'
+  STCNameStr = 'stcwindow'
+
+end

data/lib/wx/doc/cursor.rb

@@ -0,0 +1,16 @@
+
+class Wx::Cursor
+
+  # Searches for an art file with basename 'name' and creates a Cursor if found.
+  # Raises an ArgumentError if not found.
+  # Wx::ArtLocator::find_art is used to look up the art file using ::Kernel#caller_locations to
+  # determine the values for the 'art_path' and 'art_owner' arguments ('art_path' is set to the
+  # absolute path to the folder holding the caller's code and 'art_owner' to the basename of the
+  # caller's source file). The 'art_type' argument is set to <code>:icon</code>.
+  # @param [String,Symbol] name base name of art file
+  # @param [Wx::BitmapType,nil] bmp_type bitmap type for art file (nil means any supported type)
+  # @return [Wx::Cursor]
+  # @see Wx::ArtLocator::find_art
+  def self.Cursor(name, bmp_type = nil); end
+
+end

data/lib/wx/doc/data_object.rb

@@ -0,0 +1,103 @@
+
+module Wx
+
+  class DataObject
+
+    # Returns the data size of the given format.
+    # Should be overridden in derived classes.
+    # @note **IMPORTANT** Please note that it is necessary to return the **size in bytes** of the data string
+    # returned by #get_data_here (not the size in characters).
+    # @param format [Wx::DataFormat]
+    # @return [Integer]
+    def get_data_size(format) end
+    alias_method :data_size, :get_data_size
+
+  end
+
+  # This is an (abstract in Ruby) base class for the simplest possible custom data objects.
+  # Unlike in C++ in Ruby this class cannot be used to derive custom data objects from but
+  # instead {Wx::DataObjectSimpleBase} (derived from Wx::DataObjectSimple) should be used.
+  # The data object of (a class derived from) this class only supports <b>one format</b>,
+  # so the number of virtual functions to be implemented is reduced.
+  # This class is the base class for {Wx::TextDataObject}, {Wx::FileDataObject}, {Wx::BitmapDataObject},
+  # {Wx::wxCustomDataObject} and others.
+  # ===
+  #
+  # Category:  Clipboard and Drag & Drop
+  # @see Drag and Drop Overview
+  # @see  Drag & Drop Sample
+  class DataObjectSimple < DataObject
+
+    # @overload get_data_size(format)
+    #   Returns the data size of the format for this object.
+    #   @param [Wx::DataFormat] format ignored for this class
+    #   @return [Integer] default always returns 0
+    # @overload get_data_size()
+    #   Returns the data size of the format for this object.
+    #   @return [Integer] default always returns 0
+    def get_data_size(*) end
+
+    # @overload get_data_here(format)
+    #   Returns the data of this object.
+    #   @param [Wx::DataFormat] format ignored for this class
+    #   @return [String,nil] data of this object
+    # @overload get_data_here()
+    #   Returns the data of this object.
+    #   @return [String,nil] data of this object
+    def get_data_here(*) end
+
+    # @overload set_data(format, buf)
+    #   Sets the data for this object and returns true if successful, false otherwise.
+    #   @param [Wx::DataFormat] format ignored for this class
+    #   @param [String] buf non-nil data
+    #   @return [Boolean] default always returns false.
+    # @overload set_data(buf)
+    #   Sets the data for this object and returns true if successful, false otherwise.
+    #   @param [String] buf non-nil data
+    #   @return [Boolean] default always returns false.
+    def set_data(*) end
+
+  end
+
+  # This is the base class for the simplest possible custom data objects.
+  # The data object of (a class derived from) this class only supports <b>one format</b>,
+  # so the number of methods to be implemented is reduced.
+  # To be useful it must be derived. Derived objects supporting rendering the data must
+  # override {Wx::DataObjectSimpleBase#_get_data_size} and {Wx::DataObjectSimpleBase#_get_data}.
+  # By default these methods respectively return <code>0</code> and <code>nil</code>.
+  # The objects which may be set must override {Wx::DataObjectSimpleBase#_set_data} (which
+  # returns <code>false</code>).
+  # Of course, the objects supporting both operations must override all three methods.
+  # ===
+  #
+  # Category:  Clipboard and Drag & Drop
+  # @see Drag and Drop Overview
+  # @see  Drag & Drop Sample
+  # @see  Wx::DataObjectSimple
+  class DataObjectSimpleBase < DataObjectSimple
+
+    # Returns this object's data size.
+    # The default implementation calls #_get_data and determines the size of the returned data string (if any).
+    # As this is not very optimal for more complex (and larger data objects) very often this method will be
+    # overridden in derived classes.
+    # @note **IMPORTANT** Please note that it is necessary to return the **size in bytes** of the data string returned by #_get_data (not the size in characters).
+    # @return [Integer]
+    def _get_data_size; end
+    protected :_get_data_size
+
+    # Returns this object's data (default implementation returns nil).
+    # Should be overridden in derived classes.
+    # @return [String,nil]
+    def _get_data; end
+    protected :_get_data
+
+    # Sets this object's data (default implementation does nothing and returns false).
+    # Should be overridden in derived classes.
+    # @param [String] buf non-nil data
+    # @return [Boolean]
+    def _set_data(buf); end
+    protected :_set_data
+
+  end
+
+end

data/lib/wx/doc/dc.rb

@@ -1,49 +1,66 @@
 
-class Wx::DC
-
-  # Provides similar functionality like wxDCBrushChanger setting the given brush as the active
-  # brush for the DC for the duration of the block execution restoring the previous brush afterwards.
-  # @param [Wx::Brush] brush new brush to use during block execution
-  # @return [void]
-  # @yieldparam [Wx::DC] dc the DC (self)
-  def with_brush(brush) end
-
-  # Provides similar functionality like wxDCPenChanger setting the given pen as the active
-  # pen for the DC for the duration of the block execution restoring the previous pen afterwards.
-  # @param [Wx::Pen] pen new pen to use during block execution
-  # @return [void]
-  # @yieldparam [Wx::DC] dc the DC (self)
-  def with_pen(pen) end
-
-  # Provides similar functionality like wxDCFontChanger setting the given font as the active
-  # font for the DC for the duration of the block execution restoring the previous font afterwards.
-  # @param [Wx::Font] font new font to use during block execution
-  # @return [void]
-  # @yieldparam [Wx::DC] dc the DC (self)
-  def with_font(font) end
-
-  # Provides similar functionality like wxDCTextColourChanger setting the given colour as the active
-  # text foreground colour for the DC for the duration of the block execution restoring the previous colour afterwards.
-  # @param [Wx::Colour] clr new colour to use during block execution
-  # @return [void]
-  # @yieldparam [Wx::DC] dc the DC (self)
-  def with_text_foreground(clr) end
-  alias :with_text_fg :with_text_foreground
-
-  # Provides similar functionality like wxDCTextBgColourChanger setting the given colour as the active
-  # text background colour for the DC for the duration of the block execution restoring the previous colour afterwards.
-  # @param [Wx::Colour] clr new colour to use during block execution
-  # @return [void]
-  # @yieldparam [Wx::DC] dc the DC (self)
-  def with_text_background(clr) end
-  alias :with_text_bg :with_text_background
-
-  # Provides similar functionality like wxDCTextBgModeChanger setting the given mode as the active
-  # background mode for the DC for the duration of the block execution restoring the previous mode afterwards.
-  # @param [Integer] mode new mode to use during block execution
-  # @return [void]
-  # @yieldparam [Wx::DC] dc the DC (self)
-  def with_background_mode(mode) end
-  alias :with_bg_mode :with_background_mode
+module Wx
+  class DC
+
+    # Provides similar functionality like wxDCBrushChanger setting the given brush as the active
+    # brush for the DC for the duration of the block execution restoring the previous brush afterwards.
+    # @param [Wx::Brush] brush new brush to use during block execution
+    # @return [void]
+    # @yieldparam [Wx::DC] dc the DC (self)
+    def with_brush(brush) end
+
+    # Provides similar functionality like wxDCPenChanger setting the given pen as the active
+    # pen for the DC for the duration of the block execution restoring the previous pen afterwards.
+    # @param [Wx::Pen] pen new pen to use during block execution
+    # @return [void]
+    # @yieldparam [Wx::DC] dc the DC (self)
+    def with_pen(pen) end
+
+    # Provides similar functionality like wxDCFontChanger setting the given font as the active
+    # font for the DC for the duration of the block execution restoring the previous font afterwards.
+    # @param [Wx::Font] font new font to use during block execution
+    # @return [void]
+    # @yieldparam [Wx::DC] dc the DC (self)
+    def with_font(font) end
+
+    # Provides similar functionality like wxDCTextColourChanger setting the given colour as the active
+    # text foreground colour for the DC for the duration of the block execution restoring the previous colour afterwards.
+    # @param [Wx::Colour] clr new colour to use during block execution
+    # @return [void]
+    # @yieldparam [Wx::DC] dc the DC (self)
+    def with_text_foreground(clr) end
+    alias :with_text_fg :with_text_foreground
+
+    # Provides similar functionality like wxDCTextBgColourChanger setting the given colour as the active
+    # text background colour for the DC for the duration of the block execution restoring the previous colour afterwards.
+    # @param [Wx::Colour] clr new colour to use during block execution
+    # @return [void]
+    # @yieldparam [Wx::DC] dc the DC (self)
+    def with_text_background(clr) end
+    alias :with_text_bg :with_text_background
+
+    # Provides similar functionality like wxDCTextBgModeChanger setting the given mode as the active
+    # background mode for the DC for the duration of the block execution restoring the previous mode afterwards.
+    # @param [Integer] mode new mode to use during block execution
+    # @return [void]
+    # @yieldparam [Wx::DC] dc the DC (self)
+    def with_background_mode(mode) end
+    alias :with_bg_mode :with_background_mode
+
+  end
+
+  class MemoryDC
+
+    # Creates a Memory DC and passes that to the given block to draw on.
+    # Automatically unselects any source object of the MemoryDC after the block finishes.
+    # @overload self.draw_on(bitmap)
+    #   @param [Wx::Bitmap]
+    #   @yieldparam [WxMemoryDC] dc
+    # @overload self.draw_on(dc)
+    #   @param [Wx::DC]
+    #   @yieldparam [WxMemoryDC] dc
+    def self.draw_on(arg, &block) end
+
+  end
 
 end

data/lib/wx/doc/event.rb

@@ -0,0 +1,24 @@
+
+module Wx
+
+  class Event
+
+    # Constructor
+    # @param [Integer] evt_type
+    # @param [Integer] id
+    # @param [Wx::EventPropagation] prop_level
+    def initialize(evt_type = Wx::EVT_NULL, id = 0, prop_level = Wx::EVENT_PROPAGATE_NONE) end
+
+    # Returns a copy of the event.
+    # Any event that is posted to the wxRuby event system for later action (via {Wx::EvtHandler#add_pending_event},
+    # {Wx::EvtHandler#queue_event} or {Wx::EvtHandler#post_event}) must implement this method.
+    # All standard wxRuby events fully implement this method and wxRuby has taken care of correctly handling this
+    # for any user defined event classes derived from either Wx::Event or Wx::CommandEvent.
+    # Creating user defined event classes derived for other classes than Wx::Event or Wx::CommandEvent is currently
+    # *not* supported in wxRuby.
+    # @return [Wx::Event]
+    def clone; end
+
+  end
+
+end

data/lib/wx/doc/events.rb

@@ -0,0 +1,14 @@
+
+module Wx
+
+  EVT_COMMAND_SCROLL_TOP = EVT_SCROLL_TOP         
+  EVT_COMMAND_SCROLL_BOTTOM = EVT_SCROLL_BOTTOM      
+  EVT_COMMAND_SCROLL_LINEUP = EVT_SCROLL_LINEUP      
+  EVT_COMMAND_SCROLL_LINEDOWN = EVT_SCROLL_LINEDOWN    
+  EVT_COMMAND_SCROLL_PAGEUP = EVT_SCROLL_PAGEUP      
+  EVT_COMMAND_SCROLL_PAGEDOWN = EVT_SCROLL_PAGEDOWN    
+  EVT_COMMAND_SCROLL_THUMBTRACK = EVT_SCROLL_THUMBTRACK  
+  EVT_COMMAND_SCROLL_THUMBRELEASE = EVT_SCROLL_THUMBRELEASE
+  EVT_COMMAND_SCROLL_CHANGED = EVT_SCROLL_CHANGED     
+  
+end

data/lib/wx/doc/evthandler.rb

@@ -65,11 +65,26 @@ class Wx::EvtHandler
 
   # Convenience evt_handler to listen to all mouse events.
   # @yieldparam [Wx::MouseEvent] event event to handle
-  def evt_mouse_events(&block) end
+  def evt_mouse_events(*args, &block) end
 
-  # Convenience evt handler to listen to all scrollwin events.
+  # Convenience evt handler to listen to all scrollwin events
+  # (from Wx::ScrolledWindow).
+  # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
+  # @yieldparam [Wx::ScrollWinEvent] event event to handle
+  def evt_scrollwin(meth = nil, &block) end
+
+  # Convenience evt handler to listen to all scroll events
+  # (from Wx::Slider and Wx::ScrollBar).
+  # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
+  # @yieldparam [Wx::ScrollWinEvent] event event to handle
+  def evt_scroll(meth = nil, &block) end
+
+  # Convenience evt handler to listen to all scroll events
+  # (from Wx::Slider and Wx::ScrollBar) with an id.
+  # @param [Integer] id window identifier
+  # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
   # @yieldparam [Wx::ScrollWinEvent] event event to handle
-  def evt_scrollwin(&block) end
+  def evt_scroll_command(id, meth = nil, &block) end
 
   # Processes Wx::WindowDestroyEvent events.
   # In wxRuby Wx::Event#skipped will be forced to true after the provided
@@ -78,6 +93,12 @@ class Wx::EvtHandler
   # @yieldparam [Wx::WindowDestroyEvent] event event to handle
   def evt_window_destroy(&block) end
 
+  # Processes {Wx::EVT_TIMER} events. See {Wx::TimerEvent}.
+  # @param [Integer,Wx::Enum,Wx::Timer] id timer id
+  # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
+  # @yieldparam [Wx::TimerEvent] event the event to handle
+  def evt_timer(id, meth = nil, &block) end
+
   # Schedule a call for asynchronous execution (at idle time).
   # @param meth [Symbol,String,Method,Proc] (name of) method or proc to call
   # @param args [Array<Object>] optional arguments to pass to the call

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

@@ -151,4 +151,4 @@ distributes implementations over various sub-modules. These sub-modules can be l
 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.
+See [here](01_packages.md) for more details on wxRuby sub-modules.

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

@@ -5,7 +5,7 @@
 
 # 6. wxRuby Geometry classes
 
-## Size (Wx::Size) and position (Wx::Point)
+## 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 
@@ -19,13 +19,13 @@ 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:
+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` and `Wx::Point` support parallel assignment semantics such that you can write code like
+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 |
     # ...    
@@ -44,6 +44,12 @@ instead of
   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

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

@@ -0,0 +1,105 @@
+<!--
+# @markup markdown
+# @title 10. wxRuby Locating and loading art
+-->
+
+# 9. 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).
+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/gc_dc.rb

@@ -0,0 +1,21 @@
+
+class Wx
+
+  class GCDC < Wx::DC
+
+    private :initialize
+
+    # Creates a Wx::GCDC instance for target and
+    # passes the instance to the given block to draw on.
+    # @overload draw_on(dc)
+    #   @param [Wx::WindowDC,Wx::MemoryDC,Wx::PrinterDC] target DC to draw on
+    #   @yieldparam [Wx::GCDC] dc GCDC instance to draw on
+    #   @return [Object] result from block
+    # @overload draw_on(dc)
+    #   @param [Wx::GraphicsContext] gc GraphicsContext to draw on
+    #   @yieldparam [Wx::GCDC] dc GCDC instance to draw on
+    #   @return [Object] result from block
+    def self.draw_on(arg) end
+  end
+
+end