---

NSMatrix Class Reference

Overview

NSMatrix is a class used for creating groups of NSCell objects that work together in various ways.

The cells in an NSMatrix object 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 NSMatrix class has the notion of a single selected cell, which is the cell that was most recently clicked or that was so designated by a selectCellAtRow:column: or selectCellWithTag: message. The selected cell is the cell chosen for action messages except for performClick: (NSCell), which is assigned to the key cell. (The key cell is generally identical to the selected cell, but can be given click focus while leaving the selected cell unchanged.) If the user has selected multiple cells, the selected cell is the one lowest and furthest to the right in the matrix of cells.

Tasks

Initializing an NSMatrix Object

• – initWithFrame:
• – initWithFrame:mode:cellClass:numberOfRows:numberOfColumns:
• – initWithFrame:mode:prototype:numberOfRows:numberOfColumns:

Configuring the Matrix Object

• – setMode:
• – mode
• – setAllowsEmptySelection:
• – allowsEmptySelection
• – setSelectionByRect:
• – isSelectionByRect

Managing the Cell Class

• – setCellClass:
• – cellClass
• – setPrototype:
• – prototype

Laying Out the Cells of the Matrix

• – addColumn
• – addColumnWithCells:
• – addRow
• – addRowWithCells:
• – cellFrameAtRow:column:
• – cellSize
• – getNumberOfRows:columns:
• – insertColumn:
• – insertColumn:withCells:
• – insertRow:
• – insertRow:withCells:
• – intercellSpacing
• – makeCellAtRow:column:
• – numberOfColumns
• – numberOfRows
• – putCell:atRow:column:
• – removeColumn:
• – removeRow:
• – renewRows:columns:
• – setCellSize:
• – setIntercellSpacing:
• – sortUsingFunction:context:
• – sortUsingSelector:

Finding Matrix Coordinates

• – getRow:column:forPoint:
• – getRow:column:ofCell:

Managing Attributes of Individual Cells

• – setState:atRow:column:
• – setToolTip:forCell:
• – toolTipForCell:

Selecting and Deselecting Cells

• – selectCellAtRow:column:
• – selectCellWithTag:
• – selectAll:
• – setKeyCell:
• – keyCell
• – setSelectionFrom:to:anchor:highlight:
• – deselectAllCells
• – deselectSelectedCell

Finding Cells

• – selectedCell
• – selectedCells
• – selectedColumn
• – selectedRow
• – cellAtRow:column:
• – cellWithTag:
• – cells

Modifying Graphics Attributes

• – backgroundColor
• – cellBackgroundColor
• – drawsBackground
• – drawsCellBackground
• – setBackgroundColor:
• – setCellBackgroundColor:
• – setDrawsBackground:
• – setDrawsCellBackground:

Editing Text in Cells

• – selectText:
• – selectTextAtRow:column:
• – textShouldBeginEditing:
• – textDidBeginEditing:
• – textDidChange:
• – textShouldEndEditing:
• – textDidEndEditing:

Setting Tab Key Behavior

• – setTabKeyTraversesCells:
• – tabKeyTraversesCells

Managing the Delegate

• – delegate
• – setDelegate:

Resizing the Matrix and Its Cells

• – setAutosizesCells:
• – autosizesCells
• – setValidateSize:
• – sizeToCells

Scrolling Cells in the Matrix

• – setAutoscroll:
• – isAutoscroll
• – setScrollable:
• – scrollCellToVisibleAtRow:column:

Displaying and Highlighting Cells

• – drawCellAtRow:column:
• – highlightCell:atRow:column:

Managing and Sending Action Messages

• – sendAction
• – sendAction:to:forAllCells:
• – setDoubleAction:
• – doubleAction
• – sendDoubleAction

Handling Event and Action Messages

• – acceptsFirstMouse:
• – mouseDown:
• – mouseDownFlags
• – performKeyEquivalent:

Managing the Cursor

• – resetCursorRects

Instance Methods

acceptsFirstMouse:

Returns a Boolean value indicating whether the receiver accepts the first mouse.

- (BOOL)acceptsFirstMouse:(NSEvent *)theEvent

Parameters

theEvent

This parameter is ignored.

Return Value

NO if the selection mode of the receiver is NSListModeMatrix, YES if the receiver is in any other selection mode. The receiver does not accept first mouse in NSListModeMatrix to prevent the loss of multiple selections.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – mode

Declared In

NSMatrix.h

addColumn

Adds a new column of cells to the right of the last column.

