(Preliminary Documentation) Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

Application Kit Functions

Rectangle Drawing Functions

Optimize drawing

void NSEraseRect(NSRect aRect)	Erases the rectangle by filling it with white.  (This does not alter the current drawing color.)
void NSHighlightRect(NSRect aRect)	Highlights or unhighlights a rectangle by switching light gray for white and vice versa, when drawing on the screen.  If not drawing to the screen, the rectangle is filled with light gray.
void NSRectClip(NSRect aRect)	Intersects the current clipping path with the rectangle aRect, to determine a new clipping path. 
void NSRectClipList(const NSRect *rects, 	Takes an array of count number of rectangles and intersects 
int count)		the current clipping path with each of them.  Thus, the new clipping path is the graphic intersection of all the rectangles and the original clipping path. 
void NSRectFill(NSRect aRect)	Fills the rectangle referred to by aRect with the current color. 
void NSRectFillList(const NSRect *rects, 
int count)	Fills an array of count rectangles with the current color.
void NSRectFillListWithGrays(const NSRect *rects, 
const float *grays, int count)	Fills each rectangle in the array rects with the gray whose value is stored at the corresponding location in the array grays.  Both arrays must be count elements long. Avoid  rectangles that overlap, because the order in which they'll be filled can't be guaranteed. 

Draw a bordered rectangle

void NSDrawButton(NSRect aRect, 	Draws the bordered light gray rectangle whose appearance
NSRect clipRect)		signifies a button in the OpenStep user interface. aRect is the bounds for the button, but only the area where aRect intersects clipRect is drawn.
void NSDrawGrayBezel(NSRect aRect, 	Draws a bordered light gray rectangle with the appearance
NSRect clipRect)		of a pushed-in button, clipped by intersecting with clipRect.
void NSDrawGroove(NSRect aRect, 	Draws a  light gray rectangle whose border is a groove, 
NSRect clipRect)		giving the appearance of a typical box in the OpenStep user interface.
NSRect *NSDrawTiledRects(NSRect boundsRect, 	Draws an unfilled rectangle, clipped by clipRect, whose 
NSRect clipRect,   		border is defined by the parallel arrays sides and grays,
const NSRectEdge *sides,		both of length count. Each element of sides specifies an
const float *grays, 		edge of the rectangle, which is drawn with a width of
int count)		1.0 using the corresponding gray level from grays. If the edges array contains recurrences of the same edge, each is inset within the previous edge.
void NSDrawWhiteBezel(NSRect aRect, 	Draws a  white rectangle with a bezeled border. Only the
NSRect clipRect)		area that intersects clipRect is drawn.
void NSFrameRect(NSRect aRect)	Draws a frame of width 1.0 around the inside of a rectangle, using the current color. 
void NSFrameRectWithWidth(NSRect aRect, 	Draws a frame of width frameWidth around the inside of a
float frameWidth)		rectangle, using the current color.

Color Functions

Get information about color space and window depth

int NSBitsPerSampleFromDepth(NSWindowDepth depth)
	Returns the number of bits per sample (bits per pixel in each color component) for the given window depth.
NSString *NSColorSpaceFromDepth(NSWindowDepth depth)
	Returns the name of the color space that matches the given window depth.
BOOL NSGetBestDepth(NSWindowDepth *depth, 	Returns YES if the function can provide, in the depth
int numColors, int bps)		argument, a window depth deep enough for the given number of colors and the given number of bits per sample.
int NSNumberOfColorComponents(NSString *colorSpaceName)
	Returns the number of color components in the named color space.

Read the color at a screen position

NSColor *NSReadPixel(NSPoint location)	Returns the color of the pixel at the given location, which must be specified in the current view's coordinate system.

Text Functions

Filter characters entered into a Text object

unsigned short NSEditorFilter(unsigned short theChar, 
int flags, 	Identical to NSFieldFilter() except that it passes on values
NSStringEncoding theEncoding) 		corresponding to Return, Tab, and Shift-Tab directly to the NSText object.
unsigned short NSFieldFilter(unsigned short theChar, 
int flags, 	Checks each character the user types into an NSText
NSStringEncoding theEncoding)		object's text, allowing the user to move the selection among text fields by pressing Return, Tab, or Shift-Tab. Alphanumeric characters are passed to the NSText object for display. The function returns either  the ASCII value of the character typed, 0 (for illegal characters or ones entered while a Command key is held down), or a constant that the Text object interprets as a movement command.

