Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSMatrix 

Inherits From:	NSControl : NSView : NSResponder : NSObject

Conforms To:	NSCoding (NSResponder)
NSObject (NSObject)

Declared In:	AppKit/NSMatrix.h 

Class Description

NSMatrix is a class used for creating groups of NSCells that work together in various ways. It includes methods for arranging NSCells in rows and columns, either with or without space between them. NSCells in an NSMatrix are numbered by row and column, each starting with 0; for example, the top left NSCell would be at (0, 0), and the NSCell that's second down and third across would be at (1, 2). 

The cell objects that an NSMatrix contains are usually of a single subclass of NSCell, but they can be of multiple subclasses of NSCell. The only restriction is that all cell objects must be the same size. An NSMatrix can be set up to create new NSCells by copying a prototype object, or by allocating and initializing instances of a specific NSCell class.

An NSMatrix adds to NSControl's target/action paradigm by allowing a separate target and action for each of its NSCells in addition to its own target and action. It also allows for an action message that's sent when the user double-clicks an NSCell, and which is sent in addition to the single-click action message. If an NSCell doesn't have an action, the NSMatrix sends its own action to its own target. If an NSCell doesn't have a target, the NSMatrix sends the NSCell's action to its own target. The double-click action of an NSMatrix is always sent to the target of the NSMatrix.

Since the user might press the mouse button while the cursor is within the NSMatrix and then drag the mouse around, NSMatrix offers four ªselection modesº that determine how NSCells behave when the NSMatrix is tracking the mouse:

·	NSTrackModeMatrix is the most basic mode of operation. In this mode the NSCells are asked to track the mouse with trackMouse:inRect:ofView:untilMouseUp: whenever the mouse is inside their bounds. No highlighting is performed. An example of this mode might be a ªgraphic equalizerº NSMatrix of sliders, where moving the mouse around causes the sliders to move under the mouse.

·	NSHighlightModeMatrix is a modification of NSTrackModeMatrix. In this mode, an NSCell is highlighted before it's asked to track the mouse, then unhighlighted when it's done tracking. This is useful for multiple unconnected NSCells that use highlighting to inform the user that they are being tracked (like push-buttons and switches).

