#[repr(C)]pub struct NSAlert { /* private fields */ }
NSAlert
only.Expand description
A modal dialog or sheet attached to a document window.
The NSAlert
class is not designed for subclassing.
See also Apple’s documentation
Implementations§
Source§impl NSAlert
impl NSAlert
Sourcepub unsafe fn alertWithError(
error: &NSError,
mtm: MainThreadMarker,
) -> Retained<NSAlert>
pub unsafe fn alertWithError( error: &NSError, mtm: MainThreadMarker, ) -> Retained<NSAlert>
Returns an alert initialized from information in an error object.
- Parameter error: Error information to display.
- Returns: An initialized alert.
- 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.
Sourcepub unsafe fn messageText(&self) -> Retained<NSString>
pub unsafe fn messageText(&self) -> Retained<NSString>
The text that is displayed prominently in the alert.
- Note: Use this string to get the user’s attention and communicate the reason for displaying the alert.
Sourcepub unsafe fn setMessageText(&self, message_text: &NSString)
pub unsafe fn setMessageText(&self, message_text: &NSString)
Setter for messageText
.
Sourcepub unsafe fn informativeText(&self) -> Retained<NSString>
pub unsafe fn informativeText(&self) -> Retained<NSString>
The descriptive text that provides more details about the reason for the alert.
- 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.
Sourcepub unsafe fn setInformativeText(&self, informative_text: &NSString)
pub unsafe fn setInformativeText(&self, informative_text: &NSString)
Setter for informativeText
.
Sourcepub unsafe fn icon(&self) -> Option<Retained<NSImage>>
Available on crate feature NSImage
only.
pub unsafe fn icon(&self) -> Option<Retained<NSImage>>
NSImage
only.The custom icon displayed in the alert.
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.
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.
Sourcepub unsafe fn setIcon(&self, icon: Option<&NSImage>)
Available on crate feature NSImage
only.
pub unsafe fn setIcon(&self, icon: Option<&NSImage>)
NSImage
only.Setter for icon
.
Sourcepub unsafe fn addButtonWithTitle(&self, title: &NSString) -> Retained<NSButton>
Available on crate features NSButton
and NSControl
and NSResponder
and NSView
only.
pub unsafe fn addButtonWithTitle(&self, title: &NSString) -> Retained<NSButton>
NSButton
and NSControl
and NSResponder
and NSView
only.Adds a button with a given title to the alert.
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”.
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.
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
.
- Parameter title: Title of the button to add to the alert.
- Returns: The button that was added to the alert.
Available on crate features NSButton
and NSControl
and NSResponder
and NSView
only.
NSButton
and NSControl
and NSResponder
and NSView
only.The array of response buttons for the alert.
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:
.
Sourcepub unsafe fn alertStyle(&self) -> NSAlertStyle
pub unsafe fn alertStyle(&self) -> NSAlertStyle
Indicates the alert’s severity level. See the NSAlertStyle
enumeration for the list of alert style constants.
Sourcepub unsafe fn setAlertStyle(&self, alert_style: NSAlertStyle)
pub unsafe fn setAlertStyle(&self, alert_style: NSAlertStyle)
Setter for alertStyle
.
Sourcepub unsafe fn showsHelp(&self) -> bool
pub unsafe fn showsHelp(&self) -> bool
Specifies whether the alert has a help button.
Set this property’s value to YES
to specify that the alert has a help button, or NO
to specify it does not.
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.
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:
- There is no alert delegate.
- The alert delegate does not implement
-alertShowHelp:
. - The alert delegate implements
-alertShowHelp:
but returnsNO
. When this is the case, an exception is raised if no help anchor is set.
Sourcepub unsafe fn setShowsHelp(&self, shows_help: bool)
pub unsafe fn setShowsHelp(&self, shows_help: bool)
Setter for showsHelp
.
Sourcepub unsafe fn helpAnchor(&self) -> Option<Retained<NSHelpAnchorName>>
Available on crate feature NSHelpManager
only.
pub unsafe fn helpAnchor(&self) -> Option<Retained<NSHelpAnchorName>>
NSHelpManager
only.The alert’s HTML help anchor used when the user clicks the alert’s help button
Sourcepub unsafe fn setHelpAnchor(&self, help_anchor: Option<&NSHelpAnchorName>)
Available on crate feature NSHelpManager
only.
pub unsafe fn setHelpAnchor(&self, help_anchor: Option<&NSHelpAnchorName>)
NSHelpManager
only.Setter for helpAnchor
.
Sourcepub unsafe fn delegate(
&self,
) -> Option<Retained<ProtocolObject<dyn NSAlertDelegate>>>
pub unsafe fn delegate( &self, ) -> Option<Retained<ProtocolObject<dyn NSAlertDelegate>>>
The delegate of the receiver, currently only allows for custom help behavior of the alert.
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.
Sourcepub unsafe fn setDelegate(
&self,
delegate: Option<&ProtocolObject<dyn NSAlertDelegate>>,
)
pub unsafe fn setDelegate( &self, delegate: Option<&ProtocolObject<dyn NSAlertDelegate>>, )
This is a weak property.
Setter for delegate
.
Sourcepub unsafe fn accessoryView(&self) -> Option<Retained<NSView>>
Available on crate features NSResponder
and NSView
only.
pub unsafe fn accessoryView(&self) -> Option<Retained<NSView>>
NSResponder
and NSView
only.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.
Sourcepub unsafe fn setAccessoryView(&self, accessory_view: Option<&NSView>)
Available on crate features NSResponder
and NSView
only.
pub unsafe fn setAccessoryView(&self, accessory_view: Option<&NSView>)
NSResponder
and NSView
only.Setter for accessoryView
.
Sourcepub unsafe fn layout(&self)
pub unsafe fn layout(&self)
Specifies that the alert must do immediate layout instead of lazily just before display. 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.
Sourcepub unsafe fn runModal(&self) -> NSModalResponse
Available on crate feature NSApplication
only.
pub unsafe fn runModal(&self) -> NSModalResponse
NSApplication
only.Runs the alert as an app-modal dialog and returns the constant that identifies the button clicked.
Sourcepub unsafe fn showsSuppressionButton(&self) -> bool
pub unsafe fn showsSuppressionButton(&self) -> bool
Specifies whether the alert includes a suppression checkbox, which can be employed to allow a user to opt out of seeing the alert again.
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.
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:
myAlert.suppressionButton.title = “ Do not show this warning again“;
To create an alert that responds to the selection state of the suppression checkbox, check myAlert.suppressionButton.state
.
Sourcepub unsafe fn setShowsSuppressionButton(&self, shows_suppression_button: bool)
pub unsafe fn setShowsSuppressionButton(&self, shows_suppression_button: bool)
Setter for showsSuppressionButton
.
Sourcepub unsafe fn suppressionButton(&self) -> Option<Retained<NSButton>>
Available on crate features NSButton
and NSControl
and NSResponder
and NSView
only.
pub unsafe fn suppressionButton(&self) -> Option<Retained<NSButton>>
NSButton
and NSControl
and NSResponder
and NSView
only.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
.
Sourcepub unsafe fn beginSheetModalForWindow_completionHandler(
&self,
sheet_window: &NSWindow,
handler: Option<&DynBlock<dyn Fn(NSModalResponse)>>,
)
Available on crate features NSApplication
and NSResponder
and NSWindow
and block2
only.
pub unsafe fn beginSheetModalForWindow_completionHandler( &self, sheet_window: &NSWindow, handler: Option<&DynBlock<dyn Fn(NSModalResponse)>>, )
NSApplication
and NSResponder
and NSWindow
and block2
only.Runs the alert modally as a sheet attached to the specified window.
- Parameters:
- sheetWindow: The window on which to display the sheet.
- handler: The completion handler that gets called when the sheet’s modal session ends.
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.
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.
Source§impl NSAlert
NSAlertDeprecated.
impl NSAlert
NSAlertDeprecated.
pub unsafe fn beginSheetModalForWindow_modalDelegate_didEndSelector_contextInfo( &self, window: &NSWindow, delegate: Option<&AnyObject>, did_end_selector: Option<Sel>, context_info: *mut c_void, )
NSResponder
and NSWindow
only.Methods from Deref<Target = NSObject>§
Sourcepub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !
Handle messages the object doesn’t recognize.
See Apple’s documentation for details.
Methods from Deref<Target = AnyObject>§
Sourcepub fn class(&self) -> &'static AnyClass
Available on crate feature NSAccessibilityConstants
only.
pub fn class(&self) -> &'static AnyClass
NSAccessibilityConstants
only.Dynamically find the class of this object.
§Panics
May panic if the object is invalid (which may be the case for objects
returned from unavailable init
/new
methods).
§Example
Check that an instance of NSObject
has the precise class NSObject
.
use objc2::ClassType;
use objc2::runtime::NSObject;
let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());
Sourcepub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
👎Deprecated: this is difficult to use correctly, use Ivar::load
instead.Available on crate feature NSAccessibilityConstants
only.
pub unsafe fn get_ivar<T>(&self, name: &str) -> &Twhere
T: Encode,
Ivar::load
instead.NSAccessibilityConstants
only.Use Ivar::load
instead.
§Safety
The object must have an instance variable with the given name, and it
must be of type T
.
See Ivar::load_ptr
for details surrounding this.
Sourcepub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
Available on crate feature NSAccessibilityConstants
only.
pub fn downcast_ref<T>(&self) -> Option<&T>where
T: DowncastTarget,
NSAccessibilityConstants
only.Attempt to downcast the object to a class of type T
.
This is the reference-variant. Use Retained::downcast
if you want
to convert a retained object to another type.
§Mutable classes
Some classes have immutable and mutable variants, such as NSString
and NSMutableString
.
When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.
So using this method to convert a NSString
to a NSMutableString
,
while not unsound, is generally frowned upon unless you created the
string yourself, or the API explicitly documents the string to be
mutable.
See Apple’s documentation on mutability and on
isKindOfClass:
for more details.
§Generic classes
Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.
You can, however, safely downcast to generic collections where all the
type-parameters are AnyObject
.
§Panics
This works internally by calling isKindOfClass:
. That means that the
object must have the instance method of that name, and an exception
will be thrown (if CoreFoundation is linked) or the process will abort
if that is not the case. In the vast majority of cases, you don’t need
to worry about this, since both root objects NSObject
and
NSProxy
implement this method.
§Examples
Cast an NSString
back and forth from NSObject
.
use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};
let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();
Try (and fail) to cast an NSObject
to an NSString
.
use objc2_foundation::{NSObject, NSString};
let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());
Try to cast to an array of strings.
use objc2_foundation::{NSArray, NSObject, NSString};
let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();
This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.
Downcast when processing each element instead.
use objc2_foundation::{NSArray, NSObject, NSString};
let arr = NSArray::from_retained_slice(&[NSObject::new()]);
for elem in arr {
if let Some(data) = elem.downcast_ref::<NSString>() {
// handle `data`
}
}
Trait Implementations§
Source§impl ClassType for NSAlert
impl ClassType for NSAlert
Source§const NAME: &'static str = "NSAlert"
const NAME: &'static str = "NSAlert"
Source§type ThreadKind = dyn MainThreadOnly
type ThreadKind = dyn MainThreadOnly
Source§impl NSObjectProtocol for NSAlert
impl NSObjectProtocol for NSAlert
Source§fn isEqual(&self, other: Option<&AnyObject>) -> bool
fn isEqual(&self, other: Option<&AnyObject>) -> bool
Source§fn hash(&self) -> usize
fn hash(&self) -> usize
Source§fn isKindOfClass(&self, cls: &AnyClass) -> bool
fn isKindOfClass(&self, cls: &AnyClass) -> bool
Source§fn is_kind_of<T>(&self) -> bool
fn is_kind_of<T>(&self) -> bool
isKindOfClass
directly, or cast your objects with AnyObject::downcast_ref
Source§fn isMemberOfClass(&self, cls: &AnyClass) -> bool
fn isMemberOfClass(&self, cls: &AnyClass) -> bool
Source§fn respondsToSelector(&self, aSelector: Sel) -> bool
fn respondsToSelector(&self, aSelector: Sel) -> bool
Source§fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool
Source§fn debugDescription(&self) -> Retained<NSObject>
fn debugDescription(&self) -> Retained<NSObject>
Source§impl RefEncode for NSAlert
impl RefEncode for NSAlert
Source§const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF
const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF
impl DowncastTarget for NSAlert
impl Eq for NSAlert
Auto Trait Implementations§
impl !Freeze for NSAlert
impl !RefUnwindSafe for NSAlert
impl !Send for NSAlert
impl !Sync for NSAlert
impl !Unpin for NSAlert
impl !UnwindSafe for NSAlert
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<'a, T> MainThreadOnly for T
impl<'a, T> MainThreadOnly for T
Source§fn mtm(&self) -> MainThreadMarker
fn mtm(&self) -> MainThreadMarker
MainThreadMarker
from the main-thread-only object. Read more