PATH  Documentation > Mac OS X > Application Kit Reference: Java

Table of Contents

NSMatrix


Inherits from:
NSControl : NSView : NSResponder : NSObject
Package:
com.apple.yellow.application


Class Description


NSMatrix is a class used for creating groups of NSCells that work together in various ways. It includes methods for arranging NSCells in rows and columns, either with or without space between them. NSCells 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).

The cell objects that an NSMatrix contains are usually of a single subclass of NSCell, but they can be of multiple subclasses of NSCell. The only restriction is that all cell objects must be the same size. An NSMatrix can be set up to create new NSCells by copying a prototype object, or by allocating and initializing instances of a specific NSCell class. Cells created by or added to an NSMatrix are retained by the matrix.

An NSMatrix adds to NSControl's target/action paradigm by allowing a separate target and action for each of its NSCells in addition to its own target and action. It also allows for an action message that's sent when the user double-clicks an NSCell, which is sent in addition to the single-click action message. If an NSCell doesn't have an action, the NSMatrix sends its own action to its own target. If an NSCell doesn't have a target, the NSMatrix sends the NSCell's action to its own target. The double-click action of an NSMatrix is always sent to the target of the NSMatrix.

Since the user might press the mouse button while the cursor is within the NSMatrix and then drag the mouse around, NSMatrix offers four "selection modes" that determine how NSCells behave when the NSMatrix is tracking the mouse:




Constants


These constants determine how NSCells behave when the NSMatrix is tracking the mouse. For more information, see the Class Description.


Constant Description
TrackMode The NSCells are asked to track the mouse with trackMouse whenever the mouse is inside their bounds. No highlighting is performed.l
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.



Method Types


Constructors
NSMatrix
Setting the selection mode
mode
setMode
Configuring the NSMatrix
allowsEmptySelection
isSelectionByRect
setAllowsEmptySelection
setSelectionByRect
Setting the cell class
newCellClass
prototype
setNewCellClass
setPrototype
Laying out the NSMatrix
addColumn
addColumnWithCells
addRow
addRowWithCells
cellFrameAtLocation
cellSize
insertColumn
insertColumnWithCells
insertRow
insertRowWithCells
intercellSpacing
makeCellAtLocation
numberOfColumns
numberOfRows
putCellAtLocation
removeColumn
removeRow
renewRowsAndColumns
setCellSize
setIntercellSpacing
sortUsingMethod
Modifying individual cells
setStateAtLocation
Selecting cells
deselectAllCells
deselectSelectedCell
keyCell
selectAll
selectCellAtLocation
selectCellWithTag
selectedCell
selectedCells
selectedColumn
selectedRow
setKeyCell
setSelectionWithAnchor
Finding cells
cellAtLocation
cellWithTag
cells
columnForPoint
columnOfCell
rowForPoint
rowOfCell
Modifying graphic attributes
backgroundColor
cellBackgroundColor
drawsBackground
drawsCellBackground
setBackgroundColor
setCellBackgroundColor
setDrawsBackground
setDrawsCellBackground
Editing text in cells
selectText
selectTextAtLocation
textDidBeginEditing
textDidChange
textDidEndEditing
textShouldBeginEditing
textShouldEndEditing
Setting tab key behavior
nextText
previousText
setNextText
setPreviousText
setTabKeyTraversesCells
tabKeyTraversesCells
Assigning a delegate
delegate
setDelegate
Resizing the matrix and its cells
autosizesCells
setAutosizesCells
setValidateSize
sizeToCells
Scrolling
isAutoscroll
scrollCellAtLocationToVisible
setAutoscroll
setScrollable
Displaying
drawCellAtLocation
highlightCellAtLocation
Target and action
doubleAction
errorAction
sendAction
sendActionToTargetForAllCells
sendDoubleAction
setDoubleAction
setErrorAction
Handling event and action messages
acceptsFirstMouse
mouseDown
mouseDownFlags
performKeyEquivalent
Managing the cursor
resetCursorRects


