Before iOS 6, controls such as UILabel and UITextView could display text only in a single font and size. If you wanted styled text — that is, text consisting of multiple style runs, with different font, size, color, and other text features in different parts of the text — you were largely out of luck. You could construct an NSAttributedString to express styled text, by dropping down to the lowest level, Core Text; but to display it in the interface you had to use a CATextLayer or have CoreText draw it, which was a lot of work. Workarounds included using a UIWebView or manipulating multiple UILabels. (For example, that’s how the TidBITS News app used to work, as shown in Figure 19.1; the bold headline and the smaller article summary are two different labels.) Editable styled text was virtually impossible to achieve.

Starting in iOS 6, however, NSAttributedString is fully integrated. With it, you can draw styled text directly, or you can hand an attributed string to any built-in interface class that understands it, including UILabel, UITextView, and UIButton.

An NSAttributedString consists of an NSString (its string) plus the attributes, applied in ranges. For example, if the string “one red word” is blue except for the word “red” which is red, and if these are the only changes over the course of the string, then there are three distinct style runs — everything before the word “red,” the word “red” itself, and everything after the word “red.” However, we can apply the attributes in two steps, first making the whole string blue, and then making the word “red” red, just as you would expect.

The attributes are described in dictionaries. Each possible attribute has a predefined name, used as a key in these dictionaries:

To construct an NSAttributedString, you can call initWithString:attributes: if the entire string has the same attributes; otherwise, you’ll use its mutable subclass NSMutableAttributedString, which lets you set attributes over a range. To construct an NSParagraphStyle, you’ll use its mutable subclass NSMutableParagraphStyle. (The properties of NSParagraphStyle itself are all read-only, for historical reasons.) It is sufficient to apply a paragraph style to the first character of a paragraph; to put it another way, the paragraph style of the first character of a paragraph dictates how the whole paragraph is rendered. Both NSAttributedString and NSParagraphStyle come with default values for all attributes, so you only have to set the attributes you care about.

We now know enough for an example! I’ll generate the paragraph shown in Figure 23.1. This is a UILabel; its background is white, so you can see its bounds relative to the text. Two words are made extra-bold by stroking in a different color, and the whole paragraph is centered and indented from the edges of the label.

Figure 23.1. A label showing an attributed string

I start by dictating the entire string and the overall style of the text; then I apply the special style to the two stroked words:

NSString* s1 = @"The Gettysburg Address, as delivered on a certain occasion "
    @"(namely Thursday, November 19, 1863) by A. Lincoln";
NSMutableAttributedString* content =
    [[NSMutableAttributedString alloc]
     initWithString:s1
     attributes:
         @{
           NSFontAttributeName:
               [UIFont fontWithName:@"Arial-BoldMT" size:15],
           NSForegroundColorAttributeName:
               [UIColor colorWithRed:0.251 green:0.000 blue:0.502 alpha:1]
         }];
NSRange r = [s1 rangeOfString:@"Gettysburg Address"];
[content addAttributes:
    @{
      NSStrokeColorAttributeName:[UIColor redColor],
      NSStrokeWidthAttributeName: @-2.0
     } range:r];

Now I create the paragraph style and apply it to the first character. Note how the margins are dictated: the tailIndent is negative, to bring the right margin leftward, and the firstLineHeadIndent must be set separately, as the headIndent does not automatically apply to the first line:

NSMutableParagraphStyle* para = [NSMutableParagraphStyle new];
para.headIndent = 10;
para.firstLineHeadIndent = 10;
para.tailIndent = -10;
para.lineBreakMode = NSLineBreakByWordWrapping;
para.alignment = NSTextAlignmentCenter;
para.paragraphSpacing = 15;
[content addAttribute:NSParagraphStyleAttributeName
                value:para range:NSMakeRange(0,1)];

Now I’ll generate the string shown in Figure 23.2. Note the full justification, the automatic hyphenation, and the large initial cap kerned close to the following letter.

Figure 23.2. A label showing another attributed string

Once again, I start by styling the string as a whole; then I style the first letter. There’s an obvious but important difference between setAttributes: and addAttributes::

NSString* s2 = @"Fourscore and seven years ago, our fathers brought forth "
    @"upon this continent a new nation, conceived in liberty and dedicated "
    @"to the proposition that all men are created equal.";
NSMutableAttributedString* content2 =
    [[NSMutableAttributedString alloc]
     initWithString:s2
     attributes:
         @{
           NSFontAttributeName:
               [UIFont fontWithName:@"HoeflerText-Black" size:16]
         }];
[content2 setAttributes:
    @{
      NSFontAttributeName:[UIFont fontWithName:@"HoeflerText-Black" size:24]
     } range:NSMakeRange(0,1)];
[content2 addAttributes:
    @{
      NSKernAttributeName:@-4
     } range:NSMakeRange(0,1)];

Now I’ll construct the paragraph style and add it to the first character:

NSMutableParagraphStyle* para2 = [NSMutableParagraphStyle new];
para2.headIndent = 10;
para2.firstLineHeadIndent = 10;
para2.tailIndent = -10;
para2.lineBreakMode = NSLineBreakByWordWrapping;
para2.alignment = NSTextAlignmentJustified;
para2.lineHeightMultiple = 1.2;
para2.hyphenationFactor = 1.0;
[content2 addAttribute:NSParagraphStyleAttributeName
                 value:para2 range:NSMakeRange(0,1)];

Now we come to the Really Amazing Part. I can make a single attributed string consisting of both paragraphs, and a single UILabel can portray it (Figure 23.3):

int end = content.length;
[content replaceCharactersInRange:NSMakeRange(end, 0) withString:@"\n"];
[content appendAttributedString:content2];

Figure 23.3. A single label containing two differently styled paragraphs

