Mac Developer Library

Developer

AppKit Framework Reference NSMatrix Class Reference

Options
Deployment Target:

On This Page
Language:

NSMatrix

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

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.

  • Initializes a newly allocated matrix with the specified frame.

    Declaration

    Swift

    convenience init(frame frameRect: NSRect)

    Objective-C

    - (instancetype)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 OS X v10.0 and later.

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

    Declaration

    Swift

    init(frame frameRect: NSRect, mode aMode: NSMatrixMode, cellClass factoryId: AnyClass?, numberOfRows rowsHigh: Int, numberOfColumns colsWide: Int)

    Objective-C

    - (instancetype)initWithFrame:(NSRect)frameRect mode:(NSMatrixMode)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 OS X v10.0 and later.

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

    Declaration

    Swift

    init(frame frameRect: NSRect, mode aMode: NSMatrixMode, prototype aCell: NSCell, numberOfRows rowsHigh: Int, numberOfColumns colsWide: Int)

    Objective-C

    - (instancetype)initWithFrame:(NSRect)frameRect mode:(NSMatrixMode)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 OS X v10.0 and later.

  • mode mode Property

    The selection mode of the receiver.

    Declaration

    Swift

    var mode: NSMatrixMode

    Objective-C

    @property NSMatrixMode mode

    Discussion

    See NSMatrixMode for possible values.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var allowsEmptySelection: Bool

    Objective-C

    @property BOOL allowsEmptySelection

    Discussion

    When the value of this property is YEStrue, the matrix allows one or zero cells to be selected. When the value of this property is YEStrue, the matrix allows one and only one cell (not zero cells) to be selected. This setting has effect only in the NSRadioModeMatrix selection mode.

    Availability

    Available in OS X v10.0 and later.

    See Also

    mode

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

    Declaration

    Swift

    var selectionByRect: Bool

    Objective-C

    @property(getter=isSelectionByRect) BOOL selectionByRect

    Discussion

    When the value of this property is YEStrue, the matrix allows the user to select a rectangle of cells by dragging. When the value of this property is NOfalse, selection in the matrix is on a row-by-row basis. The default value of this property is YEStrue.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func addColumn()

    Objective-C

    - (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 OS X v10.0 and later.

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

    Declaration

    Swift

    func addColumnWithCells(_ newCells: [NSCell])

    Objective-C

    - (void)addColumnWithCells:(NSArray<NSCell *> *)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 OS X v10.0 and later.

  • Adds a new row of cells below the last row.

    Declaration

    Swift

    func addRow()

    Objective-C

    - (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 OS X v10.0 and later.

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

    Declaration

    Swift

    func addRowWithCells(_ newCells: [NSCell])

    Objective-C

    - (void)addRowWithCells:(NSArray<NSCell *> *)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 OS X v10.0 and later.

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

    Declaration

    Swift

    func cellFrameAtRow(_ row: Int, column col: Int) -> NSRect

    Objective-C

    - (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 OS X v10.0 and later.

    See Also

    cellSize

  • The size of each cell in the matrix.

    Declaration

    Swift

    var cellSize: NSSize

    Objective-C

    @property NSSize cellSize

    Discussion

    This value corresponds to both the width and height of each cell, because all cells in an NSMatrix are the same size.

    Availability

    Available in OS X v10.0 and later.

  • Obtains the number of rows and columns in the receiver.

    Declaration

    Swift

    func getNumberOfRows(_ rowCount: UnsafeMutablePointer<Int>, columns colCount: UnsafeMutablePointer<Int>)

    Objective-C

    - (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 OS X v10.0 and later.

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

    Declaration

    Swift

    func insertColumn(_ column: Int)

    Objective-C

    - (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 OS X v10.0 and later.

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

    Declaration

    Swift

    func insertColumn(_ column: Int, withCells newCells: [NSCell])

    Objective-C

    - (void)insertColumn:(NSInteger)column withCells:(NSArray<NSCell *> *)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 OS X v10.0 and later.

  • Inserts a new row of cells before the specified row.

    Declaration

    Swift

    func insertRow(_ row: Int)

    Objective-C

    - (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 OS X v10.0 and later.

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

    Declaration

    Swift

    func insertRow(_ row: Int, withCells newCells: [NSCell])

    Objective-C

    - (void)insertRow:(NSInteger)row withCells:(NSArray<NSCell *> *)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 OS X v10.0 and later.

  • The vertical and horizontal spacing between cells in the matrix.

    Declaration

    Swift

    var intercellSpacing: NSSize

    Objective-C

    @property NSSize intercellSpacing

    Discussion

    By default, both values are 1.0 in the matrix’s coordinate system.

    Availability

    Available in OS X v10.0 and later.

    See Also

    cellSize

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

    Declaration

    Swift

    func makeCellAtRow(_ row: Int, column col: Int) -> NSCell

    Objective-C

    - (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 OS X v10.0 and later.

  • The number of columns in the matrix. (read-only)

    Declaration

    Swift

    var numberOfColumns: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfColumns

    Availability

    Available in OS X v10.0 and later.

  • The number of rows in the matrix. (read-only)

    Declaration

    Swift

    var numberOfRows: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfRows

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func putCell(_ newCell: NSCell, atRow row: Int, column col: Int)

    Objective-C

    - (void)putCell:(NSCell *)newCell atRow:(NSInteger)row column:(NSInteger)column

    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.

  • Removes the specified column at from the receiver.

    Declaration

    Swift

    func removeColumn(_ col: Int)

    Objective-C

    - (void)removeColumn:(NSInteger)column

    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.

  • Removes the specified row from the receiver.

    Declaration

    Swift

    func removeRow(_ row: Int)

    Objective-C

    - (void)removeRow:(NSInteger)row

    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.

  • Changes the number of rows and columns in the receiver.

    Declaration

    Swift

    func renewRows(_ newRows: Int, columns newCols: Int)

    Objective-C

    - (void)renewRows:(NSInteger)newRows columns:(NSInteger)newCols

    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.

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

    Declaration

    Swift

    func sortUsingFunction(_ compare: (AnyObject, AnyObject, UnsafeMutablePointer<Void>) -> Int, context context: UnsafeMutablePointer<Void>)

    Objective-C

    - (void)sortUsingFunction:(NSInteger (*)(id, id, void *))comparator context:(void *)context

    Parameters

    comparator

    The function to use when comparing cells. The comparison function is used to compare two elements at a time and should return NSOrderedAscending if the first element is smaller than the second, NSOrderedDescending if the first element is larger than the second, and NSOrderedSame if 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)

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

    Declaration

    Swift

    func sortUsingSelector(_ comparator: Selector)

    Objective-C

    - (void)sortUsingSelector:(SEL)comparator

    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)

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

    Declaration

    Swift

    var autorecalculatesCellSize: Bool

    Objective-C

    @property BOOL autorecalculatesCellSize

    Discussion

    When the value of this property is YEStrue, auto-recalculation occurs. 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 Auto Layout. When using Auto Layout, you typically want this to be set to YEStrue.

    The default value of this property is NOfalse.

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Swift

    func getRow(_ row: UnsafeMutablePointer<Int>, column col: UnsafeMutablePointer<Int>, forPoint aPoint: NSPoint) -> Bool

    Objective-C

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

    YEStrue if the point lies within one of the cells in the receiver; NOfalse 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.

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

    Declaration

    Swift

    func getRow(_ row: UnsafeMutablePointer<Int>, column col: UnsafeMutablePointer<Int>, ofCell aCell: NSCell) -> Bool

    Objective-C

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

    YEStrue if the cell is one of the cells in the receiver, NOfalse otherwise.

    Discussion

    .

    Availability

    Available in OS X v10.0 and later.

  • Sets the state of the cell at specified location.

    Declaration

    Swift

    func setState(_ value: Int, atRow row: Int, column col: Int)

    Objective-C

    - (void)setState:(NSInteger)value atRow:(NSInteger)row column:(NSInteger)column

    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.

  • Sets the tooltip for the cell.

    Declaration

    Swift

    func setToolTip(_ toolTipString: String?, forCell cell: NSCell)

    Objective-C

    - (void)setToolTip:(NSString *)toolTipString forCell:(NSCell *)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.

  • Returns the tooltip for the specified cell.

    Declaration

    Swift

    func toolTipForCell(_ cell: NSCell) -> String?

    Objective-C

    - (NSString *)toolTipForCell:(NSCell *)cell

    Parameters

    cell

    The cell for which to return the tooltip.

    Return Value

    The string used as the cell's tooltip.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func selectCellAtRow(_ row: Int, column col: Int)

    Objective-C

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

    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.

  • Selects the last cell with the given tag.

    Declaration

    Swift

    func selectCellWithTag(_ anInt: Int) -> Bool

    Objective-C

    - (BOOL)selectCellWithTag:(NSInteger)anInt

    Parameters

    anInt

    The tag of the cell to select.

    Return Value

    YEStrue if the receiver contains a cell whose tag matches anInt, or NOfalse 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)

  • Selects and highlights all cells in the receiver.

    Declaration

    Swift

    func selectAll(_ sender: AnyObject?)

    Objective-C

    - (void)selectAll:(id)sender

    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)

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

    Declaration

    Swift

    unowned(unsafe) var keyCell: NSCell?

    Objective-C

    @property(assign) __kindof NSCell *keyCell

    Availability

    Available in OS X v10.0 and later.

  • Programmatically selects a range of cells.

    Declaration

    Swift

    func setSelectionFrom(_ startPos: Int, to endPos: Int, anchor anchorPos: Int, highlight lit: Bool)

    Objective-C

    - (void)setSelectionFrom:(NSInteger)startPos to:(NSInteger)endPos anchor:(NSInteger)anchorPos highlight:(BOOL)lit

    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

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

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

    Declaration

    Swift

    func deselectAllCells()

    Objective-C

    - (void)deselectAllCells

    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.

  • Deselects the selected cell or cells.

    Declaration

    Swift

    func deselectSelectedCell()

    Objective-C

    - (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 OS X v10.0 and later.

  • The most recently selected cell. (read-only)

    Declaration

    Objective-C

    @property(readonly, strong) __kindof NSCell *selectedCell

    Discussion

    When the value of this property is nil, no cell is selected. If more than one cell is selected, the value of this property is the cell that is lowest and farthest to the right in the matrix.

    Availability

    Available in OS X v10.0 and later.

  • An array containing all of the matrix’s highlighted cells plus its selected cell. (read-only)

    Declaration

    Swift

    var selectedCells: [NSCell] { get }

    Objective-C

    @property(readonly, copy) NSArray <__kindof NSCell *> *selectedCells

    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 access selectedCells to obtain the selection of cells.

    Availability

    Available in OS X v10.0 and later.

    See Also

    setHighlighted: (NSCell)
    selectedCell

  • The column number of the selected cell. (read-only)

    Declaration

    Swift

    var selectedColumn: Int { get }

    Objective-C

    @property(readonly) NSInteger selectedColumn

    Discussion

    When the value of this property is –1, no cells are selected. If cells in multiple columns are selected, the value of this property is the number of the last (rightmost) column containing a selected cell.

    Availability

    Available in OS X v10.0 and later.

  • The row number of the selected cell. (read-only)

    Declaration

    Swift

    var selectedRow: Int { get }

    Objective-C

    @property(readonly) NSInteger selectedRow

    Discussion

    When the value of this property is –1, no cells are selected. If cells in multiple rows are selected, the value of this property is the number of the last row containing a selected cell.

    Availability

    Available in OS X v10.0 and later.

  • Returns the cell at the specified row and column.

    Declaration

    Swift

    func cellAtRow(_ row: Int, column col: Int) -> NSCell?

    Objective-C

    - (__kindofNSCell *)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 OS X v10.0 and later.

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

    Declaration

    Swift

    func cellWithTag(_ anInt: Int) -> NSCell?

    Objective-C

    - (__kindofNSCell *)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 OS X v10.0 and later.

    See Also

    – selectCellWithTag:
    setTag: (NSActionCell)

  • An array containing the cells of the matrix. (read-only)

    Declaration

    Swift

    var cells: [NSCell] { get }

    Objective-C

    @property(readonly, copy) NSArray <NSCell *> *cells

    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.

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

    Declaration

    Swift

    @NSCopying var backgroundColor: NSColor

    Objective-C

    @property(copy) NSColor *backgroundColor

    Discussion

    The value of this property is 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 NSColor method controlColor.

    Availability

    Available in OS X v10.0 and later.

  • The background color of the matrix’s cells.

    Declaration

    Swift

    @NSCopying var cellBackgroundColor: NSColor?

    Objective-C

    @property(copy) NSColor *cellBackgroundColor

    Discussion

    The value of this property is the background color used to fill the space behind non-opaque cells. The default background color is the color returned by the NSColor method controlColor.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean that indicates whether the matrix draws its background.

    Declaration

    Swift

    var drawsBackground: Bool

    Objective-C

    @property BOOL drawsBackground

    Discussion

    When the value of this property is YEStrue, the matrix draws its background (the space between the cells).

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var drawsCellBackground: Bool

    Objective-C

    @property BOOL drawsCellBackground

    Discussion

    When the value of this property is YEStrue, the matrix draws the cell background.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func selectText(_ sender: AnyObject?)

    Objective-C

    - (void)selectText:(id)sender

    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)

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

    Declaration

    Swift

    func selectTextAtRow(_ row: Int, column col: Int) -> NSCell?

    Objective-C

    - (__kindofNSCell *)selectTextAtRow:(NSInteger)row column:(NSInteger)column

    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

    – selectText:

  • Requests permission to begin editing text.

    Declaration

    Swift

    func textShouldBeginEditing(_ textObject: NSText) -> Bool

    Objective-C

    - (BOOL)textShouldBeginEditing:(NSText *)textObject

    Parameters

    textObject

    The text object requesting permission to begin editing.

    Return Value

    YEStrue if the text object should proceed to make changes. If the delegate returns NOfalse, 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 YEStrue, 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

    delegate

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

    Declaration

    Swift

    func textDidBeginEditing(_ notification: NSNotification)

    Objective-C

    - (void)textDidBeginEditing:(NSNotification *)notification

    Parameters

    notification

    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.

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

    Declaration

    Swift

    func textDidChange(_ notification: NSNotification)

    Objective-C

    - (void)textDidChange:(NSNotification *)notification

    Parameters

    notification

    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.

  • Requests permission to end editing.

    Declaration

    Swift

    func textShouldEndEditing(_ textObject: NSText) -> Bool

    Objective-C

    - (BOOL)textShouldEndEditing:(NSText *)textObject

    Parameters

    textObject

    The text object requesting permission to end editing.

    Return Value

    YEStrue if the text object should proceed to finish editing and resign first responder status. If the delegate returns NOfalse, the text object selects all of its text and remains the first responder.

    The textShouldEndEditing: method returns NOfalse 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

    delegate

  • Invoked when text editing ends.

    Declaration

    Swift

    func textDidEndEditing(_ notification: NSNotification)

    Objective-C

    - (void)textDidEndEditing:(NSNotification *)notification

    Parameters

    notification

    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.

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

    Declaration

    Swift

    var tabKeyTraversesCells: Bool

    Objective-C

    @property BOOL tabKeyTraversesCells

    Discussion

    When the value of this property is YEStrue, pressing the Tab key should advance the key cell to the next selectable cell in the receiver. When the value of this property is NOfalse or 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.

    Pressing Shift-Tab causes the key cell to advance in the opposite direction (if the value of this property is NOfalse, 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.

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

    Declaration

    Swift

    var autosizesCells: Bool

    Objective-C

    @property BOOL autosizesCells

    Discussion

    When the value of this property is YEStrue, whenever the matrix is resized, the sizes of the cells change in proportion, keeping the intercell space constant. This property verifies that the cell sizes and intercell spacing add up to the exact size of the matrix, adjusting the size of the cells and updating the matrix if they don’t. When the value of this property is NOfalse, then the intercell spacing and cell size remain constant.

    Availability

    Available in OS X v10.0 and later.

  • Specifies whether the receiver's size information is validated.

    Declaration

    Swift

    func setValidateSize(_ flag: Bool)

    Objective-C

    - (void)setValidateSize:(BOOL)flag

    Parameters

    flag

    YEStrue to assume that the size information in the receiver is correct. If flag is NOfalse, the NSControl method calcSize will be invoked before any further drawing is done.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func sizeToCells()

    Objective-C

    - (void)sizeToCells

    Discussion

    This method does not redraw the receiver.

    Availability

    Available in OS X v10.0 and later.

    See Also

    setFrameSize: (NSView)
    sizeToFit (NSControl)

  • A Boolean that indicates whether the receiver is automatically scrolled.

    Declaration

    Swift

    var autoscroll: Bool

    Objective-C

    @property(getter=isAutoscroll) BOOL autoscroll

    Discussion

    When the value of this property is YEStrue, the matrix, if it is in a scrolling view, is automatically scrolled whenever the cursor is dragged outside the matrix after a mouse-down event within its bounds.

    Availability

    Available in OS X v10.0 and later.

  • Specifies whether the cells in the matrix are scrollable.

    Declaration

    Swift

    func setScrollable(_ flag: Bool)

    Objective-C

    - (void)setScrollable:(BOOL)flag

    Parameters

    flag

    YEStrue to make all the cells in the receiver scrollable, so the text they contain scrolls to remain in view if the user types past the edge of the cell. If flag is NOfalse, all cells are made nonscrolling. The prototype cell, if there is one, is also set accordingly

    Availability

    Available in OS X v10.0 and later.

    See Also

    prototype
    setScrollable: (NSCell)

  • Scrolls the receiver so the specified cell is visible.

    Declaration

    Swift

    func scrollCellToVisibleAtRow(_ row: Int, column col: Int)

    Objective-C

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

    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)

  • Displays the cell at the specified row and column.

    Declaration

    Swift

    func drawCellAtRow(_ row: Int, column col: Int)

    Objective-C

    - (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 OS X v10.0 and later.

    See Also

    drawCell: (NSControl)
    drawCellInside: (NSControl)

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

    Declaration

    Swift

    func highlightCell(_ flag: Bool, atRow row: Int, column col: Int)

    Objective-C

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

    Parameters

    flag

    YEStrue to highlight the cell; NOfalse to unhighlight the cell.

    row

    The row containing the cell.

    column

    The column containing the cell.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func sendAction() -> Bool

    Objective-C

    - (BOOL)sendAction

    Return Value

    YEStrue if an action was successfully sent to a target. If the selected cell is disabled, this method does nothing and returns NOfalse.

    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)

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

    Declaration

    Swift

    func sendAction(_ aSelector: Selector, to anObject: AnyObject, forAllCells flag: Bool)

    Objective-C

    - (void)sendAction:(SEL)aSelector to:(id)anObject forAllCells:(BOOL)flag

    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 NOfalse for any cell, sendAction:to:forAllCells: terminates immediately, without sending the message for the remaining cells. If it returns YEStrue, sendAction:to:forAllCells: proceeds to the next cell.

    anObject

    The object that is sent the selector for each cell in the matrix.

    flag

    YEStrue if the method should iterate through all cells in the matrix; NOfalse if 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.

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

    Declaration

    Swift

    var doubleAction: Selector

    Objective-C

    @property SEL doubleAction

    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. If the value of this property is a non-nil selector, this property also sets ignoresMultiClick to NOfalse; otherwise, it leaves ignoresMultiClick unchanged.

    Availability

    Available in OS X v10.0 and later.

    See Also

    – sendDoubleAction
    action (NSControl)
    target (NSControl)
    ignoresMultiClick (NSControl)

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

    Declaration

    Swift

    func sendDoubleAction()

    Objective-C

    - (void)sendDoubleAction

    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)

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

    Declaration

    Swift

    func acceptsFirstMouse(_ theEvent: NSEvent?) -> Bool

    Objective-C

    - (BOOL)acceptsFirstMouse:(NSEvent *)theEvent

    Parameters

    theEvent

    This parameter is ignored.

    Return Value

    NOfalse if the selection mode of the receiver is NSListModeMatrix, YEStrue 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

    mode

  • Responds to a mouse-down event.

    Declaration

    Swift

    func mouseDown(_ theEvent: NSEvent)

    Objective-C

    - (void)mouseDown:(NSEvent *)theEvent

    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.

  • The flags in effect at the mouse-down event that started the current tracking session. (read-only)

    Declaration

    Swift

    var mouseDownFlags: Int { get }

    Objective-C

    @property(readonly) NSInteger mouseDownFlags

    Discussion

    The NSMatrix mouseDown: method obtains these flags by sending a modifierFlags message to the event passed into mouseDown:. Use this property if you want to access these flags. This property 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)

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

    Declaration

    Swift

    func performKeyEquivalent(_ theEvent: NSEvent) -> Bool

    Objective-C

    - (BOOL)performKeyEquivalent:(NSEvent *)theEvent

    Parameters

    theEvent

    The event containing the character for which to find a key equivalent.

    Return Value

    YEStrue if a cell in the receiver responds to the key equivalent in theEvent, NOfalse 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.

Data Types

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

    Declaration

    Swift

    enum NSMatrixMode : UInt { case RadioModeMatrix case HighlightModeMatrix case ListModeMatrix case TrackModeMatrix }

    Objective-C

    typedef enum _NSMatrixMode { NSRadioModeMatrix = 0, NSHighlightModeMatrix = 1, NSListModeMatrix = 2, NSTrackModeMatrix = 3 } NSMatrixMode;

    Constants

    • TrackModeMatrix

      NSTrackModeMatrix

      The NSCell objects are asked to track the mouse with trackMouse:inRect:ofView:untilMouseUp: whenever the cursor is inside their bounds. No highlighting is performed.

      Available in OS X v10.0 and later.

    • HighlightModeMatrix

      NSHighlightModeMatrix

      An NSCell is highlighted before it’s asked to track the mouse, then unhighlighted when it’s done tracking.

      Available in OS X v10.0 and later.

    • RadioModeMatrix

      NSRadioModeMatrix

      Selects no more than one NSCell at a time.

      Any time an NSCell is selected, the previously selected NSCell is unselected.

      Available in OS X v10.0 and later.

    • ListModeMatrix

      NSListModeMatrix

      NSCell objects are highlighted, but don’t track the mouse.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.