Implement CMD+CLICK on Symbol Declarations to Find Usages Instantly

[essien]

Description

NetBeans currently provides a way to find usages of symbols using CTRL + F7. This method presents a dialog box that requires users to optionally modify the find parameters before clicking the "Find" button.

I propose the implementation of a CMD + CLICK feature that allows users to instantly view usages of a symbol (e.g., a method name) declaration without the need for an initial dialog box. This functionality would mimic the approach found in IntelliJ, where CMD + CLICK on a symbol opens a popup displaying the default results for usages immediately. Users would still have the option to change the find parameters after the initial results are loaded.

Additionally, the CTRL + F7 option loads all usages at once, requiring developers to wait for results to become available. The CMD + CLICK option should adopt a streaming style, presenting usages as they are discovered, thereby enhancing the overall user experience.

Use case/motivation

Finding usages is one of the most frequently performed actions during coding, whether in the writing or refactoring phases. Instant feedback through a CMD + CLICK option will allow developers to make quicker, informed decisions, ultimately boosting productivity and streamlining workflow.

Related issues

None identified.

Are you willing to submit a pull request?

Yes

[mbien]

good idea. The tricky part is that collecting usages can take some time in larger projects - and thats when popups become less interesting again UX-wise compared to dedicated views.

(there is also a second action for the call hierarchy which is similar to find usages)

[essien]

@mbien Thank you for the feedback!

Regarding the concern about usage collection time in larger projects, this proposal could help by implementing a streaming approach, allowing results to appear incrementally as they’re discovered. Rather than waiting for the full set to load, developers could interact with initial results immediately. This would give faster feedback, making the popup more practical, even in large codebases, by balancing immediacy with responsiveness.

As for the "call hierarchy" action, it provides valuable insights but with a different focus. For example, consider the following classes:

class Foo {
  void ping() {
    System.out.println("pong");
  }
}
class Bar {
  void check() {
    new Foo().ping();
  }
}

If we search for usages of Foo#ping, "find usages" highlights new Foo().ping() in Bar#check. However, using "call hierarchy" for Foo#ping would show Bar#check. While useful, this feature is distinct from "find usages," as it centers on method call relationships rather than specific usage locations within the code.

I'm happy to clarify further if needed!

[matthiasblaesing]

Regarding the concern about usage collection time in larger projects, this proposal could help by implementing a streaming approach, allowing results to appear incrementally as they’re discovered. Rather than waiting for the full set to load, developers could interact with initial results immediately. This would give faster feedback, making the popup more practical, even in large codebases, by balancing immediacy with responsiveness.

This will break down once people want a particular order in the results and that would mean, that literally anytime the order could change and you are never sure, whether your mouseclick would reach "the right" entry.

[essien]

Currently, the “Find Usages” tool in NetBeans doesn’t seem to provide options for ordering results, so introducing the cmd + click as a real-time feature wouldn’t be disrupting any established order preferences. For this first iteration, we could prioritize immediate usability, focusing on allowing developers to view results as they become available without waiting for the full set to load. This would offer a quicker workflow for developers who simply want to see initial usages as they appear.

Additionally, I haven’t encountered scenarios where order was critical while checking usages. In most cases, being able to examine any usages quickly is the primary goal. For users who do need ordering, perhaps a default option could be introduced in future iterations, configurable in NetBeans settings.

[Chris2011]

The thing with timing could be easily "workaround" by ordering the stuff which is really fast and more relevant than others and the rest can be added under a line like "see more" or smth. The same timing issue is a problem for find a file which brings this flaky jumping and reordering, which could also be fixed by "see more" a split view "most relevant" "less relevant". Etc.

[Chris2011]

Also, I mean it doesn't need to be instantly visible, this idea here is about instantly (maybe this could be a bit wrong here) without having an extra popup before. It can take time if the user see smth happening and then let's give the stuff to the user.

[Chris2011]

Find usage should do the trick with default settings, coming from the popup which will not be shown but just trigger and then let's wait. Maybe the indexer and everything else needs an improvement too but this is another topic.

