[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Font Locking

Please note: The font locking in AWK mode is currently not integrated with the rest of CC Mode, so this section does not apply there. See section 12.2 AWK Mode Font Locking, instead.

CC Mode provides font locking for its supported languages by supplying patterns for use with Font Lock mode. This means that you get distinct faces on the various syntactic parts such as comments, strings, keywords and types, which is very helpful in telling them apart at a glance and discovering syntactic errors. See section `Font Lock' in The Emacs Editor, for ways to enable font locking in CC Mode buffers.

7.1 Font Locking Preliminaries  
7.2 Faces  
7.3 Documentation Comments  

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 Font Locking Preliminaries

The font locking for most of the CC Mode languages were provided directly by the Font Lock package prior to version 5.30 of CC Mode. In the transition to CC Mode the patterns have been reworked completely and are applied uniformly across all the languages except AWK mode, just like the indentation rules (although each language still has some pecularities of its own, of course). Since the languages previously had completely separate font locking patterns, this means that it's a bit different in most languages now.

The main goal for the font locking in CC Mode is accuracy, to provide a dependable aid in recognizing the various constructs. Some, like strings and comments, are easy to recognize while others like declarations and types can be very tricky. CC Mode can go to great lengths to recognize declarations and casts correctly, especially when the types aren't recognized by standard patterns. This is a fairly demanding analysis which can be slow on older hardware, and it can therefore be disabled by choosing a lower decoration level with the variable font-lock-maximum-decoration.

The decoration levels are used as follows:

  1. Minimal font locking: Fontify only comments, strings and preprocessor directives (in the languages that use cpp).

  2. Fast normal font locking: In addition to level 1, fontify keywords, simple types and declarations that are easy to recognize. The variables *-font-lock-extra-types (where `*' is the name of the language) are used to recognize types (see below). Documentation comments like Javadoc are fontified according to c-doc-comment-style (see section 7.3 Documentation Comments).

    Use this if you think the font locking is too slow. It's the closest corresponding level to level 3 in the old font lock patterns.

  3. Accurate normal font locking: Like level 2 but uses a different approach that can recognize types and declarations much more accurately. The *-font-lock-extra-types variables are still used, but user defined types are recognized correctly anyway in most cases. Therefore those variables should be fairly restrictive and not contain patterns that are uncertain.

    This level is designed for fairly modern hardware and a font lock support mode like Lazy Lock or Just-in-time Lock mode that only fontifies the parts that are actually shown.

Since user defined types are hard to recognize you can provide additional regexps to match those you use:

User Option: c-font-lock-extra-types
User Option: c++-font-lock-extra-types
User Option: objc-font-lock-extra-types
User Option: java-font-lock-extra-types
User Option: idl-font-lock-extra-types
User Option: pike-font-lock-extra-types
For each language there's a variable *-font-lock-extra-types, where `*' stands for the language in question. It contains a list of regexps that matches identifiers that should be recognized as types, e.g. `\\sw+_t' to recognize all identifiers ending with `_t' as is customary in C code. Each regexp should not match more than a single identifier.

The default values contain regexps for many types in standard runtime libraries that are otherwise difficult to recognize, and patterns for standard type naming conventions like the `_t' suffix in C and C++. Java, Objective-C and Pike have as a convention to start class names with capitals, so there are patterns for that in those languages.

Despite the names of these variables, they are not only used for fontification but in other places as well where CC Mode needs to recognize types.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 Faces

CC Mode attempts to use the standard faces for programming languages in accordance with their intended purposes as far as possible. No extra faces are currently provided, with the exception of a replacement face c-invalid-face for emacsen that don't provide font-lock-warning-face.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3 Documentation Comments

There are various tools to supply documentation in the source as specially structured comments, e.g. the standard Javadoc tool in Java. CC Mode provides an extensible mechanism to fontify such comments and the special markup inside them.

User Option: c-doc-comment-style
This is a style variable that specifies which documentation comment style to recognize, e.g. javadoc for Javadoc comments.

The value may also be a list of styles, in which case all of them are recognized simultaneously (presumably with markup cues that don't conflict).

The value may also be an association list to specify different comment styles for different languages. The symbol for the major mode is then looked up in the alist, and the value of that element is interpreted as above if found. If it isn't found then the symbol `other' is looked up and its value is used instead.

Note that CC Mode uses this variable to set other variables that handle fontification etc. That's done at mode initialization or when you switch to a style which sets this variable. Thus, if you change it in some other way, e.g. interactively in a CC Mode buffer, you will need to do M-x java-mode (or whatever mode you're currently using) to reinitialize.

Note also that when CC Mode starts up, the other variables are modified before the mode hooks are run. If you change this variable in a mode hook, you have to call c-setup-doc-comment-style afterwards to redo that work.

CC Mode currently provides handing of the following doc comment styles:

Javadoc comments, the standard tool in Java.

For Pike autodoc markup, the standard in Pike.

The above is by no means complete. If you'd like to see support for other doc comment styles, please let us know (see section C. Mailing Lists and Submitting Bug Reports).

You can also write your own doc comment fontification support to use with c-doc-comment-style: Supply a variable or function *-font-lock-keywords where `*' is the name you want to use in c-doc-comment-style. If it's a variable, it's prepended to font-lock-keywords. If it's a function, it's called at mode initialization and the result is prepended. For an example, see javadoc-font-lock-keywords in `cc-fonts.el'.

If you add support for another doc comment style, please consider contributing it -- send a note to bug-cc-mode@gnu.org.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by XEmacs Webmaster on October, 2 2007 using texi2html