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

Sign up to get free protection for your applications and to get access to all the features.
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)