diff options
| -rw-r--r-- | olddocs/redoproposal.md (renamed from redoproposal.md) | 0 | ||||
| -rw-r--r-- | stable.md | 1041 |
2 files changed, 0 insertions, 1041 deletions
diff --git a/redoproposal.md b/olddocs/redoproposal.md index 378ecbe..378ecbe 100644 --- a/redoproposal.md +++ b/olddocs/redoproposal.md diff --git a/stable.md b/stable.md deleted file mode 100644 index 3041dd1..0000000 --- a/stable.md +++ /dev/null @@ -1,1041 +0,0 @@ -# ui --- - import "github.com/andlabs/ui" - -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. - -autogenerated by windowsconstgen; do not edit - -autogenerated by windowsconstgen; do not edit - -## Usage - -```go -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. - -#### func Go - -```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 - -```go -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 - -```go -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. - -#### type Area - -```go -type Area struct { -} -``` - -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 - -```go -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 - -```go -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 - -```go -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 - -```go -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 - -```go -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{} -} -``` - -A Button represents a clickable button with some text. - -#### func NewButton - -```go -func NewButton(text string) (b *Button) -``` -NewButton creates a new button with the specified text. - -#### func (*Button) SetText - -```go -func (b *Button) SetText(text string) -``` -SetText sets the button's text. - -#### func (*Button) Text - -```go -func (b *Button) Text() string -``` -Text returns the button's text. - -#### type Checkbox - -```go -type Checkbox struct { -} -``` - -A Checkbox is a clickable square with a label. The square can be either checked -or unchecked. Checkboxes start out unchecked. - -#### func NewCheckbox - -```go -func NewCheckbox(text string) (c *Checkbox) -``` -NewCheckbox creates a new checkbox with the specified text. - -#### func (*Checkbox) Checked - -```go -func (c *Checkbox) Checked() bool -``` -Checked() returns whether or not the checkbox has been checked. - -#### func (*Checkbox) SetText - -```go -func (c *Checkbox) SetText(text string) -``` -SetText sets the checkbox's text. - -#### func (*Checkbox) Text - -```go -func (c *Checkbox) Text() string -``` -Text returns the checkbox's text. - -#### type Combobox - -```go -type Combobox struct { -} -``` - -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 - -```go -func NewCombobox(items ...string) *Combobox -``` -NewCombobox makes a new Combobox with the given items. - -#### func NewEditableCombobox - -```go -func NewEditableCombobox(items ...string) *Combobox -``` -NewEditableCombobox makes a new editable Combobox with the given items. - -#### func (*Combobox) Append - -```go -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 - -```go -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 - -```go -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 - -```go -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 - -```go -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 - -```go -func (c *Combobox) Selection() string -``` -Selection returns the current selection. - -#### type Control - -```go -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 - -```go -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 - -```go -type ExtKey uintptr -``` - -ExtKey represents keys that are not in the typewriter section of the keyboard. - -```go -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 - -```go -type Grid struct { -} -``` - -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 - -```go -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 - -```go -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 - -```go -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 - -```go -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 - -```go -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 - -```go -type Label struct { -} -``` - -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. TODO vertical -alignment - -#### func NewLabel - -```go -func NewLabel(text string) *Label -``` -NewLabel creates a new Label with the specified text. - -#### func (*Label) SetText - -```go -func (l *Label) SetText(text string) -``` -SetText sets the Label's text. - -#### func (*Label) Text - -```go -func (l *Label) Text() string -``` -Text returns the Label's text. - -#### type LineEdit - -```go -type LineEdit struct { -} -``` - -A LineEdit is a control which allows you to enter a single line of text. - -#### func NewLineEdit - -```go -func NewLineEdit(text string) *LineEdit -``` -NewLineEdit makes a new LineEdit with the specified text. - -#### func NewPasswordEdit - -```go -func NewPasswordEdit() *LineEdit -``` -NewPasswordEdit makes a new LineEdit which allows the user to enter a password. - -#### func (*LineEdit) SetText - -```go -func (l *LineEdit) SetText(text string) -``` -SetText sets the LineEdit's text. - -#### func (*LineEdit) Text - -```go -func (l *LineEdit) Text() string -``` -Text returns the LineEdit's text. - -#### type Listbox - -```go -type Listbox struct { -} -``` - -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 - -```go -func NewListbox(items ...string) *Listbox -``` -NewListbox creates a new single-selection Listbox with the given items loaded -initially. - -#### func NewMultiSelListbox - -```go -func NewMultiSelListbox(items ...string) *Listbox -``` -NewMultiSelListbox creates a new multiple-selection Listbox with the given items -loaded initially. - -#### func (*Listbox) Append - -```go -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 - -```go -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 - -```go -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 - -```go -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 - -```go -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 - -```go -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 - -```go -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. - -```go -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 - -```go -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 - -```go -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 - -```go -type ProgressBar struct { -} -``` - -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 - -```go -func NewProgressBar() *ProgressBar -``` -NewProgressBar creates a new ProgressBar. - -#### func (*ProgressBar) SetProgress - -```go -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 - -```go -type Stack struct { -} -``` - -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 - -```go -func NewHorizontalStack(controls ...Control) *Stack -``` -NewHorizontalStack creates a new Stack that arranges the given Controls -horizontally. - -#### func NewVerticalStack - -```go -func NewVerticalStack(controls ...Control) *Stack -``` -NewVerticalStack creates a new Stack that arranges the given Controls -vertically. - -#### func (*Stack) SetStretchy - -```go -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 - -```go -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{} -} -``` - -Window represents an on-screen window. - -#### func NewWindow - -```go -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) Create - -```go -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 - -```go -func (w *Window) Hide() -``` -Hide hides the window. - -#### func (*Window) MsgBox - -```go -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 - -```go -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 - -```go -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 - -```go -func (w *Window) SetSize(width int, height int) (err error) -``` -SetSize sets the window's size. - -#### func (*Window) SetTitle - -```go -func (w *Window) SetTitle(title string) -``` -SetTitle sets the window's title. - -#### func (*Window) Show - -```go -func (w *Window) Show() -``` -Show shows the window. |