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:
These constants determine how NSCells behave when the NSMatrix
is tracking the mouse. For more information, see the Class Description.
ConstantDescription
TrackModeMatrix |
The NSCells are asked to track the mouse with
trackMouse:inRect:ofView:untilMouseUp: whenever
the mouse is inside their bounds. No highlighting is performed.l |
HighlightModeMatrix |
An NSCell is highlighted before it's asked to track the
mouse, then unhighlighted when it's done tracking. . |
RadioModeMatrix |
Selects no more than one NSCell at a time. Any time
an NSCell is selected, the previously selected NSCell is unselected. |
ListModeMatrix |
NSCells are highlighted, but don't track the mouse. |
Method Types
- Initializing an NSMatrix
object
- initWithFrame:
- initWithFrame:mode:cellClass:numberOfRows:numberOfColumns:
- initWithFrame:mode:prototype:numberOfRows:numberOfColumns:
- 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
- getNumberOfRows:columns:
- insertColumn
- insertColumnWithCells
- insertRow
- insertRowWithCells
- intercellSpacing
- makeCellAtLocation
- numberOfColumns
- numberOfRows
- putCellAtLocation
- removeColumn
- removeRow
- renewRowsAndColumns
- setCellSize
- setIntercellSpacing
- sortUsingFunction:context:
- sortUsingMethod
- Finding matrix coordinates
- getRow:column:forPoint:
- getRow:column:ofCell:
- Modifying individual
cells
- setStateAtLocation
- Selecting cells
- deselectAllCells
- deselectSelectedCell
- keyCell
- selectAll
- selectCellAtLocation
- selectCellWithTag
- selectedCell
- selectedCells
- selectedColumn
- selectedRow
- setKeyCell
- setSelectionWithAnchor
- Finding cells
- cellAtLocation
- cellWithTag
- cells
- 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(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 RadioModeMatrix
. <<This
should be an xref.>> The default cell class is NSActionCell. <<This
should be an xref.>>
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
following four constants, all of which are described in the class
description:
Tracking mode |
Description |
TrackModeMatrix |
Cells track the mouse, but do not highlight |
HighlightModeMatrix |
Cells highlight as they track the mouse |
RadioModeMatrix |
Allows no more than one selected cell |
ListModeMatrix |
Cells are highlighted, but don't track the mouse |
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
following four constants, all of which are described in the class
description: <<Should be xref's>>
Tracking mode |
Description |
TrackModeMatrix |
Cells track the mouse, but do not highlight |
HighlightModeMatrix |
Cells highlight as they track the mouse |
RadioModeMatrix |
Allows no more than one selected cell |
ListModeMatrix |
Cells are highlighted, but don't track the mouse |
The new NSMatrix creates and uses cells of class aclass.
Instance Methods
public boolean acceptsFirstMouse (NSEvent theEvent)
Returns false
if
the selection mode of the NSMatrix is ListModeMatrix
, true if
the NSMatrix is in any other selection mode. The
NSMatrix does not accept first mouse in ListModeMatrix
to
prevent the loss of multiple selections. The NSEvent parameter, theEvent,
is ignored.See Also: mode
public void addColumn()
Adds a new column of cells
to the right of the last column, creating new cells as needed with makeCellAtRow:column:.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)
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
public void addRow()
Adds a new row of cells below
the last row, creating new cells as needed with makeCellAtRow:column:.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)
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
public boolean allowsEmptySelection()
Returns whether it's possible
to have no cells selected in a radio-mode matrix.See
Also: mode
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).
public NSColor backgroundColor()
Returns the color used to draw
the background of the NSMatrix (the space between the cells).See
Also: cellBackgroundColor, drawsBackground
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:
public NSColor cellBackgroundColor()
Returns the color used to fill
the background of the NSMatrix's cells.See
Also: backgroundColor, drawsCellBackground
public Class newCellClass()
Returns the subclass of NSCell
that the NSMatrix uses when creating new (empty) cells.See
Also: prototype, makeCellAtLocation
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
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
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)
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
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 Matrix or lies within an intercell spacing, this
method returns <<WHAT?>>. Make sure aPoint is
in the coordinate system of the NSMatrix.
See
Also: getRow:column:ofCell:
public int columnOfCell(NSCell aCell)
Searches the NSMatrix for aCell and
returns the column of the cell. If aCell is
not found within the Matrix, this method returns <<WHAT?>>. See
Also: getRow:column:forPoint:
public Object delegate()
Returns the delegate for messages
from the field editor.See
Also: textShouldBeginEditing, textShouldEndEditing
public void deselectAllCells()
Deselects all cells in the
NSMatrix and, if necessary, redisplays the NSMatrix. If
the selection mode is RadioModeMatrix
and
empty selection is not allowed, this method does nothing.See
Also: allowsEmptySelection, mode, selectAll
public void deselectSelectedCell()
Deselects the selected cell
or cells. If the selection mode is RadioModeMatrix
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
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
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)
public boolean drawsBackground()
Returns whether the receiver
draws its background (the space between the cells).See
Also: backgroundColor, drawsCellBackground
public boolean drawsCellBackground()
Returns whether the receiver
draws the background within each of its cells.See
Also: cellBackgroundColor, drawsBackground
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
public void highlightCellAtLocation(boolean flag, int row, int column)
Assuming that row and column indicate
a valid cell within the NSMatrix, this method highlights (if flag is true)
or unhighlights (if flag is false
) the
specified cell.
public void insertColumn (int column)
- (void)insertColumn:(int)column
Inserts a new column of cells
before column, creating new cells
if needed with makeCellAtRow:column:. If column is
greater than the number of columns in the NSMatrix, enough columns
are created to expand the NSMatrix to be column columns
wide. 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.If the number of rows or columns in the NSMatrix 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)
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 NSMatrix, enough columns are created to expand
the NSMatrix 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 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: addColumnWithCells, insertRowWithCells
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 NSMatrix, enough rows are
created to expand the NSMatrix to be row rows high.
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.If the number of rows or columns in the NSMatrix 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)
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 NSMatrix, enough rows are created to expand the NSMatrix
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 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: addRowWithCells, insertColumnWithCells
public NSSize intercellSpacing()
Returns the vertical and horizontal
spacing between cells in the NSMatrix.See
Also: cellSize
public boolean isAutoscroll()
Returns whether the NSMatrix
will be automatically scrolled whenever the mouse is dragged outside
the NSMatrix after a mouse-down event within its bounds.See
Also: scrollCellAtLocationToVisible, setScrollable
public boolean isSelectionByRect()
Returns true
if
a the user can select a rectangle of cells in the NSMatrix by dragging
the cursor, false
otherwise.See
Also: setSelectionWithAnchor
public NSCell keyCell()
Returns the cell that will
be clicked when the user presses the Return key.See
Also: nextText, tabKeyTraversesCells
public NSCell makeCellAtLocation(int row, int column)
Creates a new cell at the specified
location in the NSMatrix. If the NSMatrix has
a prototype cell, it's copied to create the new cell. If not,
and if the NSMatrix has a cell class set, it allocates and initializes
(with init) an instance of that class.
If the NSMatrix 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
public int mode()
Returns the selection mode of the NSMatrix.
Possible return values are defined in NSMatrix.h, and are also listed
here:
Tracking mode |
Description |
NSTrackModeMatrix |
Cells track the mouse, but do not highlight |
NSHighlightModeMatrix |
Cells highlight as they track the mouse |
NSRadioModeMatrix |
Allows no more than one selected cell |
NSListModeMatrix |
Cells are highlighted, but don't track the mouse |
These modes are explained in detail in the class description.
See
Also: initWithFrame:mode:cellClass:numberOfRows:numberOfColumns:initWithFrame:mode:prototype:numberOfRows:numberOfColumns:
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 NSMatrix (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 NSMatrix depends on its selection mode,
as explained in the class description.
See
Also: sendAction, sendDoubleAction
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 NSMatrix
initiates another tracking loop as part of its action method (as
a cell that pops up a PopUpList does, for example).See
Also: - sendActionOn:(NSCell)
public Object nextText()
Returns the object that would
be selected if the user presses Tab while editing the last text
cell in the NSMatrix.See
Also: - nextKeyView (NSView), previousText, setNextText
public int numberOfColumns()
Returns the number of columns
in the NSMatrix.See Also: getNumberOfRows:columns:
public int numberOfRows()
Returns the number of rows
in the NSMatrix.See Also: getNumberOfRows:columns:
public boolean performKeyEquivalent(NSEvent theEvent)
If there's a cell in the NSMatrix 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 NSMatrix responds to the key equivalent in theEvent, false
if
no cell responds.Your code should never send this message-it
is sent when the NSMatrix 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()
Returns the object that would
be selected if the user presses Shift-Tab while editing the first
text cell in the NSMatrix.See
Also: - nextKeyView (NSView), nextText, setPreviousText
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: initWithFrame:mode:prototype:numberOfRows:numberOfColumns:makeCellAtLocation
public void putCellAtLocation(NSCell newCell, int row, int column)
Replaces the cell at the specified
row and column with newCell, and
redraws the cell.
public void removeColumn(int column)
Removes the column at position column from
the NSMatrix and autoreleases the column's cells. Doesn't
redraw the NSMatrix. Your code should normally send sizeToCells after
invoking this method to resize the NSMatrix so it fits the reduced
cell count.See Also: removeRow, addColumn, insertColumn
public void removeRow(int row)
Removes the row at position row from
the NSMatrix and autoreleases the row's cells. Doesn't
redraw the NSMatrix. Your code should normally send sizeToCells after
invoking this method to resize the NSMatrix so it fits the reduced
cell count.See Also: removeColumn, addRow, insertRow
public void renewRowsAndColumns(int newRows, int newCols)
Changes the number of rows
and columns in the NSMatrix. 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 NSMatrix.
Your code should normally send sizeToCells after invoking this method
to resize the NSMatrix so it fits the changed cell arrangement.
This method deselects all cells in the NSMatrix.See
Also: addColumn, addRow, removeColumn, removeRow
public void resetCursorRects()
Resets cursor rectangles so
the cursor becomes an I-beam over text cells. It
does this by sending resetCursorRect:inView: to each cell in the
NSMatrix. Any cell that has a cursor rectangle to set up should
then send addCursorRect:cursor: back to the NSMatrix.See
Also: - resetCursorRect:inView: (NSCell) - addCursorRect:cursor: (NSView)
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 Matrix or lies within an intercell spacing,
this method returns <<WHAT?>>. Make sure aPoint is
in the coordinate system of the NSMatrix.
See
Also: getRow:column:ofCell:
public int rowOfCell(NSCell aCell)
Searches the NSMatrix for aCell and
returns the row of the cell. If aCell is not
found within the Matrix, this method returns <<WHAT?>>. See
Also: getRow:column:forPoint:
public void scrollCellAtLocationToVisible (int row, int column)
If the NSMatrix is in a scrolling
view, and row and column represent
a valid cell within the NSMatrix, this method scrolls the NSMatrix
so the specified cell is visible.See
Also: - scrollRectToVisible: (NSView)
public void selectAll (Object sender)
Selects and highlights all
cells in the NSMatrix, except for editable text cells and disabled
cells. Redisplays the NSMatrix. sender is
ignored.See Also: - selectCell: (NSControl)
public void selectCellAtLocation(int row, int column)
Selects the cell at the specified
row and column within the NSMatrix. 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 NSMatrix
is an NSRadioModeMatrix and doesn't allow empty selection). Redraws
the affected cells.See Also: allowsEmptySelection, mode, - selectCell: (NSControl)
public boolean selectCellWithTag(int anInt)
If the NSMatrix 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 NSMatrix contains a cell whose tag matches anInt,
or false
if no such cell exists.See
Also: cellWithTag, - selectCell: (NSControl)
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)
public Object selectTextAtLocation(int row, int column)
If row and column indicate
a valid cell within the NSMatrix, 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 NSMatrix, this method does nothing and
returns the receiver.See Also: selectText
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 NSMatrix.
public NSArray selectedCells()
Returns an array containing
all of the matrice's highlighted cells.See
Also: selectedCell
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.
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.
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 NSMatrix. If the cell doesn't have an action, or
if there is no selected cell, the NSMatrix 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)
public void sendActionToTargetForAllCells(NSSelector aSelector, Object anObject, boolean flag)
Iterates through all cells
in the NSMatrix (if flag is true
),
or just the selected cells in the NSMatrix (if flag is false
),
sending aSelector to anObject for
each. Iteration begins with the cell in the upper-left
corner of the NSMatrix, 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 NSMatrix. 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 NSMatrix has a double-click action, sendDoubleAction sends
that message to the target of the NSMatrix. 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 NSMatrix is sent to the target of the NSMatrix. 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)
If flag is true
,
then the NSMatrix will allow one or zero cells to be selected. If flag is false
,
then the NSMatrix will allow one and only one cell (not zero cells)
to be selected. This setting has effect only in the RadioModeMatrix
selection
mode.
public void setAutoscroll(boolean flag)
If flag is true
and
the NSMatrix is in a scrolling view, it will be automatically scrolled
whenever the mouse is dragged outside the NSMatrix after a mouse-down
event within the bounds of the NSMatrix.
public void setAutosizesCells(boolean flag)
Sets whether the cell sizes
or the inter-cell spacing change when the NSMatrix is resized. If flag is true
,
then whenever the NSMatrix 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 NSMatrix, adjusting the size of the cells
and updating the NSMatrix if they don't. If flag is false
,
then the inter-cell space changes when the NSMatrix is resized,
with the cell size remaining constant.
public void setBackgroundColor(NSColor aColor)
Sets the background color for
the NSMatrix to aColor, and redraws
the NSMatrix. 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
public void setCellBackgroundColor(NSColor aColor)
Sets the background color for
the cells in the NSMatrix 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
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. You
only need to use this method with matrices initialized with initWithFrame:,
because the other initializers allow you to specify an instance-specific
cell class or cell prototype.
See Also: addColumn, addRow, insertColumn, insertRow, makeCellAtLocation, setPrototype
public void setCellSize(NSSize aSize)
Sets the width and height of
each of the cells in the NSMatrix to those in aSize. This
may change the size of the NSMatrix. Does not redraw the NSMatrix.See
Also: - calcSize (NSControl)
public void setDelegate(Object anObject)
Sets the delegate for messages
from the field editor.See
Also: textShouldBeginEditing, textShouldEndEditing
public void setDoubleAction(NSSelector aSelector)
Makes aSelector the
action sent to the target of the NSMatrix 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 NSMatrix's 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)
public void setDrawsBackground(boolean flag)
Sets whether the receiver draws
its background (the space between the cells).See
Also: backgroundColor, setDrawsCellBackground
public void setDrawsCellBackground(boolean flag)
Sets whether the receiver draws
the background within each of its cells.See
Also: cellBackgroundColor, setDrawsBackground
public void setErrorAction(NSSelector aSelector)
Sets 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)
public void setIntercellSpacing(NSSize aSize)
Sets the vertical and horizontal
spacing between cells in the NSMatrix. By default,
both values are 1.0 in the NSMatrix's coordinate system.See
Also: cellSize
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
public void setMode(int aMode)
Sets the selection mode of
the NSMatrix. Possible values for aMode are defined
in NSMatrix.h, and include:
Tracking mode |
Description |
NSTrackModeMatrix |
Cells track the mouse, but do not highlight |
NSHighlightModeMatrix |
Cells highlight as they track the mouse |
NSRadioModeMatrix |
Allows no more than one selected cell |
NSListModeMatrix |
Cells are highlighted, but don't track the mouse |
These modes are explained in detail in the class description.
See
Also: initWithFrame:mode:cellClass:numberOfRows:numberOfColumns:initWithFrame:mode:prototype:numberOfRows:numberOfColumns:
public void setNextText(Object anObject)
If the NSMatrix 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 NSMatrix. If the NSMatrix already
has a next key view, this method does nothing.See
Also: - setNextKeyView: (NSView), setTabKeyTraversesCells
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)
public void setPrototype(NSCell aCell)
Sets the prototype cell that's
copied whenever a new cell needs to be created.See
Also: initWithFrame:mode:prototype:numberOfRows:numberOfColumns:makeCellAtLocation
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)
public void setSelectionByRect(boolean flag)
Sets whether the user can select
a rectangle of cells in the NSMatrix by dragging the cursor. If flag is false,
selection is on a row-by-row basis. The default is true
.See
Also: 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 NSMatrix, 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
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
public void setTabKeyTraversesCells(boolean flag)
Sets whether pressing the Tab
key advances the key cell to the next selectable cell in the NSMatrix. 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
public void setValidateSize(boolean flag)
If flag is true
,
then the size information in the NSMatrix 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()
Changes the width and the height
of the NSMatrix frame so it exactly contains the cells. Does
not redraw the NSMatrix.See Also: - setFrameSize: (NSView) - sizeToFit (NSControl)
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)
public boolean tabKeyTraversesCells()
Returns whether pressing the
Tab key advances the key cell to the next selectable cell in the
NSMatrix.See Also: keyCell, setTabKeyTraversesCells
public void textDidBeginEditing(NSNotification otification)
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 NSControlTextDidBeginEditingNotification
along with the receiving object to the default notification center.
The posted notification's user info contains the contents of notification's
user info dictionary, plus an additional key/value pair. The additional
key is "NSFieldEditor"; the value for this key is the text object that
began editing.See Also: textDidChange, textDidEndEditing, textShouldEndEditing
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 NSControlTextDidChangeNotification along with
the receiving object to the default notification center. The posted
notification's user info contains the contents of notification's
user info dictionary, plus an additional key/value pair. The additional
key is "NSFieldEditor"; the value for this key is the text object that
changed.See Also: textDidBeginEditing, textDidEndEditing
public void textDidEndEditing(NSNotification notification)
Invoked when text editing ends. This
method's default behavior is to post an NSControlTextDidEndEditingNotification
along with the receiving object to the default notification center.
The posted notification's user info contains the contents of notification's
user info dictionary, plus an additional key/value pair. The additional
key is "NSFieldEditor"; the value for this key is the text object that
began editing. After posting the notification, textDidEndEditing sends an endEditing: message
to the selected cell, draws and makes the selected cell key, and
then takes the appropriate action based on which key was used to
end editing (Return, Tab, or Back-Tab).See
Also: textDidBeginEditing, textDidChange, textShouldEndEditing
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
public boolean textShouldEndEditing(NSText)
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
[Previous] [Next]