NSMatrix Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.0 and later. |
| Companion guide | |
| Declared in | NSMatrix.h |
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
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:
Autolayout Sizing
Finding Matrix Coordinates
Managing Attributes of Individual Cells
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
Managing the Delegate
Resizing the Matrix and Its Cells
Scrolling Cells in the Matrix
Displaying and Highlighting Cells
Managing and Sending Action Messages
Handling Event and Action Messages
Managing the Cursor
Instance Methods
acceptsFirstMouse:
Returns a Boolean value indicating whether the receiver accepts the first mouse.
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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.haddColumn
Adds a new column of cells to the right of the last column.
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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.haddColumnWithCells:
Adds a new column of cells to the right of the last column, using the given cells.
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
NSCellor one of its subclasses (usuallyNSActionCell). 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 OS X v10.0 and later.
Declared In
NSMatrix.haddRow
Adds a new row of cells below the last row.
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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.haddRowWithCells:
Adds a new row of cells below the last row, using the specified cells.
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
NSCellor one of its subclasses (usuallyNSActionCell). 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 OS X v10.0 and later.
Declared In
NSMatrix.hallowsEmptySelection
Returns a Boolean value indicating whether a radio-mode matrix supports an empty selection.
Return Value
YES if it is possible to have no cells selected in a radio-mode matrix; otherwise NO.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hautorecalculatesCellSize
Returns if the matrix auto-recalculates its cell size.
Return Value
YES if auto-recalculation occurs; otherwise NO.
Discussion
When using autolayout, you typically want this to be set to YES.
The default is NO.
Availability
- Available in OS X v10.8 and later.
See Also
Declared In
NSMatrix.hautosizesCells
Returns a Boolean value indicating whether the matrix automatically resizes it cells.
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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.hbackgroundColor
Returns the background color of the matrix.
Return Value
The color used to draw the background of the receiver (the space between the cells).
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hcellAtRow:column:
Returns the cell at the specified row and 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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.hcellBackgroundColor
Returns the background color of the matrix's cells.
Return Value
The color used to fill the background of the receiver's cells.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hcellClass
Returns the class that the matrix uses to create new cells.
Return Value
The subclass of NSCell that the receiver uses when creating new (empty) cells.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hcellFrameAtRow:column:
Returns the frame rectangle of the cell that would be drawn at the specified location.
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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.hcells
Returns the cells of the matrix.
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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.hcellSize
Returns the size of each cell in the matrix.
Return Value
The width and height of each cell in the receiver (all cells in an NSMatrix are the same size).
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hcellWithTag:
Searches the receiver and returns the last cell matching the specified tag.
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 OS X v10.0 and later.
See Also
-
– selectCellWithTag: -
setTag:(NSActionCell)
Declared In
NSMatrix.hdelegate
Returns the delegate for messages from the field editor.
Return Value
The delegate.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hdeselectAllCells
Deselects all cells in the receiver and, if necessary, redisplays the receiver.
Discussion
If the selection mode is NSRadioModeMatrix and empty selection is not allowed, this method does nothing.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hdeselectSelectedCell
Deselects the selected cell or cells.
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 OS X v10.0 and later.
Declared In
NSMatrix.hdoubleAction
Returns the matrix's double-click action method.
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 OS X v10.0 and later.
See Also
-
action(NSControl) -
target(NSControl) -
ignoresMultiClick(NSControl) -
– sendDoubleAction -
– setDoubleAction:
Declared In
NSMatrix.hdrawCellAtRow:column:
Displays the cell at the specified row and column.
Parameters
- row
The row containing the cell to draw.
- column
The column containing the cell to draw.
Availability
- Available in OS X v10.0 and later.
See Also
-
drawCell:(NSControl) -
drawCellInside:(NSControl)
Declared In
NSMatrix.hdrawsBackground
Returns a Boolean value indicating whether the matrix draws its background.
Return Value
YES if the receiver draws its background (the space between the cells); otherwise NO.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hdrawsCellBackground
Returns whether the matrix draws the background within each of its cells.
Return Value
YES if the receiver draws the cell background; otherwise NO.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hgetNumberOfRows:columns:
Obtains the number of rows and columns in the receiver.
Parameters
- rowCount
On return, the number of rows in the matrix.
- columnCount
On return, the number of columns in the matrix.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hgetRow: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.
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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.hgetRow:column:ofCell:
Searches the receiver for the specified cell and returns the row and column of the cell
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.
Discussion
.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hhighlightCell:atRow:column:
Highlights or unhighlights the cell at the specified row and column location.
Parameters
- flag
YESto highlight the cell;NOto unhighlight the cell.- row
The row containing the cell.
- column
The column containing the cell.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hinitWithFrame:
Initializes a newly allocated matrix with the specified frame.
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 OS X v10.0 and later.
Declared In
NSMatrix.hinitWithFrame:mode:cellClass:numberOfRows:numberOfColumns:
Initializes and returns a newly allocated matrix of the specified size using cells of the given class.
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
classmessage to the desired subclass ofNSCell.- 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 OS X v10.0 and later.
Declared In
NSMatrix.hinitWithFrame:mode:prototype:numberOfRows:numberOfColumns:
Initializes and returns a newly allocated matrix of the specified size using the given cell as a prototype.
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 OS X v10.0 and later.
Declared In
NSMatrix.hinsertColumn:
Inserts a new column of cells at the specified location. .
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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.hinsertColumn:withCells:
Inserts a new column of cells before the specified column, using the given cells.
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
NSCellor one of its subclasses (usuallyNSActionCell).
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 OS X v10.0 and later.
Declared In
NSMatrix.hinsertRow:
Inserts a new row of cells before the specified 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 OS X v10.0 and later.
See Also
Declared In
NSMatrix.hinsertRow:withCells:
Inserts a new row of cells before the specified row, using the given cells.
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
NSCellor one of its subclasses (usuallyNSActionCell).
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 OS X v10.0 and later.
Declared In
NSMatrix.hintercellSpacing
Returns the spacing between cells in the matrix.
Return Value
The vertical and horizontal spacing between cells in the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hisAutoscroll
Returns a Boolean value indicating whether the receiver is automatically scrolled.
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 OS X v10.0 and later.
Declared In
NSMatrix.hisSelectionByRect
Returns a Boolean value indicating whether the user can drag the cursor to select a rectangle of cells in the matrix.
Return Value
YES if the user can select a rectangle of cells in the receiver by dragging the cursor, NO otherwise.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hkeyCell
Returns the cell that will be clicked when the user presses the Space bar.
Return Value
The cell that will be clicked when the user presses the Space bar.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hmakeCellAtRow:column:
Creates a new cell at the location specified by the given row and column in the receiver.
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 OS X v10.0 and later.
Declared In
NSMatrix.hmode
Returns the selection mode of the matrix.
Return Value
The selection mode of the receiver. Possible return values are defined in NSMatrixMode.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hmouseDown:
Responds to a mouse-down event.
Parameters
- theEvent
The mouse-down event.
Discussion
A mouse-down event in a text cell initiates editing mode. A double click in any cell type except a text cell sends the double-click action of the receiver (if there is one) in addition to the single-click action.
Your code should never invoke this method, but you may override it to implement different mouse tracking than NSMatrix does. The response of the receiver depends on its selection mode, as explained in the class description.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hmouseDownFlags
Returns the flags in effect at the mouse-down event that started the current tracking session.
Return Value
The flags in effect when the mouse-down event is generated.
Discussion
The NSMatrixmouseDown: method obtains these flags by sending a modifierFlags message to the event passed into mouseDown:. Use this method if you want to access these flags. This method is valid only during tracking; it isn’t useful if the target of the receiver initiates another tracking loop as part of its action method (as a cell that pops up a pop-up list does, for example).
Availability
- Available in OS X v10.0 and later.
See Also
-
sendActionOn:(NSCell)
Declared In
NSMatrix.hnumberOfColumns
Returns the number of columns in the receiver.
Return Value
The number of columns in the matrix.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hnumberOfRows
Returns the number of rows in the receiver.
Return Value
The number of rows in the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hperformKeyEquivalent:
Looks for a cell that has the given key equivalent and, if found, makes that cell respond as if clicked.
Parameters
- theEvent
The event containing the character for which to find a key equivalent.
Return Value
YES if a cell in the receiver responds to the key equivalent in theEvent, NO if no cell responds.
Discussion
If there’s a cell in the receiver that has a key equivalent equal to the character in [theEventcharactersIgnoringModifiers] (taking into account any key modifier flags) and that cell is enabled, that cell is made to react as if the user had clicked it: by highlighting, changing its state as appropriate, sending its action if it has one, and then unhighlighting.
Your code should never send this message—it is sent when the receiver or one of its superviews is the first responder and the user presses a key. You may want to override this method to change the way key equivalents are performed or displayed or to disable them in your subclass.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hprototype
Returns the prototype cell that’s copied when a new cell is created.,
Return Value
The cell that the matrix copies whenever it creates a new cell, or nil if there is none.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hputCell:atRow:column:
Replaces the cell at the specified row and column with the new cell.
Parameters
- newCell
The cell to insert into the matrix.
- row
The row in which to place the new cell.
- column
The column in which to place the new cell.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hremoveColumn:
Removes the specified column at from the receiver.
Parameters
- column
The column to remove.
Discussion
The column's cells are autoreleased. This method redraws the receiver. Your code should normally send sizeToCells after invoking this method to resize the receiver so it fits the reduced cell count.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hremoveRow:
Removes the specified row from the receiver.
Parameters
- row
The row to remove.
Discussion
The row's cells are autoreleased. This method redraws the receiver. Your code should normally send sizeToCells after invoking this method to resize the receiver so it fits the reduced cell count.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hrenewRows:columns:
Changes the number of rows and columns in the receiver.
Parameters
- newRows
The new number of rows in the matrix.
- newCols
The new number of columns in the matrix.
Discussion
This method uses the same cells as before, creating new cells only if the new size is larger; it never frees cells. It doesn’t redisplay the receiver. Your code should normally send sizeToCells after invoking this method to resize the receiver so it fits the changed cell arrangement. This method deselects all cells in the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hresetCursorRects
Resets cursor rectangles so the cursor becomes an I-beam over text cells.
Discussion
This method resets the cursor rectangles by sending resetCursorRect:inView: to each cell in the receiver. Any cell that has a cursor rectangle to set up should then send addCursorRect:cursor: back to the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
-
resetCursorRect:inView:(NSCell) -
addCursorRect:cursor:(NSView)
Declared In
NSMatrix.hscrollCellToVisibleAtRow:column:
Scrolls the receiver so the specified cell is visible.
Parameters
- row
The row of the cell to make visible.
- column
The column of the cell to make visible.
Discussion
This method scrolls if the receiver is in a scrolling view and row and column represent a valid cell within the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
-
scrollRectToVisible:(NSView)
Declared In
NSMatrix.hselectAll:
Selects and highlights all cells in the receiver.
Parameters
- sender
This argument is ignored.
Discussion
Editable text cells and disabled cells are not selected. The receiver is redisplayed.
If the selection mode is not NSListModeMatrix, this method does nothing.
Availability
- Available in OS X v10.0 and later.
See Also
-
selectCell:(NSControl)
Declared In
NSMatrix.hselectCellAtRow:column:
Selects the cell at the specified row and column within the receiver.
Parameters
- row
The row of the cell to select.
- column
The column of the cell to select.
Discussion
If the specified cell is an editable text cell, its text is selected. If either row or column is –1, then the current selection is cleared (unless the receiver is an NSRadioModeMatrix and doesn’t allow empty selection). This method redraws the affected cells.
Availability
- Available in OS X v10.0 and later.
See Also
-
– allowsEmptySelection -
– mode -
selectCell:(NSControl)
Declared In
NSMatrix.hselectCellWithTag:
Selects the last cell with the given tag.
Parameters
- anInt
The tag of the cell to select.
Return Value
YES if the receiver contains a cell whose tag matches anInt, or NO if no such cell exists
Discussion
If the matrix has at least one cell whose tag is equal to anInt, the last cell (when viewing the matrix as a row-ordered array) is selected. If the specified cell is an editable text cell, its text is selected.
Availability
- Available in OS X v10.0 and later.
See Also
-
– cellWithTag: -
selectCell:(NSControl)
Declared In
NSMatrix.hselectedCell
Returns the most recently selected cell.
Return Value
The most recently selected cell or nil if no cell is selected. If more than one cell is selected, this method returns the cell that is lowest and farthest to the right in the receiver.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hselectedCells
Returns the receiver's selected and highlighted cells.
Return Value
An array containing all of the receiver’s highlighted cells plus its selected cell.
Discussion
See the class description for a discussion of the selected cell.
As an alternative to using setSelectionFrom:to:anchor:highlight: for programmatically making discontiguous selections of cells in a matrix, you could first set the single selected cell and then set subsequent cells to be highlighted; afterwards you can call selectedCells to obtain the selection of cells.
Availability
- Available in OS X v10.0 and later.
See Also
-
setHighlighted:(NSCell) -
– selectedCell
Declared In
NSMatrix.hselectedColumn
Returns the column of the selected cell.
Return Value
The column number of the selected cell or –1 if no cells are selected. If cells in multiple columns are selected, this method returns the number of the last (rightmost) column containing a selected cell.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hselectedRow
Returns the row of the selected cell.
Return Value
the row number of the selected cell, or –1 if no cells are selected. If cells in multiple rows are selected, this method returns the number of the last row containing a selected cell.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hselectText:
Selects text in the currently selected cell or in the key cell.
Discussion
If the currently selected cell is editable and enabled, its text is selected. Otherwise, the key cell is selected.
Availability
- Available in OS X v10.0 and later.
See Also
-
– keyCell -
selectText:(NSTextField)
Declared In
NSMatrix.hselectTextAtRow:column:
Selects the text in the cell at the specified location and returns the cell.
Parameters
- row
The row containing the text to select.
- column
The column containing the text to select.
Return Value
If it is both editable and selectable, the cell at the specified row and column. If the cell at the specified location, is either not editable or not selectable, this method does nothing and returns nil. If row and column indicate a cell that is outside the receiver, this method does nothing and returns the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsendAction
If the selected cell has both an action and a target, sends its action to its target.
Return Value
YES if an action was successfully sent to a target. If the selected cell is disabled, this method does nothing and returns NO.
Discussion
If the cell has an action but no target, its action is sent to the target of the receiver. If the cell doesn’t have an action, or if there is no selected cell, the receiver sends its own action to its target.
Availability
- Available in OS X v10.0 and later.
See Also
-
– sendDoubleAction -
action(NSCell) -
target(NSCell)
Declared In
NSMatrix.hsendAction:to:forAllCells:
Iterates through the cells in the receiver, sending the specified selector to an object for each cell.
Parameters
- aSelector
The selector to send to the object for each cell. This must represent a method that takes a single argument: the id of the current cell in the iteration. aSelector’s return value must be a BOOL. If aSelector returns
NOfor any cell,sendAction:to:forAllCells:terminates immediately, without sending the message for the remaining cells. If it returnsYES,sendAction:to:forAllCells:proceeds to the next cell.- anObject
The object that is sent the selector for each cell in the matrix.
- flag
YESif the method should iterate through all cells in the matrix;NOif it should iterate through just the selected cells in the matrix.
Discussion
Iteration begins with the cell in the upper-left corner of the receiver, proceeding through the appropriate entries in the first row, then on to the next.
This method is not invoked to send action messages to target objects in response to mouse-down events in the receiver. Instead, you can invoke it if you want to have multiple cells in an NSMatrix interact with an object. For example, you could use it to verify the titles in a list of items or to enable a series of radio buttons based on their purpose in relation to anObject.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsendDoubleAction
Sends the double-click action message to the target of the receiver.
Discussion
If the receiver doesn't have a double-click action, the double-click action message of the selected cell (as returned by selectedCell) is sent to the selected cell’s target. Finally, if the selected cell also has no action, then the single-click action of the receiver is sent to the target of the receiver.
If the selected cell is disabled, this method does nothing.
Your code shouldn’t invoke this method; it’s sent in response to a double-click event in the NSMatrix. Override it if you need to change the search order for an action to send.
Availability
- Available in OS X v10.0 and later.
See Also
-
– sendAction -
ignoresMultiClick(NSControl)
Declared In
NSMatrix.hsetAllowsEmptySelection:
Sets whether a radio-mode matrix allows an empty selection.
Parameters
- flag
YESto make the receiver allow one or zero cells to be selected.NOif the receiver should allow one and only one cell (not zero cells) to be selected. This setting has effect only in theNSRadioModeMatrixselection mode.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetAutorecalculatesCellSize:
Sets whether the matrix auto-recalculates its cell size.
Parameters
- flag
YESif auto-recalculation should occur; otherwiseNO.
Discussion
If set to YES, then the matrix will adjust its cellSize to accommodate its largest cell. Changing the cellSize does not directly affect the frame of the matrix; however it does affect the intrinsic content size, which may cause the receiver to resize under autolayout.
When using autolayout, you typically want this to be set to YES.
The default is NO.
Availability
- Available in OS X v10.8 and later.
See Also
Declared In
NSMatrix.hsetAutoscroll:
Sets whether the receiver is automatically scrolled.
Parameters
- flag
YESto indicate that the receiver, if it is in a scrolling view, should be automatically scrolled whenever the cursor is dragged outside the receiver after a mouse-down event within the bounds of the receiver.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsetAutosizesCells:
Sets whether the cell sizes change when the receiver is resized.
Parameters
- flag
YESto specify that, whenever the receiver is resized, the sizes of the cells change in proportion, keeping the intercell space constant; further, this method verifies that the cell sizes and intercell spacing add up to the exact size of the receiver, adjusting the size of the cells and updating the receiver if they don’t. If flag isNO, then the intercell spacing and cell size remain constant.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetBackgroundColor:
Sets the background color for the receiver and redraws the receiver.
Parameters
- aColor
The background color used to fill the space between cells or the space behind any non-opaque cells. The default background color is the color returned by the
NSColormethodcontrolColor.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsetCellBackgroundColor:
Sets the background color for the cells in the receiver
Parameters
- aColor
The background color used to fill the space behind non-opaque cells. The default cell background color is the color returned by the
NSColormethodcontrolColor
Discussion
.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsetCellClass:
Configures the receiver to use instances of the specified class when creating new cells.
Parameters
- aClass
The class to use when creating new cells. This should be the id of a subclass of
NSCell, which can be obtained by sending theclassmessage to either theNSCellsubclass object or to an instance of that subclass. The default cell class is that set with the class methodsetCellClass:, orNSActionCellif no other default cell class has been specified.
Discussion
You need to use this method only with matrices initialized with initWithFrame:, because the other initializers allow you to specify an instance-specific cell class or cell prototype.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetCellSize:
Sets the width and height of each of the cells in the matrix.
Parameters
- aSize
The new width and height of cells in the receiver.
Discussion
This method may change the size of the receiver. It does not redraw the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
-
calcSize(NSControl) -
– cellSize
Declared In
NSMatrix.hsetDelegate:
Sets the delegate for messages from the field editor.
Parameters
- anObject
The delegate.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsetDoubleAction:
Sets the action sent to the target of the receiver when the user double-clicks a cell.
Parameters
- aSelector
The selector to make the double-click action of the receiver.
Discussion
A double-click action is always sent after the appropriate single-click action, which is the cell’s single-click action, if it has one, or the receiver single-click action, otherwise. If aSelector is a non-NULL selector, this method also sets the ignoresMultiClick flag to NO; otherwise, it leaves the flag unchanged.
If an NSMatrix has no double-click action set, then by default a double click is treated as a single click.
Availability
- Available in OS X v10.0 and later.
See Also
-
– sendDoubleAction -
setAction:(NSControl) -
setTarget:(NSControl) -
– doubleAction
Declared In
NSMatrix.hsetDrawsBackground:
Sets whether the receiver draws its background.
Parameters
- flag
YESif the receiver should draw its background (the space between the cells);NOif it should not.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsetDrawsCellBackground:
Sets whether the receiver draws the background within each of its cells.
Parameters
- flag
YESif the receiver should draw the background in its cells;NOif it should not.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsetIntercellSpacing:
Sets the spacing between cells in the matrix.
Parameters
- aSize
The vertical and horizontal spacing to use between cells in the receiver. By default, both values are 1.0 in the receiver’s coordinate system.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetKeyCell:
Sets the cell that will be clicked when the user presses the Space bar.
Parameters
- aCell
The cell to set as the key cell.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetMode:
Sets the selection mode of the receiver.
Parameters
- aMode
The selection mode of the matrix. Possible values are listed in
NSMatrixMode.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetPrototype:
Sets the prototype cell that’s copied whenever the matrix creates a new cell.
Parameters
- aCell
The cell to copy when creating new cells.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetScrollable:
Specifies whether the cells in the matrix are scrollable.
Parameters
Availability
- Available in OS X v10.0 and later.
See Also
-
– prototype -
setScrollable:(NSCell)
Declared In
NSMatrix.hsetSelectionByRect:
Sets whether the user can select a rectangle of cells in the receiver by dragging the cursor.
Parameters
- flag
YESif the matrix should allow the user to select a rectangle of cells by dragging.NOif selection in the matrix should be on a row-by-row basis. The default isYES.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsetSelectionFrom:to:anchor:highlight:
Programmatically selects a range of cells.
Parameters
- startPos
The position of the cell that marks where the user would have pressed the mouse button.
- endPos
The position of the cell that marks where the user would have released the mouse button.
- anchorPos
The position of the cell to treat as the last cell the user would have selected. To simulate Shift-dragging (continuous selection) anchorPos should be the endPos used in the last method call. To simulate Command-dragging (discontinuous selection), anchorPos should be the same as this method call’s startPos.
- lit
YESif cells selected by this method should be highlighted.
Discussion
startPos, endPos, and anchorPos are cell positions, counting from 0 at the upper left cell of the receiver, in row order. For example, the third cell in the top row would be number 2.
To simulate dragging without a modifier key, deselecting anything that was selected before, call deselectAllCells before calling this method.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetState:atRow:column:
Sets the state of the cell at specified location.
Parameters
- value
The value to assign to the cell.
- row
The row in which the cell is located.
- column
The column in which the cell is located.
Discussion
For radio-mode matrices, if value is nonzero the specified cell is selected before its state is set to value. If value is 0 and the receiver is a radio-mode matrix, the currently selected cell is deselected (providing that empty selection is allowed).
This method redraws the affected cell.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetTabKeyTraversesCells:
Sets whether pressing the Tab key advances the key cell to the next selectable cell.
Parameters
- flag
YESif pressing the Tab key should advance the key cell to the next selectable cell in the receiver. If this isNOor if there aren't any selectable cells after the current one, the next view in the window becomes key when the user presses the Tab key.
Discussion
Pressing Shift-Tab causes the key cell to advance in the opposite direction (if flag is NO, or if there aren’t any selectable cells before the current one, the previous view in the window becomes key).
Availability
- Available in OS X v10.0 and later.
See Also
-
selectKeyViewFollowingView:(NSWindow) -
selectNextKeyView:(NSWindow) -
– setKeyCell: -
– tabKeyTraversesCells
Declared In
NSMatrix.hsetToolTip:forCell:
Sets the tooltip for the cell.
Parameters
- toolTipString
The string to use as the cell's tooltip (or help tag).
- cell
The cell to which to assign the tooltip.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hsetValidateSize:
Specifies whether the receiver's size information is validated.
Parameters
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.hsizeToCells
Changes the width and the height of the receiver’s frame so it exactly contains the cells.
Discussion
This method does not redraw the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
-
setFrameSize:(NSView) -
sizeToFit(NSControl)
Declared In
NSMatrix.hsortUsingFunction:context:
Sorts the receiver’s cells in ascending order as defined by the specified comparison function.
Parameters
- comparator
The function to use when comparing cells. The comparison function is used to compare two elements at a time and should return
NSOrderedAscendingif the first element is smaller than the second,NSOrderedDescendingif the first element is larger than the second, andNSOrderedSameif the elements are equal.- context
Context passed to the comparison function as its third argument, each time its called. This allows the comparison to be based on some outside parameter, such as whether character sorting is case-sensitive or case-insensitive.
Availability
- Available in OS X v10.0 and later.
See Also
-
sortUsingFunction:context:(NSMutableArray)
Declared In
NSMatrix.hsortUsingSelector:
Sorts the receiver’s cells in ascending order as defined by the comparison method.
Parameters
- comparator
The comparison method.
Discussion
The comparator message is sent to each object in the matrix and has as its single argument another object in the array. The comparison method is used to compare two elements at a time and should return NSOrderedAscending if the receiver is smaller than the argument, NSOrderedDescending if the receiver is larger than the argument, and NSOrderedSame if they are equal.
Availability
- Available in OS X v10.0 and later.
See Also
-
sortUsingSelector:(NSMutableArray)
Declared In
NSMatrix.htabKeyTraversesCells
Returns a Boolean value indicating whether pressing the Tab key advances the key cell to the next selectable cell.
Return Value
YES if pressing the Tab key advances the key cell to the next selectable cell in the receiver; otherwise NO.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.htextDidBeginEditing:
Invoked when there’s a change in the text after the receiver gains first responder status.
Parameters
- notification
The
NSControlTextDidBeginEditingNotificationnotification.
Discussion
This method’s default behavior is to post an NSControlTextDidBeginEditingNotification along with the receiving object to the default notification center. The posted notification’s user info contains the contents of notification’s user info dictionary, plus an additional key-value pair. The additional key is “NSFieldEditor”; the value for this key is the text object that began editing.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.htextDidChange:
Invoked when a key-down event or paste operation occurs that changes the receiver’s contents.
Parameters
- notification
The
NSControlTextDidChangeNotificationnotification.
Discussion
This method’s default behavior is to pass this message on to the selected cell (if the selected cell responds to textDidChange:) and then to post an NSControlTextDidChangeNotification along with the receiving object to the default notification center. The posted notification’s user info contains the contents of notification’s user info dictionary, plus an additional key-value pair. The additional key is “NSFieldEditor”; the value for this key is the text object that changed.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.htextDidEndEditing:
Invoked when text editing ends.
Parameters
- notification
The
NSControlTextDidEndEditingNotificationnotification.
Discussion
This method’s default behavior is to post an NSControlTextDidEndEditingNotification along with the receiving object to the default notification center. The posted notification’s user info contains the contents of notification’s user info dictionary, plus an additional key-value pair. The additional key is “NSFieldEditor”; the value for this key is the text object that began editing. After posting the notification, textDidEndEditing: sends an endEditing: message to the selected cell, draws and makes the selected cell key, and then takes the appropriate action based on which key was used to end editing (Return, Tab, or Back-Tab).
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.htextShouldBeginEditing:
Requests permission to begin editing text.
Parameters
- textObject
The text object requesting permission to begin editing.
Return Value
YES if the text object should proceed to make changes. If the delegate returns NO, the text object abandons the editing operation.
The default behavior of this method is to return the value obtained from control:textShouldBeginEditing:, unless the delegate doesn’t respond to that method, in which case it returns YES, thereby allowing text editing to proceed.
Discussion
This method is invoked to let the NSTextField respond to impending changes to its text. This method’s default behavior is to send control:textShouldBeginEditing: to the receiver’s delegate (passing the receiver and textObject as parameters).
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.htextShouldEndEditing:
Requests permission to end editing.
Parameters
- textObject
The text object requesting permission to end editing.
Return Value
YES if the text object should proceed to finish editing and resign first responder status. If the delegate returns NO, the text object selects all of its text and remains the first responder.
The textShouldEndEditing: method returns NO if the text field contains invalid contents; otherwise it returns the value passed back from control:textShouldEndEditing:.
Discussion
This method is invoked to let the NSTextField respond to impending loss of first-responder status. This method’s default behavior checks the text field for validity; providing that the field contents are deemed valid, and providing that the delegate responds, control:textShouldEndEditing: is sent to the receiver’s delegate (passing the receiver and textObject as parameters).
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSMatrix.hConstants
NSMatrixMode
These constants determine how NSCell objects behave when an NSMatrix object is tracking the mouse.
typedef enum _NSMatrixMode {
NSRadioModeMatrix = 0,
NSHighlightModeMatrix = 1,
NSListModeMatrix = 2,
NSTrackModeMatrix = 3
} NSMatrixMode;
Constants
NSTrackModeMatrixThe
NSCellobjects are asked to track the mouse withtrackMouse:inRect:ofView:untilMouseUp:whenever the cursor is inside their bounds. No highlighting is performed.Available in OS X v10.0 and later.
Declared in
NSMatrix.h.NSHighlightModeMatrixAn
NSCellis highlighted before it’s asked to track the mouse, then unhighlighted when it’s done tracking.Available in OS X v10.0 and later.
Declared in
NSMatrix.h.NSRadioModeMatrixSelects no more than one
NSCellat a time.Any time an
NSCellis selected, the previously selectedNSCellis unselected.Available in OS X v10.0 and later.
Declared in
NSMatrix.h.NSListModeMatrixNSCellobjects are highlighted, but don’t track the mouse.Available in OS X v10.0 and later.
Declared in
NSMatrix.h.
Availability
- Available in OS X v10.0 and later.
Declared In
NSMatrix.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)