wxruby3 0.9.3-x64-mingw-ucrt → 0.9.4-x64-mingw-ucrt

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. checksums.yaml +4 -4
  2. data/ext/wxbase32u_gcc_custom.dll +0 -0
  3. data/ext/wxbase32u_net_gcc_custom.dll +0 -0
  4. data/ext/wxbase32u_xml_gcc_custom.dll +0 -0
  5. data/ext/wxmsw32u_aui_gcc_custom.dll +0 -0
  6. data/ext/wxmsw32u_core_gcc_custom.dll +0 -0
  7. data/ext/wxmsw32u_gl_gcc_custom.dll +0 -0
  8. data/ext/wxmsw32u_html_gcc_custom.dll +0 -0
  9. data/ext/wxmsw32u_media_gcc_custom.dll +0 -0
  10. data/ext/wxmsw32u_propgrid_gcc_custom.dll +0 -0
  11. data/ext/wxmsw32u_qa_gcc_custom.dll +0 -0
  12. data/ext/wxmsw32u_ribbon_gcc_custom.dll +0 -0
  13. data/ext/wxmsw32u_richtext_gcc_custom.dll +0 -0
  14. data/ext/wxmsw32u_stc_gcc_custom.dll +0 -0
  15. data/ext/wxmsw32u_webview_gcc_custom.dll +0 -0
  16. data/ext/wxmsw32u_xrc_gcc_custom.dll +0 -0
  17. data/lib/wx/core/book_ctrl_base.rb +16 -0
  18. data/lib/wx/core/config.rb +454 -83
  19. data/lib/wx/core/notebook.rb +10 -8
  20. data/lib/wx/core/peristent_object.rb +15 -0
  21. data/lib/wx/core/persistence_manager.rb +39 -0
  22. data/lib/wx/core/persistent_window.rb +16 -0
  23. data/lib/wx/core/top_level_window.rb +16 -0
  24. data/lib/wx/core/treebook.rb +18 -0
  25. data/lib/wx/core.rb +4 -0
  26. data/lib/wx/doc/book_ctrl_base.rb +19 -0
  27. data/lib/wx/doc/config.rb +101 -41
  28. data/lib/wx/doc/extra/14_config.md +101 -0
  29. data/lib/wx/doc/extra/15_persistence.md +148 -0
  30. data/lib/wx/doc/gen/aui/aui_manager_event.rb +1 -1
  31. data/lib/wx/doc/gen/aui/aui_notebook_event.rb +1 -1
  32. data/lib/wx/doc/gen/aui/aui_tool_bar_event.rb +1 -1
  33. data/lib/wx/doc/gen/book_ctrl_event.rb +1 -1
  34. data/lib/wx/doc/gen/calendar_event.rb +1 -1
  35. data/lib/wx/doc/gen/core.rb +2 -2
  36. data/lib/wx/doc/gen/date_event.rb +1 -1
  37. data/lib/wx/doc/gen/event.rb +4 -4
  38. data/lib/wx/doc/gen/event_blocker.rb +1 -1
  39. data/lib/wx/doc/gen/event_filter.rb +0 -2
  40. data/lib/wx/doc/gen/events.rb +15 -15
  41. data/lib/wx/doc/gen/file_ctrl_event.rb +1 -1
  42. data/lib/wx/doc/gen/file_dialog_customize_hook.rb +2 -2
  43. data/lib/wx/doc/gen/file_dir_picker_event.rb +1 -1
  44. data/lib/wx/doc/gen/find_dialog_event.rb +1 -1
  45. data/lib/wx/doc/gen/gdi_common.rb +0 -8
  46. data/lib/wx/doc/gen/grid/grid_cell_activatable_editor.rb +0 -2
  47. data/lib/wx/doc/gen/grid/grid_cell_attr.rb +0 -2
  48. data/lib/wx/doc/gen/grid/grid_cell_auto_wrap_string_editor.rb +0 -2
  49. data/lib/wx/doc/gen/grid/grid_cell_auto_wrap_string_renderer.rb +0 -2
  50. data/lib/wx/doc/gen/grid/grid_cell_bool_editor.rb +0 -2
  51. data/lib/wx/doc/gen/grid/grid_cell_bool_renderer.rb +0 -2
  52. data/lib/wx/doc/gen/grid/grid_cell_choice_editor.rb +0 -2
  53. data/lib/wx/doc/gen/grid/grid_cell_date_editor.rb +0 -2
  54. data/lib/wx/doc/gen/grid/grid_cell_date_renderer.rb +0 -2
  55. data/lib/wx/doc/gen/grid/grid_cell_date_time_renderer.rb +0 -2
  56. data/lib/wx/doc/gen/grid/grid_cell_editor.rb +0 -2
  57. data/lib/wx/doc/gen/grid/grid_cell_enum_editor.rb +0 -2
  58. data/lib/wx/doc/gen/grid/grid_cell_enum_renderer.rb +0 -2
  59. data/lib/wx/doc/gen/grid/grid_cell_float_editor.rb +0 -2
  60. data/lib/wx/doc/gen/grid/grid_cell_float_renderer.rb +0 -2
  61. data/lib/wx/doc/gen/grid/grid_cell_number_editor.rb +0 -2
  62. data/lib/wx/doc/gen/grid/grid_cell_number_renderer.rb +0 -2
  63. data/lib/wx/doc/gen/grid/grid_cell_renderer.rb +0 -2
  64. data/lib/wx/doc/gen/grid/grid_cell_string_renderer.rb +0 -2
  65. data/lib/wx/doc/gen/grid/grid_cell_text_editor.rb +0 -2
  66. data/lib/wx/doc/gen/grid/grid_editor_created_event.rb +1 -1
  67. data/lib/wx/doc/gen/grid/grid_event.rb +1 -1
  68. data/lib/wx/doc/gen/grid/grid_range_select_event.rb +1 -1
  69. data/lib/wx/doc/gen/grid/grid_size_event.rb +1 -1
  70. data/lib/wx/doc/gen/gui_event_loop.rb +0 -2
  71. data/lib/wx/doc/gen/header_ctrl.rb +0 -6
  72. data/lib/wx/doc/gen/header_ctrl_event.rb +1 -1
  73. data/lib/wx/doc/gen/html/html_cell_event.rb +1 -1
  74. data/lib/wx/doc/gen/list_event.rb +1 -1
  75. data/lib/wx/doc/gen/media_event.rb +1 -1
  76. data/lib/wx/doc/gen/persistence_manager.rb +135 -0
  77. data/lib/wx/doc/gen/persistent_object.rb +52 -0
  78. data/lib/wx/doc/gen/persistent_window.rb +116 -0
  79. data/lib/wx/doc/gen/pg/property_grid_event.rb +1 -1
  80. data/lib/wx/doc/gen/pg/property_grid_interface.rb +2 -2
  81. data/lib/wx/doc/gen/rbn/ribbon_bar_event.rb +1 -1
  82. data/lib/wx/doc/gen/rbn/ribbon_button_bar_event.rb +1 -1
  83. data/lib/wx/doc/gen/rbn/ribbon_gallery_event.rb +1 -1
  84. data/lib/wx/doc/gen/rbn/ribbon_panel_event.rb +1 -1
  85. data/lib/wx/doc/gen/rbn/ribbon_tool_bar_event.rb +1 -1
  86. data/lib/wx/doc/gen/rtc/rich_text_event.rb +1 -1
  87. data/lib/wx/doc/gen/spin_double_event.rb +1 -1
  88. data/lib/wx/doc/gen/spin_event.rb +1 -1
  89. data/lib/wx/doc/gen/splitter_event.rb +1 -1
  90. data/lib/wx/doc/gen/stc/styled_text_event.rb +1 -1
  91. data/lib/wx/doc/gen/task_bar_icon_event.rb +1 -1
  92. data/lib/wx/doc/gen/text_entry.rb +0 -4
  93. data/lib/wx/doc/gen/tree_event.rb +1 -1
  94. data/lib/wx/doc/gen/utils.rb +0 -16
  95. data/lib/wx/doc/gen/wizard_event.rb +1 -1
  96. data/lib/wx/doc/persistence_manager.rb +36 -0
  97. data/lib/wx/doc/persistent_object.rb +27 -0
  98. data/lib/wx/doc/top_level_window.rb +19 -0
  99. data/lib/wx/doc/treebook.rb +6 -1
  100. data/lib/wx/version.rb +1 -1
  101. data/lib/wxruby_aui.so +0 -0
  102. data/lib/wxruby_core.so +0 -0
  103. data/lib/wxruby_grid.so +0 -0
  104. data/lib/wxruby_html.so +0 -0
  105. data/lib/wxruby_pg.so +0 -0
  106. data/lib/wxruby_prt.so +0 -0
  107. data/lib/wxruby_rbn.so +0 -0
  108. data/lib/wxruby_rtc.so +0 -0
  109. data/lib/wxruby_stc.so +0 -0
  110. data/samples/widgets/widgets.rb +5 -9
  111. data/tests/test_config.rb +207 -42
  112. data/tests/test_persistence.rb +142 -0
  113. metadata +18 -2