- (void)addColumn

Discussion

This method raises an NSRangeException if there are 0 rows or 0 columns. This method creates new cells as needed with makeCellAtRow:column:. Use renewRows:columns: to add new cells to an empty matrix.

If the number of rows or columns in the receiver has been changed with renewRows:columns:, new cells are created only if they are needed. This fact allows you to grow and shrink an NSMatrix without repeatedly creating and freeing the cells.

This method redraws the receiver. Your code may need to send sizeToCells after sending this method to resize the receiver to fit the newly added cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cellClass
• – insertColumn:
• – prototype
• – addRow

Declared In

NSMatrix.h

addColumnWithCells:

Adds a new column of cells to the right of the last column, using the given cells.

- (void)addColumnWithCells:(NSArray *)newCells

Parameters

newCells

An array of objects to use when filling the new column starting with the object at index 0. Each object in should be an instance of NSCell or one of its subclasses (usually NSActionCell). The array should have a sufficient number of cells to fill the entire column. Extra cells are ignored, unless the matrix is empty. In that case, a matrix is created with one column and enough rows for all the elements of newCells.

Discussion

This method redraws the receiver. Your code may need to send sizeToCells after sending this method to resize the receiver to fit the newly added cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – insertColumn:withCells:
• – addRowWithCells:

Declared In

NSMatrix.h

addRow

Adds a new row of cells below the last row.

- (void)addRow

Discussion

New cells are created as needed with makeCellAtRow:column:. This method raises an NSRangeException if there are 0 rows or 0 columns. Use renewRows:columns: to add new cells to an empty matrix.

If the number of rows or columns in the receiver has been changed with renewRows:columns:, then new cells are created only if they are needed. This fact allows you to grow and shrink an NSMatrix without repeatedly creating and freeing the cells.

This method redraws the receiver. Your code may need to send sizeToCells after sending this method to resize the receiver to fit the newly added cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cellClass
• – insertRow:
• – prototype
• – addColumn

Declared In

NSMatrix.h

addRowWithCells:

Adds a new row of cells below the last row, using the specified cells.

- (void)addRowWithCells:(NSArray *)newCells

Parameters

newCells

An array of objects to use to fill the new row, starting with the object at index 0. Each object should be an instance of NSCell or one of its subclasses (usually NSActionCell). The array should contain a sufficient number of cells to fill the entire row. Extra cells are ignored, unless the matrix is empty. In that case, a matrix is created with one row and enough columns for all the elements of newCells.

Discussion

This method redraws the receiver. Your code may need to send sizeToCells after sending this method to resize the receiver to fit the newly added cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – insertRow:withCells:
• – addColumnWithCells:

Declared In

NSMatrix.h

allowsEmptySelection

Returns a Boolean value indicating whether a radio-mode matrix supports an empty selection.

- (BOOL)allowsEmptySelection

Return Value

YES if it is possible to have no cells selected in a radio-mode matrix; otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – mode
• – setAllowsEmptySelection:

Declared In

NSMatrix.h

autosizesCells

Returns a Boolean value indicating whether the matrix automatically resizes it cells.

- (BOOL)autosizesCells

Return Value

YES if cells are resized proportionally to the receiver when its size changes (and intercell spacing is kept constant). NO if the cell size and intercell spacing remain constant.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setAutosizesCells:

Declared In

NSMatrix.h

backgroundColor

Returns the background color of the matrix.

- (NSColor *)backgroundColor

Return Value

The color used to draw the background of the receiver (the space between the cells).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cellBackgroundColor
• – drawsBackground
• – setBackgroundColor:

Declared In

NSMatrix.h

cellAtRow:column:

Returns the cell at the specified row and column.

- (id)cellAtRow:(NSInteger)row column:(NSInteger)column

Parameters

row

The number of the row containing the cell to return.

column

The number of the column containing the cell to return.

Return Value

The NSCell object at the specified row and column location specified, or nil if either row or column is outside the bounds of the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – getRow:column:ofCell:

Declared In

NSMatrix.h

cellBackgroundColor

Returns the background color of the matrix's cells.

- (NSColor *)cellBackgroundColor

Return Value

The color used to fill the background of the receiver's cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – backgroundColor
• – drawsCellBackground
• – setCellBackgroundColor:

Declared In

NSMatrix.h

cellClass

Returns the class that the matrix uses to create new cells.

- (Class)cellClass

Return Value

The subclass of NSCell that the receiver uses when creating new (empty) cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – prototype
• – makeCellAtRow:column:
• – setCellClass:

Declared In

NSMatrix.h

cellFrameAtRow:column:

Returns the frame rectangle of the cell that would be drawn at the specified location.

- (NSRect)cellFrameAtRow:(NSInteger)row column:(NSInteger)column

Parameters

row

The row of the cell.

column

The column of the cell.

Return Value

The frame rectangle of the cell (whether or not the specified cell actually exists).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cellSize

Declared In

NSMatrix.h

cells

Returns the cells of the matrix.

- (NSArray *)cells

Return Value

An array containing the cells of the receiver.

Discussion

The cells in the array are row-ordered; that is, the first row of cells appears first in the array, followed by the second row, and so forth.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cellAtRow:column:

Declared In

NSMatrix.h

cellSize

Returns the size of each cell in the matrix.

- (NSSize)cellSize

Return Value

The width and height of each cell in the receiver (all cells in an NSMatrix are the same size).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cellFrameAtRow:column:
• – intercellSpacing
• – setCellSize:

Declared In

NSMatrix.h

cellWithTag:

Searches the receiver and returns the last cell matching the specified tag.

- (id)cellWithTag:(NSInteger)anInt

Parameters

anInt

The tag of the cell to return.

Return Value

The last (when viewing the matrix as a row-ordered array) NSCell object that has a tag matching anInt, or nil if no such cell exists

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – selectCellWithTag:
• – setTag: (NSActionCell)

Declared In

NSMatrix.h

delegate

Returns the delegate for messages from the field editor.

- (id)delegate

Return Value

The delegate.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – textShouldBeginEditing:
• – textShouldEndEditing:
• – setDelegate:

Declared In

NSMatrix.h

deselectAllCells

Deselects all cells in the receiver and, if necessary, redisplays the receiver.

- (void)deselectAllCells

Discussion

If the selection mode is NSRadioModeMatrix and empty selection is not allowed, this method does nothing.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – allowsEmptySelection
• – mode
• – selectAll:

Declared In

NSMatrix.h

deselectSelectedCell

Deselects the selected cell or cells.

- (void)deselectSelectedCell

Discussion

If the selection mode is NSRadioModeMatrix and empty selection is not allowed, or if nothing is currently selected, this method does nothing. This method doesn’t redisplay the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – allowsEmptySelection
• – mode
• – selectCellAtRow:column:

Declared In

NSMatrix.h

doubleAction

Returns the matrix's double-click action method.

- (SEL)doubleAction

Return Value

The action method sent by the receiver to its target when the user double-clicks an entry or NULL if there’s no double-click action.

Discussion

The double-click action of an NSMatrix is sent after the appropriate single-click action (for the NSCell clicked or for the NSMatrix if the NSCell doesn’t have its own action). If there is no double-click action and the NSMatrix doesn’t ignore multiple clicks, the single-click action is sent twice.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – action (NSControl)
• – target (NSControl)
• – ignoresMultiClick (NSControl)
• – sendDoubleAction
• – setDoubleAction:

Declared In

NSMatrix.h

drawCellAtRow:column:

Displays the cell at the specified row and column.

- (void)drawCellAtRow:(NSInteger)row column:(NSInteger)column

Parameters

row

The row containing the cell to draw.

column

The column containing the cell to draw.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – drawCell: (NSControl)
• – drawCellInside: (NSControl)

Declared In

NSMatrix.h

drawsBackground

Returns a Boolean value indicating whether the matrix draws its background.

- (BOOL)drawsBackground

Return Value

YES if the receiver draws its background (the space between the cells); otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – backgroundColor
• – drawsCellBackground
• – setDrawsBackground:

Declared In

NSMatrix.h

drawsCellBackground

Returns whether the matrix draws the background within each of its cells.

- (BOOL)drawsCellBackground

Return Value

YES if the receiver draws the cell background; otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cellBackgroundColor
• – drawsBackground
• – setDrawsCellBackground:

Declared In

NSMatrix.h

getNumberOfRows:columns:

Obtains the number of rows and columns in the receiver.

- (void)getNumberOfRows:(NSInteger *)rowCount columns:(NSInteger *)columnCount

Parameters

rowCount

On return, the number of rows in the matrix.

columnCount

On return, the number of columns in the matrix.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – numberOfColumns
• – numberOfRows

Declared In

NSMatrix.h

getRow:column:forPoint:

Indicates whether the specified point lies within one of the cells of the matrix and returns the location of the cell within which the point lies.

