MiscTableCell.rtf

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

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

MiscTableCell

Inherits From: Cell : Object

Declared In: MiscTableCell.h

Class Description

This is the cell class used by MiscTableScroll to display either text or an icon. This class provides a tag and separate text and background colors for normal and highlighted states. In addition to the -setIcon: and -icon methods which are inherited from Cell, this class provides support for unnamed images with the -setImage: and -image methods. Finally, this class also 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 highlighted background color is stored in the cell would look like this:

- (unsigned int) tc1HighlightBackgroundColorPos
{
unsigned int pos = [self tc1HighlightTextColorPos];
if (tc1_flags & MISC_TC1_SELF_TEXT_COLOR_H)
pos += [self tc1HighlightTextColorLen];
return pos;
}

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

- setUseOwnerHighlightBackgroundColor: (BOOL) flag
{
if ([self useOwnerHighlightBackgroundColor] != flag)
{
unsigned int const pos = [self tc1HighlightBackgroundColorPos];
unsigned int const len = [self tc1HighlightBackgroundColorLen];
if (flag)
{
[self tc1DeleteDataPos:pos len:len];
tc1_flags &= ~(MISC_TC1_SELF_BACKGROUND_COLOR_H);
}
else // (!flag)
{
NXColor color = [[self class] defaultHighlightBackgroundColor];
[self tc1InsertData:&color pos:pos len:len];
tc1_flags |= MISC_TC1_SELF_BACKGROUND_COLOR_H;
}
}
return self;
}

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

- setHighlightBackgroundColor: (NXColor) c
{
NXColor* p;
[self setUseOwnerHighlightBackgroundColor:NO];
p = [self tc1HighlightBackgroundColorPtr];
*p = c;
return self;
}

A subclass adding more data to the end of tc1_data would provide similar methods. Its counterpart to -tc1HighlightBackgroundColorPos would first call -tc1HighlightBackgroundColorPos to determine its address and then add the correct offset returned by -tc1HighlightBackgroundColorLen 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 � initIconCell:
� initTextCell:
� free
� copyFromZone:

Drawing � drawInside:inView:
� drawSelf:inView:
� isOpaque
� bgColor
� fgColor
� ownerDraw
� setOwnerDraw:

Tag manipulation � setTag:
� tag

Font manipulation � font
� setFont:

Icon � image
� setImage:

Setting and querying colors + defaultBackgroundColor
+ defaultFont
+ defaultHighlightBackgroundColor
+ defaultHighlightTextColor
+ defaultTextColor
� backgroundColor
� backgroundGray
� highlightBackgroundColor
� highlightBackgroundGray
� highlightTextColor
� highlightTextGray
� setBackgroundColor:
� setBackgroundGray:
� setHighlightBackgroundColor:
� setHighlightBackgroundGray:
� setHighlightTextColor:
� setHighlightTextGray:
� setTextColor:
� setTextGray:
� textColor
� textGray

Selected � isSelected
� setSelected:

Setting and querying owner � owner
� setOwner:

Colors and owner inheritence � setOwnerBackgroundColor:
� setOwnerFont:
� setOwnerHighlightBackgroundColor:
� setOwnerHighlightTextColor:
� setOwnerTextColor:
� setUseOwnerBackgroundColor:
� setUseOwnerFont:
� setUseOwnerHighlightBackgroundColor:
� setUseOwnerHighlightTextColor:
� setUseOwnerTextColor:
� useOwnerBackgroundColor
� useOwnerFont
� useOwnerHighlightBackgroundColor
� useOwnerHighlightTextColor
� useOwnerTextColor

Archiving � read:
� write:

Extensible conditional allocations � tc1BackgroundColorLen
� tc1BackgroundColorPos
� tc1BackgroundColorPtr
� tc1DataSize
� tc1DeleteDataPos:len:
� tc1DestroyData
� tc1Flags
� tc1HighlightBackgroundColorLen
� tc1HighlightBackgroundColorPos
� tc1HighlightBackgroundColorPtr
� tc1HighlightTextColorLen
� tc1HighlightTextColorPos
� tc1HighlightTextColorPtr
� tc1InsertData:pos:len:
� tc1TextColorLen
� tc1TextColorPos
� tc1TextColorPtr

Class Methods

defaultBackgroundColor
+ (NXColor)defaultBackgroundColor

Returns NX_COLORLTGRAY 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, + defaultHighlightBackgroundColor, �+�defaultHighlightTextColor, + defaultTextColor, � setBackgroundColor:, ���setUseOwnerBackgroundColor:

defaultFont
+ 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:

defaultHighlightBackgroundColor
+ (NXColor)defaultHighlightBackgroundColor

Returns NX_COLORWHITE as the default highlighted background color. This is the color which is returned by -highlightBackgroundColor 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 -highlightBackgroundColor message. This is also the color used upon receipt of a -setUseOwnerHighlightBackgroundColor:NO message. Subclasses should override this method if this color is inappropriate.

See also: + defaultBackgroundColor, �+�defaultHighlightTextColor, + defaultTextColor, ���highlightBackgroundColor, � setHighlightBackgroundColor:, ���setUseOwnerHighlightBackgroundColor:

