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

Sign up to get free protection for your applications and to get access to all the features.
Files changed (160) hide show
  1. checksums.yaml +4 -4
  2. data/INSTALL.md +1 -1
  3. data/README.md +2 -2
  4. data/ext/wxbase32u_gcc_custom.dll +0 -0
  5. data/ext/wxbase32u_net_gcc_custom.dll +0 -0
  6. data/ext/wxbase32u_xml_gcc_custom.dll +0 -0
  7. data/ext/wxmsw32u_aui_gcc_custom.dll +0 -0
  8. data/ext/wxmsw32u_core_gcc_custom.dll +0 -0
  9. data/ext/wxmsw32u_gl_gcc_custom.dll +0 -0
  10. data/ext/wxmsw32u_html_gcc_custom.dll +0 -0
  11. data/ext/wxmsw32u_media_gcc_custom.dll +0 -0
  12. data/ext/wxmsw32u_propgrid_gcc_custom.dll +0 -0
  13. data/ext/wxmsw32u_qa_gcc_custom.dll +0 -0
  14. data/ext/wxmsw32u_ribbon_gcc_custom.dll +0 -0
  15. data/ext/wxmsw32u_richtext_gcc_custom.dll +0 -0
  16. data/ext/wxmsw32u_stc_gcc_custom.dll +0 -0
  17. data/ext/wxmsw32u_webview_gcc_custom.dll +0 -0
  18. data/ext/wxmsw32u_xrc_gcc_custom.dll +0 -0
  19. data/lib/wx/core/book_ctrl_base.rb +16 -0
  20. data/lib/wx/core/combo_ctrl.rb +171 -0
  21. data/lib/wx/core/config.rb +454 -83
  22. data/lib/wx/core/notebook.rb +10 -8
  23. data/lib/wx/core/peristent_object.rb +15 -0
  24. data/lib/wx/core/persistence_manager.rb +39 -0
  25. data/lib/wx/core/persistent_window.rb +16 -0
  26. data/lib/wx/core/top_level_window.rb +16 -0
  27. data/lib/wx/core/treebook.rb +18 -0
  28. data/lib/wx/core.rb +4 -0
  29. data/lib/wx/doc/book_ctrl_base.rb +19 -0
  30. data/lib/wx/doc/comboctrl.rb +128 -3
  31. data/lib/wx/doc/config.rb +101 -41
  32. data/lib/wx/doc/extra/14_config.md +101 -0
  33. data/lib/wx/doc/extra/15_persistence.md +148 -0
  34. data/lib/wx/doc/gen/app_traits.rb +2 -54
  35. data/lib/wx/doc/gen/art_provider.rb +0 -2
  36. data/lib/wx/doc/gen/aui/aui_dock_art.rb +77 -77
  37. data/lib/wx/doc/gen/aui/aui_manager.rb +0 -1
  38. data/lib/wx/doc/gen/aui/aui_manager_event.rb +1 -1
  39. data/lib/wx/doc/gen/aui/aui_mdi_client_window.rb +5 -4
  40. data/lib/wx/doc/gen/aui/aui_notebook_event.rb +1 -1
  41. data/lib/wx/doc/gen/aui/aui_tool_bar_event.rb +21 -21
  42. data/lib/wx/doc/gen/book_ctrl_event.rb +1 -1
  43. data/lib/wx/doc/gen/calendar_event.rb +1 -1
  44. data/lib/wx/doc/gen/colour.rb +0 -1
  45. data/lib/wx/doc/gen/colour_dialog.rb +1 -1
  46. data/lib/wx/doc/gen/combo_box.rb +3 -2
  47. data/lib/wx/doc/gen/combo_ctrl.rb +91 -227
  48. data/lib/wx/doc/gen/core.rb +2 -2
  49. data/lib/wx/doc/gen/date_event.rb +1 -1
  50. data/lib/wx/doc/gen/dc.rb +0 -3
  51. data/lib/wx/doc/gen/dialog.rb +0 -1
  52. data/lib/wx/doc/gen/event.rb +4 -4
  53. data/lib/wx/doc/gen/event_blocker.rb +1 -1
  54. data/lib/wx/doc/gen/event_filter.rb +0 -2
  55. data/lib/wx/doc/gen/events.rb +17 -39
  56. data/lib/wx/doc/gen/file_ctrl_event.rb +1 -1
  57. data/lib/wx/doc/gen/file_dialog.rb +0 -2
  58. data/lib/wx/doc/gen/file_dialog_customize_hook.rb +55 -63
  59. data/lib/wx/doc/gen/file_dir_picker_event.rb +1 -1
  60. data/lib/wx/doc/gen/file_system.rb +1 -58
  61. data/lib/wx/doc/gen/find_dialog_event.rb +1 -1
  62. data/lib/wx/doc/gen/frame.rb +0 -1
  63. data/lib/wx/doc/gen/gdi_common.rb +0 -8
  64. data/lib/wx/doc/gen/grid/grid_cell_activatable_editor.rb +0 -2
  65. data/lib/wx/doc/gen/grid/grid_cell_attr.rb +0 -2
  66. data/lib/wx/doc/gen/grid/grid_cell_auto_wrap_string_editor.rb +0 -2
  67. data/lib/wx/doc/gen/grid/grid_cell_auto_wrap_string_renderer.rb +0 -2
  68. data/lib/wx/doc/gen/grid/grid_cell_bool_editor.rb +0 -2
  69. data/lib/wx/doc/gen/grid/grid_cell_bool_renderer.rb +0 -2
  70. data/lib/wx/doc/gen/grid/grid_cell_choice_editor.rb +0 -2
  71. data/lib/wx/doc/gen/grid/grid_cell_date_editor.rb +0 -2
  72. data/lib/wx/doc/gen/grid/grid_cell_date_renderer.rb +0 -2
  73. data/lib/wx/doc/gen/grid/grid_cell_date_time_renderer.rb +0 -2
  74. data/lib/wx/doc/gen/grid/grid_cell_editor.rb +0 -2
  75. data/lib/wx/doc/gen/grid/grid_cell_enum_editor.rb +0 -2
  76. data/lib/wx/doc/gen/grid/grid_cell_enum_renderer.rb +0 -2
  77. data/lib/wx/doc/gen/grid/grid_cell_float_editor.rb +0 -2
  78. data/lib/wx/doc/gen/grid/grid_cell_float_renderer.rb +0 -2
  79. data/lib/wx/doc/gen/grid/grid_cell_number_editor.rb +0 -2
  80. data/lib/wx/doc/gen/grid/grid_cell_number_renderer.rb +0 -2
  81. data/lib/wx/doc/gen/grid/grid_cell_renderer.rb +0 -2
  82. data/lib/wx/doc/gen/grid/grid_cell_string_renderer.rb +0 -2
  83. data/lib/wx/doc/gen/grid/grid_cell_text_editor.rb +0 -2
  84. data/lib/wx/doc/gen/grid/grid_ctrl.rb +0 -12
  85. data/lib/wx/doc/gen/grid/grid_editor_created_event.rb +1 -1
  86. data/lib/wx/doc/gen/grid/grid_event.rb +1 -1
  87. data/lib/wx/doc/gen/grid/grid_range_select_event.rb +1 -1
  88. data/lib/wx/doc/gen/grid/grid_size_event.rb +1 -1
  89. data/lib/wx/doc/gen/gui_event_loop.rb +0 -2
  90. data/lib/wx/doc/gen/header_ctrl.rb +0 -7
  91. data/lib/wx/doc/gen/header_ctrl_event.rb +1 -1
  92. data/lib/wx/doc/gen/html/html_cell_event.rb +1 -1
  93. data/lib/wx/doc/gen/image.rb +0 -2
  94. data/lib/wx/doc/gen/list_ctrl.rb +0 -1
  95. data/lib/wx/doc/gen/list_event.rb +1 -1
  96. data/lib/wx/doc/gen/media_ctrl.rb +0 -6
  97. data/lib/wx/doc/gen/media_event.rb +1 -1
  98. data/lib/wx/doc/gen/menu.rb +0 -2
  99. data/lib/wx/doc/gen/notebook.rb +0 -1
  100. data/lib/wx/doc/gen/persistence_manager.rb +135 -0
  101. data/lib/wx/doc/gen/persistent_object.rb +52 -0
  102. data/lib/wx/doc/gen/persistent_window.rb +116 -0
  103. data/lib/wx/doc/gen/pg/pg_property.rb +0 -13
  104. data/lib/wx/doc/gen/pg/pg_validation_info.rb +0 -2
  105. data/lib/wx/doc/gen/pg/property_grid.rb +0 -2
  106. data/lib/wx/doc/gen/pg/property_grid_event.rb +1 -1
  107. data/lib/wx/doc/gen/pg/property_grid_interface.rb +2 -2
  108. data/lib/wx/doc/gen/pg/property_grid_manager.rb +0 -2
  109. data/lib/wx/doc/gen/pg/property_grid_page.rb +0 -2
  110. data/lib/wx/doc/gen/pg/property_grid_page_state.rb +0 -1
  111. data/lib/wx/doc/gen/prt/post_script_dc.rb +0 -1
  112. data/lib/wx/doc/gen/rbn/ribbon_bar_event.rb +1 -1
  113. data/lib/wx/doc/gen/rbn/ribbon_button_bar_event.rb +1 -1
  114. data/lib/wx/doc/gen/rbn/ribbon_gallery_event.rb +1 -1
  115. data/lib/wx/doc/gen/rbn/ribbon_panel_event.rb +1 -1
  116. data/lib/wx/doc/gen/rbn/ribbon_tool_bar_event.rb +1 -1
  117. data/lib/wx/doc/gen/rtc/rich_text_event.rb +1 -1
  118. data/lib/wx/doc/gen/rtc/rich_text_html_handler.rb +0 -1
  119. data/lib/wx/doc/gen/rtc/rich_text_style_list_box.rb +3 -0
  120. data/lib/wx/doc/gen/rtc/rich_text_xml_handler.rb +0 -1
  121. data/lib/wx/doc/gen/scroll_bar.rb +0 -1
  122. data/lib/wx/doc/gen/sizer.rb +0 -1
  123. data/lib/wx/doc/gen/slider.rb +0 -1
  124. data/lib/wx/doc/gen/spin_double_event.rb +1 -1
  125. data/lib/wx/doc/gen/spin_event.rb +1 -1
  126. data/lib/wx/doc/gen/splash_screen.rb +1 -1
  127. data/lib/wx/doc/gen/splitter_event.rb +1 -1
  128. data/lib/wx/doc/gen/stc/styled_text_ctrl.rb +0 -1
  129. data/lib/wx/doc/gen/stc/styled_text_event.rb +1 -2
  130. data/lib/wx/doc/gen/task_bar_icon.rb +0 -1
  131. data/lib/wx/doc/gen/task_bar_icon_event.rb +1 -1
  132. data/lib/wx/doc/gen/text_ctrl.rb +0 -5
  133. data/lib/wx/doc/gen/text_entry.rb +0 -4
  134. data/lib/wx/doc/gen/tree_ctrl.rb +0 -2
  135. data/lib/wx/doc/gen/tree_event.rb +1 -1
  136. data/lib/wx/doc/gen/utils.rb +0 -16
  137. data/lib/wx/doc/gen/v_scrolled_window.rb +0 -1
  138. data/lib/wx/doc/gen/wizard.rb +0 -1
  139. data/lib/wx/doc/gen/wizard_event.rb +1 -1
  140. data/lib/wx/doc/gen/wizard_page.rb +0 -1
  141. data/lib/wx/doc/owner_drawn_combobox.rb +5 -1
  142. data/lib/wx/doc/persistence_manager.rb +36 -0
  143. data/lib/wx/doc/persistent_object.rb +27 -0
  144. data/lib/wx/doc/top_level_window.rb +19 -0
  145. data/lib/wx/doc/treebook.rb +6 -1
  146. data/lib/wx/version.rb +1 -1
  147. data/lib/wxruby_aui.so +0 -0
  148. data/lib/wxruby_core.so +0 -0
  149. data/lib/wxruby_grid.so +0 -0
  150. data/lib/wxruby_html.so +0 -0
  151. data/lib/wxruby_pg.so +0 -0
  152. data/lib/wxruby_prt.so +0 -0
  153. data/lib/wxruby_rbn.so +0 -0
  154. data/lib/wxruby_rtc.so +0 -0
  155. data/lib/wxruby_stc.so +0 -0
  156. data/samples/widgets/widgets.rb +5 -9
  157. data/tests/test_combo_ctrl.rb +196 -0
  158. data/tests/test_config.rb +207 -42
  159. data/tests/test_persistence.rb +142 -0
  160. metadata +20 -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
