Carbon interface internals: what changed

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

Old	New		Line
1	1		## Introduction
2	2
3	3		> Warning: With the release of macOS 10.15 Catalina in October 2019, Apple has removed all support for the 32 bit Carbon framework from the operating system in favour of the [[Cocoa Internals\|64 bit Cocoa framework]]. Consequently, the Carbon widgetset is no longer being developed.
4	4
5	5		This page gives an overview of the LCL Carbon interface for macOS and will help new developers.
6	6
7	7		For installation and creating a first Carbon application refer to [[Carbon Interface]].
8	8
9	9		## Documentation about Carbon
10	10
11	11		- [Apple Carbon docs](http://developer.apple.com/documentation/Carbon)
12	12
13	13		- [Apple Mailing List search](http://search.lists.apple.com)
14	14
15	15		- [Carbon Book for download](http://www.mactech.com/macintosh-c/downloads.html)
16	16
17	17		- [Carbon Dev](http://www.carbondev.com/site/)
18	18
19	19		- ["Learning Carbon" sample book chapter](http://www.oreilly.com/catalog/learncarbon)
20	20
21	21		- Free Pascal's Carbon API unit is FPCMacOSAll.pas in /usr/local/share/fpcsrc/packages/extra/univint.
22	22
23	23		## Carbon interface development basics
24	24
25	25		- Target Mac Tiger version is 10.4
26	26		- Avoid using obsolete or deprecated APIs and functions (e. g. QuickDraw vs. Quartz 2D)
27	27		- Use object approach
28	28		- Check Carbon calls result with OSError function
29	29		- Assume UTF-8 encoded strings between LCL and Carbon widgetset (for future Lazarus Unicode support)
30	30
31	31		## What is already working ?
32	32
33	33		- Features - see [[Roadmap\|Roadmap#Status_of_features_on_each_widgetset]]
34	34		- Forms and controls - see [[Roadmap\|Roadmap#Status_of_components_on_each_widgetset]]
35	35		- Creating TOpenGLControl with AGL context (see components/opengl/)
36	36		- Mouse events
37	37		- Keyboard events
38	38
39	39		![](/wiki-images/d/d3/Carbon_interface_show_case.png)
40	40
41	41		## What needs to be done next?
42	42
43	43		See [Bug Tracker Carbon open issues](http://www.freepascal.org/mantis/view_all_set.php?type=3&source_query_id=1017)
44	44
45	45		## Carbon IDE Bugs
46	46
47		-	~~<thead>~~
48		-
49		-	~~</thead>~~
50		-	~~<tbody>~~
51		-
52		-	~~File New should be Cmd+N<br />~~
53		-	~~File Save As should be Shift+Cmd+S<br />~~
54		-	~~File Quit should be Cmd+Q<br />~~
55		-	~~Search Find should be Cmd+F<br />~~
56		-	~~Search Find Next should be Cmd+G<br />~~
57		-	~~Search Find Previous should be Shift+Cmd+G<br />~~
58		-	~~(Goto line and Procedure List need to be reassigned)<br />~~
59		-	~~Option+Cmd+F does not bring up Search Results<br />~~
60		-	~~F11 behaves weird!</td>~~
61		-
62		-	~~</tbody>~~
	47	+	\| Item \| Note \| Dependencies \| Responsible \|
	48	+	\|---\|---\|---\|---\|
	49	+	\| '...' buttons in dialogs \| Now they are too large I think \| \| \|
	50	+	\| OK/Cancel \| Many dialogs have non-Mac check-X glyphs \| \| \|
	51	+	\| \\|Menu bar \| Too wide for 1024x768 display resolution \| \| \|
	52	+	\| \\|Lazarus menu \| Help About and app prefs (Environment options) should be accessible here \| \| \|
	53	+	\| \\|Menus \| Many missing or non-standard menu shortcuts: · File New should be Cmd+N · File Save As should be Shift+Cmd+S · File Quit should be Cmd+Q · Search Find should be Cmd+F · Search Find Next should be Cmd+G · Search Find Previous should be Shift+Cmd+G · (Goto line and Procedure List need to be reassigned) · Option+Cmd+F does not bring up Search Results · F11 behaves weird! \| \\| \| \|
63	54
64	55		See [Bug Tracker Carbon IDE open issues](http://www.freepascal.org/mantis/view_all_set.php?type=3&source_query_id=1018)
65	56
66	57		## Implementation Details
67	58
68	59		### Keyboard
69	60
70	61		- Apple Command key is mapped to ssMeta
71	62		- Apple Control key is mapped to ssCtrl
72	63		- Apple Option key is mapped to its inscription, i.e. ssAlt
73	64		- Virtual key codes mapping is not reliable (depends on keyboard language layout!)
74	65
75	66		### Application
76	67
77	68		- Title: You cannot change it at runtime. You have to set it in Application Bundle.
78	69		- OnDropFiles event is fired when file is dropped on application dock icon or opened via Finder if is associated. You have to enable this event in Application Bundle.
79	70
80	71		### Drawing and measuring text precisely in parts
81	72
82	73		If you want to draw (via TextOut, TextRect) or measure (via TextWidth, TextHeight) text divided into various parts and rely it will be displayed same each time not depending on its division, you have to disable some default typographic features (like kerning, fractional positioning, ...) of Canvas. You can choose one of the following:
83	74
84	75		- CarbonWidgetSet.SetTextFractional(Canvas, False); // from CarbonInt unit
85	76		- TCarbonCustomControl(CustomControl.Handle).TextFractional := False; // from CarbonPrivate unit
86	77		- TCarbonDeviceContext(Canvas.Handle)..TextFractional := False; // from CarbonCanvas unit
87	78
88	79		### Screenshot taking
89	80
90	81		The only possible efficient way of taking a screenshot on macOS is using OpenGL. Apple provides a demonstration function which returns a CGImageRef with the screenshot. This function was converted to Pascal and is available on the glgrab.pas unit on the carbon interface directory. This function requires the Apple-specific parts of the Apple OpenGL headers, and those aren't yet on the FPC Packages, so they were translated and are located on lazarus/lcl/interfaces/carbon/opengl.pas until they are released on a stable Free Pascal.
91	82
92	83		After obtaining a CGImageRef, the next step to implement the RawImage_fromDevice method is obtaining a local copy of it's pixel data. It isn't possible to directly access the bytes of a CGImageRef, so the image needs to be drawn to a CGContextRef which uses a memory area allocated by us as buffer. This method has the great advantage of converting from the internal format of the screenshot bytes to the very convenient ARGB, 32-bits depth, 8-bits per channel format that is default to LCL.
93	84
94	85		### Focusing
95	86
96	87		macOS has two possible ways of focusing: Full keyboard navigation (enabled with Accessibility options), Text field navigation (only controls that are to receive text input should be focused). Full keyboard navigation is the same as any other widgetset.
97	88
98	89		There's no way to say if control is text-input or not. Native OS controls will handle focus themselves. The Carbon Widgetset checks if bound LCLObject is SynEdit and will switch the focus to it.
99	90
100	91		### Canvas Clipping
101	92
102	93		Because Quartz 2D's clipping is decreasing, care must be taken for proper clipping region change. There should be no code, that changes CGContext's clip region directly. Carbon widget API's functions should be used instead.
103	94
104	95		## Compatibility issues
105	96
106	97		These are things that will probably never be solved.
107	98
108	99		### Mouse.CursorPos changing does not generate mouse (move) events
109	100
110	101		### Release mouse capture is not supported
111	102
112	103		### Command line parameters
113	104
114	105		Because Carbon applications are executed via Application Bundle, command line parameters are not passed. You have to use OnDropFiles event to detect openning associated files.
115	106
116	107		### Shortcuts indication is not supported
117	108
118	109		### Drawing on Canvas outside OnPaint event is not supported
119	110
120	111		### Drawing on screen device context is not supported
121	112
122	113		### TCustomControl.Color of clBtnFace makes its background transparent
123	114
124	115		### TWinControl.Font fsStrikeOut is not supported
125	116
126	117		### TForm
127	118
128	119		- Icon is not supported
129	120		- ShowInTaskbar is not supported
130	121		- TForm.top=0 is not good. Use TForm.top=23
131	122
132	123		### TEdit.PasswordChar different then default is not supported
133	124
134	125		### TMemo.WordWrap when is disabled, does not allow to scroll text horizontally
135	126
136	127		### TListBox.Columns is not supported
137	128
138	129		### TComboBox
139	130
140	131		- DroppedDown does not show drop down list when style is csDropDownList
141	132		- DropDownCount is not supported
142	133		- Style: csSimple, csOwnerDrawFixed and csOwnerDrawVariable are not supported
143	134
144	135		### TPanel.Bevelxxx: bvLowered and bvSpace are not supported
145	136
146	137		### TBitBtn.Spacing is not supported
147	138
148	139		### TTrackBar
149	140
150	141		- LineSize is not supported
151	142		- ScalePos is not supported
152	143		- TickMarks are not supported
153	144
154	145		### TProgressBar
155	146
156	147		- BarShowText is not supported
157	148		- Smooth is not supported
158	149		- Step is not supported
159	150
160	151		### TColorDialog.Title is not supported
161	152
162	153		### macOS System (Windows' and Controls') Handles
163	154
164	155		It’s some times necessary to access system windows or control handles directly. For example, you wish to use some system features that are not available (not yet implemented?) for LCL. It’s very common for LCL Windows developers (and Delphi developers) to use TControl.Handle property, since Handle is a system window handle for Win32 widgetset. It can be used with any system function. But it’s not so for Carbon widgetset. TControl.Handle would return handle native to widgetset not macOS. TControl.Handle would return TCarbonWidget class (declared at CarbonDef unit). This’s a wrapper class, and you can use it to get system handle.
165	156
166	157		``` pascal
167	158		var
168	159		AHiView: HiViewRef;
169	160		begin
170	161		...
171	162		//this is incorrect way of getting system handle for Carbon widgetset
172	163		//AHiView:= HiViewRef(Button1.Handle)
173	164
174	165		//this is correct way
175	166		AHiView := TCarbonWidget(Button1.Handle).Widget;
176	167		...
177	168		end;
178	169		```
179	170
180	171		You should also note, that there’s difference in getting WindowRef in LCL versions. If you’re using Lazarus 0.9.26 or earlier you should get WindowRef in the following way:
181	172
182	173		``` pascal
183	174		var
184	175		MacWin: WindowRef;
185	176		begin
186	177		...
187	178		MacWin := TCarbonWidget(Form1.Handle).Widget;
188	179		...
189	180		end;
190	181		```
191	182
192	183		If you’re using svn LCL version (latest trunk), then you should use the following way:
193	184
194	185		``` pascal
195	186		uses
196	187		..CarbonPrivate..
197	188		var
198	189		MacWin: WindowRef;
199	190		begin
200	191		...
201	192		MacWin := TCarbonWindow(Form1.Handle).Window;
202	193		...
203	194		end;
204	195		```
205	196
206	197		Keep in mind, that LCL is designed to be cross-platform library, and accessing system handles to use with system functions makes you program hardly portable. The way of getting system objects handle might also be changed in future.
207	198
208	199		### TTrayIcon
209	200
210	201		#### Checking if the TTrayIcon menu is visible
211	202
212	203		Unfortunately Apple only added a facility to check menu visibility in Snow Leopard 10.6. To overcome this limitation in a simple way in previous versions one can use the following code, which should work in previous versions using a class method in TCarbonWSCustomTrayIcon:
213	204
214	205		``` pascal
215	206		uses
216	207		CarbonWSExtCtrls;
217	208
218	209		...
219	210
220	211		begin
221	212		if TCarbonWSCustomTrayIcon.IsTrayIconMenuVisible(TrayIcon1) then Caption := 'Visible'
222	213		else Caption := 'Not visible';
223	214		end;
224	215		```
225	216
226	217		## How to add a new control
227	218
228	219		For example TButton.
229	220
230	221		TButton is defined in lcl/buttons.pp. This is the platform independent part of the LCL, which is used by the normal LCL programmer.
231	222
232	223		Its widgetset class is in lcl/widgetset/wsbuttons.pp. This is the platform independent base for all widgetsets (carbon, gtk, win32, ...).
233	224
234	225		Its Carbon interface class is in lcl/interfaces/carbon/carbonwsbuttons.pp:
235	226
236	227		``` pascal
237	228		TCarbonWSButton = class(TWSButton)
238	229		private
239	230		protected
240	231		public
241	232		class function CreateHandle(const AWinControl: TWinControl; const AParams: TCreateParams): TLCLIntfHandle; override;
242	233		end;
243	234		```
244	235
245	236		Every WS class that actually implements something must be registered. See the initialization section at the end of the carbonwsXXX.pp unit:
246	237
247	238		``` pascal
248	239		RegisterWSComponent(TCustomButton, TCarbonWSButton);
249	240		```
250	241
251	242		TCarbonWSButton overrides CreateHandle to create a Carbon button helper class called TCarbonButton in carbonprivate.pp, which really creates the button control in the Carbon and installs event handlers.
252	243
253	244		---
254	245		From the Free Pascal wiki, page "Carbon interface internals", as it stood on 2021-08-04 after a change by Trev, 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).

Back to history