More Area documentation.

areahandler.go

@@ -33,13 +33,88 @@ import "C"
 var areahandlers = make(map[*C.uiAreaHandler]AreaHandler)
 
 // AreaHandler defines the functionality needed for handling events
-// from an Area.
+// from an Area. Each of the methods on AreaHandler is called from
+// the GUI thread, and every parameter (other than the Area itself)
+// should be assumed to only be valid during the life of the method
+// call (so for instance, do not save AreaDrawParams.AreaWidth, as
+// that might change without generating an event).
+// 
+// Coordinates to Draw and MouseEvent are given in points. Points
+// are generic, floating-point, device-independent coordinates with
+// (0,0) at the top left corner. You never have to worry about the
+// mapping between points and pixels; simply draw everything using
+// points and you get nice effects like looking sharp on high-DPI
+// monitors for free. Proper documentation on the matter is being
+// written. In the meantime, there are several referenes to this kind of
+// drawing, most notably on Apple's website: https://developer.apple.com/library/mac/documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Explained/Explained.html#//apple_ref/doc/uid/TP40012302-CH4-SW1
+// 
+// For a scrolling Area, points are automatically offset by the scroll
+// position. So if the mouse moves to position (5,5) while the
+// horizontal scrollbar is at position 10 and the horizontal scrollbar is
+// at position 20, the coordinate stored in the AreaMouseEvent
+// structure is (15,25). The same applies to drawing.
 type AreaHandler interface {
-	// TODO document all these
+	// Draw is sent when a part of the Area needs to be drawn.
+	// dp will contain a drawing context to draw on, the rectangle
+	// that needs to be drawn in, and (for a non-scrolling area) the
+	// size of the area. The rectangle that needs to be drawn will
+	// have been cleared by the system prior to drawing, so you are
+	// always working on a clean slate.
+	// 
+	// If you call Save on the drawing context, you must call Release
+	// before returning from Draw, and the number of calls to Save
+	// and Release must match. Failure to do so results in undefined
+	// behavior.
 	Draw(a *Area, dp *AreaDrawParams)
+
+	// MouseEvent is called when the mouse moves over the Area
+	// or when a mouse button is pressed or released. See
+	// AreaMouseEvent for more details.
+	// 
+	// If a mouse button is being held, MouseEvents will continue to
+	// be generated, even if the mouse is not within the area. On
+	// some systems, the system can interrupt this behavior;
+	// see DragBroken.
 	MouseEvent(a *Area, me *AreaMouseEvent)
+
+	// MouseCrossed is called when the mouse either enters or
+	// leaves the Area. It is called even if the mouse buttons are being
+	// held (see MouseEvent above). If the mouse has entered the
+	// Area, left is false; if it has left the Area, left is true.
+	// 
+	// If, when the Area is first shown, the mouse is already inside
+	// the Area, MouseCrossed will be called with left=false.
+	// TODO what about future shows?
 	MouseCrossed(a *Area, left bool)
+
+	// DragBroken is called if a mouse drag is interrupted by the
+	// system. As noted above, when a mouse button is held,
+	// MouseEvent will continue to be called, even if the mouse is
+	// outside the Area. On some systems, this behavior can be
+	// stopped by the system itself for a variety of reasons. This
+	// method is provided to allow your program to cope with the
+	// loss of the mouse in this case. You should cope by cancelling
+	// whatever drag-related operation you were doing.
+	// 
+	// Note that this is only generated on some systems under
+	// specific conditions. Do not implement behavior that only
+	// takes effect when DragBroken is called.
 	DragBroken(a *Area)
+
+	// KeyEvent is called when a key is pressed while the Area has
+	// keyboard focus (if the Area has been tabbed into or if the
+	// mouse has been clicked on it). See AreaKeyEvent for specifics.
+	// 
+	// Because some keyboard events are handled by the system
+	// (for instance, menu accelerators and global hotkeys), you
+	// must return whether you handled the key event; return true
+	// if you did or false if you did not. If you wish to ignore the
+	// keyboard outright, the correct implementation of KeyEvent is
+	// 	func (h *MyHandler) KeyEvent(a *ui.Area, ke *ui.AreaKeyEvent) (handled bool) {
+	// 		return false
+	// 	}
+	// DO NOT RETURN TRUE UNCONDITIONALLY FROM THIS
+	// METHOD. BAD THINGS WILL HAPPEN IF YOU DO.
 	KeyEvent(a *Area, ke *AreaKeyEvent) (handled bool)
 }
 
@@ -54,12 +129,27 @@ func unregisterAreaHandler(uah *C.uiAreaHandler) {
 	C.freeAreaHandler(uah)
 }
 
-// AreaDrawParams defines the TODO.
+// AreaDrawParams provides a drawing context that can be used
+// to draw on an Area and tells you where to draw. See AreaHandler
+// for introductory information.
 type AreaDrawParams struct {
-	// TODO document all these
+	// Context is the drawing context to draw on. See DrawContext
+	// for how to draw.
 	Context		*DrawContext
+
+	// AreaWidth and AreaHeight provide the size of the Area for
+	// non-scrolling Areas. For scrolling Areas both values are zero.
+	// 
+	// To reiterate the AreaHandler documentation, do NOT save
+	// these values for later; they can change without generating
+	// an event.
 	AreaWidth	float64
 	AreaHeight	float64
+
+	// These four fields define the rectangle that needs to be
+	// redrawn. The system will not draw anything outside this
+	// rectangle, but you can make your drawing faster if you
+	// also stay within the lines.
 	ClipX		float64
 	ClipY		float64
 	ClipWidth		float64
@@ -86,8 +176,16 @@ func doAreaHandlerDraw(uah *C.uiAreaHandler, ua *C.uiArea, udp *C.uiAreaDrawPara
 type AreaMouseEvent struct {
 	X			float64
 	Y			float64
+
+	// AreaWidth and AreaHeight provide the size of the Area for
+	// non-scrolling Areas. For scrolling Areas both values are zero.
+	// 
+	// To reiterate the AreaHandler documentation, do NOT save
+	// these values for later; they can change without generating
+	// an event.
 	AreaWidth	float64
 	AreaHeight	float64
+
 	Down		uint
 	Up			uint
 	Count		uint