@@ -7,11 +7,136 @@
7
7
 
8
8
  module Wx
9
9
 
10
- class OwnerDrawnComboBox < ComboCtrl
10
+ # In order to use a custom popup with {Wx::ComboCtrl}, a class must include {Wx::ComboPopup}.
11
+ #
12
+ # For more information on how to use it, see {Wx::ComboCtrl Setting Custom Popup for Wx::ComboCtrl}.
13
+ module ComboPopup
11
14
 
12
- alias :get_item_data :get_client_object
15
+ # Returns pointer to the associated parent {Wx::ComboCtrl}.
16
+ # @return [Wx::ComboCtrl]
17
+ def get_combo_ctrl; end
13
18
 
14
- alias :set_item_data :set_client_object
19
+ # The including class must implement this to initialize its internal variables.
20
+ #
21
+ # This method is called immediately after construction finishes. m_combo member variable has been initialized before the call.
22
+ # @return [void]
23
+ def init; end
24
+
25
+ # The including class may implement this to return true if it wants to delay call to {Wx::ComboPopup#create} until the popup is shown for the first time.
26
+ #
27
+ # It is more efficient, but on the other hand it is often more convenient to have the control created immediately.
28
+ #
29
+ # <div class="wxrb-remark">
30
+ # <b>Remark:</b>
31
+ # <p>Base implementation returns false.
32
+ # </p>
33
+ # </div>
34
+ # @return [Boolean]
35
+ def lazy_create; end
36
+
37
+ # The including class must implement this to create the popup control.
38
+ #
39
+ # true if the call succeeded, false otherwise.
40
+ # @param parent [Wx::Window]
41
+ # @return [Boolean]
42
+ def create(parent) end
43
+
44
+ # You only need to implement this member function if you create your popup class in non-standard way.
45
+ #
46
+ # The default implementation can handle both multiple-inherited popup control (as seen in {Wx::ComboCtrl} samples) and one allocated separately in heap.
47
+ # If you do completely re-implement this function, make sure it calls Destroy() for the popup control and also deletes this object (usually as the last thing).
48
+ # @return [void]
49
+ def destroy_popup; end
50
+
51
+ # Implement to customize matching of value string to an item container entry.
52
+ #
53
+ # <div class="wxrb-remark">
54
+ # <b>Remark:</b>
55
+ # <p>Default implementation always return true and does not alter trueItem.
56
+ # </p>
57
+ # </div>
58
+ # @param item [String] String entered, usually by user or from SetValue() call.
59
+ # @param trueItem [Boolean] if true the true item string should be returned in case matching but different
60
+ # @return [Boolean, String] Returns true if a match is found or false if not. If trueItem == true and item matches an entry, but the entry's string representation is not exactly the same (case mismatch, for example), then the true item string should be returned as the match result.
61
+ def find_item(item, trueItem=false) end
62
+
63
+ # The including class may implement this to return adjusted size for the popup control, according to the variables given.
64
+ #
65
+ # <div class="wxrb-remark">
66
+ # <b>Remark:</b>
67
+ # <p>This function is called each time popup is about to be shown.
68
+ # </p>
69
+ # </div>
70
+ # @param minWidth [Integer] Preferred minimum width.
71
+ # @param prefHeight [Integer] Preferred height. May be -1 to indicate no preference.
72
+ # @param maxHeight [Integer] Max height for window, as limited by screen size.
73
+ # @return [Wx::Size]
74
+ def get_adjusted_size(minWidth, prefHeight, maxHeight) end
75
+
76
+ # The including class must implement this to return pointer to the associated control created in {Wx::ComboPopup#create}.
77
+ # @return [Wx::Window]
78
+ def get_control; end
79
+
80
+ # The including class must implement this to receive string value changes from {Wx::ComboCtrl}.
81
+ # @param value [String]
82
+ # @return [void]
83
+ def set_string_value(value) end
84
+
85
+ # The including class must implement this to return string representation of the value.
86
+ # @return [String]
87
+ def get_string_value; end
88
+
89
+ # The including class may implement this to do something when the parent {Wx::ComboCtrl} gets double-clicked.
90
+ # @return [void]
91
+ def on_combo_double_click; end
92
+
93
+ # The including class may implement this to receive key down events from the parent {Wx::ComboCtrl}.
94
+ #
95
+ # Events not handled should be skipped, as usual.
96
+ # @param event [Wx::KeyEvent]
97
+ # @return [void]
98
+ def on_combo_key_event(event) end
99
+
100
+ # The including class may implement this to receive char events from the parent {Wx::ComboCtrl}.
101
+ #
102
+ # Events not handled should be skipped, as usual.
103
+ # @param event [Wx::KeyEvent]
104
+ # @return [void]
105
+ def on_combo_char_event(event) end
106
+
107
+ # The including class may implement this to do special processing when popup is hidden.
108
+ # @return [void]
109
+ def on_dismiss; end
110
+
111
+ # The including class may implement this to do special processing when popup is shown.
112
+ # @return [void]
113
+ def on_popup; end
114
+
115
+ # The including class may implement this to paint the parent {Wx::ComboCtrl}.
116
+ # This is called to custom paint in the combo control itself (ie. not the popup).
117
+ #
118
+ # Default implementation draws value as string.
119
+ # @param dc [Wx::DC]
120
+ # @param rect [Wx::Rect]
121
+ # @return [void]
122
+ def paint_combo_control(dc, rect) end
123
+
124
+ end
125
+
126
+ # A Ruby interface class for default comboctrl popup classes used by {Wx::OwnerDrawnComboBox} and
127
+ # {Wx::RichTextStyleListBox}.
128
+ #
129
+ # If no custom popup control has been installed with {Wx::ComboCtrl#SetPopupControl} an instance of this
130
+ # class will be returned when {Wx::ComboCtrl#GetPopupControl} is called for either of the widgets mentioned
131
+ # above.
132
+ # <div class="wxrb-remark">
133
+ # <b>Remark:</b>
134
+ # <p>This is an abstract class that cannot be derived from.
135
+ # </p>
136
+ # </div>
137
+ class ComboPopupWx
138
+
139
+ include ComboPopup
15
140
 
16
141
  end
17
142
 
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).