ui

package module
v0.0.0-...-09fa35e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 22, 2019 License: MIT Imports: 3 Imported by: 1

README

package ui

Lightweight go desktop ui

this package is highly experimental, drastic changes may occur

What this package tries to do
  • be intuitive for users; applications created with this packge should superficially behave like other ui toolkits, even in subtle ways
  • be intuitive for programmers; writing applications should be straightforward and not require much boilerplate or magic incantations
  • make it easy to create custom components
  • be the basis of a potential ecosystem; many parts of this package can easily be replaced, and the replacements should work well together (e.g. someone could write a different renderer, or an alternative library of components)
  • not be dependent on cgo in principle; while the current backend uses cgo, one could write e.g. an X11 backend in pure go.
What this package does not try to do
  • be the "official" go ui package
  • be useful in all situations (a big limitation right now is that applications can only use a single window)
  • be suited for mobile or web applications

Overview

The design of this package is inspired by immediate mode ui and uses similar techniques to minimize the complexity of components. Many ui libraries make heavy use of inheritance, which can be imitated in go through struct embedding. However this approach has disadvantages and is generally considered unidiomatic. This package follows a different approach by hiding most of the complexity in the ui.State struct instead of an abstract base class. This leads to the Component interface being very small, and components can be extremly lightweight.

There are three parts to this package:

ui and ui/draw

ui defines important interfaces and constants. It also provides the type State, which is central to the functionality of the library.

ui/draw contains data structures for drawing. Components do not draw directly, but rather create a list of commands that will be passed on to the renderer.

ui/toolkit

ui/toolkit is a collection of widgets. It provides common widgets (buttons, text fields etc.), simple layouts and basic themeing support.

ui/impl/...

The packages in ui/impl make up the backend. They are designed to be replaced by better packages later. These are the only packages with external dependencies.

It consists of the following packages (so far):

Usage

import (
	"github.com/jfreymuth/ui"
	"github.com/jfreymuth/ui/impl/gofont"
	"github.com/jfreymuth/ui/impl/icons"
	"github.com/jfreymuth/ui/impl/sdl"
	"github.com/jfreymuth/ui/toolkit"
)

func main() {
	button := toolkit.NewButton("Button", func(state *ui.State) {
		toolkit.ShowMessageDialog(state, "Message", "The button was pressed!", "Ok")
	})

	root := toolkit.NewRoot(button)

	sdl.Show(sdl.Options{
		Title: "Example",
		Width: 400, Height: 300,
		FontLookup: gofont.Lookup,
		IconLookup: &icons.Lookup{},
		Root:       root,
	})
}
Examples
  • examples/editor: a basic text editor, showcases the text area and demonstrates how to implement "save before quitting" comfirmations
  • examples/synth: a very simple synthesizer, demonstrates custom widgets and also some concurrency
  • examples/test: rather messy, but uses almost every single widget

Documentation

Index

Constants

View Source 
const MenuDrag menuDrag = 0

Variables

This section is empty.

Functions

func HandleKeyboardShortcuts 

func HandleKeyboardShortcuts(state *State)

Types

type BackendState 

type BackendState struct {
	State
	// contains filtered or unexported fields
}

func (*BackendState) AddKeyPress 

func (s *BackendState) AddKeyPress(k Key)

func (*BackendState) AddScroll 

func (s *BackendState) AddScroll(x, y int)

func (*BackendState) AddTextInput 

func (s *BackendState) AddTextInput(text string)

func (*BackendState) AnimationRequested 

func (s *BackendState) AnimationRequested() bool

func (*BackendState) Cursor 

func (s *BackendState) Cursor() Cursor

func (*BackendState) GrabMouse 

func (s *BackendState) GrabMouse()

func (*BackendState) QuitRequested 

func (s *BackendState) QuitRequested() bool

func (*BackendState) RefocusRequested 

func (s *BackendState) RefocusRequested() bool

func (*BackendState) ReleaseMouse 

func (s *BackendState) ReleaseMouse(b MouseButton)

func (*BackendState) ResetEvents 

func (s *BackendState) ResetEvents()

func (*BackendState) ResetRequests 

func (state *BackendState) ResetRequests()
func (s *BackendState) SetBlink(b bool)

func (*BackendState) SetHovered 

func (s *BackendState) SetHovered(h bool)

func (*BackendState) SetModifiers 

func (s *BackendState) SetModifiers(m Modifier)

func (*BackendState) SetMouseButtons 

func (s *BackendState) SetMouseButtons(b MouseButton)

func (*BackendState) SetMouseClicks 

func (s *BackendState) SetMouseClicks(clicks int)

func (*BackendState) SetMousePosition 

func (s *BackendState) SetMousePosition(x, y int)

func (*BackendState) SetWindowSize 

func (s *BackendState) SetWindowSize(w, h int)

func (*BackendState) UpdateRequested 

func (s *BackendState) UpdateRequested() bool

