glimmer-dsl-swt 0.6.5 → 4.17.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (107) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +248 -0
  3. data/LICENSE.txt +1 -1
  4. data/README.md +3931 -23
  5. data/VERSION +1 -1
  6. data/bin/girb +21 -0
  7. data/bin/girb_runner.rb +21 -0
  8. data/bin/glimmer +21 -4
  9. data/lib/ext/glimmer.rb +21 -0
  10. data/lib/ext/glimmer/config.rb +38 -1
  11. data/lib/glimmer-dsl-swt.rb +26 -9
  12. data/lib/glimmer/Rakefile +21 -0
  13. data/lib/glimmer/data_binding/list_selection_binding.rb +21 -0
  14. data/lib/glimmer/data_binding/observable_widget.rb +21 -0
  15. data/lib/glimmer/data_binding/shine.rb +22 -1
  16. data/lib/glimmer/data_binding/table_items_binding.rb +25 -1
  17. data/lib/glimmer/data_binding/tree_items_binding.rb +21 -0
  18. data/lib/glimmer/data_binding/widget_binding.rb +21 -0
  19. data/lib/glimmer/dsl/swt/async_exec_expression.rb +21 -0
  20. data/lib/glimmer/dsl/swt/bind_expression.rb +21 -0
  21. data/lib/glimmer/dsl/swt/block_property_expression.rb +21 -0
  22. data/lib/glimmer/dsl/swt/color_expression.rb +21 -0
  23. data/lib/glimmer/dsl/swt/column_properties_expression.rb +21 -0
  24. data/lib/glimmer/dsl/swt/combo_selection_data_binding_expression.rb +21 -0
  25. data/lib/glimmer/dsl/swt/cursor_expression.rb +21 -0
  26. data/lib/glimmer/dsl/swt/custom_widget_expression.rb +20 -0
  27. data/lib/glimmer/dsl/swt/data_binding_expression.rb +21 -0
  28. data/lib/glimmer/dsl/swt/dialog_expression.rb +21 -0
  29. data/lib/glimmer/dsl/swt/display_expression.rb +21 -0
  30. data/lib/glimmer/dsl/swt/dnd_expression.rb +21 -0
  31. data/lib/glimmer/dsl/swt/dsl.rb +21 -0
  32. data/lib/glimmer/dsl/swt/exec_expression.rb +28 -1
  33. data/lib/glimmer/dsl/swt/font_expression.rb +21 -0
  34. data/lib/glimmer/dsl/swt/image_expression.rb +21 -0
  35. data/lib/glimmer/dsl/swt/layout_data_expression.rb +21 -0
  36. data/lib/glimmer/dsl/swt/layout_expression.rb +21 -0
  37. data/lib/glimmer/dsl/swt/list_selection_data_binding_expression.rb +21 -0
  38. data/lib/glimmer/dsl/swt/menu_bar_expression.rb +21 -0
  39. data/lib/glimmer/dsl/swt/menu_expression.rb +21 -0
  40. data/lib/glimmer/dsl/swt/message_box_expression.rb +21 -0
  41. data/lib/glimmer/dsl/swt/observe_expression.rb +21 -0
  42. data/lib/glimmer/dsl/swt/property_expression.rb +21 -0
  43. data/lib/glimmer/dsl/swt/rgb_expression.rb +21 -0
  44. data/lib/glimmer/dsl/swt/rgba_expression.rb +21 -0
  45. data/lib/glimmer/dsl/swt/shell_expression.rb +21 -0
  46. data/lib/glimmer/dsl/swt/swt_expression.rb +21 -0
  47. data/lib/glimmer/dsl/swt/sync_exec_expression.rb +21 -0
  48. data/lib/glimmer/dsl/swt/tab_item_expression.rb +21 -0
  49. data/lib/glimmer/dsl/swt/table_items_data_binding_expression.rb +21 -0
  50. data/lib/glimmer/dsl/swt/tree_items_data_binding_expression.rb +21 -0
  51. data/lib/glimmer/dsl/swt/tree_properties_expression.rb +21 -0
  52. data/lib/glimmer/dsl/swt/widget_expression.rb +21 -0
  53. data/lib/glimmer/dsl/swt/widget_listener_expression.rb +21 -0
  54. data/lib/glimmer/launcher.rb +26 -2
  55. data/lib/glimmer/package.rb +21 -0
  56. data/lib/glimmer/rake_task.rb +70 -68
  57. data/lib/glimmer/rake_task/list.rb +21 -0
  58. data/lib/glimmer/scaffold.rb +40 -3
  59. data/lib/glimmer/swt/color_proxy.rb +21 -0
  60. data/lib/glimmer/swt/cursor_proxy.rb +21 -0
  61. data/lib/glimmer/swt/display_proxy.rb +21 -0
  62. data/lib/glimmer/swt/dnd_proxy.rb +21 -0
  63. data/lib/glimmer/swt/font_proxy.rb +21 -0
  64. data/lib/glimmer/swt/image_proxy.rb +21 -0
  65. data/lib/glimmer/swt/layout_data_proxy.rb +21 -0
  66. data/lib/glimmer/swt/layout_proxy.rb +21 -0
  67. data/lib/glimmer/swt/menu_proxy.rb +21 -0
  68. data/lib/glimmer/swt/message_box_proxy.rb +21 -0
  69. data/lib/glimmer/swt/packages.rb +21 -0
  70. data/lib/glimmer/swt/scrolled_composite_proxy.rb +21 -0
  71. data/lib/glimmer/swt/shell_proxy.rb +21 -1
  72. data/lib/glimmer/swt/style_constantizable.rb +22 -0
  73. data/lib/glimmer/swt/swt_proxy.rb +21 -0
  74. data/lib/glimmer/swt/tab_item_proxy.rb +21 -0
  75. data/lib/glimmer/swt/table_column_proxy.rb +21 -0
  76. data/lib/glimmer/swt/table_proxy.rb +37 -4
  77. data/lib/glimmer/swt/tree_proxy.rb +21 -0
  78. data/lib/glimmer/swt/widget_listener_proxy.rb +21 -0
  79. data/lib/glimmer/swt/widget_proxy.rb +74 -37
  80. data/lib/glimmer/ui/custom_shell.rb +21 -0
  81. data/lib/glimmer/ui/custom_widget.rb +21 -0
  82. data/lib/glimmer/util/proc_tracker.rb +21 -0
  83. data/samples/elaborate/contact_manager.rb +21 -0
  84. data/samples/elaborate/contact_manager/contact.rb +21 -0
  85. data/samples/elaborate/contact_manager/contact_manager_presenter.rb +21 -0
  86. data/samples/elaborate/contact_manager/contact_repository.rb +21 -0
  87. data/samples/elaborate/login.rb +20 -2
  88. data/samples/elaborate/tic_tac_toe.rb +21 -0
  89. data/samples/elaborate/tic_tac_toe/board.rb +21 -0
  90. data/samples/elaborate/tic_tac_toe/cell.rb +21 -0
  91. data/samples/elaborate/user_profile.rb +76 -0
  92. data/samples/hello/hello_browser.rb +21 -0
  93. data/samples/hello/hello_combo.rb +21 -0
  94. data/samples/hello/hello_computed.rb +21 -0
  95. data/samples/hello/hello_computed/contact.rb +21 -0
  96. data/samples/hello/hello_drag_and_drop.rb +21 -0
  97. data/samples/hello/hello_list_multi_selection.rb +21 -0
  98. data/samples/hello/hello_list_single_selection.rb +21 -0
  99. data/samples/hello/hello_menu_bar.rb +21 -0
  100. data/samples/hello/hello_message_box.rb +21 -0
  101. data/samples/hello/hello_pop_up_context_menu.rb +21 -0
  102. data/samples/hello/hello_tab.rb +21 -0
  103. data/samples/hello/hello_world.rb +21 -0
  104. data/vendor/swt/linux/swt.jar +0 -0
  105. data/vendor/swt/mac/swt.jar +0 -0
  106. data/vendor/swt/windows/swt.jar +0 -0
  107. metadata +29 -7
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8fa25c1d494d14eac00319e494d3b2f12c9a6b344c084b02a1dde9f60c2f44a5
4
- data.tar.gz: 648c050a1a25a284e972beb5c129047ef6cbf8fabb1a80981408d900afed0c25
3
+ metadata.gz: 18a8ffb4de992d68ada288d1eb3fe66652b2918a94f36feb7a7307015db72f32
4
+ data.tar.gz: cc71bfac3b12a57fdbc61c16c93206b360298e9ac2304419f48cf5240d9b46c8
5
5
  SHA512:
6
- metadata.gz: dc9dedb03e9251f0a88e5530a642c062899be1651b26d2314258925375b871a3e5736141a1ee5b8dfacde1bc7a1d606d4ce00ac8affc8bf160b06f4aa7141306
7
- data.tar.gz: 00416f75c6c00dc163501209a20839cd23fb51921a5335f8ffff7009bf013cca11ccb54389a55367c0ccbb1b0f1bb1641c61141d376a5c5792584567bd1d7937
6
+ metadata.gz: 499616144e44018c60fe0618c962a15262e0a1dd01821dc688483c5defcc8103771c57b94b540a69b0ddd2759c95ff613cae457f7072837c76eecb44d0857505
7
+ data.tar.gz: 819aa6c61fbfa7c8967e57a6f99ce83a87c102913f1ad1a0ef48ba97de6bfffa859d8f6a4f7c536194539bc6e7c401f96604e3e2ad84a27573d15c5d808ed754
@@ -0,0 +1,248 @@
1
+ # Change Log
2
+
3
+ ### 4.17.0.0
4
+
5
+ - Upgrade to SWT (Standard Widget Toolkit) 4.17 and sync version with SWT going forward
6
+ - Upgrade to Glimmer (DSL Engine) 1.0.0
7
+
8
+ ### 0.6.9
9
+
10
+ - Log error messages when running inside sync_exec or async_exec (since you cannot rescue their errors from outside them)
11
+ - Exclude gladiator from required libraries during sample listing/running/code-display
12
+ - Ensured creating a widget with swt_widget keyword arg doesn't retrigger initializers on its parents if already initialized
13
+ - Extract `WidgetProxy#interpret_style` to make it possible to extend with further styles with less code (e.g. CDateTimeProxy adds CDT styles by overriding method)
14
+
15
+ ### 0.6.8
16
+
17
+ - Support external configuration of `WidgetProxy::KEYWORD_ALIASES` (e.g. `radio` is an alias for `button(:radio)`)
18
+ - Support external configuration of `Glimmer::Config::SAMPLE_DIRECTORIES` for the `glimmer sample` commands from Glimmer gems
19
+
20
+ ### 0.6.7
21
+
22
+ - Fix issue with re-initializing layout for already initialized swt_widget being wrapped by WidgetProxy via swt_widget keyword args
23
+ - Change naming of scaffolded app bundle for mac to start with a capital letter (e.g. com.evernote.Evernote not com.evernote.evernote)
24
+
25
+ ### 0.6.6
26
+
27
+ - Add User Profile sample from DZone article
28
+ - Colored Ruby syntax highlighting for sample:code and sample:run tasks courtesy of tty-markdown
29
+ - Support `check` as alias to `checkbox` DSL keyword for Button widget with :check style.
30
+ - Validate scaffolded custom shell gem name to ensure it doesn't clash with a built in Ruby method
31
+ - GLIMMER_LOGGER_ASYNC env var for disabling async logging when needed for immediate troubleshooting purposes
32
+ - Fix issue with table equivalent sort edge case (that is two sorts that are equivalent causing an infinite loop of resorting since the table is not correctly identified as sorted already)
33
+
34
+ ### 0.6.5
35
+
36
+ - Added the [rake-tui](https://github.com/AndyObtiva/rake-tui) gem as a productivity tool for arrow key navigation/text-filtering/quick-triggering of rake tasks
37
+ - Use rake-tui gem in `glimmer` command by default on Mac and Linux
38
+
39
+ ### 0.6.4
40
+
41
+ - Display glimmer-dsl-swt gem version in glimmer command usage
42
+ - Include Glimmer Samples in Gem and provide access via `glimmer samples:list`, `glimmer samples:run`, and `glimmer samples:code` commands
43
+ - Fix issue with glimmer not listing commands in usage without having a Rakefile
44
+ - Fix issue with passing --log-level or --debug to the `girb` command
45
+
46
+ ### 0.6.3
47
+
48
+ **Scaffolding:**
49
+
50
+ - Add mnemonic to Preferences menu in scaffolding
51
+ - Make bin/glimmer, bin/girb, and scaffolded bin/script files call jruby instead of ruby in the shebang
52
+ - Launch scaffolded app on Linux without using packaging (via `glimmer bin/app_script`)
53
+ - Add all of Mac, Windows, and Linux icons upon scaffolding (not just for the OS we are on)
54
+
55
+ **Packaging:**
56
+
57
+ - Perform gemspec:generate first during packaging
58
+ - Ensure lock_jars step happens before package:jar to have vendor jar-dependencies packaged inside JAR file
59
+ - Change lock_jar vendor-dir to vendor/jars and add it to .gitignore
60
+ - Handle naming of -Bwin.menuGroup properly for Windows in scaffolded custom shell gems (and apps) (e.g. instead of Glimmer Cs Timer set to Timer only or namespace when available in a CustomShell)
61
+ - Support passing javapackager extra args after `glimmer package:native` command inside double-quotes (e.g. `glimmer package:native "-title 'CarMaker'"`)
62
+ - JDK14 experimental `jpackage` support as a packaging alternative to `javapackager` (Not recommended for production use and must specify JDK8 as JRE with an additional option since SWT doesn't support JDK14 yet)
63
+
64
+ **GUI:**
65
+
66
+ - Add radio and checkbox table editors
67
+ - Add `content` method to DisplayProxy
68
+ - Add `content` method to MessageBox
69
+ - WidgetProxy now supports taking a fully constructed swt_widget argument instead of init_args
70
+
71
+ **CI:**
72
+
73
+ - Add Windows to Travis-CI
74
+
75
+ **Issues:**
76
+
77
+ - Fix issue with TableProxy editor rejecting false and nil values set on items
78
+ - Fix issue with message_box getting stuck upon closing when no parent in its args
79
+ - Fix transient issue with git bash not interpretting glimmer package[msi] as a rake task (yet as packages instead as it resolves [msi] by picking s to match packages local directory)
80
+ - Fix issue with getting "Namespace is required!" when running `glimmer scaffold[app_name]` or `glimmer scaffold:gem:customshell[name,namespace]` (https://github.com/AndyObtiva/glimmer/issues/5)
81
+
82
+ ### 0.6.2
83
+
84
+ - Set default margins on layouts (FilLayout, RowLayout, GridLayout, and any layout that responds to marginWidth and marginHeight)
85
+ - Have scrolled_composite autoset min width and min height based on parent size
86
+ - Add `radio`, `toggle`, `checkbox`, and `arrow` widgets as shortcuts to `button` widget with different styles
87
+ - Add parent_proxy method to WidgetProxy
88
+ - Add post_add_content hook method to WidgetProxy
89
+ - Add `image` keyword to create an ImageProxy and be able to scale it
90
+ - Fix issue with ImageProxy not being scalable before swt_image is called
91
+
92
+ ### 0.6.1
93
+
94
+ - Lock JARs task for jar-dependencies as part of packaging
95
+ - Add 'vendor' to require_paths for custom shell gem
96
+ - Add Windows icon to scaffold
97
+ - Generate scaffolded app/custom-shell-gem gemspec as part of packaging (useful for jar-dependencies)
98
+ - Support a package:native type option for specifying native type
99
+ - Add a preferences menu for Windows (since it does not have one out of the box)
100
+ - Fix app scaffold on Windows by having it generate jeweler gem first (to have gemspec for jar-dependencies)
101
+ - Fix girb for Windows
102
+
103
+ ### 0.6.0
104
+
105
+ - Upgrade to JRuby 9.2.13.0
106
+ - Upgrade to SWT 4.16
107
+ - Support `font` keyword
108
+ - Support cursor setting via SWT style symbols directly
109
+ - Support `cursor` keyword
110
+
111
+ ### 0.5.6
112
+
113
+ - Fixed issue with excluding on_swt_* listeners from Glimmer DSL engine processing in CustomWidget
114
+ - Add shell minimum_size to Tic Tac Toe sample for Linux
115
+
116
+ ### 0.5.5
117
+
118
+ - Add 'package' directory to 'config/warble.rb' for packaging in JAR file
119
+ - Fix issue with image path conversion to imagedata on Mac vs Windows
120
+
121
+ ### 0.5.4
122
+
123
+ - Fix issue with uri:classloader paths generated by JRuby when using File.expand_path inside packaged JAR files
124
+
125
+ ### 0.5.3
126
+
127
+ - Set widget `image`/`images` property via string file path(s) just like `background_image`
128
+
129
+ ### 0.5.2
130
+
131
+ - Added :full_selection to table widget default SWT styles
132
+
133
+ ### 0.5.1
134
+
135
+ - Made packaging -BsystemWide option true on the Mac only
136
+
137
+ ### 0.5.0
138
+
139
+ - Upgrade to glimmer 0.10.1 to take advantage of the new logging library
140
+ - Make Glimmer commands support acronym, dash and no separator (default) alternatives
141
+ - Support scaffold commands for gems with `scaffold:gem:cw` pattern (`cs` as other suffix)
142
+ - Support listing commands with `list:gems:cw` pattern (`cs` as other suffix)
143
+ - Add -BinstalldirChooser=true / -Bcopyright=string / -Bvendor=string / -Bwin.menuGroup=string to Package class to support Windows packaging
144
+ - Configure 'logging' gem to generate log files on Windows/Linux/Mac and syslog where available
145
+ - Configure 'logging' gem to do async buffered logging via a thread to avoid impacting app performance with logging
146
+ - Make GLIMMER_LOGGER_LEVEL env var work with logging gem
147
+ - Update all logger calls to be lazy blocks
148
+ - Add logging formatter (called layout in logging library)
149
+ - Support legacy rake tasks for package and scaffold (the ones without gem/gems nesting)
150
+ - GLIMMER_LOGGER_LEVEL env var disables async logging in logging gem to help with immediate troubleshooting
151
+ - Create 'log' directory if :file logging device is specified
152
+ - Remember log level when reseting logger after the first time
153
+ - Dispose all tree items when removed
154
+ - Dispose all table items when removed
155
+ - Remove table model collection observers when updating
156
+ - Make message_box instantiate a shell if none passed in
157
+ - Eliminate unimportant (false negative) log messages getting reported as ERROR when running test suite
158
+ - Sort table on every change to maintain its sort according to its sorted column
159
+
160
+ ### 0.4.1
161
+
162
+ - Fixed an issue with async_exec and sync_exec keywords not working when used from a module that mixes Glimmer
163
+
164
+ ### 0.4.0
165
+
166
+ - Support SWT listener events that take multiple-args (as in custom libraries like Nebula GanttChart)
167
+ - Drop on_event_* keywords in favor of on_swt_* for SWT constant events
168
+ - Remove Table#table_editor_text_proxy in favor of Table#table_editor_widget_proxy
169
+ - Set WidgetProxy/ShellProxy/DisplayProxy data('proxy') objects
170
+ - Set CustomWidget data('custom_widget') objects
171
+ - Set CustomShell data('custom_shell') objects
172
+ - Delegate all WidgetProxy/ShellProxy/DisplayProxy/CustomWidget/CustomShell methods to wrapped SWT object on method_missing
173
+
174
+ ### 0.3.1
175
+
176
+ - Support multiple widgets for editing table items
177
+
178
+ ## 0.3.0
179
+
180
+ - Update API for table column sorting to pass models not properties to sorting blocks
181
+ - Support table multi-column sort_property
182
+ - Support table additional_sort_properties array
183
+ - Display table column sorting direction sign
184
+ - Update Scaffold MessageBox reference to message_box DSL keyword
185
+ - Fix issue with different sorting blocks not reseting each other on different table columns
186
+
187
+ ## 0.2.4
188
+
189
+ - Make table auto-sortable
190
+ - Configure custom sorters for table columns
191
+ - Support for ScrolledComposite smart default behavior (auto setting of content, h_scroll/v_scroll styles, and horizontal/vertical expand)
192
+
193
+ ## 0.2.3
194
+
195
+ - Upgraded to Glimmer 0.9.4
196
+ - Add vendor directory to warble config for glimmer package command.
197
+ - Make WidgetProxy register only the nearest ancestor property observer, calling on_modify_text and on_widget_selected for widgets that support these listeners, or otherwise the widget specific customizations
198
+ - Add glimmer package:clean command
199
+ - Make scaffolding gems fail when no namespace is specified
200
+ - Add a hello menu samples
201
+
202
+ ## 0.2.2
203
+
204
+ - Support Combo custom-text-entry data-binding
205
+ - Remove Gemfile.lock from .gitignore in scaffolding apps/gems
206
+
207
+ ## 0.2.1
208
+
209
+ - Support latest JRuby 9.2.12.0
210
+ - Support extra args (other than style) in WidgetProxy just like ShellProxy
211
+ - Specify additional Java packages to import when including Glimmer via Glimmer::Config::import_swt_packages=(packages)
212
+ - Add compatibility for ActiveSupport (automatically call ActiveSupport::Dependencies.unhook! if ActiveSupport is loaded)
213
+ - Fix bug with table items data binding ignoring bind converters
214
+
215
+ ## 0.2.0
216
+
217
+ - Simplified Drag and Drop API by being able to attach drag and drop event listener handlers directly on widgets
218
+ - Support drag and drop events implicitly on all widgets without explicit drag source and drop target declarations
219
+ - Set drag and drop transfer property to :text by default if not specified
220
+ - Automatically set `event.detail` inside `on_drag_enter` to match the first operation specified in `drop_target` (make sure it doesn't cause problems if source and target have differnet operations, denying drop gracefully)
221
+ - Support `dnd` keyword for easily setting `event.detail` (e.g. dnd(:drop_copy)) inside `on_drag_enter` (and consider supporting symbol directly as well)
222
+ - Support Drag and Drop on Custom Widgets
223
+ - Fix hello_computed.rb sample (convert camelcase to underscore case for layout data properties)
224
+
225
+ ## 0.1.3
226
+
227
+ - Added 'org.eclipse.swt.dnd' to glimmer auto-included Java packages
228
+ - Updated Tic Tac Toe sample to use new `message_box` keyword
229
+ - Add DragSource and DropTarget transfer expression that takes a symbol or symbol array representing one or more of the following: FileTransfer, HTMLTransfer, ImageTransfer, RTFTransfer, TextTransfer, URLTransfer
230
+ - Set default style DND::DROP_COPY in DragSource and DropTarget widgets
231
+ - Support Glimmer::SWT::DNDProxy for handling Drop & Drop styles
232
+ - Implemented list:* rake tasks for listing Glimmer custom widget gems, custom shell gems, and dsl gems
233
+ - Support querying for Glimmer gems (not just listing them)
234
+ - Fix bug with table edit remaining when sorting table or re-listing (in contact_manager.rb sample)
235
+ - Update icon of scaffolded apps to Glimmer logo
236
+
237
+ ## 0.1.2
238
+
239
+ - Extracted common model data-binding classes into glimmer
240
+
241
+ ## 0.1.1
242
+
243
+ - Fixed issue with packaging after generating gemspec
244
+ - Fixed issue with enabling development mode in glimmer command
245
+
246
+ ## 0.1.0
247
+
248
+ - Extracted Glimmer DSL for SWT (glimmer-dsl-swt gem) from Glimmer
@@ -1,4 +1,4 @@
1
- Copyright (c) 2020 Andy Maleh
1
+ Copyright (c) 2007-2020 Andy Maleh
2
2
 
3
3
  Permission is hereby granted, free of charge, to any person obtaining
4
4
  a copy of this software and associated documentation files (the
data/README.md CHANGED
@@ -1,49 +1,3937 @@
1
- # [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for SWT 0.6.5 (Desktop GUI)
1
+ # [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for SWT 4.17.0.0
2
+ ## JRuby Desktop Development GUI Library
2
3
  [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-swt.svg)](http://badge.fury.io/rb/glimmer-dsl-swt)
3
4
  [![Travis CI](https://travis-ci.com/AndyObtiva/glimmer-dsl-swt.svg?branch=master)](https://travis-ci.com/github/AndyObtiva/glimmer-dsl-swt)
4
5
  [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/glimmer-dsl-swt/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/glimmer-dsl-swt?branch=master)
5
6
  [![Maintainability](https://api.codeclimate.com/v1/badges/aaf1cba142dd351f84bd/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-swt/maintainability)
6
7
  [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
7
8
 
8
- [Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [SWT](https://www.eclipse.org/swt/) enables desktop development with [Glimmer](https://github.com/AndyObtiva/glimmer).
9
+ **[Contributors Wanted! (Submit a Glimmer App Sample to Get Started)](#contributing)**
9
10
 
10
- [Glimmer](https://github.com/AndyObtiva/glimmer) is a native-GUI cross-platform desktop development library written in Ruby. Glimmer's main innovation is a JRuby DSL that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust Eclipse SWT library. Glimmer additionally innovates by having built-in data-binding support to greatly facilitate synchronizing the GUI with domain models. As a result, that achieves true decoupling of object oriented components, enabling developers to solve business problems without worrying about GUI concerns, or alternatively drive development GUI-first, and then write clean business models test-first afterwards.
11
+ (The Original Glimmer Library Since 2007. Beware of Imitators!)
11
12
 
12
- You may find full setup/usage instructions at the main [Glimmer project page](https://github.com/AndyObtiva/glimmer).
13
+ [**Glimmer**](https://rubygems.org/gems/glimmer) is a native-GUI cross-platform desktop development library written in [JRuby](https://www.jruby.org/), an OS-threaded faster version of [Ruby](https://www.ruby-lang.org/en/). [Glimmer](https://rubygems.org/gems/glimmer)'s main innovation is a declarative [Ruby DSL](#glimmer-dsl-syntax) that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust [Eclipse SWT library](https://www.eclipse.org/swt/). [Glimmer](https://rubygems.org/gems/glimmer) additionally innovates by having built-in [data-binding](#data-binding) support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns. To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](#scaffolding) options for [Apps](#in-production), [Gems](#custom-shell-gem), and [Custom Widgets](#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](#packaging--distribution) support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in [Ruby](https://www.ruby-lang.org/en/) as truly native DMG/PKG/APP files on the [Mac](https://www.apple.com/ca/macos) + [App Store](https://developer.apple.com/macos/distribution/) and MSI/EXE files on [Windows](https://www.microsoft.com/en-ca/windows).
13
14
 
14
- Other [Glimmer](https://github.com/AndyObtiva/glimmer) DSL gems:
15
+ [Glimmer receives two updates per month](https://rubygems.org/gems/glimmer-dsl-swt/versions). You can trust [Glimmer](https://rubygems.org/gems/glimmer) with your Ruby desktop GUI development needs.
16
+
17
+ NOTE: Glimmer is in beta mode. Please make better by providing feedback and [contributing](#contributing) when possible. The more feedback and issues you report the better.
18
+
19
+ [<img src="https://covers.oreillystatic.com/images/9780596519650/lrg.jpg" width=105 /><br />
20
+ Featured in<br />JRuby Cookbook](http://shop.oreilly.com/product/9780596519650.do)
21
+
22
+ Glimmer DSL gems:
23
+ - [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop GUI)
24
+ - [glimmer-dsl-tk](https://github.com/AndyObtiva/glimmer-dsl-tk): Glimmer DSL for Tk (Ruby Desktop GUI)
15
25
  - [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
16
26
  - [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML)
17
- - [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets)
27
+ - [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS
28
+
29
+ ## Examples
30
+
31
+ ### Hello, World!
32
+
33
+ Glimmer code (from [samples/hello/hello_world.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_world.rb)):
34
+ ```ruby
35
+ include Glimmer
36
+
37
+ shell {
38
+ text "Glimmer"
39
+ label {
40
+ text "Hello, World!"
41
+ }
42
+ }.open
43
+ ```
44
+
45
+ Run:
46
+ ```
47
+ glimmer sample:run[hello_world]
48
+ ```
49
+
50
+ Glimmer app:
51
+
52
+ ![Hello World](images/glimmer-hello-world.png)
53
+
54
+ ### Tic Tac Toe
55
+
56
+ Glimmer code (from [samples/elaborate/tic_tac_toe.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/tic_tac_toe.rb)):
57
+
58
+ ```ruby
59
+ # ...
60
+ @tic_tac_toe_board = Board.new
61
+
62
+ @shell = shell {
63
+ text "Tic-Tac-Toe"
64
+ minimum_size 150, 178
65
+ composite {
66
+ grid_layout 3, true
67
+ (1..3).each { |row|
68
+ (1..3).each { |column|
69
+ button {
70
+ layout_data :fill, :fill, true, true
71
+ text bind(@tic_tac_toe_board[row, column], :sign)
72
+ enabled bind(@tic_tac_toe_board[row, column], :empty)
73
+ font style: :bold, height: 20
74
+ on_widget_selected {
75
+ @tic_tac_toe_board.mark(row, column)
76
+ }
77
+ }
78
+ }
79
+ }
80
+ }
81
+ }
82
+
83
+ observe(@tic_tac_toe_board, :game_status) { |game_status|
84
+ display_win_message if game_status == Board::WIN
85
+ display_draw_message if game_status == Board::DRAW
86
+ }
87
+ # ...
88
+ ```
89
+
90
+ Run:
91
+
92
+ ```
93
+ glimmer sample:run[tic_tac_toe]
94
+ ```
95
+
96
+ Glimmer app:
97
+
98
+ ![Tic Tac Toe](images/glimmer-tic-tac-toe-in-progress.png)
99
+
100
+ ### Contact Manager
101
+
102
+ Glimmer code (from [samples/elaborate/contact_manager.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/contact_manager.rb)):
103
+
104
+ ```ruby
105
+ # ...
106
+ shell {
107
+ text "Contact Manager"
108
+ composite {
109
+ group {
110
+ grid_layout(2, false) {
111
+ margin_width 0
112
+ margin_height 0
113
+ }
114
+ layout_data :fill, :center, true, false
115
+ text 'Lookup Contacts'
116
+ font height: 24
117
+
118
+ label {
119
+ layout_data :right, :center, false, false
120
+ text "First &Name: "
121
+ font height: 16
122
+ }
123
+ text {
124
+ layout_data :fill, :center, true, false
125
+ text bind(@contact_manager_presenter, :first_name)
126
+ on_key_pressed {|key_event|
127
+ @contact_manager_presenter.find if key_event.keyCode == swt(:cr)
128
+ }
129
+ }
130
+
131
+ label {
132
+ layout_data :right, :center, false, false
133
+ text "&Last Name: "
134
+ font height: 16
135
+ }
136
+ text {
137
+ layout_data :fill, :center, true, false
138
+ text bind(@contact_manager_presenter, :last_name)
139
+ on_key_pressed {|key_event|
140
+ @contact_manager_presenter.find if key_event.keyCode == swt(:cr)
141
+ }
142
+ }
143
+
144
+ label {
145
+ layout_data :right, :center, false, false
146
+ text "&Email: "
147
+ font height: 16
148
+ }
149
+ text {
150
+ layout_data :fill, :center, true, false
151
+ text bind(@contact_manager_presenter, :email)
152
+ on_key_pressed {|key_event|
153
+ @contact_manager_presenter.find if key_event.keyCode == swt(:cr)
154
+ }
155
+ }
156
+
157
+ composite {
158
+ row_layout {
159
+ margin_width 0
160
+ margin_height 0
161
+ }
162
+ layout_data(:right, :center, false, false) {
163
+ horizontal_span 2
164
+ }
165
+
166
+ button {
167
+ text "&Find"
168
+ on_widget_selected { @contact_manager_presenter.find }
169
+ on_key_pressed {|key_event|
170
+ @contact_manager_presenter.find if key_event.keyCode == swt(:cr)
171
+ }
172
+ }
173
+
174
+ button {
175
+ text "&List All"
176
+ on_widget_selected { @contact_manager_presenter.list }
177
+ on_key_pressed {|key_event|
178
+ @contact_manager_presenter.list if key_event.keyCode == swt(:cr)
179
+ }
180
+ }
181
+ }
182
+ }
183
+
184
+ table(:multi) { |table_proxy|
185
+ layout_data {
186
+ horizontal_alignment :fill
187
+ vertical_alignment :fill
188
+ grab_excess_horizontal_space true
189
+ grab_excess_vertical_space true
190
+ height_hint 200
191
+ }
192
+ table_column {
193
+ text "First Name"
194
+ width 80
195
+ }
196
+ table_column {
197
+ text "Last Name"
198
+ width 80
199
+ }
200
+ table_column {
201
+ text "Email"
202
+ width 200
203
+ }
204
+ items bind(@contact_manager_presenter, :results),
205
+ column_properties(:first_name, :last_name, :email)
206
+ on_mouse_up { |event|
207
+ table_proxy.edit_table_item(event.table_item, event.column_index)
208
+ }
209
+ }
210
+ }
211
+ }.open
212
+ # ...
213
+ ```
214
+
215
+ Run:
216
+
217
+ ```
218
+ glimmer sample:run[contact_manager]
219
+ ```
220
+
221
+ Glimmer App:
222
+
223
+ ![Contact Manager](images/glimmer-contact-manager.png)
224
+
225
+ ### Desktop Apps Built with Glimmer DSL for SWT
226
+
227
+ [<img alt="Are We There Yet Logo" src="https://raw.githubusercontent.com/AndyObtiva/are-we-there-yet/master/are-we-there-yet-logo.svg" width="40" />Are We There Yet?](https://github.com/AndyObtiva/are-we-there-yet) - Small Project Tracking App
228
+
229
+ [![Are We There Yet? App Screenshot](https://raw.githubusercontent.com/AndyObtiva/are-we-there-yet/master/are-we-there-yet-screenshot-windows.png)](https://github.com/AndyObtiva/are-we-there-yet)
230
+
231
+ [<img alt="Math Bowling Logo" src="https://raw.githubusercontent.com/AndyObtiva/MathBowling/master/images/math-bowling-logo.png" width="40" />Math Bowling](https://github.com/AndyObtiva/MathBowling) - Elementary Level Math Game Featuring Bowling Rules
232
+
233
+ [![Math Bowling App Screenshot](https://raw.githubusercontent.com/AndyObtiva/MathBowling/master/Math-Bowling-Screenshot.png)](https://github.com/AndyObtiva/MathBowling)
234
+
235
+ ## Table of contents
236
+
237
+ - [Glimmer (Ruby Desktop Development GUI Library)](#-glimmer-ruby-desktop-development-gui-library)
238
+ - [Examples](#examples)
239
+ - [Hello, World!](#hello-world)
240
+ - [Tic Tac Toe](#tic-tac-toe)
241
+ - [Contact Manager](#contact-manager)
242
+ - [Table of contents](#table-of-contents)
243
+ - [Background](#background)
244
+ - [Platform Support](#platform-support)
245
+ - [Pre-requisites](#pre-requisites)
246
+ - [Setup](#setup)
247
+ - [Option 1: Direct Install](#option-1-direct-install)
248
+ - [Option 2: Bundler](#option-2-bundler)
249
+ - [Glimmer Command](#glimmer-command)
250
+ - [Basic Usage](#basic-usage)
251
+ - [Advanced Usage](#advanced-usage)
252
+ - [Sample List/Run/Code](#sample-listruncode)
253
+ - [Sample List](#sample-list)
254
+ - [Sample Run](#sample-run)
255
+ - [Sample Code](#sample-code)
256
+ - [Scaffolding](#scaffolding)
257
+ - [App](#app)
258
+ - [Custom Shell](#custom-shell)
259
+ - [Custom Widget](#custom-widget)
260
+ - [Custom Shell Gem](#custom-shell-gem)
261
+ - [Custom Widget Gem](#custom-widget-gem)
262
+ - [Gem Listing](#gem-listing)
263
+ - [Listing Custom Shell Gems](#listing-custom-shell-gems)
264
+ - [Listing Custom Widget Gems](#listing-custom-widget-gems)
265
+ - [Listing DSL Gems](#listing-dsl-gems)
266
+ - [Packaging](#packaging)
267
+ - [Raw JRuby Command](#raw-jruby-command)
268
+ - [Mac Support](#mac-support)
269
+ - [Girb (Glimmer irb) Command](#girb-glimmer-irb-command)
270
+ - [Glimmer GUI DSL Syntax](#glimmer-gui-dsl-syntax)
271
+ - [DSL Auto-Expansion](#dsl-auto-expansion)
272
+ - [Widgets](#widgets)
273
+ - [Display](#display)
274
+ - [SWT Proxies](#swt-proxies)
275
+ - [Dialog](#dialog)
276
+ - [Menus](#menus)
277
+ - [ScrolledComposite](#scrolledcomposite)
278
+ - [Widget Styles](#widget-styles)
279
+ - [Explicit SWT Style Bit](#explicit-swt-style-bit)
280
+ - [Negative SWT Style Bits](#negative-swt-style-bits)
281
+ - [Extra SWT Styles](#extra-swt-styles)
282
+ - [Widget Properties](#widget-properties)
283
+ - [Color](#color)
284
+ - [Font](#font)
285
+ - [Cursor](#cursor)
286
+ - [Layouts](#layouts)
287
+ - [Layout Data](#layout-data)
288
+ - [Data-Binding](#data-binding)
289
+ - [General Examples](#general-examples)
290
+ - [Combo](#combo)
291
+ - [List](#list)
292
+ - [Table](#table)
293
+ - [Tree](#tree)
294
+ - [Observer](#observer)
295
+ - [Observing Widgets](#observing-widgets)
296
+ - [Observing Models](#observing-models)
297
+ - [Custom Widgets](#custom-widgets)
298
+ - [Simple Example](#simple-example)
299
+ - [Lifecycle Hook Example](#lifecycle-hook-example)
300
+ - [Custom Widget API](#custom-widget-api)
301
+ - [Content/Options Example](#contentoptions-example)
302
+ - [Custom Widget Lifecycle Hooks](#custom-widget-lifecycle-hooks)
303
+ - [Gotcha](#gotcha)
304
+ - [Final Notes](#final-notes)
305
+ - [Custom Shells](#custom-shells)
306
+ - [Drag and Drop](#drag-and-drop)
307
+ - [Miscellaneous](#miscellaneous)
308
+ - [Multi-DSL Support](#multi-dsl-support)
309
+ - [Application Menu Items (About/Preferences)](#application-menu-items-aboutpreferences)
310
+ - [App Name and Version](#app-name-and-version)
311
+ - [Video Widget](#video-widget)
312
+ - [Browser Widget](#browser-widget)
313
+ - [Glimmer Configuration](#glimmer-configuration)
314
+ - [logger](#logger)
315
+ - [logging_devices](#loggingdevices)
316
+ - [logging_device_file_options](#loggingdevicefileoptions)
317
+ - [logging_appender_options](#loggingappenderoptions)
318
+ - [logging_layout](#logginglayout)
319
+ - [import_swt_packages](#importswtpackages)
320
+ - [loop_max_count](#loopmaxcount)
321
+ - [excluded_keyword_checkers](#excludedkeywordcheckers)
322
+ - [log_excluded_keywords](#logexcludedkeywords)
323
+ - [Glimmer Style Guide](#glimmer-style-guide)
324
+ - [SWT Reference](#swt-reference)
325
+ - [Samples](#samples)
326
+ - [Hello Samples](#hello-samples)
327
+ - [Hello, World! Sample](#hello-world-sample)
328
+ - [Hello, Tab!](#hello-tab)
329
+ - [Hello, Combo!](#hello-combo)
330
+ - [Hello, List Single Selection!](#hello-list-single-selection)
331
+ - [Hello, List Multi Selection!](#hello-list-multi-selection)
332
+ - [Hello, Computed!](#hello-computed)
333
+ - [Hello, Message Box!](#hello-message-box)
334
+ - [Hello, Browser!](#hello-browser)
335
+ - [Hello, Drag and Drop!](#hello-drag-and-drop)
336
+ - [Hello, Menu Bar!](#hello-menu-bar)
337
+ - [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu)
338
+ - [Elaborate Samples](#elaborate-samples)
339
+ - [User Profile](#user-profile)
340
+ - [Login](#login)
341
+ - [Tic Tac Toe Sample](#tic-tac-toe-sample)
342
+ - [Contact Manager Sample](#contact-manager-sample)
343
+ - [External Samples](#external-samples)
344
+ - [Glimmer Calculator](#glimmer-calculator)
345
+ - [Gladiator](#gladiator)
346
+ - [Timer](#timer)
347
+ - [In Production](#in-production)
348
+ - [Math Bowling](#math-bowling)
349
+ - [Are We There Yet?](#are-we-there-yet)
350
+ - [Garderie Rainbow Daily Agenda](#garderie-rainbow-daily-agenda)
351
+ - [Packaging & Distribution](#packaging--distribution)
352
+ - [Packaging Defaults](#packaging-defaults)
353
+ - [Packaging Configuration](#packaging-configuration)
354
+ - [javapackager Extra Arguments](#javapackager-extra-arguments)
355
+ - [Verbose Mode](#verbose-mode)
356
+ - [Windows Application Packaging](#windows-application-packaging)
357
+ - [Mac Application Distribution](#mac-application-distribution)
358
+ - [Self Signed Certificate](#self-signed-certificate)
359
+ - [Gotchas](#gotchas)
360
+ - [App Updates](#app-updates)
361
+ - [Glimmer Supporting Libraries](#glimmer-supporting-libraries)
362
+ - [Glimmer Process](#glimmer-process)
363
+ - [Resources](#resources)
364
+ - [Help](#help)
365
+ - [Issues](#issues)
366
+ - [Chat](#chat)
367
+ - [Feature Suggestions](#feature-suggestions)
368
+ - [Change Log](#change-log)
369
+ - [Contributing](#contributing)
370
+ - [Contributors](#contributors)
371
+ - [Hire Me](#hire-me)
372
+ - [License](#license)
373
+
374
+ ## Background
375
+
376
+ Ruby is a dynamically-typed object-oriented language, which provides great productivity gains due to its powerful expressive syntax and dynamic nature. While it is proven by the Ruby on Rails framework for web development, it currently lacks a robust platform-independent framework for building desktop applications. Given that Java libraries can now be utilized in Ruby code through JRuby, Eclipse technologies, such as SWT, JFace, and RCP can help fill the gap of desktop application development with Ruby.
377
+
378
+ ## Platform Support
379
+
380
+ Glimmer runs on the following platforms:
381
+ - Mac
382
+ - Windows
383
+ - Linux
384
+
385
+ Glimmer's GUI has the native look and feel of each operating system it runs on since it uses SWT behind the scenes, which leverages the following native libraries:
386
+ - Win32 on Windows
387
+ - Cocoa on Mac
388
+ - GTK on Linux
389
+
390
+ More info about the SWT GUI on various platforms can be found on the Eclipse WIKI and SWT FAQ:
391
+
392
+ https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide#Win32.2FCocoa.2FGTK
393
+ https://www.eclipse.org/swt/faq.php
394
+
395
+ ## Pre-requisites
396
+
397
+ - JDK 8u241 (1.8.0_241) (find at https://www.oracle.com/java/technologies/javase/javase8u211-later-archive-downloads.html)
398
+ - JRuby 9.2.13.0 (supporting Ruby 2.5.x syntax) (get via [RVM](http://rvm.io) on Mac and Linux or find at [https://www.jruby.org/download](https://www.jruby.org/download) for Windows)
399
+ - SWT 4.17 (already included in the [glimmer-dsl-swt](https://rubygems.org/gems/glimmer-dsl-swt) gem)
400
+
401
+ To obtain JRuby through [RVM](http://rvm.io), you may run:
402
+
403
+ ```bash
404
+ rvm install jruby-9.2.13.0
405
+ ```
406
+
407
+ Glimmer might still work on other versions of Java, JRuby and SWT, but there are no guarantees, so it is best to stick to the pre-requisites outlined above.
408
+
409
+ ## Setup
410
+
411
+ Please follow these instructions to make the `glimmer` command available on your system via the [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem.
412
+
413
+ If you intend to learn the basics of Glimmer but are not ready to build a Glimmer app yet, pick Option 1 ([Direct Install](#option-1-direct-install)).
414
+
415
+ If you intend to build a Glimmer app from scratch with [scaffolding](#scaffolding), pick Option 1 ([Direct Install](#option-1-direct-install)) as well.
416
+
417
+ Otherwise, Option 2 ([Bundler](#option-2-bundler)) can be followed in rare cases where you want to build an app without [scaffolding](#scaffolding).
418
+
419
+ ### Option 1: Direct Install
420
+ (Use for [Scaffolding](#scaffolding))
421
+
422
+ Run this command to install directly:
423
+ ```
424
+ jgem install glimmer-dsl-swt
425
+ ```
426
+
427
+ Or this command if you want a specific version:
428
+ ```
429
+ jgem install glimmer-dsl-swt -v 4.17.0.0
430
+ ```
431
+
432
+ Note: Gem version numbers are in sync with the SWT library versions. The first two digits represent the SWT version number. The last two digits represent the minor and patch versions of Glimmer DSL for SWT.
433
+
434
+ `jgem` is JRuby's version of `gem` command.
435
+ RVM allows running `gem install` directly as an alias.
436
+ Otherwise, you may also run `jruby -S gem install ...`
437
+
438
+ If you are new to Glimmer and would like to continue learning the basics, you may continue to the [Glimmer Command](https://github.com/AndyObtiva/glimmer#glimmer-command) section.
439
+
440
+ Otherwise, if you are ready to build a Glimmer app on the Mac, you can jump to the [Glimmer Scaffolding](https://github.com/AndyObtiva/glimmer#scaffolding) section next.
441
+
442
+ Note: if you're using activerecord or activesupport, keep in mind that Glimmer unhooks ActiveSupport::Dependencies as it does not rely on it.
443
+
444
+ ### Option 2: Bundler
445
+ (Use for Manual App Creation)
446
+
447
+ Add the following to `Gemfile`:
448
+ ```
449
+ gem 'glimmer-dsl-swt', '~> 4.17.0.0'
450
+ ```
451
+
452
+ And, then run:
453
+ ```
454
+ jruby -S bundle install
455
+ ```
456
+
457
+ Note: if you're using activerecord or activesupport, keep in mind that Glimmer unhooks ActiveSupport::Dependencies as it does not rely on it.
458
+
459
+ You may learn more about other Glimmer related gems ([`glimmer-dsl-opal`](https://github.com/AndyObtiva/glimmer-dsl-opal), [`glimmer-dsl-xml`](https://github.com/AndyObtiva/glimmer-dsl-xml), and [`glimmer-dsl-css`](https://github.com/AndyObtiva/glimmer-dsl-css)) at [Multi-DSL Support](#multi-dsl-support)
460
+
461
+ ## Glimmer Command
462
+
463
+ The `glimmer` command allows you to run, scaffold, package, and list Glimmer applications/gems.
464
+
465
+ You can bring up usage instructions by running the `glimmer` command without arguments:
466
+
467
+ ```
468
+ glimmer
469
+ ```
470
+
471
+ On Mac and Linux, it additionally brings up a TUI (Text-based User Interface) for interactive navigation and execution of Glimmer tasks (courtesy of [rake-tui](https://github.com/AndyObtiva/rake-tui)).
472
+
473
+ On Windows, it simply lists the available Glimmer tasks at the end (courtsey of [rake](https://github.com/ruby/rake)).
474
+
475
+ If you are new to Glimmer, you may read the Basic Usage section and skip the rest until you have gone through [Girb (Glimmer irb) Command](#girb-glimmer-irb-command), [Glimmer GUI DSL Syntax](#glimmer-gui-dsl-syntax), and [Samples](#samples).
476
+
477
+ ### Basic Usage
478
+
479
+ ```
480
+ glimmer application.rb
481
+ ```
482
+
483
+ Runs a Glimmer application using JRuby, automatically preloading
484
+ the glimmer ruby gem and SWT jar dependency.
485
+
486
+ Example:
487
+ ```
488
+ glimmer sample:run[hello_world]
489
+ ```
490
+ This runs the Glimmer "Hello, World!" sample.
491
+
492
+ If you cloned this project locally, you may run `bin/glimmer` instead.
493
+
494
+ Example:
495
+ ```
496
+ bin/glimmer sample:run[hello_world]
497
+ ```
498
+
499
+ ### Advanced Usage
500
+
501
+ Below are the full usage instructions that come up when running `glimmer` without args.
502
+
503
+ ```
504
+ Glimmer (Ruby Desktop Development GUI Library) - JRuby Gem: glimmer-dsl-swt v4.17.0.0
505
+
506
+ Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
507
+
508
+ Runs Glimmer applications and tasks.
509
+
510
+ When applications are specified, they are run using JRuby,
511
+ automatically preloading the glimmer Ruby gem and SWT jar dependency.
512
+
513
+ Optionally, extra Glimmer options, JRuby options, and/or environment variables may be passed in.
514
+
515
+ Glimmer options:
516
+ - "--quiet" : Does not announce file path of Glimmer application being launched
517
+ - "--debug" : Displays extra debugging information, passes "--debug" to JRuby, and enables debug logging
518
+ - "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
519
+
520
+ Tasks are run via rake. Some tasks take arguments in square brackets.
521
+
522
+ Available tasks are below (if you do not see any, please add `require 'glimmer/rake_task'` to Rakefile and rerun or run rake -T):
523
+
524
+ Select a Glimmer task to run: (Press ↑/↓ arrow to move, Enter to select and letters to filter)
525
+ ‣ glimmer list:gems:customshell[query] # List Glimmer custom shell gems available at rubygems.org (query is optional) [alt: list:gems:cs]
526
+ glimmer list:gems:customwidget[query] # List Glimmer custom widget gems available at rubygems.org (query is optional) [alt: list:gems:cw]
527
+ glimmer list:gems:dsl[query] # List Glimmer DSL gems available at rubygems.org (query is optional)
528
+ glimmer package[type] # Package app for distribution (generating config, jar, and native files) (type is optional)
529
+ glimmer package:clean # Clean by removing "dist" and "packages" directories
530
+ glimmer package:config # Generate JAR config file
531
+ glimmer package:jar # Generate JAR file
532
+ glimmer package:lock_jars # Lock JARs
533
+ glimmer package:native[type] # Generate Native files
534
+ glimmer sample:code[name] # Outputs code for a Glimmer internal sample [included in gem] (name is required)
535
+ glimmer sample:list[query] # Lists Glimmer internal samples [included in gem]. Filters by query if specified (query is optional)
536
+ glimmer sample:run[name] # Runs a Glimmer internal sample [included in gem]. If no name is supplied, it runs all samples
537
+ glimmer scaffold[app_name] # Scaffold Glimmer application directory structure to build a new app
538
+ glimmer scaffold:customshell[name,namespace] # Scaffold Glimmer::UI::CustomShell subclass (full window view) under app/views (namespace is optional) [alt: scaffold:cs]
539
+ glimmer scaffold:customwidget[name,namespace] # Scaffold Glimmer::UI::CustomWidget subclass (part of a view) under app/views (namespace is optional) [alt: scaffold:cw]
540
+ glimmer scaffold:gem:customshell[name,namespace] # Scaffold Glimmer::UI::CustomShell subclass (full window view) under its own Ruby gem + app project (namespace is required) [alt: scaffold:ge...
541
+ glimmer scaffold:gem:customwidget[name,namespace] # Scaffold Glimmer::UI::CustomWidget subclass (part of a view) under its own Ruby gem project (namespace is required) [alt: scaffold:gem:cw]
542
+ ```
543
+
544
+ Example (Glimmer/JRuby option specified):
545
+ ```
546
+ glimmer --debug samples/hello/hello_world.rb
547
+ ```
548
+
549
+ Runs Glimmer application with JRuby debug option to enable JRuby debugging.
550
+
551
+ Example (Multiple apps):
552
+ ```
553
+ glimmer samples/hello/hello_world.rb samples/hello/hello_tab.rb
554
+ ```
555
+
556
+ Launches samples/hello/hello_world.rb and samples/hello_tab.rb at the same time, each in a separate JRuby thread.
557
+
558
+ ### Sample List/Run/Code
559
+
560
+ #### Sample List
561
+
562
+ You can list available Glimmer samples by running:
563
+
564
+ ```
565
+ glimmer sample:list
566
+ ```
567
+
568
+ This should output the following (providing the name of each sample, description, and command to run the sample and view its code):
569
+
570
+ ```
571
+ $ glimmer sample:list
572
+
573
+ Glimmer Hello Samples:
574
+
575
+ Name Description Run
576
+
577
+ hello_browser Hello Browser glimmer sample:run[hello_browser]
578
+ hello_combo Hello Combo glimmer sample:run[hello_combo]
579
+ hello_computed Hello Computed glimmer sample:run[hello_computed]
580
+ hello_drag_and_drop Hello Drag And Drop glimmer sample:run[hello_drag_and_drop]
581
+ hello_list_multi_selection Hello List Multi Selection glimmer sample:run[hello_list_multi_selection]
582
+ hello_list_single_selection Hello List Single Selection glimmer sample:run[hello_list_single_selection]
583
+ hello_menu_bar Hello Menu Bar glimmer sample:run[hello_menu_bar]
584
+ hello_message_box Hello Message Box glimmer sample:run[hello_message_box]
585
+ hello_pop_up_context_menu Hello Pop Up Context Menu glimmer sample:run[hello_pop_up_context_menu]
586
+ hello_tab Hello Tab glimmer sample:run[hello_tab]
587
+ hello_world Hello World glimmer sample:run[hello_world]
588
+
589
+
590
+ Glimmer Elaborate Samples:
591
+
592
+ Name Description Run
593
+
594
+ contact_manager Contact Manager glimmer sample:run[contact_manager]
595
+ login Login glimmer sample:run[login]
596
+ tic_tac_toe Tic Tac Toe glimmer sample:run[tic_tac_toe]
597
+ user_profile User Profile glimmer sample:run[user_profile]
598
+ ```
599
+
600
+ #### Sample Run
601
+
602
+ A sample may be run via `glimmer sample:run[name]`. This also outputs the sample code so that you could take a look at it and compare to the GUI that launches.
603
+
604
+ If the sample name is left empty (e.g. `glimmer sample:run`), then all samples are run.
605
+
606
+ Example:
607
+
608
+ ```
609
+ glimmer sample:run[hello_tab]
610
+ ```
611
+
612
+ This will run the hello_tab sample and output its code:
613
+
614
+ ```
615
+ $ glimmer sample:run[hello_tab]
616
+
617
+ # /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.0.0/samples/hello/hello_tab.rb
618
+
619
+ class HelloTab
620
+ include Glimmer
621
+ def launch
622
+ shell {
623
+ text "Hello, Tab!"
624
+ tab_folder {
625
+ tab_item {
626
+ text "English"
627
+ label {
628
+ text "Hello, World!"
629
+ }
630
+ }
631
+ tab_item {
632
+ text "French"
633
+ label {
634
+ text "Bonjour, Univers!"
635
+ }
636
+ }
637
+ }
638
+ }.open
639
+ end
640
+ end
641
+
642
+ HelloTab.new.launch
643
+
644
+ # # #
645
+ ```
646
+
647
+ ![Hello Tab English](images/glimmer-hello-tab-english.png)
648
+
649
+ #### Sample Code
650
+
651
+ You may output any sample code via this command: `glimmer sample:code[name]`
652
+
653
+ This is very similar to the sample run command, except the name is required.
654
+
655
+ It will not only output the main sample file, but any required supporting files as well.
656
+
657
+ Example:
658
+
659
+ ```
660
+ $ glimmer sample:code[tic_tac_toe]
661
+
662
+ # /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.0.0/samples/elaborate/tic_tac_toe.rb
663
+
664
+ require_relative "tic_tac_toe/board"
665
+
666
+ class TicTacToe
667
+ include Glimmer
668
+
669
+ def initialize
670
+ @tic_tac_toe_board = Board.new
671
+ @shell = shell {
672
+ text "Tic-Tac-Toe"
673
+ minimum_size 150, 178
674
+ composite {
675
+ grid_layout 3, true
676
+ (1..3).each { |row|
677
+ (1..3).each { |column|
678
+ button {
679
+ layout_data :fill, :fill, true, true
680
+ text bind(@tic_tac_toe_board[row, column], :sign)
681
+ enabled bind(@tic_tac_toe_board[row, column], :empty)
682
+ font style: :bold, height: 20
683
+ on_widget_selected {
684
+ @tic_tac_toe_board.mark(row, column)
685
+ }
686
+ }
687
+ }
688
+ }
689
+ }
690
+ }
691
+ observe(@tic_tac_toe_board, :game_status) { |game_status|
692
+ display_win_message if game_status == Board::WIN
693
+ display_draw_message if game_status == Board::DRAW
694
+ }
695
+ end
696
+
697
+ def display_win_message
698
+ display_game_over_message("Player #{@tic_tac_toe_board.winning_sign} has won!")
699
+ end
700
+
701
+ def display_draw_message
702
+ display_game_over_message("Draw!")
703
+ end
704
+
705
+ def display_game_over_message(message_text)
706
+ message_box(@shell) {
707
+ text 'Game Over'
708
+ message message_text
709
+ }.open
710
+ @tic_tac_toe_board.reset
711
+ end
712
+
713
+ def open
714
+ @shell.open
715
+ end
716
+ end
717
+
718
+ TicTacToe.new.open
719
+
720
+ # # #
721
+
722
+
723
+ # /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.0.0/samples/elaborate/tic_tac_toe/cell.rb
724
+
725
+ class TicTacToe
726
+ class Cell
727
+ EMPTY = ""
728
+ attr_accessor :sign, :empty
729
+
730
+ def initialize
731
+ reset
732
+ end
733
+
734
+ def mark(sign)
735
+ self.sign = sign
736
+ end
737
+
738
+ def reset
739
+ self.sign = EMPTY
740
+ end
741
+
742
+ def sign=(sign_symbol)
743
+ @sign = sign_symbol
744
+ self.empty = sign == EMPTY
745
+ end
746
+
747
+ def marked
748
+ !empty
749
+ end
750
+ end
751
+ end
752
+
753
+ # # #
754
+
755
+
756
+ # /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.0.0/samples/elaborate/tic_tac_toe/board.rb
757
+
758
+ require_relative 'cell'
759
+
760
+ class TicTacToe
761
+ class Board
762
+ DRAW = :draw
763
+ IN_PROGRESS = :in_progress
764
+ WIN = :win
765
+ attr :winning_sign
766
+ attr_accessor :game_status
767
+
768
+ def initialize
769
+ @sign_state_machine = {nil => "X", "X" => "O", "O" => "X"}
770
+ build_grid
771
+ @winning_sign = Cell::EMPTY
772
+ @game_status = IN_PROGRESS
773
+ end
774
+
775
+ #row and column numbers are 1-based
776
+ def mark(row, column)
777
+ self[row, column].mark(current_sign)
778
+ game_over? #updates winning sign
779
+ end
780
+
781
+ def current_sign
782
+ @current_sign = @sign_state_machine[@current_sign]
783
+ end
784
+
785
+ def [](row, column)
786
+ @grid[row-1][column-1]
787
+ end
788
+
789
+ def game_over?
790
+ win? or draw?
791
+ end
792
+
793
+ def win?
794
+ win = (row_win? or column_win? or diagonal_win?)
795
+ self.game_status=WIN if win
796
+ win
797
+ end
798
+
799
+ def reset
800
+ (1..3).each do |row|
801
+ (1..3).each do |column|
802
+ self[row, column].reset
803
+ end
804
+ end
805
+ @winning_sign = Cell::EMPTY
806
+ @current_sign = nil
807
+ self.game_status=IN_PROGRESS
808
+ end
809
+
810
+ private
811
+
812
+ def build_grid
813
+ @grid = []
814
+ 3.times do |row_index| #0-based
815
+ @grid << []
816
+ 3.times { @grid[row_index] << Cell.new }
817
+ end
818
+ end
819
+
820
+ def row_win?
821
+ (1..3).each do |row|
822
+ if row_has_same_sign(row)
823
+ @winning_sign = self[row, 1].sign
824
+ return true
825
+ end
826
+ end
827
+ false
828
+ end
829
+
830
+ def column_win?
831
+ (1..3).each do |column|
832
+ if column_has_same_sign(column)
833
+ @winning_sign = self[1, column].sign
834
+ return true
835
+ end
836
+ end
837
+ false
838
+ end
839
+
840
+ #needs refactoring if we ever decide to make the board size dynamic
841
+ def diagonal_win?
842
+ if (self[1, 1].sign == self[2, 2].sign) and (self[2, 2].sign == self[3, 3].sign) and self[1, 1].marked
843
+ @winning_sign = self[1, 1].sign
844
+ return true
845
+ end
846
+ if (self[3, 1].sign == self[2, 2].sign) and (self[2, 2].sign == self[1, 3].sign) and self[3, 1].marked
847
+ @winning_sign = self[3, 1].sign
848
+ return true
849
+ end
850
+ false
851
+ end
852
+
853
+ def draw?
854
+ @board_full = true
855
+ 3.times do |x|
856
+ 3.times do |y|
857
+ @board_full = false if self[x, y].empty
858
+ end
859
+ end
860
+ self.game_status = DRAW if @board_full
861
+ @board_full
862
+ end
863
+
864
+ def row_has_same_sign(number)
865
+ row_sign = self[number, 1].sign
866
+ [2, 3].each do |column|
867
+ return false unless row_sign == (self[number, column].sign)
868
+ end
869
+ true if self[number, 1].marked
870
+ end
871
+
872
+ def column_has_same_sign(number)
873
+ column_sign = self[1, number].sign
874
+ [2, 3].each do |row|
875
+ return false unless column_sign == (self[row, number].sign)
876
+ end
877
+ true if self[1, number].marked
878
+ end
879
+
880
+ end
881
+ end
882
+
883
+ # # #
884
+ ```
885
+
886
+ ### Scaffolding
887
+
888
+ Glimmer borrows from Rails the idea of Scaffolding, that is generating a structure for your app files that
889
+ helps you get started just like true buildinThis g scaffolding helps construction workers, civil engineers, and architects.
890
+
891
+ Glimmer scaffolding goes beyond just scaffolding the app files that Rails does. It also packages it and launches it,
892
+ getting you to a running and delivered state of an advanced "Hello, World!" Glimmer application right off the bat.
893
+
894
+ This should greatly facilitate building a new Glimmer app by helping you be productive and focus on app details while
895
+ letting Glimmer scaffolding take care of initial app file structure concerns, such as adding:
896
+ - Main application class that includes Glimmer (`app/{app_name}.rb`)
897
+ - Main application view that houses main window content, menu, about dialog, and preferences dialog
898
+ - View and Model directories (`app/views` and `app/models`)
899
+ - Rakefile including Glimmer tasks (`Rakefile`)
900
+ - Version (`VERSION`)
901
+ - License (`LICENSE.txt`)
902
+ - Icon (under `package/{platform}/{App Name}.{icon_extension}` for `macosx` .icns, `windows` .ico, and `linux` .png)
903
+ - Bin file for starting application (`bin/{app_name}.rb`)
904
+
905
+ NOTE: Scaffolding supports Mac and Windows packaging at the moment.
906
+
907
+ #### App
908
+
909
+ Before you start, make sure you are in a JRuby environment with Glimmer gem installed as per "Direct Install" pre-requisites.
910
+
911
+ To scaffold a Glimmer app from scratch, run the following command:
912
+
913
+ ```
914
+ glimmer scaffold[AppName]
915
+ ```
916
+
917
+ This will generate an advanced "Hello, World!" app, package it as a Mac native file (DMG/PKG/APP), and launch it all in one fell swoop.
918
+
919
+ Suppose you run:
920
+
921
+ ```
922
+ glimmer scaffold[greeter]
923
+ ```
924
+
925
+ You should see output like the following:
926
+
927
+ ```
928
+ $ glimmer scaffold[greeter]
929
+ create .gitignore
930
+ create Rakefile
931
+ create Gemfile
932
+ create LICENSE.txt
933
+ create README.rdoc
934
+ create .document
935
+ create lib
936
+ create lib/greeter.rb
937
+ create spec
938
+ create spec/spec_helper.rb
939
+ create spec/greeter_spec.rb
940
+ create .rspec
941
+ Jeweler has prepared your gem in ./greeter
942
+ Created greeter/.gitignore
943
+ Created greeter/.ruby-version
944
+ Created greeter/.ruby-gemset
945
+ Created greeter/VERSION
946
+ Created greeter/LICENSE.txt
947
+ Created greeter/Gemfile
948
+ Created greeter/Rakefile
949
+ Created greeter/app/greeter.rb
950
+ Created greeter/app/views/greeter/app_view.rb
951
+ Created greeter/package/windows/Greeter.ico
952
+ Created greeter/package/macosx/Greeter.icns
953
+ Created greeter/package/linux/Greeter.png
954
+ Created greeter/bin/greeter
955
+ Created greeter/spec/spec_helper.rb
956
+ ...
957
+ ```
958
+
959
+ Eventually, it will launch an advanced "Hello, World!" app window having the title of your application ("Greeter").
960
+
961
+ ![Glimmer Scaffold App](images/glimmer-scaffolding-app.png)
962
+
963
+ It also comes with a boilerplate Preferences dialog.
964
+
965
+ ![Glimmer Scaffold App Preferences](images/glimmer-scaffolding-app-preferences.png)
966
+
967
+ Here is the Windows version of the scaffolded "Greeter" app:
968
+
969
+ ![Glimmer Scaffold App Windows](images/glimmer-scaffolding-app-windows.png)
970
+
971
+ And, here is the Windows version of the boilerplate Preferences dialog.
972
+
973
+ ![Glimmer Scaffold App Windows Preferences](images/glimmer-scaffolding-app-windows-preferences.png)
974
+
975
+ In order to run the app after making changes, you must run the `glimmer` command and pass it the generated script under the `bin` directory as an argument:
976
+
977
+ ```
978
+ glimmer bin/greeter
979
+ ```
980
+
981
+ #### Custom Shell
982
+
983
+ To scaffold a Glimmer custom shell (full window view) for an existing Glimmer app, run the following command:
984
+
985
+ ```
986
+ glimmer scaffold:customshell[name]
987
+ ```
988
+
989
+ Or the following alternative abbreviation:
990
+
991
+ ```
992
+ glimmer scaffold:cs[name]
993
+ ```
994
+
995
+ #### Custom Widget
996
+
997
+ To scaffold a Glimmer custom widget (part of a view) for an existing Glimmer app, run the following command:
998
+
999
+ ```
1000
+ glimmer scaffold:customwidget[name]
1001
+ ```
1002
+
1003
+ Or the following alternative abbreviation:
1004
+
1005
+ ```
1006
+ glimmer scaffold:cw[name]
1007
+ ```
1008
+
1009
+ #### Custom Shell Gem
1010
+
1011
+ Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
1012
+ They have everything scaffolded Glimmer apps come with in addition to gem content like a [jeweler](https://github.com/technicalpickles/jeweler) Rakefile that can build gemspec and release gems.
1013
+ Unlike scaffolded Glimmer apps, custom shell gem content lives under the `lib` directory (not `app`).
1014
+ They can be packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem.
1015
+ Of course, you can just build a Ruby gem and disregard native executable packaging if you do not need it.
1016
+
1017
+ To scaffold a Glimmer custom shell gem (full window view distributed as a Ruby gem), run the following command:
1018
+
1019
+ ```
1020
+ glimmer scaffold:gem:customshell[name,namespace]
1021
+ ```
1022
+
1023
+ Or the following alternative abbreviation:
1024
+
1025
+ ```
1026
+ glimmer scaffold:gem:cs[name,namespace]
1027
+ ```
1028
+
1029
+ It is important to specify a namespace to avoid having your gem clash with existing gems.
1030
+
1031
+ The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell).
1032
+
1033
+ Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. [glimmer-cs-gladiator](https://rubygems.org/gems/glimmer-cs-gladiator) Ruby gem)
1034
+
1035
+ Since custom shell gems are both an app and a gem, they provide two ways to run:
1036
+ - Run the `glimmer` command and pass it the generated script under the `bin` directory that matches the gem name (e.g. run `glimmer bin/glimmer-cs-calculator`)
1037
+ - Run the executable binary file that ships with the gem directly (without `glimmer`). It intentionally has a shorter name for convenience since it is meant to be used on the command line (not in a package), so you can leave out the `glimmer-cs-` prefix (e.g. run `bin/calculator` directly)
1038
+
1039
+ Examples:
1040
+
1041
+ - [glimmer-cs-gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator): Gladiator (Glimmer Editor)
1042
+ - [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator): Glimmer Calculator
1043
+
1044
+ #### Custom Widget Gem
1045
+
1046
+ To scaffold a Glimmer custom widget gem (part of a view distributed as a Ruby gem), run the following command:
1047
+
1048
+ ```
1049
+ glimmer scaffold:gem:customwidget[name,namespace]
1050
+ ```
1051
+
1052
+ Or the following alternative abbreviation:
1053
+
1054
+ ```
1055
+ glimmer scaffold:gem:cw[name,namespace]
1056
+ ```
1057
+
1058
+
1059
+ It is important to specify a namespace to avoid having your gem clash with existing gems.
1060
+
1061
+ The Ruby gem name will follow the convention "glimmer-cw-customwidgetname-namespace" (the 'cw' is for Custom Widget)
1062
+
1063
+ Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. [glimmer-cw-video](https://rubygems.org/gems/glimmer-cw-video) Ruby gem)
1064
+
1065
+ Examples:
1066
+
1067
+ - [glimmer-cw-video](https://github.com/AndyObtiva/glimmer-cw-video): Video Widget
1068
+ - [glimmer-cw-cdatetime-nebula](https://github.com/AndyObtiva/glimmer-cw-cdatetime-nebula): Nebula CDateTime Widget
1069
+
1070
+ ### Gem Listing
1071
+
1072
+ The `glimmer` command comes with tasks for listing Glimmer related gems to make it easy to find Glimmer Custom Shells, Custom Widgets, and DSLs published by others in the Glimmer community on [rubygems.org](http://www.rubygems.org).
1073
+
1074
+ #### Listing Custom Shell Gems
1075
+
1076
+ The following command lists available Glimmer [Custom Shell Gems](#custom-shell-gem) (prefixed with "glimmer-cs-" by scaffolding convention) created by the the Glimmer community and published on [rubygems.org](http://www.rubygems.org):
1077
+
1078
+ ```
1079
+ glimmer list:gems:customshell[query]
1080
+ ```
1081
+
1082
+ Or the following alternative abbreviation:
1083
+
1084
+ ```
1085
+ glimmer list:gems:cs[query]
1086
+ ```
1087
+
1088
+ Example:
1089
+
1090
+ ```
1091
+ glimmer list:gems:cs
1092
+ ```
1093
+
1094
+ Output:
1095
+
1096
+ ```
1097
+
1098
+ Glimmer Custom Shell Gems at rubygems.org:
1099
+
1100
+ Name Gem Version Author Description
1101
+
1102
+ Calculator glimmer-cs-calculator 1.0.2 Andy Maleh Calculator - Glimmer Custom Shell
1103
+ Gladiator glimmer-cs-gladiator 0.2.4 Andy Maleh Gladiator (Glimmer Editor) - Glimmer Custom Shell
1104
+ Timer glimmer-cs-timer 1.0.0 Andy Maleh Timer - Glimmer Custom Shell
1105
+
1106
+ ```
1107
+
1108
+ #### Listing Custom Widget Gems
1109
+
1110
+ The following command lists available Glimmer [Custom Widget Gems](#custom-widget-gem) (prefixed with "glimmer-cw-" by scaffolding convention) created by the the Glimmer community and published on [rubygems.org](http://www.rubygems.org):
1111
+
1112
+ ```
1113
+ glimmer list:gems:customwidget[query]
1114
+ ```
1115
+
1116
+ Or the following alternative abbreviation:
1117
+
1118
+ ```
1119
+ glimmer list:gems:cw[query]
1120
+ ```
1121
+
1122
+ Example:
1123
+
1124
+ Check if there is a custom video widget for Glimmer.
1125
+
1126
+ ```
1127
+ glimmer list:gems:cw[video]
1128
+ ```
1129
+
1130
+ Output:
1131
+
1132
+ ```
1133
+
1134
+ Glimmer Custom Widget Gems matching [video] at rubygems.org:
1135
+
1136
+ Name Gem Version Author Description
1137
+
1138
+ Video glimmer-cw-video 0.1.3 Andy Maleh Glimmer Custom Widget - Video
1139
+
1140
+ ```
1141
+
1142
+ #### Listing DSL Gems
1143
+
1144
+ The following command lists available Glimmer [DSL Gems](#multi-dsl-support) (prefixed with "glimmer-dsl-" by convention) created by the the Glimmer community and published on [rubygems.org](http://www.rubygems.org):
1145
+
1146
+ ```
1147
+ glimmer list:gems:dsl[query]
1148
+ ```
1149
+
1150
+ Example:
1151
+
1152
+ ```
1153
+ glimmer list:gems:dsl
1154
+ ```
1155
+
1156
+ Output:
1157
+
1158
+ ```
1159
+
1160
+ Glimmer DSL Gems at rubygems.org:
1161
+
1162
+ Name Gem Version Author Description
1163
+
1164
+ Css glimmer-dsl-css 0.2.0 AndyMaleh Glimmer DSL for CSS
1165
+ Opal glimmer-dsl-opal 0.1.0 AndyMaleh Glimmer DSL for Opal
1166
+ Swt glimmer-dsl-swt 4.17.0.0 AndyMaleh Glimmer DSL for SWT
1167
+ Tk glimmer-dsl-tk 0.0.5 AndyMaleh Glimmer DSL for Tk
1168
+ Xml glimmer-dsl-xml 0.2.0 AndyMaleh Glimmer DSL for XML
1169
+ ```
1170
+
1171
+ ### Packaging
1172
+
1173
+ Glimmer packaging tasks are detailed under [Packaging & Distribution](#packaging--distribution).
1174
+
1175
+ ### Raw JRuby Command
1176
+
1177
+ If there is a need to run Glimmer directly via the `jruby` command, you
1178
+ may run the following:
1179
+
1180
+ ```
1181
+ jruby -J-classpath "path_to/swt.jar" -r glimmer -S application.rb
1182
+ ```
1183
+
1184
+ The `-J-classpath` option specifies the `swt.jar` file path, which can be a
1185
+ manually downloaded version of SWT, or otherwise the one included in the gem. You can lookup the one included in the gem by running `jgem which glimmer` to find the gem path and then look through the `vendor` directory.
1186
+
1187
+ The `-r` option preloads (requires) the `glimmer` library in Ruby.
1188
+
1189
+ The `-S` option specifies a script to run.
1190
+
1191
+ #### Mac Support
1192
+
1193
+ The Mac is well supported with the `glimmer` command. The advice below is not needed if you are using it.
1194
+
1195
+ However, if there is a reason to use the raw `jruby` command directly instead of the `glimmer` command, you need to pass an extra option (`-J-XstartOnFirstThread`) to JRuby on the Mac (Glimmer automatically passes it for you when using the `glimmer` command).
1196
+
1197
+ Example:
1198
+ ```
1199
+ jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer -S application.rb
1200
+ ```
1201
+
1202
+ ## Girb (Glimmer irb) Command
1203
+
1204
+ With `glimmer-dsl-swt` installed, you may want to run `girb` instead of standard `irb` to have SWT preloaded and the Glimmer library required and included for quick Glimmer coding/testing.
1205
+
1206
+ ```
1207
+ girb
1208
+ ```
1209
+
1210
+ If you cloned [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) project locally, you may run `bin/girb` instead.
1211
+
1212
+ ```
1213
+ bin/girb
1214
+ ```
1215
+
1216
+ Watch out for hands-on examples in this README indicated by "you may copy/paste in [`girb`](#girb-glimmer-irb-command)"
1217
+
1218
+ Keep in mind that all samples live under [https://github.com/AndyObtiva/glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt)
1219
+
1220
+ ## Glimmer GUI DSL Syntax
1221
+
1222
+ Glimmer's core is a GUI DSL with a lightweight visual syntax that makes it easy to visualize the nesting of widgets in the GUI hierarchy tree.
1223
+
1224
+ It is available through mixing in the `Glimmer` module, which makes Glimmer GUI DSL keywords available to both the instance scope and class scope:
1225
+
1226
+ ```ruby
1227
+ include Glimmer
1228
+ ```
1229
+
1230
+ For example, here is the basic "Hello, World!" sample code (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1231
+
1232
+ ```ruby
1233
+ include Glimmer
1234
+
1235
+ shell {
1236
+ text "Glimmer"
1237
+ label {
1238
+ text "Hello, World!"
1239
+ }
1240
+ }.open
1241
+ ```
1242
+
1243
+ The `include Glimmer` declaration on top mixed the `Glimmer` module into the Ruby global main object making the Glimmer GUI DSL available at the top-level global scope.
1244
+
1245
+ While this works well enough for mini-samples, it is better to isolate Glimmer in a class or module during production application development to create a clean separation between view code (GUI) and model code (business domain). Here is the "Hello, World!" sample re-written in a class to illustrate how mixing in the `Glimmer` module (via `include Glimmer`) makes the Glimmer GUI DSL available in both the instance scope and class scope. That is clearly demonstrated by pre-initializing a color constant in the class scope and building the GUI in the `#open` instance method (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1246
+
1247
+ ```ruby
1248
+ class HelloWorld
1249
+ include Glimmer # makes the GUI DSL available in both the class scope and instance scope
1250
+
1251
+ COLOR_FOREGROUND_DEFAULT = rgb(255, 0, 0) # rgb is a GUI DSL keyword used in the class scope
1252
+
1253
+ def open
1254
+ # the following are GUI DSL keywords (shell, text, and label) used in the instance scope
1255
+ shell {
1256
+ text "Glimmer"
1257
+ label {
1258
+ text "Hello, World!"
1259
+ foreground COLOR_FOREGROUND_DEFAULT
1260
+ }
1261
+ }.open
1262
+ end
1263
+ end
1264
+
1265
+ HelloWorld.new.open
1266
+ ```
1267
+
1268
+ This renders "Hello, World!" with a red foreground color:
1269
+
1270
+ ![Hello World Red Foreground Color](images/glimmer-hello-world-red-foreground-color.png)
1271
+
1272
+ The GUI DSL intentionally avoids overly verbose syntax, requiring as little declarative code as possible to describe what GUI to render, how to style it, and what properties to data-bind to the Models.
1273
+
1274
+ As such, it breaks off from Ruby's convention of using `do end` for multi-line blocks, opting instead for the lightweight and visual `{ }` curly brace blocks everywhere inside the GUI DSL. More details about Glimmer's syntax conventions may be found in the [Glimmer Style Guide](#glimmer-style-guide)
1275
+
1276
+ Glimmer DSL syntax consists mainly of:
1277
+ - keywords (e.g. `table` for a table widget)
1278
+ - style/args (e.g. :multi as in `table(:multi)` for a multi-line selection table widget)
1279
+ - content (e.g. `{ table_column { text 'Name'} }` as in `table(:multi) { table_column { text 'name'} }` for a multi-line selection table widget with a table column having header text property `'Name'` as content)
1280
+
1281
+ ### DSL Auto-Expansion
1282
+
1283
+ Glimmer supports a new and radical Ruby DSL concept called DSL Auto-Expansion. It is explained by first mentioning the two types of Glimmer GUI DSL keywords: static and dynamic.
1284
+
1285
+ Static keywords are pre-identified keywords in the Glimmer DSL, such as `shell`, `display`, `message_box`, `async_exec`, `sync_exec`, and `bind`.
1286
+
1287
+ Dynamic keywords are dynamically figured out from currently imported (aka required/loaded) SWT widgets, custom widgets, and widget properties. Examples are: `label`, `combo`, and `list` for widgets and `enabled`, `text`, and `selection` for properties.
1288
+
1289
+ The only reason to distinguish between the two types of Glimmer DSL keywords is to realize that importing new Glimmer [custom widgets](#custom-widgets) and Java SWT custom widget libraries automatically expands Glimmer's DSL vocabulary via new dynamic keywords.
1290
+
1291
+ For example, if a project adds this custom Java SWT library:
1292
+
1293
+ https://www.eclipse.org/nebula/widgets/cdatetime/cdatetime.php?page=operation
1294
+
1295
+ Glimmer will automatically support using the keyword `c_date_time`
1296
+
1297
+ You will learn more about widgets next.
1298
+
1299
+ ### Widgets
1300
+
1301
+ Glimmer GUIs (user interfaces) are modeled with widgets, which are wrappers around the SWT library widgets found here:
1302
+
1303
+ https://www.eclipse.org/swt/widgets/
1304
+
1305
+ This screenshot taken from the link above should give a glimpse of how SWT widgets look and feel:
1306
+
1307
+ [![SWT Widgets](images/glimmer-swt-widgets.png)](https://www.eclipse.org/swt/widgets/)
1308
+
1309
+ In Glimmer DSL, widgets are declared with lowercase underscored names mirroring their SWT names minus the package name. For example, here are some Glimmer widgets and their SWT counterparts:
1310
+
1311
+ - `shell` instantiates `org.eclipse.swt.widgets.Shell`
1312
+ - `text` instantiates `org.eclipse.swt.widgets.Text`
1313
+ - `button` instantiates `org.eclipse.swt.widgets.Button`
1314
+ - `label` instantiates `org.eclipse.swt.widgets.Label`
1315
+ - `composite` instantiates `org.eclipse.swt.widgets.Composite`
1316
+ - `tab_folder` instantiates `org.eclipse.swt.widgets.TabFolder`
1317
+ - `tab_item` instantiates `org.eclipse.swt.widgets.TabItem`
1318
+ - `table` instantiates `org.eclipse.swt.widgets.Table`
1319
+ - `table_column` instantiates `org.eclipse.swt.widgets.TableColumn`
1320
+ - `tree` instantiates `org.eclipse.swt.widgets.Tree`
1321
+ - `combo` instantiates `org.eclipse.swt.widgets.Combo`
1322
+ - `list` instantiates `org.eclipse.swt.widgets.List`
1323
+
1324
+ Every **widget** is sufficiently declared by name, but may optionally be accompanied with:
1325
+ - SWT **style**/***arguments*** wrapped by parenthesis according to [Glimmer Style Guide](#glimmer-style-guide) (see [next section](#widget-styles) for details).
1326
+ - Ruby block containing **content**, which may be **properties** (e.g. `enabled false`) or nested **widgets** (e.g. `table_column` nested inside `table`)
1327
+
1328
+ For example, if we were to revisit `samples/hello/hello_world.rb` above (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1329
+
1330
+ ```ruby
1331
+ shell {
1332
+ text "Glimmer"
1333
+ label {
1334
+ text "Hello, World!"
1335
+ }
1336
+ }.open
1337
+ ```
1338
+
1339
+ Note that `shell` instantiates the outer shell **widget**, in other words, the window that houses all of the desktop graphical user interface.
1340
+
1341
+ `shell` is then followed by a ***block*** that contains
1342
+
1343
+ ```ruby
1344
+ # ...
1345
+ text "Glimmer" # text property of shell
1346
+ label { # label widget declaration as content of shell
1347
+ text "Hello, World!" # text property of label
1348
+ }
1349
+ # ...
1350
+ ```
1351
+
1352
+ The first line declares a **property** called `text`, which sets the title of the shell (window) to `"Glimmer"`. **Properties** always have ***arguments*** (not wrapped by parenthesis according to [Glimmer Style Guide](#glimmer-style-guide)), such as the text `"Glimmer"` in this case, and do **NOT** have a ***block*** (this distinguishes them from **widget** declarations).
1353
+
1354
+ The second line declares the `label` **widget**, which is followed by a Ruby **content** ***block*** that contains its `text` **property** with value `"Hello, World!"`
1355
+
1356
+ The **widget** ***block*** may optionally receive an argument representing the widget proxy object that the block content is for. This is useful in rare cases when the content code needs to refer to parent widget during declaration. You may leave that argument out most of the time and only add when absolutely needed.
1357
+
1358
+ Example:
1359
+
1360
+ ```ruby
1361
+ shell {|shell_proxy|
1362
+ #...
1363
+ }
1364
+ ```
1365
+
1366
+ Remember that The `shell` widget is always the outermost widget containing all others in a Glimmer desktop windowed application.
1367
+
1368
+ After it is declared, a `shell` must be opened with the `#open` method, which can be called on the block directly as in the example above, or by capturing `shell` in a `@shell` variable (shown in example below), and calling `#open` on it independently (recommended in actual apps)
1369
+
1370
+ ```ruby
1371
+ @shell = shell {
1372
+ # properties and content
1373
+ # ...
1374
+ }
1375
+ @shell.open
1376
+ ```
1377
+
1378
+ It is centered upon initial display and has a minimum width of 130 (can be re-centered when needed with `@shell.center` method after capturing `shell` in a `@shell` variable as per samples)
1379
+
1380
+ Check out the [samples](samples) directory for more examples.
1381
+
1382
+ Example from [hello_tab.rb](samples/hello/hello_tab.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1383
+
1384
+ ![Hello Tab English](images/glimmer-hello-tab-english.png)
1385
+
1386
+ ![Hello Tab French](images/glimmer-hello-tab-french.png)
1387
+
1388
+ ```ruby
1389
+ shell {
1390
+ text "Hello, Tab!"
1391
+ tab_folder {
1392
+ tab_item {
1393
+ text "English"
1394
+ label {
1395
+ text "Hello, World!"
1396
+ }
1397
+ }
1398
+ tab_item {
1399
+ text "French"
1400
+ label {
1401
+ text "Bonjour Univers!"
1402
+ }
1403
+ }
1404
+ }
1405
+ }.open
1406
+ ```
1407
+
1408
+ If you are new to Glimmer, you have learned enough to start running some [samples](#samples). Go ahead and run all Glimmer [samples](#samples), and come back to read the rest in any order you like since this material is more organized like a reference.
1409
+
1410
+ #### Display
1411
+
1412
+ SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage GUI globally
1413
+ and access available monitors.
1414
+ It is automatically instantiated upon first instantiation of a `shell` widget.
1415
+ Alternatively, for advanced use cases, it can be created explicitly with Glimmer `display` keyword. When a `shell` is later declared, it
1416
+ automatically uses the display created earlier without having to explicitly hook it.
1417
+
1418
+ ```ruby
1419
+ @display = display {
1420
+ cursor_location 300, 300
1421
+ on_swt_keydown {
1422
+ # ...
1423
+ }
1424
+ # ...
1425
+ }
1426
+ @shell = shell { # uses display created above
1427
+ }
1428
+ ```
1429
+ The benefit of instantiating an SWT Display explicitly is to set [Properties](#widget-properties) or [Observers](#observer).
1430
+ Although SWT Display is not technically a widget, it has similar APIs in SWT and similar DSL support in Glimmer.
1431
+
1432
+ #### SWT Proxies
1433
+
1434
+ Glimmer follows Proxy Design Pattern by having Ruby proxy wrappers for all SWT objects:
1435
+ - `Glimmer::SWT:WidgetProxy` wraps all descendants of `org.eclipse.swt.widgets.Widget` except the ones that have their own wrappers.
1436
+ - `Glimmer::SWT::ShellProxy` wraps `org.eclipse.swt.widgets.Shell`
1437
+ - `Glimmer::SWT:TabItemProxy` wraps `org.eclipse.swt.widget.TabItem` (also adds a composite to enable adding content under tab items directly in Glimmer)
1438
+ - `Glimmer::SWT:LayoutProxy` wraps all descendants of `org.eclipse.swt.widget.Layout`
1439
+ - `Glimmer::SWT:LayoutDataProxy` wraps all layout data objects
1440
+ - `Glimmer::SWT:DisplayProxy` wraps `org.eclipse.swt.widget.Display` (manages displaying GUI)
1441
+ - `Glimmer::SWT:ColorProxy` wraps `org.eclipse.swt.graphics.Color`
1442
+ - `Glimmer::SWT:FontProxy` wraps `org.eclipse.swt.graphics.Font`
1443
+ - `Glimmer::SWT::WidgetListenerProxy` wraps all widget listeners
1444
+
1445
+ These proxy objects have an API and provide some convenience methods, some of which are mentioned below.
1446
+
1447
+ ##### `#content { ... }`
1448
+
1449
+ Glimmer allows re-opening any widget and adding properties or extra content after it has been constructed already by using the `#content` method.
1450
+
1451
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1452
+
1453
+ ```ruby
1454
+ @shell = shell {
1455
+ text "Application"
1456
+ row_layout
1457
+ @label1 = label {
1458
+ text "Hello,"
1459
+ }
1460
+ }
1461
+ @shell.content {
1462
+ minimum_size 130, 130
1463
+ label {
1464
+ text "World!"
1465
+ }
1466
+ }
1467
+ @label1.content {
1468
+ foreground :red
1469
+ }
1470
+ @shell.open
1471
+ ```
1472
+
1473
+ ##### `message_box`
1474
+
1475
+ The Glimmer DSL `message_box` keyword is similar to `shell`, but renders a modal dialog with a title `text` property and main body `message` property. It may also be opened via the `#open` method.
1476
+
1477
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1478
+
1479
+ ```ruby
1480
+ include Glimmer
1481
+
1482
+ @shell = shell {
1483
+ text 'Hello, Message Box!'
1484
+ button {
1485
+ text 'Please Click To Win a Surprise'
1486
+ on_widget_selected {
1487
+ message_box(@shell) {
1488
+ text 'Surprise'
1489
+ message "Congratulations!\n\nYou have won $1,000,000!"
1490
+ }.open
1491
+ }
1492
+ }
1493
+ }
1494
+ @shell.open
1495
+ ```
1496
+
1497
+ ![Hello Message Box Dialog](images/glimmer-hello-message-box-dialog.png)
1498
+
1499
+ It is also possible to use `message_box` even before instantiating the first `shell` ([Glimmer](https://rubygems.org/gems/glimmer) builds a throwaway `shell` parent automatically for it):
1500
+
1501
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1502
+
1503
+ ```ruby
1504
+ include Glimmer
1505
+
1506
+ message_box {
1507
+ text 'Greeting'
1508
+ message "Hello, World!"
1509
+ }.open
1510
+ ```
1511
+
1512
+ ##### `#swt_widget`
1513
+
1514
+ Glimmer widget objects come with an instance method `#swt_widget` that returns the actual SWT `Widget` object wrapped by the Glimmer widget object. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
1515
+
1516
+ ##### Shell widget proxy methods
1517
+
1518
+ Shell widget proxy has extra methods specific to SWT Shell:
1519
+ - `#open`: Opens the shell, making it visible and active, and starting the SWT Event Loop (you may learn more about it here: https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/widgets/Display.html). If shell was already open, but hidden, it makes the shell visible.
1520
+ - `#show`: Alias for `#open`
1521
+ - `#hide`: Hides a shell setting "visible" property to false
1522
+ - `#close`: Closes the shell
1523
+ - `#center`: Centers the shell within monitor it is in
1524
+ - `#start_event_loop`: (happens as part of `#open`) Starts SWT Event Loop (you may learn more about it here: https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/widgets/Display.html). This method is not needed except in rare circumstances where there is a need to start the SWT Event Loop before opening the shell.
1525
+ - `#visible?`: Returns whether a shell is visible
1526
+ - `#opened_before?`: Returns whether a shell has been opened at least once before (additionally implying the SWT Event Loop has been started already)
1527
+ - `#visible=`: Setting to true opens/shows shell. Setting to false hides the shell.
1528
+ - `#pack`: Packs contained widgets using SWT's `Shell#pack` method
1529
+ - `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
1530
+
1531
+ ##### Shell Icon
1532
+
1533
+ To set the shell icon, simply set the `image` property under the `shell` widget. This shows up in the operating system toolbar and app-switcher (e.g. CMD+TAB) (and application window top-left corner in Windows)
1534
+
1535
+ Example:
1536
+
1537
+ ```ruby
1538
+ shell {
1539
+ # ...
1540
+ image 'path/to/image.png'
1541
+ # ...
1542
+ }
1543
+ ```
1544
+
1545
+ ###### Shell Icon Tip for Packaging on Windows
1546
+
1547
+ When setting shell icon for a [packaged](#packaging--distribution) app, which has a JAR file at its core, you can reference the `ico` file that ships with the app by going one level up (e.g. `'../AppName.ico'`)
1548
+
1549
+ #### Dialog
1550
+
1551
+ Dialog is a variation on Shell. It is basically a shell that is modal (blocks what's behind it) and belongs to another shell. It only has a close button.
1552
+
1553
+ Glimmer facilitates building dialogs by using the `dialog` keyword, which automatically adds the SWT.DIALOG_TRIM and SWT.APPLICATION_MODAL [widget styles](#widget-styles) needed for a dialog.
1554
+
1555
+ #### Menus
1556
+
1557
+ Glimmer DSL provides support for SWT Menu and MenuItem widgets.
1558
+
1559
+ There are 2 main types of menus in SWT:
1560
+ - Menu Bar (shows up on top)
1561
+ - Pop Up Context Menu (shows up when right-clicking a widget)
1562
+
1563
+ Underneath both types, there can be a 3rd menu type called Drop Down.
1564
+
1565
+ Glimmer provides special support for Drop Down menus as it automatically instantiates associated Cascade menu items and wires together with proper parenting, swt styles, and calling setMenu.
1566
+
1567
+ The ampersand symbol indicates the keyboard shortcut key for the menu item (e.g. '&Help' can be triggered on Windows by hitting ALT+H)
1568
+
1569
+ Example of a Menu Bar (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1570
+
1571
+ ```ruby
1572
+ shell { |shell_proxy|
1573
+ text 'Hello, Menu Bar!'
1574
+ grid_layout
1575
+ label(:center) {
1576
+ font height: 16
1577
+ text 'Check Out The File Menu and History Menu in The Menu Bar Above!'
1578
+ }
1579
+ menu_bar {
1580
+ menu {
1581
+ text '&File'
1582
+ menu_item {
1583
+ text 'E&xit'
1584
+ }
1585
+ menu_item(0) {
1586
+ text '&New'
1587
+ on_widget_selected {
1588
+ message_box(shell_proxy) {
1589
+ text 'New File'
1590
+ message 'New File Contents'
1591
+ }.open
1592
+ }
1593
+ }
1594
+ menu(1) {
1595
+ text '&Options'
1596
+ menu_item(:radio) {
1597
+ text 'Option 1'
1598
+ }
1599
+ menu_item(:separator)
1600
+ menu_item(:check) {
1601
+ text 'Option 3'
1602
+ }
1603
+ }
1604
+ }
1605
+ menu {
1606
+ text '&History'
1607
+ menu {
1608
+ text '&Recent'
1609
+ menu_item {
1610
+ text 'File 1'
1611
+ on_widget_selected {
1612
+ message_box(shell_proxy) {
1613
+ text 'File 1'
1614
+ message 'File 1 Contents'
1615
+ }.open
1616
+ }
1617
+ }
1618
+ menu_item {
1619
+ text 'File 2'
1620
+ on_widget_selected {
1621
+ message_box(shell_proxy) {
1622
+ text 'File 2'
1623
+ message 'File 2 Contents'
1624
+ }.open
1625
+ }
1626
+ }
1627
+ }
1628
+ }
1629
+ }
1630
+ }.open
1631
+ ```
1632
+
1633
+ Example of a Pop Up Context Menu (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1634
+
1635
+ ```ruby
1636
+ shell { |shell_proxy|
1637
+ text 'Hello, Pop Up Context Menu!'
1638
+ grid_layout
1639
+ label {
1640
+ font height: 16
1641
+ text 'Right-Click To Pop Up a Context Menu'
1642
+ menu {
1643
+ menu {
1644
+ text '&History'
1645
+ menu {
1646
+ text '&Recent'
1647
+ menu_item {
1648
+ text 'File 1'
1649
+ on_widget_selected {
1650
+ message_box(shell_proxy) {
1651
+ text 'File 1'
1652
+ message 'File 1 Contents'
1653
+ }.open
1654
+ }
1655
+ }
1656
+ menu_item {
1657
+ text 'File 2'
1658
+ on_widget_selected {
1659
+ message_box(shell_proxy) {
1660
+ text 'File 2'
1661
+ message 'File 2 Contents'
1662
+ }.open
1663
+ }
1664
+ }
1665
+ }
1666
+ }
1667
+ }
1668
+ }
1669
+ }.open
1670
+ ```
1671
+
1672
+ #### ScrolledComposite
1673
+
1674
+ Glimmer provides smart defaults for the `scrolled_composite` widget by:
1675
+ - Automatically setting the nested widget as its content (meaning use can just like a plain old `composite` to add scrolling)
1676
+ - Automatically setting the :h_scroll and :v_scroll SWT styles (can be set manually if only one of either :h_scroll or :v_scroll is desired )
1677
+ - Automatically setting the expand horizontal and expand vertical SWT properties to `true`
1678
+
1679
+ ### Widget Styles
1680
+
1681
+ SWT widgets receive `SWT` styles in their constructor as per this guide:
1682
+
1683
+ https://wiki.eclipse.org/SWT_Widget_Style_Bits
1684
+
1685
+ Glimmer DSL facilitates that by passing symbols representing `SWT` constants as widget method arguments (i.e. inside widget `()` parentheses according to [Glimmer Style Guide](#glimmer-style-guide). See example below) in lower case version (e.g. `SWT::MULTI` becomes `:multi`).
1686
+
1687
+ These styles customize widget look, feel, and behavior.
1688
+
1689
+ Example:
1690
+
1691
+ ```ruby
1692
+ # ...
1693
+ list(:multi) { # SWT styles go inside ()
1694
+ # ...
1695
+ }
1696
+ # ...
1697
+ ```
1698
+ Passing `:multi` to `list` widget enables list element multi-selection.
1699
+
1700
+ ```ruby
1701
+ # ...
1702
+ composite(:border) { # SWT styles go inside ()
1703
+ # ...
1704
+ }
1705
+ # ...
1706
+ ```
1707
+ Passing `:border` to `composite` widget ensures it has a border.
1708
+
1709
+ When you need to pass in **multiple SWT styles**, simply separate by commas.
1710
+
1711
+ Example:
1712
+
1713
+ ```ruby
1714
+ # ...
1715
+ text(:center, :border) { # Multiple SWT styles separated by comma
1716
+ # ...
1717
+ }
1718
+ # ...
1719
+ ```
1720
+
1721
+ Glimmer ships with SWT style **smart defaults** so you wouldn't have to set them yourself most of the time (albeit you can always override them):
1722
+
1723
+ - `text(:border)`
1724
+ - `table(:border, :virtual, :full_selection)`
1725
+ - `tree(:border, :virtual, :v_scroll, :h_scroll)`
1726
+ - `spinner(:border)`
1727
+ - `list(:border, :v_scroll)`
1728
+ - `button(:push)`
1729
+
1730
+ You may check out all available `SWT` styles here:
1731
+
1732
+ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
1733
+
1734
+ #### Explicit SWT Style Bit
1735
+
1736
+ When building a widget-related SWT object manually (e.g. `GridData.new(...)`), you are expected to use `SWT::CONSTANT` directly or BIT-OR a few SWT constants together like `SWT::BORDER | SWT::V_SCROLL`.
1737
+
1738
+ Glimmer facilitates that with `swt` keyword by allowing you to pass multiple styles as an argument array of symbols instead of dealing with BIT-OR.
1739
+ Example:
1740
+
1741
+ ```ruby
1742
+ style = swt(:border, :v_scroll)
1743
+ ```
1744
+
1745
+ #### Negative SWT Style Bits
1746
+
1747
+ In rare occasions, you might need to apply & with a negative (not) style bit to negate it from another style bit that includes it.
1748
+ Glimmer facilitates that by declaring the negative style bit via postfixing a symbol with `!`.
1749
+
1750
+ Example:
1751
+
1752
+ ```ruby
1753
+ style = swt(:shell_trim, :max!) # creates a shell trim style without the maximize button (negated)
1754
+ ```
1755
+
1756
+ #### Extra SWT Styles
1757
+
1758
+ ##### Non-resizable Window
1759
+
1760
+ SWT Shell widget by default is resizable. To make it non-resizable, one must pass a complicated style bit concoction like `swt(:shell_trim, :resize!, :max!)`.
1761
+
1762
+ Glimmer makes this easier by alternatively offering a `:no_resize` extra SWT style, added for convenience.
1763
+ This makes declaring a non-resizable window as easy as:
1764
+
1765
+ ```ruby
1766
+ shell(:no_resize) {
1767
+ # ...
1768
+ }
1769
+ ```
1770
+
1771
+ ### Widget Properties
1772
+
1773
+ Widget properties such as text value, enablement, visibility, and layout details are set within the widget block using methods matching SWT widget property names in lower snakecase. You may refer to SWT widget guide for details on available widget properties:
1774
+
1775
+ https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/guide/swt_widgets_controls.htm?cp=2_0_7_0_0
1776
+
1777
+
1778
+ Code examples:
1779
+
1780
+ ```ruby
1781
+ # ...
1782
+ label {
1783
+ text "Hello, World!" # SWT properties go inside {} block
1784
+ }
1785
+ # ...
1786
+ ```
1787
+
1788
+ In the above example, the `label` widget `text` property was set to "Hello, World!".
1789
+
1790
+ ```ruby
1791
+ # ...
1792
+ button {
1793
+ enabled bind(@tic_tac_toe_board.box(row, column), :empty)
1794
+ }
1795
+ # ...
1796
+ ```
1797
+
1798
+ In the above example, the `text` widget `enabled` property was data-bound to `#empty` method on `@tic_tac_toe_board.box(row, column)` (learn more about data-binding below)
1799
+
1800
+ #### Color
1801
+
1802
+ Colors make up a subset of widget properties. SWT accepts color objects created with RGB (Red Green Blue) or RGBA (Red Green Blue Alpha). Glimmer supports constructing color objects using the `rgb` and `rgba` DSL keywords.
1803
+
1804
+ Example:
1805
+
1806
+ ```ruby
1807
+ # ...
1808
+ label {
1809
+ background rgb(144, 240, 244)
1810
+ foreground rgba(38, 92, 232, 255)
1811
+ }
1812
+ # ...
1813
+ ```
1814
+
1815
+ SWT also supports standard colors available as constants under the `SWT` namespace with the `COLOR_` prefix (e.g. `SWT::COLOR_BLUE`)
1816
+
1817
+ Glimmer supports constructing colors for these constants as lowercase Ruby symbols (with or without `color_` prefix) passed to `color` DSL keyword
1818
+
1819
+ Example:
1820
+
1821
+ ```ruby
1822
+ # ...
1823
+ label {
1824
+ background color(:black)
1825
+ foreground color(:yellow)
1826
+ }
1827
+ label {
1828
+ background color(:color_white)
1829
+ foreground color(:color_red)
1830
+ }
1831
+ # ...
1832
+ ```
1833
+
1834
+ You may check out all available standard colors in `SWT` over here (having `COLOR_` prefix):
1835
+
1836
+ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
1837
+
1838
+
1839
+ ##### `#swt_color`
1840
+
1841
+ Glimmer color objects come with an instance method `#swt_color` that returns the actual SWT `Color` object wrapped by the Glimmer color object. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
1842
+
1843
+ Example:
1844
+
1845
+ ```ruby
1846
+ color(:black).swt_color # returns SWT Color object
1847
+ ```
1848
+
1849
+ #### Font
1850
+
1851
+ Fonts are represented in Glimmer as a hash of name, height, and style keys.
1852
+
1853
+ The style can be one (or more) of 3 values: `:normal`, `:bold`, and `:italic`
1854
+
1855
+ Example:
1856
+
1857
+ ```ruby
1858
+ # ...
1859
+ label {
1860
+ font name: 'Arial', height: 36, style: :normal
1861
+ }
1862
+ # ...
1863
+ ```
1864
+
1865
+ Keys are optional, so some of them may be left off.
1866
+ When passing multiple styles, they are included in an array.
1867
+
1868
+ Example:
1869
+
1870
+ ```ruby
1871
+ # ...
1872
+ label {
1873
+ font style: [:bold, :italic]
1874
+ }
1875
+ # ...
1876
+ ```
1877
+
1878
+ You may simply use the standalone `font` keyword without nesting in a parent if there is a need to build a Font object to use in manual SWT programming outside of widget font property setting.
1879
+
1880
+ Example:
1881
+
1882
+ ```ruby
1883
+ @font = font(name: 'Arial', height: 36, style: :normal)
1884
+ ```
1885
+
1886
+ ### Cursor
1887
+
1888
+ SWT widget `cursor` property represents the mouse cursor you see on the screen when you hover over that widget.
1889
+
1890
+ The `Display` class provides a way to obtain standard system cursors matching of the SWT style constants starting with prefix `CURSOR_` (e.g. `SWT::CURSOR_HELP` shows a question mark mouse cursor)
1891
+
1892
+ Glimmer provides an easier way to obtain and set `cursor` property on a widget by simply mentioning the SWT style constant as an abbreviated symbol excluding the "CURSOR_" suffix.
1893
+
1894
+ Example:
1895
+
1896
+ ```ruby
1897
+ shell {
1898
+ minimum_size 128, 128
1899
+ cursor :appstarting
1900
+ }
1901
+ ```
1902
+
1903
+ This sets the shell `cursor` to that of `SWT::CURSOR_APPSTARTING`
1904
+
1905
+ ### Layouts
1906
+
1907
+ Glimmer lays widgets out visually using SWT layouts, which can only be set on composite widget and subclasses.
1908
+
1909
+ The most common SWT layouts are:
1910
+ - `FillLayout`: lays widgets out in equal proportion horizontally or vertically with spacing/margin options. This is the ***default*** layout for ***shell*** (with `:horizontal` option) in Glimmer.
1911
+ - `RowLayout`: lays widgets out horizontally or vertically in varying proportions with advanced spacing/margin/justify options
1912
+ - `GridLayout`: lays widgets out in a grid with advanced spacing/margin/alignment/indentation options. This is the **default** layout for **composite** in Glimmer. It is important to master.
1913
+
1914
+ In Glimmer DSL, just like widgets, layouts can be specified with lowercase underscored names followed by a block containing properties, also lowercase underscored names (e.g. `RowLayout` is `row_layout`).
1915
+
1916
+ Example:
1917
+
1918
+ ```ruby
1919
+ # ...
1920
+ composite {
1921
+ row_layout {
1922
+ wrap true
1923
+ pack false
1924
+ justify true
1925
+ type :vertical
1926
+ margin_left 1
1927
+ margin_top 2
1928
+ margin_right 3
1929
+ margin_bottom 4
1930
+ spacing 5
1931
+ }
1932
+ # ... widgets follow
1933
+ }
1934
+ # ...
1935
+ ```
1936
+
1937
+ If you data-bind any layout properties, when they change, the shell containing their widget re-packs its children (calls `#pack` method automatically) to ensure proper relayout of all widgets.
1938
+
1939
+ Alternatively, a layout may be constructed by following the SWT API for the layout object. For example, a `RowLayout` can be constructed by passing it an SWT style constant (Glimmer automatically accepts symbols (e.g. `:horizontal`) for SWT style arguments like `SWT::HORIZONTAL`.)
1940
+
1941
+ ```ruby
1942
+ # ...
1943
+ composite {
1944
+ row_layout :horizontal
1945
+ # ... widgets follow
1946
+ }
1947
+ # ...
1948
+ ```
1949
+
1950
+ Here is a more sophisticated example taken from [hello_computed.rb](samples/hello/hello_computed.rb) sample:
1951
+
1952
+ ![Hello Computed](images/glimmer-hello-computed.png)
1953
+
1954
+ ```ruby
1955
+ shell {
1956
+ text 'Hello, Computed!'
1957
+ composite {
1958
+ grid_layout {
1959
+ num_columns 2
1960
+ make_columns_equal_width true
1961
+ horizontal_spacing 20
1962
+ vertical_spacing 10
1963
+ }
1964
+ label {text 'First &Name: '}
1965
+ text {
1966
+ text bind(@contact, :first_name)
1967
+ layout_data {
1968
+ horizontal_alignment :fill
1969
+ grab_excess_horizontal_space true
1970
+ }
1971
+ }
1972
+ label {text '&Last Name: '}
1973
+ text {
1974
+ text bind(@contact, :last_name)
1975
+ layout_data {
1976
+ horizontal_alignment :fill
1977
+ grab_excess_horizontal_space true
1978
+ }
1979
+ }
1980
+ label {text '&Year of Birth: '}
1981
+ text {
1982
+ text bind(@contact, :year_of_birth)
1983
+ layout_data {
1984
+ horizontal_alignment :fill
1985
+ grab_excess_horizontal_space true
1986
+ }
1987
+ }
1988
+ label {text 'Name: '}
1989
+ label {
1990
+ text bind(@contact, :name, computed_by: [:first_name, :last_name])
1991
+ layout_data {
1992
+ horizontal_alignment :fill
1993
+ grab_excess_horizontal_space true
1994
+ }
1995
+ }
1996
+ label {text 'Age: '}
1997
+ label {
1998
+ text bind(@contact, :age, on_write: :to_i, computed_by: [:year_of_birth])
1999
+ layout_data {
2000
+ horizontal_alignment :fill
2001
+ grab_excess_horizontal_space true
2002
+ }
2003
+ }
2004
+ }
2005
+ }.open
2006
+ ```
2007
+
2008
+ Check out the samples directory for more advanced examples of layouts in Glimmer.
2009
+
2010
+ **Defaults**:
2011
+
2012
+ Glimmer composites always come with `grid_layout` by default, but you can still specify explicitly if you'd like to set specific properties on it.
2013
+
2014
+ Glimmer shell always comes with `fill_layout` having `:horizontal` type.
2015
+
2016
+ This is a great guide for learning more about SWT layouts:
2017
+
2018
+ https://www.eclipse.org/articles/Article-Understanding-Layouts/Understanding-Layouts.htm
2019
+
2020
+ Also, for a reference, check the SWT API:
2021
+
2022
+ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
2023
+
2024
+ ### Layout Data
2025
+
2026
+ Layouts organize widgets following common rules for all widgets directly under a composite. But, what if a specific widget needs its own rules. That's where layout data comes into play.
2027
+
2028
+ By convention, SWT layouts expect widgets to set layout data with a class matching their class name with the word "Data" replacing "Layout":
2029
+ - `GridLayout` on a composite demands `GridData` on contained widgets
2030
+ - `RowLayout` on a composite demands `RowData` on contained widgets
2031
+
2032
+ Not all layouts support layout data to further customize widget layouts. For example, `FillLayout` supports no layout data.
2033
+
2034
+ Unlike widgets and layouts in Glimmer DSL, layout data is simply specified with `layout_data` keyword nested inside a widget block body, and followed by arguments and/or a block of its own properties (lowercase underscored names).
2035
+
2036
+ Glimmer automatically deduces layout data class name by convention as per rule above, with the assumption that the layout data class lives under the same exact Java package as the layout (one can set custom layout data that breaks convention if needed in rare cases. See code below for an example)
2037
+
2038
+ Glimmer also automatically accepts symbols (e.g. `:fill`) for SWT style arguments like `SWT::FILL`.
2039
+
2040
+ Examples:
2041
+
2042
+ ```ruby
2043
+ # ...
2044
+ composite {
2045
+ row_layout :horizontal
2046
+ label {
2047
+ layout_data { # followed by properties
2048
+ width 50
2049
+ height 30
2050
+ }
2051
+ }
2052
+ # ... more widgets follow
2053
+ }
2054
+ # ...
2055
+ ```
2056
+
2057
+ ```ruby
2058
+ # ...
2059
+ composite {
2060
+ grid_layout 3, false # grid layout with 3 columns not of equal width
2061
+ label {
2062
+ # layout data followed by arguments passed to SWT GridData constructor
2063
+ layout_data :fill, :end, true, false
2064
+ }
2065
+ }
2066
+ # ...
2067
+ ```
2068
+
2069
+ ```ruby
2070
+ # ...
2071
+ composite {
2072
+ grid_layout 3, false # grid layout with 3 columns not of equal width
2073
+ label {
2074
+ # layout data set explicitly via an object (helps in rare cases that break convention)
2075
+ layout_data GridData.new(swt(:fill), swt(:end), true, false)
2076
+ }
2077
+ }
2078
+ # ...
2079
+ ```
2080
+
2081
+ If you data-bind any layout data properties, when they change, the shell containing their widget re-packs its children (calls `#pack` method automatically) to ensure proper relayout of all widgets.
2082
+
2083
+ **NOTE**: Layout data must never be reused between widgets. Always specify or clone again for every widget.
2084
+
2085
+ This is a great guide for learning more about SWT layouts:
2086
+
2087
+ https://www.eclipse.org/articles/Article-Understanding-Layouts/Understanding-Layouts.htm
2088
+
2089
+ Also, for a reference, check the SWT API:
2090
+
2091
+ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
2092
+
2093
+ ### Data-Binding
2094
+
2095
+ Data-binding is done with `bind` command following widget property to bind and taking model and bindable attribute as arguments.
2096
+
2097
+ #### General Examples
2098
+
2099
+ `text bind(contact, :first_name)`
2100
+
2101
+ This example binds the text property of a widget like `label` to the first name of a contact model.
2102
+
2103
+ `text bind(contact, 'address.street')`
2104
+
2105
+ This example binds the text property of a widget like `label` to the nested street of
2106
+ the address of a contact. This is called nested property data binding.
2107
+
2108
+ `text bind(contact, 'address.street', on_read: :upcase, on_write: :downcase)`
2109
+
2110
+ This example adds on the one above it by specifying converters on read and write of the model property, like in the case of a `text` widget. The text widget will then displays the street upper case and the model will store it lower case. When specifying converters, read and write operations must be symmetric (to avoid an infinite update loop between the widget and the model since the widget checks first if value changed before updating)
2111
+
2112
+ `text bind(contact, 'address.street', on_read: lambda { |s| s[0..10] })`
2113
+
2114
+ This example also specifies a converter on read of the model property, but via a lambda, which truncates the street to 10 characters only. Note that the read and write operations are assymetric. This is fine in the case of formatting data for a read-only widget like `label`
2115
+
2116
+ `text bind(contact, 'address.street') { |s| s[0..10] }`
2117
+
2118
+ This is a block shortcut version of the syntax above it. It facilitates formatting model data for read-only widgets since it's a very common view concern. It also saves the developer from having to create a separate formatter/presenter for the model when the view can be an active view that handles common simple formatting operations directly.
2119
+
2120
+ `text bind(contact, 'address.street', read_only: true)
2121
+
2122
+ This is read-ohly data-binding. It doesn't update contact.address.street when widget text property is changed.
2123
+
2124
+ `text bind(contact, 'addresses[1].street')`
2125
+
2126
+ This example binds the text property of a widget like `label` to the nested indexed address street of a contact. This is called nested indexed property data binding.
2127
+
2128
+ `text bind(contact, :age, computed_by: :date_of_birth)`
2129
+
2130
+ This example demonstrates computed value data binding whereby the value of `age` depends on changes to `date_of_birth`.
2131
+
2132
+ `text bind(contact, :name, computed_by: [:first_name, :last_name])`
2133
+
2134
+ This example demonstrates computed value data binding whereby the value of `name` depends on changes to both `first_name` and `last_name`.
2135
+
2136
+ `text bind(contact, 'profiles[0].name', computed_by: ['profiles[0].first_name', 'profiles[0].last_name'])`
2137
+
2138
+ This example demonstrates nested indexed computed value data binding whereby the value of `profiles[0].name` depends on changes to both nested `profiles[0].first_name` and `profiles[0].last_name`.
2139
+
2140
+ Example from [samples/hello/hello_combo.rb](samples/hello_combo.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2141
+
2142
+ #### Combo
2143
+
2144
+ The `combo` widget provides a dropdown of options. By default, it also allows typing in a new option. To disable that behavior, you may use with the `:read_only` SWT style.
2145
+
2146
+ When data-binding a `combo` widget, Glimmer can automatically deduce available options from data-bound model by convention: `{attribute_name}_options` method.
2147
+
2148
+ ![Hello Combo](images/glimmer-hello-combo.png)
2149
+
2150
+ ![Hello Combo](images/glimmer-hello-combo-expanded.png)
2151
+
2152
+ ```ruby
2153
+ class Person
2154
+ attr_accessor :country, :country_options
2155
+
2156
+ def initialize
2157
+ self.country_options=["", "Canada", "US", "Mexico"]
2158
+ self.country = "Canada"
2159
+ end
2160
+
2161
+ def reset_country
2162
+ self.country = "Canada"
2163
+ end
2164
+ end
2165
+
2166
+ class HelloCombo
2167
+ include Glimmer
2168
+ def launch
2169
+ person = Person.new
2170
+ shell {
2171
+ composite {
2172
+ combo(:read_only) {
2173
+ selection bind(person, :country)
2174
+ }
2175
+ button {
2176
+ text "Reset"
2177
+ on_widget_selected do
2178
+ person.reset_country
2179
+ end
2180
+ }
2181
+ }
2182
+ }.open
2183
+ end
2184
+ end
2185
+
2186
+ HelloCombo.new.launch
2187
+ ```
2188
+
2189
+ `combo` widget is data-bound to the country of a person. Note that it expects the `person` object to have the `:country` attribute and `:country_options` attribute containing all available countries (aka options). Glimmer reads these attributes by convention.
2190
+
2191
+ #### List
2192
+
2193
+ Example from [samples/hello/hello_list_single_selection.rb](samples/hello_list_single_selection.rb) sample:
2194
+
2195
+ ![Hello List Single Selection](images/glimmer-hello-list-single-selection.png)
2196
+
2197
+ ```ruby
2198
+ shell {
2199
+ composite {
2200
+ list {
2201
+ selection bind(person, :country)
2202
+ }
2203
+ button {
2204
+ text "Reset"
2205
+ on_widget_selected do
2206
+ person.reset_country
2207
+ end
2208
+ }
2209
+ }
2210
+ }.open
2211
+ ```
2212
+
2213
+ `list` widget is also data-bound to the country of a person similarly to the combo widget. Not much difference here (the rest of the code not shown is the same).
2214
+
2215
+ Nonetheless, in the next example, a multi-selection list is declared instead allowing data-binding of multiple selection values to the bindable attribute on the model.
2216
+
2217
+ Example from [samples/hello/hello_list_multi_selection.rb](samples/hello_list_multi_selection.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2218
+
2219
+ ![Hello List Multi Selection](images/glimmer-hello-list-multi-selection.png)
2220
+
2221
+ ```ruby
2222
+ class Person
2223
+ attr_accessor :provinces, :provinces_options
2224
+
2225
+ def initialize
2226
+ self.provinces_options=[
2227
+ "",
2228
+ "Quebec",
2229
+ "Ontario",
2230
+ "Manitoba",
2231
+ "Saskatchewan",
2232
+ "Alberta",
2233
+ "British Columbia",
2234
+ "Nova Skotia",
2235
+ "Newfoundland"
2236
+ ]
2237
+ self.provinces = ["Quebec", "Manitoba", "Alberta"]
2238
+ end
2239
+
2240
+ def reset_provinces
2241
+ self.provinces = ["Quebec", "Manitoba", "Alberta"]
2242
+ end
2243
+ end
2244
+
2245
+ class HelloListMultiSelection
2246
+ include Glimmer
2247
+ def launch
2248
+ person = Person.new
2249
+ shell {
2250
+ composite {
2251
+ list(:multi) {
2252
+ selection bind(person, :provinces)
2253
+ }
2254
+ button {
2255
+ text "Reset"
2256
+ on_widget_selected do
2257
+ person.reset_provinces
2258
+ end
2259
+ }
2260
+ }
2261
+ }.open
2262
+ end
2263
+ end
2264
+
2265
+ HelloListMultiSelection.new.launch
2266
+ ```
2267
+
2268
+ The Glimmer code is not much different from above except for passing the `:multi` style to the `list` widget. However, the model code behind the scenes is quite different as it is a `provinces` array bindable to the selection of multiple values on a `list` widget. `provinces_options` contains all available province values just as expected by a single selection `list` and `combo`.
2269
+
2270
+ Note that in all the data-binding examples above, there was also an observer attached to the `button` widget to trigger an action on the model, which in turn triggers a data-binding update on the `list` or `combo`. Observers will be discussed in more details in the [next section](#observer).
2271
+
2272
+ You may learn more about Glimmer's data-binding syntax by reading the code under the [samples](samples) directory.
2273
+
2274
+ #### Table
2275
+
2276
+ The SWT Tree widget renders a multi-column data table, such as a contact listing or a sales report.
2277
+
2278
+ To data-bind a Table, you need the main model, the collection property, and the text display attribute for each table column.
2279
+
2280
+ This involves using the `bind` keyword mentioned above in addition to a special `column_properties` keyword that takes the table column text attribute methods.
2281
+
2282
+ It assumes you have defined the table columns via `table_column` widget.
2283
+
2284
+ Example:
2285
+
2286
+ ```ruby
2287
+ shell {
2288
+ @table = table {
2289
+ table_column {
2290
+ text "Name"
2291
+ width 120
2292
+ }
2293
+ table_column {
2294
+ text "Age"
2295
+ width 120
2296
+ }
2297
+ table_column {
2298
+ text "Adult"
2299
+ width 120
2300
+ }
2301
+ items bind(group, :people), column_properties(:name, :age, :adult)
2302
+ selection bind(group, :selected_person)
2303
+ on_mouse_up { |event|
2304
+ @table.edit_table_item(event.table_item, event.column_index)
2305
+ }
2306
+ }
2307
+ }
2308
+ ```
2309
+
2310
+ The code above includes two data-bindings:
2311
+ - Table `items`, which first bind to the model collection property (group.people), and then maps each column property (name, age, adult) for displaying each table item column.
2312
+ - Table `selection`, which binds the single table item selected by the user to the attribute denoted by the `bind` keyword (or binds multiple table items selected for a table with `:multi` SWT style)
2313
+ - The `on_mouse_up` event handler invokes `@table.edit_table_item(event.table_item, event.column_index)` to start edit mode on the clicked table item cell, and then saves or cancel depending on whether the user hits ENTER or ESC once done editing (or focus-out after either making a change or not making any changes.)
2314
+
2315
+ Additionally, Table `items` data-binding automatically stores each node model unto the SWT TableItem object via `setData` method. This enables things like searchability.
2316
+
2317
+ The table widget in Glimmer is represented by a subclass of `WidgetProxy` called `TableProxy`.
2318
+ TableProxy includes a `search` method that takes a block to look for a table item.
2319
+
2320
+ Example:
2321
+
2322
+ ```ruby
2323
+ found_array = @table.search { |table_item| table_item.getData == company.owner }
2324
+ ```
2325
+
2326
+ This finds a person. The array is a Java array. This enables easy passing of it to SWT `Table#setSelection` method, which expects a Java array of `TableItem` objects.
2327
+
2328
+ To edit a table, you must invoke `TableProxy#edit_selected_table_item(column_index, before_write: nil, after_write: nil, after_cancel: nil)` or `TableProxy#edit_table_item(table_item, column_index, before_write: nil, after_write: nil, after_cancel: nil)`.
2329
+ This automatically leverages the SWT TableEditor custom class behind the scenes, displaying a text widget to the user to change the selected or
2330
+ passed table item text into something else.
2331
+ It automatically persists the change to `items` data-bound model on ENTER/FOCUS-OUT or cancels on ESC/NO-CHANGE.
2332
+
2333
+ ##### Table Sorting
2334
+
2335
+ Glimmer automatically adds sorting support to the SWT `Table` widget.
2336
+
2337
+ Check out the [Contact Manager](#contact-manager) sample for an example.
2338
+ You may click on any column and it will sort by ascending order first and descending if you click again.
2339
+
2340
+ Glimmer automatic table sorting supports `String`, `Integer`, and `Float` columns out of the box as well as any column data that is comparable.
2341
+
2342
+ In cases where data is nil, depending on the data-type, it is automatically converted to `Float` with `to_f`, `Integer` with `to_i`, or `String` with `to_s`.
2343
+
2344
+ Should you have a special data type that could not be compared automatically, Glimmer offers the following 3 alternatives for custom sorting:
2345
+ - `sort_property`: this may be set to an alternative property to the one data-bound to the table column. For example, a table column called 'adult', which returns `true` or `false` may be sorted with `sort_property :dob` instead. This also support multi-property (aka multi-column) sorting (e.g. `sort_property :dob, :name`).
2346
+ - `sort_by(&block)`: this works just like Ruby `Enumerable` `sort_by`. The block receives the table column data as argument.
2347
+ - `sort(&comparator)`: this works just like Ruby `Enumerable` `sort`. The comparator block receives two objects from the table column data.
2348
+
2349
+ You may also set `additional_sort_properties` on the parent `table` widget to have secondary sorting applied. For example, if you set `additional_sort_properties :name, :project_name`, then whenever you sort by `:name`, it additionally sorts by `:project_name` afterwards, and vice versa. This only works for columns that either have no custom sort set or have a `sort_property` with one property only (but no sort or sort_by block)
2350
+
2351
+ Example:
2352
+
2353
+ ```ruby
2354
+ # ...
2355
+ table {
2356
+ table_column {
2357
+ text 'Task'
2358
+ width 120
2359
+ }
2360
+ table_column {
2361
+ text 'Project'
2362
+ width 120
2363
+ }
2364
+ table_column {
2365
+ text 'Duration (hours)'
2366
+ width 120
2367
+ sort_property :duration_in_hours
2368
+ }
2369
+ table_column {
2370
+ text 'Priority'
2371
+ width 120
2372
+ sort_by { |value| ['High', 'Medium', 'Low'].index(value) }
2373
+ }
2374
+ table_column {
2375
+ text 'Start Date'
2376
+ width 120
2377
+ sort { |d1, d2| d1.to_date <=> d2.to_date }
2378
+ }
2379
+ additional_sort_properties :project_name, :duration_in_hours, :name
2380
+ items bind(Task, :list), column_properties(:name, :project_name, :duration, :priority, :start_date)
2381
+ # ...
2382
+ }
2383
+ # ...
2384
+ ```
2385
+
2386
+ Here is an explanation of the example above:
2387
+ - Task and Project table columns are data-bound to the `:name` and `:project_name` properties and sorted through them automatically
2388
+ - Task Duration table column is data-bound to the `:duration` property, but sorted via the `:duration_in_hours` property instead
2389
+ - Task Priority table column has a custom sort_by block
2390
+ - Task Start Date table column has a custom sort comparator block
2391
+ - Additional (secondary) sort properties are applied when sorting by Task, Project, or Duration in the order specified
2392
+
2393
+
2394
+ #### Tree
2395
+
2396
+ The SWT Tree widget visualizes a tree data-structure, such as an employment or composition hierarchy.
2397
+
2398
+ To data-bind a Tree, you need the root model, the children querying method, and the text display attribute on each child.
2399
+
2400
+ This involves using the `bind` keyword mentioned above in addition to a special `tree_properties` keyword that takes the children and text attribute methods.
2401
+
2402
+ Example:
2403
+
2404
+ ```ruby
2405
+ shell {
2406
+ @tree = tree {
2407
+ items bind(company, :owner), tree_properties(children: :coworkers, text: :name)
2408
+ selection bind(company, :selected_coworker)
2409
+ }
2410
+ }
2411
+ ```
2412
+
2413
+ The code above includes two data-bindings:
2414
+ - Tree `items`, which first bind to the root node (company.owner), and then dig down via `coworkers` `children` method, using the `name` `text` attribute for displaying each tree item.
2415
+ - Tree `selection`, which binds the single tree item selected by the user to the attribute denoted by the `bind` keyword
2416
+
2417
+ Additionally, Tree `items` data-binding automatically stores each node model unto the SWT TreeItem object via `setData` method. This enables things like searchability.
2418
+
2419
+ The tree widget in Glimmer is represented by a subclass of `WidgetProxy` called `TreeProxy`.
2420
+ TreeProxy includes a `depth_first_search` method that takes a block to look for a tree item.
2421
+
2422
+ Example:
2423
+
2424
+ ```ruby
2425
+ found_array = @tree.depth_first_search { |tree_item| tree_item.getData == company.owner }
2426
+ ```
2427
+
2428
+ This finds the root node. The array is a Java array. This enables easy passing of it to SWT `Tree#setSelection` method, which expects a Java array of `TreeItem` objects.
2429
+
2430
+ To edit a tree, you must invoke `TreeProxy#edit_selected_tree_item` or `TreeProxy#edit_tree_item`. This automatically leverages the SWT TreeEditor custom class behind the scenes, displaying
2431
+ a text widget to the user to change the selected or passed tree item text into something else. It automatically persists the change to `items` data-bound model on ENTER/FOCUS-OUT or cancels on ESC/NO-CHANGE.
2432
+
2433
+ ### Observer
2434
+
2435
+ Glimmer comes with `Observer` module, which is used internally for data-binding, but can also be used externally for custom use of the Observer Pattern. It is hidden when observing widgets, and used explicitly when observing models.
2436
+
2437
+ #### Observing Widgets
2438
+
2439
+ Glimmer supports observing widgets with two main types of events:
2440
+ 1. `on_{swt-listener-method-name}`: where {swt-listener-method-name} is replaced with the lowercase underscored event method name on an SWT listener class (e.g. `on_verify_text` for `org.eclipse.swt.events.VerifyListener#verifyText`).
2441
+ 2. `on_swt_{swt-event-constant}`: where {swt-event-constant} is replaced with an [`org.eclipse.swt.SWT`](https://help.eclipse.org/2020-06/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html) event constant (e.g. `on_swt_show` for `SWT.Show` to observe when widget becomes visible)
2442
+
2443
+ Additionally, there are two more types of events:
2444
+ - SWT `display` supports global listeners called filters that run on any widget. They are hooked via `on_swt_{swt-event-constant}`
2445
+ - SWT `display` supports Mac application menu item observers (`on_about` and `on_preferences`), which you can read about under [Miscellaneous](#miscellaneous).
2446
+
2447
+ Number 1 is more commonly used in SWT applications, so make it your starting point. Number 2 covers events not found in number 1, so look into it if you don't find an SWT listener you need in number 1.
2448
+
2449
+ **Regarding number 1**, to figure out what the available events for an SWT widget are, check out all of its `add***Listener` API methods, and then open the listener class argument to check its "event methods".
2450
+
2451
+ For example, if you look at the `Button` SWT API:
2452
+ https://help.eclipse.org/2019-12/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fswt%2Fbrowser%2FBrowser.html
2453
+
2454
+ It has `addSelectionListener`. Additionally, under its `Control` super class, it has `addControlListener`, `addDragDetectListener`, `addFocusListener`, `addGestureListener`, `addHelpListener`, `addKeyListener`, `addMenuDetectListener`, `addMouseListener`, `addMouseMoveListener`, `addMouseTrackListener`, `addMouseWheelListener`, `addPaintListener`, `addTouchListener`, and `addTraverseListener`
2455
+
2456
+ Suppose, we select `addSelectionListener`, which is responsible for what happens when a user selects a button (clicks it). Then, open its argument `SelectionListener` SWT API, and you find the event (instance) methods: `widgetDefaultSelected` and `widgetSelected​`. Let's select the second one, which is what gets invoked when a button is clicked.
2457
+
2458
+ Now, Glimmer simplifies the process of hooking into that listener (observer) by neither requiring you to call the `addSelectionListener` method nor requiring you to implement/extend the `SelectionListener` API.
2459
+
2460
+ Instead, simply add a `on_widget_selected` followed by a Ruby block containing the logic to perform. Glimmer figures out the rest.
2461
+
2462
+ Let's revisit the Tic Tac Toe example shown near the beginning of the page:
2463
+
2464
+ ```ruby
2465
+ shell {
2466
+ text "Tic-Tac-Toe"
2467
+ minimum_size 150, 178
2468
+ composite {
2469
+ grid_layout 3, true
2470
+ (1..3).each { |row|
2471
+ (1..3).each { |column|
2472
+ button {
2473
+ layout_data :fill, :fill, true, true
2474
+ text bind(@tic_tac_toe_board[row, column], :sign)
2475
+ enabled bind(@tic_tac_toe_board[row, column], :empty)
2476
+ on_widget_selected {
2477
+ @tic_tac_toe_board.mark(row, column)
2478
+ }
2479
+ }
2480
+ }
2481
+ }
2482
+ }
2483
+ }
2484
+ ```
2485
+
2486
+ Note that every Tic Tac Toe grid cell has its `text` and `enabled` properties data-bound to the `sign` and `empty` attributes on the `TicTacToe::Board` model respectively.
2487
+
2488
+ Next however, each of these Tic Tac Toe grid cells, which are clickable buttons, have an `on_widget_selected` observer, which once triggered, marks the cell on the `TicTacToe::Board` to make a move.
2489
+
2490
+ **Regarding number 2**, you can figure out all available events by looking at the [`org.eclipse.swt.SWT`](https://help.eclipse.org/2020-06/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html) API:
2491
+
2492
+ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
2493
+
2494
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2495
+
2496
+ `SWT.Show` - hooks a listener for showing a widget (using `on_swt_show` in Glimmer)
2497
+ `SWT.Hide` - hooks a listener for hiding a widget (using `on_swt_hide` in Glimmer)
2498
+
2499
+ ```ruby
2500
+ shell {
2501
+ @button1 = button {
2502
+ text "Show 2nd Button"
2503
+ visible true
2504
+ on_swt_show {
2505
+ @button2.swt_widget.setVisible(false)
2506
+ }
2507
+ on_widget_selected {
2508
+ @button2.swt_widget.setVisible(true)
2509
+ }
2510
+ }
2511
+ @button2 = button {
2512
+ text "Show 1st Button"
2513
+ visible false
2514
+ on_swt_show {
2515
+ @button1.swt_widget.setVisible(false)
2516
+ }
2517
+ on_widget_selected {
2518
+ @button1.swt_widget.setVisible(true)
2519
+ }
2520
+ }
2521
+ }.open
2522
+ ```
2523
+
2524
+ **Gotcha:** SWT.Resize event needs to be hooked using **`on_swt_Resize`** because [`org.eclipse.swt.SWT`](https://help.eclipse.org/2020-06/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html) has 2 constants for resize: `RESIZE` and `Resize`, so it cannot infer the right one automatically from the underscored version `on_swt_resize`
2525
+
2526
+ ##### Alternative Syntax
2527
+
2528
+ Instead of declaring a widget observer using `on_***` syntax inside a widget content block, you may also do so after the widget declaration by invoking directly on the widget object.
2529
+
2530
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2531
+
2532
+ ```
2533
+ @shell = shell {
2534
+ label {
2535
+ text "Hello, World!"
2536
+ }
2537
+ }
2538
+ @shell.on_shell_iconified {
2539
+ @shell.close
2540
+ }
2541
+ @shell.open
2542
+ ```
2543
+
2544
+ The shell declared above has been modified so that the minimize button works just like the close button. Once you minimize the shell (iconify it), it closes.
2545
+
2546
+ The alternative syntax can be helpful if you prefer to separate Glimmer observer declarations from Glimmer GUI declarations, or would like to add observers dynamically based on some logic later on.
2547
+
2548
+ #### Observing Models
2549
+
2550
+ Glimmer DSL includes an `observe` keyword used to register an observer by passing in the observable and the property(ies) to observe, and then specifying in a block what happens on notification.
2551
+
2552
+ ```ruby
2553
+ class TicTacToe
2554
+ include Glimmer
2555
+
2556
+ def initialize
2557
+ # ...
2558
+ observe(@tic_tac_toe_board, :game_status) { |game_status|
2559
+ display_win_message if game_status == Board::WIN
2560
+ display_draw_message if game_status == Board::DRAW
2561
+ }
2562
+ end
2563
+ # ...
2564
+ end
2565
+ ```
2566
+
2567
+ Observers can be a good mechanism for displaying dialog messages in Glimmer (using SWT's [`MessageBox`](https://help.eclipse.org/2020-06/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/widgets/MessageBox.html) class).
2568
+
2569
+ Look at [`samples/elaborate/tictactoe/tic_tac_toe.rb`](samples/tictactoe/tic_tac_toe.rb) for more details starting with the code included below.
2570
+
2571
+ ```ruby
2572
+ class TicTacToe
2573
+ include Glimmer
2574
+ include Observer
2575
+
2576
+ def initialize
2577
+ # ...
2578
+ observe(@tic_tac_toe_board, :game_status) { |game_status|
2579
+ display_win_message if game_status == Board::WIN
2580
+ display_draw_message if game_status == Board::DRAW
2581
+ }
2582
+ end
2583
+
2584
+ def display_win_message
2585
+ display_game_over_message("Player #{@tic_tac_toe_board.winning_sign} has won!")
2586
+ end
2587
+
2588
+ def display_draw_message
2589
+ display_game_over_message("Draw!")
2590
+ end
2591
+
2592
+ def display_game_over_message(message)
2593
+ message_box(@shell) {
2594
+ text 'Game Over'
2595
+ message message_text
2596
+ }.open
2597
+ @tic_tac_toe_board.reset
2598
+ end
2599
+ # ...
2600
+ end
2601
+ ```
2602
+
2603
+ ### Custom Widgets
2604
+
2605
+ Glimmer supports creating custom widgets with minimal code, which automatically extends Glimmer's DSL syntax with an underscored lowercase keyword.
2606
+
2607
+ Simply create a new class that includes `Glimmer::UI::CustomWidget` and put Glimmer DSL code in its `#body` block (its return value is stored in `#body_root` attribute). Glimmer will then automatically recognize this class by convention when it encounters a keyword matching the class name converted to underscored lowercase (and namespace double-colons `::` replaced with double-underscores `__`)
2608
+
2609
+ #### Simple Example
2610
+
2611
+ (you may copy/paste in [`girb`](#girb-glimmer-irb-command))
2612
+
2613
+ Definition:
2614
+ ```ruby
2615
+ class RedLabel
2616
+ include Glimmer::UI::CustomWidget
2617
+
2618
+ body {
2619
+ label(swt_style) {
2620
+ background :red
2621
+ }
2622
+ }
2623
+ end
2624
+ ```
2625
+
2626
+ Usage:
2627
+ ```ruby
2628
+ shell {
2629
+ red_label {
2630
+ text 'Red Label'
2631
+ }
2632
+ }.open
2633
+ ```
2634
+
2635
+ As you can see, `RedLabel` became Glimmer DSL keyword: `red_label`
2636
+
2637
+ #### Lifecycle Hook Example
2638
+
2639
+ (you may copy/paste in [`girb`](#girb-glimmer-irb-command))
2640
+
2641
+ Definition:
2642
+ ```ruby
2643
+ module Red
2644
+ class Composite
2645
+ include Glimmer::UI::CustomWidget
2646
+
2647
+ before_body {
2648
+ @color = :red
2649
+ }
2650
+
2651
+ body {
2652
+ composite(swt_style) {
2653
+ background @color
2654
+ }
2655
+ }
2656
+ end
2657
+ end
2658
+ ```
2659
+
2660
+ Usage:
2661
+ ```ruby
2662
+ shell {
2663
+ red__composite {
2664
+ label {
2665
+ foreground :white
2666
+ text 'This is showing inside a Red Composite'
2667
+ }
2668
+ }
2669
+ }.open
2670
+ ```
2671
+
2672
+ Notice how `Red::Composite` became `red__composite` with double-underscore, which is how Glimmer Custom Widgets signify namespaces by convention. Additionally, the `before_body` lifecycle hook was utilized to set a `@color` variable and use inside the `body`.
2673
+
2674
+ Keep in mind that namespaces are not needed to be specified if the Custom Widget class has a unique name, not clashing with a basic SWT widget or another custom widget name.
2675
+
2676
+ #### Custom Widget API
2677
+
2678
+ Custom Widgets have the following attributes available to call from inside the `#body` method:
2679
+ - `#parent`: Glimmer object parenting custom widget
2680
+ - `#swt_style`: SWT style integer. Can be useful if you want to allow consumers to customize a widget inside the custom widget body
2681
+ - `#options`: a hash of options passed in parentheses when declaring a custom widget (useful for passing in model data) (e.g. `calendar(events: events)`). Custom widget class can declare option names (array) with `::options` class method as shown below, which generates attribute accessors for every option (not to be confused with `#options` instance method for retrieving options hash containing names & values)
2682
+ - `#content`: nested block underneath custom widget. It will be automatically called at the end of processing the custom widget body. Alternatively, the custom widget body may call `content.call` at the place where the content is needed to show up as shown in the following example.
2683
+ - `#body_root`: top-most (root) widget returned from `#body` method.
2684
+ - `#swt_widget`: actual SWT widget for `body_root`
2685
+
2686
+ Additionally, custom widgets can call the following class methods:
2687
+ - `::options(*option_names)`: declares a list of options by taking an option name array (symbols/strings). This generates option attribute accessors (e.g. `options :orientation, :bg_color` generates `#orientation`, `#orientation=(v)`, `#bg_color`, and `#bg_color=(v)` attribute accessors)
2688
+ - `::option(option_name, default: nil)`: declares a single option taking option name and default value as arguments (also generates attribute accessors just like `::options`)
2689
+
2690
+ #### Content/Options Example
2691
+
2692
+ (you may copy/paste in [`girb`](#girb-glimmer-irb-command))
2693
+
2694
+ Definition:
2695
+ ```ruby
2696
+ class Sandwich
2697
+ include Glimmer::UI::CustomWidget
2698
+
2699
+ options :orientation, :bg_color
2700
+ option :fg_color, default: :black
2701
+
2702
+ body {
2703
+ composite(swt_style) { # gets custom widget style
2704
+ fill_layout orientation # using orientation option
2705
+ background bg_color # using container_background option
2706
+ label {
2707
+ text 'SANDWICH TOP'
2708
+ }
2709
+ content.call # this is where content block is called
2710
+ label {
2711
+ text 'SANDWICH BOTTOM'
2712
+ }
2713
+ }
2714
+ }
2715
+ end
2716
+ ```
2717
+
2718
+ Usage:
2719
+ ```ruby
2720
+ shell {
2721
+ sandwich(:no_focus, orientation: :vertical, bg_color: :red) {
2722
+ label {
2723
+ background :green
2724
+ text 'SANDWICH CONTENT'
2725
+ }
2726
+ }
2727
+ }.open
2728
+ ```
2729
+
2730
+ Notice how `:no_focus` was the `swt_style` value, followed by the `options` hash `{orientation: :horizontal, bg_color: :white}`, and finally the `content` block containing the label with `'SANDWICH CONTENT'`
2731
+
2732
+ #### Custom Widget Lifecycle Hooks
2733
+
2734
+ Last but not least, these are the available lifecycle hooks:
2735
+ - `before_body`: takes a block that executes in the custom widget instance scope before calling `body`. Useful for initializing variables to later use in `body`
2736
+ - `after_body`: takes a block that executes in the custom widget instance scope after calling `body`. Useful for setting up observers on widgets built in `body` (set in instance variables) and linking to other shells.
2737
+
2738
+ #### Gotcha
2739
+
2740
+ Beware of defining a custom attribute that is a common SWT widget property name.
2741
+ For example, if you define `text=` and `text` methods to accept a custom text and then later you write this body:
2742
+
2743
+ ```ruby
2744
+ # ...
2745
+ def text
2746
+ # ...
2747
+ end
2748
+
2749
+ def text=(value)
2750
+ # ...
2751
+ end
2752
+
2753
+ body {
2754
+ composite {
2755
+ label {
2756
+ text "Hello"
2757
+ }
2758
+ label {
2759
+ text "World"
2760
+ }
2761
+ }
2762
+ }
2763
+ # ...
2764
+ ```
2765
+
2766
+ The `text` method invoked in the custom widget body will call the one you defined above it. To avoid this gotcha, simply name the text property above something else, like `custom_text`.
2767
+
2768
+ #### Final Notes
2769
+
2770
+ This [Eclipse guide](https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm) for how to write custom SWT widgets is also applicable to Glimmer Custom Widgets written in Ruby. I recommend reading it:
2771
+ [https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm](https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm)
2772
+
2773
+ ### Custom Shells
2774
+
2775
+ Custom shells are a kind of custom widgets that have shells only as the body root. They can be self-contained applications that may be opened and hidden/closed independently of the main app.
2776
+
2777
+ They may also be chained in a wizard fashion.
2778
+
2779
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2780
+
2781
+ ```ruby
2782
+ class WizardStep
2783
+ include Glimmer::UI::CustomShell
2784
+
2785
+ options :number, :step_count
2786
+
2787
+ before_body {
2788
+ @title = "Step #{number}"
2789
+ }
2790
+
2791
+ body {
2792
+ shell {
2793
+ text "Wizard - #{@title}"
2794
+ minimum_size 200, 100
2795
+ fill_layout :vertical
2796
+ label(:center) {
2797
+ text @title
2798
+ font height: 30
2799
+ }
2800
+ if number < step_count
2801
+ button {
2802
+ text "Go To Next Step"
2803
+ on_widget_selected {
2804
+ body_root.hide
2805
+ }
2806
+ }
2807
+ end
2808
+ }
2809
+ }
2810
+ end
2811
+
2812
+ shell { |app_shell|
2813
+ text "Wizard"
2814
+ minimum_size 200, 100
2815
+ @current_step_number = 1
2816
+ @wizard_steps = 5.times.map { |n|
2817
+ wizard_step(number: n+1, step_count: 5) {
2818
+ on_swt_hide {
2819
+ if @current_step_number < 5
2820
+ @current_step_number += 1
2821
+ app_shell.hide
2822
+ @wizard_steps[@current_step_number - 1].open
2823
+ end
2824
+ }
2825
+ }
2826
+ }
2827
+ button {
2828
+ text "Start"
2829
+ font height: 40
2830
+ on_widget_selected {
2831
+ app_shell.hide
2832
+ @wizard_steps[@current_step_number - 1].open
2833
+ }
2834
+ }
2835
+ }.open
2836
+ ```
2837
+
2838
+ ### Drag and Drop
2839
+
2840
+ Glimmer offers Drag and Drop support, thanks to [SWT](https://www.eclipse.org/swt/) and Glimmer's lightweight [DSL syntax](#glimmer-dsl-syntax).
2841
+
2842
+ You may learn more about SWT Drag and Drop support over here: [https://www.eclipse.org/articles/Article-SWT-DND/DND-in-SWT.html](https://www.eclipse.org/articles/Article-SWT-DND/DND-in-SWT.html)
2843
+
2844
+ To get started, simply follow these steps:
2845
+ 1. On the drag source widget, add `on_drag_set_data` [DragSourceListener](https://help.eclipse.org/2020-03/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/dnd/DragSourceListener.html) event handler block at minimum (you may also add `on_drag_start` and `on_drag_finished` if needed)
2846
+ 1. Set `event.data` to transfer via drag and drop inside the `on_drag_set_data` event handler block (defaults to `transfer` type of `:text`, as in a Ruby String)
2847
+ 1. On the drop target widget, add `on_drop` [DropTargetListener](https://help.eclipse.org/2020-03/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/dnd/DropTargetListener.html) event handler block at minimum (you may also add `on_drag_enter` [must set [`event.detail`](https://help.eclipse.org/2020-06/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/dnd/DropTargetEvent.html#detail) if added], `on_drag_over`, `on_drag_leave`, `on_drag_operation_changed` and `on_drop_accept` if needed)
2848
+ 1. Read `event.data` and consume it (e.g. change widget text) inside the `on_drop` event handler block.
2849
+
2850
+ Example (taken from [samples/hello/hello_drag_and_drop.rb](#hello-drag-and-drop) / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2851
+
2852
+ ```ruby
2853
+ class Location
2854
+ attr_accessor :country
2855
+
2856
+ def country_options
2857
+ %w[USA Canada Mexico Columbia UK Australia Germany Italy Spain]
2858
+ end
2859
+ end
2860
+
2861
+ @location = Location.new
2862
+
2863
+ include Glimmer
2864
+
2865
+ shell {
2866
+ text 'Hello, Drag and Drop!'
2867
+ list {
2868
+ selection bind(@location, :country)
2869
+ on_drag_set_data { |event|
2870
+ list = event.widget.getControl
2871
+ event.data = list.getSelection.first
2872
+ }
2873
+ }
2874
+ label(:center) {
2875
+ text 'Drag a country here!'
2876
+ font height: 20
2877
+ on_drop { |event|
2878
+ event.widget.getControl.setText(event.data)
2879
+ }
2880
+ }
2881
+ }.open
2882
+ ```
2883
+
2884
+ ![Hello Drag and Drop](images/glimmer-hello-drag-and-drop.gif)
2885
+
2886
+ Optional steps:
2887
+ - Set a `transfer` property (defaults to `:text`). Values may be: :text (default), :html :image, :rtf, :url, and :file, or an array of multiple values. The `transfer` property will automatically convert your option into a [Transfer](https://help.eclipse.org/2020-03/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/dnd/Transfer.html) object as per the SWT API.
2888
+ - Specify `drag_source_style` operation (may be: :drop_copy (default), :drop_link, :drop_move, :drop_none, or an array of multiple operations)
2889
+ - Specify `drag_source_effect` (Check [DragSourceEffect](https://help.eclipse.org/2020-06/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/dnd/DragSourceEffect.html) SWT API for details)
2890
+ - Specify `drop_target_style` operation (may be: :drop_copy (default), :drop_link, :drop_move, :drop_none, or an array of multiple operations)
2891
+ - Specify `drop_target_effect` (Check [DropTargetEffect](https://help.eclipse.org/2020-06/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/dnd/DropTargetEffect.html) SWT API for details)
2892
+ - Set drag operation in `event.detail` (e.g. DND::DROP_COPY) inside `on_drag_enter`
2893
+
2894
+ ### Miscellaneous
2895
+
2896
+ #### Multi-DSL Support
2897
+
2898
+ Glimmer is a DSL engine that supports multiple DSLs (Domain Specific Languages):
2899
+ - [SWT](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
2900
+ - [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
2901
+ - [XML](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML) - Useful with [SWT Browser Widget](#browser-widget)
2902
+ - [CSS](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets) - Useful with [SWT Browser Widget](#browser-widget)
2903
+
2904
+ Glimmer automatically recognizes top-level keywords in each DSL and activates DSL accordingly. Glimmer allows mixing DSLs, which comes in handy when doing things like using the SWT Browser widget with XML and CSS. Once done processing a nested DSL top-level keyword, Glimmer switches back to the prior DSL automatically.
2905
+
2906
+ ##### SWT
2907
+
2908
+ The SWT DSL was already covered in detail. However, for the sake of mixing DSLs, you need to know that the SWT DSL has the following top-level keywords:
2909
+ - `shell`
2910
+ - `display`
2911
+ - `color`
2912
+ - `observe`
2913
+ - `async_exec`
2914
+ - `sync_exec`
2915
+
2916
+ ##### Opal
2917
+
2918
+ Full instructions are found in the [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal) DSL page.
2919
+
2920
+ The [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal) DSL is simply a web GUI adapter for desktop apps written in Glimmer. As such, it supports all the DSL keywords of the SWT DSL and shares the same top-level keywords.
2921
+
2922
+ ##### XML
2923
+
2924
+ Simply start with `html` keyword and add HTML inside its block using Glimmer DSL syntax.
2925
+ Once done, you may call `to_s`, `to_xml`, or `to_html` to get the formatted HTML output.
2926
+
2927
+ Here are all the Glimmer XML DSL top-level keywords:
2928
+ - `html`
2929
+ - `tag`: enables custom tag creation for exceptional cases by passing tag name as '_name' attribute
2930
+ - `name_space`: enables namespacing html tags
2931
+
2932
+ Element properties are typically passed as a key/value hash (e.g. `section(id: 'main', class: 'accordion')`) . However, for properties like "selected" or "checked", you must leave value `nil` or otherwise pass in front of the hash (e.g. `input(:checked, type: 'checkbox')` )
2933
+
2934
+ Example (basic HTML / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2935
+
2936
+ ```ruby
2937
+ @xml = html {
2938
+ head {
2939
+ meta(name: "viewport", content: "width=device-width, initial-scale=2.0")
2940
+ }
2941
+ body {
2942
+ h1 { "Hello, World!" }
2943
+ }
2944
+ }
2945
+ puts @xml
2946
+ ```
2947
+
2948
+ Output:
2949
+
2950
+ ```
2951
+ <html><head><meta name="viewport" content="width=device-width, initial-scale=2.0" /></head><body><h1>Hello, World!</h1></body></html>
2952
+ ```
2953
+
2954
+ Example (explicit XML tag / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2955
+
2956
+ ```ruby
2957
+ puts tag(:_name => "DOCUMENT")
2958
+ ```
2959
+
2960
+ Output:
2961
+
2962
+ ```
2963
+ <DOCUMENT/>
2964
+ ```
2965
+
2966
+ Example (XML namespaces using `name_space` keyword / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2967
+
2968
+ ```ruby
2969
+ @xml = name_space(:w3c) {
2970
+ html(:id => "thesis", :class => "document") {
2971
+ body(:id => "main") {
2972
+ }
2973
+ }
2974
+ }
2975
+ puts @xml
2976
+ ```
2977
+
2978
+ Output:
2979
+
2980
+ ```
2981
+ <w3c:html id="thesis" class="document"><w3c:body id="main"></w3c:body></w3c:html>
2982
+ ```
2983
+
2984
+ Example (XML namespaces using dot operator / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2985
+
2986
+ ```ruby
2987
+ @xml = tag(:_name => "DOCUMENT") {
2988
+ document.body(document.id => "main") {
2989
+ }
2990
+ }
2991
+ puts @xml
2992
+ ```
2993
+
2994
+ Output:
2995
+
2996
+ ```
2997
+ <DOCUMENT><document:body document:id="main"></document:body></DOCUMENT>
2998
+ ```
2999
+
3000
+ ##### CSS
3001
+
3002
+ Simply start with `css` keyword and add stylesheet rule sets inside its block using Glimmer DSL syntax.
3003
+ Once done, you may call `to_s` or `to_css` to get the formatted CSS output.
3004
+
3005
+ `css` is the only top-level keyword in the Glimmer CSS DSL
3006
+
3007
+ Selectors may be specified by `s` keyword or HTML element keyword directly (e.g. `body`)
3008
+ Rule property values may be specified by `pv` keyword or underscored property name directly (e.g. `font_size`)
3009
+
3010
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
3011
+
3012
+ ```ruby
3013
+ @css = css {
3014
+ body {
3015
+ font_size '1.1em'
3016
+ pv 'background', 'white'
3017
+ }
3018
+
3019
+ s('body > h1') {
3020
+ background_color :red
3021
+ pv 'font-size', '2em'
3022
+ }
3023
+ }
3024
+ puts @css
3025
+ ```
3026
+
3027
+ ##### Listing / Enabling / Disabling DSLs
3028
+
3029
+ Glimmer provides a number of methods on Glimmer::DSL::Engine to configure DSL support or inquire about it:
3030
+ - `Glimmer::DSL::Engine.dsls`: Lists available Glimmer DSLs
3031
+ - `Glimmer::DSL::Engine.disable_dsl(dsl_name)`: Disables a specific DSL. Useful when there is no need for certain DSLs in a certain application.
3032
+ - `Glimmer::DSL::Engine.disabled_dsls': Lists disabled DSLs
3033
+ - `Glimmer::DSL::Engine.enable_dsl(dsl_name)`: Re-enables disabled DSL
3034
+ - `Glimmer::DSL::Engine.enabled_dsls=(dsl_names)`: Disables all DSLs except the ones specified.
3035
+
3036
+ #### Application Menu Items (About/Preferences)
3037
+
3038
+ Mac applications always have About and Preferences menu items. Glimmer provides widget observer hooks for them on the `display`:
3039
+ - `on_about`: executes code when user selects App Name -> About
3040
+ - `on_preferences`: executes code when user selects App Name -> Preferences or hits 'CMD+,' on the Mac
3041
+
3042
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
3043
+
3044
+ ```ruby
3045
+ class Example
3046
+ def initialize
3047
+ display {
3048
+ on_about {
3049
+ message_box(@shell_proxy) {
3050
+ text 'About'
3051
+ message 'About Application'
3052
+ }.open
3053
+ }
3054
+ on_preferences {
3055
+ preferences_dialog = dialog {
3056
+ text 'Preferences'
3057
+ row_layout {
3058
+ type :vertical
3059
+ margin_left 15
3060
+ margin_top 15
3061
+ margin_right 15
3062
+ margin_bottom 15
3063
+ }
3064
+ label {
3065
+ text 'Check one of these options:'
3066
+ }
3067
+ button(:radio) {
3068
+ text 'Option 1'
3069
+ }
3070
+ button(:radio) {
3071
+ text 'Option 2'
3072
+ }
3073
+ }
3074
+ preferences_dialog.open
3075
+ }
3076
+ }
3077
+ @shell_proxy = shell {
3078
+ text 'Application Menu Items'
3079
+ fill_layout {
3080
+ margin_width 15
3081
+ margin_height 15
3082
+ }
3083
+ label {
3084
+ text 'Application Menu Items'
3085
+ font height: 30
3086
+ }
3087
+ }
3088
+ @shell_proxy.open
3089
+ end
3090
+ end
3091
+
3092
+ Example.new
3093
+ ```
3094
+
3095
+ #### App Name and Version
3096
+
3097
+ Application name (shows up on the Mac in top menu bar) and version may be specified upon [packaging](#packaging--distribution) by specifying "-Bmac.CFBundleName" and "-Bmac.CFBundleVersion" options.
3098
+
3099
+ Still, if you would like proper application name to show up on the Mac top menu bar during development, you may do so by invoking the SWT Display.setAppName method before any Display object has been instantiated (i.e. before any Glimmer widget like shell has been declared).
3100
+
3101
+ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
3102
+
3103
+ ```ruby
3104
+ Display.setAppName('Glimmer Demo')
3105
+
3106
+ shell(:no_resize) {
3107
+ text "Glimmer"
3108
+ label {
3109
+ text "Hello, World!"
3110
+ }
3111
+ }.open
3112
+ ```
3113
+
3114
+ Also, you may invoke `Display.setAppVersion('1.0.0')` if needed for OS app version identification reasons during development, replacing `'1.0.0'` with your application version.
3115
+
3116
+ #### Video Widget
3117
+
3118
+ [![Video Widget](images/glimmer-video-widget.png)](https://github.com/AndyObtiva/glimmer-cw-video)
3119
+
3120
+ Glimmer supports a [video custom widget](https://github.com/AndyObtiva/glimmer-cw-video) not in SWT.
3121
+
3122
+ You may obtain via `glimmer-cw-video` gem.
3123
+
3124
+ #### Browser Widget
3125
+
3126
+ ![Hello Browser](images/glimmer-hello-browser.png)
3127
+
3128
+ Glimmer supports the SWT Browser widget, which can load URLs or render HTML. It can even be instrumented with JavaScript when needed (though highly discouraged since it defeats the purpose of using Ruby except in very rare cases like leveraging a pre-existing web codebase in a desktop app).
3129
+
3130
+ Example loading a URL (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
3131
+
3132
+ ```ruby
3133
+ shell {
3134
+ minimum_size 1024, 860
3135
+ browser {
3136
+ url 'http://brightonresort.com/about'
3137
+ }
3138
+ }.open
3139
+ ```
3140
+
3141
+ Example rendering HTML with JavaScript on document ready (you may copy/paste in [`girb`](#girb-glimmer-irb-command) provided you install and require [glimmer-dsl-xml gem](https://github.com/AndyObtiva/glimmer-dsl-xml)):
3142
+
3143
+ ```ruby
3144
+ shell {
3145
+ minimum_size 130, 130
3146
+ @browser = browser {
3147
+ text html {
3148
+ head {
3149
+ meta(name: "viewport", content: "width=device-width, initial-scale=2.0")
3150
+ }
3151
+ body {
3152
+ h1 { "Hello, World!" }
3153
+ }
3154
+ }
3155
+ on_completed { # on load of the page execute this JavaScript
3156
+ @browser.swt_widget.execute("alert('Hello, World!');")
3157
+ }
3158
+ }
3159
+ }.open
3160
+ ```
3161
+
3162
+ This relies on Glimmer's [Multi-DSL Support](#multi-dsl-support) for building the HTML text using [Glimmer XML DSL](https://github.com/AndyObtiva/glimmer-dsl-xml).
3163
+
3164
+ ## Glimmer Configuration
3165
+
3166
+ Glimmer configuration may be done via the `Glimmer::Config` module.
3167
+
3168
+ ### logger
3169
+
3170
+ The Glimmer DSL engine supports logging via a standard `STDOUT` Ruby `Logger` configured in the `Glimmer::Config.logger` config option.
3171
+ It is set to level Logger::ERROR by default.
3172
+ Log level may be adjusted via `Glimmer::Config.logger.level` just like any other Ruby Logger.
3173
+
3174
+ Example:
3175
+
3176
+ ```ruby
3177
+ Glimmer::Config.logger.level = :debug
3178
+ ```
3179
+ This results in more verbose debug loggging to `STDOUT`, which is very helpful in troubleshooting Glimmer DSL syntax when needed.
3180
+
3181
+ Example log:
3182
+ ```
3183
+ D, [2017-07-21T19:23:12.587870 #35707] DEBUG -- : method: shell and args: []
3184
+ D, [2017-07-21T19:23:12.594405 #35707] DEBUG -- : ShellCommandHandler will handle command: shell with arguments []
3185
+ D, [2017-07-21T19:23:12.844775 #35707] DEBUG -- : method: composite and args: []
3186
+ D, [2017-07-21T19:23:12.845388 #35707] DEBUG -- : parent is a widget: true
3187
+ D, [2017-07-21T19:23:12.845833 #35707] DEBUG -- : on listener?: false
3188
+ D, [2017-07-21T19:23:12.864395 #35707] DEBUG -- : WidgetCommandHandler will handle command: composite with arguments []
3189
+ D, [2017-07-21T19:23:12.864893 #35707] DEBUG -- : widget styles are: []
3190
+ D, [2017-07-21T19:23:12.874296 #35707] DEBUG -- : method: list and args: [:multi]
3191
+ D, [2017-07-21T19:23:12.874969 #35707] DEBUG -- : parent is a widget: true
3192
+ D, [2017-07-21T19:23:12.875452 #35707] DEBUG -- : on listener?: false
3193
+ D, [2017-07-21T19:23:12.878434 #35707] DEBUG -- : WidgetCommandHandler will handle command: list with arguments [:multi]
3194
+ D, [2017-07-21T19:23:12.878798 #35707] DEBUG -- : widget styles are: [:multi]
3195
+ ```
3196
+
3197
+ The `logger` instance may be replaced with a custom logger via `Glimmer::Config.logger = custom_logger`
3198
+
3199
+ To reset `logger` to the default instance, you may call `Glimmer::Config.reset_logger!`
3200
+
3201
+ All logging is done lazily via blocks (e.g. `logger.debug {message}`) to avoid affecting app performance with logging when below the configured logging level threshold.
3202
+
3203
+ [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) enhances Glimmer default logging support via the Ruby [`logging`](https://github.com/TwP/logging) gem, enabling buffered asynchronous logging in a separate thread, thus completely unhindering normal desktop app performance.
3204
+
3205
+ Other config options related to the [`logging`](https://github.com/TwP/logging) gem are mentioned below.
3206
+
3207
+ #### logging_devices
3208
+
3209
+ This is an array of these possible values: `:stdout` (default), `:stderr`, `:file`, `:syslog` (default), `:stringio`
3210
+
3211
+ It defaults to `[:stdout, :syslog]`
3212
+
3213
+ When `:file` is included, Glimmer creates a 'log' directory directly below the Glimmer app local directory.
3214
+ It may also be customized further via the `logging_device_file_options` option.
3215
+ This is useful on Windows as an alternative to `syslog`, which is not available on Windows by default.
3216
+
3217
+ #### logging_device_file_options
3218
+
3219
+ This is a hash of [`logging`](https://github.com/TwP/logging) gem options for the `:file` logging device.
3220
+
3221
+ Default: `{size: 1_000_000, age: 'daily', roll_by: 'number'}`
3222
+
3223
+ That ensures splitting log files at the 1MB size and daily, rolling them by unique number.
3224
+
3225
+ #### logging_appender_options
3226
+
3227
+ Appender options is a hash passed as options to every appender (logging device) used in the [`logging`](https://github.com/TwP/logging) gem.
3228
+
3229
+ Default: `{async: true, auto_flushing: 500, write_size: 500, flush_period: 60, immediate_at: [:error, :fatal], layout: logging_layout}`
3230
+
3231
+ That ensures asynchronous buffered logging that is flushed every 500 messages and 60 seconds, or immediately at error and fatal log levels
3232
+
3233
+ #### logging_layout
3234
+
3235
+ This is a [`logging`](https://github.com/TwP/logging) gem layout that formats the logging output.
3236
+
3237
+ Default:
3238
+
3239
+ ```
3240
+ Logging.layouts.pattern(
3241
+ pattern: '[%d] %-5l %c: %m\n',
3242
+ date_pattern: '%Y-%m-%d %H:%M:%S'
3243
+ )
3244
+ ```
3245
+
3246
+ ### import_swt_packages
3247
+
3248
+ Glimmer automatically imports all SWT Java packages upon adding `include Glimmer`, `include Glimmer::UI::CustomWidget`, or `include Glimmer::UI::CustomShell` to a class or module. It relies on JRuby's `include_package` for lazy-importing upon first reference of a Java class.
3249
+
3250
+ As a result, you may call SWT Java classes from Glimmer Ruby code without mentioning Java package references explicitly.
3251
+
3252
+ For example, `org.eclipse.swt.graphics.Color` can be referenced as just `Color`
3253
+
3254
+ The Java packages imported come from the [`Glimmer::Config.import_swt_packages`](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/lib/ext/glimmer/config.rb) config option, which defaults to `Glimmer::Config::DEFAULT_IMPORT_SWT_PACKAGES`, importing the following Java packages:
3255
+ ```
3256
+ org.eclipse.swt.*
3257
+ org.eclipse.swt.widgets.*
3258
+ org.eclipse.swt.layout.*
3259
+ org.eclipse.swt.graphics.*
3260
+ org.eclipse.swt.browser.*
3261
+ org.eclipse.swt.custom.*
3262
+ org.eclipse.swt.dnd.*
3263
+ ```
3264
+
3265
+ If you need to import additional Java packages as extra Glimmer widgets, you may add more packages to [`Glimmer::Config.import_swt_packages`](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/lib/ext/glimmer/config.rb) by using the `+=` operator (or alternatively limit to certain packages via `=` operator).
3266
+
3267
+ Example:
3268
+
3269
+ ```ruby
3270
+ Glimmer::Config.import_swt_packages += [
3271
+ 'org.eclipse.nebula.widgets.ganttchart'
3272
+ ]
3273
+ ```
3274
+
3275
+ Another alternative is to simply add a `java_import` call to your code (e.g. `java_import 'org.eclipse.nebula.widgets.ganttchart.GanttChart'`). Glimmer will automatically take advantage of it (e.g. when invoking `gantt_chart` keyword)
3276
+
3277
+ Nonetheless, you can disable automatic Java package import if needed via this Glimmer configuration option:
3278
+
3279
+ ```ruby
3280
+ Glimmer::Config.import_swt_packages = false
3281
+ ```
3282
+
3283
+ Once disabled, to import SWT Java packages manually, you may simply:
3284
+
3285
+ 1. `include Glimmer::SWT::Packages`: lazily imports all SWT Java packages to your class, lazy-loading SWT Java class constants on first reference.
3286
+
3287
+ 2. `java_import swt_package_class_string`: immediately imports a specific Java class where `swt_package_class_string` is the Java full package reference of a Java class (e.g. `java_import 'org.eclipse.swt.SWT'`)
3288
+
3289
+ Note: Glimmer relies on [`nested_imported_jruby_include_package`](https://github.com/AndyObtiva/nested_inherited_jruby_include_package), which automatically brings packages to nested-modules/nested-classes and sub-modules/sub-classes.
3290
+
3291
+ You can learn more about importing Java packages into Ruby code at this JRuby WIKI page:
3292
+
3293
+ https://github.com/jruby/jruby/wiki/CallingJavaFromJRuby
3294
+
3295
+ ### loop_max_count
3296
+
3297
+ Glimmer has infinite loop detection support.
3298
+ It can detect when an infinite loop is about to occur in method_missing and stops it.
3299
+ It detects potential infinite loops when the same keyword and args repeat more than 100 times, which is unusual in a GUI app.
3300
+
3301
+ The max limit can be changed via the `Glimmer::Config::loop_max_count=(count)` config option.
3302
+
3303
+ Infinite loop detection may be disabled altogether if needed by setting `Glimmer::Config::loop_max_count` to `-1`
3304
+
3305
+ ### excluded_keyword_checkers
3306
+
3307
+ Glimmer permits consumers to exclude keywords from DSL processing by its engine via the `excluded_keyword_checkers` config option.
3308
+
3309
+ To do so, add a proc to it that returns a boolean indicating if a keyword is excluded or not.
3310
+
3311
+ Note that this proc runs within the context of the Glimmer object (as in the object mixing in the Glimmer module), so checker can can pretend to run there with its `self` object assumption.
3312
+
3313
+ Example of keywords excluded by [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt):
3314
+
3315
+ ```ruby
3316
+ Glimmer::Config.excluded_keyword_checkers << lambda do |method_symbol, *args|
3317
+ method = method_symbol.to_s
3318
+ result = false
3319
+ result ||= method.start_with?('on_swt_') && is_a?(Glimmer::UI::CustomWidget) && respond_to?(method)
3320
+ result ||= method == 'dispose' && is_a?(Glimmer::UI::CustomWidget) && respond_to?(method)
3321
+ result ||= ['drag_source_proxy', 'drop_target_proxy'].include?(method) && is_a?(Glimmer::UI::CustomWidget)
3322
+ result ||= method == 'post_initialize_child'
3323
+ result ||= method.end_with?('=')
3324
+ result ||= ['finish_edit!', 'search', 'all_tree_items', 'depth_first_search'].include?(method) && is_a?(Glimmer::UI::CustomWidget) && body_root.respond_to?(method)
3325
+ end
3326
+ ```
3327
+
3328
+ ### log_excluded_keywords
3329
+
3330
+ This just tells Glimmer whether to log excluded keywords or not (at the debug level). It is off by default.
3331
+
3332
+ ## Glimmer Style Guide
3333
+
3334
+ - Widgets are declared with underscored lowercase versions of their SWT names minus the SWT package name.
3335
+ - Widget declarations may optionally have arguments and be followed by a block (to contain properties and content)
3336
+ - Widget blocks are always declared with curly braces
3337
+ - Widget arguments are always wrapped inside parentheses
3338
+ - Widget properties are declared with underscored lowercase versions of the SWT properties
3339
+ - Widget property declarations always have arguments and never take a block
3340
+ - Widget property arguments are never wrapped inside parentheses
3341
+ - Widget listeners are always declared starting with `on_` prefix and affixing listener event method name afterwards in underscored lowercase form
3342
+ - Widget listeners are always followed by a block using curly braces (Only when declared in DSL. When invoked on widget object directly outside of GUI declarations, standard Ruby conventions apply)
3343
+ - Data-binding is done via `bind` keyword, which always takes arguments wrapped in parentheses
3344
+ - Custom widget body, before_body, and after_body blocks open their blocks and close them with curly braces.
3345
+ - Custom widgets receive additional arguments to SWT style called options. These are passed as the last argument inside the parentheses, a hash of option names pointing to values.
3346
+
3347
+ ## SWT Reference
3348
+
3349
+ https://www.eclipse.org/swt/docs.php
3350
+
3351
+ Here is the SWT API:
3352
+
3353
+ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
3354
+
3355
+ Here is a visual list of SWT widgets:
3356
+
3357
+ https://www.eclipse.org/swt/widgets/
3358
+
3359
+ Here is a textual list of SWT widgets:
3360
+
3361
+ https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/guide/swt_widgets_controls.htm?cp=2_0_7_0_0
3362
+
3363
+ Here is a list of SWT style bits as used in widget declaration:
3364
+
3365
+ https://wiki.eclipse.org/SWT_Widget_Style_Bits
3366
+
3367
+ Here is a SWT style bit constant reference:
3368
+
3369
+ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
3370
+
3371
+ Here is an SWT Drag and Drop guide:
3372
+
3373
+ https://www.eclipse.org/articles/Article-SWT-DND/DND-in-SWT.html
3374
+
3375
+ Here is an SWT Custom Widget guide:
3376
+
3377
+ https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm
3378
+
3379
+ ## Samples
3380
+
3381
+ Check the [samples](samples) directory in [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) for examples on how to write Glimmer applications. To run a sample, make sure to install the `glimmer` gem first and then use the `glimmer` command to run it (alternatively, you may clone the repo, follow [CONTRIBUTING.md](CONTRIBUTING.md) instructions, and run samples locally with development glimmer command: `bin/glimmer`).
3382
+
3383
+ If you cloned the project and followed [CONTRIBUTING.md](CONTRIBUTING.md) instructions, you may run all samples in [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) at once via `samples/launch` command:
3384
+
3385
+ ```
3386
+ samples/launch
3387
+ ```
3388
+
3389
+ ### Hello Samples
3390
+
3391
+ For hello-type simple samples, check the following.
3392
+
3393
+ #### Hello, World! Sample
3394
+
3395
+ Code:
3396
+
3397
+ [samples/hello/hello_world.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_world.rb)
3398
+
3399
+ Run:
3400
+
3401
+ ```
3402
+ glimmer sample:run[hello_world]
3403
+ ```
3404
+
3405
+ ![Hello World](images/glimmer-hello-world.png)
3406
+
3407
+ #### Hello, Tab!
3408
+
3409
+ Code:
3410
+
3411
+ [samples/hello/hello_tab.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_tab.rb)
3412
+
3413
+ Run:
3414
+
3415
+ ```
3416
+ glimmer sample:run[hello_tab]
3417
+ ```
3418
+
3419
+ ![Hello Tab English](images/glimmer-hello-tab-english.png)
3420
+ ![Hello Tab French](images/glimmer-hello-tab-french.png)
3421
+
3422
+ #### Hello, Combo!
3423
+
3424
+ This sample demonstrates combo data-binding.
3425
+
3426
+ Code:
3427
+
3428
+ [samples/hello/hello_combo.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_combo.rb)
3429
+
3430
+ Run:
3431
+
3432
+ ```
3433
+ glimmer sample:run[hello_combo]
3434
+ ```
3435
+
3436
+ ![Hello Combo](images/glimmer-hello-combo.png)
3437
+ ![Hello Combo Expanded](images/glimmer-hello-combo-expanded.png)
3438
+
3439
+ #### Hello, List Single Selection!
3440
+
3441
+ This sample demonstrates list single-selection data-binding.
3442
+
3443
+ Code:
3444
+
3445
+ [samples/hello/hello_list_single_selection.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_list_single_selection.rb)
3446
+
3447
+ Run:
3448
+
3449
+ ```
3450
+ glimmer sample:run[hello_list_single_selection]
3451
+ ```
3452
+
3453
+ ![Hello List Single Selection](images/glimmer-hello-list-single-selection.png)
3454
+
3455
+ #### Hello, List Multi Selection!
3456
+
3457
+ This sample demonstrates list multi-selection data-binding.
3458
+
3459
+ Code:
3460
+
3461
+ [samples/hello/hello_list_multi_selection.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_list_multi_selection.rb)
3462
+
3463
+ Run:
3464
+
3465
+ ```
3466
+ glimmer sample:run[hello_list_multi_selection]
3467
+ ```
3468
+
3469
+ ![Hello List Multi Selection](images/glimmer-hello-list-multi-selection.png)
3470
+
3471
+ #### Hello, Computed!
3472
+
3473
+ This sample demonstrates computed data-binding.
3474
+
3475
+ Code:
3476
+
3477
+ [samples/hello/hello_computed.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_computed.rb)
3478
+
3479
+ Run:
3480
+
3481
+ ```
3482
+ glimmer sample:run[hello_computed]
3483
+ ```
3484
+
3485
+ ![Hello Browser](images/glimmer-hello-computed.png)
3486
+
3487
+ #### Hello, Message Box!
3488
+
3489
+ This sample demonstrates a `message_box` dialog.
3490
+
3491
+ Code:
3492
+
3493
+ [samples/hello/hello_message_box.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_message_box.rb)
3494
+
3495
+ Run:
3496
+
3497
+ ```
3498
+ glimmer sample:run[hello_message_box]
3499
+ ```
3500
+
3501
+ ![Hello Message Box](images/glimmer-hello-message-box.png)
3502
+ ![Hello Message Box Dialog](images/glimmer-hello-message-box-dialog.png)
3503
+
3504
+ #### Hello, Browser!
3505
+
3506
+ This sample demonstrates the `browser` widget.
3507
+
3508
+ Code:
3509
+
3510
+ [samples/hello/hello_browser.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_browser.rb)
3511
+
3512
+ Run:
3513
+
3514
+ ```
3515
+ glimmer sample:run[hello_browser]
3516
+ ```
3517
+
3518
+ ![Hello Browser](images/glimmer-hello-browser.png)
3519
+
3520
+ #### Hello, Drag and Drop!
3521
+
3522
+ This sample demonstrates drag and drop in Glimmer.
3523
+
3524
+ Code:
3525
+
3526
+ [samples/hello/hello_drag_and_drop.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_drag_and_drop.rb)
3527
+
3528
+ Run:
3529
+
3530
+ ```
3531
+ glimmer sample:run[hello_drag_and_drop]
3532
+ ```
3533
+
3534
+ ![Hello Drag and Drop](images/glimmer-hello-drag-and-drop.gif)
3535
+
3536
+ #### Hello, Menu Bar!
3537
+
3538
+ This sample demonstrates menus in Glimmer.
3539
+
3540
+ Code:
3541
+
3542
+ [samples/hello/hello_menu_bar.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_menu_bar.rb)
3543
+
3544
+ Run:
3545
+
3546
+ ```
3547
+ glimmer sample:run[hello_menu_bar]
3548
+ ```
3549
+
3550
+ ![Hello Menu Bar](images/glimmer-hello-menu-bar.png)
3551
+ ![Hello Menu Bar File Menu](images/glimmer-hello-menu-bar-file-menu.png)
3552
+ ![Hello Menu Bar History Menu](images/glimmer-hello-menu-bar-history-menu.png)
3553
+
3554
+ #### Hello, Pop Up Context Menu!
3555
+
3556
+ This sample demonstrates pop up context menus in Glimmer.
3557
+
3558
+ Code:
3559
+
3560
+ [samples/hello/hello_pop_up_context_menu.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_pop_up_context_menu.rb)
3561
+
3562
+ Run:
3563
+
3564
+ ```
3565
+ glimmer sample:run[hello_pop_up_context_menu]
3566
+ ```
3567
+
3568
+ ![Hello Pop Up Context Menu](images/glimmer-hello-pop-up-context-menu.png)
3569
+ ![Hello Pop Up Context Menu Popped Up](images/glimmer-hello-pop-up-context-menu-popped-up.png)
3570
+
3571
+ ### Elaborate Samples
3572
+
3573
+ For more elaborate samples, check the following:
3574
+
3575
+ #### User Profile
3576
+
3577
+ This sample was used in the [DZone Article about Glimmer](https://dzone.com/articles/an-introduction-glimmer), demonstrating Glimmer widgets in general.
3578
+
3579
+ Please note that the code has changed since that article was written (the GUI DSL has been improved/simplified), so use the code sample mentioned here instead as the correct version.
3580
+
3581
+ Code:
3582
+
3583
+ [samples/elaborate/user_profile.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/user_profile.rb)
3584
+
3585
+ Run:
3586
+
3587
+ ```
3588
+ glimmer sample:run[user_profile]
3589
+ ```
3590
+
3591
+ ![User Profile](images/glimmer-user-profile.png)
3592
+
3593
+ #### Login
3594
+
3595
+ This sample demonstrates basic data-binding, password and text fields, and field enablement data-binding.
3596
+
3597
+ Code:
3598
+
3599
+ [samples/elaborate/login.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/login.rb)
3600
+
3601
+ Run:
3602
+
3603
+ ```
3604
+ glimmer sample:run[login]
3605
+ ```
3606
+
3607
+ ![Login](images/glimmer-login.png)
3608
+ ![Login Filled In](images/glimmer-login-filled-in.png)
3609
+ ![Login Logged In](images/glimmer-login-logged-in.png)
3610
+
3611
+ #### Tic Tac Toe Sample
3612
+
3613
+ This sample demonstrates a full MVC application, including GUI layout, text and enablement data-binding, and test-driven development (has [specs](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/spec/samples/elaborate/tic_tac_toe/board_spec.rb)).
3614
+
3615
+ Code:
3616
+
3617
+ (Please note that on some Linux instances where the display x-axis is set to double-scale, you need to set the `shell` `minimum_size` to `300, 178` instead of `150, 178`)
3618
+
3619
+ [samples/elaborate/tic_tac_toe.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/tic_tac_toe.rb)
3620
+
3621
+ Run:
3622
+
3623
+ ```
3624
+ glimmer sample:run[tic_tac_toe]
3625
+ ```
3626
+
3627
+ ![Tic Tac Toe](images/glimmer-tic-tac-toe.png)
3628
+ ![Tic Tac Toe In Progress](images/glimmer-tic-tac-toe-in-progress.png)
3629
+ ![Tic Tac Toe Game Over](images/glimmer-tic-tac-toe-game-over.png)
3630
+
3631
+ #### Contact Manager Sample
3632
+
3633
+ This sample demonstrates table data-binding, sorting, filtering, GUI layout, MVP pattern, and test-driven development (has [specs](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/spec/samples/elaborate/contact_manager/contact_manager_presenter_spec.rb)).
3634
+
3635
+ Code:
3636
+
3637
+ [samples/elaborate/contact_manager.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/contact_manager.rb)
3638
+
3639
+ Run:
3640
+
3641
+ ```
3642
+ glimmer sample:run[contact_manager]
3643
+ ```
3644
+
3645
+ Contact Manager
3646
+
3647
+ ![Contact Manager](images/glimmer-contact-manager.png)
3648
+
3649
+ Contact Manager - Find
3650
+
3651
+ ![Contact Manager](images/glimmer-contact-manager-find.png)
3652
+
3653
+ Contact Manager - Edit Started
18
3654
 
19
- ## Example
3655
+ ![Contact Manager](images/glimmer-contact-manager-edit-started.png)
3656
+
3657
+ Contact Manager - Edit In Progress
3658
+
3659
+ ![Contact Manager](images/glimmer-contact-manager-edit-in-progress.png)
3660
+
3661
+ Contact Manager - Edit Done
3662
+
3663
+ ![Contact Manager](images/glimmer-contact-manager-edit-done.png)
3664
+
3665
+ ### External Samples
3666
+
3667
+ #### Glimmer Calculator
3668
+
3669
+ [<img alt="Glimmer Calculator Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/master/glimmer-cs-calculator-icon.png" height=40 /> Glimmer Calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) is a basic calculator sample app demonstrating data-binding and TDD (test-driven-development) with Glimmer following the MVP pattern (Model-View-Presenter).
3670
+
3671
+ [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/master/glimmer-cs-calculator-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-calculator)
3672
+
3673
+ #### Gladiator
3674
+
3675
+ [<img src='https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/master/images/glimmer-cs-gladiator-logo.svg' height=40 /> Gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator) (short for Glimmer Editor) is a Glimmer sample project under on-going development.
3676
+ You may check it out to learn how to build a Glimmer Custom Shell gem.
3677
+
3678
+ [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/master/images/glimmer-gladiator.png" />](https://github.com/AndyObtiva/glimmer-cs-gladiator)
3679
+
3680
+ Gladiator is a good demonstration of:
3681
+ - MVP Pattern
3682
+ - Tree data-binding
3683
+ - List data-binding
3684
+ - Text selection data-binding
3685
+ - Tabs
3686
+ - Context menus
3687
+ - Custom Shell
3688
+ - Custom widget
3689
+
3690
+ #### Timer
3691
+
3692
+ [<img alt="Glimmer Timer Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/images/glimmer-timer-logo.png" height=40 /> Timer](https://github.com/AndyObtiva/glimmer-cs-timer) is a sample app demonstrating data-binding and multi-threading in a desktop application.
3693
+
3694
+ [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/glimmer-timer-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-timer)
3695
+
3696
+ ## In Production
3697
+
3698
+ The following production apps have been built with Glimmer.
3699
+
3700
+ If you have a Glimmer app you would like referenced here, please mention in a Pull Request.
3701
+
3702
+ ### Math Bowling
3703
+
3704
+ [<img alt="Math Bowling Logo" src="https://raw.githubusercontent.com/AndyObtiva/MathBowling/master/images/math-bowling-logo.png" width="40" />Math Bowling](https://github.com/AndyObtiva/MathBowling): an educational math game for elementary level kids
3705
+
3706
+ ### Are We There Yet?
3707
+
3708
+ [<img alt="Are We There Yet Logo" src="https://raw.githubusercontent.com/AndyObtiva/are-we-there-yet/master/are-we-there-yet-logo.svg" width="40" />Are We There Yet?](https://github.com/AndyObtiva/are-we-there-yet): A tool that helps you learn when your small projects will finish
3709
+
3710
+ ### Garderie Rainbow Daily Agenda
3711
+
3712
+ [<img alt="Garderie Rainbow Daily Agenda Logo" src="https://github.com/AndyObtiva/garderie_rainbow_daily_agenda/raw/master/images/garderie_rainbow_daily_agenda_logo.png" width="40" />Garderie Rainbow Daily Agenda](https://github.com/AndyObtiva/garderie_rainbow_daily_agenda): A child nursery daily agenda reporting desktop app
3713
+
3714
+ ## Packaging & Distribution
3715
+
3716
+ Glimmer simplifies the process of native-executable packaging and distribution on Mac and Windows via a single `glimmer package` command:
3717
+
3718
+ ```
3719
+ glimmer package
3720
+ ```
3721
+
3722
+ It works out of the box for any application scaffolded by [Glimmer Scaffolding](#scaffolding), generating all available packaging types on the current platform (e.g. `DMG`, `PKG`, `APP` on the Mac) and displaying a message indicating what pre-requisite setup tools are needed if not installed already (e.g. [Wix Toolset](https://wixtoolset.org/) to generate MSI files on Windows)
3723
+
3724
+ You may choose to generate a specific type of packaging instead by addionally passing in the `[type]` option. For example, this generates an MSI setup file on Windows:
3725
+
3726
+ ```
3727
+ glimmer package[msi]
3728
+ ```
3729
+
3730
+ - Available Mac packaging types are `dmg`, `pkg`, and `image` (image means a pure Mac `app` without a setup program)
3731
+ - Available Windows packaging types are `msi`, `exe`, and `image` (image means a Windows application directory without a setup program). Learn more about Windows packaging are [over here](#windows-application-packaging).
3732
+
3733
+ Note: if you are using Glimmer manually, to make the `glimmer package` command available, you must add the following line to your application `Rakefile` (automatically done for you if you scaffold an app or gem with `glimmer scaffold[AppName]` or `glimmer scaffold:gem:customshell[GemName]`):
20
3734
 
21
3735
  ```ruby
22
- include Glimmer
23
-
24
- shell {
25
- text 'Glimmer'
26
- label {
27
- text 'Hello, World!'
28
- }
29
- }.open
3736
+ require 'glimmer/rake_task'
3737
+ ```
3738
+
3739
+ The Glimmer packaging process done in the `glimmer package` command consists of the following steps:
3740
+ 1. Generate gemspec via Jeweler (`rake gemspec:generate`): Having a gemspec is required by the [`jar-dependencies`](https://github.com/mkristian/jar-dependencies) JRuby gem, used by JRuby libraries to declare JAR dependencies.
3741
+ 1. Lock JAR versions (`glimmer package:lock_jars`): This locks versions of JAR dependencies leveraged by the `jar-dependencies` JRuby gem, downloading them into the `./vendor` directory so they would get inside the top-level Glimmer app/gem JAR file.
3742
+ 1. Generate [Warbler](https://github.com/jruby/warbler) config (`glimmer package:config`): Generates initial Warbler config file (under `./config/warble.rb`) to use for generating JAR file.
3743
+ 1. Generate JAR file using [Warbler](https://github.com/jruby/warbler) (`glimmer package:jar`): Enables bundling a Glimmer app into a JAR file under the `./dist` directory
3744
+ 1. Generate native executable using [javapackager](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html) (`glimmer package:native`): Enables packaging a JAR file as a DMG/PKG/APP file on Mac, MSI/EXE/APP on Windows, and DEB/RPM/APP on Linux (Glimmer does not officially support Linux with the `glimmer package` command yet, but it generates the JAR file successfully, and you could use `javapackager` manually afterwards if needed).
3745
+
3746
+ Those steps automatically ensure generating a JAR file under the `./dist` directory using [Warbler](https://github.com/jruby/warbler), which is then used to automatically generate a DMG/MSI file (and other executables) under the `./packages/bundles` directory using `javapackager`.
3747
+ The JAR file name will match your application local directory name (e.g. `MathBowling.jar` for `~/code/MathBowling`)
3748
+ The DMG file name will match the humanized local directory name + dash + application version (e.g. `Math Bowling-1.0.dmg` for `~/code/MathBowling` with version 1.0 or unspecified)
3749
+
3750
+ The `glimmer package` command will automatically set "mac.CFBundleIdentifier" to ="org.#{project_name}.application.#{project_name}".
3751
+ You may override by configuring as an extra argument for javapackger (e.g. Glimmer::Package.javapackager_extra_args = " -Bmac.CFBundleIdentifier=org.andymaleh.application.MathBowling")
3752
+
3753
+ ### Packaging Defaults
3754
+
3755
+ Glimmer employs smart defaults in packaging.
3756
+
3757
+ The package application name (shows up in top menu bar on the Mac) will be a human form of the app root directory name (e.g. "Math Bowling" for "MathBowling" or "math_bowling" app root directory name). However, application name and version may be specified explicitly via "-Bmac.CFBundleName" and "-Bmac.CFBundleVersion" options.
3758
+
3759
+ Also, the package will only include these directories: app, config, db, lib, script, bin, docs, fonts, images, sounds, videos
3760
+
3761
+ After running once, you will find a `config/warble.rb` file. It has the JAR packaging configuration. You may adjust included directories in it if needed, and then rerun `glimmer package` and it will pick up your custom configuration. Alternatively, if you'd like to customize the included directories to begin with, don't run `glimmer package` right away. Run this command first:
3762
+
3763
+ ```
3764
+ glimmer package:config
3765
+ ```
3766
+
3767
+ This will generate `config/warble.rb`, which you may configure and then run `glimmer package` afterwards.
3768
+
3769
+ ### Packaging Configuration
3770
+
3771
+ - Ensure you have a Ruby script under `bin` directory that launches the application, preferably matching your project directory name (e.g. `bin/math_bowling`) :
3772
+ ```ruby
3773
+ require_relative '../app/my_application.rb'
3774
+ ```
3775
+ - Include Icon (Optional): If you'd like to include an icon for your app (.icns format on the Mac), place it under `package/macosx` matching the humanized application local directory name (e.g. 'Math Bowling.icns' [containing space] for MathBowling or math_bowling). You may generate your Mac icon easily using tools like Image2Icon (http://www.img2icnsapp.com/) or manually using the Mac terminal command `iconutil` (iconutil guide: https://applehelpwriter.com/tag/iconutil/)
3776
+ - Include DMG Background Icon (Optional): Simply place a .png file under `package/macosx/{HumanAppName}-background.png`
3777
+ - Include Version (Optional): Create a `VERSION` file in your application and fill it your app version on one line (e.g. `1.1.0`)
3778
+ - Include License (Optional): Create a `LICENSE.txt` file in your application and fill it up with your license (e.g. MIT). It will show up to people when installing your app. Note that, you may optionally also specify license type, but you'd have to do so manually via `-BlicenseType=MIT` shown in an [example below](#javapackager-extra-arguments).
3779
+ - Extra args (Optional): You may optionally add the following to `Rakefile` to configure extra arguments for javapackager: `Glimmer::Packager.javapackager_extra_args = "..."` (Useful to avoid re-entering extra arguments on every run of rake task.). Read about them in [their section below](#javapackager-extra-arguments).
3780
+
3781
+ ### javapackager Extra Arguments
3782
+
3783
+ In order to explicitly configure javapackager, Mac package attributes, or sign your Mac app to distribute on the App Store, you can follow more advanced instructions for `javapackager` here:
3784
+ - https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719
3785
+ - https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html
3786
+ - https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/self-contained-packaging.html#BCGICFDB
3787
+ - https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/self-contained-packaging.html
3788
+ - https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMacAppStore/index.html#//apple_ref/doc/uid/TP40010572-CH16-SW8
3789
+
3790
+ The Glimmer rake task allows passing extra options to javapackager via:
3791
+ - `Glimmer::Packager.javapackager_extra_args="..."` in your application Rakefile
3792
+ - Environment variable: `JAVAPACKAGER_EXTRA_ARGS`
3793
+
3794
+ Example (Rakefile):
3795
+
3796
+ ```ruby
3797
+ require 'glimmer/rake_task'
3798
+
3799
+ Glimmer::Package.javapackager_extra_args = '-BlicenseType="MIT" -Bmac.category="public.app-category.business" -Bmac.signing-key-developer-id-app="Andy Maleh"'
3800
+ ```
3801
+
3802
+ Note that `mac.category` defaults to "public.app-category.business", but can be overridden with one of the category UTI values mentioned here:
3803
+
3804
+ https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMacAppStore/index.html#//apple_ref/doc/uid/TP40010572-CH16-SW8
3805
+
3806
+ Example (env var):
3807
+
3808
+ ```
3809
+ JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"' glimmer package
3810
+ ```
3811
+
3812
+ That overrides the default application display name.
3813
+
3814
+ ### Verbose Mode
3815
+
3816
+ Pass `-v` to javapackager in `Glimmer::Package.javapackager_extra_args` or by running `glimmer package:native[type] -v` to learn more about further available customizations for the installer you are requesting to generate.
3817
+
3818
+ ### Windows Application Packaging
3819
+
3820
+ Windows offers two options for setup packaging:
3821
+ - `msi` (recommended): simpler packaging option. Requires [WiX Toolset](https://wixtoolset.org/) and [.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework). Simply run `glimmer package[msi]` (or `glimmer package:native[msi]` if it's not your first time) and it will give you more details on the pre-requisites you need to install (e.g. [WiX Toolset](https://wixtoolset.org/) and [.NET Framework 3.5 SP1](https://dotnet.microsoft.com/download/dotnet-framework/net35-sp1)).
3822
+ - `exe`: more advanced packaging option. Requires [Inno Setup](https://jrsoftware.org/isinfo.php). Simply run `glimmer package[exe]` (or `glimmer package:native[exe]` if it's not your first time) and it will tell you what you need to install.
3823
+
3824
+ If you just want to test out packaging into a native Windows app that is not packaged for Windows setup, just pass `image` to generate a native Windows app only.
3825
+
3826
+ ### Mac Application Distribution
3827
+
3828
+ Recent macOS versions (starting with Catalina) have very stringent security requirements requiring all applications to be signed before running (unless the user goes to System Preferences -> Privacy -> General tab and clicks "Open Anyway" after failing to open application the first time they run it). So, to release a desktop application on the Mac, it is recommended to enroll in the [Apple Developer Program](https://developer.apple.com/programs/) to distribute on the [Mac App Store](https://developer.apple.com/distribute/) or otherwise request [app notarization from Apple](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution) to distribute independently.
3829
+
3830
+ Afterwards, you may add developer-id/signing-key arguments to `javapackager` via `Glimmer::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS` according to this webpage: https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719
3831
+
3832
+ DMG signing key argument:
3833
+ ```
3834
+ -Bmac.signing-key-developer-id-app="..."
3835
+ ```
3836
+
3837
+ PKG signing key argument:
3838
+ ```
3839
+ -Bmac.signing-key-developer-id-installer="..."
3840
+ ```
3841
+
3842
+ Mac App Store signing key arguments:
3843
+ ```
3844
+ -Bmac.signing-key-app="..."
3845
+ -Bmac.signing-key-pkg="..."
3846
+ ```
3847
+
3848
+ ### Self Signed Certificate
3849
+
3850
+ You may still release a signed DMG file without enrolling into the Apple Developer Program with the caveat that users will always fail in opening the app the first time, and have to go to System Preferences -> Privacy -> General tab to "Open Anyway".
3851
+
3852
+ To do so, you may follow these steps (abbreviated version from https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/Procedures/Procedures.html#//apple_ref/doc/uid/TP40005929-CH4-SW2):
3853
+ - Open Keychain Access
3854
+ - Choose Keychain Access > Certificate Assistant > Create Certificate ...
3855
+ - Enter Name (referred to below as "CertificateName")
3856
+ - Set 'Certificate Type' to 'Code Signing'
3857
+ - Create (if you alternatively override defaults, make sure to enable all capabilities)
3858
+ - Add the following option to javapackager: `-Bmac.signing-key-developer-id-app="CertificateName"` via `Glimmer::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS`
3859
+
3860
+ Example:
3861
+
3862
+ ```ruby
3863
+ Glimmer::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
30
3864
  ```
31
3865
 
32
- ![Glimmer DSL for SWT Hello World](https://github.com/AndyObtiva/glimmer/blob/master/images/glimmer-hello-world.png)
3866
+ Now, when you run `glimmer package`, it builds a self-signed DMG file. When you make available online, and users download, upon launching application, they are presented with your certificate, which they have to sign if they trust you in order to use the application.
33
3867
 
34
- Learn more at the main [Glimmer project page](https://github.com/AndyObtiva/glimmer).
3868
+ ### Gotchas
3869
+
3870
+ 1. Specifying License File
3871
+
3872
+ The javapackager documentation states that a license file may be specified with "-BlicenseFile" javapackager option. However, in order for that to work, one must specify as a source file via "-srcfiles" javapackager option.
3873
+ Keep that in mind if you are not going to rely on the default `LICENSE.txt` support.
3874
+
3875
+ Example:
3876
+
3877
+ ```ruby
3878
+ Glimmer::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="ACME.txt" -BlicenseType="ACME"'
3879
+ ```
3880
+
3881
+ 2. Mounted DMG Residue
3882
+
3883
+ If you run `glimmer package` multiple times, sometimes it leaves a mounted DMG project in your finder. Unmount before you run the command again or it might fail with an error saying: "Error: Bundler "DMG Installer" (dmg) failed to produce a bundle."
3884
+
3885
+ By the way, keep in mind that during normal operation, it does also indicate a false-negative while completing successfully similar to the following (please ignore):
3886
+
3887
+ ```
3888
+ Exec failed with code 2 command [[/usr/bin/SetFile, -c, icnC, /var/folders/4_/g1sw__tx6mjdgyh3mky7vydc0000gp/T/fxbundler4076750801763032201/images/MathBowling/.VolumeIcon.icns] in unspecified directory
3889
+ ```
3890
+
3891
+ ## App Updates
3892
+
3893
+ Glimmer already supports automatic (and manual) app updates via the Mac App Store for Mac apps. Simply run the `glimmer package` command with the Mac App Store keys configured as per [Mac Application Distribution](mac-application-distribution) instructions and you get automatic (and manual) app update support courtesy of the Mac App Store.
3894
+
3895
+ ## Glimmer Supporting Libraries
3896
+
3897
+ Here is a list of notable 3rd party gems used by Glimmer:
3898
+ - [jeweler](https://github.com/technicalpickles/jeweler): generates app gems during [Glimmer Scaffolding](#scaffolding)
3899
+ - [logging](https://github.com/TwP/logging): provides extra logging capabilities not available in Ruby Logger such as multi-threaded buffered asynchronous logging (to avoid affecting app performance) and support for multiple appenders such as stdout, syslog, and log files (the last one is needed on Windows where syslog is not supported)
3900
+ - [nested_inherited_jruby_include_package](https://github.com/AndyObtiva/nested_inherited_jruby_include_package): makes included [SWT](https://www.eclipse.org/swt/)/[Java](https://www.java.com/en/) packages available to all classes/modules that mix in the Glimmer module without having to manually reimport
3901
+ - [os](https://github.com/rdp/os): provides OS detection capabilities (e.g. `OS.mac?` or `OS.windows?`) to write cross-platform code inexpensively
3902
+ - [puts_debuggerer](https://github.com/AndyObtiva/puts_debuggerer): helps in troubleshooting when adding `require 'pd'` and using the `pd` command instead of `puts` or `p` (also `#pd_inspect` or `#pdi` instead of `#inspect`)
3903
+ - [rake](https://github.com/ruby/rake): used to implement and execute `glimmer` commands
3904
+ - [rake-tui](https://github.com/AndyObtiva/rake-tui): Rake Text-based User Interface. Allows navigating rake tasks with arrow keys and filtering task list by typing to quickly find an run a rake task.
3905
+ - [super_module](https://github.com/AndyObtiva/super_module): used to cleanly write the Glimmer::UI:CustomWidget and Glimmer::UI::CustomShell modules
3906
+ - [text-table](https://github.com/aptinio/text-table): renders textual data in a textual table for the command-line interface of Glimmer
3907
+ - [warbler](https://github.com/jruby/warbler): converts a Glimmer app into a Java JAR file during packaging
3908
+
3909
+ ## Glimmer Process
3910
+
3911
+ [Glimmer Process](https://github.com/AndyObtiva/glimmer/blob/master/PROCESS.md) is the lightweight software development process used for building Glimmer libraries and Glimmer apps, which goes beyond Agile, rendering all Agile processes obsolete. [Glimmer Process](PROCESS.md) is simply made up of 7 guidelines to pick and choose as necessary until software development needs are satisfied.
3912
+
3913
+ Learn more by reading the [GPG](https://github.com/AndyObtiva/glimmer/blob/master/PROCESS.md) (Glimmer Process Guidelines)
3914
+
3915
+ ## Resources
3916
+
3917
+ * [Code Master Blog](http://andymaleh.blogspot.com/search/label/Glimmer)
3918
+ * [JRuby Cookbook by Justin Edelson & Henry Liu](http://shop.oreilly.com/product/9780596519650.do)
3919
+ * [InfoQ Article](http://www.infoq.com/news/2008/02/glimmer-jruby-swt)
3920
+ * [DZone Tutorial](https://dzone.com/articles/an-introduction-glimmer)
3921
+ * [MountainWest RubyConf 2011 Video](https://confreaks.tv/videos/mwrc2011-whatever-happened-to-desktop-development-in-ruby)
3922
+ * [RubyConf 2008 Video](https://confreaks.tv/videos/rubyconf2008-desktop-development-with-glimmer)
35
3923
 
36
3924
  ## Help
37
3925
 
38
3926
  ### Issues
39
3927
 
40
- You may submit [issues](https://github.com/AndyObtiva/glimmer/issues) on [GitHub](https://github.com/AndyObtiva/glimmer/issues).
3928
+ You may submit [issues](https://github.com/AndyObtiva/glimmer-dsl-swt/issues) on [GitHub](https://github.com/AndyObtiva/glimmer-dsl-swt/issues).
41
3929
 
42
- [Click here to submit an issue.](https://github.com/AndyObtiva/glimmer/issues)
3930
+ [Click here to submit an issue.](https://github.com/AndyObtiva/glimmer-dsl-swt/issues)
43
3931
 
44
3932
  ### Chat
45
3933
 
46
- If you need live help, try to [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
3934
+ If you need live help, try to [![Join the chat at https://gitter.im/AndyObtiva/glimmer](https://badges.gitter.im/AndyObtiva/glimmer.svg)](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
47
3935
 
48
3936
  ## Feature Suggestions
49
3937
 
@@ -51,26 +3939,46 @@ These features have been suggested. You might see them in a future version of Gl
51
3939
 
52
3940
  [TODO.md](TODO.md)
53
3941
 
3942
+ Glimmer DSL Engine specific tasks are at:
3943
+
3944
+ [glimmer/TODO.md](https://github.com/AndyObtiva/glimmer/blob/master/TODO.md)
3945
+
54
3946
  ## Change Log
55
3947
 
56
3948
  [CHANGELOG.md](CHANGELOG.md)
57
3949
 
3950
+ Also: [glimmer/CHANGELOG.md](https://github.com/AndyObtiva/glimmer/blob/master/CHANGELOG.md)
3951
+
58
3952
  ## Contributing
59
3953
 
3954
+ **Contributors Wanted!**
3955
+
3956
+ If you would like to contribute to Glimmer, please study up on Glimmer and [SWT](#swt-reference), run all Glimmer [samples](#samples), and build a small sample app (perhaps from [this TODO list](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/TODO.md#samples)) to add to [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) Hello or Elaborate samples via a Pull Request. Once done, contact me on [Chat](#chat).
3957
+
3958
+ You may apply for contributing to any of these Glimmer DSL gems whether you prefer to focus on the desktop or web:
3959
+ - [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
3960
+ - [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
3961
+ - [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML)
3962
+ - [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets)
3963
+
60
3964
  [CONTRIBUTING.md](CONTRIBUTING.md)
61
3965
 
62
3966
  ## Contributors
63
3967
 
64
3968
  * [Andy Maleh](https://github.com/AndyObtiva) (Founder)
3969
+ * [Dennis Theisen](https://github.com/Soleone) (Contributor, originally in [Glimmer](https://github.com/AndyObtiva/glimmer/graphs/contributors) before splitting glimmer-dsl-swt)
65
3970
 
66
3971
  [Click here to view contributor commits.](https://github.com/AndyObtiva/glimmer-dsl-swt/graphs/contributors)
67
3972
 
3973
+ ## Hire Me
3974
+
3975
+ If your company would like to invest fulltime in further development of the Glimmer open-source project, [hire me](https://www.linkedin.com/in/andymaleh/).
3976
+
68
3977
  ## License
69
3978
 
70
- [MIT](https://opensource.org/licenses/MIT)
3979
+ [MIT](LICENSE.txt)
71
3980
 
72
- Copyright (c) 2020 - Andy Maleh.
73
- See [LICENSE.txt](LICENSE.txt) for further details.
3981
+ Copyright (c) 2007-2020 - Andy Maleh.
74
3982
 
75
3983
  --
76
3984