<!--
{
  "availability" : [
    "macOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "AppKit",
  "identifier" : "/documentation/AppKit/NSMatrix",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AppKit"
    ],
    "preciseIdentifier" : "c:objc(cs)NSMatrix"
  },
  "title" : "NSMatrix"
}
-->

# NSMatrix

A legacy interface for grouping radio buttons or other types of cells together.

```
class NSMatrix
```

## Overview> Important:
> Use of NSMatrix is discouraged in apps that run in macOS 10.8 and later. If you need to create a radio button group in an app that runs in macOS 10.8 and later, create instances of [NSButton](https://developer.apple.com/library/archive/technotes/tn2219/_index.html#//apple_ref/doc/uid/DTS10004624-CH1-SUBSECTION12) that each specify a button type of `NSRadioButton` and specify the same action and the same superview for each button in the group.

`NSMatrix` uses flipped coordinates by default. The cells in an [`NSMatrix`](/documentation/AppKit/NSMatrix) object are numbered by row and column, each starting with 0; for example, the top left [`NSCell`](/documentation/AppKit/NSCell) would be at (0, 0), and the [`NSCell`](/documentation/AppKit/NSCell) that’s second down and third across would be at (1, 2).

The [`NSMatrix`](/documentation/AppKit/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 [`selectCell(atRow:column:)`](/documentation/AppKit/NSMatrix/selectCell(atRow:column:)) or [`selectCell(withTag:)`](/documentation/AppKit/NSMatrix/selectCell(withTag:)) message. The selected cell is the cell chosen for action messages except for [`performClick(_:)`](/documentation/AppKit/NSCell/performClick(_:)) ([`NSCell`](/documentation/AppKit/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.

## Topics

### Initializing an NSMatrix Object

[`init(frame:)`](/documentation/AppKit/NSMatrix/init(frame:))

Initializes a newly allocated matrix with the specified frame.

[`init(frame:mode:cellClass:numberOfRows:numberOfColumns:)`](/documentation/AppKit/NSMatrix/init(frame:mode:cellClass:numberOfRows:numberOfColumns:))

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

[`init(frame:mode:prototype:numberOfRows:numberOfColumns:)`](/documentation/AppKit/NSMatrix/init(frame:mode:prototype:numberOfRows:numberOfColumns:))

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

### Configuring the Matrix Object

[`mode`](/documentation/AppKit/NSMatrix/mode-swift.property)

The selection mode of the receiver.

[`allowsEmptySelection`](/documentation/AppKit/NSMatrix/allowsEmptySelection)

A Boolean that indicates whether a radio-mode matrix supports an empty selection.

[`isSelectionByRect`](/documentation/AppKit/NSMatrix/isSelectionByRect)

A Boolean that indicates whether the user can select a rectangle of cells in the receiver by dragging the cursor.

### Managing the Cell Class

[`cellClass`](/documentation/AppKit/NSMatrix/cellClass)

The subclass of [`NSCell`](/documentation/AppKit/NSCell) that the matrix uses when creating new (empty) cells.

[`prototype`](/documentation/AppKit/NSMatrix/prototype)

The prototype cell that’s copied whenever the matrix creates a new cell.

### Laying Out the Cells of the Matrix

[`addColumn()`](/documentation/AppKit/NSMatrix/addColumn())

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

[`addColumn(with:)`](/documentation/AppKit/NSMatrix/addColumn(with:))

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

[`addRow()`](/documentation/AppKit/NSMatrix/addRow())

Adds a new row of cells below the last row.

[`addRow(with:)`](/documentation/AppKit/NSMatrix/addRow(with:))

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

[`cellFrame(atRow:column:)`](/documentation/AppKit/NSMatrix/cellFrame(atRow:column:))

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

[`cellSize`](/documentation/AppKit/NSMatrix/cellSize)

The size of each cell in the matrix.

[`getNumberOfRows(_:columns:)`](/documentation/AppKit/NSMatrix/getNumberOfRows(_:columns:))

Obtains the number of rows and columns in the receiver.

[`insertColumn(_:)`](/documentation/AppKit/NSMatrix/insertColumn(_:))

Inserts a new column of cells at the specified location.

[`insertColumn(_:with:)`](/documentation/AppKit/NSMatrix/insertColumn(_:with:))

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

[`insertRow(_:)`](/documentation/AppKit/NSMatrix/insertRow(_:))

Inserts a new row of cells before the specified row.

[`insertRow(_:with:)`](/documentation/AppKit/NSMatrix/insertRow(_:with:))

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

[`intercellSpacing`](/documentation/AppKit/NSMatrix/intercellSpacing)

The vertical and horizontal spacing between cells in the matrix.

[`makeCell(atRow:column:)`](/documentation/AppKit/NSMatrix/makeCell(atRow:column:))

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

[`numberOfColumns`](/documentation/AppKit/NSMatrix/numberOfColumns)

The number of columns in the matrix.

[`numberOfRows`](/documentation/AppKit/NSMatrix/numberOfRows)

The number of rows in the matrix.

[`putCell(_:atRow:column:)`](/documentation/AppKit/NSMatrix/putCell(_:atRow:column:))

Replaces the cell at the specified row and column with the new cell.

[`removeColumn(_:)`](/documentation/AppKit/NSMatrix/removeColumn(_:))

Removes the specified column at from the receiver.

[`removeRow(_:)`](/documentation/AppKit/NSMatrix/removeRow(_:))

Removes the specified row from the receiver.

[`renewRows(_:columns:)`](/documentation/AppKit/NSMatrix/renewRows(_:columns:))

Changes the number of rows and columns in the receiver.

[`sort(using:context:)`](/documentation/AppKit/NSMatrix/sort(using:context:))

Sorts the receiver’s cells in ascending order as defined by the specified comparison function.

[`sort(using:)`](/documentation/AppKit/NSMatrix/sort(using:))

Sorts the receiver’s cells in ascending order as defined by the comparison method.

### Auto Layout Sizing

[`autorecalculatesCellSize`](/documentation/AppKit/NSMatrix/autorecalculatesCellSize)

A Boolean that indicates whether the matrix auto-recalculates its cell size.

### Finding Matrix Coordinates

[`getRow(_:column:for:)`](/documentation/AppKit/NSMatrix/getRow(_:column:for:))

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.

[`getRow(_:column:of:)`](/documentation/AppKit/NSMatrix/getRow(_:column:of:))

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

### Managing Attributes of Individual Cells

[`setState(_:atRow:column:)`](/documentation/AppKit/NSMatrix/setState(_:atRow:column:))

Sets the state of the cell at specified location.

[`setToolTip(_:for:)`](/documentation/AppKit/NSMatrix/setToolTip(_:for:))

Sets the tooltip for the cell.

[`toolTip(for:)`](/documentation/AppKit/NSMatrix/toolTip(for:))

Returns the tooltip for the specified cell.

### Selecting and Deselecting Cells

[`selectCell(atRow:column:)`](/documentation/AppKit/NSMatrix/selectCell(atRow:column:))

Selects the cell at the specified row and column within the receiver.

[`selectCell(withTag:)`](/documentation/AppKit/NSMatrix/selectCell(withTag:))

Selects the last cell with the given tag.

[`selectAll(_:)`](/documentation/AppKit/NSMatrix/selectAll(_:))

Selects and highlights all cells in the receiver.

[`keyCell`](/documentation/AppKit/NSMatrix/keyCell)

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

[`setSelectionFrom(_:to:anchor:highlight:)`](/documentation/AppKit/NSMatrix/setSelectionFrom(_:to:anchor:highlight:))

Programmatically selects a range of cells.

[`deselectAllCells()`](/documentation/AppKit/NSMatrix/deselectAllCells())

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

[`deselectSelectedCell()`](/documentation/AppKit/NSMatrix/deselectSelectedCell())

Deselects the selected cell or cells.

### Finding Cells

[`selectedCell`](/documentation/AppKit/NSMatrix/selectedCell)

The most recently selected cell.

[`selectedCells`](/documentation/AppKit/NSMatrix/selectedCells)

An array containing all of the matrix’s highlighted cells plus its selected cell.

[`selectedColumn`](/documentation/AppKit/NSMatrix/selectedColumn)

The column number of the selected cell.

[`selectedRow`](/documentation/AppKit/NSMatrix/selectedRow)

The row number of the selected cell.

[`cell(atRow:column:)`](/documentation/AppKit/NSMatrix/cell(atRow:column:))

Returns the cell at the specified row and column.

[`cell(withTag:)`](/documentation/AppKit/NSMatrix/cell(withTag:))

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

[`cells`](/documentation/AppKit/NSMatrix/cells)

An array containing the cells of the matrix.

### Modifying Graphics Attributes

[`backgroundColor`](/documentation/AppKit/NSMatrix/backgroundColor)

The background color of the matrix (the space between the cells).

[`cellBackgroundColor`](/documentation/AppKit/NSMatrix/cellBackgroundColor)

The background color of the matrix’s cells.

[`drawsBackground`](/documentation/AppKit/NSMatrix/drawsBackground)

A Boolean that indicates whether the matrix draws its background.

[`drawsCellBackground`](/documentation/AppKit/NSMatrix/drawsCellBackground)

A Boolean that indicates whether the matrix draws the background within each of its cells.

### Editing Text in Cells

[`selectText(_:)`](/documentation/AppKit/NSMatrix/selectText(_:))

Selects text in the currently selected cell or in the key cell.

[`selectText(atRow:column:)`](/documentation/AppKit/NSMatrix/selectText(atRow:column:))

Selects the text in the cell at the specified location and returns the cell.

[`textShouldBeginEditing(_:)`](/documentation/AppKit/NSMatrix/textShouldBeginEditing(_:))

Requests permission to begin editing text.

[`textDidBeginEditing(_:)`](/documentation/AppKit/NSMatrix/textDidBeginEditing(_:))

Invoked when there’s a change in the text after the receiver gains first responder status.

[`textDidChange(_:)`](/documentation/AppKit/NSMatrix/textDidChange(_:))

Invoked when a key-down event or paste operation occurs that changes the receiver’s contents.

[`textShouldEndEditing(_:)`](/documentation/AppKit/NSMatrix/textShouldEndEditing(_:))

Requests permission to end editing.

[`textDidEndEditing(_:)`](/documentation/AppKit/NSMatrix/textDidEndEditing(_:))

Invoked when text editing ends.

### Setting Tab Key Behavior

[`tabKeyTraversesCells`](/documentation/AppKit/NSMatrix/tabKeyTraversesCells)

A Boolean that indicates whether pressing the Tab key advances the key cell to the next selectable cell.

### Managing the Delegate

[`delegate`](/documentation/AppKit/NSMatrix/delegate)

The delegate for messages from the field editor.

[`NSMatrixDelegate`](/documentation/AppKit/NSMatrixDelegate)

The `NSMatrixDelegate` protocol defines the optional methods implemented by delegates of `NSMatrix` objects.

### Resizing the Matrix and Its Cells

[`autosizesCells`](/documentation/AppKit/NSMatrix/autosizesCells)

A Boolean that indicates whether the cell sizes change when the receiver is resized.

[`setValidateSize(_:)`](/documentation/AppKit/NSMatrix/setValidateSize(_:))

Specifies whether the receiver’s size information is validated.

[`sizeToCells()`](/documentation/AppKit/NSMatrix/sizeToCells())

Changes the width and the height of the receiver’s frame so it exactly contains the cells.

### Scrolling Cells in the Matrix

[`isAutoscroll`](/documentation/AppKit/NSMatrix/isAutoscroll)

A Boolean that indicates whether the receiver is automatically scrolled.

[`setScrollable(_:)`](/documentation/AppKit/NSMatrix/setScrollable(_:))

Specifies whether the cells in the matrix are scrollable.

[`scrollCellToVisible(atRow:column:)`](/documentation/AppKit/NSMatrix/scrollCellToVisible(atRow:column:))

Scrolls the receiver so the specified cell is visible.

### Displaying and Highlighting Cells

[`drawCell(atRow:column:)`](/documentation/AppKit/NSMatrix/drawCell(atRow:column:))

Displays the cell at the specified row and column.

[`highlightCell(_:atRow:column:)`](/documentation/AppKit/NSMatrix/highlightCell(_:atRow:column:))

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

### Managing and Sending Action Messages

[`sendAction()`](/documentation/AppKit/NSMatrix/sendAction())

If the selected cell has both an action and a target, sends its action to its target.

[`sendAction(_:to:forAllCells:)`](/documentation/AppKit/NSMatrix/sendAction(_:to:forAllCells:))

Iterates through the cells in the receiver, sending the specified selector to an object for each cell.

[`doubleAction`](/documentation/AppKit/NSMatrix/doubleAction)

The action sent to the target of the receiver when the user double-clicks a cell.

[`sendDoubleAction()`](/documentation/AppKit/NSMatrix/sendDoubleAction())

Sends the double-click action message to the target of the receiver.

### Handling Event and Action Messages

[`acceptsFirstMouse(for:)`](/documentation/AppKit/NSMatrix/acceptsFirstMouse(for:))

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

[`mouseDown(with:)`](/documentation/AppKit/NSMatrix/mouseDown(with:))

Responds to a mouse-down event.

[`mouseDownFlags`](/documentation/AppKit/NSMatrix/mouseDownFlags)

The flags in effect at the mouse-down event that started the current tracking session.

[`performKeyEquivalent(with:)`](/documentation/AppKit/NSMatrix/performKeyEquivalent(with:))

Looks for a cell that has the given key equivalent and, if found, makes that cell respond as if clicked.

### Managing the Cursor

[`resetCursorRects()`](/documentation/AppKit/NSMatrix/resetCursorRects())

Resets cursor rectangles so the cursor becomes an I-beam over text cells.

### Constants

[`NSMatrix.Mode`](/documentation/AppKit/NSMatrix/Mode-swift.enum)

These constants determine how [`NSCell`](/documentation/AppKit/NSCell) objects behave when an [`NSMatrix`](/documentation/AppKit/NSMatrix) object is tracking the mouse.

### Instance Methods

[`selectedCell()`](/documentation/AppKit/NSMatrix/selectedCell())


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)