CHAPTER 4
Command Reference
Commands Overview
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 37.
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 132.
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 151
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 <release> F activates the File menu.
Source Insight does not use Alt+<menu letter> by default to activate a menu. The Alt key can be combined with any character and assigned to any command by using the Key Assignments command. If you want to make Alt+F activate the File menu, for example, you can just make that key assignment. If you want to assign any key combination to activate the File menu, you can do that.
Activate Clip Window
Opens and selects the Clip Window. The Clip Window holds small pieces of text that can be pasted quickly.
See “Copy To Clip” on page 176
Activate FTP Browser
Opens and activates the FTP Browser panel.
Activate Project File List
Opens and activates the Project File List panel so you can start typing in the name of a file to open.
Activate Project Search Bar
Opens and activates the Project Search Bar, which appears near the top of the main application window.
Activate Project Symbol List
This command makes the Project Symbol List panel visible; showing all project symbols in a list, and puts the cursor in the text box at the top. Once activated, you can type into the text box and the symbol list will be filtered based on what you type. Pressing Enter or Esc will re-activate your source file window again.
This is a quick way to navigate to functions or symbols within your project.
See “Project Symbol List” on page 274.
152 Source Insight 4 User Guide
Commands Overview
Activate Project Window
Opens and activates the Project Window. The Project Window usually contains multiple tabbed panels. The last tab that was active is made active again.
Activate Relation Window
Opens and selects the Relation Window. The input focus is moved to the Relation Window.
See “Relation Window” on page 297.
Activate Search Bar
Opens and activates the file Search Bar, which appears above the source window area. The Search Bar lets you search within the current file.
Activate Search Results
This command simply activates the Search Results window and brings it to the front, if it is open. This provides a quick way to return to the Search Results.
Activate Snippet Window
Opens and activates the Code Snippet panel.
Activate Symbol Window
This command makes the Symbol Window visible and puts the cursor in the text box at the top. Once activated, you can type into the text box and the symbol list will be filtered based on what you type. Pressing
Enter or Esc will re-activate your source file window again.
See “Symbol Window command” on page 339.
Activate Window List
Opens and activates the Window List panel, which displays all the open source files.
Add and Remove Project Files
This command lets you add source files to the current project, or remove source files from the current project.
This is the primary way to add a large number of files to the project. With this command, you can add and remove single files, groups of files, and whole source directory trees.
Note:
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.
What Files Should You Add to a Project?
Tip:
Add only text files to your projects.
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.
Source Insight 4 User Guide 153
Commands Overview
The file types that are defined by default in Options > File Type Options correspond to the types of source files you probably want to use with Source Insight. Normally, only those types of files should be added to a project.
Tip:
Use
Options > File Type Options
to control what types of files are added to projects.
The File Type Options dialog box contains the check box: Include when adding to projects. You can use this check box to control what file types Source Insight will automatically add to your project, or what file types will be displayed in the list box in the Add and Remove Project Files dialog box.
Using a 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 44.
Add and Remove Project Files Dialog Box
File Name
Type the name of the file you want to add or remove in this text box. The lists will be matched automatically with what you type. You can type a wildcard and press Enter to filter the file list to show only those files that match the wildcard.
You can also type a full directory path, or a drive letter followed by a colon to switch the current directory.
154 Source Insight 4 User Guide
Commands Overview
Directory List
Contains a directory tree of the current drive. If you select a directory name in this list box, the File Name list will show what is in that directory. The current working directory and wildcard filter, if any, is displayed above the list box.
File Name List
Contains a list of all files in the currently selected directory. If you select a file from this list box, the file name is loaded into the File Name text box. This list box will not display files that are already part of the project.
Project Files List
Lists all the files currently added to the project. You can select files from this list and click the Remove… buttons to remove the files from the project.
Close
Closes the dialog box, keeping the changes you made.
Add
Adds the selected file(s) to the project. If a directory is selected, then the current directory switches to that directory.
Add All
Selects all the items in the File Name list and adds them to the project. If any directories are included, then their contents are added too. Source Insight will prompt you first to see if you want to include the directories.
Add Tree
Click Add Tree to add a whole source tree to your project.
When a directory is selected, this adds the whole directory tree to the project. That is, all the directories in the sub tree are scanned for files that match known file types, and they are added to the project.
Remove Tree
When a directory is selected, this removes all files found in that directory tree.
Show only known file types
Only files that are defined in Options > File Type Options are included in the file list. Furthermore, only file types that have the "Include when adding to project" option enabled are included. You can change the known file types with the File Type Options command.
If not enabled, then all file types are listed in the File Name list. You should only add text files to a project, and not binary files.
Remove File
Removes the file(s) selected in the Project Files list.
Remove All
Removes all files from the project. The project will be empty.
Remove Special…
Brings up the Remove File dialog box, which allows you to do special remove operations, such as removing all *.h files.
Add from list…
Brings up the Add File List dialog box. This asks you to specify an input text file that contains a list of files and directories to be added to the project.
Source Insight 4 User Guide 155
Commands Overview
Add File
The Add File command adds one or more source files to the current project. This command existed in earlier versions of Source Insight, however the Add and Remove Project Files command is a newer replacement, which provides a central dialog box from which to add and remove files from your project.
File Name
The name of the file to be added to the project. You may type a file name or a wildcard pattern and press
Enter. If you typed a wildcard, the pattern will be applied to the file list box.
File list box
Contains a list of all files in the current working directory of the current drive that are not already a part of the current project. If you select a file from this list box, the file name is loaded into the File Name text box. The current working directory is displayed above the list box. This list box will not display files that are already part of the project. Also, only files that belong to file types that have the "Include when adding to project"
option turned on are included in the list. See “File Type Options” on page 207.
Add
Click this button to add the file named in the File Name text box to the project and close the dialog box. If the
File Name text box contains wildcard characters, the wildcards will be expanded and displayed in the File list box, and the dialog box will not be closed. If one or more files are selected in the File list box, then all selected files are added to the project.
Select All
Click this button to select all the files contained in the File list box.
Add Dir
Click this button to add a whole directory to the project. If the Subdirs Also check box is enabled, then this will recursively add all files in the whole subdirectory tree.
Show Dirs
Click this button to toggle the list box contents between showing file names, and showing subdirectory names.
Subdirs Also
If enabled, then Source Insight will recurse through all subdirectories when the Add button is clicked, or when a single directory is selected and Add is clicked.
If not enabled, then Source Insight will only add the selected files or the files in the selected directory and will ignore sub-directories.
Browse
Click this button to bring up the standard Windows Open dialog box, which allows you to browse around your disks. If you select a file in this dialog box, its path will be placed into the File Name text box.
Remove
Click this button to switch to the Remove File dialog box.
Add File List
The Add File List command allows you to add file names and directories specified in an input file to the current project.
This is a useful way to let you, or a project administrator, maintain a list of source files and/or source directories, which can be used to build a Source Insight project. This can be done in lieu of adding the files by hand.
156 Source Insight 4 User Guide
Commands Overview
Advanced Options
This allows you to selectively disable internal optimizations in Source Insight. This can help to narrow down a possible bug. If you report a bug, you may be asked to make changes in the Advanced Options dialog box to help troubleshoot a problem. Normally, you should have no need to use this feature.
Arrange Windows
Tiles and arranges source file windows within the Multiple-Document area.
Arrangement Toolbar
Shows or hides the Window Arrangement toolbar.
Back Tab
The Back Tab command moves the cursor to the left by one tab stop.
Backspace
The Backspace command backs over the character to the left of the insertion point. If the selection is extended, the text in the selection is deleted instead.
Beginning of Line
The Beginning of Line command moves the insertion point to the beginning of the current line.
Beginning of Selection
The Beginning of Selection command moves the insertion point to the beginning of the current selection if it is extended. If the selection is already an insertion point, then nothing happens.
Blank Line Down
The Blank Line Down command moves the insertion point to the beginning of the next blank line.
Blank Line Up
The Blank Line Up command moves the insertion point to the beginning of the previous blank line.
Block Down
The Block Down command moves the insertion point to the next } brace. This corresponds to the end of the current code block in languages like C/C++ and Java.
Block Up
The Block Up command moves the insertion point to the previous { brace. This corresponds to the beginning of the current code block in languages like C/C++ and Java.
Source Insight 4 User Guide 157
Commands Overview
Bookmark
The Bookmark command activates the Bookmark panel. Bookmarks are useful for storing locations of interest in your files.
See “Bookmarks” on page 100.
Bookmark Window
The Bookmark Window command shows and hides the Bookmark Window panel. The Bookmark Panel is a floating, dock-able window that shows the current list of bookmarks.
See “Bookmarks” on page 100.
Text Field
Type the partial name of a bookmark, or a line number here. Source Insight checks to see if the mark you typed matches an existing bookmark name. If it does, then pressing Enter will position you to that mark. If the bookmark you've just typed does not exist, then pressing Enter will create a new bookmark.
Marks list
Displays a list of all the bookmarks currently set. Each item in the list shows the bookmark's name, the file it's in, and the line number it's on, and the function that contains the bookmark, if any.
Right-click the mouse on the list to see the bookmark menu.
Add (Ctrl+N)
Click this button to create a new bookmark. The mark's name is taken from the Name text box. If the bookmark name is already in the list (i.e. it already exists), then its position will be redefined to the current cursor position.
Delete (Ctrl-X)
Click this button to delete the selected marks. To delete all bookmarks, right-click on the list and select
"Delete All Bookmarks".
Go To (press Enter)
Click this button to jump to the mark that is selected in the Marks list.
Load Bookmarks (Ctrl-O)
Click this to import bookmarks from another bookmark file.
Save Bookmarks (Ctrl-S)
Click this to save the selected bookmarks to a new bookmark file.
158 Source Insight 4 User Guide
Commands Overview
Bookmark Options... (Ctrl-Q)
Click this button to edit the bookmarking options. See: “Bookmark Options” on page 159
Bookmark Options
The Bookmark Options command sets the options for handling bookmarks.
Preserve bookmarks between sessions
If this box is checked, then bookmarks are restored when you exit and restart Source Insight. Otherwise, all the bookmarks disappear when you quit Source Insight.
Delete bookmarks when file closes
If this box is checked, then all the bookmarks in a file are deleted when you close that file.
Confirm when deleting bookmarks
If enabled, you will be prompted before deleting bookmarks in the Bookmarks panel.
Font & Color...
Click this to pick the font and foreground and background colors used in th Bookmarks panel.
Bottom of File
The Bottom of File command makes an insertion point at the last line in the current file.
Bottom of Window
The Bottom of Window command makes an insertion point at the last visible line in the active window.
Browse Files
The Browse Files command brings up the standard Windows system Open File dialog box so that you can browse the regular file system and open any file. This is unlike the regular Source Insight Open command, which brings up the Project Window, which lists only the files in the current project, regardless of directories.
Source Insight 4 User Guide 159
Commands Overview
Browse Project Symbols
Lists all the symbols in the current project. From this dialog box, you can
•
Find symbols based on parts of their names.
•
Look at symbol definitions.
•
Jump to symbol definitions.
•
Insert a call to a function into your source file.
•
Generate a cross-reference listing.
The Browse Project Symbols command automatically selects the first word in the selection before the dialog box comes up. The word is also loaded into the symbol name text box of the dialog box. The word is selected so that you can use the Insert buttons to replace the symbol name.
Tip:
Instead of using this dialog box, which is modal, you can use the Project Window's symbol list view. The Project
Window is mode-less; it can float or dock to the side of the application window. Furthermore, the Context Window shows the declaration of the item you select in the Project Window symbol list.
Browse Global Symbols Dialog box
Symbol List
This list displays a list of all symbols in the project. If a search pattern was given in the Symbol Name text box, then this is a list of all the symbols that satisfy the search pattern. Below the symbol list, the currently selected symbol's type and file of origin are displayed.
The types of symbols in the list are controlled by the settings accessed with the Symbol Types button.
As you type, Source Insight will display partial matches in the Symbol List. For example, if you type "Pch", then the first item in the list (in sorted order) that starts with "Pch" is selected in the list. The match is not case sensitive and leading underscores are ignored.
If you have symbol name fragment matching enabled (in Preferences: Typing) then the Symbol List will also show matches on name fragments, which you may type in any order. For example, if you type "cre win" (note the space between items), the Symbol List will show all symbols that have "Cre" and "Win" somewhere in the name.
To temporarily toggle name fragment matching on and off, prefix your entry with a space character.
Tip:
You can search for symbols using regular expressions, by prefixing your pattern with a question mark (?).
You can specify a regular expressions style search pattern to search for symbols by typing a question mark (?) and then the search pattern, and click the Jump button. All the symbols that match the pattern are placed in the Symbol List. For example, to find all symbols beginning with "Delete" and containing "Foo", you could type "?^Delete.*Foo".
Jump
Click this to jump to the definition of the currently selected symbol. If an item is selected in the Symbol List, then that is the current symbol. Otherwise, the symbol typed in the Symbol Name text box is used.
If the symbol name text box starts with a question mark (?), then Source Insight will replace the list with all the symbols that match the search pattern that follows the question mark; the dialog box will remain open.
Info
Click this button to run the Symbol Info command on the selected symbol.
References
Click this button to search for references to the selected symbol.
160 Source Insight 4 User Guide
Commands Overview
Insert w/Args
Click this button to replace the current selection with the name of the symbol, followed by the parameters as they appear in the symbol definition, if the symbol is a function.
Insert Name
Click this button to replace the current selection with the name of the symbol.
List
Click this button to create a cross-reference list of the symbols currently listed in the Symbol List. A new file is created and named Symlist.txt. Each line of the file contains a symbol name, and the file and line number where it's defined.
Symbol Types
This button is used to specify what types of symbols will be included in the symbol list and what types of symbols will be searched for when using a regular expression in the symbol name text box.
Making a Cross Reference Listing
You can have Source Insight create an output file that contains a list of symbol names.
To create a symbol cross reference list
1.
Run the Browse Project Symbols command.
2.
Click the List button. A new file named Symlist.txt will be created containing a list of all the symbols displayed in the Symbol List, along with the file and line number where the symbol is found.
To create a partial symbol cross reference list
1.
Run the Browse Project Symbols command.
2.
Click the Symbol Types button to specify the desired types of symbols to appear in the list.
3.
4.
5.
6.
Type a search expression in the Symbol Name text box. You must begin the pattern with a ? character to indicate that it is a pattern. For example, "?Word" searches for all symbols containing the substring "Word".
Click the Jump button to replace the list contents with all the symbols that match the pattern. When the search is done, all the matching symbols will appear in the Symbol List box.
Click the List button to create the symbol list.
Fix up the arguments in the function call to be appropriate.
To Search for a Function by Name
Let's say you want to call a function but can't remember its name. You know it has "Insert" and "Char" in its name. This example assumes you have enabled the symbol name fragment matching when you created the project.
1.
Select the place in your file where you want to insert the function call.
2.
3.
Run the Browse Project Symbols command.
Type "Insert Char" in the File Name text box and wait a moment. Note the space between the two words. Source Insight will use the name fragments you typed to filter the Symbol List to show all symbols with Insert and Char in the name. This technique only works if each word you type starts with an uppercase letter.
Browse Local File Symbols
The Browse Local File Symbols command lists all the symbols in the current file that are at the file scope.
From this dialog box, you can look at the symbol definition, jump to the symbol, or insert a copy of the symbol definition into the current selection.
Source Insight 4 User Guide 161
Commands Overview
The Browse Local File Symbols command automatically selects the first word in the selection before the dialog box comes up. The word is selected so that you can use the Insert buttons to replace the symbol name.
Symbol
The name of the symbol to be looked up. This text box is automatically loaded with the first word in the current selection when the dialog box comes up. You can type any symbol name into this text box.
Symbol List
Displays a list of all symbols in the project. If a search pattern was given in the Symbol Name text box, then this is a list of all the symbols that satisfy the search pattern. Below the symbol list, the currently selected symbol's type and file of origin are displayed.
The types of symbols shown in the list are controlled by the settings accessed with the Symbol Types button.
As you type, Source Insight will select the symbol in the Symbol List that starts with what you are typing. For example, if you type "Pch", then the first item in the list (in sorted order) that starts with "Pch" is selected in the list. The match is not case sensitive and leading underscores are ignored.
You can specify a regular expression style search pattern to search for symbols by typing a question mark (?) and then the search pattern, and click the Jump button. All the symbols that match the pattern are placed in the Symbol List. For example, to find all symbols beginning with "Delete" and containing "Foo", you could type "?^Delete.*Foo".
Jump
Click to jump to the definition of the currently selected symbol. If an item is selected in the Symbol List, then that is the selected symbol. Otherwise, the symbol typed in the Symbol Name text box is used.
If the symbol name text box starts with a question mark (?), then Source Insight will perform a search, and the dialog box will remain up.
Info
Click to run the Symbol Info command on the selected symbol.
References
Click to search for references to the selected symbol.
Insert w/Args
Click to replace the current selection with the name of the symbol followed by the parameters as they appear in the symbol definition.
Insert Name
Click to replace the current selection with the name of the symbol.
List
Click to create a cross-reference list of the symbols currently listed in the Symbol List. A new file is created and named SYMLIST.TXT. Each line of the file contains a symbol name and the file and line number where it's defined.
Symbol Types
This button is used to specify what types of symbols will be included in the symbol list and what types of symbols will be searched for when using a regular expression in the symbol name text box.
Browser Mode
The Browser Mode command toggles Source Insight's Browser-Mode. When Browser-Mode is on, your source code becomes read-only, and acts like a web browser. For example, single clicking on the name of a function in a function call will jump to the function's definition.
162 Source Insight 4 User Guide
Commands Overview
You can also toggle Browser-Mode by right-clicking in the small box at the bottom right of the Source Insight application window. Then select Enable/Disable Browse Mode from the pop-up menu
Table 4.1: Browser Mode Keyboard Commands
Key or Mouse click
Backspace
Space
Hold down CTRL
Click on a symbol name
Action
Navigate back to previous location.
Jump to definition of symbol under cursor.
Allows you to drag out a text selection instead of jumping to a definition.
Jump to definition of symbol.
Calculate
This replaces a selected mathematical expression with its result. To use this command, first select text that is some kind of mathematical expression. For example 112*14. Invoke the calculate command to solve the expression and insert the answer. In this case, 1568.
Cascade Windows
The Cascade Windows command rearranges the windows by cascading them down the screen.
Check for Updates
Checks with the Source Insight server to see if there is a newer version available.
Checkpoint
Saves the current file to disk and erases its change history and undo history. You can think of this as a "clean" save operation. It has the same effect as saving the file, closing it, and opening it again. After using Checkpoint, you will not be able to undo any prior changes.
Checkpoint All
Performs the Checkpoint command on all open files. This saves all open files to disk and erases their undo and change histories. After using Checkpoint All, you will not be able to undo any prior changes in your files.
Clear Highlights
Removes all word highlighting in all source windows. Highlighting is applied by using the Highlight Word command.
Clip Properties
(On Clip Window toolbar and right-click menu)
The Clip Properties command allows you to edit the name of the clip.
Source Insight 4 User Guide 163
Commands Overview
Clip Window
This shows or hides the Clip Window. The Clip Window displays a list of clipboard-like clips of text that you can insert.
A clip is a piece of text that you might want to insert easily into your code. For example, a standard function heading comment.
New Clip (Ctrl+N)
Creates a new clip in the Clip window.
Delete Clip (Ctrl+X)
Deletes the selected clip from the Clip Window
Edit Clip (Ctrl+E)
Allows you to edit the clip in a source window. When you close the source window the clip contents will be saved.
Cut To Clip (Ctrl+Shift+X)
Deletes the current selection from the current source window and puts it into a new clip.
Copy To Clip (Ctrl+Shift+Del)
Copies the current selection in the current source window and puts it into a new clip.
Paste From Clip
Pastes the selected clip contents into the current file.
Clip Window Options
Controls the settings of the Clip Window.
Using Clips
To create a clip:
1.
Select the text you want to make into a clip.
2.
3.
Use the Edit > Copy To Clip command. The Clip Window will appear.
Type the name of the new clip and press Enter. The new clip will appear in the Clip Window.
To paste a clip:
1.
Select where you want the clip inserted in your file.
2.
3.
Use the Edit > Paste From Clip command. The Clip Window will appear. If the Clip Window is already visible, just double click on the desired clip and it will be inserted.
Type the name of the clip, or just double click on it in the Clip Window
164 Source Insight 4 User Guide
Commands Overview
You can set Clip Window options using the Clip Window Properties command, or clicking the properties but-
ton in the Clip Window toolbar. See “Clip Window Options” on page 165.
Clip Window Options
This command brings up the Clip Window Options dialog box and allows you to set options for the Clip Window.
Preserve clips between sessions
If enabled, then clips are automatically saved to the Clips directory (in the Source Insight program directory) and will be reloaded the next time you run Source Insight. If not enabled, then clips are thrown away when
Source Insight exits.
Prompt for new clip name when text is dropped
If enabled, then Source Insight prompts you for the name of a clip whenever you drop text on the Clip Window. If not enabled, then Source Insight will generate a simple name for the clip automatically.
Delete clip after clip is dragged out
If enabled, then when you drag a clip out of the Clip Window, the clip will be deleted from the Clip Window. If not enabled, then the clip will be retained.
Always paste at the start of the line
If enabled, then the clip will be pasted at the beginning of the current line, instead of exactly where the cursor is. This does not apply when you drag a clip out of the window to a particular spot.
Process text variables when pasting from clips
If enabled, then text variables in the clip contents will be expanded and replaced when you paste the clip into your source file. Text variables behave the same as when inserting a code snippet.
Font, Text Color, Back Color
Lets you pick the display options for the Clip Window.
Close
The Close command closes the current file. If the file has been edited, but not saved, then Source Insight will ask you if you want to save the changes before closing the file by using a dialog box with the following buttons.
Source Insight 4 User Guide 165
Commands Overview
Yes
Click to save and close the file.
No
Click to close the file without saving it. Changes you've made will not be saved.
Cancel
Click to cancel the Close command. The file will remain open, and it will not be saved.
Close All
The Close All command performs a Close command on each open file. For any files that you have changed but not saved, Source Insight will ask if you want to save them.
If you have any captured custom command windows open and the custom command is still running, those windows are not closed.
Close Project
The Close Project command closes the current project. When the project is closed, all open files are also closed. Source Insight does this by performing the Close command on each open file. The workspace and configuration files for the project are also saved.
Close Window
The Close Window command closes the current window. Since a file can appear in more than one window, closing a window does not necessarily mean you will close the file buffer too. If you close the only window showing a file, then the file is closed also.
Color Options
Activates the Preferences: Colors & Fonts dialog box, which allows you to specify the colors of user interface items, and the font and color options of the panel windows.
166 Source Insight 4 User Guide
The color items in this dialog can also be grouped into Visual Themes.
Commands Overview
Color Item list
Lists the user interface items that can be colorized. The list contains the following items:
Display Item
Default Text
Window Background
Selection Bar
Printed Default Text
Printed Window Background
Change Marks
Table 4.2: Color Items
Description
Plain text that has no other style applied. If a file type has no language parser, this is the color the text will appear in. If there is a language parser, but an identifier is unknown, this is the color the identifier will appear in.
The color of the source window background.
The color of the left margin area.
The printed color of plain text.
The printed background color.
The color of the change marks that appear in the left margin alongside lines that have been edited, but not saved.
Source Insight 4 User Guide 167
Commands Overview
Display Item
Saved Change Marks
Current Line Indicator
End of File
Application Background
Frame and Panel Text
Table 4.2: Color Items
Frame and Panel Background
Description
The color of the change marks that appear in the left margin alongside lines that have been edited, after the changes have been saved to disk.
The color used to highlight the current line containing the selection.
The color is used as the background color of the whole line. This is only used if the option to show the current line indicator is enabled in
Options > Preferences: Windows
.
The color of the area that appears below the end of files.
The color of the main application frame window behind the source file windows.
The text color used in the main application window frame, the window tabs, and the titles of panel windows. Panel window are floating and docked windows.
The background color of the main application window frame, the window tabs, and the panel windows.
Pick Color...
Click this button to select a new color for the item in the list.
Styles...
Opens the Style Properties dialog to edit the formatting style settings. The styles are applied to text based on parsing. The colors used in styles should work together with the colors you pick for the items in the list. For example, the Window Background color should not conflict with the text or background colors you choose for styles.
Themes...
Opens the Visual Themes manager.
Use Defaults...
Resets the color options to the initial defaults.
Set Panel Fonts and Colors...
Many panels show lists of text, and each panel has optional settings for the font and colors used in those lists.
When clicked, this sets the fonts and colors in all panels to a single setting. Even though each panel has its own font and color settings, this button sets them all to the same thing. This button is a simple way to change all the panel fonts and colors at once, instead of selecting the options for each panel individually. However, this wipes out any differences in their settings.
Note:
Applying a Visual Theme will also change all the panel colors en masse to whatever is stored in the theme.
168 Source Insight 4 User Guide
Commands Overview
Command Shell
The Command Shell command is a Custom Command that launches a shell command box from Source
Insight.
Compare Files
The Compare Files command compares two files and shows them in the File Compare window side by side.
See “File Compare” on page 199.
To compare a file:
1.
Select Tools > Compare Files
2.
In File 1, enter the path of the file. The current file name is preloaded into this field.
3.
4.
In File 2, enter the path of the second file. You can enter just a directory path and the file name will be implied. To load any other open file, click the down-arrow to show recent files and other open files.
Press Enter or click Compare. The File Compare window will open and show the files side-by-side with differences highlighted.
To compare a file with a previous version
1.
Open a source file.
2.
3.
Select Tools > Compare with Backup File.
The Compare with Backup Version dialog will appear. Select the old version you want to compare
with, and click OK. See “Compare with Backup File” on page 170.
Source Insight 4 User Guide 169
Commands Overview
To compare a files from the command line
1.
Invoke Source Insight from the command line like this: sourceinsight4.exe -d <file1> <file2>
2.
The File Compare window will open and show the two given files.
Compare with Backup File
This command compares the current file with a saved backup version of the same file. See “File Compare” on page 199.
Select the backup file that contains a previously saved version, then click OK to show the differences. The number of backup files available depends on how many times you saved a file, and how long backup files are
stored. The backup settings are controlled in the File Options dialog. See “File Options” on page 202.
Every time you save a file for the first time in a session, normally Source Insight saves a copy of the original file in as a backup. A unique number is added to the file name so multiple versions of the file can exist in the backup directory.
Each project has its own backup directory. You can set it in the Project Settings dialog. See “Project Settings” on page 277.
Complete Snippet
Completes and expands a code snippet by name. This is similar to the auto-completion list that appears when you type a symbol name, except only snippet names appear in the list.
170 Source Insight 4 User Guide
Commands Overview
By default, snippet names also appear in the regular auto-completion list. However you can disable that
option and use Complete Snippet to explicitly show snippets. See “Code Snippets” on page 96.
Figure 4.1 The Compete Snippet window
Complete Symbol
The Complete Symbol command invokes the auto-completion function. The popup auto-completion window will appear.
Figure 4.2 The Auto-Completion window appearing after typing
By default, code snippet names also appear in the regular auto-completion list. However you can disable
that option and use the Complete Snippet command (Ctrl+E) to explicitly show snippets. See “Code Snippets” on page 96.
The Complete Symbol command replaces the whole word you are typing with the complete name of the symbol.
For example, let's say that you have a function called InitWindowState. As you type in the letters: "InitWi", the auto completion window narrows what you've typed down to a unique function (InitWindowState). The
Complete Symbol command will replace what you've just typed with the whole name "InitWindowState".
The auto completion settings affect how the completion function works. You have the option of inserting function parameters when a function name is inserted. You can change the auto-completion options using
the Preferences command. See: “Typing Options” on page 354
Conditional Parsing List
This is used to define conditional parsing identifiers for a single project, or for all projects. Condition values are used to interpret
#if
and
#ifdef
statements. They are typically defined as constants using
#define
statements, or in compiler command line options, or in your IDE settings. See “Conditional Parsing and Preprocessor Support” on page 58.
Source Insight maintains two sets of conditions: a global list applies to all projects, and the project-specific list applies only to the current project. The project-specific condition values are stored with each project. To
Source Insight 4 User Guide 171
Commands Overview
access this dialog, select Options > Preferences: Languages, then click the corresponding "Conditions" button.
Add / Delete
Use this to add a new condition identifier and its value, or to delete entries in the list.
Edit...
Use this to edit the value of the selected identifier in the list.
Import / Export...
You can import or export the current condition list.
Scan Files...
This will scan your project’s source files to determine what conditional identifiers are used, and their defined values, if any. The results are put into the list. Note that the value of "Ignore Condition" means that Source
Insight assumes the value is unknown, and will ignore preprocessor statements that use that condition identifier.
Context Window
This command toggles the Context Window visibility on and off.
See “Context window” on page 88.
172 Source Insight 4 User Guide
Commands Overview
Context Window Options
This command allows you to specify properties for the Context Window. The Context Window tracks what you select and type in text windows, as well as what files you select in the Project Window, Relation Window,
and Clip Window. See “Context window” on page 88.
Show all matches on the current symbol
Select this to have the Context Window show a complete list of all symbol matches in its list. If you have multiple definitions with the same name, then they will all appear in the list.
Show only the first symbol match
Select this to show only first matching symbol's definition. If you often have symbols that are defined in more than one place but are essentially the same thing, then you might want to turn on this radio button.
Show base types for data structure variables
Select this to have Source Insight decode variable declarations and try to locate base structure-type definitions (i.e. structs, unions, classes, etc.).
For example: struct S { int x; }; struct S *psvar; psvar->...
If you select inside of psvar, then Source Insight will look at the declaration of psvar, see that it is a pointer to struct S, and then show you the declaration of struct S.
Clear this option to simply show the declaration of the each variable, without walking up the declaration hierarchy.
Show line numbers
Makes line numbers visible in the Context Window.
Use 'Mono Font View'
Displays the Context Window in the Mono Font View style, which uses limited formatting. See “Mono Font
View” on page 256 .
Source Insight 4 User Guide 173
Commands Overview
Scaling (percentage)
Sets the percentage of text size scaling in the Context Window.
Tracking Options…
Click this button to view the Symbol Tracking Options dialog box, which displays options that guide what the
Context Window will pay attention to.
Font…
Specifies the font used to display symbol lists and source code in the Context Window. If the Context Window is currently showing a list, then this specifies the list font. If the Context Window is currently showing a source file, then this specifies the source code font.
Text Color…
Specifies the text color of list items in the Context Window. The colors of source code are determined by the
Syntax Formatting options in the Preferences dialog box.
Back Color…
Specifies the background color of list items in the Context Window. The colors of source code are determined by the Syntax Formatting options in the Preferences dialog box.
Symbol Tracking Options
This dialog box displays options that control what type of symbols or selections the Context Window will react to.
Automatic Symbol Tracking
As you move your cursor around in a source file, the Context Window "tracks" the symbol under the cursor, or around the cursor. This group of options tells the Context Window what to track.
Off
Select this to disable automatic symbol tracking.
Track selected symbol (i.e. under cursor)
Select this to have the Context Window look up the definition of the symbol currently under the typing cursor.
174 Source Insight 4 User Guide
Commands Overview
Track the enclosing function or class
Select this to have the Context Window show the definition of the function or class that contains the typing cursor. This is useful to have a function definition and formal parameters visible in the Context Window while you edit the function.
Activate Tracking Group
This group controls when the automatic tracking is activated.
Inside of comments
Select this to have the Context Window look up symbols when the cursor is inside of comments.
Inside of string constants
Select this to have the Context Window look up symbols when the cursor is inside of quoted string constants.
Inside all file types
Select this to have the Context Window look up symbols when the cursor is inside any type of file, not just source code files.
Copy
The Copy command copies the contents of the current selection to the clipboard. Once in the clipboard, it can be pasted to other locations using the Paste command. This command is only allowed if the current selection is extended.
Copy File Path
Copies the full file path of the current file to the clipboard.
Copy Line
The Copy Line command extends the current selection to include whole lines and copies that selection to the clipboard. Each use of Copy Line extends the selection down one more line.
Copy Line Right
The Copy Line Right command copies the text from the insertion point to the end of the current line into the clipboard.
Copy List
This command appears on the right-click menu when you click on a list. It copies the contents of the list to the Clipboard. This lets you make a copy of any list, or paste any list into a file and print it.
Source Insight 4 User Guide 175
Commands Overview
Copy Project
This copies the current project to a new project. The new project is created by cloning the current project data files. Your source files will not be copied. The new project will point to the same source files. If you delete the original project after copying it, you have effectively renamed the project.
New project name
Enter the name of the new project. Do not enter a path name here. This is the name that will appear in the
Open Project dialog.
Where do you want to store the project data files?
Specify the full path to the data file folder here. This is where Source Insight will store all its project data, independently of your source files. By default, Source Insight creates a sub-folder with the same name as the
project. For more information on the project data location, See “New Project” on page 257.
Also copy the project’s source backup files
If selected, then any files in the current project’s backup folder are also copied to the new project’s backup folder.
Copy Symbol
This command appears on the Symbol Window right-click menu.
The Copy Symbol command copies the selected symbol, along with its definition body, to the Clipboard. For example, if you click on a function name and select Copy Symbol, then the whole function is copies to the
Clipboard.
Copy To Clip
The Copy To Clip command copies the contents of the current selection to a clip buffer that you name. The
Clip Window is activated when you use this command so that you can specify the destination clip name.
After either selecting a clip item in the list, or typing a clip name, press the Enter key to complete the copy operation.
176 Source Insight 4 User Guide
Commands Overview
Create Key List
The Create Key List command generates a new file named Keylist.txt containing a list of all commands and the keystrokes assigned to each command. The Keylist.txt file is just a regular, unsaved file. You can edit the file normally. This is useful for creating your own keyboard quick reference guide.
Create Bookmarks from Relation Items
Creates new bookmarks from all the items in the Relation window.
Create Command List
This generates a new file named "Command List", which contains a list of all commands and their descriptions. The output file is just a regular, unsaved file. You can edit the file normally. This is useful for creating your own command quick reference guide.
Cursor Down
The Cursor Down command moves the insertion point down by one line.
Cursor Left
The Cursor Left command moves the insertion point left by one character.
Cursor Right
The Cursor Right command moves the insertion point right by one character.
Cursor Up
The Cursor Up command moves the insertion point up by one line.
Custom Commands
Custom commands are similar to command shell batch files. They allow Source Insight to spawn any command line driven tool, and to capture its output. Custom commands can also execute Windows programs.
Customs commands can execute, and then return to Source Insight. The output of shell custom commands can be captured into a file for editing, or can be pasted into the current selection. Custom commands are stored as part of the current configuration.
Custom commands can be used to spawn compilers, source control programs, and file filters, such as "sort".
Tip:
A shortcut for editing a custom command is to hold down the Ctrl key while selecting the command. The Custom Commands dialog box will appear for that command.
Source Insight 4 User Guide 177
Commands Overview
Custom Command Dialog box
Command
Displays the name of the currently selected command. This pull-down list contains a list of all the custom commands defined.
Run
This is the command line to be executed when the custom command is invoked. The Run text box can con-
tain special meta-characters. See “The 'Run' Field Format” on page 180.
Dir
The working directory used when executing the script specified in the Run text box. Source Insight sets the current working directory to this location before running the command. If left blank, then Source Insight sets the current working directory to the project source directory. This field can also contain special meta-charac-
ters, just as with the Run field. See “The 'Run' Field Format” on page 180.
Output Group
This group of options control what happens to the output of the command.
Iconic Window
If enabled, the spawned program will be put into a minimized window. If not enabled, then the program will launch normally.
Capture Output
If enabled, the standard output of the command will be captured and will appear in a new command output window when the command completes. The command output window's title will be the name of the custom command. If not enabled, the standard output will not be captured.
Paste Output
If enabled, the standard output of the command is pasted to the current selection.
178 Source Insight 4 User Guide
Commands Overview
Control Group
This group of options specifies what Source Insight does before and after the command runs.
Save Files First
If enabled, Source Insight will perform a Save All command prior to executing the command. The Save All command will prompt you for each file that has been edited to see if you want to save the file.
If not enabled, the command will be executed without saving any changed files. The unsaved changes will be retained when the command completes and control returns to Source Insight. If the command should cause
a crash, Source Insight will be able to perform a recovery and all changes will be intact. See “Recovering From
Crashes” on page 125.
Pause When Done
If enabled, Source Insight will display this message in a command shell window when the command completes:
Press any key to return to Source Insight...
If not enabled, the shell window will terminate after the command completes.
Beep When Done
If enabled, Source Insight will beep when the command terminates.
Wait Until Done
If enabled, then Source Insight will suspend itself until the command finishes.
If not enabled, then Source Insight will run the command and continue. You will be able to switch back to the
Source Insight window and continue working while the command runs in the background.
Exit Source Insight
Source Insight will exit after launching the program.
Source Links in Output
These options specify how the output is to be treated after the command finishes. You may tell Source Insight to parse through the captured output to find specific warning or error messages.
Parse Source Links
The command output will be searched for source link patterns. The patterns typically will match warning and error messages. If a pattern match is found, Source Insight inserts a source link at that line. The source link is used to link the warning or error message to its target source line. If Parse Source Links is enabled, you must have a valid search expression in the Pattern text box.
Pattern contains
File, then Line and Line, then File. This indicates the order of the groups in the pattern expression.
Select File, then Line if the first group in the pattern expression is the file name and the second group is the line number. With this setting, the second group, (i.e. the line number), is optional.
Select Line, then File if the first group in the pattern expression is the line number and the second group is the file name.
Pattern
Contains the regular expression used to search the command output for file names and line numbers. This is ignored if the Parse Source Links option is disabled. If the option is enabled, then this text box must contain a
valid regular expression that contains "groups" for the file name and the line number. See “Regular Expressions” on page 107.
Source Insight 4 User Guide 179
Commands Overview
Regular Expression Syntax
Selects the type of regular expression syntax to use with the pattern.
Define
Click this button to define the command named in the Name text box. If the command already exists, it is redefined.
Remove
Click this button to delete the command.
Run
Click this button to define and execute the command.
Cancel
Click this button to cancel the dialog box. Any definitions made in the dialog box will be retained.
Menu…
Click this button to define the current command and jump to the Menu Assignments dialog.
Keys…
Click this button to define the current command and jump to the Key Assignments dialog.
The 'Run' Field Format
The Run text box contains the command line to execute when the custom command is invoked. The Run text box can contain more than one command. Each command should be separated by a semi-colon. For example, cat make.log;echotime
This string causes "cat make.log" to execute, followed by "echotime".
Running the Command Shell
If you want to run a shell command, such as "type", or "dir", or you want to run a batch file, then you have to run cmd.exe first. For example, cmd /c mybat.bat or cmd /c type foo.txt
If the Run string contains more than one command, separated by semi-colons, you don't need to run cmd.exe because Source Insight creates a batch file from the run string commands and runs cmd.exe automatically in that case. For example, cat readme.txt;dir
This works fine because it is already running in a batch file inside a shell.
Command Line Substitutions
Both the Run text box, and the Dir text box can contain meta-characters that cause the following items to be substituted in the string.
Character
%f
%r
Table 4.3: Custom Command Meta-Characters
Expands to
full path name of the current file
* path name of current file relative to the project source directory *
Example
c:\myproj\file.c
file.c
180 Source Insight 4 User Guide
Commands Overview
Character
%n
%d
%h
%b
%e
%c
%p
%j
%J
%v
%o
%l
%w
%s
%a
%t
%1 - %9
Table 4.3: Custom Command Meta-Characters
Expands to Example
leaf name of the current file * file.c
directory path of the current file c:\myproj
\myproj directory path of current file without the drive letter leaf name of current file w/o extension * file extension of the current file drive letter of the current file the current project name the source directory of the current project the data directory of the current project c c: c:\myproj\myproj c:\myproj
C:\Documents and Settings\Jim Smith\Documents\Source Insight
4.0\Projects\Base c: the drive letter of the current project's source directory leaf name of the project without path the current line number first word in the selection, or the word under the cursor myproj any number any word name of a temp file where the current selection is saved while the custom command runs.
the current date d:\tmp\vt0004.
05-12-02 the current time 08:23 user is prompted for arguments any strings
You can also postfix any of the above characters marked with * with either of the following modifier characters.
Character
%o
%m
Expands to
for all open files for all modified files
Example
%f%o
%f%m
Path Variables
You can also use Path Variables in Run and Dir text fields. See “Predefined Path Variables” on page 147.
ShellExecute Commands
Tip:
ShellExecute lets you invoke Windows Shell commands.
Custom Commands support the "ShellExecute" function, which lets you tell the Windows shell to perform an operation on a specified file. The nice thing about ShellExecute is that you don't need to know what specific application is registered to handle a particular type of file. For technical background information, see the
"ShellExecute" function in the Windows Shell API documentation.
Source Insight 4 User Guide 181
Commands Overview
To use this feature, the Run string in the custom command needs to start with "ShellExecute". The format should be:
ShellExecute <verb> <filespec> <optional parameters>
For example, to browse a website:
ShellExecute open http://www.somedomain.com
The verb is a single word, which can be one of the following:
• edit
Opens an editor for the file.
• explore
The function explores the folder specified.
• open
The function opens the file specified. The file can be an executable file or a document file. It can also be a folder.
• print
The function prints the document file specified. If filespec is not a document file, the function will fail.
• properties
Displays the file or folder's properties.
• find
Launches the Find Files application found on the Start menu.
•
""
(empty string) to skip this parameter to ShellExecute.
The filespec parameter can be any valid path. Use double quotes around complex path names with embedded spaces. You can also use a meta-character, such as %f (for the current file). It can also be the name of an executable file.
The optional parameters list is anything to the right of the filespec. It specifies the parameters to be passed to the application that ultimately runs. The format is determined by the verb that is to be invoked, and the application that runs. You can use custom command meta-characters here as well.
The working directory text box of the custom command is applied before the ShellExecute is invoked. However, output cannot be captured or parsed when using ShellExecute.
ShellExecute Examples
Here are some useful examples showing how to use ShellExecute.
Action Custom Command Run String
To browse to a web site:
To explore your Windows documents file folder:
ShellExecute open http://www.somewebsite.com
ShellExecute explore "C:\Documents and
Settings"
To launch Internet Explorer: ShellExecute "" iexplore
To preview a file in Internet
Explorer:
ShellExecute "" iexplore %f
To search for files in the current project folder:
ShellExecute find %j
Running Custom Commands in the Background
When Source Insight spawns a Custom Command shell program, it actually runs a program called
Sihook4.exe. Sihook4.exe in turn spawns the command and performs the output capturing. You can run a custom command and click back on the Source Insight window to continue editing with Source Insight while the custom command runs in the background.
Creating a Compile and Build command
You can launch a compiler from Source Insight, using a custom command, and have the output captured and parsed for error messages. Then you can use Go To First Link and Go To Next Link to view each error in your source files.
182 Source Insight 4 User Guide
Commands Overview
To create a simple Compile command
To create a simple Compile command using the Microsoft ® C++ compiler:
1.
Select Tools > Custom Command.
2.
3.
4.
Type "Compile File" in the Name text box.
In the Run text box, type " cl %f
". This invokes the compiler on the current file. You could also invoke a "make" program or a batch file here instead. If you use a batch file, you must run the command processor first. For example, " cmd /c mybatch.bat
".
Turn on the Parse Source Links option. The default parse pattern is setup to parse the compiler error messages from the compiler output.
5.
6.
Turn on the Save Files First option so that your file is saved before running the compiler.
Click the Define button to save the new command. Alternatively, you can click the Menu or Keys buttons to define the new command and run the Menu Assignments or Keyboard Assignments commands, which will allow you to put the command on a menu or assign a key to it.
The Parse Source Links option causes Source Insight to search the compiler output and setup source links for each error message. In this case, the "link sources" are each error message in the compiler output file. The
"link target" for each link is the file and line number given in each error message.
To Build a Project with Microsoft ® Developer Studio
1.
Select Tools > Custom Command.
2.
Select the Build Project command in the Command drop-down list. The Build Project custom command is predefined when you install Source Insight.
3.
In the Run text box, type the following:
C:\MsDevPath\msdev project.dsp /make /rebuild
Where "MsDevPath" is the path to your msdev.exe program, and "project.dsp" is the name of the Developer
Studio project.
This line invokes msdev.exe to rebuild the given project.
4.
5.
Turn on the Parse Source Links option. The default parse pattern is setup to parse the compiler error messages from the compiler output.
Turn on the Save Files First option so that your file is saved before building the project.
Viewing Compiler Errors
To view source lines with errors:
1.
2.
Run the Compile File custom command, which is defined as described above.
Assuming there are errors, when the compiler finishes the error messages will be in the "Compile
File" window. Source Insight will automatically setup the source links and run the Go To First Link command. The first error message and the erroneous source line will be selected and made visible.
3.
4.
Use the Go To Next Link command (Shift+F9). The next error message in the "Compile File" window is selected, and the target of that link is shown, as was the first error.
Continue to use the Go To Next Link command until all the links (error messages) have been visited.
If there are no more links, then Source Insight beeps and the message, "No links." will appear in the status bar.
Cut
The Cut command copies the contents of the current selection to the clipboard, and deletes the selection.
Note that although the Cut command deleted the current selection, you still have that text saved in the clipboard. You could reverse the deletion by following the Cut command with a Paste command.
Source Insight 4 User Guide 183
Commands Overview
Cut Line
The Cut Line command copies the current line to the clipboard and deletes the line. The cursor can be anywhere on the line when you use this command.
Cut Line Left
The Cut Line Left command cuts all the characters to the left of the insertion point on the current line.
Cut Line Right
The Cut Line Right command cuts all the characters to the right of the insertion point on the current line.
Cut Selection or Paste
The Cut Selection or Paste command performs a Cut command if the current selection is extended, or it performs a Paste command if the selection is an insertion point.
If you assign this to a key or mouse button, this command makes moving text around easy because you only have to press a single key or mouse button.
To use this command:
1.
Select the text you want to move by clicking and dragging with the left mouse button.
2.
Click the mouse button or press the key to cut the text.
3.
4.
Point and click the mouse button to select the new location.
Click the mouse button or key to paste the text.
Cut Symbol
(On the Symbol Window right-click menu)
The Cut Symbol command cuts the selected symbol.
Cut To Clip
The Cut To Clip command copies the contents of the current selection to a clip buffer that you name, and then deletes the text. The Clip Window is activated when you use this command so that you can specify the destination clip name.
Cut Word
The Cut Word command cuts the word to the right, starting at the insertion point.
Cut Word Left
The Cut Word Left command cuts the word to the left, starting at the insertion point.
Deactivate License
Deactivates and de-authorizes your installation of Source Insight. This frees your license up to be installed and used on a different machine.
184 Source Insight 4 User Guide
Commands Overview
Delete
The Delete command deletes any file on disk, including the currently open file.
Delete All Clips
This command deletes all user clips from the Clip Window. The Clipboard is a special clip that cannot be deleted.
Delete Character
The Delete Character command deletes the character at the insertion point. If the current selection is extended, it deletes the whole selection.
Delete Clip
(On Clip Window tool bar and right-click menu)
The Delete Clip command deletes a clip file from the Clip Window and from disk.
Delete File
The Delete File command deletes a file from the disk and removes it from the current project if it was part of the project. If you specify the current file, then that file is closed and deleted.
Delete Line
The Delete Line command deletes the current line. Unlike the Cut Line command, the clipboard is not effected.
Directory Compare
This opens the Directory Compare window, which is used to compare the files in two directories. The Directory Compare windows shows two lists of files side by side - the left and right directory contents.
Source Insight 4 User Guide 185
Commands Overview
The File Compare window can be used to compare two versions of a file. See “File Compare” on page 199.
Toolbar
1.
Compare Selected File - opens the File Compare window to show differences between the selected files.
2.
Refresh / Rescan Directory and compare again.
3.
4.
5.
6.
Go to Previous / Next file that differs.
Copy File From Left-to-Right and Right-to-Left directories.
Delete the Left / Right file.
Open the Directory Compare Options. See “Directory Compare Options” on page 187.
To compare directories:
1.
Type the path of the left directory above the left list, or click the ... button to browse.
2.
Type the path of the right directory above the right list, or click the ... button to browse.
3.
4.
Press Enter or click the Go button.
Source Insight will scan the files in both directories and show the results below in a side by side listing.
The Status column in the center of the list indicates if the left-hand file is the same, different, newer, or older than the right-hand file.
You can control how the files are compared by clicking the properties button. See “Directory Compare
Options” on page 187.
To compare a file within a directory:
1.
Using the Directory Compare window, navigate to the directories that contain the file versions.
2.
Double-click on a file in the directory listing. The File Compare window will open to show the two
versions of the file side by side. See “File Compare” on page 199.
186 Source Insight 4 User Guide
Directory Compare Options
This sets the way that the Directory Compare window looks and how it compares files.
Commands Overview
Show Columns
Check mark the columns you want to see in the file listing.
Comparison Method
These options determine how each file in the directories is compared.
Only compare file modification dates
Only the modification dates are compared. The contents of the files, and the file size as reported by the operation system are not compared.
Only compare file sizes and modification dates
Both the modification dates and the file sizes are compared. The contents of the files are not compared.
Compare file contents
The file system date stamps are ignored, and the file contents are scanned for differences. Use this when you don't trust the time stamps in the file system. However, this method is the slowest.
When Comparing File Contents
These options control how the contents of the files are compared.
Ignore differences in white space
Only non-white space characters in the files are compared. White spaces are ignored.
Source Insight 4 User Guide 187
Commands Overview
Ignore differences in end-of-line characters
Differences in the end-of-line characters are ignored. This is useful if you are comparing files between Unix,
Windows, or Mac environments where the end-of-line characters are different.
Other Options
Show only known file types
Check this box to limit the files to the file types defined using the File Type Options command. The file types are usually all some kind of text file, so this open prevents Source Insight from attempting to compare any binary file.
Confirm before copying or deleting files
Check this box to have Source Insight prompt you with a confirmation before you copy or delete a file in the
Directory Compare window.
Font & Color...
Click this to customize the font and background color of the window.
188 Source Insight 4 User Guide
Commands Overview
Display Options
This command brings up the Display page of the Preferences dialog box. These options are part of the current configuration.
Display Elements
The Display Elements group is used to turn on and off elements of the user interface.
Main Tool Bar
Displays the main toolbar at the top of the Source Insight application window.
Search Bar
Displays the File Search bar that appears below the main toolbar.
Status Bar
Displays the status bar at the bottom of the Source Insight application window.
Popup Toolbar
This enables the popup toolbar that appears when you whole-word select a symbol name. The popup toolbar fades into view and lets you quickly jump to a symbol’s definition, a function’s caller, or find references to a symbol. The popup toolbar is first shown translucent, but it gets more opaque as you move the mouse closer to it.
Source Insight 4 User Guide 189
Commands Overview
Overviews (based on file type)
This globally enables the use of Overview scrollers in all source windows. See “The Overview Scroller” on page 25.
When enabled, each file type determines if the Overview scroller is used in that type of file. See “File Type
Options” on page 207.
To disable the use of Overview scrollers in all source windows, disable this option.
Tab Tray
Turns on and off the tab tray at the bottom of the Source Insight application window. Floating windows that are minimized appear in the Tab Tray.
Reset
Resets the positions of all the auxiliary windows so that they are moved onto the main monitor, and are not transparent.
Options Group
The items in the Options Group control general options for different display elements in the program.
Page Number in status bar
If enabled, then the current page number that contains the current selection is also displayed in the status bar. The page number is calculated from the size the printer font selected in the File Type Options command, plus syntax formatting options, and the settings made in Page Setup.
Show exact case of file names
If enabled, then Source Insight displays file names using the exact upper and lower case of the name as it appears in the file system. If not enabled, then Source Insight will format the file name to look a little nicer by converting it to lower case and capitalizing the first letter. Source Insight does not alter the file name if it already contains a mixture of upper and lower case letters.
This option only affects how Source Insight displays file names. The file names are stored internally and in the database exactly as the file system reports them.
Show read-only file names with ! mark
If enabled, then Source Insight displays read-only file names in window titles with an exclamation point (!) at the beginning of the file name. This only affects how the file name is displayed in window titles.
Show current project name in application background
If enabled, then the name of the current project is drawn in the multiple document background area of the
Source Insight application window.
Tile source and destination windows for Source Link commands
If enabled, then Source Insight tiles two windows to show the source and destination source links whenever you use one of the source link commands, such as Go To First Link, or Go To Next Link. The source link commands are also used when you run a custom command that parses output for source links (such as a "compile" command). If not enabled, then Source Insight will not alter the window arrangement when you used the source link commands, but it will active the window containing the target of the source link.
Source Insight does not perform tiling if the current window is maximized.
Enable Animations
Enables simple animations to show when input focus changes to a floating tool window, and when floating windows are "rolled up" or "rolled down". You might want to turn off animations if your video card performance is slow.
190 Source Insight 4 User Guide
Commands Overview
Trim long path names with ellipses
Long file path names are shortened and ellipses are inserted. This affects areas such as the title bar of windows.
Panels Group
These options affect floating and docked panel windows. See “Panel Windows” on page 29.
Toolbar position in panels (Top or Bottom)
Each panel has a toolbar. You can select whether it is displayed at the top or bottom of the panel.
Enable transparent panels
If enabled, then floating panel windows will contain a transparency button in the title bar area of the window so that you can adjust the panel’s transparency.
Other Buttons
Styles…
Edits style properties. See “Style Properties” on page 333.
Spacing...
Click this button to change character spacing options. See “Character Spacing Options” on page 192.
Window Tabs...
Click this button to edit the window tab options.
Scroll Bars...
Click this button to edit the vertical scroll bar options. See “Scroll Bar Options” on page 312.
Source Insight 4 User Guide 191
Commands Overview
Character Spacing Options
Character spacing options are used to control the horizontal and vertical spacing of characters. This dialog box lets you adjust how Source Insight computes the width of spaces, tabs, and common delimiters. The first two settings have no effect unless Line up white space is enabled in the File Type Options dialog box.
Horizontal Spacing Options
Horizontal spacing options affect the width of characters drawn when a proportionally spaced (variablepitch) font is used and the Line up white space option is enabled in the File Type Options dialog box. If enabled, Source Insight will attempt to use a fixed width for spaces and tabs so that spaces and tabs line up the same way they do with a fixed pitch font. Programs generally look better with this turned on if you are using a proportional font.
The Space-Width Character
The space width character controls how wide a single space is, and therefore the displayed width of tab characters (tabs are some number of spaces wide). Source Insight computes a space to be same width as this character in whatever font is used for displaying. For example, the character "1" specified in this dialog box means that a space character will have the same width as the character "1". (Do not confuse the character with its numeric value 1. Source Insight does not interpret the character's numeric value.)
Source Insight computes the width based on the space width character so that spaces will scale correctly, independent of the font and the font size used.
In a mono-spaced font, such as Courier New, or Consolas, all characters are the same width, including spaces. However in a proportional font, such as Calibri, a space character is typically narrow, and many characters may be wider than the space character in the font. This option gives you control over how wide a space character is displayed, and therefore how wide tabs are.
192 Source Insight 4 User Guide
Commands Overview
Working with Wide Fonts
You may want to change this setting if you are working with a font that has unusual character widths, or if you just want to expand or contract your white space and indentation amounts. A narrower character will shrink the white space, and a wider character will expand it. This width is independent of the tab width setting specified in the File Type Options dialog box because the tab width is specified as a number of fixedwidth character columns.
The common delimiter character controls the width of delimiters in a way similar to spaces. The delimiters affected are
- | \ / and
!
which are typically narrow characters in most fonts.
Layout tabstops using monospaced calculations
This option controls how tab widths are displayed. If enabled, then the width of a given tab will calculated assuming that you were using a monospaced font. This will generally make tabbed columns of text line up, even if you are using a variable pitched font for displaying your source code.
Layout spaces using monospaced calculations
This aligns space characters to appear how they would if a monospaced font is used. For example, 4 spaces in a row would appear the same width as a tab stop (if the tab width was 4 spaces). Source Insight looks at each line and tries to determine simply when to apply this rule to a space character. If it looks like you meant to line up columns manually using spaces, then it applies this rule. It only applies the rule for 2 or more consecutive spaces. Otherwise, it calculates a space width to be the natural width of a space in the given font. This option is on by default.
Using this option, space size is natural, unless it looks like you meant to line up columns by using tabs and spaces. This is not an exact science!
Source Insight should be doing a good job of showing you how text lines up in a simple display, even if you are using Syntax Formatting. You can also use the View > Mono Font View command to switch to a simple monospaced font view and see the text alignment.
Vertical Spacing Options
These options control vertical line spacing.
Smaller Line Heights
Check this box to compress the line heights in order to show more lines of text on the screen. This is accomplished by reducing the amount of "leading" added to the font by the operating system. Font leading is added to make vertical line spacing look pleasing in printed documents. However, it is not really necessary for editing source code.
Why All The Fuss About Spacing?
You may be wondering, "Why go to all this trouble? Can't you make a tab stop be ½ inch or whatever?" The answer is a little complicated. The problem is, unlike a word processor, Source Insight is trying to maintain a text file that other people may want to look at in a different editor or viewed in a fixed-pitch font.
A word processing program attempts to show text the way it would be printed on a physical printer. Source
Insight is trying to show you how the text would look if you were looking at it in another editor in a fixed pitch font.
In a word processing program, text dimensions are measured in physical units, like inches or centimeters. It makes sense to have a tab stop at say, ½ inch. When the text is printed, the word processor makes sure the tab stop looks ½ inch wide on the printer too.
In Source Insight, tab stops are measured in fixed-size character columns. Source Insight tries to line up tabbed columns the same way it does with a fixed-pitch font.
If Source Insight just did the simple thing of moving to the next tab position, based on the horizontal pixel position, then when you look at the code with a simple fixed-pitch font, there may a different number of tabs than it appears on the screen.
Source Insight 4 User Guide 193
Commands Overview
Here is an example. Let's say somebody wrote this in Notepad, using Courier New (a fixed-pitch font), with tabs between columns so that X and Y, and Q and R line up. Both the words "narrow" and "very-wide" fit within column 0 - one tab stop, as shown below.
3 Tab stop:
Line 1:
Line 2:
0
narrow wide
1
X
Y
2
Q
R
Now, in Source Insight, with rich formatting, "narrow" fits within a tab width, but "wide" doesn't. If Source
Insight just pushed Y over by one more tab stop, this is what you get:
Tab stop:
Line 1:
Line 2:
0
narrow
w i d e
1
X
2
Q
Y
3
R
Now Y is aligned with Q. The rest of the columns don't line up anymore. In fact, this is exactly what happens if you turn off Line up white space in File Type Options.
When Line up white space is enabled, Source Insight tries to help the situation by lining up tab positions like this:
Tab stop:
Line 1:
Line 2:
0 1
narrow X
w i d e
Y
2
Q
R
3
If your code looks like it does above, then you may want to specify a different space width character, such as
"M" or "W", which are wider letters in most fonts. This would have an effect like this, where all tab stops would be wider:
Tab stop:
Line 1:
Line 2:
0
narrow
w i d e
1
X
Y
2
Q
R
This also works the other way when the text looks a lot narrower than it would be in a fixed pitch font.
Drag Line Down
Moves selected text down by one line. This is useful for dragging a whole line or lines down below something else in a file.
Drag Line Down More
Moves selected text down by several lines. This works like the Drag Line Down command, only it moves the lines further.
Drag Line Up
Moves selected text up by one line. This is useful for dragging a whole line or lines up above something else in a file.
Drag Line Up More
Moves selected text up by several lines. This works like the Drag Line Up command, only it moves the lines further.
194 Source Insight 4 User Guide
Commands Overview
Duplicate
The Duplicate command creates a duplicate of whatever is selected.
Duplicate Symbol
(On the Symbol Window right-click menu)
The Duplicate Symbol command creates a duplicate of the selected symbol.
Edit Condition
Use this command to edit the value of a selected parsing condition variable. This is used for languages that support conditional compilation, such as C, C++, and Window Resource files. Conditional code is placed
between #-directives such as #ifdef. See “Conditional Parsing and Preprocessor Support” on page 58.
You can right-click on your source code and select Edit Condition from the menu.
Source Insight can parse those sections of code conditionally depending on the value of condition variables that you specify. The Edit Condition command lets you edit the value of a condition variable, or edit the list of condition variables.
To use this command, right-click on an identifier that is a condition variable in your code. Then select Edit
Condition. You will be able to specify that variable's value.
For example, place the cursor inside of MACOBJECTS and select Edit Condition.
#ifdef MACOBJECTS int jklm;
#endif
Project vs. Global Conditions
There are two condition variable sets. One is project specific and is stored with your project. The second set is global and applies to all projects. If a condition appears in both lists, the project specific value is used.
Edit Condition Dialog box
Edit Condition Set
Selects which condition set you want to affect. This is either the project-specific, or the global list. Any changes you make to the condition's value are put into the list you select here.
Source Insight 4 User Guide 195
Commands Overview
Condition
The name of the condition variable.
Value
The value of the condition. Typical values are 0 (zero) to indicate "False", or 1 to indicate "True". However, you can give the variable any value. If you leave the value empty, then Source Insight will ignore conditional preprocessor directives that refer to this variable.
Set False
Click this to set the Value field to 0 (zero).
Set True
Click this to set the Value field to 1.
Ignore
Click this to empty the Value field. When the Value field is empty, Source Insight assumes you don't want to specify the value of the condition variable. If you don't specify a value, then preprocessor statements like #if are ignored if they refer to this variable. This is the default case for any conditional variables encountered.
Scan Files
Click this button to scan your project files to determine what preprocessor variables are defined, along with their values. The results are put into either the global, or project condition list, depending on which one is selected in the Edit Condition Set option.
Edit List
Click this to go to the Conditional Parsing List dialog box, which displays all the defined conditions. The list
you get to edit depends on which one is selected in the Edit Condition Set option. See “Conditional Parsing
List” on page 171.
Enable Event Handlers
This command is a toggle that enables or disables macro event handlers. For more information, see “Macro
Event Handlers” on page 411.
End of Line
The End of Line command moves the insertion point to the end of the current line.
End of Selection
The End of Selection command moves the insertion point to the end of an extended selection. If the current selection is not extended, this command does nothing.
Exit
The Exit command exits the Source Insight program. Source Insight will ask you if you want to save each file that has been changed but not saved.
When Source Insight exits, it saves the current workspace file, so you may resume your session when you run
Source Insight the next time.
196 Source Insight 4 User Guide
Commands Overview
Exit and Suspend
The Exit and Suspend command writes a Source Insight recovery file out and then closes Source Insight without saving any files. This allows you to exit Source Insight and save your edits without altering any files. Run
Source Insight again to recover your edits.
Warning! Do not alter the files that Source Insight had open before you run Source Insight a second time to recover your changes. Source Insight's recovery system relies on the original files being left unchanged.
Expand
Expands the current hidden block of source code.
Expand All
Expands all collapsed source code blocks. Each function and class will show with a corresponding outline button you can click to collapse them.
Expand Text Variables
Processes and replaces text variables in the selected text.
A text variable is a special identifier that is replaced with a particular value when a snippet is inserted into a file.
See “Code Snippets” on page 96.
Expand Special
Used inside tree lists, this expands the selected item a specified number of tree levels.
Number of levels to expand
Type the number of levels, beyond the selected node, that you want to expand the tree. For example, if you type "1", then one level below the selected node is revealed.
Export File as HTML
Exports the current file to an HTML representation. This creates a file that can be viewed in a web browser that represents your source file.
The resulting HTML file will look a lot like the source file displayed inside of Source Insight. The HTML file will retain most of the syntax formatting.
You can also export a snapshot of your entire project to a set of HTML files by using the Export Project To
HTML command. See “Export Project To HTML” on page 198.
Export Project File List
Saves a text file containing a list of all the source files in your project.
This is useful for creating a Master File List for the project if you don’t have one already. See “Using a Master
File List” on page 44.
Source Insight 4 User Guide 197
Commands Overview
Export Project To HTML
This 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.
Destination Folder
Enter the path to the directory where the HTML files will be output.
HTML file extension
Enter the file extension you want the HTML files to have. This is typically .htm or .html.
Create 'Table of Contents' page
Check this to create a single Table of Contents page with links to all the source files.
Use external CSS files (vs. embedded styles)
Causes a single cascading style sheet (CSS) file to be output that contains formatting definitions. If this box is not checked, then the style declarations are inlined into each output HTML file.
The style formatting closely matches the formatting as it appears in Source Insight.
Include Hyperlinks to symbol declarations
This causes each identifier reference to have a hyperlink to its definition. For example, you will be able to click on the function name in a function call, and the browser will jump to the function's definition.
Link Symbol Types...
Click this button to select which types of symbols should have hyperlinks. For example, you can choose to link function names, class names, class member names, and others.
198 Source Insight 4 User Guide
Commands Overview
File Compare
The File Compare window shows differences between two files. This is a fancy version of the diff
tool.
The window is divided into three parts: The left and right files, plus a difference list on the left side. By default, the File Compare window is grouped with the Directory Compare window in a tabbed panel.
Toolbar
1.
Compare Directory
- switches to the Directory Compare window.
2.
3.
Refresh
- Re-examines files and refreshes the window.
Show line numbers
4.
5.
6.
Lock the window
Previous Difference
(Ctrl+Up) / Next Difference (Ctrl+Down) - selects the previous or next difference in the files.
Copy selected lines left
(Alt+Left) or right (Alt+Right) - the selected block of lines will be copied to the other file. This can be undone. This type of edit is disabled by default for safety, but you will be prompted to enable it.
7.
8.
9.
Undo
(Ctrl+Z) and Redo (Ctrl+Shift+Z) the lines that were copied.
Open new files to compare
(Ctrl+O)
File Compare Window Options
(Ctrl+Q) - opens the options window. See “File Compare Window
Options” on page 201.
Source Insight 4 User Guide 199
Commands Overview
Right-Click Menu
•
Edit File
(Ctrl+E) - Opens the file you clicked on in a regular source file window so that you can edit it.
This is also useful to open and jump to the highlighted section in the file so you can use regular browsing and navigation commands of a source file window.
•
Search
(Ctrl+F) and Search Forward - Searches within the file you clicked on.
•
Copy to Clipboard
(Ctrl+C) - Copies the selected difference block to the clipboard. You must first select with the mouse on a highlighted difference block.
•
Mono Font View
- Switches to mono font view. See “Mono Font View” on page 256.
•
Overview- Toggles
the Overview scroller.
•
Vertical Scrollbar
- Toggles the vertical scrollbar.
•
Nesting Lines
- Toggles showing code block nesting lines.
•
Show Difference List
- Shows and hides the difference list that appears on the left side of the File
Compare window.
To Compare Two Files
To compare two files, click the toolbar button (8) to open two new files to compare, or select Tools > Com-
pare Files
. See “Compare Files” on page 169.
You can also compare the current file with an older backup version by selecting Tools > Compare with Backup
File
.
Working in the File Compare Window
The left and right files are displayed side by side and aligned so that similar lines will line up horizontally. If you are using syntax formatting that uses multiple font sizes, sometimes the alignment can be off a little. You can right-click and select "Mono Font View" to switch to a monospaced font, which will make it easier to align the two files.
The left and right files scroll vertically together. However, you can scroll one file independently by holding down Ctrl while clicking up or down in the vertical scrollbar.
You an control zooming by holding down Ctrl and using the mouse wheel. Alternatively, you can open the File
Compare Window Options and specify the zoom factor.
To jump to the definition of a symbol in the File Compare window, hold down Ctrl and click on the symbol name. The File Compare Window will minimize and a source file window will open at the symbol definition.
If the file type has the option enabled for "Highlight references to selected symbols", then you can click on symbol identifiers in the File Compare windows and Source Insight will automatically highlight references to
that symbol. See “File Type Options” on page 207.
Difference List
The Difference List appears on the left side. It shows a list of difference blocks in the file, and shows what symbols the differences are contained within. The symbols are the ones defined in the left hand file. You can show or hide the difference list by right-clicking on it and selecting Difference List.
Selecting Difference Blocks
You can click on a highlighted difference block to select it. Once a block is selected, you can copy it to the clipboard, or copy it to the left or right file.
To move to the next difference, use the Next Difference command (Ctrl+Down). To move to the previous difference, use the Previous Difference command (Ctrl+Up).
200 Source Insight 4 User Guide
File Compare Window Options
This sets the options for the File Compare window. See “File Compare” on page 199.
Commands Overview
Display in Mono Font View
Displays the source code in mono font view, which uses a mono-spaced font and no other font formatting or size changes. This helps to align right and left files horizontally.
Show line numbers
Shows line numbers at the left of each line.
Show code block nesting lines
Shows code block nesting lines the same as in regular source windows.
Show difference list
Shows the difference list window on the left size of the File Compare window. The difference list contains the list of differences in the file, and what symbols the differences are within.
Show vertical scroll bar
Shows the vertical scroll bar for each file window.
Show Overview
Shows the Overview scroller control on the right edge of each file window.
Allow edits
Enables the "Copy Line Left" and "Copy Line Right" commands, which copy whole line difference blocks to either the left or right file. This option is disabled by default for safety.
Scaling
Sets the display scaling of the File Compare windows. You can also hold down Ctrl and use the mouse wheel to affect the scaling.
Source Insight 4 User Guide 201
Commands Overview
Diff Command....
Sets the external diff command that performs the diff operation. Source Insight comes with its own sidiff.exe tool that performs the diff operation. You can substitute your own tool as long as its output is compatible with Unix diff tools.
File Options
This command activates the File page of the Preferences dialog box. It allows you to set file loading and saving options.
202 Source Insight 4 User Guide
File Options Dialog box
Commands Overview
Options for Opening Files
Sharing
Enable this to allow other programs to modify files while they are open in Source Insight. In other words, a file that is open in Source Insight can be written over by another program.
Disable this to give Source Insight exclusive write access to the files. Files will still be opened in read-only mode, except during Save operations. However, other programs will not be able to open the same files for writing.
Source Insight 4 User Guide 203
Commands Overview
Reload externally modified files automatically
Turn this on to enable Source Insight to detect that files have been modified externally. Files are reloaded automatically. Files are checked every few seconds and whenever the Source Insight application window comes to the front. Each modified file is reloaded silently, without any prompting, unless the Ask before
reloading modified files
option is on, or you have edited the file in Source Insight.
If disabled, you can still run the Reload Modified Files command to manually force Source Insight to reload any modified files that are found.
Ask before reloading modified files
If enabled, then Source Insight will prompt you when it detects that a file has been modified externally to see if you want to reload it.
If disabled, then Source Insight will automatically reload externally modified files silently without any prompting, unless you have also edited the file in Source Insight. If you have already edited a file, the reload operation is not performed.
Assume ^Z (ASCII 26) is End-Of-File
If enabled, then Source Insight will stop loading a file when it sees the EOF (ASCII 26) character. When it saves the file, an EOF character will be appended to the end. If disabled, then Source Insight will continue to read past the EOF character.
Open all backup files as read-only
When you open a file from the backup directory, it will be opened in read-only mode. You can open a backup file by selecting File > Open Backup Version. Source Insight maintains previous version in the backup file if you have the Make backup files when saving option enabled.
Customize the 'Open' Command…
This lets you pick the action performed by the Open command. The Open command is normally assigned to
Ctrl+O, and it has a toolbar button.
The options are:
•
Project File List
- the list of files in the Project Window.
•
Project Directory
- the folder browser in the Project Window.
•
Load File command
- the Load File command dialog box.
•
Standard Open dialog
- the Windows system Open File dialog box.
Options for Saving Files
Make backup files when saving
If enabled, then Source Insight will move the previous version of a file on disk to the backup directory whenever it saves the file. The backup directory is stored in a subdirectory named "Backup" in the Source Insight program directory.
If not enabled, then Source Insight will save files without preserving the previous version on disk.
Remove backup files older than (days)
Specifies how many days to hold onto backup files before deleting them. Backup files older than this are deleted. If this is set to zero, then backup files are kept indefinitely.
Save All command will query on each file separately
If enabled, the Save All command will prompt you to save each modified file. You will have an opportunity to save it, not save it, or cancel the Save operation on each file.
If not enabled, the Save All command will show a list of modified files before saving. You can specify which files will be saved or not.
204 Source Insight 4 User Guide
Commands Overview
Save All operation saves without prompts
If enabled, the Save All command will ask you if you want to save any modified files.
If not enabled, the Save All command will unconditionally save all files that have been modified since the last time they were saved.
Save all files when Source Insight program is deactivated
If enabled, Source Insight will automatically perform a "Save All" command when the Source Insight application window loses focus (i.e. every time you activate a different application). This enables you to work with another editor or IDE that has the same files open. For example, if you switch to your IDE application then
Source Insight will automatically save all edited files to disk. If not enabled, Source Insight will not save files when deactivated.
Confirm saving over modified files
if enabled, Source Insight will prompt you to confirm saving over a file that has been modified outside of
Source Insight while you had it open. This option is enabled by default.
If not enabled, then you can save over a modified file without any confirmation prompt.
Note:
We recommend that you enable this option, so that you are aware of possibly overwriting important changes to files.
Save over read-only files without prompting
If enabled, then Source Insight will save over a read-only file without warning you it is read-only. Actually, you will be warned the first time you attempt to save over a read-only file in a session.
If not enabled, then Source Insight will prompt you for each read-only file that is saved. You will still have the option of overwriting a read-only file on a file-by-file basis.
When Source Insight saves over a read-only file, the file is changed to read/write.
Note:
This option is not recommended, as you may accidentally write over valuable files that are read-only for a good reason. This option may be of use if your source control system will respect a read/write file as "checked out".
Thus, you can edit and save files before you check them out.
Preserve Undo and revision marks after saving
If enabled, then you will be able to perform Undo, and see revision marks, even after you save a file.
Remove extra white space when saving
This option will cause any trailing space or tab characters to be stripped off each line when a file gets saved.
Other Options
Allow editing Read-Only file buffers
This option lets you edit a file buffer, even if it is marked read-only. You will not be able to save back to the file, unless you change its permissions to read/write outside of Source Insight, or you explicitly overwrite the read-only file by clicking the "Overwrite" button during saves. Depending on your source control system, you may be able to check out your version of the file, and then return to Source Insight and save the file.
Note that when you edit a file buffer inside Source Insight, you are not changing the file on disk until you use the Save command, or you cause Source Insight to save the file some other way, such as task switching out of
Source Insight to another program when you have the Save all files when Source Insight is deactivated option enabled.
Confirm all file deletions
Source Insight will confirm before deleting any source files. Source Insight does not delete source files when you remove them from a project, or when you delete a project. It only deletes the project data files created by
Source Insight. However, you can select a source file in the Project Window and delete it.
Source Insight 4 User Guide 205
Commands Overview
Default file format
This specifies the default text file format used when Source Insight saves new source files. The formats differ by their end-of-line characters, which are indicated by CR for Carriage Return and LF for Line Feed. The formats are:
•
Window (CR/LF)
•
Unix (LF)
•
Mac (pre-OS X) (CR)
Note that when Source Insight opens an existing file and saves it, it will preserve the original file's format. You can save to a different format with the File > Save As command.
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 206.
File Search Bar Options
This sets the options for the File Search Bar, which can be shown at the top below the main toolbar. See “File
Search Bar” on page 206.
Select text when found
If enabled, then the matching text is selected. Otherwise only the caret is moved.
Case sensitive
If enabled, the match is case sensitive.
Wrap around to beginning or end of file
If the end of the file is reached while searching, it wraps around and starts again at the top of the file.
Match only whole words
Only whole-words are considered for matches.
206 Source Insight 4 User Guide
Commands Overview
Search while typing
If enabled, then Source Insight searches for a match after you enter any character.
Load word at cursor when buttons are pressed
If enabled, then the word at the cursor position is loaded into the search field when you click Next or Previous button in the search bar. If not enabled, then the current text in the search field is not changed.
Use context sensitive symbol search
If enabled, then searching for an identifier uses context and scope sensitive matching. Symbols with the same textual name, but in different scopes will not be found.
Regular Expressions
Use this to enable regular expression, and to select the regular expression syntax type.
File Type Options
The File Type Options command allows you to define editing and display options based on the file name or extension of the file you are currently editing.
The file type of the current source file is automatically selected in the File Type Options dialog when it appears.
File Types
A file type is a file classification that is defined in the File Type Options dialog. Each file's name determines its file type by using the wildcards in the File Filter field. The file type specifies display options, editing options, and the language used to parse the file.
For example, the "C/C++ Source File" type applies to files that match the *.cpp wildcard pattern, and the file type specifies that the "C/C++ Language" is used to parse the file for symbolic information.
See “File Types” on page 70.
Source Insight 4 User Guide 207
Commands Overview
File Type Options Dialog box
File Type
This pull-down list contains a list of all the file types you have defined so far. When you select a file type from this list, the other text boxes in the dialog box are updated to reflect the properties of that file type. The first entry in the list is always the Default file type, which you may modify, but not remove.
When the File Type Options dialog box first comes up, the file type of the current file is automatically selected here.
Add Type
Click this button to add a new file type. You will be prompted for the file type name.
Remove Type
Deletes the selected file type. This action is not undo-able.
Auto Indent…
Click this to change the Auto Indent settings for this file type. See “Auto Indenting” on page 213.
File Filter
This text box should contain a delimited list of file name specifications. The entries in the list can be delimited with a space, a semi-colon, or a comma. Each entry can be either an unambiguous file name, or an ambiguous wildcard file specification. The entries should not contain a drive letter or a full path that includes backslashes.
208 Source Insight 4 User Guide
Commands Overview
For example,
*.c;*.h
Tip:
Files are matched to File Types using wildcard filters.
Given a file name, Source Insight will identify the file's file type by searching all defined file types looking for a match on a file specification in the File Filter text box. In effect, Source Insight makes two passes through the entire set file type records to determine a file's file type.
1.
2.
First, it tries to find an exact match on the file name in all the File Filter lists.
If no exact match is found, it tries to find a wildcard match in all the File Filter lists.
3.
If still no match is found, Source Insight assumes the file's type is the Default file type.
This means that you can treat some individual files in a special way. For example, "*.inc" is normally considered an Assembly File type, but let's say you have a file called "cmd.inc" that you want to have the C Source
File type. In the C Source file type's File Filter text box, you would include "cmd.inc":
*.c;*.h;cmd.inc
If you include a simple * as the file filter for a file type, then it will become the default catchall type, instead of the "Default" file type. The catchall will only apply if the file does not already match any other file type.
Adding New File Extensions
You can add new entries to the file filter of a standard file type to make Source Insight include those files also.
For example, by default, Source Insight considers C Source Files to be "*.c" and "*.h". If you also have C source files with .h2 extensions, then you can add "*.h2" to the File Filter list of the C Source File file type.
*.c;*.h;*.h2
Tip:
You can control which file types are added to projects.
Whenever Source Insight displays a list of files, such as in the Add Files dialog box, the list is an expansion of the union of all File Filter text boxes in all defined file types. In other words, when you add new file types, those files will also appear in the file lists.
Include when adding to project
If enabled, then the Add File command and the automatic add file feature will include this type of file when looking for new files to add to the project.
Font Options Group
Emulate screen fonts when printing
If enabled, then Source Insight will attempt to select the same fonts for the printer as you have selected for the screen. If you are using a TrueType screen font, that should work fine. If not enabled, then the font setting of the Printer Fonts button is used when printing.
Line up white space
This option only applies if you have selected a proportionally spaced font. Fixed-pitch fonts, such as Courier
New, are not affected.
Tip:
You can use a proportional font and still display indentation correctly.
If enabled, Source Insight will attempt to use a fixed width for spaces and tabs so that tabs line up the same way they do with a fixed-pitch font. Programs generally look better with this turned on if you are using a proportional font. If you are tired of using Courier New (or some other boring fixed-pitch font) to view your code, try this!
If disabled, then Source Insight uses the natural widths of characters as reported by the font.
This option is helpful if you have to work with other tools, or people that use tools that display source code with fixed-pitch fonts. You will be able to use a proportional font, and still keep a valid representation of the fixed pitch font indentation.
Source Insight 4 User Guide 209
Commands Overview
You can control how Source Insight computes the fixed width of spaces by clicking the Spacing button in the
Preferences: Display dialog box.
For more information, see “Character Spacing Options” on page 192.
Screen Fonts
Click this button to select a font to use for displaying the file on the screen. The name of the currently selected font is displayed to the right of the button. The screen font selected here becomes the default font for this file type. Style properties will also apply on top of this font. For example, a style for declarations might add "bold". Or a style might specify a different font and override the screen font selection in the file type.
When you click OK in the font selection dialog, you will see this prompt:
To apply the font to ALL the file types, type "yes" in the box and click OK. To only apply it to the current file type, click No.
Printer Fonts
Click this button to select a font to use for printing the file. The name of the currently selected font is displayed to the right of the button. This setting only has an effect if the Emulate screen fonts when printing option (described above) is turned off.
Parsing Group
Language list
This pull-down list contains a list of all the languages defined in Source Insight. Select from this list to specify how Source Insight should parse and display the current file type. For example, to parse the document as a
Java source file, select "Java Language" from the list. You can also select "None" to use no parser.
To add a new custom language, select the item <New Language>.
The language selected here determines the syntax formatting, as well as how symbol declarations, such as functions and classes are parsed in the file.
Language…
Click this button to open the Language Options dialog box. From there, you can add a new language, and edit the properties of a language. For example, you can edit the syntax formatting keyword list that is associated
with each language. Each language type has its own keyword list. See “Language Options” on page 235.
Custom Tag Type
This pull-down list specifies what type of symbol is found as a result of using the custom parser pattern in the
Custom Pattern text box. The list contains all of the possible symbol types. One of the entries in the list says
"No Custom Parser". If that item is selected, then Source Insight does not use the custom pattern. If any other item is selected in the list, then the custom pattern should contain a regular expression pattern for parsing symbol names out of the file.
210 Source Insight 4 User Guide
Commands Overview
Custom Pattern
This text box should contain a valid regular expression with one group in it. The group describes what part of the matching pattern is assumed the symbol tag. The symbol parsed by using this pattern is given the type indicated by the Custom Tag Type. If the Custom Tag Type is set to "No Custom Parser", then this text box is ignored.
Using a custom pattern that allows you to parse some symbols out of files for which Source Insight has no built-in knowledge. For example, the following string parses sections out of .INI files like WIN.INI.
^\[\(.*\)\]
You can define a new file type named "INI File" that uses this custom parsing pattern. Now, when you open a file like WIN.INI, you can jump to any of the section names or see them all in the symbol window.
Status Bar Options
This group controls the appearance of the status bar at the bottom of the program window.
Line, Col, Symbol
The status bar shows the line number, the column number, and the name of the symbol that the insertion point is in.
Line, Col, Char, Byte
The status bar shows the line number, the column position on the line, the character position on the line, and the byte position in the file.
Editing Options Group
This group of items controls how the file type is edited. All files of the selected file type will have the following editing options in effect.
Word Wrap
If checked then Source Insight will automatically wrap words onto the next line when the insertion point moves past the margin width. This only applies while you are typing new text. If not checked then Source
Insight will not do any automatic wrapping of text.
Allow auto-complete
If enabled, then symbolic auto-completion is allowed for the file type if auto-completion is enabled globally in the Options > Preferences: Typing dialog box.
Allow intelligent paste
If enabled, then intelligent paste is allowed for the file type if intelligent paste is enabled globally in the
Options > Preferences: Typing
dialog box.
Tab Width
The width of a tab character in character spaces.
Margin Width
The width of text in characters spaces before automatic word wrapping will occur
Expand tabs to spaces
If checked then Source Insight will expand a tab character to the equivalent number of spaces when you type a tab. The text will look the same as if a tab was typed, but spaces will be used to fill. If not checked then
Source Insight will simply insert a tab character into the file when you type a tab.
Source Insight 4 User Guide 211
Commands Overview
Enter key inserts new line
If checked then pressing the Return or Enter key while typing will insert a new line. If not checked then pressing Return or Enter will move the insertion point to the beginning of the next line.
Show line numbers
Displays line numbers in the left margin.
Show right margin
Displays a light vertical line at the right margin. If you are using proportional fonts, then the right margin position is only approximate.
Allow code snippets
Allows code snippet expansion in this file type. If enabled, code snippets will appear in the auto-completion list when you type, and code snippet variables will be displayed in a highlighted color.
Visible Tabs
If checked then Source Insight will display a special symbol where ever a tab characters is, instead of just displaying white space.
Visible Spaces
If checked then Source Insight will display a special symbol where ever a space characters is, instead of just displaying white space.
Symbol Window
If enabled, then files with this file type will have a Symbol Window attached at the left side of their source
windows. See “Symbol Windows ” on page 28.
The Symbol Window command on the right-click source file menu toggles this setting.
Use Overview
If enabled, then an Overview scroller will be displayed in the file's source window. at the far right edge. See
“The Overview Scroller” on page 25.
The Overview command on the right-click source file menu toggles this setting.
Show page breaks
Source Insight will show light horizontal lines that represent the printed page breaks. The pagination is computed based on syntax formatting, and the printer font that is selected.
Highlight references to selected symbol
References to the symbol at the caret position will be highlighted. 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.
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.
Use typing shortcuts for parentheses and quotes
This enables several typing shortcuts related to parentheses, square brackets, angle brackets, and quote characters. Typing an open parenthesis, bracket, or quote character will automatically insert the corresponding closing character. In HTML and XML files, opening and closing angle brackets (
<>
) are also inserted automatically.
212 Source Insight 4 User Guide
Commands Overview
For example, to insert
(a + b)
, you would type this:
You Type
( a + b
)
Result - | marks the insertion point
(|)
(a + b|)
(a + b)|
To insert the quoted string "Hello World", you would type this:
You Type
"
Hello World
"
Result - | marks the insertion point
"|"
"Hello World|"
"Hello World"|
If you just inserted an empty pair of parentheses, brackets, or quotes, and want to delete them, press Backspace. Both characters will be deleted. For example:
You Type
(
Backspace
Result - | marks the insertion point
(|)
|
If you type an open parenthesis just before another open parentheses, then the parenthesized block that follows will be surrounded with parentheses. For example:
You Type
Starting with
|(thing)
(
Result - | marks the insertion point
|(thing)
(|(thing))
Auto Indenting
The auto-indenting feature controls the level of indentation as you type new text. Source Insight supports
Simple and Smart types of auto-indentation. Not all languages support the Smart level.
You can also reformat exiting source code using Tools > Reformat Source Code. See “Reformat Source Code
Options” on page 281.
Auto Indent Type
Specifies the type of auto-indenting. Automatic indenting occurs when you insert new lines.
•
None
No special indenting occurs. Source Insight will return the insertion point to the very beginning of the next line when you insert a new line or word wrap.
•
Simple
Source Insight will automatically indent text to line up with the previous or following line.
•
Smart
Source Insight will automatically increase or decrease the indentation level when you insert new lines. Not all languages support smart indenting. If this button is selected, then the Smart Indent
Options are applied.
Smart Indent Options
These check boxes determine how the smart indenting affects open and closing curly braces.
Desired Indent Style
if (x)
{
}
Check box setting
Clear both boxes.
Source Insight 4 User Guide 213
Commands Overview
Desired Indent Style
if (x)
{
} if (x) {
}
Check box setting
Select both boxes
Select Indent Open Brace;
Un-select Indent Close Brace
Folder Options
This command activates the Folders page of the Preferences dialog box. It allows you to specify the location of various data folders used by Source Insight. These options are saved as part of the current configuration.
Folder Options Dialog box
Main User Data Folder
This is the main folder for storing Source Insight information on your machine. Source Insight creates several sub folders inside this folder. If you make a change to this, then all the sub folders that appear below it in this dialog box are automatically updated.
By default, this folder is
Documents\Source Insight 4.0
. As such, there is a separate folder for each user on the machine.
214 Source Insight 4 User Guide
Commands Overview
You may want to change this folder location if you prefer to have your personal "Documents" folder on a network drive. Source Insight can become slow if it has to constantly access data across the network. In that case, you should change the folder location to a folder somewhere on you local machine.
Settings Folder
This is the folder that will contain you configuration files, which has your customizations.
Projects Folder
This is folder that will contain your project data files. Each project will have a sub folder within this folder.
Backup Folder (for non-Projects)
This is the folder where backup source files are saved when you do not have a project open.
Clips Folder
This is the folder that will contain clips, which are accessed from the Clips Window.
FTP Browser
This is an simple FTP client window that allows you to connect to a remove host, and upload and download files. You can browse to a file on a remote host, open it, edit it, and save it back to the remote host.
Toolbar
1.
Connect to Host - Click this to connect to a host. The FTP Site list window will appear so you can pick the host to connect to.
2.
Disconnect - Disconnects from the host.
3.
4.
5.
6.
Refresh List - Refreshes the file list in the FTP Browser.
Download File - Downloads the selected file from the remote host to your local machine. A "Save As" dialog box will appear so you can indicate where to save the file.
Upload File - Uploads a file from your machine to the remote host. A dialog box will appear so you can select the file to upload.
FTP Browser Options - Edits the settings for the FTP Browser panel. You can set options and edit the
list of remote hosts. See “FTP Browser Options” on page 216.
Opening a Remote File to Edit
To open a file on the remote host to edit, double click on the file. The file will be downloaded to a temporary file buffer so you can edit it. When you save the file, it will be uploaded automatically.
Source Insight 4 User Guide 215
Commands Overview
Defining Remote Sites
To setup the details for connecting to a remote site, click the FTP Browser Options button, then click the Site
List... button. Alternatively, you can click the Connect to Host button and the Site List will appear. If you need to add the site, click the "Add" button.
Connect to FTP Site
This dialog appears when you click the Connect to Host button in the FTP Browser window. Select the site
you want to connect to and click Continue. For details, See “FTP Site List” on page 217.
FTP Browser Options
This allows you to specify options for the FTP Browser window.
Binary / ASCII Mode
You can force the data transfer to assume binary or ASCII text mode.
•
Auto
- The mode depends on the file extension. Source Insight can recognize files that are typically textual and use the ASCII mode.
•
Force Binary Mode
- the data is transfered byte-by-byte.
•
Force ASCII Mode
- the data is assumed to be text, and end of line characters are handled correctly.
216 Source Insight 4 User Guide
Commands Overview
Site List...
Edits the list of FTP Sites (hosts). See “FTP Site List” on page 217.
Font & Color...
Let's you pick the text font and colors for the FTP Browser window.
FTP Site List
This window lists all the remote FTP sites you defined. You can add or delete sites from the list.
To add a site, click the Add button. To edit an existing site, select the site and click the Edit button. The Edit
FTP Site Properties dialog will appear. See “Edit FTP Site Properties” on page 218.
Source Insight 4 User Guide 217
Commands Overview
Edit FTP Site Properties
This window is used to specify the properties of a remote host site for the FTP Browser.
Site Name
The user-friendly name you can give to the remote site. For example, "Company Server".
Host Name
The FTP host address of the server. Typically something like "ftp.mysite.com", or an IP address.
User name
The FTP user name used to log on to the server.
Password
The FTP password for the user.
Initial directory
The directory on the remote server that will become the current working directory after the connection.
Port number
The TCP port number to use to connect to the remote host. The default is port 21.
Passive mode
If selected, then the Passive mode is used. Passive mode is best used when you are behind a firewall. In Passive mode, the remote server tells Source Insight what data port to connect to, instead of Source Insight opening a data port on your machine.
If not selected, then the Active mode is used. In Active mode, Source Insight needs to open a data port for the remote server to connect to. This is usually not a good practice for security reasons, and will usually not work with firewalls.
Keep connection alive
If selected, then Source Insight will attempt to keep the connection alive by sending simple FTP commands at random intervals to keep the remote host from becoming idle and disconnecting.
218 Source Insight 4 User Guide
Commands Overview
Full Screen (F11)
This toggles Full Screen mode. In Full Screen mode, the Source Insight main window is expanded to take over all of the current monitor.
Function Down
The Function Down command moves the insertion point to the next function or method defined in the current file.
Function Up
The Function Up command moves the insertion point to the previous function or method defined in the current file.
General Options
This command activates the General page of the Preferences dialog box. It allows you to change miscellaneous Source Insight options. These options are part of the current configuration.
Source Insight 4 User Guide 219
Commands Overview
General Options Dialog box
Sleep when Source Insight is in background
If enabled, Source Insight will not perform any background processing when the Source Insight application is minimized or not in front (such as when a custom command is in front).
If not enabled, then background processing will occur normally.
Note:
If your computer is running on battery power, then Source Insight significantly reduces its background processing after a few seconds of idle time to allow your system to enter a low-power state and use less battery power.
220 Source Insight 4 User Guide
Commands Overview
Background Tasks
Source Insight performs a number of tasks in the background, including the following:
•
It parses files and updates the Symbol Window contents for all open source windows.
•
It checks for finished Custom Commands.
•
If Background Synchronization is enabled, then it synchronizes all the files in the project, possibly adding new ones in the process.
•
It synchronizes the Context Window with the current text selection.
•
It synchronizes the Relation Windows with the current text selection.
•
It updates the File Compare window if one of the files has changed.
•
It checks for and reloads open files that are modified outside of Source Insight by other programs.
Usually there is nothing to do, in which case Source Insight sleeps and uses little or no processor cycles.
Source Tips
Sets the level of information provided by pop-up source tip windows. Source tip windows appear when you hover the mouse cursor over a symbol identifier for a few seconds.
Crash Recovery Options
Recovery: Update recovery file every NNN seconds
Specifies how often Source Insight will update the crash recovery file. The default value is 15 seconds. The recovery file is only updated when there have been edits since the last time it was updated. The recovery update is very fast and you probably will not even notice anything being saved. You will never be interrupted to save the recovery file. You should keep this interval short.
Project File Synchronization
Synchronize on start-up
If enabled and background synchronization is turned on, then Source Insight will check file time-stamps right away every time you start Source Insight or open a new project. When files are found to be out of date with respect to the project, Source Insight marks the files for re-synchronizing. Later, the files will be rescanned and synchronized in the background.
Add new files automatically
If enabled, then before synchronizing all the files, Source Insight will add new files in the project's source directory and in all subdirectories, recursively. However, only directories that already have project files in them are scanned. Directories that are not descendants of the project source directory are not scanned. This feature allows you to simply add new files to your project directories on disk, such as with a source control system, and then have Source Insight add those new files to your Source Insight project automatically.
An alternative to adding (or removing) files automatically is to use a Master File List. See “Using a Master File
List” on page 44.
Remove missing files from the project
If enabled, then before synchronizing all the files, Source Insight will remove missing files from the project’s file list. Note this is not recommended if your source files are mostly on networked drives. If the network drive is disconnected, the files will be removed from your project.
An alternative is to use a Master File List. See “Using a Master File List” on page 44.
Background project synchronization every NNN minutes
If enabled, then Source Insight will perform the actions of the Synchronize File command in the background, while you edit. You typically will not have to run the Synchronize Files command at all if this option is enabled.
Source Insight 4 User Guide 221
Commands Overview
NNN specifies how often the project files should be examined to determine if files need re-synchronizing.
When this period expires, Source Insight checks the file time-stamps and begins the synchronization process in background.
Use stricter confirmation dialog
If enabled, then when Source Insight confirms an operation, you will be required to type "yes" to confirm it.
Keep dialogs on the same monitor as the main window
If enabled, then dialog boxes will be forced onto same monitor as the main Source Insight application window. If not enabled, then Source Insight remembers the positions of dialog boxes, regardless of what monitor they were on.
Enable event handlers
If enabled, then macro event handlers are enabled. For more, see “Macro Event Handlers” on page 411.
Automatically check for software updates
If selected, then Source Insight will periodically check with the Source Insight website to see if an update is available. If an update is found, you will be see a notification window.
Logging...
Click this to edit Source Insight's application logging options. See “Logging Options” on page 248.
Use Defaults...
Click this to reset all the configuration settings to factory defaults. Your current settings will be saved in a
backup file. See “Resetting the Configuration to Defaults” on page 137.
Generate Call Tree
Displays direct and indirect calls from the selected identifier in the Relation window.
The Relation window can show call trees, call reference trees, class trees and other things. An alternative to use the Generate Call Tree command directly is to simply keep the Relation window open and un-locked, and
just put your cursor on a function in your source code. See “Relation Window” on page 297.
Go Back
The Go Back command moves the insertion point to its previous location. Source Insight keeps a selection history, which is a circular list of the last 100 positions you've visited. The selection history is global to all open files, not just the current file.
222 Source Insight 4 User Guide
Commands Overview
The Go Back and Go Forward commands function like the navigation buttons in a web browser.
Using Go Back to View a Function Call Chain
The Go Back command works nicely with the Jump To Definition command. If you jump to a function definition, you can use Go Back to go back to the function caller. This process can recurse many times. You can use
Go Back, and Go Forward to traverse the call chain forward and backward.
The selection history is circular, so eventually you will end up at your starting point.
You can use the Selection History command to show the list. That command shows each position, along with the function or enclosing symbol at each location.
Go Back Toggle
The Go Back Toggle command toggles between running the Go Back command and the Go Forward command. Using Go Back Toggle repeatedly will toggle you between your last two positions.
Go Forward
The Go Forward command moves the insertion point to the next location in the selection history, which is a circular list of the last 100 positions you've visited. See the Go Back command for more details.
The Go Back and Go Forward commands function like the navigation buttons in a web browser.
Go To First Link
The Go To First Link command locates the first source link and does the following:
1.
2.
It selects the link line in the link source file.
It selects the link line in the link target file.
3.
It ensures both files are visible on the screen in windows. If the current window was maximized when this command was used, then only the link target file will be made visible.
The Go To Next Link and Go To Previous Link commands do the same thing, except with the next and previous source link, respectively.
First Source Link
The "first source link" is the first link in the link source file with which a Go To Link Location command was used. For example, if you used the Search Files command to create a Search Results file containing source links, and then you used the Go To Link Location command on a line in the Search Results window, the first source link is determined to be the first link in the Search Results window.
The Go To First Link, Go To Next Link, and Go To Previous Link commands are used to quickly skip from link to link, and are especially useful when the source links are connecting compiler error messages and program source lines.
Using Links With Compiler Errors
If you spawn the compiler from Source Insight, using a custom command, and the output is captured and parsed for error messages, then you can use Go To First Link and Go To Next Link to view each error in your source files.
When you define the "Compile File" custom command, you should have the "Parse Source Links" option on.
Source Insight will then search the compiler output and setup source links for each error message. In this case, the "link sources" are each error message in the compiler output file. The "link target" for each link is the file and line number given in each error message.
Source Insight 4 User Guide 223
Commands Overview
To view source lines with errors
To run a build or compile command, and let Source Insight position to each error message:
1.
2.
Run the "Compile File" or "Build Project" custom command, which is defined as described at “Creating a Compile and Build command” on page 182.
Assuming there are errors, when the compiler finishes the error messages will be in a command output window. Source Insight will automatically setup the source links and run the Go To First Link command. The first error message and the erroneous source line will be selected and made visible.
3.
4.
Run the Go To Next Link command. The next error message in the command output window is selected, and the target of that link is shown, as was the first error.
Continue to use the Go To Next Link command until all the links (error messages) have been visited.
If there are no more links, then Source Insight beeps and the message, "No links." will appear in the status bar.
Using Links With Search Output
The Search Files command puts its output into a Search Results window. Along with each line of text in the
Search Results window is a source link. In this case, the "link sources" are each line in the Search Results window. The "link target" for each link is the file and line where the search pattern was found.
To view each place where a pattern was found:
To perform a search and then visit each place where the pattern was found:
1.
Run the Search Files command.
2.
3.
4.
Use the Go To First Link command to see the first match.
Use the Go To Next Link command to see successive matches.
Continue using the Go To Next Link command until the "No Links." message appears.
Go To Line
The Go To Line command allows you to type a line number and position the insertion point on that line.
Note:
You can also type a line number into the Bookmark window to go to a line within the current file.
Go to Line
Type the line number here.
OK
Click to go to the line number. If you type a line number beyond the end of the file, Source Insight positions to the last line in the file.
Cancel
Click to cancel the Go To Line command.
224 Source Insight 4 User Guide
Commands Overview
Go To Next Change
Moves the cursor to the next block of lines that were edited. It moves the cursor to the next set of change marks.
Go To Previous Change
Moves the cursor to the previous block of lines that were edited. It moves the cursor to the last set of change marks.
Go To Next Link
The Go To Next Link command behaves the same as the Go To First Link command, except the next link is used. See Also: Go To First Link command.
Go To Previous Link
The Go To Previous Link command behaves the same as the Go To Next Link command, except the previous link is used. See Also: Go To First Link command.
Go To Next Reference Highlight
This moves the cursor forward to the next highlighted reference.
To enable reference highlights, select Options > File Type Options , and check the box that says "Highlight references to selected symbol". This option is set per-file type.
When enabled, Source Insight highlights all 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. The highlight will only appear if more than one instance appears in the file.
Go To Previous Reference Highlight
This moves the cursor back to the previous highlighted reference.
To enable reference highlights, select Options > File Type Options , and check the box that says "Highlight references to selected symbol". This option is set per-file type.
When enabled, Source Insight highlights all 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. The highlight will only appear if more than one instance appears in the file.
Help
The Help command brings up help on Source Insight. You can also press F1 while a dialog box is up and
Source Insight will display help on the current command.
Help Mode
The Help Mode command turns on the help mode. When a command is invoked while the help mode is on,
Source Insight displays help on the command and turns off the help mode, instead of running the command.
You can cancel the help mode by running the Help Mode command again.
Source Insight 4 User Guide 225
Commands Overview
For example, to get help on the File > Open command, type Ctrl+F1 to turn on the help mode. A message will appear in the status bar to indicate that help mode is active. Now go to the File menu and select the Open command. A help window will open and display help on the Open command.
You can also press F1 while a dialog box is up and Source Insight will display help on the current command.
Highlight Word
Toggles word-highlighting for the word under the cursor in all source windows. This is like using a highlighter pen on paper. If you select a word, and use the Highlight Word command, then anywhere that word appears in your source, it will appear highlighted.
By default, the highlight appears like bold black text with a bright yellow background. However, you can set the highlight effect yourself by editing the Highlight style. The Style Properties command is used to edit styles.
Incremental Search
The Increment Search and Incremental Search Backward commands invoke the incremental search mode.
By default, F12 is the Incremental Search command, and Shift+F12 is Incremental Search Backwards.
Once in incremental search mode, Source Insight will start finding matches as you type characters, starting at the current cursor position. As you type more characters, the search will become more specific. The characters you type will appear at the bottom in the status bar.
You can exit the incremental search mode with any command key (such as an arrow key) or by pressing Esc. If you want to search again, just type F12 twice - it will load the old pattern and find again.
Incremental Search Mode
Once you press F12, you enter the incremental search mode. Once in the incremental search mode:
•
F12 will search again for the current string, or it will load the current string with the previous one if the current string is empty.
•
Shift+F12 will search backwards.
•
Backspace reduces the search string.
•
Esc will cancel and return to the initial position.
•
Enter will stop and leave the selection at its current position.
•
Any key that maps to a command will exit the incremental search mode and leave the selection at its current position, and then the command will execute.
•
Any other simple key is added to the current search pattern, which is displayed at the bottom in the status bar.
•
The search buffer is left with the last successful search pattern.
The incremental search pattern is not case sensitive, unless you type an uppercase character.
Incremental Search Backward
Searches backwards, incrementally, in the current file. See “Incremental Search” on page 226.
Horizontal Scroll Bar
This command toggles the horizontal scroll bar on and off in the current source file window
226 Source Insight 4 User Guide
Commands Overview
HTML Help
Looks up the currently selected word in the HTML Help file. The HTML Help file is the one specified in the
Setup HTML Help command. See “Setup HTML Help” on page 325.
Import External Symbols
The Import External Symbols command lets you import symbol information from external sources, such as
.NET assemblies, Java classes, standard C/C++ header libraries, and other source trees. The symbol information is used for symbolic auto-completion while you type, and to show function or class definitions, and symbol syntax formatting.
The imported symbols are put into special "import library projects" to contain the imported symbols. This replaces the functionality of the "Project Symbol Path" feature from version 3.x. For example, you could use it to create symbols for SDKs, or the STL, or the C-runtime header files.
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. The list is searched in the order it appears in this dialog. 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. The list is searched in the order it appears in this dialog. 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.
What is an Import Library?
An import library is a special Source Insight project that contains imported symbols - the symbols come from an external source, such as a .NET assembly or Java class. Symbols can be imported from the following types of files:
•
.NET .dll and .exe files
•
A whole diretory tree of .NET .dll and .exe files
•
Java .jar files
•
Java .class files
•
A whole directory tree of Java .class files
•
A whole directory tree of source files
•
All the source files in a directory path, such as an INCLUDE path
•
Another Source Insight project
When you import symbols from one of these sources, a new hidden 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 holding down CTRL and selecting
Project > Open Project
. The project list will contains all your projects, plus the import projects.
Source Insight 4 User Guide 227
Commands Overview
Import Library Dialog
This dialog is used to edit the import library list.
Library list
This is the import library list. It is a list of the external libraries currently imported. Source Insight searches libraries in the order they appear in this list. You can use the Move Up or Move Down buttons to rearrange the list.
Add...
Adds a new external library to the list. The "Add Library Symbols" dialog will appear.
Delete
Deletes the selected library from the import list. You will also be prompted to remove the corresponding
Source Insight project that holds the symbols.
Once you delete a library from the import list, Source Insight will no longer search for symbols in it.
Properties...
Displays information about the selected library, such as what file it was imported from.
Move Up / Move Down...
Moves the selected library up or down in the list. Source Insight searches for symbols in the library list in the order they appear in this dialog box. Therefore, the listing order may be significant to you.
Add Library Symbols
This dialog is used to import symbols from an external file into a new Source Insight import library.
228 Source Insight 4 User Guide
Commands Overview
When you import a file or set of files, a new import project is created to hold the symbols, and the project is added to the import library list.
Import from an INCLUDE path
This imports symbols from source files found on the INCLUDE environment variable directory path. The
INCLUDE environment variable should be defined in your environment. If not, you can enter any directory path. All the directories in the path will be scanned for source files and added to the import library.
Use this to import the standard C and C++ header files, and/or the standard Windows headers files, or any header library or source code library that is not already part of your Source Insight project.
Import from a source code tree
The specified directory tree will be scanned for source files and added to the import library.
This is useful for importing symbols from an external source code library that is not already a part of your
Source Insight project. For example, you can refer to symbols in a third-party runtime library, or a third-party library's header files.
.Import a directory tree of .NET assemblies
This imports an entire directory tree of .NET assembly files.
You can use this to import an entire version of the .NET Framework. This allows auto-complete to work for the packages that have been imported into a C# source file using the using statement.
Import a Java jar file
This imports a single Java .jar file.
Source Insight 4 User Guide 229
Commands Overview
Import a directory tree of Java classes
This imports an entire directory tree of Java .class files. For example, you can import an entire Java package hierarchy.
Import from a another Source Insight project
Click this to import symbols from another existing Source Insight project. This doesn't actually create the project. It just adds the project to the import list.
Import single file
Click this to import a single .dll, jar, or .class file.
Import External Symbols for Current Project
This command imports external symbol definitions for use with the current project only. Other projects are
not affected. See “Import External Symbols” on page 227.
Indent Left
The Indent Left command out-dents the lines intersecting with the current selection to the left by the size of one tab stop. Lines that begin with # are not indented.
Indent Right
The Indent Right command indents the lines intersecting with the current selection to the right by the size of one tab stop. Lines that begin with # are not indented. Source Insight indents lines to the right by inserting a tab character. If you have the "Expand tabs to spaces" option on for the current file type, then spaces equivalent to a tab stop are inserted instead of a tab character.
Insert ASCII
The Insert ASCII command inserts a character that you specify with its ASCII code.
Radix
Selects the input radix of the character code you typed. If Auto is selected, then the input radix is determined from the text you type. For example, if you type 0x20, then the radix is assumed to be Hex, and ASCII 32 is inserted.
Character Code
This is the ASCII code of the character you want to insert.
Insert File
The Insert File command pastes the text of another file into the current selection.
File Name
The name of the file to insert. You may also type a series of wildcard specifications and click the Insert button and Source Insight will replace the file List contents with the results of wildcard expansion. The wildcards are expanded in the current directory.
230 Source Insight 4 User Guide
Commands Overview
File list
If the Project Wide option is enabled, then this list displays all files in the current project. If disabled, then this list displays all the files in the current working directory. The current directory path is displayed at the top of the list box.
Insert
Click Insert to insert the contents of the file in the File Name text box. If the File Name text box contains one or more wildcard specifications, then Source Insight will replace the File List contents with the results of the expansion. The wildcards are expanded in the current directory.
Show Dirs
Click this button to toggle the list box contents between showing file names, and showing only subdirectory names.
Browse
Click this button to bring up the standard Windows Open dialog box, which allows you to browse around your disks.
Project Wide
If enabled, the file List will show all the files that have been added to the current project. If not enabled, the file List will show files in the current directory only. This option is always unchecked if no project is open.
Insert GUID
Generates a new GUID (Globally-Unique-Identifier) and inserts it into the source file.
Insert Line
The Insert Line command inserts a new, empty line before the line the selection is on. The cursor does not have to be at the beginning or end of the line.
If Auto Indent is turned on, then the new line will be indented even with the line below it.
Insert Line Before Next
The Insert Line Before Next command inserts a new, empty line after the line the current selection is on. If
Auto Indent is turned on, then the new line will be indented even with the line above it.
Insert New Line
The Insert New Line command inserts a new line starting at the insertion point. This is just like pressing Enter, except the cursor does not move to the next line.
Insert Snippet
Join Lines
The Join Lines command joins the line the insertion point is on, and the next line, so that it forms one single line. If the selection is extended, then all the lines intersecting with the selection are joined.
Source Insight 4 User Guide 231
Commands Overview
Jump To Base Type
Moves the cursor to the most base structure type of the selected variable or type. For example, consider the following code: struct MyStruc
{
int afield;
int anotherfield;
};
// MS type is defined as struct MyStruct typedef struct MyStruct MS;
MS ms; // declare ms with a type of "MS" x = ms.afield;
If you put the cursor in ms in the assignment statement (or anywhere the ms variable appears), the Jump To
Base Type command will jump to the definition of struct MyStruc, because that is the most base structure type of the variable. It won't stop at the typedef of MS.
Jump To Caller
Jumps to the caller of the selected function, if any. For example, if you put the cursor on a function name and use Jump To Caller, then you will jump to the function that calls it. If more then one function calls it, you will see a list from which you may pick.
Jump To Definition
The Jump To Definition command takes the symbol from the first word in the current selection and jumps to its definition. The Go Back and Go Forward commands are useful for navigating back and forth between all your jumping spots.
To use this command:
1.
2.
Select within the symbol name as it appears in a source file.
Type Alt+= to jump to the actual symbol definition.
Mouse Shortcut
Hold down Ctrl and left click with the mouse on a symbol name to jump to its definition.
Opening Header Files
You can also use the Jump To Definition command when the cursor is in a file name in an #include statement to open the file.
Jump To Link
Moves to the other end of the source link at the current line. See “Go To First Link” on page 223.
Jump To Prototype
Jumps to the declaration of the selected function's prototype. This only works if the selected symbol is a function.
232 Source Insight 4 User Guide
Commands Overview
Key Assignments
The Key Assignments command allows you to assign or reassign keystroke combinations to commands. The mouse buttons can also be assigned to commands. The key assignments are part of the current configuration.
Key Assignments Dialog box
Command
You can type into this text box to narrow down the command list, so that you can find the command you want easily. With name fragment matching, you can simply type a word contained within any command name.
Command list
Lists all the Source Insight commands, including macros and custom commands that you've defined. When you select a command here, the keystrokes list is loaded with all the keystrokes currently assigned to the selected command.
Keystrokes list
Lists all the keystrokes assigned to the selected command. Select a keystroke here before clicking the Delete button when deleting it.
OK
Click this to record the new key assignments in the current configuration.
Cancel
Click this to cancel the command. The current configuration will not be affected by any changes in the dialog box so far.
Source Insight 4 User Guide 233
Commands Overview
Assign New Key…
Click to add a new keystroke or mouse click to the command selected in the Command list. A window will pop up prompting you to type a key combination.
Delete Assignment
Click to remove the assignment of the keystroke selected in the Keystrokes list from the command selected in the Command List.
Run
Click to run the selected command. This also records any changes you have made.
Reset
Click to reset the key assignments to their default, factory settings. Source Insight will ask you if you are sure you want to do this.
List
Click to create a key assignments list file. This also records any changes you have made. The list file is just a text file that contains a list of commands, and their key assignments.
Menu
Click Menu to record the new key assignments in the current configuration, and then run the Menu Assign-
ments command. See “Menu Assignments” on page 255.
Numeric Keypad Keys
The numeric keypad keys
/ * - + are bound to these commands by default:
Key
-
+
/
*
Command
Scroll Half Page Up
Scroll Half Page Down
Function Up
Function Down
If you want those keys to function normally by just inserting the character on the key top, then you need to un-assign those keys from the commands.
Use the Options > Key Assignments dialog box to find those commands and delete the key assignments for each of them. When the key assignments are removed from those keys, they will function normally.
Assigning Keys and Mouse Clicks
The procedures for assigning keys and mouse clicks are described below.
To Assign Keystrokes
You can add any combination of Alt, Ctrl, and Shift key modifiers with any other key, including mouse buttons.
To assign a new keystroke combination to a command:
1.
Select the command in the Command list.
2.
3.
Click the Assign New Key button.
Type the keystroke(s) that you want to assign. Pressing Esc cancels the assign procedure. If the keystroke you typed is already assigned to a different command, Source Insight will ask you if you want to re-assign it.
234 Source Insight 4 User Guide
Commands Overview
To Assign Mouse Clicks
To assign a mouse click to a command:
1.
Select the command in the Command list.
2.
3.
Click the Assign New Key button.
Click the mouse button that you want to assign. If you want a modifier key, such as Alt, Shift, or Ctrl, to be included, press the modifier key before clicking the mouse button. You can even use the Left mouse button to modify the right button. Pressing Esc cancels the assign procedure.
To Delete a Key Assignment
To delete a keystroke assignment from a command:
1.
2.
3.
Select the command in the Command list.
Select the keystroke to be deleted in the Keystroke list.
Click the Delete button.
Language Options
This command activates the Languages page of the Preferences dialog box. It allows you to edit languagespecific options, such as the language keyword list.
Source Insight 4 User Guide 235
Commands Overview
Source Insight supports two types of languages: Built-in and Custom. You can alter a few options for built-in languages. For custom languages, you can control all the parameters for a generic language.
Language
This list contains all the installed languages. Custom Languages are marked with a red asterisk in the icon.
You associate a language with a particular file type with the File Type Options command. See “File Type
Options” on page 207.
Add…
Click this button to add a new custom language. See “Language Properties” on page 238.
Delete…
Click this to delete the selected custom language. Only custom languages can be deleted. The built-in languages cannot be deleted.
Import…
Click this to import a custom language into the list from a custom language file. A custom language file (.CLF) contains all the properties of a single custom language.
Export…
Click this to export the selected custom language to a custom language file (.CLF). A custom language file contains all the properties of a single custom language. You can export a custom language so that other people can import the language into their Source Insight configurations.
236 Source Insight 4 User Guide
Commands Overview
Properties…
Click this button to open the Language Properties dialog box. Use this to control custom languages proper-
ties. See “Language Properties” on page 238.
Keywords
Click this button to edit the keyword list associated with the selected language type. The Language Keywords dialog box will appear.
File Types…
Opens the File Type Options dialog box.
Special…
Displays options that are specific to the selected language. Not all languages have special options.
Conditional Parsing Options
Project Specific Conditions…
Click to edit the conditions defined that are specific to the current project only. These conditions are only in effect when the current project is open, and only for files that belong to the project.
Global Conditions…
Click to edit the global condition set. Global conditions are defined for all projects. The total set of conditions defined for any given project is a combination of both the project-specific, and the global condition sets. The
project-specific conditions will override global conditions with the same name. See “Edit Condition” on page 195.
Special Language Options
When you click the Special button in the Preferences: Languages dialog box, the Special Language Options dialog box appears. This dialog box controls special options for built-in languages.
C/C++ Options
Ignore namespace declarations
If enabled, then namespace declarations are simply ignored in C++ code. All symbols declared within the namespaces are considered at the file scope, as though you did not write the namespace declaration.
If not checked (the default), then symbols declared within namespaces are considered in the namespace scope.
Parse standard COM macros
If enabled, then the standard COM helper preprocessor macros, such as STDMETHOD, are recognized and parsed. Note that if you already have entries for these macros in your c.tom token macro file, then this option has no effect.
Java Options
Ignore package declarations
If enabled, then package declarations in your Java files are ignored. Any symbols declared after the package statement are considered in the "global" package scope. That is, they are all in the same virtual package.
If not checked (the default), then any symbols declared after a package statement are considered in that package scope.
Source Insight 4 User Guide 237
Commands Overview
HTML and Scripts Options
Default script language
You can specify the default script language to use in HTML and ASP files with this control. The default script language is only used if another language is not specified in the script.
Language Properties
This command displays the properties of the currently selected language. The Language Properties dialog box appears when you click the Properties button in the Preferences: Language dialog box.
Source Insight supports two types of languages: Built-in and Custom. You can alter a few options for built-in languages. For custom languages, you can control all the parameters for a generic language.
Language Info
The Info page is used to edit the name of the language, and a comment. Clicking the Keywords… button opens the Language Keywords dialog box.
238 Source Insight 4 User Guide
Commands Overview
Basic Language Options
Each language has basic options that govern how Source Insight treats files with this language. Built-in languages, such as C/C++ have fewer options in this page than do custom languages.
Contains program source code
If enabled, then Source Insight will consider this a programming language. Certain features are altered when a programming language is used, as opposed to a simple textual language. For instance, references to declared symbols are displayed in the "Ref to …" styles.
Case sensitive text
This indicates whether the language is case sensitive or not. This affects how keywords are matched, as well as how symbols names are resolved in the symbol lookup engine.
Uses C preprocessor
If enabled, then Source Insight will recognize #if and #ifdef preprocessor directives.
Allow smart tab
If enabled, then the Smart Tab feature will be enabled when editing this type of language. If not enabled, then Smart Tab will perform like a simple tab.
Use Syntax Formatting
If enabled, then Syntax Formatting will be used when displaying files in this language.
Source Insight 4 User Guide 239
Commands Overview
Detect comment styles
If enabled, then special comment styles will be detected. See “Comment Styles” on page 83.
Non-AlphaNum identifier chars
This text box contains the set of all valid non-alpha-numeric identifier characters. Alpha-numeric strings are always considered identifiers.
Detect numbers
If enabled, then numbers found in the text are formatted with the "Number" style. The check boxes following this enable special number formats for hex and octal numbers.
Comments and Ranges
The Comments and Ranges page is where you specify how comments and other multi-line range elements are parsed. A quoted string is an example of a non-comment multi-line range element.
Add…
Click this button to add a new range element. The Range Definition dialog box will appear. See “Range Definition” on page 240.
Delete
Deletes the selected range element.
Edit…
Opens the Range Definition dialog box so that you can edit the range element's properties. See “Range Definition” on page 240.
Delete All
Deletes all range elements.
Range Definition
The Range Definition dialog box appears when you add a new range element, or edit a range element in the
Language Properties: Comments and Ranges dialog box. It controls all the properties of a range. A range defi-
240 Source Insight 4 User Guide
Commands Overview
nition specifies how comments and other multi-line range elements are parsed. A quoted string is an example of a non-comment multi-line range element.
Type of range
Select the type of range element from this list. There are two types of range elements:
•
Line
The range starts with a delimiter, and extends to the end of the line. It cannot span more than a single line.
•
Multiline
The range starts with a delimiter, and ends with another delimiter. The range can span more than single line, but it can also be contained within a single line. The starting and ending delimiter can be the same (such as a quote).
The list also contains presets for single and double quoted string ranges, and some comment styles. When you select one of the presets, the parameters for the preset are loaded into the other text boxes in the dialog box.
Syntax Formatting Style
This specifies the syntax formatting style to apply to the range. Normally, you would select a comment style.
However, you are free to select any style. If the range element describes a quoted string, you would probably
want to select the "String" style. See “Style Properties” on page 333.
Note:
The style is applied to the whole range. The style overrides any other automatically applied style, such as "Reference To…" styles.
Range begins/ends with
These two text boxes specify the delimiter tokens that start and end the range. The tokens can be up to 15 characters long. If a Line range type is specified, then there is only one delimiter text box enabled. If you are
Source Insight 4 User Guide 241
Commands Overview
specifying a Multiline range, the beginning and ending delimiters can be the same. This would be the case for a quoted string.
Escape sequence
If either the Begin or End delimiter is preceded by this escape sequence, then the delimiter is ignored. For example, you might specify backslash \ as an escape character in a quoted string so that you can embed quote characters inside the string like this: "a string with \"embedded\" quotes".
Allow nesting
This applies only if a Multiline range is specified. If this option is turned on, then the range can be nested. If the Begin and End delimiters are the same, nesting is not allowed because it doesn't make any sense.
Skip symbol parsing
The contents of the range will be ignored when the file is parsed for symbol definitions.
Include delimiters in style
The Begin and End delimiters are also formatted with the selected style. If this is unchecked, then the delimiters are formatted in the "Delimiter" style.
Columns Group
The columns group allows you to control if the range element should be sensitive to where on the line it occurs.
Only valid in the following columns
If enabled, then the range is only recognized if its Begin delimiter occurs in the range starting at the First col-
umn
and up to and including the Last column. If this check box is unchecked, then the column is ignored.
242 Source Insight 4 User Guide
Commands Overview
Custom Parsing
The Custom Parsing page is where you can type a set of regular expressions to perform simple parsing operations on the language source files.
Use regular expressions for parsing
This enables the custom parsing expressions. Uncheck this to disable the use of custom parsing.
Expressions
This lists each parsing expression and the type of symbol it yields. When Source Insight parses a file, all the expressions are applied to the whole file.
Add…
Click this button to add a new parsing expression to the list. See “Custom Parsing Expression” on page 244.
Delete
Click this to delete the selected expression.
Edit…
Click this to edit the expression. See “Custom Parsing Expression” on page 244.
Delete All
Click this to delete all the expressions from the list.
Source Insight 4 User Guide 243
Commands Overview
Custom Parsing Expression
When you click the Add or Edit button in the Custom Parsing dialog box, the Custom Parsing Expression dialog box appears.
Regular expression pattern:
This text box contains the regular expression used to parse a symbol definition out of a file. The expression should contain one group. The group describes what part of the matching pattern is the symbol name. Using a custom pattern allows you to parse symbols out of files for which Source Insight has no built-in knowledge.
For example, the following string parses sections out of .INI files like WIN.INI.
^\[\(.*\)\]
For more information, see “Regular Expressions” on page 107.
Finds this symbol type:
This pull-down list specifies what type of symbol is found by the parsing pattern. The list contains all of the possible symbol types. The symbol types are fixed and cannot be extended. The symbol type also determines the syntax formatting style used to display the symbol.
Styles for Custom Parsing Symbols
The symbol type specified for the custom parsing expression determines the style that will be used to display the symbol's declaration and references. Each symbol type X has a corresponding "Ref to X" and "Declare X" style.
When a symbol definition is parsed, the corresponding "Declare…" style is used when displaying the symbol name. For example, if the symbol definition is a Function, then the function name will be displayed in the
"Declare Function" style. See “Style Properties” on page 333.
Last Window (Ctrl+Tab) or (Ctrl+Shift+Tab)
Activates the previous current window. You can hold down CTRL while repeating the Tab key to select each successive window. This works like Alt+Tab in the Window’s user interface.
Layout Toolbar
Shows and hides the Layout toolbar within the main toolbar.
244 Source Insight 4 User Guide
Commands Overview
Line Numbers
This command toggles the display of line numbers. The line numbers appear at the left of each line. They are displayed in the Line Number style. You can edit the style using the Style Properties command.
Link All Windows
The Link All Windows command toggles the Link All Windows mode. When the Link All Windows mode is on, then scrolling any window will scroll all the other windows. The Link All Windows mode overrides the normal window links that are setup by the Link Window command.
Link Window
The Link Window command links the current window to another window so that they scroll together. This command lets you specify what window is linked.
Once you link the current window to another window, scrolling the current window will scroll the linked window.
If the Two Way check box is on, then the windows are linked together so that scrolling either of them will scroll the other. However, if the check box is off, then this is a one-way link. Scrolling the linked window will not scroll the other one.
Linkage
Link A to B.
Link A to B to C
Result
Window A has a link to window B. Scrolling window A will cause windows A and B to scroll, but not the other way around.
Windows may be linked to windows that are in turn linked to other windows. Scrolling window
A, will cause all windows to scroll. Scrolling window B will scroll B and C.
Window links can even be circular. In other words, a window may be indirectly linked to itself. This is sometimes useful to get all the linked windows to scroll; regardless of what window you actually caused to scroll.
Another way to get all windows to scroll is to use the Link All Windows command to turn on the Link All Windows mode, or just turn on the Two Way check box.
Line Window To
This list contains all windows, other than the current window. Select the window you want to link to here.
Select <none> if you want to unlink the window.
Two Way
Turn this on to link both windows so that scrolling either of them will scroll the other. Turn this off to only perform a one-way link.
Load Configuration
The Load Configuration command loads a new group of program settings from a configuration file. A configuration file contains your customizations and optional settings. You can load the whole configuration file, or just part of it.
See “Customized Settings and Configurations” on page 133.
Source Insight 4 User Guide 245
Commands Overview
Load Configuration Dialog
The Load Configuration command will open a configuration file and load the settings. The configuration file may only contain certain parts. Before it loads the settings, you will see a list of the parts contained in the file.
Check mark the items you want to load.
You can save a partial configuration file using the Save Configuration command. For instance, you may only save the key maps. When you load a configuration file that contains a partial configuration, only the parts that exist in the file are loaded. The rest is unchanged. By loading and saving partial configurations, you can
mix and match some of the configuration parts. See: “Save Configuration” on page 310.
Load File
The Load File command opens a file to edit. It opens a dialog box containing a list of all files in the project, regardless of directory.
You can also open files by using the Open command, or by dragging files from Windows Explorer and dropping them on the Source Insight window.
File Name
Type part of the name of the file you want to open. You may also type a series of wildcard specifications and click the Open button, and Source Insight will replace the File list contents with the results of wildcard expansion. The wildcards are expanded in the current directory.
As you type in this text box, partial matching occurs in the file list.
File list
If the Project Wide option is on, then this list displays all files in the current project, regardless of directory.
246 Source Insight 4 User Guide
Commands Overview
If the Project Wide option is off, then this list displays all the files in the current working directory. The current directory path is displayed above the list box. The files shown in the current directory are expanded from the wildcard strings specified in the File Type Options dialog box for all file types.
Open
Click this to open the file selected in the file list. If nothing is currently selected in the file list, then Source
Insight opens the file named in the File Name text box. If the File Name text box contains one or more wildcard specifications, then Source Insight will replace the file list with the results of the expansion. If the Project
Wide option is on, the wildcards are expanded over the whole list of files in the current project; otherwise, the wildcards are expanded in the current directory. If the file specified does not exist, Source Insight will allow you to create a new file with that name.
Select All
Click this to select all the files listed in the file list.
Show Dirs
Click this button to toggle the list box contents between showing file names, and showing subdirectory names.
Project Wide
If enabled, the file list will show all the files that have been added to the current project, regardless of directory. If not enabled, the file list will show files in the current directory only. This option is always disabled if no project is open.
Browse
Click this button to bring up the standard system Open dialog box, which allows you to browse around your disks.
Load Layout
This command loads a layout file, which contains window arrangements. This makes it easy to transition between different tasks that require different window arrangements.
A layout contains the following:
1.
2.
The size and position of the Source Insight application window.
The size and position of each panel window. A panel window is either floating or docked.
3.
The properties and settings for each panel window.
See “Saving Window Arrangements with Layouts” on page 140.
Special Load Layout Commands
There are also four Load Layout commands which are on toolbar buttons, and which you can bind a keystroke to. They are:
•
Load Layout A
•
Load Layout B
•
Load Layout C
•
Load Layout D
Each of the above commands loads from a layout file named "layout_a.xml", "layout_b.xml", etc. These are the layout files created when you use the Save Layout command and select the quick layouts A through D.
See “Save Layout” on page 311.
Source Insight 4 User Guide 247
Commands Overview
Load Search String
The Load Search String command loads the contents of the current selection into the current search pattern.
The search pattern is what is in the Find text box of the Search and Replace commands.
Lock Context Window
This command locks the Context Window so that its contents don't change. When the Context Window is locked, it does not track your actions.
Lock Relation Window
Toggles Relation Window locking. When locked, it will not automatically update. You can still use the "Show
Relation" command to manually update the Relation Window. You can also click on the Refresh Relation Window button in the Relation Window toolbar.
Logging Options
This dialog sets options for Source Insight's application logging. Source Insight can maintain a log file that is useful for debugging issues with Source Insight.
Checking Level
This option is only available in special "debugging" builds of Source Insight. This specifies the amount of internal checking that is performed.
Log user commands
Every time you issue a command in Source Insight, the command is logged to the file.
Log file names
When you open or save perform some operation on a file, the file name is logged to the log file. If you are concerned with the secrecy of your file names, then you should not check this box.
Show Assertion Failure messages
If a debugging check fails, an "assertion failed" message box will appear with some debugging information.
Even if this is not checked, the assertion failure information is still logged to the file.
Output to log file
Enables logging to the log file. If this is not checked, then no logging is performed. The name of the current log file is displayed to the right. It is typically named SI.LOG, or SI2.LOG etc. Multiple the number is incremented if more than one instance of Source Insight is running.
Open log file in notepad
Click this to open the current log file in Notepad.
Empty the log file
Click this to empty the log file to start over.
Lookup References
The Lookup References command searches the current project for references to a selected symbol. For example, click inside "BeginPaint", run the Lookup References command, and Source Insight will open a Search
Results window, which lists all the places that reference "BeginPaint" in your project.
Source Insight uses its symbol indexes to make the searching fast.
248 Source Insight 4 User Guide
Commands Overview
References can be found in all source code text, including comments, and potentially inactive #ifdef branches. However, you can control whether these places are searched or not.
Note:
The Search Project command is the same as Lookup References, but with different option state. See “Search
Project” on page 319.
Lookup References Dialog box
The Lookup References command is very similar to the Search Project command. In fact, each dialog box is identical. However, each dialog box has its own persistent state.
Find References To
Type the symbol name you want to locate. The word under the cursor is automatically loaded into this text box. Source Insight will use the context of the cursor position to determine the exact symbol instance you want. If you invoked Lookup References from a symbol dialog box or window, then Source Insight keeps the exact symbol references along with this text box.
Typically, you would type the name of an identifier in your program, however you can type any string here and a project-wide search will be performed. The search is very fast if you type a single word only.
Search In
This drop-down list contains a list of file types. You can use this list to restrict the search to only a particular type of file, or just the current file. If the Project Window is visible, then you can also use this list to specify the files selected in the Project Window.
Search Method
You can pick the search method to use from this list. There are four different searching methods available:
•
Simple String
•
Regular Expression
interprets the pattern as a regular expression.
•
Keyword Expression
similar to an Internet search query.
•
Lookup Reference
searches for symbol references.
Source Insight 4 User Guide 249
Commands Overview
Lines of Context
This only applies if you selected the Keyword Expression search method. This specifies how closely, in num-
ber of lines, the keywords must occur in order to qualify as a match. See “Keyword Expressions” on page 250.
Find word variations
If enabled, Source Insight will also find different ending forms of the keywords you specified. For example, if you specified the keyword "open", Source Insight will also find "opens", or "opened", or "opening". This option is only available for the Keyword Expression search method.
Include in Results...
Click this button to specify what information is included in the Search Results.
Search Options
Case Sensitive
Specifies whether the search is case sensitive or not.
Whole Words Only
For the Lookup References mode, this option is always on. If you choose a different search method, this will restrict matches to only whole words.
Skip Inactive Code
If enabled, then only code that is active under conditional compilation is searched. You must first specify known conditions in the Preferences: Languages dialog box, in order for Source Insight to know what conditions are active or not. Conditional compilation only applies to some languages.
Skip Comments
If enabled, then comments will not be searched.
Search Only Comments
If enabled, then only comments will be searched. This is mutually exclusive with the Skip Comments option.
The comment options slow the search down a little.
Smart Reference Matching
This enables Source Insight's smart reference matching feature. Source Insight will determine whether each reference found is actually referring to the symbol you are looking for.
Tip:
Matching exact references slows the reference finding process.
The Smart Reference Matching option means that the search results will only contain references strictly to the exact symbol you specified. For example, if you select a member of a struct and look up its references, the search results will only contain references to that particular member of that particular struct – not just any string that is equivalent. Note that this option slows the process down because each same-string occurrence has to be qualified with a symbol lookup.
Touch files and cause recompile. Turn this on to cause each file's "last modified" time stamp to be set to the current time. This is useful if you have a compile time dependency on an identifier usage. Just turn this on and search for references with this command. The places where the identifier is referenced will be "touched" and your make program or development system will recompile those files the next time you build your program.
Keyword Expressions
A keyword expression search is similar to an Internet search engine query. Source Insight searches the project for occurrences of a set of keywords that appear within a specified number of lines. The Lines of Context text box indicates the maximum distance the keyword terms can be from each other to qualify as a match.
250 Source Insight 4 User Guide
Commands Overview
For example, if you typed "cat food", then Source Insight will search for occurrences of "cat" and "food" within X lines of each other.
There is an implicit logical-AND operator between keywords. That is, if you type more than one keyword, the both keywords must be present to qualify as a match. You can include other Boolean operations as well. The following table lists the operators available:
Operator
AND or +
OR
NOT or – or !
=
? "regexp"
Table 4.4: Keyword Search Operators
Example
cat and dog cat or dog
-cat
Action
Both terms must be present.
Either term must be present
The term must not be present
=Betty
? "^Ich"
Case sensitive match
Term is a regular expression
You can also group expressions using parentheses. For example:
(cat or kitty) and food
(file or buffer) and (save or write) and !error
Keyword Variations
If you enabled the Find word variations option, then Source Insight will also find different ending forms of the keywords you specified. For example, if you specified the keyword "open", Source Insight will also find
"opens", "opened", and "opening". This has the same effect as typing this expression:
(open or opens or opening)
Word variations are applied to each keyword term. For example, if you specified: save write
Which implies "save" and "write" must be present. With word variations enabled, this search would be equivalent to:
(save or saves or saving) and (write or writes or writing)
Keyword Search Results
When you perform a keyword search, the Search Results will list blocks of lines that include the keywords together. This gives you a little bit of context around the matches.
Make Column Selection
The Make Column Selection is used with the mouse. Alt+Left Click and drag creates a rectangular selection.
The column selection can be Cut, Copied, or Pasted.
Manage License
The Manage License dialog allows you to view your license information, enter a new serial number and activate your license, or deactivate your license. The options available in this dialog depends on the current status of your license and whether it is a Trial or Regular license.
To Begin a Trial
Choose "Begin a Trial". After you finish filling out some basic information, Source Insight will connect to the
Source Insight licensing system and issue you a trial license. You can continue to use Source Insight for 30 days.
Source Insight 4 User Guide 251
Commands Overview
To Begin Using a Purchased License
Choose "Enter a purchased serial number" to enter your license serial number. Source Insight will connect to the Source Insight licensing system to validate the license and activate it on your machine. You will not have to activate it again.
To Deactivate a License
If you no longer want to run Source Insight on your machine, or would rather use it on a different machine, we recommend deactivating your license. If your license is deactivated, you can activate it again with the same serial number on a new machine. Deactivating reduces your activation count so that you can activate it on another machine.
License Activation General Information
Source Insight requires activation over the Internet to run. Once you install and launch Source Insight, you will be prompted to either enter a serial number or start a new Trial license.
When prompted, please enter your name and email address. This information 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.
See “Activating Source Insight” on page 16.
If you have any problems or questions about the activation process, please email us at [email protected].
Manage Visual Themes
This is used to define and apply visual themes. A visual theme is a collection of font and color settings, plus style settings used in source code windows. From here you can apply a theme, define and delete themes, rename themes, and also import and export themes from external theme files.
252 Source Insight 4 User Guide
See “Visual Themes” on page 138.
Commands Overview
Apply Theme
Applies the currently selected theme to the program. You can also double click the theme name to apply it.
Note that once you apply it, the <Current Settings> items becomes <Previous Settings>. You can still apply the <Previous Settings> theme from the list to return to the settings that where in effect when you invoked this dialog box.
Define
Defines a new theme by recording all the current color, font, and style settings. Once you set all the colors, fonts, and styles they way you like them, use the Visual Themes dialog to record all the settings into a new theme.
The Define Visual Theme dialog allows you to define a new theme, or redefine an existing theme. You can also specify what should be included in the theme.
Delete
Deletes the selected theme.
Rename
Renames the selected theme.
Import
Imports themes from a previously saved themes file. A themes file can have any number of themes in it. Since theme files may contain multiple themes, the Import Theme dialog allows you to pick and choose which themes to import.
The new themes are added to the existing list. Themes with the same names will be replaced with the imported themes.
Source Insight 4 User Guide 253
Commands Overview
Export
Exports the selected themes to a new themes file. You can use this to share themes with other people, or to load into a different configuration you have saved separately.
Define Visual Theme
This appears when you click Define in the Manage Visual Themes dialog.
Once you set all the colors, fonts, and styles they way you like them, use the Visual Themes dialog to record all the settings into a new theme. Click the Define button and the Define Visual Theme dialog appears.
See “Visual Themes” on page 138.
Save To
Select the theme you want to save to. You can select an existing theme to re-define it. Or select "New Theme" to define a new theme. If you select "New Theme" from the list, you will be prompted for a theme name.
Include In Theme
Select the components you that want to be part of the theme. When a theme is applied, only the components that are part of it have any effect. For example, you can include just the color of the main window, but not the styles. Or you can include only styles.
254 Source Insight 4 User Guide
Commands Overview
Menu Assignments
The Menu Assignments command allows you to assign or reassign commands to the menus. The menu assignments are part of the current configuration.
Command
You can type into this text box to narrow down the command list, so that you can find the command you want easily.
Command list
This lists all the Source Insight commands, including macros and custom commands that you've defined.
The commands are listed by category. When you select a command here, the menu it appears on, if any, is selected in the Menu list, and the contents of that menu are loaded into the Menu Contents.
Note that there is a special command in the list called "--Menu Separator--". Insert this item on the menu to create a separator line in the menu.
Menu list
This pull-down list contains the titles of all the top level menus. When you select a menu from here, the contents of the menu are loaded into the Menu Contents. There is a menu in this listed named "Work", which only appear on the application menu bar if you add a command to it.
Menu Contents
This lists the menu items of the menu selected in the Menu list. Select a menu item here to indicate what item should be deleted, and where to insert new items.
OK
Click to record your menu assignment changes in the current configuration.
Cancel
Click to cancel the command. None of your changes up to this point will be saved in the current configuration.
Source Insight 4 User Guide 255
Commands Overview
Insert
Click to insert the selected command onto the selected menu. The command is inserted just before the selected menu item. You must select a command, a menu, and a menu item before clicking Insert.
Delete
Click to delete the selected menu item. You must select a menu item in Menu Contents before clicking Delete.
Up
Moves the selected menu item up, towards the top of the menu.
Down
Moves the selected menu item down, towards the bottom of the menu.
Run
Click to record your menu assignment changes in the current configuration, and run the selected command.
Reset
Click to reset the menus assignments to their default, factory settings. Source Insight will ask you if you are sure you want to do this.
Keys…
Click to record the new menu assignments in the current configuration, and then switch to the Key Assign-
ments command. See “Key Assignments” on page 233.
Mono Font View
The Mono Font View command on the View menu toggles the Mono Font View mode on and off. When this mode is on, all syntax formatting is suppressed, except for color changes, and a mono-spaced font is used.
Tip:
Use Mono Font View to quickly see how text columns lines up. You can edit the Mono Font View font in Style Properties
All text is displayed using the "Mono Font View" style, which can be edited with the Style Properties dialog
box. The "Mono Font View" style is preset to use a mono-spaced font. See “Style Properties” on page 333.
The Syntax Formatting features of Source Insight are powerful, and allow you to use a variable pitch font if you want, but sometimes you need to see how text will line up in another editor or in a simple display mode when only a single font is used. 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.
New
The New command creates a new, unsaved file buffer. The file is not created on disk until you save it using the Save or Save As commands.
The New command will prompt you for a file name. By default, the new file is given a name of the form
New0001.ext. The next time you use the New command, the new file name will be New0002.ext, and so on.
The extension used will be the same as the current file. The name and extension you type will determine what file types will be in effect for that file.
When you save new files for the first time, Source Insight allows you to change their names, and asks if you want to add them to the current project.
256 Source Insight 4 User Guide
Commands Overview
Another way to create a new file is to use the Open command and specify a file name that does not exist.
Source Insight will ask you if you want to create the file. Assuming you do, Source Insight will create a new unsaved file with the name you specified.
New Clip
The New Clip command creates a new clip buffer. You will be prompted for a clip name. You should not add
extensions to the clip name. See “Clip Window” on page 164.
New Relation Window
This creates a new Relation Window. You can have as many Relation Windows as you like. Each window has its own set of options.
For example, you could select a function name, and have one Relation Window showing what other functions it calls, and another Relation Window showing who calls the selected function.
Alternatively, you could have one Relation Window tracking the current selection, and another tracking the enclosing function.
See “Relation Window” on page 297.
New Project
The New Project command creates and opens a new project. See “Projects” on page 38.
Since Source Insight allows only one project open at a time, Source Insight will ask you if it's okay to close the current project, before proceeding.
You will be asked for a project name, where the files should be stored, and what source files you want to add to the project.
New project name
Enter the name of your project. Enter a simple user-friendly name; do not enter a path name here. This is the name that will appear in the Open Project dialog. In the data folder (specified below this) Source Insight will create several data files that start with this name and have different extensions.
Source Insight 4 User Guide 257
Commands Overview
Where do you want to store the project data files?
Specify the full path of the project data file folder here. Source Insight will store all its project data in this folder, independently of your source files. You can specify the same folder as your source files, or use a separate location.
By default, Source Insight creates a sub-folder with the same name as the project inside your user document directory in the Projects folder. This is the recommended location.
For best performance and reliability, we recommend a local, non-networked drive for the project data directory.
If you are creating a project that refers to source 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 on your local machine, preferably in the default proposed location.
After you answer these two questions, you will be taken to the Project Settings dialog. When the Project Settings dialog box appears, enter the location of the your source files into the project source directory
field.See “Project Settings” on page 277.
New Window
The New Window command opens a new window on the screen. The file appearing in the current window will appear in the new window as well.
Next File
The Next File command runs the Close command, and then runs the Open command. You will have an opportunity to save the current file if you've modified it, unless you have the Save Quietly option turned on in the
Preferences: General dialog.
Next Relation Window View
Cycles through the view modes of the Relation Window. This includes the outline view, and graphical views.
Open
The Open command activates the Project Window and sets the focus on the text box of the Project Window. If the Project Window was not visible, it is made visible, and then hidden after you select a file to open.
You can customize what the Open command does in the Preferences: Files dialog box. Instead of activating the Project Window, you could have it bring up other dialog boxes or windows instead.
If you do not have a project open, then this command will bring up the system Open dialog box, which is a standard system dialog box.
You can also open a file by dragging a file and dropping it onto the Source Insight application window.
258 Source Insight 4 User Guide
Commands Overview
Open Backup File
This command opens a backup version of the current file. Depending on your backup settings, you may have many or few backup copies of your file.
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.
To open the Backup folder in Window Explorer, click the Show Folder button.
See “Backup Files” on page 123.
Open Project
The Open Project command allows you to open a new current project. It first closes the current project, if
any, since a Source Insight instance only allows one project open at a time. See “Projects” on page 38.
Source Insight 4 User Guide 259
Commands Overview
You can also open a project by dragging a project file (.siproj) from Windows Explorer onto the Source Insight window, or specifying a project file in the Open dialog.
Project Name
Type the name, or part of the name, of the project you would like to select.
Project list
Displays a list of all the projects you have created or opened on your machine. Select the project you want to open here. This list is simply a recording of known projects. You may have other projects that are not listed here. To open those, click the Browse button and locate the project file.
Browse
Click this button to bring up the standard Open dialog box, which allows you to browse around your disks.
Locate a project file with a .siproj extension. Once you select a file and close the Open dialog box, the file you selected will be loaded into the Project Name text box. Then click OK to open it.
Show import projects
If selected, then import projects will also appear in the project list. Import project names begin with "_import_".
An import project is a special Source Insight project that contains imported symbols - the symbols come from an external source, such as library headers, a .NET assembly or Java class.
See “Import External Symbols” on page 227.
Outline Toolbar
Shows and hides the Outlining toolbar.
260 Source Insight 4 User Guide
Commands Overview
Outlining Options
These options control the outlining features, which allow you to collapse and expand blocks of code.
The outlining options are displayed inside the Window Options dialog. See “Window Options” on page 360.
Overview Options
This shows or hides the Overview scroller. The Overview shows a "bird's eye" view of your source file. It's a miniature version of your file that helps to orient you within a source file, or even within a long function. The
Overview attaches to the side of a source window, like a scroll bar.
General Options
Displays the optional settings for the Overview scroller.
Enable hover messages
Enables popup source tips when the mouse hovers over the Overview.
Show bookmarks
Draws marks that represent the position of bookmarks in the text.
Show change marks
Draws marks that represent areas that have been edited in the text.
Show active selection
Shows highlighted text when you make a text selection in the source window.
Show code block nesting lines
Draws nesting lines around nested functions and code blocks.
Source Insight 4 User Guide 261
Commands Overview
Show all function boundaries
Draws boundaries marks around function bodies to show where functions are.
Show only current function boundary
Draws boundary marks around only the currently viewed function in the source window.
Text Scaling %
Sets the scaling percentage of the Overview text. It is typically something small, such as 10%. A settings of
100% would show the text full size as it appears in the source window.
Note: the width of the Overview can be adjusted by dragging its border with the mouse.
Colors
These set the colors of items in the Overview.
Use regular text colors of source window
Uses whatever text color is set for the source windows, instead of picking a custom color.
Use background color of source window
Uses whatever background color is set for the source windows, instead of picking a custom color.
Page Down
The Page Down command scrolls the active window down by one window full, with one line of continuity.
Page Setup
The Page Setup command allows you to control the layout of text on printed pages that are printed with the
Print command.
Columns
Specifies the number of columns to print per sheet of paper. Each column will get its own page number. For example, if you have two columns, then each sheet of paper will get two pages of source code printed on it.
This is more useful if you print in landscape mode (where the paper is wider than tall).
Borders around page
If enabled, then a single line border will be drawn around the text on the page.
More…
Click this button to open the standard system Page Setup dialog box. This dialog box allows you to set paper size, margins, and orientation (i.e. Portrait vs. Landscape). You can also change the current printer settings from this dialog box.
Title Strings Options
The items in this group affect the titles printed on the cover page, the top of the page (header), and the bottom of the page (footer).
Cover, Header, Footer
These text boxes specify the formatting codes to be used for the cover page, and the header and footer on
each page. See “Header and Footer Codes” on page 263 for details on the format of the strings.
262 Source Insight 4 User Guide
Commands Overview
Include cover page
If enabled, then a single cover page will be printed before all other pages. Typically, you would put your name in the Cover string text box so that someone at the printer could identify the source of your print job. If not enabled, then no cover page is printed.
Header per column
If enabled, then a header will be printed above each column. This only has an effect if the number of columns is set to two or more. If not enabled, then a single header is printed at the top of the page.
Footer per column
If enabled, then a footer will be printed below each column. This only has an effect if the number of columns is set to two or more. If not enabled, then a single footer is printed at the bottom of the page.
Formatting Options
The formatting options control how syntax formatting is output to the printer. These options work independently of the screen settings, which you control in the Preferences: Syntax Formatting dialog box.
Print Syntax Formatting
If enabled, all syntax formatting effects will be printed, as well as displayed on the screen.
Print in color
If enabled, then color is used for printing. If your printer is not a color printer, then colors will be displayed in shades of gray. If you disable this option, then all text, regardless of on-screen color, is printed in full black or white. However, text that is colored near a neutral gray is printed in gray.
Header and Footer Codes
A header is a title printed at the top of the page. A footer is a title printed at the bottom of the page.
You can customize headers and footers for printed pages with the Page Setup command. You do this by using the following codes in the Header and Footer text boxes:
Code
&/
&B
&I
&U
&L
&C
&R
&D
&T
&F
&P
&N
&&
Table 4.5: Header and Footer Codes
Result
Left-align characters that follow. This is the default.
Center characters that follow.
Right-align characters that follow.
Move to the next line.
Print the characters that follow in Bold.
Print the characters that follow in Italic.
Print the characters that follow in Underline style.
Print the current Date.
Print the current Time.
Print the File name.
Print the Page number.
Print the total Number (N) of pages in the document. For example, in a file 12 pages in length, you would type Page &P of &N to have Page 1 of 12, Page 2 of 12, Page 3 of 12, etc., printed on the pages.
Print a single ampersand (&) as a literal character rather than as an instruction.
Source Insight 4 User Guide 263
Commands Overview
For example, to print "Confidential" at the left margin, center the page number, and print current date at the right margin, type:
&LConfidential&C&P&R&D
Page Up
The Page Up command scrolls the active window up by one window full, with one line of continuity.
Paren Left
The Paren Left command moves the insertion point left to the next enclosing parentheses.
Paren Right
The Paren Right command moves the insertion point right to the next enclosing parentheses.
Parse Source Links
The Parse Source Links command searches the current file for a specified pattern. Whenever it finds a match, it creates a source link at that location. The source link links the source line in the current file to the file and line number that was parsed using the pattern.
File, then Line
and Line, then File. Select File, then Line if the first group in the pattern expression is the file name, and the second group is the line number. With this setting, the second group, (i.e. the line number), is optional.
Select Line, then File if the first group in the pattern expression is the line number, and the second group is the file name.
Pattern
Contains the regular expression used to search the command output for file names and line numbers. This text box must contain a valid regular expression that contains "groups" for the file name and the line number.
The contents of this text box are saved in the current workspace.
The Parse Source Links command is useful if you have some kind of log file that contains compiler output and error messages. You just open the log file, and run the Parse Source Links command. A link will be setup for
each line in the log file containing an error message. “Searching and Source Links” on page 105.
Maintaining Multiple Parse Patterns
If you often have more than one type of parse pattern that you want to use, you can use Custom Commands to define a custom command for each type that simply echoes the file and parses source links from the output. Each custom command can have its own parse pattern, so you can save many parse patterns this way.
For example,
1.
From the Options menu, select Custom Commands.
2.
3.
4.
Click the Add button, and type "Parse Type 1" in the Name text box.
In the Run text box, type " command /c type %f
". This command line will type out the contents of the current source file.
Check the Parse Link in Output box.
5.
Type the parse pattern you want in the Pattern text box.
When you run this command, the current file will be typed out, captured by Source Insight, and parsed for source links using the parse pattern stored with the custom command.
264 Source Insight 4 User Guide
Commands Overview
Paste
The Paste command copies the contents of the clipboard to the current selection. If the current selection is already extended, it is deleted before pasting.
Paste From Clip
The Paste From Clip command copies the contents of a clip buffer to the current selection. The Clip Window is activated when you use this command so that you can specify the source clip name.
Double-clicking on a clip in the Clip Window also runs this command.
See “Clip Window” on page 164.
Paste Line
The Paste Line command moves the insertion point to the beginning of the current line and executes the
Paste command. Cut Line, Copy Line, and Paste Line can be used together to quickly move whole lines around in a file.
Paste Symbol
(On the Symbol Window right-click menu)
The Paste Symbol command pastes the text in the Clipboard just before the selected symbol in the Symbol
Window.
Pick Window
Manages the list of open source windows and file buffers. It also lists file buffers that are not visible in any window.
Note:
You can use the Window List panel instead of this dialog. It is a mode-less version of this dialog.
Window list
Contains a list of all open source windows, and file buffers that may be open in the "background" that do not appear in a window. You can sort the window list by name or by recently-used order. To sort the list, click on the header titles at the top of the list.
Activate
Brings the selected window to the front.
Close Window
Closes the selected windows.
Save
Saves the selected files.
Save As
Performs a Save As command on each selected file.
Minimize
Minimizes the selected windows.
Source Insight 4 User Guide 265
Commands Overview
Restore
Restores the selected windows.
Tile Horiz
Tiles the selected windows horizontally so they are generally wider than they are tall
Tile Vert
Tiles the selected windows vertically so they are generally taller than they are wide.
Play Recording
The Play Recording command plays back a command recording. Commands are recorded by using the Start
Recording command. If the recorder is on when you use the Play Recording command, then recorder is automatically turned off first.
Preferences
The Preferences dialog specifies many of the program options. This multi-page dialog box contains several tabs for various types of options, such as Display, Files, and Syntax Formatting. The settings are stored in a configuration file.
For more specific information:
See “General Options” on page 219.
See “Typing Options” on page 354.
See “File Options” on page 202.
See “Folder Options” on page 214.
See “Language Options” on page 235.
See “Symbol Lookup Options” on page 337.
See “Display Options” on page 189.
See “Color Options” on page 166.
See “Syntax Decorations” on page 343.
See “Syntax Formatting” on page 346.
See “Searching Options” on page 319.
See “Remote Options” on page 303.
Print
The Print command prints the current file. The standard Windows Print dialog box will appear.
You can control what font is used for printing files with the File Type Options command. The File Type
Options command lets you specify what font should be used for printing and what font should be used for the screen. Alternatively, you can tell Source Insight to emulate the screen font when printing. If you have a
TrueType font selected, then emulating that font on the printer should work just fine. If you have a raster font selected, such as "MS San Serif" or "Courier", then printing that font on the printer may look blocky, or the printer driver may just substitute that font with something similar.
Color Printing
If you want to print your files with syntax formatting and color, you need to make sure you have enabled those options in the Page Setup dialog box.
266 Source Insight 4 User Guide
Commands Overview
Print Relation Window
This command prints the graphic contents of the Relation Window. You can access this command by rightclicking on the Relation Window.
Source Insight can print a multiple page graph. Each page will indicate its page coordinate at the bottom. For example, if a graph spans a 4 x 3 page output, the bottom of the first page printed will contain "Cell 1,1 of 4 x
3 square".
Project File Types
Displays a list of project files, categorized by file type, in the Project Window. The Context Window tracks the selection in this list.
Project File Type List Properties
This dialog shows the options for the Project File Types List window.
Show Columns
Check the box next to the columns you would like to appear in the list.
Code Metrics
Select the type of code metrics to show in the column. The drop-down list to the right selects which code metric value to display in the column.
Font & Color
Click this button to edit the font, and foreground and background color of the list.
Project Folder Browser
Displays the Folder Browser view of the current project. This view allows you to browse around directories on your disk.
Source Insight 4 User Guide 267
Commands Overview
Project Folder Browser Options
Displays the Folder Browser options.
Show Columns
Check the box next to the columns you would like to appear in the list.
Layout based on window shape
Check this box to let the window change its layout based on the shape of the window. If the window is tall, the lists will be stacked vertically. If the window is wide, the lists will be side by side.
Select the folder and file entry of the current file
If enabled, then the folder browser will automatically select and display the current file that you are editing.
The directory structure containing the file is expanded so you can see the file’s location.
Font & Color
Click this button to edit the font, and foreground and background color of the list.
268 Source Insight 4 User Guide
Commands Overview
Project File List
Displays a list of the files in the current project. This is a "flattened" list of all the files in the current project, regardless of directory. When a project is open, then the File > Open command activates the Project File List window.
To open a file, double click on a file in the list, or start typing the name into the text field.
To add a file to the project, you can drag files from Window Explorer onto the Project File List.
The Context Window previews the file selected in this list without needing to open the file.
Source Insight 4 User Guide 269
Commands Overview
Right-Click Menu
Project File List Options
This dialog shows the options for the Project File List.
Show Columns
Check the box next to the columns you would like to appear in the list.
270 Source Insight 4 User Guide
Commands Overview
Code Metrics
Select the type of code metrics to show in the column. The drop-down list to the right selects which code metric value to display in the column.
Font & Color
Click this button to edit the font, and foreground and background color of the list.
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 view the Project Search Bar, select View > Project Search Bar.
To activate it so you can start typing, use Activate Project Search Bar (Alt+Shift+P)
See “Search Project” on page 319.
Project Rebuild Notice
This window appears if Source Insight tried to open a project in the background, but noticed that the project needed rebuilding or reindexing.
If you cancel or do not rebuild the projects, then Source Insight will ignore those projects and will not notify you again for the rest of the session. If you exit Source Insight and restart it, the notice will appear again.
Why Do Projects Need Rebuilding?
A project needs to be rebuilt if wasn’t closed correctly and is corrupted. It may also need to be rebuilt or reindexed if the Source Insight version used to create it was older and there has been a change in Source Insight.
For example, if the data or index format changed.
Source Insight 4 User Guide 271
Commands Overview
If you try to open a project that needs rebuilding by using Project > Open Project, Source Insight will ask if you want to rebuild it. However, projects that are opened in the background do not cause such a user prompt. Therefore this notice window appears when Source Insight is idle.
Background Projects
You normally have a current project open. However, Source Insight opens other projects in the background in order to provide auto-completion, and to use syntax formatting for externally defined symbols, and to locate user macro commands. Source Insight opens Import library projects, projects on the Project Symbol Path, and the Base project in the background.
See “Importing Symbols from Libraries” on page 53.
See “Import External Symbols” on page 227.
See “The Project Symbol Path” on page 54.
See “The Base Project” on page 47.
272 Source Insight 4 User Guide
Commands Overview
Project Symbol Categories
Displays a list of project symbols by category. The Context Window and the Relation Windows track the selection in this list.
Project Symbol Category Window Options
This dialog shows the options for the Project Symbol Category List window.
Show Columns
Check the box next to the columns you would like to appear in the list.
Symbol Types
Click this button to choose or filter the types of symbols that appear in the list.
Source Insight 4 User Guide 273
Commands Overview
Font & Color
Click this button to edit the font, and foreground and background color of the list.
Project Symbol List
This panel lists all the symbols in the current project. This is a very handy way to quickly jump to functions or other symbol definitions if you know part of the name.
From this panel, you can
•
Find symbols based on parts of their names.
•
Look at symbol definition in the Context window.
•
Look at references to symbols in the Relation window.
•
Jump to symbol definitions.
See “Project Symbol List Options” on page 276.
To locate a symbol quickly, type a part of the symbol name and the list will be filtered down as you type. You can also use name fragment matching to find parts of symbol names. For example, if you type: doc write this will match symbol names such as DocWrite, WriteDoc, Doc::DoWrite, WriteOpenDoc, CanWriteAnyDoc,
etc. See “Name Fragment Matching Symbol Names” on page 64.
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”.
274 Source Insight 4 User Guide
Commands Overview
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 297.
Source Insight 4 User Guide 275
Commands Overview
Right-Click Menu
Project Symbol List Options
This dialog shows the options for the Project Symbol List window. See “Project Symbol List” on page 274.
Show Columns
Check the box next to the columns you would like to appear in the list.
Symbol Types
Click this button to choose or filter the types of symbols that appear in the list.
276 Source Insight 4 User Guide
Commands Overview
Font & Color
Click this button to edit the font, and foreground and background color of the list.
Project Settings
The Project Settings command allows you to set various options that govern the current project. If no project is currently open, then the Project Settings command allows you to set the default options inherited by subsequently created new projects.
The Project Settings are saved with the project data file. These settings are independent of the configuration file.
Conditional Parsing
This controls the settings of condition compilation values.
Source Insight 4 User Guide 277
Commands Overview
Conditions…
Click to edit the conditions defined that are specific to the current project only. The conditions are only in effect when the current project is open, and only for files that belong to the project. Another quick way to edit the conditions is to use the Edit Condition command.
Project Source Directory
This is the directory you consider to be the "root" of your project’s source tree. When Source Insight displays file names, it will show them relative to this directory. If you leave this text box blank, then Source Insight will
use the project data directory where you created the main project file, with the .siproj extension. See “New
Project” on page 257.
The project data files are stored in the project data directory - which you specified when you created the project. Typically source files reside somewhere else. For example, you could create a project stored locally on your workstation, and add files from a remote network drive to the project. The file names will not contain extra path information if you specify the network drive path to the source files as the project source directory.
Using different data vs source directories is helpful when you are not allowed, or unable, to create project data files in the same directory as the source files. Some project administrators will allow you read-only access to the source code share point, and do not want you to put any Source Insight files there.
You can change the project source directory setting in the Project Settings dialog at any time after the project is created.
The project source directory path is stored with the project data in a relative format. The path is relative to the directory with the .siproj file. That allows projects that were created on one machine to be opened remotely from another without confusing the logical drives. It also allows copying whole project directory trees to new locations.
Some Custom Command string meta-character substitutions are also affected by this path setting. The %j
(project source directory) and %v (project source directory volume letter) refer to this path value, and not where the .siproj file is.
See “Project Directories” on page 39.
Project Backup Directory
Specified where you want to keep backups of your source files. By default, a Backup folder is created within
your project folder. You can use Path Variables in this field. See “Predefined Path Variables” on page 147.
Project Source Files
Add and remove source files manually
The project will contain only the files that you added using Project > Add and Remove Files.
Use a Master File List
The project will contain whatever is listed in the Master File List. You can still use add and remove files from the project manually. The changes you make will be saved to the MFL. If the MFL contains a file name 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 the project, then it will be removed from the project. See “Using a Master File List” on page 44.
You can use Path Variables in this field. See “Predefined Path Variables” on page 147.
Symbol Database Options
These options affect what is stored in the project's symbol database. You should choose these options before you add a bunch of files to your project. If you change these options after the project is already built, then the project will need to be rebuilt. Source Insight will rebuild it for you.
Quick browsing for member names
If enabled, you only need to type the structure and class member names in order to perform partial matches on their names. However, the symbol index size and memory usage can increase by a factor of two or more.
278 Source Insight 4 User Guide
Commands Overview
This option is recommended if you are using an object-oriented language primarily, so that you can find member functions and variables without having to type in the class name too.
Quick browsing for symbol name fragments
If enabled, you only need to type one or two name fragments of symbol names in order to perform partial matching on their names. However, the symbol index size and memory usage can increase by a factor of four or more. By indexing name fragments, you can use name fragment matching to quickly find symbols, even if you don't know what letters the symbol names begin with.
This option is not recommended for external common projects that you intend to only refer to via the project symbol path or the Import External Symbols feature. In that case, name fragment indexing offers no benefit and just uses extra disk space.
If your project is very large (over several thousand files, or hundreds of thousands of symbols), turning off this option can improve performance by using less memory and speeding up the Project Symbol List window.
If both check boxes are turned off, then the list filtering in the Project Symbol List panel 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.
Index Performance
Name Fragment matching is such a useful feature, that we recommend enabling it, unless you think performance is affected. The symptoms of too large an index are:
•
Disk thrashing while building or rebuilding a large project, while little progress is being made.
•
Opening or closing a project takes a long time.
•
Synchronizing individual files is slow.
•
The Project Symbol List (F7) is slow to come up, accompanied by a lot of disk activity. Some delay is normal the first time you use it.
•
Your project has over 2 or 3 million index entries. Obviously, this limit depends on the amount of RAM you have.
•
Your hard drive light never seems to go off, or your system pauses for a long time while the disk is flushed.
If you experience slow-downs and you have a large project, (say over 300,000 symbols,) you should try turning off Quick browsing for symbol name fragments.
You can find out how large the database is by selecting Project > Rebuild Project and looking at the statistics on the bottom of the dialog box. Just cancel this dialog box when you are done. If the index entries are in the millions, then things can start to slow down. However, most modern machines should handle this size project well.
Project Report
The Project Report command generates an output report file called <project>.RPT, which contains a list of files and symbols in the current project.
Files
Turn on these check boxes to include the corresponding information.
Include Symbols
If enabled, then symbols will be listed under each file. If not enabled, then no symbol information will be listed in the project report.
Source Insight 4 User Guide 279
Commands Overview
Line Numbers
If enabled, then the line number where the symbol is defined is listed by the symbol name.
Sort by
If Occurrence is selected, then symbols will by listed by line number. If Name is selected, then symbols will be listed by symbol name.
Symbol Types
Click this button to indicate what types of symbols will be included.
Project Window command
The Project Window can be toggled on and off by running the Project Window command. You can activate and set the focus to the Project Window by running the Activate Project Window command.
The Project Window is a floating/dock-able window. By default it contains all the Project-List sub-window panels:
•
Project Symbol List - quick access to all symbols in the project. See “Project Symbol List” on page 274.
•
Project File List - quick access to all files in the project. See “Project File List” on page 269.
•
Project Symbol Categories - See “Project Symbol Categories” on page 273.
•
Project Folder Browser - See “Project Folder Browser” on page 267.
•
Project File Types - See “Project File Types” on page 267.
If the Context Window is open, then it will display the contents of any file or symbol selected in the Project
Window.
Rebuild Project
The Rebuild Project command rebuilds the project data files. Source Insight creates the data files.
You may want to rebuild the project to get all the files re-parsed after a large change, or if you suspect the project data is not correct.
A project may become corrupted if Source Insight was abnormally aborted without closing the project.
The Rebuild Project dialog box also lists some statistics about your project. The number of symbol database records, symbol index entries, and files is displayed. This information is also output by the Project Report command.
There are three methods of rebuilding the project. The last method is recommended.
Re-Parse all source files
This simply scans all the files in the project, and re-parses them to update the symbol database. This is the slowest method. However, if you cancel the operation, the symbol database will be left intact, although it may be slightly out of date. If you cancel, you can continue to edit normally and the re-parsing will continue in the background. The symbol database will be at least as current as it was when you began the rebuild process.
Fix database file corruption, if any
This option scans the databases and ensures that the databases are in a legal, self-consistent state. However, some files or symbols may be missing from the databases after the rebuild is complete if you recently added or removed files from your project. This is the fast method. You should use this command if you suspect that your project is corrupted. Normally, Source Insight can detect if a project was not closed properly when it tries to open the project. If Source Insight detects that the project is corrupt, it will ask you if you want to rebuild the project. Source Insight will not knowingly allow you to open a corrupted project.
280 Source Insight 4 User Guide
Commands Overview
Re-Create the whole project from scratch (recommended)
This is the most thorough method of rebuilding the project, and it is the recommended method. This deletes all symbolic information about the project, and rescans all the source files to regenerate the symbol database from scratch. It may take more time than the Fix database file corruption method. If you cancel it, the symbol database will be only partly complete. Source Insight will only have knowledge of symbols in the files that have been scanned. The background synchronization will complete the parsing. Alternatively, you can complete the process by using the Project > Synchronize Files command.
Redo
The Redo command reverses the effect of the Undo command. In effect, as you edit, Source Insight makes a list of the changes you've made to each file. The Undo command backs up through that list and the Redo command advances through the list.
You can also use the Redo All command to reverse all the Undo actions.
Source Insight keeps Undo/Redo history for each open file independently.
Redo All
Reverse the effect of all Undo actions. This brings the file all the way back up to date with your last change. It is equivalent to running the Redo command repeatedly until there is nothing left to Redo.
Redraw Screen
The Redraw Screen command redisplays the whole Source Insight screen.
Reform Paragraph
The Reform Paragraph command re-formats the selected paragraph of text so that all the lines in the paragraph are as wide as possible, within the margin width for the current file type.
If you have an insertion point selection, then the enclosing paragraph is reformed. If more than one paragraph is selected, then all the paragraphs in the selection are reformed.
If the first line of the paragraph is indented, then all subsequent lines in each paragraph will be indented by the same amount.
A paragraph of text is assumed a series of lines, bounded by blank lines.
You can specify the margin width in the File Type Options command under the current file's file type.
For example, before running Reform Paragraph:
The quick brown fox jumped over the lazy dog, and other mysterious sentences.
After running Reform Paragraph, the lines are made as wide a possible within the margin.
The quick brown fox jumped over the lazy dog, and other mysterious sentences.
Reformat Source Code Options
This is a code-beautifier feature that reformats source code.
Source Insight’s code formatter works with C/C++, C#, Java and other language files that have similar curlybrace syntax.
Source Insight 4 User Guide 281
Commands Overview
There are several different code formatting presets, and you can save additional presets. A preset is a group of formatting options. For example, there is a K&R preset, and a GNU preset.
To reformat your source code:
1.
Either select a block of code, or leave an insertion point in your file to format the whole file.
2.
3.
Select Tools > Reformat Source Code Options
The Reformat Source Code Options dialog will appear. Select your desired preset and click the For-
mat
button.
The preset you select will become the "current preset". Once selected, you can use the Tools > Reformat
Source Code with xxx Preset
command to reformat your code in one step.
Reformat Source Code Dialog Box
This dialog lists the formatting presets that are defined. To use a preset to format your source code, select the preset and click the Format button. You can also add, delete, import, and export presets.
Format
Click this button to format your source code using the selected preset.
Add / Delete
Click these to add or delete your own presets. The presets that are installed by default cannot be deleted.
282 Source Insight 4 User Guide
Commands Overview
Edit Preset...
Edits the code formatting options for the selected preset.
Import
Imports a single preset from a preset XML file.
Export
Exports the selected preset to a preset XML file.
Export All
Exports the list of presets to a preset XML file.
Restore Defaults
Restores the default presets that are installed with Source Insight.
Format Preset Properties
Each formatting preset contains a group of formatting options. To view and edit a preset's formatting options, click the Properties button in the Reformat Source Code dialog box. The Preset Properties dialog will open.
Source Insight 4 User Guide 283
Commands Overview
Layout and Flow Tab
This tab contains options that control the general flow of source code around control statements and curly braces.
Control Statements Options
Control statements start a new line
Each control statement (i.e. if, while, for, etc.) will start on its own line.
284 Source Insight 4 User Guide
Commands Overview
For example: x = 0; while (x < limit) would be converted to: x = 0; while (x < limit)
Blank line before control statements
A blank line is inserted just above the control statement.
Blank line after control statements
A blank line is inserted after the control statement's block of code.
Keep else-if on same line
The "if" following an "else" will appear on the same line as the "else", instead of breaking the "if" statement onto its own line.
Force single line bodies onto next line
This forces the statement body onto a new line. For example: if (abc) x = 0; would be converted to: if (abc)
x = 0;
Add braces around single statement bodies
A single statement body would be converted to a brace block. For example: if (abc)
x = 0; would be converted to: if (abc)
{
x = 0;
}
Space after keywords: if, while, for, etc.
Control keywords such as if, while, for, etc. are followed by a single space.
Source Insight 4 User Guide 285
Commands Overview
Brace Style Options
Open { brace on new line
The open brace will start on its own line. For example: if (abc)
{
If this box is not checked, the output looks like the code below. This is used by the K&R style preset: if (abc) {
Indent the open { brace
Indents the open brace by one indent level (if the open brace is the first character on the line). For example: if (abc)
{
If this box is not checked, the output will look like this: if (abc)
{
Indent the close } brace
Indents the closing } brace by one level. For example: if (abc)
{
x = 0;
} // closing brace is indented
If this box is not checked, then the output will look like this: if (abc)
{
x = 0;
} // closing brace is not indented
Extra indent of statements inside of braces
Adds one more level of indentation to the block of statements inside of the curly braces. For example: if (abc)
{
x = 0; // indented 1 more level inside of braces
y = 1;
}
Outermost braces at column 1
The outer-most open and close curly braces are placed at the far left (column 1). This is used typically for the braces around function or class bodies, even when the inside braces follow different indent rules. For example: void MyFunction()
{ // open brace at column 1
if (abc)
{ // inner braces are still indented according to other options
}
}
Indentation Options
Convert spaces to tabs
Spaces are converted to the equivalent number of tabs, or tabs plus spaces.
Indent width
This is the width in character positions of each indent level. For example, entering 4 would mean that an indent is equivalent to 4 spaces, or 1 tab is the tab width is set to 4.
286 Source Insight 4 User Guide
Commands Overview
Label Indentation Options
Indent with statements
Labels are indented at the same level as the surrounding statements. For example:
label1:
if (abc)
{
label2:
x = 0;
}
At far left edge
Labels are indented all the way to left, regardless of the indentation level of the surrounding statements. For example: label1:
if (abc)
{ label2: // both labels are at column 1
x = 0;
}
Hanging indent
Labels are indented 1 level less than the surrounding code. For example: if (abc)
{ label1:
if (xyz)
{
label2:
x = 0;
}
}
Blank line above labels
Adds a blank line above each label statement. For example:
x = 0;
L1: // label has blank line above it
y = 1;
Blank line below labels
Adds a blank line below each label statement.
Source Insight 4 User Guide 287
Commands Overview
Classes and Comments Tab
This tab contains options that control how classes, structures and comments are formatted.
Classes and Structs Options
Indent members
The members, or the contents of the body of the class or struct is indented by one level. This applies to class, struct, enum, and unions. For example: class MyClass
{
void func1(); // member declaration is indented 1 level
}
Blank line above public/private labels
Labels inside the class declaration, such as private, public, protected, etc. will have a blank line above them.
288 Source Insight 4 User Guide
Commands Overview
Blank line below public/private labels
Labels inside the class declaration, such as private, public, protected, etc. will have a blank line below them.
Source Insight 4 User Guide 289
Commands Overview
Align field members at column #
This aligns the declared names of data members at a particular column. For example: class MyClass
{
alignment here---> <-----
int m1; // m1 and m2 are aligned
int m2;
}
Align bit-field sizes at column #
This aligns the bit field sizes of data members at a particular column. For example: class MyClass
{
alignment here---> <----
int bitfield1 : 8 ; // bit field : are aligned
int bitfield2 : 24;
}
Indent labels for public/private
Indent with statements
Labels are indented at the same level as the surrounding statements. For example: class MyClass
{
public:
int func1();
private:
int func2();
}
At far left edge
Labels are indented all the way to left, regardless of the indentation level of the surrounding statements. For example: class MyClass
{ public:
int func1(); private: // label is always at column 1 even if members are indented
int special_function();
int another_special_function();
int func2();
}
Hanging indent
Labels are indented 1 level less than the surrounding code. For example: class MyClass
{ public:
int func1(); private:
int func2();
class InnerClass
{
public:
int func3();
}
}
Comment Options
290 Source Insight 4 User Guide
Commands Overview
Preserve blank lines in comments
Blank lines completely inside of multi-line comments are preserved. For example:
/*
Description:
The blank line above this line is preserved.
*/
Blank line above comment blocks
This inserts a blank line above a block of statements following comments. This attempts to identify a block of statements that follows one or more comment lines. This presumes the comments are referring to the block of statements that follow it. For example: a = 0;
// Initialize block - some comment before a "block" of statements
// (The blank line above this block is inserted by this formatting option.) s.x = 1; s.y = 14;
Wrap comment line at right margin
Multiline comments are word-wrapped at the right margin. The right margin value is defined by the file type.
See “File Type Options” on page 207.
Source Insight 4 User Guide 291
Commands Overview
For example: right margin ---------------------------->|
/* some really long long long long long
long wordy wordy wordy comment that is
word wrapped at the right margin*/
Preserve text formatting in lines that contain only comments
This preserves extra spaces and tabs inside of comments if the comment is the only thing on the line. This typically preserves the author's intentional formatting of the comment. For example:
/*
Field1 Description
------- -----------
something something else in table format
*/
Align right-hand comments at column #
Aligns comments at the end of a line to a specific column. For example:
alignment here ---> <--x = 0; // right hand comment y = 1; // another right hand comment
Other Options
Indent namespace contents
Indents the contents of a C++ or C# namespace. Everything inside the namespace is nested by one level, so this affects whether that nesting affects the indentation. For example: namespace N1
{
int n1_x;
void n1_func();
}
If this box is not checked, then the formatting would look like this: namespace N1
{ int n1_x; void n1_func();
}
Spacing Options Tab
This tab contains options that control how white space and line space is handled, as well as preprocessor macros.
292 Source Insight 4 User Guide
Commands Overview
White Space Options
Space between function name and parentheses
Adds a space between function names and the open parentheses that follows. For example: myfunction (x) // note the space before the parameter list.
Spaces between function parameters
Adds a space between function parameters. For example: myfunction(x, y, z) // note spaces after commas
Spaces around operators
Adds spaces around binary operators in expressions, such as + and -. Some examples: a + b * c a < b a += b
Source Insight 4 User Guide 293
Commands Overview
If this box is not checked, then the above code would be formatted like this: a+b*c a<b a+=b
Spaces inside parentheses like "( this )"
Adds spaces after the open parentheses, and before the closing parentheses in expressions and function parameter lists. For example: myfunction( a ) if ( x > 0 )
If this box is not checked, then the above code would be formatted like this: myfunction(a) if (x > 0)
Remove extra white space at end of lines
All extra spaces and tabs at the end of lines are stripped.
Align variables at column #
This aligns the declared names of variables at a particular column. For example:
alignment here---> <----int x1; // x1 and x2 are aligned int x2;
Align assignments at column #
This aligns assignment operators at a particular column. For example:
alignment here---> <----int x1 = 0; // x1 and xyz are aligned int xyz = 0;
Line Spacing Options
Preserve blank lines in source
This preserves any completely blank line in the original source. If this box is not checked, then unnecessary blank lines are removed. Some blank lines are automatically inserted by some formatting options.
Blank lines between functions #
Inserts the specified number of blank lines just above function declarations.
294 Source Insight 4 User Guide
Commands Overview
Preprocessor Macros (#defines) Options
Align macro names at column #
This aligns the declared names of preprocessor macros at a particular column. For example:
alignment here---> <-----
#define SUM(a, b) ((a) + (b))
#define ABCD(x) (x)
Align macro values at column #
This aligns the substitution value of preprocessor macros at a particular column. For example:
alignment here---> <-----
#define SUM(a, b) ((a) + (b))
#define ABCD(x) (x)
Align macro continuation \ at column #
This aligns the line-continuation character of preprocessor macros at a particular column. For example:
alignment here---> <-----
#define SUM(a, b) \
((a) + \
(b))
Refresh Relation Window
This command refreshes the Relation Window re-computing its contents.
Normally, the Relation Window updates automatically based on your selection.
If you prefer that the Relation Window not automatically update, you can either lock it with Lock Relation
Window command, or use the Relation Window Properties command to set the "Automatic Symbol Tracking" to "None". Then you can use the Refresh Relation Window command to manually calculate the Relation Window contents.
Source Insight 4 User Guide 295
Commands Overview
Relation Window Graph Options
Displays the graphing properties of the Relation Window. The graphing properties apply when the Relation
Window is in a graph mode, not the outline mode.
Back Color
Click this to select a background color for the graph window.
Graph Layout
Selects the layout mode for the graph. You can choose either top to bottom, or left to right.
Spacing
Type a percentage that represents the scale factor of the inter-node graph spacing. A large percentage value will make the nodes spread out more.
Node Options
Node options control the appearance of node elements in the graph.
Type
Selects the shape of nodes.
Font
Selects the font used inside of each node.
Border, Text, Back Color
Selects the colors used for the node borders, text, and background fill.
296 Source Insight 4 User Guide
Commands Overview
Drop Shadow
Enable this to put a drop shadow on each node.
Shaded
Uses a gradient shading effect to draw the graph nodes.
Connection Line Options
Connection Line options control the way the lines that connect nodes appear.
Type
Selects the style of lines that connect nodes.
•
Direct
Lines are drawn straight between nodes.
•
Orthogonal
Lines are drawn with right angle bends.
•
Splined
Lines are drawn as curves.
Line Color
Selects the color used for connection lines.
Thick Line
Enable this to make connection lines thicker.
Arrows
Enable this to put arrowheads on the connection lines. If the Spacing percentage is small, the arrowheads are omitted due to the lack of inter-node space.
Unique backward line color
Enable this to have reverse flowing lines drawn in a separate color. Use the Backward Line Color button to select the color.
Backward Line Color
Selects the color used for reverse flowing lines.
Relation Window
The Relation Window command shows or hides the Relation Window.
The Relation Window shows the relationship between the currently selected symbol and other things. The
Relation Window can show function call trees, class hierarchies, structure members, reference trees, and more. It can be docked along side your source windows, and it works in the background tracking what you are selecting and showing relationship information automatically.
See “Relation Window” on page 91.
Relation Window Options
The Relation Window Options command is accessed from the Relation Window toolbar or shortcut menu.
You control what relationships are shown from this dialog box, and how the window is displayed.
See “Relation Window” on page 91.
Source Insight 4 User Guide 297
Commands Overview
Relation Window Options Dialog Box
Font…, Text Color…, Back Color…
Click on these to select the font, text color, and background color, respectively, of the Relation Window.
These apply to the outline view only.
Graph…
Click on this button to open the Relation Graph Properties dialog box. From there, you can adjust the options for the graph view of the Relation Window.
Automatic Symbol Tracking
Click the Tracking Options button to control what the Relation Window tracks. It can track the symbol that appears under the cursor, or it can track the enclosing function or data structure where the selection is located.
Automatic Expansion Options
This section specifies how deep the Relation Window should expand automatically. You can override this on an individual basis by right-clicking on a node in the Relation Window and selecting Expand Special.
298 Source Insight 4 User Guide
Commands Overview
Levels
The number of levels to expand below the root node.
Expand duplicate branches
Enable this to expand duplicate child branches, even if they have already been expanded earlier. If this is disabled, then duplicate children are inserted in a collapsed state.
View Relationship Group
This group specifies the relationship expanding rules the Relation Window uses when it tracks symbols of different types.
View Relationship
The relationship shown depends on the type of symbol. You can specify what relationship is shown for different symbol types. For example, you could set the relationship viewed for functions to "Calls", and the relationship viewed for classes to “Inheritance”. Thus, when you select a function, the Relation Window shows a
call tree, and when you select a class name, the Relation Window shows the class inheritance hierarchy. See
“Relationship Rules” on page 299.
Show all references inside each function
In the graph view, when the Relation Window is showing a “references” type of relationship, this option groups multiple references from within the same symbol into a single node. For example, if function B is called three times from inside of function A, then the node for function A will contain three items drawn inside of it to represent the three calls to function B.
Call Graph Filtering
Click this button to use the Call Graph Filter dialog box. This allows you to control what symbols participate
in the call tree calculation. See “Call Graph Filter” on page 300.
Symbol Types
Click this button to view the Symbol Type Filter dialog box. This allows you to filter out specific types of sym-
bols from the Relation Window output. See “Symbol Type Filter” on page 301.
Columns Group
This group specifies what columns should appear in the outline list view. The Relation Window can be sorted by clicking on any column header.
Show file names
Shows the file name column.
Show line numbers
Shows the line number column. In most cases, the line number is where the given symbol is referred to.
Show code metrics
Shows the selected code metrics column. Only one code metrics column is allowed.
Relationship Rules
The relationship shown in the Relation Window depends on the type of symbol. You can specify what relationship is shown for different symbol types. For example, you could set the relationship viewed for functions to "Calls", and the relationship viewed for classes to "Inheritance". Thus, when you select a function, the
Relation Window shows a call tree, and when you select a class name, the Relation Window shows the class inheritance hierarchy.
Source Insight 4 User Guide 299
Commands Overview
Each time the Relation Window expands a symbol to show a new level, the relationship represented by the expansion is based on the type of symbol being expanded. That means each Relation Window has the potential to show multiple relationships. For example, a class might show its contents, which consists of member functions. Each member function might show its references.
The "Type of" Relationship
There is a relationship in the list for Variables that is named "Type of". The "Type of" relationship yields the type of the variable. Then, the relationship rule for Types is applied. It is a kind of indirect relationship.
For example, let's say you set the Variable relationship to "Type of", and the Type relationship to "References". Now when you select a variable of a particular structure or class type, the Relation Window will decode the variable's type, then apply the "References" relationship rule and show the references to the variable's type.
Call Graph Filter
The Call Graph Filtering dialog box allows you to control what symbols participate in the call tree calculation.
Exclusions
This section controls what symbols are filtered out of the call tree.
Exclude Symbols…
Click this button bring up the Exclude Call Graph Symbols list. You can add specific symbols to this list. If a symbol is in the exclusion list, then Source Insight will not expand the symbol in the call graph display.
Exclude C Macros
Check this to omit C function-like macros from the call graph. If this option is off, then function-like macros are expanded in the call graph as though they were an actual function.
Code Metric Filter
This section specifies the code metrics criteria for filtering out symbols. If enabled, symbols will only be included in the call graph is the symbols code metric value is within an acceptable range.
From the Code Metric Filter drop-down list, select the code metric that you want to use as the criteria, or select "None" if you don't want to use this option.
300 Source Insight 4 User Guide
Commands Overview
Minimum value
A symbol must have a code metric value of this or greater to be included.
Maximum value
A symbol must have a code metric value of this or less to be included. If the value is set to –1, then there is no maximum.
Symbol Type Filter
The Symbol Type Filter dialog box appears whenever you ask to specify symbol types to be used to filter an operation or listing.
Symbol Tracking Options
This dialog box displays options that guide what the Relation window will pay attention to.
Automatic Symbol Tracking
As you move your cursor around in a source file, the Relation Window "tracks" the symbol under the cursor, or around the cursor. This group of options tells the Relation Window what to track.
Off
Select this to disable automatic symbol tracking.
Track selected symbol (i.e. under cursor)
Select this to have the Relation Window look up the definition of the symbol currently under the typing cursor.
Track the enclosing function or class
Select this to have the Relation Window show the definition of the function or class that contains the typing cursor. This is useful to have a function definition and formal parameters visible in the Relation Window while you edit the function.
Activate Tracking Group
This group controls when the automatic tracking is activated.
Inside of comments
Select this to have the Relation Window look up symbols when the cursor is inside of comments.
Inside of string constants
Select this to have the Relation Window look up symbols when the cursor is inside of quoted string constants.
Inside all file types
Select this to have the Relation Window look up symbols when the cursor is inside any type of file, not just source code files.
Reload File
Reloads the current file from disk, losing all changes since saving. This has the same effect as closing the file without saving, and then opening the file again. The change history and undo history are also lost.
Source Insight 4 User Guide 301
Commands Overview
Reload Modified Files
This command will check the time stamps on each open file and reload those that have been changed outside of the editor. This only applies to files that were opened with the "Sharing..." option turned on in the
Preferences: Files
dialog box.
You can have this work performed automatically in the background by selecting an option in the Prefer-
ences: Files
dialog box.
Remove File
The Remove File command removes one or more source files from the current project. Note that the actual files are not deleted from the disk, but only removed from the project.
Note:
You can also remove files by using the Project File List window. Select the files in the list, right-click, and select
"Remove File from Project".
File Name
Contains the name of the file to be removed from the project. You can also add a wildcard and press Enter to expand the wildcard into the file list.
File List
Contains a list of all project files in the current working directory. If you select a file from this list box, the file name is loaded into the File Name text box.
Remove
Click this button to remove the selected file from the project. If the File Name text box contains wildcard characters, the wildcards will be expanded and displayed in the File list box, and the dialog box will not be closed.
Select All
Click this button to select all the files contained in the file list.
Remove Dir
Click this button to remove the selected directory contents from the project.
Show Dirs
Click this button to toggle the list contents between showing file names, and showing subdirectory names.
When the subdirectories are shown, this button changes to "Show Files".
Browse
Click this button to bring up the standard Open dialog box, which allows you to browse around your disks.
Add
Click this to go to the Add Files dialog box.
Remove Project
The Remove Project command removes an existing project. When a project is removed, all project data files created by Source Insight are deleted. The Remove Project command will not delete your source files.
Project Name
Add the name of the project you want to remove.
302 Source Insight 4 User Guide
Commands Overview
Project list
Displays a list of all projects opened or created on your computer. Select the project you want to remove here.
Since the process of creating and adding source files to a large project can be somewhat time consuming,
Source Insight confirms that you indeed want to remove the project.
Click No to cancel the Remove Project command. The project will not be removed. If the project you selected to be removed was previously open, then it will be closed at this point.
Click Yes to confirm that you want to remove the project.
Remote Options
The Remote Options dialog box allows you to set options for how Source Insight behaves when used in a Terminal Server or Remote Desktop session. In a Terminal Server session, Source Insight runs on a remote machine, but the desktop is displayed on a local machine.
The settings you make in this dialog box only apply when you run in a Terminal Server or Remote Desktop session.
Remote Session Options
These check boxes disable display behaviors that can be slow if your remote connection is not very fast.
Font Scaling
Sets the percent of overall text scaling in the program. Most text, including source code and lists, are scaled by this percentage.
Rename
The Rename command renames the current file. The file does not have to be saved on disk. If the file is part of the current project, the project is adjusted to reflect the new name. You may also move the file to a new directory with this command, but you cannot move the file to a different drive.
The Rename command does not save the file.
Renumber
The Renumber command reorders numbers found in the current file, or just the current selection. If the selection is extended when the Renumber command is used, then only the selection is processed. If the current selection is an insertion point, then the whole file is processed. Renumber also works on a column selection.
Radix
Select a radio button in this group to specify the radix of the numbers generated by the Renumber command.
Auto
Use the radix of the original number, as determined by Source Insight.
Decimal
Use base 10.
Hex
Use base 16.
Source Insight 4 User Guide 303
Commands Overview
Octal
Use base 8.
Numbers
Specifies what action is to be performed on numbers found in the file. You can add values into the Start at and Offset text boxes in base 10, 8, or 16.
Auto
Replace numbers in ascending order, beginning with the value of the first number found.
Start at
Replace numbers in ascending order, beginning with this value.
Offset
Replace numbers with the same number, plus this value.
Radix Determination
Source Insight determines the radix of a number as follows.
•
If the number begins with 0x then it is assumed hexadecimal.
•
If the number begins with zero and a digit, it is assumed octal.
•
Otherwise, the number is assumed decimal.
Repeat Typing
The Repeat Typing command repeats the last characters you typed. For example, if you select somewhere and type abc, then run Repeat Typing, another abc will be inserted automatically.
Replace
The Replace command performs a search & replace operation on the current file. The search & replace can be done over the whole file, or just the current selection.
Old
Add the old pattern you want to replace in this text box. The pattern can be a regular expression.
New
Add the new pattern that should replace the old one in this text box.
Replace
Click this to begin the replacing operation.
Files
Click this button to transfer to the Replace Files command, where you can perform replacements in multiple files.
Options Group
Case Sensitive
If enabled, Source Insight will only find matches if the case matches exactly.
304 Source Insight 4 User Guide
Commands Overview
Use Regular Expressions
If enabled, the Old and New patterns are assumed to be regular expressions.
Wrap Around
If enabled, the search continues at the beginning of the file when it reaches the end of the file. The search will wrap around only once. If not enabled, the search stops when it reaches the end of the file.
One Occurrence / Line
If enabled, only the first occurrence of the Old pattern on each line is replaced. If not enabled, then all occurrences of the Old pattern on each line are replaced.
Whole Words Only
If enabled, then Source Insight only finds matches that are whole words. If not enabled, then Source Insight will also find matches that are embedded in words.
Preserve Old Case
If enabled, then Source Insight will replace text but retain the upper and lower case of the original text. If not enabled, then Source Insight will replace text using the case exactly as it appears in the New text box. This option is most useful when Case Sensitive is off.
This feature lets you replace all occurrences of a word, regardless of case, and still maintain the original case.
For example, let's say you want to replace all "abc" and "ABC" with "xyz" and "XYZ" respectively. Add "abc" in the Old text box, add "xyz" in the New text box. Disable Case Sensitive, and enable Preserve Old Case.
Confirm Replacements
If enabled, Source Insight will confirm each replacement by prompting you.
Search Group
The Search group of options specifies the scope of the search.
Selection
Searches only the currently selected text. This check box is automatically checked if the current selection is extended when the Replace command is invoked.
Whole File
Searches the whole file, from the first line to the last. This check box is automatically checked if the current selection is an insertion point when the Replace command is invoked.
Nothing checked in this group means to start searching at the current selection, and continue to the end of the file.
Replace Files
The Replace Files command searches for a specified pattern in multiple files and replaces each occurrence with a new pattern.
Replace
Click this button to begin the replace operation.
Select All
Click this to select all the files in the file list.
Show Dirs
Click this button to toggle the file list contents between showing file names, and showing only subdirectory names. When the subdirectories are shown, this button changes to "Show Files".
Source Insight 4 User Guide 305
Commands Overview
Old
Add the old pattern to be found and replaced in this text box. The pattern can be a regular expression.
New
Add the new pattern that should replace the old one in this text box.
File Name
The name of the file to search. You may also add a series of wildcard specifications and click the Replace button (or press Enter) and Source Insight will replace the file list with the results of the wildcard expansion. If the Project Wide option is on, the wildcards are expanded over the whole list of files in the current project; otherwise, the wildcards are expanded in the current directory.
If the Project Wide option is on, Source Insight will search the project symbol for file names added in the File
Name text box, so you don't have to include a directory specification for those files.
File list
If the Project Wide option is on, then this list displays all files in the current project.
If the Project Wide option is off, then this list displays all the files in the current working directory. The current directory path is displayed above the file list. Source Insight shows only files for known file types in the current directory. The file types are specified with the File Type Options command.
Options Group
Project Wide
This check box controls whether the File list shows all the files in the project, or just the files in the current working directory.
Include Subdirectories
If this check box is checked, then any selected directories are recursively searched. This option and the Project Wide option are mutually exclusive.
To recursively search a set of directories:
1.
Uncheck the Project Wide check box.
2.
3.
Check the Include Subdirectories check box.
Select one or more directories in the file list.
You can also type a file wildcard specification in the File Name text box to limit the search to particular file extensions or names.
Case Sensitive
If enabled, Source Insight will only find matches if the case matches exactly
Use Regular Expressions
If enabled, the Old and New patterns are assumed to be regular expressions.
One Occurrence / Line
If enabled, only the first occurrence of the Old pattern on each line is replaced. If not enabled, then all occurrences of the Old pattern on each line are replaced.
Whole Words Only
If enabled, then Source Insight only finds matches that are whole words. If not enabled, then Source Insight will also find matches that are embedded in words.
306 Source Insight 4 User Guide
Commands Overview
Skip Inactive Code
If enabled, then only code that is active under conditional compilation is searched. You must first specify known conditions in the Preferences: Languages dialog box, in order for Source Insight to know what conditions are active or not. Conditional compilation only applies to some languages.
Skip Comments
If enabled, then comments will not be searched.
Search Only Comments
If enabled, then only comments will be searched. This is mutually exclusive with the Skip Comments option.
The comment options slow the search down a little.
Preserve Old Case
If enabled, then Source Insight will replace text but retain the upper and lower case of the original text. If not enabled, then Source Insight will replace text using the case exactly as it appears in the New text box. This option is most useful when Case Sensitive is off.
This feature lets you replace all occurrences of a word, regardless of case, and still maintain the original case.
For example, let's say you want to replace all "abc" and "ABC" with "xyz" and "XYZ" respectively. Add "abc" in the Old text box, add "xyz" in the New text box. Disable Case Sensitive, and enable Preserve Old Case.
Confirm Each Replacement
If enabled, Source Insight will confirm each replacement by prompting you.
Confirm Each File
If enabled, Source Insight will confirm each modified file by prompting you.
Include Read-Only Files (keep buffers open)
If enabled, then replacements will be made inside of read-only file buffers. Source Insight will not attempt to save the file as the replacement operation progresses. The files will be left open and modified, allowing you to save the files yourself. If not enabled, then read-only files will be skipped. Note that this options works independently from the Preferences: Files option Allow editing read-only file buffers.
You can make Source Insight automatically save over read-only files while replacing if you enable the Preferences: Files option: Save over read-only files without prompting.
Restore File
The Restore File command restores the current file to its original contents, as it was when it was first opened.
Reverting will lose all changes you made since it was first opened, even if you saved the file. The file that is saved on disk is not altered. Only the open file buffer is restored.
You should use caution with this command, since it effectively undoes any saving you performed on the file.
Note that you can use the Undo command to undo the Restore File operation.
Source Insight 4 User Guide 307
Commands Overview
Restore Lines
The Restore Lines command restores a block of edited lines back to their original contents. The lines will be as they were when you first opened the file.
Restoring lines will lose those changes you made since it was first opened, even if you saved the file. The file that is saved on disk is not altered. Only the lines in the open file buffer are restored.
The Restore Line command is undo-able. This gives you a powerful, out-of-order undo capability.
You can access the Restore Lines command quickly by right-clicking in the selection bar (left margin) area next to a block of modified lines and choosing it from the right-click menu. You can see what lines are modified by turning on line revision marks. (See Preferences: Display command.)
Save
The Save command saves the current file to disk. The file is saved to its current name. Prior to saving, any changes you made to the current file were only present in the unsaved version you were editing. The file on disk never is changed until you save the file by using the Save, Save As, or Save All commands.
A file can also be saved by answering "Yes" to the "Save changes to file?" message when you try to close a changed file.
If the file is new and has never been saved before, or the file is read-only, then the Save command runs the
Save As command instead. The Save As command allows you to specify the name of the file to be saved.
Save A Copy
Saves the current file to a new file, but does not replace or affect the current file. The newly saved file is left open as just another file buffer. This is a handy way to duplicate a file.
308 Source Insight 4 User Guide
Commands Overview
Save All
The Save All command saves all files that are open and have changed since they were saved last.
Save Modified Files Dialog Box
All files that require saving will appear in the Save Modified Files dialog box. Select the files to be saved here and click OK. This dialog box also appears if you use the Close All command, or exit Source Insight when files require saving.
Saving Without Prompts
If you want Source Insight to just save all files without showing the Save Modified Files dialog box, then select
Options > Preferences: Files
and select the check box that says "Save All operation saves without prompts".
Saving When You Switch to Another Program
To make Source Insight automatically saving modified files when you switch to a different program, select
Options > Preferences: Files
dialog box and select the check box that says "Save all files when Source Insight program is deactivated".
Prompting for Each File Separately
If you want Source Insight to prompt for each file using a separate "Yes, No, Cancel" message, then select
Options > Preferences: Files
dialog box and select the check box that says "Save All operation will query on each file separately".
For each file that has changed and requires saving, a dialog box is presented.
Yes
Click this button to save the file.
No
Click this button to not save the file, and to continue
Cancel
Click this button to stop the Save All command.
Save All Quietly
The Save All Quietly command saves all files that are open and have changed since they were saved last.
Source Insight will not ask you if want to save each file; they will be saved automatically.
Save As
The Save As command saves the current file to disk as the name that you specify.
Adding a New File to the Current Project
If the file being saved is a new file that hasn't been saved before and you have a project open, then Source
Insight will ask if you if you want to add the file to the current project.
Yes
Click to add the file to the current project.
No
Click to not add the file to the current project. The file will still be saved.
Source Insight 4 User Guide 309
Commands Overview
Save Configuration
The Save Configuration command saves your current program customizations and settings to a new configu-
ration file. You can save the entire current configuration to a file, or just a subset of it. See “Customized Settings and Configurations” on page 133.
When a configuration file is loaded that contains a configuration subset, it only affects the settings it contains. For example, you could save only keyboard settings to a configuration file and name it "MyKeyboard".
When "MyKeyboard" is loaded, it will only affect the keyboard.
Configuration Sections
Check the sections of the configuration you want to save. Click the All button to check all the sections.
OK
Displays the standard Save dialog box. You can select the configuration file you want to save to with this dialog box.
Having Multiple Configurations
You can keep several favorite configurations. After setting up the current configuration the way you like it in
Source Insight, use the Save Configuration command to save each configuration to a different file. When you want to change configurations, use the Load Configuration command and specify the name of the configuration file you want to open. When the configuration file is opened, it replaces the current configuration.
Note:
Once you load a configuration file, it will be automatically saved to the current configuration file. By default, that file is config_all.xml in your Source Insight\Settings user directory. Make sure you make a backup of config_all.xml if you want to keep it!
See “Load Configuration” on page 245.
310 Source Insight 4 User Guide
Commands Overview
Save Layout
This saves the current window panel arrangement to a layout file. There are four buttons to quickly save to layouts A - D. These save into files named "layout_a.xml", "layout_b.xml", etc..
To save to more than the four special layout slots, click the Other button.
You load the layouts by using the Load Layout command, or the corresponding Load Layout buttons on the
layout toolbar. See “Load Layout” on page 247.
Save 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 259.
Save Selection
The Save Selection command saves the currently selected text to a new file. The new file will remain open.
The file may be a new file, or an already existing file. The file may also be a file that is already open in Source
Insight. If the file is already open, then Source Insight will ask if you want to replace the file with the new text, or append the new text to the file.
Save Settings
(On the Symbol Window right-click menu.)
This makes the current settings of the window become the new Default settings for new windows.
For the Symbol Window, this records the window's width, symbol sorting, and symbol type filtering and uses those parameters as the new default for new windows created subsequently.
Source Insight 4 User Guide 311
Commands Overview
Save Workspace
The Save Workspace command saves the current workspace to a new workspace file.
The workspace contains your session information, such as the names of the files and file windows you have open.
The current workspace is automatically saved for you when you exit Source Insight, and reloaded the next time you run Source Insight.
Working With Multiple Workspaces
If you find that you work with sets of files, rather than individual files, you can save each set of files to a different workspace file. When you want to change to another set of files, use the Open command and specify the name of the workspace file you want to open. When the workspace file is opened, it replaces the current workspace. In other words, all files are closed, and the files in the new workspace are opened.
Scroll Bar Options
This dialog sets the scroll bar options. The scroll bar can displays information about the file content inside the scroll bar.
Use enhanced vertical scroll bar
When selected, the vertical scroll bar has additional features. The options below apply only if this option is selected.
312 Source Insight 4 User Guide
Commands Overview
Options
Waveform View
If the Show text contents option is enabled, then the file's contents are displayed symmetrically mirrored around the vertical center of the bar. This sometimes makes the shape of the contents stand out more.
Show symbol boundaries
Shows markers around the boundaries of functions, classes, and other declared blocks.
Show text contents
Shows a miniature version of the file's content inside the scroll bar. The scroll bar shows a "bird's eye" view of the whole file.
Show inactive lines
Inactive code is displayed in gray. Inactive is code is source code that is shown in the Inactive style because it resides inside an inactive preprocessor block, such as inside of a C or C++
#ifdef
block.
Show change marks
Highlights the areas of edited text in the scroll bar. The miniature text appears in yellow.
Show active selection
Repeats the source window's selection inside the scroll bar.
Show bookmarks
Bookmark indicators appear in the scroll bar.
Enable hover messages
When you hover the mouse over the scroll bar, messages will appear to say what function or declared thing is at the mouse position. Also, dragging the "thumb" of the scroll bar will display the function at that current position of the thumb.
Enable scaling handles
Small handles at the top and bottom of the scroll bar thumb will appear. You can scale the window text by dragging the scaling handles up or down. Each source window has its own scaling factor.
Width in percent
This is the width of the scroll bar, expressed as a percentage of the standard scroll bar width. For example, if a standard Windows scroll bar appears 30 pixels wide, then setting this to 100% will make the Source Insight vertical scroll bar the same 30 pixels. Setting this to 200% will make it 60 pixels wide, and so on.
Color Options
This section affects the colors of the scroll bar parts.
Text...
The color of the miniature "text" inside the scroll bar.
Back...
The background color of the scroll bar. If the Color based on window box is checked, then the scroll bar's background color is based on the background color of the source file window.
Markings...
The color of the symbol boundary markings.
Source Insight 4 User Guide 313
Commands Overview
Scroll Half Page Down
The Scroll Half Page Down command scrolls the active window down by half a window in distance.
Scroll Half Page Up
The Scroll Half Page Up command scrolls the active window up by half a window in distance.
Scroll Left
The Scroll Left command scrolls the active window to the left by one tab size.
Scroll Line Down
The Scroll Line Down command scrolls the current window down in the file by one line.
Scroll Line Up
The Scroll Line Up command scrolls the current window up in the file by one line.
Scroll Right
The Scroll Right command scrolls the active window to the right by one tab size.
SDK Help
The SDK Help command takes the word in the current selection and looks it up in the Windows Software
Development Kit help file. For example, if you selected "TextOut" in your program and ran the SDK Help command, a Help window for the TextOut Windows function would open.
You must have a Windows SDK help file installed on your computer to use this.
Any help file for WinHelp 3.1 or greater may be used; it does not have to be an SDK help file. If you often want to perform help lookups from Source Insight using a different help file, that will work just fine.
You can tell Source Insight what WinHelp file to run for the SDK Help command by running the Change the
SDK Help File command.
Search
The Search command searches the current file or selection for a specified pattern.
Find
Add the pattern you want to search for in this text box.
Search
Click this to begin searching.
Cancel
Click this to cancel the command.
Whole File
Click this button to search the whole file, from top to bottom, and place the search results in the Search
Results window.
314 Source Insight 4 User Guide
Commands Overview
Files
Click this button to open the Search Files dialog box, which lets you search across files.
Case Sensitive
Search will only find matches if the case matches exactly.
Use Regular Expressions
The Find pattern is assumed a regular expression. See “Regular Expressions” on page 107.
Wrap Around
If enabled, the search continues at the beginning of the file when it reaches the end of the file. The search will wrap around only once. If not enabled, the search stops when it reaches the end of the file.
Select When Found
If enabled, Source Insight will select any characters that match when a match is found. If not enabled, Source
Insight will put the insertion point before the first character of the matching text.
Whole Words Only
If enabled, then Source Insight only finds matches that are whole words. If not enabled, then Source Insight will also find matches that are embedded in words.
Search Scope
This group of options specifies the scope and the direction of the search.
Forward
Searches forward starting at the current selection. The search is always forward if Selection or Whole File is checked.
Backward
Searches backwards starting at the current selection.
Selection
Searches only the current selection, in the forward direction.
Whole File
Searches the whole file, in the forward direction.
If neither Selection nor Whole File is checked, then the search continues from the current selection point, either forward or backwards through the file.
Search Backward
The Search Backward command searches backward in the current file for the pattern previously searched for. The search pattern is initially added using the Search command dialog box. The search begins at the current insertion point.
Search Backward for Selection
This command searches for the previous occurrence of the first word in the current selection. To use this command, put the insertion point within the word you want to search for and invoke this command. Source
Insight will find the previous occurrence of that word.
Source Insight 4 User Guide 315
Commands Overview
Search Engines
Use this to edit the Internet search engine options used by the Search Web command. Each search engine entry has a web query URL specification that is used to invoke the search. Source Insight substitutes
%S
in the web URL with the search term.
Adding or Editing a Search Engine
Pressing the Add or Edit button opens the property dialog.
The URL query specification should contain a
%S
, which gets substituted with the search term.
Search Files
The Search Files command searches through multiple files. A new Search Results output window is created.
Each time Source Insight finds a matching line in a file, it appends an entry to the Search Results. Each line in the Search Results file can have source links that link the line with the location of the matching text in another file.
316 Source Insight 4 User Guide
Commands Overview
Search
Click this button to begin the searching in the selected files, or the file named in the File Name text box.
Select All
Click to select all the files in the file list.
Browse
Click this button to show the Open File dialog box, so that you can browse your disks to locate a file to be searched. When you select a file in the Open File dialog box, its full path will be placed in the File Name text box.
Find
Type the pattern to be found in this text box. The pattern can be a regular expression.
File Name
The name of the file to search. You may also add a series of wildcard specifications and click the Search button and Source Insight will replace the file list with the results of the wildcard expansion. If the Project Wide option is on, the wildcards are expanded over the whole list of files in the current project; otherwise, the wildcards are expanded in the current directory.
If the Project Wide option is on, Source Insight will search the project symbol for file names added in the File
Name text box, so you don't have to include a directory specification for those files.
File list
If the Project Wide option is on, then this list displays all files in the current project.
If the Project Wide option is off, then this list displays all the files in the current working directory. The current directory path is displayed above the file list. Source Insight shows only files for known file types in the current directory. The file types are specified with the File Type Options command.
Show Dirs
Click this button to toggle the file list contents between showing file names, and showing only subdirectory names. When the subdirectories are shown, this button changes to "Show Files".
Options Group
Project Wide
This check box controls whether the File list shows all the files in the project, or just the files in the current working directory.
Include Subdirectories
If this check box is checked, then any selected directories are recursively searched. This option and the Project Wide option are mutually exclusive.
To recursively search a set of directories:
1.
Uncheck the Project Wide check box.
2.
Check the Include Subdirectories check box.
3.
Select one or more directories in the file list.
You can also type a file wildcard specification in the File Name text box to limit the search to particular file extensions or names.
Case Sensitive
If enabled, Source Insight will only find matches if the case matches exactly.
Source Insight 4 User Guide 317
Commands Overview
Use Regular Expressions
If enabled, the Find pattern is assumed a regular expression. See “Regular Expressions” on page 107.
Find Non-Matching
If enabled, Source Insight will find all lines where the pattern did not match.
Whole Words Only
If enabled, then Source Insight only finds matches that are whole words. If not enabled, then Source Insight will also find matches that are embedded in words.
Skip Inactive Code
If enabled, then only code that is active under conditional compilation is searched. You must first specify known conditions in the Preferences: Languages dialog box, in order for Source Insight to know what conditions are active or not. Conditional compilation only applies to some languages.
Skip Comments
If enabled, then comments will not be searched.
Search Only Comments
If enabled, then only comments will be searched. This is mutually exclusive with the Skip Comments option.
The comment options slow the search down a little.
Search Results
These options affect what appears in the Search Results after the search is completed.
Include in Results...
Click this button to specify what information is included in the Search Results.
To Search a Set of Files
If you add file name wildcards into the File Name text box and click the Search button, the wildcard list will be expanded, and all the files in the file list will be selected automatically. If the Project Wide check box is on, then the wildcards will be expanded over all files in the project.
So, for example, if you wanted to search all .h files in your project, you would add *.h into the File Name text box, press Enter to click the Search button, and click the Search button again to search all the files in the file list. If the Project Wide option is on, Source Insight will fill the file list with all .h files in the project, regardless of what directory they are in.
See “Replace Files” on page 305.
Search Forward
The Search Forward command searches forward in the current file for the pattern previously searched for.
The search pattern is initially added using the Search command or the Search Forward for Selection command. The search begins at the current insertion point.
Search Forward for Selection
This command searches for the next occurrence of the first word in the current selection. To use this command, put the insertion point within the word you want to search for and invoke this command. Source
Insight will find the next occurrence of that word.
318 Source Insight 4 User Guide
Commands Overview
Search List
The Search List command appears on most right-click menus when you click on a list. This allows you to search the list for a string or regular expression.
Tip:
Once the input focus is on a list, you can press F4 to search for the next occurrence.
String to find in the list
Add the string pattern to search for.
Start at beginning
If enabled, then the search starts at the first item in the list. If not enabled, then the search starts just after the selected item in the list.
Match Case
Turn this on to perform a case-sensitive search.
Use Regular Expressions
Turn this on to interpret the search string as a regular expression. See “Regular Expressions” on page 107.
Searching Options
Specifies options for the Search commands.
Ask before replacing old Search Results
You are always prompted as to whether you want to replace or append to the existing Search Results, or to create a new Search Results file.
Always replace old Search Results
Any existing Search Results are thrown out and replaced with the new results.
Always append to old Search Results
The new search results are appended to the end of the current Search Results file as a new results set.
Automatically jump to first result.
When the searching is complete, Source Insight jumps to the first matching result. If disabled, then the first matching result in the Search Results window will be selected.
Automatically load selection into Find pattern.
The word under the cursor is automatically loaded into the Find pattern of the Search dialog boxes. If disabled, then the previous search pattern is preserved.
Reselect original lines after Replace operation.
The original whole-line selection is selected again after the Replace operation completes.
Search Project
Searches for text or keywords across all project files. This command works the same as the Lookup Refer-
ences command. The only difference is that each dialog box has its own persistent state. See “Lookup References” on page 248.
You can also use the Project Search Bar to perform the same type of search. See “Project Search Bar” on page 271.
Source Insight 4 User Guide 319
Commands Overview
Search Project Dialog
For details on the basic options in this dialog, See “Lookup References” on page 248.
Keyword Expressions
A keyword expression search is similar to an Internet search engine query. Source Insight searches the project for occurrences of a set of keywords that appear within a specified number of lines. The Lines of Context text box indicates the maximum distance the keyword terms can be from each other to qualify as a match.
For example, if you typed "cat food", then Source Insight will search for occurrences of "cat" and "food" within X lines of each other.
There is an implicit logical-AND operator between keywords. That is, if you type more than one keyword, the both keywords must be present to qualify as a match. You can include other Boolean operations as well. The following table lists the operators available:
Operator
AND or +
OR
NOT or – or !
=
? "regexp"
Table 4.6: Keyword Search Operators
Example
cat and dog cat or dog
-cat
Action
Both terms must be present.
Either term must be present
The term must not be present
=Betty
? "^Ich"
Case sensitive match
Term is a regular expression
320 Source Insight 4 User Guide
Commands Overview
You can also group expressions using parentheses. For example:
(cat or kitty) and food
(file or buffer) and (save or write) and !error
Word Variations
If you enabled the Find word variations option, then Source Insight will also find different ending forms of the keywords you specified. For example, if you specified the keyword "open", Source Insight will also find
"opens", "opened", and "opening". This has the same effect as typing this expression:
(open or opens or opening)
Word variations are applied to each keyword term. For example, if you specified: save write
Which implies "save" and "write" must be present. With word variations enabled, this search would be equivalent to:
(save or saves or saving) and (write or writes or writing)
Find Word Fragments
If you enabled the Find word fragments option, then Source Insight will search for name or word fragments.
For example, if you specified the keywords " open doc
", Source Insight will match occurrences of identifiers such as
OpenDoc
,
DocumentOpen
,
IsDocthingOpened
, etc.
This is very powerful type of search. If your project uses fairly consistent naming conventions, you can search for combined references to multiple subsystems.
Some examples:
Find String
open ip open doc save remote
Typical Matches
DocOpen, HTMLOpen, FileOpenReadWrite
IpOpen, OpenIp, OpeningIp, IpsecOpen
SaveDocToRemote, IsDocSavedOnRemote
Keyword Search Results
When you perform a keyword search, the Search Results will list blocks of lines that include the keywords together. This gives you a little bit of context around the matches.
Search Results Options
This controls what information is included in the Search Results created by the Search Files, Lookup References, and Search Project commands. Each of those dialog boxes have a button that brings this dialog box up, and each of those dialog boxes have their own separate settings for these options.
Include name of container function or class
The enclosing function or class name of the match is included in the search results.
Include file names
If enabled, then the file name where the match was found is inserted in the search results. If this option is on, and Include line numbers and Include line text are both off, then a file name is inserted in the search results only once if any matches were found in the file. That is, only one match per file is listed in the search results.
Include line numbers
The line number in the file where the match was found is listed in the search results.
Include line text
The source text of the line where the match was found is listed in the search results.
Source Insight 4 User Guide 321
Commands Overview
Create Source Links
If enabled, then source links are also created for each line appended to the search results. Source links allow you to jump between the line in the search results and the line in the file where the match was found. Source
Links are adjusted automatically while you edit, so they maintain their linkage.
If not enabled, then only text is appended to the search results. You may want to turn off this option if you think you will find thousands of matches, since source links take up memory.
Normalize file names
If enabled, then the file names listed in the search results will be normalized. If not enabled, then the file
names listed will be full paths. See “Normalized File Names” on page 40.
Search Web
This command launches your web browser to search for the identifier at the cursor position. You can specify which search engine site to use. The Search Web is on the Search menu, and on the right-click menu. There is also a toolbar button.
Find
Enter the text to find here. The identifier symbol under the cursor is automatically loaded for you.
Search Engine
Choose which search engine to use. The engine you pick is remembered for the next time you use the Search
Web command.
Edit
Press this button to add or change the list of search engines. See “Search Engines” on page 316.
Select All
The Select All command selects all the text in the current file.
Select Block
The Select Block command selects the smallest C block that encloses the current selection. Each time the
Select Block command is used, it selects the next larger C block.
Select Char Left
The Select Char Left command extends the current selection left by one character.
322 Source Insight 4 User Guide
Commands Overview
Select Char Right
The Select Char Right command extends the current selection right by one character.
Select Function or Symbol
The Select Function or Symbol command attempts to select the whole enclosing symbol, such as the enclosing function. You can also invoke this command by double clicking the mouse in the left margin.
Select Line
The Select Line command selects all of the current line.
Select Line Down
The Select Line Down command extends the current selection down by one line.
Select Line Up
The Select Line Up command extends the current selection up by one line.
Select Match
The Select Match command selects up to the matching brace, parentheses, or quote mark. For example, if the insertion point is just before an open brace, this command selects up to and including the closing brace.
Select Next Window
The Select Next Window command changes the active window focus to the next window. This command cycles through all open windows.
If the active window is maximized when this command is used, the next window is shown as maximized also.
Select Paragraph
The Select Paragraph command selects the entire enclosing paragraph. A paragraph of text is assumed to be a series of lines, bounded by blank lines.
Select Sentence
The Select Sentence command selects up to the next period.
Select Symbol
The Select Symbol command selects the entire enclosing symbol. For example, if the current selection is inside of a function, the Select Symbol command selects the whole function, including the lines that precede the function, up to the bottom of the previous symbol.
Select To
The Select To command is used with the mouse to extend an existing selection up to a new point.
Source Insight 4 User Guide 323
Commands Overview
To use this command, point and click the left mouse button while holding down the Shift key. The selection will be extended up to the place you pointed at. If you pointed to a position already within the selection, then the selection will be shrunk to that location.
Select To End Of File
The Select To End Of File command extends the selection from the insertion point to the end of the file.
Select To Top Of File
The Select To Top Of File command extends the selection from the insertion point to the beginning of the file.
Select Word
The Select Word command selects the whole word at the insertion point.
To use this command with the mouse:
Point and click the left mouse button at a word while holding the Ctrl+key down.
The whole word gets selected. Now, while still holding the left button down, you can drag and extend the selection in whole word increments.
Select Word Left
The Select Word Left command extends the selection from the insertion point to the beginning of the current word.
Select Word Right
The Select Word Right command extends the selection from the insertion point to the end of the current word.
Selection History
The Selection History displays a list of places that you have been in the currently open files. The list is sorted such that the first item is the most recent place you have been.
324 Source Insight 4 User Guide
Commands Overview
You can also use the Go Back (Alt+,) and Go Forward (Alt+.) to navigate back and forth like in a web browser.
Position
Displays a list of all selection history positions. Each item in the list shows the file and line number. If the position is within a symbol, the symbol is also shown. For example, if you were inside of a function, then the function name is in the list too.
Go To
Click this button to jump to the selected position.
Setup HTML Help
Use this command to locate the HTML Help file on your disk that will be used by the HTML Help command. If you have Microsoft® MSDN™ or Microsoft® Developer Studio™ tools installed, you will probably want to select the compiled HTML help "collection" file that is the main help file for the developer tools. The file has a .col extension. That will allow you to invoke HTML Help on Windows development APIs from within Source
Insight.
Setup WinHelp File
This command allows you to locate the WinHelp help file on your disk to be used for the SDK Help command.
A system Open File dialog box will appear and allow you to pick the .HLP file to be used.
Show Clipboard
The Show Clipboard command opens a window, which displays the clipboard. You cannot edit or select in the clipboard.
Show File Status
The Show File Status command shows the current file's size in lines and bytes in the status bar. It also shows whether the file has been changed since it was saved last, and if it is read-only.
Source Insight 4 User Guide 325
Commands Overview
Simple Tab
Simple Tab Inserts a regular tab, overriding the Smart Tab mode. This is useful if you have the Smart Tab option enabled. The Smart Tab mode alters the behavior of the regular Tab key. Sometimes, the Smart Tab results in unwanted results. Use the Simple Tab command to just insert a regular tab, without any special effects.
Smart End of Line
Moves the cursor generally to the end of the line. It does one of the following:
•
If the cursor is in the middle of a line, move it to just after the last non-white space character on the line.
•
If the cursor is after the last non-white space character, move it to the actual end of the line.
•
If the cursor is already at the end of the line, move to the end of the file.
Smart Beginning of Line
Moves the cursor generally to the beginning of the current line. It does one of the following:
•
If the cursor is in the middle of a line, move it to just before the first non-white space character on the line.
•
If the cursor is before the first non- white space character on the line, move it to the actual start of the line.
•
If the cursor is already at the start of the line, move to the start of the file.
Smart Rename
Smart Rename will rename a symbol, including its definition and usages, across all project files or within a local function. If the Smart Reference Matching option is enabled, then Smart Rename will rename the symbol only in the correct contexts. It can be used to rename function local variables, class or struct member, and functions.
Smart Rename is a specialized form of a global search & replace. Source Insight uses its symbol database index to make it very fast.
Old Name
Add the name of the identifier to be renamed. The word under the cursor is automatically loaded for you. The position of the cursor is significant because Source Insight will determine exactly which symbol you want to rename, based on the local scope context.
You can add any string into this text box; however, the rename operation is optimized and much faster for single-word strings. Also, if you type anything into this text box, Source Insight will have to re-establish exactly what symbol you are trying to rename, based on the initial cursor position.
If you are renaming a member variable, or a local variable, you will notice that the Old Name text box contains the full symbol name, including the container symbols. For example, it might say "DocDraw.paintStruc", where "DocDraw" is a function name, and "paintStruc" is a local variable. In a sense, "paintStruc" is a member of the "DocDraw" function.
New Name
Add the new name here. For members, you should only add the new member name, and omit the symbol container qualifiers.
326 Source Insight 4 User Guide
Commands Overview
Output Search Results
If enabled, then the results of the search will be output to the Search Results window. This provides you with a log of changes made to each occurrence. The Search Results window will list the text the way it was before the replacement with the New Name string.
Confirm Each Replacement
If enabled, Source Insight will confirm each replacement by prompting you.
Confirm Each File
If enabled, Source Insight will confirm each modified file by prompting you.
Smart Reference Matching
This tells Source Insight to use its language information, and the scope context to determine exactly what symbol is being renamed, and to make sure it only renames strict references to it.
Skip Inactive Code
If enabled, then only code that is active under conditional compilation is searched. You must first specify known conditions in the Preferences: Languages dialog box, in order for Source Insight to know what conditions are active or not. Conditional compilation only applies to some languages.
Skip Comments
If enabled, then symbol references inside comments will not be renamed.
Include Read-Only Files (keep buffers open)
If enabled, then replacements will be made inside of read-only file buffers. Source Insight will not attempt to save the file as the replacement operation progresses. The files will be left open and modified, allowing you to save the files yourself. If not enabled, then read-only files will be skipped. Note that this options works independently from the Preferences: Files option Allow editing read-only file buffers.
You can make Source Insight automatically save over read-only files while renaming if you enable the Preferences: Files option: Save over read-only files without prompting.
Smart Tab
When the Smart Tab command is used at various positions in your source code, Source Insight moves the selection to the next "field". A field is an interesting position, depending on the current context. Smart Tab lets you move the cursor around easily, especially when typing new function calls.
When the Smart Tab option is on (Preferences: Typing), then pressing the regular Tab key will invoke the
Smart Tab command. The Simple Tab command simply inserts a tab, and avoids the Smart Tab behavior.
Therefore, if you have the Smart Tab option turned on, you can use the Simple Tab command to occasionally override the Smart Tab behavior.
Smart Tab Examples
Here are some examples, starting with step 1 as the initial selection state, and steps 2 and later are the new selections after using Smart Tab. The current insertion point is marked by ^ and a selected range of text is underlined like this:
Source Insight 4 User Guide 327
Commands Overview
Example 1:
1. Beg^inPaint(hwnd, pps);
2. BeginPaint(hwnd, pps);
Example 2:
1. BeginPaint^(hwnd, pps);
2. BeginPaint(hwnd, pps);
3. BeginPaint(hwnd, pps);
4. BeginPaint(hwnd, pps^);
5. BeginPaint(hwnd, pps)^;
Example 3:
1. ResetAbc(^)
2. ResetAbc()^
Smart Tab works like a regular tab when you use it at the beginning or end of line text, or on a line that doesn't have a function call.
The Smart Tab works well with auto-completion of function calls. When you insert a function call via the popup auto-completion window, the function's parameter types and names are also inserted, and the first parameter is selected. You only have to start typing over the first parameter, then press Smart Tab to select the next parameter.
328 Source Insight 4 User Guide
Commands Overview
Snippet Properties
This window is used to edit the contents of a code snippet located in the Snippet Window. See “Code Snippets” on page 96.
Name
The name of the snippet. This is the name that will appear in the auto-completion list as you type.
Description
This should contain a short description of the snippet. If you leave this blank, Source Insight will use a portion of the snippet’s body text as the description.
Storage Location
This determines whether the snippet belongs to the current project, or is common to all projects (Global).
Note that changing this setting will cause the snippet to be saved to the new location, and removed from the old location.
Source Insight 4 User Guide 329
Commands Overview
Include in auto-completion list as you type
Select this to include this particular snippet in the auto-completion list as you type in the editor.
Enable text variables when inserting
Select this to enable text variables to be automatically replaced with their values when you insert this particular snippet.
Insert onto a new line
Select this to cause the snippet to be inserted onto a new line, instead of in-line. This is appropriate for many statement snippets, such as "while" or "for". The current auto-indenting mode will apply when inserting onto a new line.
Language Context
Specifies from what programming language files this snippet should be available. For example, you can have a snippet that is only applicable in Java. The auto-completion list will only include snippets that are applicable to the language type of the current file.
Body Text
This is the contents of the snippet. This is a mini-editor window where you can type and edit the snippet text.
The snippet is inserted just as you enter it here.
You can use text variables within the snippet body. The Insert Text Variable list contains all the predefined text variables you can enter.
You can also simply type any text variable in, including any variable you want to use as a placeholder when inserting the snippet.
Insert Text Variable
This is a list of all the predefined text variables. Select an item from this list to insert the text variable into the body text of the snippet.
Snippet Window
The Snippet Window lists all code snippets. From this window, you can create, edit, delete, and insert code
snippets. See “Code Snippets” on page 96.
To insert a snippet into the current file, type the name of the snippet and press Enter. You can activate the
Snippet Window first by using the Activate Snippet Window command (Ctrl+Alt+S).
New Snippet (Ctrl+N)
Creates a new snippet. The Snippet Properties window will open so you can edit the new snippet.
330 Source Insight 4 User Guide
Commands Overview
Delete Snippet (Ctrl+X)
Delete the selected snippets.
Edit Snippet Text in Editor
Opens the selected snippet in a source file window so that you can edit it. To save it back into the Snippet
Window, use File > Save. To stop editing the snippet, use File > Close.
Edit Snippet (Ctrl+E)
Opens the Snippet Properties window so that you can edit the snippet. See “Snippet Properties” on page 329.
Load Snippets (Ctrl+O)
Imports snippets from a snippet file. The snippets are merged with the current list. If a loaded snippet matches the name of an existing snippet, the existing snippet is replaced with the loaded version.
Save Snippets (Ctrl+S)
Saves the selected snippets to a new snippet file.
Snippet Window Options (Ctrl+Q)
Edits the options for the Snippet Window, and also for snippets in general. See “Snippet Window Options” on page 331.
Snippet Window Options
This is used to edit the options for the Snippet Window, and for snippets in general. See “Code Snippets” on page 96.
Source Insight 4 User Guide 331
Commands Overview
List Columns
Select the columns you want to include in the Snippet Window.
List Contents
Select the type of snippets you want to include in the Snippet Window.
Snippet Options
Confirm when deleting snippets
Select this to be prompted before deleting any snippets in the Snippet Window.
Propose snippets in auto-completion as you type
Select this to include snippets in the auto-completion list as you type in the editor. If you disable this option, you can explicitly complete snippets using the Complete Snippets command (Ctrl+E)
Note you can also set this option on a per-snippet basis in the Snippet Properties window. See “Snippet
Properties” on page 329.
Enable text variables when inserting snippet
Select this to enable text variables to be automatically replaced with their values when you insert snippets.
Note you can also set this option on a per-snippet basis in the Snippet Properties window. See “Snippet
Properties” on page 329.
Sort Symbol Window
The Sort Symbol Window command cycles the sorting state of the symbol window in the current file window.
You can sort it by:
•
Name.
•
Line number (the default).
•
Type + Name.
Sort Symbols By Line
Sorts the symbol entries listed in the Symbol Window by line number. Each symbol in the file will appear in the list in the order of occurrence.
By default, the Symbol Window is sorted by line number (occurrence).
If you want all Symbol Windows to be sorted this way by default, then right-click on the Symbol Window and select Save Settings on the Symbol Window's right-click shortcut menu.
Sort Symbols by Name
Sorts the symbol entries listed in the Symbol Window alphabetically by symbol name.
By default, the Symbol Window is sorted by line number (occurrence).
If you want all Symbol Windows to be sorted this way by default, then right-click on the Symbol Window and select Save Settings on the Symbol Window's right-click shortcut menu.
Sort Symbols By Type
Sorts the symbol entries listed in the Symbol Window by symbol type. For example, all structs will appear together, followed by all functions, etc.
By default, the Symbol Window is sorted by line number (occurrence).
332 Source Insight 4 User Guide
Commands Overview
If you want all Symbol Windows to be sorted this way by default, then right-click on the Symbol Window and select Save Settings on the Symbol Window's right-click shortcut menu.
Source Dynamics on the Web
This command opens your web browser and goes to the Source Dynamics web site.
Start Recording
The Start Recording command turns on the command recorder. While recording, any command you run will also be recorded. This allows you to record a single series of commands, which can be played back with the
Play Recording command.
To stop recording, use the Stop Recording command, or just play the recording back with the Play Recording command.
You can keep only one recording at a time. The recording is saved with the workspace.
Stop Recording
The Stop Recording commands turns off the command recorder. The Start Recording command is used to start the recorder. The command recorder allows you to record a single series of commands, which can be played back with the Play Recording command.
Style Properties
This command allows you to set formatting properties for display styles. For more information about how
styles work, see “Syntax Formatting and Styles” on page 76.
Formatting Properties
Each style has a number of formatting properties. Because styles exist in a hierarchy, each formatting property is combined with the parent style to yield a final result.
For example, if bold = "ON", then bold formatting is added. If bold = "OFF", then bold formatted is subtracted from the parent style properties.
Many formatting controls in this dialog box show one of these values:
•
On – the property is added to the parent style formatting.
•
Off – the property is deleted from the parent style formatting.
•
A Number – the value replaces the parent style property.
•
= (equal) - the property has no effect, and it inherits the exact same value as in the parent style.
Source Insight 4 User Guide 333
Commands Overview
Style Properties Dialog Box
Style Name list
Lists all the syntax formatting styles. When you select a style in this list, its properties are loaded into the controls to the right. A sample of the style is also displayed in the sample box. The list depicts the style hierarchy.
Each style has a parent style and inherits its properties from the parent.
Parent Style
This is the parent style in the style hierarchy. The current style inherits its formatting from the parent style.
The style list depicts the style hierarchy. Any property that is other than "equal" (meaning "the same") is combined with the parent style formatting.
Add Style
Click this button to add a new user-defined style.
Delete Style
Click this button to delete a user-defined style. The standard built-in styles cannot be deleted.
Load…
Click this button to load a new style sheet from a configuration file.
Save
Click this button to save the current style sheet settings to a new style configuration file. The file will contain only style properties, and won't contain other elements that can be stored in a configuration file. If you load this configuration file, only the style properties are loaded.
334 Source Insight 4 User Guide
Commands Overview
Reset…
Click this button to reset all the styles to the factory defaults. This loses all your changes since installing
Source Insight.
Font Options
Font Name
Indicates the font currently selected.
Size
Selects the font size, specifically as a point size. You may find the relative Scale property more useful, since it is relative, and works well regardless of changes to the parent styles.
Scale
Specifies the font size scaling as a percentage of the parent style's font size. For example, if the scale is 50%, then it will be half the size of whatever the parent style font size is.
Bold
Selects the bold property of the style, if any.
Italic
Selects the italic property of the style, if any.
Underline
Selects the underline property of the style, if any.
All Caps
Selects the All Caps (capitalization) property of the style.
Strike-Thru
Selects the Strike-Thru property of the current style.
Colors Options
Foreground
Selects the foreground color of the current style.
Background
Selects the background color of the current style.
Shadow
Selects the color of the drop-shadow of the current style.
Inverse
Selects the Inverse property of the current style. Inverse means that the foreground and background colors are reversed.
Spacing Options
Above Line
This selects the percentage of vertical spacing to add above the line.
Source Insight 4 User Guide 335
Commands Overview
Below Line
This selects the percentage of vertical spacing to add below the line.
Expanded
This selects the percentage of horizontal spacing to add to characters.
Fixed White Space
This option only applies if you have selected a proportionally spaced font. Fixed-pitch fonts, such as Courier
New, are not affected. If enabled, Source Insight will attempt to use a fixed width for spaces and tabs so that tabs line up the same way they do with a fixed-pitch font. Programs generally look better with this turned on
if you are using a proportional font. See “Character Spacing Options” on page 192.
Print together with next line
If enabled, Source Insight will try to keep the text on the same page as the following line, when printing.
Symbol Info
The Symbol Info command displays a pop-up window showing the definition of the symbol under the cursor.
This is a quick way to check the definition of an identifier.
Symbol Name, Type, and Location
The symbol's name, type, and location are displayed at the top of the window.
Source File
The source file name and line number where the symbol is defined are displayed at the top left of the dialog box below the symbol name. If known, the symbol's size in lines is displayed also.
Text Window
This scrollable window contains the contents of the source file where the symbol is defined.
Close
Click this to close the window.
Jump
Click this to close the Symbol Info window and jump to the symbol definition directly.
References
Click this button to search for references in the whole project to the symbol.
Leave File Open
Click this button to leave the file displayed in the list box open. This button is disabled if the file is already open. If you leave the file open, you can select the file name from Window menu after the window closes.
336 Source Insight 4 User Guide
Commands Overview
Symbol Lookup Options
Sets options for the way Source Insight looks up symbol definitions. This command activates the Symbol
Lookups page of the Preferences dialog box.
Parse locally before lookup
Source Insight will ensure that the symbolic information for the current file is completely up-to-date before trying to lookup a symbol. This option comes into play when you are editing. Every time you type a character,
Source Insight considers the symbol data for the file to be stale. If this option is enabled, then the file will be parsed after you type anything. If the option is disabled, then Source Insight will use the possibly stale symbol data for the current file. Enabling this option will make the symbol lookups more accurate, but it is slower. It will also cause the auto-completion window to appear slower. Most of the time, lookups work fine when this option is turned off.
Source Insight 4 User Guide 337
Commands Overview
Find symbols across different language types
If enabled, then Source Insight will lookup symbol definitions in any language, regardless of the source language. If unchecked (the default) then only symbols that are defined in the same language will be found.
Find symbols in open files not part of the current project
Symbols will be found in both the current project, and in any open files. It will find symbols in open files that are not part of the project. If this box is not checked, then only the current project and its files are searched.
Search symbol path if symbol is not found
If a symbol cannot be found in the current project, or any open file, then Source Insight will search the projects listed in the project symbol path. If it does search the symbol path, then it searches through all projects in the symbol path.
Search symbol path, even if symbol is found in current project
When enabled, all projects in the symbol path are searched every time Source Insight looks up a symbol, even if the symbol was already found in either an open file or the current project. This is sometimes useful if you are working on an alternate version of a project, with many of the same symbol names. Looking up a particular symbol in the current project will also show matches in the other projects on the symbol path.
If disabled, then Source Insight will only search the symbol path if a symbol was not already found in either an open file or the current project.
Project symbol path
The project symbol path is a delimited list of projects that Source Insight will search through when looking up a symbol. The project symbol path enables you to create smaller, self-contained projects, but still have the ability to locate symbols in other projects.
Each item in this list should be a full path name of a project. Project paths should be separated by a semicolon. Remember to include the name of the project file in addition to the directory it is in.
Example: c:\include\include;c:\windev\include\include
The project symbol path is only used for locating the definitions of symbols external to the current project. It is not used for finding references to symbols, or for searching across multiple projects.
Note:
The
Project > Import External Symbols
command is a more powerful way to refer to symbols in external
sources, such as assemblies, header file libraries, and other Source Insight projects. See “Import External Symbols” on page 227.
Add to Project Path…
Click this button to pick a project to append to the exiting project symbol path.
Import Symbols for All Projects
Click this to import symbol information from external files and projects. The imported symbols are used by
all projects. See “Import External Symbols” on page 227.
Import Symbols in Current Project
Click this to import symbol information into the current project from external files and projects . See “Import
External Symbols for Current Project” on page 230.
338 Source Insight 4 User Guide
Commands Overview
Symbol Type Filter
This allows you edit the filter used to filter out symbol types. Various option settings in Source Insight allow filtering by symbol type. This dialog is used to set the filtering. Check mark the symbol types you want to include in the filter.
Symbol Window command
The Symbol Window command opens and closes the symbol window pane at the left of the current file window.
Source Insight 4 User Guide 339
Commands Overview
The symbol window shows a list of symbols defined in the file. The symbol window is only available if the file
type has a parsed language selected. See “Symbol Windows ” on page 28.
Figure 4.3 The Symbol Window pane appears at the left of each source window and lists all the declarations in that file.
The symbol window can be sorted by using the Sort Symbol Window command, or by clicking the three sorting buttons in the toolbar at the bottom of the window.
Click the gear button to select the Symbol Window options. You can also invoke the Symbol Window Options
command directly by mapping a key to it. See “Symbol Window Options” on page 341.
340 Source Insight 4 User Guide
Commands Overview
Symbol Window Options
Displays the properties of the Symbol Window, which appears on the left of each source window. See “Symbol Window Options” on page 341.
Show class members
If enabled, the member contents of classes are included in the Symbol Window. If unchecked, then only the class name is included in the list.
Show structure members
If enabled, then the structure field members are included in the Symbol Window. If not enabled, then only the structure name is included in the list.
Show enum constants
Includes enum constants in the Symbol Window. If not enabled, then only the enum type name will appear in the list.
Show local definitions
If enabled, then function local declarations are also shown in the Symbol Window under each function.
Show edited symbols
Function names and other symbol names will appear highlighted if you made any edits in them.
Apply Now
Applies the changes you made in this dialog box to the Symbol Window.
Symbol Types…
Click this button to open the Symbol Type dialog box, where you can filter out different types of symbols from the Symbol Window.
Font…
Click this button to pick the font used to draw the Symbol Window.
Text Color…
Click this button to pick the color of the text in the Symbol Window.
Source Insight 4 User Guide 341
Commands Overview
Back Color…
Click this button to pick the background color of the Symbol Window.
Sync File Windows
The Sync File Windows command scrolls all windows showing the current file to same location as the current window.
Synchronize Files
The Synchronize Files command synchronizes the current project with all the source files in the project. The command scans each file in the project and updates the symbol database for each file that has been modified since Source Insight parsed the file last. In addition, files that were part of the project that don't exist anymore are removed from the project.
You normally do not need to run this command because Source Insight scans your source files in the background by default. You can control the background synchronization by selecting Options > Preferences: Gen-
eral
.
Force all files to be re-parsed
If enabled, then Source Insight will ignore file time-stamps and consider all files in the project to be out of date. It will update the symbol database for all files. This provides an easy and relatively quick way to completely rebuild Source Insight's project data files.
If not enabled, then only those files in the project that are considered out of date are updated.
Synchronize the current source file only
Only the currently active source file is synchronized with the symbol database. This has the effect of replacing all symbol database information known for the current source file.
Add new files automatically
Before synchronizing all the files, Source Insight will add new files in the project's source directory and in all subdirectories, recursively. However, only directories that already have project files in them are scanned.
Directories that are not descendants of the project source directory are not scanned. This feature allows you to add new files to your project directories, and then run the Synchronize Files to add those new files to your
Source Insight project automatically.
You can also use a Master File List in your project to control which files are in your project. Use the Project >
Project Settings
command to specify the Master File List. See “Using a Master File List” on page 44.
342 Source Insight 4 User Guide
Commands Overview
Remove missing files from project
Any files that are now missing are removed from the project.
You can also use a Master File List in your project to control which files are in your project. Use the Project >
Project Settings
command to specify the Master File List. See “Using a Master File List” on page 44.
Syntax Decorations
This command specifies syntax decoration options for displaying source files. It activates the Syntax Decorations page of the Options > Preferences dialog box.
Source Insight can replace some common operators with more useful symbolic characters. The Syntax Deco-
rations command lets you control which decorations are used. See “Syntax Decorations” on page 85.
Source Insight 4 User Guide 343
Commands Overview
It's important to remember that symbol decorations and substitutions do not change the text in the source file; only its representation on the screen changes to show the special symbols. You still need to type the operators normally when editing your code, or when searching for them.
Display Substitutions
This group of options controls which operators are substituted with special symbols.
User special operator symbol substitutions
This enables or disables the whole group of operator substitutions that appear below.
344 Source Insight 4 User Guide
Pointer field reference uses right arrow
This replaces the -> pointer operator with an actual arrow like this . For example:
Commands Overview
Not Equal
This replaces the != not equal operator with .
Equal
This replaces the == equal operator with a mathematic EQUIVALENT character.
Less Than or Equal
This replaces the <= operator with .
Greater Than or Equal
This replaces the >= operator with .
Assignment uses left arrow
This replaces the = assignment operator with .
Division
This replaces the / division operator with .
Logical AND
This replaces the && logical And with .
Logical OR
This replaces the || logical Or with .
Scale nested parentheses
Nested parentheses are shown so that outer levels are larger than inner levels. This makes it easier to visually identify matching parentheses.
Auto Annotations
Source Insight can automatically add certain annotations to your source code display. The following options control which annotations appear.
Source Insight 4 User Guide 345
Commands Overview
Show arrows at goto statements
This causes either an up or down arrow symbol to appear in goto statements next to the label name. The arrow indicates whether the indicated label is above or below the goto statement line.
Annotate closing braces with end-comments
This causes end-comment annotations to appear after closing curly braces. The end-comment contains a show description of the start of the block. For example:
Annotate closing braces only for long blocks
This suppresses the auto-annotated end-comments for blocks less than 20 lines tall.
Syntax Formatting
This command specifies syntax formatting options for displaying source files. It activates the Syntax Formatting page of the Options > Preferences dialog box.
Source Insight uses information gathered from its language parsers to format source code. Identifiers can be
displayed in different fonts or font sizes, along with a variety of effects such as bold and italics. See “Syntax
Formatting and Styles” on page 76.
346 Source Insight 4 User Guide
Commands Overview
Formatting is applied using "styles". A style is a set of formatting properties. For example, a style may specify bold + italic. You can edit each style's formatting properties with the Style Properties command.
Styles…
Click to edit the style properties.
File Types…
Click to edit the file types.
Basic Options
Basic option are:
Use Syntax Formatting
Enable this to have Source Insight display source code with syntax formatting. If disabled, then source code will display with no coloring or font changes.
Source Insight 4 User Guide 347
Commands Overview
Use only color formatting
All non-color formatting properties, such as font size changes, or bold and italics, will be suppressed. Display tokens will only contain color changes. This is similar to how earlier versions of Source Insight displayed text.
Use no color formatting (monochrome)
If enabled, then Source Insight will suppress all color changes. Text will be displayed in black and white and gray.
Apply Styles for Language Elements
Source Insight will apply styles to display tokens based on their lexical and contextual meaning. Each option in this group enables successively more elaborate formatting.
Symbol declarations
Declarations of symbols are formatted with the appropriate "Declare…" styles. For example, a function name will appear in the "Declare Function" style where it is declared.
Function-local symbol declarations
Declarations of local function scope variables and other symbols will be formatted with the appropriate
"Declare…" styles. This includes local variables, and function parameters.
References to function-local symbols
References to local function scope variables and symbols are formatted with the appropriate "Ref to…" reference styles. For example, references to (i.e. usages of) a local variable will have the "Ref to Local" style.
References to non-function-local symbols
References to symbols declared outside of function scopes, such as class scopes and the global scope, are formatted with the appropriate "Ref to…" reference styles. This option requires more work, and it will slow down the display somewhat. The reference information is cached, so once a piece of code is rendered, it usually will display quickly afterwards.
References to members
References to structure and class members are formatted with the "Ref to Member" style. The veracity of the member reference can be controlled with the Qualify references to members option.
Special comment styles
Source Insight supports special comment styles that are controlled by special //1-4 comment heading tokens, and the placement of comments. If this option is enabled, then Source Insight will apply the appropriate comment style to those special comments
348 Source Insight 4 User Guide
Commands Overview
Comment Headings
Comment heading styles are comments that begin with a single digit in the range 1 to 4. For example:
//1 This is heading one.
//2 This is heading two.
When the comment styles are used, the //x at the beginning of the comment is hidden, and the heading style formatting is applied to the rest of the line. The result looks like this:
Inactive conditional code blocks
Code contained in inactive conditional code blocks are formatted with the "Inactive Code" style. An inactive code block is one contained in an inactive #ifdef, #if, #elif, or #else branch. You control the state of the conditions with the Edit Condition command.
Symbol Reference Lookups
When a potential reference is encountered, Source Insight must verify that the symbol is declared somewhere. This section controls how Source Insight resolves references to symbols declared in the project, as it renders source code.
Search in the Project Symbol Path
Source Insight will search not only the current project for a declaration, but also all the projects in the Project
Symbol Path.
Qualify references to members
If enabled, Source Insight will verify that the member declaration exists before formatting it with the "Ref to
Member" styles.
If disabled, then Source Insight will format tokens with the "Ref to Member" style if the tokens look syntactically like a member reference. There is no guarantee that the member actually exists. For example:
PtrFoo->somemember // looks like a member reference
FooThing.somemember // looks like a member reference
Qualify references to functions
If enabled, Source Insight will verify that the function declaration exists before formatting it with the "Ref to
Function" or "Ref to Method" styles.
If disabled, then Source Insight will format tokens with the reference styles if the tokens look syntactically like a function call. There is no guarantee that the function actually exists. For example:
SomeFunction(x) // looks like a function reference
Syntax Keyword List
Brings up the Language Keywords dialog box, which lets you edit the language keywords used for syntax for-
matting in the current language. See “Syntax Formatting and Styles” on page 76.
The Language Keywords dialog box lists keywords and styles. The title of the dialog box will specify which language type you are working with. Source Insight uses a very fast hashing technique to maintain large keyword lists and still have outstanding performance.
Source Insight 4 User Guide 349
Commands Overview
Keywords and Styles
The keyword list contains all the language keywords that can be highlighted with syntax formatting. Each keyword in the list is associated with a style name. The Style Properties command is used to set the formatting options of each style.
For example, in the C Language keyword list, the word "NULL" is associated with the "Null Value" style.
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 4.4 The style used for a word in source text is determined by the keyword list of the language of the file type of the file in question.
By having keywords assigned to formatting styles, you are able to change the syntax formatting quickly by simply changing the style with the Style Properties command. Then all language keywords associated with that style reflect the new style formatting.
350 Source Insight 4 User Guide
Language Keywords Dialog box
Commands Overview
Keyword
The keyword list for the language. When you select a keyword from the list, the keyword's associated style is selected in the Style list.
Style
The list of all syntax formatting styles. When you select a style from this list, you are changing the style associated with the keyword selected in the keyword list. You can also double-click on a style name to edit the style.
OK
Click OK to record your changes.
Cancel
Aborts the command and ignores your changes.
Add Word
Click this button to add a new word to the keyword list. You can type any single word that does not include spaces. Source Insight will add the word to the keyword list. After adding the word, make sure you select the style you want it to have.
Delete Word
Click this button to delete the word currently selected in the keyword list.
Import
Click this button to import new keyword list entries from an external text file. See below for more information.
Source Insight 4 User Guide 351
Commands Overview
Export
Click this button to export the keyword list to a text file.
Reset
Click this button to return the language keyword list to the factory default settings.
Importing and Exporting Keyword Lists
The Import and Export buttons in the Language Keyword dialog box allow you to import and export keyword-style associations from and to text files.
The text file should contain keyword, style name pairs; one per line:
<keyword> , <style-name> or
"<keyword>", "<style-name>"
Each keyword should be a single word without white space. The style name should be one of the defined style names that are listed in the Language Keywords style list, or the Style Properties style list. You may enclose the keyword or style name in double quotes.
When importing, duplicate keywords are ignored.
Import Options
When you click the Import button in the Language Keywords dialog box, you will be given the option of either replacing or merging the keyword list.
Replace current keyword list with imported list
Select this if you want to completely replace the keyword list currently loaded with the imported list. even after importing a list, you can still click the Cancel button in the Language Keywords dialog box to ignore the changes you made to the keyword list.
Merge current keyword list with imported list
Select this if you want to merge the imported list with the currently loaded list. Merging means that the imported list will be added to the existing list, and imported keywords will replace like-named keywords in the current list.
Tab Tray
Shows and hides the Tab Tray at the bottom of the main window. The tab tray contains floating panels that have been minimized.
Tabs to Spaces
Converts tabs to the equivalent numbers of space characters.
Tile Horizontal
The Tile Horizontal command arranges all windows so they are not overlapping. The tiling algorithm will attempt to make windows wider than they are tall. This is useful for viewing 2 or more files on top of each other.
Tile One Window
The Tile One Window command minimizes all but the current window. The current window is grown to fill most of the Source Insight window's workspace area.
352 Source Insight 4 User Guide
Commands Overview
Tile Two Windows
The Tile Two Windows command splits the screen into two windows; the first window will contain the current file. The other window will contain the previous current file (i.e. the last file you were viewing). This command is only allowed if two or more windows are open.
Tile Vertical
The Tile Vertical command arranges all windows so they are not overlapping. The tiling algorithm will attempt to make windows taller than they are wide. This is useful for viewing 2 or more files side by side.
Toggle Extend Mode
The Toggle Extend Mode command toggles extend mode on and off. If extend mode is on, then movement commands, such as Cursor Up, Cursor Down, Top of Window, and Go To Line (to name a few), will cause the current selection to be extended to the new location. If extend mode is off, then the movement commands simply put an insertion point at their destination.
Toggle Insert Mode
The Toggle Insert Mode toggles between insertion and overstrike mode. In insertion mode, characters typed will be inserted before the insertion point. In overstrike mode, characters typed will replace characters at the insertion point.
Top of File
The Top of File command moves the insertion point to the first line in the current file.
Top of Window
The Top of Window command moves the insertion point to the first line in the active window.
Touch All Files in Relation
This command is available from the right-click menu of the Relation Window. It touches (i.e. updates the lastwrite timestamp) on all the files currently shown in the Relation Window.
This is useful if you want to cause re-compilation of all the files containing the symbols shown in the Relation
Window. This is especially handy if the Relation Window is showing references.
Source Insight 4 User Guide 353
Commands Overview
Typing Options
This command specifies typing and editing options. It activates the Typing page of the Preferences dialog box.
Source Editing Options
Per File Type...
Opens the File Type Options dialog, which contains more file-type-specific typing and editing options. The
File Type Options for the current source file is automatically selected.
354 Source Insight 4 User Guide
Commands Overview
Highlight matching parentheses while typing
Source Insight will momentarily highlight up to the matching parentheses or brace when you type a closing parentheses or brace. This is useful for seeing that you are matching up your braces and parentheses while typing new source code.
Always use Symbol Windows
Source Insight will automatically attach a symbol window to each new window it opens, if the file is setup to be parsed for symbols in the File Type Options dialog box. Each file type can also control whether it uses a symbol window.
Keep cursor in window when paging up and down
If enabled, then the insertion point cursor will stay visible in the window as you page up and down. If disabled, then the insertion point will remain at its position in the text regardless of how you scroll.
Use block cursor shape
If enabled, then the insertion point cursor will be block shaped instead of an I-beam.
Use Smart Tab for field selections
Causes the regular Tab key to invoke the Smart Tab command. See Smart Tab.
Typing tab indents line, regardless of selection
If enabled, then typing a tab will indent the whole line. Also, the Back Tab command reverses the indent. If not enabled, then typing a tab inserts a tab stop.
Typing tab replaces current selection
If enabled, then inserting a tab will replace any selected text. For example, if you select a word, then type a tab, the tab replaces the word. If not enabled, then the tab is inserted just to the left of the selection. In any case, if one or more whole lines are selected, then the tab key indents the whole lines.
Indent commands effect #-preprocessor statements
If enabled, then the Indent Right and Indent Left commands will indent and outdent lines that start with C preprocessor statements, such as #ifdef. If this is not checked, then indenting has no effect on those lines.
Use intelligent paste
This modifies paste behavior in two ways when you are pasting whole lines of text:
•
If you have an insertion point anywhere on a line, then the pasted whole-lines are inserted above the current line. If the insertion point is at the end of a line, then the new lines are pasted below the current line.
•
The pasted text is automatically indented to match the destination. This works with Paste, Paste Line,
Drag Line Up/Down commands, the Clip Window, and drag and drop.
You also can enable intelligent paste on a per-file type basis in the File Type Options dialog box. See “File
Type Options” on page 207.
Always select pasted text after pasting whole lines
If enabled, then when you paste whole-lines, they are selected after pasting.
After pasting, select:
This indicates where the selection should end up after using a paste command.
Auto Completion Options
This section customizes the way the auto completion feature works.
The auto completion window appears after you type a character. Its purpose is to reduce the number of characters you have to type by automatically providing a list of possible identifiers to insert. The symbols that
Source Insight 4 User Guide 355
Commands Overview
appear in the completion window depend on the context, such as the cursor position, or the type of variable being referred to.
Use automatic symbol completion window
Enables the auto completion window. If this option is disabled, then you can still use auto completion by invoking it manually with the Complete Symbol command.
Use detailed completion window
The auto completion window shows details about functions, such as their parameter lists.
Insert parameters for functions
The parameter list for a function is inserted along with the name of the function. This only happens if there isn't a parenthesized list of parameters already to the right of the insertion point.
Insert spaces between parameters
A space character is inserted between function parameters. If not enabled, then parameters are inserted with no intervening spaces.
Insert space after function name
A space character is inserted after the function name and before the open parentheses.
Use completion window inside comments
Enables the auto completion feature while you are typing into a comment. If this option is disabled, then you can still use auto completion by invoking it manually with the Complete Symbol command.
Use case-sensitive matching
The auto completion window will list only symbol names that match the case as you have typed it. If this option is disabled, then all symbols that match your input, regardless of case, are listed. However, Source
Insight will attempt to select the item that matches the case you typed.
Tab key selects item
If enabled, then pressing the Tab key while the completion window is showing will insert the selected item in the list. If this option is disabled, then a Tab key just inserts a tab. In any case, the Enter key can also be used to insert the selected item.
Propose snippets in auto-completion list
As you type, code snippet names will be proposed in the auto-completion list along with other possible symbol matches.
Browsing in Lists
This section customizes the way that auto completion works while typing in symbol and file lists.
Match name fragments while typing
Enables name fragment matching by default. If this option is disabled, you can still match name fragments by inserting a space character first, followed by your input.
Match members while typing
Class and struct members are matched according to your input. A full symbol name is like a path that starts with the symbol's top-most container. For example, a class member might be named MyClass.member.
356 Source Insight 4 User Guide
Commands Overview
Enabling this option will allow you to just type "member". If disabled, then only full symbol names are matched. You can still use this feature, even if disabled, by prefixing your input with a dot ('.'), like this:
.member
Undo
The Undo command reverses the action of the last editing command in the current file. For example, if you type some new text and perform Undo, the text you typed is removed. Alternatively, if you delete a line and perform Undo, the line reappears.
In effect, as you edit, Source Insight makes a list of the changes you've made to each file. The Undo command backs up through that list and the Redo command advances through the list.
Undo information is saved for each open file independently.
Undoing Cursor Movement
The Undo command does not undo cursor movements, as with some other editors. In Source Insight, the best way to "back up" through the history of cursor movements is to use the Go Back command (and conversely, the Go Forward command).
Undoing All Changes
You can use the Undo command several times in a row to undo several changes. In addition, you can use the
Undo All command to undo all changes made to the current file since the last time it was opened.
The Undo History
The undo history is maintained after you save a file, as long as the file is open. Undo history is lost when the file is closed, or if you use the Checkpoint command to perform a final save. You can control whether undo is normally available after saving by using the Options > Preferences: Files dialog box.
It is possible to save a file, and then undo the few last edits. After that, the file saved on disk represents a state that has more edits than the current file buffer. This can become confusing. To help, Source Insight displays the file name with an asterisk whenever the loaded buffer differs from the file saved on disk. If you try to undo to a point before the file was saved, you will prompted to confirm you want to do that.
Restoring Lines
An alternative to Undo is the Restore Lines command. This command restores the selected lines to their original contents when the file was first opened. Furthermore, the Restore Lines command can be undone with the Undo command. Mixing both Undo and Restore Lines can be very useful.
Undo All
The Undo All command undoes all the editing changes to the current file since the last time it was opened.
See Also: Undo, Redo, Redo All commands.
Vertical Scroll Bar
This command toggles the vertical scroll bar in the current on and off.
If you want all windows to have a vertical scroll bar or not, you should use the Preferences: Display Options dialog box option: Vertical Scroll Bar for each new window.
View Clip
(On Clip Window toolbar and right-click menu)
Source Insight 4 User Guide 357
Commands Overview
The View Clip command displays the selected clip in a source file window. If you close the window, you will be asked if you want to retain the clip in the Clip Window.
View Relation Outline
This command changes the Relation Window so it displays its tree data in a textual outline format. See “Relation Window” on page 297.
View Relation Window Horizontal Graph
This command changes the Relation Window so it displays a tree graph view that grows horizontally, from
left to right. See “Relation Window” on page 297.
View Relation Window Vertical Graph
This command changes the Relation Window so it displays a tree graph view that grows vertically, from top
to bottom. See “Relation Window” on page 297.
View Toolbar
Shows or hides the View toolbar.
Visible Tabs
This toggles the display of visible tab characters. Source Insight displays symbols in place of tabs.
Visible Tabs and Spaces
This toggles the display of visible tab and space characters. Source Insight displays symbols in place of spaces and tabs.
358 Source Insight 4 User Guide
Window List
The Window List is a floating/dock able panel window that shows all the open windows.
Commands Overview
Window list
Contains a list of all open source windows, and file buffers that may be open in the "background" that do not appear in a window. You can sort the window list by name or by recently-used order. To sort the list, click on the header titles at the top of the list.
To activate a window, double-click the window in the list.
To edit the Window List Options, click the option button. See “Window List Options” on page 359.
Window List Options
Use this window to change the settings of the Window List panel. See “Window List” on page 359.
Sort List By
Sorts the window list by either most recently usage, or by name.
Include open files without windows
This will include files that are open, but not visible in a window. Sometimes Source Insight open files in the background for symbol resolution or other reasons. For example, a file might be open and visible in the Context window, even though you didn't explicitly open it.
Source Insight 4 User Guide 359
Commands Overview
Show current symbol
This will show the nearest symbol at the cursor position in each window.
Window Options
This command specifies options for handling and displaying source file windows.
Window Positioning
Reuse window position for new windows
If enabled, Source Insight will position new windows exactly at the same location as the current window. The new window will cover the old window.
If not enabled, Source Insight will cascade new windows down the screen in the conventional Windows way.
360 Source Insight 4 User Guide
Commands Overview
Maximize new windows
If enabled, then Source Insight will automatically maximize newly opened windows. If not enabled, then
Source Insight will open the windows according to the option above.
Window Display
Horizontal scroll bars for each new window
If enabled, then each new source file window created will get a horizontal scroll bar.
Vertical scroll bars for each new window
If enabled, then each new source file window created will get a vertical scroll bar.
Show line revision marks in left margin
If enabled, then Source Insight displays a highlight in the left margin selection bar area next to each line that has been edited, or where lines have been deleted since the file was saved or opened. This makes it easy to see what lines you have edited. The Go To Next Change and Go To Previous Change commands (ALT+Keypad
+ and ALT+Keypad -) will jump forward and backward through the changes in the current file.
Show current-line indicator
If enabled, then a horizontal indicator highlight is drawn at the line that contains the cursor position. The indicator is not drawn if you select more than one line.
Show bookmarks in left margin
If enabled, then Source Insight displays a bookmark icon in the left margin selection bar area next to each line that has a mark added with the Bookmarks command.
Smooth scrolling windows
If enabled, then windows will scroll more smoothly, instead of jumping one line at a time. Smooth scrolling only takes place if you are not scrolling continuously, but rather one or two lines at a time. If you start editing or scrolling quickly then smooth scrolling speeds up too. If not enabled, then windows scroll one whole line at a time.
Accelerate smooth scrolling when paging quickly
If enabled, then the smooth window scrolling will not happen if you page up or down quickly.
Text Scaling (%)
Select the percentage of over-all text scaling used in source windows. A scaling of 100% means 'No Scaling'.
Each source window has its own scaling factor. Selecting a scaling factor here applies it to all source file windows, and any new windows that open.
Sort Window Menu
Select the order in which file names appear on the Window menu in the main menu bar.
Outlining Options
Outline options relate to collapsible code blocks.
Show outlining
If enabled, then all source windows will show outline buttons for collapsing and expanding all the time. If this is not selected, the outline buttons and markings only show if you used one of the outlining commands to collapse a section.
Source Insight 4 User Guide 361
Commands Overview
Include code blocks inside functions
If enabled, the code blocks inside functions, such as for
and while
statements, will get outline buttons. Otherwise only function and class level items will display outline buttons.
Show potential collapse points when hovering with the mouse
If the outline handles are hidden, then they will appear when the mouse overs over the area just to the left of a statement that can be collapsed. This option only applies if the above option is not checked.
Show code block nesting lines
If enabled, then nesting lines are drawn by code blocks to make it easier to see the nesting of blocks. You can enable this option independently of showing outlining. That is, you can show nesting lines without having outline buttons appearing.
Outlining Position:
Controls whether the outline buttons appear at the far left, or indented along with the source code.
Window Tabs
The Window Tabs command shows or hides the source file window tabs that appear above the source file
windows. You can control tab options with the Window Tab Options. See “Window Tab Options” on page 362.
Window Tab Options
This controls options for the window tabs that appear above the source file windows.
Use window tabs
Select this to display the window tabs.
Show path information in tabs
When enabled, tabs shows directory path information for any file not in the project source root directory. For example, if file.c
is a file in the util\fileman
subdirectory of the project source root, then the tab will show file.c (util\fileman)
If not enabled, then tabs only show a simple file name without directory information. This allows more tabs to fit in the same space.
Tab Sorting
This controls the order of tabs from left to right.
362 Source Insight 4 User Guide
Commands Overview
Most recent on left
Select this to keep the tabs for files you have visited recently on the left side. Every time you select a different file window, that new "current window" tab will be moved to the left-most tab position.
Tab name
Select this to sort the tabs alphabetically by file name. Depending on the width of the main window, only so many tabs will fit. Therefore, only tabs for files you have visited recently are shown in the tab bar, and they are sorted alphabetically.
Word Fragment Left
The Word Left command moves the insertion point to left by one word fragment. See “Name Fragment
Matching Symbol Names” on page 64.
Word Fragment Right
The Word Right command moves the insertion point to the right by one word fragment. See “Name Fragment
Matching Symbol Names” on page 64.
Word Left
The Word Left command moves the insertion point to left by one word.
Word Right
The Word Right command moves the insertion point to the right by one word.
Zoom Window
If the current window is not already maximized, the Zoom Window command maximizes it. If the current window is already maximized, the Zoom Window command restores the window to its un-maximized size.
Source Insight 4 User Guide 363
Commands Overview
364 Source Insight 4 User Guide