Calculate or draw a line of text (in Text object)

int NSDrawALine(id self, 	Draws a line of text, using the global variables set by
NSLayInfo *layInfo)		NSScanALine(). The return value has no significance.
int NSScanALine(id self, 	Determines the placement of characters in a line of text. self
NSLayInfo *layInfo)		 refers to the NSText object calling the function, and *layInfo is an NSLayInfo struct.  The function returns 1  if a word's length exceeds the width of a line and the NSText's charWrap instance variable is NO.  Otherwise, it returns 0.

Calculate font ascender, descender, and line height (in Text object)

void NSTextFontInfo(NSFont *font, 	Calculates, and returns by reference, the ascender,
float *ascender, float *descender, 		descender, and line height values for the NSFont given 
float *lineHeight)		by  font.

Access Text object's word tables

NSData * NSDataWithWordTable(const unsigned char *preSelSmart, 
const unsigned char *postSelSmart, 	Given pointers to word table structures, records the
const unsigned char *charClasses, 		structures in the returned NSData object. The
const NSFSM *wrapBreaks, 		arguments are similar to those of
int wrapBreaksCount, 		NSReadWordTable().
const NSFSM *clickBreaks, 
int clickBreaksCount, 
BOOL charWrap) 
void  NSReadWordTable(NSZone *zone, 	Given data, creates word tables in the memory zone
NSData *data, 		specified by zone, returning (in the subsequent 
unsigned char **preSelSmart, 		arguments)  pointers to the various tables. The integer
unsigned char **postSelSmart, 		pointer arguments return the length of the preceding
unsigned char **charClasses, 		array, and charWrap indicates whether words whose
NSFSM **wrapBreaks, 		length exceeds the Text object's line length should be
int *wrapBreaksCount, 		wrapped on a character-by-character basis.
NSFSM **clickBreaks, 
int *clickBreaksCount, 
BOOL *charWrap)

Array allocation functions for use by the NSText class

NSTextChunk *NSChunkCopy(NSTextChunk *pc, 	Copies the array pc to the array dpc and returns a pointer to
NSTextChunk *dpc)		the copy. 
NSTextChunk *NSChunkGrow(NSTextChunk *pc, 	Increases the array identified by the pointer pc to a size of
int newUsed)		newUsed bytes.
NSTextChunk *NSChunkMalloc(int growBy, 	Allocates initial memory for a structure whose  first field is
int initUsed)		an NSTextChunk structure and whose subsequent field is a variable-sized array. The amount of memory allocated is equal to initUsed.  If initUsed is 0, growBy bytes are allocated. growBy specifies how much memory should be allocated when the chunk grows.
NSTextChunk *NSChunkRealloc(NSTextChunk *pc)	
	Increases the amount of memory available for the array identified by the pointer pc, as determined by the array's NSTextChunk.
NSTextChunk *NSChunkZoneCopy(NSTextChunk *pc, 
NSTextChunk *dpc, 	Like NSChunkCopy(), but uses the specified zone of
NSZone *zone)		memory.
NSTextChunk *NSChunkZoneGrow(NSTextChunk *pc,
int newUsed, 	Like NSChunkGrow(), but uses the specified zone of
NSZone *zone)		memory.
NSTextChunk *NSChunkZoneMalloc(int growBy, 	Like NSChunkMalloc(), but uses the specified zone of
int initUsed, 		memory.
NSZone *zone)
NSTextChunk *NSChunkZoneRealloc(NSTextChunk *pc, 
NSZone *zone)	Like NSChunkRealloc(), but uses the specified zone of memory.

Imaging Functions

Copy an image

void  NSCopyBitmapFromGstate(int gstate, 	Copies the pixels in the rectangle srcRect to the rectangle
NSRect srcRect, 		destRect.  The source rectangle is defined in the 
NSRect destRect)	  	graphics state designated by gstate, and the destination is defined in the current graphics state.  
void NSCopyBits(int gstate, 	Copies the pixels in the rectangle aRect to the location
NSRect aRect, 		aPoint.  The source rectangle is defined in the current
NSPoint aPoint)		 graphics state if gstate is NSNullObject; otherwise, in the graphics state designated by gstate.  The aPoint destination is defined in the current graphics state.

Render bitmap images

