#24 - add docs for ctrlutil

ctrlutil.go

@@ -5,6 +5,9 @@ import (
 	"strings"
 )
 
+// CalculateMinimalSize return the minimal width and height
+// of the Control based on control's children minial sizes
+// and control's paddings
 func CalculateMinimalSize(c Control) (int, int) {
 	w, h := c.Constraints()
 
@@ -45,6 +48,8 @@ func CalculateMinimalSize(c Control) (int, int) {
 	return w, h
 }
 
+// CalculateTotalScale return sum of all
+// control children scale coefficients
 func CalculateTotalScale(c Control) int {
 	scale := 0
 
@@ -58,6 +63,13 @@ func CalculateTotalScale(c Control) int {
 	return scale
 }
 
+// RepositionControls calculates position of all
+// control children and moves them to a new positions.
+// Call the funtion after the control is resized.
+// dx and dy are position of the container control
+// relative to parent View. Initial calculation start
+// point is 0, 0. After calculation all childen are
+// moved by dx and dy
 func RepositionControls(dx, dy int, c Control) {
 	if len(c.Children()) == 0 {
 		return
@@ -130,6 +142,15 @@ func RepositionControls(dx, dy int, c Control) {
 	}
 }
 
+// RealColor return attribute than should be applied to an
+// object. By default all attributes equal ColorDefault and
+// the real color should be retrieved from the current theme.
+// Attribute selection word this way: if color is not ColorDefault,
+// it is returned as is, otherwise the function tries to load
+// color from the theme.
+// tm - the theme to retrieve color from
+// clr - current object color
+// id - color ID in theme
 func RealColor(tm Theme, clr term.Attribute, id string) term.Attribute {
 	if clr != ColorDefault {
 		return clr
@@ -142,6 +163,16 @@ func RealColor(tm Theme, clr term.Attribute, id string) term.Attribute {
 	return clr
 }
 
+// StringToColor returns attribute by its string description.
+// Description is the list of attributes separated with
+// spaces, plus or pipe symbols. You can use 8 base colors:
+// black, white, red, green, blue, magenta, yellow, cyan
+// and a few modifiers:
+// bold or bright, underline or underlined, reverse
+// Note: some terminals do not support all modifiers, e.g,
+// Windows one understands only bold/bright - it makes the
+// color brighter with the modidierA
+// Examples: "red bold", "green+underline+bold"
 func StringToColor(str string) term.Attribute {
 	var parts []string
 	if strings.ContainsRune(str, '+') {

interface.go

@@ -61,18 +61,37 @@ type Theme interface {
 }
 
 type View interface {
+	// Title returns the current title or text of the control
 	Title() string
+	// SetTitle changes control text or title
 	SetTitle(string)
 	Draw(Canvas)
 	// Repaint draws the control on console surface
 	Repaint()
+	// Constraints return minimal control widht and height
 	Constraints() (int, int)
+	// Size returns current control width and height
 	Size() (int, int)
+	// SetSize changes control size. Constant DoNotChange can be
+	// used as placeholder to indicate that the control attrubute
+	// should be unchanged.
+	// Method panics if new size is less than minimal size
 	SetSize(int, int)
+	// Pos returns the current control position: X and Y.
+	// For View the position's origin is top left corner of console window,
+	// for other controls the origin is top left corner of View that hold
+	// the control
 	Pos() (int, int)
+	// SetPos changes contols position. Manual call of the method does not
+	// make sense for any control except View because control positions
+	// inside of container always recalculated after View resizes
 	SetPos(int, int)
 	Canvas() Canvas
+	// Active returns if a control is active. Only active controls can
+	// process keyboard events. Parent View looks for active controls to
+	// make sure that there is only one active control at a time
 	Active() bool
+	// SetActive activates and deactivates control
 	SetActive(bool)
 	/*
 	   ProcessEvent processes all events come from the control parent. If a control
@@ -84,28 +103,69 @@ type View interface {
 	ActivateControl(Control)
 	RegisterControl(Control)
 	Screen() Screen
+	// Parent return control's container or nil if there is no parent container
 	Parent() Control
 	HitTest(int, int) HitResult
 	SetModal(bool)
 	Modal() bool
 	OnClose(func(Event))
 
+	// Paddings returns a number of spaces used to auto-arrange children inside
+	// a container: indent from left and right sides, indent from top and bottom
+	// sides, horizontal space between controls, vertical space between controls.
+	// Horizontal space is used in case of PackType is horizontal, and vertical
+	// in other case
 	Paddings() (int, int, int, int)
+	// SetPaddings changes indents for the container. Use DoNotChange as a placeholder
+	// if you do not want to touch a parameter
 	SetPaddings(int, int, int, int)
+	// AddChild adds a new child to a container. For the most
+	// of controls the method is just a stub that panics
+	// because not every control can be a container
 	AddChild(Control, int)
+	// SetPack changes the direction of children packing
 	SetPack(PackType)
+	// Pack returns direction in which a container packs
+	// its children: horizontal or vertical
 	Pack() PackType
+	// Children returns the list of container child controls
 	Children() []Control
 	ChildExists(Control) bool
+	// Scale return scale coefficient that is used to calculate
+	// new control size after its parent resizes.
+	// DoNotScale means the controls never changes its size.
+	// Any positive value is a real coefficient of scaling.
+	// How the scaling works: after resizing, parent control
+	// calculates the difference between minimal and current sizes,
+	// then divides the difference between controls that has
+	// positive scale depending on a scale value. The more scale,
+	// the larger control after resizing. Example: if you have
+	// two controls with scales 1 and 2, then after every resizing
+	// the latter controls expands by 100% more than the first one.
 	Scale() int
+	// SetScale sets a scale coefficient for the control.
+	// See Scale method for details
 	SetScale(int)
+	// TabStop returns if a control can be selected by traversing
+	// controls using TAB key
 	TabStop() bool
+	// Colors return the basic attrubutes for the controls: text
+	// attribute and background one. Some controls inroduce their
+	// own additional controls: see ProgressBar
 	Colors() (term.Attribute, term.Attribute)
+	// ActiveColors return the attrubutes for the controls when it
+	// is active: text and background colors
 	ActiveColors() (term.Attribute, term.Attribute)
+	// SetBackColor changes background color of the control
 	SetBackColor(term.Attribute)
+	// SetActiveBackColor changes background color of the active control
 	SetActiveBackColor(term.Attribute)
+	// SetTextColor changes text color of the control
 	SetTextColor(term.Attribute)
+	// SetActiveTextColor changes text color of the active control
 	SetActiveTextColor(term.Attribute)
+	// RecalculateConstraints used by containers to recalculate new minimal size
+	// depending on its children constraints after a new child is added
 	RecalculateConstraints()
 
 	Logger() *log.Logger
@@ -132,18 +192,50 @@ type Control interface {
 	// should be unchanged.
 	// Method panics if new size is less than minimal size
 	SetSize(int, int)
+	// Scale return scale coefficient that is used to calculate
+	// new control size after its parent resizes.
+	// DoNotScale means the controls never changes its size.
+	// Any positive value is a real coefficient of scaling.
+	// How the scaling works: after resizing, parent control
+	// calculates the difference between minimal and current sizes,
+	// then divides the difference between controls that has
+	// positive scale depending on a scale value. The more scale,
+	// the larger control after resizing. Example: if you have
+	// two controls with scales 1 and 2, then after every resizing
+	// the latter controls expands by 100% more than the first one.
 	Scale() int
+	// SetScale sets a scale coefficient for the control.
+	// See Scale method for details
 	SetScale(int)
+	// Constraints return minimal control widht and height
 	Constraints() (int, int)
+	// Paddings returns a number of spaces used to auto-arrange children inside
+	// a container: indent from left and right sides, indent from top and bottom
+	// sides, horizontal space between controls, vertical space between controls.
+	// Horizontal space is used in case of PackType is horizontal, and vertical
+	// in other case
 	Paddings() (int, int, int, int)
+	// SetPaddings changes indents for the container. Use DoNotChange as a placeholder
+	// if you do not want to touch a parameter
 	SetPaddings(int, int, int, int)
 	// Repaint draws the control on its View surface
 	Repaint()
+	// AddChild adds a new child to a container. For the most
+	// of controls the method is just a stub that panics
+	// because not every control can be a container
 	AddChild(Control, int)
+	// SetPack changes the direction of children packing
 	SetPack(PackType)
+	// Pack returns direction in which a container packs
+	// its children: horizontal or vertical
 	Pack() PackType
+	// Children returns the list of container child controls
 	Children() []Control
+	// Active returns if a control is active. Only active controls can
+	// process keyboard events. Parent View looks for active controls to
+	// make sure that there is only one active control at a time
 	Active() bool
+	// SetActive activates and deactivates control
 	SetActive(bool)
 	/*
 	   ProcessEvent processes all events come from the control parent. If a control
@@ -152,15 +244,29 @@ type Control interface {
 	   the event to the control parent
 	*/
 	ProcessEvent(Event) bool
+	// TabStop returns if a control can be selected by traversing
+	// controls using TAB key
 	TabStop() bool
+	// Parent return control's container or nil if there is no parent container
 	Parent() Control
+	// Colors return the basic attrubutes for the controls: text
+	// attribute and background one. Some controls inroduce their
+	// own additional controls: see ProgressBar
 	Colors() (term.Attribute, term.Attribute)
+	// ActiveColors return the attrubutes for the controls when it
+	// is active: text and background colors
 	ActiveColors() (term.Attribute, term.Attribute)
+	// SetBackColor changes background color of the control
 	SetBackColor(term.Attribute)
+	// SetActiveBackColor changes background color of the active control
 	SetActiveBackColor(term.Attribute)
+	// SetTextColor changes text color of the control
 	SetTextColor(term.Attribute)
+	// SetActiveTextColor changes text color of the active control
 	SetActiveTextColor(term.Attribute)
 
+	// RecalculateConstraints used by containers to recalculate new minimal size
+	// depending on its children constraints after a new child is added
 	RecalculateConstraints()
 
 	Logger() *log.Logger