net.sf.jguiraffe.gui.app

Class OpenWindowCommand

java.lang.Object

net.sf.jguiraffe.gui.cmd.CommandBase

net.sf.jguiraffe.gui.app.OpenWindowCommand

All Implemented Interfaces:

ApplicationClient, Command

Direct Known Subclasses:

OpenViewSettingsDlgCommand

public class OpenWindowCommand
extends CommandBase
implements ApplicationClient

A specialized Command implementation for opening a sub window.

This Command class provides functionality for opening sub frames or dialog boxes. An instance is initialized with the Locator to the builder script that defines the window. It executes this script in the worker thread and eventually displays the resulting window.

Most applications need to open dialog boxes or other sub windows. With this command this can be done in a standard way. Using CommandActionTask an instance can be associated with an action. It is possible to define such an action completely in a builder script using the dependency injection framework. This can look as follows:

 <!-- Definition of the command bean for opening a dialog -->
 <di:bean name="openDialogCommand" singleton="false"
   beanClass="net.sf.jguiraffe.gui.app.OpenWindowCommand">
   <di:constructor>
     <di:param>
       <di:bean class="net.sf.jguiraffe.locators.ClassPathLocator">
         <di:factory>
           <di:methodInvocation method="getInstance">
             <di:param value="myDialog.jelly"/>
           </di:methodInvocation>
         </di:factory>
       </di:bean>
     </di:param>
   </di:constructor>
 </di:bean>
 <!-- The command task used by the action for opening a dialog -->
 <di:bean name="openDialogTask"
   beanClass="net.sf.jguiraffe.gui.app.CommandActionTask">
   <di:setProperty property="commandBeanName"
     value="openDialogCommand"/>
   <di:setProperty property="beforeEnabler">
     <di:bean beanClass="net.sf.jguiraffe.gui.builder.enablers.ActionEnabler">
       <di:constructor>
         <di:param value="openDialogAction"/>
       </di:constructor>
     </di:bean>
   </di:setProperty>
 </di:bean>
 <!-- The action for opening a dialog -->
 <a:action name="openDialogAction" text="Open dialog..."
   taskBean="openDialogTask"/>
 

This fragment first defines the OpenWindowCommand bean. The bean is passed a newly created Locator object when it is constructed. Here a locator implementation is used that searches the builder script in the class path. It follows the definition of the action task bean. This is a CommandActionTask which is configured with our command bean. Note that also an action enabler is specified; this object disables the action while it is executed. Finally the action itself is defined. It references the task bean. The action can later be used to create a menu item or a button in a tool bar.

Version:

$Id: OpenWindowCommand.java 205 2012-01-29 18:29:57Z oheger $

Author:

Oliver Heger

Constructor Summary

Constructors

Constructor and Description
OpenWindowCommand(Locator loc) Creates a new instance of OpenWindowCommand and initializes it with the Locator pointing to the builder script.

Method Summary

Modifier and Type	Method and Description
void	execute() Executes this command.
Application	getApplication() Returns the central Application instance.
Locator	getLocator() Returns the Locator to the builder script executed by this command.
protected void	performGUIUpdate() Updates the UI after background processing is complete.
protected void	prepareBuilderData(ApplicationBuilderData builderData) Prepares the ApplicationBuilderData object.
void	setApplication(Application app) Sets the central Application instance.

Methods inherited from class net.sf.jguiraffe.gui.cmd.CommandBase

getException, getGUIUpdater, getLog, isUpdateGUI, onException, onFinally, setException

Methods inherited from class java.lang.Object

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

Constructor Detail

OpenWindowCommand

public OpenWindowCommand(Locator loc)

Creates a new instance of OpenWindowCommand and initializes it with the Locator pointing to the builder script. The command will execute this builder script and display the resulting window.

Parameters:

loc - the Locator to the builder script (must not be null)

Throws:

IllegalArgumentException - if the Locator is null

Method Detail

getLocator

public final Locator getLocator()

Returns the Locator to the builder script executed by this command.

Returns:

the Locator

getApplication

public final Application getApplication()

Returns the central Application instance.

Returns:

the Application

setApplication

public final void setApplication(Application app)

Sets the central Application instance. From this object the ApplicationContext is obtained, which provides access to the builder. This method is typically called by the dependency injection framework.

Specified by:

setApplication in interface ApplicationClient

Parameters:

app - the central Application object

execute

public void execute()
             throws Exception

Executes this command. This implementation calls the builder to execute the builder script defining the window to be opened. Then the window is actually displayed.

Note: This method does not implement a sophisticated exception handling. It expects the current Locator to be valid and to point to a builder script that actually returns a window. Otherwise, an exception is thrown which will be passed to the onException() method.

Specified by:

execute in interface Command

Throws:

Exception - if an error occurs

performGUIUpdate

protected void performGUIUpdate()

Updates the UI after background processing is complete. This implementation opens the window created in the background thread unless an exception occurred before.

Overrides:

performGUIUpdate in class CommandBase

prepareBuilderData

protected void prepareBuilderData(ApplicationBuilderData builderData)

Prepares the ApplicationBuilderData object. This method is called by execute() with the ApplicationBuilderData object obtained from the ApplicationContext. Derived classes can override it to perform custom initialization. This base implementation is empty.

Parameters:

builderData - the ApplicationBuilderData object to be initialized