SourceInsight4UserGuide PDF
SourceInsight4UserGuide PDF
0
User Guide
Copyright © 2018 by Source Dynamics, Inc.
3.19.2018
Symbol Naming..................................................................... 55
Resolving Symbol Definitions ................................................. 55
Common Projects .................................................................. 55
Importing Symbols from Libraries .......................................... 55
The Project Symbol Path......................................................... 56
C/C++ Symbols...................................................................... 57
C# and .NET Framework Symbols ........................................... 57
Java Symbols......................................................................... 57
HTML and Scripts................................................................... 58
PHP Pages ............................................................................. 58
Active Server Page Scripts....................................................... 58
Conditional Parsing and Preprocessor Support .............. 60
Parsing Considerations and Parsing Problems ........................ 62
Fixing "Parse-Too-Complex" ................................................... 63
Preprocessor Token Macros .................................................... 64
Name Fragment Matching Symbol Names ..................... 66
Controlling Name Fragment Matching ................................... 66
Using Name Fragment Matching ........................................... 66
Using Name Fragment Shortcuts............................................ 67
Source Control ................................................................ 68
Source Control Commands .................................................... 68
Using IBM® Rational ClearCase ® Commands .......................... 69
Using Git Commands ............................................................. 69
File Types ........................................................................ 72
File-Type-Specific Options ...................................................... 72
Associating Files with File Types.............................................. 72
Associating File Names Without Extensions ............................ 73
Adding New File Types............................................................ 73
Editing the File Types.............................................................. 73
Browsing and Analysis .................................................... 74
Symbolic Parsing ................................................................... 74
Symbol Navigation Commands.............................................. 74
Project Symbol List Window ................................................... 75
Call Trees and Reference Trees ................................................ 75
Context Window .................................................................... 75
Command Line Symbol Access ............................................... 75
Finding References to Symbols ............................................... 75
Reference Highlights .............................................................. 76
Creating a Project Report ....................................................... 76
Smart Renaming ................................................................... 76
Comparing Files and Directories............................................. 77
Syntax Formatting and Styles ......................................... 78
How Styles Apply to Source Code............................................ 80
How a Style Works ................................................................. 80
Formatting Properties ............................................................ 80
Parent Styles .......................................................................... 81
Language Keyword Styles ...................................................... 82
Declaration Styles .................................................................. 82
Reference Styles ..................................................................... 83
Inactive Code Style................................................................. 84
Comment Styles..................................................................... 85
Syntax Decorations................................................................ 87
Controlling Syntax Formatting ............................................... 88
Context window ............................................................. 90
Key Benefits
Source Insight’s important benefits are:
• It helps to understand an existing code base.
• You can quickly navigate function calls and callers.
• You can find references to functions, variables, and more - almost instantly.
• You can see call graphs and class tree diagrams.
• It previews function and class definitions without having to open a file.
• It shows live references to variables and other declarations with Syntax Formatting.
• It has powerful editing features, including code snippets, symbolic auto-completion, and smart-
rename.
• Dynamic information panels work together to create a productive workflow.
Activation Questions
Q: I want to transfer my license to a new machine, but don't have access to my old machine
anymore to deactivate it.
First, please try to simply install and activate on your new machine. There is a good chance it will activate just
fine. We allow a certain number of overages over a period of time. If the activation fails because of too many
activations, please contact [email protected].
In addition, many customers and companies using Source Insight want to know that their licenses are
authentic, and want a way to automatically stay in compliance with the license agreement.
We designed the activation system to be very low impact, and to err on the side of legitimate users. The
licensing system allows a certain number of activation overages over a period of time, so it is unlikely any
valid license will fail to activate. We absolutely do not want anybody to be stuck if they have a valid license.
on page 46.
• Export project source to HTML site. You can use this to export all the files to HTML versions that contain
most of the same syntax formatting you see in Source Insight. This basically builds a web site that can
used to browse the project source code. See “Export Project To HTML” on page 204.
• Browser Mode - Source Insight behaves as a read-only code browser. In this mode you cannot edit your
files. Simply clicking on identifiers will jump to definitions like in a web browser. Press Backspace to Go
Back, and press Space with the cursor in a symbol name to jump to its definition. Hold down CTRL
while clicking to make a regular selection. See “Browser Mode” on page 168.
• Symbol Window pane attached to each source file window now has a collapsible outline view.
• All new configuration system which keeps all your settings in XML files.
• Many improvements all over the program!
File Storage
Source Insight 4 stores most of its data in <HOMEDRIVE>/users/<user-name>/Documents/Source Insight 4.0
The folders within the "Documents/Source Insight 4.0" folder are as follows:
This chapter describes the main Source Insight program window and general information about using differ-
ent windows available in Source Insight.
The user interface of Source Insight consists mainly of:
• The main menu and toolbar area at the top.
• The source file windows that you edit files in.
• Panel windows, which can dock or float.
Source Insight is a Tabbed-MDI (Multiple Document Interface) application. This means that each source file
you open has its own child window contained within the Source Insight application window. In addition, file
window tabs appear across the top just below the toolbar area
Below is a typical window layout, showing a source file window, the Relation window, and Context window.
The main Source Insight program window, showing a source file window with a symbol window attached on
Source file
window for
editing and
viewing code
Relation
Window: shows
Symbol Window: references, call
shows symbols trees, and other
defined in each relationships
file
Context
Window:
automatically
shows
declarations and
other
information
while you click
on things or type
Multiple
document frame
When you open a source file, it appears in its own source file window. This window is where you do all of your
regular editing. File window tabs appear above the main source file area.
When you open a file that has a language attached, a Symbol Window will be attached to the left side of the
source file window. You can control whether a Symbol Window is used by selecting File Types And Options
and setting the Use symbol window check box accordingly. See “File Type Options” on page 213.
Below is a source file window, which has a symbol window attached to the left side, and the optional Over-
view Scroller control on the right edge of the source window.
Symbol Text area of source file Overview Scroller
Window
The Overview scroller shows a boundary marker around the current function that contains the selection or
insertion point. This helps to see where you are within a long function.
As you scroll within a file, the area visible within the source file window is represented by a shaded rectangle
in the Overview scroller. You can click and drag this rectangle to scroll. As you drag it near the top or bottom
of the Overview scroller, the Overview itself will scroll.
Shortcuts
To quickly set the magnification level, put the mouse cursor over the Overview scroller, and hold down the
Ctrl key while rolling the mouse wheel.
To scroll the Overview scroller itself (not the source window), put the mouse cursor over the Overview
scroller and use the mouse wheel. To scroll in bigger increments, hold down the Shift key while using the
mouse wheel.
Symbol Windows
Symbol Windows appear at the left side of each source file window. The Symbol Window lists all the symbols
declared in the file to allow easy navigation within each file, and to provide a quick overview of the file. For
example, it lists all functions, structs, classes, macros, constants, and so on. There is a small icon to the left of
each item in the Symbol Window list, which describes the type of the symbol. The Symbol Window also dis-
plays #ifdef-#endif nesting levels.
Source Insight dynamically updates the Symbol Window. If you type in a new declaration, the symbol will
appear right away in the Symbol Window.
Data structure symbols, such as classes, display in a bold font. Also, functions whose length is greater than
the average in that file are displayed in bold. The idea being that larger functions may be more important.
You can also drag symbols from one Symbol Window to another, or within the same file.
File Name
Symbol window
toolbar
At the bottom of the Symbol Window is a small toolbar. There are controls for sorting the list. You can right-
click on the Symbol Window to bring up its shortcut menu.
This records the window’s width, symbol sorting, and symbol type filtering and uses those parameters as the
new default for new windows created from now on.
Panel Windows
Panel windows are tool windows that can float in front of the main application window, and they can be
docked to various places along the main window. By dragging a floating window to an edge of the main win-
dow, you can dock it to the main window. Panel windows can float outside the application window, or even
on another monitor.
Below is an example of the Snippet Window floating in front of the main application window. The Snippet
Window is an example of a floating window that stays in front of the main Source Insight window. You can
also dock it to the edge of the program window.
Panel windows have a sticky behavior when you move them close to each other, or the edge of the Source
Insight application window. They will snap to the edge of a neighboring window, and they will automatically
resize if an adjacent panel window is resized.
The docked and floating layout of all the panel windows is saved in a layout file. You can quickly load differ-
ent panel layouts by selecting View > Load Layout..., or clicking one of the A-D layout buttons in Layout tool-
bar:
Note: To get a floating window to dock where you want it, drag it so that the mouse cursor itself is near the edge
where you want to dock the window.
Figure 2.1 Dragging a panel over another docked panel to dock it.
Docking Positions
You can dock a panel window in any of the following locations:
• Any outer edge of the main application window
• Any inner edge of the main window inside other docked panels.
• A split point inside another docked panel. Dragging over a docked panel will show a potential docking
position that is half the size of the existing panel.
• You can also leave the panel floating in front or outside of the main window, or on another monitor.
Close Panel
The transparency control is only shown if the panel is floating and the "Enable transparent panels" option is
enabled inside the Options > Preferences: Display.
Minimize
Tab Tray appears at the bottom when you minimize a panel window
To adjust the transparency amount, click on the transparency button in the panel’s window-control toolbar.
Toolbars
The main toolbar appears at the top of the Source Insight program window. You can toggle the whole main
toolbar on and off with the View > Toolbars > Main Toolbar command.
The main toolbar is made up of smaller sub toolbars. Each sub toolbar can be displayed independently using
the View > Toolbars menu. You can also drag the sub toolbars around within the main toolbar.
The position of each toolbar is saved in the configuration file automatically.
Each toolbar icon corresponds to a Source Insight command. Please refer to the Command Reference chap-
ter for information on each command.
To set options, click the Options button. See “File Search Bar Options” on page 212.
Browse Toolbar
The Browse toolbar shows the navigation operations, like in a web browser.
Go Back Go Forward
Standard Toolbar
The Standard toolbar contains the basic file operations.
New Open Save As
This chapter contains overviews of Source Insight's important features and concepts.
As you read this chapter, you will become familiar with Source Insight's features. Later, as you explore Source
Insight's commands, you can refer to the Command Reference chapter for information on specific com-
mands. Also, many dialog boxes in Source Insight contain a Help button that opens the help topic for the dia-
log or command in question.
Projects
The most powerful features of Source Insight are designed around projects. A Source Insight project is a col-
lection of source files, plus associated data files that helps you navigate quickly around your source code.
You can add existing source files, or an entire source tree to a project. You can add files as you create the files
inside Source Insight. If new files appear in your source directory or subdirectories, they can also be added
automatically to your project by running the Project > Synchronize Files command, or by letting Source
Insight synchronize automatically in the background. You can also have Source Insight maintain a Master File
List for a project, which determines what files are in the project.
Project Features
Source Insight projects have several important features:
• A project logically groups related files.
• When you want to open a file, you don't have to specify its drive or directory.
• Source Insight maintains a symbol database, which contains data about all symbols declarations and
references in the project. You can use Source Insight to locate symbols and their references very
quickly. When source files are saved, the symbol database is automatically updated incrementally so
that Source Insight always "knows" where a symbol is. When files are changed externally, for example
by a source control system, Source Insight will automatically synchronize those files with the project
symbol database. See “Symbols and Language Parsing” on page 54.
• Source Insight can show symbol relationships in the project, such as call trees, reference trees, and
class hierarchies.
• Source Insight maintains a reference index, which greatly speeds up project-wide searches for symbol
references. The reference index is updated incrementally as you edit and save your files.
• Each project has its own session workspace. When a project is opened, all the session state is restored.
When a project is closed, all open files are closed and the workspace is saved.
Inside a Project
A project consists of basically two things: Your source files, and the project data files that Source Insight
maintains.
Each project contains a list file paths that point to your source files. A project also contains a symbol data-
base, which is maintained by Source Insight. Your source files are parsed by Source Insight and symbol decla-
rations and definitions, and references are recorded in the symbol database. All you have to do is add source
files to your project; you do not have to generate any other "tag" files. Source Insight does that automati-
cally.
Each project has its own session workspace. The workspace contains session information, such as the list of
files that are open and window positions.
Project Directories
When you create a project, you must specify two directories for each project:
• Project Data Directory - this is where Source Insight stores its project data files. For example, the
.siproj file is stored here. By default, Source Insight creates a project data directory inside the Docu-
ments\Source Insight 4.0\Projects folder when you create a new project.
• Project Source Directory - this is typically the root of your local source repository tree. By maintain-
ing these two separate folder locations, you can store your Source Insight data separate from your
source files. Furthermore, your Source Insight project data files are kept in your own user data area,
and other users on the same machine will not be able to access them. If you want, you may use the
same location for both folder locations.
As an example, let's say we are creating a project for a game program. The source tree looks like this:
We have source code in the "presentation", "core", and "core" subdirectories. Our Source Insight project will
include files from all these directories. We should specify c:\game as the project source directory when we
create the project so that all file paths will look relative to that directory.
You will be asked for a project name, where the files should be stored, and what source files you want to add
to the project.
Note: You can also use Master File List to maintain the files in your project. This is useful for maintaining projects on
separate machines and with other team members. See “Using a Master File List” on page 46.
Use File Type Options to control what types of files are added to projects
The File Type Options dialog box contains the check box: Include when adding to projects. You can use this
check box to control what file types Source Insight will automatically add to your project, or what file types
will be displayed in the list box in the Add and Remove Project Files dialog box.
mand. This way, the Source Insight symbol database files are stored locally on your machine, but the source
files still reside on the server. See “Add and Remove Project Files” on page 159.
Using the Project Settings command, you should specify the remote source code directory, on the server, as
the project source directory. That way, files will be displayed relative to the main source directory, not rela-
tive to your local project data file directory. See “Project Settings” on page 285.
Note: You can also use Master File List to maintain the files in your project. This is useful for maintaining projects on
separate machines and with other team members. See “Using a Master File List” on page 46.
Here is an example:
; Source Insight Project File List
; Project Name: WorkTest
; Generated by Source Insight 4.00.0048 at 11/19/2015 1:41:06 PM
; Version=4.00.0048
;
; Each line should contain either a file name, a wildcard, or a sub-directory name.
; File paths are relative to the project source root directory.
;
FM15Output\copycss.bat
FM15Output\custom-table.css
FM15Output\custom.css
devices
console\get.c
console\put.c
cmd*.c
cmd*.h
The example above uses a combination of specific file names, wildcards, and a directory name (devices). All
the names are relative to the project source directory root.
Removing a Project
To remove a project, use the Remove Project command. This command removes all the project data files that
Source Insight creates and associates with the project. Your source files are not deleted. See “Remove Proj-
ect” on page 311.
Copying a Project
The Project > Copy Project command copies the current project to a new name and location. The new project
is created by cloning the current project data files. Your source files will not be copied. The new project will
point to the same source files. If you delete the original project after copying it, you have effectively renamed
the project. See “Copy Project” on page 182.
Read-Only Projects
Sometimes it makes sense for a project to be read-only, and Source Insight allows for that. A project should
be read-only if it is used only as a import library, or the project only exists on the project symbol path for
auto-completion use. Also, a read-only project can be opened simultaneously by multiple instances of
Source Insight.
When Source Insight opens a project in the background to get symbol information for auto-completion or
other reference-oriented uses, it opens the project as read-only so that other instances of Source Insight can
open the project too.
To make a project always open as read-only, set the read-only file attribute of the project’s .siproj file,
which is stored in the project’s data directory.
When you open a read-only project, you will not be able to save any files in the project, or add or remove files
from it.
The synchronizing process can also optionally add and remove files automatically as new files appear, or dis-
appear from directories. The options are set in Options > Preferences: General Options. See “General
Options” on page 225.
You can also use a Master File List to control what files are in your project. If you use this option, then the syn-
chronization process uses the Master File List to add or remove files as needed. See “Using a Master File List”
on page 46.
Note: You do not have to add the Base project to the project symbol path. Source Insight automatically searches it as
though it were in the list.
This gives you a convenient place to save common symbols. Any symbol stored in the Base project is visible
from any other project. The Base project is also a good place to add your favorite Source Insight editor macro
files.
Rebuilding Projects
Sometimes you may need to rebuild a project if you suspect the data files are corrupted or just too far out of
date.
If you can still open your project, use the Project > Rebuild Project command to rebuild it. This rebuilds all
the Source Insight data files. See “Rebuild Project” on page 288.
Source Insight automatically detects if a project is corrupted when you open a project. If corruption is
detected, it will rebuild the project at that time.
Project Windows
There are several project related panel windows. The main Project Window appears when you View > Panels
> Project Window. The Project Window is set up by default as a tabbed container for all the project-related
panels, such as the Project File List and Project Symbol List. Each project panel has a tab.
The Project Window can be either docked to a side of the Source Insight main application window, or it can
float in front.
As with any grouped panels, you can click on the tab for any project panel and drag it out into its own floating
window, or dock it separately.
Using name fragment matching, you can type part of a file name to locate a file, without bothering with the
directory name.
Expanding Wildcards
If you type a wildcard specification and press Enter, then the file list will be filtered down to match that spec-
ification. For example, if you type *.c and press Enter, you will see all *.c files in your project, regardless of
directory. To remove the wildcard, press * (asterisk) and press Enter.
To locate a symbol quickly, type a part of the symbol name and the list will be filtered down as you type. You
can also use name fragment matching to find parts of symbol names. For example, if you type:
doc write
this will match symbol names such as DocWrite, WriteDoc, WriteOpenDoc, CanWriteAnyDoc, etc. See “Name
Fragment Matching Symbol Names” on page 66.
Languages
Source Insight uses a language abstraction to encapsulate the properties of various programming languages.
For a given file buffer, the file's name determines its file type. The file type determines its language parser.
The Options > File Type Options dialog box is used to associate a file type with a file extension and a lan-
guage. For example, the Java Source File file type uses the *.java file filter to associate Java files with that
file type. Further, the Java Source File file type specifies the Java Language parser. See “File Type Options” on
page 213.
To see a list of the currently supported languages, use the Options > Preferences: Languages dialog box.
New languages are added to the list from time to time in program updates. See “Language Options” on
page 241.
Languages in Source Insight are divided into two categories: Built-In, and Custom.
Built-In Languages
Source Insight contains built-in optimized support for several languages, including C/C++, C#, Java, Objec-
tive-C, Python, Perl, ASP, Visual Basic, and others.
Most built-in languages support extra features, like finding references and generating call-trees.
Custom Languages
You can also add your own custom language support to Source Insight using the Options > Preferences: Lan-
guages dialog box. A custom language is a simple generic language that specifies syntax rules, syntax format-
ting keywords, and simple parsing expressions. See “Language Options” on page 241.
Custom languages can also be exported and imported.
Note: The File Types dialog still allows you to add a custom parsing pattern directly into the file type properties, in
lieu of adding a new language. However, you have more control by adding a new custom language and using
your file type to point to the new language.
The Language Options topic in the Command Reference contains more details on custom language proper-
ties. See “Language Options” on page 241.
Symbol Naming
In Source Insight, symbol names are stored as a "dotted path." The dotted path contains the symbol's con-
tainer name, followed by a dot (.) and the symbol's name. For example, a member of a class may look like:
MyClass.member
All symbols that have their declarations nested inside of another symbol will have a dotted path. If you look
through the symbols listed in the Project Window, you will see the dotted paths. Even in languages like C++,
where the scope resolution operator :: is used to declare members, the symbol name is stored internally as
a dotted path.
When typing the full name of a symbol, you should use the dot in the symbol name if you want to also specify
its container.
Note: It is possible for a symbol to have an embedded dot (.) character in its name. Source Insight will store the sym-
bol name so that the embedded dot is not confused with the dotted path dot character.
Common Projects
Consider the case when you have a set of header files from a library that you often use with multiple projects.
You could add these files to each of your projects, but that would be redundant. A better solution is to create
a single common project for each set of common header files, and let Source Insight search the common
project from any open project.
Common projects enables you to create smaller, self-contained projects, but still have the ability to locate
symbol declarations in other projects. The Base project (See “The Base Project” on page 49.) is the final place
Source Insight looks to find symbols; it is implicitly at the end of the project symbol path.
Common projects are used in two ways:
• You can add the common project as an import library project. There global and project-specific import
library lists. See “Importing Symbols from Libraries” on page 55.
• You can put the common project onto the project symbol path. There is only one project symbol path
that is used regardless of what the current project is. See “The Project Symbol Path” on page 56.
Source Insight will search the import library projects, and the project symbol path whenever it looks up a
symbol and can't find it in your current project, or in an open file.
An import library is a special Source Insight project, whose symbols come from an external sources. Symbols
can be imported from the following types of files:
• All the source files on the INCLUDE path
• .NET .dll files
• A whole directory tree of .NET .dll files
• Java .jar files
• Java .class files
• A whole directory tree of Java .class files
• A whole directory tree of source files (such as *.h files)
• Another Source Insight project
When you import symbols from one of these sources, a new special Source Insight project is created to hold
the symbols, and Source Insight opens and searches these import projects automatically.
Note: Import projects have an "_import_" prefix in their name. You can open an import project by selecting Project >
Open Project and enabling "Show import projects". The project list will contains all your projects, plus the
import projects.
There is both a global import library list, and a project-specific import library list. Therefore, import libraries
are more flexible than using the project symbol path.
on if you want to see if there are redundant (or at least like-named) symbols in your project and any others
on the project symbol path.
The project symbol path is only used to locate symbol definitions. It is not used to locate symbol references,
or used by Search Files, or Smart Rename. Those operations only work on the files in the current project.
C/C++ Symbols
When editing C/C++ files, Source Insight can perform symbol completion for the standard libraries, such as
the C-runtime, STL, WinAPI, or any other library such as Boost. This is accomplished by importing symbols
from the C/C++ files and header files on your machine.
To import the C/C++ runtime symbols, use the Project > Import External Symbols command, or use the Pref-
erences: Symbol Lookups dialog box and click the Import Symbols button.
Java Symbols
When editing Java files, Source Insight can perform symbol completion for the standard Java runtime librar-
ies. This is accomplished by importing symbols from the Java jar files on your machine.
To import the Java runtime symbols, use the Project > Import External Symbols command, or use the Prefer-
ences: Symbol Lookups dialog box and click the Import Symbols button.
PHP Pages
The PHP File Type, which uses the PHP Page language parser, supports PHP with embedded HTML, plus cli-
ent-side script. PHP scripting blocks will appear using the syntax formatting for PHP, and the appropriate for-
matting for client-side script elements. PHP symbols are also displayed in the symbol window, and are saved
in the symbol database. The Relation Window will show references and call trees for PHP symbols.
Source Insight supports the PHP script start tokens: <? and <?= and <?php . The PHP end script token is ?>.
The deprecated <% and %> tokens are not supported. Source Insight parses both the script and the HTML.
To populate the symbol information, Source Insight parses multiple streams from the same file: one for the
server side PHP and one for the client side HTML. In addition, the client side may contain HTML script ele-
ments. Given the way PHP pages are typically written, the HTML elements from a PHP page file usually are
parsed and recognized by Source Insight. However, it is not guaranteed to work, since PHP fragments can
emit conflicting HTML tags, or they can be out of order.
You may notice in Options > Preferences: Languages, that there is a separate PHP Language which is not
bound to a file type. This is responsible for parsing pure PHP code, and does not understand interleaved
HTML at all. A separate language type: The PHP Page parser brokers the HTML and PHP server-side pieces to
either the HTML or PHP Language.
To populate the symbol information, Source Insight parses multiple streams from the same file: one for the
server side ASP script, and one for the client side HTML. In addition, the client side may contain script ele-
ments. The Active Server Page parser brokers HTML and server-side script to different languages, depending
on the language specified in the ASP file.
Note: Conditional statements such as #if and #ifdef are only interpreted when all the condition values are speci-
fied in the Edit Conditions dialog box.
By default, Source Insight ignores the conditional directives altogether. It attempts to make sense of all
branches in a conditional compilation construct. Often, this works well because declarations in the condi-
tional branches do not interfere with each other.
However, sometimes a tricky declaration may be broken in the middle with an #ifdef. This will often confuse
Source Insight. For example:
void DoThing(
int param1,
#ifdef ABC
int param2)
#else
int param2, param3)
#endif
If you are not interested in code that is inactive, you can specify condition values. See “Conditional Parsing”
on page 60.
Conditional Parsing
Conditional parsing applies only to languages that support conditional compilation in Source Insight: C/C++,
C#, etc. See “Edit Condition” on page 201.
Source Insight maintains two types of condition variable lists.
• Global condition list. This applies to all projects. This list is saved in the configuration file, which con-
tains your customizations.
• Project-Specific condition list. This list is saved with each project. You can have different condition
variables defined for each individual project. For example, you could have "RELEASE" defined in one
project, and "DEBUG" defined in another.
The two condition lists are combined when Source Insight parses a file. The project-specific conditions take
precedence over the global conditions.
Condition Variables
Condition variables can be used in expressions in #if, #ifdef, #ifndef, and #elif statements. These are typically
constant values defined in a header file, or on the compiler command line. For example:
#if VER < 3 && DEF_OPEN != 0
....
In this example, two condition variables are used: VER and DEF_OPEN. Each variable value can be specified
using the Edit Condition command. See “Edit Condition” on page 201.
Each condition variable can have any textual value. As in C and C++, any numerical value that equals zero is
considered "False", and any non-zero value is "True".
Parsing Limitations
Because regular C/C++ preprocessing is not performed by Source Insight's parsers, some coding styles affect
parsing correctness in Source Insight.
Having #ifdef blocks break up an individual declaration will confuse Source Insight. If it cannot be avoided,
and Source Insight doesn't parse the code correctly, you will need to define the condition value using Edit
Condition, so that Source Insight will disable the inactive block of code causing the confusion. See “Condi-
tional Parsing” on page 60.
For example:
void MyFunc
#ifdef XYZ
(int param1, int param2)
#else
(long param1, long param2)
#endif
{
...
}
Replacing standard language keywords or combinations with #define'd substitutions will confuse Source
Insight. If you cannot avoid this, then you will need to define Token Macros to support them. See “Preproces-
sor Token Macros” on page 64.
For example:
#define ourpublic public
class D : ourpublic B { … }
This causes a problem because Source Insight doesn't know that the keyword ourpublic really means pub-
lic.
Fixing "Parse-Too-Complex"
If Source Insight encounters too many problems trying to parse a file, the symbol window at the left side of
the source window will say "Parse Too Complex" instead of listing the symbols in the file.
The Parse-too-complex can often be handled by using the Edit Condition dialog, or defining Source Insight
preprocessor macros (token macros).
The Parse-too-complex usually happens in the following situations.
DeclareMyFunction(foo)
..body of function
}
This fails to parse because Source Insight does not expand the macro and fails to see the function name or
the opening brace. Again, this can be fixed by defining a token macro in the c.tom file located in your Docu-
ments\Source Insight 4.0 folder. See “Preprocessor Token Macros” on page 64. To fix this example, you
need to define a token macro for DeclareMyFunction.
Each built-in language parser has a corresponding token macro file. The name of the token macro file for
each language is summarized below:
Table 3.1: Token Macro Files for Different Languages
Language File Name
C/C++/Objective-C C.tom – a default copy ships with
Source Insight.
Java Java.tom
Resource Files Rc.tom
Save a token macro file to get Source Insight to recognize the macros
When you edit a token macro file, you must save it to disk before Source Insight will re-parse your open files.
However, Source Insight will not automatically re-parse your whole project. You should make all your
changes to the token macro file first, then use the Rebuild Project command to re-parse your whole project.
Until your project is re-parsed, the symbol information stored in Source Insight's symbol database will not
reflect the changes you made to your token macros.
For example, the symbol name "CreateWindow" has two name fragments: "Create" and "Window". Source
Insight indexes both name fragments so that you can browse for the symbol by typing "Cre" or "Win" or any
combination, and in any order. Each name fragment is prefix matched by what you type.
You can browse symbols this way using the Project Window symbol and file list. This also works in the text
box above the symbol window pane on the left side of each source window.
In addition, all lists in Source Insight that are matched with a text box have this standard ability as well.
The name fragment filtering is not case sensitive. However, once the filtered list is displayed, Source Insight
will try to select the item in the list that most closely matches what you typed, including the case.
For example, the following specifications are equivalent:
CreWin
Cre Win
cre win
WinCre
Win Cre
win cre
win_cre
Win.cre
Source Insight will filter the list contents down and sort the results, with best matches near the top. Symbols
that match exactly what you typed, starting with the first character of the symbol, are displayed near the top
of the list.
For example, if you have two symbols: "TopBottom" and "TopAndBottom", and you type "TopBot", then the
"TopBottom" symbol will appear first, even though both symbol names match the specification.
Source Control
Source Insight is designed to work well in team programming situations. As team programmers contribute to
the code base, Source Insight automatically recognizes their contributions and updates its symbolic informa-
tion. Moreover, as large amounts of new code are added to a project, or moved from module to module, you
will appreciate Source Insight's ability to keep track of everything for you.
Edit each of the above Custom Commands, and set the "Run" string from the above table.
Note: A shortcut to edit a Custom Command is to hold down the Ctrl key while clicking on one of the source control
icons in the toolbar. For example, Ctrl+click on the "Check Out" button. The Custom Command dialog will
appear open to the "Check Out" command.
The cleartool utility must be on your PATH. If not, replace the instances of cleartool above with the full path
to the cleartool.exe command on your machine.
The %f parameter in the "Run" string of a custom command will be replaced with the full path of the current
file.
You may want to alter some of the options specified above. You can also add more commands for additional
operations. Please refer to ClearCase documentation.
Git has many fine-grained commands and concepts that go beyond the relatively simple source control con-
cept used in Source Insight. The following table is one version that you may find useful. You can always add
more custom commands in Source Insight for addition Git commands.
Table 3.4: Git Source Control Commands
Custom Command Run String Description
Check Out n/a With Git, there really isn’t a need to
check a file out first. Simply modify
your copy of the file as you want.
Use the "Check In" command to
commit your change when you are
done.
Check In git commit %r -m "" Commit the current file to your
local repository without comment.
Undo Check Out git checkout -- %r This command actually undoes the
modifications to the file since you
last committed the file.
Sync to Source Con- git pull origin Pulls new changes from the remote
trol Project repository and updates all files in
the current branch.
By default, "origin" is the name of
the repository you first cloned
from. If you have a specific reposi-
tory you want to pull from, you
should replace "origin" with the
name of the repository.
Git pull will perform merges as
needed if you have both local
changes, and changes in the
remote version of a file since you
last pulled the file.
Sync File to Source git fetch origin;git checkout FETCH_HEAD Effectively pulls changes for a sin-
Control Project -- %r gle file from the remote repository.
Edit each of the above Custom Commands, and set the "Run" string from the above table.
Note: A shortcut to edit a Custom Command is to hold down the Ctrl key while clicking on one of the source control
icons in the toolbar. For example, Ctrl+click on the "Check Out" button. The Custom Command dialog will
appear open to the "Check Out" command.
The %r parameter in the "Run" string of a custom command will be replaced with the path of the current file
relative to the project’s root source directory.
The git.exe and associated executables must be on your PATH.
You will need to install Git and initialize your local repository with the git init command before using any
of these commands. Furthermore, you can configure Git so that the Git commands automatically work with
your remote repository.
For information on Git, please refer to https://git-scm.com/
File Types
A file type is a file classification that is defined with the File Type Options command. There are file types for
"C/C++ Source Files", "Java Source Files", and so on. Source Insight uses each file's name to determine its file
type. For example a file matching the *.c wildcard is a "C/C++ Source File". The file type defines parsing, dis-
play, and editing options.
Figure 3.4 The file name determines the file type. The file type determines the font, the language type used to parse the
file and display it with syntax formatting, and other editing options.
The File Type Options command defines new file types or changes the built-in types. See “File Type Options”
on page 213.
Language Types
Source Insight uses a language abstraction to encapsulate the properties of various programming languages.
Each file type specifies a language type in the Parsing section. Therefore the file type and language type are
separate, but connected. For example, there is a file type named "C/C++ Source File", which uses the "C/C++
Language" for parsing.
File-Type-Specific Options
The file type is key to determining how Source Insight treats a file. Most importantly, it controls what pro-
gramming language is associated with each file. A file type also specifies editing and display options, such as
the tab width, word wrap, auto-indentation, display font, and others.
Tip: To see what file type is associated with the current file, right-click on the source file window and select File
Type Options. The file's current file type is automatically selected in the dialog box.
Symbolic Parsing
Source Insight parses your project files while you edit. You can locate classes, methods, functions, and more
without having to compile your files.
Once a file has been added to your project, the names and locations of the symbol definitions in the file are
stored in the project's symbol database. The symbol definition can be found quickly using the several tech-
niques. Remember, you can right-click on many objects in Source Insight to bring up the object's shortcut
menu. Some of the following commands are on the shortcut menus.
Note: Another way to jump to a definition is to have the Context Window open. Let the Context Window show the defi-
nition. If you want to jump there, just double click on the Context Window.
Browser Mode
The Edit > Browser Mode command toggles Source Insight's Browser-Mode. When Browser-Mode is on, your
source code becomes read-only, and acts like a web browser. For example, single clicking on the name of a
function in a function call will jump to the function's definition. See “Browser Mode” on page 168.
Context Window
The Context Window is a Source Insight innovation that provides symbolic information automatically. It
tracks what you are selecting and typing and shows you relevant symbol declarations automatically, while
you work. See “Context window” on page 90.
Reference Highlights
Source Insight can automatically highlight references to the symbol at the cursor position. For example, you
can click in a variable name, and all references to the variable will be highlighted. The references are context
sensitive, so a symbol in a different scope will not get highlighted. This works for variables, class members,
functions, and so on.
You can enable this feature by selecting Options > File Type Options, then selecting the option "Highlight ref-
erences to selected symbol".
Once enabled, if you click on a symbol name, all references to it in that file are highlighted. The highlight will
only appear if more than one instance appears in the file.
To change the color or format of the highlight, select Options > Style Properties and edit the "Reference
Highlight" style. By default, it only changes the text and background colors.
Smart Renaming
The Smart Rename command is a context-sensitive form of a global search & replace. It renames an identifier
across all project files using a smart context-sensitive method. Source Insight's search index makes the
search very fast. This is the easiest way to replace a single word identifier with a new string. In addition, you
can have Source Insight produce a log of replacements in the Search Results window. Each replacement line
is listed, along with a source link to the location of each line that was changed. See “Smart Rename” on
page 336.
Comparing Files
The Tools > Compare File command compares two files to show differences within the files. It shows two files
side by side and highlights the differences. This is a fancy version of the diff command. See “Compare Files”
on page 175. See “File Compare” on page 205.
The Tools > Compare with Backup File command compares the current file with a backup version of the same
file. See “Compare with Backup File” on page 176.
Comparing Directories
The Tools > Directory Compare command compares two file directories to show what files are different
between them. See “Directory Compare” on page 191.
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 343.
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.
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.
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:
In the Style Properties dialog, the style hierarchy is displayed visually. See “Style Properties” on page 343.
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.
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.
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.
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 "Hdo-
cOfTgl" 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.
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 sym-
bol lookup operation each time it encounters a potential symbol reference.
Blocks of code that are inactive are given the "Inactive Code" style. For more information, see “Conditional
Parsing” on page 60.
Comment Styles
Source Insight adds some explicit formatting to comments. All comments inherit from the Comment parent
style. The comment style hierarchy appears below.
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
comment 1
//2 This is a Heading
comment 2
//3 This is a Heading
comment 3
//4 This is a Heading
comment 4
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.
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 some-
thing 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 repre-
sentation 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.
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.
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.
Context window
The Context window is a Source Insight innovation that automatically provides relevant information while
you are viewing and editing your source code. It is a floating, dock-able panel window that displays contex-
tual information while you type or click on things. For example, if you click on a function call, the Context
window will display the function’s definition. If you click on a variable, the Context window will decode its
declaration to show you its base structure or class type.
The Context window works in conjunction with other panel windows to enhance those windows functional-
ity. For example, the Context window automatically displays files selected in the Project File List, symbols in
the Project Symbol List, and other types of previews.
Figure 3.11 The Context window on the bottom shows the declaration of the selected symbol.
You can toggle the Context window on and off by selecting View > Panels > Context window.
The following sections describe typical use cases for the Context window.
Figure 3.12 The Context window is previewing the file selected in the Project File List panel.
If you select the mem in ptvar->mem, then the Context window will find the declaration of PT ptvar, and
decode the type hierarchy until it finds the struct S, and it will display the declaration of the field mem within
struct S.
The Context window also decodes class hierarchies dynamically. That is, it will travel up the class derivation
hierarchy looking for members that are in scope.
Relation Window
The Relation Window is a Source Insight innovation that shows the relationship between the currently
selected symbol and other things. The Relation Window can show function call trees, class hierarchies, struc-
ture members, reference trees, and more. It can be docked along side your source windows, and it works in
the background tracking what you are selecting and showing relationship information automatically.
To show the Relation Window, select View > Panels > Relation Window.
You can specify the relationship types and many other options in the Relation Window Options dialog. See
“Relation Window Options” on page 306.
The Relation Window runs in the background and tracks what symbols you have selected. The beauty of the
Relation Window is that you don’t have to do anything special. It works in the background while you work,
but you can interact with it when you want to. You can also have several Relation Windows open, each show-
ing different types of information.
Outline View
The Relation Window outline view is a compact, textual view of the relation hierarchy. You can click to
expand and collapse levels in the outline.
Graph View
The Relation Window graph view is a visual representation of the same relationship as the outline view. You
can expand and collapse nodes in the graph. You can select either a horizontal graph layout, or a vertical
graph layout. You can also print the graph, or copy the graph images to the system clipboard so you can pro-
cess it in another imaging program.
To expand or collapse a node, hover the mouse cursor first over the right or left edge of the node in a horizon-
tal graph (or the top or bottom middle of a node in a vertical graph). The mouse cursor will contain a + or -
symbol. Click to expand or collapse.
You can choose Graph View options by right-clicking on the Relation Window and selecting Relation Window
Graph Options. See “Relation Window Graph Options” on page 305.
Relationship Rules
The relation view that appears when you select a symbol depends on the type of symbol. You have control
over this in the Relation Window Options. For example, you can specify that if you select a function in your
source code, the Relation Window will show references to that function. And, if you select a class name, the
Relation Window will show the classes derived from it.
Each time the Relation Window expands a symbol to show a new level, the relationship represented by the
expansion is based on the type of symbol being expanded. That means each Relation Window can potentially
show multiple relationships. See “Relation Window Options” on page 306.
Relationship Types
The relationships fall into these general categories, listed from computationally the fastest to slowest:
• Contains – show the contents of the current symbol. For example, the members of a struct.
• Calls – show what other symbols are referred to by the current symbol. For example, functions that
are called by the current function.
• Calls and Callers - show a split graph; one side are the functions called by the current function, the
other side is the functions that call the current function.
• References – show what other symbols refer to the current symbol. For example, functions that call
the current function.
Call Graphs
The function call graph relationships can be filtered to show only what you consider the most interesting
paths. The “Call Graph Filtering” button in the Relation Window Properties dialog box takes you to a dialog
box that lets you control the filtering by specifying particular functions you want to exclude. You can also fil-
ter functions out by code metrics constraints.
Note that Source Insight considers C/C++ macros legitimate function-like symbols, and so C/C++ macros may
show up in a call graph. You can filter them out in the Call Graph Filtering dialog box if you want.
Code Snippets
Code Snippets are small chunks of commonly used source code that you can insert into your source files. For
example, you can use a snippet to insert a "for" or "while" loop. Snippets are intended for boiler plate text.
The Snippets panel contains all your code snippets and helps to organize them. The Snippets panel lets you
create, edit, delete, and insert code snippets. You can also import and export snippets.
Snippets can also be programming language-specific, or common to all languages, or common to certain
sets of languages. For example, you can have a snippet for C/C++ and another with the same name just for
Java. See “Snippet Window” on page 340.
Inserting Snippets
To insert a snippet, you can do any of the following:
• From the Snippet panel, double-click on a snippet or type the name of snippet and press Enter. You
can activate the Snippet panel first so you can type into it by using the Activate Snippet Window
command (Ctrl+Alt+S).
• From the Edit menu, select Insert Snippet > "snippet name".
• Use the Complete Snippet command (Ctrl+E) to pop up a list of snippets.
• Start typing a snippet name and the auto-completion list will show the snippet. Note that having
snippet names in the auto-completion list is optional.
Text Variables
Snippets may contain text variables (sometimes referred to as placeholders). A text variable is a special iden-
tifier that is replaced with a particular value when the snippet is inserted. For example, $date$ is a text vari-
able that gets replaced with the current date when you insert a snippet containing that text variable.
A text variable starts and ends with a dollar sign ($). For example $this$. When you select anywhere within
it, the whole thing gets selected. Arrow keys move over text variables in one press. To select inside one, hold
down Ctrl and click with the mouse in it.
You can also force Source Insight to process text variables in any selected text by using Expand Text Vari-
ables. See “Expand Text Variables” on page 203.
For example, this snippet insert a "for" statement and has placeholders for the iterator variable, the limit
value, and the final cursor position.
for ($i$ = 0; $i$ < $lim$; ++$i$)
{
$end$
}
When this snippet is inserted, the first text variable is automatically selected. In this example, that would be
the $i$ variable. You can simply type the name of the variable to replace $i$.
Then, you can use the Select Next Snippet Placeholder command (Ctrl+Shift+;) to select the next place-
holder. Alternatively, you can use any other navigation command to move the cursor.
Snippet Options
You can control what file types can use snippets. To enable or disable snippet use for each file type, Select
Options > File Type Options and select or de-select the "Enable code snippets" option. If the code snippets
are disabled, then code snippets will not be proposed in the auto-completion list while you edit, and text
variables will not have any special behavior in those files.
You can control automatic text variable replacements on a per-snippet basis. In the Snippet panel, select a
snippet and click the Edit Snippet button (Ctrl+E). Select or de-select the "Enable text variables when insert-
ing" option as desired.
You can also enable or disable text variables for all snippets in the Snippet Window Options of the Snippet
panel. Select or de-select the "Enable text variables when inserting" option as desired.
See “Snippet Window Options” on page 341.
Clip Window
The Clip Window is a floating and dockable window that displays clips. You can drag and drop text onto the
Clip Window and drag text from the Clip Window onto your files.
What Is A Clip?
Clips are clipboard-like documents. In fact, the Clipboard is considered a clip in Source Insight. Instead of
having only one clipboard, Source Insight lets you have many clips. A clip is like any other file. You can edit it
the same as any other file. The difference is that clips are automatically saved between sessions and clips can
be pasted easily with the Paste From Clip command.
Clips are useful for rearranging code, especially between many files. Clips are also useful for boilerplate text
that you often want to insert.
You can toggle the Clip Window on and off by running the Clip Window command, or by running the Activate
Clip Window command, which makes it visible and then sets the focus on the Clip Window text box.
Clip Storage
Clips are automatically saved to the Clips subdirectory of your Source Insight program directory. Any text file
that you place in that Clips subdirectory will be automatically loaded when Source Insight starts up.
Bookmarks
Bookmarks are useful for remembering locations of interest in your files. Bookmarks are accessed and man-
aged from the Bookmark Window panel. The vertical scrollbar and Overiew scroller also indicate bookmarks.
The Bookmark Panel is a floating, dock-able window that shows the current list of bookmarks. The Book-
mark command activates the Bookmark Window. See “Bookmark” on page 164.
A bookmark points to a particular line position in a file. Each bookmark has a name, and specifies a file and
line number. The Bookmark window also displays the function or symbol where the mark is located.
The Bookmark Window has functions for adding, deleting, saving, and loading bookmarks. See “Bookmark
Window” on page 164.
Setting a Bookmark
To set a new bookmark, do one of the following:
• Use the Bookmark command (Ctrl+M), or
• Right-click in the selection bar area in the far left margin, and select Bookmark...
The Bookmark Window will open.
You can press Enter and Source Insight will assign a single letter name to the bookmark and add a new book-
mark. Or, you can type a meaningful name and press Enter.
You can also type the name of an existing bookmark and press Enter to jump to that bookmark. There are
other keyboard shortcuts available in the Bookmark Window. See “Bookmark Window” on page 164.
Bookmark Storage
Bookmarks are saved in a special file named booksmarks.xml, so they are preserved from session to ses-
sion. Each project has its own bookmarks.xml file located in the project data directory. Each bookmark is
saved as a line offset relative to a symbol declaration, such as a function. This helps to maintain the book-
marks if the original file is edited outside of Source Insight.
Bookmarks are maintained as you edit your files. For example, if you set a mark on a particular line, and then
insert lines before that one, the mark will still be on the original line of text, even though the actual line num-
ber may have changed. If the line that the mark is set at is deleted, then the mark is deleted also.
FTP Bookmarks
Bookmarks can also point to a file on an FTP host. If you used the FTP Panel to open a file and set a bookmark
in that file, then the bookmark will remember the FTP Site name and directory so you can open the file again.
However, this requires that the FTP Site is defined in the FTP Panel. If you set a bookmark, and later delete
the FTP Site from the Site List of the FTP Panel, then the bookmark will not work anymore. See “FTP
Browser” on page 221.
To set options, click the Options button. See “File Search Bar Options” on page 212.
Searching a Project
The Search Project command searches for text or keywords across all project files. This command works the
same as the Lookup References command. The only difference is that each dialog box has its own persistent
state.
Replacing Text
These are the methods for replacing or renaming identifiers in the current file or multiple files.
Renaming an Identifier
Use Smart Rename to perform context-sensitive renaming of symbols - global or local.
To rename an identifier across all project files using a smart context-sensitive method, use the Smart
Rename command (Ctrl+Single-Quote). Smart Rename is a context-sensitive form of a global Search and
Replace. See “Smart Rename” on page 336. Source Insight's search index makes the search very fast. This is
the easiest way to replace a single word identifier with a new string. In addition, you can have Source Insight
produce a log of replacements in the Search Results window. Each replacement line is listed, along with a
source link to the location of each line that was changed.
Smart Rename is also excellent for renaming local scope variables.
To traverse a link, use the Jump To Link command (Ctrl+L), which takes you to the other end of the source
link at the current line. A link can be traversed as long as the link source file is open. If the link target file is not
open, the Jump To Link command will open the file automatically.
Figure 3.14 The Search Results window has a source link on each listed match. Each source link corresponds to a location
in a file at some line number. The window above the Search Results is the target location of one of the source links.
Source Links are bi-directional, so you can use the Jump To Link command to go from the link source to the
target, or from the target back to the source.
In addition, the link information is maintained as you edit your files, just as bookmarks are. A link is only
removed if you delete its link source line, or close the link source file.
Regular Expressions
Regular expressions are special search strings that are useful for matching complicated patterns. In a regular
expression string, many characters have special meanings. For example, there is a special character that
means "the beginning of the line".
Optional Syntaxes
Source Insight support two different regular expression syntaxes: "Source Insight" and "Perl Compatible".
Most places that let you enter a regular expression has a down-down list where you can select the regular
expression syntax.
Multi-Line Patterns
There are regular and "multi-line" versions of each regular expression syntax. The multi-line versions basi-
cally match a new-line (end-of-line sequence) with the dot (.) character. So for example, .* would match the
whole file. And "start.*end" would find everything from "start" to "end" in the file, even across line breaks.
Wildcard Matching
. (dot)
The dot . matches any character.
Example: b.g matches big, beg, and bag, but not bp or baag.
If you use the "multi-line" version of the regular expression syntax, then the dot (.) character also matches
new-lines. For example .* matches the whole file.
Example: a\*b matches a*b literally. The * character does not mean "match 0 or more occurrences".
Multi-Line Matches
Most places in the program where you can specify a regular expression also has a "regular expression syntax"
selection. If you select the "multi-line" version of the syntax, then the dot (.) character matches new-lines. For
example .* matches the whole file.
Example: begin.*end matches everything from "begin" to "end" across multiple lines. "begin" could be at
line 1 and "end" could be at line 100.
Comparing Files
The Tools > Compare File command compares two files to show differences within the files. It shows two files
side by side and highlights the differences. This is a fancy version of the diff command. See “Compare Files”
on page 175. See “File Compare” on page 205.
The Tools > Compare with Backup File command compares the current file with a backup version of the same
file. See “Compare with Backup File” on page 176.
Figure 3.15 The File Compare window panel showing a file being compared to an earlier backup version of the file.
Comparing Directories
The Tools > Directory Compare command compares two file directories to show what files are different
between them. See “Directory Compare” on page 191.
Scrolling Commands
The scrolling commands scroll the active window. They do not affect the current selection. They only affect
the window.
Table 3.9: Scrolling Commands
Command Key Description
Scroll Line Up Alt+Up Scrolls up by one line
Scroll Line Down Alt+Down Scrolls down by one line
Page Up PgUp Scrolls up by a window
full
Page Down PgDn Scrolls down by a window
full
Scroll Half Page Up Ctrl+PgUp Scrolls up by half a win-
dow
Scroll Half Page Down Ctrl+PgDn Scrolls down by half a
window
Scroll Left Alt+Left Scrolls left by aprox. 1 tab
stop
Scroll Right Alt+Right Scrolls right by aprox. 1
tab stop
Selection Commands
The selection commands change the current selection. Usually, if the resulting selection is not visible in the
window, the window is scrolled to show it. These commands change the selection to an insertion point and
move it to a new location in the file.
Table 3.10: Cursor Movement Commands
Command Key Description
Cursor Down Down Arrow Move down by one line.
Cursor Up Up Arrow Move up by one line.
Cursor Left Left Arrow Move left by one character.
Cursor Right Right Arrow Move right by one character.
Beginning of Line Home Move to beginning of line.
End of Line End Move to end of line.
Top of File Ctrl+Home Move to top of file.
Bottom of File Ctrl+End Move to end of file.
Beginning of Selection Ctrl+Alt+[ Move to start of an extended
selection.
End of Selection Ctrl+Alt+] Move to end of an extended
selection.
Top of Window Move to top of window.
Bottom of Window Move to bottom of window.
Word Left Ctrl+Left Move left by one word.
Word Right Ctrl+Right Move right by one word.
Word Fragement Left Move left by a word fragment.
A fragment is a section of
characters bounded by a
change in case or punctua-
tion. You can use this for
camel-case words, such as
"OpenFileCore"
Word Fragment Right Move right by a word frag-
ment.
Function Down Keypad + Move to next function defini-
tion.
Function Up Keypad - Move to previous function
definition.
Blank Line Down Move to next blank line.
Blank Line Up Move to previous blank line.
Paren Left Ctrl+9 Move to previous enclosing
parentheses.
Paren Right Ctrl+0 Move to next enclosing paren-
theses.
Blank Line Up Move to previous blank line.
Blank Line Up Move to previous blank line.
Block Up Ctrl+Shift+{ Move to previous { block level.
Block Down Ctrl+Shift+} Move to next { block level.
Go To Line F5, Move to a specified line num-
ber.
Ctrl+G
The Toggle Extend Mode command toggles Extend Mode on and off. When Extend Mode is on and you use a
movement command, such as Cursor Left, the current selection is extended in that direction.
See “Browsing and Analysis” on page 74.
Selection Shortcuts
Source Insight provides many short cuts for selecting meaningful objects within your source code.
Source Insight has a "selection bar" area in the left margin of each source file window. Many shortcuts involve
clicking in the selection bar.
You can control whether outline controls are visible, and whether they are in the left margin or indented by
selecting Options > Preferences: Windows and choosing outline options. See “Window Options” on page 370.
Here is the same piece of code with the outline buttons indented with the code:
You can also select any lines and use the Collapse command to collapse them, regardless of the code block
nesting structure. You can invoke Collapse by right-clicking in the left margin and selecting it in the menu.
Outline Toolbar
Buttons
1. Toggle Expansions - toggles expansion of the selected outline region.
2. Expand All - expands all blocks that can be expanded.
3. Collapse All - collapses all major blocks that can be collapsed, such as functions.
4. Show Outlining - turns outline views on and off in the current file.
Code Beautifier
Source Insight has a code beautifier that works with C/C++, C#, Java and other language files that have simi-
lar curly-brace syntax.
There are several different code formatting presets, and you can save additional presets. To access all the
presets, or to use a preset, select Tools > Reformat Source Code Options. The preset you select in this dialog
box becomes the current preset.
To reformat a file using the currently selected preset, select Tools > Reformat Source Code with xxx Preset.
Note: xxx will be changed to the name of the currently selected preset.
To reformat a whole file, select an insertion point anywhere in the file and select Tools > Reformat Source
Code with xxx Preset. To reformat only selected lines, select the lines you want to reformat first.
See “Reformat Source Code Options” on page 289.
The resulting HTML files will look a lot like the source files displayed inside of Source Insight. The HTML files
will retain most of the syntax formatting. Identifiers that appear in the source code will have hyperlinks to
definitions.
See “Export Project To HTML” on page 204.
File Encodings
Source Insight can load and save files using different character encodings. By default, Source Insight uses
UTF-8 (Unicode) encoding.
Encoding Basics
Characters in files are stored using a character encoding scheme. Examples are:
• ASCII
• Shift-JIS is a character encoding for the Japanese language
• Chinese Big5 is a character encoding for traditional Chinese characters
• Unicode encodings
Non-Unicode encodings use code pages, which are tables containing character sets designed for encoding a
particular set of glyphs.
Unicode was developed as a unifying encoding that could encode all characters. However, Unicode itself can
be encoded in several flavors, such as UTF-8, UTF-16, and UTF-32.
Unfortunately, the code page encoding used in a file is not saved with the file. Therefore, it is possible to open
a file assuming the wrong encoding. If you open a file with the wrong encoding, you will probably observe
some characters are incorrect or look garbled. You can use the File > Reload As Encoding command to reload
the file with the correct encoding.
Another problem with code pages is that characters are not guaranteed to map between code pages, which
could lead to files being corrupted. It is best to use a Unicode encoding to avoid those problems.
Programmers are encouraged now to use UTF-8 encoding. Most web browsers and programming tools sup-
port UTF-8, and UTF-8 supports a super-set of other regional encodings.
To change the default encoding, select Options > Preferences: File, and change the setting for Default encod-
ing. See “File Options” on page 208.
The default encoding setting from the File Preferences is used to interpret files when you open them. It is also
used when you create a new file buffer (using File > New) and save the buffer the first time.
If you open a file that has an explicit UTF signature, known as a Byte-Order-Mark (BOM), then the UTF format
is used instead of the default. You can override this by using the File > Reload As Encoding command.
Note: Source Insight performs slightly faster if you set the default encoding to "UTF-8" or "UTF-8 with BOM".
Note: If you want to reload a file that you made changes to, and you want to keep your changes, do NOT save the file
back over itself, because that will overwrite the file and could corrupt it. Instead, save it to a new file by select-
ing File > Save As Encoding, and pick the UTF-8 format. After you reload the original file, you can compare the
differences between the files and merge your changes back.
Once you load a file with a specific encoding, that encoding type is associated with the file buffer as long as
Source Insight keeps the file open. The encoding type is also stored in the session workspace so that it is pre-
served between Source Insight sessions. However, if you close a file, and then open it again, the default
encoding will be used.
Backup Files
Source Insight makes a backup copy of a file the first time you save the file after opening it. If you open a file
and save it ten times, you will still only get one backup file. If you close and reopen file, or start a new Source
Insight session, a new backup will be saved when you save the file again.
Backup Options
You can set options for backup files by selecting Options > Preferences: Files. See “File Options” on page 208.
The following options control backup files:
Checkpointing Files
The File > Checkpoint command saves the current file to disk and erases its change history and undo history.
You can think of this as a "clean" save operation. It has the same effect as saving the file, closing it, and open-
ing it again.
After using Checkpoint, you will not be able to undo any prior changes. Checkpoint also re-arms the file
backup feature so that when you save it again, a new backup file is made.
Time stamping
Source Insight records each source file's signature in the project database. The signature is composed of the
file’s modification date, plus the file’s size. If you open a source file later and the file's signature differs from
what is in the project database, then Source Insight will re-synchronize the project symbol database for that
file. By automatically synchronizing, you or others in your development team can use another text editor or a
source control system and still maintain Source Insight's project databases. See “Synchronize Files” on
page 352.
Recovery Procedure
If you have been editing and a crash occurred before you could save your files, then simply run Source Insight
again. Source Insight will know that there were outstanding changes to your files because it will find
orphaned recovery files. A dialog box will come up and indicate that a previous session with Source Insight
did not end normally. At that point, you have three options.
• Click the Recover button. Source Insight will proceed to recover all files previously opened. After
recovery, your session should look the same as it was the last time the recovery file was synchronized.
All unsaved edits should still be present.
(or)
• Click the Continue button. Source Insight will continue to start as though no recovery were done. You
will not be able to recover after continuing.
(or)
• Click the Quit button. Source Insight will quit immediately without attempting recovery. If you run
Source Insight again, it will still be able to do the recovery if you want to.
When a recovery is performed, Source Insight will resume as though you were in the middle of an editing ses-
sion. All the previously opened files will still be open and any edits you made will still be there. After the
recovery, you can continue to edit normally, or you can quit and save each file that had changes. Use File >
Save All to save all recovered files.
Note: Before a recovery can take place, the recovery system requires that the original files you had open previously
must still exist, and be unchanged since Source Insight opened or saved them. If you need to perform a recov-
ery, you should do it right away, before any of the original files are modified.
Warnings
Verify the results of a recovery before saving.
Source Insight's recovery system is very good, however, no recovery system can be foolproof. There are
always windows of vulnerability. If a recovery is needed, it is probably due to unusual circumstances, such as
a hardware failure, a power failure, a bug in a program that you spawned from Source Insight, or a bug in
Source Insight. Whatever the reason, it is still a good idea for you to scroll through each recovered file to see
that everything looks intact before you actually go ahead and save the files. If Source Insight's recovery file
was damaged or not written entirely, or the failure occurred while the recovery file was being updated, then
Source Insight may unwittingly trash your file while it thought it was recovering it.
If you find that the recovery didn't work correctly, do not save the file. Close the file without saving it. The
original, unsaved file will still be intact, although without your last changes saved. Also, the backup feature
probably made a recent backup of your file in the Backup folder.
Opening Files
On the Source Insight command line, you can specify files following the options. Each file name may be
optionally preceded by a plus sign (+) and a line number. If this is done, the file will be displayed with that line
number visible.
For example:
sourceinsight4 +100 file.c
This will open file.c and position the file so that line 100 is visible.
Opening Workspaces
In addition to regular text files, you may also specify the name of a workspace file for Source Insight to open.
For example:
sourceinsight4 myset.siwork
This will open all the files in the workspace file myset.siwork.
Any number of workspace file names may also be intermixed with regular file names.
For example:
sourceinsight4 +100 file.c myset.vw print.c myset2.siwork
This will open both the files and the workspace files.
Finding a Symbol
-f <symbol_name>
This option locates the symbol given in symbol_name, opens that file, and positions the insertion point on
the symbol. If the symbol can't be found, Source Insight will give an error message. This is unlike specifying
a symbol in place of a file name because this explicitly tells Source Insight that you are looking for a parsed
symbol, not a file.
Example:
sourceinsight4 -f DoIdle
Example:
sourceinsight4 –ub
Comparing Files
-d <file1> <file2>
This option open the File Compare window and compares the two given files. See “File Compare” on
page 205.
User-Level Commands
A command is a user-level operation that Source Insight performs when you select a menu item or type a
keystroke. For example, the File > Open command opens a file, and Ctrl+S invokes the File > Save command.
Each command has a name, and an action.
You can assign commands to menus, keystrokes, and mouse clicks, and those assignments are saved with
the current configuration. You can assign a keystroke to a command with Options > Key Assignments. You
can assign a command to a menu with Options > Menu Assignments. See “Key Assignments” on page 239,
and “Menu Assignments” on page 262.
User-level commands can also be implemented by Source Insight macro functions. See “Macros as Com-
mands” on page 377.
You can also define custom commands, which are useful for launching a compiler and other external tools
from Source Insight. See “Custom Commands” on page 137.
Custom Commands
A command is a user-level operation that Source Insight performs when you select a menu item or type a
keystroke.
In addition to the commands that are built into Source Insight, you can define custom commands. Custom
commands are similar to shell batch files. They execute external command-line programs and Windows GUI
programs. Source Insight allows custom commands to execute in the background. The output of custom
commands can be captured into a file for editing, or can be pasted into the current selection.
To define or edit custom commands, select Tools > Custom Commands. Once defined, a custom command is
like any other command. It can be assigned to a menu or a keystroke can be assigned to it. Custom com-
mands are saved in the current configuration.
Custom commands are useful for launching a compilation. By having a custom command that runs the com-
piler or make program, you can capture the compiler error messages and have the errors parsed and have
source links pointing to the erroneous source code automatically.
You can also implement a variety of text filters using custom commands. For example, you could define a
Sort custom command that runs a sort filter and pastes the output back over the current selection.
See also: “Custom Commands” on page 183, “Key Assignments” on page 239, and “Menu Assignments” on
page 262.
Note: Layouts are another type of settings file you can save and load. Layouts contain window arrangements. See
“Saving Window Arrangements with Layouts” on page 146.
The current configuration is loaded and saved automatically, but you can save and load configuration files
directly using the Options > Save Configuration and Options > Load Configuration commands. You can also
save or load individual parts, such as just key assignments.
By default, all your customizations are saved in a file called config_all.xml, stored in the Source Insight
user data directory. This is a global configuration file that applies no matter what project is open.
Each panel window has its own font and color settings. Edit the settings and select the desired fonts and col-
ors in all panels. A quick way to set them all at once is to use the Options > Preferences: Color & Fonts tab and
click the Set Panel Fonts and Colors button.
Configuration files contain multiple parts for different types of options. Here are some of the things stored in
the configuration:
• Preferences - The Preferences command sets a variety of user options, such as file handling, display
options, and language support.
• File Types - The File Type Options command defines and changes file types. File types let you govern
Source Insight's behavior depending on the name or extension of each file.
• Key Assignments - The Key Assignments command remaps the keyboard in Source Insight. Each com-
mand in Source Insight is listed in this dialog box and each command can be given a keystroke or
mouse button shortcut.
• Menu Assignments - The Menu Assignments command customizes the Source Insight menu bar. Each
command in Source Insight is listed in this dialog box and each command can be put on any menu.
When you make changes to your settings via a dialog box setting, or load new configurations, the configura-
tion file on disk is updated too.
The config_all.xml file contains sections for each part of the configuration. When you load or save a con-
figuration file, you can specify what parts are loaded or saved.
Each user that logs in and runs Source Insight gets a user data directory inside the Documents\Source
Insight 4.0 folder. Therefore, each user on a particular machine will have their own preferences stored
separately.
Note: It is wise to keep a backup copy of your global configuration file, which will end up containing all your customi-
zations. Once you use the Load Configuration command, or make a change to the customization settings inside
Source Insight, the configuration file will be changed automatically.
It is also a good idea to make a backup copy if you update your Source Insight software. Often, newer builds of
Source Insight will be compatible with older configuration files, but not the other way around. If you should
wish to revert to an older build of the software, it is best to use an older configuration file.
Any configuration part file attribute can be prefixed with the following tags:
Prefix Tag File Location Example
project_source: Points to the directory where your proj- project_source:config_keymaps.xml
ect's source files are. You can see and
edit this path in Project > Project Set-
tings.
project_data: Points to the directory where your proj- project_data:config_menus.xml
ect's data files are maintained. This is
specified when you first create your
project.
Loading a Configuration
Use the Options > Load Configuration command and select a new configuration file to be loaded. This com-
mand loads either the entire configuration contents, or only a specified subset of the configuration, such as
just the menu contents. See “Load Configuration” on page 252.
Saving a Configuration
Use the Options > Save Configuration command to save the contents of the current configuration to any
other configuration file. By saving configuration files, you can create several customized versions of Source
Insight, with each one having different menus, keystroke assignments, screen colors, and more. The Save
Configuration command can also save a specified subset of the current configuration.
Source Insight automatically saves any option changes you make, so you normally would not need to use the
Save Configuration command. See “Save Configuration” on page 320.
Visual Themes
A visual theme is a snapshot of user interface color settings and syntax formatting style properties.
You can quickly change the color and look of Source Insight by changing the current visual theme. To select
and apply a new theme, select Options > Visual Theme > theme name.
You can also create new themes. When you define a theme, you are recording the colors and fonts used in
various user-interface items and panels, along with the syntax formatting styles.
Some predefined themes come with Source Insight. For example, there is a theme called "Black" that
switches to light text colors on a black background.
To manage themes, select Options > Visual Theme > Manage Visual Themes. You can define new themes,
redefine themes, as well as import and export themes. See “Manage Visual Themes” on page 259.
Inside a Theme
A visual theme is a collection of font and color settings. It contains:
• Colors of user interface elements (from Options > Preferences: Color & Fonts)
• All panel fonts and colors. Note that each panel can have its own color and font settings.
• Styles properties which are used for syntax formatting in source windows
When you define a theme, you can choose any or all of the above to be saved as part of the theme. Loading a
theme will apply the components contained in the theme and leave the rest alone. So for example you could
define a theme that only changes panel colors.
Color Interactions
It’s important to pick colors and styles that work well together. The color of user interface elements, such as
the Window Background color and Default Text color, can effect the readability of text formatted with some
styles. For example, if you set the Window Background color to black, and you have a style that uses a black
text color, then text in that style will not show up.
Therefore, you need to make sure the colors and style colors work in concert. That is why themes are
designed to bundle style settings with other color settings.
Applying a Theme
To select and apply a new theme, select Options > Visual Theme > theme name. You can also apply a theme
by selecting Options > Visual Theme > Manage Visual Themes, then picking a theme to apply.
When a theme gets applied, the theme properties are simply applied to the various font, color, and style set-
tings in Source Insight. Those settings are all saved in your current configuration, which is typically all saved
in a single configuration file. So loading a theme sets a bunch of settings in the configuration, then the config-
uration file gets saved.
See “Customized Settings and Configurations” on page 138.
4. Select Options > Visual Themes > Manage Visual Themes and click the Define button. The Define
Visual Theme dialog will appear.
5. In the Save To item, if you want to create a new theme then select New Theme, or to redefine an
existing theme select the existing theme name. In the section titled "Include In Theme", select the
components you want to be part of the theme. When a theme is applied, only the components that
are part of it have any effect.
Saving Layouts
To save a layout, select View > Save Layout. This saves the current layout to a new layout file. You can also
click the Save Layout button on the Layout Toolbar to save the current layout.
Layout Files
Layout files are stored in XML format in the Documents\Source Insight 4.0\Settings user folder. You can
save as many different files as you want.
There are four special layout file names:
• layout_a.xml
• layout_b.xml
• layout_c.xml
• layout_d.xml
Each name corresponds to the four "load layout" buttons on the Layout toolbar.
Loading Layouts
To load a layout, select View > Load Layout, or click one of the four "Load Layout" buttons on the Layout tool-
bar.
There are also four Load Layout commands which you can bind a keystroke to. They are:
• Load Layout A
• Load Layout B
• Load Layout C
• Load Layout D
They load one of the four special layout_X.xml files mentioned above.
Performance Tuning
Depending on the size of your project, you may want to tune Source Insight for better performance. The Pref-
erences dialog box, and the Project Settings dialog box both contain options that affect performance.
Project Size
The size of a project has a large effect on the performance of certain features in Source Insight. The project
size can be measured in number of files, and in number of declared symbols.
Tip: Use Project Report to see project size statistics.
To find out how large your project is, use the Project > Project Report command and note the top lines of the
report. At the top of the project report, Source Insight prints the number of files, the number of symbols, and
the number of symbol index entries in the project. You can also see these same statistics in the Project >
Rebuild Project dialog box at the bottom of the dialog box. (You do not have to rebuild the project to see the
statistics.)
Memory Usage
Source Insight very efficient in its memory use. However, Source Insight uses virtual memory in proportion to
the size of your project. If your projects are large, Source Insight will require more virtual memory. Large proj-
ects can use a lot of virtual memory.
Source Insight makes heavy use of memory-mapped files. This is a operating system feature whereby files
can be mapped into virtual address space, so that a file looks like a block of memory to a program. Source
Insight uses memory-mapped files to provide the fastest possible access to source files and database files.
Source Insight uses an efficient way of mapping large project databases and indexes into virtual memory.
The size of a project database is proportional to the number of declared symbols in the project. Therefore, if
your project is very large, the amount of memory used by Source Insight as reported by Task Manager (the
Working Set) can be several hundred megabytes. However, most of the memory represents portions of the
symbol database mapped into virtual memory space. Source Insight does not require this much physical
memory.
The display code has been sped up considerably to be able to provide more features with acceptable perfor-
mance. It is possible to reduce the display functionality to speed it up.
The Preferences: Syntax Formatting dialog box lets you specify how detailed you want the display. Each
option has a performance cost. The significant options are listed here, starting with the least costly, to the
slowest and most costly:
1. Apply styles for references to members
2. Apply styles for symbol declarations
3. Apply styles for local symbol declarations
4. Apply styles for references to function-local symbols
5. Apply styles for non-function-local symbols
6. Find references using the Project Symbol Path
7. Qualify member references
Speeding Up Auto-Completion
As you type an identifier, the auto-completion window pops up to propose matching identifier names. Every
time you type a character, Source Insight considers the symbol data for that file to be "stale". To give you the
most accurate auto-completion results, Source Insight would need to reparse your file after each character
you type. There is an option that controls this in the Preferences: Symbol Lookups dialog box.
The Parse locally before lookup option causes Source Insight to reparse before the auto-completion window
appears. On a fast machine, or in a small file, the speed will be acceptable. However, turning this option off
will result in a faster response.
The fastest type of search in Source Insight is the Lookup References search. When you search this way,
Source Insight looks for references to a single whole-word item. When you search for a single whole-word,
Source Insight uses a special index file to make the search fast. It's a good idea to get into the habit of using
Lookup References, instead of Search Files, when you can.
The following folders are created in the current user's Source Insight folder:
File or Folder Description
Backup Folder containing non-project backup ver-
sions of files that are saved with Source
Insight.
Clips Folder containing clips files, which are listed
in the Clip Window. You can also copy your
own text files to this directory and they will
be included automatically in the Clip Win-
dow.
Projects Folder containing Source Insight projects
created on your machine. Each project gets
its own sub-folder inside this folder.
Projects\project_list.sidb The Project List: contains a list of all projects
opened or create on your machine.
Projects\Base Folder containing project files for the "Base"
project.
Snippets Folder containing code snippets.
Settings Folder containing your configuration settings
files and layout files.
c.tom C/C++ preprocessor token macros.
.si_recovery Crash recovery files, which contains informa-
tion needed to recover unsaved changes
after an abnormal termination. These files
only exist if a earlier session crashed.
Global.siwork Global Workspace: the session state used
when no project is open.
filealias.txt File name alias file, used to override the file
type associated with a given file name. This
is local copy for the current user. The original
version is stored in the Program Files direc-
tory of Source Insight.
File Description
Name.snippets.xml Code snippets for the project.
Name.SearchResults Last search results performed.
Name.sip._* Various data files
Backup The project’s backup folder, which contains
backup versions of your source files
cache Various cache files
This is an alphabetical listing of all the user-level Source Insight commands. Each command is described in
detail.
For overviews on important concepts, please refer to “Features and Concepts” on page 39.
Commands Overview
A command is a user-level operation that Source Insight performs when you select a menu item or type a key-
stroke. For example, the Open command opens a file; the Save command saves a file. Each command has a
name, and an action.
Commands are resources that can be assigned to menus, keystrokes, and mouse clicks, and those assign-
ments are part of a configuration.
Keystrokes and mouse clicks are assigned to commands. For example, the Ctrl+O keystroke is assigned to the
Open command. More than one keystroke may be assigned to a given command. Use the Key Assignments
command to customize the keyboard.
Commands are assigned to menus. For example, the Open command is assigned to the File menu. Use the
Menu Assignments command to customize the contents of the menus.
Source Insight also allows you to define custom commands, which are useful for launching the compiler and
other external tools from Source Insight. See “Custom Commands” on page 137.
Commands
This is an alphabetical listing of all user-level commands in Source Insight.
Note: You can also add files to the project by dragging files from Windows Explorer and dropping them onto the Proj-
ect File List panel. The Project File List panel also allows removing files from the project.
The file types that are defined by default in Options > File Type Options correspond to the types of source
files you probably want to use with Source Insight. Normally, only those types of files should be added to a
project.
Tip: Use Options > File Type Options to control what types of files are added to projects.
The File Type Options dialog box contains the check box: Include when adding to projects. You can use this
check box to control what file types Source Insight will automatically add to your project, or what file types
will be displayed in the list box in the Add and Remove Project Files dialog box.
File Name
Type the name of the file you want to add or remove in this text box. The lists will be matched automatically
with what you type. You can type a wildcard and press Enter to filter the file list to show only those files that
match the wildcard.
You can also type a full directory path, or a drive letter followed by a colon to switch the current directory.
Directory List
Contains a directory tree of the current drive. If you select a directory name in this list box, the File Name list
will show what is in that directory. The current working directory and wildcard filter, if any, is displayed
above the list box.
Close
Closes the dialog box, keeping the changes you made.
Add
Adds the selected file(s) to the project. If a directory is selected, then the current directory switches to that
directory.
Add All
Selects all the items in the File Name list and adds them to the project. If any directories are included, then
their contents are added too. Source Insight will prompt you first to see if you want to include the directories.
Add Tree
Click Add Tree to add a whole source tree to your project.
When a directory is selected, this adds the whole directory tree to the project. That is, all the directories in
the sub tree are scanned for files that match known file types, and they are added to the project.
Remove Tree
When a directory is selected, this removes all files found in that directory tree.
Remove File
Removes the file(s) selected in the Project Files list.
Remove All
Removes all files from the project. The project will be empty.
Remove Special…
Brings up the Remove File dialog box, which allows you to do special remove operations, such as removing
all *.h files.
Add File
The Add File command adds one or more source files to the current project. This command existed in earlier
versions of Source Insight, however the Add and Remove Project Files command is a newer replacement,
which provides a central dialog box from which to add and remove files from your project.
File Name
The name of the file to be added to the project. You may type a file name or a wildcard pattern and press
Enter. If you typed a wildcard, the pattern will be applied to the file list box.
Add
Click this button to add the file named in the File Name text box to the project and close the dialog box. If the
File Name text box contains wildcard characters, the wildcards will be expanded and displayed in the File list
box, and the dialog box will not be closed. If one or more files are selected in the File list box, then all selected
files are added to the project.
Select All
Click this button to select all the files contained in the File list box.
Add Dir
Click this button to add a whole directory to the project. If the Subdirs Also check box is enabled, then this
will recursively add all files in the whole subdirectory tree.
Show Dirs
Click this button to toggle the list box contents between showing file names, and showing subdirectory
names.
Subdirs Also
If enabled, then Source Insight will recurse through all subdirectories when the Add button is clicked, or
when a single directory is selected and Add is clicked.
If not enabled, then Source Insight will only add the selected files or the files in the selected directory and will
ignore sub-directories.
Browse
Click this button to bring up the standard Windows Open dialog box, which allows you to browse around
your disks. If you select a file in this dialog box, its path will be placed into the File Name text box.
Remove
Click this button to switch to the Remove File dialog box.
Advanced Options
This allows you to selectively disable internal optimizations in Source Insight. This can help to narrow down
a possible bug. If you report a bug, you may be asked to make changes in the Advanced Options dialog box to
help troubleshoot a problem. Normally, you should have no need to use this feature.
Arrange Windows
Tiles and arranges source file windows within the Multiple-Document area.
Arrangement Toolbar
Shows or hides the Window Arrangement toolbar.
Back Tab
The Back Tab command moves the cursor to the left by one tab stop.
Backspace
The Backspace command backs over the character to the left of the insertion point. If the selection is
extended, the text in the selection is deleted instead.
Beginning of Line
The Beginning of Line command moves the insertion point to the beginning of the current line.
Beginning of Selection
The Beginning of Selection command moves the insertion point to the beginning of the current selection if it
is extended. If the selection is already an insertion point, then nothing happens.
Blank Line Up
The Blank Line Up command moves the insertion point to the beginning of the previous blank line.
Block Down
The Block Down command moves the insertion point to the next } brace. This corresponds to the end of the
current code block in languages like C/C++ and Java.
Block Up
The Block Up command moves the insertion point to the previous { brace. This corresponds to the beginning
of the current code block in languages like C/C++ and Java.
Bookmark
The Bookmark command activates the Bookmark panel. Bookmarks are useful for storing locations of inter-
est in your files.
See “Bookmarks” on page 102.
Bookmark Window
The Bookmark Window command shows and hides the Bookmark Window panel. The Bookmark Panel is a
floating, dock-able window that shows the current list of bookmarks.
See “Bookmarks” on page 102.
Text Field
Type the partial name of a bookmark, or a line number here. Source Insight checks to see if the mark you
typed matches an existing bookmark name. If it does, then pressing Enter will position you to that mark. If
the bookmark you've just typed does not exist, then pressing Enter will create a new bookmark.
Marks list
Displays a list of all the bookmarks currently set. Each item in the list shows the bookmark's name, the file
it's in, and the line number it's on, and the function that contains the bookmark, if any.
Right-click the mouse on the list to see the bookmark menu.
Add (Ctrl+N)
Click this button to create a new bookmark. The mark's name is taken from the Name text box. If the book-
mark name is already in the list (i.e. it already exists), then its position will be redefined to the current cursor
position.
Delete (Ctrl-X)
Click this button to delete the selected marks. To delete all bookmarks, right-click on the list and select
"Delete All Bookmarks".
Go To (press Enter)
Click this button to jump to the mark that is selected in the Marks list.
Bookmark Options
The Bookmark Options command sets the options for handling bookmarks.
Bottom of File
The Bottom of File command makes an insertion point at the last line in the current file.
Bottom of Window
The Bottom of Window command makes an insertion point at the last visible line in the active window.
Browse Files
The Browse Files command brings up the standard Windows system Open File dialog box so that you can
browse the regular file system and open any file. This is unlike the regular Source Insight Open command,
which brings up the Project Window, which lists only the files in the current project, regardless of directories.
Tip: Instead of using this dialog box, which is modal, you can use the Project Window's symbol list view. The Project
Window is mode-less; it can float or dock to the side of the application window. Furthermore, the Context Win-
dow shows the declaration of the item you select in the Project Window symbol list.
Jump
Click this to jump to the definition of the currently selected symbol. If an item is selected in the Symbol List,
then that is the current symbol. Otherwise, the symbol typed in the Symbol Name text box is used.
If the symbol name text box starts with a question mark (?), then Source Insight will replace the list with all
the symbols that match the search pattern that follows the question mark; the dialog box will remain open.
Info
Click this button to run the Symbol Info command on the selected symbol.
References
Click this button to search for references to the selected symbol.
Insert w/Args
Click this button to replace the current selection with the name of the symbol, followed by the parameters as
they appear in the symbol definition, if the symbol is a function.
Insert Name
Click this button to replace the current selection with the name of the symbol.
List
Click this button to create a cross-reference list of the symbols currently listed in the Symbol List. A new file is
created and named Symlist.txt. Each line of the file contains a symbol name, and the file and line number
where it's defined.
Symbol Types
This button is used to specify what types of symbols will be included in the symbol list and what types of
symbols will be searched for when using a regular expression in the symbol name text box.
The Browse Local File Symbols command automatically selects the first word in the selection before the dia-
log box comes up. The word is selected so that you can use the Insert buttons to replace the symbol name.
Symbol
The name of the symbol to be looked up. This text box is automatically loaded with the first word in the cur-
rent selection when the dialog box comes up. You can type any symbol name into this text box.
Symbol List
Displays a list of all symbols in the project. If a search pattern was given in the Symbol Name text box, then
this is a list of all the symbols that satisfy the search pattern. Below the symbol list, the currently selected
symbol's type and file of origin are displayed.
The types of symbols shown in the list are controlled by the settings accessed with the Symbol Types button.
As you type, Source Insight will select the symbol in the Symbol List that starts with what you are typing. For
example, if you type "Pch", then the first item in the list (in sorted order) that starts with "Pch" is selected in
the list. The match is not case sensitive and leading underscores are ignored.
You can specify a regular expression style search pattern to search for symbols by typing a question mark (?)
and then the search pattern, and click the Jump button. All the symbols that match the pattern are placed in
the Symbol List. For example, to find all symbols beginning with "Delete" and containing "Foo", you could
type "?^Delete.*Foo".
Jump
Click to jump to the definition of the currently selected symbol. If an item is selected in the Symbol List, then
that is the selected symbol. Otherwise, the symbol typed in the Symbol Name text box is used.
If the symbol name text box starts with a question mark (?), then Source Insight will perform a search, and
the dialog box will remain up.
Info
Click to run the Symbol Info command on the selected symbol.
References
Click to search for references to the selected symbol.
Insert w/Args
Click to replace the current selection with the name of the symbol followed by the parameters as they appear
in the symbol definition.
Insert Name
Click to replace the current selection with the name of the symbol.
List
Click to create a cross-reference list of the symbols currently listed in the Symbol List. A new file is created
and named SYMLIST.TXT. Each line of the file contains a symbol name and the file and line number where it's
defined.
Symbol Types
This button is used to specify what types of symbols will be included in the symbol list and what types of
symbols will be searched for when using a regular expression in the symbol name text box.
Browser Mode
The Browser Mode command toggles Source Insight's Browser-Mode. When Browser-Mode is on, your source
code becomes read-only, and acts like a web browser. For example, single clicking on the name of a function
in a function call will jump to the function's definition.
You can also toggle Browser-Mode by right-clicking in the small box at the bottom right of the Source Insight
application window. Then select Enable/Disable Browse Mode from the pop-up menu
Table 4.1: Browser Mode Keyboard Commands
Key or Mouse click Action
Backspace Navigate back to previous location.
Space Jump to definition of symbol under
cursor.
Hold down CTRL Allows you to drag out a text selec-
tion instead of jumping to a defini-
tion.
Click on a symbol name Jump to definition of symbol.
Calculate
This replaces a selected mathematical expression with its result. To use this command, first select text that is
some kind of mathematical expression. For example 112*14. Invoke the calculate command to solve the
expression and insert the answer. In this case, 1568.
Cascade Windows
The Cascade Windows command rearranges the windows by cascading them down the screen.
Checkpoint
Saves the current file to disk and erases its change history and undo history. You can think of this as a "clean"
save operation. It has the same effect as saving the file, closing it, and opening it again. After using Check-
point, you will not be able to undo any prior changes.
Checkpoint All
Performs the Checkpoint command on all open files. This saves all open files to disk and erases their undo
and change histories. After using Checkpoint All, you will not be able to undo any prior changes in your files.
Clear Highlights
Removes all word highlighting in all source windows. Highlighting is applied by using the Highlight Word
command.
Clip Properties
(On Clip Window toolbar and right-click menu)
The Clip Properties command allows you to edit the name of the clip.
Clip Window
This shows or hides the Clip Window. The Clip Window displays a list of clipboard-like clips of text that you
can insert.
A clip is a piece of text that you might want to insert easily into your code. For example, a standard function
heading comment.
Using Clips
To create a clip:
1. Select the text you want to make into a clip.
2. Use the Edit > Copy To Clip command. The Clip Window will appear.
3. Type the name of the new clip and press Enter. The new clip will appear in the Clip Window.
To paste a clip:
1. Select where you want the clip inserted in your file.
2. Use the Edit > Paste From Clip command. The Clip Window will appear. If the Clip Window is already
visible, just double click on the desired clip and it will be inserted.
3. Type the name of the clip, or just double click on it in the Clip Window
You can set Clip Window options using the Clip Window Properties command, or clicking the properties but-
ton in the Clip Window toolbar. See “Clip Window Options” on page 171.
Close
The Close command closes the current file. If the file has been edited, but not saved, then Source Insight will
ask you if you want to save the changes before closing the file by using a dialog box with the following but-
tons.
Yes
Click to save and close the file.
No
Click to close the file without saving it. Changes you've made will not be saved.
Cancel
Click to cancel the Close command. The file will remain open, and it will not be saved.
Close All
The Close All command performs a Close command on each open file. For any files that you have changed
but not saved, Source Insight will ask if you want to save them.
If you have any captured custom command windows open and the custom command is still running, those
windows are not closed.
Close Project
The Close Project command closes the current project. When the project is closed, all open files are also
closed. Source Insight does this by performing the Close command on each open file. The workspace and
configuration files for the project are also saved.
Close Window
The Close Window command closes the current window. Since a file can appear in more than one window,
closing a window does not necessarily mean you will close the file buffer too. If you close the only window
showing a file, then the file is closed also.
Color Options
Activates the Preferences: Colors & Fonts dialog box, which allows you to specify the colors of user interface
items, and the font and color options of the panel windows.
The color items in this dialog can also be grouped into Visual Themes.
Pick Color...
Click this button to select a new color for the item in the list.
Styles...
Opens the Style Properties dialog to edit the formatting style settings. The styles are applied to text based on
parsing. The colors used in styles should work together with the colors you pick for the items in the list. For
example, the Window Background color should not conflict with the text or background colors you choose
for styles.
Themes...
Opens the Visual Themes manager.
Use Defaults...
Resets the color options to the initial defaults.
Note: Applying a Visual Theme will also change all the panel colors en masse to whatever is stored in the theme.
Command Shell
The Command Shell command is a Custom Command that launches a shell command box from Source
Insight.
Compare Files
The Compare Files command compares two files and shows them in the File Compare window side by side.
See “File Compare” on page 205.
To compare a file:
1. Select Tools > Compare Files
2. In File 1, enter the path of the file. The current file name is preloaded into this field.
3. In File 2, enter the path of the second file. You can enter just a directory path and the file name will
be implied. To load any other open file, click the down-arrow to show recent files and other open
files.
4. Press Enter or click Compare. The File Compare window will open and show the files side-by-side
with differences highlighted.
Select the backup file that contains a previously saved version, then click OK to show the differences. The
number of backup files available depends on how many times you saved a file, and how long backup files are
stored. The backup settings are controlled in the File Options dialog. See “File Options” on page 208.
Every time you save a file for the first time in a session, normally Source Insight saves a copy of the original
file in as a backup. A unique number is added to the file name so multiple versions of the file can exist in the
backup directory.
Each project has its own backup directory. You can set it in the Project Settings dialog. See “Project Settings”
on page 285.
Complete Snippet
Completes and expands a code snippet by name. This is similar to the auto-completion list that appears
when you type a symbol name, except only snippet names appear in the list.
By default, snippet names also appear in the regular auto-completion list. However you can disable that
option and use Complete Snippet to explicitly show snippets. See “Code Snippets” on page 98.
Complete Symbol
The Complete Symbol command invokes the auto-completion function. The popup auto-completion win-
dow will appear.
By default, code snippet names also appear in the regular auto-completion list. However you can disable
that option and use the Complete Snippet command (Ctrl+E) to explicitly show snippets. See “Code Snip-
pets” on page 98.
The Complete Symbol command replaces the whole word you are typing with the complete name of the
symbol.
For example, let's say that you have a function called InitWindowState. As you type in the letters: "InitWi", the
auto completion window narrows what you've typed down to a unique function (InitWindowState). The
Complete Symbol command will replace what you've just typed with the whole name "InitWindowState".
The auto completion settings affect how the completion function works. You have the option of inserting
function parameters when a function name is inserted. You can change the auto-completion options using
the Preferences command. See: “Typing Options” on page 364
access this dialog, select Options > Preferences: Languages, then click the corresponding "Conditions" but-
ton.
Add / Delete
Use this to add a new condition identifier and its value, or to delete entries in the list.
Edit...
Use this to edit the value of the selected identifier in the list.
Import / Export...
You can import or export the current condition list.
Scan Files...
This will scan your project’s source files to determine what conditional identifiers are used, and their defined
values, if any. The results are put into the list. Note that the value of "Ignore Condition" means that Source
Insight assumes the value is unknown, and will ignore preprocessor statements that use that condition iden-
tifier.
Context Window
This command toggles the Context Window visibility on and off.
See “Context window” on page 90.
psvar->...
If you select inside of psvar, then Source Insight will look at the declaration of psvar, see that it is a pointer to
struct S, and then show you the declaration of struct S.
Clear this option to simply show the declaration of the each variable, without walking up the declaration
hierarchy.
Scaling (percentage)
Sets the percentage of text size scaling in the Context Window.
Tracking Options…
Click this button to view the Symbol Tracking Options dialog box, which displays options that guide what the
Context Window will pay attention to.
Font…
Specifies the font used to display symbol lists and source code in the Context Window. If the Context Window
is currently showing a list, then this specifies the list font. If the Context Window is currently showing a source
file, then this specifies the source code font.
Text Color…
Specifies the text color of list items in the Context Window. The colors of source code are determined by the
Syntax Formatting options in the Preferences dialog box.
Back Color…
Specifies the background color of list items in the Context Window. The colors of source code are determined
by the Syntax Formatting options in the Preferences dialog box.
Off
Select this to disable automatic symbol tracking.
Inside of comments
Select this to have the Context Window look up symbols when the cursor is inside of comments.
Copy
The Copy command copies the contents of the current selection to the clipboard. Once in the clipboard, it
can be pasted to other locations using the Paste command. This command is only allowed if the current
selection is extended.
Copy Line
The Copy Line command extends the current selection to include whole lines and copies that selection to the
clipboard. Each use of Copy Line extends the selection down one more line.
Copy List
This command appears on the right-click menu when you click on a list. It copies the contents of the list to
the Clipboard. This lets you make a copy of any list, or paste any list into a file and print it.
Copy Project
This copies the current project to a new project. The new project is created by cloning the current project
data files. Your source files will not be copied. The new project will point to the same source files. If you delete
the original project after copying it, you have effectively renamed the project.
Copy Symbol
This command appears on the Symbol Window right-click menu.
The Copy Symbol command copies the selected symbol, along with its definition body, to the Clipboard. For
example, if you click on a function name and select Copy Symbol, then the whole function is copies to the
Clipboard.
Copy To Clip
The Copy To Clip command copies the contents of the current selection to a clip buffer that you name. The
Clip Window is activated when you use this command so that you can specify the destination clip name.
After either selecting a clip item in the list, or typing a clip name, press the Enter key to complete the copy
operation.
Cursor Down
The Cursor Down command moves the insertion point down by one line.
Cursor Left
The Cursor Left command moves the insertion point left by one character.
Cursor Right
The Cursor Right command moves the insertion point right by one character.
Cursor Up
The Cursor Up command moves the insertion point up by one line.
Custom Commands
Custom commands are similar to command shell batch files. They allow Source Insight to spawn any com-
mand line driven tool, and to capture its output. Custom commands can also execute Windows programs.
Customs commands can execute, and then return to Source Insight. The output of shell custom commands
can be captured into a file for editing, or can be pasted into the current selection. Custom commands are
stored as part of the current configuration.
Custom commands can be used to spawn compilers, source control programs, and file filters, such as "sort".
Tip: A shortcut for editing a custom command is to hold down the Ctrl key while selecting the command. The Cus-
tom Commands dialog box will appear for that command.
Command
Displays the name of the currently selected command. This pull-down list contains a list of all the custom
commands defined.
Run
This is the command line to be executed when the custom command is invoked. The Run text box can con-
tain special meta-characters. See “The 'Run' Field Format” on page 186.
Dir
The working directory used when executing the script specified in the Run text box. Source Insight sets the
current working directory to this location before running the command. If left blank, then Source Insight sets
the current working directory to the project source directory. This field can also contain special meta-charac-
ters, just as with the Run field. See “The 'Run' Field Format” on page 186.
Output Group
This group of options control what happens to the output of the command.
Iconic Window
If enabled, the spawned program will be put into a minimized window. If not enabled, then the program will
launch normally.
Capture Output
If enabled, the standard output of the command will be captured and will appear in a new command output
window when the command completes. The command output window's title will be the name of the custom
command. If not enabled, the standard output will not be captured.
Paste Output
If enabled, the standard output of the command is pasted to the current selection.
Control Group
This group of options specifies what Source Insight does before and after the command runs.
Pattern contains
File, then Line and Line, then File. This indicates the order of the groups in the pattern expression.
Select File, then Line if the first group in the pattern expression is the file name and the second group is the
line number. With this setting, the second group, (i.e. the line number), is optional.
Select Line, then File if the first group in the pattern expression is the line number and the second group is the
file name.
Pattern
Contains the regular expression used to search the command output for file names and line numbers. This is
ignored if the Parse Source Links option is disabled. If the option is enabled, then this text box must contain a
valid regular expression that contains "groups" for the file name and the line number. See “Regular Expres-
sions” on page 109.
Define
Click this button to define the command named in the Name text box. If the command already exists, it is
redefined.
Remove
Click this button to delete the command.
Run
Click this button to define and execute the command.
Cancel
Click this button to cancel the dialog box. Any definitions made in the dialog box will be retained.
Menu…
Click this button to define the current command and jump to the Menu Assignments dialog.
Keys…
Click this button to define the current command and jump to the Key Assignments dialog.
You can also postfix any of the above characters marked with * with either of the following modifier charac-
ters.
Character Expands to Example
%o for all open files %f%o
%m for all modified files %f%m
Path Variables
You can also use Path Variables in Run and Dir text fields. See “Predefined Path Variables” on page 153.
ShellExecute Commands
Tip: ShellExecute lets you invoke Windows Shell commands.
Custom Commands support the "ShellExecute" function, which lets you tell the Windows shell to perform an
operation on a specified file. The nice thing about ShellExecute is that you don't need to know what specific
application is registered to handle a particular type of file. For technical background information, see the
"ShellExecute" function in the Windows Shell API documentation.
To use this feature, the Run string in the custom command needs to start with "ShellExecute". The format
should be:
ShellExecute <verb> <filespec> <optional parameters>
For example, to browse a website:
ShellExecute open http://www.somedomain.com
The verb is a single word, which can be one of the following:
• edit Opens an editor for the file.
• explore The function explores the folder specified.
• open The function opens the file specified. The file can be an executable file or a document file. It can
also be a folder.
• print The function prints the document file specified. If filespec is not a document file, the function
will fail.
• properties Displays the file or folder's properties.
• find Launches the Find Files application found on the Start menu.
• "" (empty string) to skip this parameter to ShellExecute.
The filespec parameter can be any valid path. Use double quotes around complex path names with embed-
ded spaces. You can also use a meta-character, such as %f (for the current file). It can also be the name of an
executable file.
The optional parameters list is anything to the right of the filespec. It specifies the parameters to be passed to
the application that ultimately runs. The format is determined by the verb that is to be invoked, and the
application that runs. You can use custom command meta-characters here as well.
The working directory text box of the custom command is applied before the ShellExecute is invoked. How-
ever, output cannot be captured or parsed when using ShellExecute.
ShellExecute Examples
Here are some useful examples showing how to use ShellExecute.
Action Custom Command Run String
To browse to a web site: ShellExecute open http://www.someweb-
site.com
To explore your Windows ShellExecute explore "C:\Documents and
documents file folder: Settings"
To launch Internet Explorer: ShellExecute "" iexplore
To preview a file in Internet ShellExecute "" iexplore %f
Explorer:
To search for files in the cur- ShellExecute find %j
rent project folder:
Cut
The Cut command copies the contents of the current selection to the clipboard, and deletes the selection.
Note that although the Cut command deleted the current selection, you still have that text saved in the clip-
board. You could reverse the deletion by following the Cut command with a Paste command.
Cut Line
The Cut Line command copies the current line to the clipboard and deletes the line. The cursor can be any-
where on the line when you use this command.
Cut Symbol
(On the Symbol Window right-click menu)
The Cut Symbol command cuts the selected symbol.
Cut To Clip
The Cut To Clip command copies the contents of the current selection to a clip buffer that you name, and
then deletes the text. The Clip Window is activated when you use this command so that you can specify the
destination clip name.
Cut Word
The Cut Word command cuts the word to the right, starting at the insertion point.
Deactivate License
Deactivates and de-authorizes your installation of Source Insight. This frees your license up to be installed
and used on a different machine.
Delete
The Delete command deletes any file on disk, including the currently open file.
Delete Character
The Delete Character command deletes the character at the insertion point. If the current selection is
extended, it deletes the whole selection.
Delete Clip
(On Clip Window tool bar and right-click menu)
The Delete Clip command deletes a clip file from the Clip Window and from disk.
Delete File
The Delete File command deletes a file from the disk and removes it from the current project if it was part of
the project. If you specify the current file, then that file is closed and deleted.
Delete Line
The Delete Line command deletes the current line. Unlike the Cut Line command, the clipboard is not
effected.
Directory Compare
This opens the Directory Compare window, which is used to compare the files in two directories. The Direc-
tory Compare windows shows two lists of files side by side - the left and right directory contents.
The File Compare window can be used to compare two versions of a file. See “File Compare” on page 205.
Toolbar
1. Compare Selected File - opens the File Compare window to show differences between the selected
files.
2. Refresh / Rescan Directory and compare again.
3. Go to Previous / Next file that differs.
4. Copy File From Left-to-Right and Right-to-Left directories.
5. Delete the Left / Right file.
6. Open the Directory Compare Options. See “Directory Compare Options” on page 193.
To compare directories:
1. Type the path of the left directory above the left list, or click the ... button to browse.
2. Type the path of the right directory above the right list, or click the ... button to browse.
3. Press Enter or click the Go button.
4. Source Insight will scan the files in both directories and show the results below in a side by side list-
ing.
The Status column in the center of the list indicates if the left-hand file is the same, different, newer, or older
than the right-hand file.
You can control how the files are compared by clicking the properties button. See “Directory Compare
Options” on page 193.
Show Columns
Check mark the columns you want to see in the file listing.
Comparison Method
These options determine how each file in the directories is compared.
Other Options
Display Options
This command brings up the Display page of the Preferences dialog box. These options are part of the current
configuration.
Display Elements
The Display Elements group is used to turn on and off elements of the user interface.
Search Bar
Displays the File Search bar that appears below the main toolbar.
Status Bar
Displays the status bar at the bottom of the Source Insight application window.
Popup Toolbar
This enables the popup toolbar that appears when you whole-word select a symbol name. The popup tool-
bar fades into view and lets you quickly jump to a symbol’s definition, a function’s caller, or find references to
a symbol. The popup toolbar is first shown translucent, but it gets more opaque as you move the mouse
closer to it.
Tab Tray
Turns on and off the tab tray at the bottom of the Source Insight application window. Floating windows that
are minimized appear in the Tab Tray.
Reset
Resets the positions of all the auxiliary windows so that they are moved onto the main monitor, and are not
transparent.
Options Group
The items in the Options Group control general options for different display elements in the program.
Enable Animations
Enables simple animations to show when input focus changes to a floating tool window, and when floating
windows are "rolled up" or "rolled down". You might want to turn off animations if your video card perfor-
mance is slow.
Panels Group
These options affect floating and docked panel windows. See “Panel Windows” on page 31.
Other Buttons
Styles…
Edits style properties. See “Style Properties” on page 343.
Spacing...
Click this button to change character spacing options. See “Character Spacing Options” on page 198.
Window Tabs...
Click this button to edit the window tab options.
Scroll Bars...
Click this button to edit the vertical scroll bar options. See “Scroll Bar Options” on page 322.
Here is an example. Let's say somebody wrote this in Notepad, using Courier New (a fixed-pitch font), with
tabs between columns so that X and Y, and Q and R line up. Both the words "narrow" and "very-wide" fit
within column 0 - one tab stop, as shown below.
Tab stop: 0 1 2 3
Line 1: narrow X Q
Line 2: wide Y R
Now, in Source Insight, with rich formatting, "narrow" fits within a tab width, but "wide" doesn't. If Source
Insight just pushed Y over by one more tab stop, this is what you get:
Tab stop: 0 1 2 3
Line 1: narrow X Q
Line 2: w i d e Y R
Now Y is aligned with Q. The rest of the columns don't line up anymore. In fact, this is exactly what happens if
you turn off Line up white space in File Type Options.
When Line up white space is enabled, Source Insight tries to help the situation by lining up tab positions like
this:
Tab stop: 0 1 2 3
Line 1: narrow X Q
Line 2: w i d e Y R
If your code looks like it does above, then you may want to specify a different space width character, such as
"M" or "W", which are wider letters in most fonts. This would have an effect like this, where all tab stops
would be wider:
Tab stop: 0 1 2
Line 1: narrow X Q
Line 2: w i d e Y R
This also works the other way when the text looks a lot narrower than it would be in a fixed pitch font.
Drag Line Up
Moves selected text up by one line. This is useful for dragging a whole line or lines up above something else in
a file.
Duplicate
The Duplicate command creates a duplicate of whatever is selected.
Duplicate Symbol
(On the Symbol Window right-click menu)
The Duplicate Symbol command creates a duplicate of the selected symbol.
Edit Condition
Use this command to edit the value of a selected parsing condition variable. This is used for languages that
support conditional compilation, such as C, C++, and Window Resource files. Conditional code is placed
between #-directives such as #ifdef. See “Conditional Parsing and Preprocessor Support” on page 60.
You can right-click on your source code and select Edit Condition from the menu.
Source Insight can parse those sections of code conditionally depending on the value of condition variables
that you specify. The Edit Condition command lets you edit the value of a condition variable, or edit the list of
condition variables.
To use this command, right-click on an identifier that is a condition variable in your code. Then select Edit
Condition. You will be able to specify that variable's value.
For example, place the cursor inside of MACOBJECTS and select Edit Condition.
#ifdef MACOBJECTS
int jklm;
#endif
Condition
The name of the condition variable.
Value
The value of the condition. Typical values are 0 (zero) to indicate "False", or 1 to indicate "True". However, you
can give the variable any value. If you leave the value empty, then Source Insight will ignore conditional pre-
processor directives that refer to this variable.
Set False
Click this to set the Value field to 0 (zero).
Set True
Click this to set the Value field to 1.
Ignore
Click this to empty the Value field. When the Value field is empty, Source Insight assumes you don't want to
specify the value of the condition variable. If you don't specify a value, then preprocessor statements like #if
are ignored if they refer to this variable. This is the default case for any conditional variables encountered.
Scan Files
Click this button to scan your project files to determine what preprocessor variables are defined, along with
their values. The results are put into either the global, or project condition list, depending on which one is
selected in the Edit Condition Set option.
Edit List
Click this to go to the Conditional Parsing List dialog box, which displays all the defined conditions. The list
you get to edit depends on which one is selected in the Edit Condition Set option. See “Conditional Parsing
List” on page 177.
End of Line
The End of Line command moves the insertion point to the end of the current line.
End of Selection
The End of Selection command moves the insertion point to the end of an extended selection. If the current
selection is not extended, this command does nothing.
Exit
The Exit command exits the Source Insight program. Source Insight will ask you if you want to save each file
that has been changed but not saved.
When Source Insight exits, it saves the current workspace file, so you may resume your session when you run
Source Insight the next time.
Caution: Do not alter the files that Source Insight had open before you run Source Insight a second time to recover your
changes. Source Insight's recovery system relies on the original files being left unchanged.
Expand
Expands the current hidden block of source code.
Expand All
Expands all collapsed source code blocks. Each function and class will show with a corresponding outline
button you can click to collapse them.
Expand Special
Used inside tree lists, this expands the selected item a specified number of tree levels.
Destination Folder
Enter the path to the directory where the HTML files will be output.
File Compare
The File Compare window shows differences between two files. This is a fancy version of the diff tool.
The window is divided into three parts: The left and right files, plus a difference list on the left side. By
default, the File Compare window is grouped with the Directory Compare window in a tabbed panel.
Toolbar
1. Compare Directory - switches to the Directory Compare window.
2. Refresh - Re-examines files and refreshes the window.
3. Show line numbers
4. Lock the window
5. Previous Difference (Ctrl+Up) / Next Difference (Ctrl+Down) - selects the previous or next differ-
ence in the files.
6. Copy selected lines left (Alt+Left) or right (Alt+Right) - the selected block of lines will be copied to
the other file. This can be undone. This type of edit is disabled by default for safety, but you will be
prompted to enable it.
7. Undo (Ctrl+Z) and Redo (Ctrl+Shift+Z) the lines that were copied.
8. Open new files to compare (Ctrl+O)
9. File Compare Window Options (Ctrl+Q) - opens the options window. See “File Compare Window
Options” on page 207.
Right-Click Menu
• Edit File (Ctrl+E) - Opens the file you clicked on in a regular source file window so that you can edit it.
This is also useful to open and jump to the highlighted section in the file so you can use regular brows-
ing and navigation commands of a source file window.
• Search (Ctrl+F) and Search Forward - Searches within the file you clicked on.
• Copy to Clipboard (Ctrl+C) - Copies the selected difference block to the clipboard. You must first
select with the mouse on a highlighted difference block.
• Mono Font View - Switches to mono font view. See “Mono Font View” on page 263.
• Overview- Toggles the Overview scroller.
• Vertical Scrollbar - Toggles the vertical scrollbar.
• Nesting Lines - Toggles showing code block nesting lines.
• Show Difference List - Shows and hides the difference list that appears on the left side of the File
Compare window.
Difference List
The Difference List appears on the left side. It shows a list of difference blocks in the file, and shows what
symbols the differences are contained within. The symbols are the ones defined in the left hand file. You can
show or hide the difference list by right-clicking on it and selecting Difference List.
Show Overview
Shows the Overview scroller control on the right edge of each file window.
Allow edits
Enables the "Copy Line Left" and "Copy Line Right" commands, which copy whole line difference blocks to
either the left or right file. This option is disabled by default for safety.
Scaling
Sets the display scaling of the File Compare windows. You can also hold down Ctrl and use the mouse wheel
to affect the scaling.
Diff Command....
Sets the external diff command that performs the diff operation. Source Insight comes with its own sidiff.exe
tool that performs the diff operation. You can substitute your own tool as long as its output is compatible
with Unix diff tools.
File Options
This command activates the File page of the Preferences dialog box. It allows you to set file loading and sav-
ing options.
Sharing
Enable this to allow other programs to modify files while they are open in Source Insight. In other words, a
file that is open in Source Insight can be written over by another program.
Disable this to give Source Insight exclusive write access to the files. Files will still be opened in read-only
mode, except during Save operations. However, other programs will not be able to open the same files for
writing.
Note: We recommend that you enable this option, so that you are aware of possibly overwriting important changes to
files.
Note: This option is not recommended, as you may accidentally write over valuable files that are read-only for a good
reason. This option may be of use if your source control system will respect a read/write file as "checked out".
Thus, you can edit and save files before you check them out.
Other Options
Default encoding
Sets the default character encoding Source Insight uses when opening files, and when saving new files. The
default is UTF-8 (Unicode). See “File Encodings” on page 125.
To set options, click the Options button. See “File Search Bar Options” on page 212.
Case sensitive
If enabled, the match is case sensitive.
Regular Expressions
Use this to enable regular expression, and to select the regular expression syntax type.
File Types
A file type is a file classification that is defined in the File Type Options dialog. Each file's name determines its
file type by using the wildcards in the File Filter field. The file type specifies display options, editing options,
and the language used to parse the file.
For example, the "C/C++ Source File" type applies to files that match the *.cpp wildcard pattern, and the file
type specifies that the "C/C++ Language" is used to parse the file for symbolic information.
See “File Types” on page 72.
File Type
This pull-down list contains a list of all the file types you have defined so far. When you select a file type from
this list, the other text boxes in the dialog box are updated to reflect the properties of that file type. The first
entry in the list is always the Default file type, which you may modify, but not remove.
When the File Type Options dialog box first comes up, the file type of the current file is automatically selected
here.
Add Type
Click this button to add a new file type. You will be prompted for the file type name.
Remove Type
Deletes the selected file type. This action is not undo-able.
Auto Indent…
Click this to change the Auto Indent settings for this file type. See “Auto Indenting” on page 219.
File Filter
This text box should contain a delimited list of file name specifications. The entries in the list can be delim-
ited with a space, a semi-colon, or a comma. Each entry can be either an unambiguous file name, or an
ambiguous wildcard file specification. The entries should not contain a drive letter or a full path that includes
backslashes.
For example,
*.c;*.h
Tip: Files are matched to File Types using wildcard filters.
Given a file name, Source Insight will identify the file's file type by searching all defined file types looking for a
match on a file specification in the File Filter text box. In effect, Source Insight makes two passes through the
entire set file type records to determine a file's file type.
1. First, it tries to find an exact match on the file name in all the File Filter lists.
2. If no exact match is found, it tries to find a wildcard match in all the File Filter lists.
3. If still no match is found, Source Insight assumes the file's type is the Default file type.
This means that you can treat some individual files in a special way. For example, "*.inc" is normally consid-
ered an Assembly File type, but let's say you have a file called "cmd.inc" that you want to have the C Source
File type. In the C Source file type's File Filter text box, you would include "cmd.inc":
*.c;*.h;cmd.inc
If you include a simple * as the file filter for a file type, then it will become the default catchall type, instead of
the "Default" file type. The catchall will only apply if the file does not already match any other file type.
You can control how Source Insight computes the fixed width of spaces by clicking the Spacing button in the
Preferences: Display dialog box.
For more information, see “Character Spacing Options” on page 198.
Screen Fonts
Click this button to select a font to use for displaying the file on the screen. The name of the currently
selected font is displayed to the right of the button. The screen font selected here becomes the default font
for this file type. Style properties will also apply on top of this font. 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.
Printer Fonts
Click this button to select a font to use for printing the file. The name of the currently selected font is dis-
played to the right of the button. This setting only has an effect if the Emulate screen fonts when printing
option (described above) is turned off.
Parsing Group
Language list
This pull-down list contains a list of all the languages defined in Source Insight. Select from this list to specify
how Source Insight should parse and display the current file type. For example, to parse the document as a
Java source file, select "Java Language" from the list. You can also select "None" to use no parser.
To add a new custom language, select the item <New Language>.
The language selected here determines the syntax formatting, as well as how symbol declarations, such as
functions and classes are parsed in the file.
Language…
Click this button to open the Language Options dialog box. From there, you can add a new language, and edit
the properties of a language. For example, you can edit the syntax formatting keyword list that is associated
with each language. Each language type has its own keyword list. See “Language Options” on page 241.
Custom Pattern
This text box should contain a valid regular expression with one group in it. The group describes what part of
the matching pattern is assumed the symbol tag. The symbol parsed by using this pattern is given the type
indicated by the Custom Tag Type. If the Custom Tag Type is set to "No Custom Parser", then this text box is
ignored.
Using a custom pattern that allows you to parse some symbols out of files for which Source Insight has no
built-in knowledge. For example, the following string parses sections out of .INI files like WIN.INI.
^\[\(.*\)\]
You can define a new file type named "INI File" that uses this custom parsing pattern. Now, when you open a
file like WIN.INI, you can jump to any of the section names or see them all in the symbol window.
Word Wrap
If checked then Source Insight will automatically wrap words onto the next line when the insertion point
moves past the margin width. This only applies while you are typing new text. If not checked then Source
Insight will not do any automatic wrapping of text.
Allow auto-complete
If enabled, then symbolic auto-completion is allowed for the file type if auto-completion is enabled globally
in the Options > Preferences: Typing dialog box.
Tab Width
The width of a tab character in character spaces.
Margin Width
The width of text in characters spaces before automatic word wrapping will occur
Visible Tabs
If checked then Source Insight will display a special symbol where ever a tab characters is, instead of just dis-
playing white space.
Visible Spaces
If checked then Source Insight will display a special symbol where ever a space characters is, instead of just
displaying white space.
Symbol Window
If enabled, then files with this file type will have a Symbol Window attached at the left side of their source
windows. See “Symbol Windows ” on page 30.
The Symbol Window command on the right-click source file menu toggles this setting.
Use Overview
If enabled, then an Overview scroller will be displayed in the file's source window. at the far right edge. See
“The Overview Scroller” on page 27.
The Overview command on the right-click source file menu toggles this setting.
To insert the quoted string "Hello World", you would type this:
If you just inserted an empty pair of parentheses, brackets, or quotes, and want to delete them, press Back-
space. Both characters will be deleted. For example:
If you type an open parenthesis just before another open parentheses, then the parenthesized block that fol-
lows will be surrounded with parentheses. For example:
Auto Indenting
The auto-indenting feature controls the level of indentation as you type new text. Source Insight supports
Simple and Smart types of auto-indentation. Not all languages support the Smart level.
You can also reformat exiting source code using Tools > Reformat Source Code. See “Reformat Source Code
Options” on page 289.
Folder Options
This command activates the Folders page of the Preferences dialog box. It allows you to specify the location
of various data folders used by Source Insight. These options are saved as part of the current configuration.
You may want to change this folder location if you prefer to have your personal "Documents" folder on a net-
work drive. Source Insight can become slow if it has to constantly access data across the network. In that
case, you should change the folder location to a folder somewhere on you local machine.
Settings Folder
This is the folder that will contain you configuration files, which has your customizations.
Projects Folder
This is folder that will contain your project data files. Each project will have a sub folder within this folder.
Clips Folder
This is the folder that will contain clips, which are accessed from the Clips Window.
FTP Browser
This is an simple FTP client window that allows you to connect to a remove host, and upload and download
files. You can browse to a file on a remote host, open it, edit it, and save it back to the remote host.
Toolbar
1. Connect to Host - Click this to connect to a host. The FTP Site list window will appear so you can pick
the host to connect to.
2. Disconnect - Disconnects from the host.
3. Refresh List - Refreshes the file list in the FTP Browser.
4. Download File - Downloads the selected file from the remote host to your local machine. A "Save As"
dialog box will appear so you can indicate where to save the file.
5. Upload File - Uploads a file from your machine to the remote host. A dialog box will appear so you
can select the file to upload.
6. FTP Browser Options - Edits the settings for the FTP Browser panel. You can set options and edit the
list of remote hosts. See “FTP Browser Options” on page 222.
Site List...
Edits the list of FTP Sites (hosts). See “FTP Site List” on page 223.
To add a site, click the Add button. To edit an existing site, select the site and click the Edit button. The Edit
FTP Site Properties dialog will appear. See “Edit FTP Site Properties” on page 224.
Site Name
The user-friendly name you can give to the remote site. For example, "Company Server".
Host Name
The FTP host address of the server. Typically something like "ftp.mysite.com", or an IP address.
User name
The FTP user name used to log on to the server.
Password
The FTP password for the user.
Initial directory
The directory on the remote server that will become the current working directory after the connection.
Port number
The TCP port number to use to connect to the remote host. The default is port 21.
Passive mode
If selected, then the Passive mode is used. Passive mode is best used when you are behind a firewall. In Pas-
sive mode, the remote server tells Source Insight what data port to connect to, instead of Source Insight
opening a data port on your machine.
If not selected, then the Active mode is used. In Active mode, Source Insight needs to open a data port for the
remote server to connect to. This is usually not a good practice for security reasons, and will usually not work
with firewalls.
Function Down
The Function Down command moves the insertion point to the next function or method defined in the cur-
rent file.
Function Up
The Function Up command moves the insertion point to the previous function or method defined in the cur-
rent file.
General Options
This command activates the General page of the Preferences dialog box. It allows you to change miscella-
neous Source Insight options. These options are part of the current configuration.
Note: If your computer is running on battery power, then Source Insight significantly reduces its background process-
ing after a few seconds of idle time to allow your system to enter a low-power state and use less battery power.
Background Tasks
Source Insight performs a number of tasks in the background, including the following:
• It parses files and updates the Symbol Window contents for all open source windows.
• It checks for finished Custom Commands.
• If Background Synchronization is enabled, then it synchronizes all the files in the project, possibly add-
ing new ones in the process.
• It synchronizes the Context Window with the current text selection.
• It synchronizes the Relation Windows with the current text selection.
• It updates the File Compare window if one of the files has changed.
• It checks for and reloads open files that are modified outside of Source Insight by other programs.
Usually there is nothing to do, in which case Source Insight sleeps and uses little or no processor cycles.
Source Tips
Sets the level of information provided by pop-up source tip windows. Source tip windows appear when you
hover the mouse cursor over a symbol identifier for a few seconds.
Synchronize on start-up
If enabled and background synchronization is turned on, then Source Insight will check file time-stamps right
away every time you start Source Insight or open a new project. When files are found to be out of date with
respect to the project, Source Insight marks the files for re-synchronizing. Later, the files will be rescanned
and synchronized in the background.
NNN specifies how often the project files should be examined to determine if files need re-synchronizing.
When this period expires, Source Insight checks the file time-stamps and begins the synchronization process
in background.
Logging...
Click this to edit Source Insight's application logging options. See “Logging Options” on page 255.
Use Defaults...
Click this to reset all the configuration settings to factory defaults. Your current settings will be saved in a
backup file. See “Resetting the Configuration to Defaults” on page 143.
The Relation window can show call trees, call reference trees, class trees and other things. An alternative to
use the Generate Call Tree command directly is to simply keep the Relation window open and un-locked, and
just put your cursor on a function in your source code. See “Relation Window” on page 306.
Go Back
The Go Back command moves the insertion point to its previous location. Source Insight keeps a selection
history, which is a circular list of the last 100 positions you've visited. The selection history is global to all
open files, not just the current file.
The Go Back and Go Forward commands function like the navigation buttons in a web browser.
Go Back Toggle
The Go Back Toggle command toggles between running the Go Back command and the Go Forward com-
mand. Using Go Back Toggle repeatedly will toggle you between your last two positions.
Go Forward
The Go Forward command moves the insertion point to the next location in the selection history, which is a
circular list of the last 100 positions you've visited. See the Go Back command for more details.
The Go Back and Go Forward commands function like the navigation buttons in a web browser.
Go To First Link
The Go To First Link command locates the first source link and does the following:
1. It selects the link line in the link source file.
2. It selects the link line in the link target file.
3. It ensures both files are visible on the screen in windows. If the current window was maximized
when this command was used, then only the link target file will be made visible.
The Go To Next Link and Go To Previous Link commands do the same thing, except with the next and previ-
ous source link, respectively.
Go To Line
The Go To Line command allows you to type a line number and position the insertion point on that line.
Note: You can also type a line number into the Bookmark window to go to a line within the current file.
Go to Line
Type the line number here.
OK
Click to go to the line number. If you type a line number beyond the end of the file, Source Insight positions to
the last line in the file.
Cancel
Click to cancel the Go To Line command.
Go To Next Change
Moves the cursor to the next block of lines that were edited. It moves the cursor to the next set of change
marks.
Go To Previous Change
Moves the cursor to the previous block of lines that were edited. It moves the cursor to the last set of change
marks.
Go To Next Link
The Go To Next Link command behaves the same as the Go To First Link command, except the next link is
used. See Also: Go To First Link command.
Go To Previous Link
The Go To Previous Link command behaves the same as the Go To Next Link command, except the previous
link is used. See Also: Go To First Link command.
Help
The Help command brings up help on Source Insight. You can also press F1 while a dialog box is up and
Source Insight will display help on the current command.
Help Mode
The Help Mode command turns on the help mode. When a command is invoked while the help mode is on,
Source Insight displays help on the command and turns off the help mode, instead of running the command.
You can cancel the help mode by running the Help Mode command again.
For example, to get help on the File > Open command, type Ctrl+F1 to turn on the help mode. A message will
appear in the status bar to indicate that help mode is active. Now go to the File menu and select the Open
command. A help window will open and display help on the Open command.
You can also press F1 while a dialog box is up and Source Insight will display help on the current command.
Highlight Word
Toggles word-highlighting for the word under the cursor in all source windows. This is like using a highlighter
pen on paper. If you select a word, and use the Highlight Word command, then anywhere that word appears
in your source, it will appear highlighted.
By default, the highlight appears like bold black text with a bright yellow background. However, you can set
the highlight effect yourself by editing the Highlight style. The Style Properties command is used to edit
styles.
Incremental Search
The Increment Search and Incremental Search Backward commands invoke the incremental search mode.
By default, F12 is the Incremental Search command, and Shift+F12 is Incremental Search Backwards.
Once in incremental search mode, Source Insight will start finding matches as you type characters, starting at
the current cursor position. As you type more characters, the search will become more specific. The charac-
ters you type will appear at the bottom in the status bar.
You can exit the incremental search mode with any command key (such as an arrow key) or by pressing Esc. If
you want to search again, just type F12 twice - it will load the old pattern and find again.
HTML Help
Looks up the currently selected word in the HTML Help file. The HTML Help file is the one specified in the
Setup HTML Help command. See “Setup HTML Help” on page 335.
Note: Import projects have an "_import_" prefix in their name. You can open an import project by holding down CTRL
and selecting Project > Open Project. The project list will contains all your projects, plus the import projects.
Library list
This is the import library list. It is a list of the external libraries currently imported. Source Insight searches
libraries in the order they appear in this list. You can use the Move Up or Move Down buttons to rearrange the
list.
Add...
Adds a new external library to the list. The "Add Library Symbols" dialog will appear.
Delete
Deletes the selected library from the import list. You will also be prompted to remove the corresponding
Source Insight project that holds the symbols.
Once you delete a library from the import list, Source Insight will no longer search for symbols in it.
Properties...
Displays information about the selected library, such as what file it was imported from.
When you import a file or set of files, a new import project is created to hold the symbols, and the project is
added to the import library list.
Indent Left
The Indent Left command out-dents the lines intersecting with the current selection to the left by the size of
one tab stop. Lines that begin with # are not indented.
Indent Right
The Indent Right command indents the lines intersecting with the current selection to the right by the size of
one tab stop. Lines that begin with # are not indented. Source Insight indents lines to the right by inserting a
tab character. If you have the "Expand tabs to spaces" option on for the current file type, then spaces equiva-
lent to a tab stop are inserted instead of a tab character.
Insert ASCII
The Insert ASCII command inserts a character that you specify with its ASCII code.
Radix
Selects the input radix of the character code you typed. If Auto is selected, then the input radix is determined
from the text you type. For example, if you type 0x20, then the radix is assumed to be Hex, and ASCII 32 is
inserted.
Character Code
This is the ASCII code of the character you want to insert.
Insert File
The Insert File command pastes the text of another file into the current selection.
File Name
The name of the file to insert. You may also type a series of wildcard specifications and click the Insert button
and Source Insight will replace the file List contents with the results of wildcard expansion. The wildcards are
expanded in the current directory.
File list
If the Project Wide option is enabled, then this list displays all files in the current project. If disabled, then this
list displays all the files in the current working directory. The current directory path is displayed at the top of
the list box.
Insert
Click Insert to insert the contents of the file in the File Name text box. If the File Name text box contains one or
more wildcard specifications, then Source Insight will replace the File List contents with the results of the
expansion. The wildcards are expanded in the current directory.
Show Dirs
Click this button to toggle the list box contents between showing file names, and showing only subdirectory
names.
Browse
Click this button to bring up the standard Windows Open dialog box, which allows you to browse around
your disks.
Project Wide
If enabled, the file List will show all the files that have been added to the current project. If not enabled, the
file List will show files in the current directory only. This option is always unchecked if no project is open.
Insert GUID
Generates a new GUID (Globally-Unique-Identifier) and inserts it into the source file.
Insert Line
The Insert Line command inserts a new, empty line before the line the selection is on. The cursor does not
have to be at the beginning or end of the line.
If Auto Indent is turned on, then the new line will be indented even with the line below it.
Join Lines
The Join Lines command joins the line the insertion point is on, and the next line, so that it forms one single
line. If the selection is extended, then all the lines intersecting with the selection are joined.
Jump To Caller
Jumps to the caller of the selected function, if any. For example, if you put the cursor on a function name and
use Jump To Caller, then you will jump to the function that calls it. If more then one function calls it, you will
see a list from which you may pick.
Jump To Definition
The Jump To Definition command takes the symbol from the first word in the current selection and jumps to
its definition. The Go Back and Go Forward commands are useful for navigating back and forth between all
your jumping spots.
To use this command:
1. Select within the symbol name as it appears in a source file.
2. Type Alt+= to jump to the actual symbol definition.
Mouse Shortcut
Hold down Ctrl and left click with the mouse on a symbol name to jump to its definition.
Jump To Link
Moves to the other end of the source link at the current line. See “Go To First Link” on page 229.
Jump To Prototype
Jumps to the declaration of the selected function's prototype. This only works if the selected symbol is a
function.
Key Assignments
The Key Assignments command allows you to assign or reassign keystroke combinations to commands. The
mouse buttons can also be assigned to commands. The key assignments are part of the current configura-
tion.
Command
You can type into this text box to narrow down the command list, so that you can find the command you
want easily. With name fragment matching, you can simply type a word contained within any command
name.
Command list
Lists all the Source Insight commands, including macros and custom commands that you've defined. When
you select a command here, the keystrokes list is loaded with all the keystrokes currently assigned to the
selected command.
Keystrokes list
Lists all the keystrokes assigned to the selected command. Select a keystroke here before clicking the Delete
button when deleting it.
OK
Click this to record the new key assignments in the current configuration.
Cancel
Click this to cancel the command. The current configuration will not be affected by any changes in the dialog
box so far.
Delete Assignment
Click to remove the assignment of the keystroke selected in the Keystrokes list from the command selected
in the Command List.
Run
Click to run the selected command. This also records any changes you have made.
Reset
Click to reset the key assignments to their default, factory settings. Source Insight will ask you if you are sure
you want to do this.
List
Click to create a key assignments list file. This also records any changes you have made. The list file is just a
text file that contains a list of commands, and their key assignments.
Menu
Click Menu to record the new key assignments in the current configuration, and then run the Menu Assign-
ments command. See “Menu Assignments” on page 262.
If you want those keys to function normally by just inserting the character on the key top, then you need to
un-assign those keys from the commands.
Use the Options > Key Assignments dialog box to find those commands and delete the key assignments for
each of them. When the key assignments are removed from those keys, they will function normally.
To Assign Keystrokes
You can add any combination of Alt, Ctrl, and Shift key modifiers with any other key, including mouse but-
tons.
To assign a new keystroke combination to a command:
1. Select the command in the Command list.
2. Click the Assign New Key button.
3. Type the keystroke(s) that you want to assign. Pressing Esc cancels the assign procedure. If the key-
stroke you typed is already assigned to a different command, Source Insight will ask you if you want
to re-assign it.
Language Options
This command activates the Languages page of the Preferences dialog box. It allows you to edit language-
specific options, such as the language keyword list.
Source Insight supports two types of languages: Built-in and Custom. You can alter a few options for built-in
languages. For custom languages, you can control all the parameters for a generic language.
Language
This list contains all the installed languages. Custom Languages are marked with a red asterisk in the icon.
You associate a language with a particular file type with the File Type Options command. See “File Type
Options” on page 213.
Add…
Click this button to add a new custom language. See “Language Properties” on page 245.
Delete…
Click this to delete the selected custom language. Only custom languages can be deleted. The built-in lan-
guages cannot be deleted.
Import…
Click this to import a custom language into the list from a custom language file. A custom language file (.CLF)
contains all the properties of a single custom language.
Export…
Click this to export the selected custom language to a custom language file (.CLF). A custom language file
contains all the properties of a single custom language. You can export a custom language so that other peo-
ple can import the language into their Source Insight configurations.
Properties…
Click this button to open the Language Properties dialog box. Use this to control custom languages proper-
ties. See “Language Properties” on page 245.
Keywords
Click this button to edit the keyword list associated with the selected language type. The Language Keywords
dialog box will appear.
File Types…
Opens the File Type Options dialog box.
Special…
Displays options that are specific to the selected language. Not all languages have special options.
Global Conditions…
Click to edit the global condition set. Global conditions are defined for all projects. The total set of conditions
defined for any given project is a combination of both the project-specific, and the global condition sets. The
project-specific conditions will override global conditions with the same name. See “Edit Condition” on
page 201.
C/C++ Options
Java Options
Language Properties
This command displays the properties of the currently selected language. The Language Properties dialog
box appears when you click the Properties button in the Preferences: Language dialog box.
Source Insight supports two types of languages: Built-in and Custom. You can alter a few options for built-in
languages. For custom languages, you can control all the parameters for a generic language.
Language Info
The Info page is used to edit the name of the language, and a comment. Clicking the Keywords… button
opens the Language Keywords dialog box.
Uses C preprocessor
If enabled, then Source Insight will recognize #if and #ifdef preprocessor directives.
Detect numbers
If enabled, then numbers found in the text are formatted with the "Number" style. The check boxes following
this enable special number formats for hex and octal numbers.
Add…
Click this button to add a new range element. The Range Definition dialog box will appear. See “Range Defini-
tion” on page 247.
Delete
Deletes the selected range element.
Edit…
Opens the Range Definition dialog box so that you can edit the range element's properties. See “Range Defi-
nition” on page 247.
Delete All
Deletes all range elements.
Range Definition
The Range Definition dialog box appears when you add a new range element, or edit a range element in the
Language Properties: Comments and Ranges dialog box. It controls all the properties of a range. A range defi-
nition specifies how comments and other multi-line range elements are parsed. A quoted string is an exam-
ple of a non-comment multi-line range element.
Type of range
Select the type of range element from this list. There are two types of range elements:
• Line The range starts with a delimiter, and extends to the end of the line. It cannot span more than a
single line.
• Multiline The range starts with a delimiter, and ends with another delimiter. The range can span more
than single line, but it can also be contained within a single line. The starting and ending delimiter can
be the same (such as a quote).
The list also contains presets for single and double quoted string ranges, and some comment styles. When
you select one of the presets, the parameters for the preset are loaded into the other text boxes in the dialog
box.
Note: The style is applied to the whole range. The style overrides any other automatically applied style, such as "Ref-
erence To…" styles.
specifying a Multiline range, the beginning and ending delimiters can be the same. This would be the case for
a quoted string.
Escape sequence
If either the Begin or End delimiter is preceded by this escape sequence, then the delimiter is ignored. For
example, you might specify backslash \ as an escape character in a quoted string so that you can embed
quote characters inside the string like this: "a string with \"embedded\" quotes".
Allow nesting
This applies only if a Multiline range is specified. If this option is turned on, then the range can be nested. If
the Begin and End delimiters are the same, nesting is not allowed because it doesn't make any sense.
Columns Group
The columns group allows you to control if the range element should be sensitive to where on the line it
occurs.
Custom Parsing
The Custom Parsing page is where you can type a set of regular expressions to perform simple parsing opera-
tions on the language source files.
Expressions
This lists each parsing expression and the type of symbol it yields. When Source Insight parses a file, all the
expressions are applied to the whole file.
Add…
Click this button to add a new parsing expression to the list. See “Custom Parsing Expression” on page 251.
Delete
Click this to delete the selected expression.
Edit…
Click this to edit the expression. See “Custom Parsing Expression” on page 251.
Delete All
Click this to delete all the expressions from the list.
Layout Toolbar
Shows and hides the Layout toolbar within the main toolbar.
Line Numbers
This command toggles the display of line numbers. The line numbers appear at the left of each line. They are
displayed in the Line Number style. You can edit the style using the Style Properties command.
Link Window
The Link Window command links the current window to another window so that they scroll together. This
command lets you specify what window is linked.
Once you link the current window to another window, scrolling the current window will scroll the linked win-
dow.
If the Two Way check box is on, then the windows are linked together so that scrolling either of them will
scroll the other. However, if the check box is off, then this is a one-way link. Scrolling the linked window will
not scroll the other one.
Linkage Result
Link A to B. Window A has a link to window B. Scrolling win-
dow A will cause windows A and B to scroll, but
not the other way around.
Link A to B to C Windows may be linked to windows that are in
turn linked to other windows. Scrolling window
A, will cause all windows to scroll. Scrolling win-
dow B will scroll B and C.
Window links can even be circular. In other words, a window may be indirectly linked to itself. This is some-
times useful to get all the linked windows to scroll; regardless of what window you actually caused to scroll.
Another way to get all windows to scroll is to use the Link All Windows command to turn on the Link All Win-
dows mode, or just turn on the Two Way check box.
Line Window To
This list contains all windows, other than the current window. Select the window you want to link to here.
Select <none> if you want to unlink the window.
Two Way
Turn this on to link both windows so that scrolling either of them will scroll the other. Turn this off to only
perform a one-way link.
Load Configuration
The Load Configuration command loads a new group of program settings from a configuration file. A configu-
ration file contains your customizations and optional settings. You can load the whole configuration file, or
just part of it.
See “Customized Settings and Configurations” on page 138.
The Load Configuration command will open a configuration file and load the settings. The configuration file
may only contain certain parts. Before it loads the settings, you will see a list of the parts contained in the file.
Check mark the items you want to load.
You can save a partial configuration file using the Options > Save Configuration command. For instance, you
can save just the key maps. When you load a configuration file that contains a partial configuration, only the
parts that exist in the file are loaded. The rest is unchanged. By loading and saving partial configurations, you
can mix and match some of the configuration parts. See: “Save Configuration” on page 320.
Load File
The Load File command opens a file to edit. It opens a dialog box containing a list of all files in the project,
regardless of directory.
You can also open files by using the Open command, or by dragging files from Windows Explorer and drop-
ping them on the Source Insight window.
File Name
Type part of the name of the file you want to open. You may also type a series of wildcard specifications and
click the Open button, and Source Insight will replace the File list contents with the results of wildcard expan-
sion. The wildcards are expanded in the current directory.
As you type in this text box, partial matching occurs in the file list.
File list
If the Project Wide option is on, then this list displays all files in the current project, regardless of directory.
If the Project Wide option is off, then this list displays all the files in the current working directory. The current
directory path is displayed above the list box. The files shown in the current directory are expanded from the
wildcard strings specified in the File Type Options dialog box for all file types.
Open
Click this to open the file selected in the file list. If nothing is currently selected in the file list, then Source
Insight opens the file named in the File Name text box. If the File Name text box contains one or more wild-
card specifications, then Source Insight will replace the file list with the results of the expansion. If the Project
Wide option is on, the wildcards are expanded over the whole list of files in the current project; otherwise,
the wildcards are expanded in the current directory. If the file specified does not exist, Source Insight will
allow you to create a new file with that name.
Select All
Click this to select all the files listed in the file list.
Show Dirs
Click this button to toggle the list box contents between showing file names, and showing subdirectory
names.
Project Wide
If enabled, the file list will show all the files that have been added to the current project, regardless of direc-
tory. If not enabled, the file list will show files in the current directory only. This option is always disabled if
no project is open.
Browse
Click this button to bring up the standard system Open dialog box, which allows you to browse around your
disks.
Load Layout
This command loads a layout file, which contains window arrangements. This makes it easy to transition
between different tasks that require different window arrangements.
A layout contains the following:
1. The size and position of the Source Insight application window.
2. The size and position of each panel window. A panel window is either floating or docked.
3. The properties and settings for each panel window.
See “Saving Window Arrangements with Layouts” on page 146.
Each of the above commands loads from a layout file named "layout_a.xml", "layout_b.xml", etc. These are
the layout files created when you use the Save Layout command and select the quick layouts A through D.
See “Save Layout” on page 321.
Logging Options
This dialog sets options for Source Insight's application logging. Source Insight can maintain a log file that is
useful for debugging issues with Source Insight.
Checking Level
This option is only available in special "debugging" builds of Source Insight. This specifies the amount of
internal checking that is performed.
Lookup References
The Lookup References command searches the current project for references to a selected symbol. For exam-
ple, click inside "BeginPaint", run the Lookup References command, and Source Insight will open a Search
Results window, which lists all the places that reference "BeginPaint" in your project.
Source Insight uses its symbol indexes to make the searching fast.
References can be found in all source code text, including comments, and potentially inactive #ifdef
branches. However, you can control whether these places are searched or not.
Note: The Search Project command is the same as Lookup References, but with different option state. See “Search
Project” on page 329.
Find References To
Type the symbol name you want to locate. The word under the cursor is automatically loaded into this text
box. Source Insight will use the context of the cursor position to determine the exact symbol instance you
want. If you invoked Lookup References from a symbol dialog box or window, then Source Insight keeps the
exact symbol references along with this text box.
Typically, you would type the name of an identifier in your program, however you can type any string here
and a project-wide search will be performed. The search is very fast if you type a single word only.
Search In
This drop-down list contains a list of file types. You can use this list to restrict the search to only a particular
type of file, or just the current file. If the Project Window is visible, then you can also use this list to specify the
files selected in the Project Window.
Search Method
You can pick the search method to use from this list. There are four different searching methods available:
• Simple String
• Regular Expression interprets the pattern as a regular expression.
• Keyword Expression similar to an Internet search query.
• Lookup Reference searches for symbol references.
Lines of Context
This only applies if you selected the Keyword Expression search method. This specifies how closely, in num-
ber of lines, the keywords must occur in order to qualify as a match. See “Keyword Expressions” on page 258.
Include in Results...
Click this button to specify what information is included in the Search Results.
Search Options
Case Sensitive
Specifies whether the search is case sensitive or not.
Skip Comments
If enabled, then comments will not be searched.
and your make program or development system will recompile those files the next time you build your pro-
gram.
Keyword Expressions
A keyword expression search is similar to an Internet search engine query. Source Insight searches the proj-
ect for occurrences of a set of keywords that appear within a specified number of lines. The Lines of Context
text box indicates the maximum distance the keyword terms can be from each other to qualify as a match.
For example, if you typed "cat food", then Source Insight will search for occurrences of "cat" and "food"
within X lines of each other.
There is an implicit logical-AND operator between keywords. That is, if you type more than one keyword, the
both keywords must be present to qualify as a match. You can include other Boolean operations as well. The
following table lists the operators available:
Table 4.4: Keyword Search Operators
Operator Example Action
AND or + cat and dog Both terms must be present.
OR cat or dog Either term must be present
NOT -cat The term must not be present
or –
or !
= =Betty Case sensitive match
? "regexp" ? "^Ich" Term is a regular expression
Keyword Variations
If you enabled the Find word variations option, then Source Insight will also find different ending forms of the
keywords you specified. For example, if you specified the keyword "open", Source Insight will also find
"opens", "opened", and "opening". This has the same effect as typing this expression:
(open or opens or opening)
Word variations are applied to each keyword term. For example, if you specified:
save write
Which implies "save" and "write" must be present. With word variations enabled, this search would be equiv-
alent to:
(save or saves or saving) and (write or writes or writing)
Manage License
The Manage License dialog allows you to view your license information, enter a new serial number and acti-
vate your license, or deactivate your license. The options available in this dialog depends on the current sta-
tus of your license and whether it is a Trial or Regular license.
To Begin a Trial
Choose "Begin a Trial". After you finish filling out some basic information, Source Insight will connect to the
Source Insight licensing system and issue you a trial license. You can continue to use Source Insight for 30
days.
To Deactivate a License
If you no longer want to run Source Insight on your machine, or would rather use it on a different machine,
we recommend deactivating your license. If your license is deactivated, you can activate it again with the
same serial number on a new machine. Deactivating reduces your activation count so that you can activate it
on another machine.
Apply Theme
Applies the currently selected theme to the program. You can also double click the theme name to apply it.
Note that once you apply it, the <Current Settings> items becomes <Previous Settings>. You can still apply
the <Previous Settings> theme from the list to return to the settings that where in effect when you invoked
this dialog box.
Define
Defines a new theme by recording all the current color, font, and style settings. Once you set all the colors,
fonts, and styles they way you like them, use the Visual Themes dialog to record all the settings into a new
theme.
The Define Visual Theme dialog allows you to define a new theme, or redefine an existing theme. You can also
specify what should be included in the theme.
Delete
Deletes the selected theme.
Rename
Renames the selected theme.
Import
Imports themes from a previously saved themes file. A themes file can have any number of themes in it. Since
theme files may contain multiple themes, the Import Theme dialog allows you to pick and choose which
themes to import.
The new themes are added to the existing list. Themes with the same names will be replaced with the
imported themes.
Export
Exports the selected themes to a new themes file. You can use this to share themes with other people, or to
load into a different configuration you have saved separately.
Save To
Select the theme you want to save to. You can select an existing theme to re-define it. Or select "New Theme"
to define a new theme. If you select "New Theme" from the list, you will be prompted for a theme name.
Include In Theme
Select the components you that want to be part of the theme. When a theme is applied, only the components
that are part of it have any effect. For example, you can include just the color of the main window, but not the
styles. Or you can include only styles.
Menu Assignments
The Menu Assignments command allows you to assign or reassign commands to the menus. The menu
assignments are part of the current configuration.
Command
You can type into this text box to narrow down the command list, so that you can find the command you
want easily.
Command list
This lists all the Source Insight commands, including macros and custom commands that you've defined.
The commands are listed by category. When you select a command here, the menu it appears on, if any, is
selected in the Menu list, and the contents of that menu are loaded into the Menu Contents.
Note that there is a special command in the list called "--Menu Separator--". Insert this item on the menu to
create a separator line in the menu.
Menu list
This pull-down list contains the titles of all the top level menus. When you select a menu from here, the con-
tents of the menu are loaded into the Menu Contents. There is a menu in this listed named "Work", which
only appear on the application menu bar if you add a command to it.
Menu Contents
This lists the menu items of the menu selected in the Menu list. Select a menu item here to indicate what item
should be deleted, and where to insert new items.
OK
Click to record your menu assignment changes in the current configuration.
Cancel
Click to cancel the command. None of your changes up to this point will be saved in the current configura-
tion.
Insert
Click to insert the selected command onto the selected menu. The command is inserted just before the
selected menu item. You must select a command, a menu, and a menu item before clicking Insert.
Delete
Click to delete the selected menu item. You must select a menu item in Menu Contents before clicking Delete.
Up
Moves the selected menu item up, towards the top of the menu.
Down
Moves the selected menu item down, towards the bottom of the menu.
Run
Click to record your menu assignment changes in the current configuration, and run the selected command.
Reset
Click to reset the menus assignments to their default, factory settings. Source Insight will ask you if you are
sure you want to do this.
Keys…
Click to record the new menu assignments in the current configuration, and then switch to the Key Assign-
ments command. See “Key Assignments” on page 239.
New
The New command creates a new, unsaved file buffer. The file is not created on disk until you save it using
the Save or Save As commands.
The New command will prompt you for a file name. By default, the new file is given a name of the form
New0001.ext. The next time you use the New command, the new file name will be New0002.ext, and so on.
The extension used will be the same as the current file. The name and extension you type will determine
what file types will be in effect for that file.
When you save new files for the first time, Source Insight allows you to change their names, and asks if you
want to add them to the current project.
Another way to create a new file is to use the Open command and specify a file name that does not exist.
Source Insight will ask you if you want to create the file. Assuming you do, Source Insight will create a new
unsaved file with the name you specified.
New Clip
The New Clip command creates a new clip buffer. You will be prompted for a clip name. You should not add
extensions to the clip name. See “Clip Window” on page 170.
New Project
The New Project command creates and opens a new project. See “Projects” on page 40.
Since Source Insight allows only one project open at a time, Source Insight will ask you if it's okay to close the
current project, before proceeding.
You will be asked for a project name, where the files should be stored, and what source files you want to add
to the project.
New Window
The New Window command opens a new window on the screen. The file appearing in the current window
will appear in the new window as well.
Next File
The Next File command runs the Close command, and then runs the Open command. You will have an oppor-
tunity to save the current file if you've modified it, unless you have the Save Quietly option turned on in the
Preferences: General dialog.
Open
The File > Open command activates the Project Window and sets the focus on the text box of the Project Win-
dow. If the Project Window was not visible, it is made visible, and then hidden after you select a file to open.
You can customize what the Open command does in the Options > Preferences: Files dialog box. Instead of
activating the Project Window, you could have it bring up other dialog boxes or windows instead.
If you do not have a project open, then this command will bring up the system Open dialog box, which is a
standard system dialog box.
You can also open a file by dragging a file and dropping it onto the Source Insight application window.
Open As Encoding
This opens a new file using a specific character encoding. To use this select File > Open As Encoding. Select
the desired encoding, then click the Open button.
Encoding
You can type part of the encoding name to find it in the list.
Encoding List
This is a list of encodings supported by Source Insight. The non-Unicode encodings also list the Windows sys-
tem code page used.
Backup files are given a unique name based on the original file name. For example if the original file name is
render.c, then the backup name will be something like render(1066).c where the (1066) part is a ran-
dom value to make the file name unique in the Backup directory.
To open the Backup folder in Window Explorer, click the Show Folder button.
See “Backup Files” on page 128.
Open Project
The Open Project command allows you to open a new current project. It first closes the current project, if
any, since a Source Insight instance only allows one project open at a time. See “Projects” on page 40.
You can also open a project by dragging a project file (.siproj) from Windows Explorer onto the Source Insight
window, or specifying a project file in the Open dialog.
Project Name
Type the name, or part of the name, of the project you would like to select.
Project list
Displays a list of all the projects you have created or opened on your machine. Select the project you want to
open here. This list is simply a recording of known projects. You may have other projects that are not listed
here. To open those, click the Browse button and locate the project file.
Browse
Click this button to bring up the standard Open dialog box, which allows you to browse around your disks.
Locate a project file with a .siproj extension. Once you select a file and close the Open dialog box, the file you
selected will be loaded into the Project Name text box. Then click OK to open it.
Outline Toolbar
Shows and hides the Outlining toolbar.
Outlining Options
These options control the outlining features, which allow you to collapse and expand blocks of code.
The outlining options are displayed inside the Window Options dialog. See “Window Options” on page 370.
Overview Options
This shows or hides the Overview scroller. The Overview shows a "bird's eye" view of your source file. It's a
miniature version of your file that helps to orient you within a source file, or even within a long function. The
Overview attaches to the side of a source window, like a scroll bar.
General Options
Displays the optional settings for the Overview scroller.
Show bookmarks
Draws marks that represent the position of bookmarks in the text.
Text Scaling %
Sets the scaling percentage of the Overview text. It is typically something small, such as 10%. A settings of
100% would show the text full size as it appears in the source window.
Note: the width of the Overview can be adjusted by dragging its border with the mouse.
Colors
These set the colors of items in the Overview.
Page Down
The Page Down command scrolls the active window down by one window full, with one line of continuity.
Page Setup
The Page Setup command allows you to control the layout of text on printed pages that are printed with the
Print command.
Columns
Specifies the number of columns to print per sheet of paper. Each column will get its own page number. For
example, if you have two columns, then each sheet of paper will get two pages of source code printed on it.
This is more useful if you print in landscape mode (where the paper is wider than tall).
More…
Click this button to open the standard system Page Setup dialog box. This dialog box allows you to set paper
size, margins, and orientation (i.e. Portrait vs. Landscape). You can also change the current printer settings
from this dialog box.
Formatting Options
The formatting options control how syntax formatting is output to the printer. These options work inde-
pendently of the screen settings, which you control in the Preferences: Syntax Formatting dialog box.
Print in color
If enabled, then color is used for printing. If your printer is not a color printer, then colors will be displayed in
shades of gray. If you disable this option, then all text, regardless of on-screen color, is printed in full black or
white. However, text that is colored near a neutral gray is printed in gray.
For example, to print "Confidential" at the left margin, center the page number, and print current date at the
right margin, type:
&LConfidential&C&P&R&D
Page Up
The Page Up command scrolls the active window up by one window full, with one line of continuity.
Paren Left
The Paren Left command moves the insertion point left to the next enclosing parentheses.
Paren Right
The Paren Right command moves the insertion point right to the next enclosing parentheses.
Pattern
Contains the regular expression used to search the command output for file names and line numbers. This
text box must contain a valid regular expression that contains "groups" for the file name and the line number.
The contents of this text box are saved in the current workspace.
The Parse Source Links command is useful if you have some kind of log file that contains compiler output and
error messages. You just open the log file, and run the Parse Source Links command. A link will be setup for
each line in the log file containing an error message. “Searching and Source Links” on page 107.
Paste
The Paste command copies the contents of the clipboard to the current selection. If the current selection is
already extended, it is deleted before pasting.
Paste Line
The Paste Line command moves the insertion point to the beginning of the current line and executes the
Paste command. Cut Line, Copy Line, and Paste Line can be used together to quickly move whole lines
around in a file.
Paste Symbol
(On the Symbol Window right-click menu)
The Paste Symbol command pastes the text in the Clipboard just before the selected symbol in the Symbol
Window.
Pick Window
Manages the list of open source windows and file buffers. It also lists file buffers that are not visible in any
window.
Note: You can use the Window List panel instead of this dialog. It is a mode-less version of this dialog.
Window list
Contains a list of all open source windows, and file buffers that may be open in the "background" that do not
appear in a window. You can sort the window list by name or by recently-used order. To sort the list, click on
the header titles at the top of the list.
Activate
Brings the selected window to the front.
Close Window
Closes the selected windows.
Save
Saves the selected files.
Save As
Performs a Save As command on each selected file.
Minimize
Minimizes the selected windows.
Restore
Restores the selected windows.
Tile Horiz
Tiles the selected windows horizontally so they are generally wider than they are tall
Tile Vert
Tiles the selected windows vertically so they are generally taller than they are wide.
Play Recording
The Play Recording command plays back a command recording. Commands are recorded by using the Start
Recording command. If the recorder is on when you use the Play Recording command, then recorder is auto-
matically turned off first.
Preferences
The Preferences dialog specifies many of the program options. This multi-page dialog box contains several
tabs for various types of options, such as Display, Files, and Syntax Formatting. The settings are stored in a
configuration file.
For more specific information:
See “General Options” on page 225.
See “Typing Options” on page 364.
See “File Options” on page 208.
See “Folder Options” on page 220.
See “Language Options” on page 241.
See “Symbol Lookup Options” on page 347.
See “Display Options” on page 195.
See “Color Options” on page 172.
See “Syntax Decorations” on page 353.
See “Syntax Formatting” on page 356.
See “Searching Options” on page 329.
See “Remote Options” on page 312.
Print
The Print command prints the current file. The standard Windows Print dialog box will appear.
You can control what font is used for printing files with the File Type Options command. The File Type
Options command lets you specify what font should be used for printing and what font should be used for
the screen. Alternatively, you can tell Source Insight to emulate the screen font when printing. If you have a
TrueType font selected, then emulating that font on the printer should work just fine. If you have a raster font
selected, such as "MS San Serif" or "Courier", then printing that font on the printer may look blocky, or the
printer driver may just substitute that font with something similar.
Color Printing
If you want to print your files with syntax formatting and color, you need to make sure you have enabled
those options in the Page Setup dialog box.
Show Columns
Check the box next to the columns you would like to appear in the list.
Code Metrics
Select the type of code metrics to show in the column. The drop-down list to the right selects which code
metric value to display in the column.
Show Columns
Check the box next to the columns you would like to appear in the list.
To open a file, double click on a file in the list, or start typing the name into the text field.
To add a file to the project, you can drag files from Window Explorer onto the Project File List.
The Context Window previews the file selected in this list without needing to open the file.
Right-Click Menu
Show Columns
Check the box next to the columns you would like to appear in the list.
Code Metrics
Select the type of code metrics to show in the column. The drop-down list to the right selects which code
metric value to display in the column.
To view the Project Search Bar, select View > Project Search Bar.
To activate it so you can start typing, use Activate Project Search Bar (Alt+Shift+P)
See “Search Project” on page 329.
If you cancel or do not rebuild the projects, then Source Insight will ignore those projects and will not notify
you again for the rest of the session. If you exit Source Insight and restart it, the notice will appear again.
If you try to open a project that needs rebuilding by using Project > Open Project, Source Insight will ask if
you want to rebuild it. However, projects that are opened in the background do not cause such a user
prompt. Therefore this notice window appears when Source Insight is idle.
Background Projects
You normally have a current project open. However, Source Insight opens other projects in the background in
order to provide auto-completion, and to use syntax formatting for externally defined symbols, and to locate
user macro commands. Source Insight opens Import library projects, projects on the Project Symbol Path,
and the Base project in the background.
See “Importing Symbols from Libraries” on page 55.
See “Import External Symbols” on page 233.
See “The Project Symbol Path” on page 56.
See “The Base Project” on page 49.
Show Columns
Check the box next to the columns you would like to appear in the list.
Symbol Types
Click this button to choose or filter the types of symbols that appear in the list.
To locate a symbol quickly, type a part of the symbol name and the list will be filtered down as you type. You
can also use name fragment matching to find parts of symbol names. For example, if you type:
doc write
this will match symbol names such as DocWrite, WriteDoc, Doc::DoWrite, WriteOpenDoc, CanWriteAnyDoc,
etc. See “Name Fragment Matching Symbol Names” on page 66.
Right-Click Menu
Show Columns
Check the box next to the columns you would like to appear in the list.
Symbol Types
Click this button to choose or filter the types of symbols that appear in the list.
Project Settings
The Project Settings command allows you to set various options that govern the current project. If no project
is currently open, then the Project Settings command allows you to set the default options inherited by sub-
sequently created new projects.
The Project Settings are saved with the project data file. These settings are independent of the configuration
file.
Conditional Parsing
This controls the settings of condition compilation values.
Conditions…
Click to edit the conditions defined that are specific to the current project only. The conditions are only in
effect when the current project is open, and only for files that belong to the project. Another quick way to edit
the conditions is to use the Edit Condition command.
This option is recommended if you are using an object-oriented language primarily, so that you can find
member functions and variables without having to type in the class name too.
Index Performance
Name Fragment matching is such a useful feature, that we recommend enabling it, unless you think perfor-
mance is affected. The symptoms of too large an index are:
• Disk thrashing while building or rebuilding a large project, while little progress is being made.
• Opening or closing a project takes a long time.
• Synchronizing individual files is slow.
• The Project Symbol List (F7) is slow to come up, accompanied by a lot of disk activity. Some delay is
normal the first time you use it.
• Your project has over 2 or 3 million index entries. Obviously, this limit depends on the amount of RAM
you have.
• Your hard drive light never seems to go off, or your system pauses for a long time while the disk is
flushed.
If you experience slow-downs and you have a large project, (say over 300,000 symbols,) you should try turn-
ing off Quick browsing for symbol name fragments.
You can find out how large the database is by selecting Project > Rebuild Project and looking at the statistics
on the bottom of the dialog box. Just cancel this dialog box when you are done. If the index entries are in the
millions, then things can start to slow down. However, most modern machines should handle this size proj-
ect well.
Project Report
The Project Report command generates an output report file called <project>.RPT, which contains a list of
files and symbols in the current project.
Files
Turn on these check boxes to include the corresponding information.
Include Symbols
If enabled, then symbols will be listed under each file. If not enabled, then no symbol information will be
listed in the project report.
Line Numbers
If enabled, then the line number where the symbol is defined is listed by the symbol name.
Sort by
If Occurrence is selected, then symbols will by listed by line number. If Name is selected, then symbols will be
listed by symbol name.
Symbol Types
Click this button to indicate what types of symbols will be included.
Rebuild Project
The Rebuild Project command rebuilds the project data files. Source Insight creates the data files.
You may want to rebuild the project to get all the files re-parsed after a large change, or if you suspect the
project data is not correct.
A project may become corrupted if Source Insight was abnormally aborted without closing the project.
The Rebuild Project dialog box also lists some statistics about your project. The number of symbol database
records, symbol index entries, and files is displayed. This information is also output by the Project Report
command.
There are three methods of rebuilding the project. The last method is recommended.
Redo
The Redo command reverses the effect of the Undo command. In effect, as you edit, Source Insight makes a
list of the changes you've made to each file. The Undo command backs up through that list and the Redo
command advances through the list.
You can also use the Redo All command to reverse all the Undo actions.
Source Insight keeps Undo/Redo history for each open file independently.
Redo All
Reverse the effect of all Undo actions. This brings the file all the way back up to date with your last change. It
is equivalent to running the Redo command repeatedly until there is nothing left to Redo.
Redraw Screen
The Redraw Screen command redisplays the whole Source Insight screen.
Reform Paragraph
The Reform Paragraph command re-formats the selected paragraph of text so that all the lines in the para-
graph are as wide as possible, within the margin width for the current file type.
If you have an insertion point selection, then the enclosing paragraph is reformed. If more than one para-
graph is selected, then all the paragraphs in the selection are reformed.
If the first line of the paragraph is indented, then all subsequent lines in each paragraph will be indented by
the same amount.
A paragraph of text is assumed a series of lines, bounded by blank lines.
You can specify the margin width in the File Type Options command under the current file's file type.
For example, before running Reform Paragraph:
The quick brown
fox jumped
over the
lazy dog,
and other
mysterious sentences.
After running Reform Paragraph, the lines are made as wide a possible within the margin.
The quick brown fox jumped over the lazy dog, and other mysterious sentences.
There are several different code formatting presets, and you can save additional presets. A preset is a group
of formatting options. For example, there is a K&R preset, and a GNU preset.
Format
Click this button to format your source code using the selected preset.
Add / Delete
Click these to add or delete your own presets. The presets that are installed by default cannot be deleted.
Edit Preset...
Edits the code formatting options for the selected preset.
Import
Imports a single preset from a preset XML file.
Export
Exports the selected preset to a preset XML file.
Export All
Exports the list of presets to a preset XML file.
Restore Defaults
Restores the default presets that are installed with Source Insight.
For example:
x = 0; while (x < limit)
would be converted to:
x = 0;
while (x < limit)
Indentation Options
Indent width
This is the width in character positions of each indent level. For example, entering 4 would mean that an
indent is equivalent to 4 spaces, or 1 tab is the tab width is set to 4.
Hanging indent
Labels are indented 1 level less than the surrounding code. For example:
if (abc)
{
label1:
if (xyz)
{
label2:
x = 0;
}
}
Indent members
The members, or the contents of the body of the class or struct is indented by one level. This applies to class,
struct, enum, and unions. For example:
class MyClass
{
void func1(); // member declaration is indented 1 level
}
private:
int func2();
}
Hanging indent
Labels are indented 1 level less than the surrounding code. For example:
class MyClass
{
public:
int func1();
private:
int func2();
class InnerClass
{
public:
int func3();
}
}
Comment Options
For example:
right margin ---------------------------->|
/* some really long long long long long
long wordy wordy wordy comment that is
word wrapped at the right margin*/
Other Options
void n1_func();
}
If this box is not checked, then the formatting would look like this:
namespace N1
{
int n1_x;
void n1_func();
}
If this box is not checked, then the above code would be formatted like this:
a+b*c
a<b
a+=b
Reload As Encoding
This command reloads the current file using a specific character encoding. If you opened a file and the
encoding looks incorrect or text is garbled, then you probably need to reload it with the correct encoding.
You should do this before you make any changes to the file.
Caution: The current file is reloaded from scratch and wipes out any changes you may have made. If the file has unsaved
changes, Source Insight will confirm you want to reload it and lose your changes. If you want to keep your changes, do
NOT save the file back over itself, because that could overwrite the file with the wrong encoding and corrupt the file.
Instead, save it to a new file by selecting File > Save As Encoding, and pick the UTF-8 format. After you reload the origi-
nal file, you can compare the differences between the files and merge your changes back.
To use this command, select the desired encoding, then press the Load button reload the current file.
Encoding
You can type part of the encoding name to find it in the list.
Encoding List
This is a list of encodings supported by Source Insight. The non-Unicode encodings also list the Windows sys-
tem code page used.
Back Color
Click this to select a background color for the graph window.
Graph Layout
Selects the layout mode for the graph. You can choose either top to bottom, or left to right.
Spacing
Type a percentage that represents the scale factor of the inter-node graph spacing. A large percentage value
will make the nodes spread out more.
Node Options
Node options control the appearance of node elements in the graph.
Type
Selects the shape of nodes.
Font
Selects the font used inside of each node.
Drop Shadow
Enable this to put a drop shadow on each node.
Shaded
Uses a gradient shading effect to draw the graph nodes.
Type
Selects the style of lines that connect nodes.
• Direct Lines are drawn straight between nodes.
• Orthogonal Lines are drawn with right angle bends.
• Splined Lines are drawn as curves.
Line Color
Selects the color used for connection lines.
Thick Line
Enable this to make connection lines thicker.
Arrows
Enable this to put arrowheads on the connection lines. If the Spacing percentage is small, the arrowheads are
omitted due to the lack of inter-node space.
Relation Window
The Relation Window command shows or hides the Relation Window.
The Relation Window shows the relationship between the currently selected symbol and other things. The
Relation Window can show function call trees, class hierarchies, structure members, reference trees, and
more. It can be docked along side your source windows, and it works in the background tracking what you
are selecting and showing relationship information automatically.
See “Relation Window” on page 93.
Graph…
Click on this button to open the Relation Graph Properties dialog box. From there, you can adjust the options
for the graph view of the Relation Window.
Levels
The number of levels to expand below the root node.
View Relationship
The relationship shown depends on the type of symbol. You can specify what relationship is shown for differ-
ent symbol types. For example, you could set the relationship viewed for functions to "Calls", and the rela-
tionship viewed for classes to “Inheritance”. Thus, when you select a function, the Relation Window shows a
call tree, and when you select a class name, the Relation Window shows the class inheritance hierarchy. See
“Relationship Rules” on page 308.
Symbol Types
Click this button to view the Symbol Type Filter dialog box. This allows you to filter out specific types of sym-
bols from the Relation Window output. See “Symbol Type Filter” on page 310.
Columns Group
This group specifies what columns should appear in the outline list view. The Relation Window can be sorted
by clicking on any column header.
Relationship Rules
The relationship shown in the Relation Window depends on the type of symbol. You can specify what rela-
tionship is shown for different symbol types. For example, you could set the relationship viewed for functions
to "Calls", and the relationship viewed for classes to "Inheritance". Thus, when you select a function, the
Relation Window shows a call tree, and when you select a class name, the Relation Window shows the class
inheritance hierarchy.
Each time the Relation Window expands a symbol to show a new level, the relationship represented by the
expansion is based on the type of symbol being expanded. That means each Relation Window has the poten-
tial to show multiple relationships. For example, a class might show its contents, which consists of member
functions. Each member function might show its references.
Exclusions
This section controls what symbols are filtered out of the call tree.
Exclude Symbols…
Click this button bring up the Exclude Call Graph Symbols list. You can add specific symbols to this list. If a
symbol is in the exclusion list, then Source Insight will not expand the symbol in the call graph display.
Exclude C Macros
Check this to omit C function-like macros from the call graph. If this option is off, then function-like macros
are expanded in the call graph as though they were an actual function.
Minimum value
A symbol must have a code metric value of this or greater to be included.
Maximum value
A symbol must have a code metric value of this or less to be included. If the value is set to –1, then there is no
maximum.
Off
Select this to disable automatic symbol tracking.
Inside of comments
Select this to have the Relation Window look up symbols when the cursor is inside of comments.
Reload File
Reloads the current file from disk, losing all changes since saving. This has the same effect as closing the file
without saving, and then opening the file again. The change history and undo history are also lost.
Remove File
The Remove File command removes one or more source files from the current project. Note that the actual
files are not deleted from the disk, but only removed from the project.
Note: You can also remove files by using the Project File List window. Select the files in the list, right-click, and select
"Remove File from Project".
File Name
Contains the name of the file to be removed from the project. You can also add a wildcard and press Enter to
expand the wildcard into the file list.
File List
Contains a list of all project files in the current working directory. If you select a file from this list box, the file
name is loaded into the File Name text box.
Remove
Click this button to remove the selected file from the project. If the File Name text box contains wildcard
characters, the wildcards will be expanded and displayed in the File list box, and the dialog box will not be
closed.
Select All
Click this button to select all the files contained in the file list.
Remove Dir
Click this button to remove the selected directory contents from the project.
Show Dirs
Click this button to toggle the list contents between showing file names, and showing subdirectory names.
When the subdirectories are shown, this button changes to "Show Files".
Browse
Click this button to bring up the standard Open dialog box, which allows you to browse around your disks.
Add
Click this to go to the Add Files dialog box.
Remove Project
The Remove Project command removes an existing project. When a project is removed, all project data files
created by Source Insight are deleted. The Remove Project command will not delete your source files.
Project Name
Add the name of the project you want to remove.
Project list
Displays a list of all projects opened or created on your computer. Select the project you want to remove
here.
Since the process of creating and adding source files to a large project can be somewhat time consuming,
Source Insight confirms that you indeed want to remove the project.
Click No to cancel the Remove Project command. The project will not be removed. If the project you selected
to be removed was previously open, then it will be closed at this point.
Click Yes to confirm that you want to remove the project.
Remote Options
The Remote Options dialog box allows you to set options for how Source Insight behaves when used in a Ter-
minal Server or Remote Desktop session. In a Terminal Server session, Source Insight runs on a remote
machine, but the desktop is displayed on a local machine.
The settings you make in this dialog box only apply when you run in a Terminal Server or Remote Desktop
session.
Font Scaling
Sets the percent of overall text scaling in the program. Most text, including source code and lists, are scaled
by this percentage.
Rename
The Rename command renames the current file. The file does not have to be saved on disk. If the file is part
of the current project, the project is adjusted to reflect the new name. You may also move the file to a new
directory with this command, but you cannot move the file to a different drive.
The Rename command does not save the file.
Renumber
The Renumber command reorders numbers found in the current file, or just the current selection. If the
selection is extended when the Renumber command is used, then only the selection is processed. If the cur-
rent selection is an insertion point, then the whole file is processed. Renumber also works on a column selec-
tion.
Radix
Select a radio button in this group to specify the radix of the numbers generated by the Renumber command.
Auto
Use the radix of the original number, as determined by Source Insight.
Decimal
Use base 10.
Hex
Use base 16.
Octal
Use base 8.
Numbers
Specifies what action is to be performed on numbers found in the file. You can add values into the Start at
and Offset text boxes in base 10, 8, or 16.
Auto
Replace numbers in ascending order, beginning with the value of the first number found.
Start at
Replace numbers in ascending order, beginning with this value.
Offset
Replace numbers with the same number, plus this value.
Radix Determination
Source Insight determines the radix of a number as follows.
• If the number begins with 0x then it is assumed hexadecimal.
• If the number begins with zero and a digit, it is assumed octal.
• Otherwise, the number is assumed decimal.
Repeat Typing
The Repeat Typing command repeats the last characters you typed. For example, if you select somewhere
and type abc, then run Repeat Typing, another abc will be inserted automatically.
Replace
The Replace command performs a search & replace operation on the current file. The search & replace can be
done over the whole file, or just the current selection.
Old
Add the old pattern you want to replace in this text box. The pattern can be a regular expression.
New
Add the new pattern that should replace the old one in this text box.
Replace
Click this to begin the replacing operation.
Files
Click this button to transfer to the Replace Files command, where you can perform replacements in multiple
files.
Options Group
Case Sensitive
If enabled, Source Insight will only find matches if the case matches exactly.
Wrap Around
If enabled, the search continues at the beginning of the file when it reaches the end of the file. The search will
wrap around only once. If not enabled, the search stops when it reaches the end of the file.
Confirm Replacements
If enabled, Source Insight will confirm each replacement by prompting you.
Search Group
The Search group of options specifies the scope of the search.
Selection
Searches only the currently selected text. This check box is automatically checked if the current selection is
extended when the Replace command is invoked.
Whole File
Searches the whole file, from the first line to the last. This check box is automatically checked if the current
selection is an insertion point when the Replace command is invoked.
Nothing checked in this group means to start searching at the current selection, and continue to the end of
the file.
Replace Files
The Replace Files command searches for a specified pattern in multiple files and replaces each occurrence
with a new pattern.
Replace
Click this button to begin the replace operation.
Select All
Click this to select all the files in the file list.
Show Dirs
Click this button to toggle the file list contents between showing file names, and showing only subdirectory
names. When the subdirectories are shown, this button changes to "Show Files".
Old
Add the old pattern to be found and replaced in this text box. The pattern can be a regular expression.
New
Add the new pattern that should replace the old one in this text box.
File Name
The name of the file to search. You may also add a series of wildcard specifications and click the Replace but-
ton (or press Enter) and Source Insight will replace the file list with the results of the wildcard expansion. If
the Project Wide option is on, the wildcards are expanded over the whole list of files in the current project;
otherwise, the wildcards are expanded in the current directory.
If the Project Wide option is on, Source Insight will search the project symbol for file names added in the File
Name text box, so you don't have to include a directory specification for those files.
File list
If the Project Wide option is on, then this list displays all files in the current project.
If the Project Wide option is off, then this list displays all the files in the current working directory. The current
directory path is displayed above the file list. Source Insight shows only files for known file types in the cur-
rent directory. The file types are specified with the File Type Options command.
Options Group
Project Wide
This check box controls whether the File list shows all the files in the project, or just the files in the current
working directory.
Include Subdirectories
If this check box is checked, then any selected directories are recursively searched. This option and the Proj-
ect Wide option are mutually exclusive.
Case Sensitive
If enabled, Source Insight will only find matches if the case matches exactly
Skip Comments
If enabled, then comments will not be searched.
Restore File
The Restore File command restores the current file to its original contents, as it was when it was first opened.
Reverting will lose all changes you made since it was first opened, even if you saved the file. The file that is
saved on disk is not altered. Only the open file buffer is restored.
You should use caution with this command, since it effectively undoes any saving you performed on the file.
Note that you can use the Undo command to undo the Restore File operation.
Restore Lines
The Restore Lines command restores a block of edited lines back to their original contents. The lines will be
as they were when you first opened the file.
Restoring lines will lose those changes you made since it was first opened, even if you saved the file. The file
that is saved on disk is not altered. Only the lines in the open file buffer are restored.
The Restore Line command is undo-able. This gives you a powerful, out-of-order undo capability.
You can access the Restore Lines command quickly by right-clicking in the selection bar (left margin) area
next to a block of modified lines and choosing it from the right-click menu. You can see what lines are modi-
fied by turning on line revision marks. (See Preferences: Display command.)
Save
The Save command saves the current file to disk. The file is saved to its current name. Prior to saving, any
changes you made to the current file were only present in the unsaved version you were editing. The file on
disk never is changed until you save the file by using the Save, Save As, or Save All commands.
A file can also be saved by answering "Yes" to the "Save changes to file?" message when you try to close a
changed file.
If the file is new and has never been saved before, or the file is read-only, then the Save command runs the
Save As command instead. The Save As command allows you to specify the name of the file to be saved.
Save A Copy
Saves the current file to a new file, but does not replace or affect the current file. The newly saved file is left
open as just another file buffer. This is a handy way to duplicate a file.
Save All
The Save All command saves all files that are open and have changed since they were saved last.
Yes
Click this button to save the file.
No
Click this button to not save the file, and to continue
Cancel
Click this button to stop the Save All command.
Save As
The Save As command saves the current file to disk as the name that you specify.
Yes
Click to add the file to the current project.
No
Click to not add the file to the current project. The file will still be saved.
Save As Encoding
This command saves the current file with a specified character encoding. To use this command, select the
desired encoding, then click the Save button to save the file.
If you just opened a file and it looks like text is garbled, and it loaded with the wrong encoding, do NOT save
the file. That will overwrite the file and potentially change it incorrectly. Instead, select File > Reload As
Encoding. See “Reload As Encoding” on page 303.
Saving files using Unicode (such as UTF-8) is the best practice to avoid corruption due to incorrect decoding
or encoding going forward. For example, if you load a file encoded with one code page, and save it using a dif-
ferent code page, that could corrupt your file because some of the characters won’t map to characters in the
new code page. However, if you save using a Unicode encoding, the characters will be mapped correctly.
UTF-8 is the preferred encoding in Source Insight because there is less conversion required to open and save
files.
See “File Encodings” on page 125.
Encoding
You can type part of the encoding name to find it in the list. If you select a UTF-8 based encoding, your file will
be saved in the best format to avoid incorrect encoding or re-encoding problems. In addition, UTF-8 files load
and save faster in Source Insight.
Encoding List
This is a list of encodings supported by Source Insight. The non-Unicode encodings also list the Windows sys-
tem code page used.
Save Configuration
The Save Configuration command saves your current program customizations and settings to a new configu-
ration file. You can save the entire current configuration to a file, or just a subset of it. See “Customized Set-
tings and Configurations” on page 138.
When a configuration file is loaded that contains a configuration subset, it only affects the settings it con-
tains. For example, you could save only keyboard settings to a configuration file and name it "MyKeyboard".
When "MyKeyboard" is loaded, it will only affect the keyboard.
Configuration Sections
Check the sections of the configuration you want to save. Click the All button to check all the sections.
OK
Displays the standard Save dialog box. You can select the configuration file you want to save to with this dia-
log box.
Note: Once you load a configuration file, it will be automatically saved to the current configuration file. By default,
that file is config_all.xml in your Source Insight\Settings user directory. Make sure you make a backup of con-
fig_all.xml if you want to keep it!
Save Layout
This saves the current window panel arrangement to a layout file. There are four buttons to quickly save to
layouts A - D. These save into files named "layout_a.xml", "layout_b.xml", etc..
To save to more than the four special layout slots, click the Other button.
You load the layouts by using the Load Layout command, or the corresponding Load Layout buttons on the
layout toolbar. See “Load Layout” on page 254.
Save Selection
The Save Selection command saves the currently selected text to a new file. The new file will remain open.
The file may be a new file, or an already existing file. The file may also be a file that is already open in Source
Insight. If the file is already open, then Source Insight will ask if you want to replace the file with the new text,
or append the new text to the file.
Save Settings
(On the Symbol Window right-click menu.)
This makes the current settings of the window become the new Default settings for new windows.
For the Symbol Window, this records the window's width, symbol sorting, and symbol type filtering and uses
those parameters as the new default for new windows created subsequently.
Save Workspace
The Save Workspace command saves the current workspace to a new workspace file.
The workspace contains your session information, such as the names of the files and file windows you have
open.
The current workspace is automatically saved for you when you exit Source Insight, and reloaded the next
time you run Source Insight.
Options
Waveform View
If the Show text contents option is enabled, then the file's contents are displayed symmetrically mirrored
around the vertical center of the bar. This sometimes makes the shape of the contents stand out more.
Show bookmarks
Bookmark indicators appear in the scroll bar.
Width in percent
This is the width of the scroll bar, expressed as a percentage of the standard scroll bar width. For example, if a
standard Windows scroll bar appears 30 pixels wide, then setting this to 100% will make the Source Insight
vertical scroll bar the same 30 pixels. Setting this to 200% will make it 60 pixels wide, and so on.
Color Options
This section affects the colors of the scroll bar parts.
Text...
The color of the miniature "text" inside the scroll bar.
Back...
The background color of the scroll bar. If the Color based on window box is checked, then the scroll bar's
background color is based on the background color of the source file window.
Markings...
The color of the symbol boundary markings.
Scroll Left
The Scroll Left command scrolls the active window to the left by one tab size.
Scroll Line Up
The Scroll Line Up command scrolls the current window up in the file by one line.
Scroll Right
The Scroll Right command scrolls the active window to the right by one tab size.
SDK Help
The SDK Help command takes the word in the current selection and looks it up in the Windows Software
Development Kit help file. For example, if you selected "TextOut" in your program and ran the SDK Help com-
mand, a Help window for the TextOut Windows function would open.
You must have a Windows SDK help file installed on your computer to use this.
Any help file for WinHelp 3.1 or greater may be used; it does not have to be an SDK help file. If you often want
to perform help lookups from Source Insight using a different help file, that will work just fine.
You can tell Source Insight what WinHelp file to run for the SDK Help command by running the Change the
SDK Help File command.
Search
The Search command searches the current file or selection for a specified pattern.
Find
Add the pattern you want to search for in this text box.
Search
Click this to begin searching.
Cancel
Click this to cancel the command.
Whole File
Click this button to search the whole file, from top to bottom, and place the search results in the Search
Results window.
Files
Click this button to open the Search Files dialog box, which lets you search across files.
Case Sensitive
Search will only find matches if the case matches exactly.
Wrap Around
If enabled, the search continues at the beginning of the file when it reaches the end of the file. The search will
wrap around only once. If not enabled, the search stops when it reaches the end of the file.
Search Scope
This group of options specifies the scope and the direction of the search.
Forward
Searches forward starting at the current selection. The search is always forward if Selection or Whole File is
checked.
Backward
Searches backwards starting at the current selection.
Selection
Searches only the current selection, in the forward direction.
Whole File
Searches the whole file, in the forward direction.
If neither Selection nor Whole File is checked, then the search continues from the current selection point,
either forward or backwards through the file.
Search Backward
The Search Backward command searches backward in the current file for the pattern previously searched
for. The search pattern is initially added using the Search command dialog box. The search begins at the cur-
rent insertion point.
Search Engines
Use this to edit the Internet search engine options used by the Search Web command. Each search engine
entry has a web query URL specification that is used to invoke the search. Source Insight substitutes %S in the
web URL with the search term.
The URL query specification should contain a %S, which gets substituted with the search term.
Search Files
The Search Files command searches through multiple files. A new Search Results output window is created.
Each time Source Insight finds a matching line in a file, it appends an entry to the Search Results. Each line in
the Search Results file can have source links that link the line with the location of the matching text in
another file.
Search
Click this button to begin the searching in the selected files, or the file named in the File Name text box.
Select All
Click to select all the files in the file list.
Browse
Click this button to show the Open File dialog box, so that you can browse your disks to locate a file to be
searched. When you select a file in the Open File dialog box, its full path will be placed in the File Name text
box.
Find
Type the pattern to be found in this text box. The pattern can be a regular expression.
File Name
The name of the file to search. You may also add a series of wildcard specifications and click the Search but-
ton and Source Insight will replace the file list with the results of the wildcard expansion. If the Project Wide
option is on, the wildcards are expanded over the whole list of files in the current project; otherwise, the
wildcards are expanded in the current directory.
If the Project Wide option is on, Source Insight will search the project symbol for file names added in the File
Name text box, so you don't have to include a directory specification for those files.
File list
If the Project Wide option is on, then this list displays all files in the current project.
If the Project Wide option is off, then this list displays all the files in the current working directory. The current
directory path is displayed above the file list. Source Insight shows only files for known file types in the cur-
rent directory. The file types are specified with the File Type Options command.
Show Dirs
Click this button to toggle the file list contents between showing file names, and showing only subdirectory
names. When the subdirectories are shown, this button changes to "Show Files".
Options Group
Project Wide
This check box controls whether the File list shows all the files in the project, or just the files in the current
working directory.
Include Subdirectories
If this check box is checked, then any selected directories are recursively searched. This option and the Proj-
ect Wide option are mutually exclusive.
Case Sensitive
If enabled, Source Insight will only find matches if the case matches exactly.
Find Non-Matching
If enabled, Source Insight will find all lines where the pattern did not match.
Skip Comments
If enabled, then comments will not be searched.
Search Results
These options affect what appears in the Search Results after the search is completed.
Include in Results...
Click this button to specify what information is included in the Search Results.
Search Forward
The Search Forward command searches forward in the current file for the pattern previously searched for.
The search pattern is initially added using the Search command or the Search Forward for Selection com-
mand. The search begins at the current insertion point.
Search List
The Search List command appears on most right-click menus when you click on a list. This allows you to
search the list for a string or regular expression.
Tip: Once the input focus is on a list, you can press F4 to search for the next occurrence.
Start at beginning
If enabled, then the search starts at the first item in the list. If not enabled, then the search starts just after the
selected item in the list.
Match Case
Turn this on to perform a case-sensitive search.
Searching Options
Specifies options for the Search commands.
Search Project
Searches for text or keywords across all project files. This command works the same as the Lookup Refer-
ences command. The only difference is that each dialog box has its own persistent state. See “Lookup Refer-
ences” on page 256.
You can also use the Project Search Bar to perform the same type of search. See “Project Search Bar” on
page 279.
For details on the basic options in this dialog, See “Lookup References” on page 256.
Keyword Expressions
A keyword expression search is similar to an Internet search engine query. Source Insight searches the proj-
ect for occurrences of a set of keywords that appear within a specified number of lines. The Lines of Context
text box indicates the maximum distance the keyword terms can be from each other to qualify as a match.
For example, if you typed "cat food", then Source Insight will search for occurrences of "cat" and "food"
within X lines of each other.
There is an implicit logical-AND operator between keywords. That is, if you type more than one keyword, the
both keywords must be present to qualify as a match. You can include other Boolean operations as well. The
following table lists the operators available:
Table 4.6: Keyword Search Operators
Operator Example Action
AND or + cat and dog Both terms must be present.
OR cat or dog Either term must be present
NOT -cat The term must not be present
or –
or !
= =Betty Case sensitive match
? "regexp" ? "^Ich" Term is a regular expression
Word Variations
If you enabled the Find word variations option, then Source Insight will also find different ending forms of
the keywords you specified. For example, if you specified the keyword "open", Source Insight will also find
"opens", "opened", and "opening". This has the same effect as typing this expression:
(open or opens or opening)
Word variations are applied to each keyword term. For example, if you specified:
save write
Which implies "save" and "write" must be present. With word variations enabled, this search would be equiv-
alent to:
(save or saves or saving) and (write or writes or writing)
Search Web
This command launches your web browser to search for the identifier at the cursor position. You can specify
which search engine site to use. The Search Web is on the Search menu, and on the right-click menu. There is
also a toolbar button.
Find
Enter the text to find here. The identifier symbol under the cursor is automatically loaded for you.
Search Engine
Choose which search engine to use. The engine you pick is remembered for the next time you use the Search
Web command.
Edit
Press this button to add or change the list of search engines. See “Search Engines” on page 326.
Select All
The Select All command selects all the text in the current file.
Select Block
The Select Block command selects the smallest C block that encloses the current selection. Each time the
Select Block command is used, it selects the next larger C block.
Select Line
The Select Line command selects all of the current line.
Select Line Up
The Select Line Up command extends the current selection up by one line.
Select Match
The Select Match command selects up to the matching brace, parentheses, or quote mark. For example, if
the insertion point is just before an open brace, this command selects up to and including the closing brace.
Select Sentence
The Select Sentence command selects up to the next period.
Select Symbol
The Select Symbol command selects the entire enclosing symbol. For example, if the current selection is
inside of a function, the Select Symbol command selects the whole function, including the lines that precede
the function, up to the bottom of the previous symbol.
Select To
The Select To command is used with the mouse to extend an existing selection up to a new point.
To use this command, point and click the left mouse button while holding down the Shift key. The selection
will be extended up to the place you pointed at. If you pointed to a position already within the selection, then
the selection will be shrunk to that location.
Select Word
The Select Word command selects the whole word at the insertion point.
To use this command with the mouse:
Point and click the left mouse button at a word while holding the Ctrl+key down.
The whole word gets selected. Now, while still holding the left button down, you can drag and extend the
selection in whole word increments.
Selection History
The Selection History displays a list of places that you have been in the currently open files. The list is sorted
such that the first item is the most recent place you have been.
You can also use the Go Back (Alt+,) and Go Forward (Alt+.) to navigate back and forth like in a web browser.
Position
Displays a list of all selection history positions. Each item in the list shows the file and line number. If the
position is within a symbol, the symbol is also shown. For example, if you were inside of a function, then the
function name is in the list too.
Go To
Click this button to jump to the selected position.
Show Clipboard
The Show Clipboard command opens a window, which displays the clipboard. You cannot edit or select in
the clipboard.
Simple Tab
Simple Tab Inserts a regular tab, overriding the Smart Tab mode. This is useful if you have the Smart Tab
option enabled. The Smart Tab mode alters the behavior of the regular Tab key. Sometimes, the Smart Tab
results in unwanted results. Use the Simple Tab command to just insert a regular tab, without any special
effects.
Smart Rename
Smart Rename will rename a symbol, including its definition and usages, across all project files or within a
local function. If the Smart Reference Matching option is enabled, then Smart Rename will rename the sym-
bol only in the correct contexts. It can be used to rename function local variables, class or struct member,
and functions.
Smart Rename is a specialized form of a global search & replace. Source Insight uses its symbol database
index to make it very fast.
Old Name
Add the name of the identifier to be renamed. The word under the cursor is automatically loaded for you. The
position of the cursor is significant because Source Insight will determine exactly which symbol you want to
rename, based on the local scope context.
You can add any string into this text box; however, the rename operation is optimized and much faster for
single-word strings. Also, if you type anything into this text box, Source Insight will have to re-establish
exactly what symbol you are trying to rename, based on the initial cursor position.
If you are renaming a member variable, or a local variable, you will notice that the Old Name text box con-
tains the full symbol name, including the container symbols. For example, it might say "DocDraw.paintStruc",
where "DocDraw" is a function name, and "paintStruc" is a local variable. In a sense, "paintStruc" is a mem-
ber of the "DocDraw" function.
New Name
Add the new name here. For members, you should only add the new member name, and omit the symbol
container qualifiers.
Skip Comments
If enabled, then symbol references inside comments will not be renamed.
Smart Tab
When the Smart Tab command is used at various positions in your source code, Source Insight moves the
selection to the next "field". A field is an interesting position, depending on the current context. Smart Tab
lets you move the cursor around easily, especially when typing new function calls.
When the Smart Tab option is on (Preferences: Typing), then pressing the regular Tab key will invoke the
Smart Tab command. The Simple Tab command simply inserts a tab, and avoids the Smart Tab behavior.
Therefore, if you have the Smart Tab option turned on, you can use the Simple Tab command to occasionally
override the Smart Tab behavior.
Example 1:
1. Beg^inPaint(hwnd, pps);
2. BeginPaint(hwnd, pps);
Example 2:
1. BeginPaint^(hwnd, pps);
2. BeginPaint(hwnd, pps);
3. BeginPaint(hwnd, pps);
4. BeginPaint(hwnd, pps^);
5. BeginPaint(hwnd, pps)^;
Example 3:
1. ResetAbc(^)
2. ResetAbc()^
Smart Tab works like a regular tab when you use it at the beginning or end of line text, or on a line that
doesn't have a function call.
The Smart Tab works well with auto-completion of function calls. When you insert a function call via the
popup auto-completion window, the function's parameter types and names are also inserted, and the first
parameter is selected. You only have to start typing over the first parameter, then press Smart Tab to select
the next parameter.
Snippet Properties
This window is used to edit the contents of a code snippet located in the Snippet Window. See “Code Snip-
pets” on page 98.
Name
The name of the snippet. This is the name that will appear in the auto-completion list as you type.
Description
This should contain a short description of the snippet. If you leave this blank, Source Insight will use a por-
tion of the snippet’s body text as the description.
Storage Location
This determines whether the snippet belongs to the current project, or is common to all projects (Global).
Note that changing this setting will cause the snippet to be saved to the new location, and removed from the
old location.
Language Context
Specifies from what programming language files this snippet should be available. For example, you can have
a snippet that is only applicable in Java. The auto-completion list will only include snippets that are applica-
ble to the language type of the current file.
Body Text
This is the contents of the snippet. This is a mini-editor window where you can type and edit the snippet text.
The snippet is inserted just as you enter it here.
You can use text variables within the snippet body. The Insert Text Variable list contains all the predefined
text variables you can enter.
You can also simply type any text variable in, including any variable you want to use as a placeholder when
inserting the snippet.
Snippet Window
The Snippet Window lists all code snippets. From this window, you can create, edit, delete, and insert code
snippets. See “Code Snippets” on page 98.
To insert a snippet into the current file, type the name of the snippet and press Enter. You can activate the
Snippet Window first by using the Activate Snippet Window command (Ctrl+Alt+S).
List Columns
Select the columns you want to include in the Snippet Window.
List Contents
Select the type of snippets you want to include in the Snippet Window.
Snippet Options
If you want all Symbol Windows to be sorted this way by default, then right-click on the Symbol Window and
select Save Settings on the Symbol Window's right-click shortcut menu.
Start Recording
The Start Recording command turns on the command recorder. While recording, any command you run will
also be recorded. This allows you to record a single series of commands, which can be played back with the
Play Recording command.
To stop recording, use the Stop Recording command, or just play the recording back with the Play Recording
command.
You can keep only one recording at a time. The recording is saved with the workspace.
Stop Recording
The Stop Recording commands turns off the command recorder. The Start Recording command is used to
start the recorder. The command recorder allows you to record a single series of commands, which can be
played back with the Play Recording command.
Style Properties
This command allows you to set formatting properties for display styles. For more information about how
styles work, see “Syntax Formatting and Styles” on page 78.
Formatting Properties
Each style has a number of formatting properties. Because styles exist in a hierarchy, each formatting prop-
erty is combined with the parent style to yield a final result.
For example, if bold = "ON", then bold formatting is added. If bold = "OFF", then bold formatted is subtracted
from the parent style properties.
Many formatting controls in this dialog box show one of these values:
• On – the property is added to the parent style formatting.
• Off – the property is deleted from the parent style formatting.
• A Number – the value replaces the parent style property.
• = (equal) - the property has no effect, and it inherits the exact same value as in the parent style.
Parent Style
This is the parent style in the style hierarchy. The current style inherits its formatting from the parent style.
The style list depicts the style hierarchy. Any property that is other than "equal" (meaning "the same") is
combined with the parent style formatting.
Add Style
Click this button to add a new user-defined style.
Delete Style
Click this button to delete a user-defined style. The standard built-in styles cannot be deleted.
Load…
Click this button to load a new style sheet from a configuration file.
Save
Click this button to save the current style sheet settings to a new style configuration file. The file will contain
only style properties, and won't contain other elements that can be stored in a configuration file. If you load
this configuration file, only the style properties are loaded.
Reset…
Click this button to reset all the styles to the factory defaults. This loses all your changes since installing
Source Insight.
Font Options
Font Name
Selects the font name for the style. If the Default style is currently selected, then the Font setting changes the
font name and size of the File Type of the current file. This is because the Default style refers to the font set-
tings of the File Type of the current file. See “File Type Options” on page 213.
Size
Selects the font size, specifically as a point size. You may find the relative Scale property more useful, since it
is relative, and works well regardless of changes to the parent styles.
Scale
Specifies the font size scaling as a percentage of the parent style's font size. For example, if the scale is 50%,
then it will be half the size of whatever the parent style font size is.
Bold
Selects the bold property of the style, if any.
Italic
Selects the italic property of the style, if any.
Underline
Selects the underline property of the style, if any.
All Caps
Selects the All Caps (capitalization) property of the style.
Strike-Thru
Selects the Strike-Thru property of the current style.
Colors Options
Foreground
Selects the foreground color of the current style.
Background
Selects the background color of the current style.
Shadow
Selects the color of the drop-shadow of the current style.
Inverse
Selects the Inverse property of the current style. Inverse means that the foreground and background colors
are reversed.
Spacing Options
Above Line
This selects the percentage of vertical spacing to add above the line.
Below Line
This selects the percentage of vertical spacing to add below the line.
Expanded
This selects the percentage of horizontal spacing to add to characters.
Symbol Info
The Symbol Info command displays a pop-up window showing the definition of the symbol under the cursor.
This is a quick way to check the definition of an identifier.
Source File
The source file name and line number where the symbol is defined are displayed at the top left of the dialog
box below the symbol name. If known, the symbol's size in lines is displayed also.
Text Window
This scrollable window contains the contents of the source file where the symbol is defined.
Close
Click this to close the window.
Jump
Click this to close the Symbol Info window and jump to the symbol definition directly.
References
Click this button to search for references in the whole project to the symbol.
Note: The Project > Import External Symbols command is a more powerful way to refer to symbols in external
sources, such as assemblies, header file libraries, and other Source Insight projects. See “Import External Sym-
bols” on page 233.
The symbol window shows a list of symbols defined in the file. The symbol window is only available if the file
type has a parsed language selected. See “Symbol Windows ” on page 30.
Figure 4.3 The Symbol Window pane appears at the left of each source window and lists all the declarations in that file.
The symbol window can be sorted by using the Sort Symbol Window command, or by clicking the three sort-
ing buttons in the toolbar at the bottom of the window.
Click the gear button to select the Symbol Window options. You can also invoke the Symbol Window Options
command directly by mapping a key to it. See “Symbol Window Options” on page 351.
Apply Now
Applies the changes you made in this dialog box to the Symbol Window.
Symbol Types…
Click this button to open the Symbol Type dialog box, where you can filter out different types of symbols
from the Symbol Window.
Font…
Click this button to pick the font used to draw the Symbol Window.
Text Color…
Click this button to pick the color of the text in the Symbol Window.
Back Color…
Click this button to pick the background color of the Symbol Window.
Synchronize Files
The Synchronize Files command synchronizes the current project with all the source files in the project. The
command scans each file in the project and updates the symbol database for each file that has been modi-
fied since Source Insight parsed the file last. In addition, files that were part of the project that don't exist
anymore are removed from the project.
You normally do not need to run this command because Source Insight scans your source files in the back-
ground by default. You can control the background synchronization by selecting Options > Preferences: Gen-
eral.
You can also use a Master File List in your project to control which files are in your project. Use the Project >
Project Settings command to specify the Master File List. See “Using a Master File List” on page 46.
Syntax Decorations
This command specifies syntax decoration options for displaying source files. It activates the Syntax Decora-
tions page of the Options > Preferences dialog box.
Source Insight can replace some common operators with more useful symbolic characters. The Syntax Deco-
rations command lets you control which decorations are used. See “Syntax Decorations” on page 87.
It's important to remember that symbol decorations and 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.
Display Substitutions
This group of options controls which operators are substituted with special symbols.
Not Equal
This replaces the != not equal operator with ≠.
Equal
This replaces the == equal operator with a mathematic EQUIVALENT character.
Division
This replaces the / division operator with ÷.
Logical AND
This replaces the && logical And with ∩.
Logical OR
This replaces the || logical Or with ∪.
Auto Annotations
Source Insight can automatically add certain annotations to your source code display. The following options
control which annotations appear.
Syntax Formatting
This command specifies syntax formatting options for displaying source files. It activates the Syntax Format-
ting page of the Options > Preferences dialog box.
Source Insight uses information gathered from its language 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. See “Syntax
Formatting and Styles” on page 78.
Formatting is applied using "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 Style Properties command.
Styles…
Click to edit the style properties.
File Types…
Click to edit the file types.
Basic Options
Basic option are:
Symbol declarations
Declarations of symbols are formatted with the appropriate "Declare…" styles. For example, a function name
will appear in the "Declare Function" style where it is declared.
References to members
References to structure and class members are formatted with the "Ref to Member" style. The veracity of the
member reference can be controlled with the Qualify references to members option.
Comment Headings
Comment heading styles are comments that begin with a single digit in the range 1 to 4. For example:
//1 This is heading one.
//2 This is heading two.
When the comment styles are used, the //x at the beginning of the comment is hidden, and the heading style
formatting is applied to the rest of the line. The result looks like this:
Figure 4.4 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.
By having keywords assigned to formatting styles, you are able to change the syntax formatting quickly by
simply changing the style with the Style Properties command. Then all language keywords associated with
that style reflect the new style formatting.
Keyword
The keyword list for the language. When you select a keyword from the list, the keyword's associated style is
selected in the Style list.
Style
The list of all syntax formatting styles. When you select a style from this list, you are changing the style asso-
ciated with the keyword selected in the keyword list. You can also double-click on a style name to edit the
style.
OK
Click OK to record your changes.
Cancel
Aborts the command and ignores your changes.
Add Word
Click this button to add a new word to the keyword list. You can type any single word that does not include
spaces. Source Insight will add the word to the keyword list. After adding the word, make sure you select the
style you want it to have.
Delete Word
Click this button to delete the word currently selected in the keyword list.
Import
Click this button to import new keyword list entries from an external text file. See below for more informa-
tion.
Export
Click this button to export the keyword list to a text file.
Reset
Click this button to return the language keyword list to the factory default settings.
Import Options
When you click the Import button in the Language Keywords dialog box, you will be given the option of either
replacing or merging the keyword list.
Tab Tray
Shows and hides the Tab Tray at the bottom of the main window. The tab tray contains floating panels that
have been minimized.
Tabs to Spaces
Converts tabs to the equivalent numbers of space characters.
Tile Horizontal
The Tile Horizontal command arranges all windows so they are not overlapping. The tiling algorithm will
attempt to make windows wider than they are tall. This is useful for viewing 2 or more files on top of each
other.
Tile Vertical
The Tile Vertical command arranges all windows so they are not overlapping. The tiling algorithm will
attempt to make windows taller than they are wide. This is useful for viewing 2 or more files side by side.
Top of File
The Top of File command moves the insertion point to the first line in the current file.
Top of Window
The Top of Window command moves the insertion point to the first line in the active window.
Typing Options
This command specifies typing and editing options. It activates the Typing page of the Preferences dialog
box.
appear in the completion window depend on the context, such as the cursor position, or the type of variable
being referred to.
Browsing in Lists
This section customizes the way that auto completion works while typing in symbol and file lists.
Enabling this option will allow you to just type "member". If disabled, then only full symbol names are
matched. You can still use this feature, even if disabled, by prefixing your input with a dot ('.'), like this:
.member
Undo
The Undo command reverses the action of the last editing command in the current file. For example, if you
type some new text and perform Undo, the text you typed is removed. Alternatively, if you delete a line and
perform Undo, the line reappears.
In effect, as you edit, Source Insight makes a list of the changes you've made to each file. The Undo command
backs up through that list and the Redo command advances through the list.
Undo information is saved for each open file independently.
Restoring Lines
An alternative to Undo is the Restore Lines command. This command restores the selected lines to their orig-
inal contents when the file was first opened. Furthermore, the Restore Lines command can be undone with
the Undo command. Mixing both Undo and Restore Lines can be very useful.
Undo All
The Undo All command undoes all the editing changes to the current file since the last time it was opened.
See Also: Undo, Redo, Redo All commands.
View Clip
(On Clip Window toolbar and right-click menu)
The View Clip command displays the selected clip in a source file window. If you close the window, you will be
asked if you want to retain the clip in the Clip Window.
View Toolbar
Shows or hides the View toolbar.
Visible Tabs
This toggles the display of visible tab characters. Source Insight displays symbols in place of tabs.
Window List
The Window List is a floating/dock able panel window that shows all the open windows.
Window list
Contains a list of all open source windows, and file buffers that may be open in the "background" that do not
appear in a window. You can sort the window list by name or by recently-used order. To sort the list, click on
the header titles at the top of the list.
To activate a window, double-click the window in the list.
To edit the Window List Options, click the option button. See “Window List Options” on page 369.
Sort List By
Sorts the window list by either most recently usage, or by name.
Window Options
This command specifies options for handling and displaying source file windows.
Window Positioning
Window Display
Outlining Options
Outline options relate to collapsible code blocks.
Show outlining
If enabled, then all source windows will show outline buttons for collapsing and expanding all the time. If this
is not selected, the outline buttons and markings only show if you used one of the outlining commands to
collapse a section.
Outlining Position:
Controls whether the outline buttons appear at the far left, or indented along with the source code.
Window Tabs
The Window Tabs command shows or hides the source file window tabs that appear above the source file
windows. You can control tab options with the Window Tab Options. See “Window Tab Options” on page 372.
Tab Sorting
This controls the order of tabs from left to right.
Tab name
Select this to sort the tabs alphabetically by file name. Depending on the width of the main window, only so
many tabs will fit. Therefore, only tabs for files you have visited recently are shown in the tab bar, and they
are sorted alphabetically.
Word Left
The Word Left command moves the insertion point to left by one word.
Word Right
The Word Right command moves the insertion point to the right by one word.
Zoom Window
If the current window is not already maximized, the Zoom Window command maximizes it. If the current win-
dow is already maximized, the Zoom Window command restores the window to its un-maximized size.
Source Insight provides an interpreted C-like macro language, which is useful for scripting commands, insert-
ing specially formatted text, and automating editing operations.
Here is an example of a macro function that shows a message box.
macro HelloWorld()
{
msg("Hello World!") // message box appears with "Hello World"
}
Macros are saved in a text file with a .em extension. The macro source files can be added to your project, or to
any project on the Project Symbol Path, or to the Base project. Once a macro file is part of the project, the
macro functions in the file become available as user-level commands in the Key Assignments or Menu Assign-
ments dialog boxes.
There is a library of built-in macro functions for accessing Source Insight objects, such as file buffers, or win-
dows. You can call these built-in functions from your own macro functions.
Identifier Names
Identifier names are used to identify variables and functions.
• Identifier names are not case sensitive. For example, Open and open are the same.
• Identifier names must begin with a letter A to Z or a to z or an underscore (_), followed by zero or more
letters, underscores and digits. Examples are isOpen, MyThing2, and open_file.
• Identifier names cannot contain punctuation characters such as @ or % or dot(.).
Comments
Two types of comments are supported:
• A comment begins with /* and ends with */. The comment can span any number of lines.
• A single line comment begins with // and extends to the end of the line.
For example:
/* this is a comment */
var a
/* this comment
spans
multiple lines */
Strings
Strings must be enclosed in double-quote marks. Single quotes are not used. For example:
a = "this is a literal string"
To embed a double-quote character in a string, you must escape it with a backslash character. For example:
a = "Open the file \"test.txt\" to begin the test."
Macro Functions
A macro function is declared in a format that looks like a C function. White space is ignored, and function and
variable names are not case sensitive. A macro function begins with either the macro or function keyword,
followed by the name of the function. Here is a most basic function:
macro HelloWorld()
{
msg("Hello World!") // message box appears with "Hello World"
}
Macro functions can have parameters and can call other macros. You can return a value from a macro by
using "return n" where n is the return value. For example:
function add2(n)
{
return n + 2
}
For example, this function becomes a user-level command, and it can be assigned to a keystroke:
macro SaveCurrentFileNow ()
{
perform_save()
}
You can use Options > Key Assignments to locate the SaveCurrentFileNow command and assign a keystroke
to it.
However this function can only be called from another macro function, because it is declared with the func-
tion keyword:
function perform_save ()
{
var hbuf
hbuf = GetCurrentBuf()
if (hbuf != nil)
SaveBuf(hbuf)
}
Running Macros
You can run macros by invoking the macro command directly with a keystroke or menu item, or by using the
Run Macro command to begin running macro statements at the current cursor position. You can also run a
macro by selecting the macro command inside the Options > Key Assignments, or Options > Menu Assign-
ments dialog, then clicking the Run button.
Macros as Commands
If a macro function is declared with the macro keyword, and has no parameters, then Source Insight consid-
ers it to be a user-level command. User-level macro commands appear in the command lists of the Key
Assignments and Menu Assignments dialog boxes. This allows you to place macro commands on the menu or
in the keymap. You can also run commands directly from those dialog boxes. If a macro function has parame-
ters, it will not appear as a command in the command lists, and you wont be able to assign a keystroke to it
or put it on a menu.
Tip: A shortcut for editing a user level macro command is to hold down the Ctrl key while selecting the command.
The macro function source code will appear for that command.
If you create a new macro command function in a macro file, you must save the macro file and allow Source
Insight to synchronize it with the project database files before the macro command will appear in menu and
key assignments command lists.
You can also store macros in the Base project, or any other project on the project symbol path. Source Insight
will search those projects when resolving macro names.
Note: Source Insight will not add macro functions to the user-level command list unless they are saved in Source
Insight macro files using a .em extension.
Statements
Macros are composed of individual statements. Compound statements consisting of two or more statements
are enclosed with curly braces { }.
Statement Examples
Here are a few example statements:
hbuf = OpenBuf("file.c") // call internal function OpenBuf
SaveBufAs(hbuf, "filenew.c") // call internal function SaveBufAs
Select_All // call user-level command "Select All"
Copy // call user-level command "Copy"
Line_Up // call user-level command "Line Up"
x = add2(n) // call user-defined macro function add2.
Statement Elements
The following table summarizes the macro language statements.
Table 5.1: Macro Statements
Statement Description
break Exits a while loop.
if (cond)… else Tests a condition.
continue Continues a while loop at the top.
global Declares a global variable.
return n <or> Returns n from a function. If a semi-
return; colon follows return, then the nil
string is returned.
stop Stops executing the macro.
strictvars true/false Turns on or off strict variable decla-
rations mode.
var Declares a function-local variable.
while (cond) Loops while cond is true.
Variables
Variables are defined by simply assigning a value to them for the first time. Using the default settings, vari-
ables do not need to be declared before using them. However, you can use the var statement to explicitly
declare a variable. Further, you can require variable declarations by using the strictvars statement.
You can create a variable by assigning a value to it for the first time. For example:
i = 0 // creates new variable i with value 0
If the strictvars mode is on, then the above statement will cause an error because the variable is used before
being declared.
You can declare a variable by using the var statement. For example:
var i // declares new variable i
Variable names are not case sensitive. Variable names must begin with a letter or underscore, not a digit.
Variables act like strings most of the time. There are no types like in C, and no need to declare variables. This
makes working with variables very easy. There is no need to do conversions or casts. In addition, there is no
need for string memory management.
Declaring a Variable
The var statement declares a local variable, and sets it value to the empty string (nil).
var variable_name
You can declare more than one variable by separating the variables with a comma. For example:
var a, b, c // declares three variables
A local variable cannot be accessed outside of its function.
You don't have to declare variables if strictvars mode is off (default), but there are a couple of benefits if you
do:
• Syntax formatting works in the display for references to it.
• Variables are initialized to the empty string value, nil, so they are not confused with literal values when
used without being initialized.
For example:
macro SomeFunction()
{
var localx
strictvars Mode
The strictvars statement turns on or off strictvars mode. If strictvars mode is on, then variables must be
declared before you use them. By default, strictvars mode is off.
The strictvars statement syntax is:
strictvars <value>
where <value> is true or "1' to enable the mode, or false or "0' to disable the mode.
For example:
strictvars true
i = 0 // error: the variable i has not been declared
If you refer to a variable that has not been declared, and strictvars mode is enabled, then you will get an
error. For example:
var s
s = somestring // error if variable "somestring' is not declared
If the strictvars mode is enabled, then identifiers must be defined variables, and the identifier name will
never be used as a literal string.
Note that the strictvars statement is an executed statement, and must be in the path of execution. If the
program never runs the strictvars statement, then the mode is not changed. Further, you can use the
strictvars statement more than once turn the mode on or off.
Variable Initialization
Variables are initialized by simply assigning a value to them (unless strictvars mode is enabled). It may be
useful to initialize a variable to the empty string. A special constant, named nil is used for that.
For example:
S = nil // s is set to the empty string
S = "" // same thing
You can also use the var statement to declare a new variable and set it equal to nil. For example:
var s // s is created and set to the empty string
Global Variables
A variable that is declared with the var statement, or created by assignment is considered local to the func-
tion that contains the statement. You cannot access the local variable outside of the function that defines it.
A local variable ceases to exist after the function returns. However, a global variable has a global scope
instead of local. That means you can access it from multiple functions, and its value exists after a function
returns, or the whole macro stops running.
Once a global variable is defined, its value will be retained as long as the Source Insight session lasts. That is,
they can contain information between invocations of macros or event functions. They are lost when you exit
Source Insight.
The global statement should appear inside a function, and must be in the execution path of your code. For
example:
macro SomeFunction()
{
global last_count
...
}
When the global statement is encountered, the variable is entered into the global-scope variable table. The
variable is initialized to nil. This example shows how you might declare and use a global counter variable:
macro SomeFunction()
{
global last_count
Note: Global variables hold their values for the whole Source Insight session.
Global variables are useful for adding counters, and other persistent state. They cannot hold any kind of han-
dle, because all handles are destroyed when a macro finishes. So, for example, this will not work:
global hbuf
hbuf = OpenBuf("abc.txt")
In the above example, the hbuf variable will contain a bogus handle as soon as this macro finishes because
handles only exist while a macro is running.
Variable Values
If an identifier is the name of a defined variable, then it yields the variable value. Otherwise, the identifier
name is used as a literal string. For example:
s = abc // same as s = "abc" if abc is not defined
..or..
abc = Hello
s = abc // same as s = "Hello" (if Hello is not defined!)
s = "abc" // s equals "abc"
If the strictvars mode is enabled, then identifiers must be the names of defined variables, and the identi-
fier name will never be used as a literal string.
To avoid unintentionally using the name of variable as a literal value, you should get into the habit of declar-
ing your variables with the var statement. Or, you can use the strictvars statement to require variable
declarations. See also “strictvars Mode” on page 380.
For example:
s = "Hey, @username@, don't break the build again!"
This example replaces @username@ with the value of the variable username in the string.
You can escape the @ character with a backslash \ or by using two @ characters together. For example:
s = "Mail info@@company.com for information."
Variable Arithmetic
Even though variables are represented as strings, you can perform arithmetic on them. E.g.
s = "1"
x = s + 2 // x now contains the string "3"
y = 2 * x + 5 // x now contains "11"
Using variables numerically is very natural and normally you don't have to even think about how they are
stored. The only time you need to be careful is if a variable might contain a string that does not evaluate to a
number. In that case, an error is generated. For example:
s = "hello"
x = s + 1 // error
Record Variables
While data structures such as classes are not supported, Source Insight supports record variables. A record
variable is actually a delimited list of "name=value" pairs. There is no predefined order of fields in a record
variable, and they don’t have to be declared before using them.
Record variables are used in the same way that a "struct" would be used in C. Record fields are referred to
with the dot (.) operator using a <recordvar>.<fieldname> format.
For example, this reads the name of a symbol's file location from a symbol lookup record variable.
Filename = slr.file // get file field of slr
LineNumber = slr.lnFirst // get lnFirst field of slr
You can create your own record variables whenever you want this way.
Record variables are a convenient way to return multiple values from a function. Several built-in functions
return record variables.
An example of a standard record is the Selection Record. See “Selection Record” on page 392.
If you wanted to construct a whole record variable string from scratch, you would have to surround it in dou-
ble quotes and escape each embedded quote mark with the backslash character, like this: (C programmers
should be used to this.)
rec = "name=\"Joe Smith\";age=\"34\";experience=\"guru\""
Array Techniques
The Source Insight macro language does not support array variables. However, file buffers can be used as
dynamic arrays. Each line in a buffer can represent an array element. Furthermore, record variables can be
stored in each line to give you record arrays.
Buffer functions are described in a following section. Some useful functions are NewBuf and CloseBuf for cre-
ating and destroying buffers; and the buffer line functions: GetBufLine, PutBufLine, InsBufLine, AppendBu-
fLine, DelBufLine, and GetBufLineCount. You can also call NewWnd to put the array buffer in a window so you
can see the array contents.
Special Constants
Some constant values are always defined while a macro is running. As with all other identifiers, the constant
names are not case sensitive.
Table 5.2: Runtime Constants
Constant Value
True "1"
False "0"
Nil "" – the empty string.
hNil "0" – an invalid handle value.
invalid "-1" – an invalid index value.
Operators
Most binary operators are the same as in C. Operator precedence is the same as C. You can also use parenthe-
ses to group expressions.
Table 5.3: Operators
Operator Meaning
+ and - add and subtract
* and / multiply and divide
! Invert or "Not". E.g. !True equals False.
++i and i++ pre and post increment
--i and i-- pre and post decrement
|| logical OR operation
&& logical AND operation
!= logical NOT EQUAL operation
== logical EQUAL operation
< less than
Since variables may contain non-numeric values, relational operators are treated thus:
Table 5.4: Relational Operators for Strings
Operator Meaning
== strings must be equal (case sensitive)
!= strings must not be equal (case sensitive)
< strings are converted to numbers and then compared.
> Empty strings or strings that are non-numeric result in
<= a runtime error.
>=
The if Statement
The if statement is used to test a condition and execute a statement or statements based on the condition.
The if statement has the following syntax:
if (condition)
statement // condition is true
In the above example, if condition is true, then statement is executed. You can use {} brackets to group more
than one statement. For example:
if (condition)
{
statement1
statement2
}
Note: Source Insight evaluates the whole condition expression, unlike C/C++ which performs partial evaluation. See
“Conditional Evaluation” on page 387.
In the above example, the statement in the while block is executed as long as the condition is true. The condi-
tion is tested at the top of the loop each time. You can use {} brackets to group more than one statement. For
example:
while (condition)
{
statement1
statement2
}
Note: Source Insight evaluates the whole condition expression, unlike C/C++ which performs partial evaluation. See
“Conditional Evaluation” on page 387.
The continue statement continues again at the top of the loop, just before condition expression is evalu-
ated.
while (condition)
{
if (skip_rest_loop)
continue // continue at the top of the while loop
…
}
Conditional Evaluation
Source Insight evaluates the whole conditional expression each time. Expressions are not short-circuited.
This is an important difference from the way that C conditional expressions are evaluated. In C, the expres-
sion may be partially evaluated. Consider the following conditional expression:
if (hbuf != hNil && GetBufLineCount(hbuf) > x)
This conditional expression would lead to an error in Source Insight if hbuf is equal to hNil. In C, the evalua-
tion would be terminated after determining that hbuf != hNil. In Source Insight, the whole expression is
evaluated. In this case, causing an error since hNil would be passed as the buffer handle to GetBufLine-
Count.
Naming Conventions
Variables and function parameters described in this macro guide are named using the following conventions.
Table 5.5: Identifier Naming Conventions
Name Meaning
s and sz a string
ch single character string. If more than one character is
in a string, only the first character is used.
ich zero-based index to a character in a string or charac-
ter in a line
ichFirst first index in a range of characters
ichLast last index in a range of characters (inclusively)
ichLim limit index - one past the last index in a range
cch count of characters
fThing "f" means flag or boolean. fThing means "Thing" is
True.
TRUE a non-zero value, e.g. "1"
FALSE a zero value, i.e. "0"
ln zero-based line number
lnFirst first line number in a range
lnLast last line number in a range (inclusively)
lnLim limit - one past the last line number in a range
hbuf handle to a file buffer
hwnd handle to a window
hprj handle to a project
hsyml Handle to a symbol list
Any other names general string variables
This section describes the record structures used by the internal macro functions in Source Insight.
Bookmark Record
A bookmark points to a position in a file. The Bookmark record has the following fields:
Field Description
Name The bookmark name.
File The file name of the bookmark position.
ln The line number position.
ich The character index on the line (zero based).
Symbol A nearby symbol definition to which the bookmark is
anchored. This is usually the enclosing function or class.
lnOffset The line number offset (distance) from Symbol.
SymbolType The type of Symbol.
FtpSiteName If the bookmark points to a file hosted on an FTP host,
this is the "Site Name" used in the FTP Panel. If the book-
mark points to a local file, then this field is empty.
FtpRemoteDir If the bookmark points to a file hosted on an FTP host,
this is the remote directory name on the host. If the
bookmark points to a local file, then this field is empty.
Bufprop Record
A Bufprop record contains file buffer properties. It is returned by GetBufProps. The Bufprop record has the
following fields:
Field Description
Name The buffer name (i.e. file name)
fNew True if buffer is a new, unsaved buffer.
fDirty True if the buffer has been edited since it was saved or
opened.
fReadOnly True if the buffer is read-only.
fClip True if the buffer is a clip that appears in the Clip Win-
dow.
fMacro True if the buffer is a macro file.
fRunningMacro True if the buffer is a currently running macro file.
fCaptureResults True if the buffer contains captured custom command
output.
fSearchResults True if the buffer contains search results.
fProtected True if the buffer protected and reserved for internal
use.
lnCount The line count of the buffer.
Language The programming language of the buffer. The lan-
guage is determined by the file's document type.
DocumentType The document type of the buffer.
DIM Record
The DIM record describes horizontal and vertical pixel dimensions.
Field Description
Cxp Count of X-pixels (horizontal size)
Cyp Count of Y-pixels (vertical size)
Link Record
A Link record describes a location in a file, which is pointed to by a source link. The Link record has the follow-
ing fields:
Field Description
File The file name
ln The line number - this is only valid for as long as the file is
unchanged. If lines are inserted or deleted from the file, the
line number is going to be off. However, you can call Get-
SourceLink again to get an updated line number.
ProgEnvInfo Record
The ProgEnvInfo record contains information about the environment where Source Insight is running.
Field Description
ProgramDir The Source Insight program directory, where the
program file is stored.
TempDir The temporary files directory.
BackupDir The backup directory, where Source Insight stores
backups of files that you save.
ClipDir The directory where clips are persisted.
ProjectDirectoryFile The name of the project directory file. The project
directory file contains a list of all the projects that
have been opened.
ConfigurationFile The name of the currently active single configura-
tion file. This entry will be empty if the master
configuration file uses separate files for separate
parts.
MasterConfigurationFile The name of the master configuration file.
ShellCommand The name of the command shell. The command
shell depends on the operating system version
you are running.
UserName The registered user's name.
UserOrganization The registered user's organization.
SerialNumber The registered license serial number.
ProgInfo Record
The ProgInfo record describes the version of Source Insight that is running. It has the following fields:
Field Description
ProgramName The name of the program (i.e. "Source Insight")
versionMajor The major version number. If the version number
is 1.02.0003, then the major version is 1.
versionMinor The minor version number. If the version number
is 1.02.0003, then the major version is 2.
versionBuild The build number of the version. If the version
number is 1.02.0003, then the build number is 3.
CopyrightMsg The Source Dynamics copyright message.
fTrialVersion True if the program is a Trial version.
fBetaVersion True if the program is a Beta version.
ExeFileName The name of the executable file.
cchLineMax The maximum number of characters allowed in a
source file line.
cchPathMax The maximum number of characters supported in
a path name.
cchSymbolMax The maximum number of characters allowed in a
symbol's full name.
cchCmdMax The maximum number of characters allowed in a
command, custom command, or macro com-
mand name.
cchBookmarkMax The maximum number of characters allowed in a
bookmark name.
cchInputMax The maximum number of characters allowed in a
dialog box text input field.
cchMacroStringMax The maximum number of characters allowed in a
macro string variable.
lnMax The maximum number of lines supported in a
source file.
integerMax The maximum integer value supported.
integerMin The minimum integer value supported (a negative
number).
Rect Record
A Rect record describes the coordinates of a rectangle. The Rect records has the following fields:
Field Description
Left The left pixel coordinate of the rectangle
Top The top pixel coordinate of the rectangle
Right The right pixel coordinate of the rectangle
Bottom The bottom pixel coordinate of the rectangle
Selection Record
A Selection record describes the state of a text selection in a window. The Selection record has the following
fields:
Field Description
lnFirst the first line number
ichFirst the index of the first character on the line lnFirst
lnLast the last line number
ichLim the limit index (one past the last) of the last character on
the line given in lnLast
fExtended TRUE if the selection is extended to include more than
one character. FALSE if the selection is a simple insertion
point.
this is the same as the following expression:
(sel.fRect || sel.lnFirst != sel.lnLast || sel.ichFirst != sel.ich-
Lim)
fRect TRUE if selection is rectangular (block style).
FALSE if the selection is a linear range of characters.
The following fields only apply if fRect is TRUE:
xLeft the left pixel position of the rectangle in window coordi-
nates.
xRight the pixel position of the right edge of the rectangle in
window coordinates.
Symbol Record
The Symbol record describes a symbol declaration. It specifies the location and type of a symbol. It is used to
uniquely describe a symbol in a project, or in an open file buffer.
Symbol records are returned by several functions, and Symbol records are used as input to several functions.
The Symbol record has the following fields:
Field Description
Symbol The full symbol name. A symbol name is actually a path.
Every symbol name is divided into path components,
which are separated by dot (.) characters. For example, a
symbol name might be "myclass.member1". In this
example, "member1" is contained by "myclass".
Type The symbol's type (e.g. "Function", "Class", etc.)
Project The full path of the project where the symbol was found
File The full path of the file where the symbol was found
lnFirst The first line number of the symbol declaration
lnLim The limit line number of the symbol declaration
lnName The line number where the symbol's name appears in
the declaration.
ichName The character index of the symbol's name in the declara-
tion at the line lnName.
Instance The instance number path of the symbol within File. For
example, the first occurrence of a symbol is instance 0,
the second is instance 1, and so on.
SYSTIME Record
The SYSTIME record describes the system time. It is returned by the GetSysTime function.
Field Description
time the time of day in string format.
date the day of week, day, month, and year as a string.
Year current year.
Month current month number. January is 1.
DayOfWeek day of week number. Sunday is 0, Monday is 1, etc.
Day day of month.
Hour current hour.
Minute current minute.
Second current second
Milliseconds current milliseconds
String Functions
String functions are provided to allow string manipulation. You don't have to worry about memory manage-
ment of strings, or declaring buffers to hold strings.
AsciiFromChar (ch)
Returns the ASCII value of the given character ch. If ch is a string with more than one character, only the first
character is tested.
cat (a, b)
Concatenates strings a and b together and returns the result.
Alternatively, you can use the infix string concatenation operator (#) within an expression. For example:
full_name = first_name # " " # last_name
CharFromAscii (ascii_code)
Returns a string containing a single character that corresponds to the ASCII code in ascii_code.
islower (ch)
Returns TRUE if the given character ch is lowercase. If ch is a string with more than one character, only the
first character is tested.
IsNumber (s)
Returns TRUE if the string s contains a numeric string. Non numeric strings cause a run-time error when used
in arithmetic expressions.
isupper (ch)
Returns TRUE if the given character ch is uppercase. If ch is a string with more than one character, only the
first character is tested.
strlen (s)
Returns the length of the string.
tolower (s)
Returns the lowercase version of the given string.
toupper (s)
Returns the uppercase version of the given string.
Ask (prompt_string)
Prompts the user with a message box window displaying the string prompt_string. The Ask message box has
an OK button, and a Cancel button. Clicking the Cancel button stops the macro.
AssignKeyToCmd(key_value, cmd_name)
Assigns the key_value to command named by cmd_name. Subsequently, when the user presses the
key_value, the command is invoked.
key_value is a numeric keyboard value that is returned by GetKey and KeyFromChar. You can use CharFrom-
Key to convert a key_value into a character.
cmd_name is the string name of the command.
Example:
key = GetKey();
AssignKeyToCmd(key, "Open Project");
Beep ()
Gives a single beep.
CharFromKey (key_code)
Returns the character associated with the given key code. Returns zero if the key_code is not a regular char-
acter key code.
key_code is a numeric keyboard value that is returned by GetKey and KeyFromChar. You can use CharFrom-
Key to convert a key_code into a character.
CmdFromKey(key_value)
Returns the string name of the Source Insight command currently mapped to key_value. The command
returned is the name of the command that gets invoked when the user presses key_value.
key_value is a numeric keyboard value that is returned by GetKey and KeyFromChar.
You can use CharFromKey to convert a key_value into a character.
Example:
key = GetKey();
cmd_name = CmdFromKey(key);
msg("That key will invoke the @cmd@ command.");
EndMsg ()
Takes down the message box started by StartMsg.
FuncFromKey (key_code)
Return the function key number (1 - 12 for F1 - F12) from a function key code. Returns zero if key_code is not a
function key code.
key_code is a numeric keyboard value that is returned by GetKey and KeyFromChar. You can use CharFrom-
Key to convert a key_code into a character.
GetChar ()
Waits for the user to press a key and returns a single character.
GetKey ()
Waits for the user to press a key and returns the key code. The key code is a special numeric value that Source
Insight associates with each key. You can use the CharFromKey function to map a key code into a character.
GetSysTime(fLocalTime)
Returns a SYSTIME record, which contain string representations of the time and date. See “SYSTIME Record”
on page 393.
If fLocalTime is non-zero, then the local time is returned, otherwise the system time (expressed in Coordi-
nated Universal Time (UTC)) is returned.
IsAltKeyDown (key_code)
Returns TRUE if the ALT key is down for key_code. key codes contain the CTRL and ALT key state.
key_code is a numeric keyboard value that is returned by GetKey and KeyFromChar. You can use CharFrom-
Key to convert a key_code into a character.
IsCtrlKeyDown (key_code)
Returns TRUE if the CTRL key is down for key_code. key codes contain the CTRL and ALT key state.
key_code is a numeric keyboard value that is returned by GetKey and KeyFromChar. You can use CharFrom-
Key to convert a key_code into a character.
IsFuncKey (key_code)
Returns TRUE if key_code is a function key, or FALSE if not.
key_code is a numeric keyboard value that is returned by GetKey and KeyFromChar. You can use CharFrom-
Key to convert a key_code into a character.
Msg (s)
Display a message window showing the string s. The message box has a Cancel button that the user can click
to stop the macro.
StartMsg (s)
Display a message window showing the string s. The message box has a Cancel button that the user can click
to stop the macro. The message window stays up after returning.
BufListCount ()
This function returns the number of buffers in the buffer list. Use BufListItem to access the buffer handle at a
particular index position.
BufListItem (index)
This function returns the buffer handle at the given index. The size of the buffer list is returned by BufList-
Count. Index values start at zero, and continue up to one less than the value returned by BufListCount.
AppendBufLine (hbuf, s)
Appends a new line of text s to the file buffer hbuf.
ClearBuf (hbuf)
Empties the buffer hbuf so that it contains no lines.
CloseBuf (hbuf)
Closes a file buffer. Hbuf is the buffer handle.
GetBufHandle (filename)
Returns the handle of the open file buffer whose name is filename. This function searches all open file buffers
to find the one that matches the given filename parameter. GetBufHandle returns hNil if no buffer can be
found with the given file name.
GetBufLineCount (hbuf)
Returns the number of lines of text in a file buffer. Hbuf is the file buffer handle.
GetBufLnCur (hbuf)
Returns the current line number of the user's selection inside of the file buffer hbuf. A macro error is gener-
ated if the given file buffer is not already displayed in a source file window.
GetBufName (hbuf)
Returns the name of the file associated with a file buffer. Hbuf is the file buffer handle.
GetBufProps (hbuf)
Returns a Bufprop record, which contains properties for the given buffer. See “Bufprop Record” on page 389.
GetBufSelText (hbuf)
Returns the selected characters in the file buffer hbuf as a string. A maximum of one line of text is returned.
This is useful for getting the text of a word selection. A macro error is generated if the given file buffer is not
already displayed in a source file window.
GetCurrentBuf ()
Returns a handle to the current buffer. The current buffer is the file buffer that appears in the front-most
source file window. Returns hNil if there is no current buffer (i.e. no open source file windows).
IsBufDirty (hbuf)
Returns True if the buffer is dirty. A dirty buffer is one that has been edited since it was opened or saved. A
dirty buffer contains changes that have not been saved.
IsBufRW (hbuf)
Return True if the given buffer is read-write-able. This function returns False if the buffer is read-only.
NewBuf (name)
Creates a new empty file buffer and returns a handle to the file buffer (an hbuf). The name of the new buffer is
specified by the name parameter. NewBuf returns hNil if the buffer could not be created due to errors.
OpenBuf (filename)
Opens a file named filename into a file buffer and returns a handle to the file buffer. OpenBuf returns hNil if
the file could not be opened.
OpenMiscFile (filename)
Opens a file named filename. The action taken depends on the type of files opened. For example, opening a
file with a .CF3 extension will load a new configuration file. Opening a project file (.PR extension) will open
that project. OpenMiscFile returns TRUE if it was successful, or FALSE if not.
SaveBuf (hbuf)
Saves a file buffer to disk. Hbuf is the buffer handle.
SetBufSelText (hbuf, s)
Replaces the currently selected characters in the file buffer hbuf with the string s. This is useful for replacing
the text of a word selection. A macro error is generated if the given file buffer is not already displayed in a
source file window.
This is the simplest way to insert new text into a buffer. For example, this code inserts "new text" into the cur-
rent buffer at the current insertion position:
hbuf = GetCurrentBuf()
SetBufSelText(hbuf, "new text")
SetCurrentBuf (hbuf)
Sets the active file buffer to the buffer whose handle is hbuf. The current buffer is the file buffer that appears
in the front-most source file window.
GetEnv (env_name)
Returns the value of the environment variable given in env_name. Returns an empty string if the environ-
ment variable does not exist.
GetReg (reg_key_name)
Returns the value associated with the registry key named reg_key_name. The key value is stored under the
key path: HKEY_CURRENT_USER/Software/Source Dynamics/Source Insight/4.0. Returns an empty string if
the key does not exist.
The SetReg and GetReg functions give you a way to store your own Source Insight related information
between sessions.
IsCmdEnabled (cmd_name)
Returns TRUE if the command specified in cmd_name is currently enabled. A command would not be
enabled if Source Insight cannot run it due the state of the program. For example, the Save command is not
enabled if there are no open source file windows.
RunCmd (cmd_name)
Runs the command specified by cmd_name. This allows you to run special commands, namely custom com-
mands, which are defined with the Custom Commands command.
ShellExecute Parameters
Table 5.7: ShellExecute Parameters
Parameter Meaning
sVerb A single word that specifies the action to be taken.
See the table below for possible values.
sFile The filespec parameter can be any valid path. Use
double quotes around complex path names with
embedded spaces. It can also be the name of an exe-
cutable file.
sExtraParams Optional parameters: It specifies the parameters to
be passed to the application that ultimately runs . The
format is determined by the verb that is to be invoked,
and the application that runs.
sWorkingDir The working directory when the command runs. If
empty, then the project home directory is used.
windowstate An integer that specifies the size and state of the win-
dow that opens. Valid values are: 1 = normal, 2 = mini-
mized, 3 = maximized.
sVerb Values
The sVerb parameter is a single word string that specifies the action to be taken by Shell Execute.
Table 5.8: Values for sVerb Parameter
sVerb Value Meaning
edit Opens an editor for the file.
explore The function explores the folder specified.
open The function opens the file specified. The file can be
an executable file or a document file. It can also be a
folder.
print The function prints the document file specified. If
filespec is not a document file, the function will fail.
properties Displays the file or folder's properties.
find Launches the Find Files application found on the Start
menu.
"" (empty string) Ships this parameter to ShellExecute.
Examples:
To browse a web site:
ShellExecute("open", "http://www.somedomain.com", "", "", 1)
To open a document file:
ShellExecute("open", "somefile.doc", "", "", 1)
To explore your Windows documents file folder:
ShellExecute("explore", "C :\Documents and Settings", "", "", 1)
To launch Internet Explorer:
ShellExecute("", "iexplore", "", "", 1)
To preview a file in Internet Explorer:
ShellExecute("", "iexplore somefile.htm", "", "", 1)
To search for files in the current project folder:
ShellExecute("find", filespec, "", "", 1)
WndListCount ()
This function returns the number of windows in the window list. Use WndListItem to access the window han-
dle at a particular index in the list.
WndListItem (index)
This function returns the window handle at the given index. The size of the window list is returned by
WndListCount. Index values start at zero, and continue up to one less than the value returned by WndList-
Count.
This example enumerates all the open window handles:
cwnd = WndListCount()
iwnd = 0
while (iwnd < cwnd)
{
hwnd = WndListItem(iwnd)
// … do something with window hwnd
iwnd = iwnd + 1
}
Window Functions
Window functions allow manipulation of source file windows. File buffers are displayed in source windows.
An hwnd is typically a small integer value. An hwnd of hNil indicates an error.
The functions use window handle (hwnd) parameters. These are macro-level handles to open source file win-
dows. Note that a macro hwnd is similar in concept, but is not exactly the same as a window handle HWND in
the Microsoft Windows API.
Each source window has a selection in it, which describes what characters are selected. See “GetWndSel
(hwnd)” on page 405 for more information.
In some functions, a window handle (hwnd) can also represent a handle to a system level window, such as
the application window. System level windows do not contain a file buffer, or a selection. The GetApplica-
tionWnd function returns a handle to the Source Insight application window.
CloseWnd (hwnd)
Closes the window hwnd. Closing a window does not close the file buffer displayed in the window.
GetApplicationWnd ()
Returns a window handle to the Source Insight application window.
Note: This is not the same as a system-level window handle. It is a Source Insight macro-level handle value.
The returned handle can be passed to functions that do not assume a file buffer or selection, such as
GetWndDim and IsWndMax.
GetCurrentWnd ()
Returns the handle of the active, front-most source file window, or returns hNil if no windows are open.
GetNextWnd (hwnd)
Returns the next window handle in the window Z order after hwnd. This is usually the previous window that
was active. GetNextWnd returns hNil if there are no other windows.
For example, if hwnd is the top-most window, then GetNextWnd(hwnd) will return the next window down.
Note that if you are using SetCurrentWnd to set the front-most active window, subsequent calls to GetNex-
tWnd are affected.
GetWndBuf (hwnd)
Returns the handle of the file buffer displayed in the window hwnd.
GetWndClientRect (hwnd)
Returns a Rect record, which contains the client rectangle of the given window. The coordinates are given in
the window's local coordinate system. The client rectangle does not include the window's frame or other
non-client areas. See “Rect Record” on page 391.
GetWndDim (hwnd)
Returns a DIM record, which describes the pixel dimension of the given window hwnd. See “DIM Record” on
page 390.
The horizontal dimension returned is the width of the text area of the window only. It does not include the
left margin or the symbol window attached to the source window.
GetWndHandle (hbuf)
Returns a window handle for the front-most window that displays the file buffer specified by hbuf. GetWnd-
Handle returns hNil if the file buffer is not in a window.
Since a file buffer may appear in more than one window, GetWndHandle searches through all windows in
front-to-back order. So if the specified file buffer is the current buffer in the active window, the handle for
that window is always returned.
GetWndHorizScroll (hwnd)
Returns the horizontal scroll state of the window hwnd. The horizontal scroll state is the pixel count of the
scroll.
GetWndLineCount (hwnd)
Returns the vertical size of the window hwnd in lines. This is the maximum number of lines potentially visible
in the window. If the file buffer does not fill the entire window, GetWndLineCount will still return the maxi-
mum number of lines.
This function allows you to measure the width of characters in a given window. Since the font used by each
window is determined by the file's document type, the width of text can vary from window to window. Syntax
formatting also affects the width of text.
This function can be used along with ScrollWndHoriz to scroll a window to show a particular character.
Examples
To find the width of the whole line at line 100:
dim = GetWndLineWidth(hwnd, 100, -1)
Msg ("Line 100 is " # dim.cxp # " pixels wide.")
GetWndParent (hwnd)
Returns the handle to the window's parent window. Returns hNil if there is no parent.
GetWndRect (hwnd)
Returns a Rect record, which contains the screen rectangle coordinates of the given window. The rectangle
includes the window frame and non-client areas. See “Rect Record” on page 391.
GetWndSel (hwnd)
Returns the selection state of the window specified by hwnd. The selection state is returned in a Selection
record. See “Selection Record” on page 392.
GetWndSelIchFirst (hwnd)
Returns the index of the first character in the selection in the window hwnd.
GetWndSelIchLim (hwnd)
Returns the index of one past the last character in the selection in the window hwnd.
GetWndSelLnFirst (hwnd)
Returns the first line number of the selection in the window hwnd.
GetWndSelLnLast (hwnd)
Returns the last line number of the selection in the window hwnd.
GetWndVertScroll (hwnd)
Returns the vertical scroll state of the window hwnd. The vertical scroll state is the line number that appears
at the top of the window.
Inputs:
Parameter Description
hwnd The window.
ln The line number that contains the text to be mea-
sured. If ln is out of range, then –1 is returned.
xp The x-position, which is relative to the left edge of
the whole window. If xp exceeds the width of the
line, then the total number of characters on the line
is returned.
Note: You can use the XposFromIch function to perform the reverse mapping.
IsWndMax (hwnd)
Returns TRUE if the window hwnd is currently maximized.
IsWndMin (hwnd)
Returns TRUE if the window hwnd is currently minimized.
IsWndRestored (hwnd)
Returns TRUE if the window hwnd is currently not maximized and not minimized.
Note: You can use the YposFromLine function to perform the reverse mapping.
MaximizeWnd (hwnd)
Maximizes (or "zooms") the window specified by hwnd.
MinimizeWnd (hwnd)
Minimizes (or "iconizes") the window specified by hwnd.
NewWnd (hbuf)
Creates a new window and displays the file buffer hbuf in the window. NewWnd returns a window handle, or
hNil if errors.
SetCurrentWnd (hwnd)
Sets the front-most active window. Hwnd is the window handle to activate.
ToggleWndMax (hwnd)
Toggles the window hwnd between maximized and restored sizes.
Inputs:
Parameter Description
hwnd The window.
ln The line number that contains the text to be mea-
sured. If ln is out of range, then –1 is returned.
ich The character index, which is the zero based index of
a character on the specified line. If ich exceeds the
number of characters on the line, then the x position
of the end of the line is returned.
Note: You can use the IchFromXpos function to perform the reverse mapping.
Note: You can use the LineFromYpos function to perform the reverse mapping.
Bookmark Functions
All bookmarks are kept in a single bookmark list. You can use the bookmark functions to enumerate through
all bookmarks, and to add and remove bookmarks. The bookmark list is persisted in the workspace file.
BookmarksCount ()
This function returns the number of bookmarks in the bookmark list. Use BookmarksItem to access the
bookmark at a particular index in the list.
BookmarksDelete (name)
Deletes the bookname named name.
BookmarksItem (index)
This function returns the bookmark at the given index. The size of the bookmark list is returned by Book-
marksCount. Index values start at zero, and continue up to one less than the value returned by Bookmarks-
Count.
This example enumerates all the bookmarks:
cmark = BookmarksCount()
imark = 0
while (imark < cmark)
{
bookmark = BookmarksItem(imark)
// … do something with bookmark
imark = imark + 1
}
See “Bookmark Record” on page 389.
BookmarksLookupName (name)
Searches for the bookmark named name.
Returns a Bookmark record or nil if the bookmark is not found. See “Bookmark Record” on page 389.
SymListCount ()
This function returns the number of symbols in the symbol list. Use SymListItem to access the symbol record
at a particular zero-based index in the list. See “Symbol Record” on page 392.
SymListFree (hsyml)
This function deallocates the given symbol list.
SymListNew ()
Allocates a new, empty symbol list. Returns the new symbol list handle, or hNil if errors. You should call Sym-
ListFree when you are finished with the symbol list.
Symbol Functions
Symbol functions allow you to access Source Insight's symbol lookup engine. Source Insight maintains sym-
bolic information about your project in a symbol database. These symbol functions make use of the symbol
database and Source Insight's built-in language parsers to locate symbols in your source files.
You may want to review the section "Symbols and Projects" in the "Projects" chapter for a description of how
Source Insight maintains symbolic information and what the lookup rules are.
Symbol Record
The Symbol record describes a symbol declaration. It specifies the location and type of a symbol. It is used to
uniquely describe a symbol in a project, or in an open file buffer.
Symbol records are returned by several functions, and Symbol records are used as input to several functions.
See “Symbol Record” on page 392.
GetBufSymCount(hbuf)
Returns the number of symbols declared in the buffer hbuf. Returns zero if no symbols are declared, or if the
file could not be processed, or if the document type for the file does not specify a language parser.
GetBufSymLocation(hbuf, isym)
Returns the Symbol record of the symbol indexed by isym in the buffer hbuf. Each parsed file buffer main-
tains an index of symbols defined in it. The index is sorted by symbol name. Symbol index values start at zero
and go up to the count returned by GetBufSymCount minus one. This function maps a symbol index (isym)
into a symbol Symbol record.
See “Symbol Record” on page 392.
GetBufSymName(hbuf, isym)
Returns the name of the symbol indexed by isym in the buffer hbuf. Each parsed file buffer maintains an
index of symbols defined in it. The index is sorted by symbol name. Symbol index values start at zero and go
up to the count returned by GetBufSymCount minus one. This function maps a symbol index (isym) into a
symbol name.
This example iterates through all file buffer symbols:
isymMax = GetBufSymCount (hbuf)
isym = 0
while (isym < isymMax)
{
symname = GetBufSymName (hbuf, isym)
...
isym = isym + 1
}
GetCurSymbol ()
Returns the name of the symbol where the current selection is. The current selection is the selection (or cur-
sor position) in the active window. GetCurSymbol returns an empty string if no symbol is found.
GetSymbolLine (symbol_name)
Returns the line number of the symbol named symbol_name. If multiple symbols are defined with the same
name, then the user will be able to select the appropriate one.
GetSymbolLocation (symbol_name)
Returns the location of the symbol name specified in symbol_name. The location is returned in a Symbol
record. An empty string is returned if the symbol is not found. See “Symbol Record” on page 392.
This function performs a look up operation the same way that Source Insight looks up symbols when you use
the Jump To Definition command. If the symbol is not found in the current project, or any open file, then all
the projects on the project symbol path are searched as well. If more than one declaration is found for
symbol_name, then the user is presented with a multiple-definition list to select from.
You can also call GetSymbolLocationEx for more control over how the lookup operation is performed, and to
locate multiple definitions of the same symbol name.
This example looks up the definition of a symbol and displays its source file and line number.
symbol = Ask("What symbol do you want to locate?")
loc = GetSymbolLocation(symbol)
if (loc == "")
Msg (symbol # " was not found")
else
Msg (symbol # " was found in " # loc.file #
" at line " # loc.lnFirst)
For example:
loc = GetSymbolLocation("simple.c")
fullfilename = loc.file
// fullfilename could be something like "d:\proj\simple.c"
JumpToLocation (symbol_record)
Jumps to the location given in symbol_record. This opens the file in the Symbol record and moves the cursor
to the symbol defined there. This works the same way as the Jump To Definition command.
The Symbol record is returned by the GetSymbolLocation function. See “Symbol Record” on page 392.
JumpToSymbolDef (symbol_name)
Jumps to the definition of the symbol named symbol_name. This opens a file and moves the cursor to the
symbol defined there. This works the same way as the Jump To Definition command.
SymbolChildren (symbol)
Returns a new symbol list handle containing the children of the given symbol. The children of a symbol are
the symbols declared within the body of the symbol. For example, the children of a class are the class mem-
bers.
symbol contains a Symbol record. See “Symbol Record” on page 392.
You should call SymListFree to free the symbol list handle returned by SymbolChildren.
You can use the Symbol List functions to access the symbol list returned by this function.
Example
This example looks up the definition of a symbol and displays its children:
symbolname = Ask("What symbol do you want to locate?")
symbol = GetSymbolLocation(symbolname)
if (symbol == nil)
Msg (symbolname # " was not found")
else
{
hsyml = SymbolChildren(symbol)
cchild = SymListCount(hsyml)
ichild = 0
while (ichild < cchild)
{
childsym = SymListItem(hsyml, ichild)
Msg (childsym.symbol # " was found in "
# childsym.file # " at line " # childsym.lnFirst)
ichild = ichild + 1
}
SymListFree(hsyml)
}
SymbolContainerName (symbol)
Returns the container component of the symbol's name.
symbol contains a Symbol record. See “Symbol Record” on page 392.
Every symbol name is divided into path components, which are separated by dot (.) characters. For example,
a symbol name might be "myclass.member1". In this example, "member1" is contained by "myclass".
SymbolDeclaredType (symbol)
Returns a Symbol record of the declared type of the given symbol.
symbol contains a Symbol record. See “Symbol Record” on page 392.
SymbolLeafName (symbol)
Returns the "leaf", or right-most component of the symbol's name.
symbol contains a Symbol record. See “Symbol Record” on page 392.
Every symbol name is divided into path components, which are separated by dot (.) characters. For example,
a symbol name might be "myclass.member1". In this example, "member1" is contained by "myclass".
SymbolParent (symbol)
Returns a Symbol record of the parent of the given symbol. The parent of a symbol is the symbol that con-
tains it.
SymbolRootContainer (symbol)
Returns the root, or left-most component of the symbol's name.
symbol contains a Symbol record. See “Symbol Record” on page 392.
Every symbol name is divided into path components, which are separated by dot (.) characters. For example,
a symbol name might be "myclass.member1". In this example, "member1" is contained by "myclass".
SymbolStructureType (symbol)
Returns a Symbol record of the structural type of the given symbol. The structural type is the struct or class
type of the symbol, which may be indirectly referenced through typedefs.
symbol contains a Symbol record. See “Symbol Record” on page 392.
Searching Functions
These functions search for references to words and patterns.
Project Functions
Project functions allow you to open and close projects, and get project information.
AddFileToProj(hprj, filename)
Adds the given filename to the project hprj.
CloseProj (hprj)
Closes the project hprj.
DeleteConditionVariable(hprj, szName)
Deletes a new conditional parsing variable used to evaluation conditional statements such as #if while pars-
ing code.
Hprj is a handle to the project. If hprj is hNil, then the variable is deleted from the global condition list.
The name of the variable is given in szName.
There are two condition lists: the global list and the project-specific list. When you open a project, the two
lists are merged, with the project-specific list taking precedence over entries in the global list.
See also “AddConditionVariable(hprj, szName, szValue)” on page 415.. See “Conditional Parsing” on page 60.
DeleteProj (proj_name)
Delete the project named in proj_name. If that project is currently open, then the user is asked if they want to
close it first. If the user does not close the project, then the project is not deleted.
EmptyProj ()
Empties the project by removing all files from the project. The actual files themselves are not affected.
Returns True if successful, or False if errors.
GetCurrentProj ()
Returns the handle (hprj) of the currently open project. Source Insight only allows the user to open a single
project at a time; however from the macro language, more than one project can be open.
GetProjDir (hprj)
Returns the source directory path of the project hprj.
GetProjFileCount (hprj)
Returns the number of files added to the project hprj.
GetProjName (hprj)
Returns the name of the project hprj. The name contains the full path of the project file.
GetProjSymCount (hprj)
Returns the number of symbols in the project hprj.
NewProj (proj_name)
Creates a new project and returns a project handle (hprj), or returns hNil if errors.
OpenProj (proj_name)
Opens the project named proj_name and returns a project handle (hprj), or hNil if errors.
RemoveFileFromProj(hprj, filename)
Removes the given filename from the project hprj. The file on disk is not altered or deleted.
SyncProj (hprj)
Synchronizes the project hprj. All files in the project are checked for external changes and Source Insight's
symbol database is updated incrementally for files that have changed.
DumpMacroState (hbufOutput)
This function appends text describing the current state of the running macro to the buffer hbufOutput. The
macro state consists of the values of all variables, and the execution stack. This function is useful when
debugging macros.
GetProgramEnvironmentInfo ()
Returns a ProgEnvInfo record, which contains information about the environment where Source Insight is
running. See “ProgEnvInfo Record” on page 390.
GetProgramInfo ()
Returns a ProgInfo structure, which contains information about Source Insight. See “ProgInfo Record” on
page 391.
Debugging
Source Insight does not contain a debugger for macros. However, since macros are interpreted, you can eas-
ily figure out what's going on by using the "Msg" function at strategic points in your code to output strings
and variable values. See “Msg (s)” on page 397.
To begin executing a macro statement at the current cursor position, use the Run Macro. Just put the inser-
tion point on the line you want to start running at and invoke the Run Macro command.
You can dump the execution stack and variable state of a running macro by calling the DumpMacroState
function. See “DumpMacroState (hbufOutput)” on page 418.
Persistence
Global variables are preserved between runs, but not between sessions. Local variables are not preserved
between runs or sessions. However, you can preserve values by storing them in a file, or writing and reading
registry keys.
No Self-Modifying Macros
Make sure that a macro is not modifying itself while running. Source Insight will abort any macro that
attempts to edit a file containing a running macro.
Sample Macros
A macro file is in included with Source Insight called "utils.em". This file contains some useful functions and
you may want to look at it to see some examples.
Event Handlers
An event handler is a function written in Source Insight's macro language that gets called when specific
events occur. For more, see Chapter 6 "Macro Event Handlers" on page 421.
This chapter describes event handler functions that are written in the Source Insight macro language. An
event handler is a function that gets called when specific events occur. This chapter assumes you are familiar
with the macro language rules and syntax.
Application Events
event AppStart()
event AppShutdown()
event AppCommand(sCommand)
Document Events
event DocumentNew(sFile)
event DocumentOpen(sFile)
event DocumentClose(sFile)
event DocumentSave(sFile)
event DocumentSaveComplete(sFile)
event DocumentChanged(sFile)
event DocumentSelectionChanged(sFile)
Project Events
event ProjectOpen(sProject)
event ProjectClose(sProject)
Statusbar Events
event StatusbarUpdate(sMessage)
Note: For security reasons, you cannot run the Enable Event Handlers command from a macro.
Application Events
Application events apply to the Source Insight application as a whole.
event AppStart()
Called after the Source Insight application loads and initializes. The current project and workspace session is
already loaded.
event AppShutdown()
Called just before the Source Insight application exits.
event AppCommand(sCommand)
Called just after the given user-level command has executed.
Document Events
Document events apply to when file buffers are opened, closed, saved, or modified.
event DocumentNew(sFile)
Called just after the given file buffer is created. The file name is sFile.
event DocumentOpen(sFile)
Called just after the file buffer is opened. The file name is sFile.
event DocumentClose(sFile)
Called just after the file buffer is closed. The file name is sFile.
event DocumentSave(sFile)
Called just before the file buffer is saved. The file name is sFile. You can make edits to the file buffer at this
point just before it gets saved. If you want to do something after the file is saved, then you can use the Docu-
mentSaveComplete event.
event DocumentSaveComplete(sFile)
Called just after the file buffer is saved. The file name is sFile. If you want to get control before the file is
saved, then you can use the DocumentSave event.
event DocumentChanged(sFile)
Called when the file buffer is edited by the user. The file name is sFile. This event is handled asynchro-
nously. That is, it is not called as the user is typing. It is called after a moment of idleness. This allows you edit
the file inside this event handler. Note because this function is called asynchronously, it is possible the sFile
file may not be open, so you need to test the return value of GetBufHandle(sFile) to make sure it is not
hNil.
event DocumentSelectionChanged(sFile)
Called when the user selects text, or moves the cursor in the current file. The file name is sFile. This event is
handled asynchronously. That is, it is not called as the user moves the cursor. It is called after a moment of
idleness. Note because this function is called asynchronously, it is possible the sFile file may not be open,
so you need to test the return value of GetBufHandle(sFile) to make sure it is not hNil.
Project Events
Project Events apply to opening and closing Source Insight projects.
event ProjectOpen(sProject)
Called after the project is opened.
event ProjectClose(sProject)
Called before the project is closed.
Statusbar Events
Statusbar events occur when the statusbar text changes.
event StatusbarUpdate(sMessage)
Called when the contents of the statusbar changes. This event is handled asynchronously. That is, it is not
called at the exact moment the statusbar changes. It is called after a moment of idleness. This allows you
edit the file inside this event handler.
using Search Results window 106 expanding text variables in text 203
using source links 106 files 156
Searching and Replacing Text 104 folder for storing 155
Searching Options 329 in auto-completion list while typing 177
Searching, wildcards 109 in clips 171
See "File Type Options" on page 152. 73 inserting when typing 176
See “Document Options” on page 152. 73 managing list of 340
Select All 332 overview 98
Select Block 332 project vs global 100
Select Char Left 332 setting options 100
Select Char Right 333 text variables 98
Select Function or Symbol 333 Sort Symbol Window 342
Select Line 333 Sort Symbols By Line 342
Select Line Down 333 Sort Symbols by Name 342
Select Line Up 333 Sort Symbols By Type 342
Select Match 333 Source Control Commands 68
Select Next Window 333 Source Control Toolbar 69
Select Sentence 333 Source Dynamics on the Web 343
Select Symbol 333 Source File Windows 26
Select To 333 Source Insight Concepts 39
Select To End Of File 334 Source Links 106, 108
Select To Top Of File 334 creating 108
Select Word 334 parsing 272
Select Word Left 334 with compiler errors 229
Select Word Right 334 with search output 230
Selecting Source Links from Custom Command Output 108
a paragraph of text 119 spaces
a whole line 119 lining up with mono font view 263
between lines 119 making visible 218
matching parentheses and blocks 119 Spacing, the Space-Width Character 198
the enclosing block 119 Special Language Options 244
the whole file 119 Specifying a Project to Open 134
whole functions or symbols 118 Specifying File Arguments 132
whole words 118 Speeding Up
Selection Commands 116 auto-completion 151
Selection History 334 building and synchronizing projects 151
Selection Record 392 lookup references 152
Selection Shortcuts 118 program features 149
Selections relation windows 151
extending 117 searching files 151
SetBufDirty function 400 syntax formatting 149
SetBufIns function 400 typing in browse dialog boxes 150
SetBufSelText function 400 splash screen, suppressing 135
SetCurrentBuf function 400 Start Recording 343
SetCurrentWnd function 407 StartMsg function 397
SetReg function 401 Stop Recording 343
SetSourceLink function 415 Storing Configuration Parts in Separate Files 141
Settings Folder 221 strictvars mode 380
Settings folder 155 strlen function 394
Setup HTML Help 335 strmid function 394
Setup WinHelp File 335 strtrunc function 394
SetWndRect function 407 Style Properties 343
SetWndSel function 407 Style Properties Dialog Box 344
ShellExecute Commands 187 Styles
ShellExecute function 401 and syntax formatting 78
Show Clipboard 335 applied to source code 80
Show File Status 335 changing properties 88
Showing Declarations and Definitions 92 comment headings 85, 359
Simple Tab 336 defining with Style Properties 343
Smart Beginning of Line 336 for declarations 82
Smart End of Line 336 for inactive code 84
Smart Indent Options 219 for language elements 358
Smart Rename 336 for mono font view 263
Smart Renaming 76, 106 for references 83
Smart Tab 337 formatting properties 343
Smart Tab Examples 337 how they work 80
Snippet Properties 339 mapped from language keywords 82
Snippet Window 340 parent styles 81
Snippet Window Options 341 single and multi line comment styles 86
Snippets Styles for Custom Parsing Symbols 251
allow in auto-completion list 340 Suppressing New Program Instances 133
allow in file type options 218 Suppressing the Splash Screen 135
complete when typing 176 Switching Off Syntax Formatting Temporarily 89
editing 339 Syllable Matching 66
X
XposFromIch function 407
Y
YdimFromLine 408
YposFromLine 408
Z
Zoom Window 373