@@ -8,15 +8,17 @@
8
8
 
9
9
  # Displays a set of pages in parallel using tabs
10
10
 
11
- class Wx::Notebook
12
- # Convenience method for iterating pages
13
- def each_page
14
- if block_given?
15
- 0.upto(get_page_count - 1) do | i |
16
- yield get_page(i)
11
+ module Wx
12
+ class Notebook
13
+ # Convenience method for iterating pages
14
+ def each_page
15
+ if block_given?
16
+ 0.upto(get_page_count - 1) do | i |
17
+ yield get_page(i)
18
+ end
19
+ else
20
+ ::Enumerator.new { |y| each_page { |pg| y << pg } }
17
21
  end
18
- else
19
- ::Enumerator.new { |y| each_page { |pg| y << pg } }
20
22
  end
21
23
  end
22
24
  end
@@ -0,0 +1,15 @@
1
+ # Copyright (c) 2023 M.J.N. Corino, The Netherlands
2
+ #
3
+ # This software is released under the MIT license.
4
+
5
+ module Wx
6
+
7
+ class PersistentObject
8
+
9
+ # make these protected
10
+ protected :save_value
11
+ protected :restore_value
12
+
13
+ end
14
+
15
+ end
@@ -0,0 +1,39 @@
1
+ # Copyright (c) 2023 M.J.N. Corino, The Netherlands
2
+ #
3
+ # This software is released under the MIT license.
4
+
5
+ module Wx
6
+
7
+ # Function used to create the correct persistent adapter for the given object.
8
+ def self.create_persistent_object(obj)
9
+ obj.create_persistent_object
10
+ end
11
+
12
+ # A shorter synonym for {Wx::PersistenceManager#register_and_restore}.
13
+ def self.persistent_register_and_restore(obj, name=nil)
14
+ obj.name = name if name && !name.empty?
15
+ PersistenceManager.get.register_and_restore(obj)
16
+ end
17
+
18
+ class PersistenceManager
19
+
20
+ class << self
21
+
22
+ # Cache the global instance to keep it safe from GC
23
+
24
+ wx_get = instance_method :get
25
+ define_method :get do
26
+ @the_manager ||= wx_get.bind(self).call
27
+ end
28
+
29
+ wx_set = instance_method :set
30
+ define_method :set do |pman|
31
+ wx_set.bind(self).call(pman)
32
+ @the_manager = pman
33
+ end
34
+
35
+ end
36
+
37
+ end
38
+
39
+ end
@@ -0,0 +1,16 @@
1
+ # Copyright (c) 2023 M.J.N. Corino, The Netherlands
2
+ #
3
+ # This software is released under the MIT license.
4
+
5
+ module Wx
6
+
7
+ class PersistentWindowBase < PersistentObject
8
+
9
+ alias :get :get_object
10
+
11
+ end
12
+
13
+ # class alias
14
+ PersistentWindow = PersistentWindowBase
15
+
16
+ end
@@ -0,0 +1,16 @@
1
+ # Copyright (c) 2023 M.J.N. Corino, The Netherlands
2
+ #
3
+ # This software is released under the MIT license.
4
+
5
+ module Wx
6
+
7
+ class TopLevelWindow
8
+
9
+ # create PersistentObject for toplevel windows (incl. Dialog and Frame)
10
+ def create_persistent_object
11
+ PersistentTLW.new(self)
12
+ end
13
+
14
+ end
15
+
16
+ end
@@ -0,0 +1,18 @@
1
+ # Copyright (c) 2023 M.J.N. Corino, The Netherlands
2
+ #
3
+ # This software is released under the MIT license.
4
+
5
+ require_relative './book_ctrl_base'
6
+
7
+ module Wx
8
+
9
+ class Treebook
10
+
11
+ # Creates PersistentObject for this treebook control instance.
12
+ def create_persistent_object
13
+ PersistentTreeBookCtrl.new(self)
14
+ end
15
+
16
+ end
17
+
18
+ end
data/lib/wx/core.rb CHANGED
@@ -49,6 +49,10 @@ end
49
49
  ::Wx.include(WxRubyStyleAccessors)
