add Impose() Constraint chan to Env

1 files changed, 30 insertions, 20 deletions

diff --git a/env.go b/env.go
index 2515417..005ef80 100644
--- a/env.go
+++ b/env.go
@@ -7,27 +7,37 @@ import (
 
 // Env is the most important thing in this package. It is an interactive graphical
 // environment, such as a window.
-//
-// It has two channels: Events() and Draw().
-//
-// The Events() channel produces events, like mouse and keyboard presses, while the
-// Draw() channel receives drawing functions. A drawing function draws onto the
-// supplied draw.Image, which is the drawing area of the Env and returns a rectangle
-// covering the whole part of the image that got changed.
-//
-// An Env guarantees to produce a "resize/<x0>/<y0>/<x1>/<y1>" event as its first event.
-//
-// The Events() channel must be unlimited in capacity. Use MakeEventsChan() to create
-// a channel of events with an unlimited capacity.
-//
-// The Draw() channel may be synchronous.
-//
-// Drawing functions sent to the Draw() channel are not guaranteed to be executed.
-//
-// Closing the Draw() channel results in closing the Env. The Env will subsequently
-// close the Events() channel. On the other hand, when the Events() channel gets closed
-// the user of the Env should subsequently close the Draw() channel.
 type Env interface {
+	// The Events() channel produces events, like mouse and keyboard presses.
+	//
+	// An Env guarantees to produce a "resize/<x0>/<y0>/<x1>/<y1>" event as its first event.
+	//
+	// The Events() channel must be unlimited in capacity. Use MakeEventsChan() to create
+	// a channel of events with an unlimited capacity.
 	Events() <-chan Event
+
+	// The Draw() channel receives drawing functions.
+	//
+	// A drawing function draws onto the supplied draw.Image, which is the drawing area
+	// of the Env, and returns a rectangle covering the whole part of the image that
+	// got changed.
+	//
+	// Drawing functions are not guaranteed to be executed.
+	//
+	// The Draw() channel may be synchronous.
 	Draw() chan<- func(draw.Image) image.Rectangle
+
+	// The Impose() channel receives constraints that are imposed on the size/layout of
+	// the Env by the widget occupying it.
+	//
+	// The Env may respond to constraints by sending a Resize event on the Events() channel.
+	// However, constraints are not guaranteed to be satisfied, e.g. if there is not
+	// enough space.
+	//
+	// The Impose() channel may be synchronous.
+	Impose() chan<- Constraint
+
+	// Close destroys the Env. The Env will subsequently close the Events(), Draw(),
+	// and Impose() channels.
+	Close()
 }