Sign in Join
Wiki copytemporary

Using macOS Alert Panels: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Using macOS Alert Panels

OldNewLine
1+*(macOS only)*
2+
3+## Overview
4+
5+> **Note:** The NSRunAlertPanel functions first appeared in Mac OS X 10.0 (Cheetah) and were deprecated in OS X 10.11 (El Capitan). They have been superseded by the [[macOS NSAlert|NSAlert]] class available from Mac OS X 10.3 (Panther) which can display modal dialogs or sheets.
6+
7+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:
8+
9+\<syntaxhighlight lang="pascal\>NSInteger NSRunAlertPanel(NSString *title, NSString *msgFormat, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, ...);
10+
11+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.
12+
13+## Example code
14+
15+The example code below creates an alert panel with three buttons: Cancel, Abort and OK (Tested working on Mojave, Catalina and Big Sur). Cancel returns 0; Abort returns -1 and OK returns 1. The status is displayed in the TForms's caption property.
16+
17+``` pascal
18+unit unit1;
19+
20+{$modeswitch objectivec1}
21+
22+interface
23+
24+uses
25+ ...
26+ MacOSAll, CocoaAll, LCLType,
27+ ...
28+ ;
29+
30+type
31+
32+ { TForm1 }
33+
34+ TForm1 = class(TForm)
35+ ...
36+
37+ private
38+
39+ public
40+
41+ end;
42+
43+var
44+ Form1: TForm1;
45+
46+implementation
47+
48+{$R *.lfm}
49+
50+{ TForm1 }
51+
52+...
53+
54+function ShowAlertPanel(const alertTitle, alertMessage, defButton, altButton, othButton: String) :Integer;
55+var
56+ tNSStr, mNSStr, defButNSStr, altButNSStr, othButNSStr: NSString;
57+begin
58+ tNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, alertTitle, kCFStringEncodingUTF8));
59+ mNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, alertMessage, kCFStringEncodingUTF8));
60+ defButNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, defButton, kCFStringEncodingUTF8));
61+ altButNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, altButton, kCFStringEncodingUTF8));
62+ othButNSStr := NSString(CFStringCreateWithPascalString(kCFAllocatorDefault, othButton, kCFStringEncodingUTF8));
63+ Result := NSRunAlertPanel(tNSStr, mNSStr, defButNSStr, altButNSStr, othButNSStr);
64+end;
65+
66+...
67+```
68+
69+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](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html).
70+
71+To call the **ShowAlertPanel** function from, for example, a menu item:
72+
73+``` pascal
74+procedure TForm1.MenuItem1Click(Sender: TObject);
75+var
76+ status: Integer;
77+begin
78+ status := ShowAlertPanel('Title', 'Message text', 'OK', 'Cancel', 'Abort');
79+ Caption := 'Status: ' + IntToStr(status);
80+end;
81+```
82+
83+## See also
84+
85+- [[macOS NSAlert]]
86+
87+## External links
88+
89+- [Apple: NSRunAlertPane](https://developer.apple.com/documentation/appkit/1540934-nsrunalertpanel).
90+
91+---
92+*From the Free Pascal wiki, page "Using macOS Alert Panels", as it stood on 2021-05-08 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
93+Category: Code Snippets
94+Category: Platform-sensitive development
95+Category: macOS

Back to history