Mac Developer Library

Developer

AppKit Framework Reference AppKit Functions Reference

Options
Deployment Target:

On This Page
Language:

AppKit Functions Reference

This document describes functions and function-like macros defined in the Application Kit framework.

Functions

Additional information on accessibility can be found in NSAccessibility.

  • Returns a standard description for an action.

    Declaration

    Swift

    func NSAccessibilityActionDescription(_ action: String!) -> String!

    Objective-C

    NSString * NSAccessibilityActionDescription ( NSString *action );

    Discussion

    This function returns a standard description for action.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sends a notification to any observing assistive applications.

    Declaration

    Swift

    func NSAccessibilityPostNotification(_ element: AnyObject!, _ notification: String!)

    Objective-C

    void NSAccessibilityPostNotification ( id element, NSString *notification );

    Discussion

    Sends notification to any assistive applications that have registered to receive the notification from the user interface object element in your application. Accessibility notifications require special handling, so they cannot be posted using NSNotificationCenter.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Sends a notification and an optional userInfo dictionary to any observing assistive applications.

    Declaration

    Swift

    func NSAccessibilityPostNotificationWithUserInfo(_ element: AnyObject!, _ notification: String!, _ userInfo: [NSObject : AnyObject]!)

    Objective-C

    void NSAccessibilityPostNotificationWithUserInfo ( id element, NSString *notification, NSDictionary *userInfo );

    Discussion

    Sends notification and userInfo to any assistive applications that have registered to receive the notification from the UI object element in your app. The userInfo dictionary values are restricted to the same values to which accessibility attributes are restricted (for a list of these values, see Attributes). The userInfo dictionary can also be nil (most accessibility notifications don’t require it).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Raises an error if the parameter is the wrong type or has an illegal value

    Declaration

    Swift

    func NSAccessibilityRaiseBadArgumentException(_ element: AnyObject!, _ attribute: String!, _ value: AnyObject!)

    Objective-C

    void NSAccessibilityRaiseBadArgumentException ( id element, NSString *attribute, id value );

    Discussion

    Raises an error if a parameter is the wrong type or has an illegal value. This function can also be used to raise an error if an attempt is made to set an attribute's value with the wrong type or an illegal value.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns a standard description for a role and subrole.

    Declaration

    Swift

    func NSAccessibilityRoleDescription(_ role: String!, _ subrole: String!) -> String!

    Objective-C

    NSString * NSAccessibilityRoleDescription ( NSString *role, NSString *subrole );

    Discussion

    You should pass nil to this function if there is no subrole. This function returns a description of a standard role. For example, if you implement a button widget that does not inherit from NSButton, you should use this function to return a localized role description matching that returned by a standard button.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns a standard role description for a user interface element.

    Declaration

    Swift

    func NSAccessibilityRoleDescriptionForUIElement(_ element: AnyObject!) -> String!

    Objective-C

    NSString * NSAccessibilityRoleDescriptionForUIElement ( id element );

    Discussion

    This function is like the NSAccessibilityRoleDescription function, except that it queries element to get the role and subrole. The NSAccessibilityRoleDescription function is more efficient, but this function is useful for accessorizing base classes so that they properly handle derived classes, which may override the subrole or even the role.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets whether the app may have protected content.

    Declaration

    Swift

    func NSAccessibilitySetMayContainProtectedContent(_ flag: Bool) -> Bool

    Objective-C

    BOOL NSAccessibilitySetMayContainProtectedContent ( BOOL flag );

    Discussion

    Uses the value of flag to specify whether the app may have protected content. Protected content is identified by a value of YEStrue for NSAccessibilityContainsProtectedContentAttribute, but if NSAccessibilitySetMayContainProtectedContent returns NOfalse, the value of NSAccessibilityContainsProtectedContentAttribute is ignored. This function returns YEStrue on success.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • Returns a list of unignored accessibility objects, descending the hierarchy if necessary.

    Declaration

    Swift

    func NSAccessibilityUnignoredChildren(_ originalChildren: [AnyObject]!) -> [AnyObject]!

    Objective-C

    NSArray * NSAccessibilityUnignoredChildren ( NSArray *originalChildren );

    Discussion

    This function first tests whether originalChildren contains any ignored objects. If the array contains no ignored objects, the function returns originalChildren. If the array contains ignored objects, this function returns a new array that contains the contents of originalChildren, but with each ignored object replaced by its unignored descendant.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Returns a list of unignored accessibility objects, descending the hierarchy if necessary.

    Declaration

    Swift

    func NSAccessibilityUnignoredChildrenForOnlyChild(_ originalChild: AnyObject!) -> [AnyObject]!

    Objective-C

    NSArray * NSAccessibilityUnignoredChildrenForOnlyChild ( id originalChild );

    Discussion

    Tests whether originalChild is an ignored object and returns an array containing either originalChild, if it is not ignored, or its unignored descendants.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Returns an unignored accessibility object, descending the hierarchy if necessary.

    Declaration

    Swift

    func NSAccessibilityUnignoredDescendant(_ element: AnyObject!) -> AnyObject!

    Objective-C

    id NSAccessibilityUnignoredDescendant ( id element );

    Discussion

    Tests whether element is an ignored object, returning either element, if it is not ignored, or the first unignored descendant of element. Use this function only if you know there is a linear, one-to-one, hierarchy below element. Otherwise, if element has either no unignored children or multiple unignored children, this function fails and returns nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Returns an unignored accessibility object, ascending the hierarchy if necessary.

    Declaration

    Swift

    func NSAccessibilityUnignoredAncestor(_ element: AnyObject!) -> AnyObject!

    Objective-C

    id NSAccessibilityUnignoredAncestor ( id element );

    Discussion

    Tests whether element is an ignored object, returning either element, if it is not ignored, or the first unignored ancestor of element.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Returns the frame in screen coordinates.

    Declaration

    Swift

    func NSAccessibilityFrameInView(_ parentView: NSView!, _ frame: NSRect) -> NSRect

    Objective-C

    NSRect NSAccessibilityFrameInView ( NSView *parentView, NSRect frame );

    Discussion

    Given a frame in the specified view’s coordinates, it returns the same frame in the screen’s coordinates.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Returns the point in screen coordinates.

    Declaration

    Swift

    func NSAccessibilityPointInView(_ parentView: NSView!, _ point: NSPoint) -> NSPoint

    Objective-C

    NSPoint NSAccessibilityPointInView ( NSView *parentView, NSPoint point );

    Discussion

    Given a point in the specified view’s coordinates, it returns the same point in the screen’s coordinates.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

