ui

type Area ¶

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

Area represents a blank canvas upon which programs may draw anything and receive arbitrary events from the user. An Area has an explicit size, represented in pixels, that may be different from the size shown in its Window; Areas have both horizontal and vertical scrollbars that are hidden when not needed. The coordinate system of an Area always has an origin of (0,0) which maps to the top-left corner; all image.Points and image.Rectangles sent across Area's channels conform to this. The size of an Area must be at least 1x1 (that is, neither its width nor its height may be zero or negative).

To handle events to the Area, an Area must be paired with an AreaHandler. See AreaHandler for details.

Do not use an Area if you intend to read text. Area reads keys based on their position on a standard 101-key keyboard, and does no character processing. Character processing methods differ across operating systems; trying ot recreate these yourself is only going to lead to trouble. [Use TextArea instead, providing a TextAreaHandler.]

To facilitate development and debugging, for the time being, Areas only work on GTK+.

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

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

type AreaHandler ¶

type AreaHandler interface {
	// Paint is called when the Area needs to be redrawn.
	// The part of the Area that needs to be redrawn is stored in cliprect.
	// Before Paint() is called, this region is cleared with a system-defined background color.
	// You MUST handle this event, and you MUST return a valid image, otherwise deadlocks and panicking will occur.
	// The image returned must have the same size as rect (but does not have to have the same origin points).
	// Example:
	// 	imgFromFile, _, err := image.Decode(file)
	// 	if err != nil { panic(err) }
	// 	img := image.NewRGBA(imgFromFile.Rect)
	// 	draw.Draw(img, img.Rect, imgFromFile, image.ZP, draw.Over)
	// 	// ...
	// 	func (h *myAreaHandler) Paint(rect image.Rectangle) *image.RGBA {
	// 		return img.SubImage(rect).(*image.RGBA)
	// 	}
	Paint(cliprect image.Rectangle) *image.RGBA

	// Mouse is called when the Area receives a mouse event.
	// You are allowed to do nothing in this handler (to ignore mouse events).
	// See MouseEvent for details.
	// If repaint is true, the Area is marked as needing to be redrawn.
	Mouse(e MouseEvent) (repaint bool)

	// Key is called when the Area receives a keyboard event.
	// You are allowed to do nothing except return false for handled in this handler (to ignore keyboard events).
	// Do not do nothing but return true for handled; this may have unintended consequences.
	// See KeyEvent for details.
	// If repaint is true, the Area is marked as needing to be redrawn.
	Key(e KeyEvent) (handled bool, repaint bool)
}

AreaHandler represents the events that an Area should respond to. These methods are all executed on the main goroutine, not necessarily the same one that you created the AreaHandler in; you are responsible for the thread safety of any members of the actual type that implements ths interface. (Having to use this interface does not strike me as being particularly Go-like, but the nature of Paint makes channel-based event handling a non-option; in practice, deadlocks occur.)

type Button ¶

type Button struct {
	// Clicked gets a message when the button is clicked.
	// You cannot change it once the Window containing the Button has been opened.
	// If you do not respond to this signal, nothing will happen.
	Clicked chan struct{}
	// contains filtered or unexported fields
}

A Button represents a clickable button with some text.

func NewButton(text string) (b *Button)

func (b *Button) SetText(text string)

func (b *Button) Text() string

type Checkbox ¶

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

A Checkbox is a clickable square with a label. The square can be either checked or unchecked. Checkboxes start out unchecked.

func NewCheckbox(text string) (c *Checkbox)

func (c *Checkbox) Checked() bool

func (c *Checkbox) SetText(text string)

func (c *Checkbox) Text() string

type Combobox ¶

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

