wxruby3 0.9.0.pre.beta.13-x64-mingw-ucrt → 0.9.0.pre.rc.1-x64-mingw-ucrt

Sign up to get free protection for your applications and to get access to all the features.
Files changed (240) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +1 -0
  3. data/README.md +47 -4
  4. data/assets/hello_button.png +0 -0
  5. data/assets/hello_button_clicked.png +0 -0
  6. data/assets/hello_world.png +0 -0
  7. data/assets/repo-social-preview.png +0 -0
  8. data/ext/wxbase32u_gcc_custom.dll +0 -0
  9. data/ext/wxbase32u_net_gcc_custom.dll +0 -0
  10. data/ext/wxbase32u_xml_gcc_custom.dll +0 -0
  11. data/ext/wxmsw32u_aui_gcc_custom.dll +0 -0
  12. data/ext/wxmsw32u_core_gcc_custom.dll +0 -0
  13. data/ext/wxmsw32u_gl_gcc_custom.dll +0 -0
  14. data/ext/wxmsw32u_html_gcc_custom.dll +0 -0
  15. data/ext/wxmsw32u_media_gcc_custom.dll +0 -0
  16. data/ext/wxmsw32u_propgrid_gcc_custom.dll +0 -0
  17. data/ext/wxmsw32u_qa_gcc_custom.dll +0 -0
  18. data/ext/wxmsw32u_ribbon_gcc_custom.dll +0 -0
  19. data/ext/wxmsw32u_richtext_gcc_custom.dll +0 -0
  20. data/ext/wxmsw32u_stc_gcc_custom.dll +0 -0
  21. data/ext/wxmsw32u_webview_gcc_custom.dll +0 -0
  22. data/ext/wxmsw32u_xrc_gcc_custom.dll +0 -0
  23. data/lib/wx/accessors.rb +8 -2
  24. data/lib/wx/core/art_locator.rb +2 -2
  25. data/lib/wx/core/artprovider.rb +2 -2
  26. data/lib/wx/core/bitmap.rb +6 -5
  27. data/lib/wx/core/bitmap_combobox.rb +34 -0
  28. data/lib/wx/core/controlwithitems.rb +52 -14
  29. data/lib/wx/core/cursor.rb +1 -1
  30. data/lib/wx/core/dc.rb +0 -20
  31. data/lib/wx/core/event_blocker.rb +14 -0
  32. data/lib/wx/core/events/evt_list.rb +12 -0
  33. data/lib/wx/core/evthandler.rb +36 -0
  34. data/lib/wx/core/find_replace_dialog.rb +24 -0
  35. data/lib/wx/core/icon.rb +1 -1
  36. data/lib/wx/core/image.rb +1 -1
  37. data/lib/wx/core/paintdc.rb +8 -0
  38. data/lib/wx/core/text_entry.rb +15 -0
  39. data/lib/wx/core/v_list_box.rb +13 -0
  40. data/lib/wx/core/window.rb +1 -1
  41. data/lib/wx/doc/busy_info.rb +21 -0
  42. data/lib/wx/doc/client_dc.rb +28 -0
  43. data/lib/wx/doc/controlwithitems.rb +11 -0
  44. data/lib/wx/doc/dc.rb +0 -14
  45. data/lib/wx/doc/event_blocker.rb +27 -0
  46. data/lib/wx/doc/evthandler.rb +4 -0
  47. data/lib/wx/doc/extra/02_lifecycles.md +49 -0
  48. data/lib/wx/doc/extra/10_art.md +1 -1
  49. data/lib/wx/doc/extra/11_drawing_and_dc.md +62 -0
  50. data/lib/wx/doc/gen/about_dialog_info.rb +27 -24
  51. data/lib/wx/doc/gen/accelerator.rb +11 -12
  52. data/lib/wx/doc/gen/app.rb +6 -3
  53. data/lib/wx/doc/gen/art_provider.rb +53 -29
  54. data/lib/wx/doc/gen/aui/aui_manager.rb +4 -0
  55. data/lib/wx/doc/gen/aui/aui_mdi_child_frame.rb +1 -1
  56. data/lib/wx/doc/gen/aui/aui_pane_info.rb +2 -0
  57. data/lib/wx/doc/gen/aui/aui_tab_ctrl.rb +2 -0
  58. data/lib/wx/doc/gen/bitmap.rb +25 -25
  59. data/lib/wx/doc/gen/bitmap_combo_box.rb +157 -0
  60. data/lib/wx/doc/gen/box_sizer.rb +6 -8
  61. data/lib/wx/doc/gen/brush.rb +2 -0
  62. data/lib/wx/doc/gen/busy_info.rb +52 -46
  63. data/lib/wx/doc/gen/caret.rb +0 -4
  64. data/lib/wx/doc/gen/check_list_box.rb +0 -2
  65. data/lib/wx/doc/gen/choice.rb +1 -5
  66. data/lib/wx/doc/gen/client_dc.rb +13 -18
  67. data/lib/wx/doc/gen/clipboard.rb +30 -27
  68. data/lib/wx/doc/gen/collapsible_pane.rb +11 -9
  69. data/lib/wx/doc/gen/colour.rb +6 -3
  70. data/lib/wx/doc/gen/colour_dialog.rb +111 -23
  71. data/lib/wx/doc/gen/combo_box.rb +2 -4
  72. data/lib/wx/doc/gen/control.rb +20 -18
  73. data/lib/wx/doc/gen/core.rb +2 -2
  74. data/lib/wx/doc/gen/cursor.rb +18 -50
  75. data/lib/wx/doc/gen/data_format.rb +0 -2
  76. data/lib/wx/doc/gen/data_object.rb +37 -44
  77. data/lib/wx/doc/gen/dc.rb +16 -24
  78. data/lib/wx/doc/gen/defs.rb +3 -40
  79. data/lib/wx/doc/gen/dialog.rb +21 -17
  80. data/lib/wx/doc/gen/dir_dialog.rb +10 -8
  81. data/lib/wx/doc/gen/event.rb +2 -2
  82. data/lib/wx/doc/gen/event_blocker.rb +49 -0
  83. data/lib/wx/doc/gen/event_filter.rb +95 -0
  84. data/lib/wx/doc/gen/event_list.rb +16 -2
  85. data/lib/wx/doc/gen/events.rb +103 -112
  86. data/lib/wx/doc/gen/evt_handler.rb +28 -52
  87. data/lib/wx/doc/gen/file_dialog.rb +8 -4
  88. data/lib/wx/doc/gen/find_replace_dialog.rb +1 -1
  89. data/lib/wx/doc/gen/font.rb +10 -2
  90. data/lib/wx/doc/gen/font_data.rb +2 -0
  91. data/lib/wx/doc/gen/font_dialog.rb +1 -1
  92. data/lib/wx/doc/gen/frame.rb +4 -3
  93. data/lib/wx/doc/gen/fs_file.rb +8 -0
  94. data/lib/wx/doc/gen/gcdc.rb +2 -22
  95. data/lib/wx/doc/gen/gdi_common.rb +18 -2
  96. data/lib/wx/doc/gen/gdi_object.rb +2 -0
  97. data/lib/wx/doc/gen/graphics_context.rb +4 -43
  98. data/lib/wx/doc/gen/graphics_object.rb +2 -0
  99. data/lib/wx/doc/gen/grid/grid_cell_attr.rb +2 -1
  100. data/lib/wx/doc/gen/grid/grid_ctrl.rb +4 -2
  101. data/lib/wx/doc/gen/grid/grid_table_message.rb +2 -0
  102. data/lib/wx/doc/gen/grid_bag_sizer.rb +4 -0
  103. data/lib/wx/doc/gen/help_controller.rb +4 -1
  104. data/lib/wx/doc/gen/html/html_cell.rb +4 -1
  105. data/lib/wx/doc/gen/html/html_help_controller.rb +4 -1
  106. data/lib/wx/doc/gen/html/html_help_data.rb +4 -0
  107. data/lib/wx/doc/gen/html/html_help_window.rb +2 -1
  108. data/lib/wx/doc/gen/html/html_list_box.rb +138 -11
  109. data/lib/wx/doc/gen/html/html_window.rb +9 -3
  110. data/lib/wx/doc/gen/icon.rb +7 -1
  111. data/lib/wx/doc/gen/icon_location.rb +2 -0
  112. data/lib/wx/doc/gen/image.rb +15 -8
  113. data/lib/wx/doc/gen/keyboard_state.rb +6 -0
  114. data/lib/wx/doc/gen/list_box.rb +0 -11
  115. data/lib/wx/doc/gen/list_ctrl.rb +10 -13
  116. data/lib/wx/doc/gen/locale.rb +7 -3
  117. data/lib/wx/doc/gen/log.rb +6 -2
  118. data/lib/wx/doc/gen/mdi_frame.rb +2 -0
  119. data/lib/wx/doc/gen/media_ctrl.rb +2 -0
  120. data/lib/wx/doc/gen/memory_dc.rb +105 -18
  121. data/lib/wx/doc/gen/menu.rb +4 -2
  122. data/lib/wx/doc/gen/menu_bar.rb +0 -2
  123. data/lib/wx/doc/gen/menu_item.rb +9 -3
  124. data/lib/wx/doc/gen/message_dialog.rb +6 -3
  125. data/lib/wx/doc/gen/mirror_dc.rb +2 -8
  126. data/lib/wx/doc/gen/mouse_state.rb +2 -0
  127. data/lib/wx/doc/gen/multi_choice_dialog.rb +0 -2
  128. data/lib/wx/doc/gen/non_owned_window.rb +2 -1
  129. data/lib/wx/doc/gen/notebook.rb +4 -2
  130. data/lib/wx/doc/gen/paint_dc.rb +2 -6
  131. data/lib/wx/doc/gen/palette.rb +3 -3
  132. data/lib/wx/doc/gen/pen.rb +6 -1
  133. data/lib/wx/doc/gen/pg/pg_editor.rb +2 -1
  134. data/lib/wx/doc/gen/pg/pg_multi_button.rb +4 -0
  135. data/lib/wx/doc/gen/pg/pg_properties.rb +30 -3
  136. data/lib/wx/doc/gen/pg/pg_property.rb +30 -4
  137. data/lib/wx/doc/gen/pg/pg_validation_info.rb +2 -0
  138. data/lib/wx/doc/gen/pg/property_grid.rb +5 -2
  139. data/lib/wx/doc/gen/pg/property_grid_interface.rb +6 -2
  140. data/lib/wx/doc/gen/pg/property_grid_manager.rb +2 -0
  141. data/lib/wx/doc/gen/pg/property_grid_page_state.rb +2 -0
  142. data/lib/wx/doc/gen/picker_base.rb +2 -1
  143. data/lib/wx/doc/gen/platform_info.rb +4 -1
  144. data/lib/wx/doc/gen/property_sheet_dialog.rb +2 -0
  145. data/lib/wx/doc/gen/prt/post_script_dc.rb +2 -8
  146. data/lib/wx/doc/gen/prt/print_data.rb +6 -0
  147. data/lib/wx/doc/gen/prt/printer.rb +0 -3
  148. data/lib/wx/doc/gen/prt/printer_dc.rb +2 -6
  149. data/lib/wx/doc/gen/radio_box.rb +2 -2
  150. data/lib/wx/doc/gen/rbn/ribbon_art_provider.rb +6 -0
  151. data/lib/wx/doc/gen/rbn/ribbon_panel.rb +1 -1
  152. data/lib/wx/doc/gen/region.rb +2 -0
  153. data/lib/wx/doc/gen/rtc/rich_text_buffer.rb +6 -0
  154. data/lib/wx/doc/gen/rtc/rich_text_ctrl.rb +0 -4
  155. data/lib/wx/doc/gen/rtc/rich_text_header_footer_data.rb +2 -0
  156. data/lib/wx/doc/gen/rtc/rich_text_html_handler.rb +2 -1
  157. data/lib/wx/doc/gen/rtc/symbol_picker_dialog.rb +2 -0
  158. data/lib/wx/doc/gen/screen_dc.rb +2 -0
  159. data/lib/wx/doc/gen/scroll_bar.rb +2 -1
  160. data/lib/wx/doc/gen/scrolled_canvas.rb +4 -8
  161. data/lib/wx/doc/gen/scrolled_control.rb +4 -8
  162. data/lib/wx/doc/gen/scrolled_window.rb +4 -8
  163. data/lib/wx/doc/gen/search_ctrl.rb +131 -0
  164. data/lib/wx/doc/gen/single_choice_dialog.rb +0 -2
  165. data/lib/wx/doc/gen/sizer.rb +14 -3
  166. data/lib/wx/doc/gen/splash_screen.rb +2 -0
  167. data/lib/wx/doc/gen/static_box.rb +6 -3
  168. data/lib/wx/doc/gen/static_box_sizer.rb +2 -1
  169. data/lib/wx/doc/gen/status_bar.rb +0 -5
  170. data/lib/wx/doc/gen/stc/styled_text_ctrl.rb +4 -5
  171. data/lib/wx/doc/gen/svg_file_dc.rb +10 -11
  172. data/lib/wx/doc/gen/text_ctrl.rb +10 -3
  173. data/lib/wx/doc/gen/text_entry.rb +8 -3
  174. data/lib/wx/doc/gen/text_entry_dialog.rb +4 -2
  175. data/lib/wx/doc/gen/timer_event.rb +2 -0
  176. data/lib/wx/doc/gen/tool_bar.rb +8 -4
  177. data/lib/wx/doc/gen/top_level_window.rb +5 -2
  178. data/lib/wx/doc/gen/tree_ctrl.rb +0 -6
  179. data/lib/wx/doc/gen/ui_action_simulator.rb +100 -0
  180. data/lib/wx/doc/gen/utils.rb +1 -1
  181. data/lib/wx/doc/gen/v_list_box.rb +36 -26
  182. data/lib/wx/doc/gen/validator.rb +2 -1
  183. data/lib/wx/doc/gen/variant.rb +10 -0
  184. data/lib/wx/doc/gen/window.rb +38 -17
  185. data/lib/wx/doc/gen/window_dc.rb +2 -0
  186. data/lib/wx/doc/gen/window_disabler.rb +2 -0
  187. data/lib/wx/doc/gen/wizard_page_simple.rb +2 -0
  188. data/lib/wx/doc/gen/xml_node.rb +6 -0
  189. data/lib/wx/doc/gen/xml_resource.rb +4 -1
  190. data/lib/wx/doc/memory_dc.rb +75 -0
  191. data/lib/wx/doc/mirror_dc.rb +16 -0
  192. data/lib/wx/doc/prt/printer_dc.rb +26 -0
  193. data/lib/wx/doc/screen_dc.rb +10 -6
  194. data/lib/wx/doc/svg_file_dc.rb +20 -0
  195. data/lib/wx/doc/v_list_box.rb +9 -0
  196. data/lib/wx/doc/window_disabler.rb +10 -0
  197. data/lib/wx/global_const.rb +24 -18
  198. data/lib/wx/html/keyword_defs.rb +6 -7
  199. data/lib/wx/html/require.rb +1 -0
  200. data/lib/wx/html/simple_html_listbox.rb +105 -0
  201. data/lib/wx/keyword_defs.rb +7 -0
  202. data/lib/wx/version.rb +1 -1
  203. data/lib/wx/wxruby/cmd/test.rb +1 -1
  204. data/lib/wxruby_aui.so +0 -0
  205. data/lib/wxruby_core.so +0 -0
  206. data/lib/wxruby_grid.so +0 -0
  207. data/lib/wxruby_html.so +0 -0
  208. data/lib/wxruby_pg.so +0 -0
  209. data/lib/wxruby_prt.so +0 -0
  210. data/lib/wxruby_rbn.so +0 -0
  211. data/lib/wxruby_rtc.so +0 -0
  212. data/lib/wxruby_stc.so +0 -0
  213. data/rakelib/install.rb +3 -1
  214. data/rakelib/yard/yard/relative_markdown_links.rb +5 -1
  215. data/samples/bigdemo/wxArtProvider.rbw +5 -4
  216. data/samples/controls/controls.rb +2 -2
  217. data/samples/controls/htlbox.rb +411 -0
  218. data/samples/controls/tn_htlbox.png +0 -0
  219. data/samples/drawing/graphics_drawing.rb +1 -2
  220. data/samples/drawing/{svgtest.rb → image_prt.rb} +49 -18
  221. data/samples/drawing/tn_image_prt.png +0 -0
  222. data/samples/propgrid/propgrid.rb +23 -21
  223. data/samples/ribbon/ribbon.rb +47 -46
  224. data/tests/lib/wxapp_runner.rb +3 -3
  225. data/tests/lib/wxframe_runner.rb +59 -0
  226. data/tests/test_app_event_filter.rb +74 -0
  227. data/tests/test_art_provider.rb +52 -0
  228. data/tests/test_clipboard.rb +2 -1
  229. data/tests/test_event_handling.rb +199 -16
  230. data/tests/test_events.rb +4 -11
  231. data/tests/test_gdi_object.rb +161 -0
  232. data/tests/test_intl.rb +11 -14
  233. data/tests/test_item_data.rb +33 -1
  234. data/tests/test_std_controls.rb +147 -0
  235. metadata +38 -8
  236. data/lib/wx/doc/gen/auto_buffered_paint_dc.rb +0 -47
  237. data/lib/wx/doc/gen/buffered_dc.rb +0 -95
  238. data/lib/wx/doc/gen/buffered_paint_dc.rb +0 -55
  239. data/lib/wx/doc/gen/colour_data.rb +0 -96
  240. data/samples/drawing/tn_svgtest.png +0 -0
