org.salespointframework.core
Class FormSheet

java.lang.Object
  extended by org.salespointframework.core.FormSheet
Direct Known Subclasses:
AbstractJavaDBConnection.JavaDBConfigurationFS, DataExchangeFormSheet, DescriptiveFormSheet, ListViewFormSheet, LogOnForm, LogTableForm, MessageForm.MessageFormSheet, MsgForm, SingleTableFormSheet, TextInputForm, UserTableFormSheet

public class FormSheet
extends java.lang.Object

A FormSheet to be displayed in a FormSheetContainer.

FormSheets comprise a caption, a JComponent of arbitrary complexity, and a button bar. FormSheets will be displayed by FormSheetContainers, which define what the FormSheet finally looks like on the screen. Usually, the FormSheet's caption will become part of the FormSheetContainer's frame caption; the FormSheet's component will take up most of the client space of the FormSheetContainer's frame; and the button bar will be displayed at the bottom side of the FormSheetContainer's frame.

However, FormSheets are designed to make transparent the final display of the GUI, and, thus, you as an application developer do not need to worry about the final layout. All you need to know is what components you want to present and which buttons you want to put into the button bar. Buttons in the button bar are associated an Action that will be performed when the button is clicked. In the doAction() method of that Action, you will have access to the SalesPoint and SaleProcess in whose context the FormSheet is displayed, if any. There is also a special ActionListener, ActionActionListener, that you can use to associate any button in a FormSheet with an Action.

To actually display a FormSheet, you need a Display on which you can call Display.setFormSheet(org.salespointframework.core.FormSheet) or Display.popUpFormSheet(org.salespointframework.core.FormSheet).

Since:
v1.0
Version:
4.0
Author:
Steffen Zschaler

Nested Class Summary
static class FormSheet.FormButton
          A button in the FormSheet's button bar.
 
Field Summary
static int BTNID_CANCEL
          Button ID used for the standard Cancel button.
static int BTNID_OK
          Button ID used for the standard OK button.
static int BUTTONBAR_BOTTOM
          Place Buttonbar at bottom
static int BUTTONBAR_LEFT
          Place Buttonbar on left side
static int BUTTONBAR_NONE
          Don't display the Buttonbar
static int BUTTONBAR_RIGHT
          Place Buttonbar on right side
static int BUTTONBAR_TOP
          Place Buttonbar at top
protected  boolean m_fCancelled
          True if this FormSheet was canelled.
 
Constructor Summary
FormSheet(java.lang.String sCaption, FormSheetContentCreator fscc, boolean fWaitResponse)
          Create a new FormSheet, using a content creator.
FormSheet(java.lang.String sCaption, javax.swing.JComponent jcmpComponent)
          Create a new FormSheet.
FormSheet(java.lang.String sCaption, javax.swing.JComponent jcmpComponent, boolean fWaitResponse)
          Create a new FormSheet.
 
Method Summary
 void addButton(FormSheet.FormButton fb)
          Add a button to the FormSheet's button bar.
 void addButton(java.lang.String sCaption, int nID, Action aAction)
          Add a button to the FormSheet's button bar.
 void addContentCreator(FormSheetContentCreator fscc)
          Add a contents creator for this FormSheet.
 FormSheetContainer attach(FormSheetContainer fsc)
          Attach a FormSheetContainer to this FormSheet.
 SaleProcess attach(SaleProcess p)
          Attach a process to this FormSheet.
 SalesPoint attach(SalesPoint sp)
          Attach a SalesPoint to this FormSheet.
 java.util.Iterator<FormSheet.FormButton> buttonIterator()
          Return a fail-fast, readonly iterator iterating over the buttons in the button bar.
 java.util.Iterator<FormSheet.FormButton> buttonIterator(boolean fSorted)
          Return a readonly iterator iterating over the buttons in the button bar.
 void cancel()
          Hook method called whenever the standard "Cancel" button was clicked.
 void close()
          Close the FormSheet.
 void copyFormSheetDnDComponents(FormSheet fs)
          registers all DnDComponents from given FormSheet to this one
 javax.swing.JPanel customizeButtonbar(javax.swing.JPanel buttonbar)
          Hook method called before buttons are added.
 FormSheetContainer detachDisplay()
          Detach the current FormSheetContainer from this FormSheet.
 SaleProcess detachProcess()
          Detach the current process from this FormSheet.
 SalesPoint detachSalesPoint()
          Detach the current SalesPoint from this FormSheet.
 javax.swing.JPanel fillBtnPanel(javax.swing.JPanel jp)
          Called by the Framework to generate the button bar's representation.
 FormSheet.FormButton getButton(int nID)
          Get a button from the FormSheet's button bar.
 int getButtonbarPosition()
           
 java.lang.Object getButtonsLock()
          Get the monitor used to synchronize access to the FormSheet's button bar.
 java.lang.String getCaption()
          Get the FormSheet's caption.
 javax.swing.JComponent getComponent()
          Get the component of this FormSheet.
 java.lang.Object getComponentLock()
          Get the monitor to be used when accessing this FormSheet's component.
 FormSheetContainer getDisplay()
          Get the currently attached FormSheetContainer.
