Cocoa Internals/Application: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		Cocoa's Application API pretty much matches what LCL provides. It could be possible to simply call NSApp apis, that correspond to LCL APIs. However, there's a major difference, that makes a simple solution not possible. LCL Application provides a methods HandleMessages and ProcessMessagess allowing a manual control over the event-loop.
2	2
3	3		NSApp doesn't provide any corresponding counter parts, thus it's necessary to process events loops manually.
4	4
5	5		## Event Loop
6	6
7	7		The technical decisions over TCocoaApplication implementation are described below.
8	8
9	9		### HiJacking (COCOALOOPHIJACK)
10	10
11	11		macOS 10.15 beta is throwing a KVO inconsistency error. The issue <https://bugs.freepascal.org/view.php?id=35702>
12	12
13		-	~~`*** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: `\~~
14		-	~~`'Cannot update for observer <NSFrontmostDocumentWindowObserver 0x7fff8ec52208> for the key path "mainWindow.representedURL" `\~~
15		-	~~`from <TCocoaApplication 0x100d089a0>, most likely because the value for the key "mainWindow" has changed without an appropriate `\~~
16		-	~~`KVO notification being sent. Check the KVO-compliance of the TCocoaApplication class.'`~~
	13	+	```
	14	+	*** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason:
	15	+	'Cannot update for observer <NSFrontmostDocumentWindowObserver 0x7fff8ec52208> for the key path "mainWindow.representedURL"
	16	+	from <TCocoaApplication 0x100d089a0>, most likely because the value for the key "mainWindow" has changed without an appropriate
	17	+	KVO notification being sent. Check the KVO-compliance of the TCocoaApplication class.'
	18	+	```
