| 1 | // |
|---|
| 2 | // AIOutlineView.h |
|---|
| 3 | // Adium |
|---|
| 4 | // |
|---|
| 5 | // Created by Adam Iser on Tue Mar 23 2004. |
|---|
| 6 | // Copyright (c) 2004-2005 The Adium Team. All rights reserved. |
|---|
| 7 | // |
|---|
| 8 | |
|---|
| 9 | #define AIOutlineViewUserDidExpandItemNotification @"AIOutlineViewUserDidExpandItemNotification" |
|---|
| 10 | #define AIOutlineViewUserDidCollapseItemNotification @"AIOutlineViewUserDidCollapseItemNotification" |
|---|
| 11 | |
|---|
| 12 | @class NSMutableString; |
|---|
| 13 | @class NSMenu, NSEvent, NSOutlineView, NSImage; |
|---|
| 14 | @class AIOutlineView; |
|---|
| 15 | |
|---|
| 16 | /*! |
|---|
| 17 | * @protocol AIOutlineViewDelegate |
|---|
| 18 | * @brief Delegate protocol for <tt>AIOutlineView</tt> |
|---|
| 19 | * |
|---|
| 20 | * Implementation of all methods is optional. |
|---|
| 21 | */ |
|---|
| 22 | @protocol AIOutlineViewDelegate |
|---|
| 23 | /*! |
|---|
| 24 | * @brief Requests a contextual menu for an event from the delegate |
|---|
| 25 | * |
|---|
| 26 | * This delegate method gives the delegate an opportunity to return an <tt>NSMenu</tt> to be displayed when the user right-clicks (control-clicks) in the outline view. The passed event can be used to determine where the click occurred to make the menu sensitive to which row or column was clicked. |
|---|
| 27 | * @param outlineView The <tt>NSOutlineView</tt> which was clicked |
|---|
| 28 | * @param theEvent The event of the click |
|---|
| 29 | * @return An <tt>NSMenu</tt> to be displayed, or nil if no menu should be displayed |
|---|
| 30 | */ |
|---|
| 31 | - (NSMenu *)outlineView:(NSOutlineView *)outlineView menuForEvent:(NSEvent *)theEvent; |
|---|
| 32 | |
|---|
| 33 | /*! |
|---|
| 34 | * outlineView:setExpandState:ofItem: |
|---|
| 35 | * @brief Informs the delegate that the item was collapsed or exapnded |
|---|
| 36 | * |
|---|
| 37 | * This delegate method informs the delegate that the item was collapsed or expanded. |
|---|
| 38 | * @param outlineView The <tt>NSOutlineView</tt> which was changed |
|---|
| 39 | * @param state YES if the item is now expanded; NO if it is no collapsed |
|---|
| 40 | * @param item The item which was changed |
|---|
| 41 | */ |
|---|
| 42 | - (void)outlineView:(NSOutlineView *)outlineView setExpandState:(BOOL)state ofItem:(id)item; |
|---|
| 43 | |
|---|
| 44 | /*! |
|---|
| 45 | * @brief Requests the correct expanded state for an item |
|---|
| 46 | * |
|---|
| 47 | * After reloading data, NSOutlineView collapses all items, which is generally not a desired behavior. <tt>AIOutlineView</tt> provides the delegate an opportunity to specify whether each item should be exapnded or collapsed after a reload. This delegate method should return the correct expanded state of the passed item. |
|---|
| 48 | * @param outlineView The <tt>NSOutlineView</tt> which is reloading data |
|---|
| 49 | * @param item The item whose expanded state is requested |
|---|
| 50 | * @return YES if the item should be expanded; NO if it should be collapsed |
|---|
| 51 | */ |
|---|
| 52 | - (BOOL)outlineView:(NSOutlineView *)outlineView expandStateOfItem:(id)item; |
|---|
| 53 | |
|---|
| 54 | /*! |
|---|
| 55 | * @brief Informs the delegate of a request to delete the selected rows |
|---|
| 56 | * |
|---|
| 57 | * Informs the delegate of a request to delete the selected rows (via the delete key, generally). The delegate may wish to retrieve the currently selected rows and remove them from the data source and subsequently reload the outline view. |
|---|
| 58 | * @param outlineView The <tt>NSOutlineView</tt> from which the user wants to delete one or more rows. |
|---|
| 59 | */ |
|---|
| 60 | - (void)outlineViewDeleteSelectedRows:(NSOutlineView *)outlineView; |
|---|
| 61 | |
|---|
| 62 | /*! |
|---|
| 63 | * @brief Passes on NSObject's <tt>draggedImage:endedAt:operation:</tt> to the delegate |
|---|
| 64 | * |
|---|
| 65 | * Passes on NSObject's <tt>draggedImage:endedAt:operation:</tt>, which is invoked in the dragging source as the drag ends, |
|---|
| 66 | * to the delegate. See <tt>NSObject</tt>'s documentation for more details. |
|---|
| 67 | * |
|---|
| 68 | * @param outlineView The <tt>NSOutlineView</tt> which ended the drag |
|---|
| 69 | * @param image The <tt>NSImage</tt> drag image |
|---|
| 70 | * @param screenPoint An <tt>NSPoint</tt> in screen coordinates |
|---|
| 71 | * @param operation The <tt>NSDragOperation</tt> of the drag |
|---|
| 72 | */ |
|---|
| 73 | - (void)outlineView:(NSOutlineView *)outlineView draggedImage:(NSImage *)image endedAt:(NSPoint)screenPoint operation:(NSDragOperation)operation; |
|---|
| 74 | |
|---|
| 75 | /*! |
|---|
| 76 | * @brief Informs the delegate of a request to show or hide the fine panel |
|---|
| 77 | * |
|---|
| 78 | * Informs the delegate of a request to show the find panel if it is hidden, and hide it if shown. The delegate must implement the find panel UI and filtering |
|---|
| 79 | * @param outlineView The <tt>NSOutlineView</tt> that the user wants to filter |
|---|
| 80 | */ |
|---|
| 81 | - (void)outlineViewToggleFindPanel:(NSOutlineView *)outlineView; |
|---|
| 82 | |
|---|
| 83 | |
|---|
| 84 | /*! |
|---|
| 85 | * @brief Informs the delegate of a request to forward a key down event to the find panel text field, displaying it if necessary |
|---|
| 86 | * |
|---|
| 87 | * Informs the delegate of a request to forward a key down event to the find panel text field,displaying it if necessary. The key down event was recieved by outlineView, and it determined it should be added to the search string |
|---|
| 88 | * @param outlineView The <tt>NSOutlineView</tt> that the user wants to filter |
|---|
| 89 | * @param theEvent The key down event |
|---|
| 90 | * |
|---|
| 91 | * @result YES if the find panel handled theEvent. If NO, outlineView will forward theEvent to super for handling |
|---|
| 92 | */ |
|---|
| 93 | - (BOOL)outlineView:(NSOutlineView *)outlineView forwardKeyEventToFindPanel:(NSEvent *)theEvent; |
|---|
| 94 | |
|---|
| 95 | @end |
|---|
| 96 | |
|---|
| 97 | /*! |
|---|
| 98 | * @class AIOutlineView |
|---|
| 99 | * @brief An NSOutlineView subclass with several improvments |
|---|
| 100 | * |
|---|
| 101 | * <p>This <tt>NSOutlineView</tt> subclass has several improvements and serves as the base class for the other outline view subclasses in the AIUtilities framework.</p> |
|---|
| 102 | * <p>It supports contextual menu, expanded state, deletion, and dragging-ended notification methods for its delegate (see the <tt>AIOutlineViewDelegate</tt> protocol description for details).</p> |
|---|
| 103 | * <p>It posts AIOutlineViewUserDidExpandItemNotification and AIOutlineViewUserDidCollapseItemNotification to the default NSNotificationCenter when items expand and collapse, respectively; for these notifications, the object is the <tt>AIOutlineView</tt> and the userInfo is an NSDictionary with the changed item in the key @"Object". |
|---|
| 104 | * <p>It supports improved keyboard navigation of the outline view, including supporting the delete key.</p> |
|---|
| 105 | * <p>It adds the use of tab and backtab to cycle through matches when using KFTypeSelectTableView</p> |
|---|
| 106 | * <p>Finally, it fixes a crash when reloadData is called from 'outlineView:setObjectValue:forTableColumn:byItem:' while the last row is edited in a way that will reduce the number of rows in the outline view (crash fix is relevant on all system versions as of OS X 10.3.7).</p> |
|---|
| 107 | */ |
|---|
| 108 | @interface AIOutlineView : NSOutlineView { |
|---|
| 109 | BOOL needsReload; |
|---|
| 110 | BOOL ignoreExpandCollapse; |
|---|
| 111 | } |
|---|
| 112 | - (void)performFindPanelAction:(id)sender; |
|---|
| 113 | @end |
|---|