data/lib/wx/doc/dc.rb CHANGED
@@ -49,18 +49,4 @@ module Wx
49
49
 
50
50
  end
51
51
 
52
- class MemoryDC
53
-
54
- # Creates a Memory DC and passes that to the given block to draw on.
55
- # Automatically unselects any source object of the MemoryDC after the block finishes.
56
- # @overload self.draw_on(bitmap)
57
- # @param [Wx::Bitmap]
58
- # @yieldparam [WxMemoryDC] dc
59
- # @overload self.draw_on(dc)
60
- # @param [Wx::DC]
61
- # @yieldparam [WxMemoryDC] dc
62
- def self.draw_on(arg, &block) end
63
-
64
- end
65
-
66
52
  end
@@ -0,0 +1,27 @@
1
+
2
+ module Wx
3
+
4
+ class EventBlocker
5
+
6
+ class << self
7
+
8
+ # Constructs the blocker for the given window and for the given event type and passes the blocker to the
9
+ # given block. The blocker is destroyed after the block returns.
10
+ #
11
+ # If type is Wx::EVT_ANY, then all events for that window are blocked. You can call #block after creation to
12
+ # add other event types to the list of events to block.
13
+ #
14
+ # @note Note that the win window must remain alive until the given block returns (i.e. until Wx::EventBlocker's
15
+ # object destruction).
16
+ # @param [Wx::Window] win the window to block events for
17
+ # @param [Integer] evt_type the event type to block
18
+ # @yieldparam [Wx::EventBlocker] blkr the blocker object
19
+ # @return [Object] the value returned by the block
20
+ def blocked_for(win, evt_type=Wx::EVT_ANY) end
21
+ alias :block_for :blocked_for
22
+
23
+ end
24
+
25
+ end
26
+
27
+ end
@@ -3,6 +3,10 @@
3
3
 
