Source Insight 4.0 User Guide Insight4User
User Manual:
Open the PDF directly: View PDF .
Page Count: 434
Source Insight 4.0
User Guide
Copyright © 2017 by Source Dynamics, Inc.
2.26.2017
Source Insight 4 User Guide
1
Chapter i
2
Source Insight 4 User Guide
Source Insight - Version 4
Copyright © 1987-2017 by Source Dynamics, Inc.
This documentation and the software described in it are copyrighted with all rights reserved. Under the
copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine readable form, in whole or in part, without the prior
written consent of Source Dynamics, Inc.
Disclaimer of Warranties and Limitation of Liabilities
This manual and the software described in it were prepared by Source Dynamics, Inc., and are subject to
change without notice. Source Dynamics, Inc. assumes no liability resulting from any inaccuracy or omissions contained herein or from the use of the information or programs contained herewith.
Source Dynamics, Inc. makes no expressed or implied warranty of any kind with regard to these programs or
to the supplemental documentation in this manual. In no event shall Source Dynamics, Inc. be liable for incidental or consequential damages in connection with or arising out of the furnishing, performance, or use of
the program or documentation. This disclaimer includes, but is not limited to, any loss of service, loss of
business, or anticipatory profits, or consequential damages resulting from the use or operation of the
enclosed software.
Source Insight is a trademark of Source Dynamics, Inc.
Other product names are trademarks of their respective manufacturers.
Source Dynamics, Inc.
22525 SE 64th Place, Suite 260
Issaquah, WA 98027
USA
Phone: (425) 557-3630
Fax: (425) 557-3631
Web: sourceinsight.com
Technical Support: support@sourceinsight.com
Sales: sales@sourceinsight.com
Source Insight 4 User Guide
3
Chapter i
4
Source Insight 4 User Guide
CHAPTER 1
GETTING STARTED ...............................................................15
Installing Source Insight ................................................. 15
Activating Source Insight................................................ 16
Compatibility With Old Versions of Source Insight.......... 18
Important Changes From Version 3 ........................................ 19
New Features in Version 4 ............................................... 20
File Format Changes .............................................................. 21
File Storage ............................................................................ 21
CHAPTER 2
USER INTERFACE ..................................................................23
Source File Windows ....................................................... 26
The Overview Scroller............................................................. 27
Symbol Windows ........................................................... 30
Panel Windows................................................................ 31
Docking Panel Windows......................................................... 32
Panel Window Controls .......................................................... 34
Grouping Panel Windows ....................................................... 35
Un-Grouping Panel Windows ................................................. 36
Using Semi-Transparent Panel Windows ................................. 36
Toolbars .......................................................................... 37
CHAPTER 3
FEATURES AND CONCEPTS ....................................................39
Projects ........................................................................... 40
Project Features ..................................................................... 40
Inside a Project....................................................................... 40
The Current Project................................................................. 41
Project Directories .................................................................. 41
Normalized File Names........................................................... 42
Creating a New Project ........................................................... 42
Adding Files to a Project ......................................................... 45
Removing Files from a Project................................................. 46
Using a Master File List ........................................................... 46
Opening and Closing Projects................................................. 47
Removing a Project ................................................................ 47
Copying a Project ................................................................... 48
Read-Only Projects................................................................. 48
Changing Project Settings ...................................................... 48
Symbols and Projects ............................................................. 48
Synchronizing Project Files ..................................................... 48
The Base Project ..................................................................... 49
Creating a Web Version of Your Project.................................... 49
Rebuilding Projects................................................................. 49
Project Windows ............................................................. 50
Project File List ....................................................................... 50
Project Symbol List ................................................................. 51
Project Folder Browser ............................................................ 52
Symbols and Language Parsing...................................... 54
Built-In Languages ................................................................. 54
Custom Languages ................................................................ 54
Source Insight 4 User Guide
5
Chapter ii
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
6
Source Insight 4 User Guide
Previewing Files and Source Code ........................................... 91
Showing Declarations and Definitions.................................... 92
Customizing the Context window .......................................... 92
Relation Window............................................................. 93
Outline and Graph Views........................................................ 93
Relationship Rules.................................................................. 96
Call Graphs ............................................................................ 97
Multiple Relation Windows..................................................... 97
Customizing the Relation Window.......................................... 97
Code Snippets................................................................. 98
Inserting Snippets .................................................................. 98
Text Variables......................................................................... 98
Snippet Options ...................................................................100
Clip Window.................................................................. 101
What Is A Clip? .....................................................................101
Creating a New Clip..............................................................101
Clip Storage .........................................................................101
Bookmarks .................................................................... 102
Setting a Bookmark..............................................................102
Bookmark Storage ...............................................................103
FTP Bookmarks ....................................................................103
Searching and Replacing Text....................................... 104
Searching for Symbol References ..........................................104
Searching the Current File ....................................................104
Searching Multiple Files........................................................105
Replacing Text......................................................................105
Search Results Window ........................................................106
Regular Expressions ...................................................... 109
Regular Expression Elements ................................................109
Multi-Line Matches ..............................................................111
Regular Expression Summary ...............................................111
Comparing Files and Directories................................... 112
Navigation with the Selection History .......................... 114
Go Back and Go Forward commands ...................................114
Scrolling and Selecting Text.......................................... 115
Moving Through a File..........................................................115
Scrolling Commands............................................................115
Selection Commands ...........................................................116
Extending the Selection........................................................117
Selection Shortcuts ..............................................................118
The Overview Scroller...........................................................120
Outlining and Collapsing Text....................................... 121
Outline Toolbar ....................................................................122
Code Beautifier ............................................................. 123
Generating HTML from Project Sources........................ 124
File Encodings............................................................... 125
File Buffer Basics............................................................ 128
Backup Files .........................................................................128
Checkpointing Files ..............................................................129
Reloading and Restoring Files...............................................129
Time stamping.....................................................................129
Recovering From Crashes ............................................. 130
Source Insight 4 User Guide
7
Chapter ii
Recovery Procedure.............................................................. 130
Command Line Syntax.................................................. 132
Specifying File Arguments .................................................... 132
Opening Files....................................................................... 132
Opening Workspaces ........................................................... 133
Command Line Options ....................................................... 133
User-Level Commands .................................................. 136
Custom Commands ...................................................... 137
Customized Settings and Configurations ..................... 138
Customizing the Keyboard and Menus ................................. 138
Changing Screen Colors and Appearance Options ................ 138
Changing Various Options ................................................... 139
The Configuration File.......................................................... 139
Configuration Master File..................................................... 140
Loading a Configuration ...................................................... 142
Saving a Configuration ........................................................ 142
Resetting the Configuration to Defaults................................ 143
Visual Themes ............................................................... 144
Saving Window Arrangements with Layouts ................ 146
Saving and Restoring Workspaces ................................ 147
Performance Tuning ..................................................... 148
Factors That Affect Performance .......................................... 148
Speeding Up Program Features ............................................ 149
Predefined Path Variables ............................................. 153
Files Created by Source Insight ..................................... 154
Files in the Program Directory .............................................. 154
Per-User Data Folder ............................................................ 154
Files Created for Each User ................................................... 154
Files Created for Each Project................................................ 155
CHAPTER 4
COMMAND REFERENCE ...................................................... 157
Commands Overview ................................................... 157
Commands.......................................................................... 157
CHAPTER 5
MACRO LANGUAGE GUIDE ................................................. 373
...........................................................................Macro Functions374
Macro Scopes and References ...................................... 375
Running Macros............................................................ 375
Macros as Commands.......................................................... 375
Running Inline Macro Statements ........................................ 376
Statements.................................................................... 376
Variables ....................................................................... 378
Declaring a Variable ............................................................ 378
strictvars Mode .................................................................... 378
Variable Initialization........................................................... 379
Global Variables .................................................................. 379
Variable Values .................................................................... 380
Expanding Variables in a String ............................................ 380
Variable Arithmetic .............................................................. 381
8
Source Insight 4 User Guide
Indexing Into Strings ............................................................381
Record Variables ..................................................................381
Record Variable Storage .......................................................382
Array Techniques..................................................................382
Special Constants.......................................................... 383
Operators...................................................................... 383
Conditions and Loops: if-else and while ....................... 384
The if Statement...................................................................384
The while statement.............................................................385
Break and Continue..............................................................385
Conditional Evaluation ........................................................385
Naming Conventions .................................................... 386
Standard Record Structures .......................................... 386
Bookmark Record.................................................................387
Bufprop Record ....................................................................387
DIM Record ..........................................................................388
Link Record ..........................................................................388
ProgEnvInfo Record..............................................................388
ProgInfo Record ...................................................................389
Rect Record ..........................................................................389
Selection Record...................................................................390
Symbol Record .....................................................................390
SYSTIME Record ...................................................................391
Internal Macro Functions .............................................. 391
String Functions............................................................ 391
AsciiFromChar (ch)...............................................................391
cat (a, b)...............................................................................391
CharFromAscii (ascii_code) ..................................................391
islower (ch) ..........................................................................392
IsNumber (s).........................................................................392
isupper (ch)..........................................................................392
strlen (s) ...............................................................................392
strmid (s, ichFirst, ichLim) .....................................................392
strtrunc (s, cch).....................................................................392
tolower (s)............................................................................392
toupper (s) ...........................................................................392
User Input and Output Functions ................................. 392
Ask (prompt_string) .............................................................392
AssignKeyToCmd(key_value, cmd_name) ............................392
Beep () .................................................................................393
CharFromKey (key_code) .....................................................393
CmdFromKey(key_value) .....................................................393
EndMsg ().............................................................................393
FuncFromKey (key_code) .....................................................393
GetChar () ............................................................................393
GetKey () ..............................................................................393
GetSysTime(fLocalTime).......................................................393
IsAltKeyDown (key_code) .....................................................393
IsCtrlKeyDown (key_code) ....................................................394
IsFuncKey (key_code) ...........................................................394
KeyFromChar(char, fCtrl, fShift, fAlt) .....................................394
Msg (s) .................................................................................395
StartMsg (s)..........................................................................395
Buffer List Functions ..................................................... 395
BufListCount () .....................................................................395
Source Insight 4 User Guide
9
Chapter ii
BufListItem (index) ............................................................... 395
File Buffer Functions ..................................................... 396
AppendBufLine (hbuf, s) ....................................................... 396
ClearBuf (hbuf) .................................................................... 396
CloseBuf (hbuf) .................................................................... 396
CopyBufLine (hbuf, ln).......................................................... 396
DelBufLine (hbuf, ln) ............................................................ 396
GetBufHandle (filename)...................................................... 396
GetBufLine (hbuf, ln) ............................................................ 396
GetBufLineCount (hbuf) ....................................................... 396
GetBufLineLength (hbuf, ln) ................................................. 396
GetBufLnCur (hbuf).............................................................. 397
GetBufName (hbuf).............................................................. 397
GetBufProps (hbuf) .............................................................. 397
GetBufSelText (hbuf) ............................................................ 397
GetCurrentBuf ()................................................................... 397
InsBufLine (hbuf, ln, s) .......................................................... 397
IsBufDirty (hbuf) .................................................................. 397
IsBufRW (hbuf)..................................................................... 397
MakeBufClip (hbuf, fClip) ..................................................... 397
NewBuf (name).................................................................... 397
OpenBuf (filename).............................................................. 397
OpenMiscFile (filename) ...................................................... 397
PasteBufLine (hbuf, ln) ......................................................... 398
PrintBuf (hbuf, fUseDialogBox)............................................. 398
PutBufLine (hbuf, ln, s) ......................................................... 398
RenameBuf (hbuf, szNewName) ........................................... 398
SaveBuf (hbuf) ..................................................................... 398
SaveBufAs (hbuf, filename) .................................................. 398
SetBufDirty (hbuf, fDirty) ...................................................... 398
SetBufIns (hbuf, ln, ich)......................................................... 398
SetBufSelText (hbuf, s).......................................................... 398
SetCurrentBuf (hbuf) ............................................................ 398
Environment and Process Functions............................. 399
GetEnv (env_name) ............................................................. 399
GetReg (reg_key_name)....................................................... 399
IsCmdEnabled (cmd_name)................................................. 399
PutEnv (env_name, value).................................................... 399
RunCmd (cmd_name).......................................................... 399
RunCmdLine (sCmdLine, sWorkingDirectory, fWait).............. 399
SetReg (reg_key_name, value) ............................................. 399
ShellExecute (sVerb, sFile, sExtraParams, sWorkingDirectory, windowstate)399
Window List Functions.................................................. 401
WndListCount ()................................................................... 401
WndListItem (index)............................................................. 401
Window Functions ........................................................ 401
CloseWnd (hwnd) ................................................................ 402
GetApplicationWnd () .......................................................... 402
GetCurrentWnd () ................................................................ 402
GetNextWnd (hwnd) ............................................................ 402
GetWndBuf (hwnd) .............................................................. 402
GetWndClientRect (hwnd).................................................... 402
GetWndDim (hwnd)............................................................. 402
GetWndHandle (hbuf).......................................................... 402
GetWndHorizScroll (hwnd)................................................... 403
GetWndLineCount (hwnd) ................................................... 403
GetWndLineWidth (hwnd, ln, cch) ........................................ 403
GetWndParent (hwnd) ......................................................... 403
GetWndRect (hwnd)............................................................. 403
10
Source Insight 4 User Guide
GetWndSel (hwnd) ...............................................................403
GetWndSelIchFirst (hwnd) ....................................................403
GetWndSelIchLim (hwnd).....................................................403
GetWndSelLnFirst (hwnd).....................................................404
GetWndSelLnLast (hwnd) .....................................................404
GetWndVertScroll (hwnd).....................................................404
IchFromXpos (hwnd, ln, xp) ..................................................404
IsWndMax (hwnd)................................................................404
IsWndMin (hwnd).................................................................404
IsWndRestored (hwnd) .........................................................404
LineFromYpos (hwnd, ypos) .................................................404
MaximizeWnd (hwnd)..........................................................405
MinimizeWnd (hwnd)...........................................................405
NewWnd (hbuf)....................................................................405
ScrollWndHoriz (hwnd, pixel_count).....................................405
ScrollWndToLine (hwnd, ln)..................................................405
ScrollWndVert (hwnd, line_count) ........................................405
SetCurrentWnd (hwnd) ........................................................405
SetWndRect (hwnd, left, top, right, bottom) ..........................405
SetWndSel (hwnd, selection_record).....................................405
ToggleWndMax (hwnd)........................................................405
XposFromIch (hwnd, ln, ich) .................................................405
YposFromLine (hwnd, ln)......................................................406
YdimFromLine (hwnd, ln) .....................................................406
Bookmark Functions ..................................................... 406
BookmarksAdd (name, filename, ln, ich) ...............................406
BookmarksCount () ..............................................................407
BookmarksDelete (name).....................................................407
BookmarksItem (index) ........................................................407
BookmarksLookupLine (filename, ln)....................................407
BookmarksLookupName (name)..........................................407
Symbol List Functions ................................................... 407
SymListCount ()....................................................................407
SymListFree (hsyml) .............................................................407
SymListInsert (hsyml, isymBefore, symbolNew) .....................408
SymListItem (hsyml, isym) ....................................................408
SymListNew () ......................................................................408
SymListRemove (hsyml, isym)...............................................408
Symbol Functions ......................................................... 408
GetBufSymCount(hbuf) ........................................................408
GetBufSymLocation(hbuf, isym) ...........................................408
GetBufSymName(hbuf, isym) ...............................................409
GetCurSymbol ()...................................................................409
GetSymbolLine (symbol_name)............................................409
GetSymbolLocation (symbol_name).....................................409
GetSymbolLocationEx (symbol_name, output_buffer, fMatchCase, LocateFiles, fLocateSymbols)..............................................................................410
GetSymbolFromCursor (hbuf, ln, ich) ....................................410
GetSymbolLocationFromLn (hbuf, ln) ...................................410
JumpToLocation (symbol_record) ........................................410
JumpToSymbolDef (symbol_name)......................................411
SymbolChildren (symbol) .....................................................411
SymbolContainerName (symbol)..........................................411
SymbolDeclaredType (symbol) .............................................411
SymbolLeafName (symbol) ..................................................411
SymbolParent (symbol) ........................................................411
SymbolRootContainer (symbol)............................................412
SymbolStructureType (symbol) .............................................412
Searching Functions ..................................................... 412
Source Insight 4 User Guide
11
Chapter ii
GetSourceLink (hbufSource, lnSource) .................................. 412
LoadSearchPattern(pattern, fMatchCase, fRegExp, fWholeWordsOnly)412
ReplaceInBuf(hbuf, oldPattern, newPattern, lnStart, lnLim, fMatchCase, fRegExp, fWholeWordsOnly, fConfirm) .......................................................... 412
SearchForRefs (hbuf, word, fTouchFiles) ............................... 413
SearchInBuf (hbuf, pattern, lnStart, ichStart, fMatchCase, fRegExp, fWholeWordsOnly)413
SetSourceLink (hbufSource, lnSource, target_file, lnTarget)... 413
Project Functions .......................................................... 413
AddConditionVariable(hprj, szName, szValue)...................... 413
AddFileToProj(hprj, filename)............................................... 414
CloseProj (hprj) .................................................................... 414
DeleteConditionVariable(hprj, szName) ............................... 414
DeleteProj (proj_name)........................................................ 414
EmptyProj ()......................................................................... 414
GetCurrentProj ().................................................................. 414
GetProjDir (hprj) .................................................................. 414
GetProjFileCount (hprj) ........................................................ 414
GetProjFileName (hprj, ifile) ................................................. 414
GetProjName (hprj).............................................................. 414
GetProjSymCount (hprj) ....................................................... 415
GetProjSymLocation (hprj, isym) .......................................... 415
GetProjSymName (hprj, isym)............................................... 415
NewProj (proj_name)........................................................... 415
OpenProj (proj_name) ......................................................... 415
RemoveFileFromProj(hprj, filename) .................................... 415
SyncProj (hprj) ..................................................................... 415
SyncProjEx(hprj, fAddNewFiles, fForceAll, fSupressWarnings) 415
Miscellaneous Macro Functions.................................... 416
DumpMacroState (hbufOutput) ........................................... 416
GetProgramEnvironmentInfo ()............................................ 416
GetProgramInfo ()................................................................ 416
Other Information about Macros .................................. 416
Debugging .......................................................................... 416
Persistence........................................................................... 416
No Self-Modifying Macros .................................................... 416
Sample Macros .................................................................... 416
Event Handlers.............................................................. 417
CHAPTER 6
MACRO EVENT HANDLERS ................................................. 419
Macro Event Handlers................................................... 419
Event Handler Uses ....................................................... 420
Adding Event Handlers to Source Insight ..................... 420
Enabling Event Handlers ...................................................... 421
Editing Event Handler Files ................................................... 421
Errors in Event Handlers ....................................................... 421
Synchronous Vs. Asynchronous Events.................................. 421
Helpful Tips for Event Handlers ............................................. 421
Application Events ........................................................ 421
event AppStart() .................................................................. 421
event AppShutdown() .......................................................... 422
event AppCommand(sCommand)........................................ 422
Document Events ......................................................... 422
event DocumentNew(sFile) .................................................. 422
event DocumentOpen(sFile)................................................. 422
12
Source Insight 4 User Guide
event DocumentClose(sFile) .................................................422
event DocumentSave(sFile) ..................................................422
event DocumentSaveComplete(sFile) ...................................422
event DocumentChanged(sFile) ...........................................422
event DocumentSelectionChanged(sFile) .............................422
Project Events ............................................................... 423
event ProjectOpen(sProject) .................................................423
event ProjectClose(sProject)..................................................423
Statusbar Events ........................................................... 423
event StatusbarUpdate(sMessage) .......................................423
Source Insight 4 User Guide
13
Chapter ii
14
Source Insight 4 User Guide
Installing Source Insight
CHAPTER 1
Getting Started
Welcome to Source Insight.
We hope that using Source Insight will increase your productivity and enjoyment of coding. It was created
out of a need to navigate large code bases, and to help understand complex code while working and planning.
Source Insight is being used today by important technology companies to develop some of the largest commercial hardware and software products.
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 smartrename.
•
Dynamic information panels work together to create a productive workflow.
Installing Source Insight
Once Source Insight is installed on a machine, it is available to any user on that machine, but the licensing
differs depending on whether the operation system is a server or not.
On desktop operating systems, Source Insight is licensed per-machine. There is a license stored for the whole
machine. Once installed and activated, you can run Source Insight from any user account on the machine.
On server operating systems (including Terminal Servers), Source Insight is licensed per-user. It must be activated separately for each user, and there is a license stored for each user.
Source Insight 4 User Guide
15
Activating Source Insight
Activating Source Insight
Source Insight requires initial activation over the Internet. The activation process is new to version 4 and we
have designed it to have very low impact on users. Please understand that activation secures your license,
validates your serial number, and allows us to continue developing Source Insight.
When you launch Source Insight the first time, the Manage License window will appear. See “Manage
License” on page 258.You will be prompted to either enter a serial number, or start a new Trial license. A Trial
license runs for 30 days. You do not need a serial number to use a Trial license.
When prompted, please enter your name and email address. Your email address is optional but highly recommended so you will be able to retrieve your license if you should lose it. This also allows us to notify you if
any important updates are available.
Source Insight will then activate your license using our licensing system. After a second or two, your license
will be activated and you won't have to activate again.
When you activate a license, Source Insight sends the information you provided, plus a hardware fingerprint
to our licensing system over a secure SSL connection so we can match the license to the machine. You can
still make most hardware changes without invalidating the installation. We respect your privacy, and we specifically do not share your information with any third party.
If you have any problems or questions about the activation process, please email us at info@sourceinsight.com.
Transferring Your License - Deactivation
If you decide to stop using Source Insight, or want to use your license on a different machine, you should first
deactivate your license on your old machine by selecting Help > Manage License, and selecting "Deactivate
License". This reduces your activation count so that you can activate it on another machine. A single license
gives you up to two machine activations.
If you don’t have access to your old machine anymore (to deactivate it), 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
info@sourceinsight.com
Activation Questions
Q: Can I activate Source Insight more than once?
The Source Insight license allows you to activate Source Insight on up to two machines at the same time, provided that only a single person is using both installations. For example, you can install it on a desktop
machine at work, plus a laptop, or home machine. Therefore you can have up to two machines activated per
license.
If for some reason you activate it on the same machine more than once, it does not count against your two
activation limit.
Q: What if I want to switch to a new machine?
To transfer a license to a new machine, you should first deactivate Source Insight on the old machine by
selecting Help > Manage License, and selecting "Deactivate License". This reduces your activation count so
that you can activate it on another machine. A single license gives you up to two machine activations.
Q: How do I get a serial number?
When you purchase a license, you will be provided with a valid license serial number. It is usually emailed to
you.
16
Source Insight 4 User Guide
Activating Source Insight
Q: How do I start a Trial license?
Launch Source Insight. When the Manage License window appears, select "Begin a Trial", and click Continue.
Q: Do I need a serial number for a Trial license?
You do not need a serial number to begin a Trial license. When you begin a Trial license, a special Trial serial
number will be assigned to you.
Q: How can I transfer my license to a new machine?
To transfer a license to a new machine, you should first deactivate Source Insight on the old machine by
selecting Help > Manage License, and selecting "Deactivate License". Once you deactivate the old machine,
you can activate it on the new machine. Deactivating reduces your activation count so that you can activate
it on another machine without exceeding your activation limit.
When you activate on the new machine, you will need to provide your license serial number. Use the same
serial number as before.
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 info@sourceinsight.com.
Q: What happens if I change my hardware?
It is very unlikely that changing your hardware will invalidate your license activation. If you replace your main
drive, you will have to re-install and activate Source Insight again. Even then, the licensing system allows a
certain number of changes over a period of time. We absolutely do not want you to be stuck if you have a
valid license.
Q: What if I reformat my drive and re-install Source Insight?
When you re-install and run Source Insight, you will be prompted to activate again. However, that is mainly to
refresh the license on your machine, and won’t count as a new activation.
Q: What if I don’t have an Internet connection?
The activation process will defer for a while until you have Internet connectivity, so you can still work with it.
In the event your machine will never have an Internet connection, please contact support@sourceinsight.com.
Q: What network ports does activation use to setup a firewall / proxy?
The activation process uses port 443 (HTTPS) to connect to sls.sourceinsight.com. You can test a connection with a web browser using this URL, which will display "OK":
https://sls.sourceinsight.com/lsstatus/
Note: you must include the trailing slash.
Q: Why does Source Insight require activation?
We have given this long consideration and decided some form of license validation is helpful. Past versions of
Source Insight did not have activation, and that resulted in many illegal licenses being used and even sold to
unsuspecting customers.
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.
Source Insight 4 User Guide
17
Compatibility With Old Versions of Source Insight
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.
Compatibility With Old Versions of Source Insight
If you have used older versions of Source Insight, for example version 3.x, you may find the topics in this section useful.
You can use both Source Insight version 4 and version 3 together on the same machine. They each use separate files and Windows Registry settings, so they will not conflict. The project data file formats are different,
but file extensions are different so they should not conflict.
Opening Projects from Version 3
To open an old version 3.x project, select Project > Open Project... and click the Browse button to locate the
old project .PR file. The old project will be copied into the new format. The original version 3 project will
remain unmodified.
Importing Configuration Settings from Version 3
Source Insight looks for an older version when you first install and run it. If it finds an old configuration file, it
will prompt you to import the settings.
To import version 3 configuration settings at any time, select Options > Load Configuration, and navigate to
your version 3 configuration file. It is usually stored here:
C:\Users\\Documents\Source Insight\GLOBAL.CF3\
where C: is your system drive letter, and is the account user name.
18
Source Insight 4 User Guide
Compatibility With Old Versions of Source Insight
Important Changes From Version 3
In order to make the program easier to understand, a few things have been moved or renamed.
•
What was called "Document Options" in version 3 is now called File Type Options. It contains all filetype specific options. For example, there is a file type named "C/C++ Files". The "Document Type" term
has been replaced with "File Type". See “File Types” on page 72.
•
The C and C++ file types have been merged into just "C/C++ Source File"
•
What was called "Draft View" in version 3 is now called "Mono Font View"
•
What used to be called "symbol syllables" in version 3 is now called "name fragments".
•
Dock-able/Floating windows are now called Panels. Besides the Context and Relation window, there
are a few new panels, such as FTP Browser, Window List, Snippets, Bookmarks, Directory Compare,
and File Compare.
•
Project Files - the new extension is .siproj for the main project file. All the data file formats have
changed from version 3. You can still open version 3 projects, but they will be converted to the new format.
•
The Project Symbol Path idea has been replaced with Project > Import External Symbols. This feature
lets you import symbols from external sources, such as header files, .NET assemblies, and Java jar
files. Each time you import something, Source Insight creates a special "import" project for you. It will
automatically search for symbols there. You can still use the project symbol path if you want. See
“Importing Symbols from Libraries” on page 55.
•
Project Settings now has a "Backup Directory" option. By default, each project gets its own backup
folder under its project folder.
•
All projects share the same configuration settings now. However the configuration file system has
some flexibility when it comes to project-specific configuration parts. See “Customized Settings and
Configurations” on page 138.
Source Insight 4 User Guide
19
New Features in Version 4
New Features in Version 4
Many new features have been added to version 4 of Source Insight. Here are some of the highlights:
•
Improved language parsing for C/C++, C#, Java, and other languages.
•
Language support now built-in for Objective-C, Python, PHP, XML, and JSON files.
•
Imports symbols from external sources, such as .NET assemblies, Java JAR files, and Include files. Use
Project > Import External Symbols to do this. See “Importing Symbols from Libraries” on page 55.
•
File Window tabs appear across the top of the main application window. Right-click on them and
select Window Tab Options to change the sort order.
•
Collapsible code blocks. You can control the position and appearance by selecting Options > Preferences: Windows and refer to the Outline and Nesting section. See “Outlining and Collapsing Text” on
page 121.
•
File and directory comparing (diff). Invoke them from the Tools menu. See “File Compare” on
page 205. See “Directory Compare” on page 191.
•
Code beautifier that works on curly brace languages, such as C/C++ and C#. See “Code Beautifier” on
page 123.
•
Unicode support.
•
New User Interface with Panels and Visual Themes. See “Visual Themes” on page 144.
•
New Overview scroller bar is positioned like a scroll bar, but gives you a bird's eye view of your file. It
works a little different than a scroll bar, but you can use it to scroll. It can show you the boundaries of
the current function and help to orient you within long functions. See “The Overview Scroller” on
page 27.
•
New enhanced vertical scroll bar shows more details within the scroll bar. Right-click on it and select
Scroll Bar Options to play with its settings. See “Scroll Bar Options” on page 321.
•
Multiple window layouts you can switch quickly. Use either View > Load/Save Layout, or click one of
the layout toolbar buttons to quickly switch between 4 different layout presets. See “Saving Window
Arrangements with Layouts” on page 146.
•
Code Snippets - define templates of code to insert. Select Tools > Activate Snippet Window to show the
Snippet panel. Snippets are intended for boiler plate text the you want to insert. You can put text variables in the snippet text that get expanded when you insert the snippet. For example $date$ gets
replaced with the current date. See “Code Snippets” on page 98.
•
Improved bookmarks - book marks are now stored persistently and they are stored as a line offset
from a nearby function or class name. Each project has its own book mark list. See “Bookmarks” on
page 102.
•
Improved Relation window - Reference finding is faster. There is also a new relation type for functions:
"calls and callers". This shows both in the same outline or graph. You can also copy the graph view to
the Window clipboard. See “Relation Window” on page 93.
•
Maintain backup files per-project, and easily compare with backup versions. Use Tools > Compare with
Backup File to quickly compare the current file with a backup version. You can also use the File > Open
Backup File to open an older version of the current file. See “Backup Files” on page 128.
•
Better regular expressions - now supports Perl-compatible and multi-line expressions. Most places
that let you enter a regular expression now have a list where you can select the type of RegEx. There
are regular and "multi-line" versions of the classic Source Insight regex, and Perl compatible regex.
The multi-line regex types basically match a new-line 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.
•
Better support for large projects. The virtual memory usage has been improved so that very large projects can fit better into the memory space. Version 3 could suffer from a file read error on the project
index files for large numbers of symbols, leading to project corruption. This has been eliminated.
•
Easier project management with multiple users and machines by using a Master File List. A project can
have a MFL, which can be a part of your source code repository and shared with other people. It is a
simple text file that lists all the files (and/or directories) in your project. See “Using a Master File List”
20
Source Insight 4 User Guide
New Features in Version 4
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 Format Changes
Several data files created and maintained by Source Insight have changed in version 4.
•
Project Files - the new extension is .siproj for the main project file. All the project data file formats
have changed from version 3. You can still open version 3 projects, but they will be converted to the
new format.
•
Configuration Files - all configuration settings are now saved in XML files. Because the configuration
changed so much, version 3.5 configuration files are not supported.
•
Workspace Files - new extension is .siwork. These are not compatible with version 3.
•
Recovery Files - the new extension is .si_recovery.
File Storage
Source Insight 4 stores most of its data in /users//Documents/Source Insight 4.0
The folders within the "Documents/Source Insight 4.0" folder are as follows:
Table 1.1: Folders & Files In User Document Area
Folder Name
Description
Backup
Stores file backups for nonproject files.
Bookmarks
The "global" bookmarks used
in all projects.
Clips
Clip storage. See Clips feature.
Logs
Log files. Controlled by Options
> Preferences: General : Logging...
Projects
Each project has a data folder
inside this folder.
Settings
Your configuration settings,
themes and layouts.
Snippets
Code Snippets
c.tom file
C/C++ preprocessor token macros.
FileAlias.txt file
Maps file names without extensions to File Types
Source Insight 4 User Guide
21
New Features in Version 4
22
Source Insight 4 User Guide
CHAPTER 2
User Interface
This chapter describes the main Source Insight program window and general information about using different 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
Source Insight 4 User Guide
23
In the screen shot below, the main Source Insight application window contains the main toolbar at the top, a
source file window in the middle, and some panel windows docked to the right side. The symbols declared in
the source file appear on the left in a symbol panel.
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
24
Source Insight 4 User Guide
the left side, and a Relation Window docked to the right edge. The Context window appears docked at the
bottom edge.
Source file
window for
editing and
viewing code
Symbol Window:
shows symbols
defined in each
file
Relation
Window: shows
references, call
trees, and other
relationships
Context
Window:
automatically
shows
declarations and
other
information
while you click
on things or type
For more information:
See “Relation Window” on page 93.
See “Context window” on page 90.
Source Insight 4 User Guide
25
Source File Windows
Source File Windows
Each file you open will display in a separate source file window. Source Insight is a Tabbed Multiple-Document-Interface (MDI) application. Each source file window has a symbol window on the left side. You can hide
this window if you like.
Source file windows
are arranged inside
the frame of the
application window
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.
26
Source Insight 4 User Guide
Source File Windows
Below is a source file window, which has a symbol window attached to the left side, and the optional Overview Scroller control on the right edge of the source window.
Symbol
Window
Text area of source file
Overview Scroller
The Overview Scroller
The Overview scroller is an optional control which appears at the right edge of source file windows, and it
gives you a bird's eye view of your file. It shows a miniature version of your file, and can help to orient you
within a long function or set of functions. You can use it to scroll too.
Source Insight 4 User Guide
27
Source File Windows
To show or hide the Overview scroller, select View > Overview.
You can control several settings for the Overview scroller, such as the magnification level, and what display
elements to show. To set the options for the Overview scroller, right-click on it and select Overview Options.
See “Overview Options” on page 268.
28
Source Insight 4 User Guide
Source File Windows
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.
Source Insight 4 User Guide
29
Symbol Windows
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 displays #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
You can type into
this field to quickly
select items in the
list
Symbol Window:
lists all the symbols
declared in the file.
Each symbol has an
icon to identify its
type. You can click
the icon to drag and
drop whole symbols.
Text area of source
window
Symbol window
toolbar
At the bottom of the Symbol Window is a small toolbar. There are controls for sorting the list. You can rightclick on the Symbol Window to bring up its shortcut menu.
Customizing the Symbol Window
Right click on the Symbol Window and select “Symbol Window Properties” to change its settings. See “Symbol Window Options” on page 350.
Changing the Width of the Symbol Window
To change the width of the Symbol Window, click on the right edge of the window and drag. This will only
resize the current window. If you want to change the size for all other windows, resize it and then right-click
on it and select “Save Settings”
Permanently Changing the Width of the Symbol Window
To permanently change the width of the symbol window, and all future Symbol Windows in other files, resize
the window by dragging the right edge. Then, right-click on the Symbol Window and select “Save Settings”.
30
Source Insight 4 User Guide
Panel Windows
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 window, 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.
A floating panel 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 different panel layouts by selecting View > Load Layout..., or clicking one of the A-D layout buttons in Layout toolbar:
Source Insight 4 User Guide
31
Panel Windows
The panel windows are:
•
Project Symbol List - shows all functions, classes, and other symbols in the project.
•
Project Files List - shows all files in the project.
•
Project File Type List - shows all project files, organized by type.
•
Project Folder Browser - shows the disk and directory structure of a project.
•
Project Symbol Categories - shows all symbols, organized by symbol type.
•
Context window - a context sensitive information window.
•
Clips Window - shows clipboard-like clips for easy copying and pasting.
•
Bookmark Window - shows a list of bookmarked places.
•
Relation Windows - shows call trees, class trees, and other relationships.
•
Snippet Window - manages all code snippets.
•
Window List - shows all the open file buffer windows.
•
FTP Browser - connects to FTP servers.
•
File Compare - shows differences between two files.
•
Directory Compare - shows differences between two directories.
Docking Panel Windows
Panel windows can be docked to any edge of the main application window. They can be stacked horizontally
or vertically. This example shows several panels docked at the side and bottom.
To dock a panel window:
1. Drag it to the edge of the application window, or to the edge of an existing panel window.
2.
32
You can also drag it over an existing panel window to split the panel area in half.
Source Insight 4 User Guide
Panel Windows
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.
A docked panel will
be split if you drag
another panel over
it.
Drag a panel over an
existing docked
panel to split it in
half. Release the
mouse button to
drop and dock the
panel.
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.
Source Insight 4 User Guide
33
Panel Windows
In the example below, the possible docking positions are highlighted:
Panel Window Controls
Each panel window has a set of window-control buttons in the upper right of its frame. A floating panel can
be maximized, or minimized to the Tab Tray area at the bottom of the main window.
Click and drag title bar to move panel.
Double-click to toggle maximize & normal size.
Adjust transparency
Minimize to Tab Tray
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.
34
Source Insight 4 User Guide
Panel Windows
Grouping Panel Windows
Panel windows can be grouped together into a single, tabbed window. In the picture below, the Clips panel is
floating by itself on the left, and three other panels are grouped together into a tabbed panel on the right.
Panel Windows
Grouped Panel Windows - each has a tab
Minimize
Tab Tray appears at the bottom when you minimize a panel window
To group a panel with another panel:
1. Click on the source panel’s title bar and drag and drop it in the tab area of another panel window.
To group two non-grouped panels:
1. Drag the source panel so it hovers over the title bar area of the destination panel. A ghost tab will
appear. Release the mouse button to group the panels.
Source Insight 4 User Guide
35
Panel Windows
Un-Grouping Panel Windows
To un-group a panel:
1. Click and drag on its tab at the top.
2.
Drag it out onto the desktop or other area. The panel will be placed into its own floating panel window.
Using Semi-Transparent Panel Windows
Panel window can be semi-transparent when they are floating. This makes the panel windows a little like a
HUD (Head Up Display) in a game.
Panel transparency is only available if the panel is floating and the "Enable transparent panels" option is
enabled inside the Options > Preferences: Display. See “Display Options” on page 195.
When a panel window is transparent, you can click through it to the text below it, as long as you are not clicking inside an object within the floating window.
36
Source Insight 4 User Guide
Toolbars
To adjust the transparency amount, click on the transparency button in the panel’s window-control toolbar.
Click to adjust transparency
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 chapter for information on each command.
Project Search Bar
The project search bar is used for searching across the whole project. It is a powerful way to perform a keyword based search to find name or word fragments within a given number of lines of context. To show it,
select View > Project Search Bar.
See “Search Project” on page 328.
Source Insight 4 User Guide
37
Toolbars
File Search Bar
The File Search Bar is used to search within the current file. To show it, select View > File Search Bar. Alternatively, you can use Activate Search Bar (Alt+Shift+F) to activate it so you can start typing into it.
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
Save
38
Save All
Print
Source Insight 4 User Guide
CHAPTER 3
Features and Concepts
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 commands. Also, many dialog boxes in Source Insight contain a Help button that opens the help topic for the dialog or command in question.
Source Insight 4 User Guide
39
Projects
Projects
The most powerful features of Source Insight are designed around projects. A Source Insight project is a collection 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.
Figure 3.1 The components of a Source Insight project.
Each project contains a list file paths that point to your source files. A project also contains a symbol database, which is maintained by Source Insight. Your source files are parsed by Source Insight and symbol declarations and definitions, and references are recorded in the symbol database. All you have to do is add source
40
Source Insight 4 User Guide
Projects
files to your project; you do not have to generate any other "tag" files. Source Insight does that automatically.
Each project has its own session workspace. The workspace contains session information, such as the list of
files that are open and window positions.
The Current Project
Each Source Insight instance allows only one project open at a time. You can have multiple instances of
Source Insight running - each of which can have a different project open.
Sometimes Source Insight will open other secondary projects to search for symbol declarations. These are
background projects and you will not be aware that they are opened or closed.
Throughout this documentation, most discussions assume that you have a project open, unless otherwise
stated. Whenever there is a difference in the way a command works with and without a project open, it will
be noted.
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 Documents\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 maintaining 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.
Here is an example of a typical project setup:
Project Data Directory:
C:\Users\John\Documents\Source Insight 4.0\Projects\MyProj
which contains the file MyProj.siproj - the main project file.
Project Source Directory:
c:\work\proj1\src
which contains your source code, possibly including sub-directories of source code.
To edit the project source directory location, use the Project Settings command. See “Project Settings” on
page 284.
Project Source Directory
The project source directory is what you consider the main location of your source files. The project source
directory is typically the topmost, or root directory of your source repository. You might think of this as the
"home" directory of the project. Source Insight normalizes project file names relative to this directory when
it displays file names. You can actually set the source directory to any location on your disk, after the project
is created, by using the Project Settings command. This affects how the source file paths are displayed,
because they are displayed relative to that directory.
See “Where do you want to store the project data files?” on page 264.
Once a project is created in a given directory, you can add files to it from any directory and any drive, including network drives, and UNC paths.
Source Insight 4 User Guide
41
Projects
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.
Normalized File Names
When Source Insight displays a file name and the file is part of a project, it arranges the name and path to
make it easier to see and select the base file name without all the directory paths getting in the way. This process is called normalizing the file name. This is an important feature because many projects have files spread
out across multiple subdirectories; and "flattening" out the directory tree makes it easy to type and select
the most significant part of file names.
A normalized file name always begins with the leaf file name, and it's followed by the directory path in parentheses. Furthermore, the directory path shown is relative to the project's source directory, unless the file is on
a different drive. If the file is on a different drive, or not part of the project source directory tree, then the full
path is displayed in parentheses.
If you prefer not to see file names normalized in the Project Window, you can turn it off by using the Project
Window Properties command and checking the File Directory box to add a separate column to the list for the
directory name.
Here are some examples using the game project discussed above:
If the file path is:
The file name is displayed as:
c:\game\file.c
file.c
c:\game\core\file.c
file.c (core)
c:\game\core\io\file.c
file.c (io)
c:\game\core\enemy\file.c
file.c (core\enemy)
c:\game\presentation\file.c
file.c (presentation)
c:\SomeDir\file.c
file.c (C:\SomeDir)
d:\OtherDir\file.c
file.c (D:\OtherDir)
Creating a New Project
Use the Project > New Project command to create a new project. You must give the project a name and specify where you want Source Insight to store the project data.
42
Source Insight 4 User Guide
Projects
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 project name
Enter the name of your project. Source Insight will create several files that start with this name and have different extensions.
Where do you want to store the project data files?
Enter the full path to the folder where you want to save the project data files that are created by Source
Insight. They can either be in the same folder as your source files, or in a separate location. By default, they
are created under your Source Insight user directory in the Projects folder.
We recommend that your data directory be on a local, non-networked drive for reliability and best performance.
After you answer these two questions, you will be taken to the Project Settings dialog. See “Project Settings”
on page 284.
Where Should You Create A Project?
If you are creating a project for source files that are stored locally on your machine, there should not be any
problem creating the project data files in the same directory as your source files.
If you are creating a project that refers to files on a shared server, or any other place that you do not have permission to write to, then you should create the project data somewhere on your local machine. When the
Project Settings dialog box appears, enter the location of the your source files into the project source directory field.
The folder you specified as the project data directory will become the default project source directory. In the
Project Settings dialog box, you can specify a different path for the project source directory. The project
source directory typically is the path of the topmost directory containing your source files. When Source
Insight displays file names, the files are displayed relative to project source directory. If you point the project
source directory to the directory containing most of your source files, then you will not have to look at a lot of
redundant path information.
In addition, the "Add new files automatically" feature (in Options > Preferences: General) only will add new
files automatically to your project if the files are in the project source directory or a descendant of this directory.
See “Synchronize Files” on page 351., and “Project Settings” on page 284.
Source Insight 4 User Guide
43
Projects
New Project Settings
When you create a project, the New Project Setting dialog opens. See “Project Settings” on page 284.
Setting Index Options for Projects
Name Fragment and Member indexing takes up index space on disk and in memory. It also slows database
access a little bit. You can control what is indexed in the Project Settings dialog box.
Two check boxes control indexing:
Quick browsing for member names
Select this to allow member name indexing. When this option is enabled, you can simply type the member
names of classes or structures, instead of having the type the class or structure name, followed by a dot (.)
and the member name. De-selecting this will save on disk space and memory.
Quick browsing for symbol name fragments
Select this to allow name fragment indexing. When this option is enabled, you can type partial name fragments and find symbols containing those name fragments. Un-checking this will save on disk space and
memory. If your project is large, then Source Insight may operate slowly when browsing, or synchronizing
files with the symbol database.
If both check boxes are turned off, then the Project Symbol List panel filtering will revert to simple prefix
matching. However, the Symbol Window on the left side of each source window, and the Project Window file
list will still allow name fragment browsing.
44
Source Insight 4 User Guide
Projects
Adding Files to a Project
After you create a project, you next need to add source files to the project. There are several ways to add files.
If you created a new file in Source Insight and save it for the first time, Source Insight will ask you if you want
to add the file to the current project. This will be the most natural way to add a file if you are writing new code
and are creating new source files a lot.
If you already have existing source files and you want to add them to the current project, use the Add and
Remove Project Files command. This command adds any existing files, including whole directory trees, from
anywhere on your disk to the current project. See “Add and Remove Project Files” on page 159., and “Add File
List” on page 162.
You can also add files to the project by dragging files from Windows Explorer and dropping them onto the
Project File List panel. The Project File List panel also allows removing files from 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.
Adding a file to a project has the following effects:
•
The file name is stored in the file name database for the project. Whenever Source Insight displays a
list of files, that file name will be in the list. Therefore, for example, when you use the Open command,
the file name will be in the list box.
•
The file is parsed based on its language type. Symbol definitions are added to the project's symbol
database. The language parser used for each file is determined by its file type. See “File Types” on
page 72.
•
The file's modification date is recorded in the file name database, so that Source Insight will know to
synchronize the project symbol database if the file was modified outside of Source Insight, for example by a source control system.
•
The way the name of the file is displayed is changed. The file name becomes "normalized" to the project's source directory.
•
The file will become part of the project code base, which is searched when showing symbol relations,
such as call trees.
What Files Should You Add to a Project?
Source Insight projects should consist of program source files and text files only. It doesn't make any sense to
add a binary format file to a Source Insight project. For example, adding an exe or bitmap file to your project
would have no benefit.
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.
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.
Adding Remote Network Files to a Project
For whatever reason, you may want to access your source files directly on a network server, not from local
copies of the files. Of course, you are free to open any file on the network directly. However, keep in mind that
you may be locking other people out of the file by having it open, or otherwise causing contention over the
file. In addition, you won't get the benefit of Source Insight's project features unless the remote file is added
to your project.
One way to have a project that refers directly to files on the server is to create a project locally on your workstation and add the files from the remote server to your project using the Add and Remove Project Files com-
Source Insight 4 User Guide
45
Projects
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 relative to your local project data file directory. See “Project Settings” on page 284.
Project Master File List
Instead of adding and removing files manually through the Add and Remove Project Files command, you can
setup a special file called a Master File List and associate that with the current project. For more information,
See “Using a Master File List” on page 46.
Removing Files from a Project
To remove a file from the current project's file list, use the Project > Add and Remove Project Files command.
When a file is removed from a project, all the symbols found in that file are removed from the project's symbol database. Source Insight will not actually delete the file from the disk. See “Add and Remove Project
Files” on page 159.
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.
Using a Master File List
You can use a Master File List to control what source files are in a project. The Master File List is a text file containing the names of each file or directory in the project. To use it, select Project > Project Settings and
enable the Master File List setting.
Although the Master File List (MFL) controls what files are in your project, you can still add or remove files
manually by using Project > Add and Remove Files. When you add or remove a file from your project, the
change will be saved to the MFL. If the MFL contains a file that is not in your project, then it will get added
automatically to your project. If the MFL does not contain a file that is in your project, then it will be removed
from your project automatically.
The Master File List can be a part of your source code repository and shared with other people. It is a simple
text file that lists all the files (and/or directories) in your project. The MFL is maintained as you add or remove
files from your project. If you add or remove files, the changes are saved to the MFL, and when the MFL is
pushed out or checked in, your team members will get the additions or deletions automatically as their
Source Insight syncs up with the MFL.
Master File List Format
Each line in the Master File List should contain a path relative to your project's source directory. It can be a
simple file name, a wildcard, such as open*.c, or a directory name.
If a line item is a directory name, then all the files that match known file types in the directory are included in
the project. Sub-directories and their contents are not included.
Lines that begin with the semi-colon (;) character are comments.
46
Source Insight 4 User Guide
Projects
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.
Generating a Master File List
If you already have a project built and you would like to use a Master File List, select Project > Export Project
File List to create a new file list. Select Project > Project Settings and specify the file list in the Master File List
Path section.
Editing the Master File List
You can edit the Master File List directly by selecting Project > Open Project Master File List. Normally you
would not need to edit it because Source Insight changes it automatically as you add and remove files from
your project. However, you are free to edit it. When you save the file, Source Insight will resynchronize the
project with the new version of the Master File List.
Synchronizing with the Master File List
Source Insight periodically checks to see if the Master File List has changed on disk. It resynchronizes with it
when a change is detected. This can cause new files to be added to the project, or files to be removed from
the project. This is handy if your Master File List is part of your source code repository. For example, if a colleague adds a new file to the project, when you get a new version of the repository, the new source file will be
automatically added to your Source Insight project.
Opening and Closing Projects
To open a different project, use the Project > Open Project command (See “Open Project” on page 266.)
Source Insight only allows you to have one project open at a time, so if you already have a project open, it will
ask you if you're sure you want to close the current project and save any changes to files. Assuming you do
close the current project, the Open Project command will display a list box of existing projects from which to
choose.
To close the current project and have no project open, use the Close Project command. Source Insight asks
you if you want to save each file you have opened that you've changed, then it closes all files.
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 Project” on page 310.
Source Insight 4 User Guide
47
Projects
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.
Changing Project Settings
The Project Settings command sets various options that govern the current project. If no project is currently
open, then the Project Settings command sets the default options inherited by subsequently created projects.
When you create a new project, the Project Settings dialog box appears.
You may specify whether the project has its own private configuration, or if it uses the global configuration
file. You can also indicate where the project's source directory is, and what types of symbol information
should be indexed.
See “Project Settings” on page 284.
Symbols and Projects
Source Insight parses symbol definitions dynamically out of your source files while you edit. Symbol information is stored on disk in an indexed symbol database, which is integral to the project.
The symbol database is updated incrementally as you open and save files. Files that are changed by other
project team members are also automatically synchronized with the symbol database in the background.
You typically do not need to do anything to keep Source Insight’s symbol information current.
Synchronizing Project Files
Source Insight uses a synchronization process to keep files and symbols up to date with respect to its project
databases. This is helpful when files are edited without using Source Insight. For example, you may be using
a source control system that updates files on your machine, or you may have files that are machine generated by your build process. When that happens, Source Insight has to re-parse those out-of-date files to bring
the Source Insight project up to date. Normally, this is done automatically in the background for you, but you
can do it manually by using the Project > Synchronize Files command.
The synchronize process ensures that the entire project is up to date. It scans each file in the project and
updates the symbol database for each file that has been modified since Source Insight had the file open last.
48
Source Insight 4 User Guide
Projects
The synchronizing process can also optionally add and remove files automatically as new files appear, or disappear 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 synchronization process uses the Master File List to add or remove files as needed. See “Using a Master File List”
on page 46.
To synchronize files in a project:
You can synchronize a project in one of two ways:
•
The default: If the "background synchronization" option is enabled in Options > Preferences: General,
then synchronizing the project will happen in the background while you continue to edit in Source
Insight. See “General Options” on page 225. You basically don’t need to do anything.
•
You can run the Synchronize Files command, which synchronizes the project on demand. See “Synchronize Files” on page 351.
Normally, if you open a file that has been modified since Source Insight had it open, the symbol database is
updated automatically when you open the file. By automatically synchronizing, the update is transparent to
you. However, if a symbol is moved from one file to another, you may find that Source Insight loses track of
where the symbol is, unless both files are in sync with the project. In addition, if new symbols have been
defined, Source Insight won't know about them until the containing file is synchronized.
The Base Project
Source Insight automatically creates a project named Base. When Source Insight cannot find a symbol definition anywhere else, it searches the Base project. It is implicitly at the end of the project symbol path.
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.
Creating a Web Version of Your Project
You can create a snapshot of your project sources as a set of web pages. You can use any web browser to
browse your source code. The resulting web pages will have syntax formatting close to what is displayed
inside Source Insight.
Use the Project > Export Project to HTML command to save a new set of HTML files. See “Export Project To
HTML” on page 204.
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 287.
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.
Source Insight 4 User Guide
49
Project Windows
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.
Project File List
The Project File List shows all the files in the project. You can type into it to open files quickly; regardless of
what directory they are in. Most files can be opened with just a few keystrokes. You can also type wildcards
and change working directories directly by typing into the text box and pressing Enter.
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 specification. 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.
Browsing Non-Project Files
If you want to browse your disk and see files that are not necessarily part of your project, type dot (.) and
press Enter. The current working directory contents will fill the list. To return to the “project-only” view of the
files, type ** (two asterisks) and press Enter. Alternatively, you can switch to the Project Folder Browser panel
to browse directory contents.
50
Source Insight 4 User Guide
Project Windows
Project Symbol List
The Project Symbol List shows all the symbols in the project. You can quickly type the first few characters of
most files to open them quickly without navigating to any directories.
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.
Regular Expression Searches
You can also perform a regular expression search for symbol name by prefixing the regular expression with a
question mark (?). For example,
?Insert.*Stack
will find all symbols that have “Insert”, followed by zero or more characters, followed by “Stack”.
Finding Only Functions
You can limit search results to only function symbols by adding an open parenthesis at the end of the text.
For example:
Open(
will find only function that contain Open in the name.
Combining With the Context window and Relation Window
Both the Context window and the Relation window track the current selection in the Project Symbol List.
Therefore if you select a function in the Project Symbol List, the Context window will automatically show you
the definition of the function. The Relation window will automatically show the call tree or reference tree for
the function. (The Relation window has options you can set to tell it what you want to see.) See “Relation
Window” on page 93.
Source Insight 4 User Guide
51
Project Windows
Project Folder Browser
The Project Folder Browser shows disk directories and files. This allows you to perform some basic directory
and file maintenance, and to open non-project files easily.
File Types View
File Type View shows a breakdown of project source files by file type.
52
Source Insight 4 User Guide
Project Windows
Project Symbol Categories
The Project Symbol Categories panel shows a breakdown of symbols by symbol type.
Source Insight 4 User Guide
53
Symbols and Language Parsing
Symbols and Language Parsing
One of Source Insight’s most important strengths is its static analysis of source code while you edit. Its language parsers determine where symbols are defined in your project, and where they are used. It displays
source code with syntax formatting based on that analysis.
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 language. 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, Objective-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: Languages dialog box. A custom language is a simple generic language that specifies syntax rules, syntax formatting keywords, and simple parsing expressions. See “Language Options” on page 241.
Custom languages can also be exported and imported.
To Add a Custom Language
Adding support for a new language is basically a two-step process:
1.
Add the language, using Options > Preferences: Languages. See “Language Options” on page 241.
2.
Add the File Type that refers to the language, by using Options > File Type Options. See “File Types”
on page 72.
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 properties. See “Language Options” on page 241.
54
Source Insight 4 User Guide
Symbols and Language Parsing
Symbol Naming
In Source Insight, symbol names are stored as a "dotted path." The dotted path contains the symbol's container 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 symbol name so that the embedded dot is not confused with the dotted path dot character.
Resolving Symbol Definitions
When Source Insight displays source code, it formats identifiers based on their declaration. For example, is it
a function, or a class, or a struct? Is it a local variable? Is it a class member? And so on. Source Insight uses its
symbol lookup engine to resolve an identifier’s declaration.
When Source Insight looks up a symbol definition, it searches in a particular order to find it.
1.
It searches all open files and the symbol database for the current project (if a project is open).
2.
It searches the project’s import library list. See “Importing Symbols from Libraries” on page 55.
3.
It searches the global import library list.
4.
It searches every project in the project symbol path.
5.
Finally, the Base project is searched.
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.
Importing Symbols from Libraries
You can import symbols from external sources, such as INCLUDE path header files, Java packages, and .NET
assemblies. Source Insight creates a special import library project for imported symbols. You can use the
Project > Import Library Symbols dialog to maintain the list of import library projects. See “Import External
Symbols” on page 233.
Source Insight 4 User Guide
55
Symbols and Language Parsing
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.
The Global Import Library List
Source Insight maintains a single global import-library list that is used for all projects, or in the case where
you don't have a project open. The import list is searched when a symbol needs to be found. To manage this
list, select Project > Import External Symbols.
The Project-Specific Import Library List
Each project also contains an import-library list, which is only used when that project is the current project.
The import list is searched when a symbol needs to be found. To manage the project-specific list, select Project > Import External Symbols for Current Project, or select Project > Project Settings, and click the "Import
Symbols" button.
Only Definitions are Found via the Import Lists
The import libraries are only used to locate symbol definitions. They are 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.
The Project Symbol Path
The project symbol path is a delimited list of common projects that Source Insight will search when looking
up a symbol definition. It gets searched after all the open files, the current project, and the import library
projects.
There is only one project symbol path that is searched regardless of what the current project is.
Every project in the project symbol path is searched. If the symbol is still not found, then the Base project is
searched. If more than one symbol is found with the specified name, then Source Insight will ask you to pick
from a list of the matching symbols, their locations, and types.
You can edit the project symbol path using the Options > Preferences: Symbol Lookups command. See “Symbol Lookup Options” on page 346.
You can enable the Always search symbol path option in the Preferences: Symbol Lookups dialog box. When
this option is on, all projects in the symbol path are searched every time Source Insight looks up a symbol,
even if the symbol was already found in an open file or the current project. You may want to turn this option
56
Source Insight 4 User Guide
Symbols and Language Parsing
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 Preferences: Symbol Lookups dialog box and click the Import Symbols button.
To import C/C++ runtime symbols:
1. In the Options > Preferences: Symbol Lookups dialog box, click the Import Symbols button.
2.
In the Import External Symbols dialog box, click on the Add... button. If you already have an
INCLUDE path environment variable, then click on Import from an INCLUDE path. Otherwise, you
can click on Import from a source code tree and navigate to the directory that contains the runtime
library include files.
3.
The directories will be scanned and symbol declarations will be extracted into a special project
called an import library. This may take a few minutes depending on the number of file encountered.
Now, auto-complete should work for the symbols that are defined in the header files.
C# and .NET Framework Symbols
When editing C# files, Source Insight can perform symbol completion for the .NET Framework class library
symbols. This is accomplished by importing symbols from the .NET Framework assemblies on your machine.
To import the .NET Framework assemblies, use the Project > Import External Symbols command, or use the
Preferences: Symbol Lookups dialog box and click the Import Symbols button.
To import .NET Framework symbols:
1. In the Options > Preferences: Symbol Lookups dialog box, click the Import Symbols button.
2.
In the Import External Symbols dialog box, click on the Add... button. Click next on Import a directory tree of .NET assemblies. Navigate to the directory that contains the .NET Framework assemblies. This is typically in a location like C:\Windows\Microsoft.NET\Framework\v2.0.50727. Select the
directory and click OK.
3.
The directory tree containing .NET dlls will be scanned and symbol declarations will be extracted
into a special project called an import library. This may take a few minutes since there are many
.NET Framework assemblies.
Now, auto-complete should work for the packages that have been imported into the C# source file using the
using statement.
Java Symbols
When editing Java files, Source Insight can perform symbol completion for the standard Java runtime libraries. 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 Preferences: Symbol Lookups dialog box and click the Import Symbols button.
Source Insight 4 User Guide
57
Symbols and Language Parsing
To import Java runtime symbols:
1. In the Options > Preferences: Symbol Lookups dialog box, click the Import Symbols button.
2.
In the Import External Symbols dialog box, click on the Add... button. Click next on Import a Java jar
file. Navigate to the jar file that contains the runtime library. This is typically in a location like C:\Program Files (x86)\Java\jre6\lib\rt.jar. Select the jar file and click Open.
3.
The jar file will be scanned and symbol declarations will be extracted into a special project called an
import library. This may take a few minutes since the jar file is large.
Now, auto-complete should work for the packages that have been imported into the Java source file using
the import statement.
HTML and Scripts
The HTML File Type, which uses the HTML Language parser, parses HTML elements along with client-side
scripts elements. Client-side scripting blocks will appear using the syntax formatting appropriate for whatever scripting language is used. Symbols defined in the scripts are also displayed in the symbol window, and
are saved in the symbol database.
Source Insight uses the script language specified in the SCRIPT element. You can specify the default scripting
language to use in HTML in the Options > Preferences: Languages dialog box. Click on the Special button and
select the default language where it says "Default script language".
PHP Pages
The PHP File Type, which uses the PHP Page language parser, supports PHP with embedded HTML, plus client-side script. PHP scripting blocks will appear using the syntax formatting for PHP, and the appropriate formatting 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: .
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 elements. 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.
Active Server Page Scripts
The Active Server Page (ASP) File Type, which uses the Active Server Page language parser, supports HTML
with embedded server-side scripts, plus client-side script elements. Script blocks will appear using the syntax formatting appropriate for whatever scripting language is used. Symbols defined in the scripts are also
displayed in the symbol window, and are saved in the symbol database.
You can specify the default scripting language to use in HTML or ASP in the Options > Preferences: Languages
dialog box. Click on the Special button and select the default language where it says "Default script language".
Source Insight supports embedded ASP script using the start token <% and the end token %>. Source Insight
parses both the script and the HTML. Source Insight supports script sections embedded anywhere within the
HTML, just as the web server does.
58
Source Insight 4 User Guide
Symbols and Language Parsing
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 elements. The Active Server Page parser brokers HTML and server-side script to different languages, depending
on the language specified in the ASP file.
Source Insight 4 User Guide
59
Conditional Parsing and Preprocessor Support
Conditional Parsing and Preprocessor Support
This section discusses features and issues that apply mainly to C/C++ and C# language files that use a preprocessor and have #if or #ifdef statements.
Working with Inactive Code - ifdef Support
Source Insight can recognize inactive blocks of code that are disabled at compile-time with #ifdef, #if, and
#elif directives in languages that support those statements. There are project-specific and global lists of
conditional identifier values. To edit the conditional constant values, select Options > Preferences: Language
and click on either "Project Specific Conditions", or "Global Conditions". See “Conditional Parsing List” on
page 177. You can also edit the conditions using the Edit Condition command on the right-click menu of a
source window. See “Edit Condition” on page 201.
Note:
Conditional statements such as #if and #ifdef are only interpreted when all the condition values are specified 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 conditional 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.
Inactive code is formatted with the Inactive Code style.
Blocks of code that are inactive are displayed in the "Inactive Code" style. For example:
Figure 3.2 The "Inactive Code" style is displayed.
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 contains 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.
60
Source Insight 4 User Guide
Conditional Parsing and Preprocessor Support
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".
Ignoring Condition Variables
If you do not specify a variable's value, then any preprocessor statement that includes that variable is
skipped and simply ignored. This is the default behavior for any #if-type statement in Source Insight. If the
condition is not defined using the Edit Condition dialog, then Source Insight ignore the conditional and all
branches of the #if-#else block are parsed by Source Insight.
For example:
#if VER < 3 && WINVER >= 5
int a = 1;
#else
int a = 2;
#endif
If both VER and WINVER are defined using Edit Condition, then the expression in the #if statement will be
evaluated, and only one of the branches will be active. However, if either of those variables are not defined in
Source Insight, then both branches will be active.
Editing the Condition Variables
To edit the value of a conditional variable, right-click on it and select Edit Condition. See “Edit Condition” on
page 201. When you edit the condition list, Source Insight will ask you if you want to re-parse your whole
project. You should make all your changes to the condition list first, and then 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.
Source Insight 4 User Guide
61
Conditional Parsing and Preprocessor Support
Parsing Considerations and Parsing Problems
The language parsing in Source Insight is somewhere between a strict grammar parser, and a simple pattern
matcher. This is good because the parser is error-tolerant and works well on code that can be incomplete or
have some syntax errors. However, there are some points to keep in mind:
•
The source files can have syntax errors. They don't have to be compiled. That means symbols will be
found in source code that doesn't even compile or is in an intermediate state, which is most of the
time!
•
Preprocessor macros are not expanded before Source Insight parses the code. This may sound bad,
but in reality it works quite well. Source Insight parses your program at its most abstract level - at the
same level as it was written. Among other things, this also allows call trees to contain function-like
macros.
•
Symbol declarations are parsed from all of the source code, not just what was active at the time of
compilation. For example, C/C++ code inside of #ifdef-#endif clauses are also added to the symbol
database, even if the #ifdef branch is not active when you compile. This can be a great help if you are
working on a multi-state program, and you need to be aware of all cases, not only what the compiler
sees. If you do want to omit inactive code blocks, you can define condition values with the Edit Condition command, or in Options > Preferences: Languages.
•
The text in comments and constants is also indexed for searching. Source Insight is focused on source
level code; not just what the compiler transforms into object code.
•
All header files are assumed accessible in all source files. Source Insight does not notice what header
files are included in each particular source file. Therefore, all symbols are known at all points. This is
technically inaccurate with respect to how a compiler will see your program, but in most cases it works
well. This is a trade-off of speed versus complete correctness.
•
Some programming styles may cause symbols not to be found by Source Insight. The default parsing
that Source Insight uses works very well with most programming styles. In the event that you have
some declarations types that Source Insight can't recognize, you can add Token Macros, which expand
during a preprocessing phase, or you can add a custom parsing regular expression pattern. See “Preprocessor Token Macros” on page 64.
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 “Conditional 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 “Preprocessor Token Macros” on page 64.
62
Source Insight 4 User Guide
Conditional Parsing and Preprocessor Support
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 public.
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.
#ifdef Statements Confuse the Parser
In this situation, you have some #ifdefs that confuse the parser, especially when it splits the declaration of
some symbol. This can be handled by using the Edit Condition command to define the state of the #if or
#ifdef condition variable. See “Edit Condition” on page 201.
For example:
#ifdef ABC
typedef struct FOO_V1 {
#else
typedef struct FOO_V2 {
#endif
int x;
} FOO;
In the above example, the declaration of the typedef-struct is split up with #ifdef-#else-#endif. Source
Insight tries to parse this by ignoring the preprocessor statements because the conditional value ABC is not
defined using Edit Condition. Source Insight ends up interpreted the code like this:
typedef struct FOO_V1 {
typedef struct FOO_V2 {
int x;
} FOO;
This is obviously not valid code, and therefore Source Insight cannot parse it. However, if you use Edit Condition to define the value of ABC then Source Insight will parse the code.
Declaring Things Using a Preprocessor Macro
In this situation, you are using a preprocessor macro to declare things. An example of this might be something like this:
#define MyArray(name) char *name[]
MyArray(foo) =
{
"abc",
"xyz",
...
};
In this case, Source Insight thinks MyArray(foo) is a function, so it skips ahead and eventually gets confused.
This can be fixed usually by defining a token macro in the c.tom file located in your Documents\Source
Insight 4.0 folder. See “Preprocessor Token Macros” on page 64. To fix this example, you need to define a
token macro for MyArray.
Source Insight 4 User Guide
63
Conditional Parsing and Preprocessor Support
Replacing Keywords, Operators, or Delimiters with Preprocessor Macros
In this situation, a preprocessor macro contains syntax keywords or braces.
#define DeclareMyFunction(name) void name() {
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 Documents\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.
Preprocessor Token Macros
Source Insight contains its own preprocessor, which is used when parsing files. The preprocessor macros are
called Token Macros. They are token substitutions that occur as Source Insight parses a file. They allow
Source Insight to handle any special language keywords not known to Source Insight's parsers, and to handle
special C/C++ preprocessor substitutions that would otherwise confuse it.
Preprocessor macros are normally not expanded by Source Insight
Source Insight does not expand C/C++ preprocessor macros when it parses your files. Because of this, certain
preprocessor macros and constants can fool Source Insight. Therefore, token macros are used to let Source
Insight selectively expand some preprocessor substitutions.
For example, the STDMETHOD(methodname) macro is used to declare a COM method function. Source
Insight ships with a default C/C++ token macro file (c.tom) that has entries for this macro, and many others.
Token Macro Files
The token macros are listed in a file with a .tom extension. The global token macro file resides in the Source
Insight program directory. The project-specific token macro file, if any, is stored in project's data directory.
The project token macro file is combined with the global file, with the project macros taking precedence.
Token Macro Syntax
A token macro file consists of token macros, one per line. The format of a token macro is:
macroname
macroname
substituted text here
macroname(parameter list)
substituted text with parameter names
macroname(parameter)
text##parameter // concatenates text
; comments begin with a semicolon
Some examples of token macros:
MyStructure(sname)
struct sname
NoOperation
BuildName(name1, name2)
name1##name2
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
64
Language
File Name
C/C++/Objective-C
C.tom – a default copy ships with
Source Insight.
Java
Java.tom
Resource Files
Rc.tom
Source Insight 4 User Guide
Conditional Parsing and Preprocessor Support
Table 3.1: Token Macro Files for Different Languages
Language
File Name
x86 Assembly Language
X86.tom
Perl
Perl.tom
Editing Token Macros
If you want to change the token macros, simply open the token macro file, make your changes, and save the
file. Source Insight will recognize that the token macros have changed for the appropriate language. Open
files are automatically re-parsed.
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.
Project Specific Token Macros
Each project can have its own set of token macro files. Source Insight does not create them automatically,
but you can yourself. A project token macro file is saved in the project's data directory. When Source Insight
parses a source file, it combines the project token macros with the global set saved in the Source Insight program directory. The project token macros take precedence over the global ones. By adding project specific
token macros, you can tailor the token macro expansion for each project individually.
Source Insight 4 User Guide
65
Name Fragment Matching Symbol Names
Name Fragment Matching Symbol Names
Name Fragment indexing and matching is a feature that helps you find symbols, even if you are not sure what
the symbol's name is. For APIs that maintain consistent naming conventions, you can use name fragment
matching to find all symbols relevant to a particular topic. By typing a meaningful partial name, you will be
able to narrow your search to related items. For example, by just typing "Win", you can see all "Win" related
functions.
Name Fragment matching also works in most type-in boxes that are associated with lists; not just symbol
lists.
A name fragment (or word fragment) in a symbol or file name is a series of two or more characters that start
with a capital letter. It can also be a series of capital letters. Here are some examples:
Symbol Name
Name Fragments
CreateWindow
Create and Window
OpenHTML
Open and HTML
HTMLOpen
HTML and Open
FOpenDoc
Open and Doc
Vip32Test
Vip32 and Test
open_file
open and file
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.
Controlling Name Fragment Matching
You can control whether lists are affected by name fragment matching in the Options > Preferences: Typing
dialog box. The check box Match name fragments while typing controls whether name fragment matching is
active or not, regardless of whether the project setting indicate that name fragments are indexed in the symbol database.
Tip: Type a space character in front of a name fragment to toggle name fragment matching for an individual case.
As a shortcut, you can toggle the use of name fragment matching by prefixing what you type with a space
character. For example, if you turned name fragment matching off in the Options > Preferences: Typing dialog box, you can use it selectively by adding a space character in front of the name fragment you type.
Using Name Fragment Matching
Many of the text boxes where you can type a symbol or file name allow you to type a series of name fragments. The list box associated with the text box will be filtered down based on what you type.
Tip: Type name fragments into any text box associated with a list box. You can type multiple name fragments for filtering.
When you type, begin with the starting two or more characters of a name fragment, and follow that with
another name fragment. For example, "CreWin". You can separate name fragments with a space also. For
example, "Cre Win". For the most part, you can type the name fragments in any order.
66
Source Insight 4 User Guide
Name Fragment Matching Symbol Names
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.
Using Name Fragment Shortcuts
You can use these shortcuts when typing into a symbol name field to specify strict prefix matching, or member name matching:
To match strictly prefixes only, prefix the spec with a single space or the caret ^ character.
For example, ^Format and Format will match only symbols that start with "format". (Case insensitively.) It will not match "LineFormat". The prefix actually toggles name fragment matching on and off.
To match strictly prefixes of member names, prefix the spec with a dot . character. For example, .fdirty will
match only struct or class members that start with "fdirty". This also works with nested class members. For
example, .draw will match the method "Class1::Class2::Draw".
Underscores, which are common in program identifier names, are ignored. For example, _insert, and
insert would also appear in the list together.
Source Insight 4 User Guide
67
Source Control
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 information. 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.
Using Source Control in Source Insight
Source Insight has a few predefined Custom Commands built-in to handle common source control operations. You can invoke them by using the source control toolbar. For example, there are "Check Out" and
"Check In" commands. The general meaning of the source control commands is summarized in the next section.
Source Insight works best if each team member has their own local copies (or code repositories) of the project source files on their own local machine. This provides the best performance and reliability.
Source Control Commands
Source Insight has a few predefined Custom Commands built-in to handle common source control operations. Use the Tools > Custom Commands dialog box to edit the commands. You can easily change them to
support different source control, or version control systems.
The source control commands appear in the table below. Their exact meanings are really based on how you
choose to set them up in the Custom Commands dialog box. See “Custom Commands” on page 183. Source
Insight defines the following command semantics.
Table 3.2: Source Control Commands
68
Command Name
Action
Check Out
Checks the current file out of the Source Control
project, so that you can edit it.
Check In
Checks the current file into the Source Control
project. You should use Check In after you are finished editing a file, and want to put it back into
the main Source Control project for other team
members to access.
Undo Check Out
Reverses the action of a Check Out. This does not
check the file back in.
Sync to Source Control
Project
Updates all the files in your local project so they
are current with respect to the Source Control
project.
Sync File to Source Control Project
Updates the current file so it is current with
respect to the Source Control project.
Source Insight 4 User Guide
Source Control
Source Control Toolbar
The Source Control toolbar contains buttons for each of the source control commands.
Check In
Check Out
Sync To Source Control
Project
Undo
Check Out
Sync File To Source
Control Project
Figure 3.3 The Source Control toolbar
Using IBM® Rational ClearCase ® Commands
IBM® ClearCase® is a version control system that is used by software developers. The following table lists the
Source Control commands in Source Insight, and useful settings for using ClearCase.
Table 3.3: ClearCase Source Control Commands
Custom Command
Run String
Description
Check Out
cleartool checkout -unr -nc %f
check out current file unreserved
(non-locking), no comment
Check In
cleartool checkin -nc %f
check in current file without comment
Undo Check Out
cleartool uncheckout %f
undo check out of current file
Sync to Source Control Project
cleartool update
update the view
Sync File to Source
Control Project
cleartool update %f
update the current file in the view
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.
Using Git Commands
Git is a free and open source distributed version control system The following table lists the predefined
Source Control commands in Source Insight, and useful settings for using Git.
Source Insight 4 User Guide
69
Source Control
Git has many fine-grained commands and concepts that go beyond the relatively simple source control concept 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 Control Project
git pull origin
Pulls new changes from the remote
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 repository 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
Control Project
git fetch origin;git checkout FETCH_HEAD
-- %r
Effectively pulls changes for a single 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.
Additional Git Information
Before you can use the commands above on a given file, the file must be part of the Git repository. To add a
new file to your local repository, use the "add" command:
git add
And follow it by:
git commit -m "here is my comment"
By default, "origin" is the name of the repository you first cloned from. If you have a specific repository you
want to pull from, you should replace "origin" with the name of the repository. In addition, if you need to pull
from a specific branch of the remote, you should specify origin in the commands.
70
Source Insight 4 User Guide
Source Control
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/
Source Insight 4 User Guide
71
File Types
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, display, 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 programming 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.
Associating Files with File Types
The File Type Options command associates a file type with a filename wildcard. For any given file, Source
Insight determines the file type by matching its name with the filename wildcards specified in all defined file
types. For example, *.c files belong to the "C/C++ Source File" file type, while *.py files belong to the
"Python Source File" file type.
72
Source Insight 4 User Guide
File Types
Associating File Names Without Extensions
Some files in your project may not have any file extension. For instance, the standard C++ header files, such
as "complex" do not have file extensions. This situation makes it difficult to use wildcard specifications to
associate a file with a file type. For that reason, Source Insight uses a special file named filealias.txt to create
file name aliases for the purpose determining the file's file type.
The filealias.txt file is stored in your Source Insight program directory. You can edit this file. By default, it contains the names of the standard C++ header files.
The format of filealias.txt is as follows:
oldfilename=newfilename
This maps oldfilename to newfilename before determining the file's file type. For example:
algorithm=algorithm.h
When Source Insight sees the file algorithm, it uses the alias algorithm.h when determining the file type of
the file.
Adding New File Types
Adding new file types makes Source Insight aware of new types of files. All the defined file types become
Source Insight's file “vocabulary”. That is, when Source Insight shows you the files in a directory, it will only
display files that belong to currently defined file types. In addition, when Source Insight automatically adds
files to a project, it will only add files that belong to known file types. Therefore, by adding a new file type,
you are expanding Source Insight's knowledge of file types.
Editing the File Types
The easiest way to edit a file's file type, or to see what file type it belongs to, is to make sure the file’s window
is activated, then select Options > File Type Options. The file type of the current file is automatically selected
in the File Types dialog. See “File Type Options” on page 213.
Source Insight 4 User Guide
73
Browsing and Analysis
Browsing and Analysis
Source Insight provides many ways to locate symbols, and review symbolic information in your projects. This
is one of Source Insight's important strengths.
This section describes briefly the Source Insight features that help you access symbol information.
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 techniques. 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.
Symbol Navigation Commands
These commands are the most commonly used commands to navigate to symbol definitions, or function
callers.
Jump to Definition command
The Jump to Definition command jumps to the declaration of the symbol under the cursor. See “Jump To
Definition” on page 238. Type Alt+equal or Ctrl+click with the left mouse button to invoke the command. You
can also right-click on the symbol and use the shortcut menu to run this command.
Tip: To jump to a definition, hold down Ctrl and click on its name.
After locating the symbol, the symbol's file is opened, displayed in a window, and the symbol name is
selected. If you have more than one symbol with the same name in your project, Source Insight will ask you
to select the one you want.
Note:
Another way to jump to a definition is to have the Context Window open. Let the Context Window show the definition. If you want to jump there, just double click on the Context Window.
Jump to Caller command
The Jump to Caller command jumps to the caller of the function under the cursor. See “Jump To Caller” on
page 238. You can right-click on the symbol and use the shortcut menu to run this command. This only works
if the object under the cursor is a function name.
Refresh Relation Window command
This command causes the Relation Window to update to reflect the currently selected symbol. For example,
if the Relation Window is setup to show function references and you have the cursor on a function name,
then this command will make the Relation Window show all the references to the function. This command is
useful is you normally keep the Relation Window locked to prevent automatic updates. See “Relation Window” on page 305.
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.
74
Source Insight 4 User Guide
Browsing and Analysis
Project Symbol List Window
The Project Symbol List Window displays a list of all project symbols. You can type into the text box to perform prefix and name fragment name matching. The Project Window is a mode-less window. Therefore, as
you select symbols in the Project Window, the Context Window and Relation Window will update and provide
information about the selected symbol. See “Project Windows” on page 50.
The Project Symbol Categories Window is a hierarchical view, where symbols are listed by category. For
example, all global variables are grouped together; all structs are grouped together, and so on. For structured
types, such as classes, structs, and unions, the Project Window can expand them to show their members. See
“Project Symbol Categories” on page 280.
Call Trees and Reference Trees
The Relation Window is another 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, structure members, reference trees, and more. It works in the background tracking what you are selecting and
showing relationship information automatically. See “Relation Window” on page 93.
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.
Command Line Symbol Access
You can jump to a symbol by using the -f option on the Source Insight command line when you
start Source Insight.
For example:
sourceinsight4 -f myfunc
This will position to the symbol named "myfunc".
You can also simply give the name of the symbol on the command line without a special command option, as
though it were a file name. In this case, Source Insight will try to determine whether the symbol you specified
is either a file, or a parsed symbol. You can list as many symbols on the command line as you like, just as with
file names.
For example:
sourceinsight4 myfunc fcb init
This will open all files where the symbols "myfunc", "fcb", and "init" are located. See “Command Line Syntax” on page 132.
Finding References to Symbols
The Search > Lookup References command can be used to quickly find all references to the word in the current selection. For example, to find all calls to TextOut, put the insertion point inside of the TextOut identifier
and run the Lookup References command. A Search Results window will be built which will list all references
found. See “Lookup References” on page 255.
The Relation Window can also be used to show references automatically to the word in the current selection.
See “Relation Window” on page 305.
The Project Search Bar and the Search > Search Project command can be used to search across your whole
project, using a powerful keyword and name fragment based search. This is like an Internet search across
your project.
Source Insight 4 User Guide
75
Browsing and Analysis
See “Search Project” on page 328.
See “Project Search Bar” on page 278.
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.
Figure 3.5 Example of reference highlights
You can enable this feature by selecting Options > File Type Options, then selecting the option "Highlight references 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.
Creating a Project Report
The Project Report command will create a report file containing a symbol cross-reference, and statistics
about the files in your project. See “Project Report” on page 286.
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 335.
76
Source Insight 4 User Guide
Browsing and Analysis
Comparing Files and Directories
Source Insight can compare two files and show differences. It can also compare two different directories.
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.
Source Insight 4 User Guide
77
Syntax Formatting and Styles
Syntax Formatting and Styles
Syntax Formatting is an important Source Insight feature that renders information in a dense, yet pleasing
and useful way.
Syntax Formatting uses rich text formatting based on program information. Source Insight uses information
gathered from its parsers to format source code. Identifiers can be displayed in different fonts or font sizes,
along with a variety of effects such as bold and italics.
78
Source Insight 4 User Guide
Syntax Formatting and Styles
For example, in the image below, it’s easy to tell the difference between class members and local variables,
because class members are styled in italics.
Formatting is applied with "styles". A style is a set of formatting properties. For example, a style may specify
bold + italic. You can edit each style's formatting properties with the Options > Style Properties command.
See “Style Properties” on page 342.
Formatting styles are applied to source code elements automatically, based on parsing information. There
are many predefined styles that correspond to syntax elements. For example, there is a style for a function
definition, and another style for class definition. You can also add your own styles that you can explicitly
associate with keywords or identifiers.
Source Insight 4 User Guide
79
Syntax Formatting and Styles
How Styles Apply to Source Code
Styles are automatically applied to source code text. With the exception of comment styles, you cannot
explicitly apply a style yourself, like in a word processor. The applicable language parser is used to assign
styles based on parsed information.
Styles are used automatically for the following:
•
Language keywords, for example C keywords such as while, and void.
•
Delimiters and numbers.
•
Comments
•
Declarations of symbols - for example a function declaration.
•
References to symbols - for example, a call to a function.
•
User-defined identifier associations - You can explicitly associate a style with any identifier by editing
the language’s keyword list.
How a Style Works
Styles contain formatting instructions that can be combined with other styles. When a style is applied to text,
it combines with the underlying text properties. The basic text properties are set in each file type's font settings. You can control this with the Options > File Type Options command. Style properties are combined
with the basic text properties. Styles also can inherit properties from other "parent" styles. See “Parent
Styles” on page 81.
The formatting properties of all the applicable styles are combined with the font selected in a given file's
type.
Figure 3.6 Style properties combine with each other, and with the default font set in the File Types dialog box.
Formatting Properties
Each style is like a list of formatting differences from its parent style. For example if a style has the "bold"
property, then "bold" is added to the parent. Each formatting item has the following possible states:
•
On The formatting property is added. E.g. Bold-On
•
Off The formatting property is removed. E.g. Bold-Off
•
A Number This number applies to items like scaling, or font point size. E.g. scaling = 120%.
•
Font Name This overrides the font used.
•
No Change The style has no effect on the formatting property. It inherits the properties of the parent
style.
80
Source Insight 4 User Guide
Syntax Formatting and Styles
Parent Styles
Styles inherit formatting properties from parent styles. Each style has a "Parent Style" property. Therefore
the styles form a hierarchy. For example, the built-in styles contain a hierarchy for Declarations, a portion of
which looks like this:
Figure 3.7 An example of a style hierarchy.
In the Style Properties dialog, the style hierarchy is displayed visually. See “Style Properties” on page 342.
Formatting properties in a style are combined with its parent style. Thus, the Declare Struct style inherits the
formatting properties of the Declaration style. You can affect changes to all declaration styles by altering the
single Declaration style.
The topmost parent style is the "Default Text" style. Its formatting properties are determined by the file
type's font settings.
You can change the parent style of any style using the Style Properties command.
Source Insight 4 User Guide
81
Syntax Formatting and Styles
In the figure below is an example of how styles might combine for a function declaration.
Figure 3.8 Style properties "add up" on top of the default font specified by the file type.
Language Keyword Styles
The simplest application of styles is for formatting language keywords. Each language contains a keyword
list. Each keyword list item associates a keyword, for example while, with a style. The keyword list is editable. Source Insight displays the keyword using the associated style. You can edit the language keyword list
in the Preferences: Languages dialog box, or by invoking the Keyword List command directly. See “Language
Options” on page 241.
To determine the formatting of any given word in a window, Source Insight locates the word in the keyword
list of the appropriate language type. The keyword list contains a style name, which in turn implies the formatting associated with the style.
Therefore, starting with a file name and a word in the file, Source Insight derives the word's style with this
relationship:
Figure 3.9 The style used for a word in source text is determined by the keyword list of the language of the file type of the
file in question.
Declaration Styles
Wherever a symbol is declared or defined, its name is formatted with an appropriate "Declaration" style.
There are declaration styles for different types of things, like structs, classes, unions, functions, etc.
82
Source Insight 4 User Guide
Syntax Formatting and Styles
For example, a structure might look like this:
The structure name "CLIP" is shown in the "Declare Struct" style. The member fields inside the struct are
shown in the "Declare Member" style. There are several styles named "Declare...something".
If you select Options > Style Properties, you can see all the declaration styles. Their names all start with
"Declare...".
Reference Styles
References to symbols that are not actual declarations are formatted with an appropriate "Reference" style.
There are reference styles for different types of symbols. Reference formatting gives you a lot of information
without having to ask for it. It becomes instantly obvious if you have misspelled a function name, or whether
you are using a constant, or a local variable, or a global variable.
For example, a code fragment might look like:
The call to "SeekTokenLnIch" is formatted with the "Ref to Function" style. The C macro function "HdocOfTgl" is formatted with the "Ref to Macro" style, which helps you know just by looking at it that it is a
macro. The parameter "hpar" is formatted with the "Ref to Parameter" style, so we know it is a parameter
passed to the current function. The identifier "htglLocal" is formatted with the "Ref to Local Variable" style,
so we know it is a local variable in the current function. The "kswaChangeMark" constant is formatted with
the "Ref to Constant" style, so we know it is either a #define or enum value.
Distinguishing Class and Struct Members
Reference styles are also useful to distinguish member variables and member functions from other variables.
In this example, the function DoSomething is referencing both member variables, and a file-scope function
and a global variable. The reference styles make each reference look different. The Ref To Member styles in
Source Insight 4 User Guide
83
Syntax Formatting and Styles
this example have been given the Italic property. So, for example, the references to valueTest inside the
DoSomething function is shown in italic. This tells you that valueTest is a member variable.
If you select Options > Style Properties, you can see all the reference styles. Their names all start with "Ref
to...".
Note:
Enabling reference formatting can slow the display down in some cases. Source Insight needs to perform symbol lookup operation each time it encounters a potential symbol reference.
Inactive Code Style
For languages that support #if and #ifdef statements, Source Insight recognizes inactive blocks of code based
on the value of the conditions. You can edit the conditional values by selecting Options > Preferences: Language and clicking either "Project Specific Conditions" or "Global Conditions". You can also click inside a
conditional identifier, then rigth-click and select Edit Condition.
Blocks of code that are inactive are given the "Inactive Code" style. For more information, see “Conditional
Parsing” on page 60.
84
Source Insight 4 User Guide
Syntax Formatting and Styles
Comment Styles
Source Insight adds some explicit formatting to comments. All comments inherit from the Comment parent
style. The comment style hierarchy appears below.
Figure 3.10 The comment styles hierarchy.
Comment Heading Styles
Comment heading styles are very useful for breaking up large chunks of code with high-level comments.
Source Insight 4 User Guide
85
Syntax Formatting and Styles
Comment Heading styles are specified with a //n comment prefix, where n is a number between 1 and 4. For
example:
//1
//2
//3
//4
This
This
This
This
is
is
is
is
a
a
a
a
Heading
Heading
Heading
Heading
1
2
3
4
comment
comment
comment
comment
When the comment displays, the //n at the beginning of the comment is hidden, unless the cursor is on that
line. The above lines appear like this:
If the cursor is on the line, then the //n will appear so that you can edit it.
Comment Right Style
Comments that appear to the right of code are given the "Comment Right" style. For example:
Single and Multi Line Comment Styles
Multi-Line comments are displayed in the Comment Multi Line style. These are any comments using the /*
and */ delimiters in C/C++ and Java.
Single line comments are displayed in the Comment Line style. These include comments that start with //
delimiters in C/C++ and Java.
Comment Styles and Custom Languages
When you define a custom language, using the Preferences: Languages dialog box, you can specify comment
or text-range types, and associate them with a style. For example, you could create a comment range that
starts with (* and ends with *) and the text is formatted with the "Comment Multi Line" style. You can actually
define any delimited range of text, and associate it with any style (including a non-comment style).See “Symbols and Language Parsing” on page 54. and “Special Language Options” on page 243.
86
Source Insight 4 User Guide
Syntax Formatting and Styles
Syntax Decorations
Syntax Decorations add extra information to your code display.
Source Insight can replace some common operators with more useful symbolic characters. The Preferences:
Syntax Decorations command controls which decorations are used.
The symbolic characters are formatted with the "Symbol Characters" style. If you use the Options > Style
Properties command to look at the Symbol Characters style, you will see that it uses the Symbol font. You
may change the style's properties, such as the color or font size, but if you change the font name to something other than Symbol, your syntax decoration symbols will probably not show up correctly.
Note:
It's important to remember that symbol substitutions do not change the text in the source file; only its representation on the screen changes to show the special symbols. You still need to type the operators normally
when editing your code, or when searching for them.
Operator Substitutions
Common operators, such as the pointer dereference right arrow (->), or the assignment operator (=) can be
replaced with symbolic operators, such as arrows. For example, instead of this:
With decorations on, the = and -> are replaced with arrows:
Boolean, math, and other operators can be substituted with decorative symbols too.
Source Insight 4 User Guide
87
Syntax Formatting and Styles
Scaled Nested Parentheses
Source Insight can display nested parentheses in different sizes to make it easier to identify matching sets.
This even works across multiple lines.
Goto Arrows
Another useful decoration is the "goto arrow". An up or down arrow appears in goto statements which points
in the direction of the target label.
End Brace Annotations
Source Insight can also add automatic "end brace" annotations to the closing curly brace in C/C++/C# and
Java code. This makes it easier to understand nested if, while, switch, and other blocks of code.
Controlling Syntax Formatting
You have control over how Source Insight formats your code.
Changing Style Properties
The Style Properties command controls the formatting properties of each style. You can also add your own
styles, and import and export them.
The Syntax Formatting command
The Preferences: Syntax Formatting command controls how much display formatting is applied. You can
speed up the display by disabling some options here. For more information, see “Syntax Formatting” on
page 355.
The Syntax Decorations command
This Preferences: Syntax Decorations command controls what syntax decorations are performed.
Turning off Syntax Formatting
The Syntax Formatting features of Source Insight are powerful, but sometimes you may want to see how text
will line up in another editor, or in a simple display mode when only a single font is used.
88
Source Insight 4 User Guide
Syntax Formatting and Styles
Switching off Syntax Formatting temporarily
If you want to temporarily see your files without syntax formatting, use the View > Mono Font View command.
Mono Font mode is useful for quickly switching your display to a basic monospaced font display. This is particularly useful if you are using spaces instead of tab characters to line columns up. When Mono Font mode is
active, it overrides the settings of the Preferences: Syntax Formatting and Syntax Decorations dialog boxes.
Keeping fonts from changing
If you want to just see only color formatting, but no font changes, or font embellishments such as bold and
italic, then use the Options > Preferences: Syntax Formatting dialog box and check the Use only color formatting box.
Changing the font used to display source code
To change the base font used to display source code, open a source file, and select Options > File Type
Options. The file type for the current source file will be automatically selected as the active file type. Click the
Screen Fonts button and pick the desired font. This font will become the new base default font for that file
type. For example, a style for declarations might add "bold". Or a style might specify a different font and
override the screen font selection in the file type.
When you click OK in the font selection dialog, you will see this prompt:
To apply the font to ALL the file types, type "yes" in the box and click OK. To only apply it to the current file
type, click No.
Source Insight 4 User Guide
89
Context window
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 contextual 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 functionality. 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.
The Context window
shows information
about the selected
identifier in the
source file window. In
this case, it is showing
the definition of the
selected class
member function.
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.
90
Source Insight 4 User Guide
Context window
Previewing Files and Source Code
The Context window is used to quickly preview files and other things without having to open them. For example, if the Project File List panel is in front, the Context window previews the currently selected file.
Figure 3.12 The Context window is previewing the file selected in the Project File List panel.
The Context window previews the following types of objects:
•
Files selected in the Project File List, Project Folder Browser, and Directory Compare panels
•
Symbol definitions in the Project Symbol List panel
•
Reference locations in the Relation Window panel.
•
Code Snippets in the Snippet panel
•
Clips in the Clips panel
•
Bookmark locations in the Bookmarks panel
•
Symbol selected in the symbol pane in a source file window
•
Symbol selected in the auto-completion list.
•
Source Window selected in the Window List panel
Context window Results
To summarize, the Context window does the follow:
Your Action
Context window Result
Selecting (clicking) on an identifier in a source file window
Shows symbol definition based on context.
If more than one symbol matches, the Context window
will show a list of matches.
If the symbol is an instance of a class or data structure,
then the class or data structure declaration is shown.
Selecting a symbol in the Project
Symbol List
Source Insight 4 User Guide
Shows the symbol’s definition.
91
Context window
Your Action
Context window Result
Selecting an item in the Relation
Window
If the item is a reference to a symbol, then it shows the
place where the reference or call occurs. Otherwise it
shows the definition of the selected symbol.
Typing in a source file window
If the auto-completion feature is enabled, then it
shows the declaration of the selected item in the autocompletion list
Selecting a bookmark in the
Bookmark Window
Shows the location of the bookmark.
Selecting a clip in the Clip Window
Shows the clip contents
Selecting an item in the Snippet
Window
Shows the body of the selected snippet.
Selecting an item in the Window
List (list of open file windows)
Shows the contents of the file window.
Typing or selecting an item in the
symbol window pane of a source
file window
Shows the symbols definition.
Showing Declarations and Definitions
When you click on an identifier name in a source file window, the Context window will show you the symbol’s
declaration automatically. Functions and other symbols show up in the Context window along with their
parameters and other definition information.
The Context window determines what type of symbol you are clicking or typing. For example, if you click on a
variable, it will show you the declaration of the variable. If the variable is a data structure instance or a
pointer to a data structure, then the Context window will show you the structure or class definition.
Decoding Base Types to Show Structures
The Context window will determine the “base” structural type of a symbol by climbing up the type hierarchy.
That is, typedefs are decoded all the way back to the base structure type. For example, if you have code like
this:
struct S { ... };
typedef S T;
typedef T *PT;
PT ptvar;
...
...
ptvar->mem....
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.
Customizing the Context window
The Context window Options command allows you to change the Context window settings. You can turn off
the base type decoding mentioned above, and control how the context window tracks the cursor. See “Context Window Options” on page 179.
92
Source Insight 4 User Guide
Relation Window
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, 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.
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 305.
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 showing different types of information.
Outline and Graph Views
The Relation Window has two types of views: Outline view and Graph view. The Graph view shows symbols as
graph nodes with lines connecting them. The Relation Graph Options command (available on the Relation
Window right-click menu) gives you control over the appearance of the graph view.
Source Insight 4 User Guide
93
Relation Window
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
94
Source Insight 4 User Guide
Relation Window
graph layout. You can also print the graph, or copy the graph images to the system clipboard so you can process 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 horizontal 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 304.
Source Insight 4 User Guide
95
Relation Window
Relation Window Right-Click Menu
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 305.
Relationship Types
The relationships fall into these general categories, listed from computationally the fastest to slowest:
96
•
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.
Source Insight 4 User Guide
Relation Window
•
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 filter 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.
Relation Window Performance
The Relation Window requires some processing. Some relationships are slower to compute. For very large
projects, the “References” relationship will be the slowest to compute.
Multiple Relation Windows
You can have multiple Relation Window instances, so you can show multiple relationships at the same time.
Each Relation Window has its own relationship options. For example, one window could show you what functions are called by the selected function, and another window could show you what functions make calls to
the selected function. To create a new Relation Window, right-click on the Relation Window and select New
Relation Window.
Customizing the Relation Window
The Relation Window Options command is accessed from the Relation Window toolbar or shortcut menu.
You control what relationships are shown from this command, and how the window displayed. See “Relation
Window Options” on page 305.
You can also customize the appearance of the Graph View of the Relation Window by using the Relation
Graph Options command. See “Relation Window Graph Options” on page 304.
Source Insight 4 User Guide
97
Code Snippets
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 339.
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 identifier that is replaced with a particular value when the snippet is inserted. For example, $date$ is a text variable 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 Variables. See “Expand Text Variables” on page 203.
Note:
98
Text variables can also be used in Clips (see Clips).
Source Insight 4 User Guide
Code Snippets
Predefined Text Variables
There are many predefined text variables that are automatically replaced with values when a snippet is
inserted.
Table 3.5: Predefined Text Variables
Name
Value
$current_function$
name of the current enclosing function
$current_namespace$
name of the current enclosing namespace
$current_package$
name of the current enclosing package
$current_symbol$
name of symbol declared or enclosing the cursor position
$current_type$
name of the current enclosing struct, class or data type
$current_word$
the current word at the cursor position before the snippet is inserted
$date$
the current local date
$dollar$
the dollar sign ($)
$enclosing_symbol$
name of the function, class, or symbol that encloses the cursor
$file$
current file name with path
$file_in_project$
current file name relative to project source directory (root)
$file_no_path$
current file name without path
$next_function$
name of the function declared after the current line
$next_namespace$
name of the namespace declared after the current line
$next_package$
name of package declared after the current line
$next_symbol$
name of the symbol declared after the current line
$next_type$
name of the type declared after the current line
$prev_function$
name of the function declared before the current line
$prev_namespace$
name of the namespace declared before the current line
$prev_package$
name of the package declared before the current line
$prev_symbol$
name of the symbol declared before the current line
$prev_type$
name of the type declared before the current line
$return_type$
return type of the current function
$selection$
the currently selected text before the snippet is inserted
$time$
the current local time
$username$
the system user name that is logged in
$UTC_date$
the current UTC date
$UTC_time$
the current UTC time
$UTC_year$
the current UTC year
$year$
the current local year
Placeholder Text Variables
You can also use your own text variables to represent placeholders that behave similar to form fields after the
snippet is inserted.
Source Insight 4 User Guide
99
Code Snippets
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 placeholder. Alternatively, you can use any other navigation command to move the cursor.
Automatic Text Variable Replacements
When you edit a placeholder, all instances of the same text variable placeholder get replaced automatically
with what you typed. For example, if $myvar$ appears in 4 places, and you select it and type over it, then all 4
places are replaced with what you typed. This is useful for snippets that refer to the same identifier in multiple places.
In the above example, let's say you type ioffset to replace the value of $i$. The other instances of $i$ will
get replaced with ioffset.
To select the next text variable in a file, use the Select Next Snippet Placeholder command (CTRL+SHIFT+;).
This selects the next text variable placeholder in the file. If you have the "Smart Tab" feature enabled, then
you can just type Tab in many cases to move to the next placeholder.
In the above example, the $lim$ placeholder will get selected. Now you can type the limit value of this for
loop.
Pressing Ctrl+Shift+; again will select the $end$ placeholder. Now you can edit the body of the for loop.
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 inserting" 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 340.
Project vs Global Snippets
Snippets can be project-specific, or common to all projects. The Storage Location of a snippet specifies if the
snippet is stored with the project, or global. Global means it is common to all projects. The Snippets panel
lists all your snippets, both project and global.
Global snippets which apply to all projects are stored in a file named global.snippets.xml in the Source
Insight 4.0 documents folder inside the Snippets folder. For example:
C:\Users\John\Documents\Source Insight 4.0\Snippets\global.snippets.xml
Project-specific snippets are stored in a file named .snippets.xml in your project data
directory. For example in a project named "myproject" :
C:\Users\John\Documents\Source Insight 4.0\Projects\myproject\myproject.snippets.xml
For more information: See “Snippet Window” on page 339.
100
Source Insight 4 User Guide
Clip Window
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.
Type into this field to
select a clip. This list is
filtered as you type.
Other clip information
will appear at the top,
telling you where the
clip came from.
This is a list of all open
clips. Each item shows
the first line of text in
the clip.
Figure 3.13 The Clip Window
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.
Creating a New Clip
To create a new clip, run the New Clip command (located on the File menu, and on the Clip Window toolbar).
A new source file window will open. You can type and edit this file like any other. When you close it, the clip
will be retained in the Clip Window until you delete it.
You can also create a clip anytime by using the Copy to Clip command, or by dragging and dropping text onto
the Clip window. You can also drag a file from Explorer onto the Clip Window to open a file as a clip.
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.
Source Insight 4 User Guide
101
Bookmarks
Bookmarks
Bookmarks are useful for remembering locations of interest in your files. Bookmarks are accessed and managed 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 Bookmark 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 bookmark. 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.
102
Source Insight 4 User Guide
Bookmarks
Bookmark Storage
Bookmarks are saved in a special file named booksmarks.xml, so they are preserved from session to session. 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 bookmarks 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 number 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.
Source Insight 4 User Guide
103
Searching and Replacing Text
Searching and Replacing Text
Source Insight provides a number of searching commands, and replacement commands that operate on the
current file as well as across multiple files. When searching multiple files, source links can be used to quickly
link matches.
Searching is an important activity for programmers. As such, Source Insight devotes a lot technology to help
you navigate large code projects quickly. This is one of Source Insight’s important strengths.
Searching for Symbol References
To quickly search the current project for references to the currently selected symbol, use the Lookup References command (Ctrl+/). See “Lookup References” on page 255. For example, click inside an identifier such
as "BeginPaint", then invoke the Lookup References command. Source Insight will open a Search Results
window, which lists all the places you used BeginPaint in your project. Each matching line listed in the Search
Results window will also have a source link to the location of each line containing the word you looked up.
The Lookup References command is context sensitive, so that if finds only the correctly matching references,
given the scoping context.
The Lookup References command and the Relation Window use a special search index for speed.
Relation Window Shows References Automatically
The Relation Window also shows references to the symbol at the cursor position automatically. You don’t
need to use the Lookup References command unless you want to put the results into the Search Results window. See “Relation Window” on page 93.
Automatically Highlighting References in the Code
You can have Source Insight automatically highlight references to the symbol at the cursor position within
the source code window. This is controlled by on a per-file-type basis using an option in Options > File Type
Options. See “File Type Options” on page 213.
Searching the Current File
The Search command (Alt+F) searches the current file for a search pattern. The search can be forward or
backwards. In addition, the search can be batch style, where the search output results are placed in a Search
Results window. See “Search” on page 323.
The Search Forward (F4) command repeats the last search, allowing you to advance through the file, finding
each occurrence of a pattern.
The Search Forward for Selection command searches for the next occurrence of the first word in the current
selection.
The Incremental Search command (F12) finds matches as you type the characters. See “Incremental Search”
on page 232.
File Search Bar
The File Search Bar is used to search within the current file. To show it, select View > File Search Bar. Alternatively, you can use Activate Search Bar (Alt+Shift+F) to activate it so you can start typing into it.
To set options, click the Options button. See “File Search Bar Options” on page 212.
104
Source Insight 4 User Guide
Searching and Replacing Text
Searching Multiple Files
To search for a pattern across all project files, or other non-project files, use the Search Files command. See
“Search Files” on page 325. The Search Files command is similar to the Search command, except you can
specify what files you want to search. The results of the search are placed in the Search Results window. The
search results also contain hidden information called source links.
If you are just looking for single, whole-word references across your whole project, the Lookup References
command is much faster. See “Lookup References” on page 255.
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.
Project Search Bar
The project search bar is used for searching across the whole project. It is a powerful way to perform a keyword based search to find name or word fragments within a given number of lines of context. To show it,
select View > Project Search Bar.
See “Search Project” on page 328.
Searching for Keywords
If you want to search your whole project as though it was a web site, then use the Search Project command.
Using keyword searching, you can find any combination of terms or symbol name fragments that occur
within a specified number of lines of context. See “Search Project” on page 328.
Searching the Web
The Search Web command (Ctrl+Alt+W) searches for the identifier at the cursor position using your web
browser and your preferred web search engine. See “Search Web” on page 331.
Replacing Text
These are the methods for replacing or renaming identifiers in the current file or multiple files.
Replacing in the Current File
The Replace command searches the current file for a search pattern, and replaces the pattern with a new pattern. The range of replacement can be the whole file, or just the current selection. See “Replace” on page 312.
Replacing in Multiple Files
The Replace Files command is similar to the Replace command, except you can specify what files you want to
do the replaces in. See “Replace Files” on page 313.
If you want to rename a symbol across multiple files, the Smart Rename command is usually better, because
it is context sensitive. See “Smart Rename” on page 335.
Source Insight 4 User Guide
105
Searching and Replacing Text
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 335. 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.
Search Results Window
The Search Results window is created whenever you use a search feature that searches across multiple files,
such as the Search Project, Search Files, or Lookup References commands. Each line in the Search Results
window corresponds to a match in some file at some line number. Matches listed in the Search Results window contain source links, which are hypertext-like links to the locations where the matches were found.
The Search Results is a text file buffer that you can also edit.
Navigation Using Source Links
Source Links connect two locations in two different text files. They connect a line of text in a "link source" file
to a location in a "link target" file. Links are associated with individual lines.
106
Source Insight 4 User Guide
Searching and Replacing Text
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.
Searching and Source Links
The search results placed in the Search Results window by the Search, Search Files, and Lookup References
commands contain Source Links. The link source file is the Search Results temporary file, and the link target
for each link is the location of the matching patterns in the various files that were searched.
Source links are part of the current workspace, which means it is part of the session state. If you save the
Search Results to a new file name, the Source links will be retained in the current workspace. For example,
you could search for one pattern, save the Search Results to S1.OUT, do a second search, and both S1.OUT
and Search Results will have their source links. If you close the Search Results window, the source links are
deleted.
Source Insight 4 User Guide
107
Searching and Replacing Text
Creating Source Links
The Parse Source Links command creates source links in the current file. You specify a search pattern which
is used to parse file names and line numbers from a file. Each time a pattern matches, a new source link is
inserted into the current file.
The Parse Source Links command is useful if you have a "log" or "output" 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.
Source Links from Custom Command Output
You can create source links from the output of a custom command. When defining the custom command, the
"Parse Source Links" option should be on in Custom Command dialog. You must specify a search pattern to
be used to parse file names and line numbers. When the command terminates, Source Insight automatically
invokes the Go To First Link command.
This is the recommended way to invoke a compiler or build tool from Source Insight. This runs the compiler,
and Source Insight will position you to at each erroneous source line.
Source Link Commands
Source Insight provides the following commands for moving between link locations.
Table 3.6: Source Link Commands
Command
Key
Description
Jump To Link
Ctrl+L
Moves to the other end of
the source link at the current line.
Go To First Link
Ctrl+Shift+L
Selects the first link line in
the link source file, and
selects the associated link
line in the link target file,
and ensures both files are
visible on the screen in windows.
Go To Next Link
Shift+F9
Same as above, except with
the next link in the link
source file.
Go To Previous Link
Shift+F8
Jumps to the previous link
in the source file.
Search Results Text
Each set of matches in the Search Results window has a search heading that lists the pattern that was used to
search, followed by a match count. The search headings are parsed by Source Insight and each search pattern appears in the symbol window on the left side of the Search Results window to provide an overview.
For example, a typical search heading might look like:
---- GetStockObject (23) -----
meaning that 23 occurrences where found.
The Search Results window is actually just another file buffer that you can edit. You may freely delete lines
from the window to trim down the results. The Search Results buffer is automatically saved when you exit
Source Insight.
108
Source Insight 4 User Guide
Regular Expressions
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 basically 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.
Regular Expression Elements
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.
Matching the Beginning or End of a Line
^ and $
The caret ^ matches the beginning of a line when the caret appears as the first character in the search pattern.
Example: ^Hello matches only if Hello appears at the beginning of a line.
The $ matches the end of a line.
Example: TRUE$ matches only if TRUE appears at the very end of a line.
Matching a Tab or Space
\t
\s
\w
\t matches a single tab character.
Example: \tint abc; matches a tab character followed by int abc;.
\s matches a single space character.
Example: \sif matches a space character followed by if.
\w matches a single white space character. In other words, \w matches either a tab or space character.
Example: \wwhile matches either a tab or space character, followed by while.
Source Insight 4 User Guide
109
Regular Expressions
Matching 0, 1, or More Occurrences
* and +
* matches zero or more occurrences of the preceding character. The fewest possible occurrences of a pattern
will satisfy the match.
Example: a*b will match b, ab, aab, aaab, aaaab, and so on.
+ matches one or more occurrences of the preceding character.
Example: a+b will match ab, aab, aaab, aaaab, and so on, but not just b.
Matching Any in a Set of Characters
[ .. ]
When a list of characters are enclosed in square braces [..] then any character in that set will be matched.
Example: [abc] matches a, b, and c, but not d.
When a caret ^ appears at the beginning of the set, the match succeeds only if the character is not in the set.
Example: [^abc] matches d, e, or f, but not a, b, or c.
Sets can conveniently be described with a range. A range is specified by two characters separated by a dash,
such as [a-z]. The beginning character must have a lower ASCII value than the ending character.
Example: [a-z] matches any character in the range a through z, but not A or 1 or 2.
Sets can contain multiple ranges.
Example 1: [a-zA-Z] matches any alphabetic character.
Example 2: [^a-zA-Z0-9] matches any non-alphanumeric character.
Matching a Line Break
\n
This matches a new-line, or line-break. Use this when you want to match an end-of-line within a larger pattern.
Example: dog\ncat matches dog, followed by a line break, followed by cat.
Regular Expression Groups
\( and \)
Parts of a regular expression can be isolated by enclosing them with \( and \), thereby forming a group.
Groups are useful for extracting part of a match to be used in a replacement pattern. Each group in a pattern
is assigned a number, starting with 1, from left to right.
Example: abc\(xyz\) matches abcxyz. xyz is considered group #1.
This is not all that useful, unless we are using the Replace command. The replace string can contain group
characters in the form of \. Each time a group character is encountered in the replacement pattern,
it means "substitute the group value from the matched pattern".
Example 1: replace \(abc\)\(xyz\) with \2\1. This replaces the matched string abcxyz with the contents of
group #2 xyz, followed by the contents of group #1 abc. So abcxyz is replaced with xyzabc. This is still not too
amazing. See the next example.
Example 2: replace \(\w+\)\(.*\)ing with \1\2ed. This changes words ending in ing with the same word
ending with ed. Your English teacher would not be too happy.
Overriding Regular Expression Characters
\ (backslash)
A backslash character \ preceding a meta-character overrides its special meaning. The backslash is ignored
from the string.
110
Source Insight 4 User Guide
Regular Expressions
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.
Regular Expression Summary
The following special characters are interpreted in regular expressions
Table 3.7: Regular Expression Characters
Character
Matches
^ (at the beginning only)
beginning of line
.
any single character. In multi-line
mode, this also matches the endof-line character.
[abc]
any single character that belongs
to the set abc
[^abc]
any single character that does not
belong to the set abc
*
zero or more occurrences of the
preceding character
+
one or more occurrences of the
preceding character
\t
a tab character
\s
a space character
\w
white space (a tab or a space character)
\n
new-line, or the end-of-line character. Use this if you want to match a
line break in the middle of a pattern.
$
the end of the line
Sets, such as [abc] may be in the following formats.
Table 3.8: Regular Expression Sets
Set type
Meaning
[]
eg. [abcde]
Matches any character within the
set. The set can be any number of
characters long.
[x-y]
eg. [a-z]
Matches on any character within
the range of x through y, inclusively. The ASCII value of x must be
less than that of y.
combination;
eg. [WXYa-z0-9]
Character lists and ranges may be
combined.
Source Insight 4 User Guide
111
Comparing Files and Directories
Comparing Files and Directories
Source Insight can compare two files and show differences. It can also compare two different directories.
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.
112
Source Insight 4 User Guide
Comparing Files and Directories
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.
Figure 3.16 The Directory Compare window panel.
Source Insight 4 User Guide
113
Navigation with the Selection History
Navigation with the Selection History
The selection history is a circular list of your last 100 selection positions in the currently opened files.
You can use the Search > Selection History command to display and jump to positions in the selection history. The Selection History command also displays the function or symbol where each history item is located,
along with its file and line number.
The Selection History window looks like this:
Go Back and Go Forward commands
The Forward and Back buttons at the top left in the main toolbar work just like in a web browser. They invoke
the Go Forward and Go Back commands.
The Go Back command (Alt+,) jumps to the previous location in the selection history. The Go Forward command (Alt+.) jumps to the next location in the selection history. The selection history list is circular, so if you
reach the end of the list, the Go Forward and Go Back commands will wrap around to the other end of the list.
The Go Back and Jump To Definition commands make it easy to travel down a function call chain, and "pop"
back up the chain, and then travel down another path with a different function call.
114
Source Insight 4 User Guide
Scrolling and Selecting Text
Scrolling and Selecting Text
Scrolling around the selecting text is a basic operation, and there are a lot of commands for doing some variation of those things.
In Source Insight, a selection is a range of zero or more characters highlighted in a source file window.
Selected text is highlighted and displayed in the "Selection" style; usually an inverse color. You can change
the look of selected text by editing the Selection style in Options > Style Properties.
Each source file window has its own single selection. Switching between windows leaves the selections in
each window intact. The selection in the current window and current file is referred to as the current selection.
Selections can be made with the keyboard and the mouse. Commands used for selecting text are listed
below. To select text with the mouse, simply point at the text and drag across it. Double-clicking the left
mouse button selects a whole word.
Scrolling the window will only change the selection if the "Keep cursor in window when paging up and down"
option is turned on in the Options > Preferences: General dialog box. Otherwise, only cursor movement keys,
pointing with the mouse, or editing your file will change the selection.
Moving Through a File
There are many commands to move you around in a file. It's important to know that there are two types of
movement: selecting and scrolling.
Selecting is moving the current selection (usually an insertion point) around in the file.
Scrolling is when the file window is scrolled to reveal new parts of the file. You can scroll a window up, down,
left, and right. Scrolling does not always affect the location of the selection.
Selection commands can cause scrolling to occur if the place you are selecting is not visible in the window.
For example, if the cursor is on the bottom line of a window and use the Cursor Down command, the window
is scrolled to reveal the line below.
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 window
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
Source Insight 4 User Guide
115
Scrolling and Selecting Text
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 punctuation. You can use this for
camel-case words, such as
"OpenFileCore"
Word Fragment Right
Move right by a word fragment.
Function Down
Keypad +
Move to next function definition.
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 parentheses.
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 number.
Ctrl+G
116
Source Insight 4 User Guide
Scrolling and Selecting Text
Table 3.10: Cursor Movement Commands
Command
Key
Description
Search
Ctrl+F
Search for occurrence of a
pattern.
Search Forward
F4
Search for next occurrence.
Search Backward
F3
Search for previous occurrence.
Search Forward for
Selection
Shfit+F4
Searches for next occurrence
of the word under the cursor.
Selection History
Ctrl+Shift+M
Displays a list of your past
selections.
Extending the Selection
These commands will create an extended selection or extend an existing selection. The keystrokes listed are
the defaults.
Table 3.11: Selection Commands
Command
Key
Description
Select All
Hold down Ctrl and
click the mouse in the
selection bar at the
left.
Select the whole file.
Select Block
Ctrl+-
Selects the next smallest enclosing set of
braces or parentheses.
Select Function Or
Symbol
Double-click in selection bar at the left of
edge of the window
Select the whole
enclosing symbol definition.
Select Char Left
Shift+Left
Extends selection to
the left by one character.
Select Char Right
Shift+Right
Extends selection to
the right by one character.
Select Line
Shift+F6
Selects whole line.
Select Line Down
Shift+Down
Extends selection
down a line.
Select Line Up
Shift+Up
Extends selection up
by a line.
Select Match
Alt+=
Selects up to the
matching brace,
parentheses, or quote
mark.
Select Sentence
Shift+F7,
Selects whole sentence (up to the next
period).
Ctrl+.
Select Word
Shift+F5,
Selects whole word.
and
Double-click L. Mouse
Source Insight 4 User Guide
117
Scrolling and Selecting Text
Table 3.11: Selection Commands
Command
Key
Description
Select Word Left
Ctrl+Shift+Left
Extends selection to
include the whole
word on the to the
left.
Select Word Right
Ctrl+Shift+Right
Extends selection to
include the whole
word on the to the
Right.
Select To
Shift+L. Mouse
Extends the selection
to the current mouse
location. This is
assigned to the
mouse.
Select To Top Of File
Shift+Home
Selects up to the
beginning of the file.
Select To End Of File
Shift+End
Selects up to the end
of the file.
Select To End Of Line
Selects up the end of
the current line.
Toggle Extend Mode
When on, movement
keys extend the selection.
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.
Selecting Whole Words
Simply double-click on a word to select the whole word. You can drag out a selection in this mode to select
whole words.
Selecting Whole Functions or Symbols
To select a whole function, struct, or other type of symbol, simply double-click in the selection bar area of a
source file window. If you hold the mouse button down and drag, Source Insight will select whole functions
or symbols as you drag.
You can also use the Select Symbol command to select the symbol that encloses the current text selection.
The Symbol Window (on the left of the source file window) also can be used to select whole symbols. Doubleclicking on any entry in the list will select the symbol.
118
Source Insight 4 User Guide
Scrolling and Selecting Text
Selecting Matching Parentheses and Blocks
To select to the matching brace or parentheses, double-click on any parentheses, square brace, curly brace,
or double-quote mark. Source Insight selects up to its match. The Select Match command (Alt+equal) also
selects up to the matching brace or parentheses.
Selecting the Enclosing Block
The Select Block command (Ctrl+minus) selects the enclosing block. An enclosing block is one that is surrounded by either a parentheses, square brace, or curly brace. If you repeat this command, it will select the
next outer-most block.
Selecting a Whole Line
To select a whole line of text, simply click in the selection bar. A whole line of text will be selected. If you hold
the mouse button down and drag, whole lines will be selected. The Select Line command (Shift+F6) also
selects a whole line.
Selecting the Whole File
To select the whole file, hold down the Ctrl key and click the mouse in the left margin. Or, use the Select All
(Ctrl+A) command.
Selecting a Paragraph of Text
For files that do not have a language parser attached (See “File Type Options” on page 213), you can doubleclick in the selection bar to select a whole paragraph of text.
A paragraph is defined as a group of text lines surrounded by blank lines.
Selecting Between Lines
Source Insight allows you to select in between lines by providing a wedge shaped cursor when the cursor is
near the start of a line and slightly above or below it. When you click at that point with the mouse, Source
Insight selects the space between the lines. If you start typing, Source Insight automatically inserts a line
break first. This is a handy way to insert a new line.
Source Insight 4 User Guide
119
Scrolling and Selecting Text
The Overview Scroller
The Overview scroller is an optional control which appears at the right edge of source file window. It shows a
miniature version of you file, along with function boundary markers.
See “The Overview Scroller” on page 27.
120
Source Insight 4 User Guide
Outlining and Collapsing Text
Outlining and Collapsing Text
Source Insight can collapse blocks of source code using "outline" commands and collapse and expand buttons in the left margin or optionally indented with the code. The following shows outline buttons in the left
margin and a collapsed if statement.
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 369.
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.
Potential Outline Points
When Source Insight parses your file, it identifies potential lines that could be collapse. It displays outline
buttons near data structures such as structs and classes, and code blocks such as functions, if statements,
for statement, switch statements, and case labels. It also displays outline buttons near #ifdef and #pragma
region statements.
Source Insight 4 User Guide
121
Outlining and Collapsing Text
Outline Toolbar
Buttons
122
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.
Source Insight 4 User Guide
Code Beautifier
Code Beautifier
Source Insight has a code beautifier that works with C/C++, C#, Java and other language files that have similar 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 288.
Source Insight 4 User Guide
123
Generating HTML from Project Sources
Generating HTML from Project Sources
The Project > Export Project to HTML command generates HTML versions of your source files. It creates a
snapshot of your source code project that can be viewed with a web browser for online browsing and reference.
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.
124
Source Insight 4 User Guide
File Encodings
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.
Note:
For more information on character encodings, please visit:
https://www.w3.org/International/articles/definitions-characters/
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 support UTF-8, and UTF-8 supports a super-set of other regional encodings.
Encoding Is Associated with File Buffers
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 preserved between Source Insight sessions. However, if you close a file, and then open it again, the default
encoding will be used.
Changing the Default Encoding
Source Insight uses UTF-8 (Unicode) encoding by default when you first install it. However, if you typically
work with files that use a different encoding, such as Japanese Shift-JIS, or Chinese (Big5), then you should
change the default encoding.
Source Insight 4 User Guide
125
File Encodings
To change the default encoding, select Options > Preferences: File, and change the setting for Default encoding. 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".
Reloading a File With a Different Encoding
If you opened a file and the encoding looks incorrect, then you probably need to reload it with a specific
encoding. This can happen if the default encoding is set to something other than the encoding used by the
file. Unfortunately, the encoding scheme used in a file is usually not saved with the file. Therefore, it is possible to open a file assuming the wrong encoding.
To reload a file that is already open, and use a different encoding, select File > Reload As Encoding. Select the
encoding and click the Load button. If you edited the file before reloading it, Source Insight will ask you to
save the file first, because reloading the file with a new encoding will wipe out your changes, and it is not
undo-able. See “Reload As Encoding” on page 302.
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 selecting 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 preserved between Source Insight sessions. However, if you close a file, and then open it again, the default
encoding will be used.
Opening a File With a Different Encoding
If a file is not currently open, and you want to open that file with a specific encoding, select File > Open As
Encoding. Select the encoding and click the Open button to select the file. See “Open As Encoding” on
page 264.
This is used to open a file that is not already open. If the file is already open, you should use File > Reload As
Encoding.
126
Source Insight 4 User Guide
File Encodings
Saving a File With an Encoding
To save a file with a different encoding, select File > Save As Encoding. Select the desired encoding, then click
the Save button. See “Save As Encoding” on page 318.
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 different 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.
If you opened a file and it looks like text is garbled and it loaded with the wrong encoding, do NOT save the
file again using Save As Encoding. That will overwrite the file and potentially change it. Instead, select File >
Reload As Encoding. See “Reload As Encoding” on page 302.
Source Insight 4 User Guide
127
File Buffer Basics
File Buffer Basics
A file buffer is the temporary image of a file that you can edit in a source file window. All edits are recorded in
this temporary file buffer until a file is saved.
The File > Save command writes the file buffer contents back over the original file. This is the only time the
original file is changed.
Figure 3.17 Open and Save operations.
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.
Opening a Backup File
To open a backup version of the current file, select File > Open Backup File. See “Open Backup File” on
page 266.
Saving a New Backup File
Normally you don’t need to save your own backup files because they get created automatically when you
save files. However you can use the Save New Backup File command to take a snapshot of the current file
buffer and save it as a new backup file. The new backup is added to the existing backup files in the Backup
folder.
To open a backup version of the current file, select File > Open Backup File. See “Open Backup File” on
page 266.
Backup Folder Location
Backup files are stored in the Backup folder of the current project. You can edit the Backup folder location by
using Project > Project Settings.
Backup File Names
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 random
value to make the file name unique in the Backup directory.
128
Source Insight 4 User Guide
File Buffer Basics
Comparing a File with a Backup Version
To compare the current file with a backup version of the same file, select Tools > Compare With Backup File.
See “Compare with Backup File” on page 176.
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 opening 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.
Reloading and Restoring Files
To reload a file, use the Reload File command. This loads the file from disk again, losing all undo information.
It’s exactly like closing the file, then opening it again. You cannot use Undo to undo any prior changes.
To restore a file to its original state when you first opened it, use the Restore File command. This loses all
changes you made since you first opened it. It does not reload the file from disk. It returns the file to the way
it looked when you first opened it. You can use Undo to undo the Restore File operation.
To open an older version of your file, use the File > Open Backup File command to pick a backup file and load
it. The backup file will open in a new source file window and won’t alter the current file.
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 351.
Source Insight 4 User Guide
129
Recovering From Crashes
Recovering From Crashes
Your unsaved edits are saved periodically in the background to a temporary recovery file. This saving process
is very fast and you will usually not notice that anything is being done. You will not be interrupted. Note that
Source Insight does use an automatic-save style of protection, because the recovery file is much more efficient.
The recovery file actually only contains pointers to other files. Therefore, it is small and fast to write out. By
saving edits incrementally to the recovery file, Source Insight insures you against a system failure, power outage, or crashes. Source Insight will recognize when a recovery needs to be done the next time you run it.
You can set how often the recovery file is saved in the Options > Preferences: General dialog. The default
value is every 15 seconds. If you make the recovery time smaller, the recovery file is updated more often. If
you make it too long, you will be able to do many changes to your files without the changes being recorded in
the recovery file. The recovery save process is usually quick, so you should the keep the period as short as
possible.
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 session. 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 recovery, 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.
130
Source Insight 4 User Guide
Recovering From Crashes
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.
Source Insight 4 User Guide
131
Command Line Syntax
Command Line Syntax
Source Insight's command line has the following syntax:
sourceinsight4 [-option] [ [+linenumber file] [+file] [file] [symbolname] ]
Optional parameters are shown here inside […] brackets. Any number of options, files, and symbol names
may be given on the command line.
Each option given on the command line must be preceded by a dash (-) or a forward slash (/).
Specifying File Arguments
Each "file" argument may be one of the following types:
•
A regular file name. If more than one file exists with that name, then a list will be shown and you will be
able to pick the exact file.
•
A symbol name. Since Source Insight treats file names as symbols, each file argument can be more
generally thought of as a symbol. Source Insight will open the file where the symbol lives and jump to
its location. You may specify any number of symbols. If the symbol name conflicts with file names
(without extensions), or with other symbols, then a list will be shown and you will be able to pick the
exact symbol instance.
•
The name of a workspace file, including the .siwork extension. Source Insight will open all the files
contained in the workspace.
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 an Additional File
Each file name may be optionally preceded with a plus sign (+) only. In this case, the file is opened along with
the other files in the current workspace.
For example:
sourceinsight4 +file.c
This will open file.c along with all the files previously open in the current workspace.
If one or more files are specified on the command line without the plus sign prefix, then the files previously
open in the current workspace are not opened. Instead, only the files specified on the command line are
opened.
For example:
sourceinsight4 file.c other.c
This will open only file.c and other.c. The previously opened files in the current workspace are not
opened.
132
Source Insight 4 User Guide
Command Line Syntax
Jumping to a Symbol Definition
If you specify a symbol name that does not happen to conflict with a file name, then Source Insight will open
the correct file and jump to the definition. For example:
sourceinsight4 OpenTcpPort
This will open the file containing OpenTcpPort and jump to its definition. You can combine multiple symbols
on the command line.
How a File is Located
When a relative file name path is given on the command line, Source Insight first tries to find the file relative
to the directory that you started Source Insight in. If it can't find the file and a project is open, it looks for the
file in the project's file list.
In other words, you can start Source Insight in any directory and give it a file name, and if the file is in the current project, Source Insight should find it. If there happens to be a file with the same name in the startup
directory (or relative to it), then Source Insight will open that file.
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.
Command Line Options
The following options may be included on the Source Insight command line.
Suppressing New Program Instances
-i
This option will direct the rest of the command line to an already running instance of Source Insight, if any. If
there are no instances already running, then a new instance is started.
Example:
sourceinsight4 –i myfile.cpp
This will locate an already running instance of Source Insight, and tell it to open myfile.cpp.
Always Starting a New Program Instance
-ni
This option will start a new instance of Source Insight, even if one is already running.
Example:
sourceinsight4 -ni myfile.cpp
Normally, if you invoke Source Insight with one or more file name on the command line, and another
instance of Source Insight is already running, then the files will open in the existing instance of Source
Insight. A new Source Insight instance is not launched. This option forces a new instance to launch.
Source Insight 4 User Guide
133
Command Line Syntax
Running a Source Insight Command
-c
This option will start Source Insight, and run the specified command. The command can be a built-in command, or a defined custom command, or a macro command.
To invoke a macro command, use the name of the macro function, but do not include parentheses. There is
no way to pass parameters to a macro function from the command line. For example:
sourceinsight4 -c MyMacroFunction
Specifying a Project to Open
-p
This option closes the current project, if any, and opens the project given in project-name. If the project
does not exist, Source Insight will give an error message.
Example:
sourceinsight4 -p myproj
Closing the Current Project
-pc
This option closes the current project if one is open. No other project is opened.
Example:
sourceinsight4 -pc
Using a Temporary Project
-pt
This option closes the current project, if any, and opens the project given in projectname. Unlike the -p
option, the next time you run Source Insight, the old current project is opened. This is useful if you want to
put a Source Insight command in a batch file, but don't want the current project to be changed.
Example:
sourceinsight4 -pt mail
Finding a Symbol
-f
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
Synchronizing Project Files
-u
This option updates all project files right away when Source Insight starts. It is exactly like using the Synchronize Files command on the Project menu.
Example:
sourceinsight4 -u
Synchronizing Files in Batch Mode
-ub
This option is like -u except that Source Insight quits after the files are updated. This is useful for putting a
command in a batch file to synchronize Source Insight projects.
134
Source Insight 4 User Guide
Command Line Syntax
Example:
sourceinsight4 –ub
Suppressing the Splash Screen
-s
This option turns off the Source Insight splash screen that normally appears when starting up.
Comparing Files
-d
This option open the File Compare window and compares the two given files. See “File Compare” on
page 205.
Resetting All Settings
-reset
This option tells Source Insight to reset all optional settings: the configuration, the layout, and any session
information. You will be prompted and asked which things you want to reset.
Resetting Configuration Options to Defaults
-reset-config
This option tells Source Insight to reset all optional settings in the configuration. This includes things like the
color settings, styles, key bindings, and all options set on the Options menu.
Resetting the Display Layout
-reset-layout
This option tells Source Insight to reset the window layout to defaults.
Source Insight 4 User Guide
135
User-Level Commands
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 261.
User-level commands can also be implemented by Source Insight macro functions. See “Macros as Commands” on page 375.
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.
136
Source Insight 4 User Guide
Custom Commands
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 commands are saved in the current configuration.
Custom commands are useful for launching a compilation. By having a custom command that runs the compiler 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 261.
Source Insight 4 User Guide
137
Customized Settings and Configurations
Customized Settings and Configurations
You can customize many aspects of Source Insight, such as the color of the screen and the assignments of
keystrokes to commands. This collection of options is stored in a configuration file.
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.
Customizing the Keyboard and Menus
A command is a user-level operation that Source Insight performs when you select a menu item or type a
keystroke. 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 assignments are part of a configuration.
Source Insight also lets you define custom commands, which are useful for launching the compiler and other
external tools from Source Insight.
See “Custom Commands” on page 137.
Assign keys to a command with Options > Key Assignments.
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 Options > Key
Assignments command to customize the keyboard. See “Key Assignments” on page 239.
Assign commands to menus with Options > Menu Assignments.
Commands are assigned to menus. For example, the Open command is assigned to the File menu. Use the
Options > Menu Assignments command to customize the contents of the menus. See “Menu Assignments” on
page 261.
Changing Screen Colors and Appearance Options
There are several screen color options in Source Insight, and options that control appearance.
Changing the Visual Theme
To quickly change the visual theme, select Options > Visual Theme and choose a theme. You can also change
and define new themes. See “Visual Themes” on page 144.
Changing Color Settings
To change screen colors for the main application window and various display elements, use the Options >
Preferences: Color command. See “Color Options” on page 172.
138
Source Insight 4 User Guide
Customized Settings and Configurations
Each panel window has its own font and color settings. Edit the settings and select the desired fonts and colors 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.
Changing the Appearance of Source Code
Source Insight has many display options for formatting source code.
To fine-tune options about how syntax elements are formatted in general, select Options > Preferences: Syntax Formatting, and Options > Preferences: Syntax Decorations.
See “Syntax Decorations” on page 352.
See “Syntax Formatting” on page 355.
To change the appearance of syntax elements, such as how delimiters are styled, or how declarations appear,
select Options > Style Properties. This controls the colors, fonts, font sizes, and other styling applied to these
elements. See “Style Properties” on page 342.
Changing Various Options
The Options > 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. See “Preferences” on
page 273.
The Configuration File
Source Insight maintains a configuration file called config_all.xml, stored in the Settings subdirectory of
your Source Insight user directory. (Typically Documents\Source Insight 4.0\Settings.) You don't need
to load or save this file yourself. That is done automatically. It is saved whenever you make any change to a
configuration setting.
Source Insight 4 User Guide
139
Customized Settings and Configurations
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 command 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 configuration 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 configuration 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 customizations. 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.
Configuration Master File
A special file named config_master.xml specifies where the various configuration parts come from. It is
stored in your Source Insight user directory in the Settings sub directory. It gets created the first time you run
Source Insight. Normally it does not need to ever change after that.
140
Source Insight 4 User Guide
Customized Settings and Configurations
A typical config_master.xml file looks like this:
Storing All Settings in One Configuration File
An important option in config_masterl.xml is in the Options section: an attribute named OverrideWithFile. If this value points to a file, then ALL the configuration parts are maintained in that single file. This is
the simplest arrangement, and it is the default setting.
Storing Configuration Parts in Separate Files
If you prefer to store different parts of the configuration in several files, set the Option attribute OverrideWithFile to an empty string. Then the ConfigurationParts XML element is used.
The ConfigurationParts element contains elements for each configuration part. In each part, the value of
the file attribute is the file that will contain the given configuration part. For example, Menu settings could
be maintained in "config_menus.xml".
Project-Specific Configuration Parts
You may want to have some configuration part be specific to each project. In this case, the configuration part
file is stored along with either your project's source code, or the project's data directory.
Source Insight 4 User Guide
141
Customized Settings and Configurations
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 project's source files are. You can see and
edit this path in Project > Project Settings.
project_source:config_keymaps.xml
project_data:
Points to the directory where your project's data files are maintained. This is
specified when you first create your
project.
project_data:config_menus.xml
Grouping Configuration Parts into Files
You can group more than one configuration part in a file by specifying the file in multiple configuration part
file attributes. For example, you could save the Menus and Keymaps configuration parts in a single file
named config_menu_keymap.xml with these attributes:
....
....
Loading a Configuration
Use the Options > Load Configuration command and select a new configuration file to be loaded. This command 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 251.
Importing Configuration Settings from Version 3
Source Insight looks for an older version when you first install and run it. If it finds an old configuration file, it
will prompt you to import the settings.
To import version 3 configuration settings at any time, select Options > Load Configuration, and navigate to
your version 3 configuration file. It is usually stored here:
C:\Users\\Documents\Source Insight\GLOBAL.CF3\
where C: is your system drive letter, and is the account user name.
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 319.
142
Source Insight 4 User Guide
Customized Settings and Configurations
Resetting the Configuration to Defaults
There are a couple ways to reset all the configuration settings to the factory defaults:
•
Select Options > Preferences: General and click the Use Defaults button. Or,
•
From the command line, use the -reset-config option. For example:
sourceinsight4.exe -reset-config
When you reset the configuration, your previous configuration settings are backed up into another file in the
Setting folder. You can use the Options > Load Configuration command to reload it.
Source Insight 4 User Guide
143
Visual Themes
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 258.
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 settings 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 configuration file gets saved.
See “Customized Settings and Configurations” on page 138.
Defining a Visual Theme
Once you set all the colors, fonts, and styles they way you like them, use the Manage Visual Themes dialog to
record all the settings into a new theme. Click the Define button and the Define Visual Theme dialog appears.
144
Source Insight 4 User Guide
Visual Themes
To define or re-define a theme:
1. First select all the color and font settings you would like to record as theme. Use the Options > Preferences: Color tab to select user interface colors.
2.
Use the Options > Style Properties command to define syntax formatting styles.
3.
Each panel window has its own font and color settings. Edit the settings and select the desired fonts
and colors 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.
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.
Source Insight 4 User Guide
145
Saving Window Arrangements with Layouts
Saving Window Arrangements with Layouts
You can save and load window arrangements using layouts. 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.
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 toolbar.
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.
The Layout Toolbar
The Layout toolbar contains buttons so you can quickly switch between layouts.
Load Layout A-D
146
Create New Layout
Load Other
Source Insight 4 User Guide
Saving and Restoring Workspaces
Saving and Restoring Workspaces
A workspace contains session state that changes from session to session, such as the list of open files. A
workspace contains the following things:
•
The names of the files you have open
•
Selections in each file
•
Selection history (where you have been in each file)
•
The size and position of each source file window
•
Search and replace strings
•
Source links
•
Dialog box typing history
•
The command recording (see “Start Recording” on page 342.)
When you exit Source Insight, the current workspace is saved in a workspace file. When Source Insight starts,
it restores the previous session's workspace.
If a project is not open, then the name of the current workspace file is Global.siwork. If a project is open, the
name of the current workspace file is .siwork and it is stored in the project's data directory.
Loading and Saving Workspaces
To open a workspace, use the File > Load Workspace command.
You can use the File > Save Workspace command to save the contents of the current workspace to any other
workspace file.
Managing Tasks With Workspaces
By using multiple workspaces, you can group your tasks, and save them individually.
For example, let's say you have two different tasks on which you are working. For task 1, you open all the
source files for that task and begin working. When you want to stop working on task 1, you use the Save
Workspace command to save the file "Session1" (or whatever name you want to use). Close all files, and
open the source files to begin working on task 2. When you want to stop working on task 2 and resume working on task 1, use the Save Workspace command to save the file "Session2", then use the Open Workspace
command to open the task 1 session, "Session1".
Source Insight 4 User Guide
147
Performance Tuning
Performance Tuning
Depending on the size of your project, you may want to tune Source Insight for better performance. The Preferences dialog box, and the Project Settings dialog box both contain options that affect performance.
Factors That Affect Performance
Source Insight was designed to push some of the limits of functionality for a programming editor. As such, it
has features that can stress a system that is too slow or not optimized for it. This section describes factors
that you can control which affect Source Insight's 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.)
Project Index Settings
The Project Settings dialog box contains options for indexing your project. If you enable all the indexing
options, and your project is large, you may hurt performance.
The symptoms of too large an index are:
•
Disk thrashing while building or rebuilding a large project, with little progress is being made. It is normal for a very large project to require a significant amount of disk access near the end of the rebuilding
phase.
•
Opening or closing a project takes a long time.
•
Synchronizing individual files is slow.
•
The Project Symbol List window (F7) is slow to come up, accompanied by a lot of disk activity. It is normal for this to pause a second or two the first time you use it.
Tip: Name Fragment indexing a large project can be slow and memory intensive
If you have a large project (over 500,000 symbols) you should try turning off the symbol name fragment
indexing. 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 number of
index entries is over 1 million, then things can start to slow down. Adding more memory to your machine will
improve performance.
To remove the name fragment indexing, run the Project > Project Settings command and turn off Quick
browsing for symbol name fragments. Then use the Rebuild Project command to recreate your project from
scratch.
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 projects can use a lot of virtual memory.
148
Source Insight 4 User Guide
Performance Tuning
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.
Custom Parsing Expressions
You can augment a language with your own custom parsing regular expressions. You can edit these expressions by right clicking on a source file and selecting Language Properties.
Be careful with the custom parsing expressions you define. If you have too many expressions, or you are
using a regular expression that is inherently slow to match, you may notice that it takes a moment or two to
parse your files.
A regular expression can be slow to match if it starts with a pattern that is easily matched, but ends with a
pattern that often does not match. For example:
[a-z]*(\([a-z]+\))
This expression will be slow to match because the pattern starts with [a-z]*, which means, "match any zero
or more alphabetic characters". Most characters in a file will potentially match, cause the pattern matcher to
try and fail to match many times.
Location of Files on a Network
While it is possible to add source files to your project from a remote network drive, that can cause Source
Insight to slow down because access to network drives is slower in general.
In addition, locating the project data folder on a network drive can also result is poor performance. We recommend locating the Project Data Directory on your local, non-networked drive.
Location of the "Documents" Folder
In Windows, the "Documents" folder is a virtual folder that can exist either locally, or on a remote network
drive. Since Source Insight stores per-user data inside that folder, some operations can become slow if you
locate this folder on a remote drive. In particular, if you used the Import External Symbols feature, the resulting import project symbols are stored in the Documents\Source Insight 4.0\Projects folder. Therefore
auto-completion while typing can become slow.
If possible, locate your "Documents" folder on your local drive. If you cannot do that, then you can set a registry entry to force Source Insight to use a local drive for the per-user data folder.
In regedit.exe, find the key:
HKEY_CURRENT_USER\Software\Source Dynamics\Source Insight\4.0\Paths
Add a new string value named "UserDataDir". Set the string value to the full path of the folder you want to
user for per-user data.
Speeding Up Program Features
This section contains recommendations for speeding up different aspects of Source Insight.
Speeding Up Syntax Formatting
Source Insight has many interesting and useful display features for formatting source code. Some of those
features require a significant amount of processing.
Source Insight 4 User Guide
149
Performance Tuning
The display code has been sped up considerably to be able to provide more features with acceptable performance. 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
Formatting "references" is slower than "declarations".
In general, identifying "references" is slower than "declarations". Identifying references to symbols can be
slower if the project is very large, because each reference has to be resolved with a symbol lookup.
The symbol lookup engine has been heavily optimized to allow formatting references to symbols at "display
speed". A lot of information is cached in the process, so you may notice that the first time you open a file and
start scrolling around in it, it may slow down sometimes. Subsequent viewing of the file will speed up.
Some people want the fastest possible display. However, you may be willing to sacrifice a little of that speed
in turn for more useful information that increases productivity.
Speeding Up Typing in Browse Dialog Boxes
Typing and filtering symbol lists can become slow if you have a large project, and you have the Project Settings: Quick browsing for symbol name fragments turned on. Source Insight is trying to perform name fragment matching on a large name fragment index.
You can address this two different ways. Either you can turn off name fragment indexing in the Project Settings dialog box, or you can change the behavior of the list filtering with the Preferences: Typing dialog box.
The Project Settings options control what is stored and indexed in the symbol database.
The Preferences: Typing options control how the information is used in the lists. You do need the name fragment information in the database to use the symbol name fragment matching features of the lists. (But, not
for file name lists.)
If memory permits, leave Project Settings: Quick browsing for symbol name fragments enabled, and turn off
Preferences: Typing: Match name fragments while typing. Even with name fragment matching while typing
disabled, you can still use it by prefixing what you type with a space. That is, prefixing what you type with a
space toggles the name fragment matching on and off.
If you encounter a lot of disk thrashing while trying to match any name fragments in lists, then your project
may be just too big for the available memory.
In Preferences: Typing, turning off both "Match name fragments" and "Match members" will speed it up
more and return list filtering to version 2.1 functionality.
150
Source Insight 4 User Guide
Performance Tuning
Speeding Up Building and Synchronizing Projects
A very large project will take a while to build or rebuild. To speed it up, you can try the following:
•
In Project Settings, turn off Quick browsing for symbol name fragments. This index option uses a lot of
memory and slows the indexing process.
•
In Project Settings, turn off Quick browsing for member names. This index option can use a lot of
memory also.
•
Reduce the number of file types that are added to your projects. By default, Source Insight comes with
many file types defined, such as Visual Basic files, and ASP files. If you have files like that in your source
tree, but you have no need to work on them, then remove them from your project. You can permanently exclude those file types from your projects by selecting Options > File Type Options and unchecking the option Include when adding to projects – for each type of file you want to exclude from
your projects.
•
Break your project into smaller projects. If you want to still use the Jump To Definition command
between the projects, you can add the "sub-projects" to the project symbol path, which is defined in
the Preferences: Symbol Lookups dialog box.
Speeding Up Relation Windows
The Relation Window shows relationships between symbols. It works like the Context Window in that it
works in the background and automatically shows information about what is selected. For example, if you
select a function call, it can show you the call tree starting at that function.
The Relation Window can require a lot of processing. Some relationships are slower to compute. The relationships fall into three categories, listed here from fastest to slowest:
•
Contains – show the contents of the current symbol. For example, show members of a struct.
•
Calls – show what other symbols are referred to by the current symbol. For example, show functions
that are called by the current function.
•
References – show what other symbols refer to the current symbol. For example, show functions that
call the current function.
It Takes More Work to Show References
For very large projects, the "References" relationship will be by far the slowest to compute. The performance
seems very acceptable on a Pentium II machine with a moderate sized project (about 200,000 lines of code).
Limiting the relations to non-reference type relations will speed the Relation Window up.
It also works well to lock the Relation Window. To lock the Relation Window, click on the lock button in the
Relation Window toolbar. You can refresh the Relation Window at any time by using the Refresh Relation Window command, or by clicking on the Refresh button in the Relation Window toolbar.
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.
Speeding Up Searching Files
Use Lookup References instead of Search Files.
There are several ways to search across multiple files in Source Insight. The commands: Search Files, Lookup
References, and Search Project all perform multi-file searches.
Source Insight 4 User Guide
151
Performance Tuning
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.
Speeding Up Lookup References
The Lookup References command has a few options that affect its speed.
The Smart Reference Matching option means that the search is scope and context-sensitive; the search
results will only contain matches for references to the exact symbol you specify, using the surrounding context. This option slows the process down because each same-string occurrence has to be qualified with a
symbol lookup, which requires some parsing on the fly. If you turn this off, it will work like the Search Files
command; that is, it will search for the string across all the project files.
The Skip Comments and Search Only Comments options also slow the search down a little, but not as much
as the smart reference matching option.
152
Source Insight 4 User Guide
Predefined Path Variables
Predefined Path Variables
Predefined path variables are path variables that set to some of the most commonly used folders. You can
use path variables in several option dialogs, such as the Project Settings dialog. Path variables are not case
sensitive.
Table 3.12: Predefined Path Variables
Variable
Value
%APPDATA_DIR%
The current user’s roaming application data folder.
%DESKTOP_DIR%
The Windows desktop folder.
%LOCAL_APPDATA_DIR%
The current user’s non-roaming application data folder.
%MYDOCUMENTS_DIR%
The current user’s documents folder.
%PROGRAM_DIR%
Folder that contains the Source Insight program.
%PROGRAMFILES_DIR%
The Windows Program Files folder. Eg. C:\Program Files
%PROGRAMFILESX86_DIR%
The 32-bit Program Files folder. Eg. C:\Program Files (x86)
%PROJECT_DATA_DIR%
The current project’s data directory, which contains the data
files maintained by Source Insight.
%PROJECT_SOURCE_DIR%
The current project’s source directory root, which is set in Project Settings.
%PROJECT_NAM%E
The simple name of the current project, with no extension or
path.
%SHARED_DOCUMENTS_DIR%
The public or shared Windows document folder.
%SOURCEINSIGHT_USER_DIR%
The current user’s Source Insight document folder. This is typically C:\Users\\Documents\Source Insight 4.0
%TEMP_DIR%
The temp file directory where Source Insight creates temp files.
%WINDOWS_DIR%
The Windows directory.
Source Insight 4 User Guide
153
Files Created by Source Insight
Files Created by Source Insight
Source Insight creates the following files and file types on your hard disk.
Files in the Program Directory
The following files are created in the installation directory when Source Insight is installed. The installation
directory is the destination directory you specified when you ran the setup program.
File
Description
sourceinsight4.exe
The Source Insight program.
sourceinsight4.chm
The Source Insight Help file.
ReadMe.txt
Text file containing last-minute notes.
Sihook4.exe
Utility program used by Source Insight to launch Custom Commands.
FileAlias.txt
File name alias file, used to override the file type associated with a given file name. This file is copied to your
user document area when you first run Source Insight.
If you need to edit this file, you should edit your user
copy.
reflector.exe
Utility program for importing .NET assemblies.
reflector.class
Java utility for importing Java symbols
Per-User Data Folder
In Windows, the "Documents" folder is a virtual folder that exists separately for each user. Source Insight
stores per-user data inside Documents\Source Insight 4.0.
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 possible, locate your "Documents" folder on your local drive. If you cannot do that, then you can set a registry entry to force Source Insight to use a local drive for the per-user data folder.
In regedit.exe, find the key:
HKEY_CURRENT_USER\Software\Source Dynamics\Source Insight\4.0\Paths
Add a new string value named "UserDataDir". Set the string value to the full path of the folder you want to
user for per-user data. You will need to restart Source Insight after that, and you may have to recreate your
projects.
Files Created for Each User
Each user logged into Windows gets their own personal data folder, known as "Documents". Source Insight
creates a "Source Insight 4.0" folder under the "Documents" folder to contain user-specific data.
The user data directory contains the user-specific configuration settings file (config_all.xml) and the workspace file for the "no project open" mode, and project data.
154
Source Insight 4 User Guide
Files Created by Source Insight
The following folders are created in the current user's Source Insight folder:
File or Folder
Description
Backup
Folder containing non-project backup versions 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 Window.
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 information 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 directory of Source Insight.
Files Created for Each Project
When you create a Source Insight project, a project sub-folder is created inside the "Documents\Source
Insight 4.0\Projects" folder. The project folder is named the same as the project name.
For example, if you create a project name "Abc", then a project folder is created:
C:\Users\\Documents\Source Insight 4.0\Projects\Abc
Within that folder a file name Abc.siproj is created which is the main project file. Additional data files are
stored in that folder.
The following files and folders are created in the project directory. In this list, "Name" is the name of a given
project.
File
Description
Name.siproj
The main project file, which contains a list of
the files in the project. You can open this file
directly from the Project > Open Project >
Browse dialog.
Name.siproj_settings
Project settings file.
Name.siwork
The project workspace file.
Source Insight 4 User Guide
155
Files Created by 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
156
Source Insight 4 User Guide
Commands Overview
CHAPTER 4
Command Reference
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 keystroke. 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 assignments 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.
About Source Insight
The About Source Insight command brings up a window that contains the copyright message and the version
number of Source Insight. You should refer to this window to get the version number and build date of Source
Insight.
Source Insight 4 User Guide
157
Commands Overview
Activate Menu Commands
•
Activate Edit Menu
•
Activate File Menu
•
Activate Help Menu
•
Activate Option Menu
•
Activate Project Menu
•
Activate Search Menu
•
Activate Tools Menu
•
Activate View Menu
•
Activate Window Menu
•
Activate System Menu
•
Activate System Doc Menu
The Activate Menu commands activate and drop down the menu from the menu bar.
You can also just press and release the Alt key to activate the Source Insight menu bar, then just type a letter
to activate the corresponding menu. For example, Alt F activates the File menu.
Source Insight does not use Alt+
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.6
Linearized : Yes
Encryption : Standard V2.3 (128-bit)
User Access : Print, Extract, Print high-res
Language : en
Tagged PDF : Yes
XMP Toolkit : Adobe XMP Core 5.4-c005 78.150055, 2012/11/19-18:45:32
Format : application/pdf
Description : User Guide for Source Insight 4.0 Software
Title : Source Insight 4.0 User Guide
Creator : Source Dynamics, Inc.
Producer : Acrobat Distiller 11.0 (Windows)
Copyright : 2017 Source Dynamics, Inc.
Creator Tool : FrameMaker 2015.0.4
Modify Date : 2017:02:26 22:02:15-08:00
Create Date : 2017:02:23 13:27:30Z
Metadata Date : 2017:02:26 22:02:15-08:00
Document ID : uuid:c9ff0e69-b548-4300-a544-0e3eeb3e669c
Instance ID : uuid:1ece37e8-01a3-4c8d-8e1b-e50462e53cd6
Page Mode : UseOutlines
Page Count : 434
Author : Source Dynamics, Inc.
Keywords : Source, Insight
Subject : User Guide for Source Insight 4.0 Software
EXIF Metadata provided by EXIF.tools