Class

NSMatrix

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

Overview

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

The NSMatrix class has the notion of a single selected cell, which is the cell that was most recently clicked or that was so designated by a select​Cell(at​Row:​column:​) or select​Cell(with​Tag:​) message. The selected cell is the cell chosen for action messages except for perform​Click(_:​) (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.

Symbols

Initializing an NSMatrix Object

init(frame:​ NSRect)

Initializes a newly allocated matrix with the specified frame.

init(frame:​ NSRect, mode:​ NSMatrix​Mode, cell​Class:​ Any​Class?, number​Of​Rows:​ Int, number​Of​Columns:​ Int)

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

init(frame:​ NSRect, mode:​ NSMatrix​Mode, prototype:​ NSCell, number​Of​Rows:​ Int, number​Of​Columns:​ Int)

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

Configuring the Matrix Object

var mode:​ NSMatrix​Mode

The selection mode of the receiver.

var allows​Empty​Selection:​ Bool

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

var is​Selection​By​Rect:​ Bool

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

Managing the Cell Class

var cell​Class:​ Any​Class

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

var prototype:​ NSCell?

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

Laying Out the Cells of the Matrix

func add​Column()

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

func add​Column(with:​ [NSCell])

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

func add​Row()

Adds a new row of cells below the last row.

func add​Row(with:​ [NSCell])

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

func cell​Frame(at​Row:​ Int, column:​ Int)

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

var cell​Size:​ NSSize

The size of each cell in the matrix.

func insert​Column(Int)

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

func insert​Column(Int, with:​ [NSCell]?)

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

func insert​Row(Int)

Inserts a new row of cells before the specified row.

func insert​Row(Int, with:​ [NSCell]?)

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

var intercell​Spacing:​ NSSize

The vertical and horizontal spacing between cells in the matrix.

func make​Cell(at​Row:​ Int, column:​ Int)

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

var number​Of​Columns:​ Int

The number of columns in the matrix.

var number​Of​Rows:​ Int

The number of rows in the matrix.

func put​Cell(NSCell, at​Row:​ Int, column:​ Int)

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

func remove​Column(Int)

Removes the specified column at from the receiver.

func remove​Row(Int)

Removes the specified row from the receiver.

func renew​Rows(Int, columns:​ Int)

Changes the number of rows and columns in the receiver.

func sort(using:​ (Any, Any, Unsafe​Mutable​Raw​Pointer?) -> Int, context:​ Unsafe​Mutable​Raw​Pointer?)

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

func sort(using:​ Selector)

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

Auto Layout Sizing

var autorecalculates​Cell​Size:​ Bool

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

Finding Matrix Coordinates

func get​Row(Unsafe​Mutable​Pointer<Int>, column:​ Unsafe​Mutable​Pointer<Int>, for:​ NSPoint)

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.

func get​Row(Unsafe​Mutable​Pointer<Int>, column:​ Unsafe​Mutable​Pointer<Int>, of:​ NSCell)

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

Managing Attributes of Individual Cells

func set​State(Int, at​Row:​ Int, column:​ Int)

Sets the state of the cell at specified location.

func tool​Tip(for:​ NSCell)

Returns the tooltip for the specified cell.

Selecting and Deselecting Cells

func select​Cell(at​Row:​ Int, column:​ Int)

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

func select​Cell(with​Tag:​ Int)

Selects the last cell with the given tag.

func select​All(Any?)

Selects and highlights all cells in the receiver.

var key​Cell:​ NSCell?

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

func deselect​All​Cells()

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

func deselect​Selected​Cell()

Deselects the selected cell or cells.

Finding Cells

var selected​Cells:​ [NSCell]

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

var selected​Column:​ Int

The column number of the selected cell.

var selected​Row:​ Int

The row number of the selected cell.

func cell(at​Row:​ Int, column:​ Int)

Returns the cell at the specified row and column.

func cell(with​Tag:​ Int)

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

var cells:​ [NSCell]

An array containing the cells of the matrix.

Modifying Graphics Attributes

var background​Color:​ NSColor

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

var cell​Background​Color:​ NSColor?

The background color of the matrix’s cells.

var draws​Background:​ Bool

A Boolean that indicates whether the matrix draws its background.

var draws​Cell​Background:​ Bool

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

Editing Text in Cells

func select​Text(Any?)

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

func select​Text(at​Row:​ Int, column:​ Int)

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

func text​Should​Begin​Editing(NSText)

Requests permission to begin editing text.

func text​Did​Begin​Editing(Notification)

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

func text​Did​Change(Notification)

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

func text​Should​End​Editing(NSText)

Requests permission to end editing.

func text​Did​End​Editing(Notification)

Invoked when text editing ends.

Setting Tab Key Behavior

var tab​Key​Traverses​Cells:​ Bool

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

Managing the Delegate

var delegate:​ NSMatrix​Delegate?

The delegate for messages from the field editor.

Resizing the Matrix and Its Cells

var autosizes​Cells:​ Bool

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

func set​Validate​Size(Bool)

Specifies whether the receiver's size information is validated.

func size​To​Cells()

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

Scrolling Cells in the Matrix

var is​Autoscroll:​ Bool

A Boolean that indicates whether the receiver is automatically scrolled.

func set​Scrollable(Bool)

Specifies whether the cells in the matrix are scrollable.

func scroll​Cell​To​Visible(at​Row:​ Int, column:​ Int)

Scrolls the receiver so the specified cell is visible.

Displaying and Highlighting Cells

func draw​Cell(at​Row:​ Int, column:​ Int)

Displays the cell at the specified row and column.

func highlight​Cell(Bool, at​Row:​ Int, column:​ Int)

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

Managing and Sending Action Messages

func send​Action()

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

func send​Action(Selector, to:​ Any, for​All​Cells:​ Bool)

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

var double​Action:​ Selector?

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

func send​Double​Action()

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

Handling Event and Action Messages

func accepts​First​Mouse(for:​ NSEvent?)

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

func mouse​Down(with:​ NSEvent)

Responds to a mouse-down event.

var mouse​Down​Flags:​ Int

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

func perform​Key​Equivalent(with:​ NSEvent)

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

Managing the Cursor

func reset​Cursor​Rects()

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

Constants

NSMatrix​Mode

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

Instance Methods