A Combobox is a drop-down list of items, of which at most one can be selected at any given time. You may optionally make the combobox editable to allow custom items. Initially, no item will be selected (and no text entered in an editable Combobox's entry field).

func NewCombobox(items ...string) *Combobox

func NewEditableCombobox(items ...string) *Combobox

func (c *Combobox) Append(what ...string)

func (c *Combobox) Delete(index int)

func (c *Combobox) InsertBefore(what string, before int)

func (c *Combobox) Len() int

func (c *Combobox) SelectedIndex() int

func (c *Combobox) Selection() string

type Control ¶

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

A Control represents an UI control. Note that Control contains unexported members; this has the consequence that you can't build custom controls that interface directly with the system-specific code (fo rinstance, to import an unsupported control), or at least not without some hackery. If you want to make your own controls, create an Area and provide an AreaHandler that does what you need.

func Space() Control

type ExtKey ¶

type ExtKey uintptr

ExtKey represents keys that are not in the typewriter section of the keyboard.

const (
	Escape ExtKey = iota + 1
	Insert
	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 Grid ¶

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

A Grid arranges Controls in a two-dimensional grid. The height of each row and the width of each column is the maximum preferred height and width (respectively) of all the controls in that row or column (respectively). Controls are aligned to the top left corner of each cell. All Controls in a Grid maintain their preferred sizes by default; if a Control is marked as being "filling", it will be sized to fill its cell. Even if a Control is marked as filling, its preferred size is used to calculate cell sizes. One Control can be marked as "stretchy": when the Window containing the Grid is resized, the cell containing that Control resizes to take any remaining space; its row and column are adjusted accordingly (so other filling controls in the same row and column will fill to the new height and width, respectively). A stretchy Control implicitly fills its cell. All cooridnates in a Grid are given in (row,column) form with (0,0) being the top-left cell. Unlike other UI toolkit Grids, this Grid does not (yet? TODO) allow Controls to span multiple rows or columns. TODO differnet row/column control alignment

func NewGrid(nPerRow int, controls ...Control) *Grid

grid := NewGrid(3,
	control00, control01, control02,
	control10, control11, control12,
	control20, control21, control22)

func (g *Grid) SetFilling(row int, column int)

func (g *Grid) SetStretchy(row int, column int)

type KeyEvent ¶

type KeyEvent struct {
	// Key is a byte representing a character pressed
	// in the typewriter section of the keyboard.
	// The value, which is independent of whether the
	// Shift key is held, is a constant with one of the
	// following (case-sensitive) values, drawn according
	// to the key's position on the keyboard.
	//    ` 1 2 3 4 5 6 7 8 9 0 - =
	//     q w e r t y u i o p [ ] \
	//      a s d f g h j k l ; '
	//       z x c v b n m , . /
	// The actual key entered will be the key at the respective
	// position on the user's keyboard, regardless of the actual
	// layout. (Some keyboards move \ to either the row above
	// or the row below but in roughly the same spot; this is
	// accounted for. Some keyboards have an additonal key
	// to the left of 'z' or additional keys to the right of '='; these
	// cannot be read.)
	// In addition, Key will contain
	// - ' ' (space) if the spacebar was pressed
	// - '\t' if Tab was pressed, regardless of Modifiers
	// - '\n' if the typewriter Enter key was pressed
	// - '\b' if the typewriter Backspace key was pressed
	// If this value is zero, see ExtKey.
	Key byte

	// If Key is zero, ExtKey contains a predeclared identifier
	// naming an extended key. See ExtKey for details.
	// If both Key and ExtKey are zero, a Modifier by itself
	// was pressed. Key and ExtKey will not both be nonzero.
	ExtKey ExtKey

	// (TODO Modifiers alone needs to be figured out)
	// If a Key or ExtKey is pressed with Modifiers, then the following events WILL be sent:
	// 	[Modifiers != 0, Key/ExtKey == 0] (as the Modifiers keypress(es) will register separately)
	// 	[Modifiers != 0, Key/ExtKey != 0]
	// and the following WILL NOT be:
	// 	[Modifiers == 0, Key/ExtKey != 0]
	// unless the Modifiers were pressed after/released before the Key/ExtKey was.
	Modifiers Modifiers

	// If Up is true, the key was released; if not, the key was pressed.
	// There is no guarantee that all pressed keys shall have
	// corresponding release events (for instance, if the user switches
	// programs while holding the key down, then releases the key).
	// Keys that have been held down are reported as multiple
	// key press events.
	Up bool
}

A KeyEvent represents a keypress in an Area.

Key presses are based on their positions on a standard 101-key keyboard found on most computers. The names chosen for keys here are based on their names on US English QWERTY keyboards; see Key for details.

When you are finished processing the incoming event, return whether or not you did something in response to the given keystroke as the handled return of your AreaHandler's Key() implementation. If you send false, you indicate that you did not handle the keypress, and that the system should handle it instead. (Some systems will stop processing the keyboard event at all if you return true unconditionally, which may result in unwanted behavior like global task-switching keystrokes not being processed.)

Note that even given the above, some systems might intercept some keystrokes (like Alt-F4 on various Unix systems) before Area will ever see them (and the Area might get an incorrect KeyEvent in this case, but this is not guaranteed); be wary.

If a key is pressed that is not supported by Key, ExtKey, or Modifiers, no KeyEvent will be produced, and package ui will act as if false was returned for handled.

func (e KeyEvent) EffectiveKey() byte

type Label ¶

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

A Label is a static line of text used to mark other controls. Label text is drawn on a single line; text that does not fit is truncated.

func NewLabel(text string) *Label

func (l *Label) SetText(text string)

func (l *Label) Text() string

type LineEdit ¶

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

A LineEdit is a control which allows you to enter a single line of text.

func NewLineEdit(text string) *LineEdit

func NewPasswordEdit() *LineEdit

func (l *LineEdit) SetText(text string)

func (l *LineEdit) Text() string

type Listbox ¶

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

A Listbox is a vertical list of items, of which either at most one or any number of items can be selected at any given time. On creation, no item is selected. Listboxes have vertical scrollbars that are hidden when not needed. The presence of horizontal scrollbars is currently undefined.

func NewListbox(items ...string) *Listbox

func NewMultiSelListbox(items ...string) *Listbox

func (l *Listbox) Append(what ...string)

func (l *Listbox) Delete(index int)

func (l *Listbox) InsertBefore(what string, before int)

func (l *Listbox) Len() int

func (l *Listbox) SelectedIndices() []int

func (l *Listbox) Selection() []string

type Modifiers ¶

type Modifiers uintptr

Modifiers indicates modifier keys being held during an event. There is no way to differentiate between left and right modifier keys. As such, what KeyEvents get sent if the user does something unusual with both of a certain modifier key at once is (presently; TODO) undefined.

const (
	Ctrl  Modifiers = 1 << iota // the canonical Ctrl keys ([TODO] on Mac OS X, Control on others)
	Alt                         // the canonical Alt keys ([TODO] on Mac OS X, Meta on Unix systems, Alt on others)
	Shift                       // the Shift keys

)

type MouseEvent ¶

type MouseEvent struct {
	// Pos is the position of the mouse in the Area at the time of the event.
	// TODO rename to Pt or Point?
	Pos image.Point

	// If the event was generated by a mouse button being pressed, Down contains the ID of that button.
	// Otherwise, Down contains 0.
	// If Down contains nonzero, the Area will also receive keyboard focus.
	Down uint

	// If the event was generated by a mouse button being released, Up contains the ID of that button.
	// Otherwise, Up contains 0.
	// If both Down and Up are 0, the event represents mouse movement (with optional held buttons; see below).
	// Down and Up shall not both be nonzero.
	Up uint

	// If Down is nonzero, Count indicates the number of clicks: 1 for single-click, 2 for double-click.
	// If Count == 2, AT LEAST zero events with Count == 1 will have been sent prior.
	// (This is a platform-specific issue: some platforms send none, some send one, and some send two.)
	Count uint

	// Modifiers is a bit mask indicating the modifier keys being held during the event.
	Modifiers Modifiers

	// Held is a slice of button IDs that indicate which mouse buttons are being held during the event.
	// Held will not include Down and Up.
	// (TODO "There is no guarantee that Held is sorted."?)
	Held []uint
}

MouseEvent contains all the information for a mous event sent by Area.Mouse. Mouse button IDs start at 1, with 1 being the left mouse button, 2 being the middle mouse button, and 3 being the right mouse button. (TODO "If additional buttons are supported, they will be returned with 4 being the first additional button (XBUTTON1 on Windows), 5 being the second (XBUTTON2 on Windows), and so on."?) (TODO get the user-facing name for XBUTTON1/2; find out if there's a way to query available button count)

func (e MouseEvent) HeldBits() (h uintptr)

type ProgressBar ¶

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

A ProgressBar is a horizontal rectangle that fills up from left to right to indicate the progress of a long-running task. This progress is represented by an integer within the range [0,100], representing a percentage. Alternatively, a progressbar can show an animation indicating that progress is being made but how much is indeterminate. Newly-created ProgressBars default to showing 0% progress.

func NewProgressBar() *ProgressBar

func (p *ProgressBar) SetProgress(percent int)

type Stack ¶

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

A Stack stacks controls horizontally or vertically within the Stack's parent. A horizontal Stack gives all controls the same height and their preferred widths. A vertical Stack gives all controls the same width and their preferred heights. Any extra space at the end of a Stack is left blank. Some controls may be marked as "stretchy": when the Window they are in changes size, stretchy controls resize to take up the remaining space after non-stretchy controls are laid out. If multiple controls are marked stretchy, they are alloted equal distribution of the remaining space.

func NewHorizontalStack(controls ...Control) *Stack

func NewVerticalStack(controls ...Control) *Stack

func (s *Stack) SetStretchy(index int)

type Window ¶

type Window struct {
	// Closing gets a message when the user clicks the window's close button.
	// You cannot change it once the Window has been opened.
	// If you do not respond to this signal, nothing will happen; regardless of whether you handle the signal or not, the window will not be closed.
	Closing chan struct{}
	// contains filtered or unexported fields
}

Window represents an on-screen window.

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

func (w *Window) Hide()

func (w *Window) Open(control Control) (err error)

func (w *Window) SetSize(width int, height int) (err error)

func (w *Window) SetTitle(title string)

func (w *Window) Show()