ui

package module
v0.0.0-...-33155f7 Latest Latest
Warning

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

 Go to latest Published: Jun 30, 2014 License: MIT Imports: 8 Imported by: 0

README

Note to ALL users: please read and comment; the design of the package is fatally flawed but I want to know what people think of the fix.

Note to Mac users: there is a bug in Go 1.3 stable that causes cgo to crash trying to build this package. Please follow the linked bug report for detials.

Woah, lots of attention! Thanks!

Updates

  • 26 June 2014

    • Controls in Windows can now be spaced apart more naturally. Call w.SetSpaced(true) to opt in. Whether this will remain opt-in or whether the name will change is still unknown at this point.
    • There's a new function Layout() which provides high-level layout creation. The function was written by boppreh and details can be found here. Whether this function will stay in the main package or be moved to a subpackage is still unknown.
    • There is now Checkbox.SetChecked() to set the check state of a Checkbox programmatically.

  • 25 June 2014
    Labels by default now align themselves relative to the control they are next to. There is a new function NewStandaloneLabel() which returns a label whose text is aligned to the top-left corner of the alloted space regardless.

  • 11 June 2014
    I have decided to remove Mac OS X 10.6 support because it's only causing problems for building (and everyone else says I should anyway, including Mac developers!). This does break my original goal, but I'm going to have to break things sooner or later. Please let me know if any of you actually use this package on 10.6. (I personally don't like it when programs require 10.7 (or iOS 7, for that matter), but what are you gonna do?)

README

This is a placeholder README; the previous file (olddocs/oldREADME.md) was rather long and confusing. I'll be rewriting it properly soon.

Until then, here's the important things you need to know:

  • this package is very much incomplete; see stable.md for a list of what is guaranteed to not change at the API level — for everything newer, you have been warned!
  • this package requires Go 1.3, which is presently available as a RC build (source builds from go tip will work too)
    • I don't think the Windows side uses any Go 1.3 features, but just to be safe I'm going to say express caution
    • Unix builds need 1.3 to fix some type-checker bugs in cgo
    • Mac OS X builds need 1.3 because Go 1.3 adds Objective-C support to cgo
  • the Windows build does not need cgo unless you want to regenerate the zconstants_windows_*.go files; the other targets do
  • my plan is to target all versions of OSs that Go itself supports. I will, however, make concessions where appropriate. This means:
    • Windows: Windows XP or newer
    • Unix: this is trickier; I decided to settle on GTK+ 3.4 or newer as Ubuntu 12.04 LTS ships with it
    • Mac OS X: Mac OS X 10.7 or newer (Go supports 10.6 but this is a pain to compile Cocoa programs for due to flaws in the later header files)
  • for the Windows build, you won't need to provide a comctl32.dll version 6 manifest, as the package produces its own
    • comctl32.dll version 6 is required for proper functioning!

andlabs/wakeup is a repository that provides a sample application.

If you are feeling adventurous, running ./test.sh (which accepts go build options) from within the package directory will build a test program which I use to make sure everything works. (I'm not sure how to do automated tests for a package like this, so go test will say no tests found for now; sorry.) If you are cross-compiling to Windows, you will need to have a very specific Go setup which allows multiple cross-compilation setups in a single installation; this requires a CL which won't be in Go 1.3 but may appear in Go 1.4 if accepted and both windows/386 and windows/amd64 set up for cgo. (This is because ./test.sh on Windows targets invariably regenerates the zconstants_windows_*.go files; there is no option to turn it off lest I become complacent and use it myself.)

Finally, please send documentation suggestions! I'm taking the documentation of this package very seriously because I don't want to make anything ambiguous. (Trust me, ambiguity in API documentation was a pain when writing this...)

Thanks!

(Note: I temporarily disabled Travis.ci; if I can figure out how to do good cross-compiles with it, then I can put it back.)

Screenshots

You asked for them; here they are.

Image Description
The test program on Windows 7
The test program on Mac OS X 10.8
The test program on Ubuntu 14.04 with KDE and the oxygen-gtk theme

Documentation

Overview

Package ui is a simple package which provides a way to write portable GUI programs quickly and easily. It aims to run on as many systems as Go itself, but presently has support for Windows, Mac OS X, and other Unix systems using the Windows API, Cocoa, and GTK+ 3, respectively. It also aims to be Go-like: events are transmitted via channels, and the library is fully safe for concurrent use.

To use the library, place your main program code in another function and call Go(), passing that function as a parameter. (This is necessary due to threading restrictions on some environments, such as Cocoa.) Once in the function you pass to Go(), you can safely use the rest of the library. When this function returns, so does Go(), and package functions become unavailable.

Building GUIs is as simple as creating a Window, populating it with Controls, and then calling Open() on the Window. A Window only has one Control: you pack multiple Controls into a Window by arranging them in layouts (Layouts are also Controls). There are presently two Layouts, Stack and Grid, each with different semantics on sizing and placement. See their documentation.

Once a Window is open, you cannot make layout or event channel changes.

Once your Window is open, you can begin to handle events. Handling events is simple: because all events are channels exposed as exported members of the Window and Control types, simply select on them. Event channels are initialized by default. However, before you Open a Window, you can freely reassign event channels, such that multiple events trigger the same channel, making event logic more compact. You may also choose not to handle events; events are sent asynchronously so the GUI loop is not initerrupted.

Here is a simple, complete program that asks the user for their name and greets them after clicking a button. 

package main

import (
	"github.com/andlabs/ui"
)

func myMain() {
	w := ui.NewWindow("Hello", 400, 100)
	ui.AppQuit = w.Closing		// treat quitting the application like closing the main window
	nameField := ui.NewLineEdit("Enter Your Name Here")
	button := ui.NewButton("Click Here For a Greeting")
	w.Open(ui.NewVerticalStack(nameField, button))

	for {
		select {
		case <-w.Closing:		// user tries to close the window or quit the program
			return
		case <-button.Clicked:	// user clicked the button
			ui.MsgBox(w, "Hello, " + nameField.Text() + "!", "")
		}
	}
}

func main() {
	err := ui.Go(myMain)
	if err != nil {
		panic(err)
	}
}

On Dialogs

The following functions provide dialogs. They exist both in package scope and as methods on Window. 

MsgBox()
MsgBoxError()

Dialogs opened by using the package-scope functions are modal to the entire application: the user cannot interact with any other window until they are dismissed. Whether or not resizing Windows will still be allowed is implementation-defined; if the implementation does allow it, resizes will still work properly. Whether or not the dialog box stays above all other Windows in the program is also implementation-defined.

Dialogs opened by using the Window methods are modal to the receiver Window only. Attempts to interact with the receiver Window will be blocked, but all other Windows in the application can still be used properly. The dialog box will also stay above the receiver Window. Whether the receiver Window can be resized while the dialog box is displayed is implementation-defined, but will work properly if allowed. If the receiver Window has not yet been created, the methods panic. If the receiver Window has not been shown yet or is currently hidden, what the methods do is implementation-defined.

The return type also differs between the two types of functions. Both ultimately either yield a signal that the dialog has been dismissed or a code specifying what the user decided to do with the dialog (if it has multiple choices). The package-scope functions wait for the dialog box to be dismissed and merely return the code (or nothing if no code is needed). The Window methods return immediately with a channel that will eventually receive either the signal or the return code. Package ui does not close these channels, nor does it send multiple values on the same channel.

Scrollbars

The following Controls have scrolling support built in: 

Listbox *
Area

All of the above controls have both horizontal and vertical scrollbars. These scrollbars hide themselves when not needed.

[FUTURE DISCUSSIONS: scrolling programmatically, MouseEvent/KeyEvent scroll overrides]

[FUTURE PLAN: Controls that are not marked with a * in the above list can have their scrollbars disabled completely in code.]

The result of resizing the window such that the scrollbars consider themselves too small is implementation-defined.

Index

Constants

This section is empty.

Variables

View Source 
var AppQuit chan struct{}

AppQuit is pulsed when the user decides to quit the program if their operating system provides a facility for quitting an entire application, rather than merely close all windows (for instance, Mac OS X via the Dock icon). You should assign one of your Windows's Closing to this variable so the user choosing to quit the application is treated the same as closing that window. If you do not respond to this signal, nothing will happen; regardless of whether or not you respond to this signal, the application will not quit. Do not merely check this channel alone; it is not guaranteed to be pulsed on all systems or in all conditions.

Functions

func Go 

func Go(main func()) error

Go sets up the UI environment and runs main in a goroutine. If initialization fails, Go returns an error and main is not called. Otherwise, Go does not return to its caller until main does, at which point it returns nil. After it returns, you cannot call future ui functions/methods meaningfully.

It is not safe to call ui.Go() in a goroutine. It must be called directly from main().

This model is undesirable, but Cocoa limitations require it.

Go does not process the command line for flags (that is, it does not call flag.Parse()), nor does package ui add any of the underlying toolkit's supported command-line flags. If you must, and if the toolkit also has environment variable equivalents to these flags (for instance, GTK+), use those instead.

func MsgBox 

func MsgBox(primaryText string, secondaryText string)

MsgBox displays an informational message box to the user with just an OK button. primaryText should be a short string describing the message, and will be displayed with additional emphasis on platforms that support it. Optionally, secondaryText can be used to show additional information. If you pass an empty string for secondaryText, neither additional information nor space for additional information will be shown. On platforms that allow for the message box window to have a title, os.Args[0] is used.

See "On Dialogs" in the package overview for behavioral information.

func MsgBoxError 

func MsgBoxError(primaryText string, secondaryText string)

MsgBoxError displays a message box to the user with just an OK button and an icon indicating an error. Otherwise, it behaves like MsgBox.

See "On Dialogs" in the package overview for more information.

Types

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. For information on scrollbars, see "Scrollbars" in the Overview. 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). For control layout purposes, an Area prefers to be at the size you set it to (so if an Area is not stretchy in its layout, it will ask to have that size).

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. [FOR FUTURE PLANNING Use TextArea instead, providing a TextAreaHandler.]

func NewArea 

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

NewArea creates a new Area with the given size and handler. It panics if handler is nil or if width or height is zero or negative.

func (*Area) RepaintAll 

func (a *Area) RepaintAll()

RepaintAll signals the entirety of the Area for redraw. If called before the Window containing the Area is created, RepaintAll does nothing.

func (*Area) SetSize 

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

SetSize sets the Area's internal drawing size. It has no effect on the actual control size. SetSize is safe for concurrent use; if the Area is being repainted or is handling an event, SetSize will wait for that to complete before changing the Area's size. SetSize will also signal the entirety of the Area to be redrawn as in RepaintAll. It panics if width or height is zero or negative.

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.
	// After handling the mouse event, package ui will decide whether to perform platform-dependent event chain continuation based on that platform's designated action (so it is not possible to override global mouse events this way).
	Mouse(e MouseEvent) (repaint bool)

	// Key is called when the Area receives a keyboard event.
	// You are allowed to do nothing in this handler (to ignore keyboard events).
	// See KeyEvent for details.
	// If repaint is true, the Area is marked as needing to be redrawn.
	// After handling the key event, package ui will decide whether to perform platform-dependent event chain continuation based on that platform's designated action (so it is not possible to override global key events, such as Alt-Tab, this way).
	Key(e KeyEvent) (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 created.
	// 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 

func NewButton(text string) (b *Button)

NewButton creates a new button with the specified text.

func (*Button) SetText 

func (b *Button) SetText(text string)

SetText sets the button's text.

func (*Button) Text 

func (b *Button) Text() string

Text returns the button's text.

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 

func NewCheckbox(text string) (c *Checkbox)

NewCheckbox creates a new checkbox with the specified text.

func (*Checkbox) Checked 

func (c *Checkbox) Checked() bool

Checked() returns whether or not the Checkbox has been checked.

func (*Checkbox) SetChecked 

func (c *Checkbox) SetChecked(checked bool)

SetChecked() changes the checked state of the Checkbox.

func (*Checkbox) SetText 

func (c *Checkbox) SetText(text string)

SetText sets the checkbox's text.

func (*Checkbox) Text 

func (c *Checkbox) Text() string

Text returns the checkbox's text.

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). What happens to the text shown in a Combobox if its width is too small is implementation-defined.

func NewCombobox 

func NewCombobox(items ...string) *Combobox

NewCombobox makes a new Combobox with the given items.

func NewEditableCombobox 

func NewEditableCombobox(items ...string) *Combobox

NewEditableCombobox makes a new editable Combobox with the given items.

func (*Combobox) Append 

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

Append adds items to the end of the Combobox's list. Append will panic if something goes wrong on platforms that do not abort themselves.

func (*Combobox) Delete 

func (c *Combobox) Delete(index int)

Delete removes the given item from the Combobox. It panics if the given index is out of bounds.

func (*Combobox) InsertBefore 

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

InsertBefore inserts a new item in the Combobox before the item at the given position. It panics if the given index is out of bounds. InsertBefore will also panic if something goes wrong on platforms that do not abort themselves.

func (*Combobox) Len 

func (c *Combobox) Len() int

Len returns the number of items in the Combobox.

On platforms for which this function may return an error, it panics if one is returned.

func (*Combobox) SelectedIndex 

func (c *Combobox) SelectedIndex() int

SelectedIndex returns the index of the current selection in the Combobox. It returns -1 either if no selection was made or if text was manually entered in an editable Combobox.

func (*Combobox) Selection 

func (c *Combobox) Selection() string

Selection returns the current selection.

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 

func Space() Control

Space returns a null Control intended for padding layouts with blank space. It appears to its owner as a Control of 0x0 size.

For a Stack, Space can be used to insert spaces in the beginning or middle of Stacks (Stacks by nature handle spaces at the end themselves). In order for this to work properly, make the Space stretchy.

For a Grid, Space can be used to have an empty cell. A stretchy Grid cell with a Space can be used to anchor the perimeter of a Grid to the respective Window edges without making one of the other controls stretchy instead (leaving empty space in the Window otherwise). Otherwise, you do not need to do anything special for the Space to work (though remember that an entire row or column of Spaces will appear as having height or width zero, respectively, unless one is marked as stretchy).

The value returned from Space() may or may not be unique.

type ExtKey 

type ExtKey uintptr

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

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 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.

func NewGrid 

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

NewGrid creates a new Grid with the given Controls. NewGrid needs to know the number of Controls in a row (alternatively, the number of columns); it will determine the number in a column from the number of Controls given. NewGrid panics if not given a full grid of Controls. Example: 

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

func (*Grid) SetFilling 

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

SetFilling marks the given Control of the Grid as filling its cell instead of staying at its preferred size. This function cannot be called after the Window that contains the Grid has been created. It panics if the given coordinate is invalid.

func (*Grid) SetStretchy 

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

SetStretchy marks the given Control of the Grid as stretchy. Stretchy implies filling. Only one control can be stretchy per Grid; calling SetStretchy multiple times merely changes which control is stretchy. This function cannot be called after the Window that contains the Grid has been created. It panics if the given coordinate is invalid.

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

	// If both Key and ExtKey are zero, Modifier will contain exactly one of its bits set, indicating which Modifier was pressed or released.
	// As with Modifiers itself, there is no way to differentiate between left and right modifier keys.
	// As such, the result of pressing and/or releasing both left and right of the same Modifier is system-defined.
	// Furthermore, the result of holding down a Key or ExtKey, then pressing a Modifier, and then releasing the original key is system-defined.
	// Under no condition shall Key, ExtKey, AND Modifier all be zero.
	Modifier Modifiers

	// Modifiers contains all the modifier keys currently being held at the time of the KeyEvent.
	// If Modifier is nonzero, Modifiers will not contain Modifier itself.
	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.

If a key is pressed that is not supported by Key, ExtKey, or Modifiers, no KeyEvent will be produced.

func (KeyEvent) EffectiveKey 

func (e KeyEvent) EffectiveKey() byte

EffectiveKey returns e.Key if it is set. Otherwise, if e.ExtKey denotes a numpad key, EffectiveKey returns the equivalent e.Key value ('0'..'9', '.', '\n', '+', '-', '*', or '/'). Otherwise, EffectiveKey returns zero.

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. A Label can appear in one of two places: bound to a control or standalone. This determines the vertical alignment of the label.

func NewLabel 

func NewLabel(text string) *Label

NewLabel creates a new Label with the specified text. The label is set to be bound to a control, so its vertical position depends on its vertical cell size in an implementation-defined manner.

func NewStandaloneLabel 

func NewStandaloneLabel(text string) *Label

NewStandaloneLabel creates a new Label with the specified text. The label is set to be standalone, so its vertical position will always be at the top of the vertical space assigned to it.

func (*Label) SetText 

func (l *Label) SetText(text string)

SetText sets the Label's text.

func (*Label) Text 

func (l *Label) Text() string

Text returns the Label's text.

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 

func NewLineEdit(text string) *LineEdit

NewLineEdit makes a new LineEdit with the specified text.

func NewPasswordEdit 

func NewPasswordEdit() *LineEdit

NewPasswordEdit makes a new LineEdit which allows the user to enter a password.

func (*LineEdit) SetText 

func (l *LineEdit) SetText(text string)

SetText sets the LineEdit's text.

func (*LineEdit) Text 

func (l *LineEdit) Text() string

Text returns the LineEdit's text.

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. For information on scrollbars, see "Scrollbars" in the Overview. Due to implementation issues, the presence of horizontal scrollbars is currently implementation-defined.

func NewListbox 

func NewListbox(items ...string) *Listbox

NewListbox creates a new single-selection Listbox with the given items loaded initially.

func NewMultiSelListbox 

func NewMultiSelListbox(items ...string) *Listbox

NewMultiSelListbox creates a new multiple-selection Listbox with the given items loaded initially.

func (*Listbox) Append 

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

Append adds items to the end of the Listbox's list. Append will panic if something goes wrong on platforms that do not abort themselves.

func (*Listbox) Delete 

func (l *Listbox) Delete(index int)

Delete removes the given item from the Listbox. It panics if the given index is out of bounds.

func (*Listbox) InsertBefore 

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

InsertBefore inserts a new item in the Listbox before the item at the given position. It panics if the given index is out of bounds. InsertBefore will also panic if something goes wrong on platforms that do not abort themselves.

func (*Listbox) Len 

func (l *Listbox) Len() int

Len returns the number of items in the Listbox.

On platforms for which this function may return an error, it panics if one is returned.

func (*Listbox) SelectedIndices 

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

SelectedIndices returns a list of the currently selected indexes in the Listbox, or an empty list if none have been selected. This list will have at most one item on a single-selection Listbox.

func (*Listbox) Selection 

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

Selection returns a list of strings currently selected in the Listbox, or an empty list if none have been selected. This list will have at most one item on a single-selection Listbox.

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 undefined. 

const (
	Ctrl  Modifiers = 1 << iota // the keys labelled Ctrl or Control on all platforms
	Alt                         // the keys labelled Alt or Option or Meta on all platforms
	Shift                       // the Shift keys
	Super                       // the Super keys on platforms that have one, or the Windows keys on Windows, or the Command keys on Mac OS X
)

type MouseEvent 

type MouseEvent struct {
	// Pos is the position of the mouse in the Area at the time of the event.
	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 for dragging; 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, 3 for triple-click, and so on.
	// The order of events will be Down:Count=1 -> Up -> Down:Count=2 -> Up -> Down:Count=3 -> Up -> ...
	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.
	// Held will be sorted.
	// Only buttons 1, 2, and 3 are guaranteed to be detected by Held properly; whether or not any others are is implementation-defined.
	//
	// If Held is non-empty but Up and Down are both zero, the mouse is being dragged, with all the buttons in Held being held.
	// Whether or not a drag into an Area generates MouseEvents is implementation-defined.
	// Whether or not a drag over an Area when the program is inactive generates MouseEvents is also implementation-defined.
	// Moving the mouse over an Area when the program is inactive and no buttons are held will, however, generate MouseEvents.
	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. If additional buttons are supported, they will be returned with 4 being the first additional button. For example, on Unix systems where mouse buttons 4 through 7 are pseudobuttons for the scroll wheel directions, the next button, button 8, will be returned as 4, 9 as 5, etc. The association between button numbers and physical buttons are system-defined. For example, on Windows, buttons 4 and 5 are mapped to what are internally referred to as "XBUTTON1" and "XBUTTON2", which often correspond to the dedicated back/forward navigation buttons on the sides of many mice. The examples here are NOT a guarantee as to how many buttons maximum will be available on a given system.

If the user clicked on the Area to switch to the Window it is contained in from another window in the OS, the Area will receive a MouseEvent for that click.

func (MouseEvent) HeldBits 

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

HeldBits returns Held as a bit mask. Bit 0 maps to button 1, bit 1 maps to button 2, etc.

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 

func NewProgressBar() *ProgressBar

NewProgressBar creates a new ProgressBar.

func (*ProgressBar) SetProgress 

func (p *ProgressBar) SetProgress(percent int)

SetProgress sets the currently indicated progress amount on the ProgressBar. If percent is in the range [0,100], the progressBar shows that much percent complete. If percent is -1, the ProgressBar is made indeterminate. Otherwise, SetProgress panics. Calling SetProgress(-1) repeatedly will neither leave indeterminate mode nor stop any animation involved in indeterminate mode indefinitely; any other side-effect of doing so is implementation-defined.

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 Layout 

func Layout(controls ...Control) *Stack

Creates a new Stack from the given controls. The topmost Stack will have vertical orientation and margin borders, with each nested stack being oriented oppositely. Controls are displayed with a default padding between them.

func NewHorizontalStack 

func NewHorizontalStack(controls ...Control) *Stack

NewHorizontalStack creates a new Stack that arranges the given Controls horizontally.

func NewVerticalStack 

func NewVerticalStack(controls ...Control) *Stack

NewVerticalStack creates a new Stack that arranges the given Controls vertically.

func (*Stack) SetStretchy 

func (s *Stack) SetStretchy(index int)

SetStretchy marks a control in a Stack as stretchy. This cannot be called once the Window containing the Stack has been created. It panics if index is out of range.

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 created.
	// 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 

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

NewWindow allocates a new Window with the given title and size. The window is not created until a call to Create() or Open().

func (*Window) Center 

func (w *Window) Center()

Center centers the Window on-screen. The concept of "screen" in the case of a multi-monitor setup is implementation-defined. It presently panics if the Window has not been created.

func (*Window) Create 

func (w *Window) Create(control Control)

Create creates the Window, setting its control to the given control. It does not show the window. This can only be called once per window, and finalizes all initialization of the control.

func (*Window) Hide 

func (w *Window) Hide()

Hide hides the window.

func (*Window) MsgBox 

func (w *Window) MsgBox(primaryText string, secondaryText string) (done chan struct{})

MsgBox is the Window method version of the package-scope function MsgBox. See that function's documentation and "On Dialogs" in the package overview for more information.

func (*Window) MsgBoxError 

func (w *Window) MsgBoxError(primaryText string, secondaryText string) (done chan struct{})

MsgBoxError is the Window method version of the package-scope function MsgBoxError. See that function's documentation and "On Dialogs" in the package overview for more information.

func (*Window) Open 

func (w *Window) Open(control Control)

Open creates the Window with Create and then shows the Window with Show. As with Create, you cannot call Open more than once per window.

func (*Window) SetSize 

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

SetSize sets the window's size.

func (*Window) SetSpaced 

func (w *Window) SetSpaced(spaced bool)

SetSpaced sets whether the Window's child control takes padding and spacing into account. That is, with w.SetSpaced(true), w's child will have a margin around the window frame and will have sub-controls separated by an implementation-defined amount. Currently, only Stack and Grid explicitly understand this property. This property is visible recursively throughout the widget hierarchy of the Window. This property cannot be set after the Window has been created.

func (*Window) SetTitle 

func (w *Window) SetTitle(title string)

SetTitle sets the window's title.

func (*Window) Show 

func (w *Window) Show()

Show shows the window.

Source Files

View all Source files

Directories

Path Synopsis
27 march 2014 11 february 2014 26 june 2014
 27 march 2014 11 february 2014 26 june 2014
24 may 2014
 24 may 2014

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.