HOME > Community > Projects > ui

User Interface Specification:
Surround With...

Author: Gabriel Tichy
$Revision: 1.8 $

Table of Contents:

Introduction
System-Wide UI Impact
Detailed Specification: Version 1
Detailed Specification: Version 2, simplified
Issues

Introduction

Manually surround a piece of code with a Java construct (if-else, try-catch, etc.) is time-consuming process. For a user, it means to jump to the beginning of the code, position the cursor right, type the code, jump to the end, position cursor, write a code. It certainly can be automated. Surround With feature should allow to surround statements easily.

References

Feature #35661: Surround selected code

System-Wide UI Impact

See detailed specifications for the eventual impact on menus.

Detailed Specification: Version 1

Surround With is an editor action to surround the selected block of code. To call the action one or more statements needs to be selected (if nothing is selected, action selects a statement in which the cursor lies).

It has a special the pop-up menu with possible constructs listed. Selected statements are surrounded with the chosen construct.

Pop-up Menu

Menu is aligned under or above the caret. It has centered title Surround With. Background and foreground color are taken from editor's defaults. Background color for title is taken from L&F default colors.

Keyboard

Down arrow, Up arrow, PgDn, PgUp, Home, End - navigates within menu
if the user types in a few characters that match the first characters of an item in the list, the item is highlighted
Enter, Spacebar - activates menu item
Esc - dismisses menu without taking action

Supported Constructs

Let's assume this "code" is selected:


    fis = new FileInputStream(fileName);
    ...

The following sections show generated block for that selected code. All supported constructs are listed. Added code is in

blue

; position of caret is also displayed.

try-catch

    try {
        fis = new FileInputStream(fileName);
        ...
    } catch (Exception e) {
        |
    }

try-catch-finally

    try {
        fis = new FileInputStream(fileName);
        ...
    } catch (Exception e) {
        |
    } finally {
    }

NOTE: If the try-catch or try-catch-finally construct is chosen, the IDE should detect which exceptions can be thrown in the selected code and automatically add them into the catch block. If no exception is thrown, try-finally block is generated.

try-finally

    try {
        fis = new FileInputStream(fileName);
        ...
    } finally {
        |
    }

if

    if (|) {
        fis = new FileInputStream(fileName);
        ...
    }

if-else

    if (|) {
        fis = new FileInputStream(fileName);
        ...
    } else {
    }

for

    for (|) {
        fis = new FileInputStream(fileName);
        ...
    }

while

    while (|) {
        fis = new FileInputStream(fileName);
        ...
    }

do-while

    do {
        fis = new FileInputStream(fileName);
        ...
    } while (|);

synchronize

    synchronized (|) {
        fis = new FileInputStream(fileName);
        ...
    }|

Runnable

    Runnable runnable = new Runnable() {
        public void run() {
            fis = new FileInputStream(fileName);
            ...
        }
    };|

NOTE: All local variables that are used from inside the wrapped block have to be re-declared as final (or new final local variables if the original ones are written to later).

{}

    {
        fis = new FileInputStream(fileName);
        ...
    }|

Action Appearance

Name and Shortcut

Name: Surround With...
Shortcut: Ctrl+Alt-S

Action is listed in editor's keybindings (Editor Settings -> Key Bindings):

Action Name:                             Keybinding:
-----------------------------------------------------
Surround With...  [surround-with]        Ctrl+Alt-S

Source Editor contextual menu

Considering current contextual menu, action is placed after the Reformat Code action:

...
----------------------------------------
Reformat Code...           Ctrl+Shift-F
Surround With...           Ctrl+Alt-S
----------------------------------------
...

Detailed Specification: Version 2, simplified

In case we want to support only try-catch block, the action described in version 1 can be simplified into the straightforward appearance (without popup menu).

Action Name: Surround With try-catch
Behavior: selected statements is directly surrounded by try-catch construct with appropriate exception filled.

Source Editor contextual menu

Considering current contextual menu, action is placed after the Reformat Code action:

...
----------------------------------------
Reformat Code...           Ctrl+Shift-F
Surround With try-catch      Ctrl+Alt-S
----------------------------------------
...

In the near future, editor's contextual menu will be revised and the action would be probably placed in a different order.
Additionally, it should be also placed in a main menu related to the code editing itself if it will be introduced eventually (See Editor Menus spec for suggested changes).