Next Page >

Hide TOC

Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

NSMatrix

Inherits from	NSControl : NSView : NSResponder : NSObject
Implements	NSCoding (NSResponder)
Package	com.apple.cocoa.application
Companion guide	Matrix Programming Guide for Cocoa

Overview

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

The cells in an NSMatrix 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). NSMatrix has the notion of a single selected cell, which is the cell that was most recently clicked or that was so designated by a selectCellAtLocation or selectCellWithTag message. The selected cell is the cell chosen for action messages except for performClick (NSCell), which is assigned to the key cell. (The key cell is generally identical to the selected cell, but can be given click focus while leaving the selected cell unchanged.) If the user has selected multiple cells, the selected cell is the one lowest and furthest to the right in the matrix of cells.

Tasks

Constructors

Setting the Selection Mode

Configuring the NSMatrix

Setting the Cell Class

Laying out the NSMatrix

Modifying Individual Cells

Selecting Cells

Finding Cells

Modifying Graphics Attributes

Editing Text in Cells

Setting Tab Key Behavior

Assigning a Delegate

Resizing the Matrix and Its Cells

Scrolling

Displaying

Target and Action

Handling Event and Action Messages

Managing the Cursor

Constructors

NSMatrix

Creates an empty NSMatrix.

public NSMatrix()

Creates an NSMatrix, with default parameters in the frame specified by frameRect.

public NSMatrix(NSRect frameRect)

Discussion

The new NSMatrix contains no rows or columns. The default mode is RadioMode. The default cell class is NSActionCell.

Creates an NSMatrix, in the frame specified by frameRect

public NSMatrix(NSRect frameRect, int aMode, NSCell aCell, int numRows, int numColumns)

Discussion

The new NSMatrix contains numRows rows and numColumns columns. aMode is set as the tracking mode for the NSMatrix and can be one of the modes described in “Constants.”

The new Matrix creates cells by copying aCell, which should be an instance of a subclass of NSCell.

Creates an NSMatrix, in the frame specified by frameRect.

public NSMatrix(NSRect frameRect, int aMode, Class aClass, int numRows, int numColumns)

Discussion

The new NSMatrix contains numRows rows and numColumns columns. aMode is set as the tracking mode for the NSMatrix and can be one of the modes described in “Constants.”

The new NSMatrix creates and uses cells of class aClass.

Instance Methods

acceptsFirstMouse

Returns false if the selection mode of the receiver is ListMode, true if the receiver is in any other selection mode.

public boolean acceptsFirstMouse(NSEvent theEvent)

Discussion

The receiver does not accept first mouse in ListMode to prevent the loss of multiple selections. The NSEvent parameter, theEvent, is ignored.

addColumn

Adds a new column of cells to the right of the last column, creating new cells as needed with makeCellAtLocation.

public void addColumn()

Discussion

This method throws a RangeException if there are 0 rows or 0 columns. Use renewRowsAndColumns to add new cells to an empty matrix.

If the number of rows or columns in the receiver has been changed with renewRowsAndColumns, 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.

addColumnWithCells

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

public void addColumnWithCells(NSArray newCells)

Discussion

The new column is filled with objects from newCells, starting with the object at index 0. Each object in newCells should be an instance of NSCell or one of its subclasses (usually NSActionCell). newCells 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.

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.

addRow

Adds a new row of cells below the last row, creating new cells as needed with makeCellAtLocation.

public void addRow()

Discussion

This method throws a RangeException if there are 0 rows or 0 columns. Use renewRowsAndColumns to add new cells to an empty matrix.

If the number of rows or columns in the receiver has been changed with renewRowsAndColumns, 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.

addRowWithCells

Adds a new row of cells below the last row.

public void addRowWithCells(NSArray newCells)

Discussion

The new row is filled with objects from newCells, starting with the object at index 0. Each object in newCells should be an instance of NSCell or one of its subclasses (usually NSActionCell). newCells should have 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.

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.

allowsEmptySelection

Returns whether it’s possible to have no cells selected in a radio-mode matrix.

public boolean allowsEmptySelection()

autosizesCells

public boolean autosizesCells()

Discussion

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

backgroundColor

Returns the color used to draw the background of the receiver (the space between the cells).

public NSColor backgroundColor()

cellAtLocation

Returns the NSCell object at the location specified by row and column, or null if either row or column is outside the bounds of the receiver.

public NSCell cellAtLocation(int row, int column)

cellBackgroundColor

Returns the color used to fill the background of the receiver’s cells.

