Cocoa Internals/Graphics: what changed

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

Old	New		Line
1	1		## Colors
2	2
3	3		Cocoa-WS should be using device-dependent colors to match colors across other widgetsets.
4	4
5	5		That applies to color of Pen, Brush and Font.
6	6
7	7
8	8		The “Device” color-space names represent color spaces in which component values are applied to devices as specified. There is no optimization or adjustment for differences between devices in how they render colors. If you know exactly which device is connected to a system and you want to print or display a certain color on that device, then it makes sense to use a appropriate device-dependent color space when creating NSColor objects. However, it is usually not the case that an application knows which devices are connected and their specific color spaces. If you specify components of a color in a device-dependent color space—let’s say NSDeviceRGBColorSpace—and then have several displays render this color, you will see several slightly different colors.
9	9
10	10
11	11		To get around this problem you can use calibrated color spaces, which are designated by two of the color-space names in Table 1. A calibrated color space is a device-independent color space. The color spaces designated by NSCalibratedWhiteColorSpace and NSCalibratedRGBColorSpace color spaces are calibrated to a device that best represents devices in a particular class, such as color displays. It allows your application to present reasonably accurate colors when you are unsure about the color space of a device in a particular context.
12	12
13	13		### System Colors
14	14
15	15		NSColor class provides a large variety of system themed colors:
16	16
17	17		Constant
18	18
19	19		LCL definition
20	20
21	21		NSColor
22	22
23	23		[Cocoa definition](https://developer.apple.com/documentation/appkit/nscolor?language=objc)
24	24
25	25		clScrollBar
26	26
27	27		Scrollbar body
28	28
29	29		scrollBarColor
30	30
31	31		Returns the system color used for scroll “bars”—that is, for the groove in which a scroller’s knob moves
32	32
33	33		clBackground
34	34
35	35		Desktop background color
36	36
37	37		windowBackgroundColor
38	38
39	39		Returns a pattern color that will draw the ruled lines for the window background.
40	40
41	41		clActiveCaption
42	42
43	43		Active window titlebar
44	44
45	45		windowFrameColor
46	46
47	47		Returns the system color used for window frames, except for their text.
48	48
49	49		clInactiveCaption
50	50
51	51		Inactive window titlebar
52	52
53	53		windowBackgroundColor
54	54
55	55		clMenu
56	56
57	57		Regular menu item background color
58	58
59	59		controlBackgroundColor
60	60
61	61		Returns the system color used for the background of large controls.
62	62
63	63		clWindow
64	64
65	65		The normal background brush of unselected text. Defined for controls like TEdit, TComboBox, TMemo, TListBox, TTreeView.
66	66
67	67		textBackgroundColor
68	68
69	69		Returns the system color used for the text background.
70	70
71	71		clWindowFrame
72	72
73	73		Color of frame around the window
74	74
75	75		windowFrameColor
76	76
77	77		clMenuText
78	78
79	79		The font color to use together with clMenu
80	80
81	81		controlTextColor
82	82
83	83		Returns the system color used for text on controls that aren’t disabled.
84	84
85	85		clWindowText
86	86
87	87		Font color to use together with clWindow
88	88
89	89		controlTextColor
90	90
91	91		clCaptionText
92	92
93	93		Active window titlebar text color
94	94
95	95		windowFrameTextColor
96	96
97	97		Returns the system color used for the text in window frames.
98	98
99	99		clActiveBorder
100	100
101	101		?
102	102
103	103		windowFrameColor
104	104
105	105		clInactiveBorder
106	106
107	107		?
108	108
109	109		windowFrameColor
110	110
111	111		clAppWorkspace
112	112
113	113		MDIMain form background
114	114
115	115		windowBackgroundColor
116	116
117	117		clHighlight
118	118
119	119		The brush color of selected element
120	120
121	121		selectedControlColor
122	122
123	123		Returns the system color used for the face of a selected control—a control that has been clicked or is being dragged.
124	124
125	125		clHighlightText
126	126
127	127		Font color of selected text (to use together with clHighligh).
128	128
129	129		selectedControlTextColor
130	130
131	131		Returns the system color used for text in a selected control—a control being clicked or dragged.
132	132
133	133		clBtnFace
134	134
135	135		Button background
136	136
137	137		controlColor
138	138
139	139		Returns the system color used for the flat surfaces of a control.
140	140
141	141		clBtnShadow
142	142
143	143		Button shadow color (bottom right) used to achieve 3D effect
144	144
145	145		controlShadowColor
146	146
147	147		Returns the system color used for the shadows dropped from controls.
148	148
149	149		clGrayText
150	150
151	151		The font color of disabled element
152	152
153	153		disabledControlTextColor
154	154
155	155		Returns the system color used for text on disabled controls.
156	156
157	157		clBtnText
158	158
159	159		Button font color to use together with clBtnFace
160	160
161	161		controlTextColor
162	162
163	163		clInactiveCaptionText
164	164
165	165		Inactive window titlebar text color
166	166
167	167		windowFrameTextColor
168	168
169	169		clBtnHighlight
170	170
171	171		Button highlight color (top left) used to achieve 3D effect
172	172
173	173		controlLightHighlightColor
174	174
175	175		Returns the system color used for light highlights in controls.
176	176
177	177		cl3DDkShadow
178	178
179	179		?
180	180
181	181		controlDarkShadowColor
182	182
183	183		Returns the system color used for the dark edge of the shadow dropped from controls.
184	184
185	185		cl3DLight
186	186
187	187		?
188	188
189	189		controlHighlightColor
190	190
191	191		Returns the system color used for the highlighted bezels of controls.
192	192
193	193		clInfoText
194	194
195	195		Font color for hints. Use together with clInfoBk
196	196
197	197		controlTextColor
198	198
199	199		clInfoBk
200	200
201	201		Brush color for hints. Use together with clInfoText
202	202
203	203		hard coded
204	204
205	205		The actual color value depends on MacOS version. Before macOS 10.10 (Yosemite) the color is yellowish. on 10.10 and after, the color is gray. The change follows Apple system hint color change. The API to identify hint window color is unknown.
206	206
207	207		CocoaInt unit also provides a global variable CocoaHintColor. The value is used to return value for clInfoBk. Thus if Apple changes the design in future, you can always adjust hint color from your code.
208	208
209	209		clHotLight
210	210
211	211		?
212	212
213	213		alternateSelectedControlColor
214	214
215	215		Returns the system color used for the face of a selected control in a list or table.
216	216
217	217		clGradientActiveCaption
218	218
219	219		The second color used to make gradient of active window titlebar
220	220
221	221		windowFrameColor
222	222
223	223		clGradientInactiveCaption
224	224
225	225		The second color used to make gradient for inactive window titlebar
226	226
227	227		windowBackgroundColor
228	228
229	229		clMenuHighlight
230	230
231	231		The background color of selected menu item
232	232
233	233		selectedMenuItemColor
234	234
235	235		Returns the system color used for the face of selected menu items. (depreciated in macOS 10.14)
236	236
237	237		clMenuBar
238	238
239	239		The Backround color of menu bar
240	240
241	241		selectedTextBackgroundColor
242	242
243	243		Returns the system color used for the background of selected text.
244	244
245	245		clForm
246	246
247	247		?
248	248
249	249		windowBackgroundColor
250	250
251	251		clColorDesktop
252	252
253	253		?
254	254
255	255		cl3DFace
256	256
257	257		?
258	258
259	259		cl3DShadow
260	260
261	261		?
262	262
263	263		cl3DHiLight
264	264
265	265		?
266	266
267	267		clBtnHiLight
268	268
269	269		Same as clBtnHighlight
270	270
271	271		For Reference: [Apple Human Interface Guidelines - Dynamic System Colors](https://developer.apple.com/design/human-interface-guidelines/macos/visual-design/color/#dynamic-system-colors)
272	272
273	273		### Hint Window
274	274
275	275		Cocoa provides its own API to show a popup hint window. Thus Cocoa doesn't provide must information on how hint popup window should actually be shown.
276	276
277	277		On dark theme of Mojave system, it became a bit more complicated. Besides a different fill color for darktheme, the popup window also draws a border of light pixels. ![](/wiki-images/2/2f/Mojave-DarkLight-Tooltip.png)
278	278
279	279		## Fonts
280	280
281	281		Historically, MacOS (Classic MacOS, Mac OS X, and macOS) systems are using 72 ppi (or dpi). Windows is using 96 dpi (so do Linux desktop managers).
282	282
283	283		### Default
284	284
285	285		NSFont class provides a number of class methods to get proper system font without selecting the font by name. The same of getting system-native font size.
286	286
287	287		### 96 DPI
288	288
289	289		macOS native DPI (aka PPI) is 72 (it matches the basic typographic resolution).
290	290
291	291		For comparison: Windows native DPI is 96. You can read more about history of this difference [here](https://en.wikipedia.org/wiki/Dots_per_inch#Computer_monitor_DPI_standards)
292	292
293	293		In order to achieve the ease of use and design for cross-platform applications, Cocoa (screen) DPI is also emulated (by LCL) to be at 96 dpi. What that actually means is that font sizes between LCL applications and macOS native applications will be different (at roughly 33%).
294	294
295	295		![](/wiki-images/6/6b/CarbonFontWrong.png)
296	296
297	297		This can be adjusted by changing the CocoaBasePPI variable at run time.
298	298
299	299		### Font Enumeration
300	300
301	301		To implement windows-like font enumeration, two NSFontManager methods are used
302	302
303	303
304	304		availableFontFamilies - to get the list of families
305	305
306	306		availableMembersOfFontFamily: - to get the list of available styles for fonts
307	307
308	308		Input parameters recognized:
309	309
310	310		- todo: lfFaceName - the case-insensitive, exact name match.
311	311		-
312	312
313	313		## Handles
314	314
315	315		The following objects are used to implement HANDLEs for graphical objects
316	316
317	317		LCL Handle
318	318
319	319		Cocoa WS Class
320	320
321	321		Notes
322	322
323	323		HICON
324	324
325	325		TCocoaBitmap
326	326
327	327		HPEN
328	328
329	329		TCocoaPen
330	330
331	331		HBRUSH
332	332
333	333		TCocoaBrush
334	334
335	335		HRGN
336	336
337	337		TCocoaRegion
338	338
339	339		HCURSOR
340	340
341	341		TCocoaCursor
342	342
343	343		TCocoaCursor doesn't inherit from TCocoaBitmap)
344	344
345	345		HBITMAP
346	346
347	347		TCocoaBitmap
348	348
349	349		TBitmap.Canvas.Handle
350	350
351	351		TCocoaBitmapContext
352	352
353	353		The key difference from TCocoaContext is that after any changes to bitmap context, the underlying image itself is invalidated.
354	354
355	355		This is necessary for Windows like behavior. (macOS image objects are immutable, but windows bitmaps are)
356	356
357	357		TControl.Canvas.Handle
358	358
359	359		TCocoaContext
360	360
361	361		## Bitmap
362	362
363	363		TCocoaBitmap implements the internal bitmap handle.
364	364
365	365		### Change Tracking
366	366
367	367		In order for a bitmap (a 2d-array of pixel values) to be drawn, a NSBitmapImageRep object.
368	368
369	369		The NSBitmapImageRep is immutable. Its contents cannot be changed after the initial drawing (the pixel values seems it be copied within Cocoa).
370	370
371	371		If a Bitmap contents was modified (i.e. by using (Canvas) Drawing methods or by direct access via ScanLine), the bitmap must re-create NSBitmapImageRep before the next drawing.
372	372
373	373		The SetModified() marks the Bitmap as modified. TCocoaBitmapContext (Device Context created for a Bitmap) would mark the bitmap as modified on any draw method.
374	374
375	375		### Scan Lines
376	376
377	377		For PixelFormat 32-bit the pixel format is as following:
378	378
379		-	~~```~~
	379	+	```text
380	380		$BBGGRRAA
381	381		$ff0000ff - all blue
382	382		$00ff00ff - all green
383	383		$0000ffff - all red
384	384		$000000ff - all black (alpha channel only)
385	385		$ffffff00 - fully transparent
386	386		```
387	387
388	388		## Forced Repaint
389	389
390	390		There's an additional code added for processing DrawRect event. If a control was resized during a draw rect, then the resulting graphics output could be corrupted. [32970](https://bugs.freepascal.org/view.php?id=32970)
391	391
392	392		As an example TTreeView component could be used. It updates scroll bars during the initial paint. The update of scroll bars is causing a client rectangle to be changed, causing a glitch when drawing the control for the first time
393	393
394	394		Naturally, the next repaint fixes the problem right away.
395	395
396	396		![](/wiki-images/7/7c/CocoaInvalidTree.png) ![](/wiki-images/d/db/CocoaValidTree.png)
397	397
398	398		Sending another event into Cocoa event queue, to repaint the control again would cause flickering and yet bad user experience. Forcefully calling for a repaint one more time seems to be resolving the problem, while potentially is an overhead due to double job done.
399	399
400	400		Also double drawing could cause artifacts on controls that are using any sorts of transparency:
401	401
402	402		![](/wiki-images/e/e7/TransperancyDoubleDraw.png)
403	403
404	404		The best solution is to avoid changing of the control bounds at all during drawing operation.
405	405
406	406		## Theme Drawing
407	407
408	408		HITheme API is deprecated by Apple together with Carbon. It's still available in OS X, but for i386 only. It will presumably be completely removed on 64-bit only macOS.
409	409
410	410		However, some LCL controls cannot be mapped to existing Cocoa provided controls and thus might require some "custom drawing". The drawing should look system native though. In order to achieve that the NSCell family could be used. NSCell allows drawing (hit-test and as well as handle user input) for OS X native elements. If Apple changes the appearance of controls (cells), the LCL application would "pick-up" the look automatically.
411	411
412	412		Deprecated? macOS version specific? In order to be drawn NSCells require the presence of NSView, thus it's hard to use them for the implementation of LCL TTheme APIs. NSView doesn't seem to be required. At least NSCell operates without the presence NSView. However, per Apple's documentation it's mentioned that the drawing would occur in a "focused" control. That helps to use NSCell for on-screen drawing, but is a big question for bitmap drawing.
413	413
414	414		Example of NSCell usage is CocoaStatusBar drawing.
415	415
416	416		It might be that Apple moves away from using NSCell. The class itself is not yet deprecated, even though Apple suggests that NSView should be used more extensively.
417	417
418	418		## See Also
419	419
420	420		- [[Cocoa Internals]]
421	421		- [Introduction to Color Programming Topics for Cocoa](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/DrawColor/DrawColor.html)
422	422
423	423		---
424	424		From the Free Pascal wiki, page "Cocoa Internals/Graphics", as it stood on 2022-05-31 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).
425	425		Category: Cocoa
426	426		Category: macOS

Back to history