17	19
18	20		Crash can occur on on startup (for our app) or also reported to happen when a two form app when opening second form as modal dialog.
19	21
20	22		Error is caused because Cocoa currently doesn't run through base level NSApplication.run and thus appropriate ._isrunning flag is not set (notice that this also required the override of NSApplication.isRunning done for Mantis 32177)
21	23
22	24		NSFrontmostDocumentWindowObserver registers for all changes to mainWindow.representedURL. During initialization of NSApplication (down inside Cocoa code) calls to willChangeValueForKey() and didChangevalueForKey() are made to '_mainWindow' or 'mainWindow' depending on state of _isRunning flag (not from calls to .isRunning but from the memory locaiton where it is stored) and NSapplication.isActive. Because we don't go through NSApplication.run the bit for .isRunning is never set and calls to willChangevalueForKey(), didChangevalueForKey() do not happen appropriately for 'mainWindow'.
23	25
24	26		The crash occurs when _handleApplicationActivated calls removeObserverForKeyPath() on an observer object that is supposed to be set up for 'mainWindow' but it was never actually set up i.e. addObserverForKeyPath() was never called. Documentation for removeObserverForKeyPath() indicates that removing an object that hasn't been set up with addObserverForKeyPath() is an error condition. That is the condition we are hitting.
25	27
26	28		Suggested fix (patch attached) is to run through NSApplication.run first and then jump into our aloop().
27	29
28	30		Accomplished by removing TCocoaApplication.isRunning and TCocoaApplication.run methods thus allowing NSApplication.run to be called and set up NSRunloop and make first call to nextEventMatching:unitDate, etc. On first pass through nextEventMatching. (as caught by isRun = false) we grab control and call aloop.
29	31
30	32		### Native Loop (COCOALOOPNATIVE)
31	33
32	34		The approach doesn't interfere with Cocoa loop processing. The approach also DOES NOT use LCL event processing loop (as LCL event loop blocks Cocoa loop from running). Instead approach is catching FPC exceptions and handles them through LCL routines. Also end of event processing should cause Idle event to be performed. That lets Cocoa loop to run without interruptions.
33	35
34	36		Downside
35	37
36	38		- Since Application.RunLoop is not used, every time it's updated, CocoaWS side needs to be updated also. It's possible however, to Modify LCL to make the task easier. (which might look like a ultimate solution).
37	39
38	40		todo:
39	41
40	42		- test application termination with Modal loops involved. (stop: needs to be called for EVERY modal loop started) passed
41	43		- check exception catching for "sync" methods. (as those are not really events) passed
42	44
43	45		### Manual Event Loop (COCOALOOPOVERRIDE)
44	46
45	47
46	48		WARNING the method described below is no longer used.
47	49
48	50		Cocoa Widgetset implements even loops manually. Apple documentation advises that it's possible, though could be complicated.
49	51
50	52		The actual event processing code could be found at AppWaitMessage and AppProcessMessage.
51	53
52	54		```delphi
53	55		procedure TCocoaWidgetSet.AppWaitMessage;
54	56		var
55	57		event : NSEvent;
56	58		pool:NSAutoReleasePool;
57	59		begin
58	60		pool := NSAutoreleasePool.alloc.init;
59	61		event := NSApp.nextEventMatchingMask_untilDate_inMode_dequeue(NSAnyEventMask, NSDate.distantFuture, NSDefaultRunLoopMode, true);
60	62		if event <> nil then
61	63		begin
62	64		if (event.type_ = NSApplicationDefined) and (event.subtype = LCLEventSubTypeMessage) and (event.data1 = LM_NULL) and (event.data2 = AppHandle) then
63	65		CheckSynchronize
64	66		else
65	67		NSApp.sendEvent(event);
66	68		NSApp.updateWindows;
67	69		end;
68	70		pool.release;
69	71		end;
70	72		```
71	73
72	74		### Sub-classing NSApplication
73	75
74	76
75	77		WARNING the method described below is no longer used.
76	78
77	79		With a manual event loop implementation, there's another problem showed up.
78	80
79	81		NSWindows are behaving differently depending if NSApplication has started or not. (running property returning TRUE or FALSE). The Apple documentation doesn't mention that specifically, except for the following note:
80	82
81	83
82	84
83	85		Important
84	86
85	87		Many AppKit classes rely on the NSApplication class and may not work properly until this class is fully initialized.
86	88
87	89		As a result, you should not, for example, attempt to invoke methods of other AppKit classes from an initialization method of an NSApplication subclass.
88	90
89	91		If NSApplication is not running, then NSWindows would not pass the focus to another Window with the application. Instead they would keep the focus (if hidden) or make no window a focused window (if closed). (see [\#32177](https://bugs.freepascal.org/view.php?id=32177))
90	92
91	93		There are two options to make NSApplication [running](https://developer.apple.com/documentation/appkit/nsapplication/1428759-running?language=objc) flag to set to true:
92	94
93	95		- use NSApp default [run](https://developer.apple.com/documentation/appkit/nsapplication/1428631-run?language=objc) method (which could not be used, due to the need of manual event processing)
94	96		- subclass NSApplication, override "isRunning" (getter of "running" property)
95	97
96	98		The sub-classing option is used, introducing TCocoaApplication class. It overrides two methods:
97	99
98	100		- run - the code is actually LCL Loop procedure, which would process ObjC events loop manually
99	101		- isRunning - returns true, if run method was actually called.
100	102
101	103		## Termination
102	104
103	105		Normally, NSApplication.run: method never returns after being called.
104	106
105	107		NSApplication provides a special terminate: method to terminate Cocoa App. The method terminates the running process (allowing run: never to return). It should NEVER be used for FPC environment, as FreePascal runtime should call unit finalization.
106	108
107	109		The way to make run: method to return is use stop: method. Which stops the current event loop, and should be called multiple times with multiple event loops (such as modal) are used.
108	110
109	111		## Sync (MainThreadWake), PostMessage and SendMessage
110	112
111	113		Originally the syncing with the main thread, as well as Post and SendMessage implementations were based on creating a custom NSApplicationDefined event with sub type set to LCLEventSubTypeMessage
112	114
113	115		Posting the custom event into an event loop on Cocoa might have a certain undesired consequences. The major problem is with event processing for tracking mouse actions. Unlike WinAPI, where it is expected for to process standalone events, Cocoa developer should actually run a while loop. The loop should catch mouse events and stop as soon as mouse is released.
114	116
115	117		Each tracking loop however, is written differently. And some places reacting on "unexpected" events differently.
116	118
117	119		Trying to hide "unexpected" events from a loop might work for one implementation, but not the other.
118	120
119	121		The only solution that satisfies every loop is NOT to post any custom events at all.
120	122
121	123		The implementation was changed from using a custom event to performSelectorOnMainThread method.
122	124
123	125		For syncing with the main thread there's lclSyncCheck: method introduced for TCocoaApplication.
124	126
125	127		For post and send events, there's a message TLCLEventMessage class, which performSelectorOnMainThread: method is called. The class provides fields to store WParam, LParam and Result (for SendMessage).
126	128
127	129		### Clogging with Dialogs
128	130
129	131		There's an issue with a clogged sync processing. If there are two messages sent to the main thread, where both are causing a modal window to be shown. (i.e. an error message). Then if the second one arrives, while the first one is still showing the modal window, the application terminates.
130	132
131	133		## Post Event Processing
132	134
133	135		There a number of routines performed after processing each event.
134	136
135	137		### Clipboard
136	138
137	139		In Cocoa, clipboard is named Pasteboard (class NSPasteboard);
138	140
139	141		The global (system-wide) pasteboard is available via NSPasteboard.generalPasteboard method. Primary and Secondary selection boards are just unique named NSPasteboards allocated at start.
140	142
141	143		The whole implementation of API is in TCocoaWidgetSet class. (todo: could/should be separated)
142	144
143	145		The older (10.5 and earlier) APIs are used for operations. (starting with 10.6 Apple suggests using the new API, but the old one has not been deprecated so far)
144	146
145	147		There's not NSPasteboard change notification in place (unlike Windows), thus the only way to track, if the content got changed (in LCL/Windows terms - clipboard ownership was lost) is through checking "changeCount" property. The property is checked on EVERY event processed (which might impact efficiency). The only way to get rid of that is to rewrite Clipboard LCL object. (instead of relying on a notification - it should check for the change at "Get" data calls)
146	148
147	149		### ToCollect
148	150
149	151		On certain conditions a control can destroy itself while processing its own event. (For example an Edit field of a "authentication" dialog. If enter is pressed, the OnKeyDown event to close the form, causing its all children controls, including the edit field itself).
150	152
151	153		If such things occur, the callback object (linking NSObject and LCL Target) can be released (in DestoryHandle call). However, the callback object must not be freed, as Key processing routine (the one that started OnKeyDown) is not yet over. The same concept applies for other processing routines (i.e. Mouse handling, etc).
152	154
153	155		In order to prevent crashed due to access of freed object, the destruction of Callbacks objects is delayed until the end of event processing. Cocoa widgetset interface provides following method AddToCollect to add an object to be released after the event processing.
154	156
155	157		Keep in mind that events handling might be recursive, thus a destruction of an object only occurs when the processing of the event that added object to the collection is finished.
156	158
157	159		### Focus Change
158	160
159	161		The change if control focus is made post event basis to prevent endless loops of focus-fight.
160	162
161	163		Focus-fight occurs, a focus change notification is sent at the time when the focus is actually switched. It's typical for Cocoa controls to temporary switch focus to Window. (in Cocoa world, Window is used a "back-up" focus target. As it always allows to be focused... even with canBecomeKeyWindow false?). If LCL is notified by Windows getting the focus, it would attempt to switch the focus to one of its child control. This would typically be the same control as it's now. Eventually Cocoa would try to switch the focus back to Window, causing the recursive focus-fight with application responsiveness and eventual crash.
162	164
163	165		To avoid that, the focus switch is verified after event processing.
164	166
165	167		## System Wide Events
166	168
167	169		There's a number of system-wide events that are reported via Application object.
168	170
169	171		### End of User Session
170	172
171	173		Usually triggered by a user logging out or the entire system shutdown.
172	174
173	175		Supported since <https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/34798>
174	176
175	177		- IntfQueryEndSession(var Cancel: Boolean);
176	178		- IntfEndSession;
177	179
178	180		### Application Active Status
179	181
180	182		- IntfAppActivate(const Async: Boolean = False); - the event when application gets "active" by gaining the keyboard focus.
181	183
182	184
183	185
184	186		supported by processing of applicationDidBecomeActive message
185	187
186	188		- IntfAppDeactivate(const Async: Boolean = False); - the even when application gets "deactivated" by losing keybaord focus.
187	189
188	190
189	191
190	192		supported by processing of applicationDidResignActive message
191	193
192	194		### Application maximization
193	195
194	196		- IntfAppMinimize;
195	197		- IntfAppRestore;
196	198
197	199		### Files Drop
198	200
199	201		Issued by the system file exchange (drag/drop mechanism). Files can be dropped on the Application icon (shown in the system Dock)
200	202
201	203		- IntfDropFiles(const FileNames: Array of String);
202	204
203	205
204	206
205	207		supported by processing application:openFiles files messages.
206	208
207	209		the list of files is also passed to the main form of the application (similar IntfDropFiles event), by TApplication method is called first.
208	210
209	211		### System Settings Changes
210	212
211	213		- IntfSettingsChange
212	214
213	215
214	216
215	217		not supported
216	218
217	219		- IntfThemeOptionChange
218	220
219	221
220	222
221	223		not supported (need to be supported for Light/Dark theme changes?)
222	224
223	225		## See Also
224	226
225	227		- [[Cocoa Internals]]
226	228		- [NSApplication](https://developer.apple.com/documentation/appkit/nsapplication?language=objc) - apple reference documentation for NSApplication class.
227	229
228	230		---
229	231		From the Free Pascal wiki, page "Cocoa Internals/Application", as it stood on 2022-02-21 after a change by Skalogryz, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
230	232		Category: Cocoa
231	233		Category: macOS

Back to history