Find References in Visual Assist find usages of the current symbol within the current project or solution. The command ignores similarly named symbols of different contexts, and provides much more efficient access than Find in Files.
Visual Assist versus Visual Studio
In Visual Studio 2017, the built-in Find References is comparable to the implementation in Visual Assist.
In Visual Studio 2015 and older IDEs, the Visual Assist implementation is more feature-rich, faster, and available for more symbols.
Access
Find References is available from a declaration, definition, or reference to a symbol. Because Find References is typically used often, you may invoke the command in numerous ways:
- using its default shortcut (Shift+Alt+F)
-
via the Quick Action and Refactoring menu (Shift+Alt+Q)
- via the Refactor sub-menu of the context menu in the text editor (Right-Click or Shift+F10, E, D)
-
via the VAssistX entry in the menubar (Alt+X, D)
-
from within several tool windows, including the HCB component of the VA View and the VA Outline
Output from Find References is placed in the Find References Results window, where results are grouped by project and file.
Double-click entries in the results to jump to respective locations in source.
Find References in Multiple Projects
You can restrict searches to the current project, or search throughout multiple projects, via keyboard shortcut (P), toolbar icon, or setting in the context menu of the Find References Results window.
Results include only one project node when scope is restricted to the current project.
Toggle scope of search via shortcut (P), toolbar icon, or context menu (Right-Click or Shift+F10, J).
Results from multiple projects include project nodes.
Find References opens with the scope of the previous find.
If you find all references to a local variable, i.e. one whose scope does not exceed the current file, the toolbar button and shortcut (P) to change scope are ineffective. Searches are always restricted to the current file.
Filtering Results
Filter content of the Find Results window using single-letter shortcuts when focus is in a results window. Open the context menu of the window to see all available filters. Only filters and shortcuts applicable to the current results are visible. For example, the shortcut to display declarations and definitions (D) is visible only when results include a declaration or definition.
Filter shortcuts are toggles. Press R to hide read references; press R again to unhide them.
Filter states for D, R, and W toggles are not sticky. Each Find References begins with all of the respective results, and each of the shortcuts initially removes references.
Filter states are specific to each results window. You can show read references in one window and write references in a cloned window—to one or different symbols.
The count of hidden results, if non-zero, appears at the top of each results window. Each count of "found" results is exclusive of hidden results.
Highlight Results
References found can appear bold and highlighted in the results window. By default, references where a symbol is written are typically highlighted in MistyRose, whereas references where a symbol is read are highlighted in LightCyan.
Highlighting in results window requires that Enhanced Syntax Coloring be applied to views.
Specify highlight colors in the options dialog of Visual Assist.
Multiple References
Multiple references that occur on a single line in source appear in multiple entries in a results window.
Navigation
Navigate within the Find References Results window using your keyboard, mouse, or arrow keys. To see references scroll into view inside source windows, navigate within a results window using shortcuts for Edit.GotoNextLocation and Edit.GotoPrevLocation, Double-Click, or Down-Arrow and Enter.
The default shortcuts for Edit.GotoNextLocation and Edit.GotoPrevLocation vary with IDE and keyboard mapping.
IDE | Keyboard Mapping | Default Shortcuts for Next and Prev |
---|---|---|
Visual Studio 2002 and newer | Default | F8 and Shift+F8 |
Visual Studio 2005 and newer | Visual C++ 6 | F4 and Shift+F4 |
Visual Studio 2002/2003 | Visual C++ 6 | None* |
Visual C++ 6.0 | Developer Studio | Ctrl+Page-Down and Ctrl+Page-Up |
Visual C++ 6.0 | Developer Studio | F4 and Shift+F4** |
*Recommend assigning Edit.GotoNextLocation and Edit.GotoPrevLocation to F4 and Shift+F4 respectively.
**Requires pre-existing text in the Output Window.
Visual Studio 2008 and older
References scroll into view via Edit.GotoNextLocation and Edit.GotoPrevLocation even after you close the Find References Results window.
Clone Results
Clone a results window to save a result set to a new window, so you can find references to other symbols without losing your original set. Close a window using the toolbar icon, context menu (Right-Click or Shift+F10, U), or shortcut to VAssistX.CloneFindResultsWindow. Subsequent invocations of Find References populate the Find References Results window, not the cloned window(s).
Cloned windows are identified by window title and lack of "Highlight all".
Visual Studio
A cloned Find References Results window can be docked or undocked like other tool windows.
Visual C++ 6.0
A cloned window always floats. To control window visibility in relation to other IDE windows, right-click the title bar of the window and choose Stay on top.
Refresh Results
If you modify source, you can refresh contents of a results window using the shortcut for Debug.Start (F5), or the toolbar icon.
Allow Navigation to Stale Results
If you modify source after running Find References, some of the references in a results window may become stale, meaning they no longer refer to correct symbols or locations. This is often the case after you clone a results window, then use the cloned window as a to-do list. For example, you find all references to a symbol, then refactor the code surrounding several of the references.
In the following example, the reference to numWeaps is stale because the symbol in source has been changed to numberWeapons.
If you navigate to a stale reference, Visual Assist will open and jump to the top of the file containing the reference. (The jump is your indication that the reference no longer exists.) A refresh in a results window will update all references to avoid the jumps, but each refresh may require considerable time to execute. If you prefer not to refresh results as you make significant edits, allow navigation to stale results in the context menu of the Find References Results window; Visual Assist will navigate to original locations even when original references are no longer present.
Highlight References in Source Windows
Use the shortcut (H) or the checkbox in the top of the Find References Results window to toggle highlighting of all references in source windows, in addition to those within the results window. (Highlighting is available only in the primary results windows, i.e., not in cloned windows.)
Cancel highlighting with the shortcut (H), by unchecking "Highlight all", or by pressing ESC within a source window. To restore highlighting after canceling, return to the results window and type 'H' or re-click "Highlight All".
Make highlighting of references in source windows the default enabling the option in the context menu of a Find References Results window, or by checking the option associated with highlight colors in the options dialog for Visual Assist.
Visual Studio
You can specify foreground colors for highlighting in the options dialog for Visual Assist, but you can specify both foreground and background colors in IDE | Tools | Options | Environment | Fonts and Colors.
Visual C++ 6.0
You can specify only foreground colors in the options dialog for Visual Assist.
Display References in an Inheritance Chain
Visual Assist can display, in results windows, inherited references from parent classes and overridden references in child classes.
Toggle display of inherited and overridden entries by enabling "Inherited and overridden references" via the shortcut (O), toolbar, or context menu of the Find References Results window.
Find References in Code-Behind Files
For frameworks that employ a code-behind model, such as WPF, Visual Assist finds references in both design and code-behind files.
If Find References Results is not available via a context menu in design mode, access the command via its default shortcut (Shift+Alt+F).
Display Comment and String References
You can broaden searches to include hits in relevant comments and strings. Visual Assist uses heuristics to determine which candidates are "hits", e.g. proximity to non-comment and non-string references.
Toggle the broader searches using shortcut (M), or context menu of a Find References Results window.
Display Creation/Construction Hits
If your symbol identifies a class or struct that can be instantiated, search results include references to creations and constructions of the class or struct. You can narrow search results to contain only the instantiations by toggling off all filters but that for creation/construction hits.
Toggle using shortcuts visible in the context menu of a Find References Results window.
Display Scope References
You can broaden searches to include references that only identify scope, e.g., references to class DROID_GROUP required only to identify methods within the class.
Toggle the broader searches using shortcut (S), or context menu of a Find References Results window.
Show Tooltips
If you hover over a reference in a results window, a tooltip will appear containing code that surrounds the reference.
You can enable/disable tooltips via an option in the context menu of a Find References Results window.
Find in Results
You can find a string (Ctrl+F) within Find References Results to isolate specific references of interest, especially within a results window that contains numerous entries.
Invoke Find with the default shortcut (Ctrl+F) or toolbar icon.
Once you have found the first occurrence of a string, you can find next (F3) and previous (Shift+F3) entries via typical shortcuts.
If you "mark all" strings and close the Find dialog, you can scroll a results window to find references of interest. Use Ctrl+F to find strings within a results window.
"Mark All" is a toggle, and is active in subsequent searches until you reopen the Find dialog and press "Mark All" again.
Stop a Search
You can prematurely terminate lengthy searches by clicking "Stop" in the VA Find References Results window, or by via shortcuts:
- Ctrl+Break - To stop the references search.
- Alt+F3,S - The shortcut stops the continuous movement of results in the VA Find References Results window, but the search continues, and it is visible on the search progress bar.
You can use a different shortcut by assigning one to VAssistX.RefResultsCancel.
Important: Similar to the behavior of Find in Files, closing of a Find References Results window does not terminate a running search. A search will continue in the background if its window is closed. You can view the results of a search that ran in the background by reopening the Find References Results window, using VAssistX | Tools | Find References Results (Alt+X, T, F).
Display Project Nodes
References in a results window are always grouped by file. You can also group by project, although project nodes never appear in a results window when finding references to local variables or when restricting a search to the current file.
The following is an example of a results window with project nodes.
The same window is grouped solely by file when project nodes are not included.
You can include project nodes via the options dialog for Visual Assist, or via the context menu of a Find References Results window (Right-Click or Shift+F10, S).
Collapse/Expand Nodes
When project nodes are displayed, the nodes can be collapsed or expanded en masse using commands in the context menu of a Find References Results window.
Expanding is available at the project level, and collapsing is available at the project and file levels.
Find (Ctrl+F) within the results will automatically open appropriate nodes.
Show Line Numbers
You can prefix entries in the results window with containing method names and the line numbers of references.
The following is an example of a results window with method names and line numbers:
The same window can be generated without method names and line numbers:
Toggle display of method names and line numbers in the context menu of a Find References Results window (Right-Click or Shift+F10, L).
Display Unknown/Guess Hits
In some instances, e.g. with symbols defined using complex preprocessor macros, Visual Assist may be unsure if particular references to a symbol are legitimate. In these cases, the references are earmarked with a question mark in the results window.
You can toggle display of unknown/guess hits using shortcut (G), or the context menu of a results window.
The option to display unknown/guess hits is available in the context menu only if a results set includes them.
Display #Include Hits
A header file in C/C++ whose name is that of a symbol might be considered a reference to the symbol. For example, Foo.h that contains the declaration of class Foo might be considered a reference to Foo. Visual Assist can include such header files in results windows.
You can toggle #include hits using the shortcut (I), or the context menu of a results window.
The option to display #include hits is available in the context menu only if a results set includes them.
Find References in Current File
You can restrict a search to the current file by invoking Find References in File from the VAssistX menu (Alt+X, S).
Icons
Icons in a results window describe its references, including:
- definition or declaration
- modified / used on the left side of an expression
- not modified / used on the right side of an expression
Cut, Copy, Delete
You can copy (Ctrl+C) entries in a results window. If you copy a filename node, Visual Assist places the filename and its references in the clipboard. If you copy a single reference, Visual Assist places only the reference in the clipboard.
The following is an example of references pasted into WordPad.
Typically after cloning a results window, you can use a list of references as a to-do list—a list of references that need attention. Use delete (Del) to remove "completed" references from the cloned results window. (Delete does not modify source code.)
Restoring Find Results
The Find References Results window, and cloned results windows, retain their content when you close the current project and when you open a new project. Use the behavior to jump to files in a previous project after creating a new one. A new Find will reset the content of the Find References Results window.
The most recent result set can be restored without restarting a search. Simply reopen the Find References Results window. The process varies by IDE.
Visual Studio
Assign a shortcut to VAssistX.FindReferencesResults or select VAssistX | Tools | Find References Results (Alt+X, T, F).
Visual C++ 6.0
Customize your IDE menu or toolbars to include VisualAssistXFindReferencesResults.
Shared Scope Setting
The setting to display from all projects is shared with the Rename and Change Signature commands. If you restrict Find References to the current project, the scope of the next Rename or Change Signature is restricted to the current project as well. If you broaden the scope of Find References to all projects, the next invocation of Rename or Change Signature will also search all projects. The shared setting prevents you from inadvertently refactoring references inconsistent with those you review using Find References.
Caveat
Find References locates references within #ifdef
blocks, but complex preprocessors macros that severely alter the definition of symbols may interfere with the ability of Visual Assist to correctly identify symbols and their references.
Limitation
Find References is not available for operators.
See Also
Rename, to find all references and rename them.
Find by Context, to move among the next and previous references within a source window.
Registry Settings
Value Name | Meaning |
---|---|
CreationTemplateFunctionNames | Extend creation/construction hits to function templates beyond make_shared() and make_unique() |
MessageBoxFailureNotifications |
Disable message box from Find References
|