Package org.jdesktop.application

# Class SingleFrameApplication

java.lang.Object
org.jdesktop.application.AbstractBean
org.jdesktop.application.Application
org.jdesktop.application.SingleFrameApplication

public abstract class SingleFrameApplication extends Application
An application base class for simple GUIs with one primary JFrame.

This class takes care of component property injection, exit processing, and saving/restoring session state in a way that's appropriate for simple single-frame applications. The application's JFrame is created automatically, with a WindowListener that calls exit() when the window is closed. Session state is stored when the application shuts down, and restored when the GUI is shown.

To use `SingleFrameApplication`, one need only override `startup`, create the GUI's main panel, and apply `show` to that. Here's an example:

    class MyApplication extends SingleFrameApplication {
        @Override protected void startup() {
            show(new JLabel("Hello World"));
        }
    }

The call to `show` in this example creates a JFrame (named "mainFrame"), that contains the "Hello World" JLabel. Before the frame is made visible, the properties of all of the components in the hierarchy are initialized with `ResourceMap.injectComponents` and then restored from saved session state (if any) with `SessionStorage.restore`. When the application shuts down, session state is saved.

A more realistic tiny example would rely on a ResourceBundle for the JLabel's string and the main frame's title. The automatic injection step only initializes the properties of named components, so:

     class MyApplication extends SingleFrameApplication {
         @Override protected void startup() {
             JLabel label = new JLabel();
             label.setName("label");
             show(label);
         }
     }

The ResourceBundle should contain definitions for all of the standard Application resources, as well the main frame's title and the label's text. Note that the JFrame that's implicitly created by the `show` method is named "mainFrame".

     # resources/MyApplication.properties
     Application.id = MyApplication
     Application.title = My Hello World Application
     Application.version = 1.0
     Application.vendor = Illya Yalovyy
     Application.vendorId = Etf
     Application.homepage = http://kenai.com/projects/bsaf
     Application.description =  An example of SingleFrameApplication
     Application.lookAndFeel = system
     Application.icon=app_icon.png

     mainFrame.title = ${Application.title} ${Application.version}
     label.text = Hello World

## Nested Class Summary

## Nested classes/interfaces inherited from class org.jdesktop.application.Application

`Application.ExitListener`

## Field Summary

### Fields inherited from class org.jdesktop.application.Application

`KEY_APPLICATION_ICON, KEY_APPLICATION_TITLE, KEY_APPLICATION_VENDOR_ID, ready`

## Constructor Summary

Constructors
Constructor
Description
`SingleFrameApplication()`

## Method Summary

Modifier and Type
Method
Description
`protected void`
`configureWindow(Window root)`
Initialize the hierarchy with the specified root by injecting resources.
`protected void`
`end()`
Called by `exit` to terminate the application.
`final JFrame`
`getMainFrame()`
Return the JFrame used to show this application.
`FrameView`
`getMainView()`
Gets the main view of the application
`protected final void`
`setMainFrame(JFrame mainFrame)`
Sets the JFrame use to show this application.
`protected void`
`show(JComponent c)`
Show the specified component in the `main frame`.
`void`
`show(JDialog c)`
Initialize and show the JDialog.
`void`
`show(JFrame c)`
Initialize and show the secondary JFrame.
`void`
`show(View view)`
Shows the application `View`
`protected void`
`shutdown()`
Save session state for the component hierarchy rooted by the mainFrame.

### Methods inherited from class org.jdesktop.application.Application

`addExitListener, exit, exit, getContext, getExitListeners, getInstance, getInstance, handleQuit, hide, initialize, isReady, launch, quit, ready, removeExitListener, startup`

### Methods inherited from class org.jdesktop.application.AbstractBean

`addPropertyChangeListener, addPropertyChangeListener, firePropertyChange, firePropertyChange, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### SingleFrameApplication

public SingleFrameApplication()

## Method Details

### getMainFrame

public final JFrame getMainFrame()
Return the JFrame used to show this application.

The frame's name is set to "mainFrame", its title is initialized with the value of the `Application.title` resource and a `WindowListener` is added that calls `exit` when the user attempts to close the frame.

This method may be called at any time; the JFrame is created lazily and cached. For example:

     protected void startup() {
         getMainFrame().setJMenuBar(createMenuBar());
         show(createMainPanel());
     }

Returns:
  this application's main frame
See Also:
  - `setMainFrame(javax.swing.JFrame)`
  - `show(javax.swing.JComponent)`
  - `Component.setName(java.lang.String)`
  - `Frame.setTitle(java.lang.String)`
  - `Window.addWindowListener(java.awt.event.WindowListener)`

### setMainFrame

protected final void setMainFrame(JFrame mainFrame)
Sets the JFrame use to show this application.

This method should be called from the startup method by a subclass that wants to construct and initialize the main frame itself. Most applications can rely on the fact that {code getMainFrame} lazily constructs the main frame and initializes the `mainFrame` property.

If the main frame property was already initialized, either implicitly through a call to `getMainFrame` or by explicitly calling this method, an IllegalStateException is thrown. If `mainFrame` is null, an IllegalArgumentException is thrown.

This property is bound.

Parameters:
  `mainFrame` - the new value of the mainFrame property
See Also:
  - `getMainFrame()`

### configureWindow

protected void configureWindow(Window root)
Initialize the hierarchy with the specified root by injecting resources.

By default the `show` methods `inject resources` before initializing the JFrame or JDialog's size, location, and restoring the window's session state. If the application is showing a window whose resources have already been injected, or that shouldn't be initialized via resource injection, this method can be overridden to defeat the default behavior.

Parameters:
  `root` - the root of the component hierarchy
See Also:
  - `ResourceMap.injectComponents(java.awt.Component)`
  - `show(JComponent)`
  - `show(JFrame)`
  - `show(JDialog)`

### show

protected void show(JComponent c)
Show the specified component in the `main frame`. Typical applications will call this method after constructing their main GUI panel in the `startup` method.

Before the main frame is made visible, the properties of all of the components in the hierarchy are initialized with `ResourceMap.injectComponents` and then restored from saved session state (if any) with `SessionStorage.restore`. When the application shuts down, session state is saved.

Note that the name of the lazily created main frame (see `getMainFrame`) is set by default. Session state is only saved for top level windows with a valid name and then only for component descendants that are named.

Throws an IllegalArgumentException if `c` is null

Parameters:
  `c` - the main frame's contentPane child

### show

public void show(JDialog c)
Initialize and show the JDialog.

This method is intended for showing "secondary" windows, like message dialogs, about boxes, and so on. Unlike the `mainFrame`, dismissing a secondary window will not exit the application.

Session state is only automatically saved if the specified JDialog has a name, and then only for component descendants that are named.

Throws an IllegalArgumentException if `c` is null

Parameters:
  `c` - the main frame's contentPane child
See Also:
  - `show(JComponent)`
  - `show(JFrame)`
  - `configureWindow(java.awt.Window)`

### show

public void show(JFrame c)
Initialize and show the secondary JFrame.

This method is intended for showing "secondary" windows, like message dialogs, about boxes, and so on. Unlike the `mainFrame`, dismissing a secondary window will not exit the application.

Session state is only automatically saved if the specified JFrame has a name, and then only for component descendants that are named.

Throws an IllegalArgumentException if `c` is null

Parameters:
  `c` -
See Also:
  - `show(JComponent)`
  - `show(JDialog)`
  - `configureWindow(java.awt.Window)`

### shutdown

protected void shutdown()
Save session state for the component hierarchy rooted by the mainFrame. SingleFrameApplication subclasses that override shutdown need to remember call `super.shutdown()`.

Overrides:
  `shutdown` in class `Application`
See Also:
  - `Application.startup()`
  - `Application.ready`
  - `Application.exit()`
  - `Application.addExitListener(org.jdesktop.application.Application.ExitListener)`

### getMainView

public FrameView getMainView()
Gets the main view of the application

Returns:
  the main view of the application

### show

public void show(View view)
Description copied from class: `Application`
Shows the application `View`

Overrides:
  `show` in class `Application`
Parameters:
  `view` - - View to show
See Also:
  - `View`

### end

protected void end()
Description copied from class: `Application`
Called by `exit` to terminate the application. Calls `Runtime.getRuntime().exit(0)`, which halts the JVM.

Overrides:
  `end` in class `Application`
See Also:
  - `Application.exit()`