Cocoa Internals/Application: what changed

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

Back to history