Constructors



NSMatrix

public NSMatrix()

Description forthcoming.

public NSMatrix(NSRect frameRect)

Creates an NSMatrix, with default parameters in the frame specified by frameRect. The new NSMatrix contains no rows or columns. The default mode is RadioMode. The default cell class is NSActionCell.

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

Creates an NSMatrix, in the frame specified by frameRect. 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.

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

Creates an NSMatrix, in the frame specified by frameRect. 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

public boolean acceptsFirstMouse(NSEvent theEvent)

Returns false if the selection mode of the NSMatrix is ListMode, true if the NSMatrix is in any other selection mode. The NSMatrix does not accept first mouse in ListMode to prevent the loss of multiple selections. The NSEvent parameter, theEvent, is ignored.

See Also: mode



addColumn

public void addColumn()

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

If the number of rows or columns in the NSMatrix has been changed with renewRowsAndColumns, new cells are created only if they are needed. This allows you to grow and shrink an NSMatrix without repeatedly creating and freeing the cells.

This method doesn't redraw the NSMatrix. Accordingly, after calling this method you should send setNeedsDisplay to the NSMatrix. Your code may also need to use sizeToCells after sending this method to resize the NSMatrix to fit the newly added cells.

See Also: newCellClass, insertColumn, prototype



addColumnWithCells

public void addColumnWithCells(NSArray newCells)

Adds a new column of cells to the right of the last column. 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 doesn't redraw the NSMatrix. Accordingly, after calling this method you should send setNeedsDisplay to the NSMatrix. Your code may also need to use sizeToCells after sending this method to resize the NSMatrix to fit the newly added cells.

See Also: insertColumnWithCells



addRow

public void addRow()

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

If the number of rows or columns in the NSMatrix has been changed with renewRowsAndColumns, then new cells are created only if they are needed. This allows you to grow and shrink an NSMatrix without repeatedly creating and freeing the cells.

This method doesn't redraw the NSMatrix. Accordingly, after calling this method you should send setNeedsDisplay to the NSMatrix. Your code may also need to use sizeToCells after sending this method to resize the NSMatrix to fit the newly added cells.

See Also: newCellClass, insertRow, prototype



addRowWithCells

public void addRowWithCells(NSArray newCells)

Adds a new row of cells below the last row. 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 doesn't redraw the NSMatrix. Accordingly, after calling this method you should send setNeedsDisplay to the NSMatrix. Your code may also need to use sizeToCells after sending this method to resize the NSMatrix to fit the newly added cells.

See Also: insertRowWithCells



allowsEmptySelection

public boolean allowsEmptySelection()

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

See Also: mode



autosizesCells

public boolean autosizesCells()

Returns true if cells are resized proportionally to the NSMatrix when its size changes (and inter-cell spacing is kept constant). Returns false if the cell size remains constant (and inter-cell spacing changes).

backgroundColor

public NSColor backgroundColor()

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

See Also: cellBackgroundColor, drawsBackground



cellAtLocation

public NSCell cellAtLocation( int row, int column)

Returns the NSCell object at row and column, or null if either row or column are outside the bounds of the NSMatrix.

See Also: getRow:column:ofCell:



cellBackgroundColor

public NSColor cellBackgroundColor()

Returns the color used to fill the background of the NSMatrix's cells.

See Also: backgroundColor, drawsCellBackground



newCellClass

public Class newCellClass()

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

See Also: prototype, makeCellAtLocation



cellFrameAtLocation

public NSRect cellFrameAtLocation( int row, int column)

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

See Also: cellSize



cellSize

public NSSize cellSize()

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

See Also: cellFrameAtLocation, intercellSpacing



cellWithTag

public NSCell cellWithTag(int anInt)

Searches the NSMatrix 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.

See Also: selectCellWithTag, setTag (NSActionCell)



cells

public NSArray cells()

