glimmer-dsl-libui 0.8.0 → 0.9.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +5 -1
- data/README.md +230 -125
- data/VERSION +1 -1
- data/bin/girb +1 -1
- data/bin/glimmer +30 -0
- data/glimmer-dsl-libui.gemspec +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 +839 -0
- data/lib/glimmer/rake_task.rb +192 -0
- metadata +41 -12
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 7e8beebaf4e3c91450a4ae20b619b63a6303e67c82ae6a678f5f509f69a4310c
|
|
4
|
+
data.tar.gz: c2a4f231d85faf7a70fbc96572458b53007b1cd3865f2fe330fca379fd379c74
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: ec4010baf04afde8b8c2312c081af0ae748748869ee19dbdf1bb5ea92d627abbd5d89d87db8a135ba158b56fc4bb28291f2e572e728aaad728c3ca43dcfe5ed2
|
|
7
|
+
data.tar.gz: b4e2c8f38655b60b35a12fd55a634ef706c838a28d622677f86159c931b2ef548f744cf804b26b11d0a696b8fa2a6e4d44fa5118582af44814dee8b3db15a435
|
data/CHANGELOG.md
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
# Change Log
|
|
2
2
|
|
|
3
|
+
## 0.9.0
|
|
4
|
+
|
|
5
|
+
- Support `glimmer` command to more conveniently run applications (`glimmer app_path`) and examples (`glimmer examples`)
|
|
6
|
+
|
|
3
7
|
## 0.8.0
|
|
4
8
|
|
|
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`
|
|
9
|
+
- 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
10
|
- 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
11
|
- Invert `Glimmer::LibUI::ControlProxy::KEYWORD_ALIASES` to enable adding multiple aliases per keyword
|
|
8
12
|
- 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
|
|
|
@@ -342,9 +342,13 @@ 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)
|
|
347
350
|
- [Girb (Glimmer IRB)](#girb-glimmer-irb)
|
|
351
|
+
- [Glimmer GUI DSL Concepts](#glimmer-gui-dsl-concepts)
|
|
348
352
|
- [API](#api)
|
|
349
353
|
- [Supported Keywords](#supported-keywords)
|
|
350
354
|
- [Common Control Properties](#common-control-properties)
|
|
@@ -366,7 +370,9 @@ Learn more about the differences between various [Glimmer](https://github.com/An
|
|
|
366
370
|
- [Area Composite Shape](#area-composite-shape)
|
|
367
371
|
- [Area Animation](#area-animation)
|
|
368
372
|
- [Smart Defaults and Conventions](#smart-defaults-and-conventions)
|
|
369
|
-
- [Custom
|
|
373
|
+
- [Custom Controls](#custom-controls)
|
|
374
|
+
- [Method-Based Custom Controls](#method-based-custom-controls)
|
|
375
|
+
- [Class-Based Custom Controls](#class-based-custom-controls)
|
|
370
376
|
- [Observer Pattern](#observer-pattern)
|
|
371
377
|
- [Data-Binding](#data-binding)
|
|
372
378
|
- [Bidirectional (Two-Way) Data-Binding](#bidirectional-two-way-data-binding)
|
|
@@ -400,6 +406,197 @@ Learn more about the differences between various [Glimmer](https://github.com/An
|
|
|
400
406
|
- [Contributors](#contributors)
|
|
401
407
|
- [License](#license)
|
|
402
408
|
|
|
409
|
+
## Setup
|
|
410
|
+
|
|
411
|
+
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/):
|
|
412
|
+
|
|
413
|
+
```
|
|
414
|
+
gem install glimmer-dsl-libui
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
Or install via Bundler `Gemfile`:
|
|
418
|
+
|
|
419
|
+
```ruby
|
|
420
|
+
gem 'glimmer-dsl-libui', '~> 0.9.0'
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
Test that installation worked by running the [Glimmer Meta-Example](#examples):
|
|
424
|
+
|
|
425
|
+
```
|
|
426
|
+
glimmer examples
|
|
427
|
+
```
|
|
428
|
+
|
|
429
|
+
Or alternatively, run using the explicit Ruby command:
|
|
430
|
+
|
|
431
|
+
```
|
|
432
|
+
ruby -r glimmer-dsl-libui -e "require 'examples/meta_example'"
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
Mac | Windows | Linux
|
|
436
|
+
----|---------|------
|
|
437
|
+
 |  | 
