glimmer-dsl-swt 4.18.4.1 → 4.18.4.6

data/docs/reference/GLIMMER_PACKAGING_AND_DISTRIBUTION.md

@@ -0,0 +1,202 @@
+## Glimmer Packaging and Distribution
+
+Note: this section mostly applies to Mac and Windows. On Linux, you can just run `glimmer package:gem` and after installing the gem, you get an executable matching the name of the app/custom-shell-gem you are building (e.g. `calculator` command becomes available after installing the [glimmer-cs-calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) gem). On Windows, ensure system PATH includes Java bin directory like "C:\Program Files\Java\jdk1.8.0_241\bin" for javapackager command to work during packaging Glimmer applications.
+
+Note 2: Glimmer packaging has a strong dependency on JDK8 at the moment. JDK9 & JDK10 might work, but JDK11 and onward definitely won't since they dropped javapackager, which later came back as jpackage in JDK14, but it's not ready for prime time yet. Just stick to JDK8 for now, strongly supported by Oracle for the next 6 years at least.
+
+Glimmer simplifies the process of native-executable packaging and distribution on Mac and Windows via a single `glimmer package` command:
+
+```
+glimmer package
+```
+
+It works out of the box for any application scaffolded by [Glimmer Scaffolding](#scaffolding), generating all available packaging types on the current platform (e.g. `DMG`, `PKG`, `APP` on the Mac) and displaying a message indicating what pre-requisite setup tools are needed if not installed already (e.g. [Wix Toolset](https://wixtoolset.org/) to generate MSI files on Windows). If you install Wix, make sure it is on the system PATH by adding for example "C:\Program Files (x86)\WiX Toolset v3.11\bin" to the Windows Environment Variables.
+
+You may choose to generate a specific type of packaging instead by addionally passing in the `[type]` option. For example, this generates an MSI setup file on Windows:
+
+```
+glimmer package[msi]
+```
+
+- Available Mac packaging types are `dmg`, `pkg`, and `image` (image means a pure Mac `app` without a setup program). Keep in mind that the packages you produce are compatible with the same MacOS you are on or older.
+- Available Windows packaging types are `msi`, `exe`, and `image` (image means a Windows application directory without a setup program). Learn more about Windows packaging are [over here](#windows-application-packaging).
+
+Note: if you are using Glimmer manually, to make the `glimmer package` command available, you must add the following line to your application `Rakefile` (automatically done for you if you scaffold an app or gem with `glimmer scaffold[AppName]` or `glimmer scaffold:gem:customshell[GemName]`):
+
+```ruby
+require 'glimmer/rake_task'
+```
+
+The Glimmer packaging process done in the `glimmer package` command consists of the following steps:
+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.
+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.
+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.
+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
+1. Generate native executable using [javapackager](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html) (`glimmer package:native`): Enables packaging a JAR file as a DMG/PKG/APP file on Mac, MSI/EXE/APP on Windows, and DEB/RPM/APP on Linux (Glimmer does not officially support Linux with the `glimmer package` command yet, but it generates the JAR file successfully, and you could use `javapackager` manually afterwards if needed).
+
+Those steps automatically ensure generating a JAR file under the `./dist` directory using [Warbler](https://github.com/jruby/warbler), which is then used to automatically generate a DMG/MSI file (and other executables) under the `./packages/bundles` directory using `javapackager`.
+The JAR file name will match your application local directory name (e.g. `MathBowling.jar` for `~/code/MathBowling`)
+The 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)
+
+The `glimmer package` command will automatically set "mac.CFBundleIdentifier" to ="org.#{project_name}.application.#{project_name}".
+You may override by configuring as an extra argument for javapackger (e.g. Glimmer::RakeTask::Package.javapackager_extra_args = " -Bmac.CFBundleIdentifier=org.andymaleh.application.MathBowling")
+
+### Packaging Defaults
+
+Glimmer employs smart defaults in packaging.
+
+The package application name (shows up in top menu bar on the Mac) will be a human form of the app root directory name (e.g. "Math Bowling" for "MathBowling" or "math_bowling" app root directory name). However, application name and version may be specified explicitly via "-Bmac.CFBundleName" and "-Bmac.CFBundleVersion" options.
+
+Also, the package will only include these directories: app, config, db, lib, script, bin, docs, fonts, images, sounds, videos
+
+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:
+
+```
+glimmer package:config
+```
+
+This will generate `config/warble.rb`, which you may configure and then run `glimmer package` afterwards.
+
+### Packaging Configuration
+
+- Ensure you have a Ruby script under `bin` directory that launches the application, preferably matching your project directory name (e.g. `bin/math_bowling`) :
+```ruby
+require_relative '../app/my_application.rb'
+```
+- 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/)
+- Include DMG Background Icon (Optional): Simply place a .png file under `package/macosx/{HumanAppName}-background.png`
+- Include Version (Optional): Create a `VERSION` file in your application and fill it your app version on one line (e.g. `1.1.0`)
+- 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).
+- Extra args (Optional): You may optionally add the following to `Rakefile` to configure extra arguments for javapackager: `Glimmer::RakeTask::Package.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).
+
+### javapackager Extra Arguments
+
+(note: currently `Glimmer::RakeTask::Package.javapackager_extra_args` is only honored when packaging from bash, not zsh)
+
+In order to explicitly configure javapackager, Mac package attributes, or sign your Mac app to distribute on the App Store, you can follow more advanced instructions for `javapackager` here:
+- https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719
+- https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html
+- https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/self-contained-packaging.html#BCGICFDB
+- https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/self-contained-packaging.html
+- https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMacAppStore/index.html#//apple_ref/doc/uid/TP40010572-CH16-SW8
+
+The Glimmer rake task allows passing extra options to javapackager via:
+- `Glimmer::RakeTask::Package.javapackager_extra_args="..."` in your application Rakefile
+- Environment variable: `JAVAPACKAGER_EXTRA_ARGS`
+
+Example (Rakefile):
+
+```ruby
+require 'glimmer/rake_task'
+
+Glimmer::RakeTask::Package.javapackager_extra_args = '-BlicenseType="MIT" -Bmac.category="public.app-category.business" -Bmac.signing-key-developer-id-app="Andy Maleh"'
+```
+
+Note that `mac.category` defaults to "public.app-category.business", but can be overridden with one of the category UTI values mentioned here:
+
+https://developer.apple.com/library/archive/releasenotes/General/SubmittingToMacAppStore/index.html#//apple_ref/doc/uid/TP40010572-CH16-SW8
+
+Example (env var):
+
+```
+JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"' glimmer package
+```
+
+That overrides the default application display name.
+
+### Verbose Mode
+
+Pass `-v` to javapackager in `Glimmer::RakeTask::Package.javapackager_extra_args` or by running `glimmer package:native[type] -v` to learn more about further available customizations for the installer you are requesting to generate.
+
+### Windows Application Packaging
+
+Windows s two options for setup packaging:
+- `msi` (recommended): simpler packaging option. Requires [WiX Toolset](https://wixtoolset.org/) and [.NET Framework](https://dotnet.microsoft.com/download/dotnet-framework). Simply run `glimmer package[msi]` (or `glimmer package:native[msi]` if it's not your first time) and it will give you more details on the pre-requisites you need to install (e.g. [WiX Toolset](https://wixtoolset.org/) and [.NET Framework 3.5 SP1](https://dotnet.microsoft.com/download/dotnet-framework/net35-sp1)).
+- `exe`: more advanced packaging option. Requires [Inno Setup](https://jrsoftware.org/isinfo.php). Simply run `glimmer package[exe]` (or `glimmer package:native[exe]` if it's not your first time) and it will tell you what you need to install.
+
+If you just want to test out packaging into a native Windows app that is not packaged for Windows setup, just pass `image` to generate a native Windows app only.
+
+### Mac Application Distribution
+
+Recent macOS versions (starting with Catalina) have very stringent security requirements requiring all applications to be signed before running (unless the user goes to System Preferences -> Privacy -> General tab and clicks "Open Anyway" after failing to open application the first time they run it). So, to release a desktop application on the Mac, it is recommended to enroll in the [Apple Developer Program](https://developer.apple.com/programs/) to distribute on the [Mac App Store](https://developer.apple.com/distribute/) or otherwise request [app notarization from Apple](https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution) to distribute independently.
+
+Afterwards, you may add developer-id/signing-key arguments to `javapackager` via `Glimmer::RakeTask::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS` according to this webpage: https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719
+
+DMG signing key argument:
+```
+-Bmac.signing-key-developer-id-app="..."
+```
+
+PKG signing key argument:
+```
+-Bmac.signing-key-developer-id-installer="..."
+```
+
+Mac App Store signing key arguments:
+```
+-Bmac.signing-key-app="..."
+-Bmac.signing-key-pkg="..."
+```
+
+### Self Signed Certificate
+
+You may still release a signed DMG file without enrolling into the Apple Developer Program with the caveat that users will always fail in opening the app the first time, and have to go to System Preferences -> Privacy -> General tab to "Open Anyway".
+
+To do so, you may follow these steps (abbreviated version from https://developer.apple.com/library/archive/documentation/Security/Conceptual/CodeSigningGuide/Procedures/Procedures.html#//apple_ref/doc/uid/TP40005929-CH4-SW2):
+- Open Keychain Access
+- Choose Keychain Access > Certificate Assistant > Create Certificate ...
+- Enter Name (referred to below as "CertificateName")
+- Set 'Certificate Type' to 'Code Signing'
+- Create (if you alternatively override defaults, make sure to enable all capabilities)
+- Add the following option to javapackager: `-Bmac.signing-key-developer-id-app="CertificateName"` via `Glimmer::RakeTask::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS`
+
+Example:
+
+```ruby
+Glimmer::RakeTask::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
+```
+
+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.
+
+### Packaging Gotchas
+
+1. Specifying License File
+
+The javapackager documentation states that a license file may be specified with "-BlicenseFile" javapackager option. However, in order for that to work, one must specify as a source file via "-srcfiles" javapackager option.
+Keep that in mind if you are not going to rely on the default `LICENSE.txt` support.
+
+Example:
+
+```ruby
+Glimmer::RakeTask::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="ACME.txt" -BlicenseType="ACME"'
+```
+
+2. Mounted DMG Residue
+
+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."
+
+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):
+
+```
+Exec failed with code 2 command [[/usr/bin/SetFile, -c, icnC, /var/folders/4_/g1sw__tx6mjdgyh3mky7vydc0000gp/T/fxbundler4076750801763032201/images/MathBowling/.VolumeIcon.icns] in unspecified directory
+```
+
+3. Zsh (Z Shell)
+
+Currently, `Glimmer::RakeTask::Package.javapackager_extra_args` is only honored when packaging from bash, not zsh.
+
+You can get around that in zsh by running glimmer package commands with `bash -c` prefix:
+
+```
+bash -c 'glimmer package'
+```
+
+4. Java on Windows System PATH
+
+If you get any errors running Java on Windows, keep in mind that you need to have the Java binaries on the Windows System PATH environment variable:
+c:\program files\java\jre1.8.0_241
+
+The problem is Oracle seems to be adding an indirect Java path junction in later versions of their installer:
+C:\Program Files (x86)\Common Files\Oracle\Java\javapath
+
+Simply replace with the simple one above (setting the correct version number) and then reinstall JRuby to have it use Java from the right path.

data/docs/reference/GLIMMER_SAMPLES.md

@@ -0,0 +1,676 @@
+## Samples
+
+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 samples` 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`).
+
+You may run any sample via this command:
+
+```
+glimmer samples
+```
+
+This brings up the [Glimmer Meta-Sample (The Sample of Samples)](samples/elaborate/meta_sample.rb)
+
+![Glimmer Meta-Sample](/images/glimmer-meta-sample.png)
+
+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
+```
+
+### Hello Samples
+
+For hello-type simple samples, check the following.
+
+#### Hello, World!
+
+Code:
+
+[samples/hello/hello_world.rb](samples/hello/hello_world.rb)
+
+![Hello World](/images/glimmer-hello-world.png)
+
+#### Hello, Tab!
+
+Code:
+
+[samples/hello/hello_tab.rb](samples/hello/hello_tab.rb)
+
+![Hello Tab English](/images/glimmer-hello-tab-english.png)
+![Hello Tab French](/images/glimmer-hello-tab-french.png)
+
+#### Hello, Combo!
+
+This sample demonstrates combo data-binding.
+
+Code:
+
+[samples/hello/hello_combo.rb](samples/hello/hello_combo.rb)
+
+![Hello Combo](/images/glimmer-hello-combo.png)
+![Hello Combo Expanded](/images/glimmer-hello-combo-expanded.png)
+
+#### Hello, List Single Selection!
+
+This sample demonstrates list single-selection data-binding.
+
+Code:
+
+[samples/hello/hello_list_single_selection.rb](samples/hello/hello_list_single_selection.rb)
+
+![Hello List Single Selection](/images/glimmer-hello-list-single-selection.png)
+
+#### Hello, List Multi Selection!
+
+This sample demonstrates list multi-selection data-binding.
+
+Code:
+
+[samples/hello/hello_list_multi_selection.rb](samples/hello/hello_list_multi_selection.rb)
+
+![Hello List Multi Selection](/images/glimmer-hello-list-multi-selection.png)
+
+#### Hello, Computed!
+
+This sample demonstrates computed data-binding.
+
+Code:
+
+[samples/hello/hello_computed.rb](samples/hello/hello_computed.rb)
+
+![Hello Browser](/images/glimmer-hello-computed.png)
+
+#### Hello, Message Box!
+
+This sample demonstrates a `message_box` dialog.
+
+Code:
+
+[samples/hello/hello_message_box.rb](samples/hello/hello_message_box.rb)
+
+![Hello Message Box](/images/glimmer-hello-message-box.png)
+![Hello Message Box Dialog](/images/glimmer-hello-message-box-dialog.png)
+
+#### Hello, Browser!
+
+This sample demonstrates the `browser` widget.
+
+Code:
+
+[samples/hello/hello_browser.rb](samples/hello/hello_browser.rb)
+
+![Hello Browser](/images/glimmer-hello-browser.png)
+
+#### Hello, Drag and Drop!
+
+This sample demonstrates drag and drop in Glimmer.
+
+Code:
+
+[samples/hello/hello_drag_and_drop.rb](samples/hello/hello_drag_and_drop.rb)
+
+![Hello Drag and Drop](/images/glimmer-hello-drag-and-drop.gif)
+
+#### Hello, Menu Bar!
+
+This sample demonstrates menus in Glimmer, including accelerators on the Mac.
+
+Code:
+
+[samples/hello/hello_menu_bar.rb](samples/hello/hello_menu_bar.rb)
+
+![Hello Menu Bar](/images/glimmer-hello-menu-bar.png)
+
+![Hello Menu Bar File Menu](/images/glimmer-hello-menu-bar-file-menu.png)
+
+The Mac Menu includes Accelerator Keys (keyboard shortcuts).
+
+![Hello Menu Bar File Menu Mac Accelerators](/images/glimmer-hello-menu-bar-file-menu-mac-accelerators.png)
+
+![Hello Menu Bar Edit Menu](/images/glimmer-hello-menu-bar-edit-menu.png)
+
+The Mac Menu includes Accelerator Keys (keyboard shortcuts).
+
+![Hello Menu Bar Edit Menu Mac Accelerators](/images/glimmer-hello-menu-bar-edit-menu-mac-accelerators.png)
+
+![Hello Menu Bar Options Menu Disabled](/images/glimmer-hello-menu-bar-options-menu-disabled.png)
+
+![Hello Menu Bar Options Menu Select One](/images/glimmer-hello-menu-bar-options-menu-select-one.png)
+
+![Hello Menu Bar Options Menu Select Multiple](/images/glimmer-hello-menu-bar-options-menu-select-multiple.png)
+
+![Hello Menu Bar Format Menu Background Color](/images/glimmer-hello-menu-bar-format-menu-background-color.png)
+
+![Hello Menu Bar Format Menu Foreground Color](/images/glimmer-hello-menu-bar-format-menu-foreground-color.png)
+
+![Hello Menu Bar View Menu](/images/glimmer-hello-menu-bar-view-menu.png)
+
+![Hello Menu Bar View Small](/images/glimmer-hello-menu-bar-view-small.png)
+
+![Hello Menu Bar View Large](/images/glimmer-hello-menu-bar-view-large.png)
+
+![Hello Menu Bar Help Menu](/images/glimmer-hello-menu-bar-help-menu.png)
+
+The Mac Menu includes Accelerator Keys (keyboard shortcuts) and Mac built-in Search.
+
+![Hello Menu Bar Help Menu Mac Accelerators](/images/glimmer-hello-menu-bar-help-menu-mac-accelerators.png)
+
+#### Hello, Pop Up Context Menu!
+
+This sample demonstrates pop up context menus in Glimmer.
+
+Code:
+
+[samples/hello/hello_pop_up_context_menu.rb](samples/hello/hello_pop_up_context_menu.rb)
+
+![Hello Pop Up Context Menu](/images/glimmer-hello-pop-up-context-menu.png)
+![Hello Pop Up Context Menu Popped Up](/images/glimmer-hello-pop-up-context-menu-popped-up.png)
+
+#### Hello, Custom Widget!
+
+This sample demonstrates the use of a custom widget in Glimmer.
+
+Code:
+
+[samples/hello/hello_custom_widget.rb](samples/hello/hello_custom_widget.rb)
+
+![Hello Custom Widget](/images/glimmer-hello-custom-widget.gif)
+
+#### Hello, Custom Shell!
+
+This sample demonstrates the use of a custom shell (aka custom window) in Glimmer.
+
+Code:
+
+[samples/hello/hello_custom_shell.rb](samples/hello/hello_custom_shell.rb)
+
+![Hello Custom Shell](/images/glimmer-hello-custom-shell.png)
+![Hello Custom Shell Email1](/images/glimmer-hello-custom-shell-email1.png)
+![Hello Custom Shell Email2](/images/glimmer-hello-custom-shell-email2.png)
+![Hello Custom Shell Email3](/images/glimmer-hello-custom-shell-email3.png)
+
+#### Hello, Sash Form!
+
+This sample demonstrates the use of a `sash_form` in Glimmer.
+
+Code:
+
+[samples/hello/hello_sash_form.rb](samples/hello/hello_sash_form.rb)
+
+Hello, Sash Form! Horizontal Orientation
+
+![Hello Sash Form](/images/glimmer-hello-sash-form.png)
+
+Hello, Sash Form! Resized
+
+![Hello Sash Form Resized](/images/glimmer-hello-sash-form-resized.png)
+
+Hello, Sash Form! Sash Width Changed
+
+![Hello Sash Form Sash Width Changed](/images/glimmer-hello-sash-form-sash-width-changed.png)
+
+Hello, Sash Form! Vertical Orientation
+
+![Hello Sash Form Vertical](/images/glimmer-hello-sash-form-vertical.png)
+
+Hello, Sash Form! Green Label Maximized
+
+![Hello Sash Form Green Maximized](/images/glimmer-hello-sash-form-green-maximized.png)
+
+Hello, Sash Form! Red Label Maximized
+
+![Hello Sash Form Red Maximized](/images/glimmer-hello-sash-form-red-maximized.png)
+
+#### Hello, Styled Text!
+
+This sample demonstrates the use of a `styled_text` in Glimmer.
+
+Code:
+
+[samples/hello/hello_styled_text.rb](samples/hello/hello_styled_text.rb)
+
+Hello, Styled Text!
+
+![Hello Styled Text](/images/glimmer-hello-styled-text.png)
+
+#### Hello, Expand Bar!
+
+This sample demonstrates the use of a `expand_bar` and `expand_item` in Glimmer.
+
+Code:
+
+[samples/hello/hello_expand_bar.rb](samples/hello/hello_expand_bar.rb)
+
+Hello, Expand Bar! All Expanded
+
+![Hello Expand Bar All Expanded](/images/glimmer-hello-expand-bar-all-expanded.png)
+
+Hello, Expand Bar! Productivity Expanded
+
+![Hello Expand Bar Productivity Expanded](/images/glimmer-hello-expand-bar-productivity-expanded.png)
+
+Hello, Expand Bar! Tools Expanded
+
+![Hello Expand Bar Tools Expanded](/images/glimmer-hello-expand-bar-tools-expanded.png)
+
+Hello, Expand Bar! Reading Expanded
+
+![Hello Expand Bar Reading Expanded](/images/glimmer-hello-expand-bar-reading-expanded.png)
+
+#### Hello, Radio!
+
+This sample demonstrates the use of a `radio` (aka `button(:radio)`) in Glimmer.
+
+Code:
+
+[samples/hello/hello_radio.rb](samples/hello/hello_radio.rb)
+
+Hello, Radio!
+
+![Hello Radio](/images/glimmer-hello-radio.png)
+
+#### Hello, Radio Group!
+
+This sample demonstrates the use of a `radio_group` in Glimmer, which provides terser syntax for representing multiple radio buttons by relying on data-binding to automatically spawn the `radio` widgets based on available options on the model.
+
+Code:
+
+[samples/hello/hello_radio_group.rb](samples/hello/hello_radio_group.rb)
+
+Hello, Radio Group!
+
+![Hello Radio Group](/images/glimmer-hello-radio-group.png)
+
+#### Hello, Group!
+
+This sample demonstrates the use of a `group` in Glimmer (not to be confused with the logical radio group custom widget, this is just an alternative to `composite` that provides a border around content).
+
+Code:
+
+[samples/hello/hello_group.rb](samples/hello/hello_group.rb)
+
+Hello, Group!
+
+![Hello Group](/images/glimmer-hello-group.png)
+
+#### Hello, Checkbox!
+
+This sample demonstrates the use of a `checkbox` (aka `check` or `button(:check)`) in Glimmer.
+
+Code:
+
+[samples/hello/hello_checkbox.rb](samples/hello/hello_checkbox.rb)
+
+Hello, Checkbox!
+
+![Hello Checkbox](/images/glimmer-hello-checkbox.png)
+
+#### Hello, Checkbox Group!
+
+This sample demonstrates the use of a `checkbox_group` (aka `check_group`) in Glimmer, which provides terser syntax for representing multiple checkbox buttons (`button(:check)`) by relying on data-binding to automatically spawn the `checkbox` widgets (`button(:check)`) based on available options on the model.
+
+Code:
+
+[samples/hello/hello_checkbox_group.rb](samples/hello/hello_checkbox_group.rb)
+
+Hello, Checkbox Group!
+
+![Hello Checkbox Group](/images/glimmer-hello-checkbox-group.png)
+
+#### Hello, Directory Dialog!
+
+This sample demonstrates the use of a `directory_dialog` in Glimmer.
+
+Code:
+
+[samples/hello/hello_directory_dialog.rb](samples/hello/hello_directory_dialog.rb)
+
+Hello, Directory Dialog!
+
+![Hello Directory Dialog](/images/glimmer-hello-directory-dialog.png)
+
+Hello, Directory Dialog! Browse...
+
+![Hello Directory Dialog](/images/glimmer-hello-directory-dialog-browse.png)
+
+Hello, Directory Dialog! Selected Directory
+
+![Hello Directory Dialog](/images/glimmer-hello-directory-dialog-selected-directory.png)
+
+#### Hello, File Dialog!
+
+This sample demonstrates the use of a `file_dialog` in Glimmer.
+
+Code:
+
+[samples/hello/hello_file_dialog.rb](samples/hello/hello_file_dialog.rb)
+
+Hello, File Dialog!
+
+![Hello File Dialog](/images/glimmer-hello-file-dialog.png)
+
+Hello, File Dialog! Browse...
+
+![Hello File Dialog](/images/glimmer-hello-file-dialog-browse.png)
+
+Hello, File Dialog! Selected File
+
+![Hello File Dialog](/images/glimmer-hello-file-dialog-selected-file.png)
+
+#### Hello, Date Time!
+
+This sample demonstrates the use of [date_time](#datetime) widget keywords in Glimmer: `date`, `date_drop_down`, `time`, and `calendar`
+
+Code:
+
+[samples/hello/hello_date_time.rb](samples/hello/hello_date_time.rb)
+
+Hello, Date Time!
+
+![Hello Date Time](/images/glimmer-hello-date-time.png)
+
+#### Hello, Spinner!
+
+This sample demonstrates the use of `spinner` widget in Glimmer
+
+Code:
+
+[samples/hello/hello_spinner.rb](samples/hello/hello_spinner.rb)
+
+Hello, Spinner!
+
+![Hello Spinner](/images/glimmer-hello-spinner.png)
+
+#### Hello, Table!
+
+This sample demonstrates the use of [table](#table) widget in Glimmer, including data-binding, multi-type editing, sorting, and filtering.
+
+Code:
+
+[samples/hello/hello_table.rb](samples/hello/hello_table.rb)
+
+Hello, Table!
+
+![Hello Table](/images/glimmer-hello-table.png)
+
+Hello, Table! Editing Game Date
+
+![Hello Table](/images/glimmer-hello-table-editing-game-date.png)
+
+Hello, Table! Editing Game Time
+
+![Hello Table](/images/glimmer-hello-table-editing-game-time.png)
+
+Hello, Table! Editing Home Team
+
+![Hello Table](/images/glimmer-hello-table-editing-home-team.png)
+
+Hello, Table! Sorted Game Date Ascending
+
+![Hello Table](/images/glimmer-hello-table-sorted-game-date-ascending.png)
+
+Hello, Table! Sorted Game Date Descending
+
+![Hello Table](/images/glimmer-hello-table-sorted-game-date-descending.png)
+
+Hello, Table! Playoff Type Combo
+
+![Hello Table](/images/glimmer-hello-table-playoff-type-combo.png)
+
+Hello, Table! Playoff Type Changed
+
+![Hello Table](/images/glimmer-hello-table-playoff-type-changed.png)
+
+Hello, Table! Game Booked
+
+![Hello Table](/images/glimmer-hello-table-game-booked.png)
+
+Hello, Table! Context Menu
+
+![Hello Table](/images/glimmer-hello-table-context-menu.png)
+
+#### Hello, Button!
+
+This sample demonstrates the use of the `button` widget in Glimmer, including data-binding and click event triggering via `on_widget_selected`.
+
+Code:
+
+[samples/hello/hello_button.rb](samples/hello/hello_button.rb)
+
+Hello, Button!
+
+![Hello Button](/images/glimmer-hello-button.png)
+
+Hello, Button! Incremented 7 times!
+
+![Hello Button Incremented](/images/glimmer-hello-button-incremented.png)
+
+#### Hello, Link!
+
+This sample demonstrates the use of the `link` widget in Glimmer, including identifying which link was clicked and performing an action (displaying help) based on its location.
+
+Code:
+
+[samples/hello/hello_link.rb](samples/hello/hello_link.rb)
+
+Hello, Link!
+
+![Hello Link](/images/glimmer-hello-link.png)
+
+Hello, Link! Clicked
+
+![Hello Link Clicked](/images/glimmer-hello-link-clicked.png)
+
+#### Hello, Dialog!
+
+This sample demonstrates the use of the `dialog` widget in Glimmer, which provides a modal `shell` that blocks shells beneath it until closed. And unlike `message_box`, it can contain arbitrary widgets (not just a message).
+
+Code:
+
+[samples/hello/hello_dialog.rb](samples/hello/hello_dialog.rb)
+
+Hello, Dialog!
+
+![Hello Dialog](/images/glimmer-hello-dialog.png)
+
+Hello, Dialog! Open Dialog
+
+![Hello Dialog Open Dialog](/images/glimmer-hello-dialog-open-dialog.png)
+
+#### Hello, Code Text!
+
+This sample demonstrates the Glimmer Built-In [Code Text Custom Widget](#code-text-custom-widget).
+
+Code:
+
+[samples/hello/hello_code_text.rb](samples/hello/hello_code_text.rb)
+
+Hello, Code Text! Ruby Language / Glimmer Theme / Show Line Numbers (default width of 4)
+
+![Hello Code Text Ruby](/images/glimmer-hello-code-text-ruby.png)
+
+Hello, Code Text! JavaScript Language / Pastie Theme / Show Line Numbers (custom width of 2)
+
+![Hello Code Text JavaScript](/images/glimmer-hello-code-text-javascript.png)
+
+Hello, Code Text! HTML Language / GitHub Theme / No Line Numbers
+
+![Hello Code Text HTML](/images/glimmer-hello-code-text-html.png)
+
+#### Hello, Canvas!
+
+This sample demonstrates the use of the `canvas` widget and [Shape DSL](#canvas-shape-dsl) in Glimmer.
+
+Code:
+
+[samples/hello/hello_canvas.rb](samples/hello/hello_canvas.rb)
+
+Hello, Canvas!
+
+![Hello Canvas](/images/glimmer-hello-canvas.png)
+
+#### Hello, Canvas Animation!
+
+This sample demonstrates the use of the `canvas` widget and [Animation DSL](#canvas-animation-dsl) in Glimmer.
+
+Code:
+
+[samples/hello/hello_canvas_animation.rb](samples/hello/hello_canvas_animation.rb)
+
+Hello, Canvas Animation!
+
+![Hello Canvas Animation](/images/glimmer-hello-canvas-animation.png)
+
+Hello, Canvas Animation Another Frame!
+
+![Hello Canvas Animation Frame 2](/images/glimmer-hello-canvas-animation-frame2.png)
+
+#### Hello, Canvas Transform!
+
+This sample demonstrates the use of the `transform` keyword as part of the [Transform DSL](#canvas-transform-dsl) within the [Shape DSL](#canvas-shape-dsl).
+
+Code:
+
+[samples/hello/hello_canvas_transform.rb](samples/hello/hello_canvas_transform.rb)
+
+Hello, Canvas Transform!
+
+![Hello Canvas Transform](/images/glimmer-hello-canvas-transform.png)
+
+
+### Elaborate Samples
+
+For more elaborate samples, check the following:
+
+#### User Profile
+
+This sample was used in the [DZone Article about Glimmer](https://dzone.com/articles/an-introduction-glimmer), demonstrating Glimmer widgets in general.
+
+Please note that the code has changed since that article was written (the GUI DSL has been improved/simplified), so use the code sample mentioned here instead as the correct version.
+
+Code:
+
+[samples/elaborate/user_profile.rb](samples/elaborate/user_profile.rb)
+
+![User Profile](/images/glimmer-user-profile.png)
+
+#### Login
+
+This sample demonstrates basic data-binding, password and text fields, and field enablement data-binding.
+
+Code:
+
+[samples/elaborate/login.rb](samples/elaborate/login.rb)
+
+![Login](/images/glimmer-login.png)
+![Login Filled In](/images/glimmer-login-filled-in.png)
+![Login Logged In](/images/glimmer-login-logged-in.png)
+
+#### Tic Tac Toe
+
+This sample demonstrates a full MVC application, including GUI layout, text and enablement data-binding, and test-driven development (has [specs](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/spec/samples/elaborate/tic_tac_toe/board_spec.rb)).
+
+Code:
+
+(Please note that on some Linux instances where the display x-axis is set to double-scale, you need to set the `shell` `minimum_size` to `300, 178` instead of `150, 178`)
+
+[samples/elaborate/tic_tac_toe.rb](samples/elaborate/tic_tac_toe.rb)
+
+![Tic Tac Toe](/images/glimmer-tic-tac-toe.png)
+![Tic Tac Toe In Progress](/images/glimmer-tic-tac-toe-in-progress.png)
+![Tic Tac Toe Game Over](/images/glimmer-tic-tac-toe-game-over.png)
+
+#### Contact Manager
+
+This sample demonstrates table data-binding, sorting, filtering, GUI layout, MVP pattern, and test-driven development (has [specs](https://github.com/AndyObtiva/glimmer-dsl-swt/blob/master/spec/samples/elaborate/contact_manager/contact_manager_presenter_spec.rb)).
+
+Code:
+
+[samples/elaborate/contact_manager.rb](samples/elaborate/contact_manager.rb)
+
+Contact Manager
+
+![Contact Manager](/images/glimmer-contact-manager.png)
+
+Contact Manager - Find
+
+![Contact Manager](/images/glimmer-contact-manager-find.png)
+
+Contact Manager - Edit Started
+
+![Contact Manager](/images/glimmer-contact-manager-edit-started.png)
+
+Contact Manager - Edit In Progress
+
+![Contact Manager](/images/glimmer-contact-manager-edit-in-progress.png)
+
+Contact Manager - Edit Done
+
+![Contact Manager](/images/glimmer-contact-manager-edit-done.png)
+
+#### Glimmer Tetris
+
+This sample demonstrates how to build an interactive animated game with MVC architecture, custom-shell/custom-widgets, multi-threading, asynchronous programming, data-binding, canvas shape graphic decorations, canvas shape icon image generation, and keyboard events/shortcuts.
+
+Note that it works optimally on the Mac. It is very new, so it has not been optimized for Windows and Linux yet given their minor differences from the Mac.
+
+Code:
+
+[samples/elaborate/tetris.rb](samples/elaborate/tetris.rb)
+
+![Tetris Icon](/images/glimmer-tetris-icon.png)
+
+![Tetris](/images/glimmer-tetris.png)
+
+![Tetris Game Over](/images/glimmer-tetris-game-over.png)
+
+![Tetris Game Over](/images/glimmer-tetris-game-over-sorted-by-score.png)
+
+![Tetris High Scores](/images/glimmer-tetris-high-score-dialog.png)
+
+![Tetris Game Menu](/images/glimmer-tetris-game-menu.png)
+
+![Tetris View Menu](/images/glimmer-tetris-view-menu.png)
+
+![Tetris Options Menu](/images/glimmer-tetris-options-menu.png)
+
+![Tetris Help Menu](/images/glimmer-tetris-help-menu.png)
+
+### External Samples
+
+#### Glimmer Calculator
+
+[<img alt="Glimmer Calculator Icon" src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/master/glimmer-cs-calculator-icon.png" height=40 /> Glimmer Calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) is a basic calculator sample app demonstrating data-binding and TDD (test-driven-development) with Glimmer following the MVP pattern (Model-View-Presenter).
+
+[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-calculator/master/glimmer-cs-calculator-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-calculator)
+
+#### Gladiator
+
+[<img src='https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/master/images/glimmer-cs-gladiator-logo.svg' height=40 /> Gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator) (short for Glimmer Editor) is a Glimmer sample project under on-going development.
+You may check it out to learn how to build a Glimmer Custom Shell gem.
+
+[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-gladiator/master/images/glimmer-gladiator.png" />](https://github.com/AndyObtiva/glimmer-cs-gladiator)
+
+Gladiator is a good demonstration of:
+- MVP Pattern
+- Tree data-binding
+- List data-binding
+- Text selection data-binding
+- Tabs
+- Context menus
+- Custom Shell
+- Custom widget
+
+#### Timer
+
+[<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 JSound (Java Sound) library integration in a desktop application.
+
+[<img src="https://raw.githubusercontent.com/AndyObtiva/glimmer-cs-timer/master/glimmer-timer-screenshot.png" />](https://github.com/AndyObtiva/glimmer-cs-timer)
+
+## License
+
+[MIT](LICENSE.txt)
+
+Copyright (c) 2007-2021 - Andy Maleh.