glimmer-dsl-swt 4.17.2.0 → 4.17.3.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +45 -0
- data/README.md +387 -108
- data/VERSION +1 -1
- data/glimmer-dsl-swt.gemspec +9 -7
- data/lib/ext/glimmer/config.rb +1 -0
- data/lib/glimmer-dsl-swt.rb +6 -0
- data/lib/glimmer/data_binding/table_items_binding.rb +1 -0
- data/lib/glimmer/launcher.rb +16 -10
- data/lib/glimmer/rake_task.rb +36 -2
- data/lib/glimmer/rake_task/package.rb +21 -10
- data/lib/glimmer/rake_task/scaffold.rb +146 -42
- data/lib/glimmer/swt/image_proxy.rb +34 -11
- data/lib/glimmer/swt/style_constantizable.rb +2 -1
- data/lib/glimmer/swt/widget_proxy.rb +45 -33
- data/lib/glimmer/ui/custom_widget.rb +7 -4
- data/samples/elaborate/contact_manager/contact_repository.rb +3 -99
- data/samples/hello/hello_combo.rb +10 -6
- data/samples/hello/hello_custom_shell.rb +155 -0
- data/samples/hello/hello_custom_widget.rb +86 -0
- data/samples/hello/hello_tab.rb +10 -5
- data/samples/hello/hello_world.rb +2 -2
- metadata +8 -6
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 6a29cc3fc40ad3ed6f5aff4fc924a1e5d29dfc505df8f66857e669f687c177be
|
|
4
|
+
data.tar.gz: 6e93601aedd65dbce5379f0629f4e42f60a5211829e2c7ffb3e203fb5ae39551
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: d13f68897613eb659020350fd9ca3877de30f2033e4615c8b07e9ff0539646b9730e7d8b51dfd0f7b49f8d83c30cc22c9bceaca26fa3e7aabbe7a0178bb6b6e0
|
|
7
|
+
data.tar.gz: f175a664d832335006ae3a3d7bfc3ba8aabd8f8684247d735eb37e683b8e2ccf77ac37221c611e73a690f5df9e4f5e4378425e97b347fd2c03b1f8b95afcaa80
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,50 @@
|
|
|
1
1
|
# Change Log
|
|
2
2
|
|
|
3
|
+
### 4.17.3.0
|
|
4
|
+
|
|
5
|
+
- `glimmer scaffold:desktopify[appname,website]` Mac
|
|
6
|
+
- `glimmer scaffold:desktopify[appname,website]` Windows
|
|
7
|
+
- `glimmer scaffold:desktopify[appname,website]` Linux (have scaffolding include the glimmer-cw-browser-chromium gem in scaffolded app on Linux)
|
|
8
|
+
- Remove the native packaging from Linux scaffolding since it is not officially supported
|
|
9
|
+
- Add gem packaging as part of scaffolding on Linux
|
|
10
|
+
- Launch the app at the end of scaffolding in Linux
|
|
11
|
+
- Provide a `glimmer package:gem` task
|
|
12
|
+
- Add support for scaffolding "app/scaffolded_app/launch" and "lib/namespace/custom_shell/launch" to enable launching SWT apps in Glimmer DSL for Opal without changing a line of code
|
|
13
|
+
- Add a binary executable shell in "app" mode (just like "custom shell gem" mode)
|
|
14
|
+
- Have glimmer packaging check the Java version and give a warning if an unsupported version is used.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### 4.17.2.4
|
|
18
|
+
|
|
19
|
+
- New `glimmer run` glimmer command task.
|
|
20
|
+
- Add built in support for handling jar file paths like that in ImageProxy code processing "uri:classloader" path
|
|
21
|
+
- Give a good error message when Git is not properly setup for Glimmer Scaffolding
|
|
22
|
+
- Give an error message when attempting to scaffold over an already scaffolded directory
|
|
23
|
+
- Fix issue on Windows regarding use of the new EXPERIMENTAL Animated gif support in the `composite#background_image` property
|
|
24
|
+
- Fix SWTProxy.deconstruct method
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
### 4.17.2.3
|
|
28
|
+
|
|
29
|
+
- Maintain image file path upon scaling an ImageProxy
|
|
30
|
+
- Add a glimmer rake task that wraps the juwelier rake gemspec:generate task
|
|
31
|
+
- Accept `ImageProxy` as arg for `image` and `background_image` property methods
|
|
32
|
+
- (EXPERIMENTAL) Animate gif images when set as a `background_image` on a `composite`
|
|
33
|
+
- Fix issue with table redraw after data-binding changes leaving old removed table items visible (even if user cannot interact with anymore)
|
|
34
|
+
- Fix issue with running package rake task from `glimmer` command TUI
|
|
35
|
+
|
|
36
|
+
### 4.17.2.2
|
|
37
|
+
|
|
38
|
+
- Small updates/refactorings in samples
|
|
39
|
+
- Fix issue with displaying `glimmer` command tasks on Windows
|
|
40
|
+
|
|
41
|
+
### 4.17.2.1
|
|
42
|
+
|
|
43
|
+
- Add `--bundler=group` option to `glimmer` command
|
|
44
|
+
- Add `--pd` option to `glimmer` command
|
|
45
|
+
- Hello, Custom Widget! sample
|
|
46
|
+
- Hello, Custom Shell! sample
|
|
47
|
+
|
|
3
48
|
### 4.17.2.0
|
|
4
49
|
|
|
5
50
|
- `glimmer` command --bundler option to run with bundler/setup (instead of picking gems directly)
|
data/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for SWT 4.17.
|
|
1
|
+
# [<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer/master/images/glimmer-logo-hi-res.png" height=85 />](https://github.com/AndyObtiva/glimmer) Glimmer DSL for SWT 4.17.3.0
|
|
2
2
|
## JRuby Desktop Development GUI Library
|
|
3
3
|
[](http://badge.fury.io/rb/glimmer-dsl-swt)
|
|
4
4
|
[](https://travis-ci.com/github/AndyObtiva/glimmer-dsl-swt)
|
|
@@ -10,11 +10,9 @@
|
|
|
10
10
|
|
|
11
11
|
(The Original Glimmer Library Since 2007. Beware of Imitators!)
|
|
12
12
|
|
|
13
|
-
[**Glimmer**](https://rubygems.org/gems/glimmer) is a native-GUI cross-platform desktop development library written in [JRuby](https://www.jruby.org/), an OS-threaded faster version of [Ruby](https://www.ruby-lang.org/en/). [Glimmer](https://rubygems.org/gems/glimmer)'s main innovation is a declarative [Ruby DSL](#glimmer-dsl-syntax) that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust [Eclipse SWT library](https://www.eclipse.org/swt/). [Glimmer](https://rubygems.org/gems/glimmer) additionally innovates by having built-in [data-binding](#data-binding) support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns. To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](#scaffolding) options for [Apps](#in-production), [Gems](#custom-shell-gem), and [Custom Widgets](#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](#packaging--distribution) support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in [Ruby](https://www.ruby-lang.org/en/) as truly native DMG/PKG/APP files on the [Mac](https://www.apple.com/ca/macos) + [App Store](https://developer.apple.com/macos/distribution/)
|
|
13
|
+
[**Glimmer**](https://rubygems.org/gems/glimmer) is a native-GUI cross-platform desktop development library written in [JRuby](https://www.jruby.org/), an OS-threaded faster version of [Ruby](https://www.ruby-lang.org/en/). [Glimmer](https://rubygems.org/gems/glimmer)'s main innovation is a declarative [Ruby DSL](#glimmer-dsl-syntax) that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust [Eclipse SWT library](https://www.eclipse.org/swt/). [Glimmer](https://rubygems.org/gems/glimmer) additionally innovates by having built-in [data-binding](#data-binding) support, which greatly facilitates synchronizing the GUI with domain models, thus achieving true decoupling of object oriented components and enabling developers to solve business problems (test-first) without worrying about GUI concerns. To get started quickly, [Glimmer](https://rubygems.org/gems/glimmer) offers [scaffolding](#scaffolding) options for [Apps](#in-production), [Gems](#custom-shell-gem), and [Custom Widgets](#custom-widgets). [Glimmer](https://rubygems.org/gems/glimmer) also includes native-executable [packaging](#packaging--distribution) support, sorely lacking in other libraries, thus enabling the delivery of desktop apps written in [Ruby](https://www.ruby-lang.org/en/) as truly native DMG/PKG/APP files on the [Mac](https://www.apple.com/ca/macos) + [App Store](https://developer.apple.com/macos/distribution/), MSI/EXE files on [Windows](https://www.microsoft.com/en-ca/windows), and [Gem Packaged Shell Scripts](#custom-shell-gem) on [Linux](https://www.linux.org/).
|
|
14
14
|
|
|
15
|
-
[Glimmer receives two updates per month](https://rubygems.org/gems/glimmer-dsl-swt/versions). You can trust [Glimmer](https://rubygems.org/gems/glimmer) with your Ruby desktop GUI development needs.
|
|
16
|
-
|
|
17
|
-
NOTE: Glimmer is in beta mode. Please make better by providing feedback and [contributing](#contributing) when possible. The more feedback and issues you report the better.
|
|
15
|
+
[Glimmer receives two updates per month](https://rubygems.org/gems/glimmer-dsl-swt/versions). You can trust [Glimmer](https://rubygems.org/gems/glimmer) with your Ruby desktop GUI development needs. Please make [Glimmer](https://rubygems.org/gems/glimmer) even better by providing feedback and [contributing](#contributing) when possible.
|
|
18
16
|
|
|
19
17
|
[<img src="https://covers.oreillystatic.com/images/9780596519650/lrg.jpg" width=105 /><br />
|
|
20
18
|
Featured in<br />JRuby Cookbook](http://shop.oreilly.com/product/9780596519650.do)
|
|
@@ -239,6 +237,7 @@ Glimmer App:
|
|
|
239
237
|
- [Hello, World!](#hello-world)
|
|
240
238
|
- [Tic Tac Toe](#tic-tac-toe)
|
|
241
239
|
- [Contact Manager](#contact-manager)
|
|
240
|
+
- [Desktop Apps Built with Glimmer DSL for SWT](#desktop-apps-built-with-glimmer-dsl-for-swt)
|
|
242
241
|
- [Table of contents](#table-of-contents)
|
|
243
242
|
- [Background](#background)
|
|
244
243
|
- [Platform Support](#platform-support)
|
|
@@ -270,9 +269,10 @@ Glimmer App:
|
|
|
270
269
|
- [Glimmer GUI DSL Syntax](#glimmer-gui-dsl-syntax)
|
|
271
270
|
- [DSL Auto-Expansion](#dsl-auto-expansion)
|
|
272
271
|
- [Widgets](#widgets)
|
|
273
|
-
- [Display](#display)
|
|
274
272
|
- [SWT Proxies](#swt-proxies)
|
|
275
273
|
- [Dialog](#dialog)
|
|
274
|
+
- [Display](#display)
|
|
275
|
+
- [Multi-Threading](#multi-threading)
|
|
276
276
|
- [Menus](#menus)
|
|
277
277
|
- [ScrolledComposite](#scrolledcomposite)
|
|
278
278
|
- [Widget Styles](#widget-styles)
|
|
@@ -282,6 +282,7 @@ Glimmer App:
|
|
|
282
282
|
- [Widget Properties](#widget-properties)
|
|
283
283
|
- [Color](#color)
|
|
284
284
|
- [Font](#font)
|
|
285
|
+
- [Image](#image)
|
|
285
286
|
- [Cursor](#cursor)
|
|
286
287
|
- [Layouts](#layouts)
|
|
287
288
|
- [Layout Data](#layout-data)
|
|
@@ -296,10 +297,10 @@ Glimmer App:
|
|
|
296
297
|
- [Observing Models](#observing-models)
|
|
297
298
|
- [Custom Widgets](#custom-widgets)
|
|
298
299
|
- [Simple Example](#simple-example)
|
|
299
|
-
- [Lifecycle
|
|
300
|
+
- [Custom Widget Lifecycle Hooks](#custom-widget-lifecycle-hooks)
|
|
301
|
+
- [Lifecycle Hooks Example](#lifecycle-hooks-example)
|
|
300
302
|
- [Custom Widget API](#custom-widget-api)
|
|
301
303
|
- [Content/Options Example](#contentoptions-example)
|
|
302
|
-
- [Custom Widget Lifecycle Hooks](#custom-widget-lifecycle-hooks)
|
|
303
304
|
- [Gotcha](#gotcha)
|
|
304
305
|
- [Final Notes](#final-notes)
|
|
305
306
|
- [Custom Shells](#custom-shells)
|
|
@@ -335,6 +336,8 @@ Glimmer App:
|
|
|
335
336
|
- [Hello, Drag and Drop!](#hello-drag-and-drop)
|
|
336
337
|
- [Hello, Menu Bar!](#hello-menu-bar)
|
|
337
338
|
- [Hello, Pop Up Context Menu!](#hello-pop-up-context-menu)
|
|
339
|
+
- [Hello, Custom Widget!](#hello-custom-widget)
|
|
340
|
+
- [Hello, Custom Shell!](#hello-custom-shell)
|
|
338
341
|
- [Elaborate Samples](#elaborate-samples)
|
|
339
342
|
- [User Profile](#user-profile)
|
|
340
343
|
- [Login](#login)
|
|
@@ -416,7 +419,7 @@ If you intend to build a Glimmer app from scratch with [scaffolding](#scaffoldin
|
|
|
416
419
|
|
|
417
420
|
Otherwise, Option 2 ([Bundler](#option-2-bundler)) can be followed in rare cases where you want to build an app without [scaffolding](#scaffolding).
|
|
418
421
|
|
|
419
|
-
Note: if you encounter any [issues](https://github.com/AndyObtiva/glimmer-dsl-swt/issues), please [report](https://github.com/AndyObtiva/glimmer-dsl-swt/issues) and then
|
|
422
|
+
Note: if you encounter any [issues](https://github.com/AndyObtiva/glimmer-dsl-swt/issues), please [report](https://github.com/AndyObtiva/glimmer-dsl-swt/issues) and then install a previous version instead from the list of [Glimmer Releases](https://rubygems.org/gems/glimmer-dsl-swt/versions).
|
|
420
423
|
|
|
421
424
|
### Option 1: Direct Install
|
|
422
425
|
(Use for [Scaffolding](#scaffolding))
|
|
@@ -428,7 +431,7 @@ jgem install glimmer-dsl-swt
|
|
|
428
431
|
|
|
429
432
|
Or this command if you want a specific version:
|
|
430
433
|
```
|
|
431
|
-
jgem install glimmer-dsl-swt -v 4.17.
|
|
434
|
+
jgem install glimmer-dsl-swt -v 4.17.3.0
|
|
432
435
|
```
|
|
433
436
|
|
|
434
437
|
Note: Gem version numbers are in sync with the SWT library versions. The first two digits represent the SWT version number. The last two digits represent the minor and patch versions of Glimmer DSL for SWT.
|
|
@@ -439,7 +442,7 @@ Otherwise, you may also run `jruby -S gem install ...`
|
|
|
439
442
|
|
|
440
443
|
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.
|
|
441
444
|
|
|
442
|
-
Otherwise, if you are ready to build a Glimmer app
|
|
445
|
+
Otherwise, if you are ready to build a Glimmer app, you can jump to the [Glimmer Scaffolding](https://github.com/AndyObtiva/glimmer#scaffolding) section next.
|
|
443
446
|
|
|
444
447
|
Note: if you're using activerecord or activesupport, keep in mind that Glimmer unhooks ActiveSupport::Dependencies as it does not rely on it.
|
|
445
448
|
|
|
@@ -505,9 +508,9 @@ bin/glimmer sample:run[hello_world]
|
|
|
505
508
|
Below are the full usage instructions that come up when running `glimmer` without args.
|
|
506
509
|
|
|
507
510
|
```
|
|
508
|
-
Glimmer (Ruby Desktop Development GUI Library) - JRuby Gem: glimmer-dsl-swt v4.17.
|
|
511
|
+
Glimmer (Ruby Desktop Development GUI Library) - JRuby Gem: glimmer-dsl-swt v4.17.3.0
|
|
509
512
|
|
|
510
|
-
Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
|
|
513
|
+
Usage: glimmer [--bundler] [--pd] [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
|
|
511
514
|
|
|
512
515
|
Runs Glimmer applications and tasks.
|
|
513
516
|
|
|
@@ -517,7 +520,9 @@ automatically preloading the glimmer Ruby gem and SWT jar dependency.
|
|
|
517
520
|
Optionally, extra Glimmer options, JRuby options, and/or environment variables may be passed in.
|
|
518
521
|
|
|
519
522
|
Glimmer options:
|
|
520
|
-
- "--
|
|
523
|
+
- "--bundler=GROUP" : Activates gems in Bundler default group in Gemfile
|
|
524
|
+
- "--pd=BOOLEAN" : Requires puts_debuggerer to enable pd method
|
|
525
|
+
- "--quiet=BOOLEAN" : Does not announce file path of Glimmer application being launched
|
|
521
526
|
- "--debug" : Displays extra debugging information, passes "--debug" to JRuby, and enables debug logging
|
|
522
527
|
- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
|
|
523
528
|
|
|
@@ -532,9 +537,11 @@ Select a Glimmer task to run: (Press ↑/↓ arrow to move, Enter to select and
|
|
|
532
537
|
glimmer package[type] # Package app for distribution (generating config, jar, and native files) (type is optional)
|
|
533
538
|
glimmer package:clean # Clean by removing "dist" and "packages" directories
|
|
534
539
|
glimmer package:config # Generate JAR config file
|
|
540
|
+
glimmer package:gemspec # Generate gemspec
|
|
535
541
|
glimmer package:jar # Generate JAR file
|
|
536
542
|
glimmer package:lock_jars # Lock JARs
|
|
537
543
|
glimmer package:native[type] # Generate Native files
|
|
544
|
+
glimmer run[app_path] # Runs Glimmer app or custom shell gem in the current directory, unless app_path is specified, then runs it instead (app_path is optional)
|
|
538
545
|
glimmer sample:code[name] # Outputs code for a Glimmer internal sample [included in gem] (name is required)
|
|
539
546
|
glimmer sample:list[query] # Lists Glimmer internal samples [included in gem]. Filters by query if specified (query is optional)
|
|
540
547
|
glimmer sample:run[name] # Runs a Glimmer internal sample [included in gem]. If no name is supplied, it runs all samples
|
|
@@ -618,7 +625,7 @@ This will run the hello_tab sample and output its code:
|
|
|
618
625
|
```
|
|
619
626
|
$ glimmer sample:run[hello_tab]
|
|
620
627
|
|
|
621
|
-
# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.
|
|
628
|
+
# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.3.0/samples/hello/hello_tab.rb
|
|
622
629
|
|
|
623
630
|
class HelloTab
|
|
624
631
|
include Glimmer
|
|
@@ -663,7 +670,7 @@ Example:
|
|
|
663
670
|
```
|
|
664
671
|
$ glimmer sample:code[tic_tac_toe]
|
|
665
672
|
|
|
666
|
-
# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.
|
|
673
|
+
# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.3.0/samples/elaborate/tic_tac_toe.rb
|
|
667
674
|
|
|
668
675
|
require_relative "tic_tac_toe/board"
|
|
669
676
|
|
|
@@ -724,7 +731,7 @@ TicTacToe.new.open
|
|
|
724
731
|
# # #
|
|
725
732
|
|
|
726
733
|
|
|
727
|
-
# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.
|
|
734
|
+
# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.3.0/samples/elaborate/tic_tac_toe/cell.rb
|
|
728
735
|
|
|
729
736
|
class TicTacToe
|
|
730
737
|
class Cell
|
|
@@ -757,7 +764,7 @@ end
|
|
|
757
764
|
# # #
|
|
758
765
|
|
|
759
766
|
|
|
760
|
-
# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.
|
|
767
|
+
# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.3.0/samples/elaborate/tic_tac_toe/board.rb
|
|
761
768
|
|
|
762
769
|
require_relative 'cell'
|
|
763
770
|
|
|
@@ -890,7 +897,7 @@ end
|
|
|
890
897
|
### Scaffolding
|
|
891
898
|
|
|
892
899
|
Glimmer borrows from Rails the idea of Scaffolding, that is generating a structure for your app files that
|
|
893
|
-
helps you get started just like true
|
|
900
|
+
helps you get started just like true building scaffolding helps construction workers, civil engineers, and architects.
|
|
894
901
|
|
|
895
902
|
Glimmer scaffolding goes beyond just scaffolding the app files that Rails does. It also packages it and launches it,
|
|
896
903
|
getting you to a running and delivered state of an advanced "Hello, World!" Glimmer application right off the bat.
|
|
@@ -906,7 +913,9 @@ letting Glimmer scaffolding take care of initial app file structure concerns, su
|
|
|
906
913
|
- Icon (under `package/{platform}/{App Name}.{icon_extension}` for `macosx` .icns, `windows` .ico, and `linux` .png)
|
|
907
914
|
- Bin file for starting application (`bin/{app_name}.rb`)
|
|
908
915
|
|
|
909
|
-
|
|
916
|
+
You need to have your Git `user.name` and `github.user` configured before scaffolding since Glimmer uses Juwelier, which relies on them in creating a Git repo for your Glimmer app.
|
|
917
|
+
|
|
918
|
+
NOTE: Linux is not fully supported yet with scaffolding. Please report any issues you may encounter.
|
|
910
919
|
|
|
911
920
|
#### App
|
|
912
921
|
|
|
@@ -918,7 +927,7 @@ To scaffold a Glimmer app from scratch, run the following command:
|
|
|
918
927
|
glimmer scaffold[AppName]
|
|
919
928
|
```
|
|
920
929
|
|
|
921
|
-
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.
|
|
930
|
+
This will generate an advanced "Hello, World!" app, package it as a Mac or Windows native file (DMG/PKG/APP/MSI), and launch it all in one fell swoop.
|
|
922
931
|
|
|
923
932
|
Suppose you run:
|
|
924
933
|
|
|
@@ -942,7 +951,7 @@ $ glimmer scaffold[greeter]
|
|
|
942
951
|
create spec/spec_helper.rb
|
|
943
952
|
create spec/greeter_spec.rb
|
|
944
953
|
create .rspec
|
|
945
|
-
|
|
954
|
+
Juwelier has prepared your gem in ./greeter
|
|
946
955
|
Created greeter/.gitignore
|
|
947
956
|
Created greeter/.ruby-version
|
|
948
957
|
Created greeter/.ruby-gemset
|
|
@@ -976,12 +985,119 @@ And, here is the Windows version of the boilerplate Preferences dialog.
|
|
|
976
985
|
|
|
977
986
|
|
|
978
987
|
|
|
979
|
-
In order to run the app after making changes, you must run the `glimmer
|
|
988
|
+
In order to run the app after making changes, you must run the `glimmer run`. It automatically detects the generated run script under the `bin` directory and uses it as an argument.
|
|
989
|
+
|
|
990
|
+
```
|
|
991
|
+
glimmer run
|
|
992
|
+
```
|
|
993
|
+
|
|
994
|
+
Alternatively, to mantually run the app, you may type:
|
|
995
|
+
|
|
996
|
+
```
|
|
997
|
+
glimmer run[bin/greeter]
|
|
998
|
+
```
|
|
999
|
+
|
|
1000
|
+
or:
|
|
980
1001
|
|
|
981
1002
|
```
|
|
982
1003
|
glimmer bin/greeter
|
|
983
1004
|
```
|
|
984
1005
|
|
|
1006
|
+
#### Desktopify
|
|
1007
|
+
|
|
1008
|
+
This scaffolding mode enables you to desktopify a web app. Glimmer Scaffolding basically wraps the website with a [Browser Widget](#browser-widget).
|
|
1009
|
+
|
|
1010
|
+
The desktopify app is similar to the standard scaffolded app. It can be extended and the [browser may even be instrumented](https://help.eclipse.org/2020-09/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/browser/Browser.html).
|
|
1011
|
+
|
|
1012
|
+
The app even remembers your cookies if you log into the website, close the app, and reopen again.
|
|
1013
|
+
|
|
1014
|
+
Note that on Linux, the default SWT browser, which runs on webkit, does not support HTML5 Video out of the box. If you need video support, open `Gemfile` after scaffolding and enable the line that has the `glimmer-cw-browser-chromium` gem then replace the `browser` in "app/views/snowboard_utah/app_view.rb" with `browser(:chromium)`
|
|
1015
|
+
|
|
1016
|
+
Before you start, make sure you are in a JRuby environment with Glimmer gem installed as per "Direct Install" pre-requisites.
|
|
1017
|
+
|
|
1018
|
+
To scaffold a Glimmer desktopify app from scratch, run the following command:
|
|
1019
|
+
|
|
1020
|
+
```
|
|
1021
|
+
glimmer scaffold:desktopify[app_name,website]
|
|
1022
|
+
```
|
|
1023
|
+
|
|
1024
|
+
This will generate a Glimmer app, package it as a Mac or Windows native file (DMG/PKG/APP/MSI), and launch it all in one fell swoop.
|
|
1025
|
+
|
|
1026
|
+
Suppose you run:
|
|
1027
|
+
|
|
1028
|
+
```
|
|
1029
|
+
glimmer scaffold:desktopify[snowboard_utah,https://www.brightonresort.com]
|
|
1030
|
+
```
|
|
1031
|
+
|
|
1032
|
+
You should see output like the following:
|
|
1033
|
+
|
|
1034
|
+
```
|
|
1035
|
+
$ glimmer scaffold:desktopify[snowboard_utah,https://www.brightonresort.com]
|
|
1036
|
+
Fetching kamelcase-0.0.2.gem
|
|
1037
|
+
Fetching github_api-0.19.0.gem
|
|
1038
|
+
Fetching highline-2.0.3.gem
|
|
1039
|
+
Fetching juwelier-2.4.9.gem
|
|
1040
|
+
Fetching hashie-3.6.0.gem
|
|
1041
|
+
Fetching nokogiri-1.10.10-java.gem
|
|
1042
|
+
Fetching semver2-3.4.2.gem
|
|
1043
|
+
Successfully installed semver2-3.4.2
|
|
1044
|
+
Successfully installed kamelcase-0.0.2
|
|
1045
|
+
Successfully installed highline-2.0.3
|
|
1046
|
+
Successfully installed hashie-3.6.0
|
|
1047
|
+
Successfully installed github_api-0.19.0
|
|
1048
|
+
Successfully installed nokogiri-1.10.10-java
|
|
1049
|
+
Successfully installed juwelier-2.4.9
|
|
1050
|
+
7 gems installed
|
|
1051
|
+
create .gitignore
|
|
1052
|
+
create Rakefile
|
|
1053
|
+
create Gemfile
|
|
1054
|
+
create LICENSE.txt
|
|
1055
|
+
create README.markdown
|
|
1056
|
+
create .document
|
|
1057
|
+
create lib
|
|
1058
|
+
create lib/snowboard_utah.rb
|
|
1059
|
+
create .rspec
|
|
1060
|
+
Juwelier has prepared your gem in ./snowboard_utah
|
|
1061
|
+
Created snowboard_utah/.gitignore
|
|
1062
|
+
Created snowboard_utah/.ruby-version
|
|
1063
|
+
Created snowboard_utah/.ruby-gemset
|
|
1064
|
+
Created snowboard_utah/VERSION
|
|
1065
|
+
Created snowboard_utah/LICENSE.txt
|
|
1066
|
+
Created snowboard_utah/Gemfile
|
|
1067
|
+
Created snowboard_utah/Rakefile
|
|
1068
|
+
Created snowboard_utah/app/snowboard_utah.rb
|
|
1069
|
+
Created snowboard_utah/app/views/snowboard_utah/app_view.rb
|
|
1070
|
+
Created snowboard_utah/package/windows/Snowboard Utah.ico
|
|
1071
|
+
Created snowboard_utah/package/macosx/Snowboard Utah.icns
|
|
1072
|
+
Created snowboard_utah/package/linux/Snowboard Utah.png
|
|
1073
|
+
Created snowboard_utah/bin/snowboard_utah
|
|
1074
|
+
...
|
|
1075
|
+
```
|
|
1076
|
+
|
|
1077
|
+
Eventually, it will launch a desktopified version of "https://www.brightonresort.com" having the title of ("Snowboard Utah").
|
|
1078
|
+
|
|
1079
|
+
Desktopified App on Mac
|
|
1080
|
+
|
|
1081
|
+
|
|
1082
|
+
|
|
1083
|
+
It also comes with a boilerplate About dialog.
|
|
1084
|
+
|
|
1085
|
+
|
|
1086
|
+
|
|
1087
|
+
Desktopified App on Windows
|
|
1088
|
+
|
|
1089
|
+
|
|
1090
|
+
|
|
1091
|
+
Desktopified App on Linux
|
|
1092
|
+
|
|
1093
|
+
|
|
1094
|
+
|
|
1095
|
+
In order to run the app after making changes, you must run the `glimmer run`. It automatically detects the generated run script under the `bin` directory and uses it as an argument.
|
|
1096
|
+
|
|
1097
|
+
```
|
|
1098
|
+
glimmer run
|
|
1099
|
+
```
|
|
1100
|
+
|
|
985
1101
|
#### Custom Shell
|
|
986
1102
|
|
|
987
1103
|
To scaffold a Glimmer custom shell (full window view) for an existing Glimmer app, run the following command:
|
|
@@ -1013,7 +1129,7 @@ glimmer scaffold:cw[name]
|
|
|
1013
1129
|
#### Custom Shell Gem
|
|
1014
1130
|
|
|
1015
1131
|
Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
|
|
1016
|
-
They have everything scaffolded Glimmer apps come with in addition to gem content like a [
|
|
1132
|
+
They have everything scaffolded Glimmer apps come with in addition to gem content like a [Juwelier](https://rubygems.org/gems/juwelier) Rakefile that can build gemspec and release gems.
|
|
1017
1133
|
Unlike scaffolded Glimmer apps, custom shell gem content lives under the `lib` directory (not `app`).
|
|
1018
1134
|
They can be packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem.
|
|
1019
1135
|
Of course, you can just build a Ruby gem and disregard native executable packaging if you do not need it.
|
|
@@ -1038,7 +1154,7 @@ Only official Glimmer gems created by the Glimmer project committers will have n
|
|
|
1038
1154
|
|
|
1039
1155
|
Since custom shell gems are both an app and a gem, they provide two ways to run:
|
|
1040
1156
|
- Run the `glimmer` command and pass it the generated script under the `bin` directory that matches the gem name (e.g. run `glimmer bin/glimmer-cs-calculator`)
|
|
1041
|
-
- Run the executable
|
|
1157
|
+
- Run the executable shell script that ships with the gem directly (does not need the `glimmer` command). It intentionally has a shorter name for convenience since it is meant to be used on the command line (not in a package), so you can leave out the `glimmer-cs-` prefix (e.g. run `bin/calculator` directly). This is also used as the main way of running custom shell gems on Linux.
|
|
1042
1158
|
|
|
1043
1159
|
Examples:
|
|
1044
1160
|
|
|
@@ -1187,24 +1303,46 @@ Output:
|
|
|
1187
1303
|
|
|
1188
1304
|
Name Gem Version Author Description
|
|
1189
1305
|
|
|
1190
|
-
Css glimmer-dsl-css
|
|
1191
|
-
Opal glimmer-dsl-opal 0.
|
|
1192
|
-
Swt glimmer-dsl-swt 4.17.
|
|
1193
|
-
Tk glimmer-dsl-tk 0.0.
|
|
1194
|
-
Xml glimmer-dsl-xml
|
|
1306
|
+
Css glimmer-dsl-css 1.1.0 AndyMaleh Glimmer DSL for CSS
|
|
1307
|
+
Opal glimmer-dsl-opal 0.3.0 AndyMaleh Glimmer DSL for Opal
|
|
1308
|
+
Swt glimmer-dsl-swt 4.17.3.0 AndyMaleh Glimmer DSL for SWT
|
|
1309
|
+
Tk glimmer-dsl-tk 0.0.6 AndyMaleh Glimmer DSL for Tk
|
|
1310
|
+
Xml glimmer-dsl-xml 1.1.0 AndyMaleh Glimmer DSL for XML
|
|
1195
1311
|
```
|
|
1196
1312
|
|
|
1197
1313
|
### Packaging
|
|
1198
1314
|
|
|
1315
|
+
Glimmer supports packaging applications as native files on Mac and Windows.
|
|
1316
|
+
|
|
1199
1317
|
Glimmer packaging tasks are detailed under [Packaging & Distribution](#packaging--distribution).
|
|
1200
1318
|
|
|
1319
|
+
On Linux, the Glimmer [Custom Shell Gem](#custom-shell-gem) approach provides a [Gem Packaged Shell Script](#custom-shell-gem) (e.g. `calculator` command becomes available after installing the [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) gem)
|
|
1320
|
+
|
|
1201
1321
|
### Raw JRuby Command
|
|
1202
1322
|
|
|
1203
1323
|
If there is a need to run Glimmer directly via the `jruby` command, you
|
|
1204
|
-
may run the following:
|
|
1324
|
+
may run the following on Windows/Linux:
|
|
1205
1325
|
|
|
1206
1326
|
```
|
|
1207
|
-
jruby -
|
|
1327
|
+
jruby -r glimmer-dsl-swt -S application.rb
|
|
1328
|
+
```
|
|
1329
|
+
|
|
1330
|
+
Or, the following on Mac:
|
|
1331
|
+
|
|
1332
|
+
```
|
|
1333
|
+
jruby -J-XstartOnFirstThread -r glimmer-dsl-swt -S application.rb
|
|
1334
|
+
```
|
|
1335
|
+
|
|
1336
|
+
If you want to use a specific custom version of SWT, run the following on Windows/Linux:
|
|
1337
|
+
|
|
1338
|
+
```
|
|
1339
|
+
jruby -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb
|
|
1340
|
+
```
|
|
1341
|
+
|
|
1342
|
+
Or, the following on Mac:
|
|
1343
|
+
|
|
1344
|
+
```
|
|
1345
|
+
jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb
|
|
1208
1346
|
```
|
|
1209
1347
|
|
|
1210
1348
|
The `-J-classpath` option specifies the `swt.jar` file path, which can be a
|
|
@@ -1222,7 +1360,7 @@ However, if there is a reason to use the raw `jruby` command directly instead of
|
|
|
1222
1360
|
|
|
1223
1361
|
Example:
|
|
1224
1362
|
```
|
|
1225
|
-
jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer -S application.rb
|
|
1363
|
+
jruby -J-XstartOnFirstThread -J-classpath "path_to/swt.jar" -r glimmer-dsl-swt -S application.rb
|
|
1226
1364
|
```
|
|
1227
1365
|
|
|
1228
1366
|
## Girb (Glimmer irb) Command
|
|
@@ -1306,19 +1444,21 @@ Glimmer DSL syntax consists mainly of:
|
|
|
1306
1444
|
|
|
1307
1445
|
### DSL Auto-Expansion
|
|
1308
1446
|
|
|
1309
|
-
Glimmer supports a new and radical Ruby DSL concept called DSL Auto-Expansion.
|
|
1447
|
+
Glimmer supports a new and radical Ruby DSL concept called DSL Auto-Expansion. To explain, let's first mention the two types of Glimmer GUI DSL keywords: static and dynamic.
|
|
1310
1448
|
|
|
1311
1449
|
Static keywords are pre-identified keywords in the Glimmer DSL, such as `shell`, `display`, `message_box`, `async_exec`, `sync_exec`, and `bind`.
|
|
1312
1450
|
|
|
1313
|
-
Dynamic keywords are dynamically figured out from currently imported (aka required/loaded) SWT widgets
|
|
1451
|
+
Dynamic keywords are dynamically figured out from currently imported (aka required/loaded) SWT widgets and custom widgets. Examples are: `label`, `combo`, and `list` for SWT widgets and `c_date_time`, `video`, and `gantt_chart` for custom widgets.
|
|
1452
|
+
|
|
1453
|
+
The only reason to distinguish between the two is to realize that importing new Glimmer [custom widgets](#custom-widgets) and Java SWT custom widget libraries automatically expands Glimmer's DSL vocabulary with new dynamic keywords.
|
|
1314
1454
|
|
|
1315
|
-
|
|
1455
|
+
For example, if a project adds this custom Java SWT library from the [Nebula Project](https://www.eclipse.org/nebula/):
|
|
1316
1456
|
|
|
1317
|
-
|
|
1457
|
+
https://www.eclipse.org/nebula/widgets/gallery/gallery.php
|
|
1318
1458
|
|
|
1319
|
-
|
|
1459
|
+
Glimmer will automatically support using the keyword `gallery`
|
|
1320
1460
|
|
|
1321
|
-
|
|
1461
|
+
This is what DSL Auto-Expansion is.
|
|
1322
1462
|
|
|
1323
1463
|
You will learn more about widgets next.
|
|
1324
1464
|
|
|
@@ -1433,27 +1573,9 @@ shell {
|
|
|
1433
1573
|
|
|
1434
1574
|
If you are new to Glimmer, you have learned enough to start running some [samples](#samples). Go ahead and run all Glimmer [samples](#samples), and come back to read the rest in any order you like since this material is more organized like a reference.
|
|
1435
1575
|
|
|
1436
|
-
|
|
1576
|
+
If you are advanced and need more widgets, check out the [Nebula Project](https://www.eclipse.org/nebula/) for an extensive list of high quality custom widgets:
|
|
1437
1577
|
|
|
1438
|
-
|
|
1439
|
-
and access available monitors.
|
|
1440
|
-
It is automatically instantiated upon first instantiation of a `shell` widget.
|
|
1441
|
-
Alternatively, for advanced use cases, it can be created explicitly with Glimmer `display` keyword. When a `shell` is later declared, it
|
|
1442
|
-
automatically uses the display created earlier without having to explicitly hook it.
|
|
1443
|
-
|
|
1444
|
-
```ruby
|
|
1445
|
-
@display = display {
|
|
1446
|
-
cursor_location 300, 300
|
|
1447
|
-
on_swt_keydown {
|
|
1448
|
-
# ...
|
|
1449
|
-
}
|
|
1450
|
-
# ...
|
|
1451
|
-
}
|
|
1452
|
-
@shell = shell { # uses display created above
|
|
1453
|
-
}
|
|
1454
|
-
```
|
|
1455
|
-
The benefit of instantiating an SWT Display explicitly is to set [Properties](#widget-properties) or [Observers](#observer).
|
|
1456
|
-
Although SWT Display is not technically a widget, it has similar APIs in SWT and similar DSL support in Glimmer.
|
|
1578
|
+
https://www.eclipse.org/nebula/
|
|
1457
1579
|
|
|
1458
1580
|
#### SWT Proxies
|
|
1459
1581
|
|
|
@@ -1470,7 +1592,26 @@ Glimmer follows Proxy Design Pattern by having Ruby proxy wrappers for all SWT o
|
|
|
1470
1592
|
|
|
1471
1593
|
These proxy objects have an API and provide some convenience methods, some of which are mentioned below.
|
|
1472
1594
|
|
|
1473
|
-
#####
|
|
1595
|
+
##### swt_widget
|
|
1596
|
+
|
|
1597
|
+
Glimmer SWT proxies come with the instance method `#swt_widget`, which returns the actual SWT `Widget` object wrapped by the Glimmer widget proxy. It is useful in cases you'd like to do some custom SWT programming outside of Glimmer.
|
|
1598
|
+
|
|
1599
|
+
##### Shell widget proxy methods
|
|
1600
|
+
|
|
1601
|
+
Shell widget proxy has extra methods specific to SWT Shell:
|
|
1602
|
+
- `#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.
|
|
1603
|
+
- `#show`: Alias for `#open`
|
|
1604
|
+
- `#hide`: Hides a shell setting "visible" property to false
|
|
1605
|
+
- `#close`: Closes the shell
|
|
1606
|
+
- `#center`: Centers the shell within monitor it is in
|
|
1607
|
+
- `#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.
|
|
1608
|
+
- `#visible?`: Returns whether a shell is visible
|
|
1609
|
+
- `#opened_before?`: Returns whether a shell has been opened at least once before (additionally implying the SWT Event Loop has been started already)
|
|
1610
|
+
- `#visible=`: Setting to true opens/shows shell. Setting to false hides the shell.
|
|
1611
|
+
- `#pack`: Packs contained widgets using SWT's `Shell#pack` method
|
|
1612
|
+
- `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
|
|
1613
|
+
|
|
1614
|
+
##### Widget Content Block
|
|
1474
1615
|
|
|
1475
1616
|
Glimmer allows re-opening any widget and adding properties or extra content after it has been constructed already by using the `#content` method.
|
|
1476
1617
|
|
|
@@ -1496,7 +1637,31 @@ Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
|
|
1496
1637
|
@shell.open
|
|
1497
1638
|
```
|
|
1498
1639
|
|
|
1499
|
-
#####
|
|
1640
|
+
##### Shell Icon
|
|
1641
|
+
|
|
1642
|
+
To set the shell icon, simply set the `image` property under the `shell` widget. This shows up in the operating system toolbar and app-switcher (e.g. CMD+TAB) (and application window top-left corner in Windows)
|
|
1643
|
+
|
|
1644
|
+
Example:
|
|
1645
|
+
|
|
1646
|
+
```ruby
|
|
1647
|
+
shell {
|
|
1648
|
+
# ...
|
|
1649
|
+
image 'path/to/image.png'
|
|
1650
|
+
# ...
|
|
1651
|
+
}
|
|
1652
|
+
```
|
|
1653
|
+
|
|
1654
|
+
###### Shell Icon Tip for Packaging on Windows
|
|
1655
|
+
|
|
1656
|
+
When setting shell icon for a [packaged](#packaging--distribution) app, which has a JAR file at its core, you can reference the `ico` file that ships with the app by going one level up (e.g. `'../AppName.ico'`)
|
|
1657
|
+
|
|
1658
|
+
#### Dialog
|
|
1659
|
+
|
|
1660
|
+
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.
|
|
1661
|
+
|
|
1662
|
+
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.
|
|
1663
|
+
|
|
1664
|
+
##### message_box
|
|
1500
1665
|
|
|
1501
1666
|
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.
|
|
1502
1667
|
|
|
@@ -1535,48 +1700,65 @@ message_box {
|
|
|
1535
1700
|
}.open
|
|
1536
1701
|
```
|
|
1537
1702
|
|
|
1538
|
-
|
|
1539
|
-
|
|
1540
|
-
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.
|
|
1541
|
-
|
|
1542
|
-
##### Shell widget proxy methods
|
|
1543
|
-
|
|
1544
|
-
Shell widget proxy has extra methods specific to SWT Shell:
|
|
1545
|
-
- `#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.
|
|
1546
|
-
- `#show`: Alias for `#open`
|
|
1547
|
-
- `#hide`: Hides a shell setting "visible" property to false
|
|
1548
|
-
- `#close`: Closes the shell
|
|
1549
|
-
- `#center`: Centers the shell within monitor it is in
|
|
1550
|
-
- `#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.
|
|
1551
|
-
- `#visible?`: Returns whether a shell is visible
|
|
1552
|
-
- `#opened_before?`: Returns whether a shell has been opened at least once before (additionally implying the SWT Event Loop has been started already)
|
|
1553
|
-
- `#visible=`: Setting to true opens/shows shell. Setting to false hides the shell.
|
|
1554
|
-
- `#pack`: Packs contained widgets using SWT's `Shell#pack` method
|
|
1555
|
-
- `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
|
|
1703
|
+
#### Display
|
|
1556
1704
|
|
|
1557
|
-
|
|
1705
|
+
The SWT `Display` class is a singleton in Glimmer. It is used in SWT to represent your display device, allowing you to manage GUI globally
|
|
1706
|
+
and access available monitors. Additionally, it is responsible for the SWT event loop, which runs on the first thread the Glimmer application starts on. In multi-threaded programming, `Display` provides the methods `async_exec` and `sync_exec` to enable enqueuing GUI changes asynchronously or synchronously from threads other than the main (first) thread since direct GUI changes are forbidden from other threads by design.
|
|
1558
1707
|
|
|
1559
|
-
|
|
1708
|
+
`Display` is automatically instantiated upon first instantiation of a `shell` widget.
|
|
1560
1709
|
|
|
1561
|
-
|
|
1710
|
+
Alternatively, for advanced use cases, a `Display` can be created explicitly with the Glimmer `display` keyword. When a `shell` is later declared, it
|
|
1711
|
+
automatically uses the `display` created earlier without having to explicitly hook it.
|
|
1562
1712
|
|
|
1563
1713
|
```ruby
|
|
1564
|
-
|
|
1565
|
-
|
|
1566
|
-
|
|
1714
|
+
@display = display {
|
|
1715
|
+
cursor_location 300, 300
|
|
1716
|
+
on_swt_keydown {
|
|
1717
|
+
# ...
|
|
1718
|
+
}
|
|
1567
1719
|
# ...
|
|
1568
1720
|
}
|
|
1721
|
+
@shell = shell { # uses display created above
|
|
1722
|
+
}
|
|
1569
1723
|
```
|
|
1724
|
+
The benefit of instantiating an SWT Display explicitly is to set [Properties](#widget-properties) or [Observers](#observer).
|
|
1725
|
+
Although SWT Display is not technically a widget, it has similar APIs and DSL support.
|
|
1570
1726
|
|
|
1571
|
-
|
|
1727
|
+
#### Multi-Threading
|
|
1572
1728
|
|
|
1573
|
-
|
|
1729
|
+
[JRuby](https://www.jruby.org/) supports [truly parallel multi-threading](https://github.com/jruby/jruby/wiki/Concurrency-in-jruby) since it relies on the JVM (Java Virtual Machine). As such, it enables development of highly-interactive desktop applications that can do background work while the user is interacting with the GUI.
|
|
1574
1730
|
|
|
1575
|
-
|
|
1731
|
+
##### async_exec
|
|
1576
1732
|
|
|
1577
|
-
|
|
1733
|
+
`async_exec` is a Glimmer DSL keyword in addition to being a method on `display`. It accepts a block and when invoked, adds the block to the end of a queue of GUI events scheduled to run on the SWT event loop, executing asynchronously.
|
|
1578
1734
|
|
|
1579
|
-
|
|
1735
|
+
Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
|
1736
|
+
|
|
1737
|
+
```
|
|
1738
|
+
@shell = shell {
|
|
1739
|
+
text 'Glimmer'
|
|
1740
|
+
@label = label {
|
|
1741
|
+
text 'Hello, World!'
|
|
1742
|
+
}
|
|
1743
|
+
}
|
|
1744
|
+
|
|
1745
|
+
Thread.new {
|
|
1746
|
+
[:red, :dark_green, :blue].cycle { |color|
|
|
1747
|
+
async_exec {
|
|
1748
|
+
@label.content {
|
|
1749
|
+
foreground color if @shell.visible?
|
|
1750
|
+
}
|
|
1751
|
+
}
|
|
1752
|
+
sleep(1)
|
|
1753
|
+
}
|
|
1754
|
+
}
|
|
1755
|
+
|
|
1756
|
+
@shell.open
|
|
1757
|
+
```
|
|
1758
|
+
|
|
1759
|
+
##### sync_exec
|
|
1760
|
+
|
|
1761
|
+
`sync_exec` works just like `async_exec` except it executes the block synchronously at the earliest opportunity possible, waiting for the block to be finished.
|
|
1580
1762
|
|
|
1581
1763
|
#### Menus
|
|
1582
1764
|
|
|
@@ -1909,6 +2091,16 @@ Example:
|
|
|
1909
2091
|
@font = font(name: 'Arial', height: 36, style: :normal)
|
|
1910
2092
|
```
|
|
1911
2093
|
|
|
2094
|
+
### Image
|
|
2095
|
+
|
|
2096
|
+
The `image` keyword creates an instance of [org.eclipse.swt.graphics.Image](https://help.eclipse.org/2020-09/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/graphics/Image.html).
|
|
2097
|
+
|
|
2098
|
+
It is a graphics `Image` object (not a widget), but is used used in setting the `image` property on `label` and `background_image` on `composite` (and subclasses)
|
|
2099
|
+
|
|
2100
|
+
Glimmer recently included **EXPERIMENTAL** gif animation support for the `background_image` property on `composite' since SWT does not support animation by default. On Windows, it only works inside composites nested under standard shells, not ones that have the SWT styles :on_top or :no_trim
|
|
2101
|
+
|
|
2102
|
+
Learn more about images in general at this SWT Image guide: https://www.eclipse.org/articles/Article-SWT-images/graphics-resources.html
|
|
2103
|
+
|
|
1912
2104
|
### Cursor
|
|
1913
2105
|
|
|
1914
2106
|
SWT widget `cursor` property represents the mouse cursor you see on the screen when you hover over that widget.
|
|
@@ -2628,12 +2820,44 @@ end
|
|
|
2628
2820
|
|
|
2629
2821
|
### Custom Widgets
|
|
2630
2822
|
|
|
2631
|
-
Glimmer
|
|
2823
|
+
Custom widgets are brand new Glimmer DSL keywords that represent aggregates of existing widgets (e.g. `address_form`), customized existing widgets (e.g. `greeting_label`), or brand new widgets (e.g. `oscilloscope`)
|
|
2632
2824
|
|
|
2633
|
-
|
|
2825
|
+
You can find out about [published Glimmer Custom Widgets](https://github.com/AndyObtiva/glimmer-dsl-swt#gem-listing) by running the `glimmer list:gems:customwidget` command
|
|
2826
|
+
|
|
2827
|
+
Glimmer supports two ways of creating custom widgets with minimal code:
|
|
2828
|
+
1. Method-based Custom Widgets (for single-view-internal reuse): Extract a method containing Glimmer DSL widget syntax. Useful for quickly eliminating redundant code within a single view.
|
|
2829
|
+
2. Class-based Custom Widgets (for multiple-view-external reuse): Create a class that includes the `Glimmer::UI::CustomWidget` module and Glimmer DSL widget syntax in a `body {}` block. This will automatically extend Glimmer's DSL syntax with an underscored lowercase keyword matching the class name by convention. Useful in making a custom widget available in many views.
|
|
2830
|
+
|
|
2831
|
+
Approach #1 is a casual Ruby-based approach. Approach #2 is the official Glimmer approach. Typically, when referring to Custom Widgets, we are talking about Class-based Custom Widgets.
|
|
2832
|
+
|
|
2833
|
+
A developer might start with approach #1 to eliminate duplication in a view and later upgrade it to approach #2 when needing to export a custom widget to make it available in many views.
|
|
2834
|
+
|
|
2835
|
+
Class-based Custom Widgets offer a number of benefits over method-based custom widgets, such as built-in support for passing SWT style, nested block of extra widgets and properties, and `before_body`/`after_body` hooks.
|
|
2634
2836
|
|
|
2635
2837
|
#### Simple Example
|
|
2636
2838
|
|
|
2839
|
+
##### Method-Based Custom Widget Example
|
|
2840
|
+
|
|
2841
|
+
(you may copy/paste in [`girb`](#girb-glimmer-irb-command))
|
|
2842
|
+
|
|
2843
|
+
Definition and usage in the same file:
|
|
2844
|
+
```ruby
|
|
2845
|
+
def red_label(label_text)
|
|
2846
|
+
label {
|
|
2847
|
+
text label_text
|
|
2848
|
+
background :red
|
|
2849
|
+
}
|
|
2850
|
+
end
|
|
2851
|
+
|
|
2852
|
+
shell {
|
|
2853
|
+
red_label('Red Label')
|
|
2854
|
+
}.open
|
|
2855
|
+
```
|
|
2856
|
+
|
|
2857
|
+
##### Class-Based Custom Widget Example
|
|
2858
|
+
|
|
2859
|
+
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 `__`)
|
|
2860
|
+
|
|
2637
2861
|
(you may copy/paste in [`girb`](#girb-glimmer-irb-command))
|
|
2638
2862
|
|
|
2639
2863
|
Definition:
|
|
@@ -2652,15 +2876,22 @@ end
|
|
|
2652
2876
|
Usage:
|
|
2653
2877
|
```ruby
|
|
2654
2878
|
shell {
|
|
2655
|
-
red_label {
|
|
2656
|
-
text 'Red Label'
|
|
2879
|
+
red_label(:center) {
|
|
2880
|
+
text 'Red Label'
|
|
2881
|
+
foreground :green
|
|
2657
2882
|
}
|
|
2658
2883
|
}.open
|
|
2659
2884
|
```
|
|
2660
2885
|
|
|
2661
|
-
As you can see, `RedLabel` became Glimmer DSL keyword
|
|
2886
|
+
As you can see, `RedLabel` became the Glimmer DSL keyword `red_label` and worked just like a standard label by taking in SWT style and nested properties. As such, it is a first-class citizen of the Glimmer GUI DSL.
|
|
2887
|
+
|
|
2888
|
+
#### Custom Widget Lifecycle Hooks
|
|
2889
|
+
|
|
2890
|
+
You may execute code before or after evaluating the body with these lifecycle hooks:
|
|
2891
|
+
- `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`
|
|
2892
|
+
- `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.
|
|
2662
2893
|
|
|
2663
|
-
#### Lifecycle
|
|
2894
|
+
#### Lifecycle Hooks Example
|
|
2664
2895
|
|
|
2665
2896
|
(you may copy/paste in [`girb`](#girb-glimmer-irb-command))
|
|
2666
2897
|
|
|
@@ -2755,12 +2986,6 @@ shell {
|
|
|
2755
2986
|
|
|
2756
2987
|
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'`
|
|
2757
2988
|
|
|
2758
|
-
#### Custom Widget Lifecycle Hooks
|
|
2759
|
-
|
|
2760
|
-
Last but not least, these are the available lifecycle hooks:
|
|
2761
|
-
- `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`
|
|
2762
|
-
- `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.
|
|
2763
|
-
|
|
2764
2989
|
#### Gotcha
|
|
2765
2990
|
|
|
2766
2991
|
Beware of defining a custom attribute that is a common SWT widget property name.
|
|
@@ -2796,12 +3021,16 @@ The `text` method invoked in the custom widget body will call the one you define
|
|
|
2796
3021
|
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:
|
|
2797
3022
|
[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)
|
|
2798
3023
|
|
|
3024
|
+
Also, you may check out [Hello, Custom Widget!](#hello-custom-widget) for another example.
|
|
3025
|
+
|
|
2799
3026
|
### Custom Shells
|
|
2800
3027
|
|
|
2801
3028
|
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.
|
|
2802
3029
|
|
|
2803
3030
|
They may also be chained in a wizard fashion.
|
|
2804
3031
|
|
|
3032
|
+
You can find out about [published Glimmer Custom Shells](https://github.com/AndyObtiva/glimmer-dsl-swt#gem-listing) by running the `glimmer list:gems:customshell` command
|
|
3033
|
+
|
|
2805
3034
|
Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
|
|
2806
3035
|
|
|
2807
3036
|
```ruby
|
|
@@ -2861,6 +3090,8 @@ shell { |app_shell|
|
|
|
2861
3090
|
}.open
|
|
2862
3091
|
```
|
|
2863
3092
|
|
|
3093
|
+
You may check out [Hello, Custom Shell!](#hello-custom-shell) for another example.
|
|
3094
|
+
|
|
2864
3095
|
### Drag and Drop
|
|
2865
3096
|
|
|
2866
3097
|
Glimmer offers Drag and Drop support, thanks to [SWT](https://www.eclipse.org/swt/) and Glimmer's lightweight [DSL syntax](#glimmer-dsl-syntax).
|
|
@@ -2921,9 +3152,8 @@ Optional steps:
|
|
|
2921
3152
|
|
|
2922
3153
|
#### Multi-DSL Support
|
|
2923
3154
|
|
|
2924
|
-
Glimmer is a DSL
|
|
2925
|
-
- [SWT](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (
|
|
2926
|
-
- [Tk](https://github.com/AndyObtiva/glimmer-dsl-tk): Glimmer DSL for Tk (Ruby Desktop Development GUI Library)
|
|
3155
|
+
Glimmer is a DSL engine that supports multiple DSLs (Domain Specific Languages):
|
|
3156
|
+
- [SWT](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI)
|
|
2927
3157
|
- [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps)
|
|
2928
3158
|
- [XML](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML) - Useful with [SWT Browser Widget](#browser-widget)
|
|
2929
3159
|
- [CSS](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets) - Useful with [SWT Browser Widget](#browser-widget)
|
|
@@ -3420,6 +3650,18 @@ Here is an SWT Custom Widget guide:
|
|
|
3420
3650
|
|
|
3421
3651
|
https://www.eclipse.org/articles/Article-Writing%20Your%20Own%20Widget/Writing%20Your%20Own%20Widget.htm
|
|
3422
3652
|
|
|
3653
|
+
Here is an SWT Image guide:
|
|
3654
|
+
|
|
3655
|
+
https://www.eclipse.org/articles/Article-SWT-images/graphics-resources.html
|
|
3656
|
+
|
|
3657
|
+
Here is an SWT Graphics / Canvas-Drawing guide:
|
|
3658
|
+
|
|
3659
|
+
https://www.eclipse.org/articles/Article-SWT-graphics/SWT_graphics.html
|
|
3660
|
+
|
|
3661
|
+
Here is the Nebula Project (custom widget library) homepage:
|
|
3662
|
+
|
|
3663
|
+
https://www.eclipse.org/nebula/
|
|
3664
|
+
|
|
3423
3665
|
## Samples
|
|
3424
3666
|
|
|
3425
3667
|
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`).
|
|
@@ -3612,6 +3854,41 @@ glimmer sample:run[hello_pop_up_context_menu]
|
|
|
3612
3854
|
|
|
3613
3855
|
|
|
3614
3856
|
|
|
3857
|
+
#### Hello, Custom Widget!
|
|
3858
|
+
|
|
3859
|
+
This sample demonstrates the use of a custom widget in Glimmer.
|
|
3860
|
+
|
|
3861
|
+
Code:
|
|
3862
|
+
|
|
3863
|
+
[samples/hello/hello_custom_widget.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_custom_widget.rb)
|
|
3864
|
+
|
|
3865
|
+
Run:
|
|
3866
|
+
|
|
3867
|
+
```
|
|
3868
|
+
glimmer sample:run[hello_custom_widget]
|
|
3869
|
+
```
|
|
3870
|
+
|
|
3871
|
+
|
|
3872
|
+
|
|
3873
|
+
#### Hello, Custom Shell!
|
|
3874
|
+
|
|
3875
|
+
This sample demonstrates the use of a custom shell (aka custom window) in Glimmer.
|
|
3876
|
+
|
|
3877
|
+
Code:
|
|
3878
|
+
|
|
3879
|
+
[samples/hello/hello_custom_shell.rb](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/samples/hello/hello_custom_shell.rb)
|
|
3880
|
+
|
|
3881
|
+
Run:
|
|
3882
|
+
|
|
3883
|
+
```
|
|
3884
|
+
glimmer sample:run[hello_custom_shell]
|
|
3885
|
+
```
|
|
3886
|
+
|
|
3887
|
+
|
|
3888
|
+
|
|
3889
|
+
|
|
3890
|
+
|
|
3891
|
+
|
|
3615
3892
|
### Elaborate Samples
|
|
3616
3893
|
|
|
3617
3894
|
For more elaborate samples, check the following:
|
|
@@ -3733,7 +4010,7 @@ Gladiator is a good demonstration of:
|
|
|
3733
4010
|
|
|
3734
4011
|
#### Timer
|
|
3735
4012
|
|
|
3736
|
-
[<img alt="Glimmer Timer Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/images/glimmer-timer-logo.png" height=40 /> Timer](https://github.com/AndyObtiva/glimmer-cs-timer) is a sample app demonstrating data-binding
|
|
4013
|
+
[<img alt="Glimmer Timer Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/images/glimmer-timer-logo.png" height=40 /> Timer](https://github.com/AndyObtiva/glimmer-cs-timer) is a sample app demonstrating data-binding, multi-threading, and Java (Sound) library integration in a desktop application.
|
|
3737
4014
|
|
|
3738
4015
|
[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/glimmer-timer-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-timer)
|
|
3739
4016
|
|
|
@@ -3757,6 +4034,8 @@ If you have a Glimmer app you would like referenced here, please mention in a Pu
|
|
|
3757
4034
|
|
|
3758
4035
|
## Packaging & Distribution
|
|
3759
4036
|
|
|
4037
|
+
Note: this section mostly applies to Mac and Windows. On Linux, the Glimmer [Custom Shell Gem](#custom-shell-gem) approach provides a [Gem Packaged Shell Script](#custom-shell-gem) (e.g. `calculator` command becomes available after installing the [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) gem)
|
|
4038
|
+
|
|
3760
4039
|
Glimmer simplifies the process of native-executable packaging and distribution on Mac and Windows via a single `glimmer package` command:
|
|
3761
4040
|
|
|
3762
4041
|
```
|
|
@@ -3781,7 +4060,7 @@ require 'glimmer/rake_task'
|
|
|
3781
4060
|
```
|
|
3782
4061
|
|
|
3783
4062
|
The Glimmer packaging process done in the `glimmer package` command consists of the following steps:
|
|
3784
|
-
1. Generate gemspec via
|
|
4063
|
+
1. Generate gemspec via [Juwelier](https://rubygems.org/gems/juwelier) (`glimmer package:gemspec`): Having a gemspec is required by the [`jar-dependencies`](https://github.com/mkristian/jar-dependencies) JRuby gem, used by JRuby libraries to declare JAR dependencies.
|
|
3785
4064
|
1. Lock JAR versions (`glimmer package:lock_jars`): This locks versions of JAR dependencies leveraged by the `jar-dependencies` JRuby gem, downloading them into the `./vendor` directory so they would get inside the top-level Glimmer app/gem JAR file.
|
|
3786
4065
|
1. Generate [Warbler](https://github.com/jruby/warbler) config (`glimmer package:config`): Generates initial Warbler config file (under `./config/warble.rb`) to use for generating JAR file.
|
|
3787
4066
|
1. Generate JAR file using [Warbler](https://github.com/jruby/warbler) (`glimmer package:jar`): Enables bundling a Glimmer app into a JAR file under the `./dist` directory
|
|
@@ -3939,7 +4218,7 @@ Glimmer already supports automatic (and manual) app updates via the Mac App Stor
|
|
|
3939
4218
|
## Glimmer Supporting Libraries
|
|
3940
4219
|
|
|
3941
4220
|
Here is a list of notable 3rd party gems used by Glimmer:
|
|
3942
|
-
- [
|
|
4221
|
+
- [juwelier](https://rubygems.org/gems/juwelier): generates app gems during [Glimmer Scaffolding](#scaffolding)
|
|
3943
4222
|
- [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)
|
|
3944
4223
|
- [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
|
|
3945
4224
|
- [os](https://github.com/rdp/os): provides OS detection capabilities (e.g. `OS.mac?` or `OS.windows?`) to write cross-platform code inexpensively
|