public NSColor cellBackgroundColor()

cellFrameAtLocation

Returns the frame rectangle of the cell that would be drawn at the location specified by row and column (whether or not the specified cell actually exists).

public NSRect cellFrameAtLocation(int row, int column)

cells

Returns an NSArray that contains the receiver’s cells.

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

cellSize

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

public NSSize cellSize()

cellWithTag

Searches the receiver and returns the last (when viewing the matrix as a row-ordered array) NSCell object that has a tag matching anInt, or null if no such cell exists.

public NSCell cellWithTag(int anInt)

columnForPoint

Returns the column for the cell within which the specified point lies.

public int columnForPoint(NSPoint aPoint)

Discussion

If aPoint falls outside the bounds of the receiver or lies within an intercell spacing, this method returns –1.

Make sure aPoint is in the coordinate system of the receiver.

columnOfCell

Searches the receiver for aCell and returns the column of the cell.

public int columnOfCell(NSCell aCell)

Discussion

If aCell is not found within the receiver, this method returns –1.

delegate

Returns the delegate for messages from the field editor.

public Object delegate()

deselectAllCells

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

public void deselectAllCells()

Discussion

If the selection mode is RadioMode and empty selection is not allowed, this method does nothing.

deselectSelectedCell

Deselects the selected cell or cells.

public void deselectSelectedCell()

Discussion

If the selection mode is RadioMode and empty selection is not allowed, or if nothing is currently selected, this method does nothing. This method doesn’t redisplay the receiver.

doubleAction

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

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

drawCellAtLocation

Displays the cell at the specified row and column, providing that row and column reference a cell within the receiver.

public void drawCellAtLocation(int row, int column)

drawsBackground

Returns whether the receiver draws its background (the space between the cells).

public boolean drawsBackground()

drawsCellBackground

Returns whether the receiver draws the background within each of its cells.

public boolean drawsCellBackground()

highlightCellAtLocation

Assuming that row and column indicate a valid cell within the receiver, this method highlights (if flag is true) or unhighlights (if flag is false) the specified cell.

public void highlightCellAtLocation(boolean flag, int row, int column)

insertColumn

Inserts a new column of cells before column, creating new cells if needed with makeCellAtLocation.

public void insertColumn(int column)

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

insertColumnWithCells

Inserts a new column of cells before column.

public void insertColumnWithCells(int column, NSArray newCells)

Discussion

The new column is filled with objects from newCells, starting with the object at index 0. Each object in newCells should be an instance of NSCell or one of its subclasses (usually NSActionCell). 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 null 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.

insertRow

Inserts a new row of cells before row, creating new cells if needed with makeCellAtLocation.

public void insertRow(int row)

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

insertRowWithCells

Inserts a new row of cells before row.

public void insertRowWithCells(int row, NSArray newCells)

Discussion

The new row is filled with objects from newCells, starting with the object at index 0. Each object in newCells should be an instance of NSCell or one of its subclasses (usually NSActionCell). 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 null 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.

intercellSpacing

Returns the vertical and horizontal spacing between cells in the receiver.

public NSSize intercellSpacing()

isAutoscroll

Returns whether the receiver will be automatically scrolled whenever the cursor is dragged outside the receiver after a mouse-down event within its bounds.

public boolean isAutoscroll()

isSelectionByRect

Returns true if the user can select a rectangle of cells in the receiver by dragging the cursor, false otherwise.

public boolean isSelectionByRect()

keyCell

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

public NSCell keyCell()

makeCellAtLocation

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

public NSCell makeCellAtLocation(int row, int column)

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 creates an instance of that class. If the receiver hasn’t had either a prototype cell or a cell class set, makeCellAtLocation creates an NSActionCell. Returns the newly created cell.

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.

mode

public int mode()

Discussion

Returns the selection mode of the receiver. Possible return values are listed in “Constants.”

mouseDown

Responds to theEvent mouse-down event.

public void mouseDown(NSEvent theEvent)

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.

mouseDownFlags

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

public int mouseDownFlags()

Discussion

NSMatrix’s mouseDown 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).

newCellClass

Returns the subclass of NSCell that the receiver uses when creating new (empty) cells.

public Class newCellClass()

numberOfColumns

Returns the number of columns in the receiver.

public int numberOfColumns()

numberOfRows

Returns the number of rows in the receiver.

public int numberOfRows()

performKeyEquivalent

public boolean performKeyEquivalent(NSEvent theEvent)

Discussion