[mbien]

there is an argument to be made that find-usages is the reverse of the navigate-to action and would therefore deserve its own navigation mechanism (analog to navigate-to decl/impl).

ctrl+click would jump to the declaration, while ctrl+shift+click would open the usages list for example for the reverse.

In practice this will quickly hit a limit though since the actions aren't symmetric. Find usage results can be a long list which might not make sense to be displayed in a context menu. This is also the reason why there are so many configuration options for the usages query. There is also likely no good default - I change the search scope fairly often for example.

There is also a second problem: how often do you actually want to jump to only one specific usage item? What do you do if this isn't the right item - navigate back to run the query again to select something else? I am not convinced about this usage pattern - given that the dedicated usage window is one shortcut away.

(it might be interesting to experiment with a specialized menu for navigation actions, analog to the alt+insert menu. Instead of running the query it would simply aggregate all navigation actions which make sense to this item via ctrl+right click for example)

[Chris2011]

It should not jump to the first element that was found, if there are more. It should show me all available usages and let me jump to that that I need or want. Also it is not about jumping instant to somewhere, it is about to prevent this configuration popup before. Also if we can't find a default let's do this:

1. Let the default in the config window which comes up by "find usages"
2. Create an option for "instant find usage search instead of popup" and then use those this default or set the default also in the options globally

[mbien]

It should not jump to the first element that was found,

nobody said that it should

[Chris2011]

how often do you actually want to jump to only one specific usage item

Maybe I get this wrong. Anyway I think there are solutions for this instead of say no to new features. Other IDEs can do this and we should start adapt features that are used everyday and I know the features also for CSS and TS that I use it in VS Code. Back in the days they started cloning features of us nowadays it should be the way around. IMHO. And yes I know, someone needs to do it

[mbien]

Anyway I think there are solutions for this instead of say no to new features.

what are you talking about? who said no to new features?

The feature is already there (literally one shortcut away, including async updates), this is only about a different way to present it in the UI. Popup vs window. I don't have anything against it in principle - it has to make sense in NB though.

Possible problems should be cleared up before implementing something, not when the PR is already open.

[essien]

The behavior I’m suggesting for the NetBeans ctrl+click "find usages" feature can be likened to the "Go to File" functionality (accessible via ctrl+shift+o). This feature displays an empty results panel immediately upon activation and then progressively loads search results as you begin typing. The results appear quickly, even if they aren’t instantly complete, and this popup includes search customization options, such as case insensitivity, without requiring a prior configuration step.

@Chris2011 By "instantly," I don’t mean that all search results load instantaneously but rather that the popup itself should appear right away with any initial results, even as more results load progressively (this will still be quick, as is the case with "Go to File"). Currently, even with the ctrl+f7 configuration popup, loading takes time, so I don’t see the pre-configuration window step as enhancing speed.

The following points address some specific feedback:

1. Configuration Before Search: cmd+click should skip the configuration popup, similar to how "Go to File" works, where options like case insensitivity are secondary and don’t require a pre-search configuration screen. This simplifies the workflow and allows for immediate interaction.
2. ctrl+shift+click as a Reverse Navigation Mechanism: I fully agree with @mbien’s suggestion to use cmd+shift+click (or ctrl+shift+click on Windows) as a reverse of cmd+click, enabling a “find usages” action directly from the clicked symbol. This approach mirrors the existing "go to declaration" action and enhances symmetry in navigation.
3. Displaying a Long Results List in Context Menu: I understand @mbien's concern that a long list of usages may be overwhelming in a single popup. However, we already handle potentially large results lists effectively in other contexts. For instance, the "Go to File" search shows numerous files in a popup without issue. Furthermore, this list could provide sorting or filtering options to refine search scope or narrow down results.
4. Setting a Reasonable Default Scope: By default, the search could cover open projects and dependencies. This default setting also aligns with the behavior in the current ctrl+f7 "find usages" which provides a familiar experience for users and can still allow for further configuration if needed.
5. Jumping to Specific Usage Items: In cases where a user wishes to jump directly to one specific usage, there are several options: they could use bookmarks, a filter within the popup, or the traditional ctrl+f7 "find usages" in a dedicated tab. Furthermore, the popup could include an option to display all usages in a new tab, offering the flexibility to switch between quick access and a more detailed view.
6. Accessibility of the Dedicated Usage Window: While ctrl+f7 is technically one shortcut away, it still requires at least one button click and some waiting time for results. A dedicated, progressive-loading popup would offer users more immediate access to results. Furthermore, the convenience of cmd+click offers a much more accessible, user-friendly shortcut compared to ctrl+f7, especially for actions like "find usages" which are frequently used during navigation and code review. While ctrl+f7 requires both hands and disrupts flow to a degree, cmd+click is as simple as a mouse click with a quick key press, making it feel more intuitive. This accessibility is key, particularly in large codebases where quick, context-aware navigation can significantly improve productivity and user experience.

