Cocoa Internals/Input

LCL Event Handling

For general "event loop" handling you might want to refer to application event loop article.

Mouse

The biggest difference between Apple and LCL ideology is the way of handling MouseMove events.

According to Apple - mouse events are easily to flood the event queue and thus are disabled by default, unless a use presses and hold the button.

Apple provides a special NSWindow mode to allow MouseMove events to come through even with buttons unreleased. However, such MouseMove events would be reported to the focused controls (aka FirstResponder), rather than the control immediately under the cursor.

(MouseDown, MouseUp events are reported directly to the control under the cursor, similar to LCL).

Because of that, Widgetset mouse event processing routine first checks, if cursor is actually above the focused control, and if it's not, it would let Cocoa propagate the mouse event, down (from child to parent) the controls hierarchy.

Such propagation happens, when NSView inherited mouseMove event is called.

If the actual control is found, the propagation of the event is stopped.

Implemenation

The whole set of methods should be overridden for each sub-classed Objective-C control

   function acceptsFirstMouse(event: NSEvent): Boolean; override;
   procedure mouseDown(event: NSEvent); override;
   procedure mouseUp(event: NSEvent); override;
   procedure rightMouseDown(event: NSEvent); override;
   procedure rightMouseUp(event: NSEvent); override;
   procedure rightMouseDragged(event: NSEvent); override;
   procedure otherMouseDown(event: NSEvent); override;
   procedure otherMouseUp(event: NSEvent); override;
   procedure otherMouseDragged(event: NSEvent); override;
   procedure mouseDragged(event: NSEvent); override;
   procedure mouseMoved(event: NSEvent); override;
   procedure scrollWheel(event: NSEvent); override;

Even if a target LCL control doesn't publish the events (i.e. TScrollBar doesn't have any mouse events published), all those methods should still be overriden. The purpose is to give LCL control over that. For example, if a control is used at the design time, ALL of cocoa default handling should be blocked.

Typical implementation for mouseDown/mouseUp events (including "right" and "other" versions) should look like this:

procedure TCocoaControl.mouseDown(event: NSEvent);
begin
  if not Assigned(callback) or not callback.MouseUpDownEvent(event) then
    inherited mouseDown(event);
end;

procedure TCocoaControl.mouseUp(event: NSEvent);
begin
  if not Assigned(callback) or not callback.MouseUpDownEvent(event) then
    inherited mouseUp(event);
end;

Such implementation notifies LCL first (via callback) about a mouse event. If LCL doesn't block it (by returning "true" from MouseUpdownEvent) the event is passed further to Cocoa. Actually there's no harm in non-blocking mouseUp and always inheriting it.

However, for some controls, what either implementing drag and drop functionality or some sort of dragging action (i.e. ScrollBar) requires mouseDown to be implemented in the following manner:

procedure TCocoaScrollBar.mouseDown(event: NSEvent);
begin
  if not Assigned(callback) or not callback.MouseUpDownEvent(event) then
  begin
    inherited mouseDown(event);
 
    callback.MouseUpDownEvent(event, true); // forced mouse-up event
  end;
end;

The reason for that is within Cocoa (and Apple in genernal) implementation of mouse-hold button loops. Once inherited mouseDown is called, the procedure would not return until the mouse button is released or the action is cancelled. It's quite typical to do an event processing loop, until mouse-up event received .

The issue is that the actual mouseUp() selector would never be called, and must be emulated via callback.MouseUpDownEvent(, true) call.

The implementation of mouseUp method should still remain.

Also, such approach doesn't apply to rightMouseDown otherMouseDown. Apple doesn't make any event loops for those.

Ctrl+Left Click / Right Click

Apple's classic mouse is a single button mouse. The additional actions are performed by holding the mouse pressed. (One might observe the similar behavior for smartphone devices, where holding a finger on the screen for a certain period of time opens up an additional action).

However, context menus are also part of the user interface. In order to open up a context menu a user would need to hold "Control" button and click the mouse button.

With the modern mouse device (where having 3 buttons+scroll is a norm) it ended up recognized as Ctrl+Left is a Right click.

