Pinned (or marked for later pinninig) behavior of various controls; also improved Space()'s documentation.

combobox.go

@@ -6,7 +6,7 @@ import (
 	"sync"
 )
 
-// A Combobox is a drop-down list of items, of which only one can be selected at any given time. You may optionally make the combobox editable to allow custom items.
+// 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).
 type Combobox struct {
 	// TODO Select event
 
@@ -53,7 +53,7 @@ func (c *Combobox) Append(what ...string) (err error) {
 	return nil
 }
 
-// InsertBefore inserts a new item in the Combobox before the item at the given position.
+// InsertBefore inserts a new item in the Combobox before the item at the given position. (TODO action if before is out of bounds)
 func (c *Combobox) InsertBefore(what string, before int) (err error) {
 	c.lock.Lock()
 	defer c.lock.Unlock()
@@ -68,7 +68,7 @@ func (c *Combobox) InsertBefore(what string, before int) (err error) {
 	return nil
 }
 
-// Delete removes the given item from the Combobox.
+// Delete removes the given item from the Combobox. (TODO action if index is out of bounds)
 func (c *Combobox) Delete(index int) error {
 	c.lock.Lock()
 	defer c.lock.Unlock()

grid.go

@@ -68,6 +68,7 @@ func NewGrid(nPerRow int, controls ...Control) *Grid {
 
 // SetFilling sets 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.
+// (TODO action if coorindate invalid)
 func (g *Grid) SetFilling(row int, column int) {
 	g.lock.Lock()
 	defer g.lock.Unlock()
@@ -81,6 +82,7 @@ func (g *Grid) SetFilling(row int, column int) {
 // SetStretchy sets the given Control of the Grid as stretchy.
 // Stretchy implies filling.
 // This function cannot be called after the Window that contains the Grid has been created.
+// (TODO action if coorindate invalid)
 func (g *Grid) SetStretchy(row int, column int) {
 	g.lock.Lock()
 	defer g.lock.Unlock()

listbox.go

@@ -6,7 +6,8 @@ import (
 	"sync"
 )
 
-// A Listbox is a vertical list of items, of which one or (optionally) more items can be selected at any given time.
+// 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.
 type Listbox struct {
 	// TODO Select event
 
@@ -45,6 +46,7 @@ func (l *Listbox) Append(what ...string) (err error) {
 }
 
 // InsertBefore inserts a new item in the Listbox before the item at the given position.
+// (TODO action on invalid index)
 func (l *Listbox) InsertBefore(what string, before int) (err error) {
 	l.lock.Lock()
 	defer l.lock.Unlock()
@@ -60,6 +62,7 @@ func (l *Listbox) InsertBefore(what string, before int) (err error) {
 }
 
 // Delete removes the given item from the Listbox.
+// (TODO action on invalid index)
 func (l *Listbox) Delete(index int) error {
 	l.lock.Lock()
 	defer l.lock.Unlock()

stack.go

@@ -48,6 +48,7 @@ func NewVerticalStack(controls ...Control) *Stack {
 }
 
 // SetStretchy marks a control in a Stack as stretchy. This cannot be called once the Window containing the Stack has been opened.
+// (TODO action on invalid index)
 func (s *Stack) SetStretchy(index int) {
 	s.lock.Lock()
 	defer s.lock.Unlock()
@@ -182,12 +183,12 @@ func (s *Stack) preferredSize() (width int, height int, err error) {
 	return
 }
 
-// Space returns a null control intended for padding layouts with blank space.
-// It appears to its owner as a control of 0x0 size.
+// 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. (TODO stretching/sizing rules)
+// 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 resizing the other controls (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).
 func Space() Control {
 	// As above, a Stack with no controls draws nothing and reports no errors; its parent will still size it properly if made stretchy.
 	return newStack(horizontal)

todo.md

@@ -66,9 +66,7 @@ super ultra important things:
 
 important things:
 - make specific wording in documentation consistent (make/create, etc.)
-	- document minor details like wha thappens on specific events so that they are guaranteed to work the same on all platforms
-		- for instance, initial selection state of Combobox and Listbox
-			- related: should a noneditable Combobox be allowed to return to unselected mode by the user?
+	- document minor details like wha thappens on specific events so that they are guaranteed to work the same on all platforms (are there any left?)
 - make passing of parameters and type conversions of parameters to uitask on Windows consistent: explicit _WPARAM(xxx)/_LPARAM(xxx)/uintptr(xxx), for example
 	- do this for type signatures in exported functions: (err error) or just error?
 
@@ -82,3 +80,4 @@ maybe:
 - rename Stack to Box?
 - make Combobox and Listbox satisfy sort.Interface?
 - indeterminate progress bars (not supported on Windows 2000)
+- should a noneditable Combobox be allowed to return to unselected mode by the user?