func (*BackendState) WindowTitle 

func (s *BackendState) WindowTitle() string

type Component 

type Component interface {
	PreferredSize(draw.FontLookup) (int, int)
	Update(*draw.Buffer, *State)
}

type Cursor 

type Cursor byte
const (
	CursorNormal Cursor = iota
	CursorText
	CursorHand
	CursorCrosshair
	CursorDisabled
	CursorWait
	CursorWaitBackground
	CursorMove
	CursorResizeHorizontal
	CursorResizeVertical
	CursorResizeDiagonal
	CursorResizeDiagonal2
)

type Key 

type Key int
const (
	KeyUnknown Key = iota

	KeyA
	KeyB
	KeyC
	KeyD
	KeyE
	KeyF
	KeyG
	KeyH
	KeyI
	KeyJ
	KeyK
	KeyL
	KeyM
	KeyN
	KeyO
	KeyP
	KeyQ
	KeyR
	KeyS
	KeyT
	KeyU
	KeyV
	KeyW
	KeyX
	KeyY
	KeyZ
	Key1
	Key2
	Key3
	Key4
	Key5
	Key6
	Key7
	Key8
	Key9
	Key0
	KeyEnter
	KeyEscape
	KeyBackspace
	KeyTab
	KeySpace

	KeyCapsLock
	KeyF1
	KeyF2
	KeyF3
	KeyF4
	KeyF5
	KeyF6
	KeyF7
	KeyF8
	KeyF9
	KeyF10
	KeyF11
	KeyF12
	KeyPrintScreen
	KeyScrollLock
	KeyPause
	KeyInsert
	KeyHome
	KeyPageUp
	KeyDelete
	KeyEnd
	KeyPageDown
	KeyRight
	KeyLeft
	KeyDown
	KeyUp
	KeyNumLock
	KeyNumpadDiv
	KeyNumpadMul
	KeyNumpadMinus
	KeyNumpadPlus
	KeyNumpadEnter
	KeyNumpad1
	KeyNumpad2
	KeyNumpad3
	KeyNumpad4
	KeyNumpad5
	KeyNumpad6
	KeyNumpad7
	KeyNumpad8
	KeyNumpad9
	KeyNumpad0
	KeyNumpadDot

	KeyMenu

	KeyLeftControl
	KeyLeftShift
	KeyLeftAlt
	KeyLeftSuper
	KeyRightControl
	KeyRightShift
	KeyRightAlt
	KeyRightSuper
)

type Modifier 

type Modifier byte
const (
	Shift Modifier = 1 << iota
	Control
	Alt
	Super
	CapsLock
	NumLock
)

type MouseButton 

type MouseButton byte
const (
	MouseLeft MouseButton = 1 << iota
	MouseMiddle
	MouseRight
	MouseForward
	MouseBack
)
type Popup interface {
	Close()
	Closed() bool
}

type Root 

type Root interface {
	OpenDialog(Component)
	CloseDialog()
	OpenPopup(image.Rectangle, Component) Popup
	ClosePopups()
	HasPopups() bool
}

type State 

type State struct {
	// contains filtered or unexported fields
}

The State is a components connection to the application. It can be used to query input events and to request actions.

func (*State) AnimationSpeed 

func (s *State) AnimationSpeed() float32

AnimationSpeed returns the time since the last call to RequestAnimation in seconds. 

func (s *State) Blink() bool

Blink returns the current state of blinking elements. This is mostly indended for the cursor in text fields.

func (*State) ClickCount 

func (s *State) ClickCount() int

ClickCount returns the number of consecutive mouse clicks.

func (*State) ClipboardString 

func (s *State) ClipboardString() string

ClipboardString returns the contents of the clipboard.

func (*State) CloseDialog 

func (s *State) CloseDialog()

CloseDialog closes the currently open dialog, if any.

func (*State) ClosePopups 

func (s *State) ClosePopups()

ClosePopups closes all popups.

func (*State) ConsumeScroll 

func (s *State) ConsumeScroll()

ConsumeScroll notifies the State that the scroll amount has been used and should not be used by any other components.

func (*State) DisableTabFocus 

func (s *State) DisableTabFocus()

DisableTabFocus disables focus cycling with the tab key for the current component.

func (*State) DraggedContent 

func (s *State) DraggedContent() (content interface{}, drop bool)

DraggedContent returns information abount a drag and drop gesture currently in progress. If there is no drag and drop gesture, or the mouse cursor is not above the current component, content will be nil. Otherwise, content will be the value passed to InitiateDrag. drop will be true if the mouse was released just before the current update.

func (*State) DrawChild 

func (s *State) DrawChild(g *draw.Buffer, bounds image.Rectangle, c Component)

DrawChild draws another component without passing on any input.

func (*State) FocusNext 

func (s *State) FocusNext()

SetKeyboardFocus requests that the next component will receive keyboard events.

