- Inherits from:
- NSControl : NSView : NSResponder : NSObject
- Package:
- com.apple.yellow.application
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:
TrackMode
is the
most basic mode of operation. In this mode the NSCells are asked
to track the mouse with trackMouse whenever the mouse is
inside their bounds. No highlighting is performed. An example of
this mode might be a "graphic equalizer" NSMatrix of sliders,
where moving the mouse around causes the sliders to move under the
mouse.HighlightMode
is a modification
of TrackMode
. In this mode, an NSCell
is highlighted before it's asked to track the mouse, then unhighlighted
when it's done tracking. This is useful for multiple unconnected
NSCells that use highlighting to inform the user that they are being
tracked (like push-buttons and switches).RadioMode
is used when you
want no more than one NSCell to be selected at a time. It can be
used to create a set of buttons of which one and only one is selected
(there's the option of allowing no button to be selected). Any
time an NSCell is selected, the previously selected NSCell is unselected. The
canonical example of this mode is a set of radio buttons.ListMode
is the opposite of TrackMode
.
NSCells are highlighted, but don't track the mouse. This mode
can be used to select a range of text values, for example. NSMatrix
supports the standard multiple-selection paradigms of dragging to
select, using the shift key to make discontinuous selections, and
using the alternate key to extend selections. Browsers use this
mode.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. |
- 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
public NSMatrix()
public NSMatrix(NSRect frameRect)
RadioMode
.
The default cell class is NSActionCell.
public NSMatrix(
NSRect frameRect,
int aMode,
NSCell aCell,
int numRows,
int numColumns)
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)
The new NSMatrix creates and uses cells of class aClass.
public boolean acceptsFirstMouse(NSEvent theEvent)
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
public void addColumn()
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
public void addColumnWithCells(NSArray 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
public void addRow()
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
public void addRowWithCells(NSArray 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
public boolean allowsEmptySelection()
See Also: mode
public boolean autosizesCells()
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).public NSColor backgroundColor()
See Also: cellBackgroundColor, drawsBackground
public NSCell cellAtLocation(
int row,
int column)
See Also: getRow:column:ofCell:
public NSColor cellBackgroundColor()
See Also: backgroundColor, drawsCellBackground
public Class newCellClass()
See Also: prototype, makeCellAtLocation
public NSRect cellFrameAtLocation(
int row,
int column)
See Also: cellSize
public NSSize cellSize()
See Also: cellFrameAtLocation, intercellSpacing
public NSCell cellWithTag(int anInt)
See Also: selectCellWithTag, setTag (NSActionCell)
public NSArray cells()
See Also: cellAtLocation
public int columnForPoint(NSPoint aPoint)
Make sure aPoint is in the coordinate system of the receiver.
See Also: getRow:column:ofCell:
public int columnOfCell(NSCell aCell)
See Also: getRow:column:forPoint:
public Object delegate()
See Also: textShouldBeginEditing, textShouldEndEditing
public void deselectAllCells()
RadioMode
and
empty selection is not allowed, this method does nothing.See Also: allowsEmptySelection, mode, selectAll
public void deselectSelectedCell()
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
public NSSelector doubleAction()
- (SEL)doubleAction
See Also: action (NSControl), target (NSControl), ignoresMultiClick (NSControl), sendDoubleAction
public void drawCellAtLocation(
int row,
int column)
See Also: drawCell (NSControl), drawCellInside (NSControl)
public boolean drawsBackground()
See Also: backgroundColor, drawsCellBackground
public boolean drawsCellBackground()
See Also: cellBackgroundColor, drawsBackground
public NSSelector errorAction()
See Also: action (NSControl), target (NSControl), textShouldEndEditing
public void highlightCellAtLocation(
boolean flag,
int row,
int column)
false
)
the specified cell.public void insertColumn(int column)
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
public void insertColumnWithCells(
int column,
NSArray 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
public void insertRow(int row)
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
public void insertRowWithCells(
int row,
NSArray 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
public NSSize intercellSpacing()
See Also: cellSize
public boolean isAutoscroll()
See Also: scrollCellAtLocationToVisible, setScrollable
public boolean isSelectionByRect()
true
if
a the user can select a rectangle of cells in the receiver by dragging
the cursor, false
otherwise.See Also: setSelectionWithAnchor
public NSCell keyCell()
See Also: nextText , tabKeyTraversesCells
public NSCell makeCellAtLocation(
int row,
int column)
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
public int mode()
public void mouseDown(NSEvent theEvent)
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
public int mouseDownFlags()
See Also: setEventMaskForSendingAction (NSCell)
public Object nextText()
See Also: nextKeyView (NSView), previousText, setNextText
public int numberOfColumns()
See Also: getNumberOfRows:columns:
public int numberOfRows()
See Also: getNumberOfRows:columns:
public boolean performKeyEquivalent(NSEvent theEvent)
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.
public Object previousText()
See Also: nextKeyView (NSView), nextText, setPreviousText
public NSCell prototype()
See Also: makeCellAtLocation
public void putCellAtLocation(
NSCell newCell,
int row,
int column)
public void removeColumn(int column)
See Also: removeRow, addColumn, insertColumn
public void removeRow(int row)
See Also: removeColumn, addRow, insertRow
public void renewRowsAndColumns(
int newRows,
int newCols)
See Also: addColumn, addRow, removeColumn, removeRow
public void resetCursorRects()
See Also: resetCursorRect (NSCell), addCursorRect (NSView)
public int rowForPoint(NSPoint aPoint)
Make sure aPoint is in the coordinate system of the receiver.
See Also: getRow:column:ofCell:
public int rowOfCell(NSCell aCell)
See Also: getRow:column:forPoint:
public void scrollCellAtLocationToVisible(
int row,
int column)
See Also: scrollRectToVisible (NSView)
public void selectAll(Object sender)
See Also: selectCell (NSControl)
public void selectCellAtLocation(
int row,
int column)
RadioMode
and doesn't allow
empty selection). Redraws the affected cells.See Also: allowsEmptySelection, mode, selectCell (NSControl)
public boolean selectCellWithTag(int anInt)
true
if
the receiver contains a cell whose tag matches anInt,
or false
if no such cell exists.See Also: cellWithTag, selectCell (NSControl)
public void selectText(Object sender)
See Also: keyCell, selectText (NSTextField)
public Object selectTextAtLocation(
int row,
int column)
See Also: selectText
public NSCell selectedCell()
public NSArray selectedCells()
See Also: selectedCell
public int selectedColumn()
public int selectedRow()
public boolean sendAction()
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)
public void sendActionToTargetForAllCells(
NSSelector aSelector,
Object anObject,
boolean flag)
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.
public void sendDoubleAction()
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)
public void setAllowsEmptySelection(boolean flag)
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.public void setAutoscroll(boolean flag)
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.public void setAutosizesCells(boolean flag)
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.public void setBackgroundColor(NSColor aColor)
See Also: drawsBackground, setCellBackgroundColor
public void setCellBackgroundColor(NSColor aColor)
See Also: drawsCellBackground, setBackgroundColor
public void setNewCellClass(Class aClass)
See Also: addColumn, addRow, insertColumn, insertRow, makeCellAtLocation, setPrototype
public void setCellSize(NSSize aSize)
See Also: calcSize (NSControl)
public void setDelegate(Object anObject)
See Also: textShouldBeginEditing, textShouldEndEditing
public void setDoubleAction(NSSelector aSelector)
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)
public void setDrawsBackground(boolean flag)
See Also: backgroundColor, setDrawsCellBackground
public void setDrawsCellBackground(boolean flag)
See Also: cellBackgroundColor, setDrawsBackground
public void setErrorAction(NSSelector aSelector)
See Also: action (NSControl), target (NSControl)
public void setIntercellSpacing(NSSize aSize)
See Also: cellSize
public void setKeyCell(NSCell aCell)
See Also: setNextText, setTabKeyTraversesCells
public void setMode(int aMode)
public void setNextText(Object anObject)
See Also: setNextKeyView (NSView), setTabKeyTraversesCells
public void setPreviousText(Object anObject)
See Also: setNextKeyView (NSView)
public void setPrototype(NSCell aCell)
See Also: makeCellAtLocation
public void setScrollable(boolean flag)
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)
public void setSelectionByRect(boolean flag)
true
.See Also: setSelectionWithAnchor
public void setSelectionWithAnchor(
int startPos,
int endPos,
int anchorPos,
boolean lit)
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
public void setStateAtLocation(
int value,
int row,
int column)
This method redraws the affected cell.
See Also: allowsEmptySelection, setState (NSCell), selectCellAtLocation
public void setTabKeyTraversesCells(boolean flag)
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
public void setValidateSize(boolean flag)
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.public void sizeToCells()
See Also: setFrameSize (NSView), sizeToFit (NSControl)
public void sortUsingMethod(NSSelector comparator)
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)
public boolean tabKeyTraversesCells()
See Also: keyCell, setTabKeyTraversesCells
public void textDidBeginEditing(NSNotification notification)
FieldEditor
"; the value
for this key is the text object that began editing.See Also: textDidChange, textDidEndEditing, textShouldEndEditing
public void textDidChange(NSNotification)
FieldEditor
"; the value
for this key is the text object that changed.See Also: textDidBeginEditing, textDidEndEditing
public void textDidEndEditing(NSNotification notification)
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
public boolean textShouldBeginEditing(NSText textObject)
true
, thereby allowing
text editing to proceed.See Also: delegate
public boolean textShouldEndEditing(NSText textObject)
textShouldEndEditing returns false
if
the text field contains invalid contents, otherwise it returns the
value passed back from control:textShouldEndEditing:.
See Also: delegate, errorAction