
This article applies to macOS only.
See also: Multiplatform Programming Guide
This article applies to iOS only.
See also: Multiplatform Programming Guide
This page gives an overview of the LCL Carbon interface for Mac OS X and will help new developers.
For installation and creating a first Carbon application refer to Carbon Interface.
Documentation about Carbon
- Free Pascal's Carbon API unit is FPCMacOSAll.pas in /usr/local/share/fpcsrc/packages/extra/univint.
Carbon interface development basics
- Target Mac OS X version is 10.4
- Avoid using obsolete or deprecated APIs and functions (e. g. QuickDraw vs. Quartz 2D)
- Use object approach
- Check Carbon calls result with OSError function
- Assume UTF-8 encoded strings between LCL and Carbon widgetset (for future Lazarus Unicode support)
What is already working ?
- Features - see Roadmap#Status_of_features_on_each_widgetset
- Forms and controls - see Roadmap#Status_of_components_on_each_widgetset
- Creating TOpenGLControl with AGL context (see components/opengl/)
- Mouse events
- Keyboard events

What needs to be done next?
| Item | Note | Dependencies | Responsible |
|---|---|---|---|
| TListView | CreateDataBrowserControl | Tombo |
See Bug Tracker Carbon open issues
Carbon IDE Bugs
| Item | Note | Dependencies | Responsible |
|---|---|---|---|
| Synedit | No caret Vertical scroll range is not exact | ||
| Mouse | Wrong position is reported when mouse over component toolbar Bug 0009921 | ||
| PageControl | No arrows to switch tabs - switch to Group box with pop-up menu if the tabs do not fit in or draw tabs in rows via HIThemeDrawTab | ||
| PageControl | IDE crash when quit appears to be related to PageControl | ||
| ListView | IDE crash in dialogs that use TListView (not yet implemented) | ||
| '...' buttons in dialogs | Now they are too large I think | ||
| OK/Cancel | Many dialogs have non-Mac check-X glyphs | ||
| Menu bar | Too wide for 1024x768 display resolution | ||
| Lazarus menu | Help About and app prefs (Environment options) should be accessible here | ||
| 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! | ||
| Windows menu | Rename to Window menu per Mac GUI standard Currently active window should be checked | ||
| Installed Packages | Package Info box not tall enough, bug 10021 | ||
| Form designer | Selected control doesn't show any visual change | ||
| Open Package File | Filter (*.lpk) is ignored. |
Compatibility issues
Go to Carbon_interface_issues.
How to add a new control
For example TButton.
TButton is defined in lcl/buttons.pp. This is the platform independent part of the LCL, which is used by the normal LCL programmer.
Its widgetset class is in lcl/widgetset/wsbuttons.pp. This is the platform independent base for all widgetsets (carbon, gtk, win32, ...).
Its Carbon interface class is in lcl/interfaces/carbon/carbonwsbuttons.pp:
TCarbonWSButton = class(TWSButton)
private
protected
public
class function CreateHandle(const AWinControl: TWinControl; const AParams: TCreateParams): TLCLIntfHandle; override;
end;
Every WS class that actually implements something must be registered. See the initialization section at the end of the carbonwsXXX.pp unit:
RegisterWSComponent(TCustomButton, TCarbonWSButton);
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.