UEXInspectMembersAndHierarchies version1

Author: Petr Somol

Date: 22 JUN 2012

Version: 1.0 (work in progress! subject to change)

Note that this document is obsolete, for the current state see UEXInspectMembersAndHierarchies.

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 Navigator - 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 (for the new UI reuse the existing one whenever possible)

Summary - 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 now the most of the existing Navigator UI and not define a new tab-based UI (yet). In addition to changes inside Navigator the interaction with JavaDoc dockable window should be improved (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 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 or deleting a bookmarked view. The two combos will share the width of the remaining space in toolbar equally and will fill maximum available space. The left combo will play same role as before, allowing to change how the current entity is displayed - the combo to be denoted view type combo. The right combo will serve to choose view scope - either a live scope reacting to editor focus changes, or to choose bookmarked view. See Fig. 7.
  • 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.
  • bottom toolbar will offer more switches and actions
  • search bar would include label "Search:", text input field, Prev and Next buttons, and two checkboxes: "Filter", and "Match Case". 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).
Fig.7: Mockup of proposed Navigator window. Here illustrated with view type set to Members, view scope set to <focused file>, meaning that Navigator will show the main entity from the focused file (in editor or explorer view), whichever it is. This is the closest to former Navigator - Members View.

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.

Content change is triggered by

  • user change of view type
  • active file change in explorer view or in editor or change of caret position
  • user selection of bookmarked view
  • change in settings affecting the view

Rebuilding the view may be time consuming. As before, as long as the content is being prepared, the main pane should display the clock icon with message "Please wait.." exactly as it is done now in Navigator-Members View.

Interoperability with JavaDoc dockable window is as follows:

  • hovering over entity in Navigator shows JavaDoc popup as before, Ctr-F1 then opens JavaDoc window as before
  • single click on entity in Navigator updates JavaDoc window (if opened)

When decreasing Navigator width, the bottom toolbar may become too long to be displayed in entirety. TODO In such case add the on-hover-over little doublearrow to the right that would open a pop-up toolbar containing those icons that did not fit into the bottom toolbar.

TODO Add "Expand one level" and "Collapse one level" actions as buttons.

Navigator - View Types

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

Navigator - View Scope

TODO ..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.


Navigator View Type - Members

The Members view type replicates NB7.2 Navigator - Members View. See Fig.7.

Bottom Toolbar (Members)

The Members view type can be adjusted using buttons in bottom toolbar. Ordered as in Fig.7 these include:

  • Show inherited members
  • Show fields
  • Show methods
  • Show constructors
  • Show non-public members
  • Show static members
  • Show inner classes and interfaces
  • Show enum constants
  • Show fully qualified names (see Fig.10, note the grayed part of full names)
  • Sort by name
  • Sort by source

The default status of switches is shown in Fig.7.

Navigator View Type - Supertype Hierarchy

The Supertype Hierarchy view type replicates functionality of the NB7.2 Inspect Hierarchy dialog as if with enabled filter "Show supertype hierarchy". See Fig.8.

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

Bottom Toolbar (Supertype Hierarchy)

The Supertype Hierarchy view type can be adjusted using buttons in bottom toolbar. Ordered as in Fig.8 these include:

  • Show inner classes and interfaces
  • Show fully qualified names (see Fig.10, note the grayed part of full names)
  • Sort by name
  • Sort by source

Navigator View Type - Subtype Hierarchy

The Subtype Hierarchy view type replicates functionality of the NB7.2 Inspect Hierarchy dialog as if with enabled filter "Show subtype hierarchy". See Figs.9 and 10.

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

Bottom Toolbar (Subtype Hierarchy)

The Subtype Hierarchy view type can be adjusted using buttons in bottom toolbar. Ordered as in Fig.9 these include:

  • Show inner classes and interfaces
  • Show fully qualified names (see Fig.10, note the grayed part of full names)

Navigator View Type - Bean Pattern

No change, but allows new general functionality like participating in the bookmarking mechanism etc.

Navigator - Search

Search is applicable with any view type.

Fig.11: Mockup of proposed Navigator window. With focus in Navigator the user started typing the search term "icon"; this opened the search bar that is normally hidden.
Fig.12: Mockup of proposed Navigator window; same situation as in Fig. 11, here with additionally checked search option "Filter"

Navigator - User Configurations (Bookmarks)

The current state of Navigator view is defined by

  • the currently viewed entity
  • current view type
  • search string if exists and search options
  • all view-affecting switches in the bottom toolbar

The state should be possible to store and access later on demand as user "bookmark". Note that view scope only defines how and when Navigator view is to be changed, that it is not part of stored bookmark. Instead, view scope combo can be used to select bookmarks.

Fig.13: Mockup of proposed Navigator window; same as in Fig. 7, however the user has pressed the Add Bookmark icon. This resulted in storing the current view as user view configuration and selecting the respective item in view scope combo. This does not change the current view, but from now on 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. Deletion resets view scope to <focused file>

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 sorted into the bookmark block (items marked with bookmark icon), and it would become the selected choice in combo. Whenever a bookmark is selected in view scope combo, the Add Bookmark button would be disabled and Delete Bookmark button would be enabled. Whenever bookmark 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 Navigator window 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 stored 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. I.e, when switching back from a bookmark in view scope combo, Navigator UI is reconfigured to the default configuration (where any previous changes are remembered). In this sense the default view configuration is a bookmark as well.

Fig.14: Mockup of proposed Navigator window with four user bookmarked views. View scope combo shows user defined bookmarks under the two default scoping choices

Bookmarked view configurations are not persistent when NetBeans closes. (This may be reconsidered in future).

Navigator - Pop-Up menu

TODO..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

TODO what happens when cursor moves or selection is changed - what happens in Navigator and JavaDoc TODO..(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.. TODO..define persistence of views and filter switches..

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

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

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).

TODO: ensure that everything can be achieved through shortcuts only without mouse..

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