- (BOOL)getRow:(NSInteger *)row column:(NSInteger *)column forPoint:(NSPoint)aPoint

Parameters

row

On return, the row of the cell containing the specified point.

column

On return, the column of the cell containing the specified point.

aPoint

The point to locate; this point should be in the coordinate system of the receiver.

Return Value

YES if the point lies within one of the cells in the receiver; NO if the point falls outside the bounds of the receiver or lies within an intercell spacing.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – getRow:column:ofCell:

Declared In

NSMatrix.h

getRow:column:ofCell:

Searches the receiver for the specified cell and returns the row and column of the cell

- (BOOL)getRow:(NSInteger *)row column:(NSInteger *)column ofCell:(NSCell *)aCell

Parameters

row

On return, the row in which the cell is located.

column

On return, the column in which the cell is located.

aCell

The cell to locate within the matrix.

Return Value

YES if the cell is one of the cells in the receiver, NO otherwise.

Discussion

.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – getRow:column:forPoint:

Declared In

NSMatrix.h

highlightCell:atRow:column:

Highlights or unhighlights the cell at the specified row and column location.

- (void)highlightCell:(BOOL)flag atRow:(NSInteger)row column:(NSInteger)column

Parameters

flag

YES to highlight the cell; NO to unhighlight the cell.

row

The row containing the cell.

column

The column containing the cell.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMatrix.h

initWithFrame:

Initializes a newly allocated matrix with the specified frame.

- (id)initWithFrame:(NSRect)frameRect

Parameters

frameRect

The frame with which to initialize the matrix.

Return Value

The NSMatrix, initialized with default parameters. The new NSMatrix contains no rows or columns. The default mode is NSRadioModeMatrix. The default cell class is NSActionCell.

Discussion

.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMatrix.h

initWithFrame:mode:cellClass:numberOfRows:numberOfColumns:

Initializes and returns a newly allocated matrix of the specified size using cells of the given class.

- (id)initWithFrame:(NSRect)frameRect mode:(NSInteger)aMode cellClass:(Class)classId numberOfRows:(NSInteger)numRows numberOfColumns:(NSInteger)numColumns

Parameters

frameRect

The matrix's frame.

aMode

The tracking mode for the matrix; this can be one of the modes described in NSMatrixMode.

classId

The class to use for any cells that the matrix creates and uses. This can be obtained by sending a class message to the desired subclass of NSCell.

numRows

The number of rows in the matrix.

numColumns

The number of columns in the matrix.

Return Value

The initialized instance of NSMatrix.

Discussion

This method is the designated initializer for matrices that add cells by creating instances of an NSCell subclass.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMatrix.h

initWithFrame:mode:prototype:numberOfRows:numberOfColumns:

Initializes and returns a newly allocated matrix of the specified size using the given cell as a prototype.

- (id)initWithFrame:(NSRect)frameRect mode:(NSInteger)aMode prototype:(NSCell *)aCell numberOfRows:(NSInteger)numRows numberOfColumns:(NSInteger)numColumns

Parameters

frameRect

The matrix's frame.

aMode

The tracking mode for the matrix; this can be one of the modes described in NSMatrixMode.

aCell

An instance of a subclass of NSCell, which the new matrix copies when it creates new cells.

numRows

The number of rows in the matrix.

numColumns

The number of columns in the matrix.

Discussion

This method is the designated initializer for matrices that add cells by copying an instance of an NSCell subclass.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSMatrix.h

insertColumn:

Inserts a new column of cells at the specified location. .

- (void)insertColumn:(NSInteger)column

Parameters

column

The number of the column before which the new column is inserted. If column is greater than the number of columns in the receiver, enough columns are created to expand the receiver to be column columns wide.

Discussion

New cells are created if needed with makeCellAtRow:column:. This method redraws the receiver. Your code may need to send sizeToCells after sending this method to resize the receiver to fit the newly added cells.

If the number of rows or columns in the receiver has been changed with renewRows:columns:, new cells are created only if they’re needed. This fact allows you to grow and shrink an NSMatrix without repeatedly creating and freeing the cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addColumn
• – insertRow:

Declared In

NSMatrix.h

insertColumn:withCells:

Inserts a new column of cells before the specified column, using the given cells.

- (void)insertColumn:(NSInteger)column withCells:(NSArray *)newCells

Parameters

column

The column at which to insert the new cells.

newCells

An array of objects to use to fill the new column, starting with the object at index 0. Each object should be an instance of NSCell or one of its subclasses (usually NSActionCell).