Returns an NSArray that contains the NSMatrix's cells. The cells in the array are row-ordered; that is, the first row of cells appear first in the array, followed by the second row, and so forth.

See Also: cellAtLocation



columnForPoint

public int columnForPoint(NSPoint aPoint)

Returns the column for the cell within which the specified point lies. If aPoint falls outside the bounds of the receiver or lies within an intercell spacing, this method returns <<WHAT?>>.

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

See Also: getRow:column:ofCell:



columnOfCell

public int columnOfCell(NSCell aCell)

Searches the NSMatrix for aCell and returns the column of the cell. If aCell is not found within the receiver, this method returns <<WHAT?>>.

See Also: getRow:column:forPoint:



delegate

public Object delegate()

Returns the delegate for messages from the field editor.

See Also: textShouldBeginEditing, textShouldEndEditing



deselectAllCells

public void deselectAllCells()

Deselects all cells in the NSMatrix and, if necessary, redisplays the NSMatrix. If the selection mode is RadioMode and empty selection is not allowed, this method does nothing.

See Also: allowsEmptySelection, mode, selectAll



deselectSelectedCell

public void deselectSelectedCell()

Deselects the selected cell or cells. 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 NSMatrix.

See Also: allowsEmptySelection, mode, selectCellAtLocation



doubleAction

public NSSelector doubleAction()

- (SEL)doubleAction

Returns the action method sent by the NSMatrix to its target when the user double-clicks an entry, or null if there's no double-click action. 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.

See Also: action (NSControl), target (NSControl), ignoresMultiClick (NSControl), sendDoubleAction



drawCellAtLocation

public void drawCellAtLocation( int row, int column)

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

See Also: drawCell (NSControl), drawCellInside (NSControl)



drawsBackground

public boolean drawsBackground()

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

See Also: backgroundColor, drawsCellBackground



drawsCellBackground

public boolean drawsCellBackground()

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

See Also: cellBackgroundColor, drawsBackground



errorAction

public NSSelector errorAction()

Returns the action sent to the target of the NSMatrix when the user enters an illegal value for the selected cell.

See Also: action (NSControl), target (NSControl), textShouldEndEditing



highlightCellAtLocation

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

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.

insertColumn

public void insertColumn(int column)

Inserts a new column of cells before column, creating new cells if needed with makeCellAtLocation. 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 doesn't redraw the receiver. Accordingly, after calling this method you should send setNeedsDisplay to the receiver. Your code may also need to use 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 allows you to grow and shrink an NSMatrix without repeatedly creating and freeing the cells.

See Also: addColumn, insertRow



insertColumnWithCells

public void insertColumnWithCells( int column, NSArray newCells)

Inserts a new column of cells before column. 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 doesn't redraw the receiver. Accordingly, after calling this method you should send setNeedsDisplay to the receiver. Your code may also need to use sizeToCells after sending this method to resize the receiver to fit the newly added cells.

See Also: addColumnWithCells, insertRowWithCells



insertRow

public void insertRow(int row)

Inserts a new row of cells before row, creating new cells if needed with makeCellAtLocation. 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 doesn't redraw the receiver. Accordingly, after calling this method you should send setNeedsDisplay to the receiver. Your code may also need to use 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 allows you to grow and shrink an NSMatrix without repeatedly creating and freeing the cells.

See Also: addRow, insertColumn



insertRowWithCells

public void insertRowWithCells( int row, NSArray newCells)

Inserts a new row of cells before row. 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 doesn't redraw the receiver. Accordingly, after calling this method you should send setNeedsDisplay to the receiver. Your code may also need to use sizeToCells after sending this method to resize the receiver to fit the newly added cells.

See Also: addRowWithCells, insertColumnWithCells



intercellSpacing

public NSSize intercellSpacing()

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

See Also: cellSize



isAutoscroll

public boolean isAutoscroll()

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

See Also: scrollCellAtLocationToVisible, setScrollable



isSelectionByRect

public boolean isSelectionByRect()

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

See Also: setSelectionWithAnchor