·	NSRadioModeMatrix is used when you want no more than one NSCell to be selected at a time. It can be used to create a set of buttons of which one and only one is selected (there's the option of allowing no button to be selected). Any time an NSCell is selected, the previously selected NSCell is unselected. The canonical example of this mode is a set of radio buttons.

·	NSListModeMatrix is the opposite of NSTrackModeMatrix. NSCells are highlighted, but don't track the mouse. This mode can be used to select a range of text values, for example. NSMatrix supports the standard multiple-selection paradigms of dragging to select, using the shift key to make discontinuous selections, and using the alternate key to extend selections.

Initializing the NSMatrix Class 

+ (Class)cellClass	Returns the default class used to make cells.

+ (void)setCellClass:(Class)classId	Sets the default class used to make cells.

Initializing an NSMatrix Object

- (id)initWithFrame:(NSRect)frameRect	Initializes a new NSMatrix object in frameRect.

- (id)initWithFrame:(NSRect)frameRect	Initializes a new NSMatrix object in frameRect, with
mode:(int)aMode		aMode as the selection mode, classId as the class used
cellClass:(Class)classId		to make new cells, and having rowsHigh rows and
numberOfRows:(int)rowsHigh		colsWide columns.
numberOfColumns:(int)colsWide

- (id)initWithFrame:(NSRect)frameRect	Initializes a new NSMatrix object with the given values
mode:(int)aMode		with aMode as the selection mode, aCell as the
prototype:(NSCell *)aCell		prototype copied to make new cells, and having
numberOfRows:(int)rowsHigh		rowsHigh rows and colsWide columns.
numberOfColumns:(int)colsWide

Setting the Selection Mode 

- (NSMatrixMode)mode	Returns the selection mode of the matrix.

- (void)setMode:(NSMatrixMode)aMode	Sets the selection mode of the matrix.

Configuring the NSMatrix 

- (BOOL)allowsEmptySelection	Returns whether it's possible to have no cells selected.

- (BOOL)isSelectionByRect	Returns whether a user can drag a rectangular selection.

- (void)setAllowsEmptySelection:(BOOL)flag	Sets whether it's possible to have no cells selected.

- (void)setSelectionByRect:(BOOL)flag	Sets whether a user can drag a rectangular selection (the default is YES). If flag is NO, selection is on a row-by-row basis.

Setting the Cell Class 

- (Class)cellClass	Returns the subclass of NSCell used to make new cells.

- (id)prototype	Returns the prototype cell copied to make new cells.

- (void)setCellClass:(Class)classId	Sets the subclass of NSCell used to make new cells.

- (void)setPrototype:(NSCell *)aCell	Sets the prototype cell copied to make new cells.

Laying Out the NSMatrix 

- (void)addColumn	Adds a new column of cells to the right of the last column.

- (void)addColumnWithCells:(NSArray *)cellArray	Adds a new column of cells, using those contained in cellArray.

- (void)addRow	Adds a new row of cells below the last row.

- (void)addRowWithCells:(NSArray *)cellArray	Adds a new row of cells, using those contained in cellArray.

- (NSRect)cellFrameAtRow:(int)row	Returns the frame rectangle of the cell at row and column.
column:(int)column

- (NSSize)cellSize	Returns the width and height of cells in the matrix.

- (void)getNumberOfRows:(int *)rowCount	Gets the number of rows and columns in the matrix.
columns:(int *)columnCount

- (void)insertColumn:(int)column	Inserts a new column of cells at column, creating as many as needed to make the matrix column columns wide.

- (void)insertColumn:(int)column withCells:(NSArray *)cellArray
	Inserts a new row of cells at column, using those contained in cellArray.

- (void)insertRow:(int)row	Inserts a new row of cells at row, creating as many as needed to make the matrix row rows wide.

- (void)insertRow:(int)row withCells:(NSArray *)cellArray
	Inserts a new row of cells at row, using those contained in cellArray.

- (NSSize)intercellSpacing	Returns the vertical and horizontal spacing between cells

- (NSCell *)makeCellAtRow:(int)row	Creates a new cell at row, column in the matrix and returns 
column:(int)column		it.

- (void)putCell:(NSCell *)newCell	Replaces the cell at row and column with newCell.
atRow:(int)row
column:(int)column

- (void)removeColumn:(int)column	Removes the column at column, releasing the cells.

- (void)removeRow:(int)row	Removes the row at row, releasing the cells.

- (void)renewRows:(int)newRows	Changes the number of rows and columns in the receiver
columns:(int)newColumns		without freeing any cells.

- (void)setCellSize:(NSSize)aSize	Sets the width and height of all cells in the matrix.

- (void)setIntercellSpacing:(NSSize)aSize	Sets the vertical and horizontal spacing between cells.

- (void)sortUsingFunction:(int (*)(id element1, id element2, void *userData))comparator
context:(void *)context	Sorts the receiver's cells in ascending order as defined by the comparison function comparator. context is passed as the function's third argument.

- (void)sortUsingSelector:(SEL)comparator	Sorts the receiver's cells in ascending order as defined by the comparison method comparator.

Finding Matrix Coordinates 

- (BOOL)getRow:(int *)row	Gets the row and column position corresponding to aPoint.
column:(int *)column		Returns YES if aPoint is within the matrix; 
forPoint:(NSPoint)aPoint 		NO otherwise.

- (BOOL)getRow:(int *)row	Gets the row and column position of aCell.
column:(int *)column		Returns YES if aCell is in the matrix; NO otherwise.
ofCell:(NSCell *)aCell

Modifying Individual Cells 

- (void)setState:(int)value	Sets the state of the cell at row and column to value.
atRow:(int)row
column:(int)column

Selecting Cells 

- (void)deselectAllCells	Clears the receiver's selection, assuming that the NSMatrix allows an empty selection.

- (void)deselectSelectedCell	Deselects the selected cell.

- (void)selectAll:(id)sender	Selects all the cells in the matrix.

- (void)selectCellAtRow:(int)row	Selects the cell at row and col.
column:(int)column

- (BOOL)selectCellWithTag:(int)anInt	Selects the cell with the tag anInt.

- (id)selectedCell	Returns the most recently selected cell or nil if no cell has been selected.

- (NSArray *)selectedCells	Returns an array containing the selected cells.

- (int)selectedColumn	Returns the column of the selected cell or -1 if no column has been selected.

- (int)selectedRow	Returns the row of the selected cell or -1 if no row has been selected.

- (void)setSelectionFrom:(int)startPos	Selects the cells in the matrix from startPos to endPos,
to:(int)endPos		counting in row order from the upper left, as though
anchor:(int)anchorPos		anchorPos were the number of the last cell selected, and
highlight:(BOOL)flag		highlighting the cells according to flag.

Finding Cells 

- (id)cellAtRow:(int)row	Returns the cell at row row and column col.
column:(int)column

- (id)cellWithTag:(int)anInt	Returns the cell having anInt as its tag.

- (NSArray *)cells	Returns the matrix's array of cells.

Modifying Graphic Attributes 

- (NSColor *)backgroundColor	Returns the color of the background between cells.

- (NSColor *)cellBackgroundColor	Returns the color of the background within cells.

- (BOOL)drawsBackground	Returns whether the receiver draws the background between cells.

- (BOOL)drawsCellBackground	Returns whether the receiver draws the background within cells.

- (void)setBackgroundColor:(NSColor *)aColor	Sets the color of the background between cells to aColor.

- (void)setCellBackgroundColor:(NSColor *)aColor
	Sets the color of the background within cells to aColor.

- (void)setDrawsBackground:(BOOL)flag	Sets whether the receiver draws the background between cells.

- (void)setDrawsCellBackground:(BOOL)flag	Sets whether the receiver draws the background within cells.

Editing Text in Cells 

- (void)selectText:(id)sender	Selects the text in the first or last editable cell.

- (id)selectTextAtRow:(int)row	Selects the text of the cell at row, column in the matrix.
column:(int)column

- (void)textDidBeginEditing:(NSNotification *)notification
	Invoked when there's a change in the text after the receiver gains first responder status. Default behavior is pass to this message on to the text delegate. This method posts the NSControlTextDidBeginEditingNotification notification with the receiving object and, in the notification's dictionary, the text object (with the key NSFieldEditor) to the default notification center.

- (void)textDidChange:(NSNotification *)notification	
	Invoked upon a key-down event or paste operation that changes the receiver's contents. Default behavior is to pass this message on to the text delegate. This method posts the NSControlTextDidChangeNotification notification with the receiving object and, in the notification's dictionary, the text object (key NSFieldEditor) to the default notification center.

- (void)textDidEndEditing:(NSNotification *)notification
	Invoked when text editing ends and then forwarded to the text delegate.  This method posts the notification NSControlTextDidEndEditingNotification with the receiving object and, in the notification's dictionary, the text object (with the key NSFieldEditor) to the default notification center.

- (BOOL)textShouldBeginEditing:(NSText *)textObject	 
	Invoked to let the NSTextField respond to impending changes to its text and then forwarded to the text delegate.

- (BOOL)textShouldEndEditing:(NSText *)textObject	
	Invoked to let the NSTextField respond to impending loss of first responder status and then forwarded to the text delegate.

Setting Tab Key Behavior 

- (id)nextText	Returns the object to be selected when the user presses Tab while editing the last text cell.

- (id)previousText	Returns the object to be selected when the user presses Shift-Tab while editing the first text cell.

- (void)setNextText:(id)anObject	Sets the object to be selected when the user presses Tab while editing the last text cell.

- (void)setPreviousText:(id)anObject	Sets the object to be selected when user presses Shift-Tab while editing the first text cell.

Assigning a Delegate 

- (void)setDelegate:(id)anObject	Sets the delegate for messages from the field editor.

- (id)delegate	Returns the delegate for messages from the field editor.

Resizing the Matrix and Cells 

- (BOOL)autosizesCells	Returns whether the matrix resizes its cells automatically.

- (void)setAutosizesCells:(BOOL)flag	Sets whether the matrix resizes its cells automatically.

- (void)setValidateSize:(BOOL)flag	Sets whether the cell size needs to be recalculated.

- (void)sizeToCells	Resizes the matrix to fit its cells exactly.

Scrolling 

- (BOOL)isAutoscroll	Returns whether the matrix automatically scrolls when dragged in.

- (void)scrollCellToVisibleAtRow:(int)row	Scrolls the matrix so that the cell at row and column is
column:(int)column		visible.

- (void)setAutoscroll:(BOOL)flag	Sets whether the matrix automatically scrolls when dragged in.

- (void)setScrollable:(BOOL)flag	If flag is YES, makes all the cells scrollable.

Displaying 

- (void)drawCellAtRow:(int)row	Displays the cell at row and col.
column:(int)column	

- (void)highlightCell:(BOOL)flag	Highlights (or unhighlights) the cell at row, col.
atRow:(int)row
column:(int)column

Target and Action 

- (SEL)doubleAction	Returns the action method for double clicks.

- (void)setDoubleAction:(SEL)aSelector	Sets the action method used on double-clicks to aSelector.

- (SEL)errorAction	Returns the action method for editing errors.

- (BOOL)sendAction	Sends the selected cell's action, or the NSMatrix's action if the cell doesn't have one.

- (void)sendAction:(SEL)aSelector	Sends aSelector to anObject, for all cells if flag is YES.
to:(id)anObject
forAllCells:(BOOL)flag

- (void)sendDoubleAction	Sends the action corresponding to a double-click.

- (void)setErrorAction:(SEL)aSelector	Sets the action method for editing errors to aSelector.

Handling Event and Action Messages 

- (BOOL)acceptsFirstMouse:(NSEvent *)theEvent	Returns NO only if receiver's mode is NSListModeMatrix.

- (void)mouseDown:(NSEvent *)theEvent	Responds to a mouse-down event. A mouse-down event in a text cell initials editing mode. A double-click in any cell type except a text cell sends the double-click action of the NSMatrix (if there is one) in addition to the single-click action.

- (int)mouseDownFlags	Returns the event flags in effect at start of tracking. 

- (BOOL)performKeyEquivalent:(NSEvent *)theEvent
	Simulates a mouse click in the appropriate cell.

Managing the Cursor 

- (void)resetCursorRects	Resets cursor rectangles so that the cursor becomes an I-beam over text cells.