Additional information on NSApplication can be found in NSApplication Class Reference.

  • Startup function to call when running Cocoa code from a Carbon application.

    Declaration

    Swift

    func NSApplicationLoad() -> Bool

    Objective-C

    BOOL NSApplicationLoad ( void );

    Return Value

    YEStrue if the NSApplication object was successfully initialized and can now be used from your Carbon application or NOfalse if there was an error during initialization.

    Discussion

    You typically call this function before calling other Cocoa code in a plug-in loaded into a primarily Carbon application. If the shared NSApplication object is not already initialized, this function initializes it and sets up the necessary event handlers for Cocoa.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Called by the main function to create and run the application.

    Declaration

    Swift

    func NSApplicationMain(_ argc: Int32, _ argv: UnsafeMutablePointer<UnsafePointer<Int8>>) -> Int32

    Objective-C

    int NSApplicationMain ( int argc, const char *argv[] );

    Parameters

    argc

    The number of arguments in the argv parameter.

    argv

    An array of pointers containing the arguments that were passed to the application at startup.

    Return Value

    This method never returns a result code. Instead, it calls the exit function to exit the application and terminate the process. If you want to determine why the application exited, you should look at the result code from the exit function instead.

    Discussion

    Creates the application, loads the main nib file from the application’s main bundle, and runs the application. You must call this function from the main thread of your application, and you typically call it only once from your application’s main function, which is usually generated automatically by Xcode.

    Special Considerations

    NSApplicationMain itself ignores the argc and argv arguments. Instead, Cocoa gets its arguments indirectly via _NSGetArgv, _NSGetArgc, and _NSGetEnviron (see <crt_externs.h>).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Programmatically invokes a Services menu service.

    Declaration

    Swift

    func NSPerformService(_ itemName: String!, _ pboard: NSPasteboard!) -> Bool

    Objective-C

    BOOL NSPerformService ( NSString *itemName, NSPasteboard *pboard );

    Parameters

    itemName

    Specifies a Services menu item, in any language. If the requested service is from a submenu of the Services menu, the value must contain a slash (for example, “Mail/Selection”).

    pboard

    The pasteboard containing the data required by the service. This data must be present for the service to succeed. On output, this pasteboard contains the data returned by the service provider.

    Return Value

    YEStrue if the service was successfully performed or NOfalse if it was not.

    Discussion

    Use this function to programmatically invoke a service found in the application’s Services menu.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Registers a service provider.

    Declaration

    Swift

    func NSRegisterServicesProvider(_ provider: AnyObject!, _ name: String!)

    Objective-C

    void NSRegisterServicesProvider ( id provider, NSString *name );

    Parameters

    provider

    The object providing the service you want to register.

    name

    The unique name to associate with the service. This string is used to advertise the service to interested clients.

    Discussion

    Use this function to register custom services not directly related to your application.

    You should not use this function to register the services provided by your application. For your application’s services, you should use the setServicesProvider: method of NSApplication, passing a non-nil argument.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Specifies whether an item should be included in Services menus.

    Declaration

    Swift

    func NSSetShowsServicesMenuItem(_ itemName: String!, _ enabled: Bool) -> Int

    Objective-C

    NSInteger NSSetShowsServicesMenuItem ( NSString *itemName, BOOL enabled );

    Discussion

    Deprecated. This function simply returns 0.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Specifies whether a Services menu item is currently enabled.

    Declaration

    Swift

    func NSShowsServicesMenuItem(_ itemName: String!) -> Bool

    Objective-C

    BOOL NSShowsServicesMenuItem ( NSString *itemName );

    Discussion

    Deprecated. This function simply returns YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Unregisters a service provider.

    Declaration

    Swift

    func NSUnregisterServicesProvider(_ name: String!)

    Objective-C

    void NSUnregisterServicesProvider ( NSString *name );

    Parameters

    name

    The name of the service you want to unregister.

    Discussion

    Use this function to unregister custom services not directly related to your application.

    You should not use this function to unregister the services provided by your application. For your application’s services, you should use the setServicesProvider: method of NSApplication, passing a nil argument.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Causes the services information for the system to be updated.

    Declaration

    Swift

    func NSUpdateDynamicServices()

    Objective-C

    void NSUpdateDynamicServices ( void );

    Discussion

    Used by a service-providing application to reregister the services it is willing to provide. To do this, you create a bundle with the extension “.service” and place it in the application’s path or ~/Library/Services. The content of the bundle is identical to a normal service bundle. You then call this function.

    It is only necessary to call this function if your program adds dynamic services to the system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Creates a dictionary wherein the keys are string representations of the corresponding values’ variable names.

    Declaration

    Objective-C

    #define NSDictionaryOfVariableBindings(...) _NSDictionaryOfVariableBindings(@"" # __VA_ARGS__, __VA_ARGS__, nil)

    Discussion

    This macro is particularly useful when creating Auto Layout constraints—see Auto Layout Guide. For example, the following code:

    • NSDictionary *viewsDictionary = NSDictionaryOfVariableBindings(button1, button2);

    creates the dictionary { @"button1" = button1, @"button2 = button2 }.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.7 and later.

  • Returns the event mask for the specified type.

    Declaration

    Swift

    func NSEventMaskFromType(_ type: NSEventType) -> NSEventMask

    Objective-C

    NSEventMask NSEventMaskFromType ( NSEventType type );

    Parameters

    type

    The event type whose mask you want to get.

    Return Value

    The event mask corresponding to the specified type. The returned mask is equivalent to the number 1 left-shifted by type bits.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Prepares a set of glyphs for processing by character-based routines.

    Declaration

    Swift

    func NSConvertGlyphsToPackedGlyphs(_ glBuf: UnsafeMutablePointer<NSGlyph>, _ count: Int, _ packing: NSMultibyteGlyphPacking, _ packedGlyphs: UnsafeMutablePointer<Int8>) -> Int

    Objective-C

    NSInteger NSConvertGlyphsToPackedGlyphs ( NSGlyph *glBuf, NSInteger count, NSMultibyteGlyphPacking packing, char *packedGlyphs );

    Discussion

    Takes a buffer of glyphs, specified in the glBuf parameter, and packs them into a condensed character array. The character array is returned in the packedGlyphs parameter, which should have enough space for at least ((4 * count) + 1) bytes to guarantee that the packed glyphs fit. count specifies the number of glyphs in glBuf. packing specifies how the glyphs are currently packed.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Copies a bitmap image to the location specified by a destination point.

    Declaration

    Swift

    func NSCopyBits(_ srcGState: Int, _ srcRect: NSRect, _ destPoint: NSPoint)

    Objective-C

    void NSCopyBits ( NSInteger srcGState, NSRect srcRect, NSPoint destPoint );

    Discussion

    Copies the pixels in the rectangle specified by srcRect to the location specified by destPoint. The source rectangle is defined in the graphics state designated by srcGState. If srcGState is NSNullObject, the current graphics state is assumed. The destPoint destination is defined in the current graphics state.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Counts the number of onscreen windows.

    Declaration

    Objective-C

    void NSCountWindows ( NSInteger *count );

    Parameters

    count

    On output, this parameter contains the number of onscreen windows.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Counts the number of onscreen windows belonging to a particular application.

    Declaration

    Objective-C

    void NSCountWindowsForContext ( NSInteger context, NSInteger *count );

    Discussion

    Counts the number of onscreen windows belonging to a particular application, identified by context, which is a window server connection ID. The function returns the number by reference in count.

    Use of this function is discouraged as it may be deprecated in a future release.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Disables screen updates.

    Declaration

    Swift

    func NSDisableScreenUpdates()

    Objective-C

    void NSDisableScreenUpdates ( void );

    Discussion

    Prevents drawing operations from being flushed to the screen for all windows belonging to the calling process. When you re-enable screen updates (with NSEnableScreenUpdates) screen flushing for all windows belonging to the calling process appears to be simultaneous. You typically call this function so that operations on multiple windows appear atomic to the user. This is a technique particularly useful for synchronizing parent and child windows. Make sure that the period after calling this function and before reenabling updates is short; the system only allow updating to be disabled for a limited time (currently one second) before automatically reenabling updates. Successive calls to this function are placed on a stack and must be popped off that stack by matching NSEnableScreenUpdates calls.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Enables screen updates

    Declaration

    Swift

    func NSEnableScreenUpdates()

    Objective-C

    void NSEnableScreenUpdates ( void );

    Discussion

    Reenables, for all windows of a process, the flushing of drawing operations to the screen that was previously disabled by NSDisableScreenUpdates. Successive calls to NSDisableScreenUpdates are placed on a stack and must be popped off that stack by matching calls to this function.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Draws a bordered rectangle.

    Declaration

    Swift

    func NSDottedFrameRect(_ aRect: NSRect)

    Objective-C

    void NSDottedFrameRect ( NSRect aRect );

    Discussion

    Deprecated. Use a dashed NSBezierPath instead.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSDrawTiledRects

  • Draws a bitmap image.

    Declaration

    Swift

    func NSDrawBitmap(_ rect: NSRect, _ width: Int, _ height: Int, _ bps: Int, _ spp: Int, _ bpp: Int, _ bpr: Int, _ isPlanar: Bool, _ hasAlpha: Bool, _ colorSpaceName: String!, _ data: UnsafePointer<UnsafePointer<UInt8>>)

    Objective-C

    void NSDrawBitmap ( NSRect rect, NSInteger width, NSInteger height, NSInteger bps, NSInteger spp, NSInteger bpp, NSInteger bpr, BOOL isPlanar, BOOL hasAlpha, NSString *colorSpaceName, const unsigned char *const data[5] );

    Discussion

    This function is marginally obsolete. Most applications are better served using the NSBitmapImageRep class to read and display bitmap images.

    This function renders an image from a bitmap, binary data that describes the pixel values for the image.

    This function renders a bitmap image using an appropriate display operator. It puts the image in the rectangular area specified by its first argument, rect; the rectangle is specified in the current coordinate system and is located in the current window. The next two arguments, pixelsWide and pixelsHigh, give the width and height of the image in pixels. If either of these dimensions is larger or smaller than the corresponding dimension of the destination rectangle, the image will be scaled to fit.

    The remaining arguments describe the bitmap data, as explained in the following paragraphs.

    The bitsPerSample argument is the number of bits per sample for each pixel and samplesPerPixel is the number of samples per pixel. bitsPerPixel is based on samplesPerPixel and the configuration of the bitmap: if the configuration is planar, then the value of bitsPerPixel should equal the value of bitsPerSample; if the configuration isn’t planar (is meshed instead), bitsPerPixel should equal bitsPerSample * samplesPerPixel.

    The bytesPerRow argument is calculated in one of two ways, depending on the configuration of the image data (data configuration is described below). If the data is planar, bytesPerRow is (7 + (pixelsWide * bitsPerSample)) / 8. If the data is meshed, bytesPerRow is (7 + (pixelsWide * bitsPerSample * samplesPerPixel)) / 8.

    A sample is data that describes one component of a pixel. In an RGB color system, the red, green, and blue components of a color are specified as separate samples, as are the cyan, magenta, yellow, and black components in a CMYK system. Color values in a grayscale are a single sample. Alpha values that determine transparency and opaqueness are specified as a coverage sample separate from color. In bitmap images with alpha, the color (or gray) components have to be premultiplied with the alpha. This is the way images with alpha are displayed, this is the way they are read back, and this is the way they are stored in TIFFs.

    The isPlanar argument refers to the way data is configured in the bitmap. This flag should be set to YEStrue if a separate data channel is used for each sample. The function provides for up to five channels, data1, data2, data3, data4, and data5. It should be set NOfalse if sample values are interwoven in a single channel (meshed); all values for one pixel are specified before values for the next pixel.

    Grayscale windows store pixel data in planar configuration; color windows store it in meshed configuration. NSDrawBitmap can render meshed data in a planar window, or planar data in a meshed window. However, it’s more efficient if the image has a depth (bitsPerSample) and configuration (isPlanar) that match the window.

    The hasAlpha argument indicates whether the image contains alpha. If it does, the number of samples should be 1 greater than the number of color components in the model (for example, 4 for RGB).

    The colorSpace argument can be NSCustomColorSpace, indicating that the image data is to be interpreted according to the current color space in the graphics state. This allows for imaging using custom color spaces. The image parameters supplied as the other arguments should match what the color space is expecting.

    If the image data is planar, data[0] through data[samplesPerPixel–1] point to the planes; if the data is meshed, only data[0] needs to be set.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws a gray-filled rectangle representing a user-interface button.

    Declaration

    Swift

    func NSDrawButton(_ aRect: NSRect, _ clipRect: NSRect)

    Objective-C

    void NSDrawButton ( NSRect aRect, NSRect clipRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw. Only those parts of aRect that lie within the clipRect are actually drawn.

    clipRect

    The clipping rectangle to use during drawing.

    Discussion

    Draws a gray-filled rectangle, used to signify a user-interface button. Since this function is often used to draw the border of a view, the aRect parameter typically contains the view’s bounds rectangle. For an Aqua button, use an NSButton object instead.

    This function fills the specified rectangle with light gray. This function is designed for rectangles that are defined in unscaled, unrotated coordinate systems (that is, where the y axis is vertical, the x axis is horizontal, and a unit along either axis is equal to 1 screen pixel). The coordinate system can be either flipped or unflipped. The sides of the rectangle should lie on pixel boundaries.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws a dark gray-filled rectangle with a bezel border.

    Declaration

    Swift

    func NSDrawDarkBezel(_ aRect: NSRect, _ clipRect: NSRect)

    Objective-C

    void NSDrawDarkBezel ( NSRect aRect, NSRect clipRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw. Only those parts of aRect that lie within the clipRect are actually drawn.

    clipRect

    The clipping rectangle to use during drawing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSDrawTiledRects

  • Draws a gray-filled rectangle with a bezel border.

    Declaration

    Swift

    func NSDrawGrayBezel(_ aRect: NSRect, _ clipRect: NSRect)

    Objective-C

    void NSDrawGrayBezel ( NSRect aRect, NSRect clipRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw. Only those parts of aRect that lie within the clipRect are actually drawn.

    clipRect

    The clipping rectangle to use during drawing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSDrawTiledRects

  • Draws a gray-filled rectangle with a groove border.

    Declaration

    Swift

    func NSDrawGroove(_ aRect: NSRect, _ clipRect: NSRect)

    Objective-C

    void NSDrawGroove ( NSRect aRect, NSRect clipRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw. Only those parts of aRect that lie within the clipRect are actually drawn.

    clipRect

    The clipping rectangle to use during drawing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSDrawTiledRects

  • Draws a white-filled rectangle with a bezel border.

    Declaration

    Swift

    func NSDrawLightBezel(_ aRect: NSRect, _ clipRect: NSRect)

    Objective-C

    void NSDrawLightBezel ( NSRect aRect, NSRect clipRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw. Only those parts of aRect that lie within the clipRect are actually drawn.

    clipRect

    The clipping rectangle to use during drawing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSDrawTiledRects

  • Draws a three-part tiled image.

    Declaration

    Swift

    func NSDrawThreePartImage(_ frame: NSRect, _ startCap: NSImage!, _ centerFill: NSImage!, _ endCap: NSImage!, _ vertical: Bool, _ op: NSCompositingOperation, _ alphaFraction: CGFloat, _ flipped: Bool)

    Objective-C

    void NSDrawThreePartImage ( NSRect frame, NSImage *startCap, NSImage *centerFill, NSImage *endCap, BOOL vertical, NSCompositingOperation op, CGFloat alphaFraction, BOOL flipped );

    Parameters

    frame

    The rectangle (specified in the current coordinate system) in which to draw the images.

    startCap

    For a horizontal three-part image, this is the image located at the left edge of the frame rectangle. For a vertical three-part image, this image appears at the top of the screen in an unflipped coordinate system and at the bottom of the screen in a flipped coordinate system.

    centerFill

    The image used to tile the space between the startCap and endCap images.

    endCap

    For a horizontal three-part image, this is the image located at the right edge of the frame rectangle. For a vertical three-part image, this image appears at the bottom of the screen in an unflipped coordinate system and at the top of the screen in a flipped coordinate system.

    vertical

    Specify YEStrue if the images should be stacked on top of one another to create a vertically oriented element. Specify NOfalse if the images should be laid out side-by-side to create a horizontally oriented element.

    op

    The compositing operation to use when rendering the images.

    alphaFraction

    The alpha value to apply to the rendered image. This value can range between 0.0 and 1.0, with 0.0 being fully transparent and 1.0 being fully opaque.

    flipped

    Specify YEStrue if you are drawing the images in a flipped coordinate system; otherwise, specify NOfalse.

    Discussion

    This function is typically used to draw custom cells (such as the backgrounds for push button and slider controls) that are capable of being resized along a single axis only. Cells of this type are comprised of fixed-size end cap images and a center area that is filled by tiling the specified center image as many times as needed to fill the gap. These cells allow you to create sophisticated looking controls that can grow and shrink without distorting the control’s overall appearance.

    You should prefer the use of this function over your own custom code for handling multi-part images whose size can change. This function correctly manages the subtle behaviors needed to handle resolution independence issues and to avoid visual artifacts caused by tiling the various images.

    When drawing a horizontally oriented control, the images in the startCap, centerFill, and endCap parameters should all have the same height, and that height should match the height of the frame rectangle. If an image’s height does not match the height of the frame rectangle, it is scaled until it does match, which might yield less desirable results. For vertically oriented controls, the image widths are scaled instead of the heights.

    The flipped parameter lets you reorient the contents of each image when drawing in a flipped coordinate system. By default, images use an internal coordinate system that is not flipped. Rendering such an image in a flipped coordinate system would therefore cause the image to appear upside down. Passing YEStrue for the flipped parameter adjusts the image’s internal coordinate system to draw it correctly in a flipped environment.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Draws a nine-part tiled image.

    Declaration

    Swift

    func NSDrawNinePartImage(_ frame: NSRect, _ topLeftCorner: NSImage!, _ topEdgeFill: NSImage!, _ topRightCorner: NSImage!, _ leftEdgeFill: NSImage!, _ centerFill: NSImage!, _ rightEdgeFill: NSImage!, _ bottomLeftCorner: NSImage!, _ bottomEdgeFill: NSImage!, _ bottomRightCorner: NSImage!, _ op: NSCompositingOperation, _ alphaFraction: CGFloat, _ flipped: Bool)

    Objective-C

    void NSDrawNinePartImage ( NSRect frame, NSImage *topLeftCorner, NSImage *topEdgeFill, NSImage *topRightCorner, NSImage *leftEdgeFill, NSImage *centerFill, NSImage *rightEdgeFill, NSImage *bottomLeftCorner, NSImage *bottomEdgeFill, NSImage *bottomRightCorner, NSCompositingOperation op, CGFloat alphaFraction, BOOL flipped );

    Parameters

    frame

    The rectangle (specified in the current coordinate system) in which to draw the images.

    topLeftCorner

    The image to display in the top-left corner.

    topEdgeFill

    The image used to tile the space between the topLeftCorner and topRightCorner images.

    topRightCorner

    The image to display in the top-right corner.

    leftEdgeFill

    The image used to tile the space between the topLeftCorner and bottomLeftCorner images.

    centerFill

    The image used to tile the center area between the other eight images.

    rightEdgeFill

    The image used to tile the space between the topRightCorner and bottomRightCorner images.

    bottomLeftCorner

    The image to display in the bottom-left corner.

    bottomEdgeFill

    The image used to tile the space between the bottomLeftCorner and bottomRightCorner images.

    bottomRightCorner

    The image to display in the bottom-right corner.

    op

    The compositing operation to use when rendering the images.

    alphaFraction

    The alpha value to apply to the rendered image. This value can range between 0.0 and 1.0, with 0.0 being fully transparent and 1.0 being fully opaque.

    flipped

    Specify YEStrue if you are drawing the images in a flipped coordinate system; otherwise, specify NOfalse.

    Discussion

    This function is typically used to draw custom cells that are capable of being resized both vertically and horizontally. Cells of this type are comprised of four fixed-size corner images along and a set of edge and center images that are used to fill the gaps between the corners. These cells allow you to create sophisticated looking controls that can grow and shrink in any direction without distorting the control’s overall appearance.

    You should prefer the use of this function over your own custom code for handling multi-part images whose size can change. This function correctly manages the subtle behaviors needed to handle resolution independence issues and to avoid visual artifacts caused by tiling the various images.

    This function uses the top-left and bottom-right corner images to determine the widths and heights of the edge areas that need to be filled. If the width or height of the bottom-left and top-right images are not sized appropriately, they may be scaled to fill their corner area. Edge areas between the corners are tiled using the corresponding image. Similarly, the center area is tiled using the specified center image.

    The flipped parameter lets you reorient the contents of each image when drawing in a flipped coordinate system. By default, images use an internal coordinate system that is not flipped. Rendering such an image in a flipped coordinate system would therefore cause the image to appear upside down. Passing YEStrue for the flipped parameter adjusts the image’s internal coordinate system to draw it correctly in a flipped environment.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Draws rectangles with borders.

    Declaration

    Swift

    func NSDrawTiledRects(_ boundsRect: NSRect, _ clipRect: NSRect, _ sides: UnsafePointer<NSRectEdge>, _ grays: UnsafePointer<CGFloat>, _ count: Int) -> NSRect

    Objective-C

    NSRect NSDrawTiledRects ( NSRect boundsRect, NSRect clipRect, const NSRectEdge *sides, const CGFloat *grays, NSInteger count );

    Parameters

    boundsRect

    The bounding rectangle (in the current coordinate system) in which to draw. Since this function is often used to draw the border of a view, this rectangle will typically be that view’s bounds rectangle. Only those parts of boundsRect that lie within the clipRect are actually drawn.

    clipRect

    The clipping rectangle to use during drawing.

    sides

    The sides of the rectangle for which you want to specify custom gray levels. Each side must have a corresponding entry in the grays parameter.

    grays

    The gray levels to draw for each of the edges listed in the sides parameter.

    count

    The number of 1.0-unit-wide slices to draw on the specified sides.

    Return Value

    The rectangle that lies within the resulting border.

    Discussion

    This is a generic function that can be used to draw different types of borders inside a given rectangle. These borders can be used to outline an area or to give rectangles the effect of being recessed from or elevated above the surface of the screen.

    The sides, grays, and count parameters determine how thick the border is and what gray levels are used to form it. This function uses the NSDivideRect function to take successive 1.0-unit-wide slices from the sides of the rectangle specified by the sides parameter. Each slice is drawn using the corresponding gray level from the grays parameter. This function makes and draws these slices count number of times. If you specify the same side more than once, the second slice is drawn inside the first.

    The following example uses this function to draw a bezeled border consisting of a 1.0–unit-wide white line at the top and on the left side and a 1.0-unit-wide dark-gray line inside a 1.0–unit-wide black line on the other two sides. The resulting rectangle inside this border is then filled in using light gray.

    • NSRectEdge mySides[] = {NSMinYEdge, NSMaxXEdge, NSMaxYEdge, NSMinXEdge,
    • NSMinYEdge, NSMaxXEdge};
    • float myGrays[] = {NSBlack, NSBlack, NSWhite, NSWhite,
    • NSDarkGray, NSDarkGray};
    • NSRect aRect, clipRect; // Assume exists
    • aRect = NSDrawTiledRects(aRect, clipRect, mySides, myGrays, 6);
    • [[NSColor grayColor] set];
    • NSRectFill(aRect);

    In the preceding example, mySides is an array that specifies sides of a rectangle; for example, NSMinYEdge selects the side parallel to the x axis with the smallest y coordinate value. myGrays is an array that specifies the successive gray levels to be used in drawing parts of the border.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws a colored bordered rectangle.

    Declaration

    Swift

    func NSDrawColorTiledRects(_ boundsRect: NSRect, _ clipRect: NSRect, _ sides: UnsafePointer<NSRectEdge>, _ colors: AutoreleasingUnsafeMutablePointer<NSColor?>, _ count: Int) -> NSRect

    Objective-C

    NSRect NSDrawColorTiledRects ( NSRect boundsRect, NSRect clipRect, const NSRectEdge *sides, NSColor **colors, NSInteger count );

    Parameters

    boundsRect

    The bounding rectangle (in the current coordinate system) in which to draw. Since this function is often used to draw the border of a view, this rectangle will typically be that view’s bounds rectangle. Only those parts of boundsRect that lie within the clipRect are actually drawn.

    clipRect

    The clipping rectangle to use during drawing.

    sides

    The sides of the rectangle for which you want to specify custom colors. Each side must have a corresponding entry in the colors parameter.

    colors

    The colors to draw for each of the edges listed in the sides parameter.

    count

    The number of 1.0-unit-wide slices to draw on the specified sides.

    Return Value

    The rectangle that lies within the resulting border.

    Discussion

    Behaves the same as NSDrawTiledRects except it draws its border using colors from the colors array.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws a white-filled rectangle with a bezel border.

    Declaration

    Swift

    func NSDrawWhiteBezel(_ aRect: NSRect, _ clipRect: NSRect)

    Objective-C

    void NSDrawWhiteBezel ( NSRect aRect, NSRect clipRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw. Only those parts of aRect that lie within the clipRect are actually drawn.

    clipRect

    The clipping rectangle to use during drawing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSDrawTiledRects

  • Draws the window’s default background pattern into the specified rectangle of the currently focused view.

    Declaration

    Swift

    func NSDrawWindowBackground(_ aRect: NSRect)

    Objective-C

    void NSDrawWindowBackground ( NSRect aRect );

    Parameters

    aRect

    The rectangle (in the current coordinate system) in which to draw the window’s background pattern.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Erases the specified rect by filling it with white.

    Declaration

    Swift

    func NSEraseRect(_ aRect: NSRect)

    Objective-C

    void NSEraseRect ( NSRect aRect );

    Parameters

    aRect

    The rectangle (in the current coordinate system) defining the area to erase.

    Discussion

    This function fills the specified rectangle with white. It does not alter the current color.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draw a bordered rectangle.

    Declaration

    Swift

    func NSFrameRect(_ aRect: NSRect)

    Objective-C

    void NSFrameRect ( NSRect aRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw.

    Discussion

    Draws a frame around the inside of aRect in the current color and using the NSCompositeCopy compositing operation. The width is equal to 1.0 in the current coordinate system. Since the frame is drawn inside the rectangle, it will be visible even if drawing is clipped to the rectangle.

    Because this function does not draw directly on the line, but rather inside it, it uses the current fill color (not stroke color) when drawing.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSDrawTiledRects

  • Draw a bordered rectangle.

    Declaration

    Swift

    func NSFrameRectWithWidth(_ aRect: NSRect, _ frameWidth: CGFloat)

    Objective-C

    void NSFrameRectWithWidth ( NSRect aRect, CGFloat frameWidth );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw.

    frameWidth

    The width of the frame, specified in points.

    Discussion

    Draws a frame around the inside of aRect in the current color and using the NSCompositeCopy compositing operation. The width is equal to frameWidth in the current coordinate system. Since the frame is drawn inside the rectangle, it will be visible even if drawing is clipped to the rectangle.

    Because this function does not draw directly on the line, but rather inside it, it uses the current fill color (not stroke color) when drawing.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    NSDrawTiledRects

  • Draw a bordered rectangle using the specified compositing operation.

    Declaration

    Swift

    func NSFrameRectWithWidthUsingOperation(_ aRect: NSRect, _ frameWidth: CGFloat, _ op: NSCompositingOperation)

    Objective-C

    void NSFrameRectWithWidthUsingOperation ( NSRect aRect, CGFloat frameWidth, NSCompositingOperation op );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw.

    frameWidth

    The width of the frame, specified in points.

    op

    The compositing operation to use when drawing the frame.

    Discussion

    Draws a frame around the inside of aRect in the current color, using the compositing operation op. The width is equal to frameWidth in the current coordinate system. Since the frame is drawn inside the rectangle, it will be visible even if drawing is clipped to the rectangle.

    Because this function does not draw directly on the line, but rather inside it, it uses the current fill color (not stroke color) when drawing.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSEdgeInsets structure with the specified insets.

    Declaration

    Objective-C

    NSEdgeInsets NSEdgeInsetsMake(CGFloat top, CGFloat left, CGFloat bottom, CGFloat right) { NSEdgeInsets e; e.top = top; e.left = left; e.bottom = bottom; e.right = right; return e; }

  • Returns the amount of memory being used by a context.

    Declaration

    Swift

    func NSGetWindowServerMemory(_ context: Int, _ virtualMemory: UnsafeMutablePointer<Int>, _ windowBackingMemory: UnsafeMutablePointer<Int>, _ windowDumpString: AutoreleasingUnsafeMutablePointer<NSString?>) -> Int

    Objective-C

    NSInteger NSGetWindowServerMemory ( NSInteger context, NSInteger *virtualMemory, NSInteger *windowBackingMemory, NSString **windowDumpString );

    Discussion

    Calculates the amount of memory being used at the moment by the given context. If NULL is passed for context, the current context is used. The amount of virtual memory used by the current context is returned in the int pointed to by virtualMemory; the amount of window backing store used by windows owned by the current context is returned in the int pointed to by windowBackingMemory. The sum of these two numbers is the amount of the memory that this context is responsible for.

    Calculating these numbers takes some time to execute; thus, calling this function in normal operation is not recommended.

    If nil is not passed in for windowDumpStream, the information returned is echoed to the specified stream. This fact can be useful for finding out more about which windows are using up your storage.

    Normally, NSGetWindowServerMemory returns 0. If NULL is passed for context and there’s no current display context, this function returns –1.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Highlights the specified rect by filling it with white.

    Declaration

    Objective-C

    void NSHighlightRect ( NSRect aRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw.

    Discussion

    Highlights the rectangle referred to by aRect. Light gray becomes white, and white becomes light gray. This function must be called twice, once to highlight the rectangle and once to unhighlight it; the rectangle should not be left in its highlighted state. When not drawing on the screen, the compositing operation is replaced by one that fills the rectangle with light gray.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.0.

  • Reads the color of the pixel at the specified location.

    Declaration

    Swift

    func NSReadPixel(_ passedPoint: NSPoint) -> NSColor!

    Objective-C

    NSColor * NSReadPixel ( NSPoint passedPoint );

    Parameters

    passedPoint

    The pixel location to read, specified in the current coordinate system.

    Return Value

    The color of the pixel at the specified location.

    Discussion

    Because the passedPoint parameter is relative to the current coordinate system, if you wish to read a pixel from a specific view, you must convert points in the view’s coordinate system to the current coordinate system before calling this function. Alternatively, you can lock focus on the view and then specify the pixel coordinate in the view’s coordinate system.

    When mapping the specified point to pixel boundaries, this method rounds to the nearest pixel. For more information on how coordinate points map to the underlying pixels, see Coordinate Systems and Transforms in Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Modifies the current clipping path by intersecting it with the passed rect.

    Declaration

    Swift

    func NSRectClip(_ aRect: NSRect)

    Objective-C

    void NSRectClip ( NSRect aRect );

    Parameters

    aRect

    The rectangle to intersect with the current clipping rectangle.

    Discussion

    This function modifies the clipping path permanently. If you need to undo this modification later, you should save the current graphics state before calling this function and restore it once you are done.

    A side effect of this function is that it clears the current Quartz 2D drawing path information. If you used Quartz 2D functions to create a drawing path in the current context, and you want to save that path information and use it later, you should transfer it to a CGPathRef opaque type before calling this function. If you are using only Cocoa to do your drawing, this behavior should not affect you.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Modifies the current clipping path by intersecting it with the passed rect.

    Declaration

    Swift

    func NSRectClipList(_ rects: UnsafePointer<NSRect>, _ count: Int)

    Objective-C

    void NSRectClipList ( const NSRect *rects, NSInteger count );

    Parameters

    rects

    A pointer to an array of NSRect structures, which are combined and intersected with the current clipping path.

    count

    The number of rectangles in rects.

    Discussion

    This function modifies the clipping path permanently by generating a graphical union of the specified rectangles and then intersecting that union with the current clipping path. If you need to undo this modification later, you should save the current graphics state before calling this function and restore it once you are done.

    A side effect of this function is that it clears the current Quartz 2D drawing path information. If you used Quartz 2D functions to create a drawing path in the current context, and you want to save that path information and use it later, you should transfer it to a CGPathRef opaque type before calling this function. If you are using only Cocoa to do your drawing, this behavior should not affect you.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Fills the passed rectangle with the current color.

    Declaration

    Swift

    func NSRectFill(_ aRect: NSRect)

    Objective-C

    void NSRectFill ( NSRect aRect );

    Parameters

    aRect

    The bounding rectangle (in the current coordinate system) in which to draw.

    Discussion

    Fills aRect with the current color using the compositing mode NSCompositeCopy, which fills with the current color by copying the RGBA values. Use NSRectFillUsingOperation to fill specifying a compositing mode.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Fills the rectangles in the passed list with the current fill color.

    Declaration

    Swift

    func NSRectFillList(_ rects: UnsafePointer<NSRect>, _ count: Int)

    Objective-C

    void NSRectFillList ( const NSRect *rects, NSInteger count );

    Parameters

    rects

    A pointer to an array of NSRect structures representing the rectangles to fill.

    count

    The number of rectangles in rects.

    Discussion

    Fills the specified rectangles with the current fill color using the compositing mode NSCompositeCopy.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Fills the rectangles in the passed list with the passed list of colors.

    Declaration

    Swift

    func NSRectFillListWithColors(_ rects: UnsafePointer<NSRect>, _ colors: UnsafePointer<NSColor?>, _ num: Int)

    Objective-C

    void NSRectFillListWithColors ( const NSRect *rects, NSColor *const *colors, NSInteger num );

    Parameters

    rects

    A pointer to an array of NSRect structures representing the rectangles to fill.

    colors

    A pointer to an array of NSColor objects. The number of color objects in this parameter must equal the number of rectangles in the rects parameter.

    num

    The number of rectangles in the rects parameter.

    Discussion

    Takes a list of num rectangles and a matching list of color objects. The first rectangle is filled with the first color, the second rectangle with the second color, and so on. There must be an equal number of rectangles and color values. The rectangles are composited using the NSCompositeCopy operator and the order in which the rectangles are filled cannot be guaranteed; therefore, overlapping rectangles may not draw as expected. This function alters the current color of the current graphics state, setting it unpredictably to one of the values passed in colors.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Fills the rectangles in the passed list with the passed list of grays.

    Declaration

    Swift

    func NSRectFillListWithGrays(_ rects: UnsafePointer<NSRect>, _ grays: UnsafePointer<CGFloat>, _ num: Int)

    Objective-C

    void NSRectFillListWithGrays ( const NSRect *rects, const CGFloat *grays, NSInteger num );

    Parameters

    rects

    A pointer to an array of NSRect structures representing the rectangles to fill.

    grays

    A pointer to an array of floating-point values in the range 0.0 to 1.0, where 0.0 represents absolute black and 1.0 represents absolute white and numbers in between are varying levels of gray. Values outside this range are clamped to 0.0 or 1.0.

    num

    The number of rectangles in the rects parameter.

    Discussion

    Takes a list of num rectangles and a matching list of gray values. The first rectangle is filled with the first gray, the second rectangle with the second gray, and so on. There must be an equal number of rectangles and gray values. The rectangles are composited using the NSCompositeCopy operator and the order in which the rectangles are filled cannot be guaranteed; therefore, overlapping rectangles may not draw as expected. This function alters the current color of the current graphics state, setting it unpredictably to one of the values passed in grays.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Fills the rectangles in a list using the current fill color and specified compositing operation.

    Declaration

    Swift

    func NSRectFillListUsingOperation(_ rects: UnsafePointer<NSRect>, _ count: Int, _ op: NSCompositingOperation)

    Objective-C

    void NSRectFillListUsingOperation ( const NSRect *rects, NSInteger count, NSCompositingOperation op );

    Parameters

    rects

    A pointer to an array of NSRect structures representing the rectangles to fill.

    count

    The number of rectangles in the rects parameter.

    op

    The compositing operation to use when filling the rectangles.

    Discussion

    Fills a list of count rectangles with the current fill color, using the compositing operation op. For example, specifying NSCompositeSourceOver will blend with what's already been drawn.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Fills the rectangles in a list using the specified colors and compositing operation.

    Declaration

    Swift

    func NSRectFillListWithColorsUsingOperation(_ rects: UnsafePointer<NSRect>, _ colors: UnsafePointer<NSColor?>, _ num: Int, _ op: NSCompositingOperation)

    Objective-C

    void NSRectFillListWithColorsUsingOperation ( const NSRect *rects, NSColor *const *colors, NSInteger num, NSCompositingOperation op );

    Parameters

    rects

    A pointer to an array of NSRect structures representing the rectangles to fill.

    colors

    A pointer to an array of NSColor objects. The number of color objects in this parameter must equal the number of rectangles in the rects parameter.

    num

    The number of rectangles in the rects parameter.

    op

    The compositing operation to use when filling the rectangles.

    Discussion

    Takes a list of num rectangles and a matching list of color values. The first rectangle is filled with the first color, the second rectangle with the second color, and so on. There must be an equal number of rectangles and color values. Each fill operation is performed using the compositing operation op. The rectangles should not overlap; the order in which they are filled cannot be guaranteed. This function alters the current color of the current graphics state, setting it unpredictably to one of the values passed in colors.

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Fills a rectangle using the current fill color and the specified compositing operation.

    Declaration

    Swift

    func NSRectFillUsingOperation(_ aRect: NSRect, _ op: NSCompositingOperation)

    Objective-C

    void NSRectFillUsingOperation ( NSRect aRect, NSCompositingOperation op );

    Parameters

    aRect

    The rectangle to fill with the current fill color.

    op

    The compositing operation to use when filling the rectangle.

    Discussion

    For a list of compositing operations and how you use them, see Cocoa Drawing Guide.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Specifies how a focus ring will be drawn.

    Declaration

    Swift

    func NSSetFocusRingStyle(_ placement: NSFocusRingPlacement)

    Objective-C

    void NSSetFocusRingStyle ( NSFocusRingPlacement placement );

    Parameters

    placement

    Specifies how you want the focus ring to be drawn.

    Discussion

    Use NSFocusRingAbove to draw the focus ring over an image, use NSFocusRingBelow to draw the focus ring under text, and use NSFocusRingOnly if you don’t have an image or text. For the NSFocusRingOnly case, fills a shape to add the focus ring around the shape.

    Note that the focus ring may actually be drawn outside the view but will be clipped to any clipping superview or the window content view.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.1 and later.

  • Runs a system animation effect.

    Declaration

    Swift

    func NSShowAnimationEffect(_ animationEffect: NSAnimationEffect, _ centerLocation: NSPoint, _ size: NSSize, _ animationDelegate: AnyObject!, _ didEndSelector: Selector, _ contextInfo: UnsafeMutablePointer<Void>)

    Objective-C

    void NSShowAnimationEffect ( NSAnimationEffect animationEffect, NSPoint centerLocation, NSSize size, id animationDelegate, SEL didEndSelector, void *contextInfo );

    Parameters

    animationEffect

    The type of animation you want to apply.

    centerLocation

    The location at which to show the animated image, specified in screen coordinates. The animation is centered on the point you specify.

    size

    The desired size of the animated image. Specify NSZeroSize to perform the animation at the default size.

    animationDelegate

    The object to notify when the animation completes. Specify nil if you do not need to be notified when the animation completes.

    didEndSelector

    The selector of animationDelegate to call when the animation completes. Specify nil if you do not need to be notified when the animation completes. If you specify a selector, the corresponding method should have the following signature:

    • - (void)animationEffectDidEnd:(void *)contextInfo;
    contextInfo

    A pointer to any optional information you want passed as a parameter to the selector in the didEndSelector parameter.

    Discussion

    This function runs one of the standard system animation effects, which includes display and sound. For example, you can use this function to display the puff of smoke effect. For a complete list of animation effects, see NSAnimationEffect.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • NSWindowList NSWindowList (OS X v10.6)

    Gets information about onscreen windows.

    Declaration

    Objective-C

    void NSWindowList ( NSInteger size, NSInteger list[] );

    Discussion

    Provides an ordered list of all onscreen windows. It fills list with up to size window numbers; the order of windows in the array is the same as their order in the window server’s screen list (their front-to-back order on the screen). Use the count obtained by NSCountWindows to specify the size of the array for this function.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Gets information about an application’s onscreen windows.

    Declaration

    Objective-C

    void NSWindowListForContext ( NSInteger context, NSInteger size, NSInteger list[] );

    Discussion

    Provides an ordered list of onscreen windows for a particular application, identified by context, which is a window server connection ID. It fills list with up to size window numbers; the order of windows in the array is the same as their order in the window server’s screen list (their front-to-back order on the screen). Use the count obtained by the NSCountWindowsForContext function to specify the size of the array for this function.

    Use of this function is discouraged as it may be deprecated in a future release.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

  • Returns the available window depth values.

    Declaration

    Swift

    func NSAvailableWindowDepths() -> UnsafePointer<NSWindowDepth>

    Objective-C

    const NSWindowDepth * NSAvailableWindowDepths ( void );

    Discussion

    Returns a null-terminated array of NSWindowDepth—Window Depth values that specify which window depths are currently available. Window depth values are converted to specific display properties using the functions NSBitsPerPixelFromDepth, NSBitsPerSampleFromDepth, NSColorSpaceFromDepth, and NSPlanarFromDepth.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Attempts to return a window depth adequate for the specified parameters.

    Declaration

    Swift

    func NSBestDepth(_ colorSpace: String!, _ bps: Int, _ bpp: Int, _ planar: Bool, _ exactMatch: UnsafeMutablePointer<ObjCBool>) -> NSWindowDepth

    Objective-C

    NSWindowDepth NSBestDepth ( NSString *colorSpace, NSInteger bps, NSInteger bpp, BOOL planar, BOOL *exactMatch );

    Discussion

    Returns a window depth deep enough for the given number of colors in colorSpace, bits per sample specified by bps, bits per pixel specified by bpp, and whether planar as specified by planar. Upon return, the variable pointed to by exactMatch is YEStrue if the window depth can accommodate all of the values specified by the parameters, NOfalse if it can’t.

    Use this function to compute window depths. This function tries to accommodate all the parameters (match or better); if there are multiple matches, it gives the closest, with matching colorSpace first, then bps, then planar, then bpp. bpp is “bits per pixel”; 0 indicates default (same as the number of bits per plane, either bps or bps * NSNumberOfColorComponents); other values may be used as hints to provide backing stores of different configuration; for instance, 8-bit color. The exactMatch parameter is optional and indicates whether all the parameters matched exactly.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the bits per pixel for the specified window depth.

    Declaration

    Swift

    func NSBitsPerPixelFromDepth(_ depth: NSWindowDepth) -> Int

    Objective-C

    NSInteger NSBitsPerPixelFromDepth ( NSWindowDepth depth );

    Discussion

    Returns the number of bits per pixel for the window depth specified by depth.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the bits per sample for the specified window depth.

    Declaration

    Swift

    func NSBitsPerSampleFromDepth(_ depth: NSWindowDepth) -> Int

    Objective-C

    NSInteger NSBitsPerSampleFromDepth ( NSWindowDepth depth );

    Discussion

    Returns the number of bits per sample (bits per pixel in each color component) for the window depth specified by depth.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the name of the color space corresponding to the passed window depth.

    Declaration

    Swift

    func NSColorSpaceFromDepth(_ depth: NSWindowDepth) -> String!

    Objective-C

    NSString * NSColorSpaceFromDepth ( NSWindowDepth depth );

    Discussion

    Returns the color space name for the specified depth. For example, the returned color space name can be NSCalibratedRGBColorSpace, or NSDeviceCMYKColorSpace.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of color components in the specified color space.

    Declaration

    Swift

    func NSNumberOfColorComponents(_ colorSpaceName: String!) -> Int

    Objective-C

    NSInteger NSNumberOfColorComponents ( NSString *colorSpaceName );

    Discussion

    Returns the number of color components in the color space whose name is provided by colorSpaceName.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns whether the specified window depth is planar.

    Declaration

    Swift

    func NSPlanarFromDepth(_ depth: NSWindowDepth) -> Bool

    Objective-C

    BOOL NSPlanarFromDepth ( NSWindowDepth depth );

    Discussion

    Returns YEStrue if the specified window depth is planar and NOfalse if it is not.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an interface style value for the specified key and responder.

    Declaration

    Objective-C

    NSInterfaceStyle NSInterfaceStyleForKey ( NSString *key, NSResponder *responder );

    Discussion

    Used to determine an interface style based on a key and a responder, either of which may be nil. An NSInterfaceStyle value specifies the style in which an interface item, such as a button or a scroll bar, should be drawn. For example, a value of NSMacintoshInterfaceStyle indicates an item should be drawn in the Macintosh style. The values defined for NSInterfaceStyle are NSNoInterfaceStyle, NSNextStepInterfaceStyle, NSWindows95InterfaceStyle, and NSMacintoshInterfaceStyle. Note that this function never returns NSNoInterfaceStyle.

    The interface style value returned by this function depends on several factors. If responder is not nil and if responder specifies an interface style other than NSNoInterfaceStyle, this function returns the responder’s style, and key is ignored.

    Otherwise, if key is not nil and there is an interface style for key specified by the defaults system, this function returns the interface style for key from the defaults system.

    Finally, if key is nil, or if there is no interface style for key specified by the defaults system, this function returns the global interface style specified by the defaults system.

    The defaults system allows an application to customize its behavior to match a user’s preferences. You can read about the defaults system in the documentation for NSUserDefaults.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Tests whether a given object is special marker object used for indicating the state of a selection in relation to a key.

    Declaration

    Swift

    func NSIsControllerMarker(_ Term: AnyObject!) -> Bool

    Objective-C

    BOOL NSIsControllerMarker ( id object );

    Parameters

    Term

    Specify the object you want to check. This parameter can be nil.

    Return Value

    YEStrue if the object is one of the designated controller markers or NOfalse if it is not.

    Discussion

    This function helps you to create bindings between user interface elements and controller objects. The Application Kit predefines several special marker objects used as values for indicating selection state; currently these are NSMultipleValuesMarker, NSNoSelectionMarker, and NSNotApplicableMarker. These markers are typed as id and only exist for the purpose of indicating a state; they are never archived and cannot be used as object values in controls. You use this function to test whether a given object value is a marker, in which case it is not directly assignable to the object that is bound. This check is important, especially since additional markers may be added in the future.

    See the NSKeyValueBinding.h header file for further details.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns global OpenGL options.

    Declaration

    Swift

    func NSOpenGLGetOption(_ pname: NSOpenGLGlobalOption, _ param: UnsafeMutablePointer<GLint>)

    Objective-C

    void NSOpenGLGetOption ( NSOpenGLGlobalOption pname, GLint *param );

    Discussion

    Returns in param the value of the global OpenGL parameter pname. The available options are enumerated by the NSOpenGLGlobalOption type.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the NSOpenGL version numbers.

    Declaration

    Swift

    func NSOpenGLGetVersion(_ major: UnsafeMutablePointer<GLint>, _ minor: UnsafeMutablePointer<GLint>)

    Objective-C

    void NSOpenGLGetVersion ( GLint *major, GLint *minor );

    Discussion

    Returns by reference the major and minor version numbers of the NSOpenGL implementation. This function is not the same as the OpenGL version.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets global OpenGL options.

    Declaration

    Swift

    func NSOpenGLSetOption(_ pname: NSOpenGLGlobalOption, _ param: GLint)

    Objective-C

    void NSOpenGLSetOption ( NSOpenGLGlobalOption pname, GLint param );

    Discussion

    Sets the value of the global OpenGL parameter pname to param. The available options are enumerated by the NSOpenGLGlobalOption type.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Creates and runs an alert sheet.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

    void NSBeginAlertSheet ( NSString *title, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, NSWindow *docWindow, id modalDelegate, SEL didEndSelector, SEL didDismissSelector, void *contextInfo, NSString *msgFormat, ... );

    Discussion

    Creates and runs an alert sheet on docWindow, with the title of title, the text of msg, and buttons with titles of defaultButton, alternateButton, and otherButton.

    The buttons are laid out on the lower-right corner of the sheet, with defaultButton on the right, alternateButton on the left, and otherButton in the middle. If title is nil or an empty string, a default localized title is used (“Alert” in English). If defaultButton is nil or an empty string, a default localized button title (“OK” in English) is used. For the remaining buttons, this function creates them only if their corresponding button title is non-nil.

    A Command-D key equivalent for the “Don’t Save” button is provided, if one is found. The button titles are searched for the localized value for “Don’t Save.” If a match is found, that button is assigned a Command-D key equivalent, provided it is not the default button.

    If you create a modal panel using runModalForWindow: or beginSheet:modalForWindow:modalDelegate:didEndSelector:contextInfo:, you can assign the key equivalent yourself, using setKeyEquivalent: and setKeyEquivalentModifierMask:.

    The msg argument is the message that’s displayed in the panel. It can use printf-style formatting characters; any necessary arguments should be listed at the end of the function’s argument list (after the msg argument). For more information on formatting characters, see the man page for printf.

    When the modal session is ended, and before the sheet is dismissed, the didEndSelector is invoked on the modalDelegate. passing contextInfo. After the sheet is dismissed, the didDismissSelector is invoked on the modalDelegate, passing contextInfo. Typically, you will want to implement the didEndSelector but you may pass NULL for the didDismissSelector. The two selectors should be defined as follows:

    • sheetDidEnd:(NSWindow *)sheet returnCode:(int)returnCode contextInfo:(void *)contextInfo;
    • sheetDidDismiss:(NSWindow *)sheet returnCode:(int)returnCode contextInfo:(void *)contextInfo;

    where sheet is the alert sheet, returnCode specifies which button the user pressed, and contextInfo is the same contextInfo passed into NSBeginAlertSheet. returnCode can be one of the following:

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Creates and runs a critical alert sheet.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

    void NSBeginCriticalAlertSheet ( NSString *title, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, NSWindow *docWindow, id modalDelegate, SEL didEndSelector, SEL didDismissSelector, void *contextInfo, NSString *msgFormat, ... );

    Discussion

    Creates and runs a critical alert sheet on docWindow, with the title of title, the text of msg, and buttons with titles of defaultButton, alternateButton, and otherButton.

    See the description of NSBeginAlertSheet for information on layout, default parameters, and the selectors.

    The sheet 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 OS X Human Interface Guidelines.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Creates and runs an informational alert sheet.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

    void NSBeginInformationalAlertSheet ( NSString *title, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, NSWindow *docWindow, id modalDelegate, SEL didEndSelector, SEL didDismissSelector, void *contextInfo, NSString *msgFormat, ... );

    Discussion

    Creates and runs an informational alert sheet on docWindow, with the title of title, the text of msg, and buttons with titles of defaultButton, alternateButton, and otherButton.

    See the description of NSBeginAlertSheet for information on layout, default parameters, and the selectors.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Returns an alert panel.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

    id NSGetAlertPanel ( NSString *title, NSString *msgFormat, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, ... );

    Discussion

    Returns an NSPanel that can be used to set up a modal session. A modal session is useful for allowing the user to interrupt the program. During a modal session, you can perform activities while the panel is displayed and check at various points in your program whether the user has clicked one of the panel’s buttons. The arguments for this function are the same as those for NSRunAlertPanel, but unlike that function, no button is displayed if defaultButton is nil.

    To set up a modal session, send the Application object beginModalSessionForWindow: with the panel returned by NSGetAlertPanel as its argument. When you want to check if the user has clicked one of the panel’s buttons, use runModalSession:. To end the modal session, use endModalSession:. When you’re finished with the panel created by NSGetAlertPanel, you must dispose of it by passing it to NSReleaseAlertPanel.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Returns an alert panel to display a critical message.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

    id NSGetCriticalAlertPanel ( NSString *title, NSString *msgFormat, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, ... );

    Discussion

    Returns an NSPanel that can be used to set up a modal session. No button is displayed if defaultButton is nil. When you’re finished with the panel created by this function, you must dispose of it by passing it to NSReleaseAlertPanel.

    The arguments for this function are the same as those for the NSGetAlertPanel. For more information on using a panel in a modal session, see NSGetAlertPanel.

    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 OS X Human Interface Guidelines.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Returns an alert panel to display an informational message.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

    id NSGetInformationalAlertPanel ( NSString *title, NSString *msgFormat, NSString *defaultButton, NSString *alternateButton, NSString *otherButton, ... );

    Discussion

    Returns an NSPanel that can be used to set up a modal session. No button is displayed if defaultButton is nil. When you’re finished with the panel created by this function, you must dispose of it by passing it to NSReleaseAlertPanel.

    The arguments for this function are the same as those for the NSRunAlertPanel function. For more information on using a panel in a modal session, see NSGetAlertPanel.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Disposes of an alert panel.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Swift

    func NSReleaseAlertPanel(_ panel: AnyObject!)

    Objective-C

    void NSReleaseAlertPanel ( id panel );

    Discussion

    When you’re finished with a panel created by a function such as NSGetAlertPanel, NSGetCriticalAlertPanel, or NSGetInformationalAlertPanel, you must dispose of it by passing it to this function.

    Note that the alert panel may not be deallocated immediately because it may have internal references that are disposed of in a deferred way. You should not make the assumption that the alert panel is immediately removed from the application window list.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Creates an alert panel.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

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

    Discussion

    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. See the description of NSBeginAlertSheet for information on layout of buttons, default parameters, and possible return values. NSRunAlertPanel runs the panel in a modal event loop.

    A Command-D key equivalent for the “Don’t Save” button is provided, if one is found. The button titles are searched for the localized value for “Don’t Save.” If a match is found, that button is assigned a Command-D key equivalent, provided it is not the default button.

    If you create a modal panel using runModalForWindow: or beginSheet:modalForWindow:modalDelegate:didEndSelector:contextInfo:, you can assign the key equivalent yourself, using setKeyEquivalent: and setKeyEquivalentModifierMask:.

    This function not only creates the panel; it also puts the panel onscreen and runs it using the runModalForWindow: method defined in the NSApplication class. This method sets up a modal event loop that causes the panel to remain onscreen until the user clicks one of its buttons. This function then removes the panel from the screen list and returns a value that indicates which of the three buttons the user clicked. For efficiency, this function creates the panel the first time it’s called and reuses it on subsequent calls, reconfiguring it if necessary.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Creates and runs a critical alert panel.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

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

    Discussion

    Creates a critical alert panel that warns the user of some critical consequence of a requested action; the panel lets the user cancel the action and may allow the user to modify the action. It then runs the panel in a modal event loop.

    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 OS X Human Interface Guidelines.

    The arguments for this function are the same as those for NSRunAlertPanel.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Creates and runs an informational alert panel.

    Deprecation Statement

    Use NSAlert instead.

    Declaration

    Objective-C

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

    Discussion

    Creates an informational alert panel that provides information related to a requested action. It then runs the panel in a modal event loop.

    The arguments for this function are the same as those for NSRunAlertPanel.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.10.

  • Returns a pasteboard type based on the passed file type.

    The file contents pboard type allowed you to synthesize a pboard type for a file’s contents based on the file’s extension. Using the UTI of a file to represent its contents now replaces this functionality.

    Declaration

    Swift

    func NSCreateFileContentsPboardType(_ fileType: String!) -> String!

    Objective-C

    NSString * NSCreateFileContentsPboardType ( NSString *fileType );

    Discussion

    Returns an NSString to a pasteboard type representing a file’s contents based on the supplied string fileType. fileType should generally be the extension part of a filename. The conversion from a named file type to a pasteboard type is simple; no mapping to standard pasteboard types is attempted.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a pasteboard type based on the passed file type.

    The file contents pboard type allowed you to synthesize a pboard type for a file’s contents based on the file’s extension. Using the UTI of a file to represent its contents now replaces this functionality.

    Declaration

    Swift

    func NSCreateFilenamePboardType(_ fileType: String!) -> String!

    Objective-C

    NSString * NSCreateFilenamePboardType ( NSString *fileType );

    Discussion

    Returns an NSString to a pasteboard type representing a filename based on the supplied string fileType.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a file type based on the passed pasteboard type.

    The file contents pboard type allowed you to synthesize a pboard type for a file’s contents based on the file’s extension. Using the UTI of a file to represent its contents now replaces this functionality.

    Declaration

    Swift

    func NSGetFileType(_ pboardType: String!) -> String!

    Objective-C

    NSString * NSGetFileType ( NSString *pboardType );

    Discussion

    This function is the inverse of both NSCreateFileContentsPboardType and NSCreateFilenamePboardType. When passed a pasteboard type as returned by those functions, it returns the extension or filename from which the type was derived. It returns nil if pboardType isn’t a pasteboard type created by those functions.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an array of file types based on the passed pasteboard types.

    The file contents pboard type allowed you to synthesize a pboard type for a file’s contents based on the file’s extension. Using the UTI of a file to represent its contents now replaces this functionality.

    Declaration

    Swift

    func NSGetFileTypes(_ pboardTypes: [AnyObject]!) -> [AnyObject]!

    Objective-C

    NSArray * NSGetFileTypes ( NSArray *pboardTypes );

    Discussion

    Accepts a null-terminated array of pointers to pasteboard types and returns a null-terminated array of the unique extensions and filenames from the file content and filename types found in the input array. It returns nil if the input array contains no file content or filename types. The returned array is allocated and must be freed by the caller. The pointers in the return array point into strings passed in the input array.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

Additional information on sounds can be found in NSSound.

  • Plays the system beep.

    Declaration

    Swift

    func NSBeep()

    Objective-C

    void NSBeep ( void );

    Discussion

    Plays the system beep. Users can select a sound to be played as the system beep. On a Macintosh computer, for example, you can change sounds with the Sound pane of System Preferences.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.