defaultHighlightTextColor
+ (NXColor)defaultHighlightTextColor

Returns NX_COLORBLACK as the default highlighted text color. This is the color which is returned by -highlightTextColor 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 -highlightTextColor message. This is also the color used upon receipt of a -setUseOwnerHighlightTextColor:NO message. Subclasses should override this method if this color is inappropriate.

See also: + defaultBackgroundColor, �+�defaultHighlightBackgroundColor, + defaultTextColor, ���highlightTextColor, � setHighlightBackgroundColor:, ���setUseOwnerHighlightBackgroundColor:

defaultTextColor
+ (NXColor)defaultTextColor

Returns NX_COLORBLACK 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, �+�defaultHighlightBackgroundColor, �+�defaultHighlightTextColor, � setHighlightBackgroundColor:, ���setUseOwnerHighlightBackgroundColor:, � textColor

Instance Methods

backgroundColor
- (NXColor)backgroundColor

Returns the color that is used to draw the background of the cell in its normal (unhighlighted) 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: � backgroundGray, + defaultBackgroundColor, � highlightBackgroundColor, ���highlightTextColor, � setBackgroundColor:, � textColor

backgroundGray
- (float)backgroundGray

Returns the gray value from by NXConvertColorToGray() given the color returned by -backgroundColor.

See also: � backgroundColor, � highlightBackgroundGray, � highlightTextGray, ���setBackgroundGray:, � textGray

bgColor
- (NXColor)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 -highlightBackgroundColor, 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, � highlightBackgroundColor

copyFromZone:
- (id)copyFromZone:(NXZone*)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: � copyFromZone: (Cell), � free, � initIconCell:, � initTextCell:

drawInside:inView:
- (id)drawInside:(NXRect const*)cellFrame
inView: controlView

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

See also: - drawInside:inView: (Cell), - drawSelf:inView:, - lockFocus (View)

drawSelf:inView:
- (id)drawSelf:(NXRect const*)cellFrame
inView: 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 �drawInside:inView:. Returns self.

See also: - drawInside:inView:, � drawSelf:inView: (Cell), - lockFocus (View)

fgColor
- (NXColor)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 -highlightTextColor, 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, � highlightTextColor, � textColor

font
- (id)font

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

See also: -write:

setBackgroundColor:
- (id)setBackgroundColor:(NXColor)c

Sets the color that the cell will use to fill its background. This color will override any inherited value. Returns self.

setBackgroundGray:
- (id)setBackgroundGray:(float)value

The gray value is converted to a color value which is passed to -setBackgroundColor:. Returns self.

setFont:
- (id)setFont:(id)font

Sets the font of a text cell to font. This will override any inherited value. Returns self.

setHighlightBackgroundColor:
- (id)setHighlightBackgroundColor:(NXColor)c

Sets the color that will be used to fill the background of a text cell when the cell is highlighted. This will override any inherited value. Returns self.

setHighlightBackgroundGray:
- (id)setHighlightBackgroundGray:(float)value

The gray value is converted to a color value which is passed to -setHighlightBackgroundColor:. Returns self.

setHighlightTextColor:
- (id)setHighlightTextColor:(NXColor)c

Sets the color that will be used to draw the text of a text cell. This will override any inherited value. Returns self.

setHighlightTextGray:
- (id)setHighlightTextGray:(float)value

The gray value is converted to a color value which is passed to -setHighlightTextColor:. Returns self.

setImage:
- (id)setImage:(id)image

Sets the image that will be displayed in an icon cell. Returns self.

See also: � icon (Cell), � image, � initIconCell:, � setIcon: (Cell)

setOwner:
- (id)setOwner:(id)obj

Sets the owner of the cell to obj. The cell will inherit font and color values from obj. Returns self.

setOwnerDraw:
- (id)setOwnerDraw:(BOOL)flag

Sets a flag indicating whether or not the owner should perform the drawing for this object. The default value for MiscTableCell objects is YES. Returns self.

setOwnerBackgroundColor:
- (id)setOwnerBackgroundColor:(NXColor)c

Informs the cell that the owner's backgroundColor value has changed to c. The current implementation does nothing, since inherited owner values are not stored in the cells. However, the MiscTableScroll class tests for, and sends this message in preference to the -setBackgroundColor: message when the table distributes colors to the cells, so that cells can distinguish between cell-specific color assignments and global color assignments. Returns self.

setOwnerFont:
- (id)setOwnerFont:(id)font

Informs the cell that the owner's font value has changed to font. If the cell is using the font value inherited from its owner, it will change its font in response to this message. Otherwise, it will ignore the message. The MiscTableScroll class tests for, and sends this message in preference to the -setFont: message when the table distributes fonts to the cells, so that cells can distinguish between cell-specific font assignments and global font assignments. Returns self.

setOwnerHighlightBackgroundColor:
- (id)setOwnerHighlightBackgroundColor:(NXColor)c

