Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Application Kit Functions Reference

Framework
AppKit/AppKit.h
Declared in
NSAccessibility.h
NSApplication.h
NSEvent.h
NSFont.h
NSGraphics.h
NSInterfaceStyle.h
NSKeyValueBinding.h
NSOpenGL.h
NSPanel.h
NSPasteboard.h

Overview

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

Functions by Task

Accessibility

Additional information on accessibility can be found in NSAccessibility.

Applications

Additional information on NSApplication can be found in NSApplication.

Events

Fonts

Graphics

Graphics-Window Depth

Interface Styles

Key Value Bindings

OpenGL

Panels

Pasteboards

System Beep

Additional information on sounds can be found in NSSound.

Functions

NSAccessibilityActionDescription

Returns a standard description for an action.

NSString * NSAccessibilityActionDescription (
   NSString *action
);

Discussion

This function returns a standard description for action.

Availability
Declared In
NSAccessibility.h

NSAccessibilityPostNotification

Sends a notification to any observing assistive applications.

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.

Availability
Declared In
NSAccessibility.h

NSAccessibilityRaiseBadArgumentException

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

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.

Availability
Declared In
NSAccessibility.h

NSAccessibilityRoleDescription

Returns a standard description for a role and subrole.

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 NSAccessibilityRoleDescription to return a localized role description matching that returned by a standard button.

Availability
Declared In
NSAccessibility.h

NSAccessibilityRoleDescriptionForUIElement

Returns a standard role description for a user interface element.

NSString * NSAccessibilityRoleDescriptionForUIElement (
   id element
);

Discussion

This function is like NSAccessibilityRoleDescription, but it queries element to get the role and subrole. NSAccessibilityRoleDescription 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.

Availability
Declared In
NSAccessibility.h

NSAccessibilityUnignoredAncestor

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

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.

Availability
Declared In
NSAccessibility.h

NSAccessibilityUnignoredChildren

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

NSArray * NSAccessibilityUnignoredChildren (
   NSArray *originalChildren
);

Discussion

Returns a copy of originalChildren with any ignored objects in the array replaced by their unignored descendants.

Availability
Declared In
NSAccessibility.h

NSAccessibilityUnignoredChildrenForOnlyChild

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

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.

Availability
Declared In
NSAccessibility.h

NSAccessibilityUnignoredDescendant

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

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.

Availability
Declared In
NSAccessibility.h

NSApplicationLoad

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

BOOL NSApplicationLoad (
   void
);

Discussion

If NSApplication is not already initialized, initializes it and sets up event handlers for Cocoa. You typically call this before calling other Cocoa code in a plug-in loaded into a primarily Carbon application. A return value of YES indicates that NSApplication was successfully initialized for the Carbon application.

Availability
Declared In
NSApplication.h

NSApplicationMain

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

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

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.

Availability
Declared In
NSApplication.h

NSAvailableWindowDepths

Returns the available window depth values.

const NSWindowDepth * NSAvailableWindowDepths (
   void
);

Discussion

Returns a null-terminated array of NSWindowDepth 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().

Availability
Declared In
NSGraphics.h

NSBeep

Plays the system beep.

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.

Availability
Declared In
NSGraphics.h

NSBeginAlertSheet

Creates and runs an alert sheet.

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

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:

Availability
Declared In
NSPanel.h

NSBeginCriticalAlertSheet

Creates and runs a critical alert sheet.

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

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 Windows chapter of Apple Human Interface Guidelines.

Availability
Declared In
NSPanel.h

NSBeginInformationalAlertSheet

Creates and runs an informational alert sheet.

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

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.

Availability
Declared In
NSPanel.h

NSBestDepth

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

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 YES if the window depth can accommodate all of the values specified by the parameters, NO if it can’t.

Use NSBestDepth to compute window depths. NSBestDepths() 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. exactMatch is optional and indicates whether all the parameters matched exactly.

