Up

NSLayoutManager

Authors

Jonathan Gapen( jagapen@smithlab.chem.wisc.edu )
Michael Hanni( mhanni@sprintmail.com )
Richard Frith-Macdonald( rfm@gnu.org )
The text layout manager class

Copyright: (C) 1999 Free Software Foundation, Inc.

Contents -

  1. Software documentation for the NSLayoutManager class
  2. Software documentation for the NSLayoutManager(NSTextViewSupport) category
  3. Software documentation for the NSObject(NSLayoutManagerDelegate) informal protocol

Software documentation for the NSLayoutManager class

NSLayoutManager : NSObject

Declared in:
AppKit/NSLayoutManager.h
Standards:

A layout manager handles layout and glyph management for a text storage. A glyph is a symbol draewn to a display, and while there is usually a one to one correspondence between glyphs and characters in the text storage, that is no always the case.

Sometimes a group of characters (a unicode composed character sequence) can represent a single glyph, sometimes a single unicode character is represented by multiple glyphs.

eg. The text storage may contain the unichar o-umlaut and the glyph stream could contain the two glyphs "o" and umlaut. In this case, we would have two glyphs, with different glyph indexes, both corresponding to a single character index.

Instance variables

_backgroundLayout

@public _backgroundLayout;

_beganEditing

@public _beganEditing;

_cachedFont

@public _cachedFont;

_cachedFontCharRange

@public _cachedFontCharRange;

_cachedLocation

@public _cachedLocation;

_cachedLocationGlyphIndex

@public _cachedLocationGlyphIndex;

_cachedLocationNominalGlyphRange

@public _cachedLocationNominalGlyphRange;

_cachedRectArray

@public _cachedRectArray;

_cachedRectArrayCapacity

@public _cachedRectArrayCapacity;

_chunkIndex

@public _chunkIndex;

_currentGlyphs

@public _currentGlyphs;

_deferredDisplayCharRange

@public _deferredDisplayCharRange;

_delegate

@public _delegate;

_displayInvalidationDisableStack

@public _displayInvalidationDisableStack;

_extraLineFragmentContainer

@public _extraLineFragmentContainer;

_extraLineFragmentRect

@public _extraLineFragmentRect;

_extraLineFragmentUsedRect

@public _extraLineFragmentUsedRect;

_finished

@public _finished;

_firstTextView

@public _firstTextView;

_firstUnlaidCharIndex

@public _firstUnlaidCharIndex;

_firstUnlaidGlyphIndex

@public _firstUnlaidGlyphIndex;

_glyphBuffer

@public _glyphBuffer;

_glyphBufferSize

@public _glyphBufferSize;

_glyphData

@public _glyphData;

_glyphGaps

@public _glyphGaps;

_glyphGenerator

@public _glyphGenerator;

_glyphIndex

@public _glyphIndex;

_glyphOffset

@public _glyphOffset;

_hyphenationFactor

@public _hyphenationFactor;

_isSynchronizingDelegates

@public _isSynchronizingDelegates;

_isSynchronizingFlags

@public _isSynchronizingFlags;

_newlyFilledGlyphRange

@public _newlyFilledGlyphRange;

_showsControlChars

@public _showsControlChars;

_showsInvisibleChars

@public _showsInvisibleChars;

_textContainers

@public _textContainers;

_textContainersCount

@public _textContainersCount;

_textStorage

@public _textStorage;

_textViewResizeDisableStack

@public _textViewResizeDisableStack;

_typesetter

@public _typesetter;

_usesScreenFonts

@public _usesScreenFonts;
Method summary

addTextContainer:

- (void) addTextContainer: (NSTextContainer*)obj;

Adds a container to the layout manager.

backgroundLayoutEnabled

- (BOOL) backgroundLayoutEnabled;

Returns flag to say if text should get laid out in the background when the run lopp is idle.

boundingRectForGlyphRange:inTextContainer:

- (NSRect) boundingRectForGlyphRange: (NSRange)glyphRange inTextContainer: (NSTextContainer*)aTextContainer;

Description forthcoming.

characterIndexForGlyphAtIndex:

- (unsigned) characterIndexForGlyphAtIndex: (unsigned)glyphIndex;

Returns the character index for the specified glyphIndex.
If there are invalidated ranges (gaps) in the glyph stream before glyphIndex, this will cause glyph generation to fill them.

characterRangeForGlyphRange:actualGlyphRange:

- (NSRange) characterRangeForGlyphRange: (NSRange)glyphRange actualGlyphRange: (NSRange*)actualGlyphRange;

Returns the range of characters that generated the glyphs in glyphRange. Sets actualGlyphRange (if non-nul) to the range of glyphs generated by those characters.

delegate

- (id) delegate;

Description forthcoming.

deleteGlyphsInRange:

- (void) deleteGlyphsInRange: (NSRange)aRange;

Removes all the glyphs in aRange from the glyph stream, causing all subsequent glyphs to have their index decreased by aRange.length

drawsOutsideLineFragmentForGlyphAtIndex:

- (BOOL) drawsOutsideLineFragmentForGlyphAtIndex: (unsigned)glyphIndex;

Description forthcoming.

extraLineFragmentRect

- (NSRect) extraLineFragmentRect;

Description forthcoming.

extraLineFragmentTextContainer

- (NSTextContainer*) extraLineFragmentTextContainer;

Description forthcoming.

extraLineFragmentUsedRect

- (NSRect) extraLineFragmentUsedRect;

Description forthcoming.

firstUnlaidCharacterIndex

- (unsigned) firstUnlaidCharacterIndex;

Description forthcoming.

firstUnlaidGlyphIndex

- (unsigned) firstUnlaidGlyphIndex;

Description forthcoming.

getFirstUnlaidCharacterIndex:glyphIndex:

- (void) getFirstUnlaidCharacterIndex: (unsigned*)charIndex glyphIndex: (unsigned*)glyphIndex;

Description forthcoming.

getGlyphs:range:

- (unsigned) getGlyphs: (NSGlyph*)glyphArray range: (NSRange)glyphRange;

This returns a nul terminated array of glyphs... so glyphArray should contain space for glyphRange.length+1 glyphs.

glyphAtIndex:

- (NSGlyph) glyphAtIndex: (unsigned)index;

Returns the glyph at the specified index .
Causes any gaps (areas where glyphs have been invalidated) before this index to be re-filled.
Raises an exception if the index is out of range.

glyphAtIndex:isValidIndex:

- (NSGlyph) glyphAtIndex: (unsigned)index isValidIndex: (BOOL*)flag;

Returns the glyph at the specified index .
Causes any gaps (areas where glyphs have been invalidated) before this index to be re-filled.
Sets the flag to indicate whether the index was found... if it wasn't the returned glyph is meaningless.

glyphIndexForPoint:inTextContainer:

- (unsigned) glyphIndexForPoint: (NSPoint)aPoint inTextContainer: (NSTextContainer*)aTextContainer;

Description forthcoming.

glyphIndexForPoint:inTextContainer:fractionOfDistanceThroughGlyph:

- (unsigned) glyphIndexForPoint: (NSPoint)aPoint inTextContainer: (NSTextContainer*)aTextContainer fractionOfDistanceThroughGlyph: (float*)partialFraction;

Description forthcoming.

glyphRangeForBoundingRect:inTextContainer:

- (NSRange) glyphRangeForBoundingRect: (NSRect)aRect inTextContainer: (NSTextContainer*)aTextContainer;

Description forthcoming.

glyphRangeForBoundingRectWithoutAdditionalLayout:inTextContainer:

- (NSRange) glyphRangeForBoundingRectWithoutAdditionalLayout: (NSRect)bounds inTextContainer: (NSTextContainer*)aTextContainer;

Description forthcoming.

glyphRangeForCharacterRange:actualCharacterRange:

- (NSRange) glyphRangeForCharacterRange: (NSRange)charRange actualCharacterRange: (NSRange*)actualCharRange;

Returns the range of glyphs that are generated from the characters in charRange. Sets actualCharRange (if non-nul) to the full range of characters which generated those glyphs.

glyphRangeForTextContainer:

- (NSRange) glyphRangeForTextContainer: (NSTextContainer*)aTextContainer;

Description forthcoming.

init

- (id) init;
This is a designated initialiser for the class.

Sets up this instance. We should in future find a glyph generator and a typesetter to use with glyphs management, but for now we just set up the glyph storage.

insertGlyph:atGlyphIndex:characterIndex:

- (void) insertGlyph: (NSGlyph)aGlyph atGlyphIndex: (unsigned)glyphIndex characterIndex: (unsigned)charIndex;

Used by the internal glyph generation system to insert aGlyph into the glyph stream athe the specified glyphIndex and charIndex.
Invariants...
a) Glyph chunks are ordered sequentially from zero by character index.
b) Glyph chunks are ordered sequentially from zero by glyph index.
c) Adjacent glyphs may share a character index.

insertTextContainer:atIndex:

- (void) insertTextContainer: (NSTextContainer*)aTextContainer atIndex: (unsigned)index;

Inserts a new text container at index.

intAttribute:forGlyphAtIndex:

- (int) intAttribute: (int)attribute forGlyphAtIndex: (unsigned)glyphIndex;

Returns the value for the attribute at the glyphIndex.

invalidateDisplayForCharacterRange:

- (void) invalidateDisplayForCharacterRange: (NSRange)aRange;

Causes redisplay of aRange, but does not lose the alyout information.

invalidateDisplayForGlyphRange:

- (void) invalidateDisplayForGlyphRange: (NSRange)aRange;

Causes redisplay of aRange, but does not lose the alyout information.

invalidateGlyphsForCharacterRange:changeInLength:actualCharacterRange:

- (void) invalidateGlyphsForCharacterRange: (NSRange)aRange changeInLength: (int)lengthChange actualCharacterRange: (NSRange*)actualRange;

This determines the glyph range corresponding to aRange and marks the glyphs as invalid. It adjusts the character locations of all glyphs beyond this by lengthChange. It returns the actual character range corresponding to the invalidated glyphs if actualRange is non-nul.

invalidateLayoutForCharacterRange:isSoft:actualCharacterRange:

- (void) invalidateLayoutForCharacterRange: (NSRange)aRange isSoft: (BOOL)flag actualCharacterRange: (NSRange*)actualRange;

This invalidates glyph positions for all glyphs corresponding to the specified character range.
If flag is YES then the layout information needs to be redone from scratch, but if it's NO, the layout manager may try to optimise layout from the old information.
If actualRange is non-nul, returns the actual range invalidated.

lineFragmentRectForGlyphAtIndex:effectiveRange:

- (NSRect) lineFragmentRectForGlyphAtIndex: (unsigned)glyphIndex effectiveRange: (NSRange*)lineFragmentRange;

Description forthcoming.

lineFragmentUsedRectForGlyphAtIndex:effectiveRange:

- (NSRect) lineFragmentUsedRectForGlyphAtIndex: (unsigned)glyphIndex effectiveRange: (NSRange*)lineFragmentRange;

Description forthcoming.

locationForGlyphAtIndex:

- (NSPoint) locationForGlyphAtIndex: (unsigned)glyphIndex;

Description forthcoming.

notShownAttributeForGlyphAtIndex:

- (BOOL) notShownAttributeForGlyphAtIndex: (unsigned)glyphIndex;

Description forthcoming.

numberOfGlyphs

- (unsigned) numberOfGlyphs;

Returns the number of glyphs in the glyph stream... causing generation of new glyphs to fill gaps and to extend the stream until all characters in the text storage have had glyphs generated.

rangeOfNominallySpacedGlyphsContainingIndex:

- (NSRange) rangeOfNominallySpacedGlyphsContainingIndex: (unsigned)glyphIndex;

Description forthcoming.

rectArrayForCharacterRange:withinSelectedCharacterRange:inTextContainer:rectCount:

- (NSRect*) rectArrayForCharacterRange: (NSRange)charRange withinSelectedCharacterRange: (NSRange)selChareRange inTextContainer: (NSTextContainer*)aTextContainer rectCount: (unsigned*)rectCount;

Description forthcoming.

rectArrayForGlyphRange:withinSelectedGlyphRange:inTextContainer:rectCount:

- (NSRect*) rectArrayForGlyphRange: (NSRange)glyphRange withinSelectedGlyphRange: (NSRange)selectedGlyphRange inTextContainer: (NSTextContainer*)aTextContainer rectCount: (unsigned*)rectCount;

Description forthcoming.

removeTextContainerAtIndex:

- (void) removeTextContainerAtIndex: (unsigned)index;

Removes the text container at index.

replaceGlyphAtIndex:withGlyph:

- (void) replaceGlyphAtIndex: (unsigned)index withGlyph: (NSGlyph)newGlyph;

Replaces the glyph at index with newGlyph without changing character index or other attributes.

replaceTextStorage:

- (void) replaceTextStorage: (NSTextStorage*)newTextStorage;

Replaces the test storage with a new one.
Takes care (since layout managers are owned by text storages) not to get self deallocated.

setAttachmentSize:forGlyphRange:

- (void) setAttachmentSize: (NSSize)attachmentSize forGlyphRange: (NSRange)glyphRange;

Description forthcoming.

setBackgroundLayoutEnabled:

- (void) setBackgroundLayoutEnabled: (BOOL)flag;

Sets flag to say if text should get laid out in the background when the run lopp is idle.

setCharacterIndex:forGlyphAtIndex:

- (void) setCharacterIndex: (unsigned)charIndex forGlyphAtIndex: (unsigned)glyphIndex;

Sets the glyph at glyphIndex to correspond to the character at charIndex.

setDelegate:

- (void) setDelegate: (id)aDelegate;

Description forthcoming.

setDrawsOutsideLineFragment:forGlyphAtIndex:

- (void) setDrawsOutsideLineFragment: (BOOL)flag forGlyphAtIndex: (unsigned)glyphIndex;

Description forthcoming.

setExtraLineFragmentRect:usedRect:textContainer:

- (void) setExtraLineFragmentRect: (NSRect)aRect usedRect: (NSRect)usedRect textContainer: (NSTextContainer*)aTextContainer;

Description forthcoming.

setIntAttribute:value:forGlyphAtIndex:

- (void) setIntAttribute: (int)attribute value: (int)anInt forGlyphAtIndex: (unsigned)glyphIndex;

This method modifies the attributes of an existing glyph at glyphIndex. It only deals with the existing attribute types... if you subclass and add new attributed, you must replace this method with one which can store your new attributes.

setLineFragmentRect:forGlyphRange:usedRect:

- (void) setLineFragmentRect: (NSRect)fragmentRect forGlyphRange: (NSRange)glyphRange usedRect: (NSRect)usedRect;

Description forthcoming.

setLocation:forStartOfGlyphRange:

- (void) setLocation: (NSPoint)aPoint forStartOfGlyphRange: (NSRange)glyphRange;

Description forthcoming.

setNotShownAttribute:forGlyphAtIndex:

- (void) setNotShownAttribute: (BOOL)flag forGlyphAtIndex: (unsigned)glyphIndex;

Description forthcoming.

setShowsControlCharacters:

- (void) setShowsControlCharacters: (BOOL)flag;

Description forthcoming.

setShowsInvisibleCharacters:

- (void) setShowsInvisibleCharacters: (BOOL)flag;

Description forthcoming.

setTextContainer:forGlyphRange:

- (void) setTextContainer: (NSTextContainer*)aTextContainer forGlyphRange: (NSRange)glyphRange;

Description forthcoming.

setTextStorage:

- (void) setTextStorage: (NSTextStorage*)aTextStorage;

Sets the text storage for the layout manager. Use -replaceTextStorage: instead as a rule. - this method is really more for internal use by the text system. Invalidates the entire layout (should it]

setUsesScreenFonts:

- (void) setUsesScreenFonts: (BOOL)flag;

Description forthcoming.

showsControlCharacters

- (BOOL) showsControlCharacters;

Description forthcoming.

showsInvisibleCharacters

- (BOOL) showsInvisibleCharacters;

Description forthcoming.

substituteFontForFont:

- (NSFont*) substituteFontForFont: (NSFont*)originalFont;

Description forthcoming.

textContainerChangedGeometry:

- (void) textContainerChangedGeometry: (NSTextContainer*)aContainer;

Invalidates the layout of all glyphs in aContainer and all containers following it.

textContainerChangedTextView:

- (void) textContainerChangedTextView: (NSTextContainer*)aContainer;

Notifies the layout manager that one of its text containers has changed its view and an update of the display is needed.

textContainerForGlyphAtIndex:effectiveRange:

- (NSTextContainer*) textContainerForGlyphAtIndex: (unsigned)glyphIndex effectiveRange: (NSRange*)effectiveRange;

Returns the text container in which the glyph at glyphIndex is laid. If effectiveRange is non-nul, returns the range of all glyphs in the container.

textContainers

- (NSArray*) textContainers;

Return the text containers

textStorage

- (NSTextStorage*) textStorage;

