Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSLayoutManager


Inherits from:
NSObject
Package:
com.apple.yellow.application


Class Description


An NSLayoutManager coordinates the layout and display of characters held in an NSTextStorage object. It maps Unicode character codes to glyphs, sets the glyphs in a series of NSTextContainers, and displays them in a series of NSTextViews. In addition to its core function of laying out text, an NSLayoutManager coordinates its NSTextViews, provides services to those NSTextViews to support NSRulerViews for editing paragraph styles, and handles the layout and display of text attributes not inherent in glyphs (such as underline or strikethrough). You can create a subclass of NSLayoutManager to handle additional text attributes, whether inherent or not.




Constants


These constants specify how a glyph is laid out relative to the previous glyph.


Constants Description
GlyphInscribeBase Description forthcoming.
GlyphInscribeBelow Description forthcoming.
GlyphInscribeAbove Description forthcoming.
GlyphInscribeOverstrike Description forthcoming.
GlyphInscribeOverBelow Description forthcoming.

Description forthcoming


Constants Description
GlyphAttributeSoft Description forthcoming.
GlyphAttributeElastic Description forthcoming.
GlyphAttributeInscribe Description forthcoming.



Method Types


Constructors
NSLayoutManager
Setting the text storage
setTextStorage
textStorage
replaceTextStorage
Setting text containers
textContainers
addTextContainer
insertTextContainerAtIndex
removeTextContainerAtIndex
Invalidating glyphs and layout
invalidateGlyphsForCharacterRange
invalidateLayoutForCharacterRange
invalidateDisplayForCharacterRange
invalidateDisplayForGlyphRange
textContainerChangedGeometry
textStorageChanged
Turning background layout on/off
setBackgroundLayoutEnabled
backgroundLayoutEnabled
Accessing glyphs
insertGlyphAtGlyphIndex
glyphAtIndex
replaceGlyphAtIndex
glyphsInRange
deleteGlyphsInRange
numberOfGlyphs
Mapping characters to glyphs
setCharacterIndexForGlyphAtIndex
characterIndexForGlyphAtIndex
characterRangeForGlyphRange
glyphRangeForCharacterRange
Setting glyph attributes
setGlyphAttributeForGlyphAtIndex
glyphAttributeForGlyphAtIndex
Handling layout for text containers
setTextContainerForGlyphRange
glyphRangeForTextContainer
textContainerForGlyphAtIndex
usedRectForTextContainer
Handling line fragment rectangles
setLineFragmentRectForGlyphAtIndex
lineFragmentRectForGlyphAtIndex
lineFragmentUsedRectForGlyphAtIndex
setExtraLineFragmentRect
extraLineFragmentRect
extraLineFragmentUsedRect
extraLineFragmentTextContainer
setDrawsOutsideLineFragmentForGlyphAtIndex
drawsOutsideLineFragmentForGlyphAtIndex
Layout of glyphs
setLocationForStartOfGlyphRange
locationForGlyphAtIndex
rangeOfNominallySpacedGlyphsContainingIndex
rectArrayForCharacterRange
rectArrayForGlyphRange
boundingRectForGlyphRange
glyphRangeForBoundingRect
glyphRangeForBoundingRectWithoutAdditionalLayout
Display of special glyphs
setNotShownForGlyphAtIndex
notShownAttributeForGlyphAtIndex
setShowsInvisibleCharacters
showsInvisibleCharacters
setShowsControlCharacters
showsControlCharacters
Controlling hyphenation
setHyphenationFactor
hyphenationFactor
Using screen fonts
setUsesScreenFonts
usesScreenFonts
substituteFontForFont
Handling rulers
rulerAccessoryViewForTextView
rulerMarkersForTextView
Managing the responder chain
layoutManagerOwnsFirstResponderInWindow
firstTextView
textViewForBeginningOfSelection
Drawing
drawBackgroundForGlyphRange
drawGlyphsForGlyphRange
drawUnderlineForGlyphRange
underlineGlyphRange
Setting the delegate
setDelegate
delegate


Constructors



NSLayoutManager

public NSLayoutManager()

Description forthcoming.


Instance Methods



addTextContainer

public void addTextContainer(NSTextContainer aTextContainer)

Appends aTextContainer to the series of NSTextContainers where the receiver arranges text. Invalidates glyphs and layout as needed, but doesn't perform glyph generation or layout.

See Also: insertTextContainerAtIndex, removeTextContainerAtIndex, textContainers, invalidateGlyphsForCharacterRange, invalidateLayoutForCharacterRange



backgroundLayoutEnabled

public boolean backgroundLayoutEnabled()

Returns true if the receiver generates glyphs and lays out text when the application's run loop is idle, false if it only performs glyph generation and layout when necessary.

See Also: setBackgroundLayoutEnabled



boundingRectForGlyphRange

public NSRect boundingRectForGlyphRange( NSRange glyphRange, NSTextContainer aTextContainer)

Returns a single bounding rectangle enclosing all glyphs and other marks drawn in aTextContainer for glyphRange, including glyphs that draw outside their line fragment rectangles and text attributes such as underlining. This method is useful for determining the area that needs to be redrawn when a range of glyphs changes.

Performs glyph generation and layout if needed.

See Also: glyphRangeForTextContainer, drawsOutsideLineFragmentForGlyphAtIndex



characterIndexForGlyphAtIndex

public int characterIndexForGlyphAtIndex(int glyphIndex)

Returns the index in the NSTextStorage for the first character mapped to the glyph at glyphIndex within the receiver. In many cases it's better to use the range-mapping methods, characterRangeForGlyphRange and glyphRangeForCharacterRange, which provide more comprehensive information.

Performs glyph generation if needed.



characterRangeForGlyphRange

public NSRange characterRangeForGlyphRange( NSRange glyphRange, NSMutableRange actualGlyphRange)

Returns the range for the characters in the receiver's text store that are mapped to the glyphs in glyphRange. If actualGlyphRange is non-null, expands the requested range as needed so that it identifies all glyphs mapped to those characters and returns the new range by reference in actualGlyphRange.

Suppose the text store begins with the character "Ö" and the glyph cache contains "O" and "¨". If you get the character range for the glyph range {0, 1} or {1, 1}, actualGlyphRange is returned as {0, 2}, indicating that both glyphs are mapped to the character "Ö".

Performs glyph generation if needed.

See Also: characterIndexForGlyphAtIndex, glyphRangeForCharacterRange



delegate

public Object delegate()

Returns the receiver's delegate.

See Also: setDelegate



deleteGlyphsInRange

public void deleteGlyphsInRange(NSRange glyphRange)

Deletes the glyphs in glyphRange.

This method is for use by the glyph generation mechanism, and doesn't perform any invalidation or generation of the glyphs or layout. You should never directly invoke this method.

See Also: insertGlyphAtGlyphIndex



drawBackgroundForGlyphRange

public void drawBackgroundForGlyphRange( NSRange glyphRange, NSPoint containerOrigin)

Draws background marks for glyphRange, which must lie completely within a single NSTextContainer. containerOrigin indicates the position of the NSTextContainer in the coordinate system of the NSView being drawn. This method must be invoked with the graphics focus locked on that NSView.

Background marks are such things as selection highlighting, text background color, and any background for marked text.

Performs glyph generation and layout if needed.

See Also: drawGlyphsForGlyphRange, glyphRangeForTextContainer, textContainerOrigin (NSTextView)



drawGlyphsForGlyphRange

public void drawGlyphsForGlyphRange( NSRange glyphRange, NSPoint containerOrigin)

Draws the glyphs in glyphRange, which must lie completely within a single NSTextContainer. containerOrigin indicates the position of the NSTextContainer in the coordinate system of the NSView being drawn. This method must be invoked with the graphics focus locked on that NSView.

Performs glyph generation and layout if needed.

See Also: drawBackgroundForGlyphRange, glyphRangeForTextContainer, textContainerOrigin (NSTextView)



drawUnderlineForGlyphRange

public void drawUnderlineForGlyphRange( NSRange glyphRange, int underlineType, float baselineOffset, NSRect lineRect, NSRange lineGlyphRange, NSPoint containerOrigin)

Draws underlining for the glyphs in glyphRange, which must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex). underlineType indicates the style of underlining to draw; NSLayoutManager accepts only NSAttributedString.SingleUnderlineStyle, but subclasses can define their own underline styles. baselineOffset indicates how far below the text baseline the underline should be drawn; it's usually a positive value. lineRect is the line fragment rectangle containing the glyphs to draw underlining for, and lineGlyphRange is the range of all glyphs within that line fragment rectangle. containerOrigin is the origin of the line fragment rectangle's NSTextContainer in its NSTextView.

This method is invoked automatically by underlineGlyphRange; you should rarely need to invoke it directly.

See Also: textContainerForGlyphAtIndex, textContainerOrigin (NSTextView)



drawsOutsideLineFragmentForGlyphAtIndex

public boolean drawsOutsideLineFragmentForGlyphAtIndex(int glyphIndex)

Returns true if the glyph at glyphIndex exceeds the bounds of the line fragment where it's laid out, false otherwise. This can happen when text is set at a fixed line height. For example, if the user specifies a fixed line height of 12 points and sets the font size to 24 points, the glyphs will exceed their layout rectangles.

Glyphs that draw outside their line fragment rectangles aren't considered when calculating enclosing rectangles with the rectArrayForCharacterRange and rectArrayForGlyphRange methods. They are, however, considered by boundingRectForGlyphRange

Performs glyph generation and layout if needed.



extraLineFragmentRect

public NSRect extraLineFragmentRect()

Returns the rectangle defining the extra line fragment for the insertion point at the end of a text (either in an empty text or after a final paragraph separator). The rectangle is defined in the coordinate system of its NSTextContainer. Returns NSRect.ZeroRect if there is no such rectangle.

See Also: extraLineFragmentUsedRect, extraLineFragmentTextContainer, setExtraLineFragmentRect



extraLineFragmentTextContainer

public NSTextContainer extraLineFragmentTextContainer()

Returns the NSTextContainer that contains the extra line fragment rectangle, or null if there is no extra line fragment rectangle. This rectangle is used to display the insertion point for the insertion point at the end of a text (either in an empty text or after a final paragraph separator).

See Also: extraLineFragmentRect, extraLineFragmentUsedRect, setExtraLineFragmentRect



extraLineFragmentUsedRect

public NSRect extraLineFragmentUsedRect()

Returns the rectangle enclosing the insertion point drawn in the extra line fragment rectangle. The rectangle is defined in the coordinate system of its NSTextContainer. Returns NSRect.ZeroRect if there is no extra line fragment rectangle.

The extra line fragment used rectangle is twice as wide (or tall) as the NSTextContainer's line fragment padding, with the insertion point itself in the middle.

See Also: extraLineFragmentRect, extraLineFragmentTextContainer, setExtraLineFragmentRect



firstTextView

public NSTextView firstTextView()

Returns the first NSTextView in the receiver's series of text views. This NSTextView is the object of various NSText and NSTextView notifications posted.

firstUnlaidCharacterIndex

public int firstUnlaidCharacterIndex()

Returns the index for the first unlaid character in the layout manager.

firstUnlaidGlyphIndex

public int firstUnlaidGlyphIndex()

Returns the index for the first unlaid glyph in the layout manager.

fractionOfDistanceThroughGlyphForPoint

public float fractionOfDistanceThroughGlyphForPoint( NSPoint aPoint, NSTextContainer aTextContainer)

Description forthcoming

glyphAtIndex

public int glyphAtIndex(int glyphIndex)

Returns the glyph at glyphIndex. Throws a RangeException if glyphIndex is out of bounds.

Performs glyph generation if needed. To avoid an exception with glyphAtIndex you must first check the glyph index against the number of glyphs, which requires generating all glyphs.

See Also: getGlyphs:range:



glyphIndexForPoint

public int glyphIndexForPoint( NSPoint aPoint, NSTextContainer aTextContainer)

Description forthcoming.

glyphRangeForBoundingRect

public NSRange glyphRangeForBoundingRect( NSRect aRect, NSTextContainer aTextContainer)

Returns the smallest contiguous range for glyphs that are laid out wholly or partially within aRect in aTextContainer. The range returned can include glyphs that don't fall inside or intersect aRect, though the first and last glyphs in the range always do. This method is used to determine which glyphs need to be displayed within a given rectangle.

Performs glyph generation and layout if needed.

See Also: glyphRangeForBoundingRectWithoutAdditionalLayout



glyphRangeForBoundingRectWithoutAdditionalLayout

public NSRange glyphRangeForBoundingRectWithoutAdditionalLayout( NSRect bounds, NSTextContainer container)

Returns the smallest contiguous range for glyphs that are laid out wholly or partially within aRect in aTextContainer. The range returned can include glyphs which don't fall inside or intersect aRect, though the first and last glyphs in the range always do.

Unlike glyphRangeForBoundingRect, this method doesn't perform glyph generation or layout. Its results, though faster, can be incorrect. This method is primarily for use by NSTextView; you should rarely need to use it yourself.

See Also: glyphRangeForBoundingRect



glyphRangeForCharacterRange

public NSRange glyphRangeForCharacterRange( NSRange charRange, NSMutableRange actualCharRange)

Returns the range for the glyphs mapped to the characters of the text store in charRange. If actualCharRange is non-null, expands the requested range as needed so that it identifies all characters mapped to those glyphs and returns the new range by reference in actualCharRange.

Suppose the text store contains the characters "n" and the glyph cache contains "±". If you get the glyph range for the character range {0, 1} or {1, 1}, actualCharRange is returned as {0, 2}, indicating both of the characters mapped to the glyph "±".

Performs glyph generation if needed.

See Also: characterIndexForGlyphAtIndex



glyphRangeForTextContainer

public NSRange glyphRangeForTextContainer(NSTextContainer aTextContainer)

Returns the range for glyphs laid out within aTextContainer.

Performs glyph generation and layout if needed.



glyphsInRange

public int [] glyphsInRange(NSRange aRange)

Description forthcoming.

hyphenationFactor

public float hyphenationFactor()

Whenever (width of the real contents of the line) / (the line fragment width) is less than hyphenationFactor, hyphenation will be attempted when laying out the line. The range of this factor is from 0.0 to 1.0. By default, the value is 0.0, meaning hyphenation is off. A value of 1.0 causes hyphenation to be attempted always. Note that hyphenation will slow down text layout and increase memory usage, so it should be used sparingly.

See Also: setHyphenationFactor



insertGlyphAtGlyphIndex

public void insertGlyphAtGlyphIndex( int aGlyph, int glyphIndex, int charIndex)

Inserts aGlyph into the glyph cache at glyphIndex and maps it to the character at charIndex. If the glyph is mapped to several characters, charIndex should indicate the first character it's mapped to.

This method is for use by the glyph generation mechanism, and doesn't perform any invalidation or generation of the glyphs or layout. You should never directly invoke this method.

See Also: deleteGlyphsInRange, replaceGlyphAtIndex



insertTextContainerAtIndex

public void insertTextContainerAtIndex( NSTextContainer aTextContainer, int index)

Inserts aTextContainer into the series of text containers at index, and invalidates layout for all subsequent NSTextContainer's. Also invalidates glyph information as needed.

See Also: addTextContainer, removeTextContainerAtIndex, textContainers



glyphAttributeForGlyphAtIndex

public int glyphAttributeForGlyphAtIndex( int attributeTag, int glyphIndex)

Returns the value of the attribute identified by attributeTag for the glyph at glyphIndex.

Subclasses that define their own custom attributes must override this method to access their own storage for the attribute values. Non-negative tags are reserved by Apple; you can define your own attributes with negative tags and set values using setGlyphAttributeForGlyphAtIndex.



invalidateDisplayForCharacterRange

public void invalidateDisplayForCharacterRange(NSRange charRange)

Invalidates display for characterRange. Unlaid parts of the range are remembered and will definitely be redisplayed at some point later when the layout is available. Does not actually cause layout.

invalidateDisplayForGlyphRange

public void invalidateDisplayForGlyphRange(NSRange glyphRange)

Marks the glyphs in glyphRange as needing display, as well as the appropriate regions of the NSTextViews that display those glyphs (using NSView's setNeedsDisplay). You should rarely need to invoke this method.

invalidateGlyphsForCharacterRange

public void invalidateGlyphsForCharacterRange( NSRange charRange, int lengthChange, NSMutableRange actualCharRange)

Invalidates the cached glyphs for the characters in charRange and adjusts the remaining glyph-to-character mapping according to lengthChange, which indicates the number of characters added to or removed from the text store. If non-null, actualCharRange is set to the range of characters mapped to the glyphs just invalidated. This can be larger than the range of characters given due to the effect of context on glyphs and layout.

You should rarely need to invoke this method. It only invalidates glyph information, and performs no glyph generation or layout. Because invalidating glyphs also invalidates layout, after invoking this method you should also invoke invalidateLayoutForCharacterRange, passing charRange as the first argument and false as the flag.



invalidateLayoutForCharacterRange

public void invalidateLayoutForCharacterRange( NSRange charRange, boolean flag, NSMutableRange actualCharRange)

Invalidates the layout information for the glyphs mapped to the characters in charRange. If flag is true, attempts to save some layout information to avoid recalculation; if flag is false, saves no layout information. You should typically pass false for flag. If non-null, actualCharRange is set to the range of characters mapped to the glyphs whose layout information has been invalidated. This can be larger than the range of characters given due to the effect of context on glyphs and layout.

This method only invalidates information; it performs no glyph generation or layout. You should rarely need to invoke this method.

See Also: invalidateGlyphsForCharacterRange



isValidGlyphIndex

public boolean isValidGlyphIndex(int glyphIndex)

Description forthcoming.

layoutManagerOwnsFirstResponderInWindow

public boolean layoutManagerOwnsFirstResponderInWindow(NSWindow aWindow)

Returns true if the first responder in aWindow is an NSTextView associated with the receiver, false otherwise.

lineFragmentRectForGlyphAtIndex

public NSRect lineFragmentRectForGlyphAtIndex( int glyphIndex, NSMutableRange lineFragmentRange)

Returns the line fragment rectangle containing the glyph at glyphIndex. The rectangle is defined in the coordinate system of its NSTextContainer. If non-null, lineFragmentRange is set to contain the range for all glyphs in that line fragment.

Performs glyph generation and layout if needed.

See Also: lineFragmentUsedRectForGlyphAtIndex, setLineFragmentRectForGlyphAtIndex



lineFragmentUsedRectForGlyphAtIndex

public NSRect lineFragmentUsedRectForGlyphAtIndex( int glyphIndex, NSMutableRange lineFragmentRange)

Returns the portion of the line fragment rectangle containing glyphAtIndex that actually contains glyphs (such as for a partial or wrapped line), plus the line fragment padding defined by the NSTextContainer where the glyphs reside. This rectangle is defined in the coordinate system of its NSTextContainer, and is based on line calculation only-that is, it isn't a bounding box for the glyphs in the line fragment.

If non-null, lineFragmentRange is set to contain the range for all glyphs in the line fragment.

Performs glyph generation and layout if needed.

See Also: lineFragmentRectForGlyphAtIndex, setLineFragmentRectForGlyphAtIndex



locationForGlyphAtIndex

public NSPoint locationForGlyphAtIndex(int glyphIndex)

Returns the location, in terms of its line fragment rectangle, for the glyph at glyphIndex. The line fragment rectangle in turn is defined in the coordinate system of the text container where it resides.

Performs glyph generation and layout if needed.

See Also: lineFragmentRectForGlyphAtIndex, lineFragmentUsedRectForGlyphAtIndex



notShownAttributeForGlyphAtIndex

public boolean notShownAttributeForGlyphAtIndex(int glyphIndex)

Returns true if the glyph at glyphIndex isn't shown (in the sense of the PostScript show operator), false if it is. For example, a tab, newline, or attachment glyph doesn't get shown; it just affects the layout of following glyphs or locates the attachment graphic. Space characters, however, typically are shown as glyphs with a displacement, though they leave no visible marks. Throws a RangeException if glyphIndex is out of bounds.

Performs glyph generation and layout if needed.

See Also: setNotShownForGlyphAtIndex



numberOfGlyphs

public int numberOfGlyphs()

Returns the number of glyphs in the receiver, performing glyph generation if needed to determine this number.

rangeOfNominallySpacedGlyphsContainingIndex

public NSRange rangeOfNominallySpacedGlyphsContainingIndex(int glyphIndex)

Returns the range for the glyphs around glyphIndex that can be displayed with a single PostScript show operation; in other words, glyphs with no pairwise kerning or other adjustments to spacing.

Performs glyph generation and layout if needed.



rectArrayForCharacterRange

public NSRect rectArrayForCharacterRange( NSRange charRange, NSRange selCharRange, NSTextContainer aTextContainer)

Returns a rectangle for the glyphs in aTextContainer that correspond to charRange. This rectangles can be used to draw the background or highlight for the given range of characters. selCharRange indicates selected characters, which can affect the size of the rectangles; it must be equal to or contain charRange. To calculate the rectangles for drawing the background, use a selected character range whose location is NotFound. To calculate the rectangles for drawing highlighting for charRange, use a selected character range that contains charRange.

The number of rectangles returned isn't necessarily the number of lines enclosing the specified range. Contiguous lines can share an enclosing rectangle, and lines broken into several fragments have a separate enclosing rectangle for each fragment.

The rectangle returned is owned by the receiver, and is overwritten by various NSLayoutManager methods. You should never free it, and should copy it if you need to keep the values or use them after sending other messages to the layout manager.

The purpose of this method is to calculate line rectangles for drawing the text background and highlighting. These rectangles don't necessarily enclose glyphs that draw outside their line fragment rectangles; use boundingRectForGlyphRange to determine the area that contains all drawing performed for a range of glyphs.

Performs glyph generation and layout if needed.

See Also: glyphRangeForTextContainer, characterRangeForGlyphRange, drawsOutsideLineFragmentForGlyphAtIndex



rectArrayForGlyphRange

public NSRect rectArrayForGlyphRange( NSRange glyphRange, NSRange selGlyphRange, NSTextContainer aTextContainer)

Returns a rectangle for the glyphs in aTextContainer in glyphRange. This rectangles can be used to draw the background or highlight for the given range of glyphs. selGlyphRange indicates selected glyphs. To calculate the rectangles for drawing the background, use a selected glyph range whose location is NotFound. To calculate the rectangles for highlighting, use a selected glyph range that contains glyphRange.

The number of rectangles returned isn't necessarily the number of lines enclosing the specified range. Contiguous lines can share an enclosing rectangle, and lines broken into several fragments have a separate enclosing rectangle for each fragment.

The rectangle returned is owned by the receiver, and is overwritten by various NSLayoutManager methods. You should never free it, and should copy it if you need to keep the values or use them after sending other messages to the layout manager.

The purpose of this method is to calculate line rectangles for drawing the text background and highlighting. These rectangles don't necessarily enclose glyphs that draw outside their line fragment rectangles; use boundingRectForGlyphRange to determine the area that contains all drawing performed for a range of glyphs.

Performs glyph generation and layout if needed.

See Also: glyphRangeForTextContainer, drawsOutsideLineFragmentForGlyphAtIndex



removeTextContainerAtIndex

public void removeTextContainerAtIndex(int index)

Removes the NSTextContainer at index and invalidates the layout as needed. Also invalidates glyph information as needed.

See Also: addTextContainer, insertTextContainerAtIndex, textContainers, invalidateGlyphsForCharacterRange, invalidateLayoutForCharacterRange



replaceGlyphAtIndex

public void replaceGlyphAtIndex( int glyphIndex, int newGlyph)

Replaces the glyph at glyphIndex with newGlyph. Doesn't alter the glyph-to-character mapping or invalidate layout information.

This method is for use by the glyph generation mechanism, and doesn't perform any invalidation or generation of the glyphs or layout. You should never directly invoke this method.

See Also: setCharacterIndexForGlyphAtIndex, invalidateGlyphsForCharacterRange, invalidateLayoutForCharacterRange



replaceTextStorage

public void replaceTextStorage(newTextStorage newTextStorage)

Replaces the NSTextStorage for the group of text-system objects containing the receiver with newTextStorage. All NSLayoutManagers sharing the original NSTextStorage then share the new one. This method makes all the adjustments necessary to keep these relationships intact, unlike setTextStorage.

rulerAccessoryViewForTextView

public NSView rulerAccessoryViewForTextView( NSTextView aTextView, NSParagraphStyle paraStyle, NSRulerView aRulerView, boolean flag)

Returns the accessory NSView for aRulerView. This accessory contains tab wells, text alignment buttons, and so on. paraStyle is used to set the state of the controls in the accessory NSView; it must not be null. If flag is true the accessory view is enabled and accepts mouse and keyboard events; if false it's disabled.

This method is invoked automatically by the NSTextView object using the layout manager. You should rarely need to invoke it, but you can override it to customize ruler support. If you do this method directly, not that it neither installs the ruler accessory view nor sets the markers for the NSRulerView. You must install the accessory view into the ruler using NSRulerView's setAccessoryView method. To set the markers, use rulerMarkersForTextView to get the markers needed and then send setMarkers to the ruler.

See Also: horizontalRulerView (NSScrollView)



rulerMarkersForTextView

public NSArray rulerMarkersForTextView( NSTextView aTextView, NSParagraphStyle paraStyle, NSRulerView aRulerView)

Returns the NSRulerMarkers for aRulerView in aTextView, based on paraStyle. These markers represent such things as left and right margins, first-line indent, and tab stops. You can set these markers immediately with NSRulerView's setMarkers method.

This method is invoked automatically by the NSTextView object using the layout manager. You should rarely need to invoke it; but you can override it to add new kinds of markers or otherwise customize ruler support.

See Also: rulerAccessoryViewForTextView



setBackgroundLayoutEnabled

public void setBackgroundLayoutEnabled(boolean flag)

Sets whether the receiver generates glyphs and lays them out when the application's run loop is idle according to flag.

See Also: backgroundLayoutEnabled



setCharacterIndexForGlyphAtIndex

public void setCharacterIndexForGlyphAtIndex( int charIndex, int glyphIndex)

Maps the character at charIndex to the glyph at glyphIndex.

This method is for use by the glyph generation mechanism, and doesn't perform any invalidation or generation of the glyphs or layout. You should never directly invoke this method.

See Also: characterIndexForGlyphAtIndex, characterRangeForGlyphRange, glyphRangeForCharacterRange



setDelegate

public void setDelegate(Object anObject)

Sets the receiver's delegate to anObject.

See Also: delegate



setDrawsOutsideLineFragmentForGlyphAtIndex

public void setDrawsOutsideLineFragmentForGlyphAtIndex( boolean flag, int glyphIndex)

Sets according to flag whether the glyph at glyphIndex exceeds the bounds of the line fragment where it's laid out. This can happen when text is set at a fixed line height. For example, if the user specifies a fixed line height of 12 points and sets the font size to 24 points, the glyphs will exceed their layout rectangles.

This method is used by the layout mechanism; you should never invoke it directly.

See Also: drawsOutsideLineFragmentForGlyphAtIndex



setExtraLineFragmentRect

public void setExtraLineFragmentRect( NSRect aRect, NSRect usedRect, NSTextContainer aTextContainer)

Sets a line fragment rectangle for displaying an empty last line in a body of text. aRect is the rectangle to set, and aTextContainer is the NSTextContainer where the rectangle should be laid out. usedRect indicates where the insertion point is drawn.

This method is used by the layout mechanism; you should never invoke it directly.

See Also: extraLineFragmentRect, extraLineFragmentUsedRect, textContainers



setHyphenationFactor

public void setHyphenationFactor(float factor)

Sets the threshold as to when hyphenation will be done. factor is in the range of 0.0 - 1.0. Whenever (width of the real contents of the line) / (the line fragment width) is below factor, hyphenation will be attempted when laying out the line. By default, the value is 0.0, meaning hyphenation is off. A factor of 1.0 causes hyphenation to be attempted always. Note that hyphenation will slow down text layout and increase memory usage, so it should be used sparingly.

See Also: hyphenationFactor



setGlyphAttributeForGlyphAtIndex

public void setGlyphAttributeForGlyphAtIndex( int attributeTag, int anInt, int glyphIndex)

Sets a custom attribute value for the glyph at glyphIndex. attributeTag identifies the custom attribute, and anInt is its new value.

Subclasses that define their own custom attributes must override this method and provide their own storage for the attribute values. Non-negative tags are reserved ; you can define your own attributes with negative tags and set values using this method.

This method doesn't perform glyph generation or layout. The glyph at glyphIndex must already have been generated.

See Also: glyphAttributeForGlyphAtIndex



setLineFragmentRectForGlyphAtIndex

public void setLineFragmentRectForGlyphAtIndex( NSRect fragmentRect, NSRange glyphRange, NSRect usedRect)

Sets the line fragment rectangle where the glyphs in glyphRange are laid out to fragmentRect. The text container must be specified first with setTextContainerForGlyphRange, and the exact positions of the glyphs must be set after the line fragment rectangle with setLocationForStartOfGlyphRange. usedRect indicates the portion of fragmentRect, in the NSTextContainer's coordinate system, that actually contains glyphs or other marks that are drawn (including the text container's line fragment padding). usedRect must be equal to or contained within fragmentRect.

This method is used by the layout mechanism; you should never invoke it directly.

See Also: lineFragmentRectForGlyphAtIndex, lineFragmentUsedRectForGlyphAtIndex



setLocationForStartOfGlyphRange

public void setLocationForStartOfGlyphRange( NSPoint aPoint, NSRange glyphRange)

Sets the location where the glyphs in glyphRange are laid out to aPoint, which is expressed relative to the origin of the line fragment rectangle for glyphRange. glyphRange defines a series of glyphs that can be displayed with a single PostScript show operation (a nominal range). Setting the location for a series of glyphs implies that the glyphs preceding it can't be included in a single show operation.

Before setting the location for a glyph range, you must specify the text container with setTextContainerForGlyphRange and the line fragment rectangle with setLineFragmentRectForGlyphAtIndex.

This method is used by the layout mechanism; you should never invoke it directly.

See Also: rangeOfNominallySpacedGlyphsContainingIndex



setNotShownForGlyphAtIndex

public void setNotShownForGlyphAtIndex( boolean flag, int glyphIndex)

Sets according to flag whether the glyph at glyphIndex is one that isn't shown. For example, a tab or newline character doesn't leave any marks; it just indicates where following glyphs are laid out. Raises a RangeException if glyphIndex is out of bounds.

This method is used by the layout mechanism; you should never invoke it directly.

See Also: notShownAttributeForGlyphAtIndex



setShowsControlCharacters

public void setShowsControlCharacters(boolean flag)

Controls whether the receiver makes control characters visible in layout where possible. If flag is true, it substitutes visible glyphs for control characters if the font and script support it; if flag is false it doesn't.

See Also: setShowsInvisibleCharacters, showsControlCharacters



setShowsInvisibleCharacters

public void setShowsInvisibleCharacters(boolean flag)

Controls whether the receiver makes whitespace and other typically nonvisible characters visible in layout where possible. If flag is true, it substitutes visible glyphs for invisible characters if the font and script support it; if flag is false it doesn't.

See Also: setShowsControlCharacters, showsInvisibleCharacters



setTextContainerForGlyphRange

public void setTextContainerForGlyphRange( NSTextContainer aTextContainer, NSRange glyphRange)

Sets to aTextContainer the NSTextContainer where the glyphs in glyphRange are laid out. You specify the layout within the container with the setLineFragmentRectForGlyphAtIndex and setLocationForStartOfGlyphRange methods.

This method is used by the layout mechanism; you should never invoke it directly.

See Also: textContainerForGlyphAtIndex



setTextStorage

public void setTextStorage(NSTextStorage textStorage)

Sets the receiver's NSTextStorage to textStorage. This method is invoked automatically when you add an NSLayoutManager to an NSTextStorage object; you should never need to invoke it directly, but might want to override it. If you want to replace the NSTextStorage for an established group of text-system objects containing the receiver, use replaceTextStorage.

See Also: addLayoutManager (NSTextStorage)



setUsesScreenFonts

public void setUsesScreenFonts(boolean flag)

Sets according to flag whether the receiver calculates layout and displays text using screen fonts when possible.

See Also: usesScreenFonts, substituteFontForFont



showAttachmentCell

public void showAttachmentCell( NSCell cell, NSRect rect, int attachmentIndex)

Description forthcoming.

showsControlCharacters

public boolean showsControlCharacters()

Returns true if the receiver substitutes visible glyphs for control characters if the font and script support it, false if it doesn't.

See Also: showsInvisibleCharacters, setShowsControlCharacters



showsInvisibleCharacters

public boolean showsInvisibleCharacters()

Returns true if the receiver substitutes visible glyphs for invisible characters if the font and script support it, false if it doesn't.

See Also: showsControlCharacters, setShowsInvisibleCharacters



substituteFontForFont

public NSFont substituteFontForFont(NSFont originalFont)

Returns a screen font suitable for use in place of originalFont, or simply returns originalFont if a screen font can't be used or isn't available. A screen font can be substituted if the receiver is set to use screen fonts and if no NSTextView associated with the receiver are scaled or rotated.

See Also: usesScreenFonts



textContainerChangedGeometry

public void textContainerChangedGeometry(NSTextContainer aTextContainer)

Invalidates the layout information, and possibly glyphs, for aTextContainer and all subsequent NSTextContainers. This method is invoked automatically by other components of the text system; you should rarely need to invoke it directly. Subclasses of NSTextContainer, however, must invoke this method any time their size of shape changes (a text container that dynamically adjusts its shape to wrap text around placed graphics, for example, must do so when a graphic is added, moved, or removed).

textContainerChangedTextView

public void textContainerChangedTextView(NSTextContainer aTextContainer)

Updates information needed to manage NSTextView objects. This method is invoked automatically by other components of the text system; you should rarely need to invoke it directly.

textContainerForGlyphAtIndex

public NSTextContainer textContainerForGlyphAtIndex( int glyphIndex, NSMutableRange effectiveGlyphRange)

Returns the NSTextContainer where the glyph at glyphIndex is laid out. If non-null, effectiveGlyphRange is set to the range for all glyphs laid out in that text container.

Performs glyph generation and layout if needed.

See Also: setTextContainerForGlyphRange



textContainers

public NSArray textContainers()

Returns the receiver's NSTextContainers.

See Also: addTextContainer, insertTextContainerAtIndex, removeTextContainerAtIndex



textStorage

public NSTextStorage textStorage()

Returns the receiver's NSTextStorage.

See Also: setTextStorage, replaceTextStorage



textStorageChanged

public void textStorageChanged( NSTextStorage aTextStorage, int mask, NSRange range, int lengthChange, NSRange invalidatedCharRange)

Invalidates glyph and layout information for a portion of text in aTextStorage. This message is sent from NSTextStorage's processEditing method to indicate that its characters or attributes have been changed. This method invalidates glyphs and layout for the affected characters, and performs a soft invalidation of the layout information for all subsequent characters. mask specifies the nature of the changes. Its value is made by combining these options with the C bitwise OR operator:
Option Meaning
TextStorageEditedAttributes Attributes were added, removed, or changed.
TextStorageEditedCharacters Characters were added, removed, or replaced.

range indicates the extent of characters resulting from the edits. If the TextStorageEditedCharacters bit of mask is set, lengthChange gives the number of characters added to or removed from the original range (otherwise its value is irrelevant). For example, after replacing "The" with "Several" to produce the string "Several files couldn't be saved", range is {0, 7} and lengthChange is 4. The receiver uses this information to update its character-to-glyph mapping and to update the selection range based on the change.

invalidatedRange represents the range of characters affected after attributes have been fixed. For example, deleting a paragraph separator character invalidates the layout information for all characters in the paragraphs that precede and follow the separator.

textStorageChanged messages are sent in a series to each NSLayoutManager associated with the text storage object, so the NSLayoutManagers receiving them shouldn't edit aTextStorage. If one of them does, the range, lengthChange, and invalidatedRange arguments will be incorrect for all following NSLayoutManagers that receive the message.

See Also: invalidateLayoutForCharacterRange



textViewForBeginningOfSelection

public NSTextView textViewForBeginningOfSelection()

Returns the NSTextView containing the first glyph in the selection, or null if there's no selection or there isn't enough layout information to determine the text view.

underlineGlyphRange

public void underlineGlyphRange( NSRange glyphRange, int underlineType, NSRect lineRect, NSRange lineGlyphRange, NSPoint containerOrigin)

Calculates and draws underlining for the glyphs in glyphRange, which must belong to a single line fragment rectangle (as returned by lineFragmentRectForGlyphAtIndex). underlineType indicates the style of underlining to draw; NSLayoutManager accepts only NSAttributedString.SingleUnderlineStyle, but subclasses can define their own underline styles. lineRect is the line fragment rectangle containing the glyphs to draw underlining for, and lineGlyphRange is the range of all glyphs within that line fragment rectangle. containerOrigin is the origin of the line fragment rectangle's NSTextContainer in its NSTextView.

This method determines which glyphs actually need to be underlined based on underlineType. With NSAttributedString.SingleUnderlineStyle, for example, leading and trailing whitespace isn't underlined, but whitespace between visible glyphs is. A potential word-underline style would omit underlining on any whitespace. After determining which glyphs to draw underlining on, this method invokes drawUnderlineForGlyphRange for each contiguous range of glyphs that requires it.

See Also: textContainerForGlyphAtIndex, textContainerOrigin (NSTextView)



usedRectForTextContainer

public NSRect usedRectForTextContainer(NSTextContainer aTextContainer)

Returns the bounding rectangle for the glyphs laid out in aTextContainer, which tells "how full" it is. This rectangle is given in the aTextContainer's coordinate system.

See Also: containerSize (NSTextContainer)



usesScreenFonts

public boolean usesScreenFonts()

Returns true if the receiver calculates layout and displays text using screen fonts when possible, false otherwise.

See Also: setUsesScreenFonts, substituteFontForFont




Methods Implemented By the Delegate


layoutManagerDidCompleteLayoutForTextContainer

public abstract void layoutManagerDidCompleteLayoutForTextContainer( NSLayoutManager aLayoutManager, NSTextContainer aTextContainer, boolean flag)

Informs the delegate that aLayoutManager has finished laying out text in aTextContainer. aTextContainer is null if there aren't enough containers to hold all the text; the delegate can use this information as a cue to add another container. If flag is true, aLayoutManager is finished laying out its text-this also means that aTextContainer is the final text container used by the layout manager. Delegates can use this information to show an indicator or background or to enable or disable a button that forces immediate layout of text.

layoutManagerDidInvalidateLayout

public abstract void layoutManagerDidInvalidateLayout(NSLayoutManager aLayoutManager)

Informs the delegate that aLayoutManager has invalidated layout information (not glyph information). This method is invoked only when layout was complete and then became invalidated for some reason. Delegates can use this information to show an indicator or background layout or to enable a button that forces immediate layout of text.


Table of Contents