ui

package module
v0.0.0-...-5ffa77b Latest Latest
Warning

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

Go to latest
Published: May 15, 2020 License: MIT Imports: 8 Imported by: 0

README

ui: platform-native GUI library for Go

This is a library that aims to provide simple GUI software development in Go. It is based on my libui, a simple cross-platform library that does the same thing, but written in C.

It runs on/requires:

  • Windows: cgo, Windows Vista SP2 with Platform Update and newer
  • Mac OS X: cgo, Mac OS X 10.8 and newer
  • other Unixes: cgo, GTK+ 3.10 and newer
    • Debian, Ubuntu, etc.: sudo apt-get install libgtk-3-dev
    • Red Hat/Fedora, etc.: sudo dnf install gtk3-devel

It also requires Go 1.8 or newer.

It currently aligns to libui's Alpha 4.1, with only a small handful of functions not available.

Status

Package ui is currently mid-alpha software. Much of what is currently present runs stabily enough for the examples and perhaps some small programs to work, but the stability is still a work-in-progress, much of what is already there is not feature-complete, some of it will be buggy on certain platforms, and there's a lot of stuff missing. The libui README has more information.

Installation

Once you have the dependencies installed, a simple

go get github.com/andlabs/ui/...

should suffice.

Documentation

The in-code documentation is sufficient to get started, but needs improvement.

Some simple example programs are in the examples directory. You can go build each of them individually.

Windows manifests

Package ui requires a manifest that specifies Common Controls v6 to run on Windows. It should at least also state as supported Windows Vista and Windows 7, though to avoid surprises with other packages (or with Go itself; see this issue) you should state compatibility with higher versions of Windows too.

The simplest option is provided as a subpackage winmanifest; you can simply import it without a name, and it'll set things up properly:

import _ "github.com/andlabs/ui/winmanifest"

You do not have to worry about importing this in non-Windows-only files; it does nothing on non-Windows platforms.

If you wish to use your own manifest instead, you can use the one in winmanifest as a template to see what's required and how. You'll need to specify the template in a .rc file and use windres in MinGW-w64 to generate a .syso file as follows:

windres -i resources.rc -o winmanifest_windows_GOARCH.syso -O coff

You may also be interested in the github.com/akavel/rsrc and github.com/josephspurrier/goversioninfo packages, which provide other Go-like options for embedding the manifest.

Note that if you choose to ship a manifest as a separate .exe.manifest file instead of embedding it in your binary, and you use Cygwin or MSYS2 as the source of your MinGW-w64, Cygwin and MSYS2 instruct gcc to embed a default manifest of its own if none is specified. This default will override your manifest file! See this issue for more details, including workaround instructions.

macOS program execution

If you run a macOS program binary directly from the command line, it will start in the background. This is intentional; see this for more details.

Documentation

Overview

+build windows,cgo darwin,cgo

Index

Constants

View Source
const (
	TableModelColumnNeverEditable  = -1
	TableModelColumnAlwaysEditable = -2
)

TableModelColumnNeverEditable and TableModelColumnAlwaysEditable are the value of an editable model column parameter to one of the Table create column functions; if used, that jparticular Table colum is not editable by the user and always editable by the user, respectively.

View Source
const DrawDefaultMiterLimit = 10.0

TODO document

Variables

This section is empty.

Functions

func LibuiFreeText

func LibuiFreeText(c uintptr)

LibuiFreeText allows implementations of Control to call the libui function uiFreeText.

func Main

func Main(f func()) error

Main initializes package ui, runs f to set up the program, and executes the GUI main loop. f should set up the program's initial state: open the main window, create controls, and set up events. It should then return, at which point Main will process events until Quit is called, at which point Main will return nil. If package ui fails to initialize, Main returns an appropriate error.

func MainAdjusted

func MainAdjusted(f func(), skipTheme int) error

func MsgBox

func MsgBox(w *Window, title string, description string)

func MsgBoxError

func MsgBoxError(w *Window, title string, description string)

TODO

func OnShouldQuit

func OnShouldQuit(f func() bool)

OnShouldQuit schedules f to be exeucted when the OS wants the program to quit or when a Quit menu item has been clicked. Only one function may be registered at a time. If the function returns true, Quit will be called. If the function returns false, or if OnShouldQuit is never called. Quit will not be called and the OS will be told that the program needs to continue running.

func OpenFile

func OpenFile(w *Window) string

func QueueMain

func QueueMain(f func())

QueueMain queues f to be executed on the GUI thread when next possible. It returns immediately; that is, it does not wait for the function to actually be executed. QueueMain is the only function that can be called from other goroutines, and its primary purpose is to allow communication between other goroutines and the GUI thread. Calling QueueMain after Quit has been called results in undefined behavior.

If you start a goroutine in f, it also cannot call package ui functions. So for instance, the following will result in undefined behavior:

ui.QueueMain(func() {
	go ui.MsgBox(...)
})

func Quit

func Quit()

Quit queues a return from Main. It does not exit the program. It also does not immediately cause Main to return; Main will return when it next can. Quit must be called from the GUI thread.

func SaveFile

func SaveFile(w *Window) string

Types

type Align

type Align int

Align represents the alignment of a Control in its cell of a Grid.

const (
	AlignFill Align = iota
	AlignStart
	AlignCenter
	AlignEnd
)

type Area

type Area struct {
	ControlBase
	// contains filtered or unexported fields
}

Area is a Control that represents a blank canvas that a program can draw on as it wishes. Areas also receive keyboard and mouse events, and programs can react to those as they see fit. Drawing and event handling are handled through an instance of a type that implements AreaHandler that every Area has; see AreaHandler for details.

There are two types of areas. Non-scrolling areas are rectangular and have no scrollbars. Programs can draw on and get mouse events from any point in the Area, and the size of the Area is decided by package ui itself, according to the layout of controls in the Window the Area is located in and the size of said Window. There is no way to query the Area's size or be notified when its size changes; instead, you are given the area size as part of the draw and mouse event handlers, for use solely within those handlers.

Scrolling areas have horziontal and vertical scrollbars. The amount that can be scrolled is determined by the area's size, which is decided by the programmer (both when creating the Area and by a call to SetSize). Only a portion of the Area is visible at any time; drawing and mouse events are automatically adjusted to match what portion is visible, so you do not have to worry about scrolling in your event handlers. AreaHandler has more information.

The internal coordinate system of an Area is points, which are floating-point and device-independent. For more details, see AreaHandler. The size of a scrolling Area must be an exact integer number of points (that is, you cannot have an Area that is 32.5 points tall) and thus the parameters to NewScrollingArea and SetSize are ints. All other instances of points in parameters and structures (including sizes of drawn objects) are float64s.

func NewArea

func NewArea(handler AreaHandler) *Area

NewArea creates a new non-scrolling Area.

func NewScrollingArea

func NewScrollingArea(handler AreaHandler, width int, height int) *Area

NewScrollingArea creates a new scrolling Area of the given size, in points.

func (*Area) Destroy

func (a *Area) Destroy()

Destroy destroys the Area.

func (*Area) QueueRedrawAll

func (a *Area) QueueRedrawAll()

QueueRedrawAll queues the entire Area for redraw. The Area is not redrawn before this function returns; it is redrawn when next possible.

func (*Area) ScrollTo

func (a *Area) ScrollTo(x float64, y float64, width float64, height float64)

ScrollTo scrolls the Area to show the given rectangle; what this means is implementation-defined, but you can safely assume that as much of the given rectangle as possible will be visible after this call. (TODO verify this on OS X) ScrollTo panics if called on a non-scrolling Area.

func (*Area) SetSize

func (a *Area) SetSize(width int, height int)

SetSize sets the size of a scrolling Area to the given size, in points. SetSize panics if called on a non-scrolling Area.

type AreaDrawParams

type AreaDrawParams struct {
	// Context is the drawing context to draw on. See DrawContext
	// for how to draw.
	Context *DrawContext

	// AreaWidth and AreaHeight provide the size of the Area for
	// non-scrolling Areas. For scrolling Areas both values are zero.
	//
	// To reiterate the AreaHandler documentation, do NOT save
	// these values for later; they can change without generating
	// an event.
	AreaWidth  float64
	AreaHeight float64

	// These four fields define the rectangle that needs to be
	// redrawn. The system will not draw anything outside this
	// rectangle, but you can make your drawing faster if you
	// also stay within the lines.
	ClipX      float64
	ClipY      float64
	ClipWidth  float64
	ClipHeight float64
}

AreaDrawParams provides a drawing context that can be used to draw on an Area and tells you where to draw. See AreaHandler for introductory information.

