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

Framework

Refactoring actions have similar user flow with following steps:

  1. Invocation of refactoring command (manually or automatically)
  2. Possible warning messages in a dialog
  3. Set of parameters in the same dialog
  4. Possible problems in the same dialog
  5. Suggested changes with a preview in output area or without a preview
  6. Confirmation and execution
  7. 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.

scanning1-ok.png (5675 bytes)
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.


rename5-start.png (4941 bytes)
Figure 2: Case, when dialog for Rename action is being created

rename5-ok.png (5390 bytes)
Figure 3: Case, when Rename action is invoked from menu.

rename5-automatically.png (6164 bytes)
Figure 4: Case, when Rename action is invoked automatically
after double-clicking or F2 pressing. Then it has different title

rename5-error.png (5878 bytes)
Figure 5: Case, when some error message occurs due to error in the dialog

rename5-progress.png (6548 bytes)
Figure 6: Case, when user have clicked on Finish button and collecting is in progress

rename5-error2.png (6765 bytes)
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):

changemethod5-error.png (12418 bytes)
Figure 8: Change Method Parameters - error state

changemethod5-ok.png (11912 bytes)
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:

encapsulatefields.png (9920 bytes)
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.

moveclass1-simple.png (6750 bytes)
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).

moveclass1-dndsimple.png (8361 bytes)
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).

moveclass2-multiple.png (9328 bytes)
figure 13: New design of Move multiple classes action, when it's invoked automatically after D&D action

moveclass2-dndmultiple.png (10483 bytes)
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.

moveclasses-precheck1.jpg (46376 bytes)
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:

findusages-class.png (5435 bytes)
figure 16: Find Usages - Dialog for Class


findusages-method.png (5919 bytes)
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.

usages-logical.png (11016 bytes)
Figure 18: Logial view with tree structure similar to Project window structure

usages-physical.png (10311 bytes)
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:

  1. Refresh list of Usages
  2. Invoke Parameter Panel again
  3. Expand or Collapse All Nodes
  4. Show Logical (Tree) View
  5. Show Physical (File) View
  6. 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.

refactormenu1.png (2729 bytes)
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
  •  

Project Features

About this Project

ui was started in November 2009, is owned by Jiří Kovalský, and has 44 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
 
 
Close
loading
Please Confirm
Close