Return to Contents
Copyright (c) 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

const NSWindowDepth *NSAvailableWindowDepths(void)

Returns a zero-terminated list of available window depths.

NSWindowDepth NSBestDepth(NSString *colorSpace,

int bitsPerSample, int bitsPerPixel, Returns a window depth deep enough for the given number

BOOL planar, BOOL *exactMatch) of colors, bits per sample, bits per pixel, and if planar. Upon return, the variable pointed to by exactMatch is YES if the window depth can accommodate all of the values given for all of the parameters, NO if not.

int NSBitsPerPixelFromDepth(NSWindowDepth depth)

Returns the number of bits per pixel for the given 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.

int NSNumberOfColorComponents(NSString *colorSpaceName)

Returns the number of color components in the named color space.

BOOL NSPlanarFromDepth(NSWindowDepth depth)

Returns YES if the given window depth is planar, NO if not.

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(id fid, 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 *smartLeft,

const unsigned char *smartRight, 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 **smartLeft, arguments) pointers to the various tables. The integer

unsigned char **smartRight, pointer arguments return the length of the preceding

unsigned char **charClasses, array, and charWrap indicates whether words whose

NSFSM **wrapBreaks, length exceeds the NSText object's line length should

int *wrapBreaksCount, be 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 srcGstate, 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 srcGstate, and the destination is defined in the current graphics state.

void NSCopyBits(int srcGstate, Copies the pixels in the rectangle srcRect to the location

NSRect srcRect, destPoint. The source rectangle is defined in the current

NSPoint destPoint) graphics state if srcGstate is NSNullObject; otherwise, in the graphics state designated by srcGstate. The destPoint 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 *defaultButton, displayed if defaultButton 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.