4
4
  class Wx::EvtHandler
5
5
 
6
+ # Removes all (Ruby) installed EventFilter-s.
7
+ # @return [void]
8
+ def self.clear_filters; end
9
+
6
10
  # Public method to register the mapping of a custom event type
7
11
  # +konstant+ (which should be a unique integer; one will be created if
8
12
  # not supplied) to a custom event class +klass+. If +meth+ and +arity+
@@ -114,3 +114,52 @@ destroy these on a regular basis when not used (closed) possibly re-creating the
114
114
 
115
115
  Dialogs are special cases of toplevel windows which are not automatically destroyed when closed. The wxRuby library
116
116
  therefor provides special support to ease handling the destruction of these. See [here](03_dialogs.md) for more details.
117
+
118
+ ## Object identities
119
+
120
+ One of the trickier things to handle correctly in the kind of native extensions like wxRuby is maintaining object
121
+ identities i.e. keeping native instances synced with their Ruby wrapper counter parts.
122
+
123
+ Whenever a native extension is allowed to call back into Ruby space we encounter the problem the we need to map any
124
+ native object data provided for the call to the right Ruby types and when necessary to the right Ruby instance (object
125
+ identity).
126
+
127
+ Objects that are considered POD types (*plain old data* types) like numerics, booleans, strings, arrays and hashes do
128
+ not require maintaining *object identity*. For these objects it is enough to map them to the right Ruby type before
129
+ passing them on to Ruby space.
130
+
131
+ For a lot of other objects though it is essential to not only map to the right **most derived** class type but also to
132
+ the exact Ruby instance which was originally instantiated as wrapper for the native object if any exists (in case no
133
+ Ruby instance existed yet a new instance of the correct **most derived** class should be instantiated at that point).
134
+ The reason this is important is 1. because the Ruby instance may have been used to identify, link to or otherwise
135
+ reference other data and/or functionality related to that specific Ruby/native pair and 2. the Ruby instance could
136
+ contain data elements (instance variables) related to that specific Ruby/native pair.<br>
137
+ In the case of wxRuby Window instance for example it is common to derive custom Window classes with custom behaviour and
138
+ corresponding instance variables that drive that behaviour. When an event handler or an overloaded native method is passed
139
+ a native window object we absolutely need to be able to map that native object to the correct Ruby wrapper instance so
140
+ all information stays in sync.
141
+
142
+ For this purpose wxRuby uses *object tracking* i.e. maintaining hash tables mapping native object pointers to Ruby object
143
+ values. Whenever a tracked object is instantiated it is registered and can from than on be resolved whenever needed to map
144
+ from native object to Ruby object.<br>
145
+ Of course this also means wxRuby has to track object destruction so mappings can be removed when a native object is
146
+ destructed.<br>
147
+ Additionally the tracking tables are also used to mark Ruby objects during the GC marking phase so they do not get garbage
148
+ collected whenever they are not referenced in Ruby space anymore but still functioning in native space (this is for example
149
+ a common situation for many child windows created but not permanently referenced in Ruby space).
150
+
151
+ Tracking and resolving mappings from tracking tables produces a certain computing overhead but testing has shown this to be
152
+ absolutely acceptable for normal applications.
153
+
154
+ There are however quite a lot of wrapped native objects in wxRuby for which *object identity* is not essential. For these
155
+ object tracking has been disabled for their classes. This means these kind of classes/object should **not** be derived from
156
+ (if even possible and/or useful) to add functionality/information or their identity used as key to link other information.<br>
157
+ These classes include:
158
+ - classes considered POD types like Wx::Size, Wx::Point, Wx::RealPoint, Wx::Rect, Wx::GBSpan, Wx::GBPosition, Wx::BusyInfoFlags,
159
+ Wx::AboutDialogInfo
160
+ - final non-instantiatable classes like the Wx::DC (Device Context) class family, Wx::GraphicsContext, Wx::WindowsDisabler,
161
+ Wx::EventBlocker, Wx::BusyInfo
162
+ - classes with native singleton objects like Wx::Clipboard
163
+ - the reference counted GDI objects like Wx::Pen, Wx::Brush, Wx::Colour, Wx::Cursor, Wx::Bitmap, Wx::Icon
164
+
165
+ The reference documentation will note untracked object classes.
@@ -3,7 +3,7 @@
3
3
  # @title 10. wxRuby Locating and loading art
