glimmer-dsl-libui 0.8.0 → 0.9.1
Sign up to get free protection for your applications and to get access to all the features.
- 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
|