|
|
438
|
+
|
|
439
|
+
## Usage
|
|
440
|
+
|
|
441
|
+
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.
|
|
442
|
+
|
|
443
|
+
### Experimentation Usage
|
|
444
|
+
|
|
445
|
+
For experimenting and learning, add `include Glimmer` into the top-level main object and start using the Glimmer GUI DSL directly.
|
|
446
|
+
|
|
447
|
+
Example including `Glimmer` at the top-level scope just for some prototyping/demoing/testing (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
448
|
+
|
|
449
|
+
```ruby
|
|
450
|
+
require 'glimmer-dsl-libui'
|
|
451
|
+
|
|
452
|
+
include Glimmer
|
|
453
|
+
|
|
454
|
+
window('hello world', 300, 200) {
|
|
455
|
+
button('Button') {
|
|
456
|
+
on_clicked do
|
|
457
|
+
puts 'Button Clicked'
|
|
458
|
+
end
|
|
459
|
+
}
|
|
460
|
+
}.show
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
|
|
464
|
+
|
|
465
|
+
### Prototyping Usage
|
|
466
|
+
|
|
467
|
+
For prototyping, add `include Glimmer` into an actual class and start using the Glimmer GUI DSL in instance methods.
|
|
468
|
+
|
|
469
|
+
Example including `Glimmer` and manually implementing the `#launch` method (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
470
|
+
|
|
471
|
+
```ruby
|
|
472
|
+
require 'glimmer-dsl-libui'
|
|
473
|
+
|
|
474
|
+
class SomeGlimmerApp
|
|
475
|
+
include Glimmer
|
|
476
|
+
|
|
477
|
+
def launch
|
|
478
|
+
window('hello world', 300, 200) {
|
|
479
|
+
button('Button') {
|
|
480
|
+
on_clicked do
|
|
481
|
+
puts 'Button Clicked'
|
|
482
|
+
end
|
|
483
|
+
}
|
|
484
|
+
}.show
|
|
485
|
+
end
|
|
486
|
+
end
|
|
487
|
+
|
|
488
|
+
SomeGlimmerApp.new.launch
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
|
|
492
|
+
|
|
493
|
+
### Serious Usage
|
|
494
|
+
|
|
495
|
+
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.
|
|
496
|
+
|
|
497
|
+
Example including `Glimmer::LibUI::Application` (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
498
|
+
|
|
499
|
+
```ruby
|
|
500
|
+
require 'glimmer-dsl-libui'
|
|
501
|
+
|
|
502
|
+
class SomeGlimmerApp
|
|
503
|
+
include Glimmer::LibUI::Application
|
|
504
|
+
|
|
505
|
+
body {
|
|
506
|
+
window('hello world', 300, 200) {
|
|
507
|
+
button('Button') {
|
|
508
|
+
on_clicked do
|
|
509
|
+
puts 'Button Clicked'
|
|
510
|
+
end
|
|
511
|
+
}
|
|
512
|
+
}
|
|
513
|
+
}
|
|
514
|
+
end
|
|
515
|
+
|
|
516
|
+
SomeGlimmerApp.launch
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
|
|
520
|
+
|
|
521
|
+
(note: `Glimmer::LibUI::Application` is an alias for `Glimmer::LibUI::CustomWindow` since that is what it represents)
|
|
522
|
+
|
|
523
|
+
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.
|
|
524
|
+
|
|
525
|
+
|
|
526
|
+
## Glimmer Command
|
|
527
|
+
|
|
528
|
+
The `glimmer` command allows you to conveniently:
|
|
529
|
+
- Run Glimmer DSL for LibUI applications (via `glimmer [app_path]`)
|
|
530
|
+
- Run Glimmer DSL for LibUI included examples (via `glimmer examples`, which brings up the [Glimmer Meta-Example](https://github.com/AndyObtiva/glimmer-dsl-libui/blob/master/examples/meta_example.rb))
|
|
531
|
+
|
|
532
|
+
You can bring up usage instructions by running the `glimmer` command without arguments:
|
|
533
|
+
|
|
534
|
+
```
|
|
535
|
+
glimmer
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
```
|
|
539
|
+
% bin/glimmer
|
|
540
|
+
Glimmer DSL for LibUI (Prerequisite-Free Ruby Desktop Development Cross-Platform Native GUI Library) - Ruby Gem: glimmer-dsl-libui v0.8.0
|
|
541
|
+
|
|
542
|
+
Usage: glimmer [--bundler] [--pd] [--quiet] [--debug] [--log-level=VALUE] [[ENV_VAR=VALUE]...] [[-ruby-option]...] (application.rb or task[task_args])
|
|
543
|
+
|
|
544
|
+
Runs Glimmer applications and tasks.
|
|
545
|
+
|
|
546
|
+
When applications are specified, they are run using Ruby,
|
|
547
|
+
automatically preloading the glimmer-dsl-libui Ruby gem.
|
|
548
|
+
|
|
549
|
+
Optionally, extra Glimmer options, Ruby options, and/or environment variables may be passed in.
|
|
550
|
+
|
|
551
|
+
Glimmer options:
|
|
552
|
+
- "--bundler=GROUP" : Activates gems in Bundler default group in Gemfile
|
|
553
|
+
- "--pd=BOOLEAN" : Requires puts_debuggerer to enable pd method
|
|
554
|
+
- "--quiet=BOOLEAN" : Does not announce file path of Glimmer application being launched
|
|
555
|
+
- "--debug" : Displays extra debugging information and enables debug logging
|
|
556
|
+
- "--log-level=VALUE" : Sets Glimmer's Ruby logger level ("ERROR" / "WARN" / "INFO" / "DEBUG"; default is none)
|
|
557
|
+
|
|
558
|
+
Tasks are run via rake. Some tasks take arguments in square brackets (surround with double-quotes if using Zsh).
|
|
559
|
+
|
|
560
|
+
Available tasks are below (if you do not see any, please add `require 'glimmer/rake_task'` to Rakefile and rerun or run rake -T):
|
|
561
|
+
|
|
562
|
+
Select a Glimmer task to run: (Press ↑/↓ arrow to move, Enter to select and letters to filter)
|
|
563
|
+
‣ glimmer examples # Brings up the Glimmer Meta-Sample app to allow browsing, running, and viewing code of Glimmer samples
|
|
564
|
+
glimmer list:gems:customcontrol[query] # List Glimmer custom control gems available at rubygems.org (query is optional) [alt: list:gems:cc]
|
|
565
|
+
glimmer list:gems:customshape[query] # List Glimmer custom shape gems available at rubygems.org (query is optional) [alt: list:gems:cs]
|
|
566
|
+
glimmer list:gems:customwindow[query] # List Glimmer custom window gems available at rubygems.org (query is optional) [alt: list:gems:cw]
|
|
567
|
+
glimmer list:gems:dsl[query] # List Glimmer DSL gems available at rubygems.org (query is optional)
|
|
568
|
+
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)
|
|
569
|
+
glimmer scaffold[app_name] # Scaffold Glimmer application directory structure to build a new app
|
|
570
|
+
glimmer scaffold:customcontrol[name,namespace] # Scaffold Glimmer::UI::CustomControl subclass (part of a view) under app/views (namespace is optional) [alt: scaffold:cc]
|
|
571
|
+
glimmer scaffold:customshape[name,namespace] # Scaffold Glimmer::UI::CustomShape subclass (part of a view) under app/views (namespace is optional) [alt: scaffold:cs]
|
|
572
|
+
glimmer scaffold:customwindow[name,namespace] # Scaffold Glimmer::UI::CustomWindow subclass (full window view) under app/views (namespace is optional) [alt: scaffold:cw]
|
|
573
|
+
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]
|
|
574
|
+
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]
|
|
575
|
+
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]
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
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)).
|
|
579
|
+
|
|
580
|
+
On Windows and ARM64 machines, it simply lists the available Glimmer tasks at the end (courtsey of [rake](https://github.com/ruby/rake)).
|
|
581
|
+
|
|
582
|
+
Note: If you encounter an issue running the `glimmer` command, run `bundle exec glimmer` instead.
|
|
583
|
+
|
|
584
|
+
## Girb (Glimmer IRB)
|
|
585
|
+
|
|
586
|
+
You can run the `girb` command (`bin/girb` if you cloned the project locally) to do some quick and dirty experimentation and learning:
|
|
587
|
+
|
|
588
|
+
```
|
|
589
|
+
girb
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
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.
|
|
593
|
+
|
|
594
|
+
|
|
595
|
+
|
|
596
|
+
For a more advanced code editing tool, check out the [Meta-Example (The Example of Examples)](#examples).
|
|
597
|
+
|
|
598
|
+
Gotcha: On the Mac, when you close a window opened in `girb`, it remains open until you enter `exit` or open another GUI window.
|
|
599
|
+
|
|
403
600
|
## Glimmer GUI DSL Concepts
|
|
404
601
|
|
|
405
602
|
The Glimmer GUI DSL provides object-oriented declarative hierarchical syntax for [LibUI](https://github.com/kojix2/LibUI) that:
|
|
@@ -523,115 +720,6 @@ window('hello world', 300, 200) {
|
|
|
523
720
|
end
|
|
524
721
|
}.show
|
|
525
722
|
```
|
|
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
723
|
## API
|
|
636
724
|
|
|
637
725
|
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 +1653,7 @@ specify values for `fill`, `stroke`, or `transform` (though if they do, they ove
|
|
|
1565
1653
|
When you use the `include?(x, y)` or `contain?(x, y)` method on a composite `shape`, it automatically includes all its aggregated shapes
|
|
1566
1654
|
in the inclusion or containment check using the corresponding [PerfectShape](https://github.com/AndyObtiva/perfect-shape) object.
|
|
1567
1655
|
|
|
1568
|
-
Example of a `cube` method-based custom
|
|
1656
|
+
Example of a `cube` method-based custom shape built using the composite `shape` keyword:
|
|
1569
1657
|
|
|
1570
1658
|
|
|
1571
1659
|
|
|
@@ -1851,17 +1939,21 @@ SpinnerExample.new.launch
|
|
|
1851
1939
|
- 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
1940
|
- Color alpha value defaults to `1.0` when not specified.
|
|
1853
1941
|
|
|
1854
|
-
### Custom
|
|
1942
|
+
### Custom Controls
|
|
1855
1943
|
|
|
1856
|
-
Custom
|
|
1944
|
+
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
1945
|
|
|
1858
1946
|
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
1947
|
|
|
1860
|
-
There are two ways to define custom
|
|
1948
|
+
There are two ways to define custom controls:
|
|
1861
1949
|
- 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
1950
|
- 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
1951
|
|
|
1864
|
-
It is OK to use the terms "custom
|
|
1952
|
+
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`).
|
|
1953
|
+
|
|
1954
|
+
#### Method-Based Custom Controls
|
|
1955
|
+
|
|
1956
|
+
Simply define a method representing the custom control you want (e.g. `address_view`) with any arguments needed (e.g. `address(address_model)`).
|
|
1865
1957
|
|
|
1866
1958
|
Example that defines `form_field`, `address_form`, `label_pair`, and `address_view` keywords (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
1867
1959
|
|
|
@@ -1960,7 +2052,9 @@ window('Method-Based Custom Keyword') {
|
|
|
1960
2052
|
|
|
1961
2053
|
|
|
1962
2054
|
|
|
1963
|
-
|
|
2055
|
+
#### Class-Based Custom Controls
|
|
2056
|
+
|
|
2057
|
+
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
2058
|
|
|
1965
2059
|
Example (you may copy/paste in [`girb`](#girb-glimmer-irb)):
|
|
1966
2060
|
|
|
@@ -2090,11 +2184,13 @@ ClassBasedCustomControls.launch
|
|
|
2090
2184
|
|
|
2091
2185
|
|
|
2092
2186
|
|
|
2187
|
+
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.
|
|
2188
|
+
|
|
2093
2189
|
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
2190
|
|
|
2095
|
-
Defining custom
|
|
2191
|
+
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
2192
|
|
|
2097
|
-
Learn more from custom
|
|
2193
|
+
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
2194
|
|
|
2099
2195
|
### Observer Pattern
|
|
2100
2196
|
|
|
@@ -2404,7 +2500,8 @@ Learn more from data-binding usage in [Login](/docs/examples/GLIMMER-DSL-LIBUI-A
|
|
|
2404
2500
|
- `text` `string` `background` does not work on Windows due to an [issue in libui](https://github.com/andlabs/libui/issues/347).
|
|
2405
2501
|
- `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
2502
|
- `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/
|
|
2503
|
+
- 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.
|
|
2504
|
+
- 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
2505
|
- 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
2506
|
- `scrolling_area#scroll_to` does not seem to work on Windows and Linux, but works fine on Mac
|
|
2410
2507
|
|
|
@@ -2422,7 +2519,7 @@ To learn more about the [LibUI](https://github.com/kojix2/LibUI) API exposed thr
|
|
|
2422
2519
|
|
|
2423
2520
|
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
2521
|
|
|
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.
|
|
2522
|
+
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
2523
|
|
|
2427
2524
|
For Mac, consider [Platypus](https://github.com/sveinbjornt/Platypus) (builds a native Mac app from a Ruby script)
|
|
2428
2525
|
|
|
@@ -2430,6 +2527,8 @@ For Linux, simply package your app as a [Ruby Gem](https://guides.rubygems.org/w
|
|
|
2430
2527
|
|
|
2431
2528
|
Also, there is a promising project called [ruby-packer](https://github.com/pmq20/ruby-packer) that supports all platforms.
|
|
2432
2529
|
|
|
2530
|
+
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).
|
|
2531
|
+
|
|
2433
2532
|
## Glimmer Style Guide
|
|
2434
2533
|
|
|
2435
2534
|
**1 - Control arguments are always wrapped by parentheses.**
|
|
@@ -2838,6 +2937,12 @@ https://github.com/kojix2/htsgrid
|
|
|
2838
2937
|
|
|
2839
2938
|
|
|
2840
2939
|
|
|
2940
|
+
### Electric Avenue
|
|
2941
|
+
|
|
2942
|
+
This is built as an exploratory software prototype by [Ari Brown](https://github.com/seydar) (closed source software).
|
|
2943
|
+
|
|
2944
|
+
|
|
2945
|
+
|
|
2841
2946
|
## Process
|
|
2842
2947
|
|
|
2843
2948
|
[Glimmer Process](https://github.com/AndyObtiva/glimmer/blob/master/PROCESS.md)
|
data/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.
|
|
1
|
+
0.9.0
|
data/bin/girb
CHANGED
data/bin/glimmer
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
#!/usr/bin/env ruby
|
|
2
|
+
|
|
3
|
+
# Copyright (c) 2021-2023 Andy Maleh
|
|
4
|
+
#
|
|
5
|
+
# Permission is hereby granted, free of charge, to any person obtaining
|
|
6
|
+
# a copy of this software and associated documentation files (the
|
|
7
|
+
# "Software"), to deal in the Software without restriction, including
|
|
8
|
+
# without limitation the rights to use, copy, modify, merge, publish,
|
|
9
|
+
# distribute, sublicense, and/or sell copies of the Software, and to
|
|
10
|
+
# permit persons to whom the Software is furnished to do so, subject to
|
|
11
|
+
# the following conditions:
|
|
12
|
+
#
|
|
13
|
+
# The above copyright notice and this permission notice shall be
|
|
14
|
+
# included in all copies or substantial portions of the Software.
|
|
15
|
+
#
|
|
16
|
+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
17
|
+
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
18
|
+
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
19
|
+
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
20
|
+
# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
21
|
+
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
22
|
+
# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
23
|
+
|
|
24
|
+
require_relative '../lib/glimmer-dsl-libui'
|
|
25
|
+
require_relative '../lib/glimmer/launcher'
|
|
26
|
+
|
|
27
|
+
# Initialize launcher, consuming ARGV args that are for Glimmer only
|
|
28
|
+
launcher = Glimmer::Launcher.new(ARGV)
|
|
29
|
+
|
|
30
|
+
launcher.launch
|
data/glimmer-dsl-libui.gemspec
CHANGED
|
Binary file
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Copyright (c) 2021-2023 Andy Maleh
|
|
2
|
+
#
|
|
3
|
+
# Permission is hereby granted, free of charge, to any person obtaining
|
|
4
|
+
# a copy of this software and associated documentation files (the
|
|
5
|
+
# "Software"), to deal in the Software without restriction, including
|
|
6
|
+
# without limitation the rights to use, copy, modify, merge, publish,
|
|
7
|
+
# distribute, sublicense, and/or sell copies of the Software, and to
|
|
8
|
+
# permit persons to whom the Software is furnished to do so, subject to
|
|
9
|
+
# the following conditions:
|
|
10
|
+
#
|
|
11
|
+
# The above copyright notice and this permission notice shall be
|
|
12
|
+
# included in all copies or substantial portions of the Software.
|
|
13
|
+
#
|
|
14
|
+
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
15
|
+
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
16
|
+
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
17
|
+
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
18
|
+
# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
19
|
+
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
20
|
+
# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
21
|
+
|
|
22
|
+
# This Rakefile gets used from Glimmer::Launcher when the current directory for running the `glimmer` command
|
|
23
|
+
# does not have a Rakefile (e.g. during scaffolding).
|
|
24
|
+
# It is not needed when running from inside a scaffolded app or gem, or an app with a Rakefile that has
|
|
25
|
+
# `require 'glimmer/rake_task'`
|
|
26
|
+
require 'glimmer/rake_task'
|