站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > NetBeans API Javadoc 4.1.0

Explorer API - NetBeans API Javadoc 4.1.0

Overview

Javadoc

The basic management of the Explorer resides in org.openide.explorer. Classes pertaining to the Property Sheet (which displays properties of explored nodes) may be found in org.openide.explorer.propertysheet. A set of standard Explorer Views is available in org.openide.explorer.view.

Contents

Explorer API

Overview of the Explorer

Explorer views are UI components which render nodes - the most prominent in NetBeans being the Project and Files tabs on the left side of the main window. The Explorer API provides UI components to render nodes in trees, lists, combo boxes, menus, tree tables. These components handle things like cut/copy/paste, drag and drop, displaying popup menus for nodes, which contain the actions the clicked node provides from getActions().

The Explorer and Nodes

An Explorer view is solely a user-interface component: it has no particular knowledge of what it is displaying. Rather, it provides the physical user interface for a hierarchy of Nodes, as described in the Nodes API.

A given Explorer view instance will be some visual component (such as a Swing panel) displaying some representation of a Node and its children. The topmost node being displayed is said to be the root of the Explorer.

The API permits you to use the prebuilt views, and also to create your own if you need to.

Using the Explorer API

It is rather easy to use the Explorer API to just display an Explorer window of some type, browsing some set of nodes.

Displaying a new Explorer window

Probably the easiest way to show an Explorer window is just to call NodeOperation.explore(...). This will simply show a node and its subtree (if any) in a new window using the normal tree-style Explorer view. It does not permit any customization of the UI, however - it creates a standard window with the usual buttons, etc.

If you want to use a special view, it is first necessary to understand the structure of a live Explorer instance:

  1. There is a topmost container, an AWT/Swing container component of any sort, which must implement ExplorerManager.Provider. Often in NetBeans it will be a subclass of TopComponent. This topmost container does not really do anything; it just makes sure that an ExplorerManager can be found by its children. Follow the instructions in ExplorerUtils, to create such a panel. The container that implements ExplorerManager.Provider may contain non-Explorer components - add whatever components you like to it, set layout appropriately. When an Explorer view is added as a descendant of this panel, it will find this panel by searching the component hierarchy. ExplorerManager itself handles the control of the Explorer view or views it is attached to. It provides the external interface by which the selection of nodes, e.g., can be examined or set, and permits multiple views to be synchronized (for example, creating a master/detail view is very easy).
  2. Usually, an ExplorerActions object will be attached to the manager to make sure that such things as cut/copy/paste actions are correctly enabled or disabled according to the current node selection. Typically, the topmost component will attach these actions to the manager when it is activated or otherwise given focus (and detach them when not). ExplorerPanel does this for you.
  3. Most importantly, the Explorer views themselves are added as (possibly indirect) children to the topmost component. You do not need to do anything special to connect the views to the manager or to one another; when an explorer view is added to a container, it will find the nearest ExplorerManager in the component hierarchy (by searching for a parent component that implements ExplorerManager.Provider).

    Once you have created an Explorer component, your code will not typically interact directly with it - rather it will call methods on its ExplorerManager to set selection, etc.

  4. Lastly you'll call ExplorerManager.setRootContext to actually set what node the view will be displaying.
org.openide.explorer.view contains a number of prebuilt views which you may use. Of special note are the BeanTreeView, which is the standard tree view used to implement the Explorer window proper; and MenuView, which is of interest because it actually implements a view using popup menus, rather than a static display. The best way to familiarize yourself with the standard views, and to test any custom view you might build, is probably to create an ExplorerPanel which adds some or all of them; the views will be automatically synchronized, which will be helpful in understanding how they behave.

Displaying a Property Sheet

Adding a Property Sheet (which just shows the properties of the selected node(s), and may allow editing of those properties) is quite easy - all you need to do is to add a PropertySheetView to the container. It is an Explorer view which does not actually display any nodes, but rather displays a list of properties for the node or nodes which are selected according to the ExplorerManager.

Since views by default will share the same manager if they are added to the same manager-providing container, just adding a regular Explorer view and a Property Sheet to the same container will result in the Property Sheet being sensitive to the node selection in the regular view, which is usually the desired effect.

Aspects of Nodes affecting the Explorer

Particular Explorer views are of course free to display the node hierarchy any way they wish; however, there are a few common aspects of the represented nodes which are likely to be visually mirrored: Though rarely necessary, the API allows you to create your own Explorer views, as described here.

The Property Sheet

Older versions of NetBeans relied heavily on the Property Sheet as a primary element of the user interface. However, this turned out not to be terribly user-friendly, and the Property Sheet is used considerably less today (it is no longer even displayed by default on startup).

Consider providing a custom UI where possible, rather than relying on the user having the Property Sheet visible to work with your module.

Customizing the Property Sheet

The Property Sheet displays property sets in expandable categories inside a single tree, rather than using tabs as the old Property Sheet did. However, there are some cases where tabs are desirable. A mechanism exists by which an instance of Node.PropertySet can specify that it should be displayed in a tab: It must return an internationalized string from PropertySet.getValue("tabName"). If multiple property sets belonging to a single node specify the same tab name in this manner, all of them will be included on a tab with the specified name*.

* Note that for this functionality to function properly, the NetBeans Window System must be installed. Further information on how to work use this functionality in a stand-alone application can be found here.
A number of system properties, UI manager keys and such also affect the way Property Sheets are displayed and behave. A complete reference can be found here.

Property Editors

The NetBeans core installs a variety of property editors for standard JDK classes and some NetBeans classes. A number of these can have their behavior altered by passing "hints" from Node.Property or PropertyDescriptor. This is described in detail here.
Built on May 4 2005.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.