Search, Replace and Refactoring in the MPLAB® X IDE

Last modified by Microchip on 2024/06/24 06:31

This page covers the search, replace and refactor features of MPLAB^® X Integrated Development Environment (IDE).

Find in File

MPLAB X IDE provides two methods to find something in the file that is currently displayed in the editor.

Method 1

The first method requires the least amount of effort. Highlight an existing piece of text (e.g., a variable name, function name, or any other text in your code). The editor will automatically highlight all the matches in the current source file in gold. Also, a gold bar will appear in the error stripe at the far right to indicate the relative position of all instances that have been found in the file. Clicking on a bar in the error stripe will take you to that instance of the highlighted item.

Method 2

The second method is mostly used when you are searching for something that isn't presently visible to highlight. Select Edit > Find… from the main menu. This will display a bar at the bottom of the editor, containing a text box where you can type in your search term. All the matching terms will be highlighted in orange and a gold bar will appear in the error stripe at the relative position in the file of each instance that was found.

Find Usages

The Find Usages option in MPLAB X IDE opens a dialog box for searching open or active projects for usages of classes, structures, variables, macros, functions, or files within the project's source code. The results of the search displayed in the Usages window permit fast navigation to key search points in the project source. Find Usages application and caveats are presented here.

Accessing Find Usages

There are three ways of accessing the Find Usages functionality of MPLAB X IDE:

Method 1: Keyboard Shortcut ALT + F7

Method 2: Edit Menu

Method 3: Class Dialog

Method 4: Source Window Right Click

Find Usages Scope

Once Find Usages is selected for the appropriate portion of code (i.e., classes, structures, variables, macros, functions, or files), select the appropriate scope. The scope refers to whether a specific project (or all the open projects) is searched.

Running Find Usages

Click Find to run the utility and display the locations where the selection was used in the Usages window.

Usage Window Buttons

These buttons are located on the left-hand side of the Usages window :

Refresh button re-runs the Find Usages utility.
Previous/Next Occurrence buttons move through the find usages results in the source editor.
Expand/Collapse Tree button compresses/decompressed the +/- for each node of the results.
Logical View button organizes the results tree to match the logical project window organization.
Physical View button organizes the results tree to match the physical arrangement of the files (e.g., .inc file hierarchy on the hard drive).

General Find Usages Caveats

Moving through usages is difficult when the Usages window is minimized (meaning not pinned). When the Usages window is not pinned, it disappears each time a different usage is selected. For this reason, select Pin at the top right of the Usages window to make browsing between instances simpler.

Do not select Minimize Window.

The cursor location and text selection can confuse Find Usages and may result in errors such as "Find Usages Cannot Be Applied In this Context" and "The original element being refactored is not available." For this reason, it may be beneficial to use Find Usages within the Classes dialog shown in Accessing Find Usages section.

Find in Projects

MPLAB X IDE has a Find in Projects form to find text in the selected scope.

Find in Projects is selected from the main menu Edit > Find in Projects….

The form will also display when the focus is in the Project window and menu Edit > Find… is selected.
The Search Results window toolbar button Modify Results will also display the form.

The Default Search tab is currently recommended.

To Setup a Search using the Find in Project

Select the Containing Text from the combo box or type new search text.

The search text will be stored for future searches.
Options include Match Case and Whole Words

Match combo box selections are:

Literal: search for the exact string.
Basic Wildcards: search with * = any string, ? = any character.
Regular Expression: when selected, the (test) string is enabled for testing your RegEx pattern.

Select the Scope for this search from the choices in the Scope combo box.

Current Project
Open Projects
Open Documents (n files)
Browse for Files

Scope options include:

Search in Archives: ZIP files
Search in Generated Sources: can include compiler save temps like main.s

Select the File Name Patterns from the combo box.

Patterns added, like *.c or *.cpp, will be saved.
An Ignore List of folders and paths can be created.
File paths can be specified with Regular Expressions and a test utility.
Open In New Tab: when checked, a separate tab is created for each search. Unchecked will overwrite previous results.

