wxruby3 0.9.3-x64-mingw-ucrt → 0.9.5-x64-mingw-ucrt

data/lib/wx/doc/extra/15_persistence.md

@@ -0,0 +1,148 @@
+<!--
+# @markup markdown
+# @title 15. Persistence support
+-->
+
+# 15. Persistence support
+
+## Introduction
+
+wxRuby3 fully supports the wxWidgets persistence framework.
+
+This framework provides the means to persist window (and other object) states which can than be restored when
+re-creating these objects.
+
+The persistence framework depends on the configuration framework (see [here](14_config.md)).
+
+The persistence framework includes the following components:
+
+* {Wx::PersistenceManager} which all persistent objects register themselves with. This class handles actual saving 
+  and restoring of persistent data.
+* Persistent object adapters for persistent objects. These adapters provide a bridge between the associated class – 
+which has no special persistence support – and {Wx::PersistenceManager}. All Persistent object adapters need to derive 
+from {Wx::PersistentObject} (like {Wx::PersistentWindowBase} and it's derivatives).
+* The {Wx.create_persistent_object} and {Wx.persistent_register_and_restore} methods (mainly convenience methods for 
+wxWidgets compatibility).
+
+## Persistence manager
+
+By default a global singleton manager instance is available through {Wx::PersistenceManager.get} which will be used
+by all available persistent object adapters for saving/restoring state values.
+
+An alternate (possibly customized) manager instance can be installed through {Wx::PersistenceManager.set}.
+
+## Persistent object adapters
+
+All persistent object adapters must be derived from {Wx::PersistentObject}. This class provides common methods for
+saving and restoring state values connecting to the persistence manager for actual writing and reading.
+
+All windows/objects to be persisted need to be registered with the persistence manager. Creating the correct persistent
+object adapter instance for an object to persist is abstracted away in wxWidgets by using template methods allowing
+to simply only provide the object to persist instead of having to explicitly instantiate an adapter instance and provide
+both to the persistence manager (which is however still possible).
+
+wxRuby3 replaces this convenience interface (incompatible with Ruby) by a Ruby-fied approach which relies on Rubies 
+trusted *duck typing*.<br>
+In wxRuby3 any class supported by a specific persistent object adapter class should implement the method 
+`#create_persistent_object` which should return a unique adapter instance for the object instance to be persisted 
+like this:
+
+```ruby
+class MyPersistentObject < Wx::PersistentObject
+
+  # Save the object properties.
+  # The implementation of this method should use {Wx::PersistentObject#save_value}.
+  # @return [void]
+  def save
+    # ...
+  end
+
+  # Restore the object properties.
+  # The implementation of this method should use {Wx::PersistentObject#restore_value}.
+  # @return [Boolean]
+  def restore
+    # ...
+  end
+
+  # Returns the string uniquely identifying the objects supported by this adapter.
+  # This method has default implementations in any of the built-in derived adapter classes.
+  # @return [String]
+  def get_kind
+    'MyObject'
+  end
+
+  # Returns the string uniquely identifying the object we're associated with among all the other objects of the same type.
+  # This method has a default implementation in Wx::PersistentWindowBase returning the window name.
+  # @return [String]
+  def get_name
+    'object_1'
+  end
+
+end
+
+class MyObject
+  
+  # ...
+  
+  def create_persistent_object
+    MyPersistentObject.new(self)
+  end
+  
+  # ...
+  
+end
+```
+
+## Persistent windows
+
+A number of classes provide built-in support for persistence of a number of windows or controls:
+
+* {Wx::PersistentTLW} supports top level windows (including {Wx::Frame} and {Wx::Dialog}).
+* {Wx::PersistentBookCtrl} supports the book controls {Wx::Notebook}, {Wx::Listbook}, {Wx::Toolbook} and {Wx::Choicebook}.
+* {Wx::PersistentTreeBookCtrl} supports {Wx::Treebook}
+
+All persistent window adapters are derived from {Wx::PersistentWindowBase}. This class makes sure that any window 
+registered for persisting gets automatically saved when the window is destroyed. Intermittently explicit saving still
+remains possible of course.
+
+User defined persistent window adapters can be derived from this class or any of the built-in derivatives to support
+otherwise unsupported or custom windows/controls like this:
+
+```ruby
+class PersistentButton < Wx::PersistentWindowBase
+
+  def get_kind
+    'Button'
+  end
+    
+  def save
+    save_value('w', get.size.width)
+    save_value('h', get.size.height)
+    save_value('label', get.label)
+    save_value('my_custom_value', get.my_custom_value)
+  end
+    
+  def restore
+    get.size = [Integer(restore_value('w')), Integer(restore_value('h'))]
+    get.label = restore_value('label')
+    get.my_custom_value = Float(restore_value('my_custom_value'))
+    true
+  end
+
+end
+
+class MyButton < Wx::Button
+
+  def initialize(parent=nil, name)
+    super(parent, label: '', name: name)
+    @my_custom_value = ''
+  end
+
+  attr_accessor :my_custom_value
+
+  def create_persistent_object
+    PersistentButton.new(self)
+  end
+
+end
+```

data/lib/wx/doc/gen/app_traits.rb

@@ -107,14 +107,6 @@ module Wx
     # 
     class ResourceCat < Wx::Enum
     
-      # No special category, this is the default.
-      # 
-      ResourceCat_None = Wx::StandardPaths::ResourceCat.new(0)
-      
-      # Message catalog resources category.
-      # 
-      ResourceCat_Messages = Wx::StandardPaths::ResourceCat.new(1)
-      
     end # ResourceCat
     
     # Possible values for userDir parameter of {Wx::StandardPaths#get_user_dir}.
@@ -123,34 +115,6 @@ module Wx
     # 
     class Dir < Wx::Enum
     
-      # Directory for caching files.
-      # 
-      Dir_Cache = Wx::StandardPaths::Dir.new(0)
-      
-      # Directory containing user documents.
-      # 
-      Dir_Documents = Wx::StandardPaths::Dir.new(1)
-      
-      # Directory containing files on the users desktop.
-      # 
-      Dir_Desktop = Wx::StandardPaths::Dir.new(2)
-      
-      # Directory for downloaded files.
-      # 
-      Dir_Downloads = Wx::StandardPaths::Dir.new(3)
-      
-      # Directory containing music files.
-      # 
-      Dir_Music = Wx::StandardPaths::Dir.new(4)
-      
-      # Directory containing picture files.
-      # 
-      Dir_Pictures = Wx::StandardPaths::Dir.new(5)
-      
-      # Directory containing video files.
-      # 
-      Dir_Videos = Wx::StandardPaths::Dir.new(6)
-      
     end # Dir
     
     # Possible values for {Wx::StandardPaths#set_file_layout} argument.
@@ -159,14 +123,6 @@ module Wx
     # 
     class FileLayout < Wx::Enum
     
-      # Use the classic file layout.
-      # 
-      FileLayout_Classic = Wx::StandardPaths::FileLayout.new(0)
-      
-      # Use a XDG styled file layout.
-      # 
-      FileLayout_XDG = Wx::StandardPaths::FileLayout.new(1)
-      
     end # FileLayout
     
     # Possible values for {Wx::StandardPaths#make_config_file_name} naming convention argument.
@@ -175,14 +131,6 @@ module Wx
     # 
     class ConfigFileConv < Wx::Enum
     
-      # Use the class Unix dot-file convention.
-      # 
-      ConfigFileConv_Dot = Wx::StandardPaths::ConfigFileConv.new(0)
-      
-      # Use <code></code>.conf extension for the file names.
-      # 
-      ConfigFileConv_Ext = Wx::StandardPaths::ConfigFileConv.new(1)
-      
     end # ConfigFileConv
     
     # MSW-specific function undoing the effect of {Wx::StandardPaths#ignore_app_sub_dir} calls.
@@ -269,7 +217,7 @@ module Wx
     # @param lang [String] 
     # @param category [Wx::StandardPaths::ResourceCat] 
     # @return [String]
-    def get_localized_resources_dir(lang, category=Wx::StandardPaths::ResourceCat::ResourceCat_None) end
+    def get_localized_resources_dir(lang, category=RESOURCE_CAT_NONE) end
     alias_method :localized_resources_dir, :get_localized_resources_dir
     
     # Return the directory where the loadable modules (plugins) live.
@@ -404,7 +352,7 @@ module Wx
     # @param basename [String] 
     # @param conv [Wx::StandardPaths::ConfigFileConv] 
     # @return [String]
-    def make_config_file_name(basename, conv=Wx::StandardPaths::ConfigFileConv::ConfigFileConv_Ext) end
+    def make_config_file_name(basename, conv=CONFIG_FILE_CONV_EXT) end
     
     # Returns reference to the unique global standard paths object.
     # @return [Wx::StandardPaths]

data/lib/wx/doc/gen/art_provider.rb

@@ -289,7 +289,6 @@ module Wx
   # There's another way of taking advantage of this class: you can use it in your code and use platform native icons as provided by {Wx::ArtProvider.get_bitmap_bundle} or {Wx::ArtProvider.get_icon}.
   # 
   # ## Identifying art resources
-  # 
   # Every bitmap and icon bundle are known to {Wx::ArtProvider} under a unique ID that is used when requesting a resource from it. The ID is represented by the {Wx::ArtID} type and can have one of these predefined values (you can see bitmaps represented by these constants in the Art Provider Sample):
   # 
   # - {Wx::ART_ERROR} 
@@ -417,7 +416,6 @@ module Wx
   # </div>
   # 
   # ## Clients
-  # 
   # The client is the entity that calls {Wx::ArtProvider}'s {Wx::ArtProvider.get_bitmap} or {Wx::ArtProvider.get_icon} function. It is represented by {Wx::ClientID} type and can have one of these values:
   # 
   # - {Wx::ART_TOOLBAR} 

data/lib/wx/doc/gen/aui/aui_dock_art.rb

@@ -6,83 +6,6 @@
 
 module Wx::AUI
 
-  # These are the possible pane dock art settings for {Wx::AUI::AuiDefaultDockArt}.
-  # 
-  # Category:  Window Docking (wxAUI)
-  # 
-  # @wxrb_require USE_AUI
-  class AuiPaneDockArtSetting < Wx::Enum
-  
-    # Customizes the sash size.
-    # 
-    AUI_DOCKART_SASH_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(0)
-    
-    # Customizes the caption size.
-    # 
-    AUI_DOCKART_CAPTION_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(1)
-    
-    # Customizes the gripper size.
-    # 
-    AUI_DOCKART_GRIPPER_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(2)
-    
-    # Customizes the pane border size.
-    # 
-    AUI_DOCKART_PANE_BORDER_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(3)
-    
-    # Customizes the pane button size.
-    # 
-    AUI_DOCKART_PANE_BUTTON_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(4)
-    
-    # Customizes the background colour, which corresponds to the client area.
-    # 
-    AUI_DOCKART_BACKGROUND_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(5)
-    
-    # Customizes the sash colour.
-    # 
-    AUI_DOCKART_SASH_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(6)
-    
-    # Customizes the active caption colour.
-    # 
-    AUI_DOCKART_ACTIVE_CAPTION_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(7)
-    
-    # Customizes the active caption gradient colour.
-    # 
-    AUI_DOCKART_ACTIVE_CAPTION_GRADIENT_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(8)
-    
-    # Customizes the inactive caption colour.
-    # 
-    AUI_DOCKART_INACTIVE_CAPTION_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(9)
-    
-    # Customizes the inactive gradient caption colour.
-    # 
-    AUI_DOCKART_INACTIVE_CAPTION_GRADIENT_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(10)
-    
-    # Customizes the active caption text colour.
-    # 
-    AUI_DOCKART_ACTIVE_CAPTION_TEXT_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(11)
-    
-    # Customizes the inactive caption text colour.
-    # 
-    AUI_DOCKART_INACTIVE_CAPTION_TEXT_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(12)
-    
-    # Customizes the border colour.
-    # 
-    AUI_DOCKART_BORDER_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(13)
-    
-    # Customizes the gripper colour.
-    # 
-    AUI_DOCKART_GRIPPER_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(14)
-    
-    # Customizes the caption font.
-    # 
-    AUI_DOCKART_CAPTION_FONT = Wx::AUI::AuiPaneDockArtSetting.new(15)
-    
-    # Customizes the gradient type (no gradient, vertical or horizontal)
-    # 
-    AUI_DOCKART_GRADIENT_TYPE = Wx::AUI::AuiPaneDockArtSetting.new(16)
-    
-  end # AuiPaneDockArtSetting
-  
   # These are the possible gradient dock art settings for {Wx::AUI::AuiDefaultDockArt}.
   # 
   # 
@@ -198,6 +121,83 @@ module Wx::AUI
     
   end # AuiButtonId
   
+  # These are the possible pane dock art settings for {Wx::AUI::AuiDefaultDockArt}.
+  # 
+  # Category:  Window Docking (wxAUI)
+  # 
+  # @wxrb_require USE_AUI
+  class AuiPaneDockArtSetting < Wx::Enum
+  
+    # Customizes the sash size.
+    # 
+    AUI_DOCKART_SASH_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(0)
+    
+    # Customizes the caption size.
+    # 
+    AUI_DOCKART_CAPTION_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(1)
+    
+    # Customizes the gripper size.
+    # 
+    AUI_DOCKART_GRIPPER_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(2)
+    
+    # Customizes the pane border size.
+    # 
+    AUI_DOCKART_PANE_BORDER_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(3)
+    
+    # Customizes the pane button size.
+    # 
+    AUI_DOCKART_PANE_BUTTON_SIZE = Wx::AUI::AuiPaneDockArtSetting.new(4)
+    
+    # Customizes the background colour, which corresponds to the client area.
+    # 
+    AUI_DOCKART_BACKGROUND_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(5)
+    
+    # Customizes the sash colour.
+    # 
+    AUI_DOCKART_SASH_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(6)
+    
+    # Customizes the active caption colour.
+    # 
+    AUI_DOCKART_ACTIVE_CAPTION_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(7)
+    
+    # Customizes the active caption gradient colour.
+    # 
+    AUI_DOCKART_ACTIVE_CAPTION_GRADIENT_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(8)
+    
+    # Customizes the inactive caption colour.
+    # 
+    AUI_DOCKART_INACTIVE_CAPTION_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(9)
+    
+    # Customizes the inactive gradient caption colour.
+    # 
+    AUI_DOCKART_INACTIVE_CAPTION_GRADIENT_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(10)
+    
+    # Customizes the active caption text colour.
+    # 
+    AUI_DOCKART_ACTIVE_CAPTION_TEXT_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(11)
+    
+    # Customizes the inactive caption text colour.
+    # 
+    AUI_DOCKART_INACTIVE_CAPTION_TEXT_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(12)
+    
+    # Customizes the border colour.
+    # 
+    AUI_DOCKART_BORDER_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(13)
+    
+    # Customizes the gripper colour.
+    # 
+    AUI_DOCKART_GRIPPER_COLOUR = Wx::AUI::AuiPaneDockArtSetting.new(14)
+    
+    # Customizes the caption font.
+    # 
+    AUI_DOCKART_CAPTION_FONT = Wx::AUI::AuiPaneDockArtSetting.new(15)
+    
+    # Customizes the gradient type (no gradient, vertical or horizontal)
+    # 
+    AUI_DOCKART_GRADIENT_TYPE = Wx::AUI::AuiPaneDockArtSetting.new(16)
+    
+  end # AuiPaneDockArtSetting
+  
   # {Wx::AUI::AuiDockArt} is part of the {Wx::AUI} class framework.
   # 
   # See also wxAUI Overview.

data/lib/wx/doc/gen/aui/aui_manager.rb

@@ -28,7 +28,6 @@ module Wx::AUI
   # ```
   # 
   # ## Layers, Rows and Directions, Positions
-  # 
   # Inside {Wx::AUI}, the docking layout is figured out by checking several pane parameters. Four of these are important for determining where a pane will end up:
   # 
   # - Direction: Each docked pane has a direction, Top, Bottom, Left, Right, or Center. This is fairly self-explanatory. The pane will be placed in the location specified by this variable. 

data/lib/wx/doc/gen/aui/aui_manager_event.rb

@@ -35,7 +35,7 @@ module Wx::AUI
   class AuiManagerEvent < Event
   
     # Constructor.
-    # @param type [Wx::StaticLine::EventType] 
+    # @param type [Wx::Notebook::EventType] 
     # @return [Wx::AUI::AuiManagerEvent]
     def initialize(type=Wx::EVT_NULL) end
     

data/lib/wx/doc/gen/aui/aui_mdi_client_window.rb

@@ -26,12 +26,13 @@ module Wx::AUI
     # @return [Boolean]
     def create_client(parent, style=(Wx::VSCROLL|Wx::HSCROLL)) end
     
-    # Sets the page selection.
+    # Sets the selection to the given page, returning the previous selection.
     # 
-    # Calling this method will generate a page change event.
-    # @param new_page [Integer] 
+    # Notice that the call to this function generates the page changing events, use the {Wx::AUI::AuiMDIClientWindow#change_selection} function if you don't want these events to be generated.
+    # @see Wx::AUI::AuiMDIClientWindow#get_selection 
+    # @param page [Integer] 
     # @return [Integer]
-    def set_selection(new_page) end
+    def set_selection(page) end
     alias_method :selection=, :set_selection
     
     # @return [Wx::AUI::AuiMDIChildFrame]

data/lib/wx/doc/gen/aui/aui_notebook_event.rb

@@ -181,7 +181,7 @@ module Wx::AUI
   class AuiNotebookEvent < BookCtrlEvent
   
     # Constructor.
-    # @param command_type [Wx::StaticLine::EventType] 
+    # @param command_type [Wx::Notebook::EventType] 
     # @param win_id [Integer] 
     # @return [Wx::AUI::AuiNotebookEvent]
     def initialize(command_type=Wx::EVT_NULL, win_id=0) end

data/lib/wx/doc/gen/aui/aui_tool_bar_event.rb

@@ -6,6 +6,26 @@
 
 module Wx::AUI
 
+  # 
+  # 
+  EVT_AUITOOLBAR_TOOL_DROPDOWN = 10406
+  
+  # 
+  # 
+  EVT_AUITOOLBAR_OVERFLOW_CLICK = 10407
+  
+  # 
+  # 
+  EVT_AUITOOLBAR_RIGHT_CLICK = 10408
+  
+  # 
+  # 
+  EVT_AUITOOLBAR_MIDDLE_CLICK = 10409
+  
+  # 
+  # 
+  EVT_AUITOOLBAR_BEGIN_DRAG = 10410
+  
   # {Wx::AUI::AuiToolBarStyle} is part of the {Wx::AUI} class framework, used to define the appearance of a {Wx::AUI::AuiToolBar}.
   # 
   # See also wxAUI Overview.
@@ -111,26 +131,6 @@ module Wx::AUI
     
   end # AuiToolBarToolTextOrientation
   
-  # 
-  # 
-  EVT_AUITOOLBAR_TOOL_DROPDOWN = 10406
-  
-  # 
-  # 
-  EVT_AUITOOLBAR_OVERFLOW_CLICK = 10407
-  
-  # 
-  # 
-  EVT_AUITOOLBAR_RIGHT_CLICK = 10408
-  
-  # 
-  # 
-  EVT_AUITOOLBAR_MIDDLE_CLICK = 10409
-  
-  # 
-  # 
-  EVT_AUITOOLBAR_BEGIN_DRAG = 10410
-  
   # {Wx::AUI::AuiToolBarEvent} is used for the events generated by {Wx::AUI::AuiToolBar}.
   # 
   # Category:  Window Docking (wxAUI), {Wx::Events}
@@ -139,7 +139,7 @@ module Wx::AUI
   class AuiToolBarEvent < NotifyEvent
   
     # @overload initialize(commandType=Wx::EVT_NULL, winId=0)
-    #   @param commandType [Wx::StaticLine::EventType] 
+    #   @param commandType [Wx::Notebook::EventType] 
     #   @param winId [Integer] 
     #   @return [Wx::AUI::AuiToolBarEvent]
     # @overload initialize(c)

data/lib/wx/doc/gen/book_ctrl_event.rb

@@ -25,7 +25,7 @@ module Wx
   class BookCtrlEvent < NotifyEvent
   
     # Constructor (used internally by wxWidgets only).
-    # @param eventType [Wx::StaticLine::EventType] 
+    # @param eventType [Wx::Notebook::EventType] 
     # @param id [Integer] 
     # @param sel [Integer] 
     # @param oldSel [Integer] 

data/lib/wx/doc/gen/calendar_event.rb

@@ -130,7 +130,7 @@ module Wx
     # @overload initialize(win, dt, type)
     #   @param win [Wx::Window] 
     #   @param dt [Time,Date,DateTime] 
-    #   @param type [Wx::StaticLine::EventType] 
+    #   @param type [Wx::Notebook::EventType] 
     #   @return [Wx::CalendarEvent]
     def initialize(*args) end
     

data/lib/wx/doc/gen/colour.rb

@@ -55,7 +55,6 @@ module Wx
   # You can retrieve the current system colour settings with {Wx::SystemSettings}.
   # 
   # ## Channel Accessor Functions
-  # 
   # Note that this class provides pairs of functions for each of the colour channels, i.e. red, green, blue and alpha values. The one word functions {Wx::Colour#red}, {Wx::Colour#green}, {Wx::Colour#blue} and {Wx::Colour#alpha} return the values of type unsigned char, while {Wx::Colour#get_red}, {Wx::Colour#get_green}, {Wx::Colour#get_blue} and {Wx::Colour#get_alpha} returns the same value as unsigned int. According to the C++ integer promotion rules, the result of any arithmetic expression involving the former will be (signed) int, while that of the latter will be unsigned, which is what would be commonly expected, so the latter family of functions should be typically preferred (but they are only available since wxWidgets 3.1.6).
   # 
   # Category:  Graphics Device Interface (GDI)

data/lib/wx/doc/gen/colour_dialog.rb

@@ -68,7 +68,7 @@ module Wx
     # @return [Wx::ColourDialog]
     def initialize(parent, data=nil) end
     
-    # Same as {colour_dialog}.
+    # Same as {Wx::ColourDialog#initialize}.
     # @param parent [Wx::Window] 
     # @param data [Wx::ColourData] 
     # @return [Boolean]

data/lib/wx/doc/gen/combo_box.rb

@@ -228,9 +228,10 @@ module Wx
     def get_string(n) end
     alias_method :string, :get_string
     
-    # Gets the text currently selected in the control.
+    # Returns the label of the selected item or an empty string if no item is selected.
     # 
-    # If there is no selection, the returned string is empty.
+    # 
+    # @see Wx::ComboBox#get_selection 
     # @return [String]
     def get_string_selection; end
     alias_method :string_selection, :get_string_selection