Syntax Formatting and Styles
Syntax Formatting and Styles
Syntax Formatting is an important Source Insight feature that renders information in a dense, yet pleasing and useful way.
Syntax Formatting uses rich text formatting based on program information. Source Insight uses information gathered from its parsers to format source code. Identifiers can be displayed in different fonts or font sizes, along with a variety of effects such as bold and italics.
76 Source Insight 4 User Guide
Syntax Formatting and Styles
For example, in the image below, it’s easy to tell the difference between class members and local variables, because class members are styled in italics.
Formatting is applied with "styles". A style is a set of formatting properties. For example, a style may specify bold + italic. You can edit each style's formatting properties with the Options > Style Properties command.
See “Style Properties” on page 333.
Formatting styles are applied to source code elements automatically, based on parsing information. There are many predefined styles that correspond to syntax elements. For example, there is a style for a function definition, and another style for class definition. You can also add your own styles that you can explicitly associate with keywords or identifiers.
Source Insight 4 User Guide 77
Syntax Formatting and Styles
How Styles Apply to Source Code
Styles are automatically applied to source code text. With the exception of comment styles, you cannot explicitly apply a style yourself, like in a word processor. The applicable language parser is used to assign styles based on parsed information.
Styles are used automatically for the following:
•
Language keywords, for example C keywords such as while
, and void
.
•
Delimiters and numbers.
•
Comments
•
Declarations of symbols - for example a function declaration.
•
References to symbols - for example, a call to a function.
•
User-defined identifier associations - You can explicitly associate a style with any identifier by editing the language’s keyword list.
How a Style Works
Styles contain formatting instructions that can be combined with other styles. When a style is applied to text, it combines with the underlying text properties. The basic text properties are set in each file type's font settings. You can control this with the Options > File Type Options command. Style properties are combined
with the basic text properties. Styles also can inherit properties from other "parent" styles. See “Parent
Styles” on page 79.
The formatting properties of all the applicable styles are combined with the font selected in a given file's type.
Figure 3.6 Style properties combine with each other, and with the default font set in the File Types dialog box.
Formatting Properties
Each style is like a list of formatting differences from its parent style. For example if a style has the "bold" property, then "bold" is added to the parent. Each formatting item has the following possible states:
•
On
The formatting property is added. E.g. Bold-On
•
Off
The formatting property is removed. E.g. Bold-Off
•
A Number
This number applies to items like scaling, or font point size. E.g. scaling = 120%.
•
Font Name
This overrides the font used.
•
No Change
The style has no effect on the formatting property. It inherits the properties of the parent style.
78 Source Insight 4 User Guide
Syntax Formatting and Styles
Parent Styles
Styles inherit formatting properties from parent styles. Each style has a "Parent Style" property. Therefore the styles form a hierarchy. For example, the built-in styles contain a hierarchy for Declarations, a portion of which looks like this:
Figure 3.7 An example of a style hierarchy.
In the Style Properties dialog, the style hierarchy is displayed visually. See “Style Properties” on page 333.
Formatting properties in a style are combined with its parent style. Thus, the Declare Struct style inherits the formatting properties of the Declaration style. You can affect changes to all declaration styles by altering the single Declaration style.
The topmost parent style is the "Default Text" style. Its formatting properties are determined by the file type's font settings.
You can change the parent style of any style using the Style Properties command.
Source Insight 4 User Guide 79
Syntax Formatting and Styles
In the figure below is an example of how styles might combine for a function declaration.
Figure 3.8 Style properties "add up" on top of the default font specified by the file type.
Language Keyword Styles
The simplest application of styles is for formatting language keywords. Each language contains a keyword list. Each keyword list item associates a keyword, for example while
, with a style. The keyword list is editable. Source Insight displays the keyword using the associated style. You can edit the language keyword list
in the Preferences: Languages dialog box, or by invoking the Keyword List command directly. See “Language
Options” on page 235.
To determine the formatting of any given word in a window, Source Insight locates the word in the keyword list of the appropriate language type. The keyword list contains a style name, which in turn implies the formatting associated with the style.
Therefore, starting with a file name and a word in the file, Source Insight derives the word's style with this relationship:
Figure 3.9 The style used for a word in source text is determined by the keyword list of the language of the file type of the file in question.
Declaration Styles
Wherever a symbol is declared or defined, its name is formatted with an appropriate "Declaration" style.
There are declaration styles for different types of things, like structs, classes, unions, functions, etc.
80 Source Insight 4 User Guide
Syntax Formatting and Styles
For example, a structure might look like this:
The structure name "CLIP" is shown in the "Declare Struct" style. The member fields inside the struct are shown in the "Declare Member" style. There are several styles named "Declare...something".
If you select Options > Style Properties, you can see all the declaration styles. Their names all start with
"Declare...".
Reference Styles
References to symbols that are not actual declarations are formatted with an appropriate "Reference" style.
There are reference styles for different types of symbols. Reference formatting gives you a lot of information without having to ask for it. It becomes instantly obvious if you have misspelled a function name, or whether you are using a constant, or a local variable, or a global variable.
For example, a code fragment might look like:
The call to "SeekTokenLnIch" is formatted with the "Ref to Function" style. The C macro function "HdocOfTgl" is formatted with the "Ref to Macro" style, which helps you know just by looking at it that it is a macro. The parameter "hpar" is formatted with the "Ref to Parameter" style, so we know it is a parameter passed to the current function. The identifier "htglLocal" is formatted with the "Ref to Local Variable" style, so we know it is a local variable in the current function. The "kswaChangeMark" constant is formatted with the "Ref to Constant" style, so we know it is either a #define or enum value.
Distinguishing Class and Struct Members
Reference styles are also useful to distinguish member variables and member functions from other variables.
In this example, the function
DoSomething
is referencing both member variables, and a file-scope function and a global variable. The reference styles make each reference look different. The Ref To Member styles in
Source Insight 4 User Guide 81
Syntax Formatting and Styles
this example have been given the Italic property. So, for example, the references to valueTest
inside the
DoSomething
function is shown in italic. This tells you that valueTest
is a member variable.
If you select Options > Style Properties, you can see all the reference styles. Their names all start with "Ref to...".
Note:
Enabling reference formatting can slow the display down in some cases. Source Insight needs to perform symbol lookup operation each time it encounters a potential symbol reference.
Inactive Code Style
For languages that support #if and #ifdef statements, Source Insight recognizes inactive blocks of code based on the value of the conditions. You can edit the conditional values by selecting Options > Preferences: Lan-
guage
and clicking either "Project Specific Conditions" or "Global Conditions". You can also click inside a conditional identifier, then rigth-click and select Edit Condition.
Blocks of code that are inactive are given the "Inactive Code" style. For more information, see “Conditional
Parsing” on page 58.
82 Source Insight 4 User Guide
Syntax Formatting and Styles
Comment Styles
Source Insight adds some explicit formatting to comments. All comments inherit from the Comment parent style. The comment style hierarchy appears below.
Figure 3.10 The comment styles hierarchy.
Comment Heading Styles
Comment heading styles are very useful for breaking up large chunks of code with high-level comments.
Source Insight 4 User Guide 83
Syntax Formatting and Styles
Comment Heading styles are specified with a
//n
comment prefix, where n is a number between 1 and 4. For example:
//1 This is a Heading 1 comment
//2 This is a Heading 2 comment
//3 This is a Heading 3 comment
//4 This is a Heading 4 comment
When the comment displays, the
//n
at the beginning of the comment is hidden, unless the cursor is on that line. The above lines appear like this:
If the cursor is on the line, then the
//n
will appear so that you can edit it.
Comment Right Style
Comments that appear to the right of code are given the "Comment Right" style. For example:
Single and Multi Line Comment Styles
Multi-Line comments are displayed in the Comment Multi Line style. These are any comments using the
/* and
*/
delimiters in C/C++ and Java.
Single line comments are displayed in the Comment Line style. These include comments that start with
// delimiters in C/C++ and Java.
Comment Styles and Custom Languages
When you define a custom language, using the Preferences: Languages dialog box, you can specify comment or text-range types, and associate them with a style. For example, you could create a comment range that starts with (* and ends with *) and the text is formatted with the "Comment Multi Line" style. You can actually
define any delimited range of text, and associate it with any style (including a non-comment style).See “Sym-
bols and Language Parsing” on page 52. and “Special Language Options” on page 237.
84 Source Insight 4 User Guide
Syntax Formatting and Styles
Syntax Decorations
Syntax Decorations add extra information to your code display.
Source Insight can replace some common operators with more useful symbolic characters. The Preferences:
Syntax Decorations
command controls which decorations are used.
The symbolic characters are formatted with the "Symbol Characters" style. If you use the Options > Style
Properties
command to look at the Symbol Characters style, you will see that it uses the Symbol font. You may change the style's properties, such as the color or font size, but if you change the font name to something other than Symbol, your syntax decoration symbols will probably not show up correctly.
Note:
It's important to remember that symbol substitutions do not change the text in the source file; only its representation on the screen changes to show the special symbols. You still need to type the operators normally when editing your code, or when searching for them.
Operator Substitutions
Common operators, such as the pointer dereference right arrow (
->
), or the assignment operator (
=
) can be replaced with symbolic operators, such as arrows. For example, instead of this:
With decorations on, the
=
and
->
are replaced with arrows:
Boolean, math, and other operators can be substituted with decorative symbols too.
Source Insight 4 User Guide 85
Syntax Formatting and Styles
Scaled Nested Parentheses
Source Insight can display nested parentheses in different sizes to make it easier to identify matching sets.
This even works across multiple lines.
Goto Arrows
Another useful decoration is the "goto arrow". An up or down arrow appears in goto statements which points in the direction of the target label.
End Brace Annotations
Source Insight can also add automatic "end brace" annotations to the closing curly brace in C/C++/C# and
Java code. This makes it easier to understand nested if, while, switch, and other blocks of code.
Controlling Syntax Formatting
You have control over how Source Insight formats your code.
Changing Style Properties
The Style Properties command controls the formatting properties of each style. You can also add your own styles, and import and export them.
The Syntax Formatting command
The Preferences: Syntax Formatting command controls how much display formatting is applied. You can
speed up the display by disabling some options here. For more information, see “Syntax Formatting” on page 346.
The Syntax Decorations command
This Preferences: Syntax Decorations command controls what syntax decorations are performed.
Turning off Syntax Formatting
The Syntax Formatting features of Source Insight are powerful, but sometimes you may want to see how text will line up in another editor, or in a simple display mode when only a single font is used.
86 Source Insight 4 User Guide
Syntax Formatting and Styles
Switching off Syntax Formatting temporarily
If you want to temporarily see your files without syntax formatting, use the View > Mono Font View command.
Mono Font mode is useful for quickly switching your display to a basic monospaced font display. This is particularly useful if you are using spaces instead of tab characters to line columns up. When Mono Font mode is active, it overrides the settings of the Preferences: Syntax Formatting and Syntax Decorations dialog boxes.
Keeping fonts from changing
If you want to just see only color formatting, but no font changes, or font embellishments such as bold and italic, then use the Options > Preferences: Syntax Formatting dialog box and check the Use only color for-
matting
box.
Changing the font used to display source code
To change the base font used to display source code, open a source file, and select Options > File Type
Options
. The file type for the current source file will be automatically selected as the active file type. Click the
Screen Fonts button and pick the desired font. This font will become the new base default font for that file type. For example, a style for declarations might add "bold". Or a style might specify a different font and override the screen font selection in the file type.
When you click OK in the font selection dialog, you will see this prompt:
To apply the font to ALL the file types, type "yes" in the box and click OK. To only apply it to the current file type, click No.
Source Insight 4 User Guide 87