Returns the text storage for this layout manager.

textStorage:edited:range:changeInLength:invalidatedRange:

- (void) textStorage: (NSTextStorage*)aTextStorage edited: (unsigned)mask range: (NSRange)newCharRange changeInLength: (int)lengthChange invalidatedRange: (NSRange)invalidatedRange;

This method is used to handle an editing change to aTextStorage. The mask value indicates whether characters or attribuytes or both have changed.
If characters have not changed, the lengthChange argument is ignored.
The newCharRange is the effected range currently in the storage, while invalidatedRange is the original range effected.

usedRectForTextContainer:

- (NSRect) usedRectForTextContainer: (NSTextContainer*)container;

Description forthcoming.

usesScreenFonts

- (BOOL) usesScreenFonts;

Description forthcoming.

Software documentation for the NSLayoutManager(NSTextViewSupport) category

NSLayoutManager(NSTextViewSupport)

Declared in:
AppKit/NSLayoutManager.h
Standards:

Description forthcoming.

Method summary

_charIndexForInsertionPointMovingFromY:bestX:up:textContainer:

- (unsigned) _charIndexForInsertionPointMovingFromY: (float)position bestX: (float)wanted up: (BOOL)upFlag textContainer: (NSTextContainer*)tc;

Description forthcoming.

drawBackgroundForGlyphRange:atPoint:

- (void) drawBackgroundForGlyphRange: (NSRange)glyphsToShow atPoint: (NSPoint)origin;

Description forthcoming.

drawGlyphsForGlyphRange:atPoint:

- (void) drawGlyphsForGlyphRange: (NSRange)glyphsToShow atPoint: (NSPoint)origin;

Description forthcoming.

drawUnderlineForGlyphRange:underlineType:baselineOffset:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

- (void) drawUnderlineForGlyphRange: (NSRange)glyphRange underlineType: (int)underlineVal baselineOffset: (float)baselineOffset lineFragmentRect: (NSRect)lineRect lineFragmentGlyphRange: (NSRange)lineGlyphRange containerOrigin: (NSPoint)containerOrigin;

Description forthcoming.

firstTextView

- (NSTextView*) firstTextView;

Description forthcoming.

hyphenationFactor

- (float) hyphenationFactor;

Description forthcoming.

layoutManagerOwnsFirstResponderInWindow:

- (BOOL) layoutManagerOwnsFirstResponderInWindow: (NSWindow*)window;

Description forthcoming.

rulerAccessoryViewForTextView:paragraphStyle:ruler:enabled:

- (NSView*) rulerAccessoryViewForTextView: (NSTextView*)view paragraphStyle: (NSParagraphStyle*)style ruler: (NSRulerView*)ruler enabled: (BOOL)isEnabled;

Description forthcoming.

rulerMarkersForTextView:paragraphStyle:ruler:

- (NSArray*) rulerMarkersForTextView: (NSTextView*)view paragraphStyle: (NSParagraphStyle*)style ruler: (NSRulerView*)ruler;

Description forthcoming.

setHyphenationFactor:

- (void) setHyphenationFactor: (float)factor;

Description forthcoming.

textViewForBeginningOfSelection

- (NSTextView*) textViewForBeginningOfSelection;

Description forthcoming.

underlineGlyphRange:underlineType:lineFragmentRect:lineFragmentGlyphRange:containerOrigin:

- (void) underlineGlyphRange: (NSRange)glyphRange underlineType: (int)underlineVal lineFragmentRect: (NSRect)lineRect lineFragmentGlyphRange: (NSRange)lineGlyphRange containerOrigin: (NSPoint)containerOrigin;

Description forthcoming.

Software documentation for the NSObject(NSLayoutManagerDelegate) informal protocol

NSObject(NSLayoutManagerDelegate)

Declared in:
AppKit/NSLayoutManager.h
Standards:

Description forthcoming.

Method summary

layoutManager:didCompleteLayoutForTextContainer:atEnd:

- (void) layoutManager: (NSLayoutManager*)layoutManager didCompleteLayoutForTextContainer: (NSTextContainer*)textContainer atEnd: (BOOL)layoutFinishedFlag;

Description forthcoming.

layoutManagerDidInvalidateLayout:

- (void) layoutManagerDidInvalidateLayout: (NSLayoutManager*)sender;

Description forthcoming.


Up