objc2_app_kit/generated/NSAlert.rs
1//! This file has been automatically generated by `objc2`'s `header-translator`.
2//! DO NOT EDIT
3use core::ffi::*;
4use core::ptr::NonNull;
5use objc2::__framework_prelude::*;
6use objc2_foundation::*;
7
8use crate::*;
9
10/// The alert styles used by the `alertStyle` property on instances of `NSAlert`.
11///
12/// See also [Apple's documentation](https://developer.apple.com/documentation/appkit/nsalertstyle?language=objc)
13// NS_ENUM
14#[repr(transparent)]
15#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
16pub struct NSAlertStyle(pub NSUInteger);
17impl NSAlertStyle {
18 /// An alert style to be used to warn the user about a current or impending event.
19 /// This style should be used when the alert’s content is more severe than `NSAlertStyleInformational` but less than `NSAlertStyleCritical`.
20 /// This is the default alert style.
21 #[doc(alias = "NSAlertStyleWarning")]
22 pub const Warning: Self = Self(0);
23 /// An alert style to be used to inform the user about a current or impending event.
24 /// - Note: Currently, there is no visual difference between informational and warning alerts.
25 #[doc(alias = "NSAlertStyleInformational")]
26 pub const Informational: Self = Self(1);
27 /// An alert style to be used to inform the user about a critical event.
28 /// Causes the alert’s icon to be badged with a caution icon.
29 /// The critical (or “caution”) style should be used sparingly. Using it too frequently diminishes its significance. Use the symbol only when extra attention is really needed, as when confirming an action that might result in unexpected loss of data. Don’t use the symbol for tasks whose only purpose is to overwrite or remove data, such as a save or empty trash.
30 #[doc(alias = "NSAlertStyleCritical")]
31 pub const Critical: Self = Self(2);
32}
33
34unsafe impl Encode for NSAlertStyle {
35 const ENCODING: Encoding = NSUInteger::ENCODING;
36}
37
38unsafe impl RefEncode for NSAlertStyle {
39 const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
40}
41
42/// [Apple's documentation](https://developer.apple.com/documentation/appkit/nsalertfirstbuttonreturn?language=objc)
43#[cfg(feature = "NSApplication")]
44pub static NSAlertFirstButtonReturn: NSModalResponse = 1000;
45
46/// [Apple's documentation](https://developer.apple.com/documentation/appkit/nsalertsecondbuttonreturn?language=objc)
47#[cfg(feature = "NSApplication")]
48pub static NSAlertSecondButtonReturn: NSModalResponse = 1001;
49
50/// [Apple's documentation](https://developer.apple.com/documentation/appkit/nsalertthirdbuttonreturn?language=objc)
51#[cfg(feature = "NSApplication")]
52pub static NSAlertThirdButtonReturn: NSModalResponse = 1002;
53
54extern_class!(
55 /// A modal dialog or sheet attached to a document window.
56 /// The `NSAlert` class is not designed for subclassing.
57 ///
58 /// See also [Apple's documentation](https://developer.apple.com/documentation/appkit/nsalert?language=objc)
59 #[unsafe(super(NSObject))]
60 #[thread_kind = MainThreadOnly]
61 #[derive(Debug, PartialEq, Eq, Hash)]
62 pub struct NSAlert;
63);
64
65extern_conformance!(
66 unsafe impl NSObjectProtocol for NSAlert {}
67);
68
69impl NSAlert {
70 extern_methods!(
71 /// Returns an alert initialized from information in an error object.
72 /// - Parameter error: Error information to display.
73 /// - Returns: An initialized alert.
74 /// - Note: The `NSAlert` class extracts the localized error description, recovery suggestion, and recovery options from the error parameter and uses them as the alert’s message text, informative text, and button titles, respectively.
75 #[unsafe(method(alertWithError:))]
76 #[unsafe(method_family = none)]
77 pub unsafe fn alertWithError(error: &NSError, mtm: MainThreadMarker) -> Retained<NSAlert>;
78
79 /// The text that is displayed prominently in the alert.
80 /// - Note: Use this string to get the user’s attention and communicate the reason for displaying the alert.
81 #[unsafe(method(messageText))]
82 #[unsafe(method_family = none)]
83 pub unsafe fn messageText(&self) -> Retained<NSString>;
84
85 /// Setter for [`messageText`][Self::messageText].
86 #[unsafe(method(setMessageText:))]
87 #[unsafe(method_family = none)]
88 pub unsafe fn setMessageText(&self, message_text: &NSString);
89
90 /// The descriptive text that provides more details about the reason for the alert.
91 /// - Note: The informative text string is displayed below the message text and is less prominent. Use this string to provide additional context about the reason for the alert or about the actions that the user might take.
92 #[unsafe(method(informativeText))]
93 #[unsafe(method_family = none)]
94 pub unsafe fn informativeText(&self) -> Retained<NSString>;
95
96 /// Setter for [`informativeText`][Self::informativeText].
97 #[unsafe(method(setInformativeText:))]
98 #[unsafe(method_family = none)]
99 pub unsafe fn setInformativeText(&self, informative_text: &NSString);
100
101 #[cfg(feature = "NSImage")]
102 /// The custom icon displayed in the alert.
103 /// By default, the image used in an alert is the app icon (`NSApplicationIcon`). If this property’s value is set, the specified custom image is used in place of the app icon.
104 /// If a custom alert icon had been set, it can be cleared by setting this property’s value to `nil`, which restores use of the app icon for the alert.
105 #[unsafe(method(icon))]
106 #[unsafe(method_family = none)]
107 pub unsafe fn icon(&self) -> Option<Retained<NSImage>>;
108
109 #[cfg(feature = "NSImage")]
110 /// Setter for [`icon`][Self::icon].
111 #[unsafe(method(setIcon:))]
112 #[unsafe(method_family = none)]
113 pub unsafe fn setIcon(&self, icon: Option<&NSImage>);
114
115 #[cfg(all(
116 feature = "NSButton",
117 feature = "NSControl",
118 feature = "NSResponder",
119 feature = "NSView"
120 ))]
121 /// Adds a button with a given title to the alert.
122 ///
123 /// Buttons should be added from most-to-least prominent. The exact visual arrangement of the buttons is determined by `NSAlert` internally. In general, they are arranged from trailing-to-leading edge when laid out horizontally, and top-to-bottom when laid out vertically, with some exceptions for buttons like “Cancel”.
124 ///
125 /// The first three buttons are identified by the order in which they are added (not the order in which they may appear visually) as `NSAlertFirstButtonReturn`, `NSAlertSecondButtonReturn`, `NSAlertThirdButtonReturn` in the return-code parameter. Subsequent buttons are identified as `NSAlertThirdButtonReturn` + *n*, where *n* is an integer.
126 ///
127 /// By default, the first button has a key equivalent of Return, any button with a title of “Cancel” has a key equivalent of Escape, and any button with the title “Don’t Save” has a key equivalent of Command-D (but only if it’s not the first button). You can also assign different key equivalents for the buttons using the `keyEquivalent` method of the `NSButton` class. In addition, you can use the `tag` property of the `NSButton` class to set the alert presentation’s return-code. The framework reserves the use of the button’s `target` and `action`.
128 ///
129 /// - Parameter title: Title of the button to add to the alert.
130 /// - Returns: The button that was added to the alert.
131 #[unsafe(method(addButtonWithTitle:))]
132 #[unsafe(method_family = none)]
133 pub unsafe fn addButtonWithTitle(&self, title: &NSString) -> Retained<NSButton>;
134
135 #[cfg(all(
136 feature = "NSButton",
137 feature = "NSControl",
138 feature = "NSResponder",
139 feature = "NSView"
140 ))]
141 /// The array of response buttons for the alert.
142 /// The buttons are in the order in which they were added, and do not necessarily reflect the order they are arranged visually. The array does not include the default “OK” button that is shown in an alert presented without any buttons added with `-addButtonWithTitle:`.
143 #[unsafe(method(buttons))]
144 #[unsafe(method_family = none)]
145 pub unsafe fn buttons(&self) -> Retained<NSArray<NSButton>>;
146
147 /// Indicates the alert’s severity level. See the `NSAlertStyle` enumeration for the list of alert style constants.
148 #[unsafe(method(alertStyle))]
149 #[unsafe(method_family = none)]
150 pub unsafe fn alertStyle(&self) -> NSAlertStyle;
151
152 /// Setter for [`alertStyle`][Self::alertStyle].
153 #[unsafe(method(setAlertStyle:))]
154 #[unsafe(method_family = none)]
155 pub unsafe fn setAlertStyle(&self, alert_style: NSAlertStyle);
156
157 /// Specifies whether the alert has a help button.
158 ///
159 /// Set this property’s value to `YES` to specify that the alert has a help button, or `NO` to specify it does not.
160 ///
161 /// When a user clicks an alert’s help button, the alert delegate (`delegate`) receives an `alertShowHelp:` message. The delegate is responsible for displaying the help information related to this particular alert.
162 ///
163 /// Clicking an alert’s help button can alternately cause the `-openHelpAnchor:inBook:` message to be sent to the app’s help manager with a `nil` book and the anchor specified by the `helpAnchor` property, if any of the following conditions are true:
164 /// - There is no alert delegate.
165 /// - The alert delegate does not implement `-alertShowHelp:`.
166 /// - The alert delegate implements `-alertShowHelp:` but returns `NO`. When this is the case, an exception is raised if no help anchor is set.
167 #[unsafe(method(showsHelp))]
168 #[unsafe(method_family = none)]
169 pub unsafe fn showsHelp(&self) -> bool;
170
171 /// Setter for [`showsHelp`][Self::showsHelp].
172 #[unsafe(method(setShowsHelp:))]
173 #[unsafe(method_family = none)]
174 pub unsafe fn setShowsHelp(&self, shows_help: bool);
175
176 #[cfg(feature = "NSHelpManager")]
177 /// The alert’s HTML help anchor used when the user clicks the alert’s help button
178 #[unsafe(method(helpAnchor))]
179 #[unsafe(method_family = none)]
180 pub unsafe fn helpAnchor(&self) -> Option<Retained<NSHelpAnchorName>>;
181
182 #[cfg(feature = "NSHelpManager")]
183 /// Setter for [`helpAnchor`][Self::helpAnchor].
184 #[unsafe(method(setHelpAnchor:))]
185 #[unsafe(method_family = none)]
186 pub unsafe fn setHelpAnchor(&self, help_anchor: Option<&NSHelpAnchorName>);
187
188 /// The delegate of the receiver, currently only allows for custom help behavior of the alert.
189 /// For apps linked against 10.12, this property has zeroing weak memory semantics. When linked against an older SDK this back to having `retain` semantics, matching legacy behavior.
190 #[unsafe(method(delegate))]
191 #[unsafe(method_family = none)]
192 pub unsafe fn delegate(&self) -> Option<Retained<ProtocolObject<dyn NSAlertDelegate>>>;
193
194 /// This is a [weak property][objc2::topics::weak_property].
195 /// Setter for [`delegate`][Self::delegate].
196 #[unsafe(method(setDelegate:))]
197 #[unsafe(method_family = none)]
198 pub unsafe fn setDelegate(&self, delegate: Option<&ProtocolObject<dyn NSAlertDelegate>>);
199
200 #[cfg(all(feature = "NSResponder", feature = "NSView"))]
201 /// The accessory view displayed in the alert, placed between the informative text or suppression checkbox (if present) and the response buttons. Before changing the location of the accessory view, first call the `-layout` method.
202 #[unsafe(method(accessoryView))]
203 #[unsafe(method_family = none)]
204 pub unsafe fn accessoryView(&self) -> Option<Retained<NSView>>;
205
206 #[cfg(all(feature = "NSResponder", feature = "NSView"))]
207 /// Setter for [`accessoryView`][Self::accessoryView].
208 #[unsafe(method(setAccessoryView:))]
209 #[unsafe(method_family = none)]
210 pub unsafe fn setAccessoryView(&self, accessory_view: Option<&NSView>);
211
212 /// Specifies that the alert must do immediate layout instead of lazily just before display.
213 /// Used to indicate that the alert panel should do immediate layout, overriding the default behavior of laying out lazily just before showing panel. Only call this method if wanting to do custom layout after it returns. Call this method only after the alert’s other customization, including setting message and informative text, and adding buttons and an accessory view if needed. Layout changes can be made after this method returns, in particular to adjust the frame of an accessory view. Note that the standard layout of the alert may change in the future, so layout customization should be done with caution.
214 #[unsafe(method(layout))]
215 #[unsafe(method_family = none)]
216 pub unsafe fn layout(&self);
217
218 #[cfg(feature = "NSApplication")]
219 /// Runs the alert as an app-modal dialog and returns the constant that identifies the button clicked.
220 #[unsafe(method(runModal))]
221 #[unsafe(method_family = none)]
222 pub unsafe fn runModal(&self) -> NSModalResponse;
223
224 /// Specifies whether the alert includes a suppression checkbox, which can be employed to allow a user to opt out of seeing the alert again.
225 /// The default value of this property is `NO`, which specifies the absence of a suppression checkbox in the alert. Set the value to `YES` to show a suppression checkbox in the alert.
226 /// By default, a suppression checkbox has the title, “Do not show this message again.” In macOS 11.0 and later, if the alert displays multiple buttons that prompt the user to make a choice, the title is “Do not ask again.” To customize it, use the checkbox’s title property, as follows:
227 ///
228 /// myAlert.suppressionButton.title =
229 /// "
230 /// Do not show this warning again";
231 ///
232 /// To create an alert that responds to the selection state of the suppression checkbox, check `myAlert.suppressionButton.state`.
233 #[unsafe(method(showsSuppressionButton))]
234 #[unsafe(method_family = none)]
235 pub unsafe fn showsSuppressionButton(&self) -> bool;
236
237 /// Setter for [`showsSuppressionButton`][Self::showsSuppressionButton].
238 #[unsafe(method(setShowsSuppressionButton:))]
239 #[unsafe(method_family = none)]
240 pub unsafe fn setShowsSuppressionButton(&self, shows_suppression_button: bool);
241
242 #[cfg(all(
243 feature = "NSButton",
244 feature = "NSControl",
245 feature = "NSResponder",
246 feature = "NSView"
247 ))]
248 /// The alert’s suppression checkbox. The checkbox may be customized, including the title and the initial state. Additionally, use this method to get the state of the button after the alert is dismissed, which may be stored in user defaults and checked before showing the alert again. In order to show the suppression button in the alert panel, you must set `showsSuppressionButton` to `YES`.
249 #[unsafe(method(suppressionButton))]
250 #[unsafe(method_family = none)]
251 pub unsafe fn suppressionButton(&self) -> Option<Retained<NSButton>>;
252
253 #[cfg(all(
254 feature = "NSApplication",
255 feature = "NSResponder",
256 feature = "NSWindow",
257 feature = "block2"
258 ))]
259 /// Runs the alert modally as a sheet attached to the specified window.
260 /// - Parameters:
261 /// - sheetWindow: The window on which to display the sheet.
262 /// - handler: The completion handler that gets called when the sheet’s modal session ends.
263 ///
264 /// This method uses the `NSWindow` sheet methods to display the alert. If the alert has an alert style of `NSCriticalAlertStyle`, it is presented as a critical sheet, which means that it can display on top of other sheets that might already be attached to the window. Otherwise, it is presented--or queued for presentation--as a standard sheet.
265 /// Note that `-orderOut:` no longer needs to be called in the completion handler. If the alert isn’t don’t dismiss the alert, it will be done for you after the completion handler finishes.
266 #[unsafe(method(beginSheetModalForWindow:completionHandler:))]
267 #[unsafe(method_family = none)]
268 pub unsafe fn beginSheetModalForWindow_completionHandler(
269 &self,
270 sheet_window: &NSWindow,
271 handler: Option<&block2::DynBlock<dyn Fn(NSModalResponse)>>,
272 );
273
274 #[cfg(all(feature = "NSResponder", feature = "NSWindow"))]
275 /// The app-modal panel or document-modal sheet that corresponds to the alert
276 #[unsafe(method(window))]
277 #[unsafe(method_family = none)]
278 pub unsafe fn window(&self) -> Retained<NSWindow>;
279 );
280}
281
282/// Methods declared on superclass `NSObject`.
283impl NSAlert {
284 extern_methods!(
285 #[unsafe(method(init))]
286 #[unsafe(method_family = init)]
287 pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;
288
289 #[unsafe(method(new))]
290 #[unsafe(method_family = new)]
291 pub unsafe fn new(mtm: MainThreadMarker) -> Retained<Self>;
292 );
293}
294
295extern_protocol!(
296 /// A set of optional methods implemented by the delegate of an `NSAlert` object to respond to a user’s request for help.
297 ///
298 /// See also [Apple's documentation](https://developer.apple.com/documentation/appkit/nsalertdelegate?language=objc)
299 pub unsafe trait NSAlertDelegate: NSObjectProtocol + MainThreadOnly {
300 /// Sent to the delegate when the user clicks the alert’s help button. The delegate causes help to be displayed for an alert, directly or indirectly.
301 /// - Returns: `YES` when the delegate displayed help directly, `NO` otherwise. When `NO` and the alert has a help anchor (`helpAnchor`), the application’s help manager displays help using the help anchor.
302 /// - Discussion: The delegate implements this method only to override the help-anchor lookup behavior.
303 #[optional]
304 #[unsafe(method(alertShowHelp:))]
305 #[unsafe(method_family = none)]
306 unsafe fn alertShowHelp(&self, alert: &NSAlert) -> bool;
307 }
308);
309
310/// NSAlertDeprecated.
311impl NSAlert {
312 extern_methods!(
313 #[cfg(all(feature = "NSResponder", feature = "NSWindow"))]
314 #[deprecated = "Use -beginSheetModalForWindow:completionHandler: instead"]
315 #[unsafe(method(beginSheetModalForWindow:modalDelegate:didEndSelector:contextInfo:))]
316 #[unsafe(method_family = none)]
317 pub unsafe fn beginSheetModalForWindow_modalDelegate_didEndSelector_contextInfo(
318 &self,
319 window: &NSWindow,
320 delegate: Option<&AnyObject>,
321 did_end_selector: Option<Sel>,
322 context_info: *mut c_void,
323 );
324 );
325}
326
327/// [Apple's documentation](https://developer.apple.com/documentation/appkit/nswarningalertstyle?language=objc)
328pub static NSWarningAlertStyle: NSAlertStyle = NSAlertStyle(NSAlertStyle::Warning.0);
329
330/// [Apple's documentation](https://developer.apple.com/documentation/appkit/nsinformationalalertstyle?language=objc)
331pub static NSInformationalAlertStyle: NSAlertStyle = NSAlertStyle(NSAlertStyle::Informational.0);
332
333/// [Apple's documentation](https://developer.apple.com/documentation/appkit/nscriticalalertstyle?language=objc)
334pub static NSCriticalAlertStyle: NSAlertStyle = NSAlertStyle(NSAlertStyle::Critical.0);