README.md in glimmer-0.7.7 vs README.md in glimmer-0.7.8
- old
+ new
@@ -1,6 +1,6 @@
-# Glimmer 0.7.7 Beta (Desktop Development Library for Ruby)
+# Glimmer 0.7.8 Beta (Desktop Development Library for Ruby)
[](http://badge.fury.io/rb/glimmer)
[](https://travis-ci.com/github/AndyObtiva/glimmer)
[](https://codeclimate.com/github/AndyObtiva/glimmer/test_coverage)
[](https://codeclimate.com/github/AndyObtiva/glimmer/maintainability)
@@ -73,11 +73,11 @@
NOTE: Glimmer is in beta mode. Please help make better by adopting for small or low risk projects and providing feedback.
## Table of Contents
-- [Glimmer 0.7.7 Beta (Desktop Development Library for Ruby)](#glimmer-075-beta-desktop-development-library-for-ruby)
+- [Glimmer 0.7.8 Beta (Desktop Development Library for Ruby)](#glimmer-078-beta-desktop-development-library-for-ruby)
- [Examples](#examples)
- [Hello, World!](#hello-world)
- [Tic Tac Toe](#tic-tac-toe)
- [Background](#background)
- [Platform Support](#platform-support)
@@ -103,18 +103,20 @@
- [Miscellaneous](#miscellaneous)
- [Glimmer Style Guide](#glimmer-style-guide)
- [Samples](#samples)
- [Hello Samples](#hello-samples)
- [Elaborate Samples](#elaborate-samples)
+ - [External Samples](#external-samples)
- [In Production](#in-production)
- [SWT Reference](#swt-reference)
- [SWT Packages](#swt-packages)
- [Logging](#logging)
- [Raw JRuby Command](#raw-jruby-command)
- [Mac Support](#mac-support)
- [Packaging & Distribution](#packaging--distribution)
- - [Defaults](#defaults)
+ - [Packaging Defaults](#packaging-defaults)
+ - [Packaging Configuration](#packaging-configuration)
- [javapackager Extra Arguments](#javapackager-extra-arguments)
- [Mac Application Distribution](#mac-application-distribution)
- [Self Signed Certificate](#self-signed-certificate)
- [Gotchas](#gotchas)
- [Resources](#resources)
@@ -150,12 +152,13 @@
## Pre-requisites
- SWT 4.15 (comes included in Glimmer gem)
-- JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at https://www.jruby.org/download)
-- Java SE Runtime Environment 7 or higher (find at https://www.oracle.com/java/technologies/javase-downloads.html)
+- JRuby 9.2.11.1 (supporting Ruby 2.5.x syntax) (find at [https://www.jruby.org/download](https://www.jruby.org/download))
+- Java SE Runtime Environment 7 or higher (find at [https://www.oracle.com/java/technologies/javase-downloads.html](https://www.oracle.com/java/technologies/javase-downloads.html))
+- (Optional) RVM is needed for [Scaffolding](#scaffolding) only (find at [https://rvm.io/](https://rvm.io/))
On **Mac** and **Linux**, an easy way to obtain JRuby is through [RVM](http://rvm.io) by running:
```bash
rvm install jruby-9.2.11.1
@@ -169,22 +172,22 @@
### Option 1: Direct Install
Run this command to install directly:
```
-jgem install glimmer -v 0.7.7
+jgem install glimmer -v 0.7.8
```
`jgem` is JRuby's version of `gem` command.
RVM allows running `gem` as an alias.
Otherwise, you may also run `jruby -S gem install ...`
### Option 2: Bundler
Add the following to `Gemfile`:
```
-gem 'glimmer', '~> 0.7.7'
+gem 'glimmer', '~> 0.7.8'
```
And, then run:
```
jruby -S bundle install
@@ -217,11 +220,11 @@
### Advanced Usage
Below are the full usage instructions that come up when running `glimmer` without args.
```
-Usage: glimmer [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
+Usage: glimmer [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-jruby-option]...] (application.rb or task[task_args]) [[application2.rb]...]
Runs Glimmer applications/tasks.
Either a single task or one or more applications may be specified.
@@ -232,22 +235,23 @@
glimmer package:config # Generate JAR config file
glimmer package:jar # Generate JAR file
glimmer package:native # Generate Native files (DMG/PKG/APP on the Mac)
glimmer scaffold[app_name] # Scaffold a Glimmer application directory structure to begin building a new app
glimmer scaffold:custom_shell[custom_shell_name,namespace] # Scaffold a Glimmer::UI::CustomShell subclass (represents a full window view) under app/views (namespace is optional)
-glimmer scaffold:custom_shell_gem[custom_widget_name,namespace] # Scaffold a Glimmer::UI::CustomShell subclass (represents a full window view) under its own Ruby gem project (namespace is required)
+glimmer scaffold:custom_shell_gem[custom_shell_name,namespace] # Scaffold a Glimmer::UI::CustomShell subclass (represents a full window view) under its own Ruby gem + app project (namespace is required)
glimmer scaffold:custom_widget[custom_widget_name,namespace] # Scaffold a Glimmer::UI::CustomWidget subclass (represents a part of a view) under app/views (namespace is optional)
glimmer scaffold:custom_widget_gem[custom_widget_name,namespace] # Scaffold a Glimmer::UI::CustomWidget subclass (represents a part of a view) under its own Ruby gem project (namespace is required)
When applications are specified, they are run using JRuby,
automatically preloading the glimmer Ruby gem and SWT jar dependency.
Optionally, extra Glimmer options, JRuby options and environment variables may be passed in.
Glimmer options:
-- "--debug" : Displays extra debugging information and passes "--debug" to JRuby
-- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is "WARN")
+- "--quiet" : Does not announce file path of Glimmer application being launched nor enable logging
+- "--debug" : Displays extra debugging information, passes "--debug" to JRuby, and enables debug logging
+- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
Example: glimmer samples/hello_world.rb
This runs the Glimmer application samples/hello_world.rb
```
@@ -275,19 +279,19 @@
getting you to a running and delivered state of an advanced "Hello, World!" Glimmer application right off the bat.
This should greatly facilitate building a new Glimmer app by helping you be productive and focus on app details while
letting Glimmer scaffolding take care of initial app file structure concerns, such as adding:
- Main application class that includes Glimmer
-- Main application view that houses main window content
+- Main application view that houses main window content, about dialog, and preferences dialog
- View and Model directories
- Rakefile including Glimmer tasks
- Version
- License
- Icon
- Bin file for starting application
-NOTE: Scaffolding currently supports Mac packaging only at the moment.
+NOTE: Scaffolding requires RVM and currently supports Mac packaging only at the moment.
#### App
Before you start, make sure you are in a JRuby environment with Glimmer gem installed as per "Direct Install" pre-requisites.
@@ -342,12 +346,14 @@
```
#### Custom Shell Gem
Custom shell gems are self-contained Glimmer apps as well as reusable custom shells.
-As such, they are packaged as both a native executable (e.g. Mac DMG/PKG/APP) and a Ruby gem.
-Of course, you can build a Ruby gem and disregard its native executable packaging if you do not need it.
+They have everything scaffolded Glimmer apps come with in addition to gem content like a Jeweler 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.
To scaffold a Glimmer custom shell gem (full window view distributed as a Ruby gem), run the following command:
```
glimmer scaffold:custom_shell_gem[custom_shell_name, namespace]
@@ -357,12 +363,15 @@
The Ruby gem name will follow the convention "glimmer-cs-customwidgetname-namespace" (the 'cs' is for Custom Shell).
Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. [glimmer-cs-gladiator](https://rubygems.org/gems/glimmer-cs-gladiator) Ruby gem)
-Example: [https://github.com/AndyObtiva/glimmer-cs-gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator)
+Examples:
+- [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:
```
@@ -617,10 +626,16 @@
- `#opened_before?`: Returns whether a shell has been opened at least once before (additionally implying the SWT Event Loop has been started already)
- `#visible=`: Setting to true opens/shows shell. Setting to false hides the shell.
- `#pack`: Packs contained widgets using SWT's `Shell#pack` method
- `#pack_same_size`: Packs contained widgets without changing shell's size when widget sizes change
+#### Dialog
+
+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.
+
+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.
+
#### Menus
Glimmer DSL provides support for SWT Menu and MenuItem widgets.
There are 2 main types of menus in SWT:
@@ -1533,21 +1548,21 @@
Notice how `Red::Composite` became `red__composite` with double-underscore, which is how Glimmer Custom Widgets signify namespaces by convention. Additionally, `before_body` hook was utilized to set a `@color` variable and use inside the `body`.
Keep in mind that namespaces are not needed to be specified if the Custom Widget class has a unique name, not clashing with a basic SWT widget or another custom widget name.
-Custom Widgets have the following attributes (attribute readers) available to call from inside the `#body` method:
+Custom Widgets have the following attributes available to call from inside the `#body` method:
- `#parent`: Glimmer object parenting custom widget
- `#swt_style`: SWT style integer. Can be useful if you want to allow consumers to customize a widget inside the custom widget body
-- `#options`: a hash of options passed in parentheses when declaring a custom widget (useful for passing in model data) (e.g. `calendar(events: events)`). Custom widget class can declare option names (array) with `.options` method as shown below, which generates attribute readers for every option (not to be confused with `#options` instance method for retrieving options hash containing names & values)
+- `#options`: a hash of options passed in parentheses when declaring a custom widget (useful for passing in model data) (e.g. `calendar(events: events)`). Custom widget class can declare option names (array) with `::options` class method as shown below, which generates attribute accessors for every option (not to be confused with `#options` instance method for retrieving options hash containing names & values)
- `#content`: nested block underneath custom widget. It will be automatically called at the end of processing the custom widget body. Alternatively, the custom widget body may call `content.call` at the place where the content is needed to show up as shown in the following example.
- `#body_root`: top-most (root) widget returned from `#body` method.
- `#swt_widget`: actual SWT widget for `body_root`
Additionally, custom widgets can call the following class methods:
-- `.options`: declares a list of options by taking an option name array (symbols/strings). This generates option attribute readers (e.g. `options :orientation, :bg_color` generates `#orientation` and `#bg_color` attribute readers)
-- `.option`: declares a single option taking option name and default value as arguments (also generates an attribute reader just like `.options`)
+- `.options`: declares a list of options by taking an option name array (symbols/strings). This generates option attribute accessors (e.g. `options :orientation, :bg_color` generates `#orientation`, `#orientation=(v)`, `#bg_color`, and `#bg_color=(v)` attribute accessors)
+- `.option`: declares a single option taking option name and default value as arguments (also generates attribute accessors just like `.options`)
#### Content/Options Example (you may copy/paste in [`girb`](#girb-glimmer-irb-command)):
Definition:
```ruby
@@ -1975,15 +1990,25 @@
### Elaborate Samples
For more elaborate samples, check the following:
```
-glimmer samples/elaborate/login.rb # demonstrates general data-binding
+glimmer samples/elaborate/login.rb # demonstrates basic data-binding
glimmer samples/elaborate/contact_manager.rb # demonstrates table data-binding
glimmer samples/elaborate/tic_tac_toe.rb # demonstrates a full MVC application
```
+### External Samples
+
+#### [Glimmer Calculator](https://github.com/AndyObtiva/glimmer-cs-calculator)
+
+
+
+[Glimmer Calculator](https://github.com/AndyObtiva/glimmer-cs-calculator) is a basic calculator sample project demonstrating data-binding and TDD (test-driven-development) with Glimmer following the MVP pattern (Model-View-Presenter).
+
+#### [Gladiator](https://github.com/AndyObtiva/glimmer-cs-gladiator)
+
[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.
@@ -2109,52 +2134,50 @@
Glimmer apps may be packaged and distributed on the Mac, Windows, and Linux via these tools:
- Warbler (https://github.com/jruby/warbler): Enables bundling a Glimmer app into a JAR file
- javapackager (https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html): Enables packaging a JAR file as a DMG file on Mac, EXE on Windows, and multiple Linux supported formats on Linux.
-Glimmer simplifies the process for Mac packaging by providing a rake task.
+Glimmer simplifies the process of Mac packaging via the `glimmer package` command. It works out of the box for any application generated by [Glimmer Scaffolding](https://github.com/AndyObtiva/glimmer/blob/master/README.md#scaffolding):
-To use:
-- Create `Rakefile` in your app root directory
-- Add the following line to it: `require 'glimmer/rake_task'`
-- Create a Ruby script under bin (e.g. `bin/math_bowling`) to require the application file that uses Glimmer (e.g. `'../app/my_application.rb'`):
-```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 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).
-
-Now, you can run the following rake command to package your app into a Mac DMG file (using both Warbler and javapackager):
+glimmer package
```
-rake glimmer:package
-```
-This will generate a JAR file under `./dist` directory, which is then used to generate a DMG file (and pkg/app) under `./packages/bundles`.
+This will automatically generate a JAR file under `./dist` directory using Warbler, which is then used to automatically generate a DMG file (and pkg/app) under `./packages/bundles` using `javapackager`.
JAR file name will match your application local directory name (e.g. `MathBowling.jar` for `~/code/MathBowling`)
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 rake task will automatically set "mac.CFBundleIdentifier" to ="org.#{project_name}.application.#{project_name}".
+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")
-### Defaults
+### 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 `rake 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 `rake glimmer:package` right away. Run this command first:
+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:
```
-rake glimmer:package:config
+glimmer package:config
```
-This will generate `config/warble.rb`, which you may configure and then run `rake glimmer:package` afterwards.
+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 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).
+
### 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
- https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javapackager.html
@@ -2177,11 +2200,11 @@
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"' rake glimmer:package
+JAVAPACKAGER_EXTRA_ARGS='-Bmac.CFBundleName="Math Bowling Game"' glimmer package
```
That overrides the default application display name.
### Mac Application Distribution
@@ -2222,11 +2245,11 @@
```ruby
Glimmer::Package.javapackager_extra_args = '-Bmac.signing-key-developer-id-app="Andy Maleh"'
```
-Now, when you run `rake 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.
+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
1. Specifying License File
@@ -2239,10 +2262,10 @@
Glimmer::Package.javapackager_extra_args = '-srcfiles "ACME.txt" -BlicenseFile="ACME.txt" -BlicenseType="ACME"'
```
2. Mounted DMG Residue
-If you run `rake 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."
+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