Forem: Mihhail Lapushkin

Nerdy internals of an Apple text editor 👨🏻‍🔧

Mihhail Lapushkin — Mon, 04 Mar 2024 13:41:35 +0000

I tried my best to convert it from the original article.

⌘+Click on the DEMO links to view the videos.

In this article, we’ll dive into the details of the way Paper functions as a TextView-based text editor for Apple platforms.

The first article was just a warm-up — here is where we get to truly geek out! 🤓

Before we start, I’ll add that for the time being Paper is built on the older TextKit 1 framework, so the article is relative to TextKit 1. That said, all of the concepts, abstractions, and principles discussed here still exist in TextKit 2, either unchanged or under a better API.

Text view

To understand how text editing works in native Apple text editors, we first need to discuss the centerpiece of the whole system — the TextView class. Technically, NSTextView and UITextView have their differences, but the API is similar enough that we can treat them as a single TextView class. I will highlight the differences where necessary.

TextView is a massive component that only grows in complexity with each release of respective operating systems. The TextEdit app consists almost entirely of a single TextView. When a single class can be used to build an entire app — you know it’s a beast.

Luckily, TextView is not just one huge pile of code. Apple tried to subdivide it into a bunch of layers — each represented by a flagship class. The layers build on top of each other to create a text editing experience.

`NSTextStorage`

Stores the raw text string.
Stores the attributes (string-value pairs) assigned to ranges of text.
- Styles such as font and color (defined by AppKit and UIKit).
- Any string-value pair that acts as metadata for your needs.
Emits events about text and attribute changes.

`NSTextContainer`

Defines the shape and dimensions of the area that hosts text symbols (glyphs).
Most of the time it’s a rectangle (duh 🙄) but can be any shape.

`NSLayoutManager`

Figures out the dimensions of the glyphs and the spacings between them by looking at the ranges of attributes applied to the text string in NSTextStorage.
- Extracts vector glyphs from the font.
- Converts each text character to one or more glyphs. Some symbols and languages need more than one.
- Calculates the size of each glyph.
- Calculates the distances between glyphs.
- Calculates the distances between lines of glyphs.
Lays out each glyph, line by line, into the shape defined by NSTextContainer.
- Calculates where every line of text starts and ends.
- Calculates how many lines there are and what is the total height of the text.

`TextView`

Draws the glyph layout generated by NSLayoutManager.
Syncs the height of the view with the current height of laid-out text.
Manages text input.
Manages the text selection.
Manages the caret — empty text selection.
Manages the typing attributes — attributes applied to the newly inserted text.
Can define margins (textContainerInset) around the NSTextContainer.
Manages all the additional bells and whistles such as dictation, copy-paste, spell check, etc.

`ScrollView`

Shows the visible portion of the TextView.
Manages scrolling, scroll bars, and zooming.
Can define its own margins (contentInset) in addition to the - textContainerInset defined by the TextView.
Implementation details:
- AppKit
  - NSScrollView contains NSClipView and two instances of NSScroller.
  - NSClipView contains NSTextView.
  - Thus many separate classes work together to make the scrolling effect.
- UIKit
  - UITextView extends from UIScrollView.
  - Thus UITextView holds everything, including the scrolling logic.
  - Another notable detail is that moving the caret outside the visible area of UITextView, bounded by contentInset, causes UITextView to auto-scroll to ensure that the caret stays within the visible area. You can often experience this in iOS text editors, where if the caret moves behind the keyboard, the editor scrolls to the next line. This is because the bottom contentInset is dynamically set to the current height of the keyboard.

Attributes

With the general structure of TextView out of the way, let’s zoom in on NSTextStorage, or rather its parent class NSAttributedString, as it is the foundation of rich text editing in Apple’s frameworks.

NSAttributedString consists of two parts:

A regular text string.
String-value pairs of attributes attached to ranges of text within the string.

Attributes are used mostly for styling purposes, but nothing restricts you from assigning custom string-value pairs for your own needs.

To get started, let’s make an NSAttributedString via the API:

NSMutableAttributedString *string = [NSMutableAttributedString.alloc
  initWithString:@"The quick brown fox jumps over the lazy dog."];

NSMutableParagraphStyle *style = NSMutableParagraphStyle.new;
style.firstLineHeadIndent = 30.0;

[string addAttribute:NSParagraphStyleAttributeName
               value:style
               range:NSMakeRange(0, string.length)];
[string addAttribute:NSFontAttributeName
               value:[NSFont systemFontOfSize:25.0]
               range:NSMakeRange(0, string.length)];

[string addAttribute:NSForegroundColorAttributeName
               value:NSColor.brownColor
               range:NSMakeRange(10, 5)];

[string addAttribute:NSFontAttributeName
               value:[NSFont boldSystemFontOfSize:25.0]
               range:NSMakeRange(20, 5)];

[string addAttribute:NSBackgroundColorAttributeName
               value:NSColor.lightGrayColor
               range:NSMakeRange(26, 4)];

[string addAttribute:NSUnderlineStyleAttributeName
               value:@(NSUnderlineStyleSingle)
               range:NSMakeRange(35, 4)];
[string addAttribute:NSFontAttributeName
               value:[NSFontManager.sharedFontManager
                      convertFont:[NSFont boldSystemFontOfSize:25.0]
                      toHaveTrait:NSFontItalicTrait]
               range:NSMakeRange(35, 4)];

NSRange is a structure consisting of a location and a length. NSMakeRange(10,5) means a range of 5 characters starting from position 10, or in other words, an inclusive range between positions 10 and 14. In case different ranges define the same attribute under the same position then the last applied range takes precedence. In the example above, the bold and italic fonts overwrite the default font that is applied to the whole string.

This code can be easily visualized in TextEdit as it is pretty much an NSTextView with some buttons.

The second big part of the API is dedicated to checking what attributes are applied to what ranges. The API itself is quite peculiar. A lot of thought has gone into making it fast and efficient, but as a result, the usage can be a bit of a pain.

For instance, if you want to check whether a certain attribute exists at a certain position you would use this method:

id value = [string attribute:NSFontAttributeName
                     atIndex:6
              effectiveRange:nil];

If the value is nil, then it does not exist. Otherwise, it is the value of the attribute which in this case is a NSFont/UIFont object. So this method can be used both to query the value and to check the existence of the attribute.

But it gets better. You can pass a pointer to the NSRange structure as the last argument (the good old C technique to return multiple values from a single function call):

NSRange effectiveRange;
id value = [string attribute:NSFontAttributeName
                     atIndex:6
              effectiveRange:&effectiveRange];

And it will return either:

The range of the continuous span of the same attribute with the same value.
Or the range of the gap where the attribute is absent.

Though not exactly… You see the effectiveRange here is not what you think it is. Quoting the documentation:

The range isn’t necessarily the maximum range covered by the attribute, and its extent is implementation-dependent.

In other words, it could be the correct maximum range… but it also might not be.

“Ahh — I just love having a bit of non-determinism in my code!”

To get the guaranteed maximum range you need to use a different method.

NSRange effectiveRange;
id value = [string attribute:NSFontAttributeName
                     atIndex:6
       longestEffectiveRange:&effectiveRange
                     inRange:NSMakeRange(0, string.length)];

I suppose, this separation is done to make the checking of the attribute existence faster with the former method as the latter one probably needs to do some range merging to figure out the longest range when multiple ranges overlap. Still — how the effectiveRange in the former method is even useful? 🤷🏼‍♂️

The same pair of methods exist to query an NSDictionary of all the attributes at a position and the effectiveRange for which this unique combination of attributes spans.

NSRange effectiveRange;
NSDictionary<NSAttributedStringKey, id> attributes =

  [string attributesAtIndex:6
      longestEffectiveRange:&effectiveRange
                    inRange:NSMakeRange(0, string.length)];

Finally, there is a convenience method to iterate over attributes within a range. With the longest constant name that ever existed for specifying which mode of attribute range inspection you prefer.

[string enumerateAttribute:NSFontAttributeName
                   inRange:NSMakeRange(0, string.length)
  options:NSAttributedStringEnumerationLongestEffectiveRangeNotRequired
  usingBlock:^(id value, NSRange range, BOOL *stop) {
  // do something
}];

Styling

With the foundational knowledge behind us, it’s time to discuss how the syntax highlighting and text styling work in Paper.

As mentioned before, styling means applying special framework-defined attributes to ranges of text. In addition to them, Paper also uses custom attributes to identify the structure of the text before styling it. Here’s the breakdown:

Meta attributes
- Defined by the Markdown parser to identify individual parts of the Markdown syntax.
- These are custom string-value pairs used purely for semantics.
- They do not influence the visual look of the text.
- You can think of them as a simplified AST for Markdown.
Styling attributes
- The visual attributes applied on top of the parts marked by meta attributes.
- These are built-in string-value pairs defined by AppKit and UIKit.

The attributes are kept in sync with:

The Markdown text in NSTextStorage that changes due to user input.
The text-affecting settings that change as the user adjusts them from various menu items, sliders, and gestures.

Technically, we can identify three types of events that trigger this attribute update process:

Document opened — full update of meta attributes and styling attributes.
Text changed — partial update of meta attributes and styling attributes in the affected part. Most of the time only in the edited text. Sometimes in the whole paragraph. More on that in the next chapter.
Setting changed — full update of styling attributes but not meta attributes.

In every update there is a well-defined sequence of steps:

Start the text editing transaction
- Without a transaction, every attribute change would trigger an expensive layout recalc by the NSLayoutManager. Instead, we want to batch all the changes and re-layout only once in step 4.
Parse the Markdown structure
- This is where the Markdown string is broken down into pieces denoted by the meta attributes.
- This step is skipped for setting change since the Markdown structure does not change in this case.
Update layout-affecting attributes
- The first batch of styling attributes.
- This is every visual attribute that can influence the position or size of the glyphs in the text view.
End the text editing transaction
Update decorative attributes
- The second batch of styling attributes.
- The decorative attributes (or rendering attributes in Apple’s terminology) are applied outside the transaction. The reason is simple — they don’t affect the layout, so updating them is not expensive. And they are not even aware of the transaction since they live in the NSLayoutManager itself, not in NSTextStorage.

The most important attribute of the layout-affecting ones is NSParagraphStyle. It defines the bulk of the values that influence the layout of the lines and paragraphs.

The last chunk of attributes that participate in the styling process are the typing attributes. They are tied to the attributes at the position preceding the caret (for empty selection) or to the one at the start of the selection (for non-empty selection). Once you type a character, the typing attributes are assigned to the newly inserted text automatically. In a Markdown editor, they are not that important as the styling is derived entirely from the Markdown syntax, but they are crucial for rich text editors where the styles stick to the caret until you turn them off or move the caret to a new location. Despite being a Markdown editor, Paper does have a rich text editing experience called the Preview Mode. In this mode, the editor behaves just like a rich text editor with toggleable typing attributes being highlighted, for example, on the toolbar in the iOS app.

Forem: Mihhail Lapushkin

Nerdy internals of an Apple text editor 👨🏻‍🔧

Text view

NSTextStorage

NSTextContainer

NSLayoutManager

TextView

ScrollView

Attributes

Styling

Performance

Meta attributes

Formatting shortcuts

Jumping between chapters

Outline

Rearranging chapters

Converting formats

Text container math

Selection anchoring

Selection affinity

Uniform Type Identifiers

Pasteboard

That’s it for now

9 years of Apple text editor solo dev 👨🏻‍💻

Why native?

Why Objective-C?

Third-party dependencies

Vision

Architecture

Cross-platform code

Debugging

Paid features

Pricing

Gnarly stuff

Gimmicks

Tidbits

Feedback

Releases

Acknowledgment

`NSTextStorage`

`NSTextContainer`

`NSLayoutManager`

`TextView`

`ScrollView`