wxruby3 0.9.8 → 1.0.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (158) hide show
  1. checksums.yaml +4 -4
  2. data/INSTALL.md +23 -1
  3. data/README.md +13 -27
  4. data/ext/mkrf_conf_ext.rb +11 -7
  5. data/lib/wx/core/app.rb +16 -0
  6. data/lib/wx/core/colour.rb +36 -28
  7. data/lib/wx/core/const.rb +19 -0
  8. data/lib/wx/core/enum.rb +17 -1
  9. data/lib/wx/core/geometry.rb +121 -0
  10. data/lib/wx/core/graphics_pen_info.rb +18 -0
  11. data/lib/wx/core/image.rb +49 -0
  12. data/lib/wx/core/menu_bar.rb +11 -0
  13. data/lib/wx/core/paintdc.rb +9 -3
  14. data/lib/wx/doc/app.rb +97 -41
  15. data/lib/wx/doc/bitmap.rb +4 -0
  16. data/lib/wx/doc/client_dc.rb +2 -2
  17. data/lib/wx/doc/clipboard.rb +1 -1
  18. data/lib/wx/doc/colour.rb +12 -0
  19. data/lib/wx/doc/const.rb +16 -0
  20. data/lib/wx/doc/cursor.rb +4 -0
  21. data/lib/wx/doc/dc_overlay.rb +34 -0
  22. data/lib/wx/doc/enum.rb +7 -1
  23. data/lib/wx/doc/event_blocker.rb +1 -1
  24. data/lib/wx/doc/evthandler.rb +25 -3
  25. data/lib/wx/doc/functions.rb +3 -6
  26. data/lib/wx/doc/gc_dc.rb +13 -4
  27. data/lib/wx/doc/geometry.rb +136 -0
  28. data/lib/wx/doc/graphics_context.rb +25 -7
  29. data/lib/wx/doc/icon.rb +4 -0
  30. data/lib/wx/doc/image.rb +56 -0
  31. data/lib/wx/doc/list_ctrl.rb +6 -6
  32. data/lib/wx/doc/memory_dc.rb +2 -11
  33. data/lib/wx/doc/mirror_dc.rb +1 -1
  34. data/lib/wx/doc/pen.rb +26 -0
  35. data/lib/wx/doc/persistence_manager.rb +1 -1
  36. data/lib/wx/doc/persistent_object.rb +1 -1
  37. data/lib/wx/doc/pg/property_grid_interface.rb +3 -3
  38. data/lib/wx/doc/prt/printer_dc.rb +2 -2
  39. data/lib/wx/doc/region_iterator.rb +1 -1
  40. data/lib/wx/doc/scaled_dc.rb +1 -1
  41. data/lib/wx/doc/screen_dc.rb +1 -1
  42. data/lib/wx/doc/svg_file_dc.rb +1 -1
  43. data/lib/wx/doc/textctrl.rb +1 -1
  44. data/lib/wx/doc/tree_ctrl.rb +2 -2
  45. data/lib/wx/doc/validator.rb +6 -6
  46. data/lib/wx/doc/variant.rb +2 -2
  47. data/lib/wx/doc/window.rb +5 -4
  48. data/lib/wx/grid/keyword_defs.rb +1 -1
  49. data/lib/wx/html/keyword_defs.rb +3 -3
  50. data/lib/wx/keyword_defs.rb +76 -71
  51. data/lib/wx/pg/keyword_defs.rb +2 -2
  52. data/lib/wx/pg/pg_property.rb +12 -0
  53. data/lib/wx/rbn/keyword_defs.rb +1 -1
  54. data/lib/wx/rtc/keyword_defs.rb +1 -1
  55. data/lib/wx/stc/keyword_defs.rb +1 -1
  56. data/lib/wx/version.rb +1 -1
  57. data/lib/wx/wxruby/cmd/setup.rb +3 -0
  58. data/rakelib/configure.rb +7 -0
  59. data/rakelib/gem.rake +3 -2
  60. data/rakelib/gem.rb +3 -2
  61. data/rakelib/lib/config/linux.rb +1 -1
  62. data/rakelib/lib/config/mingw.rb +4 -101
  63. data/rakelib/lib/config/pkgman/linux.rb +31 -8
  64. data/rakelib/lib/config/pkgman/mingw.rb +112 -0
  65. data/rakelib/lib/config/unixish.rb +6 -7
  66. data/rakelib/lib/config.rb +25 -4
  67. data/rakelib/lib/core/include/enum.inc +31 -1
  68. data/rakelib/lib/director/affine_matrix.rb +51 -0
  69. data/rakelib/lib/director/app.rb +29 -13
  70. data/rakelib/lib/director/art_provider.rb +4 -0
  71. data/rakelib/lib/director/cursor.rb +6 -2
  72. data/rakelib/lib/director/dc.rb +1 -6
  73. data/rakelib/lib/director/derived_dc.rb +88 -31
  74. data/rakelib/lib/director/dialog.rb +0 -8
  75. data/rakelib/lib/director/geometry.rb +142 -0
  76. data/rakelib/lib/director/graphics_context.rb +3 -2
  77. data/rakelib/lib/director/graphics_object.rb +18 -25
  78. data/rakelib/lib/director/image.rb +59 -0
  79. data/rakelib/lib/director/menu.rb +2 -3
  80. data/rakelib/lib/director/menu_bar.rb +0 -3
  81. data/rakelib/lib/director/pen.rb +1 -1
  82. data/rakelib/lib/director/richtext_ctrl.rb +1 -1
  83. data/rakelib/lib/director/system_settings.rb +1 -1
  84. data/rakelib/lib/director/window.rb +9 -3
  85. data/rakelib/lib/extractor/function.rb +1 -1
  86. data/rakelib/lib/generate/doc/animation_ctrl.yaml +10 -0
  87. data/rakelib/lib/generate/doc/banner_window.yaml +35 -0
  88. data/rakelib/lib/generate/doc/graphics_context.yaml +12 -0
  89. data/rakelib/lib/generate/doc/graphics_object.yaml +12 -0
  90. data/rakelib/lib/generate/doc/grid_ctrl.yaml +25 -0
  91. data/rakelib/lib/generate/doc/header_ctrl.yaml +91 -0
  92. data/rakelib/lib/generate/doc/icon.yaml +10 -0
  93. data/rakelib/lib/generate/doc/info_bar.yaml +27 -0
  94. data/rakelib/lib/generate/doc/log.yaml +1 -1
  95. data/rakelib/lib/generate/doc/media_ctrl.yaml +27 -0
  96. data/rakelib/lib/generate/doc/persistent_window.yaml +22 -0
  97. data/rakelib/lib/generate/doc/pg_editor.yaml +1 -1
  98. data/rakelib/lib/generate/doc/pg_property.yaml +4 -4
  99. data/rakelib/lib/generate/doc/rearrange_list.yaml +14 -0
  100. data/rakelib/lib/generate/doc/ribbon_panel.yaml +15 -0
  101. data/rakelib/lib/generate/doc/rich_text_formatting_dialog.yaml +26 -0
  102. data/rakelib/lib/generate/doc/text_ctrl.yaml +1 -1
  103. data/rakelib/lib/generate/doc/wizard.yaml +27 -0
  104. data/rakelib/lib/generate/doc.rb +4 -4
  105. data/rakelib/lib/generate/interface.rb +1 -1
  106. data/rakelib/lib/specs/interfaces.rb +3 -0
  107. data/rakelib/lib/swig_runner.rb +24 -3
  108. data/rakelib/lib/typemap/points_list.rb +8 -2
  109. data/rakelib/lib/typemap/richtext.rb +17 -0
  110. data/rakelib/yard/templates/default/fulldoc/html/setup.rb +3 -3
  111. data/samples/dialogs/wizard.rb +20 -19
  112. data/samples/drawing/art/drawing/image.bmp +0 -0
  113. data/samples/drawing/art/drawing/mask.bmp +0 -0
  114. data/samples/drawing/art/drawing/pat35.bmp +0 -0
  115. data/samples/drawing/art/drawing/pat36.bmp +0 -0
  116. data/samples/drawing/art/drawing/pat4.bmp +0 -0
  117. data/samples/drawing/art/drawing/smile.xpm +42 -0
  118. data/samples/drawing/drawing.rb +2276 -0
  119. data/samples/drawing/tn_drawing.png +0 -0
  120. data/samples/html/html.rb +1 -1
  121. data/samples/propgrid/propgrid.rb +1 -1
  122. data/samples/propgrid/propgrid_minimal.rb +1 -1
  123. data/samples/propgrid/sample_props.rb +1 -1
  124. data/samples/sampler/editor.rb +13 -11
  125. data/samples/sampler.rb +14 -10
  126. data/samples/text/richtext.rb +53 -0
  127. data/samples/text/scintilla.rb +1 -1
  128. data/samples/text/unicode.rb +4 -4
  129. data/tests/test_ext_controls.rb +12 -5
  130. data/tests/test_gdi_object.rb +2 -2
  131. data/tests/test_std_controls.rb +12 -12
  132. metadata +33 -32
  133. data/lib/wx/doc/extra/00_starting.md +0 -154
  134. data/lib/wx/doc/extra/01_packages.md +0 -180
  135. data/lib/wx/doc/extra/02_lifecycles.md +0 -166
  136. data/lib/wx/doc/extra/03_dialogs.md +0 -57
  137. data/lib/wx/doc/extra/04_enums.md +0 -143
  138. data/lib/wx/doc/extra/05_event-handling.md +0 -191
  139. data/lib/wx/doc/extra/06_geometry.md +0 -62
  140. data/lib/wx/doc/extra/07_colour_and_font.md +0 -52
  141. data/lib/wx/doc/extra/08_extensions.md +0 -144
  142. data/lib/wx/doc/extra/09_exceptions.md +0 -54
  143. data/lib/wx/doc/extra/10_art.md +0 -111
  144. data/lib/wx/doc/extra/11_drawing_and_dc.md +0 -62
  145. data/lib/wx/doc/extra/12_client_data.md +0 -89
  146. data/lib/wx/doc/extra/13_validators.md +0 -139
  147. data/lib/wx/doc/extra/14_config.md +0 -101
  148. data/lib/wx/doc/extra/15_persistence.md +0 -148
  149. data/samples/sampler/back.xpm +0 -21
  150. data/samples/sampler/copy.xpm +0 -44
  151. data/samples/sampler/cut.xpm +0 -46
  152. data/samples/sampler/filesave.xpm +0 -42
  153. data/samples/sampler/find.xpm +0 -62
  154. data/samples/sampler/findrepl.xpm +0 -63
  155. data/samples/sampler/forward.xpm +0 -21
  156. data/samples/sampler/paste.xpm +0 -46
  157. data/samples/sampler/redo.xpm +0 -58
  158. data/samples/sampler/undo.xpm +0 -58
