DSGeneralTableView Class Reference





Author


Overview
Tasks
Instance Methods
Delegate Methods
Version History

Overview


A table view for general use. This subclass has the following features:

Tasks



Custom Alternating Row Colors

— setCustomAlternatingRowColors:
— customAlternatingRowColors
— setUseCustomAlternatingRowColors:
— useCustomAlternatingRowColors

Working With Drag Events

— setDraggingSourceOperationMaskForLocal:external:
— setIgnoreModifierKeysWhileDragging:
— tableView:dragFailed:endedAt:isInside: (delegate method)
— tableView:dragImageForSelectedRows:selectedColumns:dragImagePosition:dragImageSize:event: (delegate method)
— tableViewShouldSlidebackDragImage: (delegate method)

Row Selections

— setRoundedSelections:
— roundedSelections
— setUseGradientSelection:
— useGradientSelection
— setUseHighlightColorInBackground:
— useHighlightColorInBackground

Drawing Selections

— gradientFillInRect:startColor:endColor:
— highlightImage
— secondaryHighlightImage
— highlightSelectionInClipRect:

First Responder status

— isFirstResponder

Key & Text Events

— tableView:shouldHandleKeyDown: (delegate method)
— tableView:shouldAllowTextMovement:tableColumn:row: (delegate method)

Instance Methods


customAlternatingRowColors

The alternating row colors.

— (NSArray *)customAlternatingRowColors

Return Value

Returns the custom alternating row colors being used, or nil if they haven't been set.

See Also

— setCustomAlternatingRowColors:

gradientFillInRect:startColor:endColor:

Fills the specified rect with a gradient.

&mdash (void)— gradientFillInRect:(NSRect)fillRect startColor:(NSColor *)startColor endColor:(NSColor *)endColor

Parameters

fillRect

The rect you wish to fill with a gradient.

startColor

The starting color of the gradient. Note this color must be a device RGB color.

endColor

The ending color of the gradient. Note this color must be a device RGB color.

highlightImage

The highlight image drawn as the selection(s).

— (NSImage *)highlightImage

Return Value

Returns the image used to draw the selection(s).

See Also

— secondaryHighlightImage

highlightSelectionInClipRect:

Draws the selections.

— (void)highlightSelectionInClipRect:(NSRect)clipRect

Parameters

clipRect

The visible portion of the table view.

isFirstResponder

Returns if the table view is the first responder.

— (BOOL)isFirstResponder

Return Value

If the table view is the first responder, returns YES, otherwise returns NO.

roundedSelections

Returns if the table view is using rounded selections or not.

— (BOOL)roundedSelections

Return Value

Returns YES if rounded selections are being used, NO otherwise.

See Also

— authorizedCopySelector

secondaryHighlightImage

The inactive highlight image drawn as the selection(s).

— (NSImage *)secondaryHighlightImage

Return Value

Returns the image used to draw the selection(s) when the table view is inactive. Only used if the table view is using the highlight color in the background.

See Also

— highlightImage
— setUseHighlightColorInBackground:
— useHighlightColorInBackground

setCustomAlternatingRowColors:

Sets the color of the alternating row colors.

— (void)setCustomAlternatingRowColors:(NSArray *)colorArray

Parameters

colorArray

An array containing two colors to be used as the row colors.

See Also

— customAlternatingRowColors

setDraggingSourceOperationMaskForLocal:external:

Sets the dragging source opertaions.

— (void)setDraggingSourceOperationMaskForLocal:(NSDragOperation)localOperation external:(NSDragOperation)externalOperation

Discussion

For ease of setting your drag operations without needing to edit the subclass.

Note that there's a new method on 10.4 that will do this — this is mainly for pre 10.4 use.

See Also

— setDraggingSourceOperationMask:forLocal: (NSTableView)

setIgnoreModifierKeysWhileDragging:

Sets if modifier keys are ignored during drags.

— (void)setIgnoreModifierKeysWhileDragging:(BOOL *)aFlag

Parameters

aFlag

If YES, ignores modifier keys while dragging. If NO, honors modifier keys while dragging.

See Also

— ignoreModifierKeysWhileDragging: (NSDraggingSource)

setRoundedSelections:

Sets if the table view uses rounded selections.

— (void)setRoundedSelections:(BOOL)aFlag

Parameters

aFlag

If YES, selections are rounded. If NO, selections are normal.

See Also

— roundedSelections

setUseCustomAlternatingRowColors:

Sets if custom alternating row colors are used.

— (void)setUseCustomAlternatingRowColors:(BOOL)aFlag

Parameters

aFlag

If YES, sets the table view to use custom alternating row colors.

Discussion

This method will do nothing if the alternating row colors have not been set.

This flag is automatically turned on when custom row colors are set. Most likely, you will not need to call this method.

See Also