Discussion

If column is greater than the number of columns in the receiver, enough columns are created to expand the receiver to be column columns wide. newCells should either be empty or contain a sufficient number of cells to fill each new column. If newCells is nil or an array with no elements, the call is equivalent to calling insertColumn:. Extra cells are ignored, unless the matrix is empty. In that case, a matrix is created with one column and enough rows for all the elements of newCells.

This method redraws the receiver. Your code may need to send sizeToCells after sending this method to resize the receiver to fit the newly added cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addColumnWithCells:
• – insertRow:withCells:

Declared In

NSMatrix.h

insertRow:

Inserts a new row of cells before the specified row.

- (void)insertRow:(NSInteger)row

Parameters

row

The location at which to insert the new row. If this is greater than the number of rows in the receiver, enough rows are created to expand the receiver to be row rows high.

Discussion

New cells are created if needed with makeCellAtRow:column:. This method redraws the receiver. Your code may need to send sizeToCells after sending this method to resize the receiver to fit the newly added cells.

If the number of rows or columns in the receiver has been changed with renewRows:columns:, then new cells are created only if they’re needed. This fact allows you to grow and shrink an NSMatrix without repeatedly creating and freeing the cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addRow
• – insertColumn:

Declared In

NSMatrix.h

insertRow:withCells:

Inserts a new row of cells before the specified row, using the given cells.

- (void)insertRow:(NSInteger)row withCells:(NSArray *)newCells

Parameters

row

The location at which to insert the new row.

newCells

An array of objects to use when filling the new row, starting with the object at index 0. Each object in newCells should be an instance of NSCell or one of its subclasses (usually NSActionCell).

Discussion

If row is greater than the number of rows in the receiver, enough rows are created to expand the receiver to be row rows high. newCells should either be empty or contain a sufficient number of cells to fill each new row. If newCells is nil or an array with no elements, the call is equivalent to calling insertRow:. Extra cells are ignored, unless the matrix is empty. In that case, a matrix is created with one row and enough columns for all the elements of newCells.

This method redraws the receiver. Your code may need to send sizeToCells after sending this method to resize the receiver to fit the newly added cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addRowWithCells:
• – insertColumn:withCells:

Declared In

NSMatrix.h

intercellSpacing

Returns the spacing between cells in the matrix.

- (NSSize)intercellSpacing

Return Value

The vertical and horizontal spacing between cells in the receiver.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – cellSize
• – setIntercellSpacing:

Declared In

NSMatrix.h

isAutoscroll

Returns a Boolean value indicating whether the receiver is automatically scrolled.

- (BOOL)isAutoscroll

Return Value

YES if the receiver will be automatically scrolled whenever the cursor is dragged outside the receiver after a mouse-down event within its bounds; otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – scrollCellToVisibleAtRow:column:
• – setScrollable:

Declared In

NSMatrix.h

isSelectionByRect

Returns a Boolean value indicating whether the user can drag the cursor to select a rectangle of cells in the matrix.

- (BOOL)isSelectionByRect

Return Value

YES if the user can select a rectangle of cells in the receiver by dragging the cursor, NO otherwise.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setSelectionFrom:to:anchor:highlight:

Declared In

NSMatrix.h

keyCell

Returns the cell that will be clicked when the user presses the Space bar.

- (id)keyCell

Return Value

The cell that will be clicked when the user presses the Space bar.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – tabKeyTraversesCells
• – setKeyCell:

Declared In

NSMatrix.h

makeCellAtRow:column:

Creates a new cell at the location specified by the given row and column in the receiver.

- (NSCell *)makeCellAtRow:(NSInteger)row column:(NSInteger)column

Parameters

row

The row in which to create the new cell.

column

The column in which to create the new cell.

Return Value

The newly created cell.

Discussion

If the receiver has a prototype cell, it’s copied to create the new cell. If not, and if the receiver has a cell class set, it allocates and initializes (with init) an instance of that class. If the receiver hasn’t had either a prototype cell or a cell class set, makeCellAtRow:column: creates an NSActionCell.

Your code should never invoke this method directly; it’s used by addRow and other methods when a cell must be created. It may be overridden to provide more specific initialization of cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – addColumn
• – addRow
• – insertColumn:
• – insertRow:
• – setCellClass:
• – setPrototype:

Declared In

NSMatrix.h

mode

Returns the selection mode of the matrix.

- (NSMatrixMode)mode

Return Value

The selection mode of the receiver. Possible return values are defined in NSMatrixM