The API for examining and modifying an attributed string invites us to think of style runs as extending over an entire range of characters, but that may be just a convenience. The content of a mutable attributed string may be better envisioned as a sequence of characters, each of which has associated attributes. Thus we can coherently modify just the string part of a mutable attributed string. The key method here is replaceCharactersInRange:withString:, which can be used to replace characters with a plain string or, using a zero range length, to insert a plain string at the start, middle, or end of an attributed string (as demonstrated in the preceding code). The rule is that if we replace characters, the inserted string takes on the attributes of the first replaced character. If we insert characters, the inserted string takes on the attributes of the character preceding the insertion — except that, if we insert at the start, there is no such character, so the inserted string takes on the attributes of the character following the insertion.

You can query an attributed string about its attributes one character at a time — asking either about all attributes at once (attributesAtIndex:effectiveRange:) or about a particular attribute by name (attribute:atIndex:effectiveRange:). The last parameter is a pointer to an NSRange variable, which will be set to the range over which this same attribute value, or set of attribute values, applies:

NSRange range;
NSDictionary* d =
    [content attributesAtIndex:content.length-1 effectiveRange:&range];

Because style runs are an artifice, however, you might not end up with what you would think of as the entire style run. The methods with longestEffectiveRange: in their names, at the cost of some efficiency, do work out the full style run for you. Often, however, you don’t need the entire range, because you’re cycling through ranges, and you want to do that as fast as possible. In this example, I start with the combined two-paragraph attributed string derived in the previous examples, and change all the size 15 material to Arial Bold 20. I explicitly don’t care whether I’m handed longest effective ranges; I just want to cycle efficiently:

[content enumerateAttribute:NSFontAttributeName
    inRange:NSMakeRange(0,content.length)
    options:NSAttributedStringEnumerationLongestEffectiveRangeNotRequired
    usingBlock:^(id value, NSRange range, BOOL *stop)
{
    UIFont* font = value;
    if (font.pointSize == 15)
        [content addAttribute:NSFontAttributeName
                        value:[UIFont fontWithName: @"Arial-BoldMT" size:20]
                        range:range];
}];

You don’t need a UILabel to host an attributed string in the interface; you can draw the attributed string directly, and sometimes this will prove to be a more reliable approach. Just as an NSString can be drawn into a rect with drawInRect:withFont: and related methods, an NSAttributedString can be drawn with drawInRect:. (There’s no need to supply a font parameter, because the font is part of the attributed string!) Here, I draw the attributed string into an image:

UIGraphicsBeginImageContextWithOptions(rect.size, YES, 0);
[[UIColor whiteColor] setFill];
CGContextFillRect(UIGraphicsGetCurrentContext(), rect);
[self.content drawInRect:rect];
UIImage* im = UIGraphicsGetImageFromCurrentImageContext();
UIGraphicsEndImageContext();

That image can then be displayed by an image view, for example. Similarly, you can draw an attributed string directly in a UIView’s drawRect:. That, in fact, is how the current version of the TidBITS News app works (Figure 23.4). Previously, its table cells contained multiple UILabels, which had to be sized individually to fit their content (Chapter 21). Now, each cell is drawn as a single attributed string consisting of the article title and the article summary.

Figure 23.4. The TidBITS News app, rewritten for iOS 6

I’ll describe how that string is drawn. The cell’s contentView is completely occupied by a custom UIView class that I call StringDrawer; it has an attributedText property. In tableView:cellForRowAtIndexPath:, I set that property:

cell.drawer.attributedText = [self attributedStringForIndexPath: indexPath];

StringDrawer’s drawRect: draws its attributedText:

- (void)drawRect:(CGRect)rect {
    CGRect r = CGRectOffset(rect, 0, 2); // shoved down a little from top
    [self.attributedText drawWithRect:r
        options:NSStringDrawingTruncatesLastVisibleLine |
                NSStringDrawingUsesLineFragmentOrigin
        context:nil];
}

I want an ellipsis at the end of the second paragraph if the whole thing doesn’t fit in the given rect (as shown in Figure 23.4). This can’t be achieved using NSLineBreakByTruncatingTail, which truncates the first line of the second paragraph. Therefore, I’m using drawWithRect:options:context:, instead of simple drawInRect:, because it allows me to specify the option NSStringDrawingTruncatesLastVisibleLine. However, I must then also specify NSStringDrawingUsesLineFragmentOrigin; otherwise, the string is drawn with its baseline at the rect origin (so that it appears above that rect) and it doesn’t wrap. The rule is that NSStringDrawingUsesLineFragmentOrigin is the implicit default for simple drawInRect:, but with drawWithRect:options:context: you must specify it explicitly.

To derive the height of the cell, I also measure the attributed string beforehand, in tableView:heightForRowAtIndexPath::

CGRect r =
    [s boundingRectWithSize:CGSizeMake(320,10000)
        options:NSStringDrawingUsesLineFragmentOrigin context:nil];
CGFloat result = r.size.height;
if (result > 200) // set arbitrary limit on cell heights
    result = 200;

Again, the option NSStringDrawingUsesLineFragmentOrigin is crucial; without it, the measured text doesn’t wrap and the returned height will be very small.

The context: parameter of drawWithRect:options:context: and boundingRectWithSize:options:context: lets you attach an instance of NSStringDrawingContext. This simple class has properties that let you permit the text to shrink its size and compress its kerning automatically if doing so would allow it to fit in the given space. (This feature works only if the string consists of a single line — that is, a single paragraph whose line break mode doesn’t have Wrapping in its name.) It also lets you learn what actually happened. If you set an NSStringDrawingContext instance’s minimumScaleFactor (to a positive fraction, such as 0.7) and then draw or measure with this instance as the context: argument, you can then get that instance’s actualScaleFactor to learn how much the drawing engine really did shrink the text size. The minimumTrackingAdjustment (a negative fraction, such as -0.7) and actualTrackingAdjustment work similarly.

Additionally, an NSStringDrawingContext instance tells you where you just drew. With a plain NSString, you derive this information from the return value of the drawing command; for example, drawInRect:withFont: returns a CGSize telling you the size of the drawn string. But drawWithRect:options:context: has no return value. Instead, if you attach an NSStringDrawingContext, its totalBounds property tells you, after you draw, the bounds of the drawn string.

UILabel was introduced briefly in Chapter 21 (in Built-In Cell Styles). If you’re configuring a UILabel through a plain NSString, by way of its text property, then you are likely also to set its font, textColor, and textAlignment properties, and possibly its shadowColor and shadowOffset properties. The label’s text can have an alternate highlightedTextColor, to be used when its highlighted property is YES (as happens, for example, when the label is in a selected cell of a table view).

If you’re using an NSAttributedString, then you’ll set the label’s attributedText property, and you’ll probably want to leave those other properties alone; they do still work, but they’re going to change the attributes of your entire attributed string, in ways that you might not intend. Setting the text of a UILabel that has attributedText will basically eliminate the attributes. The highlightedTextColor property does not work on the attributedText.

If a UILabel consists of only one line of text (numberOfLines is 1, the default), then if you set its text, any line breaks (@"\n") are treated as spaces; but if you set its attributedText, line breaks are honored and you won’t see whatever follows the first line break.

If a UILabel consists of only one line of text (numberOfLines is 1, the default), then you can elect to permit the text to shrink and compress if this would allow the text to fit when otherwise it wouldn’t. You can turn on adjustsFontSizeToFitWidth and provide a minimumScaleFactor (replacing the now-deprecated minimumFontSize), or you can turn on adjustsLetterSpacingToFitWidth. With plain text, you can turn on both; with attributedText, you can’t (this feels like a bug). If you’re using an attributed string, the label’s (or attributed string’s) line break mode must not have Wrapping in its name. How the text is repositioned when the size shrinks is determined by the label’s baselineAdjustment property.

A UILabel may alternatively consist of multiple lines of text, where numberOfLines is greater than 1, or 0 to indicate no maximum. This matters even if you’re using an attributed string! In Figure 23.3, for example, the full text is shown because I set the label’s numberOfLines to 0.

Line breaking (wrapping) and truncation behavior, which applies to both single-line and multiline labels, is determined by its lineBreakMode. You can get a feel for line break behavior by experimenting in the nib. Your options are:

If numberOfLines is larger than the number of lines actually needed, the text is vertically centered in the label. This may be undesirable; you might prefer to shrink (or grow) the label to fit its text. In iOS 5 and before, you couldn’t use sizeToFit to do this, because the default UILabel implementation of sizeToFit was to make the label the right width to contain all its text on a single line. However, in iOS 6 that behavior is completely changed, so that in most simple cases sizeToFit will do exactly the right thing; I suspect that behind the scenes it is just calling boundingRectWithSize:options:context:.

I say “in most simple cases” because there are cases where UILabel’s sizeToFit will misbehave. These happen to be exactly the cases where boundingRectWithSize:options:context: misbehaves. The problem arises particularly with paragraph styles involving margins (headIndent and tailIndent). Take, for example, the label displayed in Figure 23.3. It’s too tall for its content, but if we call sizeToFit it becomes too narrow for its content, presumably because boundingRectWithSize:options:context: ignores the margins. A possible workaround is to call boundingRectWithSize:options:context: and set the width back to the original width, like this:

CGRect rect =
    [self.lab.attributedText boundingRectWithSize:self.lab.bounds.size
     options:NSStringDrawingUsesLineFragmentOrigin context:nil];
// width is wrong so we have to widen it again
rect.size.width = self.lab.bounds.size.width;
rect.size.height += 5; // for good measure
CGRect f = self.lab.bounds;
f.size = rect.size;
self.lab.bounds = f;

But it turns out there’s a better way. Don’t forget about constraints! If we’re using autolayout, a UILabel will attempt to configure its own height and width (its intrinsicContentSize) to fit its contents. Thus, if the label is left to its own devices, it will set its height correctly for its contents with no code at all. Merely configuring the label — setting its text, changing its font, setting its attributed text, and so forth — automatically invalidates its intrinsic content size and causes that size to be recalculated.

However, the label has two dimensions, so we must clearly give it a hint as to how it should mediate between them. One obvious way is to fix the width absolutely — for example, by an internal width constraint, or by pinning both the left and right edges of the label. In that case, assuming that no constraints prevent it, the label’s height will automatically adjust to accommodate its contents exactly. (If the label does have a height constraint, it will still adjust its own height, provided that the height constraint’s priority is less than its content hugging priority, which is 250.)

An even more flexible approach is to set the label’s preferredMaxLayoutWidth. This is the width at which the label, as its contents increase, will stop growing horizontally to accommodate its contents and start growing vertically instead. (This implies that the contents will wrap, so clearly the numberOfLines can’t be 1.) For example, consider a label containing just a couple of words, whose right edge and top edge are pinned. Thanks to its intrinsic content size, that’s sufficient to position and size the label. Now set the label’s text to be several sentences long. Assuming that no other constraints intervene, and that the label’s numberOfLines is not 1, the label’s width will increase to its preferredMaxLayoutWidth and its height will increase to accommodate its text exactly.

Conversely, you might wish to keep the label’s text the same, but make the label narrower and let it grow in height to accommodate its contents. Again, the key here is the intrinsicContentSize: we set the label’s width and its intrinsicContentSize together. For example, suppose we have an outlet to the label and to its width constraint; then this code makes the label narrower horizontally while letting it grow vertically to keep accommodating its contents:

self.widthConstraint.constant -= 10;
self.theLabel.preferredMaxLayoutWidth = self.widthConstraint.constant;

That’s all very well if we are changing the label’s width explicitly in code, but what if the label’s width is changing automatically in response to its constraints? An obvious example is a label whose left and right are pinned to its superview, and the superview changes size because the interface rotates. The label’s height will not change automatically to fit its contents; we must prompt it. For example, the view controller could respond to layout by setting the label’s preferredMaxLayoutWidth to its new width:

-(void)viewDidLayoutSubviews {
    self.lab.preferredMaxLayoutWidth = self.lab.bounds.size.width;
    [self.view layoutSubviews];
}

Or we could make the label self-adjusting, by subclassing UILabel and overriding layoutSubviews:

-(void)layoutSubviews {
    [super layoutSubviews];
    self.preferredMaxLayoutWidth = self.bounds.size.width;
}

Methods that you can override in a subclass to modify a label’s drawing are drawTextInRect: (an example appeared in Chapter 10) and textRectForBounds:limitedToNumberOfLines:.

A text field portrays just a single line of text (any return characters in its text are treated as spaces); otherwise, it has many of the same properties as a label. So, if you provide it with a plain NSString, it has a text, font, textColor, and textAlignment. It has adjustsFontSizeToFitWidth and minimumFontSize properties, although these don’t work exactly like a label; a text field won’t allow its font size to shrink automatically as small as a label will.

To provide a text field with an attributed string, you set its attributedText. In that case I would suggest that you not set its adjustsFontSizeToFitWidth to YES, as this behaves rather badly; it doesn’t allow any intermediate sizes, but either shrinks the text absolutely or doesn’t; and, if it does shrink it, it will cause your text to appear all in a single font.

Text that is too long for the text field is displayed with an ellipsis at the end. You can change the position of the ellipsis by assigning the text field an attributed string with different truncation behavior, such as NSLineBreakByTruncatingHead. When overly long text is being edited, the text shifts horizontally to show the insertion point. On the whole, though, text that is too long for the text field is probably not a very good idea; the user usually has no arrow keys, as on the desktop, so navigating long text is daunting (the user must select text and stretch the selection into the offscreen part of the text).

Regardless of whether you originally supplied a plain string or an attributed string, if the text field’s allowsEditingTextAttributes is YES, the user, when editing in the text field, can summon a menu toggling the selected text’s bold, italics, or underline features. (Oddly, there’s no way to set this property in a nib.)

A text field has a placeholder property, which is the text that appears faded within the text field when it has no text; the idea is that you can use this to suggest to the user what the text field is for. It has a styled text alternative, attributedPlaceholder.

If a text field’s clearsOnBeginEditing property is YES, it automatically deletes its existing text when the user begins editing within it. New in iOS 6, if a text field’s clearsOnInsertion property is YES, then when editing begins within it, the entire text is selected, but invisibly selected, so that if the user starts typing immediately, the current contents of the text field will be removed.

A text field’s border drawing is determined by its borderStyle property. Your options are:

A text field can have a background color (because it is a UIView) or a background image (background), possibly along with a second image (disabledBackground) to be displayed when the text field’s enabled property, inherited from UIControl, is NO. The user can’t interact with a disabled text field, but without a disabledBackground image, the user may lack any visual clue to this fact. (A rounded rectangle text field doesn’t display these background images.)

A text field may contain one or two ancillary overlay views, its leftView and rightView, and possibly a Clear button (a gray circle with a white X). The automatic visibility of each of these is determined by the leftViewMode, rightViewMode, and clearViewMode, respectively. The view mode values are:

Depending on what sort of view you use, your leftView and rightView may have to be sized manually so as not to overwhelm the text view contents. If a right view and a Clear button appear at the same time, the right view may cover the Clear button unless you reposition it. The positions and sizes of any of the components of the text field can be set in relation to the text field’s bounds by overriding the appropriate method in a subclass:

You can also override in a subclass the methods drawTextInRect: and drawPlaceholderInRect:. You should either draw the specified text or call super to draw it; if you do neither, the text won’t appear. Both these methods are called with a parameter whose size is the dimensions of the text field’s text area, but whose origin is {0,0}. In effect what you’ve got is a graphics context for just the text area; any drawing you do outside the given rectangle will be clipped.

- (BOOL)textFieldShouldReturn: (UITextField*) tf {
    [tf resignFirstResponder];
    return YES;
}

@property (nonatomic, strong)
    IBOutletCollection(NSLayoutConstraint) NSArray* verticalConstraints;
@property (nonatomic, weak) IBOutlet UIView *slidingView;
@property (nonatomic, weak) UIView* fr;

[super viewDidLoad];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(keyboardShow:)
                                         name:UIKeyboardWillShowNotification
                                         object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(keyboardHide:)
                                         name:UIKeyboardWillHideNotification
                                         object:nil];

- (void)textFieldDidBeginEditing:(UITextField *)tf {
    self.fr = tf; // keep track of first responder
}

- (void) keyboardShow: (NSNotification*) n {
    NSDictionary* d = [n userInfo];
    CGRect r = [d[UIKeyboardFrameEndUserInfoKey] CGRectValue];
    r = [self.slidingView convertRect:r fromView:nil];
    CGRect f = self.fr.frame;
    CGFloat y =
        CGRectGetMaxY(f) + r.size.height -
            self.slidingView.bounds.size.height + 5;
    NSNumber* duration = d[UIKeyboardAnimationDurationUserInfoKey];
    if (r.origin.y < CGRectGetMaxY(f)) {
        [UIView animateWithDuration:[duration floatValue] animations:^{
            for (NSLayoutConstraint* con in self.verticalConstraints) {
                con.constant = -y;
            }
            [self.view layoutIfNeeded];
        }];
    }
}

- (void) keyboardHide: (NSNotification*) n {
    NSNumber* duration = n.userInfo[UIKeyboardAnimationDurationUserInfoKey];
    [UIView animateWithDuration:[duration floatValue] animations:^{
        for (NSLayoutConstraint* con in self.verticalConstraints) {
            con.constant = 0;
        }
        [self.view layoutIfNeeded];
    }];
}

- (void) keyboardShow: (NSNotification*) n {
    self->_oldContentInset = self.scrollView.contentInset;
    self->_oldIndicatorInset = self.scrollView.scrollIndicatorInsets;
    self->_oldOffset = self.scrollView.contentOffset;
    NSDictionary* d = [n userInfo];
    CGRect r = [[d objectForKey:UIKeyboardFrameEndUserInfoKey] CGRectValue];
    r = [self.scrollView convertRect:r fromView:nil];
    CGRect f = self.fr.frame;
    CGFloat y =
        CGRectGetMaxY(f) + r.size.height -
            self.scrollView.bounds.size.height + 5;
    if (r.origin.y < CGRectGetMaxY(f))
        [self.scrollView setContentOffset:CGPointMake(0, y) animated:YES];
    UIEdgeInsets insets;
    insets = self.scrollView.contentInset;
    insets.bottom = r.size.height;
    self.scrollView.contentInset = insets;
    insets = self.scrollView.scrollIndicatorInsets;
    insets.bottom = r.size.height;
    self.scrollView.scrollIndicatorInsets = insets;
}

- (void) keyboardHide: (NSNotification*) n {
    [self.scrollView setContentOffset:self->_oldOffset animated:YES];
    [CATransaction setCompletionBlock:^{
        self.scrollView.scrollIndicatorInsets = self->_oldIndicatorInset;
        self.scrollView.contentInset = self->_oldContentInset;
    }];
}

- (void)textFieldDidBeginEditing:(UITextField *)tf {
    self.fr = tf; // keep track of first responder
    tf.inputAccessoryView = self.buttonView;
}

- (IBAction)doNextField:(id)sender {
    NSMutableArray* marr = [NSMutableArray array];
    for (UIView* v in self.fr.superview.subviews) {
        if ([v isKindOfClass: [UITextField class]])
            [marr addObject:v];
    }
    NSUInteger ix = [marr indexOfObject:self.fr];
    if (ix == NSNotFound)
        return; // shouldn't happen
    ix++;
    if (ix >= [marr count])
        ix = 0;
    UIView* v = marr[ix];
    [v becomeFirstResponder];
}

[textField addTarget:nil action:@selector(dummy:)
    forControlEvents:UIControlEventEditingDidEndOnExit];

UIMenuItem *mi = [[UIMenuItem alloc] initWithTitle:@"Expand"
                                            action:@selector(expand:)];
UIMenuController *mc = [UIMenuController sharedMenuController];
mc.menuItems = @[mi];

- (BOOL) canPerformAction:(SEL)action withSender: (id) sender {
    if (action == @selector(expand:))
        return ([self.text length] == 2); // could be more intelligent here
    return NO;
}

- (void) expand: (id) sender {
    NSString* s = self.text;
    // ... alter s here ...
    self.text = s;
}

- (BOOL) canPerformAction:(SEL)action withSender:(id)sender {
    if (action == @selector(expand:))
        return ([self.text length] == 2);
    if (action == @selector(copy:))
        return [super canPerformAction:action withSender:sender];
    return NO;
}

- (void) copy: (id) sender {
    [super copy: sender];
    UIPasteboard* pb = [UIPasteboard generalPasteboard];
    NSString* s = pb.string;
    // ... alter s here ....
    pb.string = s;
}

A text view is sort of a scrollable, multiline version of a text field (UITextField, with which it should not be confused). It is a scroll view subclass (UIScrollView, Chapter 20), and thus has (by default) no border; it is not a control. Nevertheless, it has many close similarities to a text field. It has text, font, textColor, and textAlignment properties; it can be editable or not, according to its editable property. (You might use a scrollable noneditable text view instead of a UILabel, so as not to be limited to a fixed number of lines of text in a given height.) As with a text field, iOS 6 brings to a text view the attributedText, allowsEditingTextAttributes, and typingAttributes properties, as well as clearsOnInsertion. An editable text view governs its keyboard just as a text field does: when it is first responder, it is being edited and shows the keyboard, and it implements the UITextInput protocol and has inputView and inputAccessoryView properties. Its menu works the same way as a text field’s as well.

A thing to watch out for when replacing a UITextView’s attributedText is that aspects of its previous attributedText may contaminate the new attributed string. For example:

NSAttributedString* s1 =
    [[NSAttributedString alloc] initWithString:@"Hello there!"
     attributes:@{NSForegroundColorAttributeName:[UIColor redColor]}];
NSAttributedString* s2 = [[NSAttributedString alloc] initWithString:@"Howdy"];
self.tv.attributedText = s1;
self.tv.attributedText = s2;

The result is that the text view says “Howdy” in red. This is clearly wrong behavior; if you do the same thing with a UILabel, the label says “Howdy” in black. Apparently, setting the text view’s attributedText the first time also changes its textColor, and this color is then allowed to impose itself when you set the text view’s attributedText the second time, presumably because you didn’t explicitly set the second attributed string’s color. A good workaround is to reset the text view’s properties:

self.tv.attributedText = s1;
self.tv.text = nil;
self.tv.font = nil;
self.tv.textColor = nil;
self.tv.textAlignment = NSTextAlignmentLeft;
self.tv.attributedText = s2;

One big difference, from the programmer’s point of view, between a text view and a text field is that a text view gives you information about, and control of, its selection: it has a selectedRange property which you can get and set, and it adds a scrollRangeToVisible: method so that you can scroll in terms of a range of its text. The selectedRange is useful especially if the text view is first responder, because the selection is then meaningful and visible, but it does work (invisibly) even if the text view is not first responder.

A text view also has a dataDetectorTypes property; this, if the text view is not editable, allows text of certain types (presumably located using NSDataDetector, see Chapter 10) to be rendered as tappable links.

A text view’s delegate messages (UITextViewDelegate protocol) and notifications are quite parallel to those of a text field. The big differences are:

A text view’s contentSize is maintained for you, automatically, as the text changes. You can track changes to the content size (in textViewDidChange:, for example). A common reason for doing so is to implement a self-sizing text view, that is, a text view that adjusts its height automatically to embrace the amount of text it contains.. In this example, we have an outlet to the text view’s internal height constraint:

- (void)textViewDidChange:(UITextView *)textView {
    self.heightConstraint.constant = textView.contentSize.height;
}

A self-sizing text view works best if the text view is not user-scrollable (scrollEnabled is NO). If it is user-scrollable, it might scroll itself as the user enters text, and you might then have to struggle to prevent it from doing so:

- (void)scrollViewDidScroll:(UIScrollView *)scrollView {
    scrollView.contentOffset = CGPointZero;
}

Dismissing the keyboard for a text view works differently than for a text field. Because a text view is multiline, the Return key is meaningful for character entry; you aren’t likely to want to misuse it as a way of dismissing the keyboard, and you don’t get a special delegate message for it. On the iPad, the virtual keyboard may contain a button that dismisses the keyboard. On the iPhone, the interface might well consist of a text view and the keyboard, so that instead of dismissing the keyboard, the user dismisses the entire interface. For example, in the Mail app on the iPhone, when the user is composing a message, the keyboard is present the whole time. In the Notes app, a note alternates between being read fullscreen and being edited with the keyboard present; in the latter case, a Done button is provided to dismiss the keyboard. If there’s no good place to put a Done button in the interface, you could attach an accessory view to the keyboard itself.

In an interface where the text view occupies more or less the whole screen, the easiest way to deal with the keyboard is to adjust the text view’s contentInset, as we did with a scroll view in the previous section. Here’s a fairly straightforward implementation; the text view will helpfully scroll to the insertion point automatically after the keyboard appears:

-(void)viewDidLoad {
    [[NSNotificationCenter defaultCenter] addObserver:self
        selector:@selector(keyboardShow:)
        name:UIKeyboardWillShowNotification object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self
        selector:@selector(keyboardHide:)
        name:UIKeyboardWillHideNotification object:nil];
}

- (IBAction)doDone:(id)sender {
    [self.view endEditing:NO];
}

- (void) keyboardShow: (NSNotification*) n {
    NSDictionary* d = [n userInfo];
    CGRect r = [d[UIKeyboardFrameEndUserInfoKey] CGRectValue];
    self.tv.contentInset = UIEdgeInsetsMake(0,0,r.size.height,0);
    self.tv.scrollIndicatorInsets = UIEdgeInsetsMake(0,0,r.size.height,0);
}

- (void) keyboardHide: (NSNotification*) n {
    NSDictionary* d = [n userInfo];
    NSNumber* curve = d[UIKeyboardAnimationCurveUserInfoKey];
    NSNumber* duration = d[UIKeyboardAnimationDurationUserInfoKey];
    [UIView animateWithDuration:duration.floatValue delay:0
                        options:curve.integerValue << 16
                     animations:
     ^{
         [self.tv setContentOffset:CGPointZero];
     } completion:^(BOOL finished) {
         self.tv.contentInset = UIEdgeInsetsZero;
         self.tv.scrollIndicatorInsets = UIEdgeInsetsZero;
     }];
}

Underlying all text drawing on iOS is Core Text. Before iOS 6, Core Text was the only way to draw styled text on iOS; now that an NSAttributedString can be drawn directly, or handed to an built-in interface object for it to draw, you may have less need of Core Text. Nevertheless, Core Text can still do some things you can’t do in any other way, and it is sitting there under the hood, so you may as well be aware of it. It is implemented by the Core Text framework; to utilize it, your app must link to CoreText.framework, and your code must import <CoreText/CoreText.h>. It uses C, not Objective-C, and it’s rather verbose, but getting started with it is not difficult.

A good example of the sort of thing Core Text can do that can’t be done any other way is to convert between fonts within a font family. Under CoreText, a font is a CTFont (a CTFontRef), a type which is unfortunately not bridged to UIFont. In this example, I’ll create an attributed string using only Core Text calls. You can use an NSAttributed string or its Core Foundation counterpart, CFAttributedString; they, at least, are toll-free bridged. The Core Text attribute names are listed in Apple’s Core Text String Attributes Reference, along with their value types.

I’ll start with a mutable attributed string:

NSString* s = @"Yo ho ho and a bottle of rum!";
NSMutableAttributedString* mas =
    [[NSMutableAttributedString alloc] initWithString:s];

Now I’ll apply some attributes, using Core Text calls exclusively. I’ll cycle through the words of the string; to each word I’ll apply a slightly larger size of the same font. The name supplied when creating a CTFont must be a PostScript name; a free app, Typefaces, is helpful for learning all the fonts on a device along with their PostScript names:

__block CGFloat f = 18.0;
CTFontRef basefont = CTFontCreateWithName((CFStringRef)@"Baskerville", f, nil);
[s enumerateSubstringsInRange:NSMakeRange(0, [s length])
                      options:NSStringEnumerationByWords
                   usingBlock:
 ^(NSString *substring, NSRange substringRange, NSRange encRange, BOOL *stop) {
     f += 3.5;
     CTFontRef font2 = CTFontCreateCopyWithAttributes(basefont, f, nil, nil);
     NSDictionary* d2 =
         @{(NSString*)kCTFontAttributeName: CFBridgingRelease(font2)};
     [mas addAttributes:d2 range:encRange];
 }];

Finally, I’ll make the last word bold. The easiest way to obtain the range of the last word is to cycle through the words backward and stop after the first one (by setting the incoming BOOL, stop, by indirection). Boldness is a font trait; we must obtain a bold variant of the original font. The font we started with, Baskerville, has such a variant, so this will work:

[s enumerateSubstringsInRange:NSMakeRange(0, [s length])
                      options: (NSStringEnumerationByWords |
                                NSStringEnumerationReverse)
                   usingBlock:
 ^(NSString *substring, NSRange substringRange, NSRange encRange, BOOL *stop) {
     CTFontRef font2 =
         CTFontCreateCopyWithSymbolicTraits (
             basefont, f, nil, kCTFontBoldTrait, kCTFontBoldTrait);
     NSDictionary* d2 =
         @{(NSString*)kCTFontAttributeName: CFBridgingRelease(font2)};
     [mas addAttributes:d2 range:encRange];
     *stop = YES; // do just once, last word
 }];

Finally, let’s not forget to complete our memory management:

CFRelease(basefont);

(And did you notice the cool use of ARC’s CFBridgingRelease? Recall from Chapter 12 that this is a way of crossing the bridge from a CFTypeRef to an Objective-C object and, at the same time, giving ARC responsibility for completing the memory management that we started by calling a Create function.)

You’re probably wondering why I seem to ask for the bold variant (kCTFontBoldTrait) twice. The first time (the fourth argument in the call to CTFontCreateCopyWithSymbolicTraits) I’m providing a bitmask. The second time (the fifth argument) I’m providing a second bitmask that says which bits of the first bitmask are meaningful. For example, suppose I’m starting with a font that might or might not be italic, and I want to obtain its bold variant — meaning that if it is italic, I want a bold italic font. It isn’t enough to supply a bitmask whose value is kCTFontBoldTrait, because this appears to switch boldness on and everything else off. Thus, the second bitmask says, “Only this one bit is important; leave all other attributes alone.” By the same token, to get a nonbold variant of a font that might be bold, you’d supply 0 as the fourth argument and kCTFontBoldTrait as the fifth argument.

Core Text can also draw into a graphics context. Text will be drawn upside-down unless we flip the graphics context’s coordinate system. Positioning the drawing is up to us.

If the string is a single line we can draw it directly into a graphics context with a CTLineRef. The following code, in a custom UIView subclass, draws the attributed string we created a moment ago (Figure 23.5):

- (void)drawRect:(CGRect)rect {
    if (!self.text)
        return;
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    // flip context
    CGContextSaveGState(ctx);
    CGContextTranslateCTM(ctx, 0, self.bounds.size.height);
    CGContextScaleCTM(ctx, 1.0, -1.0);
    CTLineRef line =
        CTLineCreateWithAttributedString(
            (__bridge CFAttributedStringRef)self.text);
    CGContextSetTextPosition(ctx, 1, 3);
    CTLineDraw(line, ctx);
    CFRelease(line);
    CGContextRestoreGState(ctx);
}

Figure 23.5. A single line of text, drawn by Core Text

If we want our string to be drawn wrapped, we must use a CTFramesetter. The framesetter requires a frame into which to draw; this is expressed as a CGPath, but don’t get all excited about the possibility of drawing wrapped into some interesting shape, such as an ellipse, because on iOS the path must describe a rectangle:

- (void)drawRect:(CGRect)rect {
    if (!self.text)
        return;
    CGContextRef ctx = UIGraphicsGetCurrentContext();
    // flip context
    CGContextSaveGState(ctx);
    CGContextTranslateCTM(ctx, 0, self.bounds.size.height);
    CGContextScaleCTM(ctx, 1.0, -1.0);
    CTFramesetterRef fs =
        CTFramesetterCreateWithAttributedString(
            (__bridge CFAttributedStringRef)self.text);
    CGMutablePathRef path = CGPathCreateMutable();
    CGPathAddRect(path, nil, rect);
    // range (0,0) means "the whole string"
    CTFrameRef f = CTFramesetterCreateFrame(fs, CFRangeMake(0, 0), path, nil);
    CTFrameDraw(f, ctx);
    CGPathRelease(path);
    CFRelease(f);
    CFRelease(fs);
    CGContextRestoreGState(ctx);
}

That code wraps, but the text is left-aligned. Paragraph-level behaviors such as alignment and truncation can be expressed as part of the attributed string itself by applying a CTParagraphStyle. Paragraph styles can also include first-line indent, tab stops, line height, spacing, line break mode, and more. To center our text (which results in a drawing that looks like Figure 23.6), we apply a centered style before drawing it:

NSMutableAttributedString* mas = [self.text mutableCopy];
NSString* s = [mas string];
CTTextAlignment centerValue = kCTCenterTextAlignment;
CTParagraphStyleSetting center =
    {kCTParagraphStyleSpecifierAlignment, sizeof(centerValue), &centerValue};
CTParagraphStyleSetting pss[1] = {center};
CTParagraphStyleRef ps = CTParagraphStyleCreate(pss, 1);
[mas addAttribute:(NSString*)kCTParagraphStyleAttributeName
            value:CFBridgingRelease(ps)
            range:NSMakeRange(0, [s length])];
self.text = mas;

Figure 23.6. Text wrapped and centered, drawn by Core Text

Core Text can also access font typographical features that can’t be accessed in any other way, such as the built-in ability of Didot and Hoefler Text to render themselves in small caps. As an example, we’ll draw the names of the 50 U.S. states in small caps, centered, in two columns on an iPad (Figure 23.7).

Figure 23.7. Two-column text in small caps

As we create the NSAttributedString, we use a convenience function, CTFontDescriptorCreateCopyWithFeature, to access Didot’s small caps variant. I had to log the result of CTFontCopyFeatures to learn how to access this variant of this font (there is also old documentation of font features at http://developer.apple.com/fonts/registry). We apply a centered style, as before:

NSString* path =
    [[NSBundle mainBundle] pathForResource:@"states" ofType:@"txt"];
NSString* s =
    [NSString stringWithContentsOfFile:path
     encoding:NSUTF8StringEncoding error:nil];
CTFontRef font = CTFontCreateWithName((CFStringRef)@"Didot", 18, nil);
CTFontDescriptorRef fontdesc1 = CTFontCopyFontDescriptor(font);
// names come from SFNTLayoutTypes.h (iOS 6 new feature)
CTFontDescriptorRef fontdesc2 =
CTFontDescriptorCreateCopyWithFeature(fontdesc1,
    (__bridge CFNumberRef)@(kLetterCaseType),
    (__bridge CFNumberRef)@(kSmallCapsSelector));
CTFontRef basefont = CTFontCreateWithFontDescriptor(fontdesc2, 0, nil);
NSDictionary* d =
    @{(NSString*)kCTFontAttributeName: CFBridgingRelease(basefont)};
NSMutableAttributedString* mas =
    [[NSMutableAttributedString alloc] initWithString:s attributes:d];
CTTextAlignment centerValue = kCTCenterTextAlignment;
CTParagraphStyleSetting center =
    {kCTParagraphStyleSpecifierAlignment, sizeof(centerValue), &centerValue};
CTParagraphStyleSetting pss[1] = {center};
CTParagraphStyleRef ps = CTParagraphStyleCreate(pss, 1);
[mas addAttribute:(NSString*)kCTParagraphStyleAttributeName
            value:CFBridgingRelease(ps)
            range:NSMakeRange(0, [s length])];
CFRelease(font); CFRelease(fontdesc1); CFRelease(fontdesc2);

The two-column arrangement is achieved by drawing into two frames. In our drawRect: code, after flipping the context as before (not shown), we draw the entire text into the first frame and then use CTFrameGetVisibleStringRange to learn how much of the text actually fits into it; this tells us where in the attributed string to start drawing into the second frame:

CGRect r1 = rect;
r1.size.width /= 2.0; // column 1
CGRect r2 = r1;
r2.origin.x += r2.size.width; // column 2
CTFramesetterRef fs =
    CTFramesetterCreateWithAttributedString(
        (__bridge CFAttributedStringRef)self.text);
// draw column 1
CGMutablePathRef path = CGPathCreateMutable();
CGPathAddRect(path, nil, r1);
CTFrameRef f = CTFramesetterCreateFrame(fs, CFRangeMake(0, 0), path, nil);
CTFrameDraw(f, ctx);
CGPathRelease(path);
CFRange drawnRange = CTFrameGetVisibleStringRange(f);
CFRelease(f);
// draw column 2
path = CGPathCreateMutable();
CGPathAddRect(path, nil, r2);
f = CTFramesetterCreateFrame(fs,
        CFRangeMake(drawnRange.location + drawnRange.length, 0), path, nil);
CTFrameDraw(f, ctx);
CGPathRelease(path);
CFRelease(f);
CFRelease(fs);

The result is Figure 23.7. But now let’s go further. A frame is itself composed of CTLines describing how each line of text was laid out. To demonstrate, let’s turn our two-column list of states into an interactive interface: when the user taps the name of a state, we’ll fetch that name, and we’ll briefly draw a rectangle around the name to provide feedback (Figure 23.8).

Figure 23.8. The user has tapped on California

We have two NSMutableArray properties, theLines and theBounds. We initialize them to empty arrays at the start of our drawRect:, and each time we call CTFrameDraw we also call a utility method:

[self appendLinesAndBoundsOfFrame:f context:ctx];

In appendLinesAndBoundsOfFrame:context: we save the CTLines of the frame into theLines; we also calculate the drawn bounds of each line and save it into theBounds:

- (void) appendLinesAndBoundsOfFrame:(CTFrameRef)f context:(CGContextRef)ctx{
    CGAffineTransform t1 =
        CGAffineTransformMakeTranslation(0, self.bounds.size.height);
    CGAffineTransform t2 = CGAffineTransformMakeScale(1, -1);
    CGAffineTransform t = CGAffineTransformConcat(t2, t1);
    CGPathRef p = CTFrameGetPath(f);
    CGRect r = CGPathGetBoundingBox(p); // this is the frame bounds
    NSArray* lines = (__bridge NSArray*)CTFrameGetLines(f);
    [self.theLines addObjectsFromArray:lines];
    CGPoint origins[[lines count]];
    CTFrameGetLineOrigins(f, CFRangeMake(0,0), origins);
    for (int i = 0; i < [lines count]; i++) {
        CTLineRef aLine = (__bridge CTLineRef)lines[i];
        CGRect b = CTLineGetImageBounds((CTLineRef)aLine, ctx);
        // the line origin plus the image bounds size is the bounds we want
        CGRect b2 = { origins[i], b.size };
        // but it is expressed in terms of the frame, so we must compensate
        b2.origin.x += r.origin.x;
        b2.origin.y += r.origin.y;
        // we must also compensate for the flippedness of the graphics context
        b2 = CGRectApplyAffineTransform(b2, t);
        [self.theBounds addObject: [NSValue valueWithCGRect:b2]];
    }
}

We have attached a UITapGestureRecognizer to our view; when the user taps, we cycle through the saved bounds to see if any of them contains the tap point. If it does, we fetch the name of the state, and we draw a rectangle around it:

- (void) tapped: (UITapGestureRecognizer*) tap {
    CGPoint loc = [tap locationInView:self];
    for (int i = 0; i < [self.theBounds count]; i++) {
        CGRect rect = [self.theBounds[i] CGRectValue];
        if (CGRectContainsPoint(rect, loc)) {
            // draw rectangle for feedback
            CALayer* lay = [CALayer layer];
            lay.frame = CGRectInset(rect, -5, -5);
            lay.borderWidth = 2;
            [self.layer addSublayer: lay];
            dispatch_time_t popTime =
                dispatch_time(DISPATCH_TIME_NOW, 0.3 * NSEC_PER_SEC);
            dispatch_after(popTime, dispatch_get_main_queue(), ^(void){
                [lay removeFromSuperlayer];
            });
            // fetch the drawn string tapped on
            CTLineRef theLine =
                (__bridge CTLineRef)[self.theLines[i];
            CFRange range = CTLineGetStringRange(theLine);
            CFStringRef s = CFStringCreateWithSubstring(
                nil, (__bridge CFStringRef)[self.text string], range);
            // ... could do something useful with string here ...
            NSLog(@"tapped %@", s);
            CFRelease(s);
            break;
        }
    }
}

If we needed to, we could even learn what character the user tapped by going down to the level of glyph runs (CTRun) and glyphs (CTGlyph). We have barely scratched the surface of what Core Text can do. Read Apple’s Core Text Programming Guide for further information.