UEXInspectMembersAndHierarchies

(Difference between revisions)
(Proposal for NetBeans 7.3)
(Excluded Functionality)
Line 200: Line 200:
=== Excluded Functionality ===
=== Excluded Functionality ===
-
The following functionality present in NB7.2 Inspect Members and Inspect Hierarchy is excluded from this proposal:
+
The following functionality, either present in NB7.2 Inspect Members and Inspect Hierarchy or not, is excluded from this proposal:
* the text field in bottom of dialogs displaying full entity name - this is not needed as the same is immediately accessible through JavaDoc preview on hover over
* the text field in bottom of dialogs displaying full entity name - this is not needed as the same is immediately accessible through JavaDoc preview on hover over
-
* ..enable multiple instances of the same view type to be opened at once.. (deferred until [[UEXTabReuse]] is sorted out)
+
* switches "Show private members", "Show protected members" and "Show package members" are joined to a single "Show non-private members" in order to reduce complexity of Members view bottom toolbar
 +
* enable multiple instances of the same view type to be opened at once is deferred until [[UEXTabReuse]] is sorted out

Revision as of 15:21, 22 June 2012

Date: 22 JUN 2012 Author: Petr Somol

(work in progress! subject to change)

See also: UEXJavaDoc, Java_MembersAndHierarchyPopup, TS_65_CallHierarchy.

Contents

Problem / Motivation

NetBeans 7.2 provides several tools allowing to inspect different types of hierarches and members: class members, call hierarchy, etc. These tools are spread in various contexts in various UI forms. These include the Navigator window diplayed by default docked to the left from editor window, then non-modal dialogs Inspect Memebers, Inspect File Members, Inspect Hierarchy, Inspect File Hierarchy, and a window Java Call Hierarchy that is by default placed under main editor window.

Users rightfully complain about the usability especially of the dialogs. The dialogs should enable quick inspection over various items in the displayed tree views, while viewing related details in sources and JavaDoc. The current implementation makes this difficult - it requires constant window focus switching what reduces the usability to such extent that some users refrain from using it at all.

A smoother user experience needs to be provided in order to enable users make the most of these tools at the cost of the least required usage effort.

Remark: the related JavaDoc panel redesign is proposed in UEXJavaDoc.

Current State (NetBeans 7.2)

Navigator - Members View

Fig.1: Navigator - Members View in NB72
Fig.2: Navigator - Members View, Search pops-up when typing, in NB72

Currently the most widely used tool in this context appears to be the Members View in Navigator panel (see Fig.1). Note that Navigator provides infrastructure for displaying various types of views, currently including Members View and Bean Patterns view, selectable by a combo aligned to the top of the Navigator window.

Members View lists (in tree view) the members of the class from the currently focused editor window. Recursively it lists also members of inner classes. The extent and ordering of the list is adjustable by switches, accessible in horizontal toolbar at the bottom of Members View pane. The toolbar is collapsable using a tiny arrow that appears when hovering over the upper toolbar edge. Switches available for Members View:

  • Show inherited members
  • Show fields
  • Show static members
  • Show non-public members
  • Sort by name
  • Sort by source

The view is mature in the sense that proper icons exist for all possible types of members, icons combine to visually express combined properties like private abstract enum etc., inherited members are distinguished by grayed text, deprecated members by strike over line, static members by a vertical line painted over member icon. The functionality of Members View is this:

  • single click selects the member, multiple members can be selected, then a right-click opens a menu with actions; some applicable to multiple selections, some not.
  • doubleclick opens entity in editor
  • hovering over entity shows first its complete name in case it is cropped by window border, shortly after that opens a pop-up JavaDoc window. The JavaDoc window disappears when mouse moved away from the respective intity. With JavaDoc pop-up window displayed, Ctrl-F1 opens the same content in docked JavaDoc window under the main editor area.

Members View supports Search for (sub)string in entity names (see Fig.2). With focus in Members View just start typing, this opens the Search text field. The first occurence of typed text at any position within entity highlights such entity. F3 allows to search for next. Pressing Esc or losing pane focus closes the Search pane.

Inspect Members & Inspect File Members

Fig.3: Inspect Members in NB72
Fig.4: Inspect Members with string filter and fully qualified names and inherited member display switched on in NB72

Inspect Members dialog can be invoked through Navigate->Inspect->Members or Navigate->Inspect->File Members or by right-click menus in various contexts

