README.markdown in glimmer-0.7.0 vs README.markdown in glimmer-0.7.1

- old
+ new

@@ -1,6 +1,7 @@ -# Glimmer 0.7.0 Beta (JRuby Desktop UI DSL + Data-Binding) +# Glimmer 0.7.1 Beta (JRuby Desktop UI DSL + Data-Binding) +[![Gem Version](https://badge.fury.io/rb/glimmer.svg)](http://badge.fury.io/rb/glimmer) [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/glimmer/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/glimmer?branch=master) Glimmer is a native-UI cross-platform desktop development library written in Ruby. Glimmer's main innovation is a JRuby DSL that enables productive and efficient authoring of desktop application user-interfaces while relying on the robust Eclipse SWT library. Glimmer additionally innovates by having built-in data-binding support to greatly facilitate synchronizing the UI with domain models. As a result, that achieves true decoupling of object oriented components, enabling developers to solve business problems without worrying about UI concerns, or alternatively drive development UI-first, and then write clean business components test-first afterwards. ## Examples @@ -43,11 +44,11 @@ button { layout_data :fill, :fill, true, true text bind(@tic_tac_toe_board[row, column], :sign) enabled bind(@tic_tac_toe_board[row, column], :empty) on_widget_selected { - @tic_tac_toe_board.mark_box(row, column) + @tic_tac_toe_board.mark(row, column) } } } } } @@ -68,11 +69,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 <!-- TOC START min:1 max:3 link:true asterisk:false update:true --> -- [Glimmer 0.7.0 Beta (JRuby Desktop UI DSL + Data-Binding)](#glimmer-058-beta-jruby-desktop-ui-dsl--data-binding) +- [Glimmer 0.7.1 Beta (JRuby Desktop UI DSL + Data-Binding)](#glimmer-058-beta-jruby-desktop-ui-dsl--data-binding) - [Examples](#examples) - [Hello World](#hello-world) - [Tic Tac Toe](#tic-tac-toe) - [Table of Contents](#table-of-contents) - [Background](#background) @@ -161,22 +162,22 @@ ### Option 1: Direct Install Run this command to install directly: ``` -jgem install glimmer -v 0.7.0 +jgem install glimmer -v 0.7.1 ``` `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.0' +gem 'glimmer', '~> 0.7.1' ``` And, then run: ``` jruby -S bundle install @@ -224,25 +225,26 @@ 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_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. -Concerning Glimmer options: +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") -Example: glimmer samples/hello/hello_world.rb +Example: glimmer samples/hello_world.rb -This runs the Glimmer application samples/hello/hello_world.rb +This runs the Glimmer application samples/hello_world.rb ``` Example (Glimmer/JRuby option specified): ``` glimmer --debug samples/hello/hello_world.rb @@ -260,11 +262,11 @@ ### Scaffolding Glimmer borrows from Rails the idea of Scaffolding, that is generating a structure for your app files that helps you get started just like true building scaffolding helps construction workers, civil engineers, and architects. -Glimmer scaffolding goes way beyond just scaffolding the app files that Rails does. It also packages it and launches it, +Glimmer scaffolding goes beyond just scaffolding the app files that Rails does. It also packages it and launches it, 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 @@ -274,10 +276,12 @@ - Version - License - Icon - Bin file for starting application +NOTE: Scaffolding 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. To scaffold a Glimmer app from scratch, run the following command: @@ -342,11 +346,11 @@ It is important to specify a namespace to avoid having your gem clash with existing gems. 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" Ruby gem) +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) #### Custom Widget Gem @@ -358,11 +362,11 @@ It is important to specify a namespace to avoid having your gem clash with existing gems. The Ruby gem name will follow the convention "glimmer-cw-customwidgetname-namespace" (the 'cw' is for Custom Widget) -Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. "glimmer-cw-video" Ruby gem) +Only official Glimmer gems created by the Glimmer project committers will have no namespace (e.g. [glimmer-cw-video](https://rubygems.org/gems/glimmer-cw-video) Ruby gem) Example: [https://github.com/AndyObtiva/glimmer-cw-video](https://github.com/AndyObtiva/glimmer-cw-video) ## Girb (Glimmer irb) Command @@ -422,11 +426,11 @@ - `tree` instantiates `org.eclipse.swt.widgets.Tree` - `combo` instantiates `org.eclipse.swt.widgets.Combo` - `list` instantiates `org.eclipse.swt.widgets.List` Every **widget** is sufficiently declared by name, but may optionally be accompanied with: -- SWT **style** ***argument*** wrapped by parenthesis according to [Glimmer Style Guide](#glimmer-coding-style) (see [next section](#widget-styles) for details). +- SWT **style** ***argument*** wrapped by parenthesis according to [Glimmer Style Guide](#glimmer-style-guide) (see [next section](#widget-styles) for details). - Ruby block containing **properties** (widget attributes) and **content** (nested widgets) For example, if we were to revisit `samples/hello/hello_world.rb` above (you may copy/paste in [`girb`](#girb-glimmer-irb-command)): ```ruby @@ -449,11 +453,11 @@ text "Hello, World!" # text property of label } # ... ``` -The first line declares a **property** called `text`, which sets the title of the shell (window) to `"Glimmer"`. **Properties** always have ***arguments*** (not wrapped by parenthesis according to [Glimmer Style Guide](#glimmer-coding-style)), such as the text `"Glimmer"` in this case, and do **NOT** have a ***block*** (this distinguishes them from **widget** declarations). +The first line declares a **property** called `text`, which sets the title of the shell (window) to `"Glimmer"`. **Properties** always have ***arguments*** (not wrapped by parenthesis according to [Glimmer Style Guide](#glimmer-style-guide)), such as the text `"Glimmer"` in this case, and do **NOT** have a ***block*** (this distinguishes them from **widget** declarations). The second line declares the `label` **widget**, which is followed by a Ruby **content** ***block*** that contains its `text` **property** with value `"Hello, World!"` The **widget** ***block*** may optionally receive an argument representing the widget proxy object that the block content is for. This is useful in rare cases when the content code needs to refer to parent widget during declaration. You may leave that argument out most of the time and only add when absolutely needed. @@ -688,11 +692,11 @@ SWT widgets receive `SWT` styles in their constructor as per this guide: https://wiki.eclipse.org/SWT_Widget_Style_Bits -Glimmer DSL facilitates that by passing symbols representing `SWT` constants as widget method arguments (i.e. inside widget `()` parentheses according to [Glimmer Style Guide](#glimmer-coding-style). See example below) in lower case version (e.g. `SWT::MULTI` becomes `:multi`). +Glimmer DSL facilitates that by passing symbols representing `SWT` constants as widget method arguments (i.e. inside widget `()` parentheses according to [Glimmer Style Guide](#glimmer-style-guide). See example below) in lower case version (e.g. `SWT::MULTI` becomes `:multi`). These styles customize widget look, feel, and behavior. Example: @@ -1815,10 +1819,19 @@ } } puts @css ``` +##### Listing / Enabling / Disabling DSLs + +Glimmer provides a number of methods on Glimmer::DSL::Engine to configure DSL support or inquire about it: +- `Glimmer::DSL::Engine.dsls`: Lists available Glimmer DSLs +- `Glimmer::DSL::Engine.disable_dsl(dsl_name)`: Disables a specific DSL. Useful when there is no need for certain DSLs in a certain application. +- `Glimmer::DSL::Engine.disabled_dsls': Lists disabled DSLs +- `Glimmer::DSL::Engine.enable_dsl(dsl_name)`: Re-enables disabled DSL +- `Glimmer::DSL::Engine.enabled_dsls=(dsl_names)`: Disables all DSLs except the ones specified. + #### Video Widget ![Video Widget](images/glimmer-video-widget.png) Glimmer supports a [video custom widget](https://github.com/AndyObtiva/glimmer-cw-video) not in SWT. @@ -1966,10 +1979,10 @@ For example, after imports, `org.eclipse.swt.graphics.Color` can be referenced by just `Color` Nonetheless, you can disable automatic import if needed via this Glimmer configuration option: ```ruby -Glimmer.import_swt_packages = false +Glimmer::Config.import_swt_packages = false ``` To import SWT Java packages manually instead, you have 2 options: 1. `include Glimmer::SwtPackages`: lazily imports all SWT Java packages to your class, lazy-loading SWT Java class constants on first reference.