type AreaHandler

type AreaHandler interface {
	// Draw is sent when a part of the Area needs to be drawn.
	// dp will contain a drawing context to draw on, the rectangle
	// that needs to be drawn in, and (for a non-scrolling area) the
	// size of the area. The rectangle that needs to be drawn will
	// have been cleared by the system prior to drawing, so you are
	// always working on a clean slate.
	//
	// If you call Save on the drawing context, you must call Release
	// before returning from Draw, and the number of calls to Save
	// and Release must match. Failure to do so results in undefined
	// behavior.
	Draw(a *Area, dp *AreaDrawParams)

	// MouseEvent is called when the mouse moves over the Area
	// or when a mouse button is pressed or released. See
	// AreaMouseEvent for more details.
	//
	// If a mouse button is being held, MouseEvents will continue to
	// be generated, even if the mouse is not within the area. On
	// some systems, the system can interrupt this behavior;
	// see DragBroken.
	MouseEvent(a *Area, me *AreaMouseEvent)

	// MouseCrossed is called when the mouse either enters or
	// leaves the Area. It is called even if the mouse buttons are being
	// held (see MouseEvent above). If the mouse has entered the
	// Area, left is false; if it has left the Area, left is true.
	//
	// If, when the Area is first shown, the mouse is already inside
	// the Area, MouseCrossed will be called with left=false.
	// TODO what about future shows?
	MouseCrossed(a *Area, left bool)

	// DragBroken is called if a mouse drag is interrupted by the
	// system. As noted above, when a mouse button is held,
	// MouseEvent will continue to be called, even if the mouse is
	// outside the Area. On some systems, this behavior can be
	// stopped by the system itself for a variety of reasons. This
	// method is provided to allow your program to cope with the
	// loss of the mouse in this case. You should cope by cancelling
	// whatever drag-related operation you were doing.
	//
	// Note that this is only generated on some systems under
	// specific conditions. Do not implement behavior that only
	// takes effect when DragBroken is called.
	DragBroken(a *Area)

	// KeyEvent is called when a key is pressed while the Area has
	// keyboard focus (if the Area has been tabbed into or if the
	// mouse has been clicked on it). See AreaKeyEvent for specifics.
	//
	// Because some keyboard events are handled by the system
	// (for instance, menu accelerators and global hotkeys), you
	// must return whether you handled the key event; return true
	// if you did or false if you did not. If you wish to ignore the
	// keyboard outright, the correct implementation of KeyEvent is
	// 	func (h *MyHandler) KeyEvent(a *ui.Area, ke *ui.AreaKeyEvent) (handled bool) {
	// 		return false
	// 	}
	// DO NOT RETURN TRUE UNCONDITIONALLY FROM THIS
	// METHOD. BAD THINGS WILL HAPPEN IF YOU DO.
	KeyEvent(a *Area, ke *AreaKeyEvent) (handled bool)
}

AreaHandler defines the functionality needed for handling events from an Area. Each of the methods on AreaHandler is called from the GUI thread, and every parameter (other than the Area itself) should be assumed to only be valid during the life of the method call (so for instance, do not save AreaDrawParams.AreaWidth, as that might change without generating an event).

Coordinates to Draw and MouseEvent are given in points. Points are generic, floating-point, device-independent coordinates with (0,0) at the top left corner. You never have to worry about the mapping between points and pixels; simply draw everything using points and you get nice effects like looking sharp on high-DPI monitors for free. Proper documentation on the matter is being written. In the meantime, there are several referenes to this kind of drawing, most notably on Apple's website: https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html#//apple_ref/doc/uid/TP40012302-CH4-SW1

For a scrolling Area, points are automatically offset by the scroll position. So if the mouse moves to position (5,5) while the horizontal scrollbar is at position 10 and the horizontal scrollbar is at position 20, the coordinate stored in the AreaMouseEvent structure is (15,25). The same applies to drawing.

type AreaKeyEvent

type AreaKeyEvent struct {
	Key       rune
	ExtKey    ExtKey
	Modifier  Modifiers
	Modifiers Modifiers
	Up        bool
}

TODO document all these

type AreaMouseEvent

type AreaMouseEvent struct {
	X float64
	Y float64

	// AreaWidth and AreaHeight provide the size of the Area for
	// non-scrolling Areas. For scrolling Areas both values are zero.
	//
	// To reiterate the AreaHandler documentation, do NOT save
	// these values for later; they can change without generating
	// an event.
	AreaWidth  float64
	AreaHeight float64

	Down      uint
	Up        uint
	Count     uint
	Modifiers Modifiers
	Held      []uint
}

TODO document all these

TODO note that in the case of a drag, X and Y can be out of bounds, or in the event of a scrolling area, in places that are not visible

type At

type At int

At represents a side of a Control to add other Controls to a Grid to.

const (
	Leading At = iota
	Top
	Trailing
	Bottom
)

type Attribute

type Attribute interface {
	// contains filtered or unexported methods
}

Attribute stores information about an attribute in an AttributedString.

The following types can be used as Attributes:

  • TextFamily
  • TextSize
  • TextWeight
  • TextItalic
  • TextStretch
  • TextColor
  • TextBackground
  • Underline
  • UnderlineColor
  • UnderlineColorCustom
  • OpenTypeFeatures

For every Unicode codepoint in the AttributedString, at most one value of each attribute type can be applied.

type AttributedString

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

AttributedString represents a string of UTF-8 text that can optionally be embellished with formatting attributes. Package ui provides the list of formatting attributes, which cover common formatting traits like boldface and color as well as advanced typographical features provided by OpenType like superscripts and small caps. These attributes can be combined in a variety of ways.

Attributes are applied to runs of Unicode codepoints in the string. Zero-length runs are elided. Consecutive runs that have the same attribute type and value are merged. Each attribute is independent of each other attribute; overlapping attributes of different types do not split each other apart, but different values of the same attribute type do.

The empty string can also be represented by AttributedString, but because of the no-zero-length-attribute rule, it will not have attributes.

Unlike Go strings, AttributedStrings are mutable.

AttributedString allocates resources within libui, which package ui sits on top of. As such, when you are finished with an AttributedString, you must free it with Free. Like other things in package ui, AttributedString must only be used from the main goroutine.

In addition, AttributedString provides facilities for moving between grapheme clusters, which represent a character from the point of view of the end user. The cursor of a text editor is always placed on a grapheme boundary, so you can use these features to move the cursor left or right by one "character". TODO does uiAttributedString itself need this

AttributedString does not provide enough information to be able to draw itself onto a DrawContext or respond to user actions. In order to do that, you'll need to use a DrawTextLayout, which is built from the combination of an AttributedString and a set of layout-specific properties.

func NewAttributedString

func NewAttributedString(initialString string) *AttributedString

NewAttributedString creates a new AttributedString from initialString. The string will be entirely unattributed.

func (*AttributedString) AppendUnattributed

func (s *AttributedString) AppendUnattributed(str string)

AppendUnattributed adds str to the end of s. The new substring will be unattributed.

func (*AttributedString) Delete

func (s *AttributedString) Delete(start, end int)

Delete deletes the characters and attributes of s in the byte range [start, end).

func (*AttributedString) Free

func (s *AttributedString) Free()

Free destroys s.

func (*AttributedString) InsertAtUnattributed

func (s *AttributedString) InsertAtUnattributed(str string, at int)

InsertAtUnattributed adds str to s at the byte position specified by at. The new substring will be unattributed; existing attributes will be moved along with their text.

func (*AttributedString) SetAttribute

func (s *AttributedString) SetAttribute(a Attribute, start, end int)

SetAttribute sets a in the byte range [start, end) of s. Any existing attributes in that byte range of the same type are removed.

func (*AttributedString) String

func (s *AttributedString) String() string

String returns the textual content of s.

type Bitmap

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

Bitmap represents a bitmap capable to be drawn on drawing context.

func (*Bitmap) Draw

func (b *Bitmap) Draw(x, y float64)

Draw draws the bitmap on its drawing context.

func (*Bitmap) DrawWithSize

func (b *Bitmap) DrawWithSize(x, y, width, height float64)

DrawWithSize draws the bitmap with a specified size on its drawing context.

func (*Bitmap) Free

func (b *Bitmap) Free()

Free destroys the given bitmap.

type Box

type Box struct {
	ControlBase
	// contains filtered or unexported fields
}