4
4
  -->
5
5
 
6
- # 9. wxRuby Locating and loading art
6
+ # 10. wxRuby Locating and loading art
7
7
 
8
8
  ## Introduction
9
9
 
@@ -0,0 +1,62 @@
1
+ <!--
2
+ # @markup markdown
3
+ # @title 11. wxRuby Drawing and Device Contexts
4
+ -->
5
+
6
+ # 11. wxRuby Drawing and Device Contexts (DC)
7
+
8
+ In wxRuby the Wx::DC class family provides functionality for drawing to windows, bitmaps, printers etc.
9
+
10
+ What most of these classes have in common is that actual drawing output is buffered until the time the
11
+ device context object is destroyed.
12
+ For this reason the common practice in wxWidgets C++ code would be to create temporary DC objects on the
13
+ stack and draw on them while they are in scope (for several classes it is even strongly advised to never create
14
+ them any other way and to never keep objects alive out of scope). When leaving the scope these object would than be
15
+ automatically destroyed and the any buffered output flushed to the final target.
16
+
17
+ In Ruby this approach is impossible as Ruby is a purely dynamic language and does not **this kind** of scope bound
18
+ life cycles. Any DC object created would have to be dynamically created and due to the properties of the GC driven
19
+ life cycles could well be kept alive beyond the scope of it's creation. This will not always cause problems but could
20
+ and does not really have an upside.
21
+
22
+ To prevent confusion and potential problems wxRuby defines all `Wx::DC` derived classes to be abstract classes that
23
+ cannot be instantiated using `new`. Rather all `Wx::DC` derived classes provide `::draw_on` factory methods to create
24
+ temporary dc objects that will be passed on to blocks given and will only exist for the duration of the execution of
25
+ the block. This will guarantee proper DC cleanup when leaving it's usage scope.
26
+
27
+ > Note that it is a **BAD** idea to think about storing the dc reference provide to the block for later access!
28
+
29
+ A typical usage of a `::draw_on` method would be:
30
+
31
+ ```ruby
32
+ myTestBitmap1x = Wx::Bitmap.new(60, 15, 32)
33
+ Wx::MemoryDC.draw_on(myTestBitmap1x) do |mdc|
34
+ mdc.set_background(Wx::WHITE_BRUSH)
35
+ mdc.clear
36
+ mdc.set_pen(Wx::BLACK_PEN)
37
+ mdc.set_brush(Wx::WHITE_BRUSH)
38
+ mdc.draw_rectangle(0, 0, 60, 15)
39
+ mdc.draw_line(0, 0, 59, 14)
40
+ mdc.set_text_foreground(Wx::BLACK)
41
+ mdc.draw_text("x1", 0, 0)
42
+ end
43
+ ```
44
+
45
+ ## Windows, Wx::PaintDC and Wx::AutoBufferedPaintDC
46
+
47
+ The `Wx::PaintDC` and `Wx::AutoBufferedPaintDC` classes provide `::draw_on` methods just like all other DC classes but
48
+ this is mostly to be consistent.
49
+
50
+ In this case it is recommended to instead use the `Wx::Window#paint` or `Wx::Window#paint_buffered` methods as these
51
+ provide some optimizations with regard to automatically detecting is the methods are called inside `Wx::EVT_PAINT`
52
+ handlers (which should normally be the case) or not.
53
+
54
+ So the typical way to do buffered painting inside a windows `Wx::EVT_PAINT` handler would be something like:
55
+
56
+ ```ruby
57
+ def on_paint(_event)
58
+ self.paint_buffered do |dc|
59
+ # ... do some drawing ...
60
+ end
61
+ end
62
+ ```
@@ -9,17 +9,17 @@ module Wx
9
9
  # This function shows the standard about dialog containing the information specified in info.
