Cocoa Internals/Application: what changed

Revision 3 to 4. 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		-	~~```~~
	13	+	```text
14	14		*** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason:
15	15		'Cannot update for observer <NSFrontmostDocumentWindowObserver 0x7fff8ec52208> for the key path "mainWindow.representedURL"
16	16		from <TCocoaApplication 0x100d089a0>, most likely because the value for the key "mainWindow" has changed without an appropriate
17	17		KVO notification being sent. Check the KVO-compliance of the TCocoaApplication class.'
18	18		```
19	19
20	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.
21	21
22	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)
23	23
24	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'.
25	25
26	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.
27	27
28	28		Suggested fix (patch attached) is to run through NSApplication.run first and then jump into our aloop().
29	29
30	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.
31	31
32	32		### Native Loop (COCOALOOPNATIVE)
33	33
34	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.
35	35
36	36		Downside
37	37
38	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).
39	39
40	40		todo:
41	41
42	42		- test application termination with Modal loops involved. (stop: needs to be called for EVERY modal loop started) passed
43	43		- check exception catching for "sync" methods. (as those are not really events) passed
44	44
45	45		### Manual Event Loop (COCOALOOPOVERRIDE)
46	46
47	47
48	48		WARNING the method described below is no longer used.
49	49
50	50		Cocoa Widgetset implements even loops manually. Apple documentation advises that it's possible, though could be complicated.
51	51
52	52		The actual event processing code could be found at AppWaitMessage and AppProcessMessage.
53	53
54	54		```delphi
55	55		procedure TCocoaWidgetSet.AppWaitMessage;
56	56		var
57	57		event : NSEvent;
58	58		pool:NSAutoReleasePool;
59	59		begin
60	60		pool := NSAutoreleasePool.alloc.init;
61	61		event := NSApp.nextEventMatchingMask_untilDate_inMode_dequeue(NSAnyEventMask, NSDate.distantFuture, NSDefaultRunLoopMode, true);
62	62		if event <> nil then
63	63		begin
64	64		if (event.type_ = NSApplicationDefined) and (event.subtype = LCLEventSubTypeMessage) and (event.data1 = LM_NULL) and (event.data2 = AppHandle) then
65	65		CheckSynchronize
66	66		else
67	67		NSApp.sendEvent(event);
68	68		NSApp.updateWindows;
69	69		end;
70	70		pool.release;
71	71		end;
72	72		```
73	73
74	74		### Sub-classing NSApplication
75	75
76	76
77	77		WARNING the method described below is no longer used.
78	78
79	79		With a manual event loop implementation, there's another problem showed up.
80	80
81	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:
82	82
83	83
84	84
85	85		Important
86	86
87	87		Many AppKit classes rely on the NSApplication class and may not work properly until this class is fully initialized.
88	88
89	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.
90	90
91	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))
92	92
93	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:
94	94
95	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)
96	96		- subclass NSApplication, override "isRunning" (getter of "running" property)
97	97
98	98		The sub-classing option is used, introducing TCocoaApplication class. It overrides two methods:
99	99
100	100		- run - the code is actually LCL Loop procedure, which would process ObjC events loop manually
101	101		- isRunning - returns true, if run method was actually called.
102	102
103	103		## Termination
104	104
105	105		Normally, NSApplication.run: method never returns after being called.
106	106
107	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.
108	108
109	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.
110	110
111	111		## Sync (MainThreadWake), PostMessage and SendMessage
112	112
113	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
114	114
115	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.
116	116
117	117		Each tracking loop however, is written differently. And some places reacting on "unexpected" events differently.
118	118
119	119		Trying to hide "unexpected" events from a loop might work for one implementation, but not the other.
120	120
121	121		The only solution that satisfies every loop is NOT to post any custom events at all.
122	122
123	123		The implementation was changed from using a custom event to performSelectorOnMainThread method.
124	124
125	125		For syncing with the main thread there's lclSyncCheck: method introduced for TCocoaApplication.
126	126
127	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).
128	128
129	129		### Clogging with Dialogs
130	130
131	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.
132	132
133	133		## Post Event Processing
134	134
135	135		There a number of routines performed after processing each event.
136	136
137	137		### Clipboard
138	138
139	139		In Cocoa, clipboard is named Pasteboard (class NSPasteboard);
140	140
141	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.
142	142
143	143		The whole implementation of API is in TCocoaWidgetSet class. (todo: could/should be separated)
144	144
145	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)
146	146
147	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)
148	148
149	149		### ToCollect
150	150
151	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).
152	152
153	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).
154	154
155	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.
156	156
157	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.
158	158
159	159		### Focus Change
160	160
161	161		The change if control focus is made post event basis to prevent endless loops of focus-fight.
162	162
163	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.
164	164
165	165		To avoid that, the focus switch is verified after event processing.
166	166
167	167		## System Wide Events
168	168
169	169		There's a number of system-wide events that are reported via Application object.
170	170
171	171		### End of User Session
172	172
173	173		Usually triggered by a user logging out or the entire system shutdown.
174	174
175	175		Supported since <https://gitlab.com/freepascal.org/lazarus/lazarus/-/issues/34798>
176	176
177	177		- IntfQueryEndSession(var Cancel: Boolean);
178	178		- IntfEndSession;
179	179
180	180		### Application Active Status
181	181
182	182		- IntfAppActivate(const Async: Boolean = False); - the event when application gets "active" by gaining the keyboard focus.
183	183
184	184
185	185
186	186		supported by processing of applicationDidBecomeActive message
187	187
188	188		- IntfAppDeactivate(const Async: Boolean = False); - the even when application gets "deactivated" by losing keybaord focus.
189	189
190	190
191	191
192	192		supported by processing of applicationDidResignActive message
193	193
194	194		### Application maximization
195	195
196	196		- IntfAppMinimize;
197	197		- IntfAppRestore;
198	198
199	199		### Files Drop
200	200
201	201		Issued by the system file exchange (drag/drop mechanism). Files can be dropped on the Application icon (shown in the system Dock)
202	202
203	203		- IntfDropFiles(const FileNames: Array of String);
204	204
205	205
206	206
207	207		supported by processing application:openFiles files messages.
208	208
209	209		the list of files is also passed to the main form of the application (similar IntfDropFiles event), by TApplication method is called first.
210	210
211	211		### System Settings Changes
212	212
213	213		- IntfSettingsChange
214	214
215	215
216	216
217	217		not supported
218	218
219	219		- IntfThemeOptionChange
220	220
221	221
222	222
223	223		not supported (need to be supported for Light/Dark theme changes?)
224	224
225	225		## See Also
226	226
227	227		- [[Cocoa Internals]]
228	228		- [NSApplication](https://developer.apple.com/documentation/appkit/nsapplication?language=objc) - apple reference documentation for NSApplication class.
229	229
230	230		---
231	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).
232	232		Category: Cocoa
233	233		Category: macOS

Back to history