MiscTableCell.rtf

This is MiscTableCell.rtf in view mode; [Download] [Up]

Version 2.0, Copyright ©1995, 1996, 1997 by Paul S. McCarthy and Eric Sunshine. All Rights Reserved.
Paul S. McCarthy and Eric Sunshine -- July 4, 1997

MiscTableCell

Inherits From: NSCell : NSObject

Conforms To: NSCoding (NSObject),
NSCopying (NSObject),
NSObject (NSObject)

Declared In: MiscTableCell.h

Class Description

This is the cell class used by MiscTableScroll to display either text or an image. This class provides a tag and separate text and background colors for normal and selected states. Finally, it supports the concept of an owner, and inherited font and color values.

Owner and Inheritence of Colors and Font

This class implements the concept of an owner. An owner provides the default font and colors used by the cells that it owns. This makes it fast and easy to change the appearance of an entire table: set the font and colors of the owner, and all of the cells that it owns automatically inherit the new font and colors. However, you can also set font and color values for individual cells. Values that you explicitly set supercede values implicitly inherited from the owner. You can use this feature to emphasize special cells while still using inherited values for normal cells.

Another benefit of inherited values is reduced memory usage. Inherited values don't have to be stored in the individual cells. They just ask their owner for the current value whenever it is needed. This can lead to significant savings in large tables.

Owner drawing

This class also supports a specialized concept of delegated drawing. The MiscTableScroll class will draw cells that respond with YES to the -ownerDraw message. This enables the MiscTableScroll object to eliminate many redundant font and color setting operations, greatly improving drawing performance. See the description of owner drawing in MiscTableScroll for a more detailed discussion.

Extensible Memory Management

To minimize memory usage, storage for optional items is allocated on an as-needed basis. Memory is allocated only for the values that are actually set. If no optional items are set, then no extra memory at all is allocated.

The optional allocation scheme is extensible. Subclasses of MiscTableCell can extend this allocation scheme by appending their own dynamic variables to the end of the list used by this class. There is a strict ordering for the information stored in the variable length data. This ordering is enumerated by the tc1_flags. Subclasses should append their data after the last of the information stored by this class. Methods are provided to determine whether or not a piece of information is stored in the data field as well as for finding its address. Convenience methods for extracting a given piece of information complete the interface.

The methods which return the address of the piece of data in tc1_data are dynamic in nature. For instance, text color is stored prior to background color in tc1_data so if both text color and background color have been set then the address of the storage for the background color will follow the text color. However, if text color is never set � that is it is inherited from the owner � and the background color has been set then the address of the background color will be at a different location. If text color gets set later then the storage for background color is shifted up to make room for the text color. Ergo, the strict ordering is maintained.

For example, code to locate the address of the selected background color is stored in the cell would look like this:

- (unsigned int)tc1SelectBackgroundColorPos
{
unsigned int pos = [self tc1SelectedTextColorPos];
if (tc1_flags & MISC_TC1_SELF_TEXT_COLOR_H)
pos += [self tc1SelectedTextColorLen];
return pos;
}

Since the selected background color is stored following the selected text color it first determines the location of the selected text color then adds the length of the selected text color to that address if the selected text color is in fact being stored locally. The actual shifting of the dynamic memory is done in the -setUseOwner... methods. For instance:

- (void)setUseOwnerSelectedBackgroundColor:(BOOL)flag
{
if ([self useOwnerSelectedBackgroundColor] != flag)
{
unsigned int const pos = [self tc1SelectedBackgroundColorPos];
unsigned int const len = [self tc1SelectedBackgroundColorLen];
if (flag)
{
[[self selectedBackgroundColor] release];
[self tc1DeleteDataPos:pos len:len];
tc1_flags &= ~(MISC_TC1_SELF_BACKGROUND_COLOR_H);
}
else // (!flag)
{
NSColor* color = [[[self class] defaultSelectedBackgroundColor] retain];
[self tc1InsertData:&color pos:pos len:len];
tc1_flags |= MISC_TC1_SELF_BACKGROUND_COLOR_H;
}
}
}

Finally, the -setSelectedBackgroundColor: method makes room for the data and then stores it:

- (void)setSelectedBackgroundColor:(NSColor*)c
{
NSColor** p;
[self setUseOwnerSelectedBackgroundColor:NO];
p = [self tc1SelectedBackgroundColorPtr];
[*p autorelease];
*p = [c retain];
}

A subclass adding more data to the end of tc1_data would provide similar methods. Its counterpart to -tc1SelectedBackgroundColorPos would first call -tc1SelectedBackgroundColorPos to determine its address and then add the correct offset returned by -tc1SelectedBackgroundColorLen as appropriate.

Instance Variables

id owner;
int tag;
unsigned tc1_flags;
void* tc1_data;

owner The owner of this cell; queried for font and color information.

tag A general purpose slot for your use.

tc1_flags Bit flags describing the contents of tc1_data.

tc1_data Variable length data which is allocated only as needed for storage of color values.

Method Types

Initializing, freeing, and copying � initImageCell:
� initTextCell:
� dealloc
� copyWithZone:

Drawing � drawInteriorWithFrame:inView:
� drawWithFrame:inView:
� isOpaque
� bgColor
� fgColor
� setSelected:
� isSelected
� ownerDraw
� setOwnerDraw:

Tag manipulation � setTag:
� tag

Font manipulation � font
� setFont:

Setting and querying colors + defaultBackgroundColor
+ defaultFont
+ defaultSelectedBackgroundColor
+ defaultSelectedTextColor
+ defaultTextColor
� backgroundColor
� selectedBackgroundColor
� selectedTextColor
� setBackgroundColor:
� setSelectedBackgroundColor:
� setSelectedTextColor:
� setTextColor:
� textColor

Setting and querying owner � owner
� setOwner:

Colors and owner inheritence � setOwnerBackgroundColor:
� setOwnerFont:
� setOwnerSelectedBackgroundColor:
� setOwnerSelectedTextColor:
� setOwnerTextColor:
� setUseOwnerBackgroundColor:
� setUseOwnerFont:
� setUseOwnerSelectedBackgroundColor:
� setUseOwnerSelectedTextColor:
� setUseOwnerTextColor:
� useOwnerBackgroundColor
� useOwnerFont
� useOwnerSelectedBackgroundColor
� useOwnerSelectedTextColor
� useOwnerTextColor

Archiving � initWithCoder:
� encodeWithCoder:

Extensible conditional allocations � tc1BackgroundColorLen
� tc1BackgroundColorPos
� tc1BackgroundColorPtr
� tc1DataSize
� tc1DeleteDataPos:len:
� tc1DestroyData
� tc1Flags
� tc1SelectedBackgroundColorLen
� tc1SelectedBackgroundColorPos
� tc1SelectedBackgroundColorPtr
� tc1SelectedTextColorLen
� tc1SelectedTextColorPos
� tc1SelectedTextColorPtr
� tc1InsertData:pos:len:
� tc1TextColorLen
� tc1TextColorPos
� tc1TextColorPtr

Class Methods

defaultBackgroundColor
+ (NSColor*)defaultBackgroundColor

Returns [NSColor lightGrayColor] as the default background color. This is the color which is returned by -backgroundColor if a custom color has not been set for this cell and no owner has been set or the owner does not respond to the -backgroundColor message. This is also the color used upon receipt of a -setUseOwnerBackgroundColor:NO message. Subclasses should override this method if this color is inappropriate.

See also: � backgroundColor, + defaultSelectedBackgroundColor, + defaultSelectedTextColor, +�defaultTextColor, � setBackgroundColor:, � setUseOwnerBackgroundColor:

defaultFont
+ (NSFont*)defaultFont

Returns the user-font at point-size 12.0 as the default font. This is the font which is used when initializing the cell as a text cell with �initTextCell:. Subclasses should override this method if this value is inappropriate.

See also: � font, � initTextCell:, � setFont:

defaultSelectedBackgroundColor
+ (NSColor*)defaultSelectedBackgroundColor

Returns [NSColor whiteColor] as the default selected background color. This is the color which is returned by -selectedBackgroundColor if a custom color has not been set for this cell and no owner has been set or the owner does not respond to the -selectedBackgroundColor message. This is also the color used upon receipt of a -setUseOwnerSelectedBackgroundColor:NO message. Subclasses should override this method if this color is inappropriate.