If there’s a cell in the receiver that has a key equivalent equal to the character in [theEvent charactersIgnoringModifiers] (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. Returns true if a cell in the receiver responds to the key equivalent in theEvent, false if no cell responds.

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.

prototype

Returns the prototype cell that’s copied whenever a new cell needs to be created, or null if there is none.

public NSCell prototype()

putCellAtLocation

Replaces the cell at the location specified by row and column with newCell and redraws the cell.

public void putCellAtLocation(NSCell newCell, int row, int column)

removeColumn

Removes the column at position column from the receiver and autoreleases the column’s cells.

public void removeColumn(int column)

Discussion

Redraws the receiver. Your code should normally send sizeToCells after invoking this method to resize the receiver so it fits the reduced cell count.

removeRow

Removes the row at position row from the receiver and autoreleases the row’s cells.

public void removeRow(int row)

Discussion

Redraws the receiver. Your code should normally send sizeToCells after invoking this method to resize the receiver so it fits the reduced cell count.

renewRowsAndColumns

Changes the number of rows and columns in the receiver.

public void renewRowsAndColumns(int newRows, int newCols)

Discussion

This method uses the same cells as before, creating new cells only if the new size is larger; it never frees cells. 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.

resetCursorRects

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

public void resetCursorRects()

Discussion

It does this by sending resetCursorRect to each cell in the receiver. Any cell that has a cursor rectangle to set up should then send addCursorRect back to the receiver.

rowForPoint

Returns the row for the cell within which the specified point lies.

public int rowForPoint(NSPoint aPoint)

Discussion

If aPoint falls outside the bounds of the receiver or lies within an intercell spacing, this method returns –1.

Make sure aPoint is in the coordinate system of the receiver.

rowOfCell

Searches the receiver for aCell and returns the row of the cell.

public int rowOfCell(NSCell aCell)

Discussion

If aCell is not found within the receiver, this method returns –1.

scrollCellAtLocationToVisible

If the receiver is in a scrolling view, and row and column represent a valid cell within the receiver, this method scrolls the receiver so the specified cell is visible.

public void scrollCellAtLocationToVisible(int row, int column)

selectAll

Selects and highlights all cells in the receiver, except for editable text cells and disabled cells.

public void selectAll(Object sender)

Discussion

Redisplays the receiver. sender is ignored.

selectCellAtLocation

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

public void selectCellAtLocation(int row, int column)

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 RadioMode and doesn’t allow empty selection). Redraws the affected cells.

selectCellWithTag

If the receiver 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.

public boolean selectCellWithTag(int anInt)

Discussion

If the specified cell is an editable text cell, its text is selected. Returns true if the receiver contains a cell whose tag matches anInt, or false if no such cell exists.

selectedCell

Returns the most recently selected cell, or null if no cell is selected.

public NSCell selectedCell()

Discussion

If more than one cell is selected, this method returns the cell that is lowest and farthest to the right in the receiver.

selectedCells

Returns an array containing all of the receiver’s highlighted cells plus its selected cell.

public NSArray selectedCells()

Discussion

See the class description for a discussion of the selected cell.

As an alternative to using setSelectionWithAnchor 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; aftewards you can call selectedCells to obtain the selection of cells.

selectedColumn

Returns the column number of the selected cell, or –1 if no cells are selected.

public int selectedColumn()

Discussion

If cells in multiple columns are selected, this method returns the number of the last (rightmost) column containing a selected cell.

selectedRow

Returns the row number of the selected cell, or –1 if no cells are selected.

public int selectedRow()

Discussion

If cells in multiple rows are selected, this method returns the number of the last row containing a selected cell.

selectText

public void selectText(Object sender)

Discussion

If the currently selected cell is editable and enabled, its text is selected. Otherwise, the key cell is selected.

selectTextAtLocation

public Object selectTextAtLocation(int row, int column)

Discussion

If row and column indicate a valid cell within the receiver, and that cell is both editable and selectable, this method selects and then returns the specified cell. If the cell specified by row and column is either not editable or not selectable, this method does nothing, and returns null. Finally, if row and column indicate a cell that is outside the receiver, this method does nothing and returns the receiver.

sendAction

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

public boolean sendAction()

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. Returns true if an action was successfully sent to a target.

If the selected cell is disabled, this method does nothing and returns false.

sendActionToTargetForAllCells

Iterates through all cells in the receiver (if flag is true) or just the selected cells in the receiver (if flag is false), sending aSelector to anObject for each.

