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.

• - (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.

• - (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.

• - (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.

• - (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.

• - (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.

• - (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.

• - (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.

• - (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.

• - (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.

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

• - (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.

• - (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.

• - (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.

• - (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.

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