This streamlined approach aims to improve efficiency by allowing users to access "find usages" results without the interruption of an initial configuration popup, letting them focus on the actual search and refinement steps.

[lahodaj]

I have no issue with adding an alternative UI for Find Usages, but I have a few comments:

• there is no shortage of good ideas on what should or could be done, but there's not always enough people to do them. The best way to ensure the good idea is actually realized is to work on it yourself. And just adding an alternative UI is probably not too difficult.
• (not sure if this works on Mac - I assume Ctrl-F7 is the Find Usages shortcut on Mac, it is Alt-F7 for me on Linux, and I believe on Windows as well): the dialog can be confirmed using Alt-F7 (on Linux, Ctrl-F7 may work on Mac, not sure), no need to click on any button. Alt-F7 Alt-F7 opens the result window "immediately".
• as @mbien tried to suggest several times: the Usages window is not waiting for all the results, it shows them as they are discovered. I get it may seem like it is waiting, but it is not. And while improving the speed of Find Usages would be desirable, it is a considerable amount of experimentation to find out how (for Java, at least). I am saying this mostly to avoid any impression there's some waitUntilAllIsDone(); which can be trivially removed to get fast incremental results. That one has been removed a very long time ago.

[essien]

Thank you, @lahodaj, for the detailed input! I appreciate the insights on the current state of the "Find Usages" feature, particularly regarding the immediate display and incremental loading of results, which I hadn’t fully realized before. I also understand the limitations around development resources.

However, several specific usability aspects still make this proposal relevant and valuable:

1. Bypassing the Configuration Dialog: Currently, triggering "Find Usages" presents a configuration dialog where users must select search parameters before results are shown. This extra step can interrupt workflow, especially when quick searches are needed. The proposal aims to eliminate this dialog, showing results instantly, similar to how "Go to File" works. Users would still have the option to adjust parameters as needed, but with the default search executed immediately.
2. Results Filtering: The current "Find Usages" feature lacks the ability to filter results, which would allow users to quickly narrow down results without the need to scan manually through the list with their eyes, as is necessary in the existing results panel.
3. Shortcut Accessibility: While ctrl+f7 (on Mac) opens "Find Usages", it’s not as accessible as cmd+click, which provides an intuitive experience directly in the code editor. This single-click approach mirrors shortcuts available in other IDEs, allowing users to work fluidly without leaving the code view.
4. Contextual Display of Usages: A popup view displaying usages within context allows for quick previews without shifting focus to a dedicated panel, preserving workflow continuity.
5. Alternative Flat View for Usages: The current hierarchical view of results can sometimes make it harder to scan results efficiently. A flat view listing class name, usage, and line number on each line could offer a clearer overview, minimizing navigation through nested structures.

I’d be very interested in becoming a significant contributor to the implementation of this alternative UI and am keen on any guidance to help get started. It would be great to have some initial direction on contributing to NetBeans in this area so that I can be as effective as possible. I believe these adjustments would streamline the "Find Usages" experience, making it more intuitive and responsive to developer needs.

I look forward to any further feedback on refining this idea!