void NSDrawBitmap(NSRect rect,	Renders an image from a bitmap. rect is the rectangle in
int pixelsWide,		which the image is drawn, and data is the bitmap data,
int pixelsHigh,		stored in up to 5 channels unless isPlanar is NO (in
int bitsPerSample, 		which case the channels are interleaved in a single 
int samplesPerPixel,		array).
int bitsPerPixel,
int bytesPerRow, 
BOOL isPlanar,
BOOL hasAlpha, 
NSString *colorSpaceName, 
const unsigned char *const data[5])

Attention Panel Functions

Create an attention panel without running it yet

id NSGetAlertPanel(NSString *title, 	Returns an NSPanel object that you can use in a modal
NSString *msg, 		session. Unlike NSRunAlertPanel(), no button is
NSString *firstButton, 		displayed if firstButton is NULL.
NSString *alternateButton, 
NSString *otherButton, ...)

Create and run an attention panel

int NSRunAlertPanel(NSString *title, 	Creates an attention panel that alerts the user to some
NSString *msg, 		consequence of a requested action, and runs the panel in
NSString *defaultButton, 		a modal event loop. title is the panel's title (by default, 
NSString *alternateButton, 		ªAlertº); msg is the printf()-style message that's
NSString *otherButton, ...)		displayed in the panel; defaultButton (by default, ªOKº) is the title for the main button, also activated by Return; alternateButton and otherButton give two more choices, which are displayed only if the corresponding argument isn't NULL. The trailing arguments are a variable number of printf()-style arguments to msg.
int NSRunLocalizedAlertPanel(NSString *table, 	Similar to NSRunAlertPanel(), but preferred, as it makes
NSString *title, 		use of OpenStep's localization feature for languages of
NSString *msg, 		different countries.
NSString *defaultButton, 
NSString *alternateButton, 
NSString *otherButton, ...)

Release an attention panel

void NSReleaseAlertPanel(id panel)	Releases the specified alert panel.

Services Menu Functions

Determine whether an item is included in Services menus

int NSSetShowsServicesMenuItem(NSString *item, 
BOOL showService)	Determines (based on the value of showService) whether the item command will be included in other applications' Services menus. item describes a service provided by this application, and should be the same string entered in the ªMenu Item:º field of the services file.  The function returns 0 upon success.
BOOL NSShowsServicesMenuItem(NSString *item)
	Returns YES if item is currently shown in Services menus.

Programmatically invoke a service

BOOL NSPerformService(NSString *item, 	Invokes a service found in the application's Services menu.
NSPasteboard *pboard)		 item is the name of a Services menu item, in any language; a slash in this name represents a submenu.  pboard must contain the data required by the service, and when the function returns, pboard will contain the data supplied by the service provider.

Force Services menu to update based on new services

void NSUpdateDynamicServices(void)	Re-registers the services the application is willing to provide, by reading the file with the extension ª.serviceº in the application path or in the standard path for services.

Other Application Kit Functions

Play the system beep

void NSBeep(void)	Plays the system beep.

Return file-related pasteboard types

NSString *NSCreateFileContentsPboardType(NSString *fileType)
	Returns a string naming a pasteboard type that represents a file's contents, based on the supplied string fileType.  fileType should generally be the extension part of a file name.  The conversion from a named file type to a pasteboard type is simple; no mapping to standard pasteboard types is attempted.
NSString *NSCreateFilenamePboardType(NSString *filename)
	Returns a string naming a pasteboard type that represents a a file name, based on the supplied string filename.  
NSString *NSGetFileType(NSString *pboardType)	
	Returns the extension or file name from which the pasteboard type pboardType was derived.  nil is returned  if pboardType isn't a pasteboard type created by NSCreateFileContentsPboardType() or NSCreateFilenamePboardType().
NSArray *NSGetFileTypes(NSArray *pboardTypes)
	Accepts an array of pasteboard types and returns an array of the unique extensions and file names from the file-content and file-name types found in the input array.  It returns nil if the input array contains no file-content or file-name types.

Draw a distinctive outline around linked data

void  NSFrameLinkRect(NSRect aRect, 	Draws a distinctive link outline just outside the rectangle
BOOL isDestination)	aRect.  To draw an outline around a destination link, isDestination should be YES, otherwise NO. 
float  NSLinkFrameThickness(void)	Returns the thickness of the link outline so that the outline can be properly erased by the application, or for other purposes.

Convert an event mask type to a mask

unsigned int NSEventMaskFromType(NSEventType type)
	Returns the event mask corresponding to type (which is an enumeration constant). The returned mask equals 1 left-shifted by type bits.