README.md in glimmer-dsl-swt-4.18.3.1 vs README.md in glimmer-dsl-swt-4.18.3.2
- old
+ new
@@ -1,6 +1,6 @@
-# [<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.18.3.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.18.3.2
## JRuby Desktop Development GUI Framework
[](http://badge.fury.io/rb/glimmer-dsl-swt)
[](https://travis-ci.com/github/AndyObtiva/glimmer-dsl-swt)
[](https://coveralls.io/github/AndyObtiva/glimmer-dsl-swt?branch=master)
[](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-swt/maintainability)
@@ -239,10 +239,11 @@
- [Tic Tac Toe](#tic-tac-toe)
- [Contact Manager](#contact-manager)
- [Desktop Apps Built with Glimmer DSL for SWT](#desktop-apps-built-with-glimmer-dsl-for-swt)
- [Table of contents](#table-of-contents)
- [Background](#background)
+ - [Software Architecture](#software-architecture)
- [Platform Support](#platform-support)
- [Pre-requisites](#pre-requisites)
- [Setup](#setup)
- [Option 1: Direct Install](#option-1-direct-install)
- [Option 2: Bundler](#option-2-bundler)
@@ -405,10 +406,42 @@
## Background
[Ruby](https://www.ruby-lang.org) is a dynamically-typed object-oriented language, which provides great productivity gains due to its powerful expressive syntax and dynamic nature. While it is proven by the [Ruby](https://www.ruby-lang.org) on Rails framework for web development, it currently lacks a robust platform-independent framework for building desktop applications. Given that Java libraries can now be utilized in Ruby code through JRuby, Eclipse technologies, such as [SWT](https://www.eclipse.org/swt/), JFace, and RCP can help fill the gap of desktop application development with Ruby.
+## Software Architecture
+
+There are several requirements for building enterprise-level/consumer-level desktop GUI applications:
+- Cross-Platform Support (Mac, Windows, Linux) without compilation/recompilation
+- OS Native Look & Feel
+- High Performance
+- Productivity
+- Maintainability
+- Extensibility
+- Native Executable Packaging
+- Multi-Threading / Parallel Programming
+- Arbitrary Graphics Painting
+- Audio Support
+
+Glimmer provides cross-platform support that does not require Ruby compilation (like Tk does), thanks to JRuby, a JVM (Java Virtual Machine) faster OS-threaded version of Ruby.
+
+Glimmer leverages SWT (Standard Widget Toolkit), which provides cross-platform widgets that automatically use the native GUI libraries under each operating system, such as Win32 on Windows, Cocoa on Mac, and GTK on Linux.
+
+Furthermore, what is special about SWT regarding "High Performance" is that it does all the GUI painting natively outside of Java, thus producing GUI that runs at maximum performance even in Ruby. As such, you do not need to worry about Ruby dynamic typing getting in the way of GUI performance. It has ZERO effect on it and since SWT supports making asynchronous calls for GUI rendering, you could avoid blocking the GUI completely with any computations happening in Ruby no matter how complex, thus never affecting the responsiveness of GUI of applications while taking full advantage of the productivity benefits of Ruby dynamic typing.
+
+Glimmer takes this further by providing a very programmer friendly DSL (Domain Specific Language) that visually maps lightweight Ruby syntax to the containment hierarchy of GUI widgets (meaning Ruby blocks nested within each other map to GUI widgets nested within each other). This provides maximum productivity and maintainability.
+
+Extensibility has never been simpler in desktop GUI application development than with Glimmer, which provides the ability to support any new custom keywords through custom widgets and custom shells (windows). Basically, you map a keyword by declaring a view class matching its name by convention with a GUI body that simply consists of reusable Glimmer GUI syntax. They can be passive views or smart views with additional logic. This provides the ultimate realization of Object Oriented Programming and micro-level MVC pattern.
+
+Thanks to Java and JRuby, Glimmer apps can be packaged as cross-platform JAR files (with JRuby Warbler) and native executables (with Java Packager) as Mac APP/DMG/PACKAGE or Windows EXE/MSI.
+
+The Java Virtual Machine already supports OS-native threads, so Glimmer apps can have multiple things running in parallel with no problem.
+
+SWT supports Canvas graphics drawing, and Glimmer takes that further by provding a Canvas Shape/Transform/Animation DSL, making it very simple to decorate any existing widgets or add new widgets with a completely custom look and feel if needed for branding or entertainment (gaming) purposes.
+
+Audio is supported via the Java Sound library in a cross-platform approach and video is supported via a Glimmer custom widget, so any Glimmer app can be enhanced with audio and video where needed.
+
## Platform Support
Glimmer runs on the following platforms:
- Mac
- Windows
@@ -458,11 +491,11 @@
jgem install glimmer-dsl-swt
```
Or this command if you want a specific version:
```
-jgem install glimmer-dsl-swt -v 4.18.3.1
+jgem install glimmer-dsl-swt -v 4.18.3.2
```
`jgem` is JRuby's version of `gem` command.
@@ -478,11 +511,11 @@
### Option 2: Bundler
(Use for Manual App Creation)
Add the following to `Gemfile`:
```
-gem 'glimmer-dsl-swt', '~> 4.18.3.1
+gem 'glimmer-dsl-swt', '~> 4.18.3.2
'
```
And, then run:
```
@@ -537,11 +570,11 @@
### Advanced Usage
Below are the full usage instructions that come up when running `glimmer` without args.
```
-Glimmer (JRuby Desktop Development GUI Framework) - JRuby Gem: glimmer-dsl-swt v4.18.3.1
+Glimmer (JRuby Desktop Development GUI Framework) - JRuby Gem: glimmer-dsl-swt v4.18.3.2
Usage: glimmer [--bundler] [--pd] [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
@@ -813,11 +846,11 @@
glimmer run
```
#### Custom Shell
-To scaffold a Glimmer custom shell (full window view) for an existing Glimmer app, run the following command:
+To scaffold a Glimmer [custom shell](#custom-shells) (full window view) for an existing Glimmer app, run the following command:
```
glimmer scaffold:customshell[name]
```
@@ -827,11 +860,11 @@
glimmer scaffold:cs[name]
```
#### Custom Widget
-To scaffold a Glimmer custom widget (part of a view) for an existing Glimmer app, run the following command:
+To scaffold a Glimmer [custom widget](#custom-widgets) (part of a view) for an existing Glimmer app, run the following command:
```
glimmer scaffold:customwidget[name]
```
@@ -841,11 +874,11 @@
glimmer scaffold:cw[name]
```
#### Custom Shell Gem
-Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
+Custom shell gems are self-contained Glimmer apps as well as reusable [custom shells](#custom-shells).
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.
Unlike scaffolded Glimmer apps, custom shell gem content lives under the `lib` directory (not `app`).
They can be packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem.
Of course, you can just build a Ruby gem and disregard native executable packaging if you do not need it.
@@ -876,11 +909,11 @@
- [glimmer-cs-gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator): Gladiator (Glimmer Editor)
- [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator): Glimmer Calculator
#### Custom Widget Gem
-To scaffold a Glimmer custom widget gem (part of a view distributed as a Ruby gem), run the following command:
+To scaffold a Glimmer [custom widget](#custom-widgets) gem (part of a view distributed as a Ruby gem), run the following command:
```
glimmer scaffold:gem:customwidget[name,namespace]
```
@@ -902,11 +935,11 @@
- [glimmer-cw-video](https://github.com/AndyObtiva/glimmer-cw-video): Video Widget
- [glimmer-cw-cdatetime-nebula](https://github.com/AndyObtiva/glimmer-cw-cdatetime-nebula): Nebula CDateTime Widget
### Gem Listing
-The `glimmer` command comes with tasks for listing Glimmer related gems to make it easy to find Glimmer Custom Shells, Custom Widgets, and DSLs published by others in the Glimmer community on [rubygems.org](http://www.rubygems.org).
+The `glimmer` command comes with tasks for listing Glimmer related gems to make it easy to find Glimmer [Custom Shells](#custom-shells), [Custom Widgets](#custom-widgets), and DSLs published by others in the Glimmer community on [rubygems.org](http://www.rubygems.org).
#### Listing Custom Shell Gems
The following command lists available Glimmer [Custom Shell Gems](#custom-shell-gem) (prefixed with "glimmer-cs-" by scaffolding convention) created by the the Glimmer community and published on [rubygems.org](http://www.rubygems.org):
@@ -1018,11 +1051,11 @@
Name Gem Version Author Description
Css glimmer-dsl-css 1.1.0 AndyMaleh Glimmer DSL for CSS
Opal glimmer-dsl-opal 0.10.2 AndyMaleh Glimmer DSL for Opal
- Swt glimmer-dsl-swt 4.18.3.1
+ Swt glimmer-dsl-swt 4.18.3.2
AndyMaleh Glimmer DSL for SWT
Tk glimmer-dsl-tk 0.0.6 AndyMaleh Glimmer DSL for Tk
Xml glimmer-dsl-xml 1.1.0 AndyMaleh Glimmer DSL for XML
```
@@ -1096,13 +1129,16 @@
bin/girb
```
Watch out for hands-on examples in this README indicated by "you may copy/paste in [`girb`](#girb-glimmer-irb-command)"
-Keep in mind that all samples live under [https://github.com/AndyObtiva/glimmer-dsl-swt](https://github.com/AndyObtiva/glimmer-dsl-swt)
+Keep in mind that all samples live under [https://github.com/AndyObtiva/glimmer-dsl-swt/samples](https://github.com/AndyObtiva/glimmer-dsl-swt/samples)
-If you need a more GUI interactive option to experiement with Glimmer GUI DSL Syntax, you may try the ["Ugliest Editor Ever"](https://github.com/AndyObtiva/glimmer-cs-gladiator) or just build your own using the [Glimmer DSL for SWT Ruby Gem](https://rubygems.org/gems/glimmer-dsl-swt).
+If you need a more GUI interactive option to experiement with Glimmer GUI DSL Syntax, you may try:
+- [Glimmer Meta-Sample (The Sample of Samples)](#samples): allows launching Glimmer samples and viewing/editing code to learn/experiment too.
+- ["Ugliest Editor Ever"](https://github.com/AndyObtiva/glimmer-cs-gladiator)
+- Just build your own GUI editor using the [Glimmer DSL for SWT Ruby Gem](https://rubygems.org/gems/glimmer-dsl-swt).
## Glimmer GUI DSL Syntax
Glimmer's core is a GUI DSL with a lightweight visual syntax that makes it easy to visualize the nesting of widgets in the GUI hierarchy tree.
@@ -3494,10 +3530,12 @@
}
}
}.open
```
+If you use a Custom Shell as the top-level app shell, you may invoke the class method `::launch` instead to avoid building an app class yourself or including Glimmer into the top-level namespace (e.g. `Tetris.launch` instead of `include Glimmer; tetris.open`)
+
You may check out [Hello, Custom Shell!](#hello-custom-shell) for another example.
### Drag and Drop
Glimmer s Drag and Drop support, thanks to [SWT](https://www.eclipse.org/swt/) and Glimmer's lightweight [DSL syntax](#glimmer-dsl-syntax).
@@ -4145,12 +4183,22 @@
end
```
### log_excluded_keywords
+(default = false)
+
This just tells Glimmer whether to log excluded keywords or not (at the debug level). It is off by default.
+### auto_sync_exec
+
+(default = false)
+
+This automatically uses sync_exec on GUI calls from threads other than the main GUI thread instead of requiring users to manually use sync_exec. Default value to false.
+
+Keep in mind the caveat that it would force redraws on every minor changein the models instead of applying large scope changes all together, thus causing too much drawing/stutter in the GUI. As such, this is a good fit for simpler GUIs, not ones used with highly sophisticated 2D graphics. It may be mitigated in the future by introducing the idea of large-scale observation events that wrap around smaller events. Until then, keep the caveat in mind or just use sync_exec manually as usually done with Java SWT apps.
+
## Glimmer Style Guide
- Widgets are declared with underscored lowercase versions of their SWT names minus the SWT package name.
- Widget declarations may optionally have arguments and be followed by a block (to contain properties and content)
- Widget blocks are always declared with curly braces
@@ -4225,11 +4273,11 @@
You may edit the code of any sample before launching it by clicking on the "Launch" button. This helps you learn by experimenting with Glimmer GUI DSL syntax. To go back to original code, simply hit the "Reset" button.
Note that if you fail to run any sample through the Glimmer Meta-Sample for whatever reason, you could always run directly by cloning the project, running `bundle`, and then this command (drop the "bin" if you install the glimmer-dsl-swt gem instead):
```ruby
-bin/glimmer samples/hello/hello_canvas_transform.rb
+bin/glimmer samples/hello/hello_canvas_transform.rb
```
### Hello Samples
For hello-type simple samples, check the following.
@@ -4809,9 +4857,19 @@
[samples/elaborate/tetris.rb](samples/elaborate/tetris.rb)
+
+
+
+
+
+
+
+
+
+
### External Samples
#### Glimmer Calculator