Module Utilities, part Search – UI Specification
Tomáš Pávek <firstname.lastname@example.org>, Sun Microsystems
Marián Petráš <email@example.com>, Sun Microsystems
Launching the search feature
The search feature can be activated either by a context-insensitive action Find in Projects... or by a context-sensitive action Find.... Both actions provide the same functionality, the only difference is their scope – action Find in Projects... searches through all opened projects, action Find... allows the user to search in selected nodes (so e.g. individual Java packages and folders).
Action Find in Projects... is enabled only if there is at least one project open. Context-sensitive action Find... is enabled if there is at least one node activated and each of the nodes meets at least one of the following conditions:
- the node represents a file folder
- the node represents a project's root node
- the node represents a project's source root (e.g. Source Packages, Test Packages)
- the node represents a Java package (J2SE projects only)
Both actions are presented in the Edit menu. The actions' shortcuts are as follows:
- Find... – Ctrl-F
- Find in Projects... – Ctrl-Shift-P
Scope of the Actions
If the search feature is launched using the Find in Projects... action, sources of all open projects are subject to searching.
If the search feature is launched using the Find... action, it is the current set of activated nodes that defines which folders will be searched. Each activated node is assigned a folder and a specification whether the folder should be searched recursively or not. The search is then performed on all the folders. The assignment rules are as follows:
- if the node represents a file folder, that folder is to be searched recursively
- if the node represents a project, all project's source roots are to be searched recursively
- if the node represents a project's source root (folder), that folder is to be searched recursively
- if the node represents a test's source root (folder), that folder is to be searched recursively
- if the node represents a single Java package, the corresponding folder is to be searched non-recursively
Search Criteria Dialog
|Find in Files|
This window is used for setting search criteria parameters. By default four types of criteria are implemented – full text content, object name, object type, and object modification date – four tabs in the window correspond to them. Each criterion can be switched on/off by the "Use this criterion for search" checkbox. Criterions turned on must be all fulfilled (in logical conjunction). In other words – only objects that fulfill all set criteria will appear in results.
Following search criteria are implemented by default:
- Full Text – for finding files containing given text – most useful for java sources and other textual files; a substring to find (case sensitive) or a POSIX-style regular expression can be entered,
- Object Name – for finding files of given name – also a substring of the name (case sensitive) or a POSIX-style regular expression can be entered,
- Date – for finding files modified during some last days or during a range of days,
- Type – for finding certain types of files – (more than one type can be selected by holding the Ctrl key and clicking...).
Entered settings of criterions can be saved and restored using appropriate buttons (Save Settings as..., Restore Saved...). This can be used for making search pre-definitions. Criterions are saved to Project Settings > Search Types where they can be also deleted.
Search Results window
Results of search process are displayed in this window – as a list of nodes representing objects that met all search criteria. This list behaves like the explorer – nodes may be opened, renamed, compiled etc.
Found element can have details that display additional information. Fulltext search details adds line text. User can navigate to that line by hitting Enter on it.
If multiple projects were searched, the search results are separated by projects – there is a node for each project which contains objects (files) found within that project.
The right pane contains details about the currently selected file. The Path textfield contains path to the file, relative to the root directory of the project the file pertains to. If there is no node selected or if the currently selected node does not represent a found object (file), both the Path textfield and the list of positions are empty.
After the search is complete, search results window enables following operations:
- to refine the criteria and run the search again (using Customize Criteria button),
- to sort the list of found nodes (using Sort by Name button; when sorted, it's renamed to Do Not Sort and unsorts the list back),
- to show details available for search-hits of all found nodes (using Show All Details button) – these details are displayed in the IDE's output window (see bellow),
- to display details (search-hits) for selected node only – in a list on the right-side of the window (see below),
- to locate selected node in the main explorer (in the whole repository tree) – using the button with the "explorer" icon at the bottom of the window.
Working with search details
Search details are provided for a full text search where the given substring may occur more than once in the file – all these occurrences are presented as "search details". When some found node is selected, all its search details are displayed in the listbox on the right side (below the buttons). Items in this list respond to double-click (or Enter) and show the substring directly in the file (the file is opened in the editor first if needed). There is also the possibility to show all search details for all nodes together (by Show All Details button). The IDE's output window is filled with all details – it contains also text of whole lines (in addition to information about position). The output window also responds to double-click (or Enter) – same as the listbox in the results window.
Note: when searching for the regular expression is performed, only lines are presented as search details (position on the line is not known). Complete location – both line and column position – is provided for the common substring search.
Improvements and Evaluation
OverallThe UI of search results is an improvement over the previous state. Good work!
Comments and suggestions
- show the search string in the top level node
- show the number of files that contain the search string, but also the number of occurrences
- expand all nodes (or at least the first one) and select the first occurrence by default
- show the full path next to the file name; something like "MyClass.java [src/org/netbeans/mypackage/MyClass.java]"
- consider moving the command buttons into the toolbar and put the toolbar on the top of the window (to be consistent with other widnows, e.g. TODO) - discuss the exact design with HIEs
- show a progress bar similar to TODO window
- align the white output area to the edges of the window (without extra border; keep the border only between the output area and the command buttons)