| Framework | AppKit/AppKit.h |
| Declared in | NSAccessibility.h NSApplication.h NSCell.h NSEvent.h NSFont.h NSGraphics.h NSInterfaceStyle.h NSKeyValueBinding.h NSOpenGL.h NSPanel.h NSPasteboard.h |
This document describes functions and function-like macros defined in the Application Kit framework.
Additional information on accessibility can be found in NSAccessibility.
NSAccessibilityActionDescription
NSAccessibilityPostNotification
NSAccessibilityRaiseBadArgumentException
NSAccessibilityRoleDescription
NSAccessibilityRoleDescriptionForUIElement
NSAccessibilityUnignoredChildren
NSAccessibilityUnignoredChildrenForOnlyChild
NSAccessibilityUnignoredDescendant
NSAccessibilityUnignoredAncestor
Additional information on NSApplication can be found in NSApplication Class Reference.
NSApplicationLoad
NSApplicationMain
NSPerformService
NSRegisterServicesProvider
NSSetShowsServicesMenuItem
NSShowsServicesMenuItem
NSUnregisterServicesProvider
NSUpdateDynamicServices
NSCopyBits
NSCountWindows
NSCountWindowsForContext
NSDisableScreenUpdates
NSEnableScreenUpdates
NSDottedFrameRect
NSDrawBitmap
NSDrawButton
NSDrawDarkBezel
NSDrawGrayBezel
NSDrawGroove
NSDrawLightBezel
NSDrawThreePartImage
NSDrawNinePartImage
NSDrawTiledRects
NSDrawColorTiledRects
NSDrawWhiteBezel
NSDrawWindowBackground
NSEraseRect
NSFrameRect
NSFrameRectWithWidth
NSFrameRectWithWidthUsingOperation
NSGetWindowServerMemory
NSHighlightRect
NSReadPixel
NSRectClip
NSRectClipList
NSRectFill
NSRectFillList
NSRectFillListWithColors
NSRectFillListWithGrays
NSRectFillListUsingOperation
NSRectFillListWithColorsUsingOperation
NSRectFillUsingOperation
NSSetFocusRingStyle
NSShowAnimationEffect
NSWindowList
NSWindowListForContext
NSAvailableWindowDepths
NSBestDepth
NSBitsPerPixelFromDepth
NSBitsPerSampleFromDepth
NSColorSpaceFromDepth
NSNumberOfColorComponents
NSPlanarFromDepth
NSBeginAlertSheet
NSBeginCriticalAlertSheet
NSBeginInformationalAlertSheet
NSGetAlertPanel
NSGetCriticalAlertPanel
NSGetInformationalAlertPanel
NSReleaseAlertPanel
NSRunAlertPanel
NSRunCriticalAlertPanel
NSRunInformationalAlertPanel
Additional information on sounds can be found in NSSound.
Returns a standard description for an action.
NSString * NSAccessibilityActionDescription ( NSString *action );
This function returns a standard description for action.
NSAccessibility.hSends a notification to any observing assistive applications.
void NSAccessibilityPostNotification ( id element, NSString *notification );
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.
NSAccessibility.hRaises an error if the parameter is the wrong type or has an illegal value
void NSAccessibilityRaiseBadArgumentException ( id element, NSString *attribute, id value );
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.
NSAccessibility.hReturns a standard description for a role and subrole.
NSString * NSAccessibilityRoleDescription ( NSString *role, NSString *subrole );
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.
NSAccessibility.hReturns a standard role description for a user interface element.
NSString * NSAccessibilityRoleDescriptionForUIElement ( id element );
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.
NSAccessibility.hReturns an unignored accessibility object, ascending the hierarchy if necessary.
id NSAccessibilityUnignoredAncestor ( id element );
Tests whether element is an ignored object, returning either element, if it is not ignored, or the first unignored ancestor of element.
NSAccessibility.hReturns a list of unignored accessibility objects, descending the hierarchy if necessary.
NSArray * NSAccessibilityUnignoredChildren ( NSArray *originalChildren );
Returns a copy of originalChildren with any ignored objects in the array replaced by their unignored descendants.
NSAccessibility.hReturns a list of unignored accessibility objects, descending the hierarchy if necessary.
NSArray * NSAccessibilityUnignoredChildrenForOnlyChild ( id originalChild );
Tests whether originalChild is an ignored object and returns an array containing either originalChild, if it is not ignored, or its unignored descendants.
NSAccessibility.hReturns an unignored accessibility object, descending the hierarchy if necessary.
id NSAccessibilityUnignoredDescendant ( id element );
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.
NSAccessibility.hStartup function to call when running Cocoa code from a Carbon application.
BOOL NSApplicationLoad (void);
YES if the NSApplication object was successfully initialized and can now be used from your Carbon application or NO if there was an error during initialization.
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.
NSApplication.hCalled by the main function to create and run the application.
int NSApplicationMain ( int argc, const char *argv[] );
The number of arguments in the argv parameter.
An array of pointers containing the arguments that were passed to the application at startup.
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.
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.
NSApplicationMain itself ignores the argc and argv arguments. Instead, Cocoa gets its arguments indirectly via _NSGetArgv, _NSGetArgc, and _NSGetEnviron (see <crt_externs.h>).
NSApplication.hReturns the available window depth values.
const NSWindowDepth * NSAvailableWindowDepths (void);
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.
NSGraphics.h
Plays the system beep.
void NSBeep (void);
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.
NSGraphics.h
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, ... );
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:
NSAlertDefaultReturn means the user pressed the default button.
NSAlertAlternateReturn means the user pressed the alternate button.
NSAlertOtherReturn means the user pressed the other button.
NSAlertErrorReturn means an error occurred while running the alert panel.
NSPanel.hCreates 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, ... );
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.
NSPanel.hCreates 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, ... );
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.
NSPanel.h
Attempts to return a window depth adequate for the specified parameters.
NSWindowDepth NSBestDepth ( NSString *colorSpace, NSInteger bps, NSInteger bpp, BOOL planar, BOOL *exactMatch );
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 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.
NSGraphics.h
Returns the bits per pixel for the specified window depth.
NSInteger NSBitsPerPixelFromDepth ( NSWindowDepth depth );
Returns the number of bits per pixel for the window depth specified by depth.
NSGraphics.h
Returns the bits per sample for the specified window depth.
NSInteger NSBitsPerSampleFromDepth ( NSWindowDepth depth );
Returns the number of bits per sample (bits per pixel in each color component) for the window depth specified by depth.
NSGraphics.h
Returns the name of the color space corresponding to the passed window depth.
NSString * NSColorSpaceFromDepth ( NSWindowDepth depth );
Returns the color space name for the specified depth. For example, the returned color space name can be NSCalibratedRGBColorSpace, or NSDeviceCMYKColorSpace.
NSGraphics.hPrepares a set of glyphs for processing by character-based routines.
NSInteger NSConvertGlyphsToPackedGlyphs ( NSGlyph *glBuf, NSInteger count, NSMultibyteGlyphPacking packing, char *packedGlyphs );
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.
NSFont.hCopies a bitmap image to the location specified by a destination point.
void NSCopyBits ( NSInteger srcGState, NSRect srcRect, NSPoint destPoint );
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.
NSGraphics.h
Counts the number of onscreen windows.
void NSCountWindows ( NSInteger *count );
On output, this parameter contains the number of onscreen windows.
NSGraphics.h
Counts the number of onscreen windows belonging to a particular application.
void NSCountWindowsForContext ( NSInteger context, NSInteger *count );
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.
NSGraphics.hReturns a pasteboard type based on the passed file type.
NSString * NSCreateFileContentsPboardType ( NSString *fileType );
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.
NSPasteboard.hReturns a pasteboard type based on the passed file type.
NSString * NSCreateFilenamePboardType ( NSString *fileType );
Returns an NSString to a pasteboard type representing a filename based on the supplied string fileType.
NSPasteboard.h
Disables screen updates.
void NSDisableScreenUpdates (void);
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.
NSGraphics.hDraws a bordered rectangle.
void NSDottedFrameRect ( NSRect aRect );
Deprecated. Use a dashed NSBezierPath instead.
NSGraphics.hDraws 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] );
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 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.
NSGraphics.hDraws a gray-filled rectangle representing a user-interface button.
void NSDrawButton ( NSRect aRect, NSRect clipRect );
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.
The clipping rectangle to use during drawing.
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.
NSGraphics.hDraws a colored bordered rectangle.
NSRect NSDrawColorTiledRects ( NSRect boundsRect, NSRect clipRect, const NSRectEdge *sides, NSColor **colors, NSInteger count );
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.
The clipping rectangle to use during drawing.
The sides of the rectangle for which you want to specify custom colors. Each side must have a corresponding entry in the colors parameter.
The colors to draw for each of the edges listed in the sides parameter.
The number of 1.0-unit-wide slices to draw on the specified sides.
The rectangle that lies within the resulting border.
Behaves the same as NSDrawTiledRects except it draws its border using colors from the colors array.
NSGraphics.hDraws a dark gray-filled rectangle with a bezel border.
void NSDrawDarkBezel ( NSRect aRect, NSRect clipRect );
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.
The clipping rectangle to use during drawing.
NSGraphics.hDraws a gray-filled rectangle with a bezel border.
void NSDrawGrayBezel ( NSRect aRect, NSRect clipRect );
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.
The clipping rectangle to use during drawing.
NSGraphics.hDraws a gray-filled rectangle with a groove border.
void NSDrawGroove ( NSRect aRect, NSRect clipRect );
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.
The clipping rectangle to use during drawing.
NSGraphics.hDraws a white-filled rectangle with a bezel border.
void NSDrawLightBezel ( NSRect aRect, NSRect clipRect );
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.
The clipping rectangle to use during drawing.
NSGraphics.hDraws a nine-part tiled image.
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 );
The rectangle (specified in the current coordinate system) in which to draw the images.
The image to display in the top-left corner.
The image used to tile the space between the topLeftCorner and topRightCorner images.
The image to display in the top-right corner.
The image used to tile the space between the topLeftCorner and bottomLeftCorner images.
The image used to tile the center area between the other eight images.
The image used to tile the space between the topRightCorner and bottomRightCorner images.
The image to display in the bottom-left corner.
The image used to tile the space between the bottomLeftCorner and bottomRightCorner images.
The image to display in the bottom-right corner.
The compositing operation to use when rendering the images.
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.
Specify YES if you are drawing the images in a flipped coordinate system; otherwise, specify NO.
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 YES for the flipped parameter adjusts the image’s internal coordinate system to draw it correctly in a flipped environment.
NSCell.hDraws a three-part tiled image.
void NSDrawThreePartImage(NSRect frame, NSImage *startCap, NSImage *centerFill, NSImage *endCap, BOOL vertical, NSCompositingOperation op, CGFloat alphaFraction, BOOL flipped );
The rectangle (specified in the current coordinate system) in which to draw the images.
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.
The image used to tile the space between the startCap and endCap images.
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.
Specify YES if the images should be stacked on top of one another to create a vertically oriented element. Specify NO if the images should be laid out side-by-side to create a horizontally oriented element.
The compositing operation to use when rendering the images.