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
-
- sourceList:numberOfChildrenOfItem:
Invoked by aSourceList to returns the number of direct child items of an item in the data source. -
- sourceList:child:ofItem:
Invoked by aSourceList to return the direct child of a particular item, at a specified index. -
- sourceList:objectValueForItem:
Invoked by aSourceList to return the data object associated with item. -
- sourceList:isItemExpandable:
Invoked by aSourceList to return whether an item in the Source List is expandable. -
- sourceList:setObjectValue:forItem:
Invoked by aSourceList to set the associated object value of a specified item.
Working with Badges
-
- sourceList:itemHasBadge:
Returns a Boolean specifying whether a given item shows a badge or not. -
- sourceList:badgeValueForItem:
Returns an integer specifying the badge value for a particular item. -
- sourceList:badgeTextColorForItem:
Returns a color that is used for the badge text color of an item in the Source List. -
- sourceList:badgeBackgroundColorForItem:
Returns a color that is used for the badge background color of an item in the Source List.
Working with Icons
-
- sourceList:itemHasIcon:
Returns a Boolean specifying whether a given item shows an icon or not. -
- sourceList:iconForItem:
Returns the icon for a given item in the Source List.
Handling right-clicking
-
- sourceList:contextMenuForItem:
Allows the data source to provide a context menu for a given item.
Supporting Object Persistence
-
- sourceList:itemForPersistentObject:
Invoked by aSourceList to return the item for the archived object. -
- sourceList:persistentObjectForItem:
Invoked by aSourceList to return an archived object for item.
Supporting Drag and Drop
-
- sourceList:writeItems:toPasteboard:
Returns a Boolean value specifying whether a drag operation is allowed. -
- sourceList:validateDrop:proposedItem:proposedChildIndex:
Used by a Source List to determine a valid drop target. -
- sourceList:acceptDrop:item:childIndex:
Returns a Boolean value specifying whether a drag operation was successful. -
- sourceList:namesOfPromisedFilesDroppedAtDestination:forDraggedItems:
Returns an array of filenames (not file paths) for the created files that the receiver promises to create.
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
- sourceList:badgeValueForItem:
- sourceList:badgeTextColorForItem:
- sourceList:badgeBackgroundColorForItem:
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
- sourceList:itemHasBadge:
- sourceList:badgeTextColorForItem:
- sourceList:badgeBackgroundColorForItem:
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
- sourceList:itemHasBadge:
- sourceList:badgeValueForItem:
- sourceList:badgeBackgroundColorForItem:
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