glimmer-dsl-libui 0.8.0 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +11 -1
- data/README.md +359 -126
- data/RUBY_VERSION +1 -0
- data/VERSION +1 -1
- data/bin/girb +1 -1
- data/bin/glimmer +30 -0
- data/glimmer-dsl-libui.gemspec +0 -0
- data/icons/scaffold_app.icns +0 -0
- data/icons/scaffold_app.ico +0 -0
- data/icons/scaffold_app.png +0 -0
- data/lib/glimmer/Rakefile +26 -0
- data/lib/glimmer/launcher.rb +231 -0
- data/lib/glimmer/rake_task/list.rb +105 -0
- data/lib/glimmer/rake_task/scaffold.rb +799 -0
- data/lib/glimmer/rake_task.rb +189 -0
- metadata +105 -40
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: f25a73b328f8f3edfab2fba17e5f2561291f6ea0d9138a6114263e1145f3f96b
|
|
4
|
+
data.tar.gz: a9985350bc4de488d12eeb5aaad8e9b20493d4d1eb911e2c8e247b7b622905f9
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: da98d3cc5849995f84df95b87081a14abd55df599a420c340a3f780536e574ed2ffce55898a7e61f62cfdcff6c1efd616f1b62b0c58ab3ace4c875db3a7a0dd0
|
|
7
|
+
data.tar.gz: 8ee6d0c78ba2749e86acd8380888fac51025862e0428ded65532f23b297355cb45e75a9476c15ddea1a311f40bebffe1e4f35b4be8785bdef5210850f68565a0
|
data/CHANGELOG.md
CHANGED
|
@@ -1,8 +1,18 @@
|
|
|
1
1
|
# Change Log
|
|
2
2
|
|
|
3
|
+
## 0.9.1
|
|
4
|
+
|
|
5
|
+
- Scaffold an application via Glimmer Command: `glimmer scaffold[app_name]`
|
|
6
|
+
- Hide unsupported Scaffolding tasks in Glimmer Command
|
|
7
|
+
- Add missing Glimmer Command gem dependencies: `rake`, `rake-tui`, `text-table`, `puts_debuggerer`
|
|
8
|
+
|
|
9
|
+
## 0.9.0
|
|
10
|
+
|
|
11
|
+
- Support `glimmer` command to more conveniently run applications (`glimmer app_path`) and examples (`glimmer examples`)
|
|
12
|
+
|
|
3
13
|
## 0.8.0
|
|
4
14
|
|
|
5
|
-
- Support `composite_shape` keyword (alias: `shape`) as aggregate (composite) shape that can have arbitrary shapes, text, transforms underneath, which inherit its `fill`/`stroke` colors and `transform`
|
|
15
|
+
- Support `composite_shape` keyword (alias: `shape`) as aggregate (composite) shape that can have arbitrary shapes, text, transforms underneath, which inherit its `fill`/`stroke` colors and `transform`. `composite_shape` also supports nesting mouse listeners, which check mouse click point containment against all nested shapes automatically.
|
|
6
16
|
- New `examples/basic_composite_shape.rb` with use of `shape` + drag and drop support for moving shapes and click support for changing shape colors
|
|
7
17
|
- Invert `Glimmer::LibUI::ControlProxy::KEYWORD_ALIASES` to enable adding multiple aliases per keyword
|
|
8
18
|
- Support `Glimmer::LibUI::Shape::KEYWORD_ALIASES` to enable adding multiple aliases per keyword
|
data/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
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 LibUI
|
|
2
|
-
## Prerequisite-Free Ruby Desktop Development GUI Library
|
|
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 LibUI ([Fukuoka Award Winning](http://www.digitalfukuoka.jp/topics/187?locale=ja))
|
|
2
|
+
## Prerequisite-Free Ruby Desktop Development Cross-Platform Native GUI Library
|
|
3
3
|
### The Quickest Way From Zero To GUI
|
|
4
4
|
[](http://badge.fury.io/rb/glimmer-dsl-libui)
|
|
5
5
|
[](https://gitter.im/AndyObtiva/glimmer?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
|
@@ -12,13 +12,13 @@
|
|
|
12
12
|
|
|
13
13
|
[**(Ruby Rogues Podcast Interview - Desktop Apps in Ruby ft. Andy)**](https://andymaleh.blogspot.com/2022/05/ruby-rogues-podcast-interview-desktop.html)
|
|
14
14
|
|
|
15
|
-
[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [LibUI](https://github.com/libui-ng/libui-ng) is a prerequisite-free [MRI Ruby](https://www.ruby-lang.org) desktop development GUI (Graphical User Interface) library. No need to pre-install any prerequisites. Just install the [gem](https://rubygems.org/gems/glimmer-dsl-libui) and have platform
|
|
15
|
+
[Glimmer](https://github.com/AndyObtiva/glimmer) DSL for [LibUI](https://github.com/libui-ng/libui-ng) is a [Fukuoka Award Winning](http://www.digitalfukuoka.jp/topics/187?locale=ja) prerequisite-free [MRI Ruby](https://www.ruby-lang.org) desktop development cross-platform native GUI (Graphical User Interface) library. No need to pre-install any prerequisites. Just install the [gem](https://rubygems.org/gems/glimmer-dsl-libui) and have cross-platform native GUI that just works on Mac, Windows, and Linux!
|
|
16
16
|
|
|
17
17
|
Mac | Windows | Linux
|
|
18
18
|
----|---------|------
|
|
19
19
|
 |  | 
|
|
20
20
|
|
|
21
|
-
[LibUI](https://github.com/libui-ng/libui-ng) is a relatively new C GUI library that renders native controls on every platform (similar to [SWT](https://www.eclipse.org/swt/), but without the heavy weight of the [Java Virtual Machine](https://www.java.com/en/)).
|
|
21
|
+
[LibUI](https://github.com/libui-ng/libui-ng) is a relatively new C GUI library that renders native controls on every platform (similar to [SWT](https://www.eclipse.org/swt/), but without the heavy weight of the [Java Virtual Machine](https://www.java.com/en/)). Applications built with Glimmer DSL for LibUI will provide the familiar native look, feel, and behavior of GUI on Mac, Windows, and Linux.
|
|
22
22
|
|
|
23
23
|
The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) as opposed to [Glimmer DSL for SWT](https://github.com/AndyObtiva/glimmer-dsl-swt) or [Glimmer DSL for Tk](https://github.com/AndyObtiva/glimmer-dsl-tk) is the fact that [SWT](https://www.eclipse.org/swt/) and [Tk](https://www.tcl.tk/) are more mature than mid-alpha [libui](https://github.com/libui-ng/libui-ng) as GUI toolkits. Still, if there is only a need to build a small simple application, [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) could be a good convenient choice due to having zero prerequisites (beyond Ruby and the dependencies included in the [Ruby gem](https://rubygems.org/gems/glimmer-dsl-libui)). Also, just like [Glimmer DSL for Tk](https://github.com/AndyObtiva/glimmer-dsl-tk), its apps start instantly and have a small memory footprint. [LibUI](https://github.com/kojix2/LibUI) is a promising new GUI toolkit that might prove quite worthy in the future.
|
|
24
24
|
|
|
@@ -28,7 +28,7 @@ The main trade-off in using [Glimmer DSL for LibUI](https://rubygems.org/gems/gl
|
|
|
28
28
|
- Requiring the [least amount of syntax](#glimmer-gui-dsl-concepts) possible to build GUI
|
|
29
29
|
- [Custom Control](#custom-keywords) support
|
|
30
30
|
- [Bidirectional/Unidirectional Data-Binding](#data-binding) to declaratively wire and automatically synchronize GUI Views with Models
|
|
31
|
-
- [
|
|
31
|
+
- [Scaffolding](scaffold-application) for new custom controls, apps, and gems
|
|
32
32
|
- [Far Future Plan] Native-Executable packaging on Mac, Windows, and Linux.
|
|
33
33
|
|
|
34
34
|
Hello, World!
|
|
@@ -342,9 +342,17 @@ Learn more about the differences between various [Glimmer](https://github.com/An
|
|
|
342
342
|
## Table of Contents
|
|
343
343
|
|
|
344
344
|
- [Glimmer DSL for LibUI](#)
|
|
345
|
-
- [
|
|
345
|
+
- [Setup](#setup)
|
|
346
346
|
- [Usage](#usage)
|
|
347
|
+
- [Experimentation Usage](#experimentation-usage)
|
|
348
|
+
- [Prototyping Usage](#prototyping-usage)
|
|
349
|
+
- [Serious Usage](#serious-usage)
|
|
350
|
+
- [Glimmer Command](#glimmer-command)
|
|
351
|
+
- [Run Application](#run-application)
|
|
352
|
+
- [Run Examples](#run-examples)
|
|
353
|
+
- [Scaffold Application](#scaffold-application)
|
|
347
354
|
- [Girb (Glimmer IRB)](#girb-glimmer-irb)
|
|
355
|
+
- [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
|
|
348
356
|
- [API](#api)
|
|
349
357
|
- [Supported Keywords](#supported-keywords)
|
|
350
358
|
- [Common Control Properties](#common-control-properties)
|
|
@@ -366,7 +374,9 @@ Learn more about the differences between various [Glimmer](https://github.com/An
|
|
|
366
374
|
- [Area Composite Shape](#area-composite-shape)
|
|
367
375
|
- [Area Animation](#area-animation)
|
|
368
376
|
- [Smart Defaults and Conventions](#smart-defaults-and-conventions)
|
|
369
|
-
- [Custom
|
|
377
|
+
- [Custom Controls](#custom-controls)
|
|
378
|
+
- [Method-Based Custom Controls](#method-based-custom-controls)
|
|
379
|
+
- [Class-Based Custom Controls](#class-based-custom-controls)
|
|
370
380
|
- [Observer Pattern](#observer-pattern)
|
|
371
381
|
- [Data-Binding](#data-binding)
|
|
372
382
|
- [Bidirectional (Two-Way) Data-Binding](#bidirectional-two-way-data-binding)
|
|
@@ -400,6 +410,321 @@ Learn more about the differences between various [Glimmer](https://github.com/An
|
|
|
400
410
|
- [Contributors](#contributors)
|
|
401
411
|
- [License](#license)
|
|
402
412
|
|
|
413
|
+
## Setup
|
|
414
|
+
|
|
415
|
+
Install [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) gem directly into a [maintained Ruby version](https://www.ruby-lang.org/en/downloads/):
|
|
416
|
+
|
|
417
|
+
```
|
|
418
|
+
gem install glimmer-dsl-libui
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
Or install via Bundler `Gemfile`:
|
|
422
|
+
|
|
423
|
+
```ruby
|
|
424
|
+
gem 'glimmer-dsl-libui', '~> 0.9.1'
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
Test that installation worked by running the [Glimmer Meta-Example](#examples):
|
|
428
|
+
|
|
429
|
+
```
|
|
430
|
+
glimmer examples
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
Or alternatively, run using the explicit Ruby command:
|
|
434
|
+
|
|
435
|
+
```
|
|
436
|
+
ruby -r glimmer-dsl-libui -e "require 'examples/meta_example'"
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
Mac | Windows | Linux
|
|
440
|
+
----|---------|------
|
|
441
|
+
 |  | 
|
|
442
|
+
|
|
443
|
+
## Usage
|
|
444
|
+
|
|
445
|
+
Require [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) (whether through a Ruby `require` statement or `Bundler`) and then include the `Glimmer` or `Glimmer::LibUI::Application` module to enable access to the Glimmer GUI DSL in one of multiple approaches.
|
|
446
|
+
|
|
447
|
+
### Experimentation Usage
|
|
448
|
+
|
|
449
|
+
For experimenting and learning, add `include Glimmer` into the top-level main object and start using the Glimmer GUI DSL directly.
|
|
450
|
+
|
|
451
|
+
Example including `Glimmer` at the top-level scope just for some prototyping/demoing/testing (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
452
|
+
|
|
453
|
+
```ruby
|
|
454
|
+
require 'glimmer-dsl-libui'
|
|
455
|
+
|
|
456
|
+
include Glimmer
|
|
457
|
+
|
|
458
|
+
window('hello world', 300, 200) {
|
|
459
|
+
button('Button') {
|
|
460
|
+
on_clicked do
|
|
461
|
+
puts 'Button Clicked'
|
|
462
|
+
end
|
|
463
|
+
}
|
|
464
|
+
}.show
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
|
|
468
|
+
|
|
469
|
+
### Prototyping Usage
|
|
470
|
+
|
|
471
|
+
For prototyping, add `include Glimmer` into an actual class and start using the Glimmer GUI DSL in instance methods.
|
|
472
|
+
|
|
473
|
+
Example including `Glimmer` and manually implementing the `#launch` method (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
474
|
+
|
|
475
|
+
```ruby
|
|
476
|
+
require 'glimmer-dsl-libui'
|
|
477
|
+
|
|
478
|
+
class SomeGlimmerApp
|
|
479
|
+
include Glimmer
|
|
480
|
+
|
|
481
|
+
def launch
|
|
482
|
+
window('hello world', 300, 200) {
|
|
483
|
+
button('Button') {
|
|
484
|
+
on_clicked do
|
|
485
|
+
puts 'Button Clicked'
|
|
486
|
+
end
|
|
487
|
+
}
|
|
488
|
+
}.show
|
|
489
|
+
end
|
|
490
|
+
end
|
|
491
|
+
|
|
492
|
+
SomeGlimmerApp.new.launch
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
|
|
496
|
+
|
|
497
|
+
### Serious Usage
|
|
498
|
+
|
|
499
|
+
For more serious usage, add `include Glimmer::LibUI::Application` into an actual class (it automatically includes the `Glimmer` module) to conveniently declare the GUI underneath a `body` block (with the option of implementing `before_body` and `after_body` hooks) and take advantage of the inherited `SomeClass::launch` method implementation that automatically calls `window.show` for you.
|
|
500
|
+
|
|
501
|
+
Example including `Glimmer::LibUI::Application` (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
502
|
+
|
|
503
|
+
```ruby
|
|
504
|
+
require 'glimmer-dsl-libui'
|
|
505
|
+
|
|
506
|
+
class SomeGlimmerApp
|
|
507
|
+
include Glimmer::LibUI::Application
|
|
508
|
+
|
|
509
|
+
body {
|
|
510
|
+
window('hello world', 300, 200) {
|
|
511
|
+
button('Button') {
|
|
512
|
+
on_clicked do
|
|
513
|
+
puts 'Button Clicked'
|
|
514
|
+
end
|
|
515
|
+
}
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
end
|
|
519
|
+
|
|
520
|
+
SomeGlimmerApp.launch
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
|
|
524
|
+
|
|
525
|
+
(note: `Glimmer::LibUI::Application` is an alias for `Glimmer::LibUI::CustomWindow` since that is what it represents)
|
|
526
|
+
|
|
527
|
+
If you are new to [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui), check out the [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts), [Glimmer Command](#glimmer-command), [Girb](#girb-glimmer-irb) and [Examples](#examples) to quickly learn through copy/paste. You may refer to the [API](#api) later on once you have gotten your feet wet with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) and need more detailed reference information.
|
|
528
|
+
|
|
529
|
+
|
|
530
|
+
## Glimmer Command
|
|
531
|
+
|
|
532
|
+
The `glimmer` command allows you to conveniently run applications (`glimmer app_path`), run examples (`glimmer examples`), and scaffold applications (`glimmer "scaffold[app_name]"`).
|
|
533
|
+
|
|
534
|
+
You can bring up usage instructions by running the `glimmer` command without arguments:
|
|
535
|
+
|
|
536
|
+
```
|
|
537
|
+
glimmer
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
```
|
|
541
|
+
% bin/glimmer
|
|
542
|
+
Glimmer DSL for LibUI (Prerequisite-Free Ruby Desktop Development Cross-Platform Native GUI Library) - Ruby Gem: glimmer-dsl-libui v0.8.0
|
|
543
|
+
|
|
544
|
+
Usage: glimmer [--bundler] [--pd] [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-ruby-option]...] (application.rb or task[task_args])
|
|
545
|
+
|
|
546
|
+
Runs Glimmer applications and tasks.
|
|
547
|
+
|
|
548
|
+
When applications are specified, they are run using Ruby,
|
|
549
|
+
automatically preloading the glimmer-dsl-libui Ruby gem.
|
|
550
|
+
|
|
551
|
+
Optionally, extra Glimmer options, Ruby options, and/or environment variables may be passed in.
|
|
552
|
+
|
|
553
|
+
Glimmer options:
|
|
554
|
+
- "--bundler=GROUP" : Activates gems in Bundler default group in Gemfile
|
|
555
|
+
- "--pd=BOOLEAN" : Requires puts_debuggerer to enable pd method
|
|
556
|
+
- "--quiet=BOOLEAN" : Does not announce file path of Glimmer application being launched
|
|
557
|
+
- "--debug" : Displays extra debugging information and enables debug logging
|
|
558
|
+
- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
|
|
559
|
+
|
|
560
|
+
Tasks are run via rake. Some tasks take arguments in square brackets (surround with double-quotes if using Zsh).
|
|
561
|
+
|
|
562
|
+
Available tasks are below (if you do not see any, please add `require 'glimmer/rake_task'` to Rakefile and rerun or run rake -T):
|
|
563
|
+
|
|
564
|
+
Select a Glimmer task to run: (Press ↑/↓ arrow to move, Enter to select and letters to filter)
|
|
565
|
+
‣ glimmer examples # Brings up the Glimmer Meta-Sample app to allow browsing, running, and viewing code of Glimmer samples
|
|
566
|
+
glimmer list:gems:customcontrol[query] # List Glimmer custom control gems available at rubygems.org (query is optional) [alt: list:gems:cc]
|
|
567
|
+
glimmer list:gems:customshape[query] # List Glimmer custom shape gems available at rubygems.org (query is optional) [alt: list:gems:cs]
|
|
568
|
+
glimmer list:gems:customwindow[query] # List Glimmer custom window gems available at rubygems.org (query is optional) [alt: list:gems:cw]
|
|
569
|
+
glimmer list:gems:dsl[query] # List Glimmer DSL gems available at rubygems.org (query is optional)
|
|
570
|
+
glimmer run[app_path] # Runs Glimmer app or custom window gem in the current directory, unless app_path is specified, then runs it instead (app_path is optional)
|
|
571
|
+
glimmer scaffold[app_name] # Scaffold Glimmer application directory structure to build a new app
|
|
572
|
+
glimmer scaffold:customcontrol[name,namespace] # Scaffold Glimmer::UI::CustomControl subclass (part of a view) under app/views (namespace is optional) [alt: scaffold:cc]
|
|
573
|
+
glimmer scaffold:customshape[name,namespace] # Scaffold Glimmer::UI::CustomShape subclass (part of a view) under app/views (namespace is optional) [alt: scaffold:cs]
|
|
574
|
+
glimmer scaffold:customwindow[name,namespace] # Scaffold Glimmer::UI::CustomWindow subclass (full window view) under app/views (namespace is optional) [alt: scaffold:cw]
|
|
575
|
+
glimmer scaffold:gem:customcontrol[name,namespace] # Scaffold Glimmer::UI::CustomControl subclass (part of a view) under its own Ruby gem project (namespace is required) [alt: scaffold:gem:cc]
|
|
576
|
+
glimmer scaffold:gem:customshape[name,namespace] # Scaffold Glimmer::UI::CustomShape subclass (part of a view) under its own Ruby gem project (namespace is required) [alt: scaffold:gem:cs]
|
|
577
|
+
glimmer scaffold:gem:customwindow[name,namespace] # Scaffold Glimmer::UI::CustomWindow subclass (full window view) under its own Ruby gem + app project (namespace is required) [alt: scaffold:gem:cw]
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
On Mac and Linux, it brings up a TUI (Text-based User Interface) for interactive navigation and execution of Glimmer tasks (courtesy of [rake-tui](https://github.com/AndyObtiva/rake-tui)).
|
|
581
|
+
|
|
582
|
+
On Windows and ARM64 machines, it simply lists the available Glimmer tasks at the end (courtsey of [rake](https://github.com/ruby/rake)).
|
|
583
|
+
|
|
584
|
+
Note: If you encounter an issue running the `glimmer` command, run `bundle exec glimmer` instead.
|
|
585
|
+
|
|
586
|
+
### Run Application
|
|
587
|
+
|
|
588
|
+
Run Glimmer DSL for LibUI applications via this command:
|
|
589
|
+
|
|
590
|
+
```
|
|
591
|
+
glimmer app_path
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
For example, from a cloned glimmer-dsl-libui repository:
|
|
595
|
+
|
|
596
|
+
```
|
|
597
|
+
glimmer examples/basic_window.rb
|
|
598
|
+
```
|
|
599
|
+
|
|
600
|
+
Mac | Windows | Linux
|
|
601
|
+
----|---------|------
|
|
602
|
+
 |  | 
|
|
603
|
+
|
|
604
|
+
### Run Examples
|
|
605
|
+
|
|
606
|
+
Run Glimmer DSL for LibUI included examples via this command:
|
|
607
|
+
|
|
608
|
+
```
|
|
609
|
+
glimmer examples
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
That brings up the [Glimmer Meta-Example](https://github.com/AndyObtiva/glimmer-dsl-libui/blob/master/examples/meta_example.rb))
|
|
613
|
+
|
|
614
|
+
Mac | Windows | Linux
|
|
615
|
+
----|---------|------
|
|
616
|
+
 |  | 
|
|
617
|
+
|
|
618
|
+
### Scaffold Application
|
|
619
|
+
|
|
620
|
+
Application scaffolding enables automatically generating the directories/files of a new desktop GUI application that follows the MVC architecture and can be packaged as a Ruby gem that includes a binary script for running the app conveniently.
|
|
621
|
+
|
|
622
|
+
Scaffold Glimmer DSL for LibUI application with this command:
|
|
623
|
+
|
|
624
|
+
```
|
|
625
|
+
glimmer "scaffold[app_name]"
|
|
626
|
+
```
|
|
627
|
+
|
|
628
|
+
That will generate the general MVC structure of a new Glimmer DSL for LibUI application.
|
|
629
|
+
|
|
630
|
+
For example, if we run:
|
|
631
|
+
|
|
632
|
+
```
|
|
633
|
+
glimmer "scaffold[hello_world]"
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
The following files are generated and reported by the `glimmer` command:
|
|
637
|
+
|
|
638
|
+
```
|
|
639
|
+
Created hello_world/.gitignore
|
|
640
|
+
Created hello_world/.ruby-version
|
|
641
|
+
Created hello_world/.ruby-gemset
|
|
642
|
+
Created hello_world/VERSION
|
|
643
|
+
Created hello_world/LICENSE.txt
|
|
644
|
+
Created hello_world/Gemfile
|
|
645
|
+
Created hello_world/Rakefile
|
|
646
|
+
Created hello_world/app/hello_world.rb
|
|
647
|
+
Created hello_world/app/hello_world/view/hello_world.rb
|
|
648
|
+
Created hello_world/icons/windows/Hello World.ico
|
|
649
|
+
Created hello_world/icons/macosx/Hello World.icns
|
|
650
|
+
Created hello_world/icons/linux/Hello World.png
|
|
651
|
+
Created hello_world/app/hello_world/launch.rb
|
|
652
|
+
Created hello_world/bin/hello_world
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
They include a basic Hello, World! application with menus and about/preferences dialogs.
|
|
656
|
+
|
|
657
|
+
Views live under `app/app_name/view` (e.g. `app/hello_world/view`)
|
|
658
|
+
Models live under `app/app_name/model` (e.g. `app/hello_world/model`)
|
|
659
|
+
|
|
660
|
+
Once you step into the application directory, you can run it in one of multiple ways:
|
|
661
|
+
|
|
662
|
+
```
|
|
663
|
+
bin/app_name
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
For example:
|
|
667
|
+
|
|
668
|
+
```
|
|
669
|
+
bin/hello_world
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
Or using the Glimmer generic command for running applications, which will automatically detect the application running script:
|
|
673
|
+
|
|
674
|
+
```
|
|
675
|
+
glimmer run
|
|
676
|
+
```
|
|
677
|
+
|
|
678
|
+
|
|
679
|
+
|
|
680
|
+
|
|
681
|
+
|
|
682
|
+
|
|
683
|
+
|
|
684
|
+
The application comes with `juwelier` for auto-generating an application gem from its `Rakefile` gem configuration.
|
|
685
|
+
|
|
686
|
+
You can package the newly scaffolded app as a Ruby gem by running this command:
|
|
687
|
+
|
|
688
|
+
```
|
|
689
|
+
rake build
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
You can generate the application gemspec explicitly if needed with this command (though it is not needed to build the gem):
|
|
693
|
+
|
|
694
|
+
```
|
|
695
|
+
rake gemspec:generate
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
Once you install the gem (e.g. `gem install hello_world`), you can simply run the app with its binary script:
|
|
699
|
+
|
|
700
|
+
```
|
|
701
|
+
app_name
|
|
702
|
+
```
|
|
703
|
+
|
|
704
|
+
For example:
|
|
705
|
+
|
|
706
|
+
```
|
|
707
|
+
hello_world
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
|
|
711
|
+
|
|
712
|
+
## Girb (Glimmer IRB)
|
|
713
|
+
|
|
714
|
+
You can run the `girb` command (`bin/girb` if you cloned the project locally) to do some quick and dirty experimentation and learning:
|
|
715
|
+
|
|
716
|
+
```
|
|
717
|
+
girb
|
|
718
|
+
```
|
|
719
|
+
|
|
720
|
+
This gives you `irb` with the `glimmer-dsl-libui` gem loaded and the `Glimmer` module mixed into the main object for easy experimentation with GUI.
|
|
721
|
+
|
|
722
|
+
|
|
723
|
+
|
|
724
|
+
For a more advanced code editing tool, check out the [Meta-Example (The Example of Examples)](#examples).
|
|
725
|
+
|
|
726
|
+
Gotcha: On the Mac, when you close a window opened in `girb`, it remains open until you enter `exit` or open another GUI window.
|
|
727
|
+
|
|
403
728
|
## Glimmer GUI DSL Concepts
|
|
404
729
|
|
|
405
730
|
The Glimmer GUI DSL provides object-oriented declarative hierarchical syntax for [LibUI](https://github.com/kojix2/LibUI) that:
|
|
@@ -523,115 +848,6 @@ window('hello world', 300, 200) {
|
|
|
523
848
|
end
|
|
524
849
|
}.show
|
|
525
850
|
```
|
|
526
|
-
|
|
527
|
-
## Usage
|
|
528
|
-
|
|
529
|
-
Install [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui) gem directly into a [maintained Ruby version](https://www.ruby-lang.org/en/downloads/):
|
|
530
|
-
|
|
531
|
-
```
|
|
532
|
-
gem install glimmer-dsl-libui
|
|
533
|
-
```
|
|
534
|
-
|
|
535
|
-
Or install via Bundler `Gemfile`:
|
|
536
|
-
|
|
537
|
-
```ruby
|
|
538
|
-
gem 'glimmer-dsl-libui', '~> 0.8.0'
|
|
539
|
-
```
|
|
540
|
-
|
|
541
|
-
Test that installation worked by running the [Meta-Example](#examples):
|
|
542
|
-
|
|
543
|
-
```
|
|
544
|
-
ruby -r glimmer-dsl-libui -e "require 'examples/meta_example'"
|
|
545
|
-
```
|
|
546
|
-
|
|
547
|
-
Mac | Windows | Linux
|
|
548
|
-
----|---------|------
|
|
549
|
-
 |  | 
|
|
550
|
-
|
|
551
|
-
Now to use [glimmer-dsl-libui](https://rubygems.org/gems/glimmer-dsl-libui), add `require 'glimmer-dsl-libui'` at the top.
|
|
552
|
-
|
|
553
|
-
Afterwards, `include Glimmer` into the top-level main object for testing or into an actual class for serious usage.
|
|
554
|
-
|
|
555
|
-
Alternatively, `include Glimmer::LibUI::Application` to conveniently declare the GUI `body` and run via the `::launch` method (`Glimmer::LibUI::Application` is an alias for `Glimmer::LibUI::CustomWindow` since that is what it represents).
|
|
556
|
-
|
|
557
|
-
Example including `Glimmer::LibUI::Application` (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
558
|
-
|
|
559
|
-
```ruby
|
|
560
|
-
require 'glimmer-dsl-libui'
|
|
561
|
-
|
|
562
|
-
class SomeGlimmerApp
|
|
563
|
-
include Glimmer::LibUI::Application
|
|
564
|
-
|
|
565
|
-
body {
|
|
566
|
-
window('hello world', 300, 200) {
|
|
567
|
-
button('Button') {
|
|
568
|
-
on_clicked do
|
|
569
|
-
puts 'Button Clicked'
|
|
570
|
-
end
|
|
571
|
-
}
|
|
572
|
-
}
|
|
573
|
-
}
|
|
574
|
-
end
|
|
575
|
-
|
|
576
|
-
SomeGlimmerApp.launch
|
|
577
|
-
```
|
|
578
|
-
|
|
579
|
-
Example including `Glimmer` and manually implementing the `#launch` method (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
580
|
-
|
|
581
|
-
```ruby
|
|
582
|
-
require 'glimmer-dsl-libui'
|
|
583
|
-
|
|
584
|
-
class SomeGlimmerApp
|
|
585
|
-
include Glimmer
|
|
586
|
-
|
|
587
|
-
def launch
|
|
588
|
-
window('hello world', 300, 200) {
|
|
589
|
-
button('Button') {
|
|
590
|
-
on_clicked do
|
|
591
|
-
puts 'Button Clicked'
|
|
592
|
-
end
|
|
593
|
-
}
|
|
594
|
-
}.show
|
|
595
|
-
end
|
|
596
|
-
end
|
|
597
|
-
|
|
598
|
-
SomeGlimmerApp.new.launch
|
|
599
|
-
```
|
|
600
|
-
|
|
601
|
-
Example including `Glimmer` at the top-level scope just for some prototyping/demoing/testing (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
602
|
-
|
|
603
|
-
```ruby
|
|
604
|
-
require 'glimmer-dsl-libui'
|
|
605
|
-
|
|
606
|
-
include Glimmer
|
|
607
|
-
|
|
608
|
-
window('hello world', 300, 200) {
|
|
609
|
-
button('Button') {
|
|
610
|
-
on_clicked do
|
|
611
|
-
puts 'Button Clicked'
|
|
612
|
-
end
|
|
613
|
-
}
|
|
614
|
-
}.show
|
|
615
|
-
```
|
|
616
|
-
|
|
617
|
-
If you are new to [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui), check out [Girb](#girb-glimmer-irb) and [Examples](#examples) to quickly learn through copy/paste. You may refer to the [API](#api) later on once you have gotten your feet wet with [Glimmer DSL for LibUI](https://rubygems.org/gems/glimmer-dsl-libui) and need more detailed reference information.
|
|
618
|
-
|
|
619
|
-
## Girb (Glimmer IRB)
|
|
620
|
-
|
|
621
|
-
You can run the `girb` command (`bin/girb` if you cloned the project locally) to do some quick and dirty experimentation and learning:
|
|
622
|
-
|
|
623
|
-
```
|
|
624
|
-
girb
|
|
625
|
-
```
|
|
626
|
-
|
|
627
|
-
This gives you `irb` with the `glimmer-dsl-libui` gem loaded and the `Glimmer` module mixed into the main object for easy experimentation with GUI.
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
For a more advanced code editing tool, check out the [Meta-Example (The Example of Examples)](#examples).
|
|
632
|
-
|
|
633
|
-
Gotcha: On the Mac, when you close a window opened in `girb`, it remains open until you enter `exit` or open another GUI window.
|
|
634
|
-
|
|
635
851
|
## API
|
|
636
852
|
|
|
637
853
|
Any control returned by a [Glimmer GUI DSL](#glimmer-gui-dsl-concepts) keyword declaration can be introspected for its properties and updated via object-oriented attributes (standard Ruby `attr`/`attr=` or `set_attr`).
|
|
@@ -1565,7 +1781,7 @@ specify values for `fill`, `stroke`, or `transform` (though if they do, they ove
|
|
|
1565
1781
|
When you use the `include?(x, y)` or `contain?(x, y)` method on a composite `shape`, it automatically includes all its aggregated shapes
|
|
1566
1782
|
in the inclusion or containment check using the corresponding [PerfectShape](https://github.com/AndyObtiva/perfect-shape) object.
|
|
1567
1783
|
|
|
1568
|
-
Example of a `cube` method-based custom
|
|
1784
|
+
Example of a `cube` method-based custom shape built using the composite `shape` keyword:
|
|
1569
1785
|
|
|
1570
1786
|
|
|
1571
1787
|
|
|
@@ -1851,17 +2067,21 @@ SpinnerExample.new.launch
|
|
|
1851
2067
|
- Colors may be passed in as a hash of `:r`, `:g`, `:b`, `:a`, or `:red`, `:green`, `:blue`, `:alpha`, or [X11](https://en.wikipedia.org/wiki/X11_color_names) color like `:skyblue`, or 6-char hex or 3-char hex (as `Integer` or `String` with or without `0x` prefix)
|
|
1852
2068
|
- Color alpha value defaults to `1.0` when not specified.
|
|
1853
2069
|
|
|
1854
|
-
### Custom
|
|
2070
|
+
### Custom Controls
|
|
1855
2071
|
|
|
1856
|
-
Custom
|
|
2072
|
+
Custom controls can be defined to represent custom controls (components) that provide new features or act as composites of [existing controls](#supported-keywords) that need to be reused multiple times in an application or across multiple applications. Custom controls save a lot of development time, improving productivity and maintainability immensely.
|
|
1857
2073
|
|
|
1858
2074
|
For example, you can define a custom `address_view` control as an aggregate of multiple `label` controls to reuse multiple times as a standard address View, displaying street, city, state, and zip code.
|
|
1859
2075
|
|
|
1860
|
-
There are two ways to define custom
|
|
2076
|
+
There are two ways to define custom controls:
|
|
1861
2077
|
- Method-Based: simply define a method representing the custom control you want (e.g. `address_view`) with any arguments needed (e.g. `address(address_model)`).
|
|
1862
2078
|
- Class-Based: define a class matching the camelcased name of the custom control by convention (e.g. the `address_view` custom control keyword would have a class called `AddressView`) and `include Glimmer::LibUI::CustomControl`. Classes add the benefit of being able to distribute the custom controls into separate files and reuse externally from multiple places or share via Ruby gems.
|
|
1863
2079
|
|
|
1864
|
-
It is OK to use the terms "custom
|
|
2080
|
+
It is OK to use the terms "custom control" and "custom keyword" synonymously though "custom keyword" is a broader term that covers things other than controls too like custom shapes (e.g. `cylinder`), custom attributed strings (e.g. `alternating_color_string`), and custom transforms (`isometric_transform`).
|
|
2081
|
+
|
|
2082
|
+
#### Method-Based Custom Controls
|
|
2083
|
+
|
|
2084
|
+
Simply define a method representing the custom control you want (e.g. `address_view`) with any arguments needed (e.g. `address(address_model)`).
|
|
1865
2085
|
|
|
1866
2086
|
Example that defines `form_field`, `address_form`, `label_pair`, and `address_view` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
1867
2087
|
|
|
@@ -1960,7 +2180,9 @@ window('Method-Based Custom Keyword') {
|
|
|
1960
2180
|
|
|
1961
2181
|
|
|
1962
2182
|
|
|
1963
|
-
|
|
2183
|
+
#### Class-Based Custom Controls
|
|
2184
|
+
|
|
2185
|
+
Define a class matching the camelcased name of the custom control by convention (e.g. the `address_view` custom control keyword would have a class called `AddressView`) and `include Glimmer::LibUI::CustomControl`. Classes add the benefit of being able to distribute the custom controls into separate files and reuse externally from multiple places or share via Ruby gems.
|
|
1964
2186
|
|
|
1965
2187
|
Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
1966
2188
|
|
|
@@ -2090,11 +2312,13 @@ ClassBasedCustomControls.launch
|
|
|
2090
2312
|
|
|
2091
2313
|
|
|
2092
2314
|
|
|
2315
|
+
You can also define Custom Window keywords, that is custom controls with `window` being the body root. These are also known as Applications. To define a Custom Window, you `include Glimmer::LibUI::CustomWindow` or `include Glimmer:LibUI::Application` and then you can invoke the `::launch` method on the class.
|
|
2316
|
+
|
|
2093
2317
|
The [`area`](#area-api) control can be utilized to build non-native custom controls from scratch by leveraging vector graphics, formattable text, keyboard events, and mouse events. This is demonstrated in the [Area-Based Custom Controls](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#area-based-custom-controls) example.
|
|
2094
2318
|
|
|
2095
|
-
Defining custom
|
|
2319
|
+
Defining custom controls enables unlimited extension of the [Glimmer GUI DSL](#glimmer-gui-dsl). The sky is the limit on what can be done with custom controls as a result. You can compose new visual vocabulary to build applications in any domain from higher concepts rather than [mere standard controls](#supported-keywords). For example, in a traffic signaling app, you could define `street`, `light_signal`, `traffic_sign`, and `car` as custom keywords and build your application from these concepts directly, saving enormous time and achieving much higher productivity.
|
|
2096
2320
|
|
|
2097
|
-
Learn more from custom
|
|
2321
|
+
Learn more from custom control usage in [Method-Based Custom Keyword](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#method-based-custom-keyword), [Area-Based Custom Controls](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#area-based-custom-controls), [Basic Scrolling Area](/docs/examples/GLIMMER-DSL-LIBUI-BASIC-EXAMPLES.md#basic-scrolling-area), [Histogram](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#histogram), and [Tetris](/docs/examples/GLIMMER-DSL-LIBUI-ADVANCED-EXAMPLES.md#tetris) examples.
|
|
2098
2322
|
|
|
2099
2323
|
### Observer Pattern
|
|
2100
2324
|
|
|
@@ -2404,7 +2628,8 @@ Learn more from data-binding usage in [Login](/docs/examples/GLIMMER-DSL-LIBUI-A
|
|
|
2404
2628
|
- `text` `string` `background` does not work on Windows due to an [issue in libui](https://github.com/andlabs/libui/issues/347).
|
|
2405
2629
|
- `table` `progress_bar` column on Windows cannot be updated with a positive value if it started initially with `-1` (it ignores update to avoid crashing due to an issue in [libui](https://github.com/andlabs/libui) on Windows.
|
|
2406
2630
|
- `radio_buttons` on Linux has an issue where it always selects the first item even if you did not set its `selected` value or set it to `-1` (meaning unselected). It works correctly on Mac and Windows.
|
|
2407
|
-
- It seems that [libui](https://github.com/
|
|
2631
|
+
- It seems that [libui](https://github.com/libui-ng/libui-ng) does not support nesting multiple `area` controls under a `grid` as only the first one shows up in that scenario. To workaround that limitation, use a `vertical_box` with nested `horizontal_box`s instead to include multiple `area`s in a GUI.
|
|
2632
|
+
- Both `multiline_entry` and `non_wrapping_multiline_entry` do not seem to play well with being nested in a `grid`. To get around the problem, I would use a combination of `vertical_box` and `horizontal_box`s instead.
|
|
2408
2633
|
- As per the code of [examples/basic_transform.rb](/docs/examples/GLIMMER-DSL-LIBUI-BASIC-EXAMPLES.md#basic-transform), Windows requires different ordering of transforms than Mac and Linux.
|
|
2409
2634
|
- `scrolling_area#scroll_to` does not seem to work on Windows and Linux, but works fine on Mac
|
|
2410
2635
|
|
|
@@ -2422,7 +2647,7 @@ To learn more about the [LibUI](https://github.com/kojix2/LibUI) API exposed thr
|
|
|
2422
2647
|
|
|
2423
2648
|
I am documenting options for packaging, which I have not tried myself, but figured they would still be useful to add to the README.md until I can expand further effort into supporting packaging.
|
|
2424
2649
|
|
|
2425
|
-
For Windows, the [LibUI](https://github.com/kojix2/LibUI) project recommends [OCRA](https://github.com/larsch/ocra) (One-Click Ruby Application), which builds Windows executables from Ruby source.
|
|
2650
|
+
For Windows, the [LibUI](https://github.com/kojix2/LibUI) project recommends [OCRA](https://github.com/larsch/ocra) (One-Click Ruby Application), which builds Windows executables from Ruby source. And, there is a newer fork of the project that supports newer versions of Ruby called [OCRAN](https://github.com/Largo/ocran).
|
|
2426
2651
|
|
|
2427
2652
|
For Mac, consider [Platypus](https://github.com/sveinbjornt/Platypus) (builds a native Mac app from a Ruby script)
|
|
2428
2653
|
|
|
@@ -2430,6 +2655,8 @@ For Linux, simply package your app as a [Ruby Gem](https://guides.rubygems.org/w
|
|
|
2430
2655
|
|
|
2431
2656
|
Also, there is a promising project called [ruby-packer](https://github.com/pmq20/ruby-packer) that supports all platforms.
|
|
2432
2657
|
|
|
2658
|
+
Last but not least, Ruby recently supported WASM, including the ability to [package a Ruby application as a WASI application](https://github.com/ruby/ruby.wasm#quick-example-how-to-package-your-ruby-application-as-a-wasi-application).
|
|
2659
|
+
|
|
2433
2660
|
## Glimmer Style Guide
|
|
2434
2661
|
|
|
2435
2662
|
**1 - Control arguments are always wrapped by parentheses.**
|
|
@@ -2838,6 +3065,12 @@ https://github.com/kojix2/htsgrid
|
|
|
2838
3065
|
|
|
2839
3066
|
|
|
2840
3067
|
|
|
3068
|
+
### Electric Avenue
|
|
3069
|
+
|
|
3070
|
+
This is built as an exploratory software prototype by [Ari Brown](https://github.com/seydar) (closed source software).
|
|
3071
|
+
|
|
3072
|
+
|
|
3073
|
+
|
|
2841
3074
|
## Process
|
|
2842
3075
|
|
|
2843
3076
|
[Glimmer Process](https://github.com/AndyObtiva/glimmer/blob/master/PROCESS.md)
|
data/RUBY_VERSION
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.2.2
|
data/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.
|
|
1
|
+
0.9.1
|