50
50
 
51
51
  ::Wx.include((defined?(::WX_GLOBAL_CONSTANTS) && ::WX_GLOBAL_CONSTANTS) ? WxGlobalConstants : WxEnumConstants)
52
+ # Provide support for finding enumerator constants for nested enums in Wx::Object derived classes without
53
+ # full scoping. This does not cover non Wx::Object derived classes with nested enums in the Wx hierarchy
54
+ # but there should not be too many of those.
55
+ ::Wx::Object.include(WxEnumConstants)
52
56
 
53
57
  # Load in syntax sweeteners
54
58
  require 'wx/keyword_defs'
@@ -0,0 +1,19 @@
1
+ # :stopdoc:
2
+ # Copyright (c) 2023 M.J.N. Corino, The Netherlands
3
+ #
4
+ # This software is released under the MIT license.
5
+ # :startdoc:
6
+
7
+
8
+ module Wx
9
+
10
+ class BookCtrlBase < Control
11
+
12
+ # Creates PersistentObject for this book control instance (incl. ChoiceBook, ListBook and NoteBook).
13
+ # @see Wx.create_persistent_object
14
+ # @return [Wx::PersistentBookCtrl]
15
+ def create_persistent_object; end
16
+
17
+ end
18
+
19
+ end
data/lib/wx/doc/config.rb CHANGED
@@ -14,53 +14,35 @@ module Wx
14
14
  # as in C++.