See also: + defaultBackgroundColor, + defaultSelectedTextColor, + defaultTextColor, ��selectedBackgroundColor, � setSelectedBackgroundColor:, ��setUseOwnerSelectedBackgroundColor:

defaultSelectedTextColor
+ (NSColor*)defaultSelectedTextColor

Returns [NSColor blackColor] as the default selected text color. This is the color which is returned by -selectedTextColor if a custom color has not been set for this cell and no owner has been set or the owner does not respond to the -selectedTextColor message. This is also the color used upon receipt of a -setUseOwnerSelectedTextColor:NO message. Subclasses should override this method if this color is inappropriate.

See also: + defaultBackgroundColor, + defaultSelectedBackgroundColor, + defaultTextColor, �selectedTextColor, � setSelectedBackgroundColor:, � setUseOwnerSelectedBackgroundColor:

defaultTextColor
+ (NSColor*)defaultTextColor

Returns [NSColor blackColor] as the default text color. This is the color which is returned by -textColor if a custom color has not been set for this cell and no owner has been set or the owner does not respond to the -textColor message. This is also the color used upon receipt of a -setUseOwnerTextColor:NO message. Subclasses should override this method if this color is inappropriate.

See also: + defaultBackgroundColor, +�defaultSelectedBackgroundColor, + defaultSelectedTextColor, ��setSelectedBackgroundColor:, ��setUseOwnerSelectedBackgroundColor:, � textColor

Instance Methods

backgroundColor
- (NSColor*)backgroundColor

Returns the color that is used to draw the background of the cell in its normal (unselected) state. This is the color which has been set with �setBackgroundColor: if it was ever called. If not, and the owner has been set and responds to �backgroundColor then it is queried and that color is returned. If both of the above fail then the value from +defaultBackgroundColor is returned.

See also: + defaultBackgroundColor, � selectedBackgroundColor, � selectedTextColor, � setBackgroundColor:, ��textColor

bgColor
- (NSColor*)bgColor

This method is used by cells that draw themselves rather than letting the owner draw them. It returns the color that is used to fill the background of the cell during drawing. If the cell -isSelected, then this method returns the value from -selectedBackgroundColor, otherwise it returns the value from -backgroundColor. Subclasses should override this method if they have different criteria for determining the cell's background color during drawing.

See also: � backgroundColor, � fgColor, � selectedBackgroundColor, � isSelected

copyWithZone:
- (id)copyWithZone:(NSZone*)zone

Allocates, initializes, and returns a copy of the receiving cell. The copy is allocated from zone and is assigned the same contents as the receiver.

See also: � copyWithZone: (NSCopying), � initImageCell:, � initTextCell:

dealloc
- (void)dealloc

Frees the memory used by the cell.

See also: � copyWithZone:, � initImageCell:, � initTextCell:

drawInteriorWithFrame:inView:
- (void)drawInteriorWithFrame:(NSRect)cellFrame inView:(NSView*)controlView

Draws the inside of the cell, but not the border, in cellFrame within controlView. cellFrame should be the same rectangle passed to -drawWithFrame:inView:. The PostScript focus must be locked on controlView when this message is sent.

See also: - drawInteriorWithFrame:inView: (NSCell), - drawWithFrame:inView:, - lockFocus (NSView)

drawWithFrame:inView:
- (void)drawWithFrame:(NSRect)cellFrame inView:(NSView*)controlView

Displays the cell in cellFrame within controlView. The PostScript focus must be locked on controlView when this message is sent. Draws the border of the cell, then invokes �drawInteriorWithFrame:inView:.

See also: - drawInteriorWithFrame:inView:, � drawWithFrame:inView: (NSCell), - lockFocus (NSView)

encodeWithCoder:
- (void)encodeWithCoder:(NSCoder�*)encoder

Encodes the receiver using encoder.

fgColor
- (NSColor*)fgColor

This method is used by cells that draw themselves rather than letting the owner draw them. It returns the color that is used for the text in the cell during drawing. If the cell -isSelected, then this method returns the value from -selectedTextColor, otherwise it returns the value from -textColor. Subclasses should override this method if they have different criteria for determining the cell's text color during drawing.

See also: � bgColor, � selectedTextColor, � isSelected, � textColor

font
- (NSFont*)font

Returns the Font used to display text in the cell. Returns nil if the receiver isn't a text-type cell.