The Inbox: Kernel-dtl.985.mcz

David T. Lewis uploaded a new version of Kernel to project The Inbox:
http://source.squeak.org/inbox/Kernel-dtl.985.mcz

==================== Summary ====================

Name: Kernel-dtl.985
Author: dtl
Time: 30 January 2016, 2:53:37.508491 pm
UUID: 14804760-466d-4af1-a5f8-ad60b34fdc1d
Ancestors: Kernel-dtl.984

EventSensor replaces InputSensor, update class and method comments.

=============== Diff against Kernel-dtl.984 ===============

Item was changed:
  Object subclass: #EventSensor
  instanceVariableNames: 'mouseButtons mousePosition keyboardBuffer interruptKey interruptSemaphore eventQueue inputSemaphore lastEventPoll hasInputSemaphore'
  classVariableNames: 'ButtonDecodeTable EventPollPeriod EventTicklerProcess InterruptSemaphore InterruptWatcherProcess KeyDecodeTable'
  poolDictionaries: 'EventSensorConstants'
  category: 'Kernel-Processes'!
 
+ !EventSensor commentStamp: 'dtl 1/30/2016 14:44' prior: 0!
+ An EventSensor is an interface to the user input devices.
+ There is at least one instance of EventSensor named Sensor in the system.
- !EventSensor commentStamp: 'nk 4/13/2004 11:18' prior: 0!
- EventSensor is a replacement for InputSensor based on a set of (optional) event primitives. An EventSensor updates its state when events are received so that all state based users of Sensor (e.g., Sensor keyboard, Sensor leftShiftDown, Sensor mouseButtons) will work exactly as before, by moving the current VM mechanisms into EventSensor itself. An optional input semaphore is part of the new design.
 
+ EventSensor is a replacement for the earlier InputSensor implementation based on a set of (optional) event primitives. An EventSensor updates its state when events are received so that all state based users of Sensor (e.g., Sensor keyboard, Sensor leftShiftDown, Sensor mouseButtons) will work exactly as before, by moving the current VM mechanisms into EventSensor itself. An optional input semaphore is part of the new design.
+
  For platforms that support true asynchronous event notification, the semaphore will be signaled to indicate pending events.
  On platforms that do not support asynchronous notifications about events, the UI will have to poll EventSensor periodically to read events from the VM.
 
  Instance variables:
  mouseButtons <Integer> - mouse button state as replacement for primMouseButtons
  mousePosition <Point> - mouse position as replacement for primMousePt
  keyboardBuffer <SharedQueue> - keyboard input buffer
  interruptKey <Integer> - currently defined interrupt key
  interruptSemaphore <Semaphore> - the semaphore signaled when the interruptKey is detected
  eventQueue <SharedQueue> - an optional event queue for event driven applications
  inputSemaphore <Semaphore>- the semaphore signaled by the VM if asynchronous event notification is supported
  lastEventPoll <Integer> - the last millisecondClockValue at which we called fetchMoreEvents
  hasInputSemaphore <Boolean> - true if my inputSemaphore has actually been signaled at least once.
 
  Class variables:
+ ButtonDecodeTable <ByteArray> - maps mouse buttons as reported by the VM to ones reported in the events.
+ KeyDecodeTable <Dictionary<SmallInteger->SmallInteger>> - maps some keys and their modifiers to other keys (used for instance to map Ctrl-X to Alt-X)
+ InterruptSemaphore <Semaphore> - signalled by the the VM and/or the event loop upon receiving an interrupt keystroke.
+ InterruptWatcherProcess <Process> - waits on the InterruptSemaphore and then responds as appropriate.
  EventPollPeriod <Integer> - the number of milliseconds to wait between polling for more events in the userInterruptHandler.
  EventTicklerProcess <Process> - the process that makes sure that events are polled for often enough (at least every EventPollPeriod milliseconds).
 
  Event format:
  The current event format is very simple. Each event is recorded into an 8 element array. All events must provide some SmallInteger ID (the first field in the event buffer) and a time stamp (the second field in the event buffer), so that the difference between the time stamp of an event and the current time can be reported.
 
  Currently, the following events are defined:
 
  Null event
  =============
  The Null event is returned when the ST side asks for more events but no more events are available.
  Structure:
  [1] - event type 0
  [2-8] - unused
 
  Mouse event structure
  ==========================
  Mouse events are generated when mouse input is detected.
  Structure:
  [1] - event type 1
  [2] - time stamp
  [3] - mouse x position
  [4] - mouse y position
  [5] - button state; bitfield with the following entries:
  1 - yellow (e.g., right) button
  2 - blue (e.g., middle) button
  4 - red (e.g., left) button
  [all other bits are currently undefined]
  [6] - modifier keys; bitfield with the following entries:
  1 - shift key
  2 - ctrl key
  4 - (Mac specific) option key
  8 - Cmd/Alt key
  [all other bits are currently undefined]
  [7] - reserved.
  [8] - reserved.
 
  Keyboard events
  ====================
  Keyboard events are generated when keyboard input is detected.
  [1] - event type 2
  [2] - time stamp
  [3] - character code
  For now the character code is in Mac Roman encoding.
  [4] - press state; integer with the following meaning
  0 - character
  1 - key press (down)
  2 - key release (up)
  [5] - modifier keys (same as in mouse events)
  [6] - reserved.
  [7] - reserved.
  [8] - reserved.
  !

Item was changed:
  ----- Method: EventSensor>>processKeyboardEvent: (in category 'private-I/O') -----
  processKeyboardEvent: evt
+ "process a keyboard event, updating EventSensor state"
- "process a keyboard event, updating InputSensor state"
  | charCode pressCode |
  "Never update keyboardBuffer if we have an eventQueue active"
  mouseButtons := (mouseButtons bitAnd: 7) bitOr: ((evt at: 5) bitShift: 3).
  eventQueue ifNotNil:[^self].
  charCode := evt at: 3.
  charCode = nil ifTrue:[^self]. "extra characters not handled in MVC"
  pressCode := evt at: 4.
  pressCode = EventKeyChar ifFalse:[^self]. "key down/up not handled in MVC"
  "mix in modifiers"
  charCode := charCode bitOr: ((evt at: 5) bitShift: 8).
  keyboardBuffer nextPut: charCode.!

Item was changed:
  ----- Method: EventSensor>>processMouseEvent: (in category 'private-I/O') -----
  processMouseEvent: evt
+ "process a mouse event, updating EventSensor state"
- "process a mouse event, updating InputSensor state"
  | modifiers buttons mapped |
  mousePosition := (evt at: 3) @ (evt at: 4).
  buttons := evt at: 5.
  modifiers := evt at: 6.
  mapped := self mapButtons: buttons modifiers: modifiers.
  mouseButtons := mapped bitOr: (modifiers bitShift: 3).!

Item was changed:
  ObjectTracer subclass: #ObjectViewer
  instanceVariableNames: 'valueBlock lastValue changeBlock'
  classVariableNames: ''
  poolDictionaries: ''
  category: 'Kernel-Objects'!
 
+ !ObjectViewer commentStamp: 'dtl 1/30/2016 14:50' prior: 0!
+ ObjectViewers offers the same kind of interception of messages (via doesnotUnderstand:) as ObjectTracers, but instead of just being wrappers, they actually replace the object being viewed.  This makes them a lot more dangerous to use, but one can do amazing things.  For instance, the example below actually intercepts the EventSensor object, and prints the mouse coordinates asynchronously, every time they change:
- !ObjectViewer commentStamp: '<historical>' prior: 0!
- ObjectViewers offers the same kind of interception of messages (via doesnotUnderstand:) as ObjectTracers, but instead of just being wrappers, they actually replace the object being viewed.  This makes them a lot more dangerous to use, but one can do amazing things.  For instance, the example below actually intercepts the InputSensor object, and prints the mouse coordinates asynchronously, every time they change:
  Sensor evaluate: [Sensor cursorPoint printString displayAt: 0@0]
  wheneverChangeIn: [Sensor cursorPoint].
  To exit from this example, execute:
  Sensor xxxUnTrace
  !