FPC and Carbon

Carbon is a procedural API available on Mac OS X and Classic Mac OS 8.1 or superior. It can be utilized to create full-fledged native Macintosh applications integrated with it's Aqua look. This document offers specific information about how to use this API in Object Pascal software.

Pascal Bindings

The Carbon bindings are located on the unit FPCMacOSAll, which comes with all standard installations of FPC on the Macintosh.

Carbon Tutorial

If you want to create Carbon application without using LCL components, you'll have to Carbon API to achive this goal. This little tutorial shows how to create application using only CarbonAPI functions and XCode Interface Builder to create user interface.

• Create a projects folder and create an empty .pas file there, or you can also start a new project using Lazarus (Project->New Project->Custom Application)
• Save an empty file (or empty project for Lazarus) and leave it for now.

All Mac OS GUI applications must be provided as bundles. Bundle is specially formed set of folders and files, that contain all information necessary to run a application.

• Create an application bundle with the same name as empty .pas file. The script to create a bundle can be found here: http://wiki.lazarus.freepascal.org/XDev_Toolkit

(if you're using Lazarus, you can create it easily Project Options -> Create Application Bundle);

To create a GUI application, will need to use an Interface Builder. The utility is provided with XCode tools and can be found at /Developer/Applications/. It's not necessary to use Interface Builder, to create GUI applications, but IB makes it easier.

• Open Interface Builder

• Select template Carbon -> Application. This will create a template for a carbon application containing main menu and window.

The Interface Builder can be familiar is some way, as it have a 'component palette' known and Library and 'object inspector' known as Inspector (to open inspector press cmd-shift-I or from main menu Tools->Inspector)

• On the created menu add a Static Text object (Label). To add a control simply drag it to the window. Double click on the newly added Static Text to change it caption for example to the 'Hello World';

• Save this application template to the projects folder setting the name to 'main' and file type must be nib (3.x or 2.x version for Leopard, .nib extension would be added automatically)

• Copy newly created main.nib file to the application bundle. yourBundle.app/Contents/Resources/. The Resources folder is the place where any nib file would be searched.

if you're using Finder you can access application folder by 'Show Package Content' if you're using console you can copy by the following command cp main.nib -r ./yourBundle.app/Contents/Resources/main.nib (where yourBundle.app is your application bundle name)

Now, let's return to the empty .pas file (or empty project file), that was perviously created. Set .pas code to the following

uses
  FPCMacOSAll;
       
var
  err     : OSStatus;
  nibRef  : IBNibRef = nil;
  window  : WindowRef = nil;
    
begin
  err := noErr;
   
  try
    // Create a Nib reference passing the name of the nib file (without the .nib extension)
    // CreateNibReference only searches into the application bundle.
    err := CreateNibReference(CFSTR('main'), nibRef);
    if err <> noErr then  Exit; 
             
    // Once the nib reference is created, set the menu bar. "MainMenu" is the name of the menu bar
    // object. This name is set in InterfaceBuilder when the nib is created.
    err := SetMenuBarFromNib(nibRef, CFSTR('MainMenu'));
    if err <> noErr then Exit; 
           
    // Then create a window. "MainWindow" is the name of the window object. This name is set in
    // InterfaceBuilder when the nib is created.
    err := CreateWindowFromNib(nibRef, CFSTR('Window'), window);
    if err <> noErr then Exit; 
       
  finally
    // We don't need the nib reference anymore.
    DisposeNibReference(nibRef);
  end;
    
  // The window was created hidden so show it.
  ShowWindow(window);
    
  // Running main message loop that starts the application.  
  RunApplicationEventLoop;
end.
                           

• Save the file.
• Now you'll need to build it.

command line is the following. remember that you should Free Pascal must know there FPCMacOSAll file is located (you should specify the path to it in /etc/fpc.cfg file)

 fpc yourMainFile.pas -k-framework -kCarbon

if have not created a hardlink to the file, you'll need to create one or copy executable (you'll also have to copy executable every time you rebuild the project);

 cp youMainFile ./youBundle.app/Contents/MacOS/

If you're using Lazarus, you can simply select Run->Build, you can also launch the application.