@@ -1,154 +0,0 @@
1
- <!--
2
- # @markup markdown
3
- # @title 0. Overview of wxRuby
4
- -->
5
-
6
- # 0. Overview of wxRuby
7
-
8
- ## What is wxRuby?
9
-
10
- wxRuby3 is a cross-platform GUI library for Ruby, based on the popular [wxWidgets](https://wxwidgets.org)
11
- cross platform GUI toolkit for C++. It uses native widgets wherever possible, providing
12
- the correct look, feel and behaviour to GUI applications on Windows, OS
13
- X and Linux/GTK. wxRuby aims to provide a comprehensive solution to
14
- developing professional-standard desktop applications in Ruby.
15
-
16
- Like Ruby and wxWidgets, wxRuby is Open Source, which means that it is free for anyone to use and the source code
17
- is available for anyone to look at and use in any way they like. Also, anyone can contribute (tested) fixes, additions
18
- and enhancements to the project.
19
-
20
- Like wxWidgets wxRuby is a cross platform toolkit. This means that the same program will run on multiple platforms
21
- without modification. Currently Supported platforms are Microsoft Windows, MacOSX and Linux or other
22
- unix-like systems with GTK2 or GTK3 libraries. Contributions to achieve support for other wxWidgets supported platforms
23
- are appreciated.
24
-
25
- Since the programming language is Ruby, wxRuby programs are simple and easy to write and understand. To accomplish the
26
- full Ruby experience wxRuby has not ported the wxWidgets API 1 on 1 to Ruby but has made an effort to make the wxRuby
27
- API typically Ruby-ish. This means all method signatures (names, arguments) have been transformed to conform to common
28
- Ruby naming rules as well as other Ruby programming practices. Also does wxRuby introduce iterators in favor of getters
29
- returning arrays or lists.
30
- Check out the samples and the documentation for details.
31
-
32
- ## What is wxRuby3?
33
-
34
- The wxRuby3 project is a new, rebooted, implementation of wxRuby (as compared to wxRuby2 and earlier versions) with the
35
- clear intent to make this implementation better maintainable and extensible.
36
-
37
- To this end wxRuby3 adopted much of the approach of the wxPython Phoenix project in that the wxRuby API is generated
38
- from the wxWidgets XML interface definitions. Unlike the Phoenix project however, wxRuby does not use a home-grown
39
- interface code generator but rather still relies on SWIG for that (with Ruby tooling to configure and post-process).
40
- The wxRuby generation process more or less conforms to:
41
-
42
- 1. build wxWidgets interface XML
43
- 2. parse interface XML
44
- 3. generate SWIG interface definitions
45
- 4. generate Ruby extension code with SWIG
46
- 5. post-process Ruby extension code
47
-
48
- As the wxRuby tooling is already parsing the full wxWidgets interface specs (from which wxWidgets generates it's own
49
- reference documentation) it also uses the parsed information to generate matching reference documentation for the
50
- wxRuby API. This documentation is not (yet) perfect but should go a long way in helping people using wxRuby to build
51
- GUI applications.
52
-
53
- The wxRuby3 API is largely compatible with the earlier wxRuby incarnations but not 100% mostly due to more
54
- modularization and more explicit typing of (especially) enums. Also wxRuby3 exclusively targets a lot more modern
55
- versions of wxWidgets (>= 3.2) and Ruby (>= 2.5) so there are some shifts from that as well. All in all though,
56
- people that once took a stab at looking at wxRuby(2) should not have much problems getting up to speed again.
57
-
58
- ## Quick start
59
-
60
- To create an application with wxRuby you need to require the wxRuby libraries:
61
-
62
- ```ruby
63
- require 'wx'
64
- ```
65
-
66
- Next would be the application code and a main entry point. With wxRuby (as with wxWidgets) the entry
67
- point is mostly just a simple call to start the applications event loop (as we're talking about event
68
- based GUI applications here).
69
- In wxRuby the Wx::App class provides some typically Ruby-style magic to make this as easy as possible.
70
-
71
- Using this the simplest Hello World application could be:
72
-
73
- ```ruby
74
- require 'wx'
75
- Wx::App.run { puts 'Hello world!' }
76
- ```
77
-
78
- As you can see there is no obligation to create an instance of the Wx::App class in wxRuby for
79
- (admittedly extremely) simple applications. Calling the #run class method with a block will suffice.<br>
80
- The class method will create an instance of the generic Wx::App class under the hood and use the
81
- provided block as the #on_init callback. As the code inside the block returns a false-type value (#puts
82
- returns `nil`) the application will terminate immediately after writing "Hello world!" to standard
83
- output (actually not even starting the event loop at all).
84
-
85
- Of course this is not truly a GUI application so let's elaborate a little to make the GUI element
86
- more real.
87
-
88
- ```ruby
89
- require 'wx'
90
- Wx::App.run { Wx::Frame.new(nil, title: 'Hello World!').show }
91
- ```
92
-
93
- Executing this will create a generic Frame instance in the on_init callback of the application
94
- and show the frame. As #show returns a true-type when successful the event loop will actually be
95
- started and keep the application running until the frame is closed.
96
-
97
- ## The application class
98
-
99
- For more complex applications the approach demonstrated above will quickly become insufficient. In those cases
100
- creating a specialized derived App class is the better option.
101
- This provides the possibility (as with all Ruby classes) to override the constructor (#initialize) for
102
- custom initialization, attribute definitions and create customized #on_init and/or #on_exit methods like
103
- this:
104
-
105
- ```ruby
106
- require 'wx'
107
-
108
- class MyApp < Wx::App
109
- def initialize
110
- super
111
- @frame = nil
112
- end
113
- attr_reader :frame
114
-
115
- def on_init
116
- @frame = Wx::Frame.new(nil, title: 'Hello World!')
117
- @frame.show
118
- end
119
-
120
- def on_exit
121
- puts 'Exiting.'
122
- end
123
- end
124
- ```
125
-
126
- When creating #on_init/#on_exit methods it is important to understand that those would not be overrides (as is the case
127
- with wxWidgets itself). The base Wx::App class actually does not define these methods so it's also not needed (even not possible)
128
- to call `super` in the implementation. The wxRuby application class implementation will call the wxWidget OnInit base implementation
129
- itself and after successful completion check for the existence of an #on_init method (which could also be 'automagicallly'
130
- created from a block passed to #run) and call that if available or terminate the application if not. The
131
- exit sequence of executions are similar but reversed (first a possible #on_exit method and than the wxWidgets base OnExit).
132
-
133
- What remains though is that for a derived application class it is still not necessary to explicitly create a class instance.
134
- Simply calling the #run class method will suffice.
135
-
136
- ```ruby
137
- MyApp.run
138
- ```
139
-
140
- The current application instance (as long as the application is active) can always be retrieved by
141
- calling `Wx.get_app`.
142
-
143
- ## wxRuby modules
144
-
145
- The toplevel module of the wxRuby library is the `Wx` module and when using `require 'wx'` to load the wxRuby library
146
- **all** constants and classes are loaded and can be accessed from that scope like `Wx::Frame` or `Wx::RichTextCtrl`
147
- like previous versions of wxRuby supported.
148
-
149
- With the current wxRuby library however a more modular approach has been used similar to wxWidgets itself which
150
- distributes implementations over various sub-modules. These sub-modules can be loaded separately to provide more control.
151
- The core module still provides the toplevel `Wx` namespace and all classes and constants declared in that namespace.
152
- All other modules add to that (and **all** require the core module).
153
-
154
- See [here](01_packages.md) for more details on wxRuby sub-modules.
@@ -1,180 +0,0 @@
1
- <!--
2
- # @markup markdown
3
- # @title 1. wxRuby Modules
4
- -->
5
-
6
- # 1. wxRuby Modules
7
-
8
- ## Introduction
9
-
10
- Previous wxRuby implementations provided a single toplevel module approach for the wxRuby API with a single loading
11
- option. Including `require 'wx'` in any application would load the entire wxRuby library and make all classes, module
12
- methods and constants available under the `Wx` toplevel module.
13
-
14
- The wxRuby3 project however implements a more modular approach similar to wxWidgets itself which distributes
15
- implementations over various sub-modules. These sub-modules can be loaded separately to provide more control.
16
- The core module still provides the toplevel `Wx` namespace and all classes and constants declared in that namespace.
17
- All other modules add to that (and **all** require the core module).
18
-
19
- ## Loading and Naming scopes
20
-
21
- The *old* **all-in-one** approach in still supported with the wxRuby3 project. Using
22
-
23
- ```ruby
24
- require 'wx'
25
- ```
26
-
27
- will load all wxRuby API modules and make all classes and constants available from the `Wx` toplevel module. This
28
- *global* naming scope approach does **not** extend to class or module methods (including dialog *functors*; see
29
- [here](03_dialogs.md) for more information).
30
-
31
- The *new* sub-module approach however allows for loading only part(s) of the wxRuby library like:
32
-
33
- ```ruby
34
- require 'wx/core' # load wxRuby core Wx module
35
- require 'wx/grid' # load wxRuby Wx::GRID module - provides Grid control
36
- require 'wx/rtc' # load wxRuby Wx::RTC module - provides RichText control
37
- ```
38
-
39
- However, when loading the library like this scoping rules change by default. Specifically the constants and classes
40
- from the loaded sub-modules will **not** be accessible from the `Wx` scope anymore (like `Wx::Grid`) but must instead be
41
- explicitly scoped from the sub-module (like `Wx::GRID::Grid`).
42
-
43
- It is possible to revert the 'global scope' resolution behaviour by setting the toplevel constant `WX_GLOBAL_CONSTANTS` to
44
- `true` before the require statements like:
45
-
46
- ```ruby
47
- WX_GLOBAL_CONSTANTS=true
48
- require 'wx/core' # load wxRuby core Wx module
49
- require 'wx/grid' # load wxRuby Wx::GRID module - provides Grid control
50
- require 'wx/rtc' # load wxRuby Wx::RTC module - provides RichText control
51
- ```
52
-
53
- ## Modules
54
-
55
- Currently the following modules have been implemented.
56
-
57
- ### Core
58
-
59
- The core wxRuby package providing the toplevel {Wx} module.
60
- This package includes basic classes like:
61
-
62
- - {Wx::Object}
63
- - {Wx::EvtHandler}
64
- - {Wx::Event}
65
- - {Wx::CommandEvent}
66
- - {Wx::App}
67
- - {Wx::Window}
68
- - {Wx::NonOwnedWindow}
69
- - {Wx::TopLevelWindow}
70
- - {Wx::Frame}
71
- - {Wx::Dialog}
72
-
73
- as well as most common window classes, control/widget classes, event classes, constant and enum definitions
74
- and global functions not part of any of the other packages.
75
-
76
- ### AUI - Advanced User Interface controls and related classes
77
-
78
- The wxRuby AUI package providing the {Wx::AUI} module.
79
- This package includes all classes, constants and enum definitions that are considered part of the
80
- wxWidgets AUI framework like:
81
-
82
- - {Wx::AUI::AuiManager}
83
- - {Wx::AUI::AuiMDIParentFrame}
84
- - {Wx::AUI::AuiMDIChildFrame}
85
- - {Wx::AUI::AuiMDIClientWindow}
86
- - etc
87
-
88
- ### GRID - Grid control and related classes
89
-
90
- The wxRuby GRID package providing the {Wx::GRID} module.
91
- This package includes all classes, constants and enum definitions that are associated with the
92
- wxWidgets wxGrid control like:
93
-
94
- - {Wx::GRID::Grid}
95
- - {Wx::GRID::GridTableBase}
96
- - {Wx::GRID::GridCellEditor}
97
- - {Wx::GRID::GridCellRenderer}
98
- - {Wx::GRID::GridEvent}
99
- - etc
100
-
101
- ### HTML - Html framework classes
102
-
103
- The wxRuby HTML package providing the {Wx::HTML} module.
104
- This package includes all classes, constants and enum definitions that are considered part of the
105
- wxWidgets Html framework like:
106
-
107
- - {Wx::HTML::HtmlWindow}
108
- - {Wx::HTML::HtmlHelpWindow}
109
- - {Wx::HTML::HtmlPrintout}
110
- - {Wx::HTML::HtmlHelpController}
111
- - {Wx::HTML::HtmlListBox}
112
- - etc
113
-
114
- ### PG - PropertyGrid control and related classes
115
-
116
- The wxRuby PG package providing the {Wx::PG} module.
117
- This package includes all classes, constants and enum definitions that are associated with the
118
- wxWidgets wxPropertyGrid control like:
119
-
120
- - {Wx::PG::PropertyGrid}
121
- - {Wx::PG::PropertyGridManager}
122
- - {Wx::PG::PGCell}
123
- - {Wx::PG::PGProperty}
124
- - {Wx::PG::PropertyGridEvent}
125
- - etc
126
-
127
- ### PRT - Printing framework classes
128
-
129
- The wxRuby PRT package providing the {Wx::PRT} module.
130
- This package includes all classes, constants and enum definitions that are considered part of the
131
- wxWidgets Printing framework like:
132
-
133
- - {Wx::PRT::PreviewFrame}
134
- - {Wx::PRT::Printer}
135
- - {Wx::PRT::PrinterDC}
136
- - {Wx::PRT::PrintDialog}
137
- - etc
138
-
139
- ### RBN - Ribbon framework classes
140
-
141
- The wxRuby RBN package providing the {Wx::RBN} module.
142
- This package includes all classes, constants and enum definitions that are considered part of the
143
- wxWidgets Ribbon framework like:
144
-
145
- - {Wx::RBN::RibbonControl}
146
- - {Wx::RBN::RibbonGallery}
147
- - {Wx::RBN::RibbonPanel}
148
- - {Wx::RBN::RibbonPage}
149
- - {Wx::RBN::RibbonBar}
150
- - etc
151
-
152
- ### RTC - RichText control and related classes
153
-
154
- The wxRuby RTC package providing the {Wx::RTC} module.
155
- This package includes all classes, constants and enum definitions that are associated with the
156
- wxWidgets wxRichTextCtrl control like:
157
-
158
- - {Wx::RTC::RichTextCtrl}
159
- - {Wx::RTC::RichTextEvent}
160
- - {Wx::RTC::RichTextBuffer}
161
- - etc
162
-
163
- ### STC - StyledText control and related classes
164
-
165
- The wxRuby STC package providing the {Wx::STC} module.
166
- This package includes all classes, constants and enum definitions that are associated with the
167
- wxWidgets wxStyledTextCtrl control (Scintilla integration) like:
168
-
169
- - {Wx::STC::StyledTextCtrl}
170
- - {Wx::STC::StyledTextEvent}
171
-
172
- ## Feature dependencies
173
-
174
- Availability of wxRuby packages is controlled by the wxWidget feature switches. The default build options will
175
- include all platform supported features but in case of building wxRuby for customized wxWidgets builds the wxRuby3
176
- build procedures will take the wxWidgets settings into account.
177
-
178
- If for instance wxWidgets was built without Html support (using the configure `--disable-html` switch) the wxRuby
179
- HTML package will not be available as well.
180
- This behavior is controlled by the `wxUSE_xxx` macros that wxRuby extracts from the wxWidgets `wx/setup.h` file.
@@ -1,166 +0,0 @@
1
- <!--
2
- # @markup markdown
3
- # @title 2. wxRuby Life Cycles
4
- -->
5
-
6
- # 2. wxRuby Life Cycles
7
-
8
- ## Introduction
9
-
10
- Managing the life cycles of native objects in Ruby extension libraries is tricky business because of the disparity
11
- between common C++ dynamic memory management and the GC management scheme of the Ruby language and this certainly applies
12
- to an event based environment like the wxRuby extension for wxWidgets.
13
- That said, the wxRuby library should provide you with a fairly worry-free API in that respect.
14
-
15
- The wxRuby extension manages to provide water-tight GC management for just about all mapped wxWidget objects.
16
-
17
- There are just a few, fairly specific, things to take notice of.
18
-
19
- ## Application instance
20
-
21
- Any wxWidgets application typically creates a single application instance and the same goes for wxRuby applications.
22
- We already saw [here](00_starting.md) how to start a wxRuby application. Important to note is that any reference to the
23
- (global) application instance will ever only be valid as long as the application is still active.<br>
24
- In essence this means the reference is valid from the moment the constructor (`#initialize`) is called to the moment
25
- any available `#on_exit` method has finished.
26
-
27
- There are some caveats to that however.
28
-
29
- 1. Although the application instance is valid in the constructor, the wxWidgets
30
- framework will only be fully initialized the moment the `#on_init` method starts. This means that all kinds of methods
31
- requiring initialized GUI resources (like window creation) will fail if called before that moment.
32
-
33
- 2. The global application instance returned by `Wx.get_app` will only be set from the moment the `#on_init` method
34
- starts to the moment the `#on_exit` method finishes. Outside that timespan the method will return `nil`.
35
-
36
- Also be careful with storing your own application instance variables. Code like
37
-
38
- ```ruby
39
- class MyApp < Wx::App
40
- def initialize
41
- super
42
- # ...
43
- end
44
- def on_init
45
- # ...
46
- end
47
- end
48
- $app = MyApp.new
49
- $app.run
50
- ```
51
-
52
- is entirely valid but for the fact that you **should** remember that after the `#run` method returns the `$app` variable
53
- does **not** reference a valid application instance anymore. Calling methods on that instance may result in unexpected
54
- behavior.<br>
55
- It is actually easier and safer to rewrite this code as:
56
-
57
- ```ruby
58
- class MyApp < Wx::App
59
- def initialize
60
- super
61
- # ...
62
- end
63
- def on_init
64
- # ...
65
- end
66
- end
67
- MyApp.run # or MyApp.new.run
68
- ```
69
-
70
- This way there is no reference to accidentally use after `#run` returns and `Wx.get_app` will return `nil` after that
71
- moment.
72
-
73
- ## Framework (re-)initialization
74
-
75
- As mentioned above the wxWidgets GUI framework resources will only be fully initialized after the `#on_init` method
76
- starts. Likewise the framework resources will be de-initialized (deleted) after `#on_exit` method ends which means that
77
- your application should not attempt to access any of these resources (windows, fonts, colours etc.) after that moment.
78
-
79
- Also, largely because of the way the wxWidgets framework is designed but also because of the way this meshes with Ruby
80
- GC, there is no safe way to re-initialize the framework after an application instance ends it run. This means you
81
- **cannot** safely attempt to start another application instance after a previous (first) one has ended.
82
-
83
- ## Windows
84
-
85
- Window instances (and it's derivatives) are fully managed by the wxWidget framework and cannot (are not) managed by
86
- Ruby GC handling. This means on the one hand that a window instances life time is not controlled by any reference
87
- a Ruby variable may hold and on the other hand that the Ruby object linked to that native window object is kept alive
88
- (marked in GC) as long as the window instance is alive.<br>
89
- Generally speaking window lifetimes are dependent on the (toplevel) window (or it's parent) being closed. In case of a
90
- toplevel window this result in automatic destruction of the window and all it's child windows (controls). There are
91
- however exceptions to this where explicit calling of a window's `#destroy` method is required to prevent memory leaks
92
- (when a window is not a child window but also not a toplevel window for example or in case of dialogs; see
93
- [here](03_dialogs.md)). Please check out the wxWidgets documentation for more detailed information.
94
-
95
- This has several consequences you need to be aware of.
96
-
97
- First of, in cases where you keep a reference to any window (control) instance in a local or instance variable in Ruby
98
- (which is fairly common practice) you need to be aware that the reference is only valid as long as the window has not
99
- been destroyed. In most cases this will not be an issue as most references are kept as instance variables of parent
100
- windows for child windows where the instance variables will only ever be used as long the parent window is alive itself.
101
- In other circumstances you should take care to track the lifetime of the window that is referenced.
102
-
103
- Secondly, as already indicated above not all window instances will be automatically destroyed. It is for example fairly
104
- common in more complex applications to create and show other windows as response to events triggered in the toplevel
105
- window. These windows will not (and should not) be automatically designated as toplevel window but they are also not
106
- owned (i.e. not child windows). Closing these windows will not automatically destroy them (which is a good thing as
107
- these are often re-shown after renewed events from the toplevel window) and will also not be automatically destroyed
108
- when any parent window is destroyed. This means they pose a threat for potential memory leaks.<br>
109
- In case it concerns a fairly simple application which creates one or two of these sub-windows and needs to keep these
110
- around for most or all of the lifetime of the application this is not really an issue as the window will be cleaned up
111
- at application exit eventually. If however it concerns a more complex application which potentially could create a large
112
- number of these sub windows (probably each only used for limited purposes) it would be advisable to track instances and
113
- destroy these on a regular basis when not used (closed) possibly re-creating them as needed.
114
-
115
- Dialogs are special cases of toplevel windows which are not automatically destroyed when closed. The wxRuby library
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 that 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 and similar
164
- reference counted objects like Wx::Font
165
-
166
- The reference documentation will note untracked object classes.
@@ -1,57 +0,0 @@
1
- <!--
2
- # @markup markdown
3
- # @title 3. wxRuby Dialogs
4
- -->
5
-
6
- # 3. wxRuby Dialogs
7
-
8
- Dialogs are a special class of window which are never automatically destroyed in wxWidgets.
9
- In C++ this does not cause a lot of management overhead for application programmers because of the possibility of
10
- static declaration of dialogs instances where the statically declared object is automatically destructed as execution
11
- leaves the declaration scope.<br>
12
- This kind of construct does not exist in Ruby where everything is dynamically allocated and garbage collection normally
13
- takes care of releasing objects that have gone *'out of scope'*.
14
-
15
- Like any non-owned, non-toplevel windows as discussed [here](02_lifecycles.md) this means dialogs should be explicitly
16
- destroyed in program code as appropriate like:
17
-
18
- ```ruby
19
- dlg = Wx::MessageDialog.new(parent, 'Select Yes or No', "Confirmation", Wx::YES_NO)
20
- if dlg.show_modal == Wx::ID_YES
21
- # do something
22
- end
23
- dlg.destroy
24
- ```
25
-
26
- Although this is sometimes useful (for example in cases where a dialog is repeatedly used), most of the time this makes
27
- for somewhat bothersome programming.
28
-
29
- Luckily wxRuby has a solution for this.
30
-
31
- For all dialog classes (which includes Wx::Dialog and all it's derivatives, including user defined) the library defines
32
- a module function which is identically named to the dialog class in the same scope as where the dialog class has been
33
- first defined. This is similar to the module functions Ruby itself defines for the basic object classes like `Integer`,
34
- `String`, `Array`, `Hash` and such for the `Kernel` module.<br>
35
- These dialog *functors* accept the same arguments as the dialog class's constructor with the addition of a block. The
36
- *functor* will call the class constructor and pass the created dialog instance as argument to the block. After returning
37
- from the block the dialog instance will automatically be destroyed. So, using this approach we could write the previous
38
- example like:
39
-
40
- ```ruby
41
- Wx.MessageDialog(parent, 'Select Yes or No', "Confirmation", Wx::YES_NO) do |dlg|
42
- if dlg.show_modal == Wx::ID_YES
43
- # do something
44
- end
45
- end
46
- ```
47
-
48
- Even better, if the only purpose is to show the dialog until closed without caring for the result we can leave out the
49
- block. In that case the *functor* will simply create the dialog instance, call `#show_modal` on it and destroy the
50
- instance after returning from `#show_modal` like:
51
-
52
- ```ruby
53
- Wx.MessageDialog(parent, 'Hello world!', 'Information', Wx::OK)
54
- ```
55
-
56
- Regular dialog constructors are still usable for situations where the dialog instance should have a
57
- prolonged lifetime or where different modeless behavior is required.