Class

NSMatrix

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

Declaration

@interface NSMatrix : NSControl

Overview

NSMatrix uses flipped coordinates by default. 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.

Topics

Initializing an NSMatrix Object

- initWithFrame:

Initializes a newly allocated matrix with the specified frame.

- initWithFrame:mode:cellClass:numberOfRows:numberOfColumns:

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

- initWithFrame: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

The selection mode of the receiver.

allowsEmptySelection

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

selectionByRect

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

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

prototype

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

Laying Out the Cells of the Matrix

- addColumn

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

- addColumnWithCells:

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

- addRow

Adds a new row of cells below the last row.

- addRowWithCells:

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

- cellFrameAtRow:column:

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

cellSize

The size of each cell in the matrix.

- getNumberOfRows:columns:

Obtains the number of rows and columns in the receiver.

- insertColumn:

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

- insertColumn:withCells:

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

- insertRow:

Inserts a new row of cells before the specified row.

- insertRow:withCells:

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

intercellSpacing

The vertical and horizontal spacing between cells in the matrix.

- makeCellAtRow:column:

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

numberOfColumns

The number of columns in the matrix.

numberOfRows

The number of rows in the matrix.

- putCell:atRow:column:

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

- removeColumn:

Removes the specified column at from the receiver.

- removeRow:

Removes the specified row from the receiver.

- renewRows:columns:

Changes the number of rows and columns in the receiver.

- sortUsingFunction:context:

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

- sortUsingSelector:

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

Auto Layout Sizing

autorecalculatesCellSize

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

Finding Matrix Coordinates

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

- getRow:column:ofCell:

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

Managing Attributes of Individual Cells

- setState:atRow:column:

Sets the state of the cell at specified location.

- setToolTip:forCell:

Sets the tooltip for the cell.

- toolTipForCell:

Returns the tooltip for the specified cell.

Selecting and Deselecting Cells

- selectCellAtRow:column:

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

- selectCellWithTag:

Selects the last cell with the given tag.

- selectAll:

Selects and highlights all cells in the receiver.

keyCell

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

- setSelectionFrom:to:anchor:highlight:

Programmatically selects a range of cells.

- deselectAllCells

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

- deselectSelectedCell

Deselects the selected cell or cells.

Finding Cells

selectedCell

The most recently selected cell.

selectedCells

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

selectedColumn

The column number of the selected cell.

selectedRow

The row number of the selected cell.

- cellAtRow:column:

Returns the cell at the specified row and column.

- cellWithTag:

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

cells

An array containing the cells of the matrix.

Modifying Graphics Attributes

backgroundColor

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

cellBackgroundColor

The background color of the matrix’s cells.

drawsBackground

A Boolean that indicates whether the matrix draws its background.

drawsCellBackground

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

Editing Text in Cells

- selectText:

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

- selectTextAtRow:column:

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

- textShouldBeginEditing:

Requests permission to begin editing text.

- textDidBeginEditing:

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

- textDidChange:

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

- textShouldEndEditing:

Requests permission to end editing.

- textDidEndEditing:

Invoked when text editing ends.

Setting Tab Key Behavior

tabKeyTraversesCells

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

Managing the Delegate

delegate

The delegate for messages from the field editor.

NSMatrixDelegate

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

Resizing the Matrix and Its Cells

autosizesCells

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

- setValidateSize:

Specifies whether the receiver's size information is validated.

- sizeToCells

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

Scrolling Cells in the Matrix

autoscroll

A Boolean that indicates whether the receiver is automatically scrolled.

- setScrollable:

Specifies whether the cells in the matrix are scrollable.

- scrollCellToVisibleAtRow:column:

Scrolls the receiver so the specified cell is visible.

Displaying and Highlighting Cells

- drawCellAtRow:column:

Displays the cell at the specified row and column.

- highlightCell:atRow:column:

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

Managing and Sending Action Messages

- sendAction

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

- sendAction:to:forAllCells:

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

doubleAction

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

- sendDoubleAction

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

Handling Event and Action Messages

- acceptsFirstMouse:

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

- mouseDown:

Responds to a mouse-down event.

mouseDownFlags

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

- performKeyEquivalent:

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

Managing the Cursor

- resetCursorRects

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

Constants

NSMatrixMode

These constants determine how NSCell objects behave when an NSMatrix object is tracking the mouse.

Relationships

Inherits From

See Also

Controls

NSButton

A control that defines an area on the screen that can be used to trigger actions.

NSColorWell

A control that displays a color value and lets the user change that color value.

Date Picker

Display a calendar date and provide controls for editing the date value.

NSImageView

A display of image data from an NSImage object in a frame.

NSLevelIndicator

A visual representation of a level or quantity, using discrete values.

Path Control

A display of a file system path or virtual path information.

NSPopUpButton

A display of a single item from a list of items, and provide an interface for selecting items from the list.

NSProgressIndicator

An interface that provides visual feedback to the user about the status of an ongoing task.

NSRuleEditor

An interface for configuring a rule-based list of options.

NSPredicateEditor

A defined set of rules that allows the editing of predicate objects.

Search Field

Provide a text field that is optimized for text-based search interfaces.

NSSegmentedControl

Display one or more buttons in a single horizontal group.

Slider

Display a range of values from which the user selects a single value.

NSStepper

An interface with up and down arrow buttons for incrementing or decrementing a value.

Text Field

Provide a simple interface for displaying and editing text, including support for password fields and secure forms of text entry.

Token Field

Provide a text field whose text can be rendered in a visually distinct way so that users can recognize portions more easily.

Toolbar

Provide a space for controls under a window's title bar and above your custom content.

Combo Box

Display a list of values in a pop-up menu that lets the user select a value or type in a custom value.

NSSwitch

A control that offers a binary choice.