Box is a Control that holds a group of Controls horizontally or vertically. If horizontally, then all controls have the same height. If vertically, then all controls have the same width. By default, each control has its preferred width (horizontal) or height (vertical); if a control is marked "stretchy", it will take whatever space is left over. If multiple controls are marked stretchy, they will be given equal shares of the leftover space. There can also be space between each control ("padding").

func NewHorizontalBox

func NewHorizontalBox() *Box

NewHorizontalBox creates a new horizontal Box.

func NewVerticalBox

func NewVerticalBox() *Box

NewVerticalBox creates a new vertical Box.

func (*Box) Append

func (b *Box) Append(child Control, stretchy bool)

Append adds the given control to the end of the Box.

func (*Box) Delete

func (b *Box) Delete(n int)

Delete deletes the nth control of the Box.

func (*Box) Destroy

func (b *Box) Destroy()

Destroy destroys the Box. If the Box has children, Destroy calls Destroy on those Controls as well.

func (*Box) Padded

func (b *Box) Padded() bool

Padded returns whether there is space between each control of the Box.

func (*Box) SetPadded

func (b *Box) SetPadded(padded bool)

SetPadded controls whether there is space between each control of the Box. The size of the padding is determined by the OS and its best practices.

type Button

type Button struct {
	ControlBase
	// contains filtered or unexported fields
}

Button is a Control that represents a button that the user can click to perform an action. A Button has a text label that should describe what the button does.

func NewButton

func NewButton(text string) *Button

NewButton creates a new Button with the given text as its label.

func (*Button) OnClicked

func (b *Button) OnClicked(f func(*Button))

OnClicked registers f to be run when the user clicks the Button. Only one function can be registered at a time.

func (*Button) PreferredSize

func (b *Button) PreferredSize() (int, int)

func (*Button) SetMinSize

func (b *Button) SetMinSize(width int, height int)

func (*Button) SetText

func (b *Button) SetText(text string)

SetText sets the Button's text to text.

func (*Button) Text

func (b *Button) Text() string

Text returns the Button's text.

type Checkbox

type Checkbox struct {
	ControlBase
	// contains filtered or unexported fields
}

Checkbox is a Control that represents a box with a text label at its side. When the user clicks the checkbox, a check mark will appear in the box; clicking it again removes the check.

func NewCheckbox

func NewCheckbox(text string) *Checkbox

NewCheckbox creates a new Checkbox with the given text as its label.

func (*Checkbox) Checked

func (c *Checkbox) Checked() bool

Checked returns whether the Checkbox is checked.

func (*Checkbox) OnToggled

func (c *Checkbox) OnToggled(f func(*Checkbox))

OnToggled registers f to be run when the user clicks the Checkbox. Only one function can be registered at a time.

func (*Checkbox) SetChecked

func (c *Checkbox) SetChecked(checked bool)

SetChecked sets whether the Checkbox is checked.

func (*Checkbox) SetText

func (c *Checkbox) SetText(text string)

SetText sets the Checkbox's text to text.

func (*Checkbox) Text

func (c *Checkbox) Text() string

Text returns the Checkbox's text.

type ColorButton

type ColorButton struct {
	ControlBase
	// contains filtered or unexported fields
}

ColorButton is a Control that represents a button that the user can click to select a color.

func NewColorButton

func NewColorButton() *ColorButton

NewColorButton creates a new ColorButton.

func (*ColorButton) Color

func (b *ColorButton) Color() (r, g, bl, a float64)

Color returns the color currently selected in the ColorButton. Colors are not alpha-premultiplied. TODO rename b or bl

func (*ColorButton) OnChanged

func (b *ColorButton) OnChanged(f func(*ColorButton))

OnChanged registers f to be run when the user changes the currently selected color in the ColorButton. Only one function can be registered at a time.

func (*ColorButton) SetColor

func (b *ColorButton) SetColor(r, g, bl, a float64)

SetColor sets the currently selected color in the ColorButton. Colors are not alpha-premultiplied. TODO rename b or bl

type Combobox

type Combobox struct {
	ControlBase
	// contains filtered or unexported fields
}

Combobox is a Control that represents a drop-down list of strings that the user can choose one of at any time. For a Combobox that users can type values into, see EditableCombobox.

func NewCombobox

func NewCombobox() *Combobox

NewCombobox creates a new Combobox.

func (*Combobox) Append

func (c *Combobox) Append(text string)

Append adds the named item to the end of the Combobox.

func (*Combobox) OnSelected

func (c *Combobox) OnSelected(f func(*Combobox))

OnSelected registers f to be run when the user selects an item in the Combobox. Only one function can be registered at a time.

func (*Combobox) Selected

func (c *Combobox) Selected() int

Selected returns the index of the currently selected item in the Combobox, or -1 if nothing is selected.

func (*Combobox) SetSelected

func (c *Combobox) SetSelected(index int)

SetSelected sets the currently selected item in the Combobox to index. If index is -1 no item will be selected.

type Control

type Control interface {
	// LibuiControl returns the uiControl pointer for the Control.
	// This is intended for use when adding a control to a
	// container.
	LibuiControl() uintptr

	// Destroy destroys the Control.
	Destroy()

	// Handle returns the OS-level handle that backs the
	// Control. On OSs that use reference counting for
	// controls, Handle does not increment the reference
	// count; you are sharing package ui's reference.
	Handle() uintptr

	// Visible returns whether the Control is visible.
	Visible() bool

	// Show shows the Control.
	Show()

	// Hide shows the Control. Hidden controls do not participate
	// in layout (that is, Box, Grid, etc. does not reserve space for
	// hidden controls).
	Hide()

	// Enabled returns whether the Control is enabled.
	Enabled() bool

	// Enable enables the Control.
	Enable()

	// Disable disables the Control.
	Disable()
}

Control represents a GUI control. It provdes methods common to all Controls.

The preferred way to create new Controls is to use ControlBase; see ControlBase below.

func ControlFromLibui

func ControlFromLibui(c uintptr) Control

ControlFromLibui returns the Control associated with a libui uiControl. This is intended for implementing event handlers on the Go side, to prevent sharing Go pointers with C. This function only works on Controls that use ControlBase.

type ControlBase

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

ControlBase is an implementation of Control that provides all the methods that Control requires. To use it, embed a ControlBase (not a *ControlBase) into your structure, then assign the result of NewControlBase to that field:

type MyControl struct {
	ui.ControlBase
	c *C.MyControl
}

func NewMyControl() *MyControl {
	m := &NewMyControl{
		c: C.newMyControl(),
	}
	m.ControlBase = ui.NewControlBase(m, uintptr(unsafe.Pointer(c)))
	return m
}

func NewControlBase

func NewControlBase(iface Control, c uintptr) ControlBase

NewControlBase creates a new ControlBase. See the documentation of ControlBase for an example. NewControl should only be called once per instance of Control.

func (*ControlBase) Destroy

func (c *ControlBase) Destroy()

func (*ControlBase) Disable

func (c *ControlBase) Disable()

func (*ControlBase) Enable

func (c *ControlBase) Enable()

func (*ControlBase) Enabled

func (c *ControlBase) Enabled() bool

func (*ControlBase) Handle

func (c *ControlBase) Handle() uintptr

func (*ControlBase) Hide

func (c *ControlBase) Hide()

func (*ControlBase) LibuiControl

func (c *ControlBase) LibuiControl() uintptr

func (*ControlBase) SetFocus

func (c *ControlBase) SetFocus()

func (*ControlBase) Show

func (c *ControlBase) Show()

func (*ControlBase) Visible

func (c *ControlBase) Visible() bool

type DateTimePicker

type DateTimePicker struct {
	ControlBase
	// contains filtered or unexported fields
}

DateTimePicker is a Control that represents a field where the user can enter a date and/or a time.

func NewDatePicker

func NewDatePicker() *DateTimePicker

NewDatePicker creates a new DateTimePicker that shows only a date.

func NewDateTimePicker

func NewDateTimePicker() *DateTimePicker

NewDateTimePicker creates a new DateTimePicker that shows both a date and a time.

func NewTimePicker

func NewTimePicker() *DateTimePicker

NewTimePicker creates a new DateTimePicker that shows only a time.

func (*DateTimePicker) OnChanged

func (d *DateTimePicker) OnChanged(f func(*DateTimePicker))

OnChanged registers f to be run when the user changes the time in the DateTimePicker. Only one function can be registered at a time.

func (*DateTimePicker) SetTime

func (d *DateTimePicker) SetTime(t time.Time)

SetTime sets the time in the DateTimePicker to t. t's components are read as-is via t.Date() and t.Clock(); no time zone manipulations are done.

func (*DateTimePicker) Time