15
15
  class ConfigBase
16
16
 
17
- # Create a new config object and sets it as the current one unless a global Ruby config was already created/installed.
17
+ # Create a new config instance and sets it as the current one unless a global config was already created/installed. If
18
+ # forced_create is true any existing global config will be replaced by a new config instance.
18
19
  # This function will create the most appropriate implementation of Wx::ConfigBase available for the current platform.
19
- # In Ruby this means that a Wx::Config instance will created and appropriately wrapped in C++.
20
- # @return [Wx::Config] the current configuration object
21
- def self.create; end
20
+ # If use_hash_config is true this means that a Wx::Config instance will created and appropriately wrapped in C++
21
+ # otherwise the default C++ config for the current/active platform will be used.
22
+ # @param [Boolean] forced_create specifies to force replacing any existing global config if true
23
+ # @param [Boolean] use_hash_config specifies to create a Ruby Hash based config when required if true
24
+ # @return [Wx::ConfigBase] the current configuration object
25
+ def self.create(forced_create=false, use_hash_config: false) end
22
26
 
23
27
  # Sets the config object as the current one, returns the previous current object (both the parameter and returned
24
28
  # value may be nil).
25
- # @param [Wx::Config,nil] config the config object to install
26
- # @return [Wx::Config] the previous current configuration object
29
+ # @param [Wx::ConfigBase,nil] config the config object to install
30
+ # @return [Wx::ConfigBase] the previous current configuration object
27
31
  def self.set(config) end
28
32
 
29
33
  # Get the current config object.
30
- # If there is no current object and create_on_demand is true, this creates one.
31
- # @param [Boolean] create_on_demand specifies whether to create a configuration object is none has been created/installed before
32
- # @return [Wx::Config,nil] the current configuration object
34
+ # If there is no current object and create_on_demand is true, this creates a default config instance appropriate for
35
+ # the current/active platform (registry based for Windows and file based otherwise).
36
+ # @param [Boolean] create_on_demand specifies whether to create a configuration object if none has been created/installed before
37
+ # @return [Wx::ConfigBase,nil] the current configuration object
33
38
  def self.get(create_on_demand=true) end
34
39
 
35
- end
36
-
37
- # Configuration class for wxRuby which stores it's settings in a (possibly nested) Hash.
38
- # This way configurations can be easily persisted using any commonly used Ruby methods like
39
- # YAML or JSON files.
40
- #
41
- # Wx::Config supports Boolean (true or false), Integer, Float and String values and nested groups
42
- # (essentially nested hashes). Any entry values set will be sanitized to match the supported types, i.e.
43
- # if the value matches a supported type the value is accepted unaltered otherwise Integer (`to_int`), Float (`to_f`)
44
- # or String (`to_s`) coercion are applied (in that order). Hash values are installed as nested groups.
45
- #
46
- # Like the C++ wxConfigBase derivatives Wx::Config supports arbitrary access using path strings which support
47
- # absolute paths ('/xxxx') and relative paths ('xxx/xxx', '../xxx', './xxxx'). Relative segments can also be
48
- # embedded in the path strings ('/aaa/bbb/../ccc').
49
- class Config < ConfigBase
50
-
51
40
  # Config path separator
52
41
  SEPARATOR = '/'
53
42
 
54
43
  # Common configuration access methods for either the root object or any nested group objects.
55
44
  module Interface
56
45
 
57
- # Iterate all settings at the current object (no recursion).
58
- # Passes key/value pairs to the given block or returns an Enumerator is no block given.
59
- # @yieldparam [String] key setting key
60
- # @yieldparam [Boolean,String,Integer,Float,Wx::Config::Group] value setting value
61
- # @return [Object,Enumerator] either the last result of the executed block or an enumerator if no block given
62
- def each(&block) end
63
-
64
46
  # Iterate all value entries at the current object (no recursion).
65
47
  # Passes key/value pairs to the given block or returns an Enumerator is no block given.
66
48
  # @yieldparam [String] key entry key
@@ -79,13 +61,13 @@ module Wx
79
61
  # any nested groups (if recurse is true)
80
62
  # @param [Boolean] recurse
81
63
  # @return [Integer] count
82
- def number_of_entries(recurse: false) end
64
+ def number_of_entries(recurse=false) end
83
65
 
84
66
  # Returns the total number of group entries at the current object only (if recurse is false) or including
85
67
  # any nested groups (if recurse is true)
86
68
  # @param [Boolean] recurse
87
69
  # @return [Integer] count
88
- def number_of_groups(recurse: false) end
70
+ def number_of_groups(recurse=false) end
89
71
 
90
72
  # Returns if a value entry exists matching the given path string.
91
73
  # Path strings can be absolute (starting with {SEPARATOR}) or relative to the current object and can have
@@ -114,10 +96,10 @@ module Wx
114
96
  # @return [Boolean,String,Integer,Float,Wx::Config::Group,nil] value entry value