— customAlternatingRowColors
— setCustomAlternatingRowColors:

setUseGradientSelection:

Sets if the table view uses gradient selections.

— (void)setUseGradientSelection:(BOOL)aFlag

Parameters

aFlag

If YES, selections use gradients. If NO, selections are normal.

Discussion

Gradient selections are used by default.

See Also

— useGradientSelection

setUseHighlightColorInBackground:

Sets if highlights are tinted with the user's selection color when inactive.

— (void)setUseHighlightColorInBackground:(BOOL)aFlag

Parameters

aFlag

If YES, sets to tint the highlight color when inactive.

Discussion

This is used by default.

See Also

— useHighlightColorInBackground

useCustomAlternatingRowColors

Returns if custom alternating row colors are being used.

— (BOOL)useCustomAlternatingRowColors

Return Value

Returns YES if custom alternating row colors are being used, NO if they aren't.

See Also

— setUseCustomAlternatingRowColors:

useGradientSelection

Returns if the table view is using gradient selections.

— (BOOL)gradientSelection

Return Value

Returns YES if gradient selections are being used, NO otherwise.

See Also

— setUseGradientSelection:

useHighlightColorInBackground

Returns if the table view is tinting the selections with the highlight color when inactive.

— (BOOL)useHighlightColorInBackground

Return Value

Returns YES if highlights are tinted when inactive, NO otherwise.

See Also

— setUseHighlightColorInBackground:

Delegate Methods


tableView:dragFailed:endedAt:isInside:

Lets the delegate know the drag failed.

— (void)tableView:(NSTableView *)tableView dragFailed:(NSDragOperation)operation endedAt:(NSPoint)endPoint isInside:(BOOL)isInside

Parameters

tableView

The table view for which the drag failed.

operation

The returned drag operation.

endPoint

The last position (in screen coordinates) of the lower left corner of the drag image before the drag failed.

isInside

If YES, the drag ended inside the table view.

Discussion

You can use this method to do whatever sort of clean up or anything of that nature you wish to if the drag fails.

Note that this method is called both when a drag is not accepted by any drag sources AND if the drag is dropped over the Trash icon in the Dock. In the former case, the operation parameter will be NSDragOperationNone, and in the latter it will be NSDragOperationDelete.

tableView:dragImageForSelectedRows:selectedColumns:dragImagePosition:dragImageSize:event:

Called when a drag is started to create a custom drag image.

— (NSImage *)tableView:(NSTableView *)tableView dragImageForSelectedRows:(NSIndexSet *)selectedRows selectedColumns:(NSIndexSet *)selectedColumns dragImagePosition:(NSPointPointer)imageLocation dragImageSize:(NSSize)imageSize event:(NSEvent *)dragEvent

Parameters

tableView

The table view that is starting the drag.

selectedRows

The row indexes that are selected in the table view.

selectedColumns

The column indexes that are selected in the table view.

imageLocation

A pointer to the coordinates of the lower left corner of the default drag image.

imageSize

The size of the default drag image.

dragEvent

The drag event.

Return Value

The image you wish to use as the drag image, or nil if you wish to use the table view's drag image.

Discussion

You can use this method to create your own drag image. Some things to note:

tableView:shouldAllowTextMovement:tableColumn:row:

Called when a text movement (i.e. an edit) occurs.

— (BOOL)tableView:(NSTableView *)tableView shouldAllowTextMovement:(unsigned int)textMovement tableColumn:(NSTableColumn *)tableColumn item:(int)row

Parameters

tableView

The table view for which the text movement is occurring.

textMovement

The text movment that is occurring.

tableColumn

The table column that is currently being edited.

row

The row that is currently being edited.

Return Value

If the delegate handles the text movement (or wants to ignore it), this method should return NO, otherwise it should return YES to allow the table view to handle it as it normally would.

Discussion

You can use this method to stop the edit from completing (though a formatter would likely be a better way to do this), keep the return key from going to the next field, or to keep the tab key from moving on to the next item.

tableView:shouldHandleKeyDown:

Called when a key down event occurs.

— (BOOL)tableView:(NSTableView *)tableView shouldHandleKeyDown:(NSEvent *)keyEvent

Parameters

tableView

The table view for which the key down event is occurring.

keyEvent

The key down event that is occurring.

Return Value

If the delegate handles the keydown, this method should return NO, otherwise it should return YES to allow the table view to handle it as it normally would.

tableViewShouldSlidebackDragImage:

Called when a drag is started to see if the image should slideback if not accepted.

— (BOOL)tableViewShouldSlidebackDragImage:(NSTableView *)tableView

Parameters

tableView

The table view that is starting the drag.

Return Value

If you wish for the drag image to slide back if not accepted, return YES, otherwise return NO.

Version History



0.1
May 25, 2007 - Initial release.