func (d *DateTimePicker) Time() time.Time

Time returns the time stored in the uiDateTimePicker. The time is assumed to be local time.

type DrawBrush

type DrawBrush struct {
	Type DrawBrushType

	// If Type is Solid.
	// TODO
	R float64
	G float64
	B float64
	A float64

	// If Type is LinearGradient or RadialGradient.
	// TODO
	X0          float64 // start point for both
	Y0          float64
	X1          float64 // linear: end point; radial: circle center
	Y1          float64
	OuterRadius float64 // for radial gradients only
	Stops       []DrawGradientStop
}

TODO

type DrawBrushType

type DrawBrushType int

DrawBrushType defines the various types of brushes.

TODO disclaimer

const (
	DrawBrushTypeSolid DrawBrushType = iota
	DrawBrushTypeLinearGradient
	DrawBrushTypeRadialGradient
	DrawBrushTypeImage // presently unimplemented
)

type DrawContext

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

DrawContext represents a drawing surface that you can draw to. At present the only DrawContexts are surfaces associated with Areas and are provided by package ui; see AreaDrawParams.

func (*DrawContext) Clip

func (c *DrawContext) Clip(p *DrawPath)

TODO

func (*DrawContext) DrawImage

func (c *DrawContext) DrawImage(img image.Image, x, y float64)

DrawImage is a shortcut to create and draw a disposable bitmap.

func (*DrawContext) DrawImageWithSize

func (c *DrawContext) DrawImageWithSize(
	img image.Image, x, y, width, height float64)

DrawImageWithSize is a shortcut to create and draw a disposable bitmap with a specified size.

func (*DrawContext) Fill

func (c *DrawContext) Fill(p *DrawPath, b *DrawBrush)

TODO

func (*DrawContext) NewBitmap

func (c *DrawContext) NewBitmap(img image.Image) *Bitmap

NewBitmap creates a new bitmap from a given image. The resulting bitmap is associated with the current drawing context.

func (*DrawContext) Restore

func (c *DrawContext) Restore()

TODO

func (*DrawContext) Save

func (c *DrawContext) Save()

TODO

func (*DrawContext) Stroke

func (c *DrawContext) Stroke(p *DrawPath, b *DrawBrush, sp *DrawStrokeParams)

TODO

func (*DrawContext) Text

func (c *DrawContext) Text(tl *DrawTextLayout, x, y float64)

Text draws tl in c with the top-left point of tl at (x, y).

func (*DrawContext) Transform

func (c *DrawContext) Transform(m *DrawMatrix)

TODO

type DrawFillMode

type DrawFillMode uint

TODO

TODO disclaimer

const (
	DrawFillModeWinding DrawFillMode = iota
	DrawFillModeAlternate
)

type DrawGradientStop

type DrawGradientStop struct {
	Pos float64 // between 0 and 1 inclusive
	R   float64
	G   float64
	B   float64
	A   float64
}

TODO

type DrawLineCap

type DrawLineCap int

TODO

TODO disclaimer TODO rename these to put LineCap at the beginning? or just Cap?

const (
	DrawLineCapFlat DrawLineCap = iota
	DrawLineCapRound
	DrawLineCapSquare
)

type DrawLineJoin

type DrawLineJoin int

TODO

TODO disclaimer

const (
	DrawLineJoinMiter DrawLineJoin = iota
	DrawLineJoinRound
	DrawLineJoinBevel
)

type DrawMatrix

type DrawMatrix struct {
	M11 float64
	M12 float64
	M21 float64
	M22 float64
	M31 float64
	M32 float64
}

TODO TODO should the methods of these return self for chaining?

func DrawNewMatrix

func DrawNewMatrix() *DrawMatrix

TODO identity matrix

func (*DrawMatrix) Invert

func (m *DrawMatrix) Invert() bool

TODO

If m is not invertible, false is returned and m is left unchanged.

func (*DrawMatrix) Invertible

func (m *DrawMatrix) Invertible() bool

TODO

func (*DrawMatrix) Multiply

func (m *DrawMatrix) Multiply(m2 *DrawMatrix)

TODO

func (*DrawMatrix) Rotate

func (m *DrawMatrix) Rotate(x float64, y float64, amount float64)

TODO

func (*DrawMatrix) Scale

func (m *DrawMatrix) Scale(xCenter float64, yCenter float64, x float64, y float64)

TODO

func (*DrawMatrix) SetIdentity

func (m *DrawMatrix) SetIdentity()

TODO

func (*DrawMatrix) Skew

func (m *DrawMatrix) Skew(x float64, y float64, xamount float64, yamount float64)

TODO

func (*DrawMatrix) TransformPoint

func (m *DrawMatrix) TransformPoint(x float64, y float64) (xout float64, yout float64)

TODO unimplemented

func (*DrawMatrix) TransformSize

func (m *DrawMatrix) TransformSize(x float64, y float64) (xout float64, yout float64)

TODO unimplemented

func (*DrawMatrix) Translate

func (m *DrawMatrix) Translate(x float64, y float64)

TODO

type DrawPath

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

DrawPath represents a geometric path in a drawing context. This is the basic unit of drawing: all drawing operations consist of forming a path, then stroking, filling, or clipping to that path. A path is an OS resource; you must explicitly free it when finished. Paths consist of multiple figures. Once you have added all the figures to a path, you must "end" the path to make it ready to draw with. TODO rewrite all that

Or more visually, the lifecycle of a Path is

p := DrawNewPath()
for every figure {
	p.NewFigure(...) // or NewFigureWithArc
	p.LineTo(...)    // any number of these in any order
	p.ArcTo(...)
	p.BezierTo(...)
	if figure should be closed {
		p.CloseFigure()
	}
}
p.End()
// ...
dp.Context.Stroke(p, ...) // any number of these in any order
dp.Context.Fill(p, ...)
dp.Context.Clip(p)
// ...
p.Free() // when done with the path

A DrawPath also defines its fill mode. (This should ideally be a fill parameter, but some implementations prevent it.) TODO talk about fill modes

func DrawNewPath

func DrawNewPath(fillMode DrawFillMode) *DrawPath

DrawNewPath creates a new DrawPath with the given fill mode.

func (*DrawPath) AddRectangle

func (p *DrawPath) AddRectangle(x float64, y float64, width float64, height float64)

AddRectangle creates a new figure in the DrawPath that consists entirely of a rectangle whose top-left corner is at the given point and whose size is the given size. The rectangle is a closed figure; you must either start a new figure or end the Path after calling this method.

func (*DrawPath) ArcTo

func (p *DrawPath) ArcTo(xCenter float64, yCenter float64, radius float64, startAngle float64, sweep float64, isNegative bool)

ArcTo adds a circular arc to the current figure of the DrawPath. You pass it the center of the arc, its radius in radians, the starting angle (couterclockwise) in radians, and the number of radians the arc should sweep (counterclockwise). A line segment is drawn from the current point to the start of the arc. The current point is set to the end of the arc.

func (*DrawPath) BezierTo

func (p *DrawPath) BezierTo(c1x float64, c1y float64, c2x float64, c2y float64, endX float64, endY float64)

BezierTo adds a cubic Bezier curve to the current figure of the DrawPath. Its start point is the current point. c1x and c1y are the first control point. c2x and c2y are the second control point. endX and endY are the end point. The current point is set to the end point.

func (*DrawPath) CloseFigure

func (p *DrawPath) CloseFigure()

CloseFigure draws a line segment from the current point of the current figure of the DrawPath back to its initial point. After calling this, the current figure is over and you must either start a new figure or end the DrawPath. If this is not called and you start a new figure or end the DrawPath, then the current figure will not have this closing line segment added to it (but the figure will still be over).

func (*DrawPath) End

func (p *DrawPath) End()

End ends the current DrawPath. You cannot add figures to a DrawPath that has been ended. You cannot draw with a DrawPath that has not been ended.

func (*DrawPath) Free

func (p *DrawPath) Free()

Free destroys a DrawPath. After calling Free the DrawPath cannot be used.

func (*DrawPath) LineTo

func (p *DrawPath) LineTo(x float64, y float64)

LineTo adds a line to the current figure of the DrawPath starting from the current point and ending at the given point. The current point is set to the ending point.

func (*DrawPath) NewFigure

func (p *DrawPath) NewFigure(x float64, y float64)

NewFigure starts a new figure in the DrawPath. The current point is set to the given point.

func (*DrawPath) NewFigureWithArc

func (p *DrawPath) NewFigureWithArc(xCenter float64, yCenter float64, radius float64, startAngle float64, sweep float64, isNegative bool)

