Using macOS Alert Panels

│ English (en) │

This article applies to macOS only.

See also: Multiplatform Programming Guide

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). The function NSRunAlertPanel is declared as:

NSInteger NSRunAlertPanel(NSString *title, NSString *msgFormat, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, ...);

The function creates and runs an alert panel (or dialog) with the title of title and buttons with titles of defaultButton, alternateButton, and otherButton. The optional alert message specified by msgFormat should be a static value that can consist of variable values using a format string (list any necessary arguments for this formatted string at the end of the function’s argument list), an unformatted string, or an empty string, but not nil. Note that passing an untrusted string in msgFormat can lead to security issues. The panel is in a modal event loop.

The example code below creates an alert panel with three buttons: Cancel, Abort and OK (Tested working on Mojave and Catalina). Cancel returns 0; Abort returns -1 and OK returns 1. The status is displayed in the TForms's caption property.

unit unit1;

{$modeswitch objectivec1}

interface

uses
  ...
  MacOSAll, CocoaAll, LCLType,
  ...
  ;

type

  { TForm1 }

  TForm1 = class(TForm)
  ...

  private

  public

  end;

var
  Form1: TForm1;

implementation

{$R *.lfm}

{ TForm1 }

...

function ShowAlertPanel(const alertTitle, alertMessage, defButton, altButton, othButton: String) :Integer;
var
  tNSStr, mNSStr, defButNSStr, altButNSStr, othButNSStr: NSString;
begin
  tNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, alertTitle, kCFStringEncodingUTF8));
  mNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, alertMessage, kCFStringEncodingUTF8));
  defButNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, defButton, kCFStringEncodingUTF8));
  altButNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, altButton, kCFStringEncodingUTF8));
  othButNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, othButton, kCFStringEncodingUTF8));
  Result := NSRunAlertPanel(tNSStr, mNSStr, defButNSStr, altButNSStr, othButNSStr);
end;

...

You can replace NSRunAlertPanel() with NSRunInformationalAlertPanel() or NSRunCriticalAlertPanel() which have different visual attributes. In particular, when using NSRunCriticalAlertPanel(), the panel presented to the user is badged with a caution icon. Critical alerts should be used only as specified in the "Alerts" section of the UI Element Guidelines Windows chapter of macOS Human Interface Guidelines.

To call the ShowAlertPanel function from, for example, a menu item:

procedure TForm1.MenuItem1Click(Sender: TObject);
var
  status: Integer;
begin
  status := ShowAlertPanel('Title', 'Message text', 'OK', 'Cancel', 'Abort');
  Caption := 'Status: ' + IntToStr(status);
end;