Using macOS Sheets

This article applies to macOS only.

See also: Multiplatform Programming Guide

A sheet is a modal dialog that’s attached to a particular window—usually a document—and prevents further interaction with the window until the sheet is dismissed. It is the Apple recommended way to request user input before proceeding with a document-specific action, such as attaching files, exporting, saving, and printing. Sheets are also used to present information to the user before the next step, for example, a licensing agreement that requires acceptance.

According to Apple's Human Interface Guidelines, you should only use a sheet when a window has a frame. Sheets should always emerge from a window’s frame above the body area. Here is an example:

The code below creates the sheet as shown in the above example.

unit unit1;

{$modeswitch objectivec1}

interface

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

type

  { TForm1 }

  TForm1 = class(TForm)
  ...

  private

  public

  end;

var
  Form1: TForm1;

implementation

{$R *.lfm}

{ TForm1 }

...

procedure ShowAlertSheet(FormHandle: HWND; const TitleStr, MessageStr: string);
var
  tNSStr, mNSStr, okNSStr, fNSStr: NSString;
  theWindow : CocoaAll.NSWindow;
  theID : id;
begin
  theID := NSView(FormHandle).window;
  theWindow := NSView(FormHandle).window;

  tNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, TitleStr, kCFStringEncodingUTF8));  // title
  mNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, MessageStr, kCFStringEncodingUTF8));// message
  okNSStr:= NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, 'OK', kCFStringEncodingUTF8));      // button caption
  fNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, '%@', kCFStringEncodingUTF8));      // format

  NSBeginAlertSheet(tNSStr,okNSStr,nil,nil,theWindow,theID,nil,nil,nil,fNSStr, mNSStr);
end;

...

end.

To call the ShowAlertSheet procedure from, for example, a menu item:

procedure TForm1.MenuItem1Click(Sender: TObject);
begin
  ShowAlertSheet(Form1.Handle, 'Test', 'Message text');
end;