UI design of refactoring features
Authors: Dusan Pavlica
Version: 4.0
Last update: 22/06/2004
Table of Contents
- Introduction
- Context
- References
- Framework
- List of Features
- Scenarios
- UI specification
- Scanning Project Classpaths
- Rename
- Change Method Parameters
- Encapsulate Fields
- Move Class
- Move Multiple Classes
- Find Usages
- Preview in Output
- Undo / Redo actions
- Open Issues
- List of the most visible errors
- List of features that are missing currently
Introduction
Context
This document defines UI and behavior for specific refactoring features. These features
should fit into user's flow which is described in UI Framework (mentioned link below). UI
specification chapter includes part about united design framework, which describes layout
of common Buttons, Progress Bars and Error Indication.
References
- UI Framework for new features based on MDR: http://ui.netbeans.org/docs/hi/javamdr/ui_framework.html
- Usability study on refactoring alpha build: http://ui.netbeans.org/docs/hi/javamdr/refactoring-study-report.html
Framework
Refactoring actions have similar user flow with following steps:
- Invocation of refactoring command (manually or automatically)
- Possible warning messages in a dialog
- Set of parameters in the same dialog
- Possible problems in the same dialog
- Suggested changes with a preview in output area or without a preview
- Confirmation and execution
- Undo action
Group of Refactoring features exist as a Context menu Item in the Explorer, in the
Source Editor and as Main Menu Item too. User are able to invoke these actions manually or
some actions are invoked automatically (e.g. when User rename class name directly in the
Explorer).
List of Refactoring Features
The following features have been designed and will be implemented:
- Rename
- Change method parameters
- Encapsulate Fields
- Move class
- Move method
- Move field
- Find Usages
Scenarios
We have defined detail scenarios for each refactoring feature and design will fit into
this scenarios, but this content is published only internally meantime.
You can create your own opinion about common scenario by reading basic UI Framework
scenarios.
UI specification
Following text and pictures describe parameter panels and error panels mainly and all
fits into UI Framework's user flow.
We have basic set of refactoring features and it will increase continuously. Then this
design chapter will be updated still.
Some changes were done in dependency on Usability
study (04/16-04/19 2004) too.
Scanning Project Classpaths
There is necessary to scan rt.jar and other packages for good function of Refactoring
features and Editor's features too. But this scanning takes too much time and clear
progress indication is needed. That's why the following dialog should appear after
creating of a new project. When initial parsing is done, then next scanning will not take
too much time.
Our recommendation is to show it at the most 1 minute. Otherwise it indicates bad design
or implementation.
Figure 1: Scanning dialog
This dialog could be invoked from Tools menu (Re-scan Project Classpaths menu item) in a case, when user has some problem in the IDE. But our recommendation is to remove this menu item in the future (when Refactoring will be stabilized), because it's bewildering and user can have serious problem to find it and understand it's behaviour at all.
Better way is to checking inconsistency of parsed database in the background, catch all
possible exceptions and show to user information about re-scanning only when it's needed.
Rename
Description: This action renames package, class, method or field and replaces the name at all places in the code.
Possible ways of invocation:
- On methods, fields, classes and packages in the Explorer, and in the Source Editor
- By mouse double-clicking
- By pressing F2 key
- From Main menu
Suggested design of parameter panel:
The following figures describes more possible states of rename pseudo-wizard, which are the same for other refactoring features too.
Figure 2: Case, when dialog for Rename action is being created
Figure 3: Case, when Rename action is invoked from menu.
Figure 4: Case, when Rename action is invoked automatically
after double-clicking or F2 pressing. Then it has different title
Figure 5: Case, when some error message occurs due to error in the
dialog
Figure 6: Case, when user have clicked on Finish button and
collecting is in progress
Figure 7: Case, when some error message occurs due to pre or post
checking
Existing errors of implementation:
- Small border around content
- Label for new name shouldn't be disabled during Collecting and Checking time
- Better descriptive text is needed
- Possibility to apply renaming on Comments and Strings
- Possibility to apply renaming on Text in non Java Files
- Inconsistency in renaming of nodes in the Explorer. It means that some nodes could be renamed by double clicking or F2 pressing and some not (e.g. field, method)
Change Method Parameters
Description: User is able to Change/Add/ Remove Parameters and change Modifier by given method.
Places for invocation:
- Contextual Menu from a method node in the Explorer or from the Source editor
- Refactoring menu item in the Main menu
Suggested design of parameter panel (with and without error message):
Figure 8: Change Method Parameters - error state
Figure 9: Change Method Parameters - non-error state with one new
parameter
Existing errors of implementation:
- Navigation and editing in a table has some implementation problem
Encapsulate Fields
Description: Makes the field public, generates getter and setter method for it and replaces field usage by accessors usage at all occurrences.
Possible places for invocation:
- Contextual Menu from a filed node, group of fields node, class node in the Explorer or from the Source editor (document body or selected field)
- Refactoring menu item in the Main menu
Suggested design of parameter panel:
Figure 10: Encapsulate Fields
Existing errors of implementation:
- Possibility to invoke this action from every place of document not only from field name
- Navigation and editing in a table has some implementation problem
Move class
Description: Possibility to Move class into another package or to other project.
Possible ways of invocation:
- From nodes of classes in the Explorer, and from the Editor's Contextual menu, when class name is focused too
- From Main menu when class node or name is focused
- Automatically after D&D of class in the Explorer.
- Automatically when user used Ctrl+X and CTRL+V shortcuts combination in the Explorer.
Suggested design of parameter panel:
To be consistent with a new design of Project System we suggested the following design. Unfortunately it has disability to create new package from this dialog if it's needed (see error section). So the right design should be more discussed and then current one will be improved a bit.
Figure 11: Move Class dialog - only one class was invoked manually
from some menu
When user moves class by keyboard shortcuts (CTRL+X, CTRL+V) or by Drag & Drop, then Move class action should be invoked automatically with pre-selected project, location and package in the parameter panel (see the following figure).
Figure 12: Move Class dialog - only one class was Drag&Droped
Existing design or implementation errors:
- There is no chance to create new package in the Move class dialog in current design.
Move multiple classes
Description: Possibility to move more classes into another package or project at once.
Possible ways of invocation:
- From Contextual menu in the Explorer, where more classes are selected
- From Refactoring main menu, where more classes are selected in the Explorer
- Automatically after D&D of more classes in the Explorer
- Automatically when user used Ctrl+X and CTRL+V shortcuts combination in the Explorer.
Suggested design of parameter panel:
There is a difference between manually invoked Move classes action and automatically invoked move classes action after D&D:
- When action is invoked automatically after D&D, then target package is determined already and user couldn't change it (figure 13).
- When action is invoked manually from some menu, then user should define target package (figure 14).
figure 13: New design of Move multiple classes action, when it's
invoked automatically after D&D action
figure 14: New design of Move multiple classes action, when it's
invoked manually from some menu
Next steps are the same for both methods of invocation:
- Some errors can occur during pre-check process and user can continue with refactoring (figure 15).
- User will obtain final summary about errors in the Output area and he can open problematic code in the Editor.
figure 15: List of errors during Move multiple classes action
Find Usages
Description: User could search each usage of given element (class, method and field)
Possible ways of invocation:
- Contextual Menu from a method / field / class node in the Explorer or from the Source editor
- Find Usages menu item in the Edit menu
- By Shortcut Alt+F7
Suggested version of parameter panel:
figure 16: Find Usages - Dialog for Class
figure 17: Find Usages - Dialog for Method
Preview in Output:
The following figures show Usages Results in the Output area.
There are two ways of displaying results.
Figure 18: Logial view with tree structure similar to Project window
structure
Figure 19: Physical view with not so deep tree structure
Toolbar in the Preview window is situated at left side and should contain these
actions:
- Refresh list of Usages
- Invoke Parameter Panel again
- Expand or Collapse All Nodes
- Show Logical (Tree) View
- Show Physical (File) View
- Export Usages Into File
Existing errors or missing behavior:
- There should exist option for searching in non-java files at least.
- Additionall option for open search result in a new TAB will be great.
- Missing ability for switching between logical and physical view.
- Other Missing actions in the Toolbar of Preview window (Edit parameters, Export to File)
Undo/Redo refactoring actions
Description: Possibility to skip/run again last refactoring operation
Suggested design:
User should use only one united Undo (Redo) action, which will work for Editor and For
Refactoring features together (plus other actions, e.g. D&D).
But it looks like not trivial solution, so current implementation uses the following UI
hack.
Figure 20: Undo and Redo actions are situated in the Refactor menu
temporarily
Existing design errors:
- Is too hidden as a Menu Item inside a Contextual Menu. The best way is to have one united Undo/Redo action for changes in the Source editor and for Refactoring actions. Then user will use this more easily without any misunderstanding. For Undo / Redo of refactoring action will be needed some warning dialog, which will inform user about amount of changes.
- There are implementation problems with integration this one global Undo/Redo action. Current implementation clears Editor's Undo history before each Refactoring action, which is bewildering.
Open Issues
- There is open issue about usage of pseudo-wizard dialog and especially about < Back and Finish buttons. Finish should be replaced by some more intuitive name. E.g. Next > or by name of current refacting action ?
- Right shortcuts for refactoring features. We have shortcut for Find Usages currently and rest refactoring features doesn't have any shortcuts. We discussed it internally and we have really poor rules which action should have shortcut, which not and when it isn't needed. We will find some temporary shortcuts for promo D maybe.
- Name of Non-fatal errors could be changed to Warnings
- Do you have some more open issues ?...send it to author of UI spec please
List of the most visible errors
- Preview All Changes checkbox isn't persistent
- Bad aligning of bottom part of the dialog
- Grey border of error is visible still even in situation without any errors
- Support (or indication) for invocation of refactoring features in cases when user changes code. Good example is renaming of method in a source code.
List of features that are missing and should be implemented in next versions
- Switching between logical and physical view in the Preview area
- Contextual menu above Preview Area
- Closing of Preview output TABs by clicking on close icons situated on them
- Checkboxes used for renaming on Comments, Strings and Texts in Rename dialog