115
97
  def set(key, val) end
116
98
 
117
- # Removes the entry at the current object identified by `key` if it exists and returns it's value.
118
- # @param [String] key entry key
99
+ # Removes the entry identified by `path_str` if it exists and returns it's value.
100
+ # @param [String] path_str entry path
119
101
  # @return [Boolean,String,Integer,Float,Hash,nil] entry value
120
- def delete(key) end
102
+ def delete(path_str) end
121
103
 
122
104
  # Changes key for the entry at the current object identified by `old_key` to `new_key` if it exists.
123
105
  # @param [String] old_key current entry key
@@ -126,7 +108,17 @@ module Wx
126
108
  def rename(old_key, new_key) end
127
109
 
128
110
  # Returns a value for an entry from the configuration identified by `path_str`.
129
- # Allows arbitrary access though the entire configuration using absolute or relative paths.
111
+ # Provides arbitrary access though the entire configuration using absolute or relative paths.
112
+ # Supports coercing configuration values to a specified output type (Integer,Float,String,TrueClass,FalseClass).
113
+ # By default returns un-coerced value.
114
+ # Raises exception if incompatible coercion is specified.
115
+ # @param [String] path_str
116
+ # @param [Class,Proc,nil] output output type (or converter proc) to convert to (with)
117
+ # @return [Boolean,String,Integer,Float,Wx::Config::Group,nil] value entry value
118
+ def read(path_str, output=nil) end
119
+
120
+ # Returns a value for an entry from the configuration identified by `path_str`.
121
+ # Provides arbitrary access though the entire configuration using absolute or relative paths.
130
122
  # @param [String] path_str
131
123
  # @return [Boolean,String,Integer,Float,Wx::Config::Group,nil] value entry value
132
124
  def [](path_str) end
@@ -137,7 +129,8 @@ module Wx
137
129
  # @param [String] path_str
138
130
  # @param [Boolean,String,Integer,Float,Hash,nil] val entry value
139
131
  # @return [Boolean,String,Integer,Float,Wx::Config::Group,nil] value entry value
140
- def []=(path_str, val) end
132
+ def write(path_str, val) end
133
+ alias :[]= :write
141
134
 
142
135
  # Returns the path string for the current configuration object.
143
136
  # @return [String]
@@ -166,25 +159,92 @@ module Wx
166
159
 
167
160
  end
168
161
 
162
+ end
163
+
164
+ # This is an abstract class wrapping the default C++ Config class for the active platform
165
+ # (on Windows this would be `wxRegConfig` and `wxFileConfig` otherwise).
166
+ #
167
+ # Unless {Wx::ConfigBase.create} or {Wx::ConfigBase.set} has been called this is what will be
168
+ # returned by {Wx::ConfigBase.get}.
169
+ class ConfigWx < ConfigBase
170
+
171
+ class Group
172
+
173
+ include ConfigBase::Interface
174
+
175
+ end
176
+
177
+ include ConfigBase::Interface
178
+
179
+ # Deletes all configuration content and returns true if successful.
180
+ # Also deletes any persisted storage (files or registry entries).
181
+ # @return [Boolean]
182
+ def clear; end
183
+
184
+ # Replaces the configuration content with the content of the provided Hash.
185
+ # @param [Hash] hash content to replace configuration
186
+ # @return [self]
187
+ def replace(hash) end
188
+
189
+ # Returns true if we are expanding environment variables in string values, false otherwise.
190
+ # @return [Boolean]
191
+ def is_expanding_env_vars; end
192
+ alias :expanding_env_vars? :is_expanding_env_vars
193
+
194
+ # Determine whether we wish to expand environment variables in string values.
195
+ # @param [Boolean] flag enables expanding environment variables if true, disables otherwise
196
+ def set_expand_env_vars(flag) end
197
+ alias :expand_env_vars :set_expand_env_vars
198
+
199
+ end
200
+
201
+ # Configuration class for wxRuby which stores it's settings in a (possibly nested) Hash.
202
+ # This way configurations can be easily persisted using any commonly used Ruby methods like
203
+ # YAML or JSON files.
204
+ #
205
+ # Wx::Config supports Boolean (true or false), Integer, Float and String values and nested groups
206
+ # (essentially nested hashes). Any entry values set will be sanitized to match the supported types, i.e.
207
+ # if the value matches a supported type the value is accepted unaltered otherwise Integer (`to_int`), Float (`to_f`)
208
+ # or String (`to_s`) coercion are applied (in that order). Hash values are installed as nested groups.
209
+ #
210
+ # Like the C++ wxConfigBase derivatives Wx::Config supports arbitrary access using path strings which support
211
+ # absolute paths ('/xxxx') and relative paths ('xxx/xxx', '../xxx', './xxxx'). Relative segments can also be
212
+ # embedded in the path strings ('/aaa/bbb/../ccc').
213
+ class Config < ConfigBase
214
+
169
215
  class Group
