Reached a decision about Area keystroke handling; noted it in the planning document. I just now need to figure out one thing...

1 files changed, 81 insertions, 0 deletions

diff --git a/areaplan.md b/areaplan.md
index 693c487..3256893 100644
--- a/areaplan.md
+++ b/areaplan.md
@@ -678,3 +678,84 @@ Character translation at all | Provided by OS, but not sure about some behaviora
 Single-keystroke character translation | *TODO* | Constants exist for whatever keyboard layout you can imagine | *TODO*
 Multi-keystroke character translation | `WM_DEADCHAR`/`WM_UNICHAR` | (see GTK+ s ectiona bove for issues) | Provided by OS; escape hatches avialable
 Character translation ignoring input language (so the programmer can know that the A key was pressed regardless of language) | *TODO* | *TODO* | *maybe* `charactersIgnoringModifiers`? *TODO*
+
+### OK new consensus
+Windows: use virtual key codes<br>
+OS X: use `charactersIgnoringModifiers`
+
+```go
+(on the Area comment)
+// Do not use an Area if you intend to read text.
+// Due to platform differences regarding text input,
+// keyboard events have beem compromised in
+// such a way that attempting to read Unicode data
+// in platform-native ways is painful.
+// [Use TextArea instead, providing a TextAreaHandler.]
+(corollary: this means multi-line edits will need a different name; corollary 2: this means I will have to start providing font resource acquisition, something I didn't want to do (I wanted to relegate that to freetype-go or similar, assuming that was even capable of doing so))
+
+// A KeyEvent represents a keypress in an Area.
+// 
+// KeyEvent has been designed to be predictable.
+// As the different operating systems supported by package ui
+// expose wildly different APIs and rules for reading keystrokes,
+// this means that KeyEvent has certain rules and restrictions
+// that you must mind. This makes KeyEvent unsuitable
+// for reading text (as Area's comment will say).
+// As another consequence, no KeyEvent will be generated if
+// package ui cannot portably report a given key. Supported
+// keys are described in the comments for the Rune field and
+// the ExtKey and Modifiers types.
+type KeyArea struct {
+	// Rune contains a lowercase rune specifying the name
+	// of the key pressed that triggered the event.
+	// Ideally, this would generally correspond to
+	// the raw character pressed (so there would be two
+	// events 'k', 'a' instead of 'か', if Japanese characters are
+	// input that way on a given machine). This will hold true
+	// on systems where IME returns are separate from
+	// keypress codes. On other systems, an attempt has
+	// been made to map backwards based on information
+	// that can be provided in the most portable (if the
+	// system provides multiple of its own backends) way.
+	// See [TODO] for a list of Rune values that are guaranteed
+	// to be available. There is no way to differentiate between
+	// multiple differnet Keys with the same name (for instance,
+	// there is no way to differentiate between '1' on the typewriter
+	// section of a standard 101-key keyboard and '1' on the numeric
+	// keypad section).
+	// If this field is zero, see ExtKey.
+	Rune			rune
+
+	// If Rune is zero, ExtKey contains a predeclared identifier
+	// naming an extended key. See ExtKey for details.
+	// If both Rune and ExtKey are zero, a Modifier by itself
+	// was pressed. Rune and ExtKey will not both be nonzero.
+	ExtKey		ExtKey
+
+	Modifiers		Modifiers
+
+	// If Up is true, the key was released; if not, the key was pressed.
+	// There is no guarantee that all pressed keys shall have
+	// corresponding release events (for instance, if the user switches
+	// programs while holding the key down, then releases the key).
+	// Keys that have been held down are reported as multiple
+	// key press events.
+	Up			bool
+}
+
+// ExtKey represents keys that do not have a Rune representation.
+// There is no way to differentiate between left and right ExtKeys.
+type ExtKey uintptr
+const (
+	keyname1 ExtKey = iota
+	keyname2
+	keyname3
+)
+(notes: this will have to be produced based on what's available on each platform (Mac OS X might be the biggest filter here); also as a personal favor-the-user decision Print Screen shall not be supported)
+```
+
+If I ever intend on providing alternate text-based widgets, I will need to use `GtkTextArea` and `NSTextArea` to make things work the most fluidly, so this will require another type. Woo...
+
+Also this answers the what if a key has been held down and switches away from the program question: Windows does not send a key up.
+
+This just leaves the GTK+ geometry mapping: there is a way to do it if X11 is the only supported backend, but Wayland exists...