Cocoa Internals: what changed

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

Old	New		Line
1	1		The page is about the 64 bit Cocoa Widgetset internal implementation. The page should be useful for Cocoa widgetset developers (maintainers and/or contributors) as well as any developers who need to use the Cocoa-specific API.
2	2
3	3		## Minimum Version
4	4
5	5		- Some parts of Cocoa are written using Objective C 2.0 features. Objective C 2.0 features used:
6	6
7	7
8	8
9	9		[Enumeration in Objective-C classes](https://www.freepascal.org/docs-html/ref/refse76.html#x138-16000011.10)
10	10
11	11		- Minimal macOS version is:
12	12
13	13		:* 10.5 - spiritual
14	14
15	15		:* 10.6 - de facto (a lot of 10.6 only APIs are used without any actual verification of the proper macOS version)
16	16
17	17		There's a reason to keep the backwards compatibility for 10.6. This is the last system that supports Rosetta applications to allow running [PowerPC](https://en.wikipedia.org/wiki/PowerPC) applications on an Intel processor.
18	18
19	19		### Compiler Support
20	20
21	21		APIs that not (yet) provided by a corresponding version of FPC (delivered with Lazarus), should be declared at cocoa_extra.pas header
22	22
23	23		It's desired that the legacy version (i.e. deprecated APIs) would be wrapped into the [[FPC New Features 2.6.2\|minimum version defines]].
24	24
25	25		If an application using LCL to be deployed to App Store, Apple would verify the used APIs and ban, if any older APIs are used.
26	26
27	27		## Recompilation
28	28
29	29		If you tried to modify Cocoa-Widget and the next attempt at the project or its Cocoa compilation throws an unexpected error like "cocoawscommon.pas(y:x) Error: identifier idents no member "lclFrame"", you need to delete all Cocoa compiled units.
30	30
31		-	~~` ./lazarus/lcl/units/i386-darwin/cocoa`~~
	31	+	```
	32	+	./lazarus/lcl/units/i386-darwin/cocoa
	33	+	```
32	34
33	35		or
34	36
35		-	~~` ./lazarus/lcl/units/x86_64-darwin/cocoa`~~
	37	+	```
	38	+	./lazarus/lcl/units/x86_64-darwin/cocoa
	39	+	```
36	40
37	41		(to be reported - compiler issue with ignoring extensions)
38	42
39	43		### Reconfigure LCL package
40	44
41	45		![](/wiki-images/5/53/LCL_configure_cocoa_to_removeunits.png)
42	46
43	47		Another way is to configure the LCL package to always remove .o files before recompilation of the package itself. (The same effect as removing it from command line):
44	48
45	49		- Open LCL package ( Package -\> Open Loaded Package ... -\>LCL )
46	50		- Select (package) "Options"
47	51		- Select "Compiler Command"
48	52		- specify command for "Execute before"
49	53
50		-	~~`sh -c "rm -f ../units/$(TargetCPU)-$(TargetOS)/$(LCLWidgetType)/*"`~~
	54	+	```
	55	+	sh -c "rm -f ../units/$(TargetCPU)-$(TargetOS)/$(LCLWidgetType)/*"
	56	+	```
51	57
52	58		Note that use of sh is necessary, because Lazarus IDE doesn't process * (asterisk)
53	59
54	60		## LCL specific ObjC classes
55	61
56	62		In order to control and handle an NSView's behavior LCL uses descendent classes from standard Cocoa controls. That is, for NSWindow, TCocoaWindow is introduced. The descedants are used for the purpose of "overriding" default class implementation, where it is needed. In some cases using delegate classes is not enough.
57	63
58	64		There are two ways, in order to provide a common LCL(friendly) API interface for all Cocoa classes or sub-classes:
59	65
60	66		- use protocol (similar to Interfaces in Object Pascal form). Any class, sub-classing from standard Cocoa classes, would have to implement the protocol. The downside of this approach is - a lot of code would be duplicated.
61	67		- use categories (similar to Javascript prototypes, not available in Object Pascal. Class-helpers looks alike, but are not the same). Categories allow to add methods (only methods! adding variables is not allowed) to any base class of Objective-C. Any descendants of this class automatically acquire the method, and it's default implementation. Also any subclass, can override the default implementation with its own. Apple doesn't recommend the use of categories (due to ambiguity and possible conflicts among different libraries introducing their own extensions). See more at the [[Cocoa Internals/Extensions\|Cocoa Internals Extensions]] page
62	68
63	69		## Code Style
64	70
65	71		The following requirement applies for Cocoa widgetset. Other widgetset may be following some other rules (historically), but in general LCL follows the same requirements.
66	72
67	73		- Operators Keep the operator separated by spaces between operands
68	74
69		-	~~` A := B; `\~~
70		-	~~` A := B * C;`~~
	75	+	``` pascal
	76	+	A := B;
	77	+	A := B * C;
	78	+	```
71	79
72	80		- Blocks The main rule is to make 2 character spacing from the code block start. Begin / Else should start on a new line.
73	81
74	82		``` pascal
75	83		procedure B;
76	84		begin
77	85		if A then // 2 character spacing from begin
78	86		begin
79	87		Start Here // 2 character spacing from begin
80	88		Next Line
81	89		end
82	90		else
83	91		begin
84	92		Another Line
85	93		end;
86	94		end;
87	95		```
88	96
89	97		- Standard Function Name please keep naming in ProperCase. Reserved words should be lower case. Name of (global/local) variables and fields should match declaration. Local variables should start with lower case.
90	98
91	99		``` pascal
92	100		if not Assigned(A) then
93	101		begin
94	102		Result := nil;
95	103		end;
96	104		```
97	105
98	106		## Using for-in instead of for
99	107
100	108		When dealing with arrays, it's common for Pascal to write the code using "Integer" type array index like:
101	109
102	110		```delphi
103	111		var
104	112		i : integer;
105	113		l : TList;
106	114		...
107	115		for i:=0 to l.Count-1 do
108	116		...
109	117		```
110	118
111	119		Cocoa provides it's own implementation of arrays using NSArray class. Writing the the loop in the same manner:
112	120
113	121		```delphi
114	122		var
115	123		i : integer;
116	124		l : NSArray;
117	125		...
118	126		for i:=0 to l.count-1 do
119	127		...
120	128		```
121	129
122	130		is possible, though not desired.
123	131
124	132		The reason for that, is that NSArray "count" is an NSUInteger type for Cocoa. This type has a different size on 32 and 64 platforms. (While "Integer" type is always 32 bit in FPC.)
125	133
126	134		Thus while the code written above might work just fine on 32-platform, it might cause a range check error (if such check is enabled) on a 64 bit machine. For example, when count is zero. Here's a simplest (no ObjC) example of the problem:
127	135
128	136		```delphi
129	137		{$R+}
130	138		function Count: qword;
131	139		begin
132	140		Result := 0;
133	141		end;
134	142		var
135	143		i: Integer;
136	144		begin
137	145		for i := 0 to Count-1 do // <- throws a range check error, because QWord result doesn't fit for Integer index
138	146		WriteLn(i);
139	147		end.
140	148		```
141	149
142	150		However, running a loop from elements of an array is quite a common task. For example - changing attributes of all children controls, due to some action.
143	151
144	152		Instead of using a higher size Index variable (i.e. PtrInt or PtrUInt), it's handy to use for-in loop. Most common Objective C classes provide a special feature (NSFastEnumerator protocol) to do enumeration through its member. It works for the 32 bit and well as the 64 bit platform, in the same manner, but requires the Objective C 2.0 runtime version (with objectivec2 modeswitch enabled).
145	153
146	154		An iteration for-in loop might look like this:
147	155
148	156		```delphi
149	157		var
150	158		obj : NSObject;
151	159		arr : NSArray;
152	160		...
153	161		for obj in arr do
154	162		...
155	163		```
156	164
157	165		## Writing a Cocoa app without the LCL
158	166
159	167		This is useful for testing hard to debug bugs in the LCL. Here is an example program written in Pascal-Cocoa which creates a window with 2 buttons and a simple set of menus:
160	168
161	169		```delphi
162	170		program cocoa_without_lcl;
163	171
164	172		{$mode objfpc}{$H+}
165	173		{$modeswitch objectivec1}
166	174
167	175		uses
168	176		CocoaAll, classes, sysutils;
169	177
170	178		type
171	179		{ TMyDelegate }
172	180		TMyDelegate = objcclass(NSObject)
173	181		public
174	182		procedure HandleButtonClick_A(sender: id); message 'HandleButtonClick_A:';
175	183		procedure HandleButtonClick_B(sender: id); message 'HandleButtonClick_B:';
176	184		procedure HandleMenuClick_A(sender: id); message 'HandleMenuClick_A:';
177	185		procedure HandleMenuClick_B(sender: id); message 'HandleMenuClick_B:';
178	186		end;
179	187
180	188		var
181	189		appName: NSString;
182	190		window: NSWindow;
183	191		pool: NSAutoreleasePool;
184	192		lText: NSTextField;
185	193		lButton: NSButton;
186	194		lDelegate: TMyDelegate;
187	195		//
188	196		MainMenu_A: NSMenu;
189	197		TopItem_A: NSMenuItem;
190	198		TopMenu_A: NSMenu;
191	199		MenuItem_A: NSMenuItem;
192	200		//
193	201		MainMenu_B: NSMenu;
194	202		TopItem_B: NSMenuItem;
195	203		TopMenu_B: NSMenu;
196	204		MenuItem_B: NSMenuItem;
197	205
198	206		procedure TMyDelegate.HandleButtonClick_A(sender: id);
199	207		begin
200	208		NSApp.setMainMenu(MainMenu_A);
201	209		end;
202	210
203	211		procedure TMyDelegate.HandleButtonClick_B(sender: id);
204	212		begin
205	213		NSApp.setMainMenu(MainMenu_B);
206	214		end;
207	215
208	216		procedure TMyDelegate.HandleMenuClick_A(sender: id);
209	217		var
210	218		Str: string;
211	219		begin
212	220		Str := 'A '+inttostr(random(888));
213	221		window.setTitle(NSSTR(@Str[1]));
214	222		end;
215	223
216	224		procedure TMyDelegate.HandleMenuClick_B(sender: id);
217	225		var
218	226		Str: string;
219	227		begin
220	228		Str := 'B '+inttostr(random(888));
221	229		window.setTitle(NSSTR(@Str[1]));
222	230		end;
223	231
224	232		procedure CreateMenus;
225	233		var
226	234		nsTitle: NSString;
227	235		nsKey : NSString;
228	236
229	237		function CreateMenuItem(AName, AShortcut: string; ASelector: SEL): NSMenuItem;
230	238		begin
231	239		nsKey := NSSTR(PChar(AShortcut));
232	240		nsTitle := NSSTR(PChar(AName));
233	241		Result := NSMenuItem.alloc.initWithTitle_action_keyEquivalent(nsTitle, ASelector, nsKey);
234	242		Result.setKeyEquivalentModifierMask(NSCommandKeyMask);
235	243		nsTitle.release;
236	244		nsKey.release;
237	245		Result.setKeyEquivalentModifierMask(NSCommandKeyMask);
238	246		Result.setTarget(lDelegate);
239	247		end;
240	248
241	249		begin
242	250		MainMenu_A := NSMenu.alloc.initWithTitle(NSSTR('Menu A'));
243	251		TopItem_A := CreateMenuItem('TopItem A', '', nil);
244	252		MainMenu_A.insertItem_atIndex(TopItem_A, 0);
245	253		TopMenu_A := NSMenu.alloc.initWithTitle(NSSTR('TopMenu A'));
246	254		TopItem_A.setSubmenu(TopMenu_A);
247	255		MenuItem_A := CreateMenuItem('MenuItem A', 'A', objcselector('HandleMenuClick_A:'));
248	256		MenuItem_A.setTarget(lDelegate);
249	257		TopMenu_A.insertItem_atIndex(MenuItem_A, 0);
250	258
251	259		MainMenu_B := NSMenu.alloc.initWithTitle(NSSTR('Menu B'));
252	260		TopItem_B := CreateMenuItem('TopItem B', '', nil);
253	261		MainMenu_B.insertItem_atIndex(TopItem_B, 0);
254	262		TopMenu_B := NSMenu.alloc.initWithTitle(NSSTR('TopMenu B'));
255	263		TopItem_B.setSubmenu(TopMenu_B);
256	264		MenuItem_B := CreateMenuItem('MenuItem B', 'B', objcselector('HandleMenuClick_B:'));
257	265		MenuItem_B.setTarget(lDelegate);
258	266		TopMenu_B.insertItem_atIndex(MenuItem_B, 0);
259	267		end;
260	268
261	269		begin
262	270		// Autorelease pool, app and window creation
263	271		pool := NSAutoreleasePool.new;
264	272		NSApp := NSApplication.sharedApplication;
265	273		NSApp.setActivationPolicy(NSApplicationActivationPolicyRegular);
266	274		appName := NSProcessInfo.processInfo.processName;
267	275		window := NSWindow.alloc.initWithContentRect_styleMask_backing_defer(NSMakeRect(0, 0, 200, 200),
268	276		NSTitledWindowMask or NSClosableWindowMask or NSMiniaturizableWindowMask,
269	277		NSBackingStoreBuffered, False).autorelease;
270	278		lDelegate := TMyDelegate.alloc.init;
271	279
272	280		// text label
273	281		lText := NSTextField.alloc.initWithFrame(NSMakeRect(50, 50, 120, 50)).autorelease;
274	282		lText.setBezeled(False);
275	283		lText.setDrawsBackground(False);
276	284		lText.setEditable(False);
277	285		lText.setSelectable(False);
278	286		lText.setStringValue(NSSTR('NSTextField'));
279	287		window.contentView.addSubview(lText);
280	288
281	289		// button
282	290		lButton := NSButton.alloc.initWithFrame(NSMakeRect(50, 100, 120, 50)).autorelease;
283	291		window.contentView.addSubview(lButton);
284	292		lButton.setTitle(NSSTR('Button A!'));
285	293		lButton.setButtonType(NSMomentaryLightButton);
286	294		lButton.setBezelStyle(NSRoundedBezelStyle);
287	295		// button event handler setting
288	296		lButton.setTarget(lDelegate);
289	297		lButton.setAction(ObjCSelector(lDelegate.HandleButtonClick_A));
290	298
291	299		// button B
292	300		lButton := NSButton.alloc.initWithFrame(NSMakeRect(50, 150, 120, 50)).autorelease;
293	301		window.contentView.addSubview(lButton);
294	302		lButton.setTitle(NSSTR('Button B!'));
295	303		lButton.setButtonType(NSMomentaryLightButton);
296	304		lButton.setBezelStyle(NSRoundedBezelStyle);
297	305		// button event handler setting
298	306		lButton.setTarget(lDelegate);
299	307		lButton.setAction(ObjCSelector(lDelegate.HandleButtonClick_B));
300	308
301	309		// Menus
302	310		CreateMenus();
303	311		NSApp.setMainMenu(MainMenu_A);
304	312
305	313		// Window showing and app running
306	314		window.center;
307	315		window.setTitle(appName);
308	316		window.makeKeyAndOrderFront(nil);
309	317		NSApp.activateIgnoringOtherApps(true);
310	318		NSApp.run;
311	319		end.
312	320		```
313	321
314	322		## Units
315	323
316	324		The units should use the ".pas" extension, not ".pp" for consistency. Use of "include" is not welcome and is kept there for legacy reasons only (not to lose the history, if a file is merged).
317	325
318	326		Unit
319	327
320	328		Description
321	329
322	330		CocoaPrivate
323	331
324	332		The unit contains most of the Cocoa classes overrides. The unit should stay LCL-classes free as much as possible (i.e. should not use Forms, StdCtrls, etc. Though using LCLTypes or LCLProc is ok).
325	333
326	334		CocoaUtils
327	335
328	336		The set of utility functions mostly to convert types (between LCL and Cocoa types)
329	337
330	338		Input constant conversion utilities are also placed here.
331	339
332	340		Cocoa_Extra
333	341
334	342		The purpose of the unit is to full-fill missing FPC headers declarations for macOS. (whatever is missing at CocoaAll).
335	343
336	344		Should not contain any additional functions, except for external and constant declarations.
337	345
338	346		CocoaButtons
339	347
340	348		Controls that are considered buttons (except for NSPopupButton) are declared in this unit.
341	349
342	350		CocoaCarent
343	351
344	352		The unit provides the code to implement caret for Cocoa. Cocoa itself doesn't have any "caret" specific API.
345	353
346	354		CocoaDatepicker
347	355
348	356		The unit contains the implementation of cocoa calendar control
349	357
350	358		CocoaGDIObjects
351	359
352	360		Highlever wrappers over Cocoa object to implement LCL GDI handles.
353	361
354	362		CocoaScrollers
355	363
356	364		All controls related to scrolling: TScrollBar and variants of ScrollView are implemented here
357	365
358	366		CocoaTabControls
359	367
360	368		Classes that are used to implement tabcontrol (and tabpage) are declared here
361	369
362	370		CocoaTables
363	371
364	372		The master table class is declared here. (used for TListView and TListBox).
365	373
366	374		Supplemental classes for NSCell and NSView based tables are also in this unit
367	375
368	376		CocoaTextEdits
369	377
370	378		Text editting controls are implemented here. Including Combobox and NSpopupBox (readonly combobox)
371	379
372	380		CocoaTheme
373	381
374	382		Theme drawing class.(todo: get rid of "customdrawing" parts)
375	383
376	384		CocoaWindows
377	385
378	386		Classes related to the window and its contents are implemented here
379	387
380	388		CocoaInt
381	389
382	390		cocoawinapih.inc / cocoawinapi.inc
383	391
384	392		cocoalclapih.inc /cocoalclapi.inc
385	393
386	394		The Widgetset class API (winApi-style) are implemented here.
387	395
388	396		TCocoaApplication class is also declared and implemented in this unit. Both Widgetset object and code of TCocoaApplication class are mutually using each other.
389	397
390	398		Widgetset interfacing units
391	399
392	400		CocoaWSCommon
393	401
394	402		The unit contains common bindings between native Cocoa (obcjclasses implemented in CocoaPrivate) and LCL. The actual callbacks interfaces are implemented here. Most of the "messaging" to LCL is also implemented here
395	403
396	404		## Callback Objects
397	405
398	406		- ICommonCallback is the primary object for Cocoa objects to report back actions taken. It prevents "the handlers" from dealing with Objective-C APIs over all.
399	407		- Some controls might introduce an additional interface to process more events. They all should inherit from ICommonCallback
400	408		- For each HANDLE created there should be exactly one CallBack object allocated, because
401	409		- Callback object is released on Destruction of the HANDLE (from LCL perspective). (Even though the actual ObjC object can be released later.)
402	410
403	411		## Why so Boolean?
404	412
405	413		Cocoa Widgetset introduces two ObjC-specific boolean types:
406	414
407	415		- LCLObjCBoolean - declared at CocoaPrivate and is commonly used for any Cocoa overridden methods
408	416		- ObjCBool - declared at Cocoa_Extra and is used under BOOL8FIX.
409	417
410	418		Both types were introduced to handle the issues with the Boolean type parameter. (Resulting Boolean value seems to be working as expected on x86_64).
411	419
412	420		However, the intent of each type is different:
413	421
414	422		- LCLObjCBoolean - is to compensate for FPC backwards incompatible change (targeted for 3.2.0 release) that's changing all "Boolean" type parameters to "Boolean8". Thus any overridden methods in LCL would stop compile. (Boolean8 is not an alias for Boolean.) Unfortunatelly the type is expected to stay likely forever.
415	423		- ObjCBool - is a need to resolve Boolean parameter problem with 3.0.4. For any call to boolean parameter method, additional methods were introduced to pass the parameter as byte parameter (unsigned char), and pass the actual value property. The type can be dropped as soon as LCL support for 3.0.4 is dropped. The type should not be used in any 3rd party components.
416	424
417	425		## See also
418	426
419	427		- [[Cocoa Interface]] - general information regarding the Cocoa Interface.
420	428		- [[Cocoa Internals/Application]] - details about use of NSApplication and clipboard.
421	429		- [[Cocoa Internals/Buttons]] - provides the information about internal implementation of Button controls.
422	430		- [[Cocoa Internals/Dialogs]] - implementation of common dialogs
423	431		- [[Cocoa Internals/Extensions]] - additional method introduced to ObjC classes, to prevent code duplication and if-conditions.
424	432		- [[Cocoa Internals/Forms]] - provides the information about internal implementation of Forms (Windows)
425	433		- [[Cocoa Internals/Graphics]] - graphics, fonts related topics.
426	434		- [[Cocoa Internals/Input]] - covers topics of Cocoa specific input processing implementation. Cocoa input processing is somewhat foreign to LCL (or Windows style) processing.
427	435		- [[Cocoa Internals/Memory Management]] - guidelines of memory management tactics, whenever writing/understanding Cocoa code. (provides a lot of general Cocoa information (also applicable for UIKit))
428	436		- [[Cocoa Internals/Menu]] - macOS menu bar
429	437		- [[Cocoa Internals/OS Versions]] - suggestions around macOS API deprecations.
430	438		- [[Cocoa Internals/Scroll]] - Scroll controls.
431	439		- [[Cocoa Internals/Text Controls]] - Cocoa text controls.
432	440		- [[Cocoa Internals/Theme]] - Cocoa Themes.
433	441		- [[Cocoa Internals/Widgetset]] - information about Handle implementation and focus change.
434	442
435	443		---
436	444		From the Free Pascal wiki, page "Cocoa Internals", as it stood on 2022-01-15 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).
437	445		Category: Cocoa
438	446		Category: Lazarus internals
439	447		Category: macOS

Back to history