Apple-specific UI elements

From Lazarus wiki

This article applies to macOS only.

See also: Multiplatform Programming Guide

English (en)

Apple main menu item

In each Mac application there is a main menu item with the name of the application. Lazarus will automatically add the "Services", "Hide" and "Quit" menu items to this menu. In order to add more items to this menu, create a menu item with the apple character as its Caption "" (without quotes, it is Unicode 0xF8FF). You can use ifdefs {$IFDEF DARWIN} to hide it in non-macOS.

For example:

  AppMenu := TMenuItem.Create(Self);  {Application menu}
  AppMenu.Caption := #$EF#$A3#$BF;  {Unicode Apple logo char}
  MainMenu.Items.Insert(0, AppMenu);

  AppAboutCmd := TMenuItem.Create(Self);
  AppAboutCmd.Action:= ActionList1.Actions[1];
  AppMenu.Add(AppAboutCmd);  {Add About as item in application menu}

  AppSep1Cmd := TMenuItem.Create(Self);
  AppSep1Cmd.Caption := '-';

  AppCheckCmd := TMenuItem.Create(Self);
  AppCheckCmd.Action:= ActionList1.Actions[2];
  AppMenu.Add(AppCheckCmd);  {Add Check as item in application menu}

  AppSep2Cmd := TMenuItem.Create(Self);
  AppSep2Cmd.Caption := '-';

Fixing your application name

By default your application's name will be the name of your project. You can rename your project, but you cannot add a space to the project name. So, "My App" will show up in the AppName/Apple Menu as "MyApp". Your application dock icon will also display "MyApp". Fear not, this can be fixed by editing the application Info.plist file and changing the Bundle Name key value from "MyApp" to "My App". For example:

  <string>My App</string>

The two keys to consider when renaming your application:

Key name Description
CFBundleName (Bundle name) The short name for the bundle. The value for this key is usually the name of your application. Xcode sets the value of this key by default when you create a new project.
CFBundleDisplayName (Bundle display name) The localized version of your application name. You typically include a localized value for this key in an InfoPlist.strings file in each of your language-specific resource directories.

How to make Apple main menu multilingual

To translate the Apple main menu from the default English to, for example, German, see the procedure below:

    {$ifdef LCLCocoa}   {$modeswitch objectivec2}   {$endif}
    uses ...
    {$ifdef LCLCocoa}   CocoaAll,  {$endif}
    procedure TranslateApplicationMenu;
    var mnMain: NSMenu;
        mnApp : NSMenu;
        mnItem: NSMenuItem;
        i     : integer;
       mnMain := NSApplication (NSApp).mainmenu;
       mnItem := NSMenuItem (mnMain.itemArray.objectAtIndex(0));

       if (mnItem.hasSubmenu) then 
           mnApp := mnItem.submenu;
           for i:=0 to mnApp.itemArray.count-1 do 
               mnItem := NSMenuItem(mnApp.itemArray.objectAtIndex(i));

               if (NOT mnItem.isSeparatorItem) then 
                   if (mnItem.title.UTF8String = 'Services') then
                     mnItem.setTitle (NSString.stringWithUTF8string('Dienste'));
                   if (mnItem.title.UTF8String = 'Hide Others') then
                     mnItem.setTitle (NSString.stringWithUTF8string('Andere ausblenden'));
                   if (mnItem.title.UTF8String = 'Show All') then
                     mnItem.setTitle (NSString.stringWithUTF8string('Alle einblenden'));
                   if (mnItem.title.UTF8String = 'Hide ' + Application.Title) then
                     mnItem.setTitle (NSString.stringWithUTF8string(PChar(Application.Title + ' ausblenden')));
                   if (mnItem.title.UTF8String = 'Quit ' + Application.Title) then
                     mnItem.setTitle (NSString.stringWithUTF8string(PChar(Application.Title + ' beenden')));

Adding an icon to your app bundle

1. Use /usr/bin/iconutil or a similar program to create your app's icon file (.icns extension).

2. Copy the .icns file to your app bundle's Resources folder. For example, from the command line:

cp -p myapp.icns

3. Add the following key to your app bundle's Info.plist file:


Sometimes Finder doesn't "refresh" an app to use the new icon, continuing instead to show the default icon. You can try these things to force Finder to use the new icon:

  • In a Terminal, use the UNIX command "touch" to touch the app bundle (eg touch - this should work instantly.
  • Log out and back in again.
  • Drag (move) your application to a different folder, then back again.
  • Restart Finder (Esc-Option-Apple keys).

You shouldn't have this problem with Finder when you install your app on other computers. The issue is a result of Finder caching the icon.

Removing the app icon from title bars

The Apple convention is that a window title bar has an icon only when the window represents a file. However, in the LCL the icon typically defines the application itself.

The expected Apple behaviour can be achieved by setting the global variable CocoaIconUse to true and including the CocoaInt unit. See Cocoa Form Icons for the full details.

See also the Apple Human Interface Guidelines document on window anatomy.

Removing the title bar and border from a form

To remove the title bar and border from a form, use the following code in your Form OnCreate method:

procedure TForm1.FormCreate(Sender: TObject);
  BorderIcons := [];
  BorderStyle := bsNone;
  FormStyle := fsStayOnTop;
  ShowInTaskBar := stNever;
  ControlStyle := ControlStyle - [csSetCaption];

Add an Apple help book to your app

No professional macOS application should be without a functioning Apple Help Book. Unfortunately Apple make it harder than it should be for developers to create an Apple Help Book because their documentation is significantly out of date (2013 anyone?) and the Apple Help Viewer has undergone significant change in recent versions of the operating system. For the full details on how to add an Apple Help Book to your application, along with sample code, refer to the article Add an Apple Help Book to your macOS app.

Using preferences in your app

For details on how to use Preferences in your application, refer to the articles: Reading and Writing Preferences and Preferences Menu.

Hiding an app from the Dock

For information on how to hide your application from the Dock, refer to the article Hiding a macOS app from the Dock.

Bouncing an app icon in the Dock

Bouncing your application's icon in the dock can be useful to attract a user's attention when, for example, a long-running task has finished. For how to do this, refer to the Bounce Application Icon in Dock article.

How to use a sheet

A sheet is the Apple recommended way to request user input before proceeding with a document-specific action or to present information to the user before the next step. For information on how to create and use a sheet, see: Using macOS Sheets.

How to use Alert Panels

A panel is a special kind of window, typically serving an auxiliary function in an application. An alert panel is a type of built-in dialog for alerting the user to something and retrieving any choice the user made (eg clicking an OK or Cancel button). For information on how to create and use an alert panel in your application, see the article Using macOS Alert Panels.

How to deliver user notifications

Notifications are a great way for your applications to keep your users informed. They appear in the upper-right corner of the screen and/or in the Notification Center. To use this feature in your application, see the article macOS User Notifications.

Show Badge on Application Icon in Dock

Badges are used to notify a user of something new in an application. The badge is a counter that appears on the application's dock tile (icon) as a white number on a red circular or oval, depending on the number of digits, background. For how to implement this, see the article Show Badge on Application Icon in Dock.

Detecting Light or Dark mode

Dark mode was introduced with macOS Mojave (10.14). Macs using older versions of macOS like High Sierra and Sierra are unfortunately not able to use dark mode but can enable a dark menu bar and dock. Users can enable or disable dark mode via System Preferences. An Auto mode was introduced with macOS Catalina (10.15). This mode switches between light (during the day) and dark (during the night) modes automatically.

For details of how to detect the mode, see Dark mode.

See also

External links