Mac Developer Library

Developer

AppKit Framework Reference NSMatrix Class Reference

Options
Deployment Target:

On This Page
Language:

NSMatrix

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

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

    .

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 classId: AnyClass?, numberOfRows numRows: Int, numberOfColumns numColumns: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 numRows: Int, numberOfColumns numColumns: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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: [AnyObject])

    Objective-C

    - (void)addColumnWithCells:(NSArray *)newCells

    Parameters

    newCells

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

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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: [AnyObject])

    Objective-C

    - (void)addRowWithCells:(NSArray *)newCells

    Parameters

    newCells

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

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 column: 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).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – cellSize

  • Returns the size of each cell in the matrix.

    Declaration

    Swift

    var cellSize: NSSize

    Objective-C

    @property NSSize cellSize

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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: [AnyObject])

    Objective-C

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

    Parameters

    column

    The column at which to insert the new cells.

    newCells

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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: [AnyObject])

    Objective-C

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

    Parameters

    row

    The location at which to insert the new row.

    newCells

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the spacing between cells in the matrix.

    Declaration

    Swift

    var intercellSpacing: NSSize

    Objective-C

    @property NSSize intercellSpacing

    Return Value

    The vertical and horizontal spacing between cells in the receiver.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func makeCellAtRow(_ row: Int, column column: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of columns in the receiver.

    Declaration

    Swift

    var numberOfColumns: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfColumns

    Return Value

    The number of columns in the matrix.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the number of rows in the receiver.

    Declaration

    Swift

    var numberOfRows: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfRows

    Return Value

    The number of rows in the receiver.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Removes the specified column at from the receiver.

    Declaration

    Swift

    func removeColumn(_ column: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the width and height of each of the cells in the matrix.

    Declaration

    Swift

    var cellSize: NSSize

    Objective-C

    @property NSSize cellSize

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    calcSize (NSControl)
    – cellSize

  • Sets the spacing between cells in the matrix.

    Declaration

    Swift

    var intercellSpacing: NSSize

    Objective-C

    @property NSSize intercellSpacing

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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(_ comparator: CFunctionPointer<((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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    sortUsingSelector: (NSMutableArray)

  • Returns if the matrix auto-recalculates its cell size.

    Declaration

    Swift

    var autorecalculatesCellSize: Bool

    Objective-C

    @property BOOL autorecalculatesCellSize

    Return Value

    YEStrue if auto-recalculation occurs; otherwise NOfalse.

    Discussion

    When using Auto Layout, you typically want this to be set to YEStrue.

    The default is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.8 and later.

  • Sets whether the matrix auto-recalculates its cell size.

    Declaration

    Swift

    var autorecalculatesCellSize: Bool

    Objective-C

    @property BOOL autorecalculatesCellSize

    Parameters

    flag

    YEStrue if auto-recalculation should occur; otherwise NOfalse.

    Discussion

    If set to YEStrue, 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 Auto Layout.

    When using Auto Layout, you typically want this to be set to YEStrue.

    The default is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    .

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    selectCell: (NSControl)

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

    Declaration

    Swift

    unowned(unsafe) var keyCell: AnyObject?

    Objective-C

    @property(assign) id keyCell

    Parameters

    aCell

    The cell to set as the key cell.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    unowned(unsafe) var keyCell: AnyObject?

    Objective-C

    @property(assign) id keyCell

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the most recently selected cell.

    Declaration

    Objective-C

    @property(readonly, strong) id selectedCell

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver's selected and highlighted cells.

    Declaration

    Swift

    var selectedCells: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *selectedCells

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the column of the selected cell.

    Declaration

    Swift

    var selectedColumn: Int { get }

    Objective-C

    @property(readonly) NSInteger selectedColumn

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the row of the selected cell.

    Declaration

    Swift

    var selectedRow: Int { get }

    Objective-C

    @property(readonly) NSInteger selectedRow

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 column: Int) -> AnyObject?

    Objective-C

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

    Parameters

    row

    The number of the row containing the cell to return.

    column

    The number of the column containing the cell to return.

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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) -> AnyObject?

    Objective-C

    - (id)cellWithTag:(NSInteger)anInt

    Parameters

    anInt

    The tag of the cell to return.

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – selectCellWithTag:
    setTag: (NSActionCell)

  • Returns the cells of the matrix.

    Declaration

    Swift

    var cells: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *cells

    Return Value

    An array containing the cells of the receiver.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 column: Int) -> AnyObject?

    Objective-C

    - (id)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether pressing the Tab key advances the key cell to the next selectable cell.

    Declaration

    Swift

    var tabKeyTraversesCells: Bool

    Objective-C

    @property BOOL tabKeyTraversesCells

    Parameters

    flag

    YEStrue if pressing the Tab key should advance the key cell to the next selectable cell in the receiver. If this 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.

    Discussion

    Pressing Shift-Tab causes the key cell to advance in the opposite direction (if flag is NOfalse, or if there aren’t any selectable cells before the current one, the previous view in the window becomes key).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value indicating whether pressing the Tab key advances the key cell to the next selectable cell.

    Declaration

    Swift

    var tabKeyTraversesCells: Bool

    Objective-C

    @property BOOL tabKeyTraversesCells

    Return Value

    YEStrue if pressing the Tab key advances the key cell to the next selectable cell in the receiver; otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the cell sizes change when the receiver is resized.

    Declaration

    Swift

    var autosizesCells: Bool

    Objective-C

    @property BOOL autosizesCells

    Parameters

    flag

    YEStrue to 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 is NOfalse, then the intercell spacing and cell size remain constant.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var autosizesCells: Bool

    Objective-C

    @property BOOL autosizesCells

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    setFrameSize: (NSView)
    sizeToFit (NSControl)

  • Sets whether the receiver is automatically scrolled.

    Declaration

    Swift

    var autoscroll: Bool

    Objective-C

    @property(getter=isAutoscroll) BOOL autoscroll

    Parameters

    flag

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isAutoscroll - isAutoscroll Available in OS X v10.0 through OS X v10.9

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

    Declaration

    Objective-C

    - (BOOL)isAutoscroll

    Return Value

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

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

  • 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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the matrix's double-click action method.

    Declaration

    Swift

    var doubleAction: Selector

    Objective-C

    @property SEL doubleAction

    Return Value

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

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var mouseDownFlags: Int { get }

    Objective-C

    @property(readonly) NSInteger mouseDownFlags

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.