func (*State) FocusPrevious 

func (s *State) FocusPrevious()

SetKeyboardFocus requests that the previous component will receive keyboard events.

func (*State) GetVisibilityRequest 

func (s *State) GetVisibilityRequest() (image.Rectangle, bool)

GetVisibilityRequest returns the rectangle passed to RequestVisible by a child of the current component. This method should be called after UpdateChild. The returned rectangle will be translated relative to the current component. If the second return value is false, RequestVisible was not called.

func (*State) HasKeyboardFocus 

func (s *State) HasKeyboardFocus() bool

HasKeyboardFocus returns true if the current component receives keyboard events.

func (*State) HasModifiers 

func (s *State) HasModifiers(m Modifier) bool

HasModifiers returns true if the given modifiers are currently active.

func (*State) HasMouseFocus 

func (s *State) HasMouseFocus() bool

HasMouseFocus returns true if the current component receives mouse events, i.e. if it is hovered or grabbed.

func (*State) HasPopups 

func (s *State) HasPopups() bool

HasPopups returns wether any popups are currently open.

func (*State) InitiateDrag 

func (s *State) InitiateDrag(content interface{})

InitiateDrag starts a drag and drop gesture.

func (*State) IsHovered 

func (s *State) IsHovered() bool

IsHovered returns true if the cursor is inside the current component.

func (*State) KeyPresses 

func (s *State) KeyPresses() []Key

KeyPresses returns a list of key events that the current component should process.

func (*State) KeyboardFocus 

func (s *State) KeyboardFocus() Component

KeyboardFocus returns the component that currently receives keyboard events.

func (*State) MouseButtonDown 

func (s *State) MouseButtonDown(b MouseButton) bool

MouseButtonDown returns true if a given mouse button is pressed.

func (*State) MouseClick 

func (s *State) MouseClick(b MouseButton) bool

MouseClick returns true if a given mouse button was clicked between the current and last update.

func (*State) MousePos 

func (s *State) MousePos() image.Point

MousePos returns the position of the cursor relative to the current component.

func (*State) OpenDialog 

func (s *State) OpenDialog(d Component)

OpenDialog displays the given component as a dialog. While a dialog is open, other components do not receive any events. Only one dialog may be open at a time.

func (*State) OpenPopup 

func (s *State) OpenPopup(bounds image.Rectangle, d Component) Popup

OpenPopup displays the given component as a popup.

func (*State) PeekKeyPresses 

func (s *State) PeekKeyPresses() []Key

PeekKeyPresses returns a list of key events. Unlike KeyPresses, this method returns events even if they are not intended for the current component.

func (*State) Quit 

func (s *State) Quit()

Quit requests the application to close.

func (*State) RequestAnimation 

func (s *State) RequestAnimation()

RequestAnimation requests that the ui should be updated again after a short amount of time.

func (*State) RequestRefocus 

func (s *State) RequestRefocus()

RequestRefocus requests that the component receiving mouse events should be determined again. This method should rarely be called by normal components.

func (*State) RequestUpdate 

func (s *State) RequestUpdate()

RequestUpdate requests that the ui should be updated again after the current update. This method will typically be called if an input event causes a change to the layout or to components that may have already been updated.

func (*State) RequestVisible 

func (s *State) RequestVisible(r image.Rectangle)

RequestVisible should be called to request that the current component should be scrolled, so that the given rectangle is visible.

func (*State) Scroll 

func (s *State) Scroll() image.Point

Scroll returns the amount of scrolling since the last update. 

func (s *State) SetBlink()

SetBlink requests that blinking elements should be visible.

func (*State) SetClipboardString 

func (s *State) SetClipboardString(c string)

SetClipboardString sets the contents of the clipboard.

func (*State) SetCursor 

func (s *State) SetCursor(c Cursor)

SetCursor sets the current compnents cursor style.

func (*State) SetKeyboardFocus 

func (s *State) SetKeyboardFocus(c Component)

SetKeyboardFocus requests that the given component will receive keyboard events.

func (*State) SetRoot 

func (s *State) SetRoot(r Root)

func (*State) SetWindowTitle 

func (s *State) SetWindowTitle(title string)

SetCursor sets the title of the window.

func (*State) TextInput 

func (s *State) TextInput() string

TextInput returns the string that would be generated by key inputs. Key presses that contributed to the text input will still appear in KeyPresses().

func (*State) UpdateChild 

func (s *State) UpdateChild(g *draw.Buffer, bounds image.Rectangle, c Component)

UpdateChild calls another component's Update method with a State that will deliver the correct events.

func (*State) WindowBounds 

func (s *State) WindowBounds() image.Rectangle

WindowBounds returns the bounds of the window relative to the current component's origin. This means the minimum point of the returned Rect will most likely be negative.

Source Files

View all Source files

Directories

Path Synopsis
examples
editor
synth
test
impl
gldraw
gofont
icons
sdl

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.