PXSourceListDataSource protocol reference

PXSourceListDataSource.h

Overview

The PXSourceListDataSource protocol defines methods that can be implemented by data sources of PXSourceList objects.

Despite many of these methods being optional in their implementation, several methods must be implemented by a data source of a PXSourceList object. These are: - sourceList:numberOfChildrenOfItem:, - sourceList:child:ofItem:, - sourceList:objectValueForItem: and - sourceList:isItemExpandable:

As a side note, many of the methods declared in this protocol are "wrapper" methods of the associated NSOutlineViewDataSource methods, simply to maintain consistency with the naming of the methods, whilst providing an implementation for such things as drag and drop and cell tracking. As such, the documentation provided by Apple for the NSOutlineViewDataSource protocol will be more detailed for these methods.

Tasks

Working with Items in a Source List

Working with Badges

Working with Icons

Handling right-clicking

Supporting Object Persistence

Supporting Drag and Drop

Instance Methods

sourceList:numberOfChildrenOfItem:

Invoked by aSourceList to returns the number of direct child items of an item in the data source.

- (NSUInteger)sourceList:(PXSourceList *)sourceList numberOfChildrenOfItem:(id)item
Parameters
aSourceList

The Source List that sent the message

item

An item in the data source

Return Value

The number of direct child items of item. If item is nil then you should return the number of top-level items in the Source List item hierarchy.

Important: This is a required method.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:child:ofItem:

Invoked by aSourceList to return the direct child of a particular item, at a specified index.

- (id)sourceList:(PXSourceList *)aSourceList child:(NSUInteger)index ofItem:(id)item
Parameters
aSourceList

The Source List that sent the message

index

The index of the child

item

The parent item for which you are returning the child item

Return Value

The direct child of item at the specified index. If item is nil, then return the top-level item with index of index.

Important: This is a required method.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:objectValueForItem:

Invoked by aSourceList to return the data object associated with item.

- (id)sourceList:(PXSourceList *)aSourceList objectValueForItem:(id)item
Parameters
aSourceList

The Source List that sent the message

item

An item in the data source

Return Value

The data object associated with item

Important: This is a required method.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:isItemExpandable:

Invoked by aSourceList to return whether an item in the Source List is expandable.

- (BOOL)sourceList:(PXSourceList *)aSourceList isItemExpandable:(id)item
Parameters
aSourceList

The Source List that sent the message

item

An item in the data source

Return Value

A boolean value specifying whether item is expandable.

Discussion

An expandable item is displayed with a disclosure triangle, unless it is a group item and also displayed as always expanded, as set by the Source List's delegate.

Important: This is a required method.

Availability

Available in Mac OS X v10.5 and later

Declared In
PXSourceListDataSource.h

sourceList:setObjectValue:forItem:

Invoked by aSourceList to set the associated object value of a specified item.

- (void)sourceList:(PXSourceList *)aSourceList setObjectValue:(id)object forItem:(id)item
Parameters
aSourceList

The Source List that sent the message

object

The new object value for item

item

An item in the data source

Discussion

This method must be implemented if any items in the Source List are editable.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:itemHasBadge:

Returns a Boolean specifying whether a given item shows a badge or not.

- (BOOL)sourceList:(PXSourceList *)aSourceList itemHasBadge:(id)item
Parameters
aSourceList

The Source List that sent the message

item

The item that displays the badge

Return Value

A Boolean specifying whether item displays a badge

Discussion

This method can be implemented by the data source to specify whether items display badges or not. A badge is a rounded rectangle containing a number (the badge value), displayed to the right of a row's cell.

This method must be implemented if you want to display a badge for any item with - sourceList:badgeValueForItem:

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:badgeValueForItem:

Returns an integer specifying the badge value for a particular item.

- (NSInteger)sourceList:(PXSourceList *)aSourceList badgeValueForItem:(id)item
Parameters
aSourceList

The Source List that sent the message

item

The item that displays the badge

Return Value

The badge value for item.

Discussion

This method can be implemented by the data source to specify a badge value for any particular item. If you want an item to display a badge, you must implement - sourceList:itemHasBadge: and return YES for that item.

Returning NO for items in - sourceList:itemHasBadge: means that this method will not be called for that item.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:badgeTextColorForItem:

Returns a color that is used for the badge text color of an item in the Source List.

- (NSColor *)sourceList:(PXSourceList *)aSourceList badgeTextColorForItem:(id)item
Parameters
aSourceList

The Source List that sent the message

item

The item whose badge text color you are specifying

Return Value

An NSColor for the custom badge text color.

Discussion

This method can be implemented by the data source to specify a custom badge color for a particular item.

This method is only called for item if you return YES for item in - sourceList:itemHasBadge:. If you return nil then the default text color (as set by the Source List) is used.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:badgeBackgroundColorForItem:

Returns a color that is used for the badge background color of an item in the Source List.

- (NSColor *)sourceList:(PXSourceList *)aSourceList badgeBackgroundColorForItem:(id)item
Parameters
aSourceList

The Source List that sent the message

item

The item whose badge background color you are specifying

Return Value

An NSColor for the custom badge background color.

Discussion

This method can be implemented by the data source to specify a custom badge background color for a particular item.

This method is only called for item if you return YES for item in - sourceList:itemHasBadge:. If you return nil then the default background color (as set by the Source List) is used.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:itemHasIcon:

Returns a Boolean specifying whether a given item shows an icon or not.

- (BOOL)sourceList:(PXSourceList *)aSourceList itemHasIcon:(id)item
Parameters
aSourceList