NewFigureWithArc starts a new figure in the DrawPath and adds an arc as the first element of the figure. Unlike ArcTo, NewFigureWithArc does not draw an initial line segment. Otherwise, see ArcTo.

type DrawStrokeParams

type DrawStrokeParams struct {
	Cap        DrawLineCap
	Join       DrawLineJoin
	Thickness  float64
	MiterLimit float64
	Dashes     []float64
	DashPhase  float64
}

TODO

type DrawTextAlign

type DrawTextAlign int

DrawTextAlign specifies the alignment of lines of text in a DrawTextLayout. TODO should this really have Draw in the name?

const (
	DrawTextAlignLeft DrawTextAlign = iota
	DrawTextAlignCenter
	DrawTextAlignRight
)

type DrawTextLayout

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

DrawTextLayout is a concrete representation of an AttributedString that can be displayed in a DrawContext. It includes information important for the drawing of a block of text, including the bounding box to wrap the text within, the alignment of lines of text within that box, areas to mark as being selected, and other things.

Unlike AttributedString, the content of a DrawTextLayout is immutable once it has been created.

TODO talk about OS-specific differences with text drawing that libui can't account for...

func DrawNewTextLayout

func DrawNewTextLayout(p *DrawTextLayoutParams) *DrawTextLayout

DrawNewTextLayout() creates a new DrawTextLayout from the given parameters.

func (*DrawTextLayout) Free

func (tl *DrawTextLayout) Free()

Free frees tl. The underlying AttributedString is not freed.

type DrawTextLayoutParams

type DrawTextLayoutParams struct {
	String      *AttributedString
	DefaultFont *FontDescriptor
	Width       float64
	Align       DrawTextAlign
}

DrawTextLayoutParams describes a DrawTextLayout. DefaultFont is used to render any text that is not attributed sufficiently in String. Width determines the width of the bounding box of the text; the height is determined automatically.

type EditableCombobox

type EditableCombobox struct {
	ControlBase
	// contains filtered or unexported fields
}

EditableCombobox is a Control that represents a drop-down list of strings that the user can choose one of at any time. It also has an entry field that the user can type an alternate choice into.

func NewEditableCombobox

func NewEditableCombobox() *EditableCombobox

NewEditableCombobox creates a new EditableCombobox.

func (*EditableCombobox) Append

func (e *EditableCombobox) Append(text string)

Append adds the named item to the end of the EditableCombobox.

func (*EditableCombobox) OnChanged

func (e *EditableCombobox) OnChanged(f func(*EditableCombobox))

OnChanged registers f to be run when the user either selects an item or changes the text in the EditableCombobox. Only one function can be registered at a time.

func (*EditableCombobox) SetText

func (e *EditableCombobox) SetText(text string)

SetText sets the text in the entry of the EditableCombobox.

func (*EditableCombobox) Text

func (e *EditableCombobox) Text() string

Text returns the text in the entry of the EditableCombobox, which could be one of the choices in the list if the user has selected one.

type Entry

type Entry struct {
	ControlBase
	// contains filtered or unexported fields
}

Entry is a Control that represents a space that the user can type a single line of text into.

func NewEntry

func NewEntry() *Entry

NewEntry creates a new Entry.

func NewPasswordEntry

func NewPasswordEntry() *Entry

NewPasswordEntry creates a new Entry whose contents are visibly obfuscated, suitable for passwords.

func NewSearchEntry

func NewSearchEntry() *Entry

NewSearchEntry creates a new Entry suitable for searching with. Changed events may, depending on the system, be delayed with a search Entry, to produce a smoother user experience.

func (*Entry) CenterText

func (e *Entry) CenterText(center bool)

func (*Entry) OnChanged

func (e *Entry) OnChanged(f func(*Entry))

OnChanged registers f to be run when the user makes a change to the Entry. Only one function can be registered at a time.

func (*Entry) OnKeyEvent

func (e *Entry) OnKeyEvent(f func(*Entry, *AreaKeyEvent) (handled bool))

OnKeyEvent registers f to be run when the user makes a change to the Entry. Only one function can be registered at a time.

func (*Entry) ReadOnly

func (e *Entry) ReadOnly() bool

ReadOnly returns whether the Entry can be changed.

func (*Entry) SelectAllText

func (e *Entry) SelectAllText()

func (*Entry) SelectText

func (e *Entry) SelectText(start int, end int)

func (*Entry) SetFont

func (e *Entry) SetFont(name string, size int, weight TextWeight)

func (*Entry) SetMaxLength

func (e *Entry) SetMaxLength(max int)

func (*Entry) SetPasswordChar

func (e *Entry) SetPasswordChar(ch string)

func (*Entry) SetPrefSize

func (e *Entry) SetPrefSize(w, h int)

func (*Entry) SetReadOnly

func (e *Entry) SetReadOnly(ro bool)

SetReadOnly sets whether the Entry can be changed.

func (*Entry) SetText

func (e *Entry) SetText(text string)

SetText sets the Entry's text to text.

func (*Entry) Text

func (e *Entry) Text() string

Text returns the Entry's text.

func (*Entry) UnsetFocus

func (e *Entry) UnsetFocus()

type ExtKey

type ExtKey int

TODO document

Note: these must be numerically identical to their libui equivalents.

const (
	Escape ExtKey = iota + 1
	Insert        // equivalent to "Help" on Apple keyboards
	Delete
	Home
	End
	PageUp
	PageDown
	Up
	Down
	Left
	Right
	F1 // F1..F12 are guaranteed to be consecutive
	F2
	F3
	F4
	F5
	F6
	F7
	F8
	F9
	F10
	F11
	F12
	N0 // numpad keys; independent of Num Lock state
	N1 // N0..N9 are guaranteed to be consecutive
	N2
	N3
	N4
	N5
	N6
	N7
	N8
	N9
	NDot
	NEnter
	NAdd
	NSubtract
	NMultiply
	NDivide
)

type FontButton

type FontButton struct {
	ControlBase
	// contains filtered or unexported fields
}

FontButton is a Control that represents a button that the user can click to select a font.

func NewFontButton

func NewFontButton() *FontButton

NewFontButton creates a new FontButton.

func (*FontButton) Font

func (b *FontButton) Font() *FontDescriptor

Font returns the font currently selected in the FontButton.

func (*FontButton) OnChanged

func (b *FontButton) OnChanged(f func(*FontButton))

OnChanged registers f to be run when the user changes the currently selected font in the FontButton. Only one function can be registered at a time.

type FontDescriptor

type FontDescriptor struct {
	Family  TextFamily
	Size    TextSize
	Weight  TextWeight
	Italic  TextItalic
	Stretch TextStretch
}

FontDescriptor provides a complete description of a font where one is needed. Currently, this means as the default font of a DrawTextLayout and as the data returned by FontButton.

type Form

type Form struct {
	ControlBase
	// contains filtered or unexported fields
}

Form is a Control that holds a group of Controls vertically with labels next to each. By default, each control has its preferred height; if a control is marked "stretchy", it will take whatever space is left over. If multiple controls are marked stretchy, they will be given equal shares of the leftover space. There can also be space between each control ("padding").

func NewForm

func NewForm() *Form

NewForm creates a new horizontal Form.

func (*Form) Append

func (f *Form) Append(label string, child Control, stretchy bool)

Append adds the given control to the end of the Form.

func (*Form) Delete

func (f *Form) Delete(n int)

Delete deletes the nth control of the Form.

func (*Form) Destroy

func (f *Form) Destroy()

Destroy destroys the Form. If the Form has children, Destroy calls Destroy on those Controls as well.

func (*Form) Padded

func (f *Form) Padded() bool

Padded returns whether there is space between each control of the Form.

func (*Form) SetPadded

func (f *Form) SetPadded(padded bool)

SetPadded controls whether there is space between each control of the Form. The size of the padding is determined by the OS and its best practices.

type Grid

type Grid struct {
	ControlBase
	// contains filtered or unexported fields
}

Grid is a Control that arranges other Controls in a grid. Grid is a very powerful container: it can position and size each Control in several ways and can (and must) have Controls added to it in any direction. It can also have Controls spanning multiple rows and columns.

Each Control in a Grid has associated "expansion" and "alignment" values in both the X and Y direction. Expansion determines whether all cells in the same row/column are given whatever space is left over after figuring out how big the rest of the Grid should be. Alignment determines the position of a Control relative to its cell after computing the above. The special alignment Fill can be used to grow a Control to fit its cell. Note that expansion and alignment are independent variables. For more information on expansion and alignment, read https://developer.gnome.org/gtk3/unstable/ch28s02.html.

