More mouse event planning and TODOs.

areaplan.md

@@ -372,6 +372,8 @@ All messages are supported on at least Windows 2000, so we're good using them al
 
 There does not seem to be an equivalent to the mouse entered signal provided by GTK+ and Cocoa. There *is* an equivalent to mouse left (`WM_MOUSELEAVE`), but it requires tracking support, which has to be set up in special ways.
 
+TODO what about Alt modifier?
+
 ### GTK+
 - `"button-press-event"` for mouse button presses; needs `GDK_BUTTON_PRESS_MASK` and returns `GdkEventButton`
 - `"button-release-event"` for mouse button releases; needs `GDK_BUTTON_RELEASE_MASK` and returns `GdkEventButton`
@@ -419,7 +421,7 @@ GDK_BUTTON3_MOTION_MASK
 - modifier keys (as above) AND POINTER BUTTONS THIS TIME
 
 ### Cocoa
-Our `NSView` subclass will override the following
+Our `NSView` subclass will override the following:
 ```
 mouseDown:
 mouseDragged:
@@ -439,7 +441,7 @@ The `mouse...` selectors are for the left mouse button. Each of these selectors
 ```
 where `NSEvent` is a concrete type, not an abstract class, that contains all the information we need.
 
-...almost. `NSEvent` doesn't record mouse position. Instead, it has a static method `+[NSEvent mouseLocation]` that returns the mouse location instead. And this location is relative to the screen, so we need to get it relative to the container view instead. Fun. Fortunately, the NSView Programming Guide says we can do
+...almost. `NSEvent` doesn't record mouse position directly, but rather relative to the view's parent window. The NSView Programming Guide says we can do
 ```go
 	nspoint := [self convertPoint:[e locationInWindow] fromView:nil]
 ```
@@ -455,7 +457,48 @@ TODO do we need to override `acceptsFirstMouse:` to return `YES` so a click even
 
 ### Consensus
 ```go
+// 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.
+// (TODO If additional buttons are supported, will they be returned with 4 being the first additional button (XBUTTON1 on Windows), 5 being the second (XBUTTON2 on Windows), and so on?) (TODO get the user-facing name for XBUTTON1/2)
 type MouseEvent struct {
-	xxx
+	// Pos is the position of the mouse relative to the top-left of the area.
+	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.
+	Down		uint
+
+	// If the event was generated by a mouse button being released, Up contains the ID of that button.
+	// Otherwise, Up contains 0.
+	Up			uint
+
+	// If Down is nonzero, Count indicates the number of clicks: 1 for single-click, 2 for double-click.
+	// If Count > 1, at least one (TODO exactly one?) Count-1 event will be sent before a Count event.
+	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.
+	// (TODO Is thisonly guarnateed to be valid if both Down and Up are zero (which indicates a mouse move)?))
+	Held			[]uint
 }
+
+// HeldBits returns Held as a bit mask.
+// Bit 0 maps to button 1, bit 1 maps to button 2, etc.
+func (e MousEvent) HeldBits() (h uintptr) {
+	for _, x := range e.Held {
+		h |= uintptr(1) << (x - 1)
+	}
+	return h
+}
+
+// Modifiers indicates modifier keys being held during a mouse event.
+// There is no way to differentiate between left and right modifier keys.
+type Modifiers int
+const (
+	Ctrl Modifiers = 1 << iota		// the canonical Ctrl keys (Command on Mac OS X, Control on others)
+	Alt						// the canonical Alt keys (Option on Mac OS X, Meta on Unix systems, Alt on others)
+	Shift						// the Shift keys
+)
 ```

todo.md

@@ -79,6 +79,7 @@ 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 (are there any left?)
 		- what happens when the user clicks and drags on a listbox
+	- should field descriptions in method comments include the receiver name? (for instance e.Held vs. Held) - see what Go's own documentation does
 - 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?
 	- do this for the names of GTK+ helper functions (gtkXXX or gXXX)