HOME / Docs & Support / NetBeans 6.0 / Basic IDE Documentation

Introduction to the Swing Application Framework

This guide is an introduction to the support in NetBeans IDE 6.0 for the Swing Application Framework.

Contents

Content on this page applies to NetBeans IDE 6.0 and 6.1

Introduction: Swing Application Framework in NetBeans IDE 6.0
Creating an Application
Creating and Configuring Actions
Managing Resources
Sample Framework Projects

To follow this tutorial, you need the following software and resources.

Software or Resource	Version Required
NetBeans IDE	version 6.1 or version 6.0
Java Developer Kit (JDK)	version 6 or version 5

Introduction: Swing Application Framework in NetBeans IDE 6

The Swing Application Framework is a light framework that simplifies the creation and maintaining of small- to medium-sized Java desktop applications. The framework consists of a Java class library that supports constructs for things such as the following:

Remembering state between sessions.
Easier managing of actions, including running as background tasks and specifying blocking behavior.
Enhanced resource management, including resource injection for bean properties.

The IDE supports the development of applications based on the Swing Application Framework in the following ways:

Providing the Java Desktop Application project template, which contains skeleton implementations of the main framework features. This template enables you to choose from the follow two shells:
- Basic Application. Provides a basic frame, some sample menu items, status bar, and mechanisms for managing actions and resources.
- Database Application. Provides all of the features in the Basic Application shell plus all of the features necessary for a simple database application with create, read, update, and delete features. See Building a Java Desktop Database Application for an example of how this shell can be used.
Integration of framework features in the IDE's GUI Builder. Swing Application Framework applications can be designed in the IDE like any other Swing application.
Generating your application's UI text and other resources in .properties files.
Providing a special property editor for actions in which you can associate an action with keyboard accelerators, text, and a tooltip. In addition, you can configure properties for when it is selected or enabled and you can set the action to run asynchronously.
Automatically packaging the Swing Application Framework library into your project's dist/lib folder when you build your application in the IDE.

Note: The NetBeans Platform can also be used as an application framework. The main difference between the Swing Application Framework and the NetBeans Platform in this regard is scope. The Swing Application Framework is more lightweight and easier to get started with. The NetBeans Platform is more full-featured and better suited for large and extensible applications. For more information on developing applications based on the NetBeans Platform, see NetBeans Platform Learning Trail.

Creating an Application Based on the Swing Application Framework

To best take advantage of the IDE's support for the Swing Application Framework, you need to use the Java Desktop Application project template.

To create a new Swing Application Framework application:

Choose File > New Project.
Select the Java category and select the Java Desktop Application template. Click Next.
In the Name and Location page of the wizard, fill in the necessary fields.

If you select the Basic Application shell, you can click Finish to create the project on your computer and open the project in the Projects window and the Files window.

If you select the Database Application shell, click Next to specify the database table and the configuration of the master/detail view of the database.

The generated files include:

An application class that includes the main() method, the framework's startup method, and some other utility methods. This class extends the frameworks SingleFrameApplication class.
A view class that serves as the application's main window. This class extends the framework's FrameView class and encapsulates a JPanel. This class is editable in the GUI Builder.
A sample About window for the application.
.properties files to hold the application's resources.

Creating and Configuring Actions

The Swing Application Framework provides support to help you define and manage actions.

To quote from the Java Tutorial, "An Action object is an action listener that provides not only action-event handling, but also centralized handling of the state of action-event-firing components such as tool bar buttons, menu items, common buttons, and text fields. The state that an action can handle includes text, icon, mnemonic, enabled, and selected status."

In the framework, you use the &Action annotation to mark the method that serves as the implementation of the Action's actionPerformed method. The framework then uses that method to perform the given action. You can also specify various attributes for the action that determine things such as the enabled state of the action, the action's blocking behavior, and whether the action runs in the background.

In the IDE, you can use Set Action dialog box to generate code for actions, including the annotation and any attributes. In the Set Action dialog box, you can do the following:

Set a component to use an action.
Create skeleton actions.
Configure user interface properties for the action, such as the name to appear on the visual component, tool tip text, icons, and the keyboard shortcut.
Create a Boolean property to determine whether the action is enabled.
Create a Boolean property to determine whether the action is selected. (This only applies to non-menu components that have a selected property, such as radio buttons.)
Set an action to run as a background task.
Configure an action to block other actions until it completes.

To open the Set Action dialog box, do one of the following things:

Right-click a component and choose Set Action.
Select a component and click the ellipsis (...) button next to its action property in the Properties window.

The Set Action dialog box consists of the following fields:

Set Action Property Using. Enables you to select from different property editors to set the action property. The choices are the following:
- Default editor. Provides visual support for taking generating code that is based on Swing Application framework features.
- Value From Existing Component. Enables you to specify a component from which to derive the property's value.
- Custom Code. Provides a text area for you to manually write the code for setting the property.
This help topic only covers the options in the default editor.
Action. Select an action from combo box to assign to the component.
Only methods that have the @Action annotation are listed in the combo box. If you have a method that you want to use that does not have this annotation, exit the dialog box and add that annotation to the method.

If you have not yet written a method for the action, select Create New Action. This enables you to enter a method name in the Action's Method field. Also be sure to fill in the Text field with the text that you want to appear on the component. When you click OK to exit the dialog box, a skeleton action is created for you.

Note: When you assign an action to a component, that component's text, toolTipText, and icon properties are set according to what you have entered in the Set Action dialog box. If you have previously set these properties for the component, they will be replaced by what is specified in the Set Action dialog box. However, you can return to the property sheet for the component and customize the values that you want for that component. In the running application, the component-specific properties will be used.
Action's Class. If you are creating a new action, use this combo box to select the class in which to place the action.
Action's Method. If you are creating a new action, use this text field to name the action method to be generated.
Background Task. If selected, the action is run in the background. This is useful if the action might take a long time to complete and you want the user to be able to do other things in the UI while the action completes.
Attributes, Basic Tab:
- Text. Type the text that you want to be used for the action in visual components, such as buttons and menu items.
- Tool Tip. Type any text that you would like to appear when the user mouses over any components associated with the action.
- Accelerator. Provide a keyboard shortcut for the action. To specify the shortcut you want to use, select the Letter field and type the shortcut as you would when using the shortcut. The checkboxes for any modifier keys that you use, such as Ctrl and Shift, are selected automatically.
- Icon. If desired, associate icons for the action. Use the Small Icon and Large Icon buttons to navigate to the icons that you want to use.
Attributes, Advanced Tab:
- Enabled Property. If desired, select a Boolean bean property, the value of which determines whether the action is enabled or not. If you have not yet created such a property, type a name for the property in the text field. After you click OK to exit the dialog box, a skeleton property will be created for you.
- Selected Property. If desired, select a Boolean bean property, the value of which determines whether the action is selected or not. This option only applies to components that have a selected bean property, such as JRadioButton and JToggleButton. After you click OK to exit the dialog box, a skeleton property will be created for you.
- Blocking Type. Enables you block user interaction with the user interface while a task is completing. The choices in the drop-down list enable you to set the level at which the blocking applies. For example, you can block the whole application or just a window or component. Blocking types only apply to actions that you have specified as background tasks.
- Blocking Dialog Title. Specify a title for the dialog box that appears to warn the user that a task is not yet completed.
- Blocking Dialog Message. Specify text to show in the dialog box that appears to warn the user that a task is not yet completed.

Notes:

By default, resources for the action are stored in a .properties file that has the same name as the action's .java file. The property keys are derived from the action name. The affected attributes are text, tooltip, accelerator, small icon, large icon, blocking title, and blocking message.
You can get an overview of all of the actions in your project in the Application Actions window. Open the Applications Window by choosing Window > Other > Application Actions.

Managing Resources

The Swing Application Framework simplifies the handling of resources in applications and makes it possible for more things to be stored in resource bundles.

When we speak of resources, we refer to objects that are used by the application but which are not in the .java files. Common resources in Java programs include image files and databases. You can also treat other objects as resources, such as strings, colors, and fonts. Treating strings as resouces makes it much easier to localize an application. Treating other objects as resources makes it possible to change the values of those objects without changing the .java code and rebuilding the application.

A typical Swing Application Framework application has resource bundles at both the application level and the class level. The class-level resource bundles have the same names as their corresponding .java classes except that they contain the .properties extension. All of these bundles are encapsulated by a ResourceMap object.

You can edit some standard application level resources (such as application name) in the Project Properties dialog box. Any application-level resources not included in the Project Properties dialog box (such as resources that you define yourself) can be edited in the the .properties file that corresponds with the name of the main application class.

You can open the Project Properties dialog box by right-clicking the project's node and choosing Properties. Application properties appear in the Application panel and the Desktop Application panel.

When you start an application from the Java Desktop Application project template, by default your code is generated with the Swing Application Framework's conventions for managing resources, such as UI text. The values of component properties that you set are stored as resources as well.

You can configure the way that code is generated to handle resources.

To set how configuration code is generated for a given form:

Open the form and switch to the Design view.
Select the root form node in the Inspector window.
In the Properties window, select one of the following from the Automatic Resource Management drop-down list.
- Off. All property values are hard-coded in the .java file.
- Internationalization. Resource code is generated for all strings, and the string values are stored in a .properties file.
- All Resources. Resource code is generated for all strings, colors, fonts, and icons. The values for these properties are stored in a .properties file.
- Resources + Injection. Code is generated so that resource values are injected into the application from .properties files at runtime.

If you do not want the value for a specific property to be stored in a .properties file, click the ellipsis (...) button next to the given property in the Properties window. Then clear the Define as Resource property.

Sample Framework Projects

If you want to see examples of how the framework works, you can browse some framework-based sample projects in the IDE. Both the Mars Rover Viewer and Document Editor use the Swing Application Framework. These examples are based on two of the examples that come with the Swing Application Framework library. However, they have been re-created using the IDE's GUI Builder, so you can play with them using the IDE's visual design tools.

To open one of these samples in the IDE: