Sign in Join
Wiki copytemporary

Carbon interface internals: what changed

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

OldNewLine
11## Introduction
22
33> **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.
44
55This page gives an overview of the LCL Carbon interface for macOS and will help new developers.
66
77For installation and creating a first Carbon application refer to [[Carbon Interface]].
88
99## Documentation about Carbon
1010
1111- [Apple Carbon docs](http://developer.apple.com/documentation/Carbon)
1212
1313- [Apple Mailing List search](http://search.lists.apple.com)
1414
1515- [Carbon Book for download](http://www.mactech.com/macintosh-c/downloads.html)
1616
1717- [Carbon Dev](http://www.carbondev.com/site/)
1818
1919- ["Learning Carbon" sample book chapter](http://www.oreilly.com/catalog/learncarbon)
2020
2121- Free Pascal's Carbon API unit is FPCMacOSAll.pas in /usr/local/share/fpcsrc/packages/extra/univint.
2222
2323## Carbon interface development basics
2424
2525- Target Mac Tiger version is 10.4
2626- Avoid using obsolete or deprecated APIs and functions (e. g. QuickDraw vs. *Quartz 2D*)
2727- Use object approach
2828- Check Carbon calls result with OSError function
2929- Assume UTF-8 encoded strings between LCL and Carbon widgetset (for future Lazarus Unicode support)
3030
3131## What is already working ?
3232
3333- Features - see [[Roadmap|Roadmap#Status_of_features_on_each_widgetset]]
3434- Forms and controls - see [[Roadmap|Roadmap#Status_of_components_on_each_widgetset]]
3535- Creating TOpenGLControl with AGL context (see components/opengl/)
3636- Mouse events
3737- Keyboard events
3838
39-<figure>
4039<img src="Carbon_interface_show_case.png" title="Working components in the Carbon interface" width="640" />
41-<figcaption>Working components in the Carbon interface</figcaption>
42-</figure>
4340
4441## What needs to be done next?
4542
4643See [Bug Tracker Carbon open issues](http://www.freepascal.org/mantis/view_all_set.php?type=3&source_query_id=1017)
4744
4845## Carbon IDE Bugs
4946
50-<table>
5147<thead>
52-<tr>
53-<th>Item</th>
54-<th>Note</th>
55-<th>Dependencies</th>
56-<th>Responsible</th>
57-</tr>
48+
5849</thead>
5950<tbody>
60-<tr>
61-<td>'...' buttons in dialogs</td>
62-<td>Now they are too large I think</td>
63-<td></td>
64-<td></td>
65-</tr>
66-<tr>
67-<td>OK/Cancel</td>
68-<td>Many dialogs have non-Mac check-X glyphs</td>
69-<td></td>
70-<td></td>
71-</tr>
72-<tr>
73-<td>|Menu bar</td>
74-<td>Too wide for 1024x768 display resolution</td>
75-<td></td>
76-<td></td>
77-</tr>
78-<tr>
79-<td>|Lazarus menu</td>
80-<td>Help About and app prefs (Environment options) should be accessible here</td>
81-<td></td>
82-<td></td>
83-</tr>
84-<tr>
85-<td>|Menus</td>
86-<td>Many missing or non-standard menu shortcuts:<br />
51+
8752File New should be Cmd+N<br />
8853File Save As should be Shift+Cmd+S<br />
8954File Quit should be Cmd+Q<br />
9055Search Find should be Cmd+F<br />
9156Search Find Next should be Cmd+G<br />
9257Search Find Previous should be Shift+Cmd+G<br />
9358(Goto line and Procedure List need to be reassigned)<br />
9459Option+Cmd+F does not bring up Search Results<br />
9560F11 behaves weird!</td>
96-<td>|</td>
97-<td></td>
98-</tr>
61+
9962</tbody>
100-</table>
10163
10264See [Bug Tracker Carbon IDE open issues](http://www.freepascal.org/mantis/view_all_set.php?type=3&source_query_id=1018)
10365
10466## Implementation Details
10567
10668### Keyboard
10769
10870- Apple Command key is mapped to ssMeta
10971- Apple Control key is mapped to ssCtrl
11072- Apple Option key is mapped to its inscription, i.e. ssAlt
11173- Virtual key codes mapping is not reliable (depends on keyboard language layout!)
11274
11375### Application
11476
11577- Title: You cannot change it at runtime. You have to set it in Application Bundle.
11678- 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.
11779
11880### Drawing and measuring text precisely in parts
11981
12082If 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:
12183
12284- CarbonWidgetSet.SetTextFractional(Canvas, False); // from CarbonInt unit
12385- TCarbonCustomControl(CustomControl.Handle).TextFractional := False; // from CarbonPrivate unit
12486- TCarbonDeviceContext(Canvas.Handle)..TextFractional := False; // from CarbonCanvas unit
12587
12688### Screenshot taking
12789
12890The 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.
12991
13092After 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.
13193
13294### Focusing
13395
13496macOS 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.
13597
13698There'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.
13799
138100### Canvas Clipping
139101
140102Because 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.
141103
142104## Compatibility issues
143105
144106These are things that will probably never be solved.
145107
146108### Mouse.CursorPos changing does not generate mouse (move) events
147109
148110### Release mouse capture is not supported
149111
150112### Command line parameters
151113
152114Because Carbon applications are executed via Application Bundle, command line parameters are not passed. You have to use OnDropFiles event to detect openning associated files.
153115
154116### Shortcuts indication is not supported
155117
156118### Drawing on Canvas outside OnPaint event is not supported
157119
158120### Drawing on screen device context is not supported
159121
160122### TCustomControl.Color of clBtnFace makes its background transparent
161123
162124### TWinControl.Font fsStrikeOut is not supported
163125
164126### TForm
165127
166128- Icon is not supported
167129- ShowInTaskbar is not supported
168130- TForm.top=0 is not good. Use TForm.top=23
169131
170132### TEdit.PasswordChar different then default is not supported
171133
172134### TMemo.WordWrap when is disabled, does not allow to scroll text horizontally
173135
174136### TListBox.Columns is not supported
175137
176138### TComboBox
177139
178140- DroppedDown does not show drop down list when style is csDropDownList
179141- DropDownCount is not supported
180142- Style: csSimple, csOwnerDrawFixed and csOwnerDrawVariable are not supported
181143
182144### TPanel.Bevelxxx: bvLowered and bvSpace are not supported
183145
184146### TBitBtn.Spacing is not supported
185147
186148### TTrackBar
187149
188150- LineSize is not supported
189151- ScalePos is not supported
190152- TickMarks are not supported
191153
192154### TProgressBar
193155
194156- BarShowText is not supported
195157- Smooth is not supported
196158- Step is not supported
197159
198160### TColorDialog.Title is not supported
199161
200162### macOS System (Windows' and Controls') Handles
201163
202164It’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.
203165
204166``` pascal
205167var
206168 AHiView: HiViewRef;
207169begin
208170...
209171//this is incorrect way of getting system handle for Carbon widgetset
210172//AHiView:= HiViewRef(Button1.Handle)
211173
212174//this is correct way
213175AHiView := TCarbonWidget(Button1.Handle).Widget;
214176...
215177end;
216178```
217179
218180You 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:
219181
220182``` pascal
221183var
222184 MacWin: WindowRef;
223185begin
224186...
225187MacWin := TCarbonWidget(Form1.Handle).Widget;
226188...
227189end;
228190```
229191
230192If you’re using svn LCL version (latest trunk), then you should use the following way:
231193
232194``` pascal
233195uses
234196 ..CarbonPrivate..
235197var
236198 MacWin: WindowRef;
237199begin
238200...
239201MacWin := TCarbonWindow(Form1.Handle).Window;
240202...
241203end;
242204```
243205
244206Keep 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.
245207
246208### TTrayIcon
247209
248210#### Checking if the TTrayIcon menu is visible
249211
250212Unfortunately 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:
251213
252214``` pascal
253215uses
254216 CarbonWSExtCtrls;
255217
256218...
257219
258220begin
259221 if TCarbonWSCustomTrayIcon.IsTrayIconMenuVisible(TrayIcon1) then Caption := 'Visible'
260222 else Caption := 'Not visible';
261223end;
262224```
263225
264226## How to add a new control
265227
266228For example TButton.
267229
268230TButton is defined in lcl/buttons.pp. This is the platform independent part of the LCL, which is used by the normal LCL programmer.
269231
270232Its widgetset class is in lcl/widgetset/wsbuttons.pp. This is the platform independent base for all widgetsets (carbon, gtk, win32, ...).
271233
272234Its Carbon interface class is in lcl/interfaces/carbon/carbonwsbuttons.pp:
273235
274236``` pascal
275237TCarbonWSButton = class(TWSButton)
276238private
277239protected
278240public
279241 class function CreateHandle(const AWinControl: TWinControl; const AParams: TCreateParams): TLCLIntfHandle; override;
280242end;
281243```
282244
283245Every WS class that actually implements something must be registered. See the initialization section at the end of the carbonwsXXX.pp unit:
284246
285247``` pascal
286248RegisterWSComponent(TCustomButton, TCarbonWSButton);
287249```
288250
289251TCarbonWSButton 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.
290252
291253---
292254*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