README.md in glimmer-dsl-swt-4.17.1.1 vs README.md in glimmer-dsl-swt-4.17.2.0

- 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.17.1.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.2.0 ## JRuby Desktop Development GUI Library [![Gem Version](https://badge.fury.io/rb/glimmer-dsl-swt.svg)](http://badge.fury.io/rb/glimmer-dsl-swt) [![Travis CI](https://travis-ci.com/AndyObtiva/glimmer-dsl-swt.svg?branch=master)](https://travis-ci.com/github/AndyObtiva/glimmer-dsl-swt) [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/glimmer-dsl-swt/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/glimmer-dsl-swt?branch=master) [![Maintainability](https://api.codeclimate.com/v1/badges/aaf1cba142dd351f84bd/maintainability)](https://codeclimate.com/github/AndyObtiva/glimmer-dsl-swt/maintainability) @@ -414,21 +414,23 @@ If you intend to build a Glimmer app from scratch with [scaffolding](#scaffolding), pick Option 1 ([Direct Install](#option-1-direct-install)) as well. Otherwise, Option 2 ([Bundler](#option-2-bundler)) can be followed in rare cases where you want to build an app without [scaffolding](#scaffolding). +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 go back in the list of [Glimmer Releases](https://rubygems.org/gems/glimmer-dsl-swt/versions) until you find one that works for you. + ### Option 1: Direct Install (Use for [Scaffolding](#scaffolding)) Run this command to install directly: ``` jgem install glimmer-dsl-swt ``` Or this command if you want a specific version: ``` -jgem install glimmer-dsl-swt -v 4.17.1.1 +jgem install glimmer-dsl-swt -v 4.17.2.0 ``` 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. `jgem` is JRuby's version of `gem` command. @@ -472,10 +474,12 @@ On Windows, it simply lists the available Glimmer tasks at the end (courtsey of [rake](https://github.com/ruby/rake)). If you are new to Glimmer, you may read the Basic Usage section and skip the rest until you have gone through [Girb (Glimmer irb) Command](#girb-glimmer-irb-command), [Glimmer GUI DSL Syntax](#glimmer-gui-dsl-syntax), and [Samples](#samples). +Note: If you encounter an issue running the `glimmer` command, run `bundle exec glimmer` instead. + ### Basic Usage ``` glimmer application.rb ``` @@ -499,11 +503,11 @@ ### Advanced Usage Below are the full usage instructions that come up when running `glimmer` without args. ``` -Glimmer (Ruby Desktop Development GUI Library) - JRuby Gem: glimmer-dsl-swt v4.17.1.1 +Glimmer (Ruby Desktop Development GUI Library) - JRuby Gem: glimmer-dsl-swt v4.17.2.0 Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...] Runs Glimmer applications and tasks. @@ -612,11 +616,11 @@ This will run the hello_tab sample and output its code: ``` $ glimmer sample:run[hello_tab] -# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.1.1/samples/hello/hello_tab.rb +# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.2.0/samples/hello/hello_tab.rb class HelloTab include Glimmer def launch shell { @@ -657,11 +661,11 @@ Example: ``` $ glimmer sample:code[tic_tac_toe] -# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.1.1/samples/elaborate/tic_tac_toe.rb +# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.2.0/samples/elaborate/tic_tac_toe.rb require_relative "tic_tac_toe/board" class TicTacToe include Glimmer @@ -718,11 +722,11 @@ TicTacToe.new.open # # # -# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.1.1/samples/elaborate/tic_tac_toe/cell.rb +# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.2.0/samples/elaborate/tic_tac_toe/cell.rb class TicTacToe class Cell EMPTY = "" attr_accessor :sign, :empty @@ -751,11 +755,11 @@ end # # # -# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.1.1/samples/elaborate/tic_tac_toe/board.rb +# /Users/User/.rvm/gems/jruby-9.2.13.0@glimmerapp/gems/glimmer-dsl-swt-4.17.2.0/samples/elaborate/tic_tac_toe/board.rb require_relative 'cell' class TicTacToe class Board @@ -1137,10 +1141,32 @@ Video glimmer-cw-video 1.0.0 Andy Maleh Glimmer Custom Widget - Video ``` +Example: + +Check all custom widgets for Glimmer. + +``` +glimmer list:gems:cw +``` + +Output: + +``` + + Glimmer Custom Widget Gems at rubygems.org: + + Name Gem Version Author Description + + Browser (Chromium) glimmer-cw-browser-chromium 1.0.0 Andy Maleh Chromium Browser - Glimmer Custom Widget + Cdatetime (Nebula) glimmer-cw-cdatetime-nebula 1.5.0.0.1 Andy Maleh Nebula CDateTime Widget - Glimmer Custom Widget + Video glimmer-cw-video 1.0.0 Andy Maleh Glimmer Custom Widget - Video + +``` + #### Listing DSL Gems The following command lists available Glimmer [DSL Gems](#multi-dsl-support) (prefixed with "glimmer-dsl-" by convention) created by the the Glimmer community and published on [rubygems.org](http://www.rubygems.org): ``` @@ -1161,11 +1187,11 @@ Name Gem Version Author Description Css glimmer-dsl-css 0.2.0 AndyMaleh Glimmer DSL for CSS Opal glimmer-dsl-opal 0.1.0 AndyMaleh Glimmer DSL for Opal - Swt glimmer-dsl-swt 4.17.1.1 AndyMaleh Glimmer DSL for SWT + Swt glimmer-dsl-swt 4.17.2.0 AndyMaleh Glimmer DSL for SWT Tk glimmer-dsl-tk 0.0.5 AndyMaleh Glimmer DSL for Tk Xml glimmer-dsl-xml 0.2.0 AndyMaleh Glimmer DSL for XML ``` ### Packaging @@ -2893,12 +2919,13 @@ ### Miscellaneous #### Multi-DSL Support -Glimmer is a DSL engine that supports multiple DSLs (Domain Specific Languages): -- [SWT](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (Desktop GUI) +Glimmer is a DSL Framework that supports multiple DSLs (Domain Specific Languages): +- [SWT](https://github.com/AndyObtiva/glimmer-dsl-swt): Glimmer DSL for SWT (JRuby Desktop Development GUI Library) +- [Tk](https://github.com/AndyObtiva/glimmer-dsl-tk): Glimmer DSL for Tk (Ruby Desktop Development GUI Library) - [Opal](https://github.com/AndyObtiva/glimmer-dsl-opal): Glimmer DSL for Opal (Web GUI Adapter for Desktop Apps) - [XML](https://github.com/AndyObtiva/glimmer-dsl-xml): Glimmer DSL for XML (& HTML) - Useful with [SWT Browser Widget](#browser-widget) - [CSS](https://github.com/AndyObtiva/glimmer-dsl-css): Glimmer DSL for CSS (Cascading Style Sheets) - Useful with [SWT Browser Widget](#browser-widget) Glimmer automatically recognizes top-level keywords in each DSL and activates DSL accordingly. Glimmer allows mixing DSLs, which comes in handy when doing things like using the SWT Browser widget with XML and CSS. Once done processing a nested DSL top-level keyword, Glimmer switches back to the prior DSL automatically. @@ -3763,11 +3790,11 @@ 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::Package.javapackager_extra_args = " -Bmac.CFBundleIdentifier=org.andymaleh.application.MathBowling") +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. @@ -3791,11 +3818,11 @@ ``` - 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::Packager.javapackager_extra_args = "..."` (Useful to avoid re-entering extra arguments on every run of rake task.). Read about them in [their section below](#javapackager-extra-arguments). +- 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 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 @@ -3803,19 +3830,19 @@ - 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::Packager.javapackager_extra_args="..."` in your application Rakefile +- `Glimmer::RakeTask::Package.javapackager_extra_args="..."` in your application Rakefile - Environment variable: `JAVAPACKAGER_EXTRA_ARGS` Example (Rakefile): ```ruby require 'glimmer/rake_task' -Glimmer::Package.javapackager_extra_args = '-BlicenseType="MIT" -Bmac.category="public.app-category.business" -Bmac.signing-key-developer-id-app="Andy Maleh"' +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 @@ -3828,11 +3855,11 @@ That overrides the default application display name. ### Verbose Mode -Pass `-v` to javapackager in `Glimmer::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. +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 offers 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)). @@ -3842,11 +3869,11 @@ ### 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::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS` according to this webpage: https://docs.oracle.com/javase/9/tools/javapackager.htm#JSWOR719 +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="..." ``` @@ -3870,16 +3897,16 @@ - 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::Package.javapackager_extra_args` or `JAVAPACKAGER_EXTRA_ARGS` +- 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::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"' +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. ### Gotchas @@ -3890,10 +3917,10 @@ Keep that in mind if you are not going to rely on the default `LICENSE.txt` support. Example: ```ruby -Glimmer::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="ACME.txt" -BlicenseType="ACME"' +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."