func NewGrid

func NewGrid() *Grid

NewGrid creates a new Grid.

func (*Grid) Append

func (g *Grid) Append(child Control, left, top int, xspan, yspan int, hexpand bool, halign Align, vexpand bool, valign Align)

Append adds the given control to the Grid, at the given coordinate.

func (*Grid) InsertAt

func (g *Grid) InsertAt(child Control, existing Control, at At, xspan, yspan int, hexpand bool, halign Align, vexpand bool, valign Align)

InsertAt adds the given control to the Grid relative to an existing control.

func (*Grid) Padded

func (g *Grid) Padded() bool

Padded returns whether there is space between each control of the Grid.

func (*Grid) SetPadded

func (g *Grid) SetPadded(padded bool)

SetPadded controls whether there is space between each control of the Grid. The size of the padding is determined by the OS and its best practices.

type Group

type Group struct {
	ControlBase
	// contains filtered or unexported fields
}

Group is a Control that holds another Control and wraps it around a labelled box (though some systems make this box invisible). You can use this to group related controls together.

func NewGroup

func NewGroup(title string) *Group

NewGroup creates a new Group.

func (*Group) Destroy

func (g *Group) Destroy()

Destroy destroys the Group. If the Group has a child, Destroy calls Destroy on that as well.

func (*Group) Margined

func (g *Group) Margined() bool

Margined returns whether the Group has margins around its child.

func (*Group) SetChild

func (g *Group) SetChild(child Control)

SetChild sets the Group's child to child. If child is nil, the Group will not have a child.

func (*Group) SetMargined

func (g *Group) SetMargined(margined bool)

SetMargined controls whether the Group has margins around its child. The size of the margins are determined by the OS and its best practices.

func (*Group) SetTitle

func (g *Group) SetTitle(title string)

SetTitle sets the Group's title to title.

func (*Group) Title

func (g *Group) Title() string

Title returns the Group's title.

type Image

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

Image stores an image for display on screen.

Images are built from one or more representations, each with the same aspect ratio but a different pixel size. Package ui automatically selects the most appropriate representation for drawing the image when it comes time to draw the image; what this means depends on the pixel density of the target context. Therefore, one can use Image to draw higher-detailed images on higher-density displays. The typical use cases are either:

  • have just a single representation, at which point all screens use the same image, and thus uiImage acts like a simple bitmap image, or
  • have two images, one at normal resolution and one at 2x resolution; this matches the current expectations of some desktop systems at the time of writing (mid-2018)

Image allocates OS resources; you must explicitly free an Image when you are finished with it.

func NewImage

func NewImage(width, height float64) *Image

NewImage creates a new Image with the given width and height. This width and height should be the size in points of the image in the device-independent case; typically this is the 1x size.

func (*Image) Append

func (i *Image) Append(img *image.RGBA)

Append adds the given image as a representation of the Image.

func (*Image) Free

func (i *Image) Free()

Free frees the Image.

type Label

type Label struct {
	ControlBase
	// contains filtered or unexported fields
}

Label is a Control that represents a line of text that cannot be interacted with.

func NewCenteredLabel

func NewCenteredLabel(text string) *Label

NewLabel creates a new Label with the given text.

func NewLabel

func NewLabel(text string) *Label

NewLabel creates a new Label with the given text.

func (*Label) SetFont

func (l *Label) SetFont(name string, size int, weight TextWeight)

func (*Label) SetMinSize

func (l *Label) SetMinSize(w int, h int)

func (*Label) SetText

func (l *Label) SetText(text string)

SetText sets the Label's text to text.

func (*Label) Text

func (l *Label) Text() string

Text returns the Label's text.

type Modifiers

type Modifiers uint

TODO document

Note: these must be numerically identical to their libui equivalents.

const (
	Ctrl Modifiers = 1 << iota
	Alt
	Shift
	Super
)

type MultilineEntry

type MultilineEntry struct {
	ControlBase
	// contains filtered or unexported fields
}

MultilineEntry is a Control that represents a space that the user can type multiple lines of text into.

func NewMultilineEntry

func NewMultilineEntry() *MultilineEntry

NewMultilineEntry creates a new MultilineEntry. The MultilineEntry soft-word-wraps and has no horizontal scrollbar.

func NewNonWrappingMultilineEntry

func NewNonWrappingMultilineEntry() *MultilineEntry

NewNonWrappingMultilineEntry creates a new MultilineEntry. The MultilineEntry does not word-wrap and thus has horizontal scrollbar.

func (*MultilineEntry) Append

func (m *MultilineEntry) Append(text string)

Append adds text to the end of the MultilineEntry's text. TODO selection and scroll behavior

func (*MultilineEntry) OnChanged

func (m *MultilineEntry) OnChanged(f func(*MultilineEntry))

OnChanged registers f to be run when the user makes a change to the MultilineEntry. Only one function can be registered at a time.

func (*MultilineEntry) ReadOnly

func (m *MultilineEntry) ReadOnly() bool

ReadOnly returns whether the MultilineEntry can be changed.

func (*MultilineEntry) SetReadOnly

func (m *MultilineEntry) SetReadOnly(ro bool)

SetReadOnly sets whether the MultilineEntry can be changed.

func (*MultilineEntry) SetText

func (m *MultilineEntry) SetText(text string)

SetText sets the MultilineEntry's text to text.

func (*MultilineEntry) Text

func (m *MultilineEntry) Text() string

Text returns the MultilineEntry's text.

type OpenTypeFeatures

type OpenTypeFeatures map[OpenTypeTag]uint32

OpenTypeFeatures is an Attribute that represents a set of OpenType feature tag-value pairs, for applying OpenType features to text. OpenType feature tags are four-character codes defined by OpenType that cover things from design features like small caps and swashes to language-specific glyph shapes and beyond. Each tag may only appear once in any given uiOpenTypeFeatures instance. Each value is a 32-bit integer, often used as a Boolean flag, but sometimes as an index to choose a glyph shape to use.

If a font does not support a certain feature, that feature will be ignored. (TODO verify this on all OSs)

See the OpenType specification at https://www.microsoft.com/typography/otspec/featuretags.htm for the complete list of available features, information on specific features, and how to use them. TODO invalid features

Note that if a feature is not present in a OpenTypeFeatures, the feature is NOT treated as if its value was zero, unlike in Go. Script-specific font shaping rules and font-specific feature settings may use a different default value for a feature. You should likewise NOT treat a missing feature as having a value of zero either. Instead, a missing feature should be treated as having some unspecified default value.

Note that despite OpenTypeFeatures being a map, its contents are copied by AttributedString. Modifying an OpenTypeFeatures after giving it to an AttributedString, or modifying one that comes out of an AttributedString, will have no effect.

type OpenTypeTag

type OpenTypeTag uint32

OpenTypeTag represents a four-byte OpenType feature tag.

func ToOpenTypeTag

func ToOpenTypeTag(a, b, c, d byte) OpenTypeTag

ToOpenTypeTag converts the four characters a, b, c, and d into an OpenTypeTag.

type ProgressBar

type ProgressBar struct {
	ControlBase
	// contains filtered or unexported fields
}

ProgressBar is a Control that represents a horizontal bar that is filled in progressively over time as a process completes.

func NewProgressBar

func NewProgressBar() *ProgressBar

NewProgressBar creates a new ProgressBar.

func (*ProgressBar) SetValue

func (p *ProgressBar) SetValue(value int)

SetValue sets the ProgressBar's currently displayed percentage to value. value must be between 0 and 100 inclusive, or -1 for an indeterminate progressbar.

func (*ProgressBar) Value

func (p *ProgressBar) Value() int

Value returns the value currently shown in the ProgressBar.

type RadioButtons

type RadioButtons struct {
	ControlBase
	// contains filtered or unexported fields
}

RadioButtons is a Control that represents a set of checkable buttons from which exactly one may be chosen by the user.

func NewRadioButtons

func NewRadioButtons() *RadioButtons

NewRadioButtons creates a new RadioButtons.

func (*RadioButtons) Append

func (r *RadioButtons) Append(text string)

Append adds the named button to the end of the RadioButtons.

func (*RadioButtons) OnSelected

func (r *RadioButtons) OnSelected(f func(*RadioButtons))

OnSelected registers f to be run when the user selects an option in the RadioButtons. Only one function can be registered at a time.

func (*RadioButtons) Selected

func (r *RadioButtons) Selected() int

Selected returns the index of the currently selected option in the RadioButtons, or -1 if no item is selected.