170
216
 
171
- include Interface
217
+ include ConfigBase::Interface
172
218
 
173
219
  end
174
220
 
175
- include Interface
221
+ include ConfigBase::Interface
176
222
 
177
223
  # Constructor.
178
224
  # @param [Hash] hash optional Hash initializing configuration object
179
225
  # @return [Wx::Config]
180
226
  def initialize(hash = nil)end
181
227
 
228
+ # Deletes all configuration content and returns if successful.
229
+ # @return [true]
230
+ def clear; end
231
+
182
232
  # Replaces the configuration content with the content of the provided Hash.
183
233
  # Values will be sanitized (see {Wx::Config}).
184
234
  # @param [Hash] hash content to replace configuration
185
235
  # @return [self]
186
236
  def replace(hash) end
187
237
 
238
+ # Returns true if we are expanding environment variables in string values, false otherwise.
239
+ # @return [Boolean]
240
+ def is_expanding_env_vars; end
241
+ alias :expanding_env_vars? :is_expanding_env_vars
242
+
243
+ # Determine whether we wish to expand environment variables in string values.
244
+ # @param [Boolean] flag enables expanding environment variables if true, disables otherwise
245
+ def set_expand_env_vars(flag) end
246
+ alias :expand_env_vars :set_expand_env_vars
247
+
188
248
  end
189
249
 
190
250
  end