10
10
  # If the current platform has a native about dialog which is capable of showing all the fields in info, the native dialog is used, otherwise the function falls back to the generic wxWidgets version of the dialog, i.e. does the same thing as {generic_about_box}.
11
11
  # Here is an example of how this function may be used:
12
- #
13
- # void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event))
14
- # {
15
- # wxAboutDialogInfo info;
16
- # info.SetName(_("My Program"));
17
- # info.SetVersion(_("1.2.3 Beta"));
18
- # info.SetDescription(_("This program does something great."));
19
- # info.SetCopyright(wxT("(C) 2007 Me <my@email.addre.ss>"));
20
- #
21
- # wxAboutBox(info);
22
- # }
12
+ # ```ruby
13
+ # def show_simple_about_dialog(event)
14
+ # info = Wx::AboutDialogInfo.new
15
+ # info.name = 'My Program'
16
+ # info.version = '1.2.3 Beta'
17
+ # info.description = 'This program does something great.'
18
+ # info.copyright = '(C) 2007 Me <my@email.addre.ss>'
19
+ #
20
+ # Wx.about_box(info)
21
+ # end
22
+ # ```
23
23
  #
24
24
  # Please see the Dialogs Sample for more examples of using this function and {Wx::AboutDialogInfo} for the description of the information which can be shown in the about dialog.
25
25
  # @param info [Wx::AboutDialogInfo]
@@ -39,20 +39,21 @@ module Wx
39
39
  # {Wx::AboutDialogInfo} contains information shown in the standard About dialog displayed by the {about_box} function.
40
40
  # This class contains the general information about the program, such as its name, version, copyright and so on, as well as lists of the program developers, documentation writers, artists and translators. The simple properties from the former group are represented as a string with the exception of the program icon and the program web site, while the lists from the latter group are stored as {Wx::ArrayString} and can be either set entirely at once using {Wx::AboutDialogInfo#set_developers} and similar functions or built one by one using {Wx::AboutDialogInfo#add_developer} etc.
41
41
  # Please also notice that while all the main platforms have the native implementation of the about dialog, they are often more limited than the generic version provided by wxWidgets and so the generic version is used if {Wx::AboutDialogInfo} has any fields not supported by the native version. Currently GTK+ version supports all the possible fields natively but MSW and Mac versions don't support URLs, licence text nor custom icons in the about dialog and if either of those is used, {about_box} will automatically use the generic version so you should avoid specifying these fields to achieve more native look and feel.
42
- # Example of usage:
43
42
  #
44
- # void MyFrame::OnAbout(wxCommandEvent& WXUNUSED(event))
45
- # {
46
- # wxAboutDialogInfo aboutInfo;
47
- # aboutInfo.SetName("MyApp");
48
- # aboutInfo.SetVersion(MY_APP_VERSION_STRING);
49
- # aboutInfo.SetDescription(_("My wxWidgets-based application!"));
50
- # aboutInfo.SetCopyright("(C) 1992-2023");
51
- # aboutInfo.SetWebSite("http://myapp.org");
52
- # aboutInfo.AddDeveloper("My Self");
53
- #
54
- # wxAboutBox(aboutInfo);
55
- # }
43
+ # Example of usage:
44
+ #
45
+ # ```ruby
46
+ # def on_about(event)
47
+ # info = Wx::AboutDialogInfo.new
48
+ # info.name = 'MyApp'
49
+ # info.version = MY_APP_VERSION_STRING
50
+ # info.description = 'My wxWidgets-based application!'
51
+ # info.copyright = '(C) 1992-2023'
52
+ # info.add_developer('My Self')
53
+ #
54
+ # Wx.about_box(info)
55
+ # end
56
+ # ```
56
57
  #
57
58
  # ===
58
59
  #
@@ -60,6 +61,8 @@ module Wx
60
61
  # @see Wx::AboutDialogInfo#set_artists
61
62
  #
62
63
  #
64
+ #
65
+ # @note This class is <b>untracked</b> and should not be derived from nor instances extended!
63
66
  class AboutDialogInfo < ::Object
64
67
 
65
68
  # Default constructor leaves all fields are initially uninitialized, in general you should call at least {Wx::AboutDialogInfo#set_version}, {Wx::AboutDialogInfo#set_copyright} and {Wx::AboutDialogInfo#set_description}.
@@ -55,7 +55,7 @@ module Wx
55
55
  # @overload initialize(flags=0, keyCode=0, cmd=0, item=nil)
56
56
  # Constructor.
57
57
  # @param flags [Integer] A combination of the {Wx::AcceleratorEntryFlags} values, which indicates which modifier keys are held down.
58
- # @param keyCode [Integer] The keycode to be detected. See {Wx::KeyCode} for a full list of keycodes.
58
+ # @param keyCode [Integer,String] The keycode (or character) to be detected. See {Wx::KeyCode} for a full list of keycodes.
59
59
  # @param cmd [Integer] The menu or control command identifier (ID).
60
60
  # @param item [Wx::MenuItem] The menu item associated with this accelerator.
61
61
  # @return [AcceleratorEntry]
@@ -87,7 +87,7 @@ module Wx
87
87
 
88
88
  # Sets the accelerator entry parameters.
89
89
  # @param flags [Integer] A combination of the {Wx::AcceleratorEntryFlags} values, which indicates which modifier keys are held down.
90
- # @param keyCode [Integer] The keycode to be detected. See {Wx::KeyCode} for a full list of keycodes.
90
+ # @param keyCode [Integer,String] The keycode to be detected. See {Wx::KeyCode} for a full list of keycodes.
91
91
  # @param cmd [Integer] The menu or control command identifier (ID).