The Source List that sent the message

item

The item that displays the icon

Return Value

A Boolean specifying whether item displays an icon

Discussion

This method can be implemented by the data source to specify whether items contain icons or not. Icons are images which are shown to the left of the row's cell, and provide a visual which accompanies the cell.

This method must be implemented if you want to return an icon with - sourceList:iconForItem:

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:iconForItem:

Returns the icon for a given item in the Source List.

- (NSImage *)sourceList:(PXSourceList *)aSourceList iconForItem:(id)item
Parameters
aSourceList

The Source List that sent the message

item

The item that displays the icon

Return Value

An NSImage that is the icon for that particular Source List item.

Discussion

This method must be implemented by the data source if you return YES in - sourceList:itemHasIcon: for any item in the Source List.

The maximum size of each icon is specified with the Source List property iconSize

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:contextMenuForItem:

Allows the data source to provide a context menu for a given item.

- (NSMenu *)sourceList:(PXSourceList *)aSourceList contextMenuForItem:(id)item
Parameters
aSourceList

The Source List that sent the message

item

The item that the context menu is for

Return Value

An NSMenu that has already been configured with any menu items and outlets. The Source List does not alter the menu in any way, except for setting itself to be the menu's delegate.

Discussion

This method can be implemented by the data source to provide a context menu that is displayed when the item is right-clicked.

Context menus are only applicable for non-group items (see -[PXSourceList isGroupItem:]).

Availability

Available in Mac OS X v10.5 and later

Declared In
PXSourceListDataSource.h

sourceList:itemForPersistentObject:

Invoked by aSourceList to return the item for the archived object.

- (id)sourceList:(PXSourceList *)aSourceList itemForPersistentObject:(id)object
Parameters
aSourceList

The Source List that sent the message

object

The archived representation of the item in the aSourceList's data source.

Return Value

The unarchived item that corresponds to object.

Discussion

This method must be implemented if autosaveExpandedItems returns YES.

This is essentially a wrapper for outlineView:itemForPersistentObject: defined in the NSOutlineViewDataSource protocol.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:persistentObjectForItem:

Invoked by aSourceList to return an archived object for item.

- (id)sourceList:(PXSourceList *)aSourceList persistentObjectForItem:(id)item
Parameters
aSourceList

The Source List that sent the message

item

The item which you are going to return an archived object for

Return Value

The archived object that corresponds to item.

Discussion

This method must be implemented if autosaveExpandedItems returns YES.

This is essentially a wrapper for outlineView:persistentObjectForItem: defined in the NSOutlineViewDataSource protocol.

Availability

Available in Mac OS X v10.5 and later

See Also
Declared In
PXSourceListDataSource.h

sourceList:writeItems:toPasteboard:

Returns a Boolean value specifying whether a drag operation is allowed.

- (BOOL)sourceList:(PXSourceList *)aSourceList writeItems:(NSArray *)items toPasteboard:(NSPasteboard *)pboard
Parameters
aSourceList

The Source List that sent the message

items

An array of items that are participating in the drag

pboard

The pasteboard to which to write the drag data

Discussion

This is essentially a wrapper for outlineView:writeItems:toPasteboard: defined in the NSOutlineViewDataSource protocol.

Availability

Available in Mac OS X v10.5 and later

Declared In
PXSourceListDataSource.h

sourceList:validateDrop:proposedItem:proposedChildIndex:

Used by a Source List to determine a valid drop target.

- (NSDragOperation)sourceList:(PXSourceList *)sourceList validateDrop:(id)info proposedItem:(id)item proposedChildIndex:(NSInteger)index
Parameters
aSourceList

The Source List that sent the message

info

An object which contains more information about the dragging operation

item

The proposed parent item

index

The proposed child index of the parent

Return Value

An value that specifies which drag operation the data source will perform.

Discussion

This is essentially a wrapper for outlineView:validateDrop:proposedItem:proposedChildIndex: defined in the NSOutlineViewDataSource protocol.

Availability

Available in Mac OS X v10.5 and later

Declared In
PXSourceListDataSource.h

sourceList:acceptDrop:item:childIndex:

Returns a Boolean value specifying whether a drag operation was successful.

- (BOOL)sourceList:(PXSourceList *)aSourceList acceptDrop:(id)info item:(id)item childIndex:(NSInteger)index
Parameters
aSourceList

The Source List that sent the message

info

An object that contains more information about the dragging operation

item

The parent of the item which the cursor was over when the mouse button was released

index

The index of the child of item which the cursor was over when the mouse button was released

Return Value

YES if the drag operation was successful or NO otherwise.

Discussion

This is essentially a wrapper for outlineView:acceptDrop:item:childIndex: defined in the NSOutlineViewDataSource protocol.

Availability

Available in Mac OS X v10.5 and later

Declared In
PXSourceListDataSource.h

sourceList:namesOfPromisedFilesDroppedAtDestination:forDraggedItems:

Returns an array of filenames (not file paths) for the created files that the receiver promises to create.

- (NSArray *)sourceList:(PXSourceList *)aSourceList namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropDestination forDraggedItems:(NSArray *)items
Parameters
aSourceList

The Source List that sent the message

dropDestination

The drop location where the files are created

items

The items that are being dragged

Discussion

This is essentially a wrapper for outlineView:namesOfPromisedFilesDroppedAtDestination:forDraggedItems: defined in the NSOutlineViewDataSource protocol.

Availability

Available in Mac OS X v10.5 and later

Declared In
PXSourceListDataSource.h

Last updated: 2010-01-09
Back to index / hierarchy.