Availability
Declared In
NSGraphics.h

NSBitsPerPixelFromDepth

Returns the bits per pixel for the specified window depth.

NSInteger NSBitsPerPixelFromDepth (
   NSWindowDepth depth
);

Discussion

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

Availability
Declared In
NSGraphics.h

NSBitsPerSampleFromDepth

Returns the bits per sample for the specified window depth.

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.

Availability
Declared In
NSGraphics.h

NSColorSpaceFromDepth

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

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.

Availability
Declared In
NSGraphics.h

NSConvertGlyphsToPackedGlyphs

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

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.

Availability
Declared In
NSFont.h

NSCopyBits

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

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.

Availability
Declared In
NSGraphics.h

NSCountWindows

Counts the number of onscreen windows.

void NSCountWindows (
   NSInteger *count
);

Discussion

Counts the number of onscreen windows; it returns the number by reference in count.

Availability
Declared In
NSGraphics.h

NSCountWindowsForContext

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

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.

Availability
Declared In
NSGraphics.h

NSCreateFileContentsPboardType

Returns a pasteboard type based on the passed file type.

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.

Availability
Declared In
NSPasteboard.h

NSCreateFilenamePboardType

Returns a pasteboard type based on the passed file type.

NSString * NSCreateFilenamePboardType (
   NSString *fileType
);

Discussion

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

Availability
Declared In
NSPasteboard.h

NSDisableScreenUpdates

Disables screen updates.

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. Multiple NSDisableScreenUpdates calls stack and are popped off the stack by matching NSEnableScreenUpdates calls.

Availability
Declared In
NSGraphics.h

NSDottedFrameRect

Draws a bordered rectangle.

void NSDottedFrameRect (
   NSRect aRect
);

Discussion

Deprecated. Use a dashed NSBezierPath instead.

Availability
See Also
Declared In
NSGraphics.h

NSDrawBitmap

Draws a bitmap image.

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.

The NSDrawBitmap function renders an image from a bitmap, binary data that describes the pixel values for the image (this function replaces NSImageBitmap).

NSDrawBitmap 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 YES 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 NO 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.

Availability
Declared In
NSGraphics.h

NSDrawButton

Draws a bordered rectangle.

void NSDrawButton (
   NSRect aRect,
   NSRect clipRect
);

Discussion

Draws a gray-filled rectangle, used to signify a user-interface button. For an Aqua button, use an NSButton object.

The aRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. 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 aRect that lie within the clipRect, a clipping rectangle, will be drawn.

The rectangle is filled 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.

Availability
Declared In
NSGraphics.h

NSDrawColorTiledRects

Draws a colored bordered rectangle.

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

Discussion

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

Availability
Declared In
NSGraphics.h

NSDrawDarkBezel

Draws a bordered rectangle.

void NSDrawDarkBezel (
   NSRect aRect,
   NSRect clipRect
);

Discussion

Draws a gray-filled rectangle with a bezel border.

Availability
See Also
Declared In
NSGraphics.h

NSDrawGrayBezel

Draws a bordered rectangle.

void NSDrawGrayBezel (
   NSRect aRect,
   NSRect clipRect
);

Discussion

Draws a gray-filled rectangle with a bezel border.

Availability
See Also
Declared In
NSGraphics.h

NSDrawGroove

Draws a bordered rectangle.

void NSDrawGroove (
   NSRect aRect,
   NSRect clipRect
);

Discussion

Draws a gray-filled rectangle with a groove border.

Availability
See Also
Declared In
NSGraphics.h

NSDrawLightBezel

Draws a bordered rectangle.

void NSDrawLightBezel (
   NSRect aRect,
   NSRect clipRect
);

Discussion

Draws a white-filled rectangle with a bezel border.

Availability
See Also
Declared In
NSGraphics.h

NSDrawTiledRects

Draws rectangles with borders.

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

Discussion