@@ -0,0 +1,101 @@
1
+ <!--
2
+ # @markup markdown
3
+ # @title 14. Configuration support
4
+ -->
5
+
6
+ # 14. Configuration support
7
+
8
+ ## Introduction
9
+
10
+ wxRuby3 fully supports the wxWidgets config classes providing a Ruby-fied interface.
11
+
12
+ The config classes provide a way to store some application configuration information providing features
13
+ that make them very useful for storing all kinds of small to medium volumes of hierarchically-organized,
14
+ heterogeneous data.
15
+ In wxWidgets these were especially designed for storing application configuration information and intended to be
16
+ mostly limited to that. That meant the information to be stored was intended to be:
17
+
18
+ * Typed, i.e. strings, booleans or numbers for the moment. You cannot store binary data, for example.
19
+ * Small. For instance, it is not recommended to use the Windows registry (which is the default storage medium on
20
+ that platform) for amounts of data more than a couple of kilobytes.
21
+ * Not performance critical, neither from speed nor from a memory consumption point of view.
22
+
23
+ As you will see wxRuby3 extends the support in this area and provides means to forego a lot of these restrictions.
24
+
25
+ The config classes also are intended to abstract away a lot of platform differences. In this area wxRuby3 extends the
26
+ support also.
27
+
28
+ ## Default configuration support
29
+
30
+ When the default, global, config instance is used (by using {Wx::ConfigBase.get} with default argument) this will be
31
+ a platform specific instance. On Windows platforms a Windows registry based implementation is used and on other
32
+ platforms a text format configuration file.
33
+
34
+ wxRuby3 provides a single wrapper class for these with {Wx::ConfigWx}. This is an abstract class that cannot be
35
+ instantiated in Ruby which provides a common, Ruby-fied interface supported by all config classes in wxRuby3.
36
+
37
+ While wxWidgets does a decent job of abstracting platform differences it is in no way perfect in this area. With the
38
+ text format configuration files for example the stored values loose all type information since everything is stored
39
+ as strings. This also differs from the registry based implementation where some type information is not lost but some
40
+ (like boolean types) is.
41
+ This is not a problem when accessing information for which the structure and types are exactly known as the config
42
+ classes offer type specific readers (as well as writers) which coerce values to their expected types but may offer
43
+ nasty surprises when more reflectively accessing data of which the exact typing and structure is not known.
44
+
45
+ In Ruby where we more or less expect to have common API-s that can return or accept any type of object needing to be
46
+ type specific is awkward. wxRuby3 works around this as much as possible for the {Wx::ConfigWx} wrapper class but also
47
+ provides an alternative config class integrated with the wxWidgets framework that does not suffer from these restrictions.
48
+
49
+ ## Enhanced Ruby configuration support
50
+
51
+ Instead of the default, platform specific, config classes it is also possible to use a custom wxRuby3 extension providing
52
+ a config class which is implemented in pure Ruby and integrated in the wxWidgets configuration framework.
53
+ To use an instance of this class as the global config instance the {Wx::ConfigBase.create} should be called at application
54
+ initialization time with it's `:use_hash_config` keyword argument set to `true` (and possibly, to be sure, it's
55
+ `forced_create` argument set to `true` also). This would create an instance of {Wx::Config} and install that as the global config instance (if no other instance was
56
+ yet installed or, overruling that condition, if `forced_create` was set to `true`).<br>
57
+ Alternatively a {Wx::Config} (or derivative) instance could be explicitly instantiated in code and assigned as global
58
+ instance with {Wx::ConfigBase.set}.
59
+
60
+ As the keyword argument indicates {Wx::Config} is a Ruby `Hash` based config class implementation.
61
+
62
+ Value objects are stored Ruby-style as-is into it's internal hash table (maintaining full type information) and are also
63
+ retrieved as-is by default (to maintain compatibility with the {Wx::ConfigWx} wrapper type coercion options are provided).
64
+ Grouping is based of nested `Hash` instances.
65
+
66
+ Because of the `Hash` based implementation and lack of (the need for) type coercion the {Wx::Config} class does have **any**
67
+ restrictions of the type of data stored. The only possible type restrictions to enforce may come from usage contexts:
68
+
69
+ * In case of value entries shared with wxWidgets framework code (like for example entries save by the persistence
70
+ framework; see [here](15_persistence.md)) value types should be restricted to those supported by the wxWidget platform
71
+ specific classes and correspond to what the framework code expects.
72
+ * In case of the need to save/restore the configuration data to/from persistent storage which imposes type restrictions these
73
+ should be applied.
74
+
75
+ With {Wx::Config} it would be perfectly alright to store arrays or any kind of arbitrary object (only be aware that `Hash`
76
+ instances will always be expected to provide configuration structure by default) as long as these do not conflict with
77
+ expectations of framework code or storage mechanisms.
78
+
79
+ With the standard Ruby YAML and JSON serialization support this also provides improved platform independent configuration
80
+ persistence options with full type information maintainability.
81
+
82
+ ## Differences between default and enhanced configuration support
83
+
84
+ The major difference is, as described above, the absence of type restrictions in the enhanced Ruby config class {Wx::Config}.
85
+
86
+ Another difference is that {Wx::Config} will not automatically create missing groups or entries on reading. This will only
87
+ happen when writing configuration values.
88
+
89
+ A last difference is that the default support is by default backed up by persistent storage (windows registry or file) and
90
+ the wxRuby enhanced support only provides in-memory storage (`Hash` instance) by default. +
91
+ Persisting configuration data from {Wx::Config} will require coding customized storage and retrieval operations (which is
92
+ trivial using standard YAML or JSON support).
93
+
94
+ ## Differences between wxWidgets config interface and wxRuby
95
+
96
+ In wxRuby there is no option to provide a default value argument when reading values. The reasoning is that Ruby itself
97
+ provides more than enough options to elegantly provide for defaults with statement options like `var ||= default` or
98
+ `var = get('something') || default`.
99
+
100
+ As a consequence wxRuby also does not support recording defaults on read operations (and also does not provide the
101
+ corresponding option setter/getter in the interface).
@@ -0,0 +1,148 @@
1
+ <!--
2
+ # @markup markdown
3
+ # @title 15. Persistence support
4
+ -->
5
+
6
+ # 15. Persistence support
7
+
8
+ ## Introduction
9
+
10
+ wxRuby3 fully supports the wxWidgets persistence framework.
11
+
12
+ This framework provides the means to persist window (and other object) states which can than be restored when
13
+ re-creating these objects.
14
+
15
+ The persistence framework depends on the configuration framework (see [here](14_config.md)).
16
+
17
+ The persistence framework includes the following components:
18
+
19
+ * {Wx::PersistenceManager} which all persistent objects register themselves with. This class handles actual saving
20
+ and restoring of persistent data.
21
+ * Persistent object adapters for persistent objects. These adapters provide a bridge between the associated class –
22
+ which has no special persistence support – and {Wx::PersistenceManager}. All Persistent object adapters need to derive
23
+ from {Wx::PersistentObject} (like {Wx::PersistentWindowBase} and it's derivatives).
24
+ * The {Wx.create_persistent_object} and {Wx.persistent_register_and_restore} methods (mainly convenience methods for
25
+ wxWidgets compatibility).
26
+
27
+ ## Persistence manager
28
+
29
+ By default a global singleton manager instance is available through {Wx::PersistenceManager.get} which will be used
30
+ by all available persistent object adapters for saving/restoring state values.
31
+
32
+ An alternate (possibly customized) manager instance can be installed through {Wx::PersistenceManager.set}.
33
+
34
+ ## Persistent object adapters
35
+
36
+ All persistent object adapters must be derived from {Wx::PersistentObject}. This class provides common methods for
37
+ saving and restoring state values connecting to the persistence manager for actual writing and reading.
38
+
39
+ All windows/objects to be persisted need to be registered with the persistence manager. Creating the correct persistent
40
+ object adapter instance for an object to persist is abstracted away in wxWidgets by using template methods allowing
41
+ to simply only provide the object to persist instead of having to explicitly instantiate an adapter instance and provide
42
+ both to the persistence manager (which is however still possible).
43
+
44
+ wxRuby3 replaces this convenience interface (incompatible with Ruby) by a Ruby-fied approach which relies on Rubies
45
+ trusted *duck typing*.<br>
46
+ In wxRuby3 any class supported by a specific persistent object adapter class should implement the method
47
+ `#create_persistent_object` which should return a unique adapter instance for the object instance to be persisted
48
+ like this:
49
+
50
+ ```ruby
51
+ class MyPersistentObject < Wx::PersistentObject
52
+
53
+ # Save the object properties.
54
+ # The implementation of this method should use {Wx::PersistentObject#save_value}.
55
+ # @return [void]
56
+ def save
57
+ # ...
58
+ end
59
+
60
+ # Restore the object properties.
61
+ # The implementation of this method should use {Wx::PersistentObject#restore_value}.
62
+ # @return [Boolean]
63
+ def restore
64
+ # ...
65
+ end
66
+
67
+ # Returns the string uniquely identifying the objects supported by this adapter.
68
+ # This method has default implementations in any of the built-in derived adapter classes.
69
+ # @return [String]
70
+ def get_kind
71
+ 'MyObject'
72
+ end
73
+
74
+ # Returns the string uniquely identifying the object we're associated with among all the other objects of the same type.
75
+ # This method has a default implementation in Wx::PersistentWindowBase returning the window name.
76
+ # @return [String]
77
+ def get_name
78
+ 'object_1'
79
+ end
80
+
81
+ end
82
+
83
+ class MyObject
84
+
85
+ # ...
86
+
87
+ def create_persistent_object
88
+ MyPersistentObject.new(self)
89
+ end
90
+
91
+ # ...
92
+
93
+ end
94
+ ```
95
+
96
+ ## Persistent windows
97
+
98
+ A number of classes provide built-in support for persistence of a number of windows or controls:
99
+
100
+ * {Wx::PersistentTLW} supports top level windows (including {Wx::Frame} and {Wx::Dialog}).
101
+ * {Wx::PersistentBookCtrl} supports the book controls {Wx::Notebook}, {Wx::Listbook}, {Wx::Toolbook} and {Wx::Choicebook}.
102
+ * {Wx::PersistentTreeBookCtrl} supports {Wx::Treebook}
103
+
104
+ All persistent window adapters are derived from {Wx::PersistentWindowBase}. This class makes sure that any window
105
+ registered for persisting gets automatically saved when the window is destroyed. Intermittently explicit saving still
106
+ remains possible of course.
107
+
108
+ User defined persistent window adapters can be derived from this class or any of the built-in derivatives to support
109
+ otherwise unsupported or custom windows/controls like this:
110
+
111
+ ```ruby
112
+ class PersistentButton < Wx::PersistentWindowBase
113
+
114
+ def get_kind
115
+ 'Button'
116
+ end
117
+
118
+ def save
119
+ save_value('w', get.size.width)
120
+ save_value('h', get.size.height)
121
+ save_value('label', get.label)
122
+ save_value('my_custom_value', get.my_custom_value)
123
+ end
124
+
125
+ def restore
126
+ get.size = [Integer(restore_value('w')), Integer(restore_value('h'))]
127
+ get.label = restore_value('label')
128
+ get.my_custom_value = Float(restore_value('my_custom_value'))
129
+ true
130
+ end
131
+
132
+ end
133
+
134
+ class MyButton < Wx::Button
135
+
136
+ def initialize(parent=nil, name)
137
+ super(parent, label: '', name: name)
138
+ @my_custom_value = ''
139
+ end
140
+
141
+ attr_accessor :my_custom_value
142
+
143
+ def create_persistent_object
144
+ PersistentButton.new(self)
145
+ end
146
+
147
+ end
148
+ ```
@@ -35,7 +35,7 @@ module Wx::AUI
35
35
  class AuiManagerEvent < Event
36
36
 
37
37
  # Constructor.
38
- # @param type [Wx::StaticLine::EventType]
38
+ # @param type [Wx::Notebook::EventType]
39
39
  # @return [Wx::AUI::AuiManagerEvent]
40
40
  def initialize(type=Wx::EVT_NULL) end
41
41
 
@@ -181,7 +181,7 @@ module Wx::AUI
181
181
  class AuiNotebookEvent < BookCtrlEvent
182
182
 
183
183
  # Constructor.
184
- # @param command_type [Wx::StaticLine::EventType]
184
+ # @param command_type [Wx::Notebook::EventType]
185
185
  # @param win_id [Integer]
186
186
  # @return [Wx::AUI::AuiNotebookEvent]
187
187
  def initialize(command_type=Wx::EVT_NULL, win_id=0) end
@@ -139,7 +139,7 @@ module Wx::AUI
139
139
  class AuiToolBarEvent < NotifyEvent
140
140
 
141
141
  # @overload initialize(commandType=Wx::EVT_NULL, winId=0)
142
- # @param commandType [Wx::StaticLine::EventType]
142
+ # @param commandType [Wx::Notebook::EventType]
143
143
  # @param winId [Integer]
144
144
  # @return [Wx::AUI::AuiToolBarEvent]
145
145
  # @overload initialize(c)