Syntax Coloring for Document-Based Applications

Uli Kusterer’s UKSyntaxColoredTextDocument does syntax coloring as you type for HTML, Objective-C and CSS files, and it can be extended to handle other languages by adding appropriate property list files. Using it effectively took some effort, so I hope this will smooth the way for other developers who want to have this functionality in their applications.

My application is an HTML editor, which has keyboard shortcuts for all the tags I could think of (25 so far!), and templates for common document types. The initial set up went quickly, and I was default syntax coloring immediately. The issues arose when I wanted to change from the pre-set default coloring, and had a hard time getting it to read my edited version of the HTML coloring file.

I was able to get it to read the files and get the coloring I wanted, but I’m not sure this is the best way to do it. Uli himself probably has a better way, but this is the one I’ve figured out. If you’re interested in using UKSyntaxColoredTextDocument, follow along!

Creating an Application

The first version of this application will just use the default coloring for HTML files. After that, I’ll show you how I altered Uli’s code to use my own coloring scheme.

First, you need to download the files for UKSyntaxColoredTextDocument from GitHub, here. I’m a brand-new user of git, so I won’t try to advise you on the details. Next, create a Cocoa Document-based application, and besides adding the Objective-C and header files to your project, also add…

  • the Syntax Definitions folder (and the plist files it contains)
  • SelectionRange.tiff
  • InsertionMark.tiff
  • SyntaxColorDefaults.plist, and
  • SyntaxDefinition.plist

It would also be good form to change Credits.rtf to acknowledge that you’re using UKSyntaxColoredTextDocument.

Next, go to the header file for the NSDocument subclass that Xcode created for you, MyDocument.h, and change its super class to UKSyntaxColoredTextDocument and add #import "UKSyntaxColoredTextDocument.h" to the top of the file. Now it’s time to set up the user interface.

Setting up your nib file

In Xcode, under the Resouces folder, double-click MyDocument.xib to run Interface Builder. Onto the nib’s window, drag…

  • a vertical line,
  • a label,
  • a circular progress indicator, and
  • an image well.

Select the image well, type command-1 to bring up its attributes, and change its Border to None and its Scaling to None. Choose its Image to be InsertionMark, and under layout, select Size to Fit (or press command-=). Now arrange them along the top of the window, with the image on the left, the vertical line next to it, followed by the label and finally the progress indicator. You may want to look at the nib in the original UKSyntaxColoredTextDocument project to see how Uli did this. Go to the sizing tab of the info window and set the label to stretchy in width. The label, vertical line and image should stick to the upper left of the window, and the progress indicator should stick to the upper right.

Control-drag from the File’s owner to the image view, and connect it to the selectionKindImage outlet, and likewise connect the label to the File’s owners status outlet, and the progress indicator to progress outlet, and the text view to the textView outlet. This wraps up the UI for the first version.

Adding a Splash of Code

Now go back to Xcode. We need to let UKSyntaxColoredTextDocument know what kind of syntax coloring we want. Add this method (syntaxDefinitionFilename) to the end of MyDocument.mto syntax color HTML code:

-(NSString*) syntaxDefinitionFilename {
	return @"HTML";

The UKSyntaxColoredTextDocument class loads files with the deprecated loadDataRepresentation:ofType: method, while the template that Xcode provided probably has the newer readFromData:ofType:error: method. This results in nothing happening when you have your app open a file, so comment out dataOfType:error: in MyDocument.m to use the code from UKSyntaxColoredTextDocument. Likewise, comment out dataOfType:error: in MyDocument.m in order to use dataRepresentationOfType: from UKSyntaxColoredTextDocument.

By default, UKSyntaxColoredTextDocument uses NSMacOSRomanStringEncoding to store its data, but if you don’t like that, you can change that by overriding stringEncoding like this:

-(NSStringEncoding) stringEncoding {
    return NSUTF8StringEncoding;

Now build and run your application. If all goes well, you should be able to enter HTML and see the tags colored blue and selected entities (such as <, > and &) colored green. The status label at the top will tell you what line and character you’re at. The application also does automatic indentation, just what we code monkeys want! (It is possible to turn that off, but I haven’t bothered trying that yet).

The next post will cover changing your application to handle Objective-C or CSS, and the one after that will cover customizing the coloring schemes. If you’d like me to post my code or the project, let me know.

This entry was posted in Syntax Coloring. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s