glimmer 0.7.5 → 0.8.1
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} +157 -105
- data/VERSION +1 -1
- data/lib/glimmer/data_binding/tree_items_binding.rb +6 -3
- data/lib/glimmer/dsl/swt/dialog_expression.rb +26 -0
- data/lib/glimmer/launcher.rb +13 -10
- data/lib/glimmer/rake_task.rb +3 -3
- data/lib/glimmer/scaffold.rb +208 -68
- data/lib/glimmer/swt/display_proxy.rb +14 -0
- data/lib/glimmer/swt/menu_proxy.rb +17 -0
- data/lib/glimmer/swt/shell_proxy.rb +16 -29
- data/lib/glimmer/swt/widget_proxy.rb +14 -0
- data/lib/glimmer/ui/custom_widget.rb +9 -6
- metadata +7 -36
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 0c6aff23e9890326138ca130e2e7bb80d2ff62d9586d3ff9e62cfcb97dab0c18
|
4
|
+
data.tar.gz: '038211b85b37a102b05006b5961ec60ad20c62eca31bd15f833065170d9b6b20'
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 7fea559224aa5069c03dfebdcbd4981ed7c6296d171098077164019e9c3fa8fd053fcfe0fcaf7161b03d0ad3a1dbda0af4c719629fd55a9af9868760a9b398e4
|
7
|
+
data.tar.gz: 2abec0e6d750fc5ed6417ea79c18aa102c8d2d75ee3c253a2ecec1f0e01c22793e03dc7ff25b10a99c4b81d1a907712e7f558e85158ffa675bcfe24928ec7ff7
|
@@ -1,8 +1,10 @@
|
|
1
|
-
# Glimmer 0.
|
1
|
+
# Glimmer 0.8.1 Beta (Ruby Desktop Development GUI Library)
|
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.
|
6
8
|
|
7
9
|
[<img src="https://covers.oreillystatic.com/images/9780596519650/lrg.jpg" width=105 /><br />
|
8
10
|
Featured in<br />JRuby Cookbook](http://shop.oreilly.com/product/9780596519650.do)
|
@@ -71,14 +73,12 @@ Glimmer app:
|
|
71
73
|
|
72
74
|
NOTE: Glimmer is in beta mode. Please help make better by adopting for small or low risk projects and providing feedback.
|
73
75
|
|
74
|
-
## Table of
|
76
|
+
## Table of contents
|
75
77
|
|
76
|
-
|
77
|
-
- [Glimmer 0.7.5 Beta (JRuby Desktop UI DSL + Data-Binding)](#glimmer-058-beta-jruby-desktop-ui-dsl--data-binding)
|
78
|
+
- [Glimmer 0.8.1 Beta (Ruby Desktop Development GUI Library)](#glimmer-081-beta-ruby-desktop-development-gui-library)
|
78
79
|
- [Examples](#examples)
|
79
|
-
- [Hello World](#hello-world)
|
80
|
+
- [Hello, World!](#hello-world)
|
80
81
|
- [Tic Tac Toe](#tic-tac-toe)
|
81
|
-
- [Table of Contents](#table-of-contents)
|
82
82
|
- [Background](#background)
|
83
83
|
- [Platform Support](#platform-support)
|
84
84
|
- [Pre-requisites](#pre-requisites)
|
@@ -88,6 +88,7 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
|
|
88
88
|
- [Glimmer Command](#glimmer-command)
|
89
89
|
- [Basic Usage](#basic-usage)
|
90
90
|
- [Advanced Usage](#advanced-usage)
|
91
|
+
- [Scaffolding](#scaffolding)
|
91
92
|
- [Girb (Glimmer irb) Command](#girb-glimmer-irb-command)
|
92
93
|
- [Glimmer DSL Syntax](#glimmer-dsl-syntax)
|
93
94
|
- [Widgets](#widgets)
|
@@ -102,26 +103,31 @@ NOTE: Glimmer is in beta mode. Please help make better by adopting for small or
|
|
102
103
|
- [Miscellaneous](#miscellaneous)
|
103
104
|
- [Glimmer Style Guide](#glimmer-style-guide)
|
104
105
|
- [Samples](#samples)
|
106
|
+
- [Hello Samples](#hello-samples)
|
107
|
+
- [Elaborate Samples](#elaborate-samples)
|
108
|
+
- [External Samples](#external-samples)
|
109
|
+
- [In Production](#in-production)
|
105
110
|
- [SWT Reference](#swt-reference)
|
106
111
|
- [SWT Packages](#swt-packages)
|
107
112
|
- [Logging](#logging)
|
108
113
|
- [Raw JRuby Command](#raw-jruby-command)
|
109
114
|
- [Mac Support](#mac-support)
|
110
115
|
- [Packaging & Distribution](#packaging--distribution)
|
111
|
-
- [Defaults](#defaults)
|
116
|
+
- [Packaging Defaults](#packaging-defaults)
|
117
|
+
- [Packaging Configuration](#packaging-configuration)
|
112
118
|
- [javapackager Extra Arguments](#javapackager-extra-arguments)
|
113
119
|
- [Mac Application Distribution](#mac-application-distribution)
|
114
120
|
- [Self Signed Certificate](#self-signed-certificate)
|
115
121
|
- [Gotchas](#gotchas)
|
116
122
|
- [Resources](#resources)
|
123
|
+
- [Help](#help)
|
124
|
+
- [Issues](#issues)
|
125
|
+
- [IRC Channel](#irc-channel)
|
117
126
|
- [Feature Suggestions](#feature-suggestions)
|
118
127
|
- [Change Log](#change-log)
|
119
128
|
- [Contributing](#contributing)
|
120
129
|
- [Contributors](#contributors)
|
121
130
|
- [License](#license)
|
122
|
-
<!-- TOC END -->
|
123
|
-
|
124
|
-
|
125
131
|
|
126
132
|
## Background
|
127
133
|
|
@@ -134,22 +140,22 @@ Glimmer runs on the following platforms:
|
|
134
140
|
- Windows
|
135
141
|
- Linux
|
136
142
|
|
137
|
-
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:
|
138
144
|
- Win32 on Windows
|
139
145
|
- Cocoa on Mac
|
140
146
|
- GTK on Linux
|
141
147
|
|
142
|
-
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:
|
143
149
|
|
144
150
|
https://wiki.eclipse.org/SWT/Devel/Gtk/Dev_guide#Win32.2FCocoa.2FGTK
|
145
151
|
https://www.eclipse.org/swt/faq.php
|
146
152
|
|
147
|
-
|
148
153
|
## Pre-requisites
|
149
154
|
|
150
155
|
- SWT 4.15 (comes included in Glimmer gem)
|
151
|
-
- JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at https://www.jruby.org/download)
|
152
|
-
- Java SE Runtime Environment 7 or higher (find at https://www.oracle.com/java/technologies/javase-downloads.html)
|
156
|
+
- JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at [https://www.jruby.org/download](https://www.jruby.org/download))
|
157
|
+
- 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))
|
158
|
+
- (Optional) RVM is needed for [Scaffolding](#scaffolding) only (find at [https://rvm.io/](https://rvm.io/))
|
153
159
|
|
154
160
|
On **Mac** and **Linux**, an easy way to obtain JRuby is through [RVM](http://rvm.io) by running:
|
155
161
|
|
@@ -167,7 +173,7 @@ Please follow these instructions to make the `glimmer` command available on your
|
|
167
173
|
|
168
174
|
Run this command to install directly:
|
169
175
|
```
|
170
|
-
jgem install glimmer -v 0.
|
176
|
+
jgem install glimmer -v 0.8.1
|
171
177
|
```
|
172
178
|
|
173
179
|
`jgem` is JRuby's version of `gem` command.
|
@@ -178,7 +184,7 @@ Otherwise, you may also run `jruby -S gem install ...`
|
|
178
184
|
|
179
185
|
Add the following to `Gemfile`:
|
180
186
|
```
|
181
|
-
gem 'glimmer', '~> 0.
|
187
|
+
gem 'glimmer', '~> 0.8.1'
|
182
188
|
```
|
183
189
|
|
184
190
|
And, then run:
|
@@ -215,7 +221,7 @@ bin/glimmer samples/hello/hello_world.rb
|
|
215
221
|
Below are the full usage instructions that come up when running `glimmer` without args.
|
216
222
|
|
217
223
|
```
|
218
|
-
Usage: glimmer [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
|
224
|
+
Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
|
219
225
|
|
220
226
|
Runs Glimmer applications/tasks.
|
221
227
|
|
@@ -230,7 +236,7 @@ glimmer package:jar # Generate JAR
|
|
230
236
|
glimmer package:native # Generate Native files (DMG/PKG/APP on the Mac)
|
231
237
|
glimmer scaffold[app_name] # Scaffold a Glimmer application directory structure to begin building a new app
|
232
238
|
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)
|
233
|
-
glimmer scaffold:custom_shell_gem[
|
239
|
+
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)
|
234
240
|
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)
|
235
241
|
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)
|
236
242
|
|
@@ -240,8 +246,9 @@ automatically preloading the glimmer Ruby gem and SWT jar dependency.
|
|
240
246
|
Optionally, extra Glimmer options, JRuby options and environment variables may be passed in.
|
241
247
|
|
242
248
|
Glimmer options:
|
243
|
-
- "--
|
244
|
-
- "--
|
249
|
+
- "--quiet" : Does not announce file path of Glimmer application being launched
|
250
|
+
- "--debug" : Displays extra debugging information, passes "--debug" to JRuby, and enables debug logging
|
251
|
+
- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
|
245
252
|
|
246
253
|
Example: glimmer samples/hello_world.rb
|
247
254
|
|
@@ -273,7 +280,7 @@ getting you to a running and delivered state of an advanced "Hello, World!" Glim
|
|
273
280
|
This should greatly facilitate building a new Glimmer app by helping you be productive and focus on app details while
|
274
281
|
letting Glimmer scaffolding take care of initial app file structure concerns, such as adding:
|
275
282
|
- Main application class that includes Glimmer
|
276
|
-
- Main application view that houses main window content
|
283
|
+
- Main application view that houses main window content, about dialog, and preferences dialog
|
277
284
|
- View and Model directories
|
278
285
|
- Rakefile including Glimmer tasks
|
279
286
|
- Version
|
@@ -281,7 +288,7 @@ letting Glimmer scaffolding take care of initial app file structure concerns, su
|
|
281
288
|
- Icon
|
282
289
|
- Bin file for starting application
|
283
290
|
|
284
|
-
NOTE: Scaffolding currently supports Mac packaging only at the moment.
|
291
|
+
NOTE: Scaffolding requires RVM and currently supports Mac packaging only at the moment.
|
285
292
|
|
286
293
|
#### App
|
287
294
|
|
@@ -339,9 +346,13 @@ glimmer scaffold:custom_widget[custom_widget_name]
|
|
339
346
|
|
340
347
|
#### Custom Shell Gem
|
341
348
|
|
342
|
-
Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
|
349
|
+
Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
|
350
|
+
They have everything scaffolded Glimmer apps come with in addition to gem content like a Jeweler Rakefile that can build gemspec and release gems.
|
351
|
+
Unlike scaffolded Glimmer apps, custom shell gem content lives under the `lib` directory (not `app`).
|
352
|
+
They can be packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem.
|
353
|
+
Of course, you can just build a Ruby gem and disregard native executable packaging if you do not need it.
|
343
354
|
|
344
|
-
To scaffold a Glimmer custom shell gem (full window view
|
355
|
+
To scaffold a Glimmer custom shell gem (full window view distributed as a Ruby gem), run the following command:
|
345
356
|
|
346
357
|
```
|
347
358
|
glimmer scaffold:custom_shell_gem[custom_shell_name, namespace]
|
@@ -349,15 +360,18 @@ glimmer scaffold:custom_shell_gem[custom_shell_name, namespace]
|
|
349
360
|
|
350
361
|
It is important to specify a namespace to avoid having your gem clash with existing gems.
|
351
362
|
|
352
|
-
The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell)
|
363
|
+
The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell).
|
353
364
|
|
354
365
|
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)
|
355
366
|
|
356
|
-
|
367
|
+
Examples:
|
368
|
+
|
369
|
+
- [glimmer-cs-gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator): Gladiator (Glimmer Editor)
|
370
|
+
- [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator): Glimmer Calculator
|
357
371
|
|
358
372
|
#### Custom Widget Gem
|
359
373
|
|
360
|
-
To scaffold a Glimmer custom widget gem (part of a view
|
374
|
+
To scaffold a Glimmer custom widget gem (part of a view distributed as a Ruby gem), run the following command:
|
361
375
|
|
362
376
|
```
|
363
377
|
glimmer scaffold:custom_widget_gem[custom_widget_name, namespace]
|
@@ -407,7 +421,7 @@ You will learn more about widgets next.
|
|
407
421
|
|
408
422
|
### Widgets
|
409
423
|
|
410
|
-
Glimmer
|
424
|
+
Glimmer GUIs (user interfaces) are modeled with widgets, which are wrappers around the SWT library widgets found here:
|
411
425
|
|
412
426
|
https://www.eclipse.org/swt/widgets/
|
413
427
|
|
@@ -516,7 +530,7 @@ shell {
|
|
516
530
|
|
517
531
|
#### Display
|
518
532
|
|
519
|
-
SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage
|
533
|
+
SWT Display is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage GUI globally
|
520
534
|
and access available monitors.
|
521
535
|
It is automatically instantiated upon first instantiation of a `shell` widget.
|
522
536
|
Alternatively, for advanced use cases, it can be created explicitly with Glimmer `display` keyword. When a `shell` is later declared, it
|
@@ -544,7 +558,7 @@ Glimmer follows Proxy Design Pattern by having Ruby proxy wrappers for all SWT o
|
|
544
558
|
- `Glimmer::SWT:TabItemProxy` wraps `org.eclipse.swt.widget.TabItem` (also adds a composite to enable adding content under tab items directly in Glimmer)
|
545
559
|
- `Glimmer::SWT:LayoutProxy` wraps all descendants of `org.eclipse.swt.widget.Layout`
|
546
560
|
- `Glimmer::SWT:LayoutDataProxy` wraps all layout data objects
|
547
|
-
- `Glimmer::SWT:DisplayProxy` wraps `org.eclipse.swt.widget.Display` (manages displaying
|
561
|
+
- `Glimmer::SWT:DisplayProxy` wraps `org.eclipse.swt.widget.Display` (manages displaying GUI)
|
548
562
|
- `Glimmer::SWT:ColorProxy` wraps `org.eclipse.swt.graphics.Color`
|
549
563
|
- `Glimmer::SWT:FontProxy` wraps `org.eclipse.swt.graphics.Font`
|
550
564
|
- `Glimmer::SWT::WidgetListenerProxy` wraps all widget listeners
|
@@ -613,6 +627,12 @@ Shell widget proxy has extra methods specific to SWT Shell:
|
|
613
627
|
- `#pack`: Packs contained widgets using SWT's `Shell#pack` method
|
614
628
|
- `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
|
615
629
|
|
630
|
+
#### Dialog
|
631
|
+
|
632
|
+
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.
|
633
|
+
|
634
|
+
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.
|
635
|
+
|
616
636
|
#### Menus
|
617
637
|
|
618
638
|
Glimmer DSL provides support for SWT Menu and MenuItem widgets.
|
@@ -1303,7 +1323,7 @@ Glimmer supports observing widgets with two main types of events:
|
|
1303
1323
|
|
1304
1324
|
Additionally, there are two more types of events:
|
1305
1325
|
- SWT `display` supports global listeners called filters that run on any widget. They are hooked via `on_event_{swt-event-constant}`
|
1306
|
-
-
|
1326
|
+
- SWT `display` supports Mac application menu item observers (`on_about` and `on_preferences`), which you can read about under [Miscellaneous](#miscellaneous).
|
1307
1327
|
|
1308
1328
|
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.
|
1309
1329
|
|
@@ -1403,7 +1423,7 @@ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
|
1403
1423
|
|
1404
1424
|
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.
|
1405
1425
|
|
1406
|
-
The alternative syntax can be helpful if you prefer to separate Glimmer observer declarations from Glimmer
|
1426
|
+
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.
|
1407
1427
|
|
1408
1428
|
#### Observing Models
|
1409
1429
|
|
@@ -1529,17 +1549,17 @@ Notice how `Red::Composite` became `red__composite` with double-underscore, whic
|
|
1529
1549
|
|
1530
1550
|
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.
|
1531
1551
|
|
1532
|
-
Custom Widgets have the following attributes
|
1552
|
+
Custom Widgets have the following attributes available to call from inside the `#body` method:
|
1533
1553
|
- `#parent`: Glimmer object parenting custom widget
|
1534
1554
|
- `#swt_style`: SWT style integer. Can be useful if you want to allow consumers to customize a widget inside the custom widget body
|
1535
|
-
- `#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
|
1555
|
+
- `#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)
|
1536
1556
|
- `#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.
|
1537
1557
|
- `#body_root`: top-most (root) widget returned from `#body` method.
|
1538
1558
|
- `#swt_widget`: actual SWT widget for `body_root`
|
1539
1559
|
|
1540
1560
|
Additionally, custom widgets can call the following class methods:
|
1541
|
-
-
|
1542
|
-
-
|
1561
|
+
- `::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)
|
1562
|
+
- `::option(option_name, default: nil)`: declares a single option taking option name and default value as arguments (also generates attribute accessors just like `::options`)
|
1543
1563
|
|
1544
1564
|
#### Content/Options Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
1545
1565
|
|
@@ -1549,7 +1569,7 @@ class Sandwich
|
|
1549
1569
|
include Glimmer::UI::CustomWidget
|
1550
1570
|
|
1551
1571
|
options :orientation, :bg_color
|
1552
|
-
option :fg_color, :black
|
1572
|
+
option :fg_color, default: :black
|
1553
1573
|
|
1554
1574
|
body {
|
1555
1575
|
composite(swt_style) { # gets custom widget style
|
@@ -1684,52 +1704,61 @@ shell { |app_shell|
|
|
1684
1704
|
|
1685
1705
|
#### Application Menu Items (About/Preferences)
|
1686
1706
|
|
1687
|
-
Mac applications always have About and Preferences menu items. Glimmer provides widget observer hooks for them on the `
|
1707
|
+
Mac applications always have About and Preferences menu items. Glimmer provides widget observer hooks for them on the `display`:
|
1688
1708
|
- `on_about`: executes code when user selects App Name -> About
|
1689
1709
|
- `on_preferences`: executes code when user selects App Name -> Preferences or hits 'CMD+,' on the Mac
|
1690
1710
|
|
1691
1711
|
Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
1692
1712
|
|
1693
1713
|
```ruby
|
1694
|
-
|
1695
|
-
|
1696
|
-
|
1697
|
-
|
1698
|
-
|
1699
|
-
|
1700
|
-
|
1701
|
-
|
1702
|
-
font height: 30
|
1703
|
-
}
|
1704
|
-
on_about {
|
1705
|
-
message_box = MessageBox.new(shell_proxy.swt_widget)
|
1706
|
-
message_box.setText("About")
|
1707
|
-
message_box.setMessage("About Application")
|
1708
|
-
message_box.open
|
1709
|
-
}
|
1710
|
-
on_preferences {
|
1711
|
-
preferences_dialog = shell(:dialog_trim, :application_modal) {
|
1712
|
-
text 'Preferences'
|
1713
|
-
row_layout {
|
1714
|
-
type :vertical
|
1715
|
-
margin_left 15
|
1716
|
-
margin_top 15
|
1717
|
-
margin_right 15
|
1718
|
-
margin_bottom 15
|
1714
|
+
class Example
|
1715
|
+
def initialize
|
1716
|
+
display {
|
1717
|
+
on_about {
|
1718
|
+
message_box = MessageBox.new(@shell_proxy.swt_widget)
|
1719
|
+
message_box.setText("About")
|
1720
|
+
message_box.setMessage("About Application")
|
1721
|
+
message_box.open
|
1719
1722
|
}
|
1720
|
-
|
1721
|
-
|
1723
|
+
on_preferences {
|
1724
|
+
preferences_dialog = dialog {
|
1725
|
+
text 'Preferences'
|
1726
|
+
row_layout {
|
1727
|
+
type :vertical
|
1728
|
+
margin_left 15
|
1729
|
+
margin_top 15
|
1730
|
+
margin_right 15
|
1731
|
+
margin_bottom 15
|
1732
|
+
}
|
1733
|
+
label {
|
1734
|
+
text 'Check one of these options:'
|
1735
|
+
}
|
1736
|
+
button(:radio) {
|
1737
|
+
text 'Option 1'
|
1738
|
+
}
|
1739
|
+
button(:radio) {
|
1740
|
+
text 'Option 2'
|
1741
|
+
}
|
1742
|
+
}
|
1743
|
+
preferences_dialog.open
|
1722
1744
|
}
|
1723
|
-
|
1724
|
-
|
1745
|
+
}
|
1746
|
+
@shell_proxy = shell {
|
1747
|
+
text 'Application Menu Items'
|
1748
|
+
fill_layout {
|
1749
|
+
margin_width 15
|
1750
|
+
margin_height 15
|
1725
1751
|
}
|
1726
|
-
|
1727
|
-
text '
|
1752
|
+
label {
|
1753
|
+
text 'Application Menu Items'
|
1754
|
+
font height: 30
|
1728
1755
|
}
|
1729
1756
|
}
|
1730
|
-
|
1731
|
-
|
1732
|
-
|
1757
|
+
@shell_proxy.open
|
1758
|
+
end
|
1759
|
+
end
|
1760
|
+
|
1761
|
+
Example.new
|
1733
1762
|
```
|
1734
1763
|
|
1735
1764
|
#### App Name and Version
|
@@ -1937,7 +1966,7 @@ This relies on Glimmer's [Multi-DSL Support](https://github.com/AndyObtiva/glimm
|
|
1937
1966
|
- Widget property declarations always have arguments and never take a block
|
1938
1967
|
- Widget property arguments are never wrapped inside parentheses
|
1939
1968
|
- Widget listeners are always declared starting with `on_` prefix and affixing listener event method name afterwards in underscored lowercase form
|
1940
|
-
- Widget listeners are always followed by a block using curly braces (Only when declared in DSL. When invoked on widget object directly outside of
|
1969
|
+
- 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)
|
1941
1970
|
- Data-binding is done via `bind` keyword, which always takes arguments wrapped in parentheses
|
1942
1971
|
- Custom widget body, before_body, and after_body blocks open their blocks and close them with curly braces.
|
1943
1972
|
- 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.
|
@@ -1971,12 +2000,22 @@ glimmer samples/hello/hello_computed.rb # demonstrates computed data-binding
|
|
1971
2000
|
For more elaborate samples, check the following:
|
1972
2001
|
|
1973
2002
|
```
|
1974
|
-
glimmer samples/elaborate/login.rb # demonstrates
|
2003
|
+
glimmer samples/elaborate/login.rb # demonstrates basic data-binding
|
1975
2004
|
glimmer samples/elaborate/contact_manager.rb # demonstrates table data-binding
|
1976
2005
|
glimmer samples/elaborate/tic_tac_toe.rb # demonstrates a full MVC application
|
1977
2006
|
```
|
1978
2007
|
|
1979
|
-
|
2008
|
+
### External Samples
|
2009
|
+
|
2010
|
+
#### [Glimmer Calculator](https://github.com/AndyObtiva/glimmer-cs-calculator)
|
2011
|
+
|
2012
|
+
![Glimmer Calculator](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/v1.0.0/glimmer-cs-calculator-screenshot.png)
|
2013
|
+
|
2014
|
+
[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).
|
2015
|
+
|
2016
|
+
#### [Gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator)
|
2017
|
+
|
2018
|
+
![Gladiator](https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/v0.1.5/images/glimmer-gladiator.png)
|
1980
2019
|
|
1981
2020
|
[Gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator) (short for Glimmer Editor) is a Glimmer sample project under on-going development.
|
1982
2021
|
You may check it out to learn how to build a Glimmer Custom Shell gem.
|
@@ -2105,33 +2144,20 @@ Glimmer apps may be packaged and distributed on the Mac, Windows, and Linux via
|
|
2105
2144
|
- Warbler (https://github.com/jruby/warbler): Enables bundling a Glimmer app into a JAR file
|
2106
2145
|
- 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.
|
2107
2146
|
|
2108
|
-
Glimmer simplifies the process
|
2109
|
-
|
2110
|
-
To use:
|
2111
|
-
- Create `Rakefile` in your app root directory
|
2112
|
-
- Add the following line to it: `require 'glimmer/rake_task'`
|
2113
|
-
- 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'`):
|
2114
|
-
```ruby
|
2115
|
-
require_relative '../app/my_application.rb'
|
2116
|
-
```
|
2117
|
-
- 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/)
|
2118
|
-
- Include Version (Optional): Create a `VERSION` file in your application and fill it your app version on one line (e.g. `1.1.0`)
|
2119
|
-
- 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).
|
2120
|
-
- 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).
|
2147
|
+
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):
|
2121
2148
|
|
2122
|
-
Now, you can run the following rake command to package your app into a Mac DMG file (using both Warbler and javapackager):
|
2123
2149
|
```
|
2124
|
-
|
2150
|
+
glimmer package
|
2125
2151
|
```
|
2126
2152
|
|
2127
|
-
This will generate a JAR file under `./dist` directory, which is then used to generate a DMG file (and pkg/app) under `./packages/bundles`.
|
2153
|
+
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`.
|
2128
2154
|
JAR file name will match your application local directory name (e.g. `MathBowling.jar` for `~/code/MathBowling`)
|
2129
2155
|
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)
|
2130
2156
|
|
2131
|
-
|
2157
|
+
The `glimmer package` command will automatically set "mac.CFBundleIdentifier" to ="org.#{project_name}.application.#{project_name}".
|
2132
2158
|
You may override by configuring as an extra argument for javapackger (e.g. Glimmer::Package.javapackager_extra_args = " -Bmac.CFBundleIdentifier=org.andymaleh.application.MathBowling")
|
2133
2159
|
|
2134
|
-
### Defaults
|
2160
|
+
### Packaging Defaults
|
2135
2161
|
|
2136
2162
|
Glimmer employs smart defaults in packaging.
|
2137
2163
|
|
@@ -2139,13 +2165,24 @@ The package application name (shows up in top menu bar on the Mac) will be a hum
|
|
2139
2165
|
|
2140
2166
|
Also, the package will only include these directories: app, config, db, lib, script, bin, docs, fonts, images, sounds, videos
|
2141
2167
|
|
2142
|
-
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 `
|
2168
|
+
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:
|
2143
2169
|
|
2144
2170
|
```
|
2145
|
-
|
2171
|
+
glimmer package:config
|
2146
2172
|
```
|
2147
2173
|
|
2148
|
-
This will generate `config/warble.rb`, which you may configure and then run `
|
2174
|
+
This will generate `config/warble.rb`, which you may configure and then run `glimmer package` afterwards.
|
2175
|
+
|
2176
|
+
### Packaging Configuration
|
2177
|
+
|
2178
|
+
- Ensure you have a Ruby script under `bin` directory that launches the application, preferably matching your project directory name (e.g. `bin/math_bowling`) :
|
2179
|
+
```ruby
|
2180
|
+
require_relative '../app/my_application.rb'
|
2181
|
+
```
|
2182
|
+
- 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/)
|
2183
|
+
- Include Version (Optional): Create a `VERSION` file in your application and fill it your app version on one line (e.g. `1.1.0`)
|
2184
|
+
- 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).
|
2185
|
+
- 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).
|
2149
2186
|
|
2150
2187
|
### javapackager Extra Arguments
|
2151
2188
|
|
@@ -2173,7 +2210,7 @@ https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMac
|
|
2173
2210
|
Example (env var):
|
2174
2211
|
|
2175
2212
|
```
|
2176
|
-
JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"'
|
2213
|
+
JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"' glimmer package
|
2177
2214
|
```
|
2178
2215
|
|
2179
2216
|
That overrides the default application display name.
|
@@ -2218,7 +2255,7 @@ Example:
|
|
2218
2255
|
Glimmer::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
|
2219
2256
|
```
|
2220
2257
|
|
2221
|
-
Now, when you run `
|
2258
|
+
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.
|
2222
2259
|
|
2223
2260
|
### Gotchas
|
2224
2261
|
|
@@ -2235,7 +2272,7 @@ Glimmer::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="
|
|
2235
2272
|
|
2236
2273
|
2. Mounted DMG Residue
|
2237
2274
|
|
2238
|
-
If you run `
|
2275
|
+
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."
|
2239
2276
|
|
2240
2277
|
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):
|
2241
2278
|
|
@@ -2245,12 +2282,25 @@ Exec failed with code 2 command [[/usr/bin/SetFile, -c, icnC, /var/folders/4_/g1
|
|
2245
2282
|
|
2246
2283
|
## Resources
|
2247
2284
|
|
2285
|
+
* [Code Master Blog](http://andymaleh.blogspot.com/search/label/Glimmer)
|
2248
2286
|
* [Eclipse Zone Tutorial](http://eclipse.dzone.com/articles/an-introduction-glimmer)
|
2249
2287
|
* [InfoQ Article](http://www.infoq.com/news/2008/02/glimmer-jruby-swt)
|
2250
2288
|
* [RubyConf 2008 Video](https://confreaks.tv/videos/rubyconf2008-desktop-development-with-glimmer)
|
2251
|
-
* [Code Blog](http://andymaleh.blogspot.com/search/label/Glimmer)
|
2252
2289
|
* [JRuby Cookbook by Justin Edelson & Henry Liu](http://shop.oreilly.com/product/9780596519650.do)
|
2253
2290
|
|
2291
|
+
## Help
|
2292
|
+
|
2293
|
+
### Issues
|
2294
|
+
|
2295
|
+
You may submit [issues](https://github.com/AndyObtiva/glimmer/issues) on [GitHub](https://github.com/AndyObtiva/glimmer/issues).
|
2296
|
+
|
2297
|
+
[Click here to submit an issue.](https://github.com/AndyObtiva/glimmer/issues)
|
2298
|
+
|
2299
|
+
### IRC Channel
|
2300
|
+
|
2301
|
+
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.
|
2302
|
+
|
2303
|
+
[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)
|
2254
2304
|
|
2255
2305
|
## Feature Suggestions
|
2256
2306
|
|
@@ -2268,8 +2318,10 @@ These features have been suggested. You might see them in a future version of Gl
|
|
2268
2318
|
|
2269
2319
|
## Contributors
|
2270
2320
|
|
2271
|
-
* Andy Maleh (Founder)
|
2272
|
-
* Dennis Theisen
|
2321
|
+
* [Andy Maleh](https://github.com/AndyObtiva) (Founder)
|
2322
|
+
* [Dennis Theisen](https://github.com/Soleone) (Contributor)
|
2323
|
+
|
2324
|
+
[Click here to view contributor commits.](https://github.com/AndyObtiva/glimmer/graphs/contributors)
|
2273
2325
|
|
2274
2326
|
## License
|
2275
2327
|
|