Search Results are displayed in the Output area. Display options include:

Expand / Collapse all nodes in tree.
Show results as folder tree.
Show results as list of files.
Show all details - list of results in Output view.

Replace in Projects

MPLAB X IDE has a Replace in Projects form to replace text in the selected scope.

Select Replace in Projects from the Edit option on the main menu.

The Modify Criteria button in the Search Results window toolbar will also display the form.

Steps for using the Replace In Projects Form

Select the Containing Text from the combo box or type new search text.

The search text will be stored for future searches.

Options include Match Case, Whole Words, and Preserve Case.

Match combo box selections are:

Literal: search for the exact string.

Basic Wildcards: search with * = any string, ? = any character.

Regular Expression: when selected, the (test) string is enabled for testing your RegEx pattern.

Select the Replace With from the combo box or type new replace text.

Select the Scope for this search from the choices in the Scope combo box.
Scope options include:

Current Project
Open Projects
Open Documents (n files)
Browse for Files

Select the File Name Patterns from the combo box.

Patterns added, such as *.c or *.cpp, will be saved.
An Ignore List of folders and paths can be created.
File paths can be specified with Regular Expressions and a test utility.
Open In New Tab: when checked, a separate tab is created for each search. Unchecked will overwrite previous results.

Search Results are displayed in the Output tab.
Display options include:

Go to Next / Previous matching string.
Expand / Collapse all nodes in the tree.
Show results as a folder tree.
Show results as a list of files.
Show all details - list of results in Output view.

Preview and select each matching string for replacement by checking the box.

All matches can be replaced by pressing the button at bottom left of Search Results view.
Preview pane shows currently selected match for replacement.
Selecting Next/Previous moves to that file line in the Editor and Preview Pane.

Refactor Code

What is Refactoring?

Refactoring may be a new term to many MPLAB X IDE users since many PIC^® microcontroller programs are very short. However, as applications grow more complex, IDE support for refactoring becomes very useful.

Code Refactoring is the process of changing a computer program's source code without modifying its external functional behavior in order to improve some of the nonfunctional attributes of the software. Advantages include improved code readability and reduced complexity to improve the maintainability of the source code, as well as a more expressive internal architecture or object model to improve extensibility. (Source: Wikipedia)

In a sense, refactoring is a fancy form of "search and replace" where the IDE is language-aware and can make more intelligent decisions about how and when an item should be modified. While "search and replace" might be adequate for renaming a variable when you only have one or a very small number of source files, it becomes more of a challenge if you have a large program and want to move an item to a new file or rename something throughout your entire project. Refactoring is immensely helpful in situations like that.

Rename Operations

The simplest form of refactoring is to rename a variable or function. This may be accomplished by highlighting the variable or function in your code and then selecting from the main menu Refactor > Rename…. This will open a dialog box prompting you for a new name. At this point, you may accept the new name by clicking on the Refactor button and the IDE will rename every instance of the variable or function in all files of the project. Alternatively, you may choose to preview the refactoring by clicking on the Preview button and control individual items as to whether or not they should be renamed.

The Preview window will open as a new tab in the output area. Here you can see each file in which the variable or function exists and will be renamed, with a before and after view of the code on the right side. A checkmark indicates that a specific instance will be renamed. Unchecking it will keep the original name for that specific instance. Click on the Refactor button to accept the rename operation and any modifications to individual instances you have made.

Move Operations

Move refactoring is only applicable to object-oriented languages and is used to move a class from one package to another. This is not usable in C or assembly at the present time.

Copy Operations

Copy refactoring is only applicable to object-oriented languages and is used to copy the contents of a class from one package to another. This is not usable in C or assembly at the present time.

Safely Delete Operations

Safely Delete refactoring is only applicable to object-oriented languages and is used to delete a class member variable while checking to ensure that it is not used by your code. This is not usable in C or assembly at the present time.