glimmer 0.10.0 → 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (24) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +361 -0
  3. data/CONTRIBUTING.md +62 -0
  4. data/LICENSE.txt +1 -1
  5. data/PROCESS.md +35 -0
  6. data/README.md +550 -2831
  7. data/VERSION +1 -1
  8. data/lib/glimmer.rb +30 -19
  9. data/lib/glimmer/config.rb +42 -5
  10. data/lib/glimmer/data_binding/model_binding.rb +37 -27
  11. data/lib/glimmer/data_binding/observable.rb +21 -0
  12. data/lib/glimmer/data_binding/observable_array.rb +229 -30
  13. data/lib/glimmer/data_binding/observable_model.rb +43 -20
  14. data/lib/glimmer/data_binding/observer.rb +25 -6
  15. data/lib/glimmer/dsl/engine.rb +68 -60
  16. data/lib/glimmer/dsl/expression.rb +21 -0
  17. data/lib/glimmer/dsl/expression_handler.rb +23 -3
  18. data/lib/glimmer/dsl/parent_expression.rb +21 -0
  19. data/lib/glimmer/dsl/static_expression.rb +21 -0
  20. data/lib/glimmer/dsl/top_level_expression.rb +21 -0
  21. data/lib/glimmer/error.rb +21 -0
  22. data/lib/glimmer/invalid_keyword_error.rb +21 -0
  23. metadata +44 -18
  24. data/lib/glimmer/excluded_keyword_error.rb +0 -5
data/README.md CHANGED
@@ -1,29 +1,72 @@
1
- # <img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 style="position: relative; top: 20px;" /> Glimmer (Ruby Desktop Development GUI Library)
1
+ # [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 style="position: relative; top: 20px;" />](https://rubygems.org/gems/glimmer) Glimmer 1.0.0
2
2
  [![Gem Version](https://badge.fury.io/rb/glimmer.svg)](http://badge.fury.io/rb/glimmer)
3
3
  [![Travis CI](https://travis-ci.com/AndyObtiva/glimmer.svg?branch=master)](https://travis-ci.com/github/AndyObtiva/glimmer)
4
4
  [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/glimmer/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/glimmer?branch=master)
5
+ [![Maintainability](https://api.codeclimate.com/v1/badges/38fbc278022862794414/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer/maintainability)
5
6
  [![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)
6
7
 
7
8
  **[Contributors Wanted! (Submit a Glimmer App Sample to Get Started)](#contributing)**
8
9
 
9
10
  (The Original Glimmer Library Since 2007. Beware of Imitators!)
10
11
 
11
- 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.
12
+ [**Glimmer**](https://rubygems.org/gems/glimmer) is a Ruby DSL engine with support for the following DSLs:
13
+ - [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop Development GUI Library)
14
+ - [glimmer-dsl-tk](https://github.com/AndyObtiva/glimmer-dsl-tk): Glimmer DSL for Tk (Ruby Desktop Development GUI Library)
15
+ - [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
16
+ - [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
18
+
19
+ [Glimmer and/or Glimmer DSLs receive two updates per month](https://rubygems.org/gems/glimmer-dsl-swt/versions). You can trust [Glimmer](https://rubygems.org/gems/glimmer) with your Ruby development needs.
12
20
 
13
21
  [<img src="https://covers.oreillystatic.com/images/9780596519650/lrg.jpg" width=105 /><br />
14
22
  Featured in<br />JRuby Cookbook](http://shop.oreilly.com/product/9780596519650.do)
15
23
 
16
- Glimmer DSL gems:
17
- - [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
18
- - [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
19
- - [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML)
20
- - [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS
24
+ ## Table of contents
25
+
26
+ - [Glimmer 1.0.0](#-glimmer-100)
27
+ - [Glimmer DSL for SWT (JRuby Desktop Development GUI Library)](#glimmer-dsl-for-swt-jruby-desktop-development-gui-library)
28
+ - [Glimmer DSL for SWT Samples](#glimmer-dsl-for-swt-samples)
29
+ - [Hello, World!](#hello-world)
30
+ - [Tic Tac Toe](#tic-tac-toe)
31
+ - [Contact Manager](#contact-manager)
32
+ - [Production Desktop Apps Built with Glimmer DSL for SWT](#production-desktop-apps-built-with-glimmer-dsl-for-swt)
33
+ - [Glimmer DSL for Tk (Ruby Desktop Development GUI Library)](#glimmer-dsl-for-tk-ruby-desktop-development-gui-library)
34
+ - [Glimmer DSL for Tk Samples](#glimmer-dsl-for-tk-samples)
35
+ - [Hello, World!](#hello-world)
36
+ - [Hello, Tab!](#hello-tab)
37
+ - [Hello, Combo!](#hello-combo)
38
+ - [Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)](#glimmer-dsl-for-opal-web-gui-adapter-for-desktop-apps)
39
+ - [Glimmer DSL for Opal Samples](#glimmer-dsl-for-opal-samples)
40
+ - [Hello, Computed!](#hello-computed)
41
+ - [Hello, List Single Selection!](#hello-list-single-selection)
42
+ - [Hello, List Multi Selection!](#hello-list-multi-selection)
43
+ - [Glimmer DSL for XML (& HTML)](#glimmer-dsl-for-xml--html)
44
+ - [XML DSL](#xml-dsl)
45
+ - [Glimmer DSL for CSS](#glimmer-dsl-for-css)
46
+ - [CSS DSL](#css-dsl)
47
+ - [Multi-DSL Support](#multi-dsl-support)
48
+ - [Glimmer Supporting Libraries](#glimmer-supporting-libraries)
49
+ - [Glimmer Process](#glimmer-process)
50
+ - [Resources](#resources)
51
+ - [Help](#help)
52
+ - [Issues](#issues)
53
+ - [Chat](#chat)
54
+ - [Feature Suggestions](#feature-suggestions)
55
+ - [Change Log](#change-log)
56
+ - [Contributing](#contributing)
57
+ - [Contributors](#contributors)
58
+ - [Hire Me](#hire-me)
59
+ - [License](#license)
60
+
61
+ ## Glimmer DSL for SWT (JRuby Desktop Development GUI Library)
21
62
 
22
- ## Examples
63
+ [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) 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](https://github.com/AndyObtiva/glimmer-dsl-swt#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 DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) additionally innovates by having built-in [data-binding](https://github.com/AndyObtiva/glimmer-dsl-swt#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 DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) offers [scaffolding](https://github.com/AndyObtiva/glimmer-dsl-swt#scaffolding) options for [Apps](https://github.com/AndyObtiva/glimmer-dsl-swt#in-production), [Gems](https://github.com/AndyObtiva/glimmer-dsl-swt#custom-shell-gem), and [Custom Widgets](https://github.com/AndyObtiva/glimmer-dsl-swt#custom-widgets). [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) also includes native-executable [packaging](https://github.com/AndyObtiva/glimmer-dsl-swt#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).
23
64
 
24
- ### Hello, World!
65
+ ### Glimmer DSL for SWT Samples
25
66
 
26
- Glimmer code (from `samples/hello/hello_world.rb`):
67
+ #### Hello, World!
68
+
69
+ Glimmer code (from [samples/hello/hello_world.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_world.rb)):
27
70
  ```ruby
28
71
  include Glimmer
29
72
 
@@ -37,3004 +80,680 @@ shell {
37
80
 
38
81
  Run:
39
82
  ```
40
- glimmer samples/hello/hello_world.rb
83
+ glimmer sample:run[hello_world]
41
84
  ```
42
85
 
43
86
  Glimmer app:
44
87
 
45
88
  ![Hello World](images/glimmer-hello-world.png)
46
89
 
47
- ### Tic Tac Toe
90
+ #### Tic Tac Toe
48
91
 
49
- Glimmer code (from `samples/elaborate/tic_tac_toe.rb`):
92
+ Glimmer code (from [samples/elaborate/tic_tac_toe.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/tic_tac_toe.rb)):
50
93
 
51
94
  ```ruby
52
95
  # ...
53
- shell {
54
- text "Tic-Tac-Toe"
55
- composite {
56
- grid_layout 3, true
57
- (1..3).each { |row|
58
- (1..3).each { |column|
59
- button {
60
- layout_data :fill, :fill, true, true
61
- text bind(@tic_tac_toe_board[row, column], :sign)
62
- enabled bind(@tic_tac_toe_board[row, column], :empty)
63
- on_widget_selected {
64
- @tic_tac_toe_board.mark(row, column)
96
+ @tic_tac_toe_board = Board.new
97
+
98
+ @shell = shell {
99
+ text "Tic-Tac-Toe"
100
+ minimum_size 150, 178
101
+ composite {
102
+ grid_layout 3, true
103
+ (1..3).each { |row|
104
+ (1..3).each { |column|
105
+ button {
106
+ layout_data :fill, :fill, true, true
107
+ text bind(@tic_tac_toe_board[row, column], :sign)
108
+ enabled bind(@tic_tac_toe_board[row, column], :empty)
109
+ font style: :bold, height: 20
110
+ on_widget_selected {
111
+ @tic_tac_toe_board.mark(row, column)
112
+ }
113
+ }
65
114
  }
66
115
  }
67
116
  }
68
117
  }
69
- }
70
- }
118
+
119
+ observe(@tic_tac_toe_board, :game_status) { |game_status|
120
+ display_win_message if game_status == Board::WIN
121
+ display_draw_message if game_status == Board::DRAW
122
+ }
71
123
  # ...
72
124
  ```
73
125
 
74
126
  Run:
75
127
 
76
128
  ```
77
- glimmer samples/elaborate/tic_tac_toe.rb
129
+ glimmer sample:run[tic_tac_toe]
78
130
  ```
79
131
 
80
132
  Glimmer app:
81
133
 
82
134
  ![Tic Tac Toe](images/glimmer-tic-tac-toe-in-progress.png)
83
135
 
84
- NOTE: Glimmer is in beta mode. Please help make better by [contributing](#contributing), adopting for small or low risk projects, and providing feedback.
85
-
86
- ## Table of contents
87
-
88
- - [Glimmer (Ruby Desktop Development GUI Library)](#-glimmer-ruby-desktop-development-gui-library)
89
- - [Examples](#examples)
90
- - [Hello, World!](#hello-world)
91
- - [Tic Tac Toe](#tic-tac-toe)
92
- - [Background](#background)
93
- - [Platform Support](#platform-support)
94
- - [Pre-requisites](#pre-requisites)
95
- - [Setup](#setup)
96
- - [Option 1: Direct Install](#option-1-direct-install)
97
- - [Option 2: Bundler](#option-2-bundler)
98
- - [Glimmer Command](#glimmer-command)
99
- - [Basic Usage](#basic-usage)
100
- - [Advanced Usage](#advanced-usage)
101
- - [Scaffolding](#scaffolding)
102
- - [App](#app)
103
- - [Custom Shell](#custom-shell)
104
- - [Custom Widget](#custom-widget)
105
- - [Custom Shell Gem](#custom-shell-gem)
106
- - [Custom Widget Gem](#custom-widget-gem)
107
- - [Gem Listing](#gem-listing)
108
- - [Listing Custom Shell Gems](#listing-custom-shell-gems)
109
- - [Listing Custom Widget Gems](#listing-custom-widget-gems)
110
- - [Listing DSL Gems](#listing-dsl-gems)
111
- - [Packaging](#packaging)
112
- - [Raw JRuby Command](#raw-jruby-command)
113
- - [Mac Support](#mac-support)
114
- - [Girb (Glimmer irb) Command](#girb-glimmer-irb-command)
115
- - [Glimmer DSL Syntax](#glimmer-dsl-syntax)
116
- - [Widgets](#widgets)
117
- - [Display](#display)
118
- - [SWT Proxies](#swt-proxies)
119
- - [Dialog](#dialog)
120
- - [Menus](#menus)
121
- - [ScrolledComposite](#scrolledcomposite)
122
- - [Widget Styles](#widget-styles)
123
- - [Explicit SWT Style Bit](#explicit-swt-style-bit)
124
- - [Negative SWT Style Bits](#negative-swt-style-bits)
125
- - [Extra SWT Styles](#extra-swt-styles)
126
- - [Widget Properties](#widget-properties)
127
- - [Colors](#colors)
128
- - [Fonts](#fonts)
129
- - [Layouts](#layouts)
130
- - [Layout Data](#layout-data)
131
- - [Data-Binding](#data-binding)
132
- - [General Examples](#general-examples)
133
- - [Combo](#combo)
134
- - [List](#list)
135
- - [Table](#table)
136
- - [Tree](#tree)
137
- - [Observer](#observer)
138
- - [Observing Widgets](#observing-widgets)
139
- - [Observing Models](#observing-models)
140
- - [Custom Widgets](#custom-widgets)
141
- - [Simple Example](#simple-example)
142
- - [Lifecycle Hook Example](#lifecycle-hook-example)
143
- - [Custom Widget API](#custom-widget-api)
144
- - [Content/Options Example](#contentoptions-example)
145
- - [Custom Widget Lifecycle Hooks](#custom-widget-lifecycle-hooks)
146
- - [Gotcha](#gotcha)
147
- - [Final Notes](#final-notes)
148
- - [Custom Shells](#custom-shells)
149
- - [Drag and Drop](#drag-and-drop)
150
- - [Miscellaneous](#miscellaneous)
151
- - [Multi-DSL Support](#multi-dsl-support)
152
- - [Application Menu Items (About/Preferences)](#application-menu-items-aboutpreferences)
153
- - [App Name and Version](#app-name-and-version)
154
- - [Video Widget](#video-widget)
155
- - [Browser Widget](#browser-widget)
156
- - [Glimmer Configuration](#glimmer-configuration)
157
- - [logger](#logger)
158
- - [import_swt_packages](#importswtpackages)
159
- - [loop_max_count](#loopmaxcount)
160
- - [Glimmer Style Guide](#glimmer-style-guide)
161
- - [SWT Reference](#swt-reference)
162
- - [Samples](#samples)
163
- - [Hello Samples](#hello-samples)
164
- - [Hello, World! Sample](#hello-world-sample)
165
- - [Hello, Tab!](#hello-tab)
166
- - [Hello, Combo!](#hello-combo)
167
- - [Hello, List Single Selection!](#hello-list-single-selection)
168
- - [Hello, List Multi Selection!](#hello-list-multi-selection)
169
- - [Hello, Computed!](#hello-computed)
170
- - [Hello, Message Box!](#hello-message-box)
171
- - [Hello, Browser!](#hello-browser)
172
- - [Hello, Drag and Drop!](#hello-drag-and-drop)
173
- - [Hello, Menu Bar!](#hello-menu-bar)
174
- - [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu)
175
- - [Elaborate Samples](#elaborate-samples)
176
- - [Login](#login)
177
- - [Tic Tac Toe Sample](#tic-tac-toe-sample)
178
- - [Contact Manager](#contact-manager)
179
- - [External Samples](#external-samples)
180
- - [Glimmer Calculator](#glimmer-calculator)
181
- - [Gladiator](#gladiator)
182
- - [In Production](#in-production)
183
- - [Math Bowling](#math-bowling)
184
- - [Are We There Yet?](#are-we-there-yet)
185
- - [Packaging & Distribution](#packaging--distribution)
186
- - [Packaging Defaults](#packaging-defaults)
187
- - [Packaging Configuration](#packaging-configuration)
188
- - [javapackager Extra Arguments](#javapackager-extra-arguments)
189
- - [Mac Application Distribution](#mac-application-distribution)
190
- - [Self Signed Certificate](#self-signed-certificate)
191
- - [Gotchas](#gotchas)
192
- - [Resources](#resources)
193
- - [Help](#help)
194
- - [Issues](#issues)
195
- - [Chat](#chat)
196
- - [Feature Suggestions](#feature-suggestions)
197
- - [Change Log](#change-log)
198
- - [Contributing](#contributing)
199
- - [Contributors](#contributors)
200
- - [Hire Me](#hire-me)
201
- - [License](#license)
202
-
203
- ## Background
204
-
205
- 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.
206
-
207
- ## Platform Support
208
-
209
- Glimmer runs on the following platforms:
210
- - Mac
211
- - Windows
212
- - Linux
213
-
214
- 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:
215
- - Win32 on Windows
216
- - Cocoa on Mac
217
- - GTK on Linux
218
-
219
- More info about the SWT GUI on various platforms can be found on the Eclipse WIKI and SWT FAQ:
220
-
221
- https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide#Win32.2FCocoa.2FGTK
222
- https://www.eclipse.org/swt/faq.php
223
-
224
- ## Pre-requisites
225
-
226
- - SWT 4.15 (comes included in Glimmer gem)
227
- - JRuby 9.2.12.0 (supporting Ruby 2.5.x syntax) (find at [https://www.jruby.org/download](https://www.jruby.org/download))
228
- - JDK 8 - 10 (find at [https://www.oracle.com/java/technologies/javase-downloads.html](https://www.oracle.com/java/technologies/javase-downloads.html))
229
- - (Optional) RVM is needed for [Scaffolding](#scaffolding) only (find at [https://rvm.io/](https://rvm.io/))
230
-
231
- On **Mac** and **Linux**, an easy way to obtain JRuby is through [RVM](http://rvm.io) by running:
232
-
233
- ```bash
234
- rvm install jruby-9.2.12.0
235
- ```
236
-
237
- Glimmer might still work on lower versions of Java, JRuby and SWT, but there are no guarantees, so it is best to stick to the pre-requisites outlined above.
238
-
239
- ## Setup
240
-
241
- 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.
242
-
243
- 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)).
244
-
245
- If you intend to build a Glimmer app from scratch on the Mac, pick Option 1 ([Direct Install](#option-1-direct-install)) to leverage [Glimmer Scaffolding](#scaffolding) (only available on the Mac).
246
-
247
- Otherwise, Option 2 ([Bundler](#option-2-bundler)) is recommended for building Glimmer apps on other platforms (Windows and Linux).
248
-
249
- ### Option 1: Direct Install
250
- (Use for [Scaffolding](#scaffolding) on the Mac)
251
-
252
- Run this command to install directly:
253
- ```
254
- jgem install glimmer-dsl-swt -v 0.4.1
255
- ```
256
-
257
- `jgem` is JRuby's version of `gem` command.
258
- RVM allows running `gem` as an alias.
259
- Otherwise, you may also run `jruby -S gem install ...`
260
-
261
- 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.
262
-
263
- 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.
264
-
265
- Note: if you're using activerecord or activesupport, keep in mind that Glimmer unhooks ActiveSupport::Dependencies as it does not rely on it.
266
-
267
- ### Option 2: Bundler
268
- (Use for Manual App Creation)
269
-
270
- Add the following to `Gemfile`:
271
- ```
272
- gem 'glimmer-dsl-swt', '~> 0.4.1'
273
- ```
274
-
275
- And, then run:
276
- ```
277
- jruby -S bundle install
278
- ```
279
-
280
- Note: if you're using activerecord or activesupport, keep in mind that Glimmer unhooks ActiveSupport::Dependencies as it does not rely on it.
281
-
282
- 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)
283
-
284
- ## Glimmer Command
285
-
286
- The `glimmer` command allows you to run, scaffold, package, and list Glimmer applications/gems.
287
-
288
- 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 DSL Syntax](#glimmer-dsl-syntax), and [Samples](#samples).
289
-
290
- ### Basic Usage
291
-
292
- ```
293
- glimmer application.rb
294
- ```
295
-
296
- Runs a Glimmer application using JRuby, automatically preloading
297
- the glimmer ruby gem and SWT jar dependency.
298
-
299
- Example:
300
- ```
301
- glimmer samples/hello/hello_world.rb
302
- ```
303
- This runs the Glimmer "Hello, World!" sample.
304
-
305
- If you cloned this project locally, you may run `bin/glimmer` instead.
306
-
307
- Example:
308
- ```
309
- bin/glimmer samples/hello/hello_world.rb
310
- ```
311
-
312
- ### Advanced Usage
313
-
314
- Below are the full usage instructions that come up when running `glimmer` without args.
315
-
316
- ```
317
- Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
318
-
319
- Runs Glimmer applications/tasks.
320
-
321
- Either a single task or one or more applications may be specified.
322
-
323
- When a task is specified, it runs via rake. Some tasks take arguments in square brackets.
324
-
325
- Available tasks are below (you may also lookup by adding `require 'glimmer/rake_task'` in Rakefile and running rake -T):
326
- glimmer list:custom_shell_gems[query] # List Glimmer custom shell gems available at rubygems.org (query is optional)
327
- glimmer list:custom_widget_gems[query] # List Glimmer custom widget gems available at rubygems.org (query is optional)
328
- glimmer list:dsl_gems[query] # List Glimmer DSL gems available at rubygems.org (query is optional)
329
- glimmer package # Package app for distribution (generating config, jar, and native files)
330
- glimmer package:clean # Clean by removing "dist" and "packages" directories
331
- glimmer package:config # Generate JAR config file
332
- glimmer package:jar # Generate JAR file
333
- glimmer package:native # Generate Native files (DMG/PKG/APP on the Mac)
334
- glimmer scaffold[app_name] # Scaffold a Glimmer application directory structure to begin building a new app
335
- glimmer scaffold:custom_shell[custom_shell_name,namespace] # Scaffold a Glimmer::UI::CustomShell subclass (represents a full window view) under app/views (namespace is optional)
336
- glimmer scaffold:custom_shell_gem[custom_shell_name,namespace] # Scaffold a Glimmer::UI::CustomShell subclass (represents a full window view) under its own Ruby gem + app project (namespace is required)
337
- glimmer scaffold:custom_widget[custom_widget_name,namespace] # Scaffold a Glimmer::UI::CustomWidget subclass (represents a part of a view) under app/views (namespace is optional)
338
- glimmer scaffold:custom_widget_gem[custom_widget_name,namespace] # Scaffold a Glimmer::UI::CustomWidget subclass (represents a part of a view) under its own Ruby gem project (namespace is required)
339
-
340
- When applications are specified, they are run using JRuby,
341
- automatically preloading the glimmer Ruby gem and SWT jar dependency.
342
-
343
- Optionally, extra Glimmer options, JRuby options and environment variables may be passed in.
344
-
345
- Glimmer options:
346
- - "--quiet" : Does not announce file path of Glimmer application being launched
347
- - "--debug" : Displays extra debugging information, passes "--debug" to JRuby, and enables debug logging
348
- - "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
349
-
350
- Example: glimmer samples/hello_world.rb
351
-
352
- This runs the Glimmer application samples/hello_world.rb
353
- ```
354
-
355
- Example (Glimmer/JRuby option specified):
356
- ```
357
- glimmer --debug samples/hello/hello_world.rb
358
- ```
359
-
360
- Runs Glimmer application with JRuby debug option to enable JRuby debugging.
361
-
362
- Example (Multiple apps):
363
- ```
364
- glimmer samples/hello/hello_world.rb samples/hello_tab.rb
365
- ```
366
-
367
- Launches samples/hello/hello_world.rb and samples/hello_tab.rb at the same time, each in a separate JRuby thread.
368
-
369
- ### Scaffolding
370
-
371
- Glimmer borrows from Rails the idea of Scaffolding, that is generating a structure for your app files that
372
- helps you get started just like true building scaffolding helps construction workers, civil engineers, and architects.
373
-
374
- Glimmer scaffolding goes beyond just scaffolding the app files that Rails does. It also packages it and launches it,
375
- getting you to a running and delivered state of an advanced "Hello, World!" Glimmer application right off the bat.
376
-
377
- This should greatly facilitate building a new Glimmer app by helping you be productive and focus on app details while
378
- letting Glimmer scaffolding take care of initial app file structure concerns, such as adding:
379
- - Main application class that includes Glimmer
380
- - Main application view that houses main window content, about dialog, and preferences dialog
381
- - View and Model directories
382
- - Rakefile including Glimmer tasks
383
- - Version
384
- - License
385
- - Icon
386
- - Bin file for starting application
387
-
388
- NOTE: Scaffolding requires RVM and currently supports Mac packaging only at the moment.
389
-
390
- #### App
391
-
392
- Before you start, make sure you are in a JRuby environment with Glimmer gem installed as per "Direct Install" pre-requisites.
393
-
394
- To scaffold a Glimmer app from scratch, run the following command:
395
-
396
- ```
397
- glimmer scaffold[AppName]
398
- ```
399
-
400
- 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.
401
-
402
- Suppose you run:
403
-
404
- ```
405
- glimmer scaffold[CarMaker]
406
- ```
407
-
408
- You should see output like the following:
409
-
410
- ```
411
- Created CarMaker/.ruby-version
412
- Created CarMaker/.ruby-gemset
413
- Created CarMaker/VERSION
414
- Created CarMaker/LICENSE.txt
415
- Created CarMaker/Gemfile
416
- Created CarMaker/Rakefile
417
- Created CarMaker/app/car_maker.rb
418
- Created CarMaker/app/views/car_maker/app_view.rb
419
- Created CarMaker/package/macosx/Car Maker.icns
420
- Created CarMaker/bin/car_maker
421
- ...
422
- ```
423
-
424
- Eventually, it will launch an advanced "Hello, World!" app window having the title of your application and a Mac icon.
425
-
426
- ![Glimmer Scaffold App](images/glimmer-scaffolding-app.png)
427
-
428
- On the Mac, it also comes with a boilerplate Preferences dialog.
429
-
430
- ![Glimmer Scaffold App Preferences](images/glimmer-scaffolding-app-preferences.png)
431
-
432
- #### Custom Shell
433
-
434
- To scaffold a Glimmer custom shell (full window view) for an existing Glimmer app, run the following command:
435
-
436
- ```
437
- glimmer scaffold:custom_shell[custom_shell_name]
438
- ```
439
-
440
- #### Custom Widget
441
-
442
- To scaffold a Glimmer custom widget (part of a view) for an existing Glimmer app, run the following command:
443
-
444
- ```
445
- glimmer scaffold:custom_widget[custom_widget_name]
446
- ```
447
-
448
- #### Custom Shell Gem
449
-
450
- Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
451
- They have everything scaffolded Glimmer apps come with in addition to gem content like a Jeweler Rakefile that can build gemspec and release gems.
452
- Unlike scaffolded Glimmer apps, custom shell gem content lives under the `lib` directory (not `app`).
453
- They can be packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem.
454
- Of course, you can just build a Ruby gem and disregard native executable packaging if you do not need it.
455
-
456
- To scaffold a Glimmer custom shell gem (full window view distributed as a Ruby gem), run the following command:
457
-
458
- ```
459
- glimmer scaffold:custom_shell_gem[custom_shell_name, namespace]
460
- ```
461
-
462
- It is important to specify a namespace to avoid having your gem clash with existing gems.
463
-
464
- The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell).
465
-
466
- 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)
467
-
468
- Examples:
469
-
470
- - [glimmer-cs-gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator): Gladiator (Glimmer Editor)
471
- - [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator): Glimmer Calculator
472
-
473
- #### Custom Widget Gem
474
-
475
- To scaffold a Glimmer custom widget gem (part of a view distributed as a Ruby gem), run the following command:
476
-
477
- ```
478
- glimmer scaffold:custom_widget_gem[custom_widget_name, namespace]
479
- ```
480
-
481
- It is important to specify a namespace to avoid having your gem clash with existing gems.
482
-
483
- The Ruby gem name will follow the convention "glimmer-cw-customwidgetname-namespace" (the 'cw' is for Custom Widget)
484
-
485
- 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)
486
-
487
- Examples:
488
-
489
- - [glimmer-cw-video](https://github.com/AndyObtiva/glimmer-cw-video): Video Widget
490
- - [glimmer-cw-cdatetime-nebula](https://github.com/AndyObtiva/glimmer-cw-cdatetime-nebula): Nebula CDateTime Widget
491
-
492
- ### Gem Listing
493
-
494
- 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).
495
-
496
- #### Listing Custom Shell Gems
497
-
498
- 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):
499
-
500
- ```
501
- glimmer list:custom_shell_gems[query] # List Glimmer custom shell gems available at rubygems.org (query is optional)
502
- ```
503
-
504
- Example:
505
-
506
- ```
507
- glimmer list:custom_shell_gems
508
- ```
509
-
510
- Output:
511
-
512
- ```
513
-
514
- Glimmer Custom Shell Gems at rubygems.org:
515
-
516
- Name Gem Version Author Description
517
-
518
- Calculator glimmer-cs-calculator 1.0.1 Andy Maleh Calculator - Glimmer Custom Shell
519
- Gladiator glimmer-cs-gladiator 0.2.0 Andy Maleh Gladiator (Glimmer Editor) - Glimmer Custom Shell
520
-
521
- ```
522
-
523
- #### Listing Custom Widget Gems
524
-
525
- 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):
526
-
527
- ```
528
- glimmer list:custom_widget_gems[query] # List Glimmer custom widget gems available at rubygems.org (query is optional)
529
- ```
530
-
531
- Example:
532
-
533
- Check if there is a custom video widget for Glimmer.
534
-
535
- ```
536
- glimmer list:custom_widget_gems[video]
537
- ```
538
-
539
- Output:
540
-
541
- ```
542
-
543
- Glimmer Custom Widget Gems matching [video] at rubygems.org:
544
-
545
- Name Gem Version Author Description
546
-
547
- Video glimmer-cw-video 0.1.1 Andy Maleh Glimmer Custom Widget - Video
548
-
549
- ```
550
-
551
- #### Listing DSL Gems
552
-
553
- 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):
554
-
555
- ```
556
- glimmer list:dsl_gems[query] # List Glimmer DSL gems available at rubygems.org (query is optional)
557
- ```
558
-
559
- Example:
560
-
561
- ```
562
- glimmer list:dsl_gems
563
- ```
564
-
565
- Output:
566
-
567
- ```
568
-
569
- Glimmer DSL Gems at rubygems.org:
570
-
571
- Name Gem Version Author Description
572
-
573
- Css glimmer-dsl-css 0.1.0 AndyMaleh Glimmer DSL for CSS
574
- Opal glimmer-dsl-opal 0.0.9 AndyMaleh Glimmer DSL for Opal
575
- Swt glimmer-dsl-swt 0.4.1 AndyMaleh Glimmer DSL for SWT
576
- Xml glimmer-dsl-xml 0.1.0 AndyMaleh Glimmer DSL for XML
577
-
578
- ```
579
-
580
- ### Packaging
581
-
582
- Glimmer packaging tasks are detailed under [Packaging & Distribution](#packaging--distribution).
583
-
584
- ### Raw JRuby Command
585
-
586
- If there is a need to run Glimmer directly via the `jruby` command, you
587
- may run the following:
588
-
589
- ```
590
- jruby -J-classpath "path_to/swt.jar" -r glimmer -S application.rb
591
- ```
592
-
593
- The `-J-classpath` option specifies the `swt.jar` file path, which can be a
594
- 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.
595
-
596
- The `-r` option preloads (requires) the `glimmer` library in Ruby.
597
-
598
- The `-S` option specifies a script to run.
599
-
600
- #### Mac Support
601
-
602
- The Mac is well supported with the `glimmer` command. The advice below is not needed if you are using it.
603
-
604
- 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).
605
-
606
- Example:
607
- ```
608
- jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer -S application.rb
609
- ```
610
-
611
- ## Girb (Glimmer irb) Command
136
+ #### Contact Manager
612
137
 
613
- 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.
614
-
615
- ```
616
- girb
617
- ```
618
-
619
- If you cloned [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt) project locally, you may run `bin/girb` instead.
620
-
621
- ```
622
- bin/girb
623
- ```
624
-
625
- Watch out for hands-on examples in this README indicated by "you may copy/paste in [`girb`](#girb-glimmer-irb-command)"
626
-
627
- Keep in mind that all samples live under [https://github.com/AndyObtiva/glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt)
628
-
629
- ## Glimmer DSL Syntax
630
-
631
- Glimmer DSL syntax consists of static keywords and dynamic keywords to build and bind user-interface objects.
632
-
633
- Static keywords are pre-identified keywords in the Glimmer DSL, such as `shell`, `message_box`, `async_exec`, and `bind`.
634
-
635
- Dynamic keywords are dynamically figured out from available SWT widgets, custom widgets, and properties. Examples are: `label`, `combo`, and `list`.
636
-
637
- 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.
638
-
639
- For example, if a project adds this custom Java SWT library:
640
-
641
- https://www.eclipse.org/nebula/widgets/cdatetime/cdatetime.php?page=operation
642
-
643
- Glimmer will automatically support using the keyword `c_date_time`
644
-
645
- You will learn more about widgets next.
646
-
647
- ### Widgets
648
-
649
- Glimmer GUIs (user interfaces) are modeled with widgets, which are wrappers around the SWT library widgets found here:
650
-
651
- https://www.eclipse.org/swt/widgets/
652
-
653
- This screenshot taken from the link above should give a glimpse of how SWT widgets look and feel:
654
-
655
- ![SWT Widgets](images/glimmer-swt-widgets.png)
656
-
657
- In Glimmer DSL, widgets are declared with lowercase underscored names mirroring their SWT names minus the package name:
658
-
659
- - `shell` instantiates `org.eclipse.swt.widgets.Shell`
660
- - `text` instantiates `org.eclipse.swt.widgets.Text`
661
- - `button` instantiates `org.eclipse.swt.widgets.Button`
662
- - `label` instantiates `org.eclipse.swt.widgets.Label`
663
- - `composite` instantiates `org.eclipse.swt.widgets.Composite`
664
- - `tab_folder` instantiates `org.eclipse.swt.widgets.TabFolder`
665
- - `tab_item` instantiates `org.eclipse.swt.widgets.TabItem`
666
- - `table` instantiates `org.eclipse.swt.widgets.Table`
667
- - `table_column` instantiates `org.eclipse.swt.widgets.TableColumn`
668
- - `tree` instantiates `org.eclipse.swt.widgets.Tree`
669
- - `combo` instantiates `org.eclipse.swt.widgets.Combo`
670
- - `list` instantiates `org.eclipse.swt.widgets.List`
671
-
672
- Every **widget** is sufficiently declared by name, but may optionally be accompanied with:
673
- - SWT **style** ***argument*** wrapped by parenthesis according to [Glimmer Style Guide](#glimmer-style-guide) (see [next section](#widget-styles) for details).
674
- - Ruby block containing **properties** (widget attributes) and **content** (nested widgets)
675
-
676
- For example, if we were to revisit `samples/hello/hello_world.rb` above (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
677
-
678
- ```ruby
679
- shell {
680
- text "Glimmer"
681
- label {
682
- text "Hello, World!"
683
- }
684
- }.open
685
- ```
686
-
687
- Note that `shell` instantiates the outer shell **widget**, in other words, the window that houses all of the desktop graphical user interface.
688
-
689
- `shell` is then followed by a ***block*** that contains
138
+ Glimmer code (from [samples/elaborate/contact_manager.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/contact_manager.rb)):
690
139
 
691
140
  ```ruby
692
141
  # ...
693
- text "Glimmer" # text property of shell
694
- label { # label widget declaration as content of shell
695
- text "Hello, World!" # text property of label
696
- }
697
- # ...
698
- ```
699
-
700
- 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).
701
-
702
- The second line declares the `label` **widget**, which is followed by a Ruby **content** ***block*** that contains its `text` **property** with value `"Hello, World!"`
703
-
704
- 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.
705
-
706
- Example:
707
-
708
- ```ruby
709
- shell {|shell_proxy|
710
- #...
711
- }
712
- ```
713
-
714
- Remember that The `shell` widget is always the outermost widget containing all others in a Glimmer desktop windowed application.
715
-
716
- 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)
717
-
718
- ```ruby
719
- @shell = shell {
720
- # properties and content
721
- # ...
722
- }
723
- @shell.open
724
- ```
725
-
726
- 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)
727
-
728
- Check out the [samples](samples) directory for more examples.
729
-
730
- Example from [hello_tab.rb](samples/hello/hello_tab.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
731
-
732
- ![Hello Tab English](images/glimmer-hello-tab-english.png)
733
-
734
- ![Hello Tab French](images/glimmer-hello-tab-french.png)
735
-
736
- ```ruby
737
- shell {
738
- text "Hello, Tab!"
739
- tab_folder {
740
- tab_item {
741
- text "English"
742
- label {
743
- text "Hello, World!"
744
- }
745
- }
746
- tab_item {
747
- text "French"
748
- label {
749
- text "Bonjour Univers!"
750
- }
751
- }
752
- }
753
- }.open
754
- ```
755
-
756
- #### Display
757
-
758
- SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage GUI globally
759
- and access available monitors.
760
- It is automatically instantiated upon first instantiation of a `shell` widget.
761
- Alternatively, for advanced use cases, it can be created explicitly with Glimmer `display` keyword. When a `shell` is later declared, it
762
- automatically uses the display created earlier without having to explicitly hook it.
763
-
764
- ```ruby
765
- @display = display {
766
- cursor_location 300, 300
767
- on_swt_keydown {
768
- # ...
769
- }
770
- # ...
771
- }
772
- @shell = shell { # uses display created above
773
- }
774
- ```
775
- The benefit of instantiating an SWT Display explicitly is to set [Properties](#widget-properties) or [Observers](#observer).
776
- Although SWT Display is not technically a widget, it has similar APIs in SWT and similar DSL support in Glimmer.
777
-
778
- #### SWT Proxies
779
-
780
- Glimmer follows Proxy Design Pattern by having Ruby proxy wrappers for all SWT objects:
781
- - `Glimmer::SWT:WidgetProxy` wraps all descendants of `org.eclipse.swt.widgets.Widget` except the ones that have their own wrappers.
782
- - `Glimmer::SWT::ShellProxy` wraps `org.eclipse.swt.widgets.Shell`
783
- - `Glimmer::SWT:TabItemProxy` wraps `org.eclipse.swt.widget.TabItem` (also adds a composite to enable adding content under tab items directly in Glimmer)
784
- - `Glimmer::SWT:LayoutProxy` wraps all descendants of `org.eclipse.swt.widget.Layout`
785
- - `Glimmer::SWT:LayoutDataProxy` wraps all layout data objects
786
- - `Glimmer::SWT:DisplayProxy` wraps `org.eclipse.swt.widget.Display` (manages displaying GUI)
787
- - `Glimmer::SWT:ColorProxy` wraps `org.eclipse.swt.graphics.Color`
788
- - `Glimmer::SWT:FontProxy` wraps `org.eclipse.swt.graphics.Font`
789
- - `Glimmer::SWT::WidgetListenerProxy` wraps all widget listeners
790
-
791
- These proxy objects have an API and provide some convenience methods, some of which are mentioned below.
792
-
793
- ##### `#content { ... }`
794
-
795
- Glimmer allows re-opening any widget and adding properties or extra content after it has been constructed already by using the `#content` method.
796
-
797
- Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
798
-
799
- ```ruby
800
- @shell = shell {
801
- text "Application"
802
- row_layout
803
- @label1 = label {
804
- text "Hello,"
805
- }
806
- }
807
- @shell.content {
808
- minimum_size 130, 130
809
- label {
810
- text "World!"
811
- }
812
- }
813
- @label1.content {
814
- foreground :red
815
- }
816
- @shell.open
817
- ```
818
-
819
- ##### `message_box`
820
-
821
- 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.
822
-
823
- Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
824
-
825
- ```ruby
826
- include Glimmer
827
-
828
- @shell = shell {
829
- text 'Hello, Message Box!'
830
- button {
831
- text 'Please Click To Win a Surprise'
832
- on_widget_selected {
833
- message_box(@shell) {
834
- text 'Surprise'
835
- message "Congratulations!\n\nYou have won $1,000,000!"
836
- }.open
837
- }
838
- }
839
- }
840
- @shell.open
841
- ```
842
-
843
- ##### `#swt_widget`
844
-
845
- 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.
846
-
847
- ##### Shell widget proxy methods
848
-
849
- Shell widget proxy has extra methods specific to SWT Shell:
850
- - `#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.
851
- - `#show`: Alias for `#open`
852
- - `#hide`: Hides a shell setting "visible" property to false
853
- - `#close`: Closes the shell
854
- - `#center`: Centers the shell within monitor it is in
855
- - `#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.
856
- - `#visible?`: Returns whether a shell is visible
857
- - `#opened_before?`: Returns whether a shell has been opened at least once before (additionally implying the SWT Event Loop has been started already)
858
- - `#visible=`: Setting to true opens/shows shell. Setting to false hides the shell.
859
- - `#pack`: Packs contained widgets using SWT's `Shell#pack` method
860
- - `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
861
-
862
- #### Dialog
863
-
864
- 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.
865
-
866
- 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.
867
-
868
- #### Menus
869
-
870
- Glimmer DSL provides support for SWT Menu and MenuItem widgets.
871
-
872
- There are 2 main types of menus in SWT:
873
- - Menu Bar (shows up on top)
874
- - Pop Up Context Menu (shows up when right-clicking a widget)
875
-
876
- Underneath both types, there can be a 3rd menu type called Drop Down.
877
-
878
- 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.
879
-
880
- The ampersand symbol indicates the keyboard shortcut key for the menu item (e.g. '&Help' can be triggered on Windows by hitting ALT+H)
881
-
882
- Example of a Menu Bar (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
883
-
884
- ```ruby
885
- shell { |shell_proxy|
886
- text 'Hello, Menu Bar!'
887
- grid_layout
888
- label(:center) {
889
- font height: 16
890
- text 'Check Out The File Menu and History Menu in The Menu Bar Above!'
891
- }
892
- menu_bar {
893
- menu {
894
- text '&File'
895
- menu_item {
896
- text 'E&xit'
897
- }
898
- menu_item(0) {
899
- text '&New'
900
- on_widget_selected {
901
- message_box(shell_proxy) {
902
- text 'New File'
903
- message 'New File Contents'
904
- }.open
905
- }
906
- }
907
- menu(1) {
908
- text '&Options'
909
- menu_item(:radio) {
910
- text 'Option 1'
911
- }
912
- menu_item(:separator)
913
- menu_item(:check) {
914
- text 'Option 3'
915
- }
916
- }
917
- }
918
- menu {
919
- text '&History'
920
- menu {
921
- text '&Recent'
922
- menu_item {
923
- text 'File 1'
924
- on_widget_selected {
925
- message_box(shell_proxy) {
926
- text 'File 1'
927
- message 'File 1 Contents'
928
- }.open
142
+ shell {
143
+ text "Contact Manager"
144
+ composite {
145
+ group {
146
+ grid_layout(2, false) {
147
+ margin_width 0
148
+ margin_height 0
929
149
  }
930
- }
931
- menu_item {
932
- text 'File 2'
933
- on_widget_selected {
934
- message_box(shell_proxy) {
935
- text 'File 2'
936
- message 'File 2 Contents'
937
- }.open
150
+ layout_data :fill, :center, true, false
151
+ text 'Lookup Contacts'
152
+ font height: 24
153
+
154
+ label {
155
+ layout_data :right, :center, false, false
156
+ text "First &Name: "
157
+ font height: 16
938
158
  }
939
- }
940
- }
941
- }
942
- }
943
- }.open
944
- ```
945
-
946
- Example of a Pop Up Context Menu (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
947
-
948
- ```ruby
949
- shell { |shell_proxy|
950
- text 'Hello, Pop Up Context Menu!'
951
- grid_layout
952
- label {
953
- font height: 16
954
- text 'Right-Click To Pop Up a Context Menu'
955
- menu {
956
- menu {
957
- text '&History'
958
- menu {
959
- text '&Recent'
960
- menu_item {
961
- text 'File 1'
962
- on_widget_selected {
963
- message_box(shell_proxy) {
964
- text 'File 1'
965
- message 'File 1 Contents'
966
- }.open
159
+ text {
160
+ layout_data :fill, :center, true, false
161
+ text bind(@contact_manager_presenter, :first_name)
162
+ on_key_pressed {|key_event|
163
+ @contact_manager_presenter.find if key_event.keyCode == swt(:cr)
967
164
  }
968
165
  }
969
- menu_item {
970
- text 'File 2'
971
- on_widget_selected {
972
- message_box(shell_proxy) {
973
- text 'File 2'
974
- message 'File 2 Contents'
975
- }.open
166
+
167
+ label {
168
+ layout_data :right, :center, false, false
169
+ text "&Last Name: "
170
+ font height: 16
171
+ }
172
+ text {
173
+ layout_data :fill, :center, true, false
174
+ text bind(@contact_manager_presenter, :last_name)
175
+ on_key_pressed {|key_event|
176
+ @contact_manager_presenter.find if key_event.keyCode == swt(:cr)
976
177
  }
977
178
  }
978
- }
979
- }
980
- }
981
- }
982
- }.open
983
- ```
984
-
985
- #### ScrolledComposite
986
-
987
- Glimmer provides smart defaults for the `scrolled_composite` widget by:
988
- - Automatically setting the nested widget as its content (meaning use can just like a plain old `composite` to add scrolling)
989
- - 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 )
990
- - Automatically setting the expand horizontal and expand vertical SWT properties to `true`
991
-
992
- ### Widget Styles
993
-
994
- SWT widgets receive `SWT` styles in their constructor as per this guide:
995
-
996
- https://wiki.eclipse.org/SWT_Widget_Style_Bits
997
-
998
- 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`).
999
-
1000
- These styles customize widget look, feel, and behavior.
1001
-
1002
- Example:
1003
-
1004
- ```ruby
1005
- # ...
1006
- list(:multi) { # SWT styles go inside ()
1007
- # ...
1008
- }
1009
- # ...
1010
- ```
1011
- Passing `:multi` to `list` widget enables list element multi-selection.
1012
-
1013
- ```ruby
1014
- # ...
1015
- composite(:border) { # SWT styles go inside ()
1016
- # ...
1017
- }
1018
- # ...
1019
- ```
1020
- Passing `:border` to `composite` widget ensures it has a border.
1021
-
1022
- When you need to pass in **multiple SWT styles**, simply separate by commas.
1023
-
1024
- Example:
1025
-
1026
- ```ruby
1027
- # ...
1028
- text(:center, :border) { # Multiple SWT styles separated by comma
1029
- # ...
1030
- }
1031
- # ...
1032
- ```
1033
-
1034
- 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):
1035
-
1036
- - `text(:border)`
1037
- - `table(:border)`
1038
- - `tree(:border, :virtual, :v_scroll, :h_scroll)`
1039
- - `spinner(:border)`
1040
- - `list(:border, :v_scroll)`
1041
- - `button(:push)`
1042
-
1043
- You may check out all available `SWT` styles here:
1044
-
1045
- https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
1046
-
1047
- #### Explicit SWT Style Bit
1048
-
1049
- 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`.
1050
-
1051
- 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.
1052
- Example:
1053
-
1054
- ```ruby
1055
- style = swt(:border, :v_scroll)
1056
- ```
1057
-
1058
- #### Negative SWT Style Bits
1059
-
1060
- In rare occasions, you might need to apply & with a negative (not) style bit to negate it from another style bit that includes it.
1061
- Glimmer facilitates that by declaring the negative style bit via postfixing a symbol with `!`.
1062
-
1063
- Example:
1064
-
1065
- ```ruby
1066
- style = swt(:shell_trim, :max!) # creates a shell trim style without the maximize button (negated)
1067
- ```
1068
-
1069
- #### Extra SWT Styles
1070
-
1071
- ##### Non-resizable Window
1072
-
1073
- 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!)`.
1074
-
1075
- Glimmer makes this easier by alternatively offering a `:no_resize` extra SWT style, added for convenience.
1076
- This makes declaring a non-resizable window as easy as:
1077
-
1078
- ```ruby
1079
- shell(:no_resize) {
1080
- # ...
1081
- }
1082
- ```
1083
-
1084
- ### Widget Properties
1085
-
1086
- 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:
1087
-
1088
- https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/guide/swt_widgets_controls.htm?cp=2_0_7_0_0
1089
-
1090
-
1091
- Code examples:
1092
-
1093
- ```ruby
1094
- # ...
1095
- label {
1096
- text "Hello, World!" # SWT properties go inside {} block
1097
- }
1098
- # ...
1099
- ```
1100
-
1101
- In the above example, the `label` widget `text` property was set to "Hello, World!".
1102
-
1103
- ```ruby
1104
- # ...
1105
- button {
1106
- enabled bind(@tic_tac_toe_board.box(row, column), :empty)
1107
- }
1108
- # ...
1109
- ```
1110
-
1111
- 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)
1112
-
1113
- #### Colors
1114
-
1115
- 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.
1116
-
1117
- Example:
1118
-
1119
- ```ruby
1120
- # ...
1121
- label {
1122
- background rgb(144, 240, 244)
1123
- foreground rgba(38, 92, 232, 255)
1124
- }
1125
- # ...
1126
- ```
1127
-
1128
- SWT also supports standard colors available as constants under the `SWT` namespace with the `COLOR_` prefix (e.g. `SWT::COLOR_BLUE`)
1129
-
1130
- Glimmer supports constructing colors for these constants as lowercase Ruby symbols (with or without `color_` prefix) passed to `color` DSL keyword
1131
-
1132
- Example:
1133
-
1134
- ```ruby
1135
- # ...
1136
- label {
1137
- background color(:black)
1138
- foreground color(:yellow)
1139
- }
1140
- label {
1141
- background color(:color_white)
1142
- foreground color(:color_red)
1143
- }
1144
- # ...
1145
- ```
1146
-
1147
- You may check out all available standard colors in `SWT` over here (having `COLOR_` prefix):
1148
-
1149
- https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
1150
-
1151
-
1152
- ##### `#swt_color`
1153
-
1154
- 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.
1155
-
1156
- Example:
1157
-
1158
- ```ruby
1159
- color(:black).swt_color # returns SWT Color object
1160
- ```
1161
-
1162
- #### Fonts
1163
-
1164
- Fonts are represented in Glimmer as a hash of name, height, and style keys.
1165
-
1166
- The style can be one (or more) of 3 values: `:normal`, `:bold`, and `:italic`
1167
-
1168
- Example:
1169
-
1170
- ```ruby
1171
- # ...
1172
- label {
1173
- font name: 'Arial', height: 36, style: :normal
1174
- }
1175
- # ...
1176
- ```
1177
-
1178
- Keys are optional, so some of them may be left off.
1179
- When passing multiple styles, they are included in an array.
1180
-
1181
- Example:
1182
-
1183
- ```ruby
1184
- # ...
1185
- label {
1186
- font style: [:bold, :italic]
1187
- }
1188
- # ...
1189
- ```
1190
-
1191
- ### Layouts
1192
-
1193
- Glimmer lays widgets out visually using SWT layouts, which can only be set on composite widget and subclasses.
1194
-
1195
- The most common SWT layouts are:
1196
- - `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.
1197
- - `RowLayout`: lays widgets out horizontally or vertically in varying proportions with advanced spacing/margin/justify options
1198
- - `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.
1199
-
1200
- 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`).
1201
-
1202
- Example:
1203
-
1204
- ```ruby
1205
- # ...
1206
- composite {
1207
- row_layout {
1208
- wrap true
1209
- pack false
1210
- justify true
1211
- type :vertical
1212
- margin_left 1
1213
- margin_top 2
1214
- margin_right 3
1215
- margin_bottom 4
1216
- spacing 5
1217
- }
1218
- # ... widgets follow
1219
- }
1220
- # ...
1221
- ```
1222
-
1223
- 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.
1224
-
1225
- 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`.)
1226
-
1227
- ```ruby
1228
- # ...
1229
- composite {
1230
- row_layout :horizontal
1231
- # ... widgets follow
1232
- }
1233
- # ...
1234
- ```
1235
-
1236
- Here is a more sophisticated example taken from [hello_computed.rb](samples/hello/hello_computed.rb) sample:
1237
-
1238
- ![Hello Computed](images/glimmer-hello-computed.png)
1239
-
1240
- ```ruby
1241
- shell {
1242
- text 'Hello, Computed!'
1243
- composite {
1244
- grid_layout {
1245
- num_columns 2
1246
- make_columns_equal_width true
1247
- horizontal_spacing 20
1248
- vertical_spacing 10
1249
- }
1250
- label {text 'First &Name: '}
1251
- text {
1252
- text bind(@contact, :first_name)
1253
- layout_data {
1254
- horizontal_alignment :fill
1255
- grab_excess_horizontal_space true
1256
- }
1257
- }
1258
- label {text '&Last Name: '}
1259
- text {
1260
- text bind(@contact, :last_name)
1261
- layout_data {
1262
- horizontal_alignment :fill
1263
- grab_excess_horizontal_space true
1264
- }
1265
- }
1266
- label {text '&Year of Birth: '}
1267
- text {
1268
- text bind(@contact, :year_of_birth)
1269
- layout_data {
1270
- horizontal_alignment :fill
1271
- grab_excess_horizontal_space true
1272
- }
1273
- }
1274
- label {text 'Name: '}
1275
- label {
1276
- text bind(@contact, :name, computed_by: [:first_name, :last_name])
1277
- layout_data {
1278
- horizontal_alignment :fill
1279
- grab_excess_horizontal_space true
1280
- }
1281
- }
1282
- label {text 'Age: '}
1283
- label {
1284
- text bind(@contact, :age, on_write: :to_i, computed_by: [:year_of_birth])
1285
- layout_data {
1286
- horizontal_alignment :fill
1287
- grab_excess_horizontal_space true
1288
- }
1289
- }
1290
- }
1291
- }.open
1292
- ```
1293
-
1294
- Check out the samples directory for more advanced examples of layouts in Glimmer.
1295
-
1296
- **Defaults**:
1297
-
1298
- 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.
1299
-
1300
- Glimmer shell always comes with `fill_layout` having `:horizontal` type.
1301
-
1302
- This is a great guide for learning more about SWT layouts:
1303
-
1304
- https://www.eclipse.org/articles/Article-Understanding-Layouts/Understanding-Layouts.htm
1305
-
1306
- Also, for a reference, check the SWT API:
1307
-
1308
- https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
1309
-
1310
- ### Layout Data
1311
-
1312
- 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.
1313
-
1314
- By convention, SWT layouts expect widgets to set layout data with a class matching their class name with the word "Data" replacing "Layout":
1315
- - `GridLayout` on a composite demands `GridData` on contained widgets
1316
- - `RowLayout` on a composite demands `RowData` on contained widgets
1317
-
1318
- Not all layouts support layout data to further customize widget layouts. For example, `FillLayout` supports no layout data.
1319
-
1320
- 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).
1321
-
1322
- 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)
1323
-
1324
- Glimmer also automatically accepts symbols (e.g. `:fill`) for SWT style arguments like `SWT::FILL`.
1325
-
1326
- Examples:
1327
-
1328
- ```ruby
1329
- # ...
1330
- composite {
1331
- row_layout :horizontal
1332
- label {
1333
- layout_data { # followed by properties
1334
- width 50
1335
- height 30
1336
- }
1337
- }
1338
- # ... more widgets follow
1339
- }
1340
- # ...
1341
- ```
1342
-
1343
- ```ruby
1344
- # ...
1345
- composite {
1346
- grid_layout 3, false # grid layout with 3 columns not of equal width
1347
- label {
1348
- # layout data followed by arguments passed to SWT GridData constructor
1349
- layout_data :fill, :end, true, false
1350
- }
1351
- }
1352
- # ...
1353
- ```
1354
-
1355
- ```ruby
1356
- # ...
1357
- composite {
1358
- grid_layout 3, false # grid layout with 3 columns not of equal width
1359
- label {
1360
- # layout data set explicitly via an object (helps in rare cases that break convention)
1361
- layout_data GridData.new(swt(:fill), swt(:end), true, false)
1362
- }
1363
- }
1364
- # ...
1365
- ```
1366
-
1367
- 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.
1368
-
1369
- **NOTE**: Layout data must never be reused between widgets. Always specify or clone again for every widget.
1370
-
1371
- This is a great guide for learning more about SWT layouts:
1372
-
1373
- https://www.eclipse.org/articles/Article-Understanding-Layouts/Understanding-Layouts.htm
1374
-
1375
- Also, for a reference, check the SWT API:
1376
-
1377
- https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
1378
-
1379
- ### Data-Binding
1380
-
1381
- Data-binding is done with `bind` command following widget property to bind and taking model and bindable attribute as arguments.
1382
-
1383
- #### General Examples
1384
-
1385
- `text bind(contact, :first_name)`
1386
-
1387
- This example binds the text property of a widget like `label` to the first name of a contact model.
1388
-
1389
- `text bind(contact, 'address.street')`
1390
-
1391
- This example binds the text property of a widget like `label` to the nested street of
1392
- the address of a contact. This is called nested property data binding.
1393
-
1394
- `text bind(contact, 'address.street', on_read: :upcase, on_write: :downcase)`
1395
-
1396
- 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)
1397
-
1398
- `text bind(contact, 'address.street', on_read: lambda { |s| s[0..10] })`
1399
-
1400
- 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`
1401
-
1402
- `text bind(contact, 'address.street') { |s| s[0..10] }`
1403
-
1404
- 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.
1405
-
1406
- `text bind(contact, 'address.street', read_only: true)
1407
-
1408
- This is read-ohly data-binding. It doesn't update contact.address.street when widget text property is changed.
1409
-
1410
- `text bind(contact, 'addresses[1].street')`
1411
-
1412
- 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.
1413
-
1414
- `text bind(contact, :age, computed_by: :date_of_birth)`
1415
-
1416
- This example demonstrates computed value data binding whereby the value of `age` depends on changes to `date_of_birth`.
1417
-
1418
- `text bind(contact, :name, computed_by: [:first_name, :last_name])`
1419
-
1420
- This example demonstrates computed value data binding whereby the value of `name` depends on changes to both `first_name` and `last_name`.
1421
-
1422
- `text bind(contact, 'profiles[0].name', computed_by: ['profiles[0].first_name', 'profiles[0].last_name'])`
1423
-
1424
- 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`.
1425
-
1426
- Example from [samples/hello/hello_combo.rb](samples/hello_combo.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1427
-
1428
- #### Combo
1429
-
1430
- 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.
1431
-
1432
- When data-binding a `combo` widget, Glimmer can automatically deduce available options from data-bound model by convention: `{attribute_name}_options` method.
1433
-
1434
- ![Hello Combo](images/glimmer-hello-combo.png)
1435
-
1436
- ![Hello Combo](images/glimmer-hello-combo-expanded.png)
1437
-
1438
- ```ruby
1439
- class Person
1440
- attr_accessor :country, :country_options
1441
-
1442
- def initialize
1443
- self.country_options=["", "Canada", "US", "Mexico"]
1444
- self.country = "Canada"
1445
- end
1446
-
1447
- def reset_country
1448
- self.country = "Canada"
1449
- end
1450
- end
1451
-
1452
- class HelloCombo
1453
- include Glimmer
1454
- def launch
1455
- person = Person.new
1456
- shell {
1457
- composite {
1458
- combo(:read_only) {
1459
- selection bind(person, :country)
1460
- }
1461
- button {
1462
- text "Reset"
1463
- on_widget_selected do
1464
- person.reset_country
1465
- end
1466
- }
1467
- }
1468
- }.open
1469
- end
1470
- end
1471
-
1472
- HelloCombo.new.launch
1473
- ```
1474
-
1475
- `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.
1476
-
1477
- #### List
1478
-
1479
- Example from [samples/hello/hello_list_single_selection.rb](samples/hello_list_single_selection.rb) sample:
1480
-
1481
- ![Hello List Single Selection](images/glimmer-hello-list-single-selection.png)
1482
-
1483
- ```ruby
1484
- shell {
1485
- composite {
1486
- list {
1487
- selection bind(person, :country)
1488
- }
1489
- button {
1490
- text "Reset"
1491
- on_widget_selected do
1492
- person.reset_country
1493
- end
1494
- }
1495
- }
1496
- }.open
1497
- ```
1498
-
1499
- `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).
1500
-
1501
- 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.
1502
-
1503
- 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)):
1504
-
1505
- ![Hello List Multi Selection](images/glimmer-hello-list-multi-selection.png)
1506
-
1507
- ```ruby
1508
- class Person
1509
- attr_accessor :provinces, :provinces_options
1510
-
1511
- def initialize
1512
- self.provinces_options=[
1513
- "",
1514
- "Quebec",
1515
- "Ontario",
1516
- "Manitoba",
1517
- "Saskatchewan",
1518
- "Alberta",
1519
- "British Columbia",
1520
- "Nova Skotia",
1521
- "Newfoundland"
1522
- ]
1523
- self.provinces = ["Quebec", "Manitoba", "Alberta"]
1524
- end
1525
-
1526
- def reset_provinces
1527
- self.provinces = ["Quebec", "Manitoba", "Alberta"]
1528
- end
1529
- end
1530
-
1531
- class HelloListMultiSelection
1532
- include Glimmer
1533
- def launch
1534
- person = Person.new
1535
- shell {
1536
- composite {
1537
- list(:multi) {
1538
- selection bind(person, :provinces)
1539
- }
1540
- button {
1541
- text "Reset"
1542
- on_widget_selected do
1543
- person.reset_provinces
1544
- end
1545
- }
1546
- }
1547
- }.open
1548
- end
1549
- end
1550
-
1551
- HelloListMultiSelection.new.launch
1552
- ```
1553
-
1554
- 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`.
1555
-
1556
- 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).
1557
-
1558
- You may learn more about Glimmer's data-binding syntax by reading the code under the [samples](samples) directory.
1559
-
1560
- #### Table
1561
-
1562
- The SWT Tree widget renders a multi-column data table, such as a contact listing or a sales report.
1563
-
1564
- To data-bind a Table, you need the main model, the collection property, and the text display attribute for each table column.
1565
-
1566
- This involves using the `bind` keyword mentioned above in addition to a special `column_properties` keyword that takes the table column text attribute methods.
1567
-
1568
- It assumes you have defined the table columns via `table_column` widget.
1569
-
1570
- Example:
1571
-
1572
- ```ruby
1573
- shell {
1574
- @table = table {
1575
- table_column {
1576
- text "Name"
1577
- width 120
1578
- }
1579
- table_column {
1580
- text "Age"
1581
- width 120
1582
- }
1583
- table_column {
1584
- text "Adult"
1585
- width 120
1586
- }
1587
- items bind(group, :people), column_properties(:name, :age, :adult)
1588
- selection bind(group, :selected_person)
1589
- on_mouse_up { |event|
1590
- @table.edit_table_item(event.table_item, event.column_index)
1591
- }
1592
- }
1593
- }
1594
- ```
1595
-
1596
- The code above includes two data-bindings:
1597
- - 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.
1598
- - 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)
1599
- - 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.)
1600
-
1601
- Additionally, Table `items` data-binding automatically stores each node model unto the SWT TableItem object via `setData` method. This enables things like searchability.
1602
-
1603
- The table widget in Glimmer is represented by a subclass of `WidgetProxy` called `TableProxy`.
1604
- TableProxy includes a `search` method that takes a block to look for a table item.
1605
-
1606
- Example:
1607
-
1608
- ```ruby
1609
- found_array = @table.search { |table_item| table_item.getData == company.owner }
1610
- ```
1611
-
1612
- 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.
1613
-
1614
- 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)`.
1615
- This automatically leverages the SWT TableEditor custom class behind the scenes, displaying a text widget to the user to change the selected or
1616
- passed table item text into something else.
1617
- It automatically persists the change to `items` data-bound model on ENTER/FOCUS-OUT or cancels on ESC/NO-CHANGE.
1618
-
1619
- ##### Table Sorting
1620
-
1621
- Glimmer automatically adds sorting support to the SWT `Table` widget.
1622
-
1623
- Check out the [Contact Manager](#contact-manager) sample for an example.
1624
- You may click on any column and it will sort by ascending order first and descending if you click again.
1625
-
1626
- Glimmer automatic table sorting supports `String`, `Integer`, and `Float` columns out of the box as well as any column data that is comparable.
1627
-
1628
- 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`.
1629
-
1630
- Should you have a special data type that could not be compared automatically, Glimmer offers the following 3 alternatives for custom sorting:
1631
- - `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`).
1632
- - `sort_by(&block)`: this works just like Ruby `Enumerable` `sort_by`. The block receives the table column data as argument.
1633
- - `sort(&comparator)`: this works just like Ruby `Enumerable` `sort`. The comparator block receives two objects from the table column data.
1634
-
1635
- 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)
1636
-
1637
- Example:
1638
-
1639
- ```ruby
1640
- # ...
1641
- table {
1642
- table_column {
1643
- text 'Task'
1644
- width 120
1645
- }
1646
- table_column {
1647
- text 'Project'
1648
- width 120
1649
- }
1650
- table_column {
1651
- text 'Duration (hours)'
1652
- width 120
1653
- sort_property :duration_in_hours
1654
- }
1655
- table_column {
1656
- text 'Priority'
1657
- width 120
1658
- sort_by { |value| ['High', 'Medium', 'Low'].index(value) }
1659
- }
1660
- table_column {
1661
- text 'Start Date'
1662
- width 120
1663
- sort { |d1, d2| d1.to_date <=> d2.to_date }
1664
- }
1665
- additional_sort_properties :project_name, :duration_in_hours, :name
1666
- items bind(Task, :list), column_properties(:name, :project_name, :duration, :priority, :start_date)
1667
- # ...
1668
- }
1669
- # ...
1670
- ```
1671
-
1672
- Here is an explanation of the example above:
1673
- - Task and Project table columns are data-bound to the `:name` and `:project_name` properties and sorted through them automatically
1674
- - Task Duration table column is data-bound to the `:duration` property, but sorted via the `:duration_in_hours` property instead
1675
- - Task Priority table column has a custom sort_by block
1676
- - Task Start Date table column has a custom sort comparator block
1677
- - Additional (secondary) sort properties are applied when sorting by Task, Project, or Duration in the order specified
1678
-
1679
-
1680
- #### Tree
1681
-
1682
- The SWT Tree widget visualizes a tree data-structure, such as an employment or composition hierarchy.
1683
-
1684
- To data-bind a Tree, you need the root model, the children querying method, and the text display attribute on each child.
1685
-
1686
- This involves using the `bind` keyword mentioned above in addition to a special `tree_properties` keyword that takes the children and text attribute methods.
1687
-
1688
- Example:
1689
-
1690
- ```ruby
1691
- shell {
1692
- @tree = tree {
1693
- items bind(company, :owner), tree_properties(children: :coworkers, text: :name)
1694
- selection bind(company, :selected_coworker)
1695
- }
1696
- }
1697
- ```
1698
-
1699
- The code above includes two data-bindings:
1700
- - 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.
1701
- - Tree `selection`, which binds the single tree item selected by the user to the attribute denoted by the `bind` keyword
1702
-
1703
- Additionally, Tree `items` data-binding automatically stores each node model unto the SWT TreeItem object via `setData` method. This enables things like searchability.
1704
-
1705
- The tree widget in Glimmer is represented by a subclass of `WidgetProxy` called `TreeProxy`.
1706
- TreeProxy includes a `depth_first_search` method that takes a block to look for a tree item.
1707
-
1708
- Example:
1709
-
1710
- ```ruby
1711
- found_array = @tree.depth_first_search { |tree_item| tree_item.getData == company.owner }
1712
- ```
1713
-
1714
- 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.
1715
-
1716
- 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
1717
- 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.
1718
-
1719
- ### Observer
1720
-
1721
- 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.
1722
-
1723
- #### Observing Widgets
1724
-
1725
- Glimmer supports observing widgets with two main types of events:
1726
- 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`).
1727
- 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)
1728
-
1729
- Additionally, there are two more types of events:
1730
- - SWT `display` supports global listeners called filters that run on any widget. They are hooked via `on_swt_{swt-event-constant}`
1731
- - SWT `display` supports Mac application menu item observers (`on_about` and `on_preferences`), which you can read about under [Miscellaneous](#miscellaneous).
1732
-
1733
- 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.
1734
-
1735
- **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".
1736
-
1737
- For example, if you look at the `Button` SWT API:
1738
- https://help.eclipse.org/2019-12/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fswt%2Fbrowser%2FBrowser.html
1739
-
1740
- 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`
1741
-
1742
- 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.
1743
-
1744
- 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.
1745
-
1746
- Instead, simply add a `on_widget_selected` followed by a Ruby block containing the logic to perform. Glimmer figures out the rest.
1747
-
1748
- Let's revisit the Tic Tac Toe example shown near the beginning of the page:
1749
-
1750
- ```ruby
1751
- shell {
1752
- text "Tic-Tac-Toe"
1753
- composite {
1754
- grid_layout 3, true
1755
- (1..3).each { |row|
1756
- (1..3).each { |column|
1757
- button {
1758
- layout_data :fill, :fill, true, true
1759
- text bind(@tic_tac_toe_board[row, column], :sign)
1760
- enabled bind(@tic_tac_toe_board[row, column], :empty)
1761
- on_widget_selected {
1762
- @tic_tac_toe_board.mark(row, column)
1763
- }
1764
- }
1765
- }
1766
- }
1767
- }
1768
- }
1769
- ```
1770
-
1771
- 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.
1772
-
1773
- 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.
1774
-
1775
- **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:
1776
-
1777
- https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
1778
-
1779
- Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1780
-
1781
- `SWT.Show` - hooks a listener for showing a widget (using `on_swt_show` in Glimmer)
1782
- `SWT.Hide` - hooks a listener for hiding a widget (using `on_swt_hide` in Glimmer)
1783
-
1784
- ```ruby
1785
- shell {
1786
- @button1 = button {
1787
- text "Show 2nd Button"
1788
- visible true
1789
- on_swt_show {
1790
- @button2.swt_widget.setVisible(false)
1791
- }
1792
- on_widget_selected {
1793
- @button2.swt_widget.setVisible(true)
1794
- }
1795
- }
1796
- @button2 = button {
1797
- text "Show 1st Button"
1798
- visible false
1799
- on_swt_show {
1800
- @button1.swt_widget.setVisible(false)
1801
- }
1802
- on_widget_selected {
1803
- @button1.swt_widget.setVisible(true)
1804
- }
1805
- }
1806
- }.open
1807
- ```
1808
-
1809
- **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`
1810
-
1811
- ##### Alternative Syntax
1812
-
1813
- 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.
1814
-
1815
- Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
1816
-
1817
- ```
1818
- @shell = shell {
1819
- label {
1820
- text "Hello, World!"
1821
- }
1822
- }
1823
- @shell.on_shell_iconified {
1824
- @shell.close
1825
- }
1826
- @shell.open
1827
- ```
1828
-
1829
- 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.
1830
-
1831
- 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.
1832
-
1833
- #### Observing Models
1834
-
1835
- 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.
1836
-
1837
- ```ruby
1838
- class TicTacToe
1839
- include Glimmer
1840
-
1841
- def initialize
1842
- # ...
1843
- observe(@tic_tac_toe_board, :game_status) { |game_status|
1844
- display_win_message if game_status == Board::WIN
1845
- display_draw_message if game_status == Board::DRAW
1846
- }
1847
- end
1848
- # ...
1849
- end
1850
- ```
1851
-
1852
- 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).
1853
-
1854
- Look at [`samples/elaborate/tictactoe/tic_tac_toe.rb`](samples/tictactoe/tic_tac_toe.rb) for more details starting with the code included below.
1855
-
1856
- ```ruby
1857
- class TicTacToe
1858
- include Glimmer
1859
- include Observer
1860
-
1861
- def initialize
1862
- # ...
1863
- observe(@tic_tac_toe_board, :game_status) { |game_status|
1864
- display_win_message if game_status == Board::WIN
1865
- display_draw_message if game_status == Board::DRAW
1866
- }
1867
- end
1868
-
1869
- def display_win_message
1870
- display_game_over_message("Player #{@tic_tac_toe_board.winning_sign} has won!")
1871
- end
1872
-
1873
- def display_draw_message
1874
- display_game_over_message("Draw!")
1875
- end
1876
-
1877
- def display_game_over_message(message)
1878
- message_box(@shell) {
1879
- text 'Game Over'
1880
- message message_text
1881
- }.open
1882
- @tic_tac_toe_board.reset
1883
- end
1884
- # ...
1885
- end
1886
- ```
1887
-
1888
- ### Custom Widgets
1889
-
1890
- Glimmer supports creating custom widgets with minimal code, which automatically extends Glimmer's DSL syntax with an underscored lowercase keyword.
1891
-
1892
- 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 `__`)
1893
-
1894
- #### Simple Example
1895
-
1896
- (you may copy/paste in [`girb`](#girb-glimmer-irb-command))
1897
-
1898
- Definition:
1899
- ```ruby
1900
- class RedLabel
1901
- include Glimmer::UI::CustomWidget
1902
-
1903
- body {
1904
- label(swt_style) {
1905
- background :red
1906
- }
1907
- }
1908
- end
1909
- ```
1910
-
1911
- Usage:
1912
- ```ruby
1913
- shell {
1914
- red_label {
1915
- text 'Red Label'
1916
- }
1917
- }.open
1918
- ```
1919
-
1920
- As you can see, `RedLabel` became Glimmer DSL keyword: `red_label`
1921
-
1922
- #### Lifecycle Hook Example
1923
-
1924
- (you may copy/paste in [`girb`](#girb-glimmer-irb-command))
1925
-
1926
- Definition:
1927
- ```ruby
1928
- module Red
1929
- class Composite
1930
- include Glimmer::UI::CustomWidget
1931
-
1932
- before_body {
1933
- @color = :red
1934
- }
1935
-
1936
- body {
1937
- composite(swt_style) {
1938
- background @color
1939
- }
1940
- }
1941
- end
1942
- end
1943
- ```
1944
-
1945
- Usage:
1946
- ```ruby
1947
- shell {
1948
- red__composite {
1949
- label {
1950
- foreground :white
1951
- text 'This is showing inside a Red Composite'
1952
- }
1953
- }
1954
- }.open
1955
- ```
1956
-
1957
- 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`.
1958
-
1959
- 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.
1960
-
1961
- #### Custom Widget API
1962
-
1963
- Custom Widgets have the following attributes available to call from inside the `#body` method:
1964
- - `#parent`: Glimmer object parenting custom widget
1965
- - `#swt_style`: SWT style integer. Can be useful if you want to allow consumers to customize a widget inside the custom widget body
1966
- - `#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)
1967
- - `#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.
1968
- - `#body_root`: top-most (root) widget returned from `#body` method.
1969
- - `#swt_widget`: actual SWT widget for `body_root`
1970
-
1971
- Additionally, custom widgets can call the following class methods:
1972
- - `::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)
1973
- - `::option(option_name, default: nil)`: declares a single option taking option name and default value as arguments (also generates attribute accessors just like `::options`)
1974
-
1975
- #### Content/Options Example
1976
-
1977
- (you may copy/paste in [`girb`](#girb-glimmer-irb-command))
1978
-
1979
- Definition:
1980
- ```ruby
1981
- class Sandwich
1982
- include Glimmer::UI::CustomWidget
1983
-
1984
- options :orientation, :bg_color
1985
- option :fg_color, default: :black
1986
-
1987
- body {
1988
- composite(swt_style) { # gets custom widget style
1989
- fill_layout orientation # using orientation option
1990
- background bg_color # using container_background option
1991
- label {
1992
- text 'SANDWICH TOP'
1993
- }
1994
- content.call # this is where content block is called
1995
- label {
1996
- text 'SANDWICH BOTTOM'
1997
- }
1998
- }
1999
- }
2000
- end
2001
- ```
2002
-
2003
- Usage:
2004
- ```ruby
2005
- shell {
2006
- sandwich(:no_focus, orientation: :vertical, bg_color: :red) {
2007
- label {
2008
- background :green
2009
- text 'SANDWICH CONTENT'
2010
- }
2011
- }
2012
- }.open
2013
- ```
2014
-
2015
- 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'`
2016
-
2017
- #### Custom Widget Lifecycle Hooks
2018
-
2019
- Last but not least, these are the available lifecycle hooks:
2020
- - `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`
2021
- - `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.
2022
-
2023
- #### Gotcha
2024
-
2025
- Beware of defining a custom attribute that is a common SWT widget property name.
2026
- For example, if you define `text=` and `text` methods to accept a custom text and then later you write this body:
2027
-
2028
- ```ruby
2029
- # ...
2030
- def text
2031
- # ...
2032
- end
2033
-
2034
- def text=(value)
2035
- # ...
2036
- end
2037
-
2038
- body {
2039
- composite {
2040
- label {
2041
- text "Hello"
2042
- }
2043
- label {
2044
- text "World"
2045
- }
2046
- }
2047
- }
2048
- # ...
2049
- ```
2050
-
2051
- 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`.
2052
-
2053
- #### Final Notes
2054
-
2055
- 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:
2056
- [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)
2057
-
2058
- ### Custom Shells
2059
-
2060
- 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.
2061
-
2062
- They may also be chained in a wizard fashion.
2063
-
2064
- Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2065
-
2066
- ```ruby
2067
- class WizardStep
2068
- include Glimmer::UI::CustomShell
2069
-
2070
- options :number, :step_count
2071
-
2072
- before_body {
2073
- @title = "Step #{number}"
2074
- }
2075
-
2076
- body {
2077
- shell {
2078
- text "Wizard - #{@title}"
2079
- minimum_size 200, 100
2080
- fill_layout :vertical
2081
- label(:center) {
2082
- text @title
2083
- font height: 30
2084
- }
2085
- if number < step_count
2086
- button {
2087
- text "Go To Next Step"
2088
- on_widget_selected {
2089
- body_root.hide
2090
- }
2091
- }
2092
- end
2093
- }
2094
- }
2095
- end
2096
-
2097
- shell { |app_shell|
2098
- text "Wizard"
2099
- minimum_size 200, 100
2100
- @current_step_number = 1
2101
- @wizard_steps = 5.times.map { |n|
2102
- wizard_step(number: n+1, step_count: 5) {
2103
- on_swt_hide {
2104
- if @current_step_number < 5
2105
- @current_step_number += 1
2106
- app_shell.hide
2107
- @wizard_steps[@current_step_number - 1].open
2108
- end
2109
- }
2110
- }
2111
- }
2112
- button {
2113
- text "Start"
2114
- font height: 40
2115
- on_widget_selected {
2116
- app_shell.hide
2117
- @wizard_steps[@current_step_number - 1].open
2118
- }
2119
- }
2120
- }.open
2121
- ```
2122
-
2123
- ### Drag and Drop
2124
-
2125
- Glimmer offers Drag and Drop support, thanks to [SWT](https://www.eclipse.org/swt/) and Glimmer's lightweight [DSL syntax](#glimmer-dsl-syntax).
2126
-
2127
- 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)
2128
-
2129
- To get started, simply follow these steps:
2130
- 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)
2131
- 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)
2132
- 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)
2133
- 1. Read `event.data` and consume it (e.g. change widget text) inside the `on_drop` event handler block.
2134
-
2135
- Example (taken from [samples/hello/hello_drag_and_drop.rb](#hello-drag-and-drop) / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2136
-
2137
- ```ruby
2138
- class Location
2139
- attr_accessor :country
2140
-
2141
- def country_options
2142
- %w[USA Canada Mexico Columbia UK Australia Germany Italy Spain]
2143
- end
2144
- end
2145
-
2146
- @location = Location.new
2147
-
2148
- include Glimmer
2149
-
2150
- shell {
2151
- text 'Hello, Drag and Drop!'
2152
- list {
2153
- selection bind(@location, :country)
2154
- on_drag_set_data { |event|
2155
- list = event.widget.getControl
2156
- event.data = list.getSelection.first
2157
- }
2158
- }
2159
- label(:center) {
2160
- text 'Drag a country here!'
2161
- font height: 20
2162
- on_drop { |event|
2163
- event.widget.getControl.setText(event.data)
2164
- }
2165
- }
2166
- }.open
2167
- ```
2168
-
2169
- ![Hello Drag and Drop](images/glimmer-hello-drag-and-drop.gif)
2170
-
2171
- Optional steps:
2172
- - 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.
2173
- - Specify `drag_source_style` operation (may be: :drop_copy (default), :drop_link, :drop_move, :drop_none, or an array of multiple operations)
2174
- - 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)
2175
- - Specify `drop_target_style` operation (may be: :drop_copy (default), :drop_link, :drop_move, :drop_none, or an array of multiple operations)
2176
- - 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)
2177
- - Set drag operation in `event.detail` (e.g. DND::DROP_COPY) inside `on_drag_enter`
2178
-
2179
- ### Miscellaneous
2180
-
2181
- #### Multi-DSL Support
2182
-
2183
- Glimmer is a DSL engine that supports multiple DSLs (Domain Specific Languages):
2184
- - [SWT](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
2185
- - [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
2186
- - [XML](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML) - Useful with [SWT Browser Widget](#browser-widget)
2187
- - [CSS](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets) - Useful with [SWT Browser Widget](#browser-widget)
2188
-
2189
- 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.
2190
-
2191
- ##### SWT
2192
-
2193
- 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:
2194
- - `shell`
2195
- - `display`
2196
- - `color`
2197
- - `observe`
2198
- - `async_exec`
2199
- - `sync_exec`
2200
-
2201
- ##### Opal
2202
-
2203
- Full instructions are found in the [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal) DSL page.
2204
-
2205
- 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.
2206
-
2207
- ##### XML
2208
-
2209
- Simply start with `html` keyword and add HTML inside its block using Glimmer DSL syntax.
2210
- Once done, you may call `to_s`, `to_xml`, or `to_html` to get the formatted HTML output.
2211
-
2212
- Here are all the Glimmer XML DSL top-level keywords:
2213
- - `html`
2214
- - `tag`: enables custom tag creation for exceptional cases by passing tag name as '_name' attribute
2215
- - `name_space`: enables namespacing html tags
2216
-
2217
- 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')` )
2218
-
2219
- Example (basic HTML / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2220
-
2221
- ```ruby
2222
- @xml = html {
2223
- head {
2224
- meta(name: "viewport", content: "width=device-width, initial-scale=2.0")
2225
- }
2226
- body {
2227
- h1 { "Hello, World!" }
2228
- }
2229
- }
2230
- puts @xml
2231
- ```
2232
-
2233
- Output:
2234
-
2235
- ```
2236
- <html><head><meta name="viewport" content="width=device-width, initial-scale=2.0" /></head><body><h1>Hello, World!</h1></body></html>
2237
- ```
2238
-
2239
- Example (explicit XML tag / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2240
-
2241
- ```ruby
2242
- puts tag(:_name => "DOCUMENT")
2243
- ```
2244
-
2245
- Output:
2246
-
2247
- ```
2248
- <DOCUMENT/>
2249
- ```
2250
-
2251
- Example (XML namespaces using `name_space` keyword / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2252
-
2253
- ```ruby
2254
- @xml = name_space(:w3c) {
2255
- html(:id => "thesis", :class => "document") {
2256
- body(:id => "main") {
2257
- }
2258
- }
2259
- }
2260
- puts @xml
2261
- ```
2262
-
2263
- Output:
2264
-
2265
- ```
2266
- <w3c:html id="thesis" class="document"><w3c:body id="main"></w3c:body></w3c:html>
2267
- ```
2268
-
2269
- Example (XML namespaces using dot operator / you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2270
-
2271
- ```ruby
2272
- @xml = tag(:_name => "DOCUMENT") {
2273
- document.body(document.id => "main") {
2274
- }
2275
- }
2276
- puts @xml
2277
- ```
2278
-
2279
- Output:
2280
-
2281
- ```
2282
- <DOCUMENT><document:body document:id="main"></document:body></DOCUMENT>
2283
- ```
2284
-
2285
- ##### CSS
2286
-
2287
- Simply start with `css` keyword and add stylesheet rule sets inside its block using Glimmer DSL syntax.
2288
- Once done, you may call `to_s` or `to_css` to get the formatted CSS output.
2289
-
2290
- `css` is the only top-level keyword in the Glimmer CSS DSL
2291
-
2292
- Selectors may be specified by `s` keyword or HTML element keyword directly (e.g. `body`)
2293
- Rule property values may be specified by `pv` keyword or underscored property name directly (e.g. `font_size`)
2294
-
2295
- Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2296
-
2297
- ```ruby
2298
- @css = css {
2299
- body {
2300
- font_size '1.1em'
2301
- pv 'background', 'white'
2302
- }
2303
-
2304
- s('body > h1') {
2305
- background_color :red
2306
- pv 'font-size', '2em'
2307
- }
2308
- }
2309
- puts @css
2310
- ```
2311
-
2312
- ##### Listing / Enabling / Disabling DSLs
2313
-
2314
- Glimmer provides a number of methods on Glimmer::DSL::Engine to configure DSL support or inquire about it:
2315
- - `Glimmer::DSL::Engine.dsls`: Lists available Glimmer DSLs
2316
- - `Glimmer::DSL::Engine.disable_dsl(dsl_name)`: Disables a specific DSL. Useful when there is no need for certain DSLs in a certain application.
2317
- - `Glimmer::DSL::Engine.disabled_dsls': Lists disabled DSLs
2318
- - `Glimmer::DSL::Engine.enable_dsl(dsl_name)`: Re-enables disabled DSL
2319
- - `Glimmer::DSL::Engine.enabled_dsls=(dsl_names)`: Disables all DSLs except the ones specified.
2320
-
2321
- #### Application Menu Items (About/Preferences)
2322
-
2323
- Mac applications always have About and Preferences menu items. Glimmer provides widget observer hooks for them on the `display`:
2324
- - `on_about`: executes code when user selects App Name -> About
2325
- - `on_preferences`: executes code when user selects App Name -> Preferences or hits 'CMD+,' on the Mac
2326
-
2327
- Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2328
-
2329
- ```ruby
2330
- class Example
2331
- def initialize
2332
- display {
2333
- on_about {
2334
- message_box(@shell_proxy) {
2335
- text 'About'
2336
- message 'About Application'
2337
- }.open
2338
- }
2339
- on_preferences {
2340
- preferences_dialog = dialog {
2341
- text 'Preferences'
2342
- row_layout {
2343
- type :vertical
2344
- margin_left 15
2345
- margin_top 15
2346
- margin_right 15
2347
- margin_bottom 15
2348
- }
179
+
2349
180
  label {
2350
- text 'Check one of these options:'
181
+ layout_data :right, :center, false, false
182
+ text "&Email: "
183
+ font height: 16
2351
184
  }
2352
- button(:radio) {
2353
- text 'Option 1'
2354
- }
2355
- button(:radio) {
2356
- text 'Option 2'
185
+ text {
186
+ layout_data :fill, :center, true, false
187
+ text bind(@contact_manager_presenter, :email)
188
+ on_key_pressed {|key_event|
189
+ @contact_manager_presenter.find if key_event.keyCode == swt(:cr)
190
+ }
2357
191
  }
2358
- }
2359
- preferences_dialog.open
2360
- }
2361
- }
2362
- @shell_proxy = shell {
2363
- text 'Application Menu Items'
2364
- fill_layout {
2365
- margin_width 15
2366
- margin_height 15
2367
- }
2368
- label {
2369
- text 'Application Menu Items'
2370
- font height: 30
2371
- }
2372
- }
2373
- @shell_proxy.open
2374
- end
2375
- end
2376
-
2377
- Example.new
2378
- ```
2379
-
2380
- #### App Name and Version
2381
-
2382
- 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.
2383
-
2384
- 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).
2385
-
2386
- Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2387
-
2388
- ```ruby
2389
- Display.setAppName('Glimmer Demo')
2390
-
2391
- shell(:no_resize) {
2392
- text "Glimmer"
2393
- label {
2394
- text "Hello, World!"
2395
- }
2396
- }.open
2397
- ```
2398
-
2399
- 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.
2400
-
2401
- #### Video Widget
2402
-
2403
- [![Video Widget](images/glimmer-video-widget.png)](https://github.com/AndyObtiva/glimmer-cw-video)
2404
-
2405
- Glimmer supports a [video custom widget](https://github.com/AndyObtiva/glimmer-cw-video) not in SWT.
2406
-
2407
- You may obtain via `glimmer-cw-video` gem.
2408
-
2409
- #### Browser Widget
2410
-
2411
- ![Hello Browser](images/glimmer-hello-browser.png)
2412
-
2413
- 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).
2414
-
2415
- Example loading a URL (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
2416
-
2417
- ```ruby
2418
- shell {
2419
- minimum_size 1024, 860
2420
- browser {
2421
- url 'http://brightonresort.com/about'
2422
- }
2423
- }.open
2424
- ```
2425
-
2426
- 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)):
2427
-
2428
- ```ruby
2429
- shell {
2430
- minimum_size 130, 130
2431
- @browser = browser {
2432
- text html {
2433
- head {
2434
- meta(name: "viewport", content: "width=device-width, initial-scale=2.0")
2435
- }
2436
- body {
2437
- h1 { "Hello, World!" }
2438
- }
2439
- }
2440
- on_completed { # on load of the page execute this JavaScript
2441
- @browser.swt_widget.execute("alert('Hello, World!');")
2442
- }
2443
- }
2444
- }.open
2445
- ```
2446
-
2447
- 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).
2448
-
2449
- ## Glimmer Configuration
2450
-
2451
- Glimmer configuration may be done via the `Glimmer::Config` module.
2452
-
2453
- ### logger
2454
-
2455
- Glimmer supports logging via a standard `STDOUT` Ruby `Logger` configured in the `Glimmer::Config.logger` config option.
2456
- It is set to level Logger::ERROR by default.
2457
- Log level may be adjusted via `Glimmer::Config.logger.level` just like any other Ruby Logger.
2458
- It may be replaced with a custom logger via `Glimmer::Config.logger = custom_logger`
2459
- 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.
2460
-
2461
- Example:
2462
-
2463
- ```ruby
2464
- Glimmer::Config.logger.level = :debug
2465
- ```
2466
- This results in more verbose debug loggging to `STDOUT`, which is very helpful in troubleshooting Glimmer DSL syntax when needed.
2467
-
2468
- Example log:
2469
- ```
2470
- D, [2017-07-21T19:23:12.587870 #35707] DEBUG -- : method: shell and args: []
2471
- D, [2017-07-21T19:23:12.594405 #35707] DEBUG -- : ShellCommandHandler will handle command: shell with arguments []
2472
- D, [2017-07-21T19:23:12.844775 #35707] DEBUG -- : method: composite and args: []
2473
- D, [2017-07-21T19:23:12.845388 #35707] DEBUG -- : parent is a widget: true
2474
- D, [2017-07-21T19:23:12.845833 #35707] DEBUG -- : on listener?: false
2475
- D, [2017-07-21T19:23:12.864395 #35707] DEBUG -- : WidgetCommandHandler will handle command: composite with arguments []
2476
- D, [2017-07-21T19:23:12.864893 #35707] DEBUG -- : widget styles are: []
2477
- D, [2017-07-21T19:23:12.874296 #35707] DEBUG -- : method: list and args: [:multi]
2478
- D, [2017-07-21T19:23:12.874969 #35707] DEBUG -- : parent is a widget: true
2479
- D, [2017-07-21T19:23:12.875452 #35707] DEBUG -- : on listener?: false
2480
- D, [2017-07-21T19:23:12.878434 #35707] DEBUG -- : WidgetCommandHandler will handle command: list with arguments [:multi]
2481
- D, [2017-07-21T19:23:12.878798 #35707] DEBUG -- : widget styles are: [:multi]
2482
- ```
2483
-
2484
- ### import_swt_packages
2485
-
2486
- 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.
2487
-
2488
- As a result, you may call SWT Java classes from Glimmer Ruby code without mentioning Java package references explicitly.
2489
-
2490
- For example, `org.eclipse.swt.graphics.Color` can be referenced as just `Color`
2491
-
2492
- 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:
2493
- ```
2494
- org.eclipse.swt.*
2495
- org.eclipse.swt.widgets.*
2496
- org.eclipse.swt.layout.*
2497
- org.eclipse.swt.graphics.*
2498
- org.eclipse.swt.browser.*
2499
- org.eclipse.swt.custom.*
2500
- org.eclipse.swt.dnd.*
2501
- ```
2502
-
2503
- 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).
2504
-
2505
- Example:
2506
-
2507
- ```ruby
2508
- Glimmer::Config.import_swt_packages += [
2509
- 'org.eclipse.nebula.widgets.ganttchart'
2510
- ]
2511
- ```
2512
-
2513
- 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)
2514
-
2515
- Nonetheless, you can disable automatic Java package import if needed via this Glimmer configuration option:
2516
-
2517
- ```ruby
2518
- Glimmer::Config.import_swt_packages = false
2519
- ```
2520
-
2521
- Once disabled, to import SWT Java packages manually, you may simply:
2522
-
2523
- 1. `include Glimmer::SWT::Packages`: lazily imports all SWT Java packages to your class, lazy-loading SWT Java class constants on first reference.
2524
-
2525
- 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'`)
2526
-
2527
- 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.
2528
-
2529
- You can learn more about importing Java packages into Ruby code at this JRuby WIKI page:
2530
-
2531
- https://github.com/jruby/jruby/wiki/CallingJavaFromJRuby
2532
-
2533
- ### loop_max_count
2534
-
2535
- Glimmer has infinite loop detection support.
2536
- It can detect when an infinite loop is about to occur in method_missing and stops it.
2537
- It detects potential infinite loops when the same keyword and args repeat more than 100 times, which is unusual in a GUI app.
2538
-
2539
- The max limit can be changed via the `Glimmer::Config::loop_max_count=(count)` config option.
2540
-
2541
- Infinite loop detection may be disabled altogether if needed by setting `Glimmer::Config::loop_max_count` to `-1`
2542
-
2543
- ## Glimmer Style Guide
2544
-
2545
- - Widgets are declared with underscored lowercase versions of their SWT names minus the SWT package name.
2546
- - Widget declarations may optionally have arguments and be followed by a block (to contain properties and content)
2547
- - Widget blocks are always declared with curly braces
2548
- - Widget arguments are always wrapped inside parentheses
2549
- - Widget properties are declared with underscored lowercase versions of the SWT properties
2550
- - Widget property declarations always have arguments and never take a block
2551
- - Widget property arguments are never wrapped inside parentheses
2552
- - Widget listeners are always declared starting with `on_` prefix and affixing listener event method name afterwards in underscored lowercase form
2553
- - 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)
2554
- - Data-binding is done via `bind` keyword, which always takes arguments wrapped in parentheses
2555
- - Custom widget body, before_body, and after_body blocks open their blocks and close them with curly braces.
2556
- - 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.
2557
-
2558
- ## SWT Reference
2559
-
2560
- https://www.eclipse.org/swt/docs.php
2561
-
2562
- Here is the SWT API:
2563
-
2564
- https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/index.html
2565
-
2566
- Here is a visual list of SWT widgets:
2567
-
2568
- https://www.eclipse.org/swt/widgets/
2569
-
2570
- Here is a textual list of SWT widgets:
2571
-
2572
- https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/guide/swt_widgets_controls.htm?cp=2_0_7_0_0
2573
-
2574
- Here is a list of SWT style bits as used in widget declaration:
2575
-
2576
- https://wiki.eclipse.org/SWT_Widget_Style_Bits
2577
-
2578
- Here is a SWT style bit constant reference:
2579
-
2580
- https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html
2581
-
2582
- Here is an SWT Drag and Drop guide:
2583
-
2584
- https://www.eclipse.org/articles/Article-SWT-DND/DND-in-SWT.html
2585
-
2586
- Here is an SWT Custom Widget guide:
2587
-
2588
- https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm
2589
-
2590
- ## Samples
2591
-
2592
- 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`).
2593
-
2594
- 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:
2595
-
2596
- ```
2597
- samples/launch
2598
- ```
2599
-
2600
- ### Hello Samples
2601
-
2602
- For hello-type simple samples, check the following.
2603
-
2604
- #### Hello, World! Sample
2605
-
2606
- Code:
2607
-
2608
- [samples/hello/hello_world.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_world.rb)
2609
-
2610
- Run:
2611
-
2612
- ```
2613
- glimmer samples/hello/hello_world.rb
2614
- ```
2615
-
2616
- ![Hello World](images/glimmer-hello-world.png)
2617
-
2618
- #### Hello, Tab!
2619
-
2620
- Code:
2621
-
2622
- [samples/hello/hello_tab.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_tab.rb)
2623
-
2624
- Run:
2625
-
2626
- ```
2627
- glimmer samples/hello/hello_tab.rb
2628
- ```
2629
-
2630
- ![Hello Tab English](images/glimmer-hello-tab-english.png)
2631
- ![Hello Tab French](images/glimmer-hello-tab-french.png)
2632
-
2633
- #### Hello, Combo!
2634
-
2635
- This sample demonstrates combo data-binding.
2636
-
2637
- Code:
2638
-
2639
- [samples/hello/hello_combo.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_combo.rb)
2640
-
2641
- Run:
2642
-
2643
- ```
2644
- glimmer samples/hello/hello_combo.rb
2645
- ```
2646
-
2647
- ![Hello Combo](images/glimmer-hello-combo.png)
2648
- ![Hello Combo Expanded](images/glimmer-hello-combo-expanded.png)
2649
-
2650
- #### Hello, List Single Selection!
2651
-
2652
- This sample demonstrates list single-selection data-binding.
2653
-
2654
- Code:
192
+
193
+ composite {
194
+ row_layout {
195
+ margin_width 0
196
+ margin_height 0
197
+ }
198
+ layout_data(:right, :center, false, false) {
199
+ horizontal_span 2
200
+ }
201
+
202
+ button {
203
+ text "&Find"
204
+ on_widget_selected { @contact_manager_presenter.find }
205
+ on_key_pressed {|key_event|
206
+ @contact_manager_presenter.find if key_event.keyCode == swt(:cr)
207
+ }
208
+ }
209
+
210
+ button {
211
+ text "&List All"
212
+ on_widget_selected { @contact_manager_presenter.list }
213
+ on_key_pressed {|key_event|
214
+ @contact_manager_presenter.list if key_event.keyCode == swt(:cr)
215
+ }
216
+ }
217
+ }
218
+ }
2655
219
 
2656
- [samples/hello/hello_list_single_selection.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_list_single_selection.rb)
220
+ table(:multi) { |table_proxy|
221
+ layout_data {
222
+ horizontal_alignment :fill
223
+ vertical_alignment :fill
224
+ grab_excess_horizontal_space true
225
+ grab_excess_vertical_space true
226
+ height_hint 200
227
+ }
228
+ table_column {
229
+ text "First Name"
230
+ width 80
231
+ }
232
+ table_column {
233
+ text "Last Name"
234
+ width 80
235
+ }
236
+ table_column {
237
+ text "Email"
238
+ width 200
239
+ }
240
+ items bind(@contact_manager_presenter, :results),
241
+ column_properties(:first_name, :last_name, :email)
242
+ on_mouse_up { |event|
243
+ table_proxy.edit_table_item(event.table_item, event.column_index)
244
+ }
245
+ }
246
+ }
247
+ }.open
248
+ # ...
249
+ ```
2657
250
 
2658
251
  Run:
2659
252
 
2660
253
  ```
2661
- glimmer samples/hello/hello_list_single_selection.rb
254
+ glimmer sample:run[contact_manager]
2662
255
  ```
2663
256
 
2664
- ![Hello List Single Selection](images/glimmer-hello-list-single-selection.png)
2665
-
2666
- #### Hello, List Multi Selection!
2667
-
2668
- This sample demonstrates list multi-selection data-binding.
257
+ Glimmer App:
2669
258
 
2670
- Code:
259
+ ![Contact Manager](images/glimmer-contact-manager.png)
2671
260
 
2672
- [samples/hello/hello_list_multi_selection.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_list_multi_selection.rb)
261
+ ### Production Desktop Apps Built with Glimmer DSL for SWT
2673
262
 
2674
- Run:
263
+ [<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
2675
264
 
2676
- ```
2677
- glimmer samples/hello/hello_list_multi_selection.rb
2678
- ```
265
+ ![Are We There Yet? App Screenshot](https://raw.githubusercontent.com/AndyObtiva/are-we-there-yet/master/are-we-there-yet-screenshot-windows.png)
2679
266
 
2680
- ![Hello List Multi Selection](images/glimmer-hello-list-multi-selection.png)
267
+ [<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
2681
268
 
2682
- #### Hello, Computed!
269
+ ![Math Bowling App Screenshot](https://raw.githubusercontent.com/AndyObtiva/MathBowling/master/Math-Bowling-Screenshot.png)
2683
270
 
2684
- This sample demonstrates computed data-binding.
271
+ ## Glimmer DSL for Tk (Ruby Desktop Development GUI Library)
2685
272
 
2686
- Code:
273
+ [Tcl/Tk](https://www.tcl.tk/) has evolved into a practical desktop GUI toolkit due to gaining true native widgets on Mac, Windows, and Linux in [Tk version 8.5](https://www.tcl.tk/software/tcltk/8.5.html#:~:text=Highlights%20of%20Tk%208.5&text=Font%20rendering%3A%20Now%20uses%20anti,and%20window%20layout%2C%20and%20more.).
2687
274
 
2688
- [samples/hello/hello_computed.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_computed.rb)
275
+ Additionally, [Ruby](https://www.ruby-lang.org/en/) 3.0 Ractor (formerly known as [Guilds](https://olivierlacan.com/posts/concurrency-in-ruby-3-with-guilds/)) supports truly parallel multi-threading, making both [MRI](https://github.com/ruby/ruby) and [Tk](https://www.tcl.tk/) finally viable for support in [Glimmer](https://github.com/AndyObtiva/glimmer) (Ruby Desktop Development GUI Library) as an alternative to [JRuby on SWT](https://github.com/AndyObtiva/glimmer-dsl-swt).
2689
276
 
2690
- Run:
277
+ The trade-off is that while [SWT](https://www.eclipse.org/swt/) provides a plethora of high quality reusable widgets for the Enterprise (such as [Nebula](https://www.eclipse.org/nebula/)), [Tk](https://www.tcl.tk/) enables very fast app startup time via [MRI Ruby](https://www.ruby-lang.org/en/).
2691
278
 
2692
- ```
2693
- glimmer samples/hello/hello_computed.rb
2694
- ```
279
+ [Glimmer DSL for Tk](https://github.com/AndyObtiva/glimmer-dsl-tk) aims to provide a DSL similar to the [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) to enable more productive desktop development in Ruby with:
280
+ - Declarative DSL syntax that visually maps to the GUI widget hierarchy
281
+ - Convention over configuration via smart defaults and automation of low-level details
282
+ - Requiring the least amount of syntax possible to build GUI
283
+ - Bidirectional Data-Binding to declaratively wire and automatically synchronize GUI with Business Models
284
+ - Custom Widget support
285
+ - Scaffolding for new custom widgets, apps, and gems
286
+ - Native-Executable packaging on Mac, Windows, and Linux
2695
287
 
2696
- ![Hello Browser](images/glimmer-hello-computed.png)
288
+ ### Glimmer DSL for Tk Samples
2697
289
 
2698
- #### Hello, Message Box!
290
+ #### Hello, World!
2699
291
 
2700
- This sample demonstrates a `message_box` dialog.
292
+ Glimmer code (from [samples/hello/hello_world.rb](https://github.com/AndyObtiva/glimmer-dsl-tk/blob/master/samples/hello/hello_world.rb)):
2701
293
 
2702
- Code:
294
+ ```ruby
295
+ include Glimmer
2703
296
 
2704
- [samples/hello/hello_message_box.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_message_box.rb)
297
+ root {
298
+ label {
299
+ text 'Hello, World!'
300
+ }
301
+ }.open
302
+ ```
2705
303
 
2706
- Run:
304
+ Run (with the [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed):
2707
305
 
2708
306
  ```
2709
- glimmer samples/hello/hello_message_box.rb
307
+ ruby -r glimmer-dsl-tk -e "require '../samples/hello/hello_world.rb'"
2710
308
  ```
2711
309
 
2712
- ![Hello Message Box](images/glimmer-hello-message-box.png)
2713
- ![Hello Message Box Dialog](images/glimmer-hello-message-box-dialog.png)
2714
-
2715
- #### Hello, Browser!
310
+ Glimmer app:
2716
311
 
2717
- This sample demonstrates the `browser` widget.
312
+ ![glimmer dsl tk screenshot sample hello world](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-tk/master/images/glimmer-dsl-tk-screenshot-sample-hello-world.png)
2718
313
 
2719
- Code:
314
+ #### Hello, Tab!
2720
315
 
2721
- [samples/hello/hello_browser.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_browser.rb)
316
+ Glimmer code (from [samples/hello/hello_tab.rb](https://github.com/AndyObtiva/glimmer-dsl-tk/blob/master/samples/hello/hello_tab.rb)):
2722
317
 
2723
- Run:
318
+ ```ruby
319
+ include Glimmer
2724
320
 
321
+ root {
322
+ title 'Hello, Tab!'
323
+
324
+ notebook {
325
+ frame(text: 'English') {
326
+ label {
327
+ text 'Hello, World!'
328
+ }
329
+ }
330
+
331
+ frame(text: 'French') {
332
+ label {
333
+ text 'Bonjour, Univers!'
334
+ }
335
+ }
336
+ }
337
+ }.open
2725
338
  ```
2726
- glimmer samples/hello/hello_browser.rb
2727
- ```
2728
-
2729
- ![Hello Browser](images/glimmer-hello-browser.png)
2730
339
 
2731
- #### Hello, Drag and Drop!
2732
-
2733
- This sample demonstrates drag and drop in Glimmer.
2734
-
2735
- Code:
2736
-
2737
- [samples/hello/hello_drag_and_drop.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_drag_and_drop.rb)
2738
-
2739
- Run:
340
+ Run (with the [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed):
2740
341
 
2741
342
  ```
2742
- glimmer samples/hello/hello_drag_and_drop.rb
343
+ ruby -r glimmer-dsl-tk -e "require '../samples/hello/hello_tab.rb'"
2743
344
  ```
2744
345
 
2745
- ![Hello Drag and Drop](images/glimmer-hello-drag-and-drop.gif)
346
+ Glimmer app:
2746
347
 
2747
- #### Hello, Menu Bar!
348
+ ![glimmer dsl tk screenshot sample hello tab English](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-tk/master/images/glimmer-dsl-tk-screenshot-sample-hello-tab-english.png)
349
+ ![glimmer dsl tk screenshot sample hello tab French](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-tk/master/images/glimmer-dsl-tk-screenshot-sample-hello-tab-french.png)
2748
350
 
2749
- This sample demonstrates menus in Glimmer.
351
+ #### Hello, Combo!
2750
352
 
2751
- Code:
353
+ Glimmer code (from [samples/hello/hello_combo.rb](https://github.com/AndyObtiva/glimmer-dsl-tk/blob/master/samples/hello/hello_combo.rb)):
2752
354
 
2753
- [samples/hello/hello_menu_bar.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_menu_bar.rb)
355
+ ```ruby
356
+ # ... more code precedes
357
+ root {
358
+ title 'Hello, Combo!'
359
+
360
+ combobox { |proxy|
361
+ state 'readonly'
362
+ text bind(person, :country)
363
+ }
364
+
365
+ button { |proxy|
366
+ text "Reset Selection"
367
+ command {
368
+ person.reset_country
369
+ }
370
+ }
371
+ }.open
372
+ # ... more code follows
373
+ ```
2754
374
 
2755
- Run:
375
+ Run (with the [glimmer-dsl-tk](https://rubygems.org/gems/glimmer-dsl-tk) gem installed):
2756
376
 
2757
377
  ```
2758
- glimmer samples/hello/hello_menu_bar.rb
378
+ ruby -r glimmer-dsl-tk -e "require '../samples/hello/hello_combo.rb'"
2759
379
  ```
2760
380
 
2761
- ![Hello Menu Bar](images/glimmer-hello-menu-bar.png)
2762
- ![Hello Menu Bar File Menu](images/glimmer-hello-menu-bar-file-menu.png)
2763
- ![Hello Menu Bar History Menu](images/glimmer-hello-menu-bar-history-menu.png)
381
+ Glimmer app:
2764
382
 
2765
- #### Hello, Pop Up Context Menu!
383
+ ![glimmer dsl tk screenshot sample hello combo](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-tk/master/images/glimmer-dsl-tk-screenshot-sample-hello-combo.png)
384
+ ![glimmer dsl tk screenshot sample hello combo dropdown](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-tk/master/images/glimmer-dsl-tk-screenshot-sample-hello-combo-dropdown.png)
2766
385
 
2767
- This sample demonstrates pop up context menus in Glimmer.
386
+ ## Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
2768
387
 
2769
- Code:
388
+ [Glimmer DSL for Opal](https://github.com/AndyObtiva/glimmer-dsl-opal) is an experimental proof-of-concept web GUI adapter for [Glimmer](https://github.com/AndyObtiva/glimmer) desktop apps (i.e. apps built with [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt)). It webifies them via [Rails](https://rubyonrails.org/), allowing Ruby desktop apps to run on the web via [Opal Ruby](https://opalrb.com/) without changing a line of code. Apps may then be custom-styled for the web with standard CSS.
2770
389
 
2771
- [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)
390
+ Glimmer DSL for Opal webifier successfully reuses the entire [Glimmer](https://github.com/AndyObtiva/glimmer) core DSL engine in [Opal Ruby](https://opalrb.com/) inside a web browser, and as such inherits the full range of powerful Glimmer desktop [data-binding](https://github.com/AndyObtiva/glimmer#data-binding) capabilities for the web.
2772
391
 
2773
- Run:
392
+ ### Glimmer DSL for Opal Samples
2774
393
 
2775
- ```
2776
- glimmer samples/hello/hello_pop_up_context_menu.rb
2777
- ```
394
+ #### Hello, Computed!
2778
395
 
2779
- ![Hello Pop Up Context Menu](images/glimmer-hello-pop-up-context-menu.png)
2780
- ![Hello Pop Up Context Menu Popped Up](images/glimmer-hello-pop-up-context-menu-popped-up.png)
396
+ Add the following require statement to `app/assets/javascripts/application.rb`
2781
397
 
2782
- ### Elaborate Samples
2783
398
 
2784
- For more elaborate samples, check the following:
399
+ ```ruby
400
+ require 'samples/hello/hello_computed'
401
+ ```
2785
402
 
2786
- #### Login
403
+ Or add the Glimmer code directly if you prefer to play around with it:
2787
404
 
2788
- This sample demonstrates basic data-binding, password and text fields, and field enablement data-binding.
405
+ ```ruby
406
+ class HelloComputed
407
+ class Contact
408
+ attr_accessor :first_name, :last_name, :year_of_birth
409
+
410
+ def initialize(attribute_map)
411
+ @first_name = attribute_map[:first_name]
412
+ @last_name = attribute_map[:last_name]
413
+ @year_of_birth = attribute_map[:year_of_birth]
414
+ end
415
+
416
+ def name
417
+ "#{last_name}, #{first_name}"
418
+ end
419
+
420
+ def age
421
+ Time.now.year - year_of_birth.to_i
422
+ rescue
423
+ 0
424
+ end
425
+ end
426
+ end
2789
427
 
2790
- Code:
428
+ class HelloComputed
429
+ include Glimmer
2791
430
 
2792
- [samples/elaborate/login.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/login.rb)
431
+ def initialize
432
+ @contact = Contact.new(
433
+ first_name: 'Barry',
434
+ last_name: 'McKibbin',
435
+ year_of_birth: 1985
436
+ )
437
+ end
2793
438
 
2794
- Run:
439
+ def launch
440
+ shell {
441
+ text 'Hello, Computed!'
442
+ composite {
443
+ grid_layout {
444
+ num_columns 2
445
+ make_columns_equal_width true
446
+ horizontal_spacing 20
447
+ vertical_spacing 10
448
+ }
449
+ label {text 'First &Name: '}
450
+ text {
451
+ text bind(@contact, :first_name)
452
+ layout_data {
453
+ horizontal_alignment :fill
454
+ grab_excess_horizontal_space true
455
+ }
456
+ }
457
+ label {text '&Last Name: '}
458
+ text {
459
+ text bind(@contact, :last_name)
460
+ layout_data {
461
+ horizontal_alignment :fill
462
+ grab_excess_horizontal_space true
463
+ }
464
+ }
465
+ label {text '&Year of Birth: '}
466
+ text {
467
+ text bind(@contact, :year_of_birth)
468
+ layout_data {
469
+ horizontal_alignment :fill
470
+ grab_excess_horizontal_space true
471
+ }
472
+ }
473
+ label {text 'Name: '}
474
+ label {
475
+ text bind(@contact, :name, computed_by: [:first_name, :last_name])
476
+ layout_data {
477
+ horizontal_alignment :fill
478
+ grab_excess_horizontal_space true
479
+ }
480
+ }
481
+ label {text 'Age: '}
482
+ label {
483
+ text bind(@contact, :age, on_write: :to_i, computed_by: [:year_of_birth])
484
+ layout_data {
485
+ horizontal_alignment :fill
486
+ grab_excess_horizontal_space true
487
+ }
488
+ }
489
+ }
490
+ }.open
491
+ end
492
+ end
2795
493
 
494
+ HelloComputed.new.launch
2796
495
  ```
2797
- glimmer samples/elaborate/login.rb
2798
- ```
2799
-
2800
- ![Login](images/glimmer-login.png)
2801
- ![Login Filled In](images/glimmer-login-filled-in.png)
2802
- ![Login Logged In](images/glimmer-login-logged-in.png)
2803
-
2804
- #### Tic Tac Toe Sample
2805
-
2806
- 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)).
2807
-
2808
- Code:
496
+ Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
2809
497
 
2810
- [samples/elaborate/tic_tac_toe.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/tic_tac_toe.rb)
498
+ ![Glimmer DSL for SWT Hello Computed](https://github.com/AndyObtiva/glimmer/blob/master/images/glimmer-hello-computed.png)
2811
499
 
2812
- Run:
500
+ Glimmer app on the web (using `glimmer-dsl-opal` gem):
2813
501
 
502
+ Start the Rails server:
2814
503
  ```
2815
- glimmer samples/elaborate/tic_tac_toe.rb
504
+ rails s
2816
505
  ```
2817
506
 
2818
- ![Tic Tac Toe](images/glimmer-tic-tac-toe.png)
2819
- ![Tic Tac Toe In Progress](images/glimmer-tic-tac-toe-in-progress.png)
2820
- ![Tic Tac Toe Game Over](images/glimmer-tic-tac-toe-game-over.png)
507
+ Visit `http://localhost:3000`
2821
508
 
2822
- #### Contact Manager
509
+ You should see "Hello, Computed!"
2823
510
 
2824
- 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)).
511
+ ![Glimmer DSL for Opal Hello Computed](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-opal/master/images/glimmer-dsl-opal-hello-computed.png)
2825
512
 
2826
- Code:
513
+ #### Hello, List Single Selection!
2827
514
 
2828
- [samples/elaborate/contact_manager.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/elaborate/contact_manager.rb)
515
+ Add the following require statement to `app/assets/javascripts/application.rb`
2829
516
 
2830
- Run:
2831
517
 
518
+ ```ruby
519
+ require 'samples/hello/hello_list_single_selection'
2832
520
  ```
2833
- glimmer samples/elaborate/contact_manager.rb
2834
- ```
2835
-
2836
- Contact Manager
2837
-
2838
- ![Contact Manager](images/glimmer-contact-manager.png)
2839
-
2840
- Contact Manager - Find
2841
-
2842
- ![Contact Manager](images/glimmer-contact-manager-find.png)
2843
-
2844
- Contact Manager - Edit Started
2845
521
 
2846
- ![Contact Manager](images/glimmer-contact-manager-edit-started.png)
522
+ Or add the Glimmer code directly if you prefer to play around with it:
2847
523
 
2848
- Contact Manager - Edit In Progress
524
+ ```ruby
525
+ class Person
526
+ attr_accessor :country, :country_options
2849
527
 
2850
- ![Contact Manager](images/glimmer-contact-manager-edit-in-progress.png)
528
+ def initialize
529
+ self.country_options=["", "Canada", "US", "Mexico"]
530
+ self.country = "Canada"
531
+ end
2851
532
 
2852
- Contact Manager - Edit Done
533
+ def reset_country
534
+ self.country = "Canada"
535
+ end
536
+ end
2853
537
 
2854
- ![Contact Manager](images/glimmer-contact-manager-edit-done.png)
538
+ class HelloListSingleSelection
539
+ include Glimmer
540
+ def launch
541
+ person = Person.new
542
+ shell {
543
+ composite {
544
+ list {
545
+ selection bind(person, :country)
546
+ }
547
+ button {
548
+ text "Reset"
549
+ on_widget_selected do
550
+ person.reset_country
551
+ end
552
+ }
553
+ }
554
+ }.open
555
+ end
556
+ end
2855
557
 
2856
- ### External Samples
558
+ HelloListSingleSelection.new.launch
559
+ ```
560
+ Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
2857
561
 
2858
- #### Glimmer Calculator
562
+ ![Glimmer DSL for SWT Hello List Single Selection](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-list-single-selection.png)
2859
563
 
2860
- [<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 project demonstrating data-binding and TDD (test-driven-development) with Glimmer following the MVP pattern (Model-View-Presenter).
564
+ Glimmer app on the web (using `glimmer-dsl-opal` gem):
2861
565
 
2862
- [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/master/glimmer-cs-calculator-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-calculator)
566
+ Start the Rails server:
567
+ ```
568
+ rails s
569
+ ```
2863
570
 
2864
- #### Gladiator
571
+ Visit `http://localhost:3000`
2865
572
 
2866
- [<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.
2867
- You may check it out to learn how to build a Glimmer Custom Shell gem.
573
+ You should see "Hello, List Single Selection!"
2868
574
 
2869
- [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/master/images/glimmer-gladiator.png" />](https://github.com/AndyObtiva/glimmer-cs-gladiator)
575
+ ![Glimmer DSL for Opal Hello List Single Selection](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-opal/master/images/glimmer-dsl-opal-hello-list-single-selection.png)
2870
576
 
2871
- Gladiator is a good demonstration of:
2872
- - MVP Pattern
2873
- - Tree data-binding
2874
- - List data-binding
2875
- - Text selection data-binding
2876
- - Tabs
2877
- - Context menus
2878
- - Custom Shell
2879
- - Custom widget
577
+ #### Hello, List Multi Selection!
2880
578
 
2881
- ## In Production
579
+ Add the following require statement to `app/assets/javascripts/application.rb`
2882
580
 
2883
- The following production apps have been built with Glimmer.
581
+ ```ruby
582
+ require 'samples/hello/hello_list_multi_selection'
583
+ ```
2884
584
 
2885
- ### Math Bowling
585
+ Or add the Glimmer code directly if you prefer to play around with it:
2886
586
 
2887
- [<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
587
+ ```ruby
588
+ class Person
589
+ attr_accessor :provinces, :provinces_options
2888
590
 
2889
- ### Are We There Yet?
591
+ def initialize
592
+ self.provinces_options=[
593
+ "",
594
+ "Quebec",
595
+ "Ontario",
596
+ "Manitoba",
597
+ "Saskatchewan",
598
+ "Alberta",
599
+ "British Columbia",
600
+ "Nova Skotia",
601
+ "Newfoundland"
602
+ ]
603
+ self.provinces = ["Quebec", "Manitoba", "Alberta"]
604
+ end
2890
605
 
2891
- [<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
606
+ def reset_provinces
607
+ self.provinces = ["Quebec", "Manitoba", "Alberta"]
608
+ end
609
+ end
2892
610
 
2893
- If you have a Glimmer app you would like referenced here, please mention in a Pull Request.
611
+ class HelloListMultiSelection
612
+ include Glimmer
613
+ def launch
614
+ person = Person.new
615
+ shell {
616
+ composite {
617
+ list(:multi) {
618
+ selection bind(person, :provinces)
619
+ }
620
+ button {
621
+ text "Reset"
622
+ on_widget_selected do
623
+ person.reset_provinces
624
+ end
625
+ }
626
+ }
627
+ }.open
628
+ end
629
+ end
2894
630
 
2895
- ## Packaging & Distribution
631
+ HelloListMultiSelection.new.launch
632
+ ```
633
+ Glimmer app on the desktop (using [`glimmer-dsl-swt`](https://github.com/AndyObtiva/glimmer-dsl-swt) gem):
2896
634
 
2897
- Glimmer apps may be packaged and distributed on the Mac, Windows, and Linux via these tools:
2898
- - Warbler (https://github.com/jruby/warbler): Enables bundling a Glimmer app into a JAR file
2899
- - javapackager (https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html): Enables packaging a JAR file as a DMG file on Mac, EXE on Windows, and multiple Linux supported formats on Linux.
635
+ ![Glimmer DSL for SWT Hello List Multi Selection](https://github.com/AndyObtiva/glimmer/raw/master/images/glimmer-hello-list-multi-selection.png)
2900
636
 
2901
- Glimmer simplifies the process of Mac packaging via the `glimmer package` command. It works out of the box for any application generated by [Glimmer Scaffolding](#scaffolding):
637
+ Glimmer app on the web (using `glimmer-dsl-opal` gem):
2902
638
 
639
+ Start the Rails server:
2903
640
  ```
2904
- glimmer package
641
+ rails s
2905
642
  ```
2906
643
 
2907
- This will automatically generate a JAR file under `./dist` directory using Warbler, which is then used to automatically generate a DMG file (and pkg/app) under `./packages/bundles` using `javapackager`.
2908
- JAR file name will match your application local directory name (e.g. `MathBowling.jar` for `~/code/MathBowling`)
2909
- 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)
2910
-
2911
- The `glimmer package` command will automatically set "mac.CFBundleIdentifier" to ="org.#{project_name}.application.#{project_name}".
2912
- You may override by configuring as an extra argument for javapackger (e.g. Glimmer::Package.javapackager_extra_args = " -Bmac.CFBundleIdentifier=org.andymaleh.application.MathBowling")
644
+ Visit `http://localhost:3000`
2913
645
 
2914
- ### Packaging Defaults
646
+ You should see "Hello, List Multi Selection!"
2915
647
 
2916
- Glimmer employs smart defaults in packaging.
648
+ ![Glimmer DSL for Opal Hello List Multi Selection](https://raw.githubusercontent.com/AndyObtiva/glimmer-dsl-opal/master/images/glimmer-dsl-opal-hello-list-multi-selection.png)
2917
649
 
2918
- 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.
650
+ ## Glimmer DSL for XML (& HTML)
2919
651
 
2920
- Also, the package will only include these directories: app, config, db, lib, script, bin, docs, fonts, images, sounds, videos
652
+ [Glimmer DSL for XML](https://github.com/AndyObtiva/glimmer-dsl-xml) provides Ruby syntax for building XML (eXtensible Markup Language) documents.
2921
653
 
2922
- 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:
654
+ Within the context of desktop development, Glimmer DSL for XML is useful in providing XML data for the [SWT Browser widget](https://github.com/AndyObtiva/glimmer/tree/master#browser-widget).
2923
655
 
2924
- ```
2925
- glimmer package:config
2926
- ```
2927
-
2928
- This will generate `config/warble.rb`, which you may configure and then run `glimmer package` afterwards.
2929
-
2930
- ### Packaging Configuration
656
+ ### XML DSL
2931
657
 
2932
- - Ensure you have a Ruby script under `bin` directory that launches the application, preferably matching your project directory name (e.g. `bin/math_bowling`) :
2933
- ```ruby
2934
- require_relative '../app/my_application.rb'
2935
- ```
2936
- - 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/)
2937
- - Include Version (Optional): Create a `VERSION` file in your application and fill it your app version on one line (e.g. `1.1.0`)
2938
- - 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).
2939
- - 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).
2940
-
2941
- ### javapackager Extra Arguments
658
+ Simply start with `html` keyword and add HTML inside its block using Glimmer DSL syntax.
659
+ Once done, you may call `to_s`, `to_xml`, or `to_html` to get the formatted HTML output.
2942
660
 
2943
- 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:
2944
- - https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719
2945
- - https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html
2946
- - https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/self-contained-packaging.html#BCGICFDB
2947
- - https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/self-contained-packaging.html
2948
- - https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMacAppStore/index.html#//apple_ref/doc/uid/TP40010572-CH16-SW8
661
+ Here are all the Glimmer XML DSL top-level keywords:
662
+ - `html`
663
+ - `tag`: enables custom tag creation for exceptional cases by passing tag name as '_name' attribute
664
+ - `name_space`: enables namespacing html tags
2949
665
 
2950
- The Glimmer rake task allows passing extra options to javapackager via:
2951
- - `Glimmer::Packager.javapackager_extra_args="..."` in your application Rakefile
2952
- - Environment variable: `JAVAPACKAGER_EXTRA_ARGS`
666
+ 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')` )
2953
667
 
2954
- Example (Rakefile):
668
+ Example (basic HTML):
2955
669
 
2956
670
  ```ruby
2957
- require 'glimmer/rake_task'
2958
-
2959
- Glimmer::Package.javapackager_extra_args = '-BlicenseType="MIT" -Bmac.category="public.app-category.business" -Bmac.signing-key-developer-id-app="Andy Maleh"'
671
+ @xml = html {
672
+ head {
673
+ meta(name: "viewport", content: "width=device-width, initial-scale=2.0")
674
+ }
675
+ body {
676
+ h1 { "Hello, World!" }
677
+ }
678
+ }
679
+ puts @xml
2960
680
  ```
2961
681
 
2962
- Note that `mac.category` defaults to "public.app-category.business", but can be overridden with one of the category UTI values mentioned here:
2963
-
2964
- https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMacAppStore/index.html#//apple_ref/doc/uid/TP40010572-CH16-SW8
2965
-
2966
- Example (env var):
682
+ Output:
2967
683
 
2968
684
  ```
2969
- JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"' glimmer package
685
+ <html><head><meta name="viewport" content="width=device-width, initial-scale=2.0" /></head><body><h1>Hello, World!</h1></body></html>
2970
686
  ```
2971
687
 
2972
- That overrides the default application display name.
688
+ ## Glimmer DSL for CSS
2973
689
 
2974
- ### Mac Application Distribution
2975
-
2976
- 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.
2977
-
2978
- 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
2979
-
2980
- DMG signing key argument:
2981
- ```
2982
- -Bmac.signing-key-developer-id-app="..."
2983
- ```
690
+ [Glimmer DSL for CSS](https://github.com/AndyObtiva/glimmer-dsl-css) provides Ruby syntax for building CSS (Cascading Style Sheets).
2984
691
 
2985
- PKG signing key argument:
2986
- ```
2987
- -Bmac.signing-key-developer-id-installer="..."
2988
- ```
692
+ Within the context of [Glimmer](https://github.com/AndyObtiva/glimmer) app development, Glimmer DSL for CSS is useful in providing CSS for the [SWT Browser widget](https://github.com/AndyObtiva/glimmer/tree/master#browser-widget).
2989
693
 
2990
- Mac App Store signing key arguments:
2991
- ```
2992
- -Bmac.signing-key-app="..."
2993
- -Bmac.signing-key-pkg="..."
2994
- ```
694
+ ### CSS DSL
2995
695
 
2996
- ### Self Signed Certificate
696
+ Simply start with `css` keyword and add stylesheet rule sets inside its block using Glimmer DSL syntax.
697
+ Once done, you may call `to_s` or `to_css` to get the formatted CSS output.
2997
698
 
2998
- 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".
699
+ `css` is the only top-level keyword in the Glimmer CSS DSL
2999
700
 
3000
- 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):
3001
- - Open Keychain Access
3002
- - Choose Keychain Access > Certificate Assistant > Create Certificate ...
3003
- - Enter Name (referred to below as "CertificateName")
3004
- - Set 'Certificate Type' to 'Code Signing'
3005
- - Create (if you alternatively override defaults, make sure to enable all capabilities)
3006
- - Add the following option to javapackager: `-Bmac.signing-key-developer-id-app="CertificateName"` via `Glimmer::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS`
701
+ Selectors may be specified by `s` keyword or HTML element keyword directly (e.g. `body`)
702
+ Rule property values may be specified by `pv` keyword or underscored property name directly (e.g. `font_size`)
3007
703
 
3008
704
  Example:
3009
705
 
3010
706
  ```ruby
3011
- Glimmer::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
707
+ @css = css {
708
+ body {
709
+ font_size '1.1em'
710
+ pv 'background', 'white'
711
+ }
712
+
713
+ s('body > h1') {
714
+ background_color :red
715
+ pv 'font-size', '2em'
716
+ }
717
+ }
718
+ puts @css
3012
719
  ```
3013
720
 
3014
- 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.
721
+ Output:
722
+
723
+ ```
724
+ body{font-size:1.1em;background:white}body > h1{background-color:red;font-size:2em}
725
+ ```
3015
726
 
3016
- ### Gotchas
727
+ ## Multi-DSL Support
3017
728
 
3018
- 1. Specifying License File
729
+ Glimmer allows mixing DSLs, which comes in handy when doing things like using a desktop Browser widget with HTML and CSS.
3019
730
 
3020
- 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.
3021
- Keep that in mind if you are not going to rely on the default `LICENSE.txt` support.
731
+ Glimmer DSL syntax consists mainly of:
732
+ - keywords (e.g. `table` for a table widget)
733
+ - style/args (e.g. :multi as in `table(:multi)` for a multi-line selection table widget)
734
+ - 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)
3022
735
 
3023
- Example:
736
+ DSLs are activated by specific keywords. For example, the `html` keyword activates the Glimmer DSL for XML. Glimmer automatically recognizes top-level keywords in each DSL and activates the DSL accordingly. Once done processing a nested DSL top-level keyword, Glimmer switches back to the prior DSL automatically.
3024
737
 
3025
- ```ruby
3026
- Glimmer::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="ACME.txt" -BlicenseType="ACME"'
3027
- ```
738
+ ## Glimmer Supporting Libraries
3028
739
 
3029
- 2. Mounted DMG Residue
740
+ Here is a list of notable 3rd party gems used by Glimmer and Glimmer DSLs:
741
+ - [jeweler](https://github.com/technicalpickles/jeweler): generates app gems during [Glimmer Scaffolding](https://github.com/AndyObtiva/glimmer-dsl-swt#scaffolding)
742
+ - [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)
743
+ - [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
744
+ - [os](https://github.com/rdp/os): provides OS detection capabilities (e.g. `OS.mac?` or `OS.windows?`) to write cross-platform code inexpensively
745
+ - [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`)
746
+ - [rake](https://github.com/ruby/rake): used to implement and execute `glimmer` commands
747
+ - [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.
748
+ - [super_module](https://github.com/AndyObtiva/super_module): used to cleanly write the Glimmer::UI:CustomWidget and Glimmer::UI::CustomShell modules
749
+ - [text-table](https://github.com/aptinio/text-table): renders textual data in a textual table for the command-line interface of Glimmer
750
+ - [warbler](https://github.com/jruby/warbler): converts a Glimmer app into a Java JAR file during packaging
3030
751
 
3031
- 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."
752
+ ## Glimmer Process
3032
753
 
3033
- 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):
754
+ [Glimmer Process](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.
3034
755
 
3035
- ```
3036
- 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
3037
- ```
756
+ Learn more by reading the [GPG](PROCESS.md) (Glimmer Process Guidelines)
3038
757
 
3039
758
  ## Resources
3040
759
 
@@ -3077,13 +796,14 @@ Glimmer DSL Engine specific tasks are at:
3077
796
 
3078
797
  **Contributors Wanted!**
3079
798
 
3080
- 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).
799
+ If you would like to contribute to Glimmer, please study up on Glimmer and [SWT](https://github.com/AndyObtiva/glimmer-dsl-swt#swt-reference), run all Glimmer [samples](https://github.com/AndyObtiva/glimmer-dsl-swt#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).
3081
800
 
3082
801
  You may apply for contributing to any of these Glimmer DSL gems whether you prefer to focus on the desktop or web:
3083
- - [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
802
+ - [glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop Development GUI Library)
803
+ - [glimmer-dsl-tk](https://github.com/AndyObtiva/glimmer-dsl-tk): Glimmer DSL for Tk (Ruby Desktop Development GUI Library)
3084
804
  - [glimmer-dsl-opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
3085
805
  - [glimmer-dsl-xml](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML)
3086
- - [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets)
806
+ - [glimmer-dsl-css](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS
3087
807
 
3088
808
  [CONTRIBUTING.md](CONTRIBUTING.md)
3089
809
 
@@ -3100,10 +820,9 @@ If your company would like to invest fulltime in further development of the Glim
3100
820
 
3101
821
  ## License
3102
822
 
3103
- [MIT](https://opensource.org/licenses/MIT)
823
+ [MIT](LICENSE.txt)
3104
824
 
3105
825
  Copyright (c) 2007-2020 - Andy Maleh.
3106
- See [LICENSE.txt](LICENSE.txt) for further details.
3107
826
 
3108
827
  --
3109
828