Informs the cell that the owner's highlightBackgroundColor value has changed to c. The current implementation does nothing, since inherited owner values are not stored in the cells. However, the MiscTableScroll class tests for, and sends this message in preference to the -setHighlightBackgroundColor: message when the table distributes colors to the cells, so that cells can distinguish between cell-specific color assignments and global color assignments. Returns self.

setOwnerHighlightTextColor:
- (id)setOwnerHighlightTextColor:(NXColor)c

Informs the cell that the owner's highlightTextColor value has changed to c. The current implementation does nothing, since inherited owner values are not stored in the cells. However, the MiscTableScroll class tests for, and sends this message in preference to the -setHighlightTextColor: message when the table distributes colors to the cells, so that cells can distinguish between cell-specific color assignments and global color assignments. Returns self.

setOwnerTextColor:
- (id)setOwnerTextColor:(NXColor)c

Informs the cell that the owner's textColor value has changed to c. The current implementation does nothing, since inherited owner values are not stored in the cells. However, the MiscTableScroll class tests for, and sends this message in preference to the -setTextColor: message when the table distributes colors to the cells, so that cells can distinguish between cell-specific color assignments and global color assignments. Returns self.

setSelected:
- (id)setSelected:(BOOL)flag

Sets the cell's selected status to flag. Selected cells draw with the highlighted colors. Returns self.

setTag:
- (id)setTag:(int)x

Sets the cell's tag value to x. Returns self.

setTextColor:
- (id)setTextColor:(NXColor)c

Causes the cell to render its text with the color, c. This overrides any textColor value inherited from the owner. Returns self.

setTextGray:
- (id)setTextGray:(float)value

Value is converted to a color value which is passed to -setTextColor:. Returns self.

setUseOwnerBackgroundColor:
- (id)setUseOwnerBackgroundColor:(BOOL)flag

If flag is YES, the cell will discard any backgroundColor value that it is currently storing, and begin using the backgroundColor value provided by the owner. If the owner has not been set, or the owner does not respond to the -backgroundColor message, then the value returned by +defaultBackgroundColor will be used. If flag is NO, the cell will make room to store a backgroundColor value, and initialize it to the value returned by the +defaultBackgroundColor method. Returns self.

setUseOwnerFont:
- (id)setUseOwnerFont:(BOOL)flag

If flag is YES, the cell will use the font value inherited from its owner. If flag is NO, the cell will continue using its current font, or fonts set via the -setFont: message rather than the font inherited from the owner. This method also updates the MISC_TC1_SELF_FONT bit of the tc1_flags bit mask. Returns self.

setUseOwnerHighlightBackgroundColor:
- (id)setUseOwnerHighlightBackgroundColor:(BOOL)flag

If flag is YES, the cell will discard any highlightBackgroundColor value that it is currently storing, and begin using the highlightBackgroundColor value provided by the owner. If the owner has not been set, or the owner does not respond to the -highlightBackgroundColor message, then the value returned by +defaultHighlightBackgroundColor will be used. If flag is NO, the cell will make room to store a highlightBackgroundColor value, and initialize it to the value returned by the +defaultHighlightBackgroundColor method. Returns self.

setUseOwnerHighlightTextColor:
- (id)setUseOwnerHighlightTextColor:(BOOL)flag

If flag is YES, the cell will discard any highlightTextColor value that it is currently storing, and begin using the highlightColor value provided by the owner. If the owner has not been set, or the owner does not respond to the -highlightTextColor message, then the value returned by +defaultHighlightTextColor will be used. If flag is NO, the cell will make room to store a highlightTextColor value, and initialize it to the value returned by the +defaultHighlightTextColor method. Returns self.

setUseOwnerTextColor:
- (id)setUseOwnerTextColor:(BOOL)flag

If flag is YES, the cell will discard any textColor value that it is currently storing, and begin using the textColor value provided by the owner. If the owner has not been set, or the owner does not respond to the -textColor message, then the value returned by +defaultTextColor will be used. If flag is NO, the cell will make room to store a textColor value, and initialize it to the value returned by the +defaultTextColor method. Returns self.

tableScroll:retireAt::
- (id)tableScroll:(MiscTableScroll*)scroll retireAt:(int)row :(int)col

MiscTableCell's implementation of the MiscTableScroll call-back method. This method is called whenever the cell is removed from active use by the MiscTableScroll as the result of any of the methods that reduce the number of active rows (ex: -renewRows:, -empty, etc.). The current implementation clears the string value of text cells. Unfortunately, since the overhead of performing these reset operations is quite high, the behavior of this method might change in the future. Returns self.

tableScroll:reviveAt:
- (id)tableScroll:(MiscTableScroll*)scroll reviveAt:(int)row :(int)col

MiscTableCell's implementation of the MiscTableScroll call-back method. This method is called whenever the cell is brought into active use by the MiscTableScroll as the result of any of the methods that expand the number of active rows (ex: -renewRows:, -addRow, etc.). This method sets scroll as the owner of the cell, then ensures that all attributes are set to the use-owner values. Unfortunately, since the overhead of performing these initializations is quite high, the behavior of this method might change in the future. Returns self.

tag
- (int)tag

Returns the cell's tag value.