DrawKit
Vector and illustration framework for Mac OS X
|
The style registry is a singleton category manager instance that consolidates styles from a variety of sources into a single app-wide "database" of styles, organised into categories. More...
Instance Methods | |
(NSMenu *) | - managedStylesMenuWithItemTarget:itemAction: |
Creates a new fully managed menu that lists all the styles, organised into categories. More... | |
(DKStyle *) | - mergeFromStyle:mergeDelegate: |
(BOOL) | - readFromFile:mergeOptions:mergeDelegate: |
Merge the contents of a file into the registry. More... | |
(void) | - removeAllStyles |
Set the registry empty. More... | |
(void) | - setNeedsUIUpdate |
(void) | - styleDidChange: |
(DKStyle *) | - styleForKey: |
(NSString *) | - styleNameForKey: |
Return the style's name given its key. More... | |
(NSArray *) | - styleNames |
Return a list of all the registered styles' names, in alphabetical order. More... | |
(NSArray *) | - styleNamesInCategory: |
Return a list of the registered styles' names in the category, in alphabetical order. More... | |
(NSSet *) | - stylesInCategories: |
Return the set of styles in the given categories. More... | |
(NSString *) | - uniqueNameForName: |
Return a modified name to resolve a collision with names already in use. More... | |
(BOOL) | - writeToFile:atomically: |
Write the registry to a file. More... | |
Instance Methods inherited from DKCategoryManager | |
(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 | |
(NSDictionary *) | + compareStylesInSet: |
Preflight a set of styles against the registry for a possible future merge operation. More... | |
(void) | + loadDefaults |
Loads the registry from the current user defaults. More... | |
(NSMenu *) | + managedStylesMenuWithItemTarget:itemAction: |
(NSSet *) | + mergeStyles:inCategories:options:mergeDelegate: |
Merge a set of styles with the registry. More... | |
(NSArray *) | + registeredStyleKeys |
Return the entire list of keys of the styles in the registry. More... | |
(NSData *) | + registeredStylesData |
Return data that can be saved to a file, etc. More... | |
(void) | + registerSolidColourFillsFromListNamed:asCategory: |
Creates a series of fill styles having the solid colours given by the named NSColorList, and adds them to the registry using the named category. More... | |
(void) | + registerSolidColourStrokesFromListNamed:asCategory: |
Creates a series of stroke styles having the solid colours given by the named NSColorList, and adds them to the registry using the named category. More... | |
(void) | + registerStyle: |
Register the style with the registry. More... | |
(void) | + registerStyle:inCategories: |
Register the style with the registry. More... | |
(void) | + registerStylesFromArray:inCategories: |
Register a list of styles with the registry. More... | |
(void) | + registerStylesFromArray:inCategories:ignoringDuplicateNames: |
Register a list of styles with the registry. More... | |
(void) | + resetRegistry |
Reset the registry back to a "first run" condition. More... | |
(void) | + saveDefaults |
Saves the registry to the current user defaults. More... | |
(void) | + setNeedsUIUpdate |
Send a notification that the contents of the registry has changed so any UI displaying it should be updated. More... | |
(void) | + setShouldNotAddDKDefaultCategory: |
Sets whether DK defaults category containing the default styles shoul dbe registered when the registry is built or reset. More... | |
(void) | + setStyleNotificationsEnabled: |
(DKStyleRegistry *) | + sharedStyleRegistry |
Return the single global style registry object. More... | |
(DKStyle *) | + styleForKey: |
Return the style registerd with the given key. More... | |
(DKStyle *) | + styleForKeyAddingToRecentlyUsed: |
Return the style registerd with the given key. More... | |
(void) | + unregisterStyle: |
Remove the style from the registry. More... | |
Class Methods inherited from DKCategoryManager | |
(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 style registry is a singleton category manager instance that consolidates styles from a variety of sources into a single app-wide "database" of styles, organised into categories.
Styles can come from these sources:
A. It permits the construction of a UI for accessing pre-built styles and applying them to objects in a drawing. By organising styles into categories, potentially large number of styles may be managed effectively.
B. It tracks styles across any number of documents as they are created. For example if a document uses a particular registered style, when that document is reopened at a later date, the style can be recognised and linked to the same style in the registry. If the style has changed in the meantime so that there is a difference between the saved style and the currently registered version, the user can be offered the option to update the style in the document to match the registry, update the registry to match the document, or to re-register the style as a new version.
Note the registry is not mandatory - an app using DK can use styles without registering them if it wishes. The advantage of the registry is that it permits styles to persist and be tracked across multiple documents, saving the user from having to redefine styles for every new graphic.
In order for the registry to uniquely and positively identify a style, its unique ID is used as its key. The unique ID is assigned when the style first comes into existence and cannot be changed. It is a string representation of a UUID so is guaranteed unique.
UUID's are not very user friendly and should never be exposed by an application's user interface. Thus a style also has an ordinary descriptive name which can be displayed in the UI. Such names are not guaranteed to be unique however, as the user is free to enter whatever name they wish. When a style is first registered the name may be changed to avoid a collision with an already registered style having the same name - this is done by appending 1, 2, 3 etc until the name doesn't collide. However this is just done to disambiguate the style for the user - it is not intended to guarantee uniqueness so that the name can be used as a key to the object.
A user interface will want to use the ordinary names, but internally must be set up to use the unique ID or the object itself to avoid any confusion as to which style is actually being referred to. For example a menu of available styles could use the UUID or the object as the represented object of the menu item. DO NOT USE THE ORDINARY NAME AS A KEY.
Locking. Styles in the registry are usually locked. This is to prevent accidental alteration of a style that may be being used across many documents. When a style is added to the registry, it should be unlocked (because the name might need to be automatically changed) but the registry will lock the style upon a successful operation.
Styles in a document. Styles used in a document may or may not be registered. A user may never register a style, but still have many styles defined in a document. Such styles work normally and can be copied and pasted and shared between objects if set to do so - use of styles is not dependent in any way upon the registry. When the document is saved, a flag as to whether the style was registered or not is saved with it. When the document is opened again later, such flagged styles will be optionally reconnected to the style registry so that the actual style used is always the registered style, so if the style is updated, existing documents are offered the opportunity to use the updated version.
As well as any user-defined categories, documents may wish to create a temporary category using the document's name which gives the user a way to quickly discover the complete set of registered styles used in a document. The category should be removed when the document is closed. DKDrawDocument implements this behaviour by default, so if your document class is based on it, your app can get this feature for free.
Registering a style. The style registry performs the following steps:
Cut/Paste: cut and paste of styles works independently of the registry, including dealing with shared styles. See DKStyle for more info.
+ (NSDictionary*) compareStylesInSet: | (NSSet *) | styles |
Preflight a set of styles against the registry for a possible future merge operation.
This is a way to test a set of styles against the registry prior to a merge operation (preflight). It compares each style in the set with the current registry, and returns a dictionary keyed off the style's unique key. The values in the dictionary are NSNumbers indicating whether the style is older, the same, newer or unknown. The caller can use this info to make decisions about a merge before doing it, if they wish, or to present the info to the user.
styles | a set of styles |
+ (void) loadDefaults |
Loads the registry from the current user defaults.
If used, this should be called early in the application launch sequence
Creates a new fully managed menu that lists all the styles, organised into categories.
The returned menu is fully managed, that is, the Style Registry keeps it in synch with all changes to the registry and to the styles themselves. The menu can be assigned to UI controls such as a represented object is the style, and the item shows a swatch and the style's name. The menus are ordered alphabetically. This is intended as a very high-level method to support the most common usage. If you need to pass different options or wish to handle each item differently, DKCategoryManager has more flexible methods that expose more detail.
target | the target object assigned to each menu item |
selector | the action sent by each menu item |
+ (NSSet*) mergeStyles: | (NSSet *) | styles | |
inCategories: | (NSArray *) | styleCategories | |
options: | (DKStyleMergeOptions) | options | |
mergeDelegate: | (id) | aDel | |
Merge a set of styles with the registry.
This method is for merging sets of styles read in with a document or file. The document will have already sorted the loaded styles into those which were formerly registered and those which were not
styles | a set of one or more styles |
styleCategories | a list of categories to add the styles to if they are added (one or more NSStrings) |
options | control flags for changing the preferred direction of merging, etc. |
aDel | an optional delegate object that can make a merge decision for each individual style object |
- (BOOL) readFromFile: | (NSString *) | path | |
mergeOptions: | (DKStyleMergeOptions) | options | |
mergeDelegate: | (id) | aDel | |
Merge the contents of a file into the registry.
Reads styles from the file at <path> into the registry. Styles are merged as indicated by the options, etc. The intention of this method is to load a file containing styles only - either to augment or replace the existing registry. It is not used when opening a drawing document. If the intention is to replace the reg, the caller should clear out the current one before calling this.
path | the full path of the file to write |
options | merging options |
aDel | an optional delegate object that can make a merge decision for each individual style object |
+ (NSArray*) registeredStyleKeys |
Return the entire list of keys of the styles in the registry.
+ (NSData*) registeredStylesData |
Return data that can be saved to a file, etc.
representing the registry
Creates a series of fill styles having the solid colours given by the named NSColorList, and adds them to the registry using the named category.
The named color list must exist - see [NSColorList availableColorLists];
name | the name of a NSColorList |
catName | the name of the registry category - if nil, use the colorList name |
+ (void) registerSolidColourStrokesFromListNamed: | (NSString *) | name | |
asCategory: | (NSString *) | catName | |
Creates a series of stroke styles having the solid colours given by the named NSColorList, and adds them to the registry using the named category.
The named color list must exist - see [NSColorList availableColorLists];
name | the name of a NSColorList |
catName | the name of the registry category - if nil, use the colorList name |
+ (void) registerStyle: | (DKStyle *) | aStyle |
Register the style with the registry.
This method registers styles in the "All User Styles" category only. If the style is already registered this does nothing. Registering a style locks it as a side effect (safety feature). The styles is registered using the value returned by its -uniqueKey method, which is set once for all time when the style is initialized. In general you should not interpret or display these keys. If the style's name is the same as another registered style's name, this style' name is changed by appending digits until the name collision is resolved. However the name is not the key and shouldn't be used as one.
aStyle | the style to register |
+ (void) registerStyle: | (DKStyle *) | aStyle | |
inCategories: | (NSArray *) | styleCategories | |
Register the style with the registry.
See notes for registerStyle: if the categories do not exist they are created.
aStyle | the style to register |
styleCategories | a list of one or more categories to list the style in (list of NSStrings) |
Register a list of styles with the registry.
See notes for registerStyle: if the categories do not exist they are created.
styles | an array of DKStyle objects to register |
styleCategories | a list of one or more categories to list the style in (list of NSStrings) |
+ (void) registerStylesFromArray: | (NSArray *) | styles | |
inCategories: | (NSArray *) | styleCategories | |
ignoringDuplicateNames: | (BOOL) | ignoreDupes | |
Register a list of styles with the registry.
See notes for registerStyle: if the categories do not exist they are created. Note that the "recently added" list is temporarily disabled by this method, reflecting the intention that it is used for pre-registering a number of styles in bulk.
styles | an array of DKStyle objects to register |
styleCategories | a list of one or more categories to list the style in (list of NSStrings) |
ignoreDupes | if YES, styles whose names are already known are skipped. |
- (void) removeAllStyles |
Set the registry empty.
Removes all styles from the registry, clears the "recently added" and "recently used" lists, and removes all categories except the default category.
+ (void) resetRegistry |
Reset the registry back to a "first run" condition.
This removes ALL styles from the registry, thereby unregistering them. It then starts over with the DK defaults. This puts the registry into the same state that it was in on the very first run of the client app, when there are no saved defaults. This method should be used carefully - the caller may want to confirm the action beforehand with the user.
+ (void) saveDefaults |
Saves the registry to the current user defaults.
- (void) setNeedsUIUpdate |
+ (void) setNeedsUIUpdate |
Send a notification that the contents of the registry has changed so any UI displaying it should be updated.
The notification's object is the shared style registry
+ (void) setShouldNotAddDKDefaultCategory: | (BOOL) | noDKDefaults |
Sets whether DK defaults category containing the default styles shoul dbe registered when the registry is built or reset.
See +resetRgistry
noDKDefaults | YES to turn OFF the defaults |
+ (void) setStyleNotificationsEnabled: | (BOOL) | enable |
+ (DKStyleRegistry*) sharedStyleRegistry |
Return the single global style registry object.
A style registry isn't a true singleton but in general there would probably be never any reason to create another instance. Other class methods implictly reference the registry returned by this.
- (void) styleDidChange: | (NSNotification *) | note |
Return the style registerd with the given key.
Styles returned by this method are not added to the "recently used" items list
styleID | the unique key of the style. Styles return his value from - uniqueKey. |
Return the style registerd with the given key.
Styles returned by this method are added to the "recently used" items list - usually you will use this method when applying a registered style to an object in a real app so that you can make use of the "recently used" list
styleID | the unique key of the style. Styles return his value from - uniqueKey. |
Return the style's name given its key.
The name can be used in a user interface, but the key should not. This gives you an easy way to get one from the other if you don't have the style object itself. If the key is unknown to the registry, nil is returned.
styleID | the style's key |
- (NSArray*) styleNames |
Return a list of all the registered styles' names, in alphabetical order.
Return a list of the registered styles' names in the category, in alphabetical order.
catName | the name of a single category |
Return the set of styles in the given categories.
Being a set, the result is unordered. The result may be the empty set if the categories are unknown or empty, and may contain NSNull objects if the style registry is in a state where objects have been removed and the category lists not updated (in normal use this should not occur).
cats | a list of one or more categories |
Return a modified name to resolve a collision with names already in use.
Names of styles are changed when a style is registerd to avoid a collision with any already registered styles. Names are not keys and this doesn't guarantee uniqueness - it's merely a courtesy to the user.
name | a candidate name |
+ (void) unregisterStyle: | (DKStyle *) | aStyle |
Remove the style from the registry.
Removed styles are still retained by an objects using them, so they are not dealloced unless not in use by any clients at all.
aStyle | the style to remove |