Merge pull request #196 from mcorino/develop

Develop

lib/wx/core/bitmap.rb

@@ -103,10 +103,13 @@ def draw
     end
   end
 
-  def self.Bitmap(name, bmp_type = nil)
-    art_path = File.dirname(caller_path = caller_locations(1).first.absolute_path || caller_locations(1).first.path)
-    art_owner = File.basename(caller_path, '.*')
-    art_file = ArtLocator.find_art(name, art_type: :bitmap, art_path: art_path, art_section: art_owner, bmp_type: bmp_type)
+  def self.Bitmap(name, bmp_type = nil, art_path: nil, art_section: nil)
+    unless art_path && art_section
+      caller_path = caller_locations(1).first.absolute_path || caller_locations(1).first.path
+      art_path = File.dirname(caller_path) unless art_path
+      art_section = File.basename(caller_path, '.*') unless art_section
+    end
+    art_file = ArtLocator.find_art(name, art_type: :bitmap, art_path: art_path, art_section: art_section, bmp_type: bmp_type)
     ::Kernel.raise ArgumentError, "Cannot locate art file for #{name}:Bitmap" unless art_file
     Bitmap.new(art_file, bmp_type)
   end

lib/wx/core/cursor.rb

@@ -8,10 +8,13 @@
 
 module Wx
 
-  def self.Cursor(name, bmp_type = nil, *rest)
-    art_path = File.dirname(caller_path = caller_locations(1).first.absolute_path || caller_locations(1).first.path)
-    art_owner = File.basename(caller_path, '.*')
-    art_file = ArtLocator.find_art(name, art_type: :icon, art_path: art_path, art_section: art_owner, bmp_type: bmp_type)
+  def self.Cursor(name, bmp_type = nil, *rest, art_path: nil, art_section: nil)
+    unless art_path && art_section
+      caller_path = caller_locations(1).first.absolute_path || caller_locations(1).first.path
+      art_path = File.dirname(caller_path) unless art_path
+      art_section = File.basename(caller_path, '.*') unless art_section
+    end
+    art_file = ArtLocator.find_art(name, art_type: :cursor, art_path: art_path, art_section: art_section, bmp_type: bmp_type)
     ::Kernel.raise ArgumentError, "Cannot locate art file for #{name}:Cursor" unless art_file
     Cursor.new(art_file, bmp_type || Wx::Bitmap::BITMAP_TYPE_GUESS[File.extname(art_file).sub(/\A\./,'')], *rest)
   end

lib/wx/core/icon.rb

@@ -58,10 +58,13 @@ def convert_to_image
     end
   end
 
-  def self.Icon(name, bmp_type = nil, *rest)
-    art_path = File.dirname(caller_path = caller_locations(1).first.absolute_path || caller_locations(1).first.path)
-    art_owner = File.basename(caller_path, '.*')
-    art_file = ArtLocator.find_art(name, art_type: :icon, art_path: art_path, art_section: art_owner, bmp_type: bmp_type)
+  def self.Icon(name, bmp_type = nil, *rest, art_path: nil, art_section: nil)
+    unless art_path && art_section
+      caller_path = caller_locations(1).first.absolute_path || caller_locations(1).first.path
+      art_path = File.dirname(caller_path) unless art_path
+      art_section = File.basename(caller_path, '.*') unless art_section
+    end
+    art_file = ArtLocator.find_art(name, art_type: :icon, art_path: art_path, art_section: art_section, bmp_type: bmp_type)
     ::Kernel.raise ArgumentError, "Cannot locate art file for #{name}:Icon" unless art_file
     Icon.new(art_file, bmp_type, *rest)
   end

lib/wx/core/image.rb

@@ -110,10 +110,13 @@ def find_first_unused_colour(r=1, g=0, b=0)
     end
   end
 
-  def self.Image(name, bmp_type = nil, *rest)
-    art_path = File.dirname(caller_path = caller_locations(1).first.absolute_path || caller_locations(1).first.path)
-    art_owner = File.basename(caller_path, '.*')
-    art_file = ArtLocator.find_art(name, art_type: :image, art_path: art_path, art_section: art_owner, bmp_type: bmp_type)
+  def self.Image(name, bmp_type = nil, *rest, art_path: nil, art_section: nil)
+    unless art_path && art_section
+      caller_path = caller_locations(1).first.absolute_path || caller_locations(1).first.path
+      art_path = File.dirname(caller_path) unless art_path
+      art_section = File.basename(caller_path, '.*') unless art_section
+    end
+    art_file = ArtLocator.find_art(name, art_type: :image, art_path: art_path, art_section: art_section, bmp_type: bmp_type)
     ::Kernel.raise ArgumentError, "Cannot locate art file for #{name}:Image" unless art_file
     Image.new(art_file, bmp_type, *rest)
   end

lib/wx/doc/bitmap.rb

@@ -17,13 +17,15 @@ module Wx
   # Searches for an art file with basename 'name' and creates a Bitmap 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>.
+  # determine the values for the 'art_path' and 'art_section' arguments if not specified here
+  # ('art_path' is set to the absolute path to the folder holding the caller's code and 'art_section'
+  # to the basename of the caller's source file). The 'art_type' argument is set to <code>:bitmap</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)
+  # @param [String,nil] art_path base path to look up the art file
+  # @param [String,nil] art_section optional owner folder name for art files
   # @return [Wx::Bitmap]
   # @see Wx::ArtLocator::find_art
-  def self.Bitmap(name, bmp_type = nil); end
+  def self.Bitmap(name, bmp_type = nil, art_path: nil, art_section: nil); end
 
 end

lib/wx/doc/cursor.rb

@@ -5,18 +5,20 @@
 # :startdoc:
 
 
-class Wx::Cursor
+class Wx
 
   # 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>.
+  # determine the values for the 'art_path' and 'art_section' arguments if not specified here
+  # ('art_path' is set to the absolute path to the folder holding the caller's code and 'art_section'
+  # to the basename of the caller's source file). The 'art_type' argument is set to <code>:cursor</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)
+  # @param [String,nil] art_path base path to look up the art file
+  # @param [String,nil] art_section optional owner folder name for art files
   # @return [Wx::Cursor]
   # @see Wx::ArtLocator::find_art
-  def self.Cursor(name, bmp_type = nil); end
+  def self.Cursor(name, bmp_type = nil, art_path: nil, art_section: nil); end
 
 end

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

@@ -56,117 +56,118 @@ Currently the following modules have been implemented.
 
 ### Core
 
-The core wxRuby package providing the toplevel `Wx` module.
+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`
+- {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.
+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`
+- {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.
+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`
+- {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.
+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`
+- {Wx::HTML::HtmlWindow}
+- {Wx::HTML::HtmlHelpWindow}
+- {Wx::HTML::HtmlPrintout}
+- {Wx::HTML::HtmlHelpController}
+- {Wx::HTML::HtmlListBox}
 - etc
 
 ### PG - PropertyGrid control and related classes
 
-The wxRuby PG package providing the `Wx::PG` module.
+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`
+- {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.
+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`
+- {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.
+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`
+- {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.
+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`
+- {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.
+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`
+- {Wx::STC::StyledTextCtrl}
+- {Wx::STC::StyledTextEvent}
 
 ## Feature dependencies
 

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

@@ -15,8 +15,9 @@ Instead wxRuby offers a dynamic solution that is just as easy to use and even of
 ## 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>
+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.
@@ -27,7 +28,7 @@ Like the event handler macros some of these methods require a single (window) id
 
 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`).
+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:
 
@@ -96,7 +97,7 @@ will take care of checking and handling method arity.
 
 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 
+New event classes can be registered with {Wx::EvtHandler#register_class} which returns the new event type for the event 
 class like this:
 
 ```ruby
@@ -125,27 +126,27 @@ Check the reference documentation [here](https://mcorino.github.io/wxRuby3/Wx/Ev
 
 ## 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
+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)
+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
+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
+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
+{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`.
+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 
@@ -169,20 +170,22 @@ evt_handler.call_after('Call nr. %d', 1) { |fmt, num| Wx.log_info(fmt, num) }
 
 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**
+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
+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`.
+(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
+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`
+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.