The difference between Members and File Members consists only in selecting the entity for which members are to be inspected. Inspect File Members refers to the whole file (effectively a class) either opened in editor or right-clicked in one of the explorer views. Inspect Members is equivalent to Inspect File Members in case no specific narrower focused entity is active either in one of explorer views or inside the source in active editor window. In case a narrower focused entity is active (typically when curret is placed inside the name of an investigable entity), the opened dialog inspects members of that particular entity.

The dialog (see Fig. 3) provides mainly a tree view of members similar to that in Navigator - Members View, but with more configuration options. The right half of dialog contains a JavaDoc pane to show JavaDoc text to the entity selected in the members tree view. The extent of the view can be reduced by specifying a required search string in Filter text line above the tree view and JavaDoc panes. Note that string matching is done from start of entity names. Below the main pair of panes a text field is used to display complete element signature of the currently selected item in tree view. Below it the following switches enable to restrict the extent or otherwise affect the appearance of the tree view as follows:

  • Show inherited members
  • Show fully qualified names
  • Show inner classes and interfaces
  • Show constructors
  • Show methods
  • Show fields
  • Show enum constants
  • Show protected members
  • Show package members
  • Show private members
  • Show static members

A doubleclick on entity opens it in editor window and closes the dialog. Multiple dialogs can be opened at once for various files/entities. Once the dialog is opened, its contents do not update. Once it is closed, there is no way of reopening it with previous contents. Switches persistence is global, each new dialog reuses the setting from the last one.

The difference to Navigator - Members View is in more options, switches allow finer specification what to view, fully qualified names can be displayed, the view can be restricted by string matching, and the dialog can be opened to show members of a given entity (Inspect Members) instead of just the members of the whole file (Inspect File Members). Navigator - Members View contents are always with respect to the whole file. But Navigator - Members View listens to file changes what the dialog does not.


Inspect Hierarchy & Inspect File Hierarchy

Fig.5: Inspect Hierarchy, Show supertype hierarchy switch on in NB72
Fig.6: Inspect Hierarchy, Show subtype hierarchy switch on in NB72

Inspect Hierarchy dialog (see Fig. 5) can be invoked through Navigate->Inspect->Hierarchy or Navigate->Inspect->File Hierarchy or by right-click menus in various contexts. The dialog shows the inheritance hierarchy with respect to the investigated entity; either as a tree of supertypes or as the reversed tree of subtypes (within the current limited scope).

The difference between Hierarchy and File Hierarchy consists only in selecting the entity for which hierarchy is to be inspected. Inspect File Hierarchy refers to the whole file (effectively a class) either opened in editor or right-clicked in one of the explorer views. Inspect Hierarchy is equivalent to Inspect File Hierarchy in case no specific narrower focused entity is active either in one of explorer views or inside the source in active editor window. In case a narrower focused entity is active (typically when curret is placed inside the name of an investigable entity), the opened dialog inspects hierarchy of that particular entity.

Inspect Hierarchy dialog UI is equivalent to that of Inspect Members dialog, with the main difference being in filter switches in the bottom. Inspect Hierarchy switches:

  • Show supertype hierarchy
  • Show subtype hierarchy
  • Show fully qualified names
  • Show inner classes and interface

and the last button in line of filters unfolds the whole tree view if any nodes are folded

Proposal for NetBeans 7.3

Based on user input and evaluation the redesign should aim at docking the Inspect Members and Inspect Hierarchy windows in the position of the Navigator window. This change will involve redesigning the features now present in Inspect Members and Hierarchy dialogs and aligning their UI with that of Members View, including all features that are not present in Members View.

The main improvements to be achieved are:

  • instant access to various views of Members and Hierarchies for either the selected file or entity in source, depending on where user selection or caret position is
  • keeping the views live and available at any time (till now the dialog-based solution is passive, the dialogs do not update their contents, and close as soon as entity is double-clicked to go to source)
  • enable storing view configurations ("bookmarking") - storing selected views for easy future access
  • achieve the above without consuming more screen space than before (realize the new UI as part of the existing one)

Improved Navigator window and JavaDoc window

