DRAFT: NetBeans Visual Library Widget Creation Tutorial

In this tutorial, you will learn about a different approach to creating widgets in Visual Library scenes. Other approaches are described in other tutorials:

NetBeans Visual Library Tutorial. In this introductory tutorial to the Visual Library, you are shown how widgets can be created when the user drags-and-drops an item from the Component Palette.
NetBeans Visual Database Explorer Tutorial. In this tutorial, you are shown how widgets can be created from tables in a database via a database connection in the Services window.
NetBeans Visual Library Tutorial for Java Applications. In this tutorial aimed at general Java SE applications, you are shown how widgets can be generated from the constructor of a NetBeans Visual Library Scene class.

In this tutorial, widgets are created in a slightly different way, more common to typical Visual Library scenarios. When the user clicks in a scene, a dialog will appear, where the user can specify certain attributes of the widget, after which the widget itself will be created. In other words, in contrast to the above tutorials, widgets will be created on-demand, that is, when the user requires them, when clicking in the scene, that is, without using the Component Palette.

All the information you need to know for working with the Visual Library API is collected at these two locations:

Setting Up the Application

In this section, we use wizards to create a module project and a custom window component.

Choose File > New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules. Under Projects, select NetBeans Platform Application. Click Next.

In the Name and Location panel, type DemoToolVisualizer as the name of the application. Click Finish.

Choose File > New Project (Ctrl+Shift+N). Under Categories, select NetBeans Modules. Under Projects, select Module. Click Next.

In the Name and Location panel, type ToolVisualizerSample in the Project Name field. Change the Project Location to any directory on your computer. Set the DemoToolVisualizer as the suite to which you will add your module. Click Next.

In the Basic Module Configuration panel, type org.netbeans.demo in Code Name Base.

Select "Generate XML Layer". Leave the locations of both the localizing bundle and the XML layer file so that they will be stored in a package with the name org/netbeans/demo . Click Finish.

The IDE has created an application containing a single module. The application contains all of your sources and project metadata, such as the project’s Ant build script. The project opens in the IDE. You can view its logical structure in the Projects window (Ctrl+1) and its file structure in the Files window (Ctrl+2).

Now we need to set some dependencies.

Right-click the project, choose Properties, click Libraries in the Project Properties dialog box and declare a dependency on the following APIs:
- Visual Library API
- Utilities API

Click OK.

Creating the Window

In this section, we use a wizard to create a custom window component.

Right-click the module project, choose New > Other and choose Window from the Module Development category. Click Next.

Choose editor in the drop-down list and select Open on Application Start. Click Next.

1. Type ToolVisualizer in Class Name Prefix. Optionally, add an icon with a dimension of 16x16 pixels. Click Finish.

Multiple files are generated, one of them is ToolVisualizerTopComponent . Open this file in Design mode. You should now see this:

Right-click in the TopComponent in Design mode, choose Set Layout, and select BorderLayout.

Creating the Scene

Programming with the Visual Library API is similar to programming in Swing. You build and modify a tree of visual elements that are called "widgets". The root of the tree is represented by a Scene class which holds all the visual data of the scene. The scene is a widget. You have to create a scene view, which is a JComponent. You must then add the JComponent to a JScrollPane.

In this section, we add a JScrollPane to our TopComponent. Then we create a new scene. Next, we pass the scene view to the TopComponent, so that it can be displayed in the TopComponent’s JScrollPane. We then install the module project and display our first scene.

Use the Palette (Ctrl-Shift-8) to drop a JScrollPane on the TopComponent. In the Inspector, right-click the JScrollPane , choose Change Variable Name and type shapePane .

Create a Scene in the window, as follows:

private final Scene scene;
private final LayerWidget layer;

public ToolVisualizerTopComponent() {

    ...
    ...
    ...

    scene = new Scene();

    layer = new LayerWidget(scene);
    scene.addChild(layer);

    scene.getActions().addAction(ActionFactory.createPopupMenuAction(new PopupMenuProvider() {
        public JPopupMenu getPopupMenu(Widget widget, Point localLocation) {
            JPopupMenu popup = new JPopupMenu();
            popup.add(new WidgetMenuItem(scene,"Hammer", localLocation));
            popup.add(new WidgetMenuItem(scene,"Saw", localLocation));
            return popup;
        }
    }));

    jScrollPane1.setViewportView(scene.createView());

}

class WidgetMenuItem extends JMenuItem {

    public WidgetMenuItem(final Scene scene, final String type, final Point loc) {
        super(type);
        addActionListener(new ActionListener() {
            @Override
            public void actionPerformed(ActionEvent e) {
                NotifyDescriptor.InputLine desc =
                        new NotifyDescriptor.InputLine(
                        "Description:","Create a " + type) ;
                DialogDisplayer.getDefault().notify(desc);
                ToolWidget widget = new ToolWidget(
                        scene,
                        type,
                        desc.getInputText(),
                        loc);
                layer.addChild(widget);
                scene.validate();
            }
        });
    }

}

class ToolWidget extends LabelWidget {

    public ToolWidget(Scene scene, String type, String description, Point loc) {
        super(scene);
        setLabel(type + " (" + description + ")");
        setPreferredLocation(loc);
        getActions().addAction(ActionFactory.createMoveAction());
    }

}

Run the application.

Congratulations, you have completed your first Visual Library scene.

Send Us Your Feedback

Apache NetBeans 23

DRAFT: NetBeans Visual Library Widget Creation Tutorial

Setting Up the Application

Creating the Window

Creating the Scene

Next Steps