keyCell

public NSCell keyCell()

Returns the cell that will be clicked when the user presses the Return key.

See Also: nextText , tabKeyTraversesCells



makeCellAtLocation

public NSCell makeCellAtLocation( int row, int column)

Creates a new cell at the specified location in the receiver. 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, 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.

See Also: addColumn, addRow, insertColumn, insertRow, setNewCellClass, setPrototype



mode

public int mode()

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

mouseDown

public void mouseDown(NSEvent theEvent)

Responds to a mouse-down event. 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.

See Also: sendAction, sendDoubleAction



mouseDownFlags

public int mouseDownFlags()

Returns the flags in effect at the mouse-down event that started the current tracking session. 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 PopUpList does, for example).

See Also: setEventMaskForSendingAction (NSCell)



nextText

public Object nextText()

Returns the object that would be selected if the user presses Tab while editing the last text cell in the receiver.

See Also: nextKeyView (NSView), previousText, setNextText



numberOfColumns

public int numberOfColumns()

Returns the number of columns in the receiver.

See Also: getNumberOfRows:columns:



numberOfRows

public int numberOfRows()

Returns the number of rows in the receiver.

See Also: getNumberOfRows:columns:



performKeyEquivalent

public boolean performKeyEquivalent(NSEvent theEvent)

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.



previousText

public Object previousText()

Returns the object that would be selected if the user presses Shift-Tab while editing the first text cell in the receiver.

See Also: nextKeyView (NSView), nextText, setPreviousText



prototype

public NSCell prototype()

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

See Also: makeCellAtLocation



putCellAtLocation

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

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

removeColumn

public void removeColumn(int column)

Removes the column at position column from the receiver and autoreleases the column's cells. Doesn't redraw the receiver. Your code should normally send sizeToCells after invoking this method to resize the receiver so it fits the reduced cell count.

See Also: removeRow, addColumn, insertColumn



removeRow

public void removeRow(int row)

Removes the row at position row from the receiver and autoreleases the row's cells. Doesn't redraw the receiver. Your code should normally send sizeToCells after invoking this method to resize the receiver so it fits the reduced cell count.

See Also: removeColumn, addRow, insertRow



renewRowsAndColumns

public void renewRowsAndColumns( int newRows, int newCols)

Changes the number of rows and columns in the receiver. 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.

See Also: addColumn, addRow, removeColumn, removeRow



resetCursorRects

public void resetCursorRects()

Resets cursor rectangles so the cursor becomes an I-beam over text cells. 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.

See Also: resetCursorRect (NSCell), addCursorRect (NSView)



rowForPoint

public int rowForPoint(NSPoint aPoint)

Returns the row for the cell within which the specified point lies. If aPoint falls outside the bounds of the receiver or lies within an intercell spacing, this method returns <<WHAT?>>.

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

See Also: getRow:column:ofCell:



rowOfCell

public int rowOfCell(NSCell aCell)

Searches the receiver for aCell and returns the row of the cell. If aCell is not found within the receiver, this method returns <<WHAT?>>.

See Also: getRow:column:forPoint:



scrollCellAtLocationToVisible

public void scrollCellAtLocationToVisible( int row, int column)

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.

See Also: scrollRectToVisible (NSView)



selectAll

public void selectAll(Object sender)

Selects and highlights all cells in the receiver, except for editable text cells and disabled cells. Redisplays the receiver. sender is ignored.

See Also: selectCell (NSControl)



selectCellAtLocation

public void selectCellAtLocation( int row, int column)

Selects the cell at the specified row and column within the receiver. 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.

See Also: allowsEmptySelection, mode, selectCell (NSControl)



selectCellWithTag

public boolean selectCellWithTag(int anInt)

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

See Also: cellWithTag, selectCell (NSControl)



selectText

public void selectText(Object sender)

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

See Also: keyCell, selectText (NSTextField)



selectTextAtLocation

public Object selectTextAtLocation( int row, int column)

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.

See Also: selectText



selectedCell

public NSCell selectedCell()

Returns the most recently selected cell, or null if no cell is selected. If more than one cell is selected, this method returns the cell that is lowest and furthest to the right in the receiver.

selectedCells

public NSArray selectedCells()

Returns an array containing all of the receiver's highlighted cells.

See Also: selectedCell



selectedColumn

public int selectedColumn()

Returns 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 (right-most) column containing a selected cell.

selectedRow

public int selectedRow()

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

sendAction

public boolean sendAction()

If the selected cell has both an action and a target, its action is sent to its target. 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.

See Also: sendDoubleAction, action (NSCell), target (NSCell)



sendActionToTargetForAllCells

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

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

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

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.

See Also: sendAction, ignoresMultiClick (NSControl)



setAllowsEmptySelection

public void setAllowsEmptySelection(boolean flag)

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)

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

setAutosizesCells

public void setAutosizesCells(boolean flag)

Sets whether the cell sizes or the inter-cell spacing change when the receiver is resized. If flag is true, then whenever the receiver is resized, the sizes of the cells change in proportion, keeping the inter-cell space constant; further, this method verifies that the cell sizes and inter-cell 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 inter-cell space changes when the receiver is resized, with the cell size remaining constant.

setBackgroundColor

public void setBackgroundColor(NSColor aColor)

Sets the background color for the receiver to aColor, and redraws the receiver. This color is used to fill the space between cells or the space behind any non-opaque cells. The default background color is NSColor's controlColor.

See Also: drawsBackground, setCellBackgroundColor



setCellBackgroundColor

public void setCellBackgroundColor(NSColor aColor)

Sets the background color for the cells in the receiver to aColor. This color is used to fill the space behind non-opaque cells. The default cell background color is NSColor's controlColor.

See Also: drawsCellBackground, setBackgroundColor



setNewCellClass

public void setNewCellClass(Class aClass)

Configures the receiver to use instances of aClass when creating new cells. 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.

See Also: addColumn, addRow, insertColumn, insertRow, makeCellAtLocation, setPrototype



setCellSize

public void setCellSize(NSSize aSize)

Sets the width and height of each of the cells in the receiver to those in aSize. This may change the size of the receiver. Does not redraw the receiver.

See Also: calcSize (NSControl)



setDelegate

public void setDelegate(Object anObject)

Sets the delegate for messages from the field editor.

See Also: textShouldBeginEditing, textShouldEndEditing



setDoubleAction

public void setDoubleAction(NSSelector aSelector)

Makes aSelector the action sent to the target of the receiver when the user double-clicks a cell. 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 valid 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.

See Also: sendDoubleAction, setAction (NSControl), setTarget (NSControl)



setDrawsBackground

public void setDrawsBackground(boolean flag)

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

See Also: backgroundColor, setDrawsCellBackground



setDrawsCellBackground

public void setDrawsCellBackground(boolean flag)

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

See Also: cellBackgroundColor, setDrawsBackground



setErrorAction

public void setErrorAction(NSSelector aSelector)

Sets the action sent to the target of the receiver when the user enters an illegal value for the selected cell.

See Also: action (NSControl), target (NSControl)



setIntercellSpacing

public void setIntercellSpacing(NSSize aSize)

Sets the vertical and horizontal spacing between cells in the receiver. By default, both values are 1.0 in the receiver's coordinate system.

See Also: cellSize



setKeyCell

public void setKeyCell(NSCell aCell)

Sets the cell that will be clicked when the user presses the Return key to aCell.

See Also: setNextText, setTabKeyTraversesCells



setMode

public void setMode(int aMode)

Sets the selection mode of the receiver. Possible values for aMode are listed in "Constants" .

setNextText

public void setNextText(Object anObject)

If the receiver doesn't already have a next key view, inserts anObject after the receiver in the key view loop of the receiver's NSWindow. anObject thus becomes the object that would be selected if the user presses Tab while editing the last text cell in the receiver. If the receiver already has a next key view, this method does nothing.

See Also: setNextKeyView (NSView), setTabKeyTraversesCells



setPreviousText

public void setPreviousText(Object anObject)

If anObject doesn't already have a next key view, inserts the receiver after anObject in the key view loop of anObject's NSWindow. If anObject already has a next key view, this method does nothing.

See Also: setNextKeyView (NSView)



setPrototype

public void setPrototype(NSCell aCell)

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

See Also: makeCellAtLocation



setScrollable

public void setScrollable(boolean flag)

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 non-scrolling. The prototype cell, if there is one, is also set accordingly.

See Also: prototype, setScrollable (NSCell)



setSelectionByRect

public void setSelectionByRect(boolean flag)

Sets whether the user can select a rectangle of cells in the receiver by dragging the cursor. If flag is false, selection is on a row-by-row basis. The default is true.

See Also: setSelectionWithAnchor



setSelectionWithAnchor

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

Programmatically selects a range of cells. 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.

startPos and endPos are used to mark where the user would have pressed the mouse button and released it, respectively. anchorPos locates the "last selected cell" with regard to extending the selection by Shift- or Alternate-clicking. Finally, lit determines whether cells selected by this method should be highlighted.

See Also: isSelectionByRect, selectedCells



setStateAtLocation

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

Sets the state of the cell at row and column to value. For radio-mode matrices, if value is non-zero the specified cell is selected before its state is set to value. If value is zero 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.

See Also: allowsEmptySelection, setState (NSCell), selectCellAtLocation



setTabKeyTraversesCells

public void setTabKeyTraversesCells(boolean flag)

Sets whether pressing the Tab key advances the key cell to the next selectable cell in the receiver. 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).

See Also: selectKeyViewFollowingView (NSWindow), selectNextKeyView (NSWindow), setKeyCell, setNextText



setValidateSize

public void setValidateSize(boolean flag)

If flag is true, then the size information in the receiver is assumed to be correct. If flag is false, NSControl's calcSize method will be invoked before any further drawing is done.

sizeToCells

public void sizeToCells()

Changes the width and the height of the receiver's frame so it exactly contains the cells. Does not redraw the receiver.

See Also: setFrameSize (NSView), sizeToFit (NSControl)



sortUsingMethod

public void sortUsingMethod(NSSelector comparator)

Sorts the receiver's cells in ascending order as defined by the comparison method comparator. 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.

See Also: - sortUsingSelector (NSMutableArray)



tabKeyTraversesCells

public boolean tabKeyTraversesCells()

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

See Also: keyCell, setTabKeyTraversesCells



textDidBeginEditing

public void textDidBeginEditing(NSNotification notification)

Invoked when there's a change in the text after the receiver gains first responder status. This method's default behavior is to post an 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.

See Also: textDidChange, textDidEndEditing, textShouldEndEditing



textDidChange

public void textDidChange(NSNotification)

Invoked upon a key-down event or paste operation that changes the receiver's contents. 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 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.

See Also: textDidBeginEditing, textDidEndEditing



textDidEndEditing

public void textDidEndEditing(NSNotification notification)

Invoked when text editing ends. This method's default behavior is to post an 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).

See Also: textDidBeginEditing, textDidChange, textShouldEndEditing



textShouldBeginEditing

public boolean textShouldBeginEditing(NSText textObject)

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). textShouldBeginEditing returns the value obtained from control:textShouldBeginEditing:, unless the delegate doesn't respond to that method, in which case it returns true, thereby allowing text editing to proceed.

See Also: delegate



textShouldEndEditing

public boolean textShouldEndEditing(NSText textObject)

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). If the contents of the text field aren't valid, textShouldEndEditing sends the error action to the selected cell's target.

textShouldEndEditing returns false if the text field contains invalid contents, otherwise it returns the value passed back from control:textShouldEndEditing:.

See Also: delegate, errorAction




Table of Contents