|
DrawKit
Vector and illustration framework for Mac OS X
|
Instance Methods | |
| (NSArray *) | - bezierPathsWithGlyphsOnPath:yOffset: |
| Returns a list of paths each containing one glyph from the original text. More... | |
| (NSBezierPath *) | - bezierPathWithObjectsOnPathAtInterval:factoryObject:userInfo: |
| Places objects at regular intervals along the path. More... | |
| (NSBezierPath *) | - bezierPathWithPath:atInterval: |
| Places copies of a given path at regular intervals along the path. More... | |
| (NSBezierPath *) | - bezierPathWithPath:atInterval:phase:alternate:taperDelegate: |
| Places copies of a given path at regular intervals along the path. More... | |
| (NSBezierPath *) | - bezierPathWithStringOnPath: |
| Returns a single path consisting of all of the laid out glyphs of the text. More... | |
| (NSBezierPath *) | - bezierPathWithStringOnPath:attributes: |
| Returns a single path consisting of all of the laid out glyphs of the text. More... | |
| (NSBezierPath *) | - bezierPathWithTextOnPath:yOffset: |
| Returns a single path consisting of all of the laid out glyphs of the text. More... | |
| (NSArray *) | - descenderBreaksForString:range:underlineOffset: |
| Determines the positions of any descender breaks for drawing underlines. More... | |
| (void) | - drawStrikethroughPathForLayoutManager:range:yOffset:cache: |
| Low level method draws the strikethrough attributes for ranges of text. More... | |
| (void) | - drawStrikethroughPathForLayoutManager:yOffset:cache: |
| Low level method draws the strikethrough attributes for the text if necessary. More... | |
| (BOOL) | - drawStringOnPath: |
| Renders a string on a path. More... | |
| (BOOL) | - drawStringOnPath:attributes: |
| Renders a string on a path. More... | |
| (BOOL) | - drawTextOnPath:yOffset: |
| Renders a string on a path. More... | |
| (BOOL) | - drawTextOnPath:yOffset:layoutManager:cache: |
| Renders a string on a path. More... | |
| (void) | - drawUnderlinePathForLayoutManager:range:yOffset:cache: |
| Low level method draws the undeline attributes for ranges of text. More... | |
| (void) | - drawUnderlinePathForLayoutManager:yOffset:cache: |
| Low level method draws the underline attributes for the text if necessary. More... | |
| (NSArray *) | - intersectingPointsWithHorizontalLineAtY: |
| Find the points where a line drawn horizontally across the path will intersect it. More... | |
| (void) | - kernText:toFitLength: |
| Low level method adjusts text to fit the path length. More... | |
| (BOOL) | - layoutStringOnPath:yOffset:usingLayoutHelper:layoutManager:cache: |
| Low level method performs all text on path layout. More... | |
| (NSRect) | - lineFragmentRectForProposedRect:remainingRect: |
| Find a line fragement rectange for laying out text in this shape. More... | |
| (NSRect) | - lineFragmentRectForProposedRect:remainingRect:datumOffset: |
| Find a line fragement rectange for laying out text in this shape. More... | |
| (NSArray *) | - lineFragmentRectsForFixedLineheight: |
| Find rectangles within which text can be laid out to place the text within the path. More... | |
| (void) | - moveObject:atSpeed:loop:userInfo: |
| Moves an object along the path at a constant speed. More... | |
| (void) | - pathPosition:andLength:forCharactersOfString:inRange: |
| Calculates the start and end locations of ranges of text on the path. More... | |
| (NSArray *) | - placeLinksOnPathWithEvenLinkLength:oddLinkLength:factoryObject:userInfo: |
| Places "links" along the path at alternating even and odd intervals. More... | |
| (NSArray *) | - placeLinksOnPathWithLinkLength:factoryObject:userInfo: |
| Places "links" along the path at equal intervals. More... | |
| (NSArray *) | - placeObjectsOnPathAtInterval:factoryObject:userInfo: |
| Places objects at regular intervals along the path. More... | |
| (NSTextStorage *) | - preadjustedTextStorageWithString:layoutManager: |
| Low level method adjusts justified text to fit the path length. More... | |
| (NSBezierPath *) | - textLinePathWithMask:startPosition:length:offset:lineThickness:descenderBreaks:grotThreshold: |
| Converts all the information about an underline into a path that can be drawn. More... | |
Class Methods | |
| (void) | + setTextOnPathDefaultAttributes: |
| Sets the attributes used to draw strings on paths. More... | |
| (NSDictionary *) | + textOnPathDefaultAttributes |
| Returns the attributes used to draw strings on paths. More... | |
| (NSLayoutManager *) | + textOnPathLayoutManager |
| Returns a layout manager used for text on path layout. More... | |
| - (NSArray*) bezierPathsWithGlyphsOnPath: | (NSAttributedString *) | str | |
| yOffset: | (CGFloat) | dy | |
Returns a list of paths each containing one glyph from the original text.
Each glyph is returned as a separate path, allowing attributes to be applied if required.
| str | the string to render |
| dy | the baseline offset between the path and the text |
| - (NSBezierPath*) bezierPathWithObjectsOnPathAtInterval: | (CGFloat) | interval | |
| factoryObject: | (id) | object | |
| userInfo: | (void *) | userInfo | |
Places objects at regular intervals along the path.
The factory object creates a path at each position and it is added to the resulting path
| interval | the distance between each object placed |
| object | a factory object used to supply the paths placed |
| userInfo | information passed to the factory object |
| - (NSBezierPath*) bezierPathWithPath: | (NSBezierPath *) | path | |
| atInterval: | (CGFloat) | interval | |
Places copies of a given path at regular intervals along the path.
The origin of <path> is positioned on the receiver's path at the designated location. The caller should ensure that the origin is sensible - paths based on 0,0 work as expected.
| path | a path to position at intervals on this path |
| interval | the distance between each object placed |
| - (NSBezierPath*) bezierPathWithPath: | (NSBezierPath *) | path | |
| atInterval: | (CGFloat) | interval | |
| phase: | (CGFloat) | phase | |
| alternate: | (BOOL) | alt | |
| taperDelegate: | (id) | taperDel | |
Places copies of a given path at regular intervals along the path.
The origin of <path> is positioned on the receiver's path at the designated location. The caller should ensure that the origin is sensible - paths based on 0,0 work as expected.
| path | a path to position at intervals on this path |
| interval | the distance between each object placed |
| phase | an initial offset added to the distance |
| alternate | if YES, odd-numbered elements are reversed 180 degrees |
| taperDel | an optional taper delegate. |
| - (NSBezierPath*) bezierPathWithStringOnPath: | (NSString *) | str |
Returns a single path consisting of all of the laid out glyphs of the text.
The string is drawn using the class attributes.
| str | the string to render |
| - (NSBezierPath*) bezierPathWithStringOnPath: | (NSString *) | str | |
| attributes: | (NSDictionary *) | attrs | |
Returns a single path consisting of all of the laid out glyphs of the text.
| str | the string to render |
| attrs | the drawing attributes for the text |
| - (NSBezierPath*) bezierPathWithTextOnPath: | (NSAttributedString *) | str | |
| yOffset: | (CGFloat) | dy | |
Returns a single path consisting of all of the laid out glyphs of the text.
All glyph paths are added to the single bezier path. This preserves their original shapes but attribute information such as colour runs, etc are effectively lost.
| str | the string to render |
| dy | the baseline offset between the path and the text |
| - (NSArray*) descenderBreaksForString: | (NSAttributedString *) | str | |
| range: | (NSRange) | range | |
| underlineOffset: | (CGFloat) | offset | |
Determines the positions of any descender breaks for drawing underlines.
In order to correctly and accurately interrupt an underline where a glyph descender 'cuts' through it, the locations of the start and end of each break must be computed. This does that by finding the intersections of the glyph paths and a notional underline path. As such it is computationally expensive (but is cached at a higher level).
| str | the string in question |
| range | the range of characters of interest within the string |
| offset | the distance between the text baseline and the underline |
| - (void) drawStrikethroughPathForLayoutManager: | (NSLayoutManager *) | lm | |
| range: | (NSRange) | range | |
| yOffset: | (CGFloat) | dy | |
| cache: | (NSMutableDictionary *) | cache | |
Low level method draws the strikethrough attributes for ranges of text.
Here be more dragons.
| lm | the layout manager in use |
| range | the range of text to apply the underline attribute to |
| dy | the text baseline offset from the path |
| cache | a cache used to store intermediate calculations to speed up repeated drawing |
| - (void) drawStrikethroughPathForLayoutManager: | (NSLayoutManager *) | lm | |
| yOffset: | (CGFloat) | dy | |
| cache: | (NSMutableDictionary *) | cache | |
Low level method draws the strikethrough attributes for the text if necessary.
Strikethrough text on a path is involved, as it needs to bypass NSLayoutManager's normal processing and handle it directly, in order to get smooth unbroken lines. While this sometimes results in strikethrough that differs from standard, it is very close and visually far nicer than leaving it to NSLayoutManager.
| lm | the layout manager in use |
| dy | the text baseline offset from the path |
| cache | a cache used to store intermediate calculations to speed up repeated drawing |
Renders a string on a path.
Very high-level, draws the string on the path using the set class attributes.
| str | the string to render |
| - (BOOL) drawStringOnPath: | (NSString *) | str | |
| attributes: | (NSDictionary *) | attrs | |
Renders a string on a path.
If attrs is nil, uses the current class attributes
| str | the string to render |
| attrs | the attributes to use to draw the string - may be nil |
| - (BOOL) drawTextOnPath: | (NSAttributedString *) | str | |
| yOffset: | (CGFloat) | dy | |
Renders a string on a path.
Positive values of dy place the text's baseline above the path, negative below it, where 'above' and 'below' are in the expected sense relative to the orientation of the drawn glyphs. This is the highest-level attributed text on path drawing method, and uses the shared layout mamanger and no cache.
| str | the attributed string to render |
| dy | the offset between the path and the text's baseline when drawn. |
| - (BOOL) drawTextOnPath: | (NSAttributedString *) | str | |
| yOffset: | (CGFloat) | dy | |
| layoutManager: | (NSLayoutManager *) | lm | |
| cache: | (NSMutableDictionary *) | cache | |
Renders a string on a path.
Passing nil for the layout manager uses the shared layout manager. If the same cache is passed back each time by the client code, certain calculations are cached there which can speed up drawing. The client owns the cache and is responsible for invalidating it (setting it empty) when text content changes. However the client code doesn't need to consider path changes - they are handled automatically.
| str | the attributed string to render |
| dy | the offset between the path and the text's baseline when drawn. |
| lm | the layout manager to use for layout |
| cache | an optional cache dictionary (must be a valid mutable dictionary, or nil) |
| - (void) drawUnderlinePathForLayoutManager: | (NSLayoutManager *) | lm | |
| range: | (NSRange) | range | |
| yOffset: | (CGFloat) | dy | |
| cache: | (NSMutableDictionary *) | cache | |
Low level method draws the undeline attributes for ranges of text.
Here be dragons.
| lm | the layout manager in use |
| range | the range of text to apply the underline attribute to |
| dy | the text baseline offset from the path |
| cache | a cache used to store intermediate calculations to speed up repeated drawing |
| - (void) drawUnderlinePathForLayoutManager: | (NSLayoutManager *) | lm | |
| yOffset: | (CGFloat) | dy | |
| cache: | (NSMutableDictionary *) | cache | |
Low level method draws the underline attributes for the text if necessary.
Underlining text on a path is very involved, as it needs to bypass NSLayoutManager's normal underline processing and handle it directly, in order to get smooth unbroken lines. While this sometimes results in underlining that differs from standard, it is very close and visually far nicer than leaving it to NSLayoutManager.
| lm | the layout manager in use |
| dy | the text baseline offset from the path |
| cache | a cache used to store intermediate calculations to speed up repeated drawing |
Find the points where a line drawn horizontally across the path will intersect it.
This works by approximating the curve as a series of straight lines and testing each one for intersection with the line at y. This is the primitive method used to determine line layout rectangles - a series of calls to this is needed for each line (incrementing y by the lineheight) and then rects forming from the resulting points. See -lineFragmentRectsForFixedLineheight: This is also used when calculating descender breaks for underlining text on a path. This method is guaranteed to return an even number of (or none) results.
| yPosition | the distance between the top edge of the bounds and the line to test |
| - (void) kernText: | (NSTextStorage *) | text | |
| toFitLength: | (CGFloat) | length | |
Low level method adjusts text to fit the path length.
Modifies the text storage in place by setting NSKernAttribute to stretch or compress the text to fit the given length. Text is only compressed by a certain amount - beyond that characters are dropped from the end of the line when laid out.
| text | text storage containing the text to lay out |
| length | the path length |
| - (BOOL) layoutStringOnPath: | (NSTextStorage *) | str | |
| yOffset: | (CGFloat) | dy | |
| usingLayoutHelper: | (id) | helperObject | |
| layoutManager: | (NSLayoutManager *) | lm | |
| cache: | (NSMutableDictionary *) | cache | |
Low level method performs all text on path layout.
This method does all the actual work of glyph generation and positioning of the glyphs along the path. It is called by all other methods. The helper object does the appropriate thing, either adding the glyph outline to a list or actually drawing the glyph. Note that the glyph layout is handled by the layout manager as usual, but the helper is responsible for the last step.
| str | the attributed string to render |
| dy | the text baseline offset |
| helperObject | a helper object used to process each glyph as it is laid out |
| lm | the layout manager that performs the layout |
| cache | a cache used to save layout informaiton to avoid recalculation |
Find a line fragement rectange for laying out text in this shape.
See -lineFragmentRectForProposedRect:remainingRect:datumOffset:
| aRect | the proposed rectangle |
| - (NSRect) lineFragmentRectForProposedRect: | (NSRect) | aRect | |
| remainingRect: | (NSRect *) | rem | |
| datumOffset: | (CGFloat) | dOffset | |
Find a line fragement rectange for laying out text in this shape.
This offsets <proposedRect> to the right to the next even-numbered intersection point, setting its length to the difference between that point and the next. That part is the return value. If there are any further points, the remainder is set to the rest of the rect. This allows this method to be used directly by a NSTextContainer subclass (see DKBezierTextContainer)
| aRect | the proposed rectangle |
| dOffset | a value between +0.5 and -0.5 that represents the relative position within the line used |
Find rectangles within which text can be laid out to place the text within the path.
Given a lineheight value, this returns an array of rects (as NSValues) which are the ordered line layout rects from left to right and top to bottom within the shape to layout text in. This is computationally intensive, so the result should probably be cached until the shape is actually changed. This works with a fixed lineheight, where every line is the same. Note that this method isn't really suitable for use with NSTextContainer or Cocoa's text system in general - for flowing text using NSLayoutManager use DKBezierTextContainer which calls the -lineFragmentRectForProposedRect:remainingRect: method below.
| lineHeight | the lineheight for the lines of text |
Moves an object along the path at a constant speed.
The object must respond to the informal motion protocol. This method starts a timer which runs until either the end of the path is reached when loop is NO, or until the object being moved itself returns NO. The timer runs at 30 fps and the distance moved is calculated accordingly - this gives accurate motion speed regardless of framerate, and will drop frames if necessary.
| object | the object to be moved (i.e. animated) |
| speed | the linear motion speed in points per second |
| loop | YES to repeatedly loop the movement when it gets to the end, NO for one-time motion. |
| userInfo | user info passed to the object |
| - (void) pathPosition: | (CGFloat *) | start | |
| andLength: | (CGFloat *) | length | |
| forCharactersOfString: | (NSAttributedString *) | str | |
| inRange: | (NSRange) | range | |
Calculates the start and end locations of ranges of text on the path.
Used to compute start positions and length of runs of attributes along the path, such as underlines and strikethroughs. Paragraph styles affect this, so the results tell you where to draw.
| start | receives the starting position of the range of characters |
| length | receives the length of the range of characters |
| str | the string in question |
| range | the range of characters of interest within the string |
| - (NSArray*) placeLinksOnPathWithEvenLinkLength: | (CGFloat) | ell | |
| oddLinkLength: | (CGFloat) | oll | |
| factoryObject: | (id) | object | |
| userInfo: | (void *) | userInfo | |
Places "links" along the path at alternating even and odd intervals.
Similar to object placement, but treats the objects as "links" like in a chain, where a rigid link of a fixed length connects two points on the path. The factory object is called with the pair of points computed, and returns a path representing the link between those two points. Non-nil results are accumulated into the array returned. Even and odd links can have different lengths for added flexibility. Note that to keep this working quickly, the link length is used as a path length to find the initial link pivot point, then the actual point is calculated by using the link radius in this direction. The result can be that links will not exactly follow a very convoluted or curved path, but each link is guaranteed to be a fixed length and exactly join to its neighbours. In practice, this gives results that are very "physical" in that it emulates the behaviour of real chains that are bent through acute angles.
| ell | the even interval |
| oll | th eodd interval |
| object | a factory object used to generate the links themselves |
| userInfo | user info passed to the factory object |
| - (NSArray*) placeLinksOnPathWithLinkLength: | (CGFloat) | ll | |
| factoryObject: | (id) | object | |
| userInfo: | (void *) | userInfo | |
Places "links" along the path at equal intervals.
See notes for placeLinksOnPathWithEvenLinkLength:oddLinkLength:factoryObject:userInfo:
| ll | the interval and length of each "link" |
| object | a factory object used to generate the links themselves |
| userInfo | user info passed to the factory object |
| - (NSArray*) placeObjectsOnPathAtInterval: | (CGFloat) | interval | |
| factoryObject: | (id) | object | |
| userInfo: | (void *) | userInfo | |
Places objects at regular intervals along the path.
The factory object creates an object at each position and it is added to the result array.
| interval | the distance between each object placed |
| object | a factory object used to supply the paths placed |
| userInfo | information passed to the factory object |
| - (NSTextStorage*) preadjustedTextStorageWithString: | (NSAttributedString *) | str | |
| layoutManager: | (NSLayoutManager *) | lm | |
Low level method adjusts justified text to fit the path length.
This does two things - it sets up the text's container so that text will be laid out properly within the path's length, and secondly if the text is "justified" it kerns the text to fit the path.
| text | text storage containing the text to lay out |
| length | the path length |
| + (void) setTextOnPathDefaultAttributes: | (NSDictionary *) | attrs |
Sets the attributes used to draw strings on paths.
Pass nil to set the default. The attributes are used by the drawStringOnPath: method.
| attrs | a dictionary of text attributes |
| - (NSBezierPath*) textLinePathWithMask: | (NSInteger) | mask | |
| startPosition: | (CGFloat) | sp | |
| length: | (CGFloat) | length | |
| offset: | (CGFloat) | offset | |
| lineThickness: | (CGFloat) | lineThickness | |
| descenderBreaks: | (NSArray *) | breaks | |
| grotThreshold: | (CGFloat) | gt | |
Converts all the information about an underline into a path that can be drawn.
Where descender breaks are passed in, the gap on either side of the break is widened by a factor based on gt, which in turn is usually derived from the text size. This allows the breaks to size proportionally to give pleasing results. The result may differ from Apple's standard text block rendition (but note that for some fonts, DK's way works where Apple's does not, e.g. Zapfino)
| mask | the underline attributes mask value |
| sp | the starting position for the underline on the path |
| length | the length of the underline on the path |
| offset | the distance between the text baseline and the underline |
| lineThickness | the thickness of the underline |
| breaks | an array of descender breakpoints, or nil |
| gt | threshold value to suppress inclusion of very short "bits" of underline (a.k.a "grot") |
| + (NSDictionary*) textOnPathDefaultAttributes |
Returns the attributes used to draw strings on paths.
The default is 12 point Helvetica Roman black text with the default paragraph style.
| + (NSLayoutManager*) textOnPathLayoutManager |
Returns a layout manager used for text on path layout.
This shared layout manager is used by text on path drawing unless a specific manager is passed.
1.8.9.1
