netbeans Explorer API overview

资源管理器的基础管理功能都在org.openide.explorer

显示节点的属性定义表单在org.openide.explorer.propertysheet

标准的资源管理器视图在org.openide.explorer.view

Contents

• Overview of the Explorer
• Explorer Views and Nodes
• Using the Explorer
• Displaying a new Explorer window
• Displaying a Property Sheet
• Aspects of nodes affecting the Explorer
• Customizing the Explorer
• The Property Sheet
• Customizing the Property Sheet
• Property Editors

目录

l      资源管理器概况

n      资源管理器视图和节点

l      使用资源管理器

n      显示新的资源管理器窗口

n      显示一个属性表单

n      节点对资源管理器影响的方方面面

l      自定义资源管理器

l      属性表单

n      自定义属性表单

n      属性编辑器

Explorer API

资源管理器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().

资源管理器视图是显示节点的,是nb最突出的功能,以工程和文件活页出现在nb主窗口的左侧。资源管理器API提供用户界面控件把节点显示在树、列表、组合框、菜单和树表格（？）里。这些组件处理剪切、拷贝、粘贴以及拖拽，为节点显示弹出菜单，被点击的节点可以通过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.

资源管理器和节点

资源管理器视图是用户界面的组件，它根本就不知道它所表达的是什么，它为多层的节点提供了一个物理视图，节点在节点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.

一个资源管理器视图的实例往往是可见的控件（例如Swing的Panel），显示节点和和节点的子结点。最上层的节点是资源管理器的“根”节点

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

Api允许你使用预先定义的视图，你也可以在你需要的时候创建自定义的视图

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.

可以很简单的使用api来显示一个资源管理器窗口，查看一些节点

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:

最简单的方法就是NodeOperation.explore( Node )，这样会显示一个简单的，使用普通的树结构的资源管理器，在这个窗口中，显示参数Node中的节点和它的子结点。没有定制的用户界面，就仅仅生成一个标准的窗口和常用的按钮，等等。如果你想使用一个特殊的视图，你得明白一个资源管理器实例的结构：

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

每个资源管理器都有一个最顶端的容器：一个AWT/Swing的容器组件，这个组件实现ExplorerManager.Provider类，在nb中，我们可以继承TopComponent这个类。这个最顶的容器什么都不做，只是保证ExplorerManager可以被它的子得到。根据ExplorerUtils的说明，要生成这么一个Panel（前面说的容器？）。实现ExplorerManager.Provider的容器可以包含非资源管理器的组件，只要你愿意，设置正确的布局。当一个资源管理器视图被增加到这个容器后，资源管理器视图可以通过查找容器的包含关系找到这个最顶端的容器面板。ExplorerManager处理资源管理器视图，或它依附到的视图。它提供了内部接口，可以获取或设置选中的节点，允许多个视图的同步（例如，很容易的创建一个主、细节视图）

2. Usually, actions provided by ExplorerUtils, will be attached to the component to make sure they are correctly enabled or disabled according to the current node selection. Follow the example in ExplorerUtils.

通常，ExplorerUtils将操作依附到组件上，并且根据节点的选中情况来决定组件的可视状态。ExplorerUtils的例子

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.

重要的是：资源管理器视图（可能是间接的）是顶端视图的子，你不需要作任何事情将管理者（manager）和视图帮定，当一个资源管理器视图被增加到一个容器后，它会自己寻找最近的ExplorerManager（找到实现ExplorerManager.Provider的组件）。

当你创建一个资源管理器组件时，你的代码可能不直接和它交互，它会调用发现的ExplorerManager来设置选中的节点。

4. Lastly you'll call ExplorerManager.setRootContext to actually set what node the view will be displaying.

最后，你需要使用ExplorerManager.setRootContext设置你要显示的节点

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.

Org.openide.explorer.view包内包含了一些编写好的视图，特别的是BeanTreeView，实现了一个资源管理器窗口，这是一个标准的树视图；MenuView，很有意思，因为它实现了一个弹出菜单，而不是静态的显示菜单。你可以自己创建一个ExplorerPanel，增加上面这些组件来定制自己的视图。这些视图的内容是自动同步的，对弄清楚他们的工作机制是有帮助的。

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:

• The node's display name and short description ought to be used by views to display the node and provide (e.g.) tool tips.
• The icon is used in most views alongside the display name. Non-leaf nodes upon expansion will show the opened icon.
• Some or all of the node's children are typically displayed (except of course if it is a leaf). Normally they will be in the same order as the node itself specifies, though a view might provide special display characteristics for certain children lists such as Children.Keys. Generally nodes may allow their children to be reordered.
• Node.getActions(), Node.getContextActions(), Node.getDefaultAction(), Node.getContextMenu(), etc. are typically used to build an event-handling system for the visual representation of the nodes.
• Standard actions are generally enabled on nodes in the Explorer, so that Node.hasCustomizer(), Node.getLookup().lookup(...), Node.getNewTypes(), Node.getPasteTypes(...), and so on affect other UI components (such as toolbars) which may hold action presenters.
• Node.getPropertySets() is of course used by the Property Sheet view.
• Some views may provide in-place editing commands (not relying on system actions present in popup menus, e.g.) for moving nodes, renaming them in place, etc. - these will use the standard node hooks such as Node.canRename(), Node.cloneNode(), or Node.clipboardCut().

Customizing the Explorer

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 April 2 2007.  |  Portions Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.