glimmer 0.7.3 → 0.7.8
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/{README.markdown → README.md} +164 -67
- data/VERSION +1 -1
- data/lib/glimmer/data_binding/model_binding.rb +1 -0
- data/lib/glimmer/data_binding/observable_model.rb +1 -3
- data/lib/glimmer/data_binding/table_items_binding.rb +1 -0
- data/lib/glimmer/data_binding/tree_items_binding.rb +30 -11
- data/lib/glimmer/dsl/swt/dialog_expression.rb +26 -0
- data/lib/glimmer/dsl/swt/widget_expression.rb +8 -1
- data/lib/glimmer/launcher.rb +18 -10
- data/lib/glimmer/rake_task.rb +3 -3
- data/lib/glimmer/scaffold.rb +213 -67
- data/lib/glimmer/swt/shell_proxy.rb +1 -4
- data/lib/glimmer/swt/tab_item_proxy.rb +6 -0
- data/lib/glimmer/swt/tree_proxy.rb +120 -0
- data/lib/glimmer/swt/widget_listener_proxy.rb +21 -4
- data/lib/glimmer/swt/widget_proxy.rb +46 -25
- data/lib/glimmer/ui/custom_widget.rb +10 -3
- metadata +8 -36
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 7a3d10cd74668598ac83511994d117f3b99f7332d798d671ddc412dcac3c92fa
|
4
|
+
data.tar.gz: 1daf7b7330d0e73790ec98c5ef3afdf3f991f0f447f5b72ce47bc70901bb8baa
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 81136d0e73a2e26f01bc16b8986f8569910a63509730766d6cb70a533e1fbe38fdce3bfc7e0488d5bbe2a76e10413a46b0765811960698f70a343d45ab3c78a2
|
7
|
+
data.tar.gz: e20bab1be17773690ac997385921e47520e324afe3b4efcf0f0b6ae4dcf00cd6bcaea9b36c048c9c1eec54023af4c853e8c9aaa55138b40fa58f4262cbd09872
|
@@ -1,8 +1,13 @@
|
|
1
|
-
# Glimmer 0.7.
|
1
|
+
# Glimmer 0.7.8 Beta (Desktop Development Library for Ruby)
|
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
|
+
[![Test Coverage](https://api.codeclimate.com/v1/badges/38fbc278022862794414/test_coverage)](https://codeclimate.com/github/AndyObtiva/glimmer/test_coverage)
|
5
|
+
[![Maintainability](https://api.codeclimate.com/v1/badges/38fbc278022862794414/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer/maintainability)
|
4
6
|
|
5
|
-
Glimmer is a native-
|
7
|
+
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.
|
8
|
+
|
9
|
+
[<img src="https://covers.oreillystatic.com/images/9780596519650/lrg.jpg" width=105 /><br />
|
10
|
+
Featured in<br />JRuby Cookbook](http://shop.oreilly.com/product/9780596519650.do)
|
6
11
|
|
7
12
|
## Examples
|
8
13
|
|
@@ -70,12 +75,10 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
|
|
70
75
|
|
71
76
|
## Table of Contents
|
72
77
|
|
73
|
-
|
74
|
-
- [Glimmer 0.7.3 Beta (JRuby Desktop UI DSL + Data-Binding)](#glimmer-058-beta-jruby-desktop-ui-dsl--data-binding)
|
78
|
+
- [Glimmer 0.7.8 Beta (Desktop Development Library for Ruby)](#glimmer-078-beta-desktop-development-library-for-ruby)
|
75
79
|
- [Examples](#examples)
|
76
|
-
- [Hello World](#hello-world)
|
80
|
+
- [Hello, World!](#hello-world)
|
77
81
|
- [Tic Tac Toe](#tic-tac-toe)
|
78
|
-
- [Table of Contents](#table-of-contents)
|
79
82
|
- [Background](#background)
|
80
83
|
- [Platform Support](#platform-support)
|
81
84
|
- [Pre-requisites](#pre-requisites)
|
@@ -85,6 +88,7 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
|
|
85
88
|
- [Glimmer Command](#glimmer-command)
|
86
89
|
- [Basic Usage](#basic-usage)
|
87
90
|
- [Advanced Usage](#advanced-usage)
|
91
|
+
- [Scaffolding](#scaffolding)
|
88
92
|
- [Girb (Glimmer irb) Command](#girb-glimmer-irb-command)
|
89
93
|
- [Glimmer DSL Syntax](#glimmer-dsl-syntax)
|
90
94
|
- [Widgets](#widgets)
|
@@ -99,26 +103,31 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
|
|
99
103
|
- [Miscellaneous](#miscellaneous)
|
100
104
|
- [Glimmer Style Guide](#glimmer-style-guide)
|
101
105
|
- [Samples](#samples)
|
106
|
+
- [Hello Samples](#hello-samples)
|
107
|
+
- [Elaborate Samples](#elaborate-samples)
|
108
|
+
- [External Samples](#external-samples)
|
109
|
+
- [In Production](#in-production)
|
102
110
|
- [SWT Reference](#swt-reference)
|
103
111
|
- [SWT Packages](#swt-packages)
|
104
112
|
- [Logging](#logging)
|
105
113
|
- [Raw JRuby Command](#raw-jruby-command)
|
106
114
|
- [Mac Support](#mac-support)
|
107
115
|
- [Packaging & Distribution](#packaging--distribution)
|
108
|
-
- [Defaults](#defaults)
|
116
|
+
- [Packaging Defaults](#packaging-defaults)
|
117
|
+
- [Packaging Configuration](#packaging-configuration)
|
109
118
|
- [javapackager Extra Arguments](#javapackager-extra-arguments)
|
110
119
|
- [Mac Application Distribution](#mac-application-distribution)
|
111
120
|
- [Self Signed Certificate](#self-signed-certificate)
|
112
121
|
- [Gotchas](#gotchas)
|
113
122
|
- [Resources](#resources)
|
123
|
+
- [Help](#help)
|
124
|
+
- [Issues](#issues)
|
125
|
+
- [IRC Channel](#irc-channel)
|
114
126
|
- [Feature Suggestions](#feature-suggestions)
|
115
127
|
- [Change Log](#change-log)
|
116
128
|
- [Contributing](#contributing)
|
117
129
|
- [Contributors](#contributors)
|
118
130
|
- [License](#license)
|
119
|
-
<!-- TOC END -->
|
120
|
-
|
121
|
-
|
122
131
|
|
123
132
|
## Background
|
124
133
|
|
@@ -131,12 +140,12 @@ Glimmer runs on the following platforms:
|
|
131
140
|
- Windows
|
132
141
|
- Linux
|
133
142
|
|
134
|
-
Glimmer's
|
143
|
+
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:
|
135
144
|
- Win32 on Windows
|
136
145
|
- Cocoa on Mac
|
137
146
|
- GTK on Linux
|
138
147
|
|
139
|
-
More info about the SWT
|
148
|
+
More info about the SWT GUI on various platforms can be found on the Eclipse WIKI and SWT FAQ:
|
140
149
|
|
141
150
|
https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide#Win32.2FCocoa.2FGTK
|
142
151
|
https://www.eclipse.org/swt/faq.php
|
@@ -145,8 +154,9 @@ https://www.eclipse.org/swt/faq.php
|
|
145
154
|
## Pre-requisites
|
146
155
|
|
147
156
|
- SWT 4.15 (comes included in Glimmer gem)
|
148
|
-
- JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at https://www.jruby.org/download)
|
149
|
-
- Java SE Runtime Environment 7 or higher (find at https://www.oracle.com/java/technologies/javase-downloads.html)
|
157
|
+
- JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at [https://www.jruby.org/download](https://www.jruby.org/download))
|
158
|
+
- Java SE Runtime Environment 7 or higher (find at [https://www.oracle.com/java/technologies/javase-downloads.html](https://www.oracle.com/java/technologies/javase-downloads.html))
|
159
|
+
- (Optional) RVM is needed for [Scaffolding](#scaffolding) only (find at [https://rvm.io/](https://rvm.io/))
|
150
160
|
|
151
161
|
On **Mac** and **Linux**, an easy way to obtain JRuby is through [RVM](http://rvm.io) by running:
|
152
162
|
|
@@ -164,7 +174,7 @@ Please follow these instructions to make the `glimmer` command available on your
|
|
164
174
|
|
165
175
|
Run this command to install directly:
|
166
176
|
```
|
167
|
-
jgem install glimmer -v 0.7.
|
177
|
+
jgem install glimmer -v 0.7.8
|
168
178
|
```
|
169
179
|
|
170
180
|
`jgem` is JRuby's version of `gem` command.
|
@@ -175,7 +185,7 @@ Otherwise, you may also run `jruby -S gem install ...`
|
|
175
185
|
|
176
186
|
Add the following to `Gemfile`:
|
177
187
|
```
|
178
|
-
gem 'glimmer', '~> 0.7.
|
188
|
+
gem 'glimmer', '~> 0.7.8'
|
179
189
|
```
|
180
190
|
|
181
191
|
And, then run:
|
@@ -212,7 +222,7 @@ bin/glimmer samples/hello/hello_world.rb
|
|
212
222
|
Below are the full usage instructions that come up when running `glimmer` without args.
|
213
223
|
|
214
224
|
```
|
215
|
-
Usage: glimmer [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
|
225
|
+
Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
|
216
226
|
|
217
227
|
Runs Glimmer applications/tasks.
|
218
228
|
|
@@ -227,7 +237,7 @@ glimmer package:jar # Generate JAR
|
|
227
237
|
glimmer package:native # Generate Native files (DMG/PKG/APP on the Mac)
|
228
238
|
glimmer scaffold[app_name] # Scaffold a Glimmer application directory structure to begin building a new app
|
229
239
|
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)
|
230
|
-
glimmer scaffold:custom_shell_gem[
|
240
|
+
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)
|
231
241
|
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)
|
232
242
|
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)
|
233
243
|
|
@@ -237,8 +247,9 @@ automatically preloading the glimmer Ruby gem and SWT jar dependency.
|
|
237
247
|
Optionally, extra Glimmer options, JRuby options and environment variables may be passed in.
|
238
248
|
|
239
249
|
Glimmer options:
|
240
|
-
- "--
|
241
|
-
- "--
|
250
|
+
- "--quiet" : Does not announce file path of Glimmer application being launched nor enable logging
|
251
|
+
- "--debug" : Displays extra debugging information, passes "--debug" to JRuby, and enables debug logging
|
252
|
+
- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
|
242
253
|
|
243
254
|
Example: glimmer samples/hello_world.rb
|
244
255
|
|
@@ -270,7 +281,7 @@ getting you to a running and delivered state of an advanced "Hello, World!" Glim
|
|
270
281
|
This should greatly facilitate building a new Glimmer app by helping you be productive and focus on app details while
|
271
282
|
letting Glimmer scaffolding take care of initial app file structure concerns, such as adding:
|
272
283
|
- Main application class that includes Glimmer
|
273
|
-
- Main application view that houses main window content
|
284
|
+
- Main application view that houses main window content, about dialog, and preferences dialog
|
274
285
|
- View and Model directories
|
275
286
|
- Rakefile including Glimmer tasks
|
276
287
|
- Version
|
@@ -278,7 +289,7 @@ letting Glimmer scaffolding take care of initial app file structure concerns, su
|
|
278
289
|
- Icon
|
279
290
|
- Bin file for starting application
|
280
291
|
|
281
|
-
NOTE: Scaffolding currently supports Mac packaging only at the moment.
|
292
|
+
NOTE: Scaffolding requires RVM and currently supports Mac packaging only at the moment.
|
282
293
|
|
283
294
|
#### App
|
284
295
|
|
@@ -336,9 +347,13 @@ glimmer scaffold:custom_widget[custom_widget_name]
|
|
336
347
|
|
337
348
|
#### Custom Shell Gem
|
338
349
|
|
339
|
-
Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
|
350
|
+
Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
|
351
|
+
They have everything scaffolded Glimmer apps come with in addition to gem content like a Jeweler Rakefile that can build gemspec and release gems.
|
352
|
+
Unlike scaffolded Glimmer apps, custom shell gem content lives under the `lib` directory (not `app`).
|
353
|
+
They can be packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem.
|
354
|
+
Of course, you can just build a Ruby gem and disregard native executable packaging if you do not need it.
|
340
355
|
|
341
|
-
To scaffold a Glimmer custom shell gem (full window view
|
356
|
+
To scaffold a Glimmer custom shell gem (full window view distributed as a Ruby gem), run the following command:
|
342
357
|
|
343
358
|
```
|
344
359
|
glimmer scaffold:custom_shell_gem[custom_shell_name, namespace]
|
@@ -346,15 +361,18 @@ glimmer scaffold:custom_shell_gem[custom_shell_name, namespace]
|
|
346
361
|
|
347
362
|
It is important to specify a namespace to avoid having your gem clash with existing gems.
|
348
363
|
|
349
|
-
The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell)
|
364
|
+
The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell).
|
350
365
|
|
351
366
|
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)
|
352
367
|
|
353
|
-
|
368
|
+
Examples:
|
369
|
+
|
370
|
+
- [glimmer-cs-gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator): Gladiator (Glimmer Editor)
|
371
|
+
- [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator): Glimmer Calculator
|
354
372
|
|
355
373
|
#### Custom Widget Gem
|
356
374
|
|
357
|
-
To scaffold a Glimmer custom widget gem (part of a view
|
375
|
+
To scaffold a Glimmer custom widget gem (part of a view distributed as a Ruby gem), run the following command:
|
358
376
|
|
359
377
|
```
|
360
378
|
glimmer scaffold:custom_widget_gem[custom_widget_name, namespace]
|
@@ -404,7 +422,7 @@ You will learn more about widgets next.
|
|
404
422
|
|
405
423
|
### Widgets
|
406
424
|
|
407
|
-
Glimmer
|
425
|
+
Glimmer GUIs (user interfaces) are modeled with widgets, which are wrappers around the SWT library widgets found here:
|
408
426
|
|
409
427
|
https://www.eclipse.org/swt/widgets/
|
410
428
|
|
@@ -513,7 +531,7 @@ shell {
|
|
513
531
|
|
514
532
|
#### Display
|
515
533
|
|
516
|
-
SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage
|
534
|
+
SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage GUI globally
|
517
535
|
and access available monitors.
|
518
536
|
It is automatically instantiated upon first instantiation of a `shell` widget.
|
519
537
|
Alternatively, for advanced use cases, it can be created explicitly with Glimmer `display` keyword. When a `shell` is later declared, it
|
@@ -541,7 +559,7 @@ Glimmer follows Proxy Design Pattern by having Ruby proxy wrappers for all SWT o
|
|
541
559
|
- `Glimmer::SWT:TabItemProxy` wraps `org.eclipse.swt.widget.TabItem` (also adds a composite to enable adding content under tab items directly in Glimmer)
|
542
560
|
- `Glimmer::SWT:LayoutProxy` wraps all descendants of `org.eclipse.swt.widget.Layout`
|
543
561
|
- `Glimmer::SWT:LayoutDataProxy` wraps all layout data objects
|
544
|
-
- `Glimmer::SWT:DisplayProxy` wraps `org.eclipse.swt.widget.Display` (manages displaying
|
562
|
+
- `Glimmer::SWT:DisplayProxy` wraps `org.eclipse.swt.widget.Display` (manages displaying GUI)
|
545
563
|
- `Glimmer::SWT:ColorProxy` wraps `org.eclipse.swt.graphics.Color`
|
546
564
|
- `Glimmer::SWT:FontProxy` wraps `org.eclipse.swt.graphics.Font`
|
547
565
|
- `Glimmer::SWT::WidgetListenerProxy` wraps all widget listeners
|
@@ -610,6 +628,12 @@ Shell widget proxy has extra methods specific to SWT Shell:
|
|
610
628
|
- `#pack`: Packs contained widgets using SWT's `Shell#pack` method
|
611
629
|
- `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
|
612
630
|
|
631
|
+
#### Dialog
|
632
|
+
|
633
|
+
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.
|
634
|
+
|
635
|
+
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.
|
636
|
+
|
613
637
|
#### Menus
|
614
638
|
|
615
639
|
Glimmer DSL provides support for SWT Menu and MenuItem widgets.
|
@@ -734,6 +758,7 @@ Glimmer ships with SWT style **smart defaults** so you wouldn't have to set them
|
|
734
758
|
|
735
759
|
- `text(:border)`
|
736
760
|
- `table(:border)`
|
761
|
+
- `tree(:border, :virtual, :v_scroll, :h_scroll)`
|
737
762
|
- `spinner(:border)`
|
738
763
|
- `list(:border, :v_scroll)`
|
739
764
|
- `button(:push)`
|
@@ -1075,7 +1100,7 @@ https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/
|
|
1075
1100
|
|
1076
1101
|
Data-binding is done with `bind` command following widget property to bind and taking model and bindable attribute as arguments.
|
1077
1102
|
|
1078
|
-
|
1103
|
+
#### General data-binding examples:
|
1079
1104
|
|
1080
1105
|
`text bind(contact, :first_name)`
|
1081
1106
|
|
@@ -1098,6 +1123,10 @@ This example also specifies a converter on read of the model property, but via a
|
|
1098
1123
|
|
1099
1124
|
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.
|
1100
1125
|
|
1126
|
+
`text bind(contact, 'address.street', read_only: true)
|
1127
|
+
|
1128
|
+
This is read-ohly data-binding. It doesn't update contact.address.street when widget text property is changed.
|
1129
|
+
|
1101
1130
|
`text bind(contact, 'addresses[1].street')`
|
1102
1131
|
|
1103
1132
|
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.
|
@@ -1116,6 +1145,8 @@ This example demonstrates nested indexed computed value data binding whereby the
|
|
1116
1145
|
|
1117
1146
|
Example from [samples/hello/hello_combo.rb](samples/hello_combo.rb) sample (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
1118
1147
|
|
1148
|
+
#### Combo
|
1149
|
+
|
1119
1150
|
![Hello Combo](images/glimmer-hello-combo.png)
|
1120
1151
|
|
1121
1152
|
![Hello Combo](images/glimmer-hello-combo-expanded.png)
|
@@ -1159,6 +1190,8 @@ HelloCombo.new.launch
|
|
1159
1190
|
|
1160
1191
|
`combo` widget is data-bound to the country of a person. Note that it expects `person` object to have `:country` attribute and `:country_options` attribute containing all available countries.
|
1161
1192
|
|
1193
|
+
#### List
|
1194
|
+
|
1162
1195
|
Example from [samples/hello/hello_list_single_selection.rb](samples/hello_list_single_selection.rb) sample:
|
1163
1196
|
|
1164
1197
|
![Hello List Single Selection](images/glimmer-hello-list-single-selection.png)
|
@@ -1240,6 +1273,45 @@ Note that in all the data-binding examples above, there was also an observer att
|
|
1240
1273
|
|
1241
1274
|
You may learn more about Glimmer's data-binding syntax by reading the [Eclipse Zone Tutorial](http://eclipse.dzone.com/articles/an-introduction-glimmer) mentioned in resources and opening up the samples under the [samples](samples) directory.
|
1242
1275
|
|
1276
|
+
#### Tree
|
1277
|
+
|
1278
|
+
The SWT Tree widget visualizes a tree data-structure, such as an employment or composition hierarchy.
|
1279
|
+
|
1280
|
+
To data-bind a Tree, you need the root model, the children querying method, and the text display attribute on each child.
|
1281
|
+
|
1282
|
+
This involves using the `bind` keyword mentioned above in addition to a special `tree_properties` keyword that takes the children and text attribute methods.
|
1283
|
+
|
1284
|
+
Example:
|
1285
|
+
|
1286
|
+
```ruby
|
1287
|
+
shell {
|
1288
|
+
@tree = tree {
|
1289
|
+
items bind(company, :owner), tree_properties(children: :coworkers, text: :name)
|
1290
|
+
selection bind(company, :selected_coworker)
|
1291
|
+
}
|
1292
|
+
}
|
1293
|
+
```
|
1294
|
+
|
1295
|
+
The code above includes two data-bindings:
|
1296
|
+
- 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.
|
1297
|
+
- Tree `selection`, which binds the single tree item selected by the user to the attribute denoted by the `bind` keyword
|
1298
|
+
|
1299
|
+
Additionally, Tree `items` data-binding automatically stores each node model unto the SWT TreeItem object via `setData` method. This enables things like searchability.
|
1300
|
+
|
1301
|
+
The tree widget in Glimmer is represented by a subclass of `WidgetProxy` called `TreeProxy`.
|
1302
|
+
TreeProxy includes a `depth_first_search` method that takes a block to look for a tree item.
|
1303
|
+
|
1304
|
+
Example:
|
1305
|
+
|
1306
|
+
```ruby
|
1307
|
+
found_array = @tree.depth_first_search { |tree_item| tree_item.getData == company.owner }
|
1308
|
+
```
|
1309
|
+
|
1310
|
+
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.
|
1311
|
+
|
1312
|
+
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
|
1313
|
+
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.
|
1314
|
+
|
1243
1315
|
### Observer
|
1244
1316
|
|
1245
1317
|
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.
|
@@ -1352,7 +1424,7 @@ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
|
1352
1424
|
|
1353
1425
|
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.
|
1354
1426
|
|
1355
|
-
The alternative syntax can be helpful if you prefer to separate Glimmer observer declarations from Glimmer
|
1427
|
+
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.
|
1356
1428
|
|
1357
1429
|
#### Observing Models
|
1358
1430
|
|
@@ -1478,17 +1550,17 @@ Notice how `Red::Composite` became `red__composite` with double-underscore, whic
|
|
1478
1550
|
|
1479
1551
|
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.
|
1480
1552
|
|
1481
|
-
Custom Widgets have the following attributes
|
1553
|
+
Custom Widgets have the following attributes available to call from inside the `#body` method:
|
1482
1554
|
- `#parent`: Glimmer object parenting custom widget
|
1483
1555
|
- `#swt_style`: SWT style integer. Can be useful if you want to allow consumers to customize a widget inside the custom widget body
|
1484
|
-
- `#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
|
1556
|
+
- `#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)
|
1485
1557
|
- `#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.
|
1486
1558
|
- `#body_root`: top-most (root) widget returned from `#body` method.
|
1487
1559
|
- `#swt_widget`: actual SWT widget for `body_root`
|
1488
1560
|
|
1489
1561
|
Additionally, custom widgets can call the following class methods:
|
1490
|
-
- `.options`: declares a list of options by taking an option name array (symbols/strings). This generates option attribute
|
1491
|
-
- `.option`: declares a single option taking option name and default value as arguments (also generates
|
1562
|
+
- `.options`: 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)
|
1563
|
+
- `.option`: declares a single option taking option name and default value as arguments (also generates attribute accessors just like `.options`)
|
1492
1564
|
|
1493
1565
|
#### Content/Options Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
1494
1566
|
|
@@ -1886,7 +1958,7 @@ This relies on Glimmer's [Multi-DSL Support](https://github.com/AndyObtiva/glimm
|
|
1886
1958
|
- Widget property declarations always have arguments and never take a block
|
1887
1959
|
- Widget property arguments are never wrapped inside parentheses
|
1888
1960
|
- Widget listeners are always declared starting with `on_` prefix and affixing listener event method name afterwards in underscored lowercase form
|
1889
|
-
- Widget listeners are always followed by a block using curly braces (Only when declared in DSL. When invoked on widget object directly outside of
|
1961
|
+
- 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)
|
1890
1962
|
- Data-binding is done via `bind` keyword, which always takes arguments wrapped in parentheses
|
1891
1963
|
- Custom widget body, before_body, and after_body blocks open their blocks and close them with curly braces.
|
1892
1964
|
- 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.
|
@@ -1920,12 +1992,22 @@ glimmer samples/hello/hello_computed.rb # demonstrates computed data-binding
|
|
1920
1992
|
For more elaborate samples, check the following:
|
1921
1993
|
|
1922
1994
|
```
|
1923
|
-
glimmer samples/elaborate/login.rb # demonstrates
|
1995
|
+
glimmer samples/elaborate/login.rb # demonstrates basic data-binding
|
1924
1996
|
glimmer samples/elaborate/contact_manager.rb # demonstrates table data-binding
|
1925
1997
|
glimmer samples/elaborate/tic_tac_toe.rb # demonstrates a full MVC application
|
1926
1998
|
```
|
1927
1999
|
|
1928
|
-
|
2000
|
+
### External Samples
|
2001
|
+
|
2002
|
+
#### [Glimmer Calculator](https://github.com/AndyObtiva/glimmer-cs-calculator)
|
2003
|
+
|
2004
|
+
![Glimmer Calculator](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/v1.0.0/glimmer-cs-calculator-screenshot.png)
|
2005
|
+
|
2006
|
+
[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).
|
2007
|
+
|
2008
|
+
#### [Gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator)
|
2009
|
+
|
2010
|
+
![Gladiator](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/v0.1.5/images/glimmer-gladiator.png)
|
1929
2011
|
|
1930
2012
|
[Gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator) (short for Glimmer Editor) is a Glimmer sample project under on-going development.
|
1931
2013
|
You may check it out to learn how to build a Glimmer Custom Shell gem.
|
@@ -2054,33 +2136,20 @@ Glimmer apps may be packaged and distributed on the Mac, Windows, and Linux via
|
|
2054
2136
|
- Warbler (https://github.com/jruby/warbler): Enables bundling a Glimmer app into a JAR file
|
2055
2137
|
- 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.
|
2056
2138
|
|
2057
|
-
Glimmer simplifies the process
|
2058
|
-
|
2059
|
-
To use:
|
2060
|
-
- Create `Rakefile` in your app root directory
|
2061
|
-
- Add the following line to it: `require 'glimmer/rake_task'`
|
2062
|
-
- Create a Ruby script under bin (e.g. `bin/math_bowling`) to require the application file that uses Glimmer (e.g. `'../app/my_application.rb'`):
|
2063
|
-
```ruby
|
2064
|
-
require_relative '../app/my_application.rb'
|
2065
|
-
```
|
2066
|
-
- 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/)
|
2067
|
-
- Include Version (Optional): Create a `VERSION` file in your application and fill it your app version on one line (e.g. `1.1.0`)
|
2068
|
-
- 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).
|
2069
|
-
- 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).
|
2139
|
+
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](https://github.com/AndyObtiva/glimmer/blob/master/README.md#scaffolding):
|
2070
2140
|
|
2071
|
-
Now, you can run the following rake command to package your app into a Mac DMG file (using both Warbler and javapackager):
|
2072
2141
|
```
|
2073
|
-
|
2142
|
+
glimmer package
|
2074
2143
|
```
|
2075
2144
|
|
2076
|
-
This will generate a JAR file under `./dist` directory, which is then used to generate a DMG file (and pkg/app) under `./packages/bundles`.
|
2145
|
+
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`.
|
2077
2146
|
JAR file name will match your application local directory name (e.g. `MathBowling.jar` for `~/code/MathBowling`)
|
2078
2147
|
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)
|
2079
2148
|
|
2080
|
-
|
2149
|
+
The `glimmer package` command will automatically set "mac.CFBundleIdentifier" to ="org.#{project_name}.application.#{project_name}".
|
2081
2150
|
You may override by configuring as an extra argument for javapackger (e.g. Glimmer::Package.javapackager_extra_args = " -Bmac.CFBundleIdentifier=org.andymaleh.application.MathBowling")
|
2082
2151
|
|
2083
|
-
### Defaults
|
2152
|
+
### Packaging Defaults
|
2084
2153
|
|
2085
2154
|
Glimmer employs smart defaults in packaging.
|
2086
2155
|
|
@@ -2088,13 +2157,24 @@ The package application name (shows up in top menu bar on the Mac) will be a hum
|
|
2088
2157
|
|
2089
2158
|
Also, the package will only include these directories: app, config, db, lib, script, bin, docs, fonts, images, sounds, videos
|
2090
2159
|
|
2091
|
-
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 `
|
2160
|
+
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:
|
2092
2161
|
|
2093
2162
|
```
|
2094
|
-
|
2163
|
+
glimmer package:config
|
2095
2164
|
```
|
2096
2165
|
|
2097
|
-
This will generate `config/warble.rb`, which you may configure and then run `
|
2166
|
+
This will generate `config/warble.rb`, which you may configure and then run `glimmer package` afterwards.
|
2167
|
+
|
2168
|
+
### Packaging Configuration
|
2169
|
+
|
2170
|
+
- Ensure you have a Ruby script under `bin` directory that launches the application, preferably matching your project directory name (e.g. `bin/math_bowling`) :
|
2171
|
+
```ruby
|
2172
|
+
require_relative '../app/my_application.rb'
|
2173
|
+
```
|
2174
|
+
- 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/)
|
2175
|
+
- Include Version (Optional): Create a `VERSION` file in your application and fill it your app version on one line (e.g. `1.1.0`)
|
2176
|
+
- 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).
|
2177
|
+
- 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).
|
2098
2178
|
|
2099
2179
|
### javapackager Extra Arguments
|
2100
2180
|
|
@@ -2122,7 +2202,7 @@ https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMac
|
|
2122
2202
|
Example (env var):
|
2123
2203
|
|
2124
2204
|
```
|
2125
|
-
JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"'
|
2205
|
+
JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"' glimmer package
|
2126
2206
|
```
|
2127
2207
|
|
2128
2208
|
That overrides the default application display name.
|
@@ -2167,7 +2247,7 @@ Example:
|
|
2167
2247
|
Glimmer::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
|
2168
2248
|
```
|
2169
2249
|
|
2170
|
-
Now, when you run `
|
2250
|
+
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.
|
2171
2251
|
|
2172
2252
|
### Gotchas
|
2173
2253
|
|
@@ -2184,7 +2264,7 @@ Glimmer::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="
|
|
2184
2264
|
|
2185
2265
|
2. Mounted DMG Residue
|
2186
2266
|
|
2187
|
-
If you run `
|
2267
|
+
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."
|
2188
2268
|
|
2189
2269
|
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):
|
2190
2270
|
|
@@ -2194,10 +2274,25 @@ Exec failed with code 2 command [[/usr/bin/SetFile, -c, icnC, /var/folders/4_/g1
|
|
2194
2274
|
|
2195
2275
|
## Resources
|
2196
2276
|
|
2277
|
+
* [Code Master Blog](http://andymaleh.blogspot.com/search/label/Glimmer)
|
2197
2278
|
* [Eclipse Zone Tutorial](http://eclipse.dzone.com/articles/an-introduction-glimmer)
|
2198
2279
|
* [InfoQ Article](http://www.infoq.com/news/2008/02/glimmer-jruby-swt)
|
2199
2280
|
* [RubyConf 2008 Video](https://confreaks.tv/videos/rubyconf2008-desktop-development-with-glimmer)
|
2200
|
-
* [
|
2281
|
+
* [JRuby Cookbook by Justin Edelson & Henry Liu](http://shop.oreilly.com/product/9780596519650.do)
|
2282
|
+
|
2283
|
+
## Help
|
2284
|
+
|
2285
|
+
### Issues
|
2286
|
+
|
2287
|
+
You may submit [issues](https://github.com/AndyObtiva/glimmer/issues) on [GitHub](https://github.com/AndyObtiva/glimmer/issues).
|
2288
|
+
|
2289
|
+
[Click here to submit an issue.](https://github.com/AndyObtiva/glimmer/issues)
|
2290
|
+
|
2291
|
+
### IRC Channel
|
2292
|
+
|
2293
|
+
If you need live help, try the [#glimmer](http://widget.mibbit.com/?settings=7514b8a196f8f1de939a351245db7aa8&server=irc.mibbit.net&channel=%23glimmer) IRC channel on [irc.mibbit.net](http://widget.mibbit.com/?settings=7514b8a196f8f1de939a351245db7aa8&server=irc.mibbit.net&channel=%23glimmer). If no one was available, you may [leave a GitHub issue](https://github.com/AndyObtiva/glimmer/issues) to schedule a meetup on IRC.
|
2294
|
+
|
2295
|
+
[Click here to connect to #glimmer IRC channel immediately via a web interface.](http://widget.mibbit.com/?settings=7514b8a196f8f1de939a351245db7aa8&server=irc.mibbit.net&channel=%23glimmer)
|
2201
2296
|
|
2202
2297
|
## Feature Suggestions
|
2203
2298
|
|
@@ -2215,8 +2310,10 @@ These features have been suggested. You might see them in a future version of Gl
|
|
2215
2310
|
|
2216
2311
|
## Contributors
|
2217
2312
|
|
2218
|
-
* Andy Maleh (Founder)
|
2219
|
-
* Dennis Theisen
|
2313
|
+
* [Andy Maleh](https://github.com/AndyObtiva) (Founder)
|
2314
|
+
* [Dennis Theisen](https://github.com/Soleone) (Contributor)
|
2315
|
+
|
2316
|
+
[Click here to view contributor commits.](https://github.com/AndyObtiva/glimmer/graphs/contributors)
|
2220
2317
|
|
2221
2318
|
## License
|
2222
2319
|
|