wxruby3 0.9.1-x64-mingw-ucrt → 0.9.3-x64-mingw-ucrt

data/lib/wx/doc/evthandler.rb

@@ -9,112 +9,117 @@
 
 
 
-class Wx::EvtHandler
-
-  # Removes all (Ruby) installed EventFilter-s.
-  # @return [void]
-  def self.clear_filters; end
-
-  # Public method to register the mapping of a custom event type
-  # +konstant+ (which should be a unique integer; one will be created if
-  # not supplied) to a custom event class +klass+. If +meth+ and +arity+
-  # are given, a convenience evt_handler method called +meth+ will be
-  # created, which accepts +arity+ arguments (specify both or neither).
-  # @param klass [Class] event class
-  # @param konstant [Integer] unique event type id (if nil a unique value will be autogenerated)
-  # @param meth [String,Symbol] optional event handler method name
-  # @param arity [Integer] event handler method arity (should be 0, 1 or 2 if not nil)
-  # @return [Integer] unique event type id
-  def self.register_class(klass, konstant = nil, meth = nil, arity = nil) end
-
-  def connect(first_id, last_id, evt_type, handler) end
-
-  def disconnect(first_id, last_id, evt_spec) end
-
-  # Processes an event, searching event tables and calling zero or more suitable event handler function(s).
-  #
-  # Normally, your application would not call this function: it is called in the wxWidgets implementation to
-  # dispatch incoming user interface events to the framework (and application).
-  #
-  # However, you might need to call it if implementing new functionality (such as a new control) where you
-  # define new event types, as opposed to allowing the user to override virtual functions.
-  #
-  # In wxRuby this method can not be effectively overridden.
-  # In order to override default event processing define a try_before(event) or try_after(event) method
-  # as member of a derived EvtHandler class.
-  #
-  # The normal order of event table searching is as follows:
-  #
-  # 1. {Wx::App#filter_event} is called. If it returns anything but -1 (default) the processing stops here.
-  # 2. #try_before (if it exists, otherwise the C++ default implementation) is called (this is where {Wx::Validator} are taken into account for {Wx::Window} objects). If this returns true, the function exits.
-  # 3. If the object is disabled (via a call to {Wx::EvtHandler#set_evt_handler_enabled}) the function skips to step (7).
-  # 4. Dynamic event table of the handlers bound using Bind<>() is searched in the most-recently-bound to the most-early-bound order. If a handler is found, it is executed and the function returns true unless the handler used {Wx::Event#skip} to indicate that it didn't handle the event in which case the search continues.
-  # 5. Static events table of the handlers bound using event table macros is searched for this event handler in the order of appearance of event table macros in the source code. If this fails, the base class event table is tried, and so on until no more tables exist or an appropriate function was found. If a handler is found, the same logic as in the previous step applies.
-  # 6. The search is applied down the entire chain of event handlers (usually the chain has a length of one). This chain can be formed using {Wx::EvtHandler#set_next_handler}
-  #    Note that in the case of Wx::Window you can build a stack of event handlers (see {Wx::Window#push_event_handler} for more info). If any of the handlers of the chain return true, the function exits.
-  # 7. #try_after (if it exists, otherwise the C++ default implementation) is called: for the {Wx::Window} object this may propagate the event to the window parent (recursively). If the event is still not processed, {#process_event} on the {Wx::THE_APP} object is called as the last step.
-  #
-  # Notice that steps (2)-(6) are performed in {#process_event_locally} which is called by this function.
-  #
-  # @param event [Wx::Event]  Event to process.
-  # @return [true,false] true if event has been processed
-  def process_event(event) end
-
-  # Process a command, supplying the window identifier, command event identifier, and member function or proc.
-  # @param [Integer] id window identifier
-  # @param [Integer] evt_id event type identifier
-  # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
-  # @yieldparam [Wx::CommandEvent] event event to handle
-  def evt_command(id, evt_id, meth = nil, &block) end
-
-  # Process a command for a range of window identifiers, supplying the minimum and maximum window identifiers, command event identifier, and member function or proc.
-  # @param [Integer] id1 minimum window identifier
-  # @param [Integer] id2 maximum window identifier
-  # @param [Integer] evt_id event type identifier
-  # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
-  # @yieldparam [Wx::CommandEvent] event event to handle
-  def evt_command_range(id1, id2, evt_id, meth = nil, &block) end
-
-  # Convenience evt_handler to listen to all mouse events.
-  # @yieldparam [Wx::MouseEvent] event event to handle
-  def evt_mouse_events(*args, &block) end
-
-  # 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_scroll_command(id, meth = nil, &block) end
-
-  # Processes Wx::WindowDestroyEvent events.
-  # In wxRuby Wx::Event#skipped will be forced to true after the provided
-  # handler has finished to make sure the event is propagated as it is
-  # required that Wx::App gets to handle the event in the end.
-  # @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
-  # @return [void]
-  # @yield [*args] optional arguments
-  def call_after(meth = nil, *args, &block) end
+module Wx
+
+  class EvtHandler
+
+    # Removes all (Ruby) installed EventFilter-s.
+    # @return [void]
+    def self.clear_filters; end
+
+    # Public method to register the mapping of a custom event type
+    # +konstant+ (which should be a unique integer; one will be created if
+    # not supplied) to a custom event class +klass+. If +meth+ and +arity+
+    # are given, a convenience evt_handler method called +meth+ will be
+    # created, which accepts +arity+ arguments (specify both or neither).
+    # @param klass [Class] event class
+    # @param konstant [Integer] unique event type id (if nil a unique value will be autogenerated)
+    # @param meth [String,Symbol] optional event handler method name
+    # @param arity [Integer] event handler method arity (should be 0, 1 or 2 if not nil)
+    # @return [Integer] unique event type id
+    def self.register_class(klass, konstant = nil, meth = nil, arity = nil) end
+
+    def connect(first_id, last_id, evt_type, handler) end
+
+    def disconnect(first_id, last_id, evt_spec) end
+
+    # Processes an event, searching event tables and calling zero or more suitable event handler function(s).
+    #
+    # Normally, your application would not call this function: it is called in the wxWidgets implementation to
+    # dispatch incoming user interface events to the framework (and application).
+    #
+    # However, you might need to call it if implementing new functionality (such as a new control) where you
+    # define new event types, as opposed to allowing the user to override virtual functions.
+    #
+    # In wxRuby this method can not be effectively overridden.
+    # In order to override default event processing define a try_before(event) or try_after(event) method
+    # as member of a derived EvtHandler class.
+    #
+    # The normal order of event table searching is as follows:
+    #
+    # 1. {Wx::App#filter_event} is called. If it returns anything but -1 (default) the processing stops here.
+    # 2. #try_before (if it exists, otherwise the C++ default implementation) is called (this is where {Wx::Validator} are taken into account for {Wx::Window} objects). If this returns true, the function exits.
+    # 3. If the object is disabled (via a call to {Wx::EvtHandler#set_evt_handler_enabled}) the function skips to step (7).
+    # 4. Dynamic event table of the handlers bound using Bind<>() is searched in the most-recently-bound to the most-early-bound order. If a handler is found, it is executed and the function returns true unless the handler used {Wx::Event#skip} to indicate that it didn't handle the event in which case the search continues.
+    # 5. Static events table of the handlers bound using event table macros is searched for this event handler in the order of appearance of event table macros in the source code. If this fails, the base class event table is tried, and so on until no more tables exist or an appropriate function was found. If a handler is found, the same logic as in the previous step applies.
+    # 6. The search is applied down the entire chain of event handlers (usually the chain has a length of one). This chain can be formed using {Wx::EvtHandler#set_next_handler}
+    #    Note that in the case of Wx::Window you can build a stack of event handlers (see {Wx::Window#push_event_handler} for more info). If any of the handlers of the chain return true, the function exits.
+    # 7. #try_after (if it exists, otherwise the C++ default implementation) is called: for the {Wx::Window} object this may propagate the event to the window parent (recursively). If the event is still not processed, {#process_event} on the {Wx::THE_APP} object is called as the last step.
+    #
+    # Notice that steps (2)-(6) are performed in {#process_event_locally} which is called by this function.
+    #
+    # @param event [Wx::Event]  Event to process.
+    # @return [true,false] true if event has been processed
+    def process_event(event) end
+
+    # Process a command, supplying the window identifier, command event identifier, and member function or proc.
+    # @param [Integer] id window identifier
+    # @param [Integer] evt_id event type identifier
+    # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
+    # @yieldparam [Wx::CommandEvent] event event to handle
+    def evt_command(id, evt_id, meth = nil, &block) end
+
+    # Process a command for a range of window identifiers, supplying the minimum and maximum window identifiers, command event identifier, and member function or proc.
+    # @param [Integer] id1 minimum window identifier
+    # @param [Integer] id2 maximum window identifier
+    # @param [Integer] evt_id event type identifier
+    # @param [String,Symbol,Method,Proc] meth (name of) method or event handling proc
+    # @yieldparam [Wx::CommandEvent] event event to handle
+    def evt_command_range(id1, id2, evt_id, meth = nil, &block) end
+
+    # Convenience evt_handler to listen to all mouse events.
+    # @yieldparam [Wx::MouseEvent] event event to handle
+    def evt_mouse_events(*args, &block) end
+
+    # 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_scroll_command(id, meth = nil, &block) end
+
+    # Processes Wx::WindowDestroyEvent events.
+    # In wxRuby Wx::Event#skipped will be forced to true after the provided
+    # handler has finished to make sure the event is propagated as it is
+    # required that Wx::App gets to handle the event in the end.
+    # @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
+    # @return [void]
+    # @yield [*args] optional arguments
+    def call_after(meth = nil, *args, &block) end
+
+  end
+
 end

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

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

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