Draws rectangles with borders. NSDrawTiledRects is a generic function that can be used to draw different types of borders. 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 boundsRect argument specifies the rectangle within which the border is to be drawn in the current coordinate system. 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 aRect that lie within clipRect, a clipping rectangle, will be drawn.

In addition to its boundsRect and clipRect arguments, NSDrawTiledRects takes three more arguments, which determine how thick the border is and what gray levels are used to form it. NSDrawTiledRects works through the NSDivideRect function to take successive 1.0-unit-wide slices from the sides of the rectangle specified by the sides argument. Each slice is then drawn using the corresponding gray level from grays. NSDrawTiledRects makes and draws these slices count number of times. NSDivideRect returns a pointer to the rectangle after the slice has been removed; therefore, if a side is used more than once, the second slice is made inside the first. This fact also makes it easy to fill in the rectangle inside of the border.

In the following example, NSDrawTiledRects draws 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 rectangle inside this border is 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);

As shown, 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.

NSDrawTiledRects returns a rectangle that lies within the border.

Availability
Declared In
NSGraphics.h

NSDrawWhiteBezel

Draw a bordered rectangle.

void NSDrawWhiteBezel (
   NSRect aRect,
   NSRect clipRect
);

Discussion

Draws a white-filled rectangle with a bezel border.

Availability
See Also
Declared In
NSGraphics.h

NSDrawWindowBackground

Draw the window’s background.

void NSDrawWindowBackground (
   NSRect aRect
);

Discussion

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

Availability
Declared In
NSGraphics.h

NSEnableScreenUpdates

Enables screen updates

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. Multiple NSEnableScreenUpdates calls pop matching NSDisableScreenUpdates calls off a stack.

Availability
Declared In
NSGraphics.h

NSEraseRect

Erases the passed rect by filling it with white.

void NSEraseRect (
   NSRect aRect
);

Discussion

As its name suggests, NSEraseRect erases the rectangle referred to by its argument, filling it with white. It does not alter the current color.

Availability
Declared In
NSGraphics.h

NSEventMaskFromType

Returns the event mask for the specified type.

static NSUInteger NSEventMaskFromType (
   NSEventType type
);

Discussion

Returns the event mask corresponding to the specified type (an enumerated constant). The returned mask is equal to 1 left-shifted by type bits.

Availability
Declared In
NSEvent.h

NSFrameRect

Draw a bordered rectangle.

void NSFrameRect (
   NSRect aRect
);

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.

Availability
See Also
Declared In
NSGraphics.h

NSFrameRectWithWidth

Draw a bordered rectangle.

void NSFrameRectWithWidth (
   NSRect aRect,
   CGFloat frameWidth
);

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.

Availability
See Also
Declared In
NSGraphics.h

NSFrameRectWithWidthUsingOperation

Draw a bordered rectangle using the specified compositing operation.

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

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.

Availability
Declared In
NSGraphics.h

NSGetAlertPanel

Returns an alert panel.

id NSGetAlertPanel (
   NSString *title,
   NSString *msg,
   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 free it by passing it to NSReleaseAlertPanel.

Availability
Declared In
NSPanel.h

NSGetCriticalAlertPanel

Returns an alert panel to display a critical message.

id NSGetCriticalAlertPanel (
   NSString *title,
   NSString *msg,
   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 NSGetCriticalAlertPanel, you must free 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 Windows chapter of Apple Human Interface Guidelines.

Availability
Declared In
NSPanel.h

NSGetFileType

Returns a file type based on the passed pasteboard type.

NSString * NSGetFileType (
   NSString *pboardType
);

Discussion

NSGetFileType 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.

Availability
Declared In
NSPasteboard.h

NSGetFileTypes

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

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.

Availability
Declared In
NSPasteboard.h

NSGetInformationalAlertPanel

Returns an alert panel to display an informational message.

id NSGetInformationalAlertPanel (
   NSString *title,
   NSString *msg,