README.markdown in glimmer-0.4.1 vs README.markdown in glimmer-0.4.2

- old
+ new

@@ -36,17 +36,17 @@ ```ruby shell { text "Tic-Tac-Toe" composite { - layout GridLayout.new(3,true) + grid_layout 3, true (1..3).each { |row| (1..3).each { |column| button { - layout_data GridData.new(GSWT[:fill], GSWT[:fill], true, true) - text bind(@tic_tac_toe_board.box(row, column), :sign) - enabled bind(@tic_tac_toe_board.box(row, column), :empty) + 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) } } } @@ -100,18 +100,18 @@ ### Option 1: Direct Install Run this command to install directly: ``` -jgem install glimmer -v 0.4.1 +jgem install glimmer -v 0.4.2 ``` ### Option 2: Bundler Add the following to `Gemfile`: ``` -gem 'glimmer', '~> 0.4.1' +gem 'glimmer', '~> 0.4.2' ``` And, then run: ``` bundle install @@ -139,11 +139,11 @@ Glimmer UIs (user interfaces) are modeled with widgets (wrappers around the SWT library widgets found here: https://help.eclipse.org/2019-12/topic/org.eclipse.platform.doc.isv/guide/swt_widgets_controls.htm?cp=2_0_7_0_0). In Glimmer DSL, widgets are declared with lowercase underscored naming (you may look at usage examples in the `samples` directory). -The `shell` widget is always the outermost widget containing all others in a desktop windowed application. +The `shell` widget is always the outermost widget containing all others in a desktop windowed application. It is centered upon initial display and has a minimum width of 130 (can be re-centered when needed with `@shell.center` method) Other widget examples: - `button`: wrapper for `org.eclipse.swt.widgets.Button` - `label`: wrapper for `org.eclipse.swt.widgets.Label` - `tab_folder`: wrapper for `org.eclipse.swt.widgets.TabFolder` @@ -198,11 +198,11 @@ You may check out all available `SWT` styles here: https://help.eclipse.org/2019-12/nftopic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/SWT.html -**Final Note** (advanced case outside of standard Glimmer DSL): +**Note** (advanced case outside of standard Glimmer DSL): When building a widget-related SWT object manually (e.g. `GridData.new(...)`), you are expected to use `SWT::CONSTANT` directly or BIT-OR a few SWT constants together like `SWT::BORDER | SWT::V_SCROLL`. Glimmer facilitates that with `GSWT` class by allowing you to pass multiple styles as an argument array of symbols instead of dealing with BIT-OR. For example: `GSWT[:border, :v_scroll]` @@ -234,15 +234,15 @@ ### Layouts Glimmer lays widgets out visually using SWT layouts, which can only be set on composite widget and subclasses. The most common SWT layouts are: -- `FillLayout`: lays widgets out in equal proportion horizontally or vertically with spacing/margin options +- `FillLayout`: lays widgets out in equal proportion horizontally or vertically with spacing/margin options. This is the ***default*** layout for ***shell*** (with `:horizontal` option) in Glimmer. - `RowLayout`: lays widgets out horizontally or vertically in varying proportions with advanced spacing/margin/justify options -- `GridLayout`(**default**): lays widgets out in a grid with advanced spacing/margin/alignment/indentation options. This is the **default** layout in Glimmer. It is important to master. +- `GridLayout`: lays widgets out in a grid with advanced spacing/margin/alignment/indentation options. This is the **default** layout for **composite** in Glimmer. It is important to master. -In Glimmer DSL, just like widgets, layouts can be specified with lowercase underscored names followed by a block containing properties (e.g. `RowLayout` is `row_layout`). +In Glimmer DSL, just like widgets, layouts can be specified with lowercase underscored names followed by a block containing properties, also lowercase underscored names (e.g. `RowLayout` is `row_layout`). Example: ```ruby composite { @@ -259,19 +259,74 @@ } # ... widgets follow } ``` -Alternatively, a layout may be constructed by following the SWT API for the layout object. For example, a `RowLayout` can be constructed by passing it an SWT style constant. +Alternatively, a layout may be constructed by following the SWT API for the layout object. For example, a `RowLayout` can be constructed by passing it an SWT style constant (Glimmer automatically accepts symbols (e.g. `:horizontal`) for SWT style arguments like `SWT::HORIZONTAL`.) ```ruby composite { - row_layout(:horizontal) + row_layout :horizontal # ... widgets follow } ``` +Here is a more sophisticated example taken from [hello_computed.rb](https://github.com/AndyObtiva/glimmer/blob/master/samples/hellocomputed/hello_computed.rb) sample: +```ruby +shell { + text "Hello Computed" + composite { + grid_layout { + num_columns 2 + make_columns_equal_width true + horizontal_spacing 20 + vertical_spacing 10 + } + label {text "First &Name: "} + text { + text bind(@contact, :first_name) + layout_data { + horizontalAlignment :fill + grabExcessHorizontalSpace true + } + } + label {text "&Last Name: "} + text { + text bind(@contact, :last_name) + layout_data { + horizontalAlignment :fill + grabExcessHorizontalSpace true + } + } + label {text "&Year of Birth: "} + text { + text bind(@contact, :year_of_birth) + layout_data { + horizontalAlignment :fill + grabExcessHorizontalSpace true + } + } + label {text "Name: "} + label { + text bind(@contact, :name, computed_by: [:first_name, :last_name]) + layout_data { + horizontalAlignment :fill + grabExcessHorizontalSpace true + } + } + label {text "Age: "} + label { + text bind(@contact, :age, :fixnum, computed_by: [:year_of_birth]) + layout_data { + horizontalAlignment :fill + grabExcessHorizontalSpace true + } + } + } +}.open +``` + Check out the samples directory for more advanced examples of layouts in Glimmer. **Defaults**: Glimmer composites always come with grid_layout by default, but you can still specify explicitly if you'd like to set specific properties on it. @@ -294,17 +349,21 @@ - `GridLayout` on a composite demands `GridData` on contained widgets - `RowLayout` on a composite demands `RowData` on contained widgets Not all layouts support layout data to further customize widget layouts. For example, `FillLayout` supports no layout data. -Unlike widgets and layouts in Glimmer DSL, layout data is simply specified with `layout_data` keyword nested inside a widget block body, and followed by arguments and/or a block of its own properties. Glimmer automatically deduces layout data class name by convention as per rule above, with the assumption that the layout data class lives under the same exact Java package as the layout (one can set custom layout data that breaks convention if needed in rare cases. See code below for an example) +Unlike widgets and layouts in Glimmer DSL, layout data is simply specified with `layout_data` keyword nested inside a widget block body, and followed by arguments and/or a block of its own properties (lowercase underscored names). +Glimmer automatically deduces layout data class name by convention as per rule above, with the assumption that the layout data class lives under the same exact Java package as the layout (one can set custom layout data that breaks convention if needed in rare cases. See code below for an example) + +Glimmer also automatically accepts symbols (e.g. `:fill`) for SWT style arguments like `SWT::FILL`. + Examples: ```ruby composite { - row_layout(:horizontal) + row_layout :horizontal label { layout_data { # followed by properties width 50 height 30 } @@ -313,21 +372,21 @@ } ``` ```ruby composite { - grid_layout(3, false) # grid layout with 3 columns not of equal width + grid_layout 3, false # grid layout with 3 columns not of equal width label { - # layout data followed by arguments passed to SWT constructor - layout_data(GSWT[:fill], GSWT[:end], true, false) + # layout data followed by arguments passed to SWT GridData constructor + layout_data :fill, :end, true, false } } ``` ```ruby composite { - grid_layout(3, false) # grid layout with 3 columns not of equal width + grid_layout 3, false # grid layout with 3 columns not of equal width label { # layout data set explicitly via an object (helps in rare cases that break convention) layout_data GridData.new(GSWT[:fill], GSWT[:end], true, false) } } @@ -435,25 +494,25 @@ include Glimmer include Observer def initialize # ... - observe(@tic_tac_toe_board, "game_status") + observe(@tic_tac_toe_board, :game_status) end def call(game_status) display_win_message if game_status == TicTacToeBoard::WIN display_draw_message if game_status == TicTacToeBoard::DRAW end # ... end ``` -Alternatively, one can use a default Observer::Proc implementation via Observer#proc method: +Alternatively, one can use a default Observer::Proc implementation via Observer.proc method: ```ruby observer = Observer.proc { |new_value| puts new_value } -observer.observe(@tic_tac_toe_board, "game_status") +observer.observe(@tic_tac_toe_board, :game_status) ``` Observers can be a good mechanism for displaying dialog messages with Glimmer (using SWT's `MessageBox`). Look at `samples/tictactoe/tic_tac_toe.rb` for an `Observer` dialog message example (sample below). @@ -463,11 +522,11 @@ include Glimmer include Observer def initialize # ... - observe(@tic_tac_toe_board, "game_status") + observe(@tic_tac_toe_board, :game_status) end def call(game_status) display_win_message if game_status == TicTacToeBoard::WIN display_draw_message if game_status == TicTacToeBoard::DRAW @@ -492,16 +551,20 @@ end ``` ## Samples -Check the "samples" folder for examples on how to write Glimmer applications. To run them, make sure to install the `glimmer` gem first and then use the `glimmer` command. +Check the "[samples](https://github.com/AndyObtiva/glimmer/tree/master/samples)" folder 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` command to run it (alternatively, you may clone the repo, follow contributing instructions, and run `rake install` to install the gem before running `glimmer` command). Example: ``` glimmer samples/hello_world.rb ``` + +Here is also a more elaborate project (educational game) built with Glimmer: + +[Math Bowling](https://github.com/AndyObtiva/MathBowling) ## SWT Reference https://www.eclipse.org/swt/docs.php