public void sendActionToTargetForAllCells(NSSelector aSelector, Object anObject, boolean flag)

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.

The aSelector argument 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 boolean. If aSelector returns false for any cell, sendActionToTargetForAllCells terminates immediately, without sending the message for the remaining cells. If it returns true, sendActionToTargetForAllCells proceeds to the next cell.

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.

sendDoubleAction

public void sendDoubleAction()

Discussion

If the receiver has a double-click action, sendDoubleAction sends that message to the target of the receiver. If not, then if the selected cell (as returned by selectedCell) has an action, that message 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.

setAllowsEmptySelection

public void setAllowsEmptySelection(boolean flag)

Discussion

If flag is true, then the receiver will allow one or zero cells to be selected. If flag is false, then the receiver will allow one and only one cell (not zero cells) to be selected. This setting has effect only in the RadioMode selection mode.

setAutoscroll

public void setAutoscroll(boolean flag)

Discussion

If flag is true and the receiver is in a scrolling view, it will be automatically scrolled whenever the cursor is dragged outside the receiver after a mouse-down event within the bounds of the receiver.

setAutosizesCells

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

public void setAutosizesCells(boolean flag)

Discussion

If flag is true, then 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 false, then the intercell spacing and cell size remain constant.

setBackgroundColor

Sets the background color for the receiver to aColor and redraws the receiver.

public void setBackgroundColor(NSColor aColor)

Discussion

This color is used to fill the space between cells or the space behind any nonopaque cells. The default background color is NSColor’s controlColor.

setCellBackgroundColor

Sets the background color for the cells in the receiver to aColor.

public void setCellBackgroundColor(NSColor aColor)

Discussion

This color is used to fill the space behind nonopaque cells. The default cell background color is NSColor’s controlColor.

setCellSize

Sets the width and height of each of the cells in the receiver to those in aSize.

public void setCellSize(NSSize aSize)

Discussion

This method may change the size of the receiver. Does not redraw the receiver.

setDelegate

Sets the delegate for messages from the field editor to anObject.

public void setDelegate(Object anObject)

setDoubleAction

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

public void setDoubleAction(NSSelector aSelector)

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

For the method to have any effect, the receiver’s action and target must be set to the class in which the selector is declared. See Action Messages for additional information on action messages.

setDrawsBackground

Sets whether the receiver draws its background (the space between the cells) to flag.

public void setDrawsBackground(boolean flag)

setDrawsCellBackground

Sets whether the receiver draws the background within each of its cells to flag.

public void setDrawsCellBackground(boolean flag)

setIntercellSpacing

Sets the vertical and horizontal spacing between cells in the receiver to aSize.

public void setIntercellSpacing(NSSize aSize)

Discussion

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

setKeyCell

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

public void setKeyCell(NSCell aCell)

setMode

Sets the selection mode of the receiver.

public void setMode(int aMode)

Discussion

Possible values for aMode are listed in “Constants.”

setNewCellClass

Configures the receiver to use instances of aClass when creating new cells.

public void setNewCellClass(Class aClass)

Discussion

aClass should be the id of a subclass of NSCell, which can be obtained by sending the class message to either the NSCell subclass object or to an instance of that subclass. The default cell class is that set with the class method setCellClass, or NSActionCell if no other default cell class has been specified.

setPrototype

Sets the prototype cell that’s copied whenever a new cell needs to be created.

public void setPrototype(NSCell aCell)

setScrollable

public void setScrollable(boolean flag)

Discussion

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

setSelectionByRect

Sets whether the user can select a rectangle of cells in the receiver by dragging the cursor.

public void setSelectionByRect(boolean flag)

Discussion

If flag is false, selection is on a row-by-row basis. The default is true.

setSelectionWithAnchor

Programmatically selects a range of cells.

public void setSelectionWithAnchor(int startPos, int endPos, int anchorPos, boolean lit)

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. The startPos and endPos arguments are used to mark where the user would have pressed the mouse button and released it, respectively.

anchorPos specifies which 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. To simulate dragging without a modifier key, deselecting anything that was selected before, call deselectAllCells before calling this method.

Finally, lit determines whether cells selected by this method should be highlighted.

setStateAtLocation

Sets the state of the cell at row and column to value.

public void setStateAtLocation(int value, int row, int column)

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.

setTabKeyTraversesCells

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

public void setTabKeyTraversesCells(boolean flag)

Discussion

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

setToolTip

Sets the tooltip for cell to be toolTipString.

public void setToolTip(String toolTipString, NSCell cell)

setValidateSize

If flag is true, then the size information in the receiver is assumed to be correct.

public void setValidateSize(boolean flag)

Discussion

If flag is false, NSControl’s calcSize method will be invoked before any further drawing is done.

sizeToCells

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

public void sizeToCells()

Discussion

Does not redraw the receiver.

sortUsingMethod

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

public void sortUsingMethod(NSSelector comparator)

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 OrderedAscending if the receiver is smaller than the argument, OrderedDescending if the receiver is larger than the argument, and OrderedSame if they are equal.

tabKeyTraversesCells

Returns whether pressing the Tab key advances the key cell to the next selectable cell in the receiver.

public boolean tabKeyTraversesCells()

textDidBeginEditing

Invoked when notification is posted indicating that there’s a change in the text after the receiver gains first responder status.

public void textDidBeginEditing(NSNotification notification)

Discussion

This method’s default behavior is to post a ControlTextDidBeginEditingNotification 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 “FieldEditor”; the value for this key is the text object that began editing.

textDidChange

Invoked when notification is posted indicating a key-down event or paste operation that changes the receiver’s contents.

public void textDidChange(NSNotification 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 a ControlTextDidChangeNotification 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 “FieldEditor”; the value for this key is the text object that changed.

textDidEndEditing

Invoked when notification is posted indicating that text editing ends.

public void textDidEndEditing(NSNotification notification)

Discussion

This method’s default behavior is to post a ControlTextDidEndEditingNotification 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 “FieldEditor”; 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).

textShouldBeginEditing

Invoked to let the NSTextField respond to impending changes to its text.

public boolean textShouldBeginEditing(NSText textObject)

Discussion

This method’s default behavior is to send controlTextShouldBeginEditing to the receiver’s delegate (passing the receiver and textObject as parameters). The textShouldBeginEditing method returns the value obtained from controlTextShouldBeginEditing, unless the delegate doesn’t respond to that method, in which case it returns true, thereby allowing text editing to proceed.

textShouldEndEditing

Invoked to let the NSTextField respond to impending loss of first-responder status.

public boolean textShouldEndEditing(NSText textObject)

Discussion

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, controlTextShouldEndEditing is sent to the receiver’s delegate (passing the receiver and textObject as parameters). If the contents of the text field aren’t valid, textShouldEndEditing sends the error action to the selected cell’s target.

The textShouldEndEditing method returns false if the text field contains invalid contents; otherwise it returns the value passed back from controlTextShouldEndEditing.

toolTip

Returns the string used as the tooltip for cell.

public String toolTip(NSCell cell)

Constants

These constants determine how NSCells behave when the NSMatrix is tracking the mouse.

Constant	Description
`TrackMode`	The NSCells are asked to track the mouse with `trackMouse` whenever the cursor is inside their bounds. No highlighting is performed.
`HighlightMode`	An NSCell is highlighted before it’s asked to track the mouse, then unhighlighted when it’s done tracking.
`RadioMode`	Selects no more than one NSCell at a time. Any time an NSCell is selected, the previously selected NSCell is unselected.
`ListMode`	NSCells are highlighted, but don’t track the mouse.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Legacy Document

NSMatrix

Overview

Tasks

Constructors

Setting the Selection Mode

Configuring the NSMatrix

Setting the Cell Class

Laying out the NSMatrix

Modifying Individual Cells

Selecting Cells

Finding Cells

Modifying Graphics Attributes

Editing Text in Cells

Setting Tab Key Behavior

Assigning a Delegate

Resizing the Matrix and Its Cells

Scrolling

Displaying

Target and Action

Handling Event and Action Messages

Managing the Cursor

Constructors

NSMatrix

Discussion

Discussion

Discussion

Instance Methods

acceptsFirstMouse

Discussion

See Also

addColumn

Discussion

See Also

addColumnWithCells

Discussion

See Also

addRow

Discussion

See Also

addRowWithCells

Discussion

See Also

allowsEmptySelection

See Also

autosizesCells

Discussion

See Also

backgroundColor

See Also

cellAtLocation

See Also

cellBackgroundColor

See Also

cellFrameAtLocation

See Also

cells

Discussion

See Also

cellSize

See Also

cellWithTag

See Also

columnForPoint

Discussion

See Also

columnOfCell

Discussion

See Also

delegate

See Also

deselectAllCells

Discussion

See Also

deselectSelectedCell

Discussion

See Also

doubleAction

Discussion

See Also