Cleanup QSCatalogEntry API.

Quicksilver/Code-App/QSCatalogPrefPane.m

@@ -31,6 +31,7 @@
 #include <unistd.h>
 #import "QSOutlineView.h"
 #import "QSTableView.h"
+#import "QSCatalogEntry_Private.h"
 
 @interface QSObject (NSTreeNodePrivate)
 //- (NSIndexPath *)indexPath;
@@ -168,8 +169,8 @@ - (void)awakeFromNib {
 	[[[itemContentsTable tableColumnWithIdentifier:kItemPath] dataCell] setFont:[NSFont labelFontOfSize:9]];
 	[[[itemContentsTable tableColumnWithIdentifier:kItemPath] dataCell] setWraps:NO];
 
-	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(catalogChanged:) name:QSCatalogEntryChanged object:nil];
-	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(catalogIndexed:) name:QSCatalogEntryIndexed object:nil];
+	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(catalogChanged:) name:QSCatalogEntryChangedNotification object:nil];
+	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(catalogIndexed:) name:QSCatalogEntryIndexedNotification object:nil];
 	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(updateEntrySelection) name:NSOutlineViewSelectionDidChangeNotification object:nil];
 
 	[itemTable reloadData];
@@ -283,7 +284,7 @@ - (IBAction)addSource:(id)sender {
 		[self showOptionsDrawer];
 
 	[[NSNotificationCenter defaultCenter] postNotificationName:QSCatalogStructureChanged object:nil];
-	[[NSNotificationCenter defaultCenter] postNotificationName:QSCatalogEntryChanged object:childEntry];
+	[[NSNotificationCenter defaultCenter] postNotificationName:QSCatalogEntryChangedNotification object:childEntry];
 }
 
 - (IBAction)saveItem:(id)sender {
@@ -539,8 +540,7 @@ - (void)populateCatalogEntryFields {
 
 - (IBAction)setValueForSenderForCatalogEntry:(id)sender {
 	if (sender == itemIconField) {
-		NSData *imageData = [[sender image] TIFFRepresentationUsingCompression:NSTIFFCompressionLZW factor:0];
-		[[currentItem info] setObject:imageData forKey:kItemIcon];
+        currentItem.icon = [sender image];
 		[itemTable reloadData];
 	}
 }
@@ -574,7 +574,7 @@ - (BOOL)windowShouldClose:(id)sender {
 }
 
 - (IBAction)applySettings:(id)sender {
-	[[NSNotificationCenter defaultCenter] postNotificationName:QSCatalogEntryChanged object:nil];
+	[[NSNotificationCenter defaultCenter] postNotificationName:QSCatalogEntryChangedNotification object:nil];
 	[(QSController *)[NSApp delegate] rescanItems:sender];
 }
 

Quicksilver/Code-App/QSSetupAssistant.m

@@ -78,7 +78,7 @@ - (void)windowDidLoad {
 	// [setupTabView removeTabViewItem:[setupTabView tabViewItemAtIndex:[setupTabView indexOfTabViewItemWithIdentifier:@"network"]]];
 	//[setupTabView removeTabViewItem:[setupTabView tabViewItemAtIndex:[setupTabView indexOfTabViewItemWithIdentifier:@"features"]]];
 	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(installStatusChanged:) name:@"QSPlugInUpdatesFinished" object:nil];
-	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(catalogIndexed:) name:QSCatalogEntryIsIndexing object:nil];
+	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(catalogIndexed:) name:QSCatalogEntryIsIndexingNotification object:nil];
 	[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(catalogIndexingFinished:) name:QSCatalogIndexingCompleted object:nil];
 
 	[[self window] setLevel:NSNormalWindowLevel];
@@ -145,7 +145,7 @@ - (void)catalogIndexingFinished:(id)notif {
 	}
 }
 - (void)catalogIndexed:(NSNotification *)notif {
-	if ([[notif name] isEqualToString:QSCatalogEntryIsIndexing])
+	if ([[notif name] isEqualToString:QSCatalogEntryIsIndexingNotification])
 		[scanStatusField setStringValue:[NSString stringWithFormat:@"Scanning %@", [(QSCatalogEntry *)[notif object] name]]];
 }
 

Quicksilver/Code-QuickStepCore/QSCatalogEntry.h

@@ -8,79 +8,254 @@
 
 #import <Cocoa/Cocoa.h>
 
-@interface QSCatalogEntry : NSObject {
-	__block NSDate *indexDate;
-	BOOL isPreset;
+@class QSObjectSource;
 
-	NSString *name;
 
-	id parent;
-	NSMutableArray *children;
-    dispatch_queue_t scanQueue;
-	NSMutableDictionary *info;
-	NSArray *contents;
-	NSBundle *bundle;
-	BOOL isScanning;
-}
+extern NSString *const QSCatalogEntryChangedNotification;
+extern NSString *const QSCatalogEntryIsIndexingNotification;
+extern NSString *const QSCatalogEntryIndexedNotification;
+extern NSString *const QSCatalogEntryInvalidatedNotification;
 
-@property (assign, atomic) BOOL isScanning;
+/**
+ * QSCatalogEntry represent an entry in Quicksilver's catalog.
+ *
+ * It is built as tree of QSCatalogEntry, each having both `children` (more
+ * entries) and `contents` (as a list of `QSObject`s.
+ * It is also responsible for scanning its contents regularly, using one of the
+ * QSObjectSources provided by QS or a plugin.
+ */
+@interface QSCatalogEntry : NSObject
 
+////////////////////////////////////////////////////////////////////////////////
+/// @name Properties
+////////////////////////////////////////////////////////////////////////////////
 
-@property (strong, atomic, getter=_contents) NSArray *contents;
+/** Is the receiver scanning ? */
+@property (readonly, getter=isScanning) BOOL scanning;
 
-+ (QSCatalogEntry *)entryWithDictionary:(NSDictionary *)dict;
+/** Is the receiver suppressed ? */
+@property (readonly, getter=isSuppressed) BOOL suppressed;
+
+/** Is the receiver a default preset ? */
+@property (readonly, getter=isPreset) BOOL preset;
+
+/** Is the receiver a separator ? */
+@property (readonly, getter=isSeparator) BOOL separator;
+
+/** Is the receiver a group of more entries ? */
+@property (readonly, getter=isGroup) BOOL group;
+
+/** Is the receiver modifiable ? */
+@property (readonly, getter=isEditable) BOOL editable;
+
+/** Can the receiver be indexed ? */
+@property (readonly, getter=canBeIndexed) BOOL indexable;
+
+/** Is the receiver enabled ? */
+@property (getter=isEnabled) BOOL enabled;
+
+/** The receiver's displayable name. */
+@property (copy) NSString *name;
+
+/** The receiver's icon. */
+@property (retain) NSImage *icon;
+
+/** The receiver's identifier. */
+@property (readonly, copy) NSString *identifier;
+
+/** The receiver's source. */
+@property (readonly, retain) QSObjectSource *source;
+
+/** The receiver's last index date. */
+@property (retain) NSDate *indexDate;
+
+/** The contents of the receiver. */
+@property (readonly, retain) NSArray *contents;
+
+/** The subentries of the receiver. */
+@property (readonly, retain) NSMutableArray *children;
+
+/** The settings for the receiver's object source. */
+@property (readonly, retain) NSMutableDictionary *sourceSettings;
+
+////////////////////////////////////////////////////////////////////////////////
+/// @name Lifetime
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Create a new instance of the receiver from a dictionary.
+ *
+ * @param dict A serialized entry as a dictionary.
+ *
+ * @see -[QSCatalogEntry initWithDictionary:].
+ */
++ (instancetype)entryWithDictionary:(NSDictionary *)dict;
+
+/**
+ * Initialize the receiver from a dictionary.
+ *
+ * @param dict A dictionary containing
+ *
+ * @return A newly instantiated entry, or nil.
+ */
+- (instancetype)initWithDictionary:(NSDictionary *)dict;
+
+/**
+ * Serialize the receiver to a dictionary.
+ *
+ * @warning This is an implementation detail. You should either use the
+ * receiver's properties, or the private info dictionary.
+ */
 - (NSDictionary *)dictionaryRepresentation;
 
-- (QSCatalogEntry *)initWithDictionary:(NSDictionary *)dict;
-- (void)dealloc;
-- (QSCatalogEntry *)childWithID:(NSString *)theID;
-- (QSCatalogEntry *)childWithPath:(NSString *)path;
-- (BOOL)isSuppressed;
-- (BOOL)isPreset;
-- (BOOL)isSeparator;
-- (BOOL)isGroup;
-- (BOOL)isEditable;
-- (NSInteger) state;
-- (NSInteger) hasEnabledChildren;
-- (BOOL)isEnabled;
-- (void)setEnabled:(BOOL)enabled;
+////////////////////////////////////////////////////////////////////////////////
+/// @name Basic methods
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Get the receiver's children with the given identifier.
+ *
+ * @param theID The identifier to lookup.
+ *
+ * @return An instance of QSCatalogEntry, or nil if there was no children with
+ * the given identifier.
+ */
+- (instancetype)childWithID:(NSString *)theID;
+
+/**
+ * Get one of the receiver's children given an "identifier path".
+ *
+ * @param path A slash-separated string of entry identifiers.
+ *
+ * @return An instance of QSCatalogEntry, or nil if one of the identifiers in
+ * the path wasn't valid.
+ */
+- (instancetype)childWithPath:(NSString *)path;
+
+/** Make a new unique copy of the receiver */
+- (instancetype)uniqueCopy;
+
+/*
+ * The state the receiver is in.
+ *
+ * Depending on whether the receiver is a group or not, returns either its
+ * enabled state, or a negative number whose value represents the number of
+ * enabled leaf entries.
+ */
+- (NSInteger)state;
+
+/** Is any of receiver's children enabled ? */
+- (BOOL)hasEnabledChildren;
+
+/**
+ * Enable or disable the receiver and all its children
+ *
+ * @param enabled Whether to enable or disable the children.
+ */
 - (void)setDeepEnabled:(BOOL)enabled;
+
+/**
+ * Prune all invalid children.
+ *
+ * If the receiver's a preset entry, this will recursively remove all children
+ * which have no contents.
+ */
 - (void)pruneInvalidChildren;
+
+/**
+ * Get the receiver's identifiers for its leaves.
+ *
+ * @return An array of all the enabled leaves's identifiers for the receiver.
+ */
 - (NSArray *)leafIDs;
+
+/**
+ * Get the receiver's enabled leaves.
+ *
+ * @return An array of all the enabled leaves for the receiver.
+ */
 - (NSArray *)leafEntries;
+
+/**
+ * Get the receiver's children.
+ *
+ * @param groups If YES, the resulting array will contain groups.
+ * @param leaves If YES, the resulting array will contain leaves.
+ * @param disabled If YES, the resulting array will contain disabled entries.
+ *
+ * @return An array of all the receiver's children matching the given options.
+ */
 - (NSArray *)deepChildrenWithGroups:(BOOL)groups leaves:(BOOL)leaves disabled:(BOOL)disabled;
-- (NSString *)identifier;
+
+/**
+ * Get the ancestors for the receiver.
+ *
+ * @return An array of the receiver's ancestor chain, starting with the root.
+ */
 - (NSArray *)ancestors;
-- (NSString *)name;
-- (NSImage *)icon;
-- (NSUInteger) deepObjectCount;
+
+/** Get the number of objects contained by the receiver and all its children. */
+- (NSUInteger)deepObjectCount;
+
+/** Same as deepObjectCount */
+- (NSUInteger)count;
+
+/** Returns whether the receiver is the root catalog entry. */
+- (BOOL)isCatalog;
+
+- (NSIndexPath *)catalogIndexPath;
+
+- (NSIndexPath *)catalogSetIndexPath;
+
+/**
+ * Get only the non-ommited objects from that entry and its children
+ */
+- (NSArray *)enabledContents;
+
+////////////////////////////////////////////////////////////////////////////////
+/// @name Indexing
+////////////////////////////////////////////////////////////////////////////////
+
+/** Load the receiver's index. */
 - (BOOL)loadIndex;
+
+/** Save the receiver's index. */
 - (void)saveIndex;
+
+/** Returns whether the index of the receiver is valid. */
 - (BOOL)indexIsValid;
-- (BOOL)isCatalog;
-- (id)source;
-- (BOOL)canBeIndexed;
+
+////////////////////////////////////////////////////////////////////////////////
+/// @name Scanning
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * Get the objects scanned by the receiver's object source.
+ *
+ * @warning This bypasses the index and the receiver's object cache. You should
+ * rarely need to call that method.
+ *
+ * @return An array of all object that the receiver's object source generated.
+ */
 - (NSArray *)scannedObjects;
+
+/**
+ * Scan the receiver and refresh its cache.
+ *
+ * This queries the receiver's source for objects and refresh the index.
+ *
+ * @warning If the receiver's already being scanned, this *will* return nil.
+ *
+ * @return An array of all the objects generated by the object source.
+ */
 - (NSArray *)scanAndCache;
+
+/**
+ * Scan the receiver.
+ *
+ * @param force If YES, the current index will be ignored.
+ */
 - (void)scanForced:(BOOL)force;
-- (NSMutableArray *)children;
-- (NSMutableArray *)getChildren;
-- (NSArray *)contents;
+
 - (NSArray *)contentsScanIfNeeded:(BOOL)canScan;
-- (void)setContents:(NSArray *)newContents;
-- (NSArray *)enabledContents;
-- (NSIndexPath *)catalogIndexPath;
-- (NSMutableDictionary *)info;
-- (QSCatalogEntry *)uniqueCopy;
-- (NSString *)indexLocation;
-- (void)setName:(NSString *)newName;
-
-- (NSDate *)indexDate;
-- (void)setIndexDate:(NSDate *)anIndexDate;
-- (BOOL)isScanning;
-- (void)setIsScanning:(BOOL)flag;
-//- (NSString *)countString;
-
-- (NSUInteger) count;
-- (NSIndexPath *)catalogSetIndexPath;
 @end