func (*RadioButtons) SetSelected

func (r *RadioButtons) SetSelected(index int)

SetSelected sets the currently selected option in the RadioButtons to index.

type Separator

type Separator struct {
	ControlBase
	// contains filtered or unexported fields
}

Separator is a Control that represents a horizontal line that visually separates controls.

func NewHorizontalSeparator

func NewHorizontalSeparator() *Separator

NewHorizontalSeparator creates a new horizontal Separator.

func NewVerticalSeparator

func NewVerticalSeparator() *Separator

NewVerticalSeparator creates a new vertical Separator.

type Slider

type Slider struct {
	ControlBase
	// contains filtered or unexported fields
}

Slider is a Control that represents a horizontal bar that represents a range of integers. The user can drag a pointer on the bar to select an integer.

func NewSlider

func NewSlider(min int, max int) *Slider

NewSlider creates a new Slider. If min >= max, they are swapped.

func (*Slider) OnChanged

func (s *Slider) OnChanged(f func(*Slider))

OnChanged registers f to be run when the user changes the value of the Slider. Only one function can be registered at a time.

func (*Slider) SetValue

func (s *Slider) SetValue(value int)

SetValue sets the Slider's current value to value.

func (*Slider) Value

func (s *Slider) Value() int

Value returns the Slider's current value.

type Spinbox

type Spinbox struct {
	ControlBase
	// contains filtered or unexported fields
}

Spinbox is a Control that represents a space where the user can enter integers. The space also comes with buttons to add or subtract 1 from the integer.

func NewSpinbox

func NewSpinbox(min int, max int) *Spinbox

NewSpinbox creates a new Spinbox. If min >= max, they are swapped.

func (*Spinbox) OnChanged

func (s *Spinbox) OnChanged(f func(*Spinbox))

OnChanged registers f to be run when the user changes the value of the Spinbox. Only one function can be registered at a time.

func (*Spinbox) SetValue

func (s *Spinbox) SetValue(value int)

SetValue sets the Spinbox's current value to value.

func (*Spinbox) Value

func (s *Spinbox) Value() int

Value returns the Spinbox's current value.

type Tab

type Tab struct {
	ControlBase
	// contains filtered or unexported fields
}

Tab is a Control that holds tabbed pages of Controls. Each tab has a label. The user can click on the tabs themselves to switch pages. Individual pages can also have margins.

func NewTab

func NewTab() *Tab

NewTab creates a new Tab.

func (*Tab) Append

func (t *Tab) Append(name string, child Control)

Append adds the given page to the end of the Tab.

func (*Tab) Delete

func (t *Tab) Delete(n int)

Delete deletes the nth page of the Tab.

func (*Tab) Destroy

func (t *Tab) Destroy()

Destroy destroys the Tab. If the Tab has pages, Destroy calls Destroy on the pages's Controls as well.

func (*Tab) InsertAt

func (t *Tab) InsertAt(name string, n int, child Control)

InsertAt adds the given page to the Tab such that it is the nth page of the Tab (starting at 0).

func (*Tab) Margined

func (t *Tab) Margined(n int) bool

Margined returns whether page n (starting at 0) of the Tab has margins around its child.

func (*Tab) NumPages

func (t *Tab) NumPages() int

NumPages returns the number of pages in the Tab.

func (*Tab) SetMargined

func (t *Tab) SetMargined(n int, margined bool)

SetMargined controls whether page n (starting at 0) of the Tab has margins around its child. The size of the margins are determined by the OS and its best practices.

type Table

type Table struct {
	ControlBase
	// contains filtered or unexported fields
}

Table is a Control that shows tabular data, allowing users to manipulate rows of such data at a time.

func NewTable

func NewTable(p *TableParams) *Table

NewTable creates a new Table with the specified parameters.

func (*Table) AppendButtonColumn

func (t *Table) AppendButtonColumn(name string, buttonModelColumn int, buttonClickableModelColumn int)

AppendButtonColumn appends a column to t that shows a button that the user can click on. When the user does click on the button, SetCellValue is called with a nil value and buttonModelColumn as the column. CellValue on buttonModelColumn should return the text to show in the button.

func (*Table) AppendCheckboxColumn

func (t *Table) AppendCheckboxColumn(name string, checkboxModelColumn int, checkboxEditableModelColumn int)

AppendCheckboxColumn appends a column to t that contains a checkbox that the user can interact with (assuming the checkbox is editable). SetCellValue will be called with checkboxModelColumn as the column in this case.

func (*Table) AppendCheckboxTextColumn

func (t *Table) AppendCheckboxTextColumn(name string, checkboxModelColumn int, checkboxEditableModelColumn int, textModelColumn int, textEditableModelColumn int, textParams *TableTextColumnOptionalParams)

AppendCheckboxTextColumn appends a column to t that contains both a checkbox and text.

func (*Table) AppendImageColumn

func (t *Table) AppendImageColumn(name string, imageModelColumn int)

AppendImageColumn appends an image column to t. Images are drawn at icon size, appropriate to the pixel density of the screen showing the Table.

func (*Table) AppendImageTextColumn

func (t *Table) AppendImageTextColumn(name string, imageModelColumn int, textModelColumn int, textEditableModelColumn int, textParams *TableTextColumnOptionalParams)

AppendImageTextColumn appends a column to t that shows both an image and text.

func (*Table) AppendProgressBarColumn

func (t *Table) AppendProgressBarColumn(name string, progressModelColumn int)

AppendProgressBarColumn appends a column to t that displays a progress bar. These columns work like ProgressBar: a cell value of 0..100 displays that percentage, and a cell value of -1 displays an indeterminate progress bar.

func (*Table) AppendTextColumn

func (t *Table) AppendTextColumn(name string, textModelColumn int, textEditableModelColumn int, textParams *TableTextColumnOptionalParams)

AppendTextColumn appends a text column to t. name is displayed in the table header. textModelColumn is where the text comes from. If a row is editable according to textEditableModelColumn, SetCellValue is called with textModelColumn as the column.

type TableColor

type TableColor struct {
	R float64
	G float64
	B float64
	A float64
}

TableColor is a TableValue that represents a color.

type TableImage

type TableImage struct {
	I *Image
}

TableImage is a TableValue that represents an Image. Ownership of the Image is not copied; you must keep it alive alongside the TableImage.

type TableInt

type TableInt int

TableInt is a TableValue that stores integers. These are used for progressbars. Due to current limitations of libui, they also represent checkbox states, via TableFalse and TableTrue.

const (
	TableFalse TableInt = 0
	TableTrue  TableInt = 1
)

TableFalse and TableTrue are the Boolean constants for TableInt.

type TableModel

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

TableModel is an object that provides the data for a Table. This data is returned via methods you provide in the TableModelHandler interface.

TableModel represents data using a table, but this table does not map directly to Table itself. Instead, you can have data columns which provide instructions for how to render a given Table's column — for instance, one model column can be used to give certain rows of a Table a different background color. Row numbers DO match with uiTable row numbers.

Once created, the number and data types of columns of a TableModel cannot change.

Row and column numbers start at 0. A TableModel can be associated with more than one Table at a time.

func NewTableModel

func NewTableModel(handler TableModelHandler) *TableModel

NewTableModel creates a new TableModel.

func (*TableModel) Free

func (m *TableModel) Free()

Free frees m. It is an error to Free any models associated with a Table.

func (*TableModel) RowChanged

func (m *TableModel) RowChanged(index int)

RowChanged tells any Tables associated with m that the data in the row at index has changed. You do not need to call this in your SetCellValue handlers, but you do need to call this if your data changes at some other point.

func (*TableModel) RowDeleted

func (m *TableModel) RowDeleted(index int)

RowDeleted tells any Tables associated with m that the row at index index has been deleted. You call this function when the number of rows in your model has changed; after calling it, NumRows should returm the new row count.

func (*TableModel) RowInserted

func (m *TableModel) RowInserted(index int)

RowInserted tells any Tables associated with m that a new row has been added to m at index index. You call this method when the number of rows in your model has changed; after calling it, NumRows should returm the new row count.

type TableModelHandler