92
92
  # @param item [Wx::MenuItem] The menu item associated with this accelerator.
93
93
  # @return [void]
@@ -124,15 +124,15 @@ module Wx
124
124
  # An accelerator table allows the application to specify a table of keyboard shortcuts for menu or button commands.
125
125
  # The object {Wx::NULL_ACCELERATOR_TABLE} is defined to be a table with no data, and is the initial accelerator table for a window.
126
126
  # Example:
127
- #
128
- # wxAcceleratorEntry entries[4];
129
- # entries[0].Set(wxACCEL_CTRL, (int) 'N', ID_NEW_WINDOW);
130
- # entries[1].Set(wxACCEL_CTRL, (int) 'X', wxID_EXIT);
131
- # entries[2].Set(wxACCEL_SHIFT, (int) 'A', ID_ABOUT);
132
- # entries[3].Set(wxACCEL_NORMAL, WXK_DELETE, wxID_CUT);
133
- #
134
- # wxAcceleratorTable accel(4, entries);
135
- # frame->SetAcceleratorTable(accel);
127
+ # ```ruby
128
+ # entries = [
129
+ # Wx::AcceleratorEntry.new(Wx::ACCEL_CTRL, 'N', ID_NEW_WINDOW),
130
+ # Wx::AcceleratorEntry.new(Wx::ACCEL_CTRL, 'X', Wx::ID_EXIT),
131
+ # Wx::AcceleratorEntry.new(Wx::ACCEL_CTRL, 'A', Wx::ID_ABOUT),
132
+ # Wx::AcceleratorEntry.new(Wx::ACCEL_CTRL, 'N', Wx::ID_CUT)
133
+ # ]
134
+ # frame.accelerator_table = Wx::AcceleratorTable[entries]
135
+ # ```
136
136
  #
137
137
  # An accelerator takes precedence over normal processing and can be a convenient way to program some event handling. For example, you can use an accelerator table to enable a dialog with a multi-line text control to accept CTRL-Enter as meaning 'OK'.
138
138
  #
@@ -151,7 +151,6 @@ module Wx
151
151
  # @return [AcceleratorTable]
152
152
  # @overload initialize(entries)
153
153
  # Initializes the accelerator table from an array of {Wx::AcceleratorEntry}.
154
- # <b>{Wx::Perl} Note:</b> The {Wx::Perl} constructor accepts a list of either Wx::AcceleratorEntry objects or references to 3-element arrays [flags, keyCode, cmd] , like the parameters of Wx::AcceleratorEntry::new.
155
154
  # @param entries [Array<Wx::AcceleratorEntry>] The array of entries.
156
155
  # @return [AcceleratorTable]
157
156
  # @overload initialize(resource)
@@ -172,8 +172,9 @@ module Wx
172
172
  # Sets the 'top' window.
173
173
  # You can call this from within {Wx::App#on_init} to let wxWidgets know which is the main window. You don't have to set the top window; it is only a convenience so that (for example) certain dialogs without parents can use a specific window as the top window.
174
174
  # If no top window is specified by the application, wxWidgets just uses the first frame or dialog (or better, any {Wx::TopLevelWindow}) in its top-level window list, when it needs to use the top window. If you previously called {Wx::App#set_top_window} and now you need to restore this automatic behaviour you can call
175
- #
175
+ # ```
176
176
  # wxApp::SetTopWindow(NULL)
177
+ # ```
177
178
  # .
178
179
  # @see Wx::App#get_top_window
179
180
  # @see Wx::App#on_init
@@ -342,12 +343,14 @@ module Wx
342
343
  # Sets the C locale to the default locale for the current environment.
343
344
  # It is advised to call this to ensure that the underlying toolkit uses the locale in which the numbers and monetary amounts are shown in the format expected by user and so on.
344
345
  # Calling this function is roughly equivalent to calling
345
- #
346
+ # ```
346
347
  # setlocale(LC_ALL, "");
348
+ # ```
347
349
  # but performs additional toolkit-specific tasks under some platforms and so should be used instead of <code>setlocale()</code> itself. Alternatively, you can use {Wx::Locale} to change the locale with more control.
348
350
  # Notice that this does not change the global C++ locale, you need to do it explicitly if you want, e.g.
349
- #
351
+ # ```
350
352
  # std::locale::global(std::locale(""));
353
+ # ```
351
354
  # but be warned that locale support in C++ standard library can be poor or worse under some platforms.
352
355
  # @return [void]
353
356
  def set_c_locale; end
@@ -270,28 +270,19 @@ module Wx
270
270
  # When wxWidgets needs to display an icon or a bitmap (e.g. in the standard file dialog), it does not use a hard-coded resource but asks {Wx::ArtProvider} for it instead. This way users can plug in their own {Wx::ArtProvider} class and easily replace standard art with their own version.
271
271
  # All that is needed is to derive a class from {Wx::ArtProvider}, override either its {Wx::ArtProvider#create_bitmap} and/or its {Wx::ArtProvider#create_icon_bundle} methods and register the provider with {Wx::ArtProvider.push}:
272
272
  #
273
- # class MyProvider : public wxArtProvider
274
- # {
275
- # protected:
276
- # // Override this method to return a bundle containing the required
277
- # // bitmap in all available sizes.
278
- # wxBitmapBundle CreateBitmapBundle(const wxArtID& id,
279
- # const wxArtClient& client,
280
- # const wxSize& size) override;
281
- #
282
- # // If all bitmaps are available in a single size only, it may be
283
- # // simpler to override just this one.
284
- # wxBitmap CreateBitmap(const wxArtID& id,
285
- # const wxArtClient& client,
286
- # const wxSize& size) override;
287
- #
288
- # // optionally override this one as well
289
- # wxIconBundle CreateIconBundle(const wxArtID& id,
290
- # const wxArtClient& client) override;
291
- # { ... }
292
- # };
293
- # ...
294
- # wxArtProvider::Push(new MyProvider);
273
+ # Example:
274
+ #
275
+ # ```ruby
276
+ # class MyArtProvider < Wx::ArtProvider
277
+ #
278
+ # def create_bitmap(id, client, size)
279
+ # # ... create and return bitmap
280
+ # end
281
+ #
282
+ # end
283
+ #
284
+ # Wx::ArtProvider.push(MyArtProvider.new)
285
+ # ```
295
286
  #
296
287
  # If you need bitmap images (of the same artwork) that should be displayed at different sizes you should probably consider overriding {Wx::ArtProvider#create_icon_bundle} and supplying icon bundles that contain different bitmap sizes.
