|
DrawKit
Vector and illustration framework for Mac OS X
|
The cat manager supports a UI based on menu(s). More...
Instance Methods | |
| (void) | - addCategories: |
| Create a new categories with the given names. More... | |
| (void) | - addCategory: |
| Create a new category with the given name. More... | |
| (void) | - addDefaultCategories |
| Add the default categories defined for this class or object. More... | |
| (void) | - addKey:toCategories:createCategories: |
| Adds a new key to several categories, optionally creating any if necessary. More... | |
| (void) | - addKey:toCategory:createCategory: |
| Adds a new key to a category, optionally creating it if necessary. More... | |
| (BOOL) | - addKey:toRecentList: |
| Add a key to one of the 'recent' lists. More... | |
| (void) | - addObject:forKey:toCategories:createCategories: |
| Add an object to the container, associating with a key and optionally a number of categories. More... | |
| (void) | - addObject:forKey:toCategory:createCategory: |
| Add an object to the container, associating with a key and optionally a category. More... | |
| (NSArray *) | - allCategories |
| Get a list of all categories. More... | |
| (NSArray *) | - allKeys |
| (NSArray *) | - allKeysInCategories: |
| Return all of the keys in all given categories. More... | |
| (NSArray *) | - allKeysInCategory: |
| Return all of the keys in a given category. More... | |
| (NSArray *) | - allObjects |
| Return all of the objects. More... | |
| (NSArray *) | - allSortedKeysInCategory: |
| Return all of the keys in a given category, sorted into some useful order. More... | |
| (NSArray *) | - allSortedNamesInCategory: |
| Return all of the names in a given category, sorted into some useful order. More... | |
| (BOOL) | - appendContentsWithData: |
| Retain all existing content, and load additional content from the archive data passed. More... | |
| (NSArray *) | - categoriesContainingKey: |
| Get a list of all categories that contain a given key. More... | |
| (NSArray *) | - categoriesContainingKey:withSorting: |
| (NSMenu *) | - categoriesMenuWithSelector:target: |
| Creates a menu of categories, recent items and All Items. More... | |
| (NSMenu *) | - categoriesMenuWithSelector:target:options: |
| Creates a menu of categories, recent items and All Items. More... | |
| (BOOL) | - categoryExists: |
| Test whether there is a category of the given name. More... | |
| (void) | - checkItemsInMenu:forCategoriesContainingKey: |
| Sets the checkmarks in a menu of category names to reflect the presence of <key> in those categories. More... | |
| (BOOL) | - containsKey: |
| (void) | - copyItemsFromCategoryManager: |
| Retain all existing content, and load additional content from the cat manager passed. More... | |
| (NSUInteger) | - count |
| Return total number of stored objects in container. More... | |
| (NSUInteger) | - countOfCategories |
| Get the count of all categories. More... | |
| (NSUInteger) | - countOfObjectsInCategory: |
| Count how many objects in the category of the given name. More... | |
| (NSMenu *) | - createMenuWithItemDelegate:isPopUpMenu: |
| Creates a complete menu of the entire contents of the receiver, arranged by category. More... | |
| (NSMenu *) | - createMenuWithItemDelegate:itemTarget:itemAction:options: |
| (NSMenu *) | - createMenuWithItemDelegate:options: |
| (NSData *) | - data |
| Archives the container to a data object (for saving, etc) More... | |
| (NSData *) | - dataWithFormat: |
| (NSArray *) | - defaultCategories |
| Return the default categories defined for this class or object. More... | |
| (NSDictionary *) | - dictionary |
| Return a copy of the master dictionary. More... | |
| (NSString *) | - fileType |
| Return the filetype (for saving, etc) More... | |
| (void) | - fixUpCategories |
| Checks that all keys refer to real objects, removing any that do not. More... | |
| (id) | - initWithData: |
| Initialized a category manager object from archive data. More... | |
| (id) | - initWithDictionary: |
| Initialized a category manager object from an existing dictionary. More... | |
| (BOOL) | - key:existsInCategory: |
| Query whether a given key is present in a particular category. More... | |
| (NSArray *) | - keysForObject: |
| Returns a list of all unique keys that refer to the given object. More... | |
| (id) | - mergeObject:mergeDelegate: |
| Asks delegate to make decision about the merging of an object. More... | |
| (NSSet *) | - mergeObjectsFromSet:inCategories:mergeOptions:mergeDelegate: |
| Smartly merges objects into the category manager. More... | |
| (id) | - objectForKey: |
| Return the object for the given key, but do not remember it in the "recently used" list. More... | |
| (id) | - objectForKey:addToRecentlyUsedItems: |
| Return the object for the given key, optionally remembering it in the "recently used" list. More... | |
| (NSArray *) | - objectsInCategories: |
| Return all of the objects belonging to the given categories. More... | |
| (NSArray *) | - objectsInCategory: |
| Return all of the objects belonging to a given category. More... | |
| (NSArray *) | - recentlyAddedItems |
| Return the list of recently added items. More... | |
| (NSArray *) | - recentlyUsedItems |
| Return the list of recently used items. More... | |
| (void) | - removeAllCategories |
| Removes all categories and objects from the CM. More... | |
| (void) | - removeAllObjects |
| Removes all objects from the container. More... | |
| (void) | - removeCategory: |
| Remove a category with the given name. More... | |
| (void) | - removeKey:fromCategories: |
| Removes a key from a number of categories. More... | |
| (void) | - removeKey:fromCategory: |
| Removes a key from a category. More... | |
| (void) | - removeKey:fromRecentList: |
| Remove a key from one of the 'recent' lists. More... | |
| (void) | - removeKeyFromAllCategories: |
| Removes a key from all categories. More... | |
| (void) | - removeMenu: |
| Removes the menu from the list of managed menus. More... | |
| (void) | - removeObjectForKey: |
| Remove an object from the container. More... | |
| (void) | - removeObjectsForKeys: |
| Remove multiple objects from the container. More... | |
| (void) | - renameCategory:to: |
| Change a category's name. More... | |
| (void) | - renameKey:to: |
| Renames an object's key throughout. More... | |
| (BOOL) | - replaceContentsWithData: |
| Discard all existing content, then reload from the archive data passed. More... | |
| (NSArray *) | - reservedCategories |
| Get a list of reserved categories - those that should not be deleted or renamed. More... | |
| (void) | - setRecentList:maxItems: |
| Sets the maximum length of on eof the 'recent' lists. More... | |
| (void) | - setRecentlyAddedItems: |
| Replaces the recently added items with new items, up to the current max. More... | |
| (void) | - setRecentlyAddedListEnabled: |
| Set whether the "recent;y added" list accepts new items or not. More... | |
| (void) | - updateMenusForKey: |
| Synchronises the menus to reflect any change of the object referenced by <key> More... | |
 Instance Methods inherited from NSObject | |
| (NSString *) | - address |
| (DKStyleRegistry *) | - applicationWillReturnStyleRegistry |
| (BOOL) | - canBeUsedWithSelectionTool |
| (id) | - categoryManager:shouldReplaceObject:withObject: |
| (Class) | - classForCoder |
| (NSColor *) | - colorValue |
| (NSColor *) | - colourValue |
| (id) | - copy |
| (void) | - dealloc |
| (id) | - deepCopy |
| (NSDictionary *) | - dimensionValuesForArrowStroke: |
| (CGFloat) | - drawing:convertDistanceToExternalCoordinates: |
| (NSPoint) | - drawing:convertLocationToExternalCoordinates: |
| (void) | - drawing:didDrawRect:inView: |
| (void) | - drawing:willDrawRect:inView: |
| (NSString *) | - drawing:willReturnAbbreviationForUnit: |
| (NSString *) | - drawing:willReturnFormattedCoordinateForDistance: |
| (CGFloat) | - drawingWillReturnUnitToPointsConversonFactor: |
| (void) | - finalize |
| (NSString *) | - hexString |
| (void) | - hotspot:didEndTrackingWithEvent:inView: |
| (void) | - hotspot:isTrackingWithEvent:inView: |
| (void) | - hotspot:willBeginTrackingWithEvent:inView: |
| (NSData *) | - imageData |
| (NSImage *) | - imageResourceNamed: |
| (id) | - init |
| (id) | - initWithExpression: |
| (id) | - instantiateObjectWithShortName:parameters: |
| (BOOL) | - isLiteralValue |
| (void) | - layoutManager:willPlaceGlyphAtIndex:atLocation:pathAngle:yOffset: |
| (void) | - menuItem:wasAddedForObject:inCategory: |
| (BOOL) | - moveObjectTo:position:slope:userInfo: |
| (id) | - mutableCopy |
| (void) | - oneShotComplete |
| (void) | - oneShotHasReached: |
| (void) | - oneShotWillBegin |
| (void) | - path:elementIndex:type:points:subPathIndex:subPathClosed:contextInfo: |
| (id) | - placeLinkFromPoint:toPoint:onPath:linkNumber:userInfo: |
| (id) | - placeObjectAtPoint:onPath:position:slope:userInfo: |
| (NSPoint) | - point |
| (NSPoint) | - pointForTextLayout |
| (DKStyle *) | - registry:shouldReplaceStyle:withStyle: |
| (NSBezierPath *) | - renderer:willRenderPath: |
| (void) | - routeFinder:progressHasReached: |
| (void) | - setValue:forNumericParameter: |
| (NSString *) | - stringValue |
| (CGFloat) | - taperFactorAtDistance:onPath:ofLength: |
| (void) | - toolDidPerformUndoableAction: |
| (void) | - toolWillPerformUndoableAction: |
| (NSURL *) | - url |
| Instance Methods inherited from <NSObject> | |
| (NSString *) | - description |
| (NSUInteger) | - hash |
| (BOOL) | - isEqual: |
| Instance Methods inherited from <NSKeyValueBindingCreation> | |
| (void) | - bind:toObject:withKeyPath:options: |
| (NSArray *) | - exposedBindings |
| (NSDictionary *) | - infoForBinding: |
| (NSArray *) | - optionDescriptionsForBinding: |
| (void) | - unbind: |
| (Class) | - valueClassForBinding: |
| Instance Methods inherited from <NSCoding> | |
| (void) | - encodeWithCoder: |
| (id) | - initWithCoder: |
| Instance Methods inherited from <NSCopying> | |
| (id) | - copyWithZone: |
Class Methods | |
| (DKCategoryManager *) | + categoryManager |
| Returns a new category manager object. More... | |
| (NSString *) | + categoryManagerKeyForObject: |
| Given an object, return a key that can be used to store it in the category manager. More... | |
| (DKCategoryManager *) | + categoryManagerWithDictionary: |
| Returns a new category manager object based on an existing dictionary. More... | |
| (id) | + dearchivingHelper |
| (NSArray *) | + defaultCategories |
| Return the default categories defined for this class. More... | |
| (void) | + setDearchivingHelper: |
| Class Methods inherited from NSObject | |
| (id) | + alloc |
| (Class) | + class |
| (void) | + initialize |
| (void) | + load |
| (id) | + new |
| Class Methods inherited from <NSKeyValueBindingCreation> | |
| (void) | + exposeBinding: |
The cat manager supports a UI based on menu(s).
The cat manager supports a UI based on menu(s). To assist, the DKCategoryManagerMenuInfo class is used to "own" a menu - the cat manager keeps a list of these.
When the CM is asked for a menu, this helper object is used to create and manage it. As the CM is used (items and categories added/removed) the menu helpers are informed of the changes and in turn update the menus to match by adding or deleting menu items. This is necessary because when the CM grows to a significant number of items, rebuilding the menus is very time-consuming. This way performance is much better.
| - (void) addCategories: | (NSArray *) | catNames |
Create a new categories with the given names.
| catNames | a list of the names of the new categories |
| - (void) addCategory: | (NSString *) | catName |
Create a new category with the given name.
If the name is already a category name, this does nothing
| catName | the name of the new category |
| - (void) addDefaultCategories |
Add the default categories defined for this class or object.
Is called as part of the initialisation of the CM object
Adds a new key to several categories, optionally creating any if necessary.
| key | the key to add |
| catNames | a list of categories to add it to |
| cg | YES to create the category if it doesn't exist, NO otherwise |
Adds a new key to a category, optionally creating it if necessary.
| key | the key to add |
| catName | the category to add it to |
| cg | YES to create the category if it doesn't exist, NO otherwise |
Add a key to one of the 'recent' lists.
Acceptable list IDs are kDKListRecentlyAdded and kDKListRecentlyUsed
| key | the key to add |
| whichList | an identifier for the list in question |
| - (void) addObject: | (id) | obj | |
| forKey: | (NSString *) | name | |
| toCategories: | (NSArray *) | catNames | |
| createCategories: | (BOOL) | cg | |
Add an object to the container, associating with a key and optionally a number of categories.
<obj> and <name> cannot be nil. All objects are added to the default category regardless of <catNames>
| obj | the object to add |
| name | the object's key |
| catNames | the names of the categories to add it to, or nil for defaults |
| cg | YES to create the categories if they don't exist. NO not to do so |
| - (void) addObject: | (id) | obj | |
| forKey: | (NSString *) | name | |
| toCategory: | (NSString *) | catName | |
| createCategory: | (BOOL) | cg | |
Add an object to the container, associating with a key and optionally a category.
<obj> and <name> cannot be nil. All objects are added to the default category regardless of <catName>
| obj | the object to add |
| name | the object's key |
| catName | the name of the category to add it to, or nil for defaults only |
| cg | YES to create the category if it doesn't exist. NO not to do so |
| - (NSArray*) allCategories |
Get a list of all categories.
The list is alphabetically sorted for the convenience of a user interface
| - (NSArray*) allKeys |
Return all of the keys in all given categories.
Returned objects are in no particular order.
| catNames | an array of category names |
Return all of the keys in a given category.
Returned objects are in no particular order. This also treats the "recently used" and "recently added" items as pseudo-category names, returning these arrays if the catName matches.
| catName | the category name |
Returned objects are in no particular order. The keys are obtained by enumerating the categories because the master list contains case-modified keys that may not be matched with categories.
| - (NSArray*) allObjects |
Return all of the objects.
Return all of the keys in a given category, sorted into some useful order.
By default the keys are sorted alphabetically. The UI-building methods call this, so a subclass can override it and return keys sorted by some other criteria if required.
| catName | the category name |
Return all of the names in a given category, sorted into some useful order.
For an ordinary DKCategoryManager, names == keys. However, subclasses may store keys in some other fashion (hint: they do) and so another method is needed to convert keys to names. Those subclasses must override this and do what's appropriate.
| catName | the category name |
Retain all existing content, and load additional content from the archive data passed.
Because at this level DKCategoryManager has no knowledge of the objects it is storing, it has no means to be smart about merging objects that are the same in some higher abstract way. Thus it's entirely possible to end up with multiple copies of the "same" object after this operation. Subclasses may prefer to do something smarter. Note however that duplicate categories are not created.
| data | data, being an archive earlier obtained using -data |
Get a list of all categories that contain a given key.
The list is alphabetically sorted for the convenience of a user interface
| key | the key in question |
| - (NSArray*) categoriesContainingKey: | (NSString *) | key | |
| withSorting: | (BOOL) | sortIt | |
Creates a menu of categories, recent items and All Items.
Sel and target may be nil
| sel | the selector which is set as the action for each added item |
| target | the target of category item actions |
Creates a menu of categories, recent items and All Items.
Sel and target may be nil, options may be 0
| sel | the selector which is set as the action for each category item |
| target | the target of category item actions |
| options | various flags which set which items are added |
Test whether there is a category of the given name.
| catName | the category name |
| + (DKCategoryManager*) categoryManager |
Returns a new category manager object.
Convenience method. Initial categories only consist of "All Items"
Given an object, return a key that can be used to store it in the category manager.
Subclasses will need to define this differently - used for merging.
| obj | an object |
| + (DKCategoryManager*) categoryManagerWithDictionary: | (NSDictionary *) | dict |
Returns a new category manager object based on an existing dictionary.
Convenience method. Initial categories only consist of "All Items"
| dict | an existign dictionary |
| - (void) checkItemsInMenu: | (NSMenu *) | menu | |
| forCategoriesContainingKey: | (NSString *) | key | |
Sets the checkmarks in a menu of category names to reflect the presence of <key> in those categories.
Assumes that item names will be the category names. For localized names, you should handle the localization external to this class so that both category names and menu items use the same strings.
| menu | the menu to examine |
| key | the key to test against |
| - (void) copyItemsFromCategoryManager: | (DKCategoryManager *) | cm |
Retain all existing content, and load additional content from the cat manager passed.
Categories not present in the receiver but exist in <cm> are created, and objects present in <cm> are added to the receiver if not already present (as determined solely by address). This method disables the "recently added" list while it adds the items.
| cm | a category manager object |
| - (NSUInteger) count |
Return total number of stored objects in container.
| - (NSUInteger) countOfCategories |
Get the count of all categories.
| - (NSUInteger) countOfObjectsInCategory: | (NSString *) | catName |
Count how many objects in the category of the given name.
| catName | the category name |
Creates a complete menu of the entire contents of the receiver, arranged by category.
The menu returned lists the categories, each of which is a submenu containing the actual objects corresponding to the category contents. It also populates a recent items and added items submenu. the callback object needs to set up the menu item based on the object itself. The object is added automatically as the menu item's represented object. This is one easy way to create a simple UI to the cat manager, where you can simply pick an item from the menu. Note that the returned menu is fully managed - as objects are added and removed the menu will be directly managed to keep in synch. Thus the client code does not need to bother doing this just to keep the menus up to date. The menu updating is done very efficiently for performance. If the content of a menu item needs to change, call -updateMenusForKey: for the object key in question. When the client is dealloc'd, it should call -removeMenu: for any menus it obtained using this, so that stale references to the callback object are cleared out.
| id | an object that is called back with each menu item created (may be nil) |
| isPopUp | set YES if menu is destined for use as a popup (adds extra zeroth item) |
| - (NSMenu*) createMenuWithItemDelegate: | (id) | del | |
| itemTarget: | (id) | target | |
| itemAction: | (SEL) | action | |
| options: | (DKCategoryMenuOptions) | options | |
| - (NSMenu*) createMenuWithItemDelegate: | (id) | del | |
| options: | (DKCategoryMenuOptions) | options | |
| - (NSData*) data |
Archives the container to a data object (for saving, etc)
| - (NSData*) dataWithFormat: | (NSPropertyListFormat) | format |
| + (id) dearchivingHelper |
| - (NSArray*) defaultCategories |
Return the default categories defined for this class or object.
| + (NSArray*) defaultCategories |
Return the default categories defined for this class.
| - (NSDictionary*) dictionary |
Return a copy of the master dictionary.
| - (NSString*) fileType |
Return the filetype (for saving, etc)
Subclasses should override to change the filetype used for specific examples of this object
| - (void) fixUpCategories |
Checks that all keys refer to real objects, removing any that do not.
Rarely needed, but can correct for corrupted registries where objects got removed but not all keys that refer to it did for some reason (such as an exception).
Initialized a category manager object from archive data.
Data is permitted also to be an archived dictionary
| data | data containing a correctly archived category manager |
| - (id) initWithDictionary: | (NSDictionary *) | dict |
Initialized a category manager object from an existing dictionary.
No categories other than "All Items" are created by default. The recently added list is empty.
| dict | dictionary containing a set of objects and keys |
Query whether a given key is present in a particular category.
| key | the key |
| catName | the category name |
Returns a list of all unique keys that refer to the given object.
The result may contain no keys if the object is unknown
| obj | the object |
Asks delegate to make decision about the merging of an object.
Subclasses must override this to make use of it. Returning nil means use existing object.
| obj | the object to consider |
| aDelegate | the delegate to ask |
| - (NSSet*) mergeObjectsFromSet: | (NSSet *) | aSet | |
| inCategories: | (NSArray *) | categories | |
| mergeOptions: | (DKCatManagerMergeOptions) | options | |
| mergeDelegate: | (id) | aDelegate | |
Smartly merges objects into the category manager.
| aSet | a set of objects of the same kind as the current contents |
| categories | an optional list of categories to add th eobjects to. Categories will be created if needed. |
| options | replacxement options. Delegate may override these. |
| adelegate | an optional delegate that can be asked to make decisions about which objects get replaced. |
Return the object for the given key, but do not remember it in the "recently used" list.
| key | the object's key |
| - (id) objectForKey: | (NSString *) | key | |
| addToRecentlyUsedItems: | (BOOL) | add | |
Return the object for the given key, optionally remembering it in the "recently used" list.
Use this method when you wish this access of the object to result in it being added to "recently used"
| key | the object's key |
| add | if YES, object's key is added to recently used items |
Return all of the objects belonging to the given categories.
Returned objects are in no particular order, but do match the key order obtained by -allKeysInCategories:. Should any key not exist (which should never normally occur), the entry will be represented by a NSNull object
| catNames | list of categories |
Return all of the objects belonging to a given category.
Returned objects are in no particular order, but do match the key order obtained by -allkeysInCategory. Should any key not exist (which should never normally occur), the entry will be represented by a NSNull object
| catName | the category name |
| - (NSArray*) recentlyAddedItems |
Return the list of recently added items.
Returned objects are in order of addition, most recent first.
| - (NSArray*) recentlyUsedItems |
Return the list of recently used items.
Returned objects are in order of use, most recent first.
| - (void) removeAllCategories |
Removes all categories and objects from the CM.
After this the CM is entirely empty.
| - (void) removeAllObjects |
Removes all objects from the container.
Does not remove the categories, but leaves them all empty.
| - (void) removeCategory: | (NSString *) | catName |
Remove a category with the given name.
The objects listed in the category are not removed, as they may also be listed by other categories. If they are not, they can become orphaned however. To avoid this, never delete the "All Items" category.
| catName | the category to remove |
Removes a key from a number of categories.
| key | the key to remove |
| catNames | the list of categories to remove it from |
Removes a key from a category.
| key | the key to remove |
| catName | the category to remove it from |
Remove a key from one of the 'recent' lists.
Acceptable list IDs are kDKListRecentlyAdded and kDKListRecentlyUsed
| key | the key to remove |
| whichList | an identifier for the list in question |
| - (void) removeKeyFromAllCategories: | (NSString *) | key |
Removes a key from all categories.
| key | the key to remove |
| - (void) removeMenu: | (NSMenu *) | menu |
Removes the menu from the list of managed menus.
An object using a menu created by the category manager must remove it from management when it is no longer needed as a stale reference can cause a crash.
| menu | a menu managed by this object |
| - (void) removeObjectForKey: | (NSString *) | key |
Remove an object from the container.
After this the key will not be found in any category or either list
| key | the object's key |
| - (void) removeObjectsForKeys: | (NSArray *) | keys |
Remove multiple objects from the container.
After this no keys will not be found in any category or either list
| keys | a list of keys |
Change a category's name.
If <newname> already exists, it will be replaced by the entries in <catname>
| catName | the category's old name |
| newname | the category's new name |
Renames an object's key throughout.
If <key> doesn't exist, or if <newkey> already exists, throws an exception. After this the same object that could be located using <key> can be located using <newKey> in the same categories as it appeared in originally.
| key | the existing key |
| newKey | the new key |
Discard all existing content, then reload from the archive data passed.
| data | data, being an archive earlier obtained using -data |
| - (NSArray*) reservedCategories |
Get a list of reserved categories - those that should not be deleted or renamed.
This list is advisory - a UI is responsible for honouring it, the cat manager itself ignores it. The default implementation returns the same as the default categories, thus reserving all default cats. Subclasses can change this as they wish.
| + (void) setDearchivingHelper: | (id) | helper |
| - (void) setRecentList: | (NSInteger) | whichList | |
| maxItems: | (NSUInteger) | max | |
Sets the maximum length of on eof the 'recent' lists.
Acceptable list IDs are kDKListRecentlyAdded and kDKListRecentlyUsed
| whichList | an identifier for the list in question |
| max | the maximum length to which a list may grow |
| - (void) setRecentlyAddedItems: | (NSArray *) | array |
Replaces the recently added items with new items, up to the current max.
| array | an array of suitable objects |
| - (void) setRecentlyAddedListEnabled: | (BOOL) | enable |
Set whether the "recent;y added" list accepts new items or not.
This allows the recently added items to be temporarily disabled when bulk adding items to the manager. By default the recently added items list is enabled.
| enable | YES to allow new items to be added, NO otherwise |
| - (void) updateMenusForKey: | (NSString *) | key |
Synchronises the menus to reflect any change of the object referenced by <key>
Any change to a stored object that affects the menus' appearance can be handled by calling this. this only changes the menu items that represent the object, and not the entire menu, so is an efficient way to keep menus up to date with changes.
| key | an object's key |
1.8.9.1