type TableModelHandler interface {
	// ColumnTypes returns a slice of value types of the data
	// stored in the model columns of the TableModel.
	// Each entry in the slice should ideally be a zero value for
	// the TableValue type of the column in question; the number
	// of elements in the slice determines the number of model
	// columns in the TableModel. The returned slice must remain
	// constant through the lifetime of the TableModel. This
	// method is not guaranteed to be called depending on the
	// system.
	ColumnTypes(m *TableModel) []TableValue

	// NumRows returns the number or rows in the TableModel.
	// This value must be non-negative.
	NumRows(m *TableModel) int

	// CellValue returns a TableValue corresponding to the model
	// cell at (row, column). The type of the returned TableValue
	// must match column's value type. Under some circumstances,
	// nil may be returned; refer to the various methods that add
	// columns to Table for details.
	CellValue(m *TableModel, row, column int) TableValue

	// SetCellValue changes the model cell value at (row, column)
	// in the TableModel. Within this function, either do nothing
	// to keep the current cell value or save the new cell value as
	// appropriate. After SetCellValue is called, the Table will
	// itself reload the table cell. Under certain conditions, the
	// TableValue passed in can be nil; refer to the various
	// methods that add columns to Table for details.
	SetCellValue(m *TableModel, row, column int, value TableValue)
}

TableModelHandler defines the methods that TableModel calls when it needs data.

type TableParams

type TableParams struct {
	// Model is the TableModel to use for this uiTable.
	// This parameter cannot be nil.
	Model *TableModel

	// RowBackgroundColorModelColumn is a model column
	// number that defines the background color used for the
	// entire row in the Table, or -1 to use the default color for
	// all rows.
	//
	// If CellValue for this column for any row returns NULL, that
	// row will also use the default background color.
	RowBackgroundColorModelColumn int
}

TableParams defines the parameters passed to NewTable.

type TableString

type TableString string

TableString is a TableValue that stores a string. TableString is used for displaying text in a Table.

type TableTextColumnOptionalParams

type TableTextColumnOptionalParams struct {
	// ColorModelColumn is the model column containing the
	// text color of this Table column's text, or -1 to use the
	// default color.
	//
	// If CellValue for this column for any cell returns nil, that
	// cell will also use the default text color.
	ColorModelColumn int
}

TableTextColumnOptionalParams are the optional parameters that control the appearance of the text column of a Table.

type TableValue

type TableValue interface {
	// contains filtered or unexported methods
}

TableValue is a type that represents a piece of data that can come out of a TableModel.

type TextBackground

type TextBackground struct {
	R float64
	G float64
	B float64
	A float64
}

TextBackground is an Attribute that changes the background color of the text it is applied to.

type TextColor

type TextColor struct {
	R float64
	G float64
	B float64
	A float64
}

TextColor is an Attribute that changes the color of the text it is applied to.

type TextFamily

type TextFamily string

TextFamily is an Attribute that changes the font family of the text it is applied to. Font family names are case-insensitive.

type TextItalic

type TextItalic int

TextItalic is an Attribute that changes the italic mode of the text it is applied to. Italic represents "true" italics where the slanted glyphs have custom shapes, whereas oblique represents italics that are merely slanted versions of the normal glyphs. Most fonts usually have one or the other.

const (
	TextItalicNormal TextItalic = iota
	TextItalicOblique
	TextItalicItalic
)

type TextSize

type TextSize float64

TextSize is an Attribute that changes the size of the text it is applied to, in typographical points.

type TextStretch

type TextStretch int

TextStretch is an Attribute that changes the stretch (also called "width") of the text it is applied to.

Note that due to restrictions in early versions of Windows, some fonts have "special" stretches be exposed in many programs as separate font families. This is perhaps most notable with Arial Condensed. Package ui does not do this, even on Windows (because the DirectWrite API package ui uses on Windows does not do this); to specify Arial Condensed, use family Arial and stretch TextStretchCondensed.

const (
	TextStretchUltraCondensed TextStretch = iota
	TextStretchExtraCondensed
	TextStretchCondensed
	TextStretchSemiCondensed
	TextStretchNormal
	TextStretchSemiExpanded
	TextStretchExpanded
	TextStretchExtraExpanded
	TextStretchUltraExpanded
)

type TextWeight

type TextWeight int

TextWeight is an Attribute that changes the weight of the text it is applied to. These roughly map to the OS/2 text weight field of TrueType and OpenType fonts, or to CSS weight numbers. The named constants are nominal values; the actual values may vary by font and by OS, though this isn't particularly likely. Any value between TextWeightMinimum and TextWeightMaximum, inclusive, is allowed.

Note that due to restrictions in early versions of Windows, some fonts have "special" weights be exposed in many programs as separate font families. This is perhaps most notable with Arial Black. Package ui does not do this, even on Windows (because the DirectWrite API libui uses on Windows does not do this); to specify Arial Black, use family Arial and weight TextWeightBlack.

const (
	TextWeightMinimum    TextWeight = 0
	TextWeightThin       TextWeight = 100
	TextWeightUltraLight TextWeight = 200
	TextWeightLight      TextWeight = 300
	TextWeightBook       TextWeight = 350
	TextWeightNormal     TextWeight = 400
	TextWeightMedium     TextWeight = 500
	TextWeightSemiBold   TextWeight = 600
	TextWeightBold       TextWeight = 700
	TextWeightUltraBold  TextWeight = 800
	TextWeightHeavy      TextWeight = 900
	TextWeightUltraHeavy TextWeight = 950
	TextWeightMaximum    TextWeight = 1000
)

type Underline

type Underline int

Underline is an Attribute that specifies a type of underline to use on text.

const (
	UnderlineNone Underline = iota
	UnderlineSingle
	UnderlineDouble
	UnderlineSuggestion // wavy or dotted underlines used for spelling/grammar checkers
)

type UnderlineColor

type UnderlineColor int

UnderlineColor is an Attribute that changes the color of any underline on the text it is applied to, regardless of the type of underline. In addition to being able to specify the platform-specific colors for suggestion underlines here, you can also use a custom color with UnderlineColorCustom.

To use the constants here correctly, pair them with UnderlineSuggestion (though they can be used on other types of underline as well).

If an underline type is applied but no underline color is specified, the text color is used instead. If an underline color is specified without an underline type, the underline color attribute is ignored, but not removed from the uiAttributedString.

const (
	UnderlineColorSpelling UnderlineColor = iota + 1
	UnderlineColorGrammar
	UnderlineColorAuxiliary // for instance, the color used by smart replacements on macOS or in Microsoft Office
)

type UnderlineColorCustom

type UnderlineColorCustom struct {
	R float64
	G float64
	B float64
	A float64
}

UnderlineColorCustom is an Attribute like UnderlineColor, except it allows specifying a custom color.

type Window

type Window struct {
	ControlBase
	// contains filtered or unexported fields
}

Window is a Control that represents a top-level window. A Window contains one child Control that occupies the entirety of the window. Though a Window is a Control, a Window cannot be the child of another Control.

func NewWindow

func NewWindow(title string, width int, height int, hasMenubar bool) *Window

NewWindow creates a new Window.

func (*Window) Borderless

func (w *Window) Borderless() bool

Borderless returns whether the Window is borderless.

func (*Window) Destroy

func (w *Window) Destroy()

Destroy destroys the Window. If the Window has a child, Destroy calls Destroy on that as well.

func (*Window) Margined

func (w *Window) Margined() bool

Margined returns whether the Window has margins around its child.

func (*Window) OnClosing

func (w *Window) OnClosing(f func(*Window) bool)

OnClosing registers f to be run when the user clicks the Window's close button. Only one function can be registered at a time. If f returns true, the window is destroyed with the Destroy method. If f returns false, or if OnClosing is never called, the window is not destroyed and is kept visible.

func (*Window) OnResign

func (w *Window) OnResign(f func(*Window))

func (*Window) SetAlwaysVisible

func (w *Window) SetAlwaysVisible(set bool)

func (*Window) SetBackgroundColor

func (w *Window) SetBackgroundColor(r, g, b int)

func (*Window) SetBorderless

func (w *Window) SetBorderless(borderless bool)

SetBorderless sets the Window to be borderless or not.

func (*Window) SetCentered

func (w *Window) SetCentered()

func (*Window) SetChild

func (w *Window) SetChild(child Control)

SetChild sets the Window's child to child. If child is nil, the Window will not have a child.

func (*Window) SetMargined

func (w *Window) SetMargined(margined bool)

SetMargined controls whether the Window has margins around its child. The size of the margins are determined by the OS and its best practices.

func (*Window) SetTitle

func (w *Window) SetTitle(title string)

SetTitle sets the Window's title to title.

func (*Window) SetToFront

func (w *Window) SetToFront()

func (*Window) Title

func (w *Window) Title() string

Title returns the Window's title.

Directories

Path Synopsis
Package winmanifest provides a basic manifest for use with package ui.
Package winmanifest provides a basic manifest for use with package ui.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL