DTRichTextEditorView Class Reference

Inherits from	DTAttributedTextView : UIScrollView
Conforms to	DTRichTextEditorStandardEditActions UITextInput UITextInputTraits
Declared in	DTRichTextEditorView.h

Overview

DTRichTextEditorView is a subclass of UIScrollView and offers rich text edtiting capabilities. It has a single content view of type DTRichTextEditorContentView which is repsonsible for displaying the rich text.

The Attributes category contains methods to support custom HTML attributes.

The Ranges category enhances DTRichTextEditorView with methods for working with text ranges.

The Dictation category contains methods to support dictation input.

The DTCore Text Category features enhancements for DTRichTextEditorView to interact with DTCoreText internal information.

The Manipulation category enhances DTRichTextEditorView with useful text format manipulation methods.

The Ranges category enhances DTRichTextEditorView with methods for retrieving CSS-like style information.

Tasks

Properties

attributedText

The current attributedText displayed in the receiver

@property (nonatomic, copy) NSAttributedString *attributedText

Declared In

DTRichTextEditorView.h

baseURL

Override for the base URL.

@property (nonatomic, copy) NSURL *baseURL

Discussion

This property represents part of the textDefaults. Setting those will set this property and vice versa.

Declared In

DTRichTextEditorView.h

canInteractWithPasteboard

Property to enable copy/paste support. If enabled the user can paste text into DTRichTextEditorView or copy text to the pasteboard.

@property (nonatomic, assign) BOOL canInteractWithPasteboard

Declared In

DTRichTextEditorView.h

defaultFontFamily

Override for the default font family.

@property (nonatomic, copy) NSString *defaultFontFamily

Discussion

This property represents part of the textDefaults. Setting those will set this property and vice versa.

Declared In

DTRichTextEditorView.h

defaultFontSize

Override for the default font size.

@property (nonatomic, assign) CGFloat defaultFontSize

Discussion

This property represents part of the textDefaults. Setting those will set this property and vice versa.

Declared In

DTRichTextEditorView.h

editable

Specifies that the receiver can be edited. That means that on tapping it it becomes first responder and shows the current input view (keyboard). If it is not editable then dragging the finger over the view highlights entire words and does not show the selection dragging handles.

@property (nonatomic, getter=isEditable) BOOL editable

Declared In

DTRichTextEditorView.h

editing

Specifies that the receiver is in an editing state. That means that the editor is first responder, and an inputView(usually the system keyboard) and cursor are showing. To programmatically enter an editing state, call becomeFirstResponder on the editor object when isEditable = YES(the default). To programmatically end editing, call resignFirstResponder.

@property (nonatomic, assign, readonly, getter=isEditing) BOOL editing

Declared In

DTRichTextEditorView.h

editorViewDelegate

An editor view delegate responds to editing-related messages from the editor view. You can use the delegate to track changes to the text itself and to the current selection.

@property (nonatomic, assign) id<DTRichTextEditorViewDelegate> editorViewDelegate

Declared In

DTRichTextEditorView.h

inputAccessoryView

Overrides the UIResponder input accessory view to be settable. The accessory gets shown riding on top of the inputView when input is possible.

@property (retain, readwrite) UIView *inputAccessoryView

Declared In

DTRichTextEditorView.h

maxImageDisplaySize

Override for the maximum image display size.

@property (nonatomic, assign) CGSize maxImageDisplaySize

Discussion

This property represents part of the textDefaults. Setting those will set this property and vice versa.

Declared In

DTRichTextEditorView.h

overrideInsertionAttributes

Temporary storage for typing attributes if there is no range to apply them to, e.g. for a zero-length selection. To retrieve the current typing attributes you should first inspect this property and if it is nil retrieve the typingAttributesForRange: for the current selected text range.

@property (nonatomic, retain) NSDictionary *overrideInsertionAttributes

Declared In

DTRichTextEditorView+Manipulation.h

replaceParagraphsWithLineFeeds

If this property is YES then all typed enters are replaced with the Line Feed (LF) character.

@property (nonatomic, assign) BOOL replaceParagraphsWithLineFeeds

Discussion

Warning: This causes all text to end up in a single paragraph and all paragraph-level styles are going to affect all of the text. It therefore severely affects the display performance. We recommend you don’t activate this if you don’t want spaces between paragraphs but rather set the paragraph spacing to zero via a custom style set via textDefaults.

Declared In

DTRichTextEditorView.h

textDefaults

The default options to be used for text. See the options parameter of DTHTMLAttributedStringBuilder for individual options.

@property (nonatomic, retain) NSDictionary *textDefaults

Discussion

If one of these properties is set then it is used instead of the value contained in textDefaults:

maxImageDisplaySize
defaultFontFamily
defaultFontSize
baseURL;
textSizeMultiplier;

NOTE: Changing these defaults does not affect the current NSAttributedString. They are used when calling setHTMLString.

Declared In

DTRichTextEditorView.h

textSizeMultiplier

Override for the text size multiplier.

@property (nonatomic, assign) CGFloat textSizeMultiplier

Discussion

This property represents part of the textDefaults. Setting those will set this property and vice versa.

Declared In

DTRichTextEditorView.h

Instance Methods

HTMLAttributesAtPosition:

Retrieves the dictionary of custom HTML attributes active at the given string index

- (NSDictionary *)HTMLAttributesAtPosition:(UITextPosition *)position

Parameters

position: The text position to query

Return Value

The custom HTML attributes dictionary or nil if there aren’t any at this index

Declared In

DTRichTextEditorView+Attributes.h

HTMLStringWithOptions:

Converts the current attributed string contents of the receiver to an HTML string.

- (NSString *)HTMLStringWithOptions:(DTHTMLWriterOption)options

Parameters

options: The options to apply for the conversion.

Return Value

An NSString with a generated HTML representation of the text

Discussion

This uses DTHTMLWriter and uses the currently set textScale to reverse font scale changes. This allows for HTML with a small font size to be displayed at a larger font size, but the generated HTML will still have the original font size.

Valid options are:

DTHTMLWriterOptionDocument: Styles are compressed into a stylesheet and a header is output (default)
DTHTMLWriterOptionFragment: All styles are inline and no header is output

Declared In

DTRichTextEditorView+Manipulation.h

addHTMLAttribute:value:range:replaceExisting:

Adds the custom HTML attributes with the given value on the given range, optionally replacing occurences of an attribute with the same name.

- (void)addHTMLAttribute:(NSString *)name value:(id)value range:(UITextRange *)range replaceExisting:(BOOL)replaceExisting

Parameters

name: The name of the custom HTML attribute

value: The value to set for the custom attribute

range: The text range to set the custom attribute on

replaceExisting: YES if ranges that have an attribute with the same name should be replaced. With NO the attribute is only added for ranges where there is no attribute with the given name

Declared In

DTRichTextEditorView+Attributes.h

applyTextAlignment:toParagraphsContainingRange:

Applies the given text alignment to all paragraphs that are encompassing the given text range.

- (BOOL)applyTextAlignment:(CTTextAlignment)alignment toParagraphsContainingRange:(UITextRange *)range

Parameters

alignment: The text alignment to apply

range: The text range

Return Value

YES if at least one paragraph’s alignment was changed

Declared In

DTRichTextEditorView+Manipulation.h

attributedStringAttributesForTextDefaults

Determines the Core Text attributes for the text defaults currently set on the receiver.

- (NSDictionary *)attributedStringAttributesForTextDefaults

Return Value

An attribute dictionary suitable for constructing default text

Declared In

DTRichTextEditorView+Styles.h

attributedSubstringForRange:

Retrieves that attributed substring for the given range.

- (NSAttributedString *)attributedSubstringForRange:(UITextRange *)range

Parameters

range: The text range

Return Value

The NSAttributedString substring

Declared In

DTRichTextEditorView+Manipulation.h

attributesForTagName:tagClass:tagIdentifier:relativeToTextSize:

Retrieves the NSAttributedString attributes for a given tag name, considering overrides specified via textDefaults

- (NSDictionary *)attributesForTagName:(NSString *)tagName tagClass:(NSString *)tagClass tagIdentifier:(NSString *)tagIdentifier relativeToTextSize:(CGFloat)textSize

Parameters

tagName: The tag name to retrieve a attributes for

tagClass: The tag class, or nil

tagIdentifier: The tag id or nil

textSize: The text size to use for relative measurements