data/lib/wx/doc/font.rb

@@ -6,6 +6,7 @@
 
 
 module Wx
+
   class Font
 
     # @overload find_or_create_font(point_size, family, style, weight, underline=false, facename='', encoding=Wx::FontEncoding::FONTENCODING_DEFAULT)

data/lib/wx/doc/gc_dc.rb

@@ -14,10 +14,15 @@ module Wx
     # 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
+    #   @param [Wx::WindowDC,Wx::MemoryDC] 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::PrinterDC] target DC to draw on
+    #   @yieldparam [Wx::GCDC] dc GCDC instance to draw on
+    #   @return [Object] result from block
+    #   @wxrb_require USE_PRINTING_ARCHITECTURE,WXMSW|WXOSX|USE_GTKPRINT
+    # @overload draw_on(gc)
     #   @param [Wx::GraphicsContext] gc GraphicsContext to draw on
     #   @yieldparam [Wx::GCDC] dc GCDC instance to draw on
     #   @return [Object] result from block

data/lib/wx/doc/gdi_common.rb

@@ -61,8 +61,12 @@ module Wx
 
     alias :get_x :get_width
     alias :x :get_width
+    alias :set_x :set_width
+    alias :x= :set_width
     alias :get_y :get_height
     alias :y :get_height
+    alias :set_y :set_height
+    alias :y= :set_height
 
     # Set this size to the given size's width,height values
     # @param [Wx::Size] sz