CocoaWS recognizes Ctrl+Left click as a Context Menu request only and forwards an appropriate to the control, which ends in a call to OnContextPopup event. Yet, Cocoa doesn't alternate the information about left-click in any manner. (CarbonWS reports Button as TRightButton, but the shift state indicates the that Left mouse button is actually pressed)

Keyboard

KeyDown event is handled through the NSWindow sendEvent method. There's an explicit code written in order to pass an event to the focused control (firstResponder).

Virtual Key code

LCL is using the concept of Virtual Key codes.

MacOSX APIs don't follow such concept. Instead Cocoa is using "characters" for such purpose. For example: Menu Short Cuts or special Key Combinations are typically specified by characters, rather than some special codes. For each key pressed MacOSX does provide a hardware key code (available through event.keyCode). The key represents a hardware code. Meaning that on a different keyboard layout the keyCode would remain the same, while character might be different. (for example for QWERTY vs Dvorak vs AZERTY layout, the same "q" key pressed, would produce the same keyCode, yet different character).

For this particular reason, Virtual Keycodes are determined in the following approach:

• the character (event.characterWithoutModifiers) is examined. If it's available and it can be mapped to a known VirtualKey code - then character to VK would be used and non-numpad key (i.e. "/" on keyboard is different than "/" on numpad)
• otherwise Virtual Key code is determined based on keyCode.

It covers the most common cases. The problem remains with the national characters (i.e. German ß). The character itself is not within the range of VK_(a-z) codes. It's encoded as VK_OEM_xx code. However such VK code would be different on Cocoa and Windows.

Special Keys

Some controls wants special keys, such as Tabs and Arrows to handle. (for example TMemo with WantsTab set to true, or TTrackBar to change thumb position).

Both tabs and arrows are keys used for switch focus within the application itself.

Thus, it's critical for a control to let LCL know, that they would handle those keys and focus would not be switched.

For this purpose an additional method has been introduced:

lclExpectedKeys:::

the method accepts variable 3 parameters:

• wantTabs (default value false), should be set to true, if control expects to process tab key
• wantArrows (default value false), should be set to true, if control expects to process arrow keys (all of them!)
• wantAllKeys (default value true?)... not sure how it's being used.

Major Patch

See https://bugs.freepascal.org/view.php?id=35449 by Zoë Peterson

Reference to https://asciiwwdc.com/2010/sessions/145

In short, Cocoa's key handling looks like this:

NSApplication.sendEvent

Local NSEvent Monitors

if modifierFlags include Cmd or Ctrl

NSWindow.performKeyEquivalent (Key window)

NSResponder.performKeyEquivalent (called on all views recursively)

NSWindow.performKeyEquivalent (Other "active" windows, but only for views that manage menus)

NSMenu.performKeyEquivalent

Check registered hot keys (e.g., Cmd~ for Window cycling or Ctrl+F2 to move focus to menu)

NSWindow.sendEvent (Key window)

NSResponder.keyDown (firstResponder)

inherited calls keyDown up the responder chain until it reaches the NSWindow

NSWindow.keyDown

NSWindow.performKeyEquivalent (Key Window, possibly for second time if Cmd or Ctrl)

NSMenu.performKeyEquivalent (again, possibly the second time)

<undocumented magic>

Beep

Dead Keys

By default Cocoa event handling is ignoring dead-keys (on national keyboards, i.e. Spanish). In order the event to be ready NSTextInputContext needs to be created and events "translated" through it.

The context does exist for any NSTextView field(s). Thus Cocoa native TMemo, TEdit or TcomboBox would not be affected. Custom controls however are.

In order to "translate" a keyboard event TCocoaApplication creates its own (global) NSTextInputContext and passes all events through it. In order to recognize a dead-key combination. Turning the sequence of

´ e

into

é

However, if a sequence is invalid, i.e.

´ s

Cocoa reports a single string of character "'s". CocoaWS breaks the string into separate characters and report them as a standalone characters, rather than the entire string. (This is matches WinAPI)

See Also

• Cocoa Internals