297
288
  # There's another way of taking advantage of this class: you can use it in your code and use platform native icons as provided by {Wx::ArtProvider.get_bitmap_bundle} or {Wx::ArtProvider.get_icon}.
@@ -359,14 +350,12 @@ module Wx
359
350
  # - {Wx::ART_REMOVABLE}
360
351
  # - {Wx::ART_WX_LOGO} (since 3.1.6)
361
352
  #
362
- # When building with {Wx::NO_IMPLICIT_WXSTRING_ENCODING} defined (see wxString Overview for more details), you need to explicitly use {ascii_str} around these constants.
363
- #
364
- # Additionally, any string recognized by custom art providers registered using {Wx::ArtProvider.push} may be used.
365
353
  # When running under GTK+ 2, GTK+ stock item IDs (e.g. <code>"gtk-cdrom"</code>) may be used as well:
366
- #
367
- # #ifdef __WXGTK__
368
- # wxBitmap bmp = wxArtProvider::GetBitmap("gtk-cdrom", wxART_MENU);
369
- # #endif
354
+ # ```ruby
355
+ # if Wx::PLATFORM == 'WXGTK'
356
+ # bmp = Wx::ArtProvider.get_bitmap("gtk-cdrom", Wx::ART_MENU)
357
+ # end
358
+ # ```
370
359
  # For a list of the GTK+ stock items please refer to the GTK+ documentation page. It is also possible to load icons from the current icon theme by specifying their name (without extension and directory components). Icon themes recognized by GTK+ follow the freedesktop.org Icon Themes specification. Note that themes are not guaranteed to contain all icons, so {Wx::ArtProvider} may return {Wx::NULL_BITMAP} or {Wx::NULL_ICON}. The default theme is typically installed in <code>/usr/share/icons/hicolor</code>.
371
360
  #
372
361
  # == Clients
@@ -491,6 +480,41 @@ module Wx
491
480
  # @return [Wx::Icon]
492
481
  def self.get_message_box_icon(flags) end
493
482
 
483
+
484
+ protected
485
+
486
+ # Derived art provider classes may override this method to return the size of the images used by this provider.
487
+ # Note that the returned size should be in DPI-independent pixels, i.e. DIPs. The default implementation returns the result of {Wx::ArtProvider.get_native_dip_size_hint}.
488
+ # @param client [Wx::ArtClient]
489
+ # @return [Wx::Size]
490
+ def do_get_size_hint(client) end
491
+
492
+ # Derived art provider classes may override this method to create requested art resource.
493
+ # For bitmaps available in more than one size, {Wx::ArtProvider#create_bitmap_bundle} should be overridden instead.
494
+ # Note that returned bitmaps are cached by {Wx::ArtProvider} and it is therefore not necessary to optimize {Wx::ArtProvider#create_bitmap} for speed (e.g. you may create {Wx::Bitmap} objects from XPMs here).
495
+ #
496
+ # This is not part of {Wx::ArtProvider}'s public API, use {Wx::ArtProvider.get_bitmap} or {Wx::ArtProvider.get_icon_bundle} or {Wx::ArtProvider.get_icon} to query {Wx::ArtProvider} for a resource.
497
+ # @see Wx::ArtProvider#create_icon_bundle
498
+ # @param id [Wx::ArtID] {Wx::ArtID} unique identifier of the bitmap.
499
+ # @param client [Wx::ArtClient] {Wx::ArtClient} identifier of the client (i.e. who is asking for the bitmap). This only serves as a hint.
500
+ # @param size [Array(Integer, Integer), Wx::Size] Preferred size of the bitmap. The function may return a bitmap of different dimensions, it will be automatically rescaled to meet client's request.
501
+ # @return [Wx::Bitmap]
502
+ def create_bitmap(id, client, size) end
503
+
504
+ # Override this method to create the requested art resources available in more than one size.
505
+ # Unlike {Wx::ArtProvider#create_bitmap}, this method can be overridden to return the same bitmap in several (or all, if {Wx::BitmapBundle.from_svg} is used) sizes at once, which will allow selecting the size best suited for the current display resolution automatically.
506
+ # @param id [Wx::ArtID] {Wx::ArtID} unique identifier of the bitmap.
507
+ # @param client [Wx::ArtClient] {Wx::ArtClient} identifier of the client (i.e. who is asking for the bitmap). This only serves as a hint.
508
+ # @param size [Array(Integer, Integer), Wx::Size] Default size of the bitmaps returned by the bundle.
509
+ # @return [Wx::BitmapBundle]
510
+ def create_bitmap_bundle(id, client, size) end
511
+
512
+ # This method is similar to {Wx::ArtProvider#create_bitmap} but can be used when a bitmap (or an icon) exists in several sizes.
513
+ # @param id [Wx::ArtID]
514
+ # @param client [Wx::ArtClient]
515
+ # @return [Wx::IconBundle]
516
+ def create_icon_bundle(id, client) end
517
+
494
518
  end # ArtProvider
495
519
 
496
520
 
@@ -12,15 +12,19 @@ module Wx::AUI
12
12
  # {Wx::AUI::AuiManager} works as follows: the programmer adds panes to the class, or makes changes to existing pane properties (dock position, floating state, show state, etc.). To apply these changes, {Wx::AUI::AuiManager}'s {Wx::AUI::AuiManager#update} function is called. This batch processing can be used to avoid flicker, by modifying more than one pane at a time, and then "committing" all of the changes at once by calling {Wx::AUI::AuiManager#update}.
13
13
  # Panes can be added quite easily:
14
14
  #
15
+ # ```
15
16
  # wxTextCtrl* text1 = new wxTextCtrl(this, -1);
16
17
  # wxTextCtrl* text2 = new wxTextCtrl(this, -1);
17
18
  # m_mgr.AddPane(text1, wxLEFT, "Pane Caption");
18
19
  # m_mgr.AddPane(text2, wxBOTTOM, "Pane Caption");
19
20
  # m_mgr.Update();
21
+ # ```
20
22
  #
21
23
  # Later on, the positions can be modified easily. The following will float an existing pane in a tool window:
22
24
  #
25
+ # ```
23
26
  # m_mgr.GetPane(text1).Float();
27
+ # ```
24
28
  #
25
29
  # == Layers, Rows and Directions, Positions
26
30
  #
@@ -57,7 +57,7 @@ module Wx::AUI
57
57
  def set_icons(icons) end
58
58
  alias_method :icons=, :set_icons
59
59
 
60
- # @return [void]
60
+ # @return [Wx::IconBundle]
61
61
  def get_icons; end
62
62
  alias_method :icons, :get_icons
63
63
 
@@ -128,6 +128,8 @@ module Wx::AUI
128
128
  # @see Wx::AUI::AuiDockArt
129
129
  #
130
130
  #
131
+ #
132
+ # @note This class is <b>untracked</b> and should not be derived from nor instances extended!
131
133
  class AuiPaneInfo < ::Object
132
134
 
133
135
  # name of the pane
@@ -139,6 +139,8 @@ module Wx::AUI
139
139
  #
140
140
  # Category: Window Docking (wxAUI)
141
141
  #
142
+ #
143
+ # @note This class is <b>untracked</b> and should not be derived from nor instances extended!
142
144
  class AuiTabContainerButton < ::Object
143
145
 
144
146
  end # AuiTabContainerButton
@@ -34,6 +34,8 @@ module Wx
34
34
  # @see Wx::PixelData
35
35
  #
36
36
  #
37
+ #
38
+ # @note This class is <b>untracked</b> and should not be derived from nor instances extended!
37
39
  class Bitmap < GDIObject
38
40
 
39
41
  # @overload initialize()
@@ -43,9 +45,10 @@ module Wx
43
45
  # @overload initialize(bitmap)
44
46
  # Copy constructor, uses reference counting.
45
47
  # To make a real copy, you can use:
46
- #
47
- # wxBitmap newBitmap = oldBitmap.GetSubBitmap(
48
- # wxRect(0, 0, oldBitmap.GetWidth(), oldBitmap.GetHeight()));
48
+ # ```ruby
49
+ # newBitmap = oldBitmap.get_sub_bitmap(
50
+ # Wx::Rect.new(0, 0, oldBitmap.width, oldBitmap.height))
51
+ # ```
49
52
  # @param bitmap [Wx::Bitmap]
50
53
  # @return [Bitmap]
51
54
  # @overload initialize(width, height, depth=Wx::BITMAP_SCREEN_DEPTH)
@@ -350,37 +353,34 @@ module Wx
350
353
  # - A custom bitmap source using {Wx::BitmapBundleImpl}.
351
354
  # - A single {Wx::Bitmap} or {Wx::Image} for backwards compatibility.
352
355
  # Objects of {Wx::BitmapBundle} class have value-like semantics, i.e. they can be copied around freely (and cheaply) and don't need to be allocated on the heap. However they usually are created using static factory functions (known as "pseudo-constructors") such as {Wx::BitmapBundle.from_bitmaps} instead of using the real constructors.
353
- # Example of using this class to initialize a toolbar in a frame constructor:
354
- #
355
- # MyFrame::MyFrame()
356
- # : wxFrame(nullptr, wxID_ANY, "My frame")
357
- # {
358
- # ...
359
- # wxToolBar* toolBar = CreateToolBar();
360
- #
361
- # wxVector<wxBitmap> bitmaps;
362
- # bitmaps.push_back(wxBITMAP_PNG(open_32x32));
363
- # bitmaps.push_back(wxBITMAP_PNG(open_48x48));
364
- # bitmaps.push_back(wxBITMAP_PNG(open_64x64));
365
- #
366
- # toolBar->AddTool(wxID_OPEN, "Open", wxBitmapBundle::FromBitmaps(bitmaps));
367
- # }
356
+ # ```ruby
357
+ # class MyFrame < Wx::Frame
358
+ #
359
+ # def initialize
360
+ # super(nil, Wx::ID_ANY, "My frame")
361
+ # # ...
362
+ # tool_bar = create_toolBar
363
+ #
364
+ # bitmaps = [
365
+ # Wx::Bitmap(:open_32x32, Wx::BitmapType::BITMAP_TYPE_PNG),
366
+ # Wx::Bitmap(:open_48x48, Wx::BitmapType::BITMAP_TYPE_PNG),
367
+ # Wx::Bitmap(:open_64x64, Wx::BitmapType::BITMAP_TYPE_PNG)
368
+ # ]
369
+ #
370
+ # tool_bar.add_tool(Wx::ID_OPEN, "Open", Wx::BitmapBundle.from_bitmaps(bitmaps))
371
+ # end
372
+ # ```
368
373
  #
369
374
  # The code shown above will use 32 pixel bitmap in normal DPI, 64 pixel bitmap in "high DPI", i.e. pixel-doubling or 200% resolution, and 48 pixel bitmap in 150% resolution. For all the other resolutions, the bitmap with the "best" matching size will be used, where "best" is deemed to be the bitmap with the closest size if it can be used without scaling (so that in this example the 64px bitmap will be used at 175% resolution because it typically looks much better than either downscaling it or upscaling the 48px bitmap to 56px) or, if there is no bitmap with close enough size, a bitmap upscaled by an integer scaling factor is used. Note that custom bitmap bundles can use a different algorithm for selecting the best match by overriding Wx::BitmapBundleImpl#get_preferred_bitmap_size_at_scale.
370
375
  # Of course, this code relies on actually having the resources with the corresponding names (i.e. open_NxN) in MSW .rc file or Mac application bundle and open_NxN_png arrays being defined in the program code, e.g. by including a file generated with bin2c (see {bitmap_png_from_data}), on the other platforms.
371
- # For the platforms with resources support, you can also create the bundle from the bitmaps defined in the resources, which has the advantage of not having to explicitly list all the bitmaps, e.g. the code above becomes
372
376
  #
373
- # #ifdef wxHAS_IMAGE_RESOURCES
374
- # toolBar->AddTool(wxID_OPEN, "Open", wxBitmapBundle::FromResources("open"));
375
- # #else
376
- # ... same code as shown above ...
377
- # #endif
378
- # and will load all resources called open, open_2x, open_1_5x etc (at least the first one of them must be available). See also {bitmap_bundle_2} macro which can avoid the need to check for {Wx::HAS_IMAGE_RESOURCES} explicitly in the code in a common case of having only 2 embedded resources (for standard and high DPI). See also {Wx::BitmapBundle.from_svg_resource}.
379
377
  # Also note that the existing code using {Wx::Bitmap} is compatible with the functions taking {Wx::BitmapBundle} in wxWidgets 3.1.6 and later because bitmaps are implicitly convertible to the objects of this class, so just passing {Wx::Bitmap} to the functions taking {Wx::BitmapBundle} continues to work and if high resolution versions of bitmap are not (yet) available for the other toolbar tools, single bitmaps can continue to be used instead.
380
378
  # ===
381
379
  #
382
380
  # Category: Graphics Device Interface (GDI)
383
381
  #
382
+ #
383
+ # @note This class is <b>untracked</b> and should not be derived from nor instances extended!
384
384
  class BitmapBundle < ::Object
385
385
 
386
386
  # @overload initialize()