Return Value

The attributes dictionary

Discussion

The relativeToTextSize is needed because some styles sizings depend on the current text size, e.g. 0.8em

Declared In

DTRichTextEditorView+Styles.h

boundsOfCurrentSelection

Gets the bounds of the rectangle that encloses the cursor or an envelope around the current selection. Can be used for the target area of a context menu.

- (CGRect)boundsOfCurrentSelection

Declared In

DTRichTextEditorView.h

changeParagraphLeftMarginBy:toParagraphsContainingRange:

Changes the paragraph indentation by the given amount.

- (void)changeParagraphLeftMarginBy:(CGFloat)delta toParagraphsContainingRange:(UITextRange *)range

Parameters

delta: The amont to modify the left indentation by.

range: The text range

Discussion

This modifies both the firstLineHeadIndent as well as the headIndent properties of the paragraph styles.

Declared In

DTRichTextEditorView+Manipulation.h

defaultFontDescriptor

Retrieves a font descriptor for the default font, considering overrides specified via textDefaults

- (DTCoreTextFontDescriptor *)defaultFontDescriptor

Return Value

A font descriptor

Declared In

DTRichTextEditorView+Styles.h

dictationPlaceholderAtPosition:

Convenience method to retrieve the placeholder object at the given position.

- (DTDictationPlaceholderTextAttachment *)dictationPlaceholderAtPosition:(UITextPosition *)position

Parameters

position: The text position to retrieve the placeholder from

Return Value

The dictation placeholder or nil if there is none at the given text position.

Declared In

DTRichTextEditorView+Dictation.h

fontDescriptorForRange:

Returns a font descriptor that matches the font at the given range. The method calls typingAttributesForRange: and converts the font to a font descriptor. If the range is empty then the font matches what it would be if the user would start typing. If the range is not empty then it is the font of the first character in the range.

- (DTCoreTextFontDescriptor *)fontDescriptorForRange:(UITextRange *)range

Parameters

range: The text range in the attributed string for which to query the font

Return Value

The font descriptor

Declared In

DTRichTextEditorView+Manipulation.h

glyphRunAtPosition:

Retrieves the glyph run around the given text location. This is useful to inspect the actually used attributes. For example you can get the actual writing direction or the actually used font used.

- (DTCoreTextGlyphRun *)glyphRunAtPosition:(UITextPosition *)position

Parameters

position: The text position

Return Value

The DTCoreTextGlyphRun object with all glyphs having the same attributes

Declared In

DTRichTextEditorView+Manipulation.h

handleNewLineInputInListInRange:

Handles the following scenarios of entering a New Line character inside a list block.

- (BOOL)handleNewLineInputInListInRange:(UITextRange *)range

Parameters

range: The text range of the selection

Return Value

YES if the range started inside a list

Discussion

NL at beginning of an empty paragraph at end of list: toggles off the list for this paragraph
NL at end of non-empty paragraph: extends the list to the new paragraph
NL in some other paragraph of the list: inserts a new list paragraph inside the list

Declared In

DTRichTextEditorView+Lists.h

layoutLineAtIndex:

Returns the layout line at the given string index

- (DTCoreTextLayoutLine *)layoutLineAtIndex:(NSUInteger)lineIndex

Parameters

lineIndex: The index of the line

Return Value

the layout line

Declared In

DTRichTextEditorView+DTCoreText.h

layoutLineContainingTextPosition:

Returns the layout line that contains the given text position.

- (DTCoreTextLayoutLine *)layoutLineContainingTextPosition:(UITextPosition *)textPosition

Parameters

textPosition: The text position

Return Value

the layout line

Declared In

DTRichTextEditorView+DTCoreText.h

listIndentForListStyle:

Retrieves the list indent from the leading margin to apply for a given list style

- (CGFloat)listIndentForListStyle:(DTCSSListStyle *)listStyle

Parameters

listStyle: The CSS list style to determine the list indentation for

Return Value

The indent or 0 if listStyle is nil

Discussion

This value is determined by parsing a single character HTML with the appropriate list HTML and takes the textDefaults into consideration.

Declared In

DTRichTextEditorView+Styles.h

numberOfLayoutLines

The number of text lines in the receiver.

- (NSUInteger)numberOfLayoutLines

Return Value

The number of text lines in the receiver.

Declared In

DTRichTextEditorView+DTCoreText.h

pasteboardHasSuitableContentForPaste

Determines if there is something on the pasteboard that can be pasted into the receiver.

- (BOOL)pasteboardHasSuitableContentForPaste

Return Value

YES if something can be pasted

Declared In

DTRichTextEditorView+Manipulation.h

plainTextForRange:

Prepares a plain-text representation of the substring for the given range.

- (NSString *)plainTextForRange:(UITextRange *)range

Parameters

range: The text range.

Return Value

A substring of the receivers current contents

Discussion

If the attributed string in this range contains attachments then those are removed.

Declared In

DTRichTextEditorView+Manipulation.h

rangeOfHTMLAttribute:atPosition:

Retrieves the range that an attribute with a given name is active for, beginning with the passed index

- (NSRange)rangeOfHTMLAttribute:(NSString *)name atPosition:(UITextPosition *)position

Parameters

name: The name of the custom HTML attribute to query

position: The text position to query

Return Value

The custom HTML attributes dictionary or nil if there aren’t any at this index

Discussion

Since a custom HTML attribute can occur in multiple individual attribute dictionaries this extends the range from the passed index outwards until the full range of the custom HTML attribute has been found. Those range extentions have to have an identical value, as established by comparing them to the value of the custom attribute at the index with isEqual:

Declared In

DTRichTextEditorView+Attributes.h

removeHTMLAttribute:range:

Adds the custom HTML attributes with the given value from the given range.

- (void)removeHTMLAttribute:(NSString *)name range:(UITextRange *)range

Parameters

name: The name of the custom HTML attribute

range: The text range to remove the custom attribute from

Declared In

DTRichTextEditorView+Attributes.h

replaceRange:withAttachment:inParagraph:

Inserts an attachment in the given text range.

- (void)replaceRange:(UITextRange *)range withAttachment:(DTTextAttachment *)attachment inParagraph:(BOOL)inParagraph

Parameters

range: The text range for the insertion

attachment: The text attachment to be inserted

inParagraph: If YES then the method makes sure that the attachment sits in its own paragraph

Declared In

DTRichTextEditorView+Manipulation.h

replaceRange:withText:

Replaces a range of text. The current selection is adapted, too.

- (void)replaceRange:(UITextRange *)range withText:(id)text

Parameters

range: The text range to replace

text: The text for the replacement

Discussion

This is an overwritten method that accepts either an NSString or NSAttributedString.

Declared In

DTRichTextEditorView.h

scrollCursorVisibleAnimated:

Scrolls the receiver’s content view so that the cursor is visible.

- (void)scrollCursorVisibleAnimated:(BOOL)animated

Parameters

animated: If YES then the view is scrolled animated. If NO it jumps to the scroll position

Declared In

DTRichTextEditorView.h

setFont:

Convenience method to set the defaultFontFamily and defaultFontSize to the given font’s values. Updates the entire string with this.

- (void)setFont:(UIFont *)font

Parameters

font: The font to use the values from

Declared In

DTRichTextEditorView+Manipulation.h

setForegroundColor:inRange:

Sets the text foreground color for a given range.

- (void)setForegroundColor:(UIColor *)color inRange:(UITextRange *)range

Parameters

color: The foreground color to set. Passing nil removes the color attribute and thus restores the black default color.

range: The text range

Declared In

DTRichTextEditorView+Manipulation.h

setHTMLString:

Converts the given string to an NSAttributedString using the current textDefaults and sets it on the receiver.

- (void)setHTMLString:(NSString *)string

Parameters

string: The string containing HTML text to convert to an attributed string and set as content of the receiver

Declared In

DTRichTextEditorView+Manipulation.h

setInputView:animated:

Sets the input view which will be shown instead of the keyboard. If the receiver already has first responder then this replaces the previous input view or standard keyboard. If the receiver is not first responder, then the animated parameter will be ignored

- (void)setInputView:(UIView *)inputView animated:(BOOL)animated

Parameters

inputView: The new input view to set on the receiver, or ‘nil’ to restore the keyboard

animated: Whether the replacement should be animated

Declared In

DTRichTextEditorView.h

setSelectedTextRange:animated:

Changes the current text selection range to the new value. Can optionally be animated.

- (void)setSelectedTextRange:(DTTextRange *)newTextRange animated:(BOOL)animated

Parameters

newTextRange: The new text range to select

animated: If YES then an extension (e.g. to include a full word) is animated

Declared In

DTRichTextEditorView.h

textAttachmentsWithPredicate:

Retrieving the attachments that match a predicate.

- (NSArray *)textAttachmentsWithPredicate:(NSPredicate *)predicate

Parameters

predicate: The NSPredicate that will be used to check the DTTextAttachment key values against

Return Value

An array of matching attachments

Declared In

DTRichTextEditorView+Manipulation.h

textRangeOfDictationPlaceholder

Retrieves the range of the first dictation placeholder in the text.

- (UITextRange *)textRangeOfDictationPlaceholder

Return Value

The selection range

Discussion

You can use this to replace the dictation placeholder with the recognized text.

Declared In

DTRichTextEditorView+Dictation.h

textRangeOfParagraphContainingPosition:

Finds the text range that includes the given cursor position.

- (UITextRange *)textRangeOfParagraphContainingPosition:(UITextPosition *)position

Parameters

position: The cursor position

Return Value

The paragraph range

Declared In

DTRichTextEditorView+Ranges.h

textRangeOfParagraphsContainingRange:

Extends the given range to include all full paragraphs that contain it.

- (UITextRange *)textRangeOfParagraphsContainingRange:(UITextRange *)range

Parameters

range: The text range

Return Value

The extended range

Declared In

DTRichTextEditorView+Ranges.h

textRangeOfURLAtPosition:URL:

Gets the text range of an URL at the given text position. Optionally also returns the hyperlink URL.

- (UITextRange *)textRangeOfURLAtPosition:(UITextPosition *)position URL:(NSURL **)URL

Parameters

position: The text position

URL: An optional URL output param or NULL if the URL is not required

Return Value

the text range or NULL if there is no URL at this position

Declared In

DTRichTextEditorView+Ranges.h

textRangeOfWordAtPosition:

Gets the range that encompasses the word at the given text position.

- (UITextRange *)textRangeOfWordAtPosition:(UITextPosition *)position

Parameters

position: The text position

Return Value

the text range

Declared In

DTRichTextEditorView+Ranges.h

toggleBoldInRange:

Toggles bold font style on the given range.

- (void)toggleBoldInRange:(UITextRange *)range

Parameters

range: The text range

Discussion

The first character of the range determines if the range is to be treated as bold or not.

Declared In

DTRichTextEditorView+Manipulation.h

toggleHighlightInRange:color:

Highlights a given range.

- (void)toggleHighlightInRange:(UITextRange *)range color:(UIColor *)color

Parameters

range: The text range

color: The highlight color to mark the range with. If the range is already marked then this parameter is ignored.

Discussion

The first character of the range determines if the range is to be treated as already highlighted or not.

Declared In

DTRichTextEditorView+Manipulation.h

toggleHyperlinkInRange:URL:

Toggles a hyperlink on the given range.

- (void)toggleHyperlinkInRange:(UITextRange *)range URL:(NSURL *)URL

Parameters

range: The text range

URL: The hyperlink URL to set on the range with. If the range already has a hyperlink then this parameter is ignored.

Discussion

The first character of the range determines if the range is to be treated as already hyperlinked or not.

Declared In

DTRichTextEditorView+Manipulation.h

toggleItalicInRange:

Toggles italic font style on the given range.

- (void)toggleItalicInRange:(UITextRange *)range

Parameters

range: The text range

Discussion

The first character of the range determines if the range is to be treated as italic or not.

Declared In

DTRichTextEditorView+Manipulation.h

toggleListStyle:inRange:

Toggles a list style on a given range.

- (void)toggleListStyle:(DTCSSListStyle *)listStyle inRange:(UITextRange *)range

Parameters

listStyle: the list style to toggle, or nil to remove the list style.

range: The text range

Discussion

Toggling the list style is its own Undo group unless you set _keepCurrentUndoGroup to YES.

Declared In

DTRichTextEditorView+Lists.h

toggleStrikethroughInRange:

Toggles strikethrough font style on the given range.

- (void)toggleStrikethroughInRange:(UITextRange *)range

Parameters

range: The text range

Discussion

The first character of the range determines if the range is to be treated as strikethrough or not.

Declared In

DTRichTextEditorView+Manipulation.h

toggleUnderlineInRange:

Toggles underline font style on the given range.

- (void)toggleUnderlineInRange:(UITextRange *)range

Parameters

range: The text range

Discussion

The first character of the range determines if the range is to be treated as underlined or not.

Declared In

DTRichTextEditorView+Manipulation.h

typingAttributesForRange:

The attributes to apply for new text inserted at the given range.

- (NSDictionary *)typingAttributesForRange:(UITextRange *)range

Parameters

range: The text range

Return Value

The dictionary of styles

Declared In

DTRichTextEditorView+Manipulation.h

updateFontInRange:withFontFamilyName:pointSize:

Replaces the font for a given range preserving bold or italic ranges.

- (void)updateFontInRange:(UITextRange *)range withFontFamilyName:(NSString *)fontFamilyName pointSize:(CGFloat)pointSize

Parameters

range: The text range

fontFamilyName: The postscript font family name, or nil if the font family should be preserved.

pointSize: The point size in pixels to apply, or 0 if it should be preserved

Declared In

DTRichTextEditorView+Manipulation.h

updateHeaderLevel:inRange:

Apples a given header level to the given range. The range is extended to include full paragraphs.

- (void)updateHeaderLevel:(NSUInteger)headerLevel inRange:(UITextRange *)range

Parameters

headerLevel: The header level (1-6) to set or 0 to restore normal paragraph style

range: The text range

Discussion

If the range belongs to a list then it is removed from the list. All existing attributes are replaced.

Declared In

DTRichTextEditorView+Manipulation.h

updateListsInRange:removeNonPrefixedLinesFromLists:

Updates lists (prefixes and spacing) intersecting with the given range

- (void)updateListsInRange:(UITextRange *)range removeNonPrefixedLinesFromLists:(BOOL)removeNonPrefixed

Parameters

range: The text range to update

removeNonPrefixed: Whether lines that don’t posess a prefix should be removed from lists

Declared In

DTRichTextEditorView+Lists.h

visibleBoundsOfCurrentSelection

Gets the bounds of the rectangle that encloses the cursor or an envelope around the current selection.

- (CGRect)visibleBoundsOfCurrentSelection

Return Value

the visible portion of the selection or CGRectNull if not visible.

Declared In

DTRichTextEditorView.h

visibleLayoutLines

An array of layout lines that is currently visible in the receiver.

- (NSArray *)visibleLayoutLines

Return Value

An array of layout lines that is currently visible in the receiver.

Declared In

DTRichTextEditorView+DTCoreText.h

DTRichTextEditorView Class Reference

Overview

Tasks

Setting Text Defaults

Accessing the Editor Delegate

Accessing Views

Modifying Text Content

Cursor and Selection

Getting Information

Lists Methods

Attributes Methods

Ranges Methods

Dictation Methods

DTCoreText Methods

Manipulation Methods

Styles Methods

Properties

attributedText

Declared In

baseURL

Discussion

Declared In

canInteractWithPasteboard

Declared In

defaultFontFamily

Discussion

Declared In

defaultFontSize

Discussion

Declared In

editable

Declared In

editing

Declared In

editorViewDelegate

See Also

Declared In

inputAccessoryView

Declared In

maxImageDisplaySize

Discussion

Declared In

overrideInsertionAttributes

Declared In

replaceParagraphsWithLineFeeds

Discussion

Declared In

textDefaults

Discussion

Declared In

textSizeMultiplier

Discussion

Declared In

Instance Methods

HTMLAttributesAtPosition:

Parameters

Return Value

Declared In

HTMLStringWithOptions:

Parameters

Return Value

Discussion

Declared In

addHTMLAttribute:value:range:replaceExisting:

Parameters

Declared In

applyTextAlignment:toParagraphsContainingRange:

Parameters

Return Value

Declared In

attributedStringAttributesForTextDefaults

Return Value

Declared In

attributedSubstringForRange:

Parameters

Return Value

Declared In

attributesForTagName:tagClass:tagIdentifier:relativeToTextSize:

Parameters

Return Value