Metadata¶

Every drawable object in Drawkit supports the attachment of arbitrary metadata (also known as “user data”). Typically this metadata will be in the form of an NSDictionary, allowing you to store any data you like with a given key, attached to a drawable object. While the metadata object is defined as type id, meaning you can attach anything you like, Drawkit itself does pre-attach some metadata to some objects and it always does so using an NSDictionary, so for maximal compatibility, it is best to do the same - and in fact using a dictionary has numerous advantages. An object’s metadata is saved with it in a file, and in general always remains attached and available unless you go out of your way to prevent this.

Some rasterizers are able to lookup metadata values using a key (thus assuming that metadata is indeed stored in a dictionary). For example, both DKTextAdornment and DKImageAdornment rasterizers are able to look at the object’s metadata for specific keyed values (in the first case string data, in the second, images). This feature permits you to define generic styles that nevertheless are able to display data differently for each object they are attached to even when the style is shared. Taking this one step further, these rasterizers (or indeed any client code of the metadata APIs) is able to introspect an object itself using Cocoa’s KVC mechanism. To do this, the identifier (key) for a metadata item is prefixed with a ‘$’ symbol. When the API sees this prefix, it knows to strip it off and use the remainder of the identifier as a keypath to a direct property of the object. So for example an object can display its own location using an identifier of $location.

To ensure that DKTextAdornment can work with many different possible object values, DrawKit implements -stringValue for many common objects including NSArray, NSSet, NSDictionary, etc. This is very similar in concept to Cocoa’s -description method, but formats the result more usefully for user-oriented (rather than programmer-oriented) display. NSObject implements -stringValue to returns its class as a string, so every object will return something displayable.

Some drawables, in particular DKImageShape, may set some metadata items when they are initialised. These pertain to the original path, filename and dimesions of the image used to initialise the object (if these values can indeed be determined). Clients can make use of these metadata values as they wish, or ignore them. Another object that can set metadata is DKTextShape, when it is converted to another kind of drawable. The original text is saved as a metadata item which could permit application code to still find such objects using a text search even though the text is now rendered purely as a graphic.

Build-in metadata items are defined for the following keys: [missing list - ed]