protected  java.lang.Object getDisplayLock()
          Get the monitor used to synchronize access to the display.
 javax.swing.JPanel getDragLayer()
          Get the drag layer panel
 javax.swing.JPanel getModalLayer()
          get the draglayer
 javax.swing.JPanel getPopupLayer()
          get the popup layer
 SaleProcess getProcess()
          Get the currently attached process.
 SalesPoint getSalesPoint()
          Get the currently attached SalesPoint.
 javax.swing.JComponent getWrappedComponent()
          Returns the wrapped component.
 boolean isCancelled()
          Return whether the cancel button was used to close the FormSheet.
 boolean letFollowComponentOnDragLayer(javax.swing.JComponent cmp)
          let the specified component follow the mouse cursor on drag layer
 void ok()
          Hook method called whenever the standard "OK" button was clicked.
 void paintButtonBarBackground(java.awt.Graphics graphics, javax.swing.JComponent c)
          Paints button bar's background image
 boolean registerDnDComponent(DnDComponent dndcmp)
          register a DnDComponent to FormSheet
 void removeAllButtons()
          Remove all buttons from the FormSheet's button bar.
 void removeAllDndComponents()
          removes all registered DnDComponents from list of observes DnDComponents but not from the FormSheet
 FormSheet.FormButton removeButton(int nID)
          Remove a button from the FormSheet's button bar.
 void removeDnDComponent(DnDComponent dndcmp)
          remove a DnDComponent from FormSheet
 void setButtonbarPosition(int position)
           
 void setCaption(java.lang.String sCaption)
          Set the caption for this FormSheet.
 javax.swing.JComponent setComponent(javax.swing.JComponent jcmpComponent)
          Set the component for this FormSheet.
 void setFormsheetCustomizationListener(FormsheetCustomizationListener fscl)
          Set the current FormsheetCustomizationListener
 void setWaitResponse(boolean fWaitResponse)
          Set the waitResponse property of this FormSheet.
 void stopFollowComponentOnDragLayer()
          stops the component follow the mouse on drag layer
 java.lang.String toString()
           
 boolean waitResponse()
          Return true if Display.setFormSheet(org.salespointframework.core.FormSheet) should block until the FormSheet is closed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

m_fCancelled

protected boolean m_fCancelled
True if this FormSheet was canelled.


BUTTONBAR_BOTTOM

public static final int BUTTONBAR_BOTTOM
Place Buttonbar at bottom

See Also:
Constant Field Values

BUTTONBAR_TOP

public static final int BUTTONBAR_TOP
Place Buttonbar at top

See Also:
Constant Field Values

BUTTONBAR_LEFT

public static final int BUTTONBAR_LEFT
Place Buttonbar on left side

See Also:
Constant Field Values

BUTTONBAR_RIGHT

public static final int BUTTONBAR_RIGHT
Place Buttonbar on right side

See Also:
Constant Field Values

BUTTONBAR_NONE

public static final int BUTTONBAR_NONE
Don't display the Buttonbar

See Also:
Constant Field Values

BTNID_OK

public static final int BTNID_OK
Button ID used for the standard OK button.

See Also:
Constant Field Values

BTNID_CANCEL

public static final int BTNID_CANCEL
Button ID used for the standard Cancel button.

See Also:
Constant Field Values
Constructor Detail

FormSheet

public FormSheet(java.lang.String sCaption,
                 javax.swing.JComponent jcmpComponent)
Create a new FormSheet. Display.setFormSheet(org.salespointframework.core.FormSheet) will block until this FormSheet is closed.

By default, a FormSheet has two standard buttons: "OK" and "Cancel".

Parameters:
sCaption - the caption of the FormSheet.
jcmpComponent - the component of the FormSheet.
See Also:
ok(), cancel()

FormSheet

public FormSheet(java.lang.String sCaption,
                 javax.swing.JComponent jcmpComponent,
                 boolean fWaitResponse)
Create a new FormSheet.

By default, a FormSheet has two standard buttons: "OK" and "Cancel".

Parameters:
sCaption - the caption of the FormSheet.
jcmpComponent - the component of the FormSheet.
fWaitResponse - if true, Display.setFormSheet(org.salespointframework.core.FormSheet) will block until this FormSheet is closed.
See Also:
ok(), cancel()

FormSheet

public FormSheet(java.lang.String sCaption,
                 FormSheetContentCreator fscc,
                 boolean fWaitResponse)
Create a new FormSheet, using a content creator.

When the FormSheet is being serialized, only the content creator will be serialized. When the FormSheet gets deserialized, the content creator is called to restore the FormSheet's content.

Parameters:
sCaption - the FormSheet's caption
fscc - the FormSheetContentCreator that will create the FormSheet's contents
fWaitResponse - if true, Display.setFormSheet(org.salespointframework.core.FormSheet) will block until this FormSheet is closed.
Method Detail

getComponentLock

public java.lang.Object getComponentLock()
Get the monitor to be used when accessing this FormSheet's component.

FormSheetContainers can use this monitor when displaying the FormSheet, to make sure, they don't loose any changes about the component.


getButtonsLock

public java.lang.Object getButtonsLock()
Get the monitor used to synchronize access to the FormSheet's button bar.

FormSheetContainers can use this lock to make sure, they don't loose any button change events while making the FormSheet visible.


getDisplayLock

protected java.lang.Object getDisplayLock()
Get the monitor used to synchronize access to the display.

Subclasses of FormSheet can use this lock when defining further events that must be handled by the FormSheetContainer.


addContentCreator

public final void addContentCreator(FormSheetContentCreator fscc)
Add a contents creator for this FormSheet.

When the contents creator is used to create the FormSheet's contents, all contents creators that have ever been added to the FormSheet will be called in the order in which they were added. This ensures, that you can subclass FormSheets that use contents creators properly, extending their contents by simply adding another contents creator.

In the first contents creator you can assume a null component, a "OK" as well as a "Cancel" button.

Parameters:
fscc - the new FormSheetContentCreator. Must not be null.
See Also:
ok(), cancel()

stopFollowComponentOnDragLayer

public void stopFollowComponentOnDragLayer()
stops the component follow the mouse on drag layer


letFollowComponentOnDragLayer

public boolean letFollowComponentOnDragLayer(javax.swing.JComponent cmp)
let the specified component follow the mouse cursor on drag layer

Parameters:
cmp -
Returns:

getDragLayer

public javax.swing.JPanel getDragLayer()
Get the drag layer panel


getModalLayer

public javax.swing.JPanel getModalLayer()
get the draglayer

Returns:

getPopupLayer

public javax.swing.JPanel getPopupLayer()
get the popup layer

Returns:

registerDnDComponent

public boolean registerDnDComponent(DnDComponent dndcmp)
register a DnDComponent to FormSheet

Parameters:
dndcmp - component to register
Returns:
true on success

removeDnDComponent

public void removeDnDComponent(DnDComponent dndcmp)
remove a DnDComponent from FormSheet

Parameters:
dndcmp - component to unregister

removeAllDndComponents

public void removeAllDndComponents()
removes all registered DnDComponents from list of observes DnDComponents but not from the FormSheet


copyFormSheetDnDComponents

public void copyFormSheetDnDComponents(FormSheet fs)
registers all DnDComponents from given FormSheet to this one

Parameters:
fs -

getWrappedComponent

public javax.swing.JComponent getWrappedComponent()
Returns the wrapped component. This extracts the original component that was set by setComponent(JComponent)


setComponent

public javax.swing.JComponent setComponent(javax.swing.JComponent jcmpComponent)
Set the component for this FormSheet.

If the FormSheet is being displayed, an FormSheetContainer.onFormSheetComponentChanged(org.salespointframework.core.FormSheet, javax.swing.JComponent) event is fired, so that the change can affect the display instantaneously.

consider that this component will be packed into other components. and its background will be set transparent.

Parameters:
jcmpComponent - the new component
Returns:
the previous component of this FormSheet, if any.

getComponent

public javax.swing.JComponent getComponent()
Get the component of this FormSheet. The component returned by this method is the packed one. so it is the better way to call getWrappedComponent() instead.


setCaption

public void setCaption(java.lang.String sCaption)
Set the caption for this FormSheet.

If the FormSheet is being displayed, an FormSheetContainer.onFormSheetCaptionChanged(org.salespointframework.core.FormSheet, java.lang.String) event is fired, so that the change can affect the display instantaneously.

Parameters:
sCaption - the new caption.

getCaption

public java.lang.String getCaption()
Get the FormSheet's caption.


isCancelled

public boolean isCancelled()
Return whether the cancel button was used to close the FormSheet.


close

public void close()
Close the FormSheet. This will issue a call to FormSheetContainer.closeFormSheet(org.salespointframework.core.FormSheet).


waitResponse

public boolean waitResponse()
Return true if Display.setFormSheet(org.salespointframework.core.FormSheet) should block until the FormSheet is closed.


setWaitResponse

public void setWaitResponse(boolean fWaitResponse)
Set the waitResponse property of this FormSheet.

The waitResponse property decides whether or not Display.setFormSheet(org.salespointframework.core.FormSheet) should block until the FormSheet is closed.

The new value of the waitResponse property will have no effect before the FormSheet is displayed the next time, by calling setFormSheet().

Parameters:
fWaitResponse - the new value for the waitResponse property. If true Display.setFormSheet(org.salespointframework.core.FormSheet) should block until the FormSheet is closed.

attach

public SalesPoint attach(SalesPoint sp)
Attach a SalesPoint to this FormSheet.

You will usually not call this method directly, it is called by the Framework.

Parameters:
sp - the SalesPoint to be attached.
Returns:
the previously attached SalesPoint, if any.

detachSalesPoint

public SalesPoint detachSalesPoint()
Detach the current SalesPoint from this FormSheet.

You will usually not call this method directly, it is called by the Framework.

Returns:
the detached SalesPoint, if any.

getSalesPoint

public SalesPoint getSalesPoint()
Get the currently attached SalesPoint.


attach

public SaleProcess attach(SaleProcess p)
Attach a process to this FormSheet.

You will usually not call this method directly, it is called by the Framework.

Parameters:
p - the process to be attached.
Returns:
the previously attached process, if any.

detachProcess

public SaleProcess detachProcess()
Detach the current process from this FormSheet.

You will usually not call this method directly, it is called by the Framework.

Returns:
the detached process, if any.

getProcess

public SaleProcess getProcess()
Get the currently attached process.


attach

public FormSheetContainer attach(FormSheetContainer fsc)
Attach a FormSheetContainer to this FormSheet.

You will usually not call this method directly, it is called by the Framework.

Parameters:
fsc - the FormSheetContainer to be attached.
Returns:
the previously attached FormSheetContainer, if any.

detachDisplay

public FormSheetContainer detachDisplay()
Detach the current FormSheetContainer from this FormSheet.

You will usually not call this method directly, it is called by the Framework.

Returns:
the detached FormSheetContainer, if any.

getDisplay

public FormSheetContainer getDisplay()
Get the currently attached FormSheetContainer.


addButton

public void addButton(java.lang.String sCaption,
                      int nID,
                      Action aAction)
Add a button to the FormSheet's button bar.

If the FormSheet is being displayed, an FormSheetContainer.onFormSheetButtonAdded(org.salespointframework.core.FormSheet, org.salespointframework.core.FormSheet.FormButton) event is fired, so that the change can affect the display instantaneously.

Parameters:
sCaption - the caption of the button
nID - the ID of the button. This ID will later be used to identify the button and, therefore, must be unique for this FormSheet. If there is already a button in this FormSheet that has the same ID, a DuplicateButtonIDError will be thrown.
aAction - the action to be associated with the button.
Throws:
DuplicateButtonIDError - if a button with the same ID already exists.

addButton

public void addButton(FormSheet.FormButton fb)
Add a button to the FormSheet's button bar.

If the FormSheet is being displayed, an FormSheetContainer.onFormSheetButtonAdded(org.salespointframework.core.FormSheet, org.salespointframework.core.FormSheet.FormButton) event is fired, so that the change can affect the display instantaneously.

Parameters:
fb - the button to be added. The button's ID will later be used to identify it and, therefore, must be unique for this FormSheet. If there is already a button in this FormSheet that has the same ID, a DuplicateButtonIDError will be thrown.
Throws:
DuplicateButtonIDError - if a button with the same ID already exists.

removeButton

public FormSheet.FormButton removeButton(int nID)
Remove a button from the FormSheet's button bar.

If the FormSheet is being displayed, an FormSheetContainer.onFormSheetButtonRemoved(org.salespointframework.core.FormSheet, org.salespointframework.core.FormSheet.FormButton) event is fired, so that the change can affect the display instantaneously.

Parameters:
nID - the ID of the button to be removed. If the button does not exist, nothing happens.
Returns:
the removed button, if any.

removeAllButtons

public void removeAllButtons()
Remove all buttons from the FormSheet's button bar.

If the FormSheet is being displayed, an FormSheetContainer.onFormSheetButtonsCleared(org.salespointframework.core.FormSheet) event is fired, so that the change can affect the display instantaneously.


getButton

public FormSheet.FormButton getButton(int nID)
Get a button from the FormSheet's button bar.

Parameters:
nID - the ID of the button to be returned.

buttonIterator

public java.util.Iterator<FormSheet.FormButton> buttonIterator()
Return a fail-fast, readonly iterator iterating over the buttons in the button bar.

The buttons will not be returned in the order in which they where added, but in a random order. To get them sorted in order of adding, see buttonIterator(boolean).


buttonIterator

public java.util.Iterator<FormSheet.FormButton> buttonIterator(boolean fSorted)
Return a readonly iterator iterating over the buttons in the button bar.

Parameters:
fSorted - if true, the buttons will be returned in the order in which they were added to the FormSheet.

setButtonbarPosition

public void setButtonbarPosition(int position)

getButtonbarPosition

public int getButtonbarPosition()

fillBtnPanel

public javax.swing.JPanel fillBtnPanel(javax.swing.JPanel jp)
Called by the Framework to generate the button bar's representation.

Parameters:
jp - the panel to be filled. The buttons will be added in the order in which they where added to the FormSheet.

paintButtonBarBackground

public void paintButtonBarBackground(java.awt.Graphics graphics,
                                     javax.swing.JComponent c)
Paints button bar's background image

Parameters:
g - Graphics context
c - target component

customizeButtonbar

public javax.swing.JPanel customizeButtonbar(javax.swing.JPanel buttonbar)
Hook method called before buttons are added. Here it is possible to do Buttonbar customizations use setButtonbarPosition(int) to set its position don't manipulate any button inside here.

Parameters:
buttonbar -

setFormsheetCustomizationListener

public void setFormsheetCustomizationListener(FormsheetCustomizationListener fscl)
Set the current FormsheetCustomizationListener


ok

public void ok()
Hook method called whenever the standard "OK" button was clicked.


cancel

public void cancel()
Hook method called whenever the standard "Cancel" button was clicked.

See Also:
isCancelled()

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object