SonoreDocs
Search guides and the APICtrl K
v1.0.0
  1. API reference
  2. Native GUI

gfx/window_cocoa.h

The Cocoa window, so the native UI runs on the third platform.

#include <sonore/gfx/window_cocoa.h>
On this page

Design notes

Written, compiled, never run

Say it plainly at the top rather than let a green build imply more than it earned: no machine in this project has executed a line of this file. macOS CI is the only one that could and it has not started a job since the account's spending limit was reached. What HAS happened is that a compiler has read it, against the shim in tests/au_shim -- so every name exists, every call has the right argument count, and the file is internally consistent. That is a real class of error caught, and it is not the same as working.

The Win32 and X11 peers are checked against real windows with real events. This one is not, and the feature map says so.

Written against the runtime, not in Objective-C

Same reason as webview_cocoa.h: the SDK stays plain C++, and a generated project needs no .mm file, no mixed-language build and no Xcode-specific CMake. Every Cocoa call here is objc_msgSend on a class looked up by name, which is exactly what the Objective-C compiler emits anyway.

The cost is that an NSView subclass has to be REGISTERED at runtime, with C functions as its method implementations. There is no way around that: drawing and input on macOS both arrive as overridden methods, and a view that overrides nothing draws nothing and receives nothing.

What macOS does differently

  • Its y axis points UP, and a view's coordinates start at the bottom left. Every other surface in this SDK -- the rasteriser, the component tree, every peer -- is y-down. isFlipped is overridden to return YES, which makes one view y-down and leaves the conversion in one place instead of scattering height - y through the input handlers.
  • There is no pointer grab. X11 has XGrabPointer and Windows has SetCapture; macOS has neither, and a popup dismisses because its window stops being key. That is a genuinely different mechanism, not a translation of the same one.
  • Coordinates for a click arrive in WINDOW space and have to be converted into the view. Using them unconverted is the classic Cocoa bug and it looks like an editor whose controls respond a title-bar's height away from where they are.

Screen readers and input methods (2026-10-14, compiled, not run)

The view is also the way in for VoiceOver and for input methods, and both are as unrun as the rest of this file:

  • Accessibility: the view is an AXGroup whose children are the elements of gfx/accessibility_mac.h, the NSAccessibility bridge over the same model the Windows UIA bridge reads. Retaken and announced on this view's clock.
  • Input methods: the view adopts NSTextInputClient. When a text field has the focus, keyDown: goes through interpretKeyEvents:, so the system's input method sees the key first and answers with insertText: (typed or committed text), setMarkedText: (a composition, drawn by the field, see gfx/text_input.h) or doCommandBySelector: (an editing key, delivered as the KeyPress it always was). Every range arithmetic step lives in TextInputSession and is tested on Windows; what is here is the NSString and NSRange at the edge. Without a text field focused, keys take the path they always took -- a knob has nothing to compose into, and an input method that ate its keys would swallow the host's shortcuts.

tests/mac_input_selftest.cpp is what a Mac developer runs to see what both expose; until somebody has, treat both as written and not working.

Types 2

structgfx::cocoa::CoreGraphicsApi

window_cocoa.h:190

The bit of CoreGraphics needed to put a rectangle of pixels on screen. Resolved with dlsym rather than linked, so nothing here adds a framework a generated project would have to name.

classgfx::NativeWindowCocoa

window_cocoa.h:265

A component tree in an NSView, with the same surface as the other two peers.

Identical API on purpose: NativeEditor holds whichever one the platform has and knows nothing about which, so a difference between platforms has to be written deliberately rather than arrived at.

Functions 56

Constants 2

↑↓ to move↵ to openEvery public name in the headers, and every guide