Return to the Alphabetic Index
Return to the Class Browser
Return to the Picture Browser
Copyright (c) 1994 by NeXT Computer, Inc. All Rights Reserved.


Inherits From: NSControl : NSView : NSResponder : NSObject

Conforms To: NSCoding (NSResponder) NSObject (NSObject)

Declared In: AppKit/NSMatrix.h

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.

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, and 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:

. NSTrackModeMatrix is the most basic mode of operation. In this mode the NSCells are asked to track the mouse with trackMouse:inRect:ofView:untilMouseUp: 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.

. NSHighlightModeMatrix is a modification of NSTrackModeMatrix. 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).

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

. NSListModeMatrix is the opposite of NSTrackModeMatrix. 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.

Initializing the NSMatrix Class

Initializing an NSMatrix Object

Configuring the NSMatrix

Setting the Cell Class

Laying Out the NSMatrix

Finding Matrix Coordinates

Finding Cells

Modifying Graphic Attributes

Editing Text in Cells

Setting Tab Key Behavior

Assigning a Delegate

Resizing the Matrix and Cells



Handling Event and Action Messages

Managing the Cursor