Navigator window is to be modified to incorporate the former Inspect Members and Inspect Hierarchy functionality. Because there is still no agreement on sub-tab pinning and generic sub-tab behavior (see UEXTabReuse), the idea here is to reuse the most of the existing Navigator UI. In addition to changes inside Navigator the interaction with JavaDoc dockable window and the JavaDoc window itself should be improved (for details on proposed JavaDoc window changes see UEXJavaDoc).

The new Navigator window will closely resemble the original one, with the UI differences summarized as follows (details to be described in respective subsections):

  • instead of the single combo box in the top there will be a toolbar with two combos and two buttons; the two button on the right will enable bookmarking a view and deleting a bookmarked view, the two combos will share the width of the remaining space in toolbar equally. The left combo will be the same as before - to be denoted view type combo. The right combo will serve to choose view scope or particular bookmarked view. See Fig. 1.
  • the main view panel will look the same as now, showing the message "Please wait.." until content can be displayed, then the content will have the form of tree but the contents of the tree will depend on current view type and view scope.
  • the bottom toolbar with offer more switches and actions
  • the search bar would include label "Find:", the text input line, and two checkboxes: "case sensitive", and "filter". If checked, "filter" would hide all tree contents that do not match the search. Remark: the typed string should be searched for anywhere in entity names, not only from the beginning of name.
  • right-click menu will offer more choices. List of filters will be extended to support all those from the bottom toolbar + a selection of combined filters like "show all public entities only". Actions Inspect Members and Inspect Hierarchy should be applicable also through this menu to entities in tree view where it makes sense. Additionally it will provide actions "expand all" and "collapse all".
  • hovering over entity in displayed tree shows the JavaDoc preview as before (but updated according to UEXJavaDoc), single click on entity in displayed tree updates contents of docked JavaDoc window if it is opened, double-click "goes to source".
  • similarly to editor window behavior, Alt-Wheel Up or Down increases or decreases font size in tree view. This is very recommendable to compensate for the limited space in standard Navigator window size when compared to Inspect Members and Inspect Hierarchy dialogs. Consider defining Alt-WheelClick to reset default font size (both here and in editor).

Navigator - Default/general behavior

In situations when there is nothing to be displayed (no entity nor file is selected active in IDE), Navigator should display the same empty pane with <No View Available> message in the center as before.

..define interoperability with JavaDoc window (e.g., auto-open with inspect members/hierarchy?), single-click in members/inspect view should update JavaDoc contents etc., when should JavaDoc contents persist ? click in editor overrides click in hierarchy with respect to JavaDoc etc..

Navigator - View Types

Fig.7: Mockup of proposed Navigator window in Members View mode, with respect to focused file (source in editor), after user started typing to search for entities containing string "icon"

In situations when NB7.2 upper Navigator combo offered the choices Members View and Bean Patterns, the NB7.3 view type combo should offer:

  • Members - this will be the extended version of Members View
  • Supertype Hierarchy - this will come from Inspect Hierarchy dialog as if with enabled filter Show supertype hierarchy
  • Subtype Hierarchy - this will come from Inspect Hierarchy dialog as if with enabled filter Show subtype hierarchy
  • Bean Patterns - this will be the original Bean Patterns choice
Fig.8: Mockup of proposed Navigator window; same setup as in Fig. 7, here with checked search option "Filter"

Navigator - View Scope

..define handling of current File scope versus current entity ("under caret") scope. accordingly define persistence/lifecycle of view's contents.. ..define persistence of views and filter switches..

The view scope combo would contain two default non-deletable items:

  • <focused file> - this would mean that the displayed entity is the whole entity represented by currently focused editor window or by file selected in one of explorer views. Note that this choice represents the outcome of existing actions Inspect File Members (Ctrl-F12) and Inspect File Hierarchy (Alt-F12), and of NB7.2 Members View.
  • <focused entity> - in case the cursor is in a entity name in editor or such entity is otherwise selected, it is displayed. Otherwise this is equivalent to <focused file>. Note that this choice represents the outcome of existing actions Inspect Members (Ctrl-Shift-F12) and Inspect Hierarchy (Alt-Shift-F12).

In addition to the two default items the view scope combo would be allowed to grow by bookmarking.

Fig.10: Mockup of proposed Navigator window; view scope combo with the two default choices which make Navigator contents context dependent and three saved user configurations which, if selected, would be displayed in Navigator regardless editor context. Note however that if a user configuration is displayed, all Navigator UI is still enabled, i.e., it is possible to modify filters or view type etc; modifications are persistent for the user configuration

Whenever view scope combo choice is <focused file> or <focused entity>, the Add Bookmark button would be enabled and Delete Bookmark button would be disabled. The Add Bookmark button would store the current view and add it to view scope combo, where it would be added to the bottom, marked with bookmark icon, and it would become the selected choice in combo. Whenever such non-default choice is selected in view scope combo, the Add Bookmark button would be disabled and Delete Bookmark button would be enabled. Whenever a user-defined item is selected in view scope combo, all contents of Navigator panel remain fixed to display just the bookmarked view, i.e., Navigator contents would not change in reaction to other user actions in IDE like moving cursor or making other choices in explorer views etc. However, all actions still work in such view as expected. To switch back to a mode where Navigator contents depend on cursor or file selection, the user would need to select one of the two default view scope choices: <focused file> or <focused entity>. Note that when a different bookmarked view is selected, all Navigator settings get updated to the state when the bookmark was created (includes view type choice, status of switches, plus any string and choices in search bar). Note that the two default view scope choices share one configuration, different from the other bookmarked view configurations.

Navigator View Type - Members

Bottom Toolbar (Members)

..define filter availability and default status in various views..

Navigator View Type - Supertype Hierarchy

Fig.11: Mockup of proposed Navigator window with Supertype Hierarchy selected as view type. Note the changed bottom toolbar

Bottom Toolbar (Supertype Hierarchy)

..define filter availability and default status in various views..

Navigator View Type - Subtype Hierarchy

Fig.13: Mockup of proposed Navigator window with Subtype Hierarchy selected as view type. Note the changed bottom toolbar
Fig.14: Mockup of proposed Navigator window; the same view as in Fig. 13, but with fully qualified names switched on

Bottom Toolbar (Subtype Hierarchy)

..define filter availability and default status in various views..

Navigator View Type - Bean Pattern

No change, but allows new functionality like being part of bookmarked config etc.

Navigator - Search

applicable with any view type.. ..define Search bar in Inspect views.. ..define filter availability and default status in various views..

Navigator - User Configurations (Bookmarks)

..define persistence of views and filter switches..

The current state of Navigator view (the currently viewed entity, current view type, search string if exists, search options, and all filter switches in the bottom toolbar) will be possible to store and access on demand as user "bookmark" (view configuration). Note that view configuration is view scope dependent.

Fig.9: Mockup of proposed Navigator window; as in Fig. 7, however the search bar has been cleaned and thus disabled. Then the add bookmark icon (yellow star) has been pressed. This resulted in storing the current view as user view configuration and selecting the respective item in view scope combo. Note that now Navigator contents remain static, showing the selected user configuration, regardless which file or entity gets selected in editor or explorer view. Note that the current user configuration now can be deleted by delete bookmark icon (thrash bin). Deletion reverts view scope to <focused file>

Navigator - Pop-Up menu

..filters pop-up menu: various combined choices "non-private methods only", "fields only", "inner classes only" would set multiple switches at once; right-click in view on entities that are themselves viewable (inner classes, complex variable types) should open menu with additional actions allowing to "view members for this entity" which would do the same as if user opened the view for it in source. Also include actions "unfold all" and "fold all"..

Reaction to change in editor or explorer view

what happens when cursor moves or selection is changed - what happens in Navigator and JavaDoc ..(related to the preceeding) define when views should listen to what changes in editor and elsewhere and how to react (current dialogs do not listen). take into account possible diffeneces in view refresh cost across various view types.. ..define persistence of views and filter switches..

Effect of existing Inspect (File) Members and Inspect (File) Hierarchy Actions

what happens when (Ctrl-F12, Alt-F12, Ctrl-Shift-F12 and Alt-Shift-F12) is invoked and when and where ..define exactly what and when the current actions (Ctrl-Alt-F12 etc) do.. ..define persistence of views and filter switches..

Excluded Functionality

The following functionality, either present in NB7.2 Inspect Members and Inspect Hierarchy or not, is excluded from this proposal:

  • the text field in bottom of dialogs displaying full entity name - this is not needed as the same is immediately accessible through JavaDoc preview on hover over
  • switches "Show private members", "Show protected members" and "Show package members" are joined to a single "Show non-private members" in order to reduce complexity of Members view bottom toolbar
  • enable multiple instances of the same view type to be opened at once is deferred until UEXTabReuse is sorted out
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo