Apple-specific UI elements

From Lazarus wiki
Revision as of 01:20, 15 December 2019 by Trev (talk | contribs) (→‎Apple-specific UI elements: Content moved from OS X Programming Tips)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search
macOSlogo.png

This article applies to macOS only.

See also: Multiplatform Programming Guide

English (en)

AppName/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:

  {$IFDEF DARWIN}
  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 := '-';
  AppMenu.Add(AppSep1Cmd);

  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 := '-';
  AppMenu.Add(AppSep2Cmd);
  {$ENDIF}

By default your application 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:

  <key>CFBundleName</key>
  <string>My App</string>

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:

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

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

               if (NOT mnItem.isSeparatorItem) then 
                 begin
                   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')));
                 end
             end
         end
    end;

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 myapp.app/Contents/Resources

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

<key>CFBundleIconFile</key>
<string>myapp.icns</string>

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 MyApp.app) - 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.

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.

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 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.