parent
e391e703bf
commit
2f5b498ca1
8 changed files with 429 additions and 15 deletions
@ -0,0 +1,21 @@ |
||||
# The MIT License (MIT) |
||||
|
||||
Copyright (c) 2020 Noah Petherbridge |
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy |
||||
of this software and associated documentation files (the "Software"), to deal |
||||
in the Software without restriction, including without limitation the rights |
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
||||
copies of the Software, and to permit persons to whom the Software is |
||||
furnished to do so, subject to the following conditions: |
||||
|
||||
The above copyright notice and this permission notice shall be included in all |
||||
copies or substantial portions of the Software. |
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
||||
SOFTWARE. |
||||
@ -0,0 +1,236 @@ |
||||
# ui: User Interface Toolkit for Go |
||||
|
||||
Package ui is a user interface toolkit for Go that targets desktop |
||||
applications (SDL2, for Linux, MacOS and Windows) as well as web browsers |
||||
(WebAssembly rendering to an HTML Canvas). |
||||
|
||||
 |
||||
|
||||
> _(Screenshot is from Project: Doodle's GUITest debug screen showing a_ |
||||
> _Window, several Frames, Labels, Buttons and a Checkbox widget.)_ |
||||
|
||||
It is very much a **work in progress** and it's a bit buggy. See the |
||||
[Known Issues](#known-issues) at the bottom of this document. |
||||
|
||||
This library is being developed in conjunction with my drawing-based maze |
||||
game, [Project: Doodle](https://www.kirsle.net/doodle). The rendering engine |
||||
library is at [go/render](https://git.kirsle.net/go/render) which provides |
||||
the SDL2 and Canvas back-ends. |
||||
(GitHub mirror: [kirsle/render](https://github.com/kirsle/render)) |
||||
|
||||
# Example |
||||
|
||||
```go |
||||
package main |
||||
|
||||
import ( |
||||
"fmt" |
||||
|
||||
"git.kirsle.net/go/render" |
||||
"git.kirsle.net/go/ui" |
||||
) |
||||
|
||||
func main() { |
||||
mw, err := ui.NewMainWindow("Hello World") |
||||
if err != nil { |
||||
panic(err) |
||||
} |
||||
|
||||
mw.SetBackground(render.White) |
||||
|
||||
// Draw a label. |
||||
label := ui.NewLabel(ui.Label{ |
||||
Text: "Hello, world!", |
||||
Font: render.Text{ |
||||
FontFilename: "../DejaVuSans.ttf", |
||||
Size: 32, |
||||
Color: render.SkyBlue, |
||||
Shadow: render.SkyBlue.Darken(40), |
||||
}, |
||||
}) |
||||
mw.Pack(label, ui.Pack{ |
||||
Anchor: ui.N, |
||||
PadY: 12, |
||||
}) |
||||
|
||||
// Draw a button. |
||||
button := ui.NewButton("My Button", ui.NewLabel(ui.Label{ |
||||
Text: "Click me!", |
||||
Font: render.Text{ |
||||
FontFilename: "../DejaVuSans.ttf", |
||||
Size: 12, |
||||
Color: render.Red, |
||||
Padding: 4, |
||||
}, |
||||
})) |
||||
button.Handle(ui.Click, func(p render.Point) { |
||||
fmt.Println("I've been clicked!") |
||||
}) |
||||
mw.Pack(button, ui.Pack{ |
||||
Anchor: ui.N, |
||||
}) |
||||
|
||||
// Add the button to the MainWindow's Supervisor so it can be |
||||
// clicked on and interacted with. |
||||
mw.Add(button) |
||||
|
||||
mw.MainLoop() |
||||
} |
||||
``` |
||||
|
||||
# Widgets and Features |
||||
|
||||
The following widgets have been implemented or are planned for the future. |
||||
|
||||
Widgets are designed to be composable, making use of pre-existing widgets to |
||||
create more complex ones. The widgets here are ordered from simplest to |
||||
most complex. |
||||
|
||||
**Fully implemented widgets:** |
||||
|
||||
* [x] **BaseWidget**: the base class of all Widgets. |
||||
* The `Widget` interface describes the functions common to all Widgets, |
||||
such as SetBackground, Configure, MoveTo, Resize, and so on. |
||||
* BaseWidget provides sane default implementations for all the methods |
||||
required by the Widget interface. Most Widgets inherit from |
||||
the BaseWidget. |
||||
* [x] **Frame**: a layout wrapper for other widgets. |
||||
* Pack() lets you add child widgets to the Frame, aligned against one side |
||||
or another, and ability to expand widgets to take up remaining space in |
||||
their part of the Frame. |
||||
* [x] **Label**: Textual labels for your UI. |
||||
* Supports TrueType fonts, color, stroke, drop shadow, font size, etc. |
||||
* Variable binding support: TextVariable or IntVariable can point to a |
||||
string or int reference, respectively, to provide the text of the label |
||||
dynamically. |
||||
* [x] **Image**: show a PNG or Bitmap image on your UI. |
||||
* [x] **Button**: clickable buttons. |
||||
* They can wrap _any_ widget. Labels are most common but can also wrap a |
||||
Frame so you can have labels + icon images inside the button, etc. |
||||
* Mouse hover and click event handlers. |
||||
* [x] **CheckButton** and **RadioButton** |
||||
* Variants on the Button which bind to a variable and toggle its state |
||||
when clicked. Boolean variable pointers are used with CheckButton and |
||||
string pointers for RadioButton. |
||||
* CheckButtons stay pressed in when clicked (true) and pop back out when |
||||
clicked again (false). |
||||
* RadioButtons stay pressed in when the string variable matches their |
||||
value, and pop out when the string variable changes. |
||||
* [x] **Checkbox** and **Radiobox**: a Frame widget that wraps a |
||||
CheckButton and a Label to provide a more traditional UI element. |
||||
* Works the same as CheckButton and RadioButton but draws a separate |
||||
label next to a small check button. Clicking the label will toggle the |
||||
state of the checkbox. |
||||
* [x] **Window**: a Frame with a title bar Frame on top. |
||||
* Note: Window is not yet draggable or closeable. |
||||
|
||||
**Work in progress widgets:** |
||||
|
||||
* [x] **Menu**: a frame with clickable menu items. |
||||
* To be a base widget behind right-click context menus, pull-down menus |
||||
from a MenuBar, options from a SelectBox and so on. |
||||
* Powered by Frame and Button but with a nice API for composing menu |
||||
actions. |
||||
* Partially implemented so far. |
||||
* [ ] **MenuButton**: a Button that opens a Menu when clicked. |
||||
* [ ] **MenuBar**: a Frame that houses many MenuButtons, intended for the |
||||
main menu at the top of a UI window (File, Edit, Help, etc.). |
||||
* [ ] **Scrollbar**: a Frame including a trough, scroll buttons and a |
||||
draggable slider. |
||||
|
||||
**Wish list for the longer-term future:** |
||||
|
||||
* [ ] **SelectBox:** a kind of MenuButton that lets the user choose a value |
||||
from a list of possible values, bound to a string variable. |
||||
* [ ] **WindowManager**: manages Window widgets and focus support for all |
||||
interactable widgets. |
||||
* Would enable Windows to be dragged around by their title bar, overlap |
||||
other Windows, and rise on top of other Windows when clicked. |
||||
* Would enable "focus" support for Buttons, Text Boxes and other |
||||
interactable widgets. |
||||
* [ ] **TextBox:** an editable text field that the user can focus and type |
||||
a value into. |
||||
* Would depend on the WindowManager to manage focus for the widgets. |
||||
|
||||
## Supervisor for Interaction |
||||
|
||||
Some widgets that support user interaction (such as Button, CheckButton and |
||||
Checkbox) need to be added to the Supervisor which watches over them and |
||||
communicates events that they're interested in. |
||||
|
||||
```go |
||||
func SupervisorSDL2Example() { |
||||
// NOTE: using the render/sdl engine. |
||||
window := sdl.New("Hello World", 800, 600) |
||||
window.Setup() |
||||
|
||||
// One Supervisor is needed per UI. |
||||
supervisor := ui.NewSupervisor() |
||||
|
||||
// A button for our UI. |
||||
btn := ui.NewButton("Button1", ui.NewLabel(ui.Label{ |
||||
Text: "Click me!", |
||||
})) |
||||
|
||||
// Add it to the Supervisor. |
||||
supervisor.Add(btn) |
||||
|
||||
// Main loop |
||||
for { |
||||
// Check for keyboard/mouse events |
||||
ev, _ := window.Poll() |
||||
|
||||
// Ping the Supervisor Loop function with the event state, so |
||||
// it can trigger events on the widgets under its care. |
||||
supervisor.Loop(ev) |
||||
} |
||||
} |
||||
``` |
||||
|
||||
You only need one Supervisor instance per UI. Add() each interactive widget |
||||
to it, and call its Loop() method in your main loop so it can update the |
||||
state of the widgets under its care. |
||||
|
||||
The MainWindow includes its own Supervisor, see below. |
||||
|
||||
## MainWindow for Simple Applications |
||||
|
||||
The MainWindow widget may be used for "simple" UI applications where all you |
||||
want is a GUI and you don't want to manage your own SDL2 (or Canvas) engine. |
||||
|
||||
MainWindow is only to be used **one time** per application, and it sets up |
||||
its own SDL2 render context and creates the main window. It also contains a |
||||
Frame widget for the window contents and you may Pack() widgets into the |
||||
window the same as you would a Frame. |
||||
|
||||
MainWindow includes its own Supervisor: just call the `.Add(Widget)` |
||||
method to add interactive widgets to the supervisor. The MainLoop() of the |
||||
window calls Supervisor.Loop() automatically. |
||||
|
||||
# Known Issues |
||||
|
||||
The frame packing algorithm (frame_pack.go) is currently very buggy and in |
||||
need of a re-write. Some examples of issues with it: |
||||
|
||||
* Currently, when the Frame is iterating over packed widgets to decide their |
||||
location and size, it explicitly calls MoveTo() and Resize() giving them |
||||
their pixel-coordinates, relative to the Frame's own position. |
||||
* When Frames nest other Frames this becomes more of an issue. |
||||
* The Supervisor sometimes can't determine the correct position of a |
||||
button packed inside of nested frames. It currently checks the |
||||
Point() of the button (set by its parent Frame) and this doesn't |
||||
account for the grandparent frame's position. Using the |
||||
AbsolutePosition() helper function (which recursively crawls up a |
||||
widget tree) also yields incorrect results, as the position of each |
||||
Frame is _added_ to the position of the Button which throws it off even |
||||
further. |
||||
|
||||
It's on my to-do list to rewrite the algorithm from scratch and make it |
||||
more resilient. One thing I also want to do is rename the `Anchor` field |
||||
and call it `Side` to be more in line with the Tk GUI toolkit's naming |
||||
convention. ("Side: N" or "Side: SE", and let the "Anchor" name be used for |
||||
how to center the widget inside of its space ("Top", "Center", "Left", etc.) |
||||
|
||||
# License |
||||
|
||||
MIT. |
||||
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
@ -0,0 +1,55 @@ |
||||
package main |
||||
|
||||
import ( |
||||
"fmt" |
||||
|
||||
"git.kirsle.net/go/render" |
||||
"git.kirsle.net/go/ui" |
||||
) |
||||
|
||||
func main() { |
||||
mw, err := ui.NewMainWindow("Hello World") |
||||
if err != nil { |
||||
panic(err) |
||||
} |
||||
|
||||
mw.SetBackground(render.White) |
||||
|
||||
// Draw a label.
|
||||
label := ui.NewLabel(ui.Label{ |
||||
Text: "Hello, world!", |
||||
Font: render.Text{ |
||||
FontFilename: "../DejaVuSans.ttf", |
||||
Size: 32, |
||||
Color: render.SkyBlue, |
||||
Shadow: render.SkyBlue.Darken(40), |
||||
}, |
||||
}) |
||||
mw.Pack(label, ui.Pack{ |
||||
Anchor: ui.N, |
||||
PadY: 12, |
||||
}) |
||||
|
||||
// Draw a button.
|
||||
button := ui.NewButton("My Button", ui.NewLabel(ui.Label{ |
||||
Text: "Click me!", |
||||
Font: render.Text{ |
||||
FontFilename: "../DejaVuSans.ttf", |
||||
Size: 12, |
||||
Color: render.Red, |
||||
Padding: 4, |
||||
}, |
||||
})) |
||||
button.Handle(ui.Click, func(p render.Point) { |
||||
fmt.Println("I've been clicked!") |
||||
}) |
||||
mw.Pack(button, ui.Pack{ |
||||
Anchor: ui.N, |
||||
}) |
||||
|
||||
// Add the button to the MainWindow's Supervisor so it can be
|
||||
// clicked on and interacted with.
|
||||
mw.Add(button) |
||||
|
||||
mw.MainLoop() |
||||
} |
||||
Loading…
Reference in new issue