org.wings
Class SFrame

java.lang.Object
  org.wings.SComponent
      org.wings.SContainer
          org.wings.SRootContainer
              org.wings.SFrame

All Implemented Interfaces:

PropertyChangeListener, Serializable, Cloneable, EventListener, LowLevelEventListener, Renderable

public class SFrame
extends SRootContainer
implements PropertyChangeListener, LowLevelEventListener

The root component of every component hierarchy.

A SessionServlet requires an instance of SFrame to render the page. SFrame consists of some header informaton (meta, link, script) and a stack of components. The bottommost component of the stack is always the contentPane. When dialogs are to be shown, they are stacked on top of it.

Author:

Holger Engels, Armin Haaf

See Also:

Serialized Form

Field Summary

protected List	headers A list of all header used by this frame.
protected String	statusLine
protected StyleSheet	styleSheet the style sheet used in certain look and feels.
protected String	title The Title of the Frame.

Fields inherited from class org.wings.SRootContainer

contentPane, windowsPane

Fields inherited from class org.wings.SComponent

DONE_RENDERING, dynamicStyles, enabled, propertyChangeSupport, SELECTOR_ALL, START_RENDERING, visible, WHEN_FOCUSED_OR_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_IN_FOCUSED_FRAME

Constructor Summary

SFrame()
Creates a new SFrame

SFrame(String title)
Creates a new SFrame

Method Summary

void	addDynamicResource(DynamicResource d) Adds a dynamic ressoure.
void	addHeader(int index, Object headerElement) Add an Renderable into the header of the HTML page at the desired index position
void	addHeader(Object headerElement) Add an Renderable into the header of the HTML page
void	addInvalidLowLevelEventListener(SInvalidLowLevelEventListener l) Registers an SInvalidLowLevelEventListener in this frame.
void	clearHeaders() Removes all headers.
void	deregisterGlobalInputMapComponent(SComponent comp)
void	fireIntermediateEvents() fire events which describes a "in progress" state change, like TreeWillExpand, or ListSelectionEvent with getIsAdjusting() true, ...
void	fireInvalidLowLevelEventListener(LowLevelEventListener source) Notify all SInvalidLowLevelEventListener about an outdated request on the passed component
Map<String,Object>	getAutoAdjustLayout()
SButton	getBackButton() A button activated on detected browser back clicks.
DynamicResource	getDynamicResource(Class c) Severeral Dynamic code Ressources are attached to a SFrame.
Collection	getDynamicResources()
String	getEventEpoch()
SComponent	getFocus()
Set<SComponent>	getGlobalInputMapComponents()
List	getHeaders()
InputMap	getInputMap(int condition)
String	getLogLevel()
SFrame	getParentFrame() Return this.
RequestURL	getRequestURL() Returns the base URL for a request to the WingsServlet.
String	getTargetResource() Every externalized ressource has an id.
String	getTitle() Title of this HTML page.
Map<String,Object>	getUpdateCursor()
boolean	handleError(Throwable e) custom error handling.
List	headers() Deprecated. Use getHeaders() instead
void	hide() Hides this frame.
protected void	initializeContentPane()
void	invalidate() Invalidate this frame by incrementing its event epoch.
void	invite(ComponentVisitor visitor) Invite a ComponentVisitor.
boolean	isDebugJs()
boolean	isEpochCheckEnabled() Asks the low-level event listener if epoch checking should be perfomed on it.
boolean	isFormContentPane() Tell wether the contentPane is an SForm.
boolean	isNoCaching()
boolean	isUpdateEnabled()
void	processLowLevelEvent(String name, String[] values) Deliver low level/http events (parameters).
void	propertyChange(PropertyChangeEvent pe)
void	registerGlobalInputMapComponent(SComponent comp)
void	removeDispatchListener(SInvalidLowLevelEventListener l) Removes the passed SInvalidLowLevelEventListener from this frame.
void	removeDynamicResource(Class dynamicResourceClass) Removes the instance of the dynamic ressource of the given class.
boolean	removeHeader(Object headerElement)
void	setAutoAdjustLayout(Map<String,Object> autoAdjustLayout)
void	setBackButton(SButton defaultBackButton) This button allows you to programattically react on Back buttons pressed in the browser itselfs.
void	setCG(FrameCG cg)
void	setEpochCheckEnabled(boolean epochCheckEnabled)
void	setFocus(SComponent focusOnComponent) Choose which component rendered inside this frame should gain the edit focus on next rendering This function is called by SComponent.requestFocus()
void	setFormContentPane(boolean contentPaneForm) Determine wether the contentPane shall be an SForm.
void	setInputMap(int condition, InputMap inputMap) Sets The current input map.
void	setNoCaching(boolean noCaching) Typically you don't want any wings application to operate on old 'views' meaning old pages.
void	setRequestURL(RequestURL requestURL) Set server address.
void	setStatusLine(String s)
void	setTargetResource(String targetResource) Set the target resource
void	setTitle(String title) Sets the title of this HTML page.
void	setUpdateCursor(Map<String,Object> updateCursor)
void	setUpdateEnabled(boolean enabled)
void	setVisible(boolean visible) Shows or hide this frame.
void	show() Shows this frame.
void	write(Device s) Mark this component as subject to reload if the property, that is given in its old and new fashion, changed.

Methods inherited from class org.wings.SRootContainer

addComponent, getContentPane, getWindowCount, getWindowsPane, initializeWindowsPane, popWindow, pushWindow, remove, removeWindow, setCG, setContentPane, setWindowsPane

Methods inherited from class org.wings.SContainer

add, add, add, add, addComponent, addComponent, addComponent, addContainerListener, addNotify, clone, fireContainerEvent, getComponent, getComponentCount, getComponentList, getComponents, getConstraintAt, getConstraintList, getLayout, inviteEachComponent, isShowingChildren, processContainerEvent, remove, removeAll, removeContainerListener, removeNotify, setCG, setLayout, setParentFrame, updateCG

Methods inherited from class org.wings.SComponent

addComponentListener, addDynamicStyle, addEventListener, addParentFrameListener, addPropertyChangeListener, addPropertyChangeListener, addRenderListener, addScriptListener, addStyle, fireComponentChangeEvent, fireFinalEvents, fireKeyEvents, fireRenderEvent, getActionMap, getBackground, getBorder, getCG, getClientProperty, getComponentPopupMenu, getDynamicStyle, getDynamicStyles, getFocusTraversalIndex, getFont, getForeground, getHorizontalAlignment, getInputMap, getListenerCount, getListenerList, getListeners, getLowLevelEventId, getName, getParent, getPreferredSize, getResidesInForm, getScriptListenerList, getScriptListeners, getSession, getShowAsFormComponent, getStyle, getToolTipText, getVerticalAlignment, isDifferent, isEnabled, isFocusOwner, isRecursivelyVisible, isReloadForced, isUpdatePossible, isVisible, paramString, processComponentEvent, processKeyEvents, putClientProperty, reload, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, removeComponentListener, removeDynamicStyle, removeEventListener, removeParentFrameListener, removePropertyChangeListener, removePropertyChangeListener, removeRenderListener, removeScriptListener, removeStyle, requestFocus, scrollRectToVisible, setActionMap, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributes, setBackground, setBorder, setCG, setComponentPopupMenu, setDynamicStyles, setEnabled, setFocusTraversalIndex, setFont, setForeground, setHorizontalAlignment, setInputMap, setName, setNameRaw, setParent, setPreferredSize, setReloadForced, setShowAsFormComponent, setStyle, setToolTipText, setVerticalAlignment, toString, update

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.wings.LowLevelEventListener

fireFinalEvents, getLowLevelEventId, getName, isEnabled

Field Detail

title

protected String title

The Title of the Frame.

headers

protected List headers

A list of all header used by this frame.

styleSheet

protected StyleSheet styleSheet

the style sheet used in certain look and feels.

statusLine

protected String statusLine

Constructor Detail

SFrame

public SFrame()

Creates a new SFrame

SFrame

public SFrame(String title)

Creates a new SFrame

Parameters:

title - Title of this frame, rendered in browser window title

Method Detail

addDynamicResource

public void addDynamicResource(DynamicResource d)

Adds a dynamic ressoure.

See Also:

getDynamicResource(Class)

removeDynamicResource

public void removeDynamicResource(Class dynamicResourceClass)

Removes the instance of the dynamic ressource of the given class.

Parameters:

dynamicResourceClass - Class of dynamic ressource to remove

See Also:

getDynamicResource(Class)

getDynamicResource

public DynamicResource getDynamicResource(Class c)

Severeral Dynamic code Ressources are attached to a SFrame.
See Frame.plaf for details, but in general you wil find attached to every SFrame a

• A ReloadResource rendering the HTML-Code of all SComponents inside this frame.

getDynamicResources

public Collection getDynamicResources()

Returns:

all dynamic script resources

getParentFrame

public SFrame getParentFrame()

Return this.

Overrides:

getParentFrame in class SComponent

Returns:

this.

See Also:

SComponent.addParentFrameListener(org.wings.event.SParentFrameListener)

invalidate

public final void invalidate()

Invalidate this frame by incrementing its event epoch. This method is called whenever a change took place inside this frame - that is whenever one of its child components has become dirty. In consequence each dynamic resource which is attached to this frame has to be externalized with a new "version-number".

getEventEpoch

public final String getEventEpoch()

setRequestURL

public final void setRequestURL(RequestURL requestURL)

Set server address.

getRequestURL

public final RequestURL getRequestURL()

Returns the base URL for a request to the WingsServlet. This URL is used to assemble an URL that trigger events. In order to be used for this purpose, you've to add your parameters here.

Overrides:

getRequestURL in class SComponent

Returns:

The HTTP URL where this component can be accessed.

setTargetResource

public void setTargetResource(String targetResource)

Set the target resource

getTargetResource

public String getTargetResource()

Every externalized ressource has an id. A frame is a ReloadResource.

Returns:

The id of this ReloadResource

addHeader

public void addHeader(Object headerElement)

Add an Renderable into the header of the HTML page

Parameters:

headerElement - is typically a Link or DynamicResource.

See Also:

Link

addHeader

public void addHeader(int index,
                      Object headerElement)

Add an Renderable into the header of the HTML page at the desired index position

Parameters:

headerElement - is typically a Link or DynamicResource.

index - index in header list to add this item

See Also:

Link, getHeaders()

removeHeader

public boolean removeHeader(Object headerElement)

Returns:

true if this frame contained the specified header element.

See Also:

addHeader(Object)

clearHeaders

public void clearHeaders()

Removes all headers. Be carful about what you do!

See Also:

addHeader(Object)

headers

public List headers()

Deprecated. Use getHeaders() instead

See Also:

addHeader(Object)

getHeaders

public List getHeaders()

See Also:

addHeader(Object)

setTitle

public void setTitle(String title)

Sets the title of this HTML page. Typically shown in the browsers window title.

Parameters:

title - The window title.

getTitle

public String getTitle()

Title of this HTML page. Typically shown in the browsers window title.

Returns:

the current page title or an empty string if this page doesn't have a title.

setStatusLine

public void setStatusLine(String s)

isNoCaching

public boolean isNoCaching()

Returns:

true if the generated HTML code of this frame/page should not be cached by browser, false if no according HTTP/HTML headers should be rendered

See Also:

setNoCaching(boolean)

write

public void write(Device s)
           throws IOException

Description copied from class: SComponent

Mark this component as subject to reload if the property, that is given in its old and new fashion, changed.

Specified by:

write in interface Renderable

Overrides:

write in class SComponent

Throws:

IOException

setNoCaching

public void setNoCaching(boolean noCaching)

Typically you don't want any wings application to operate on old 'views' meaning old pages. Hence all generated HTML pages (SFrame objects rendered through ReloadResource are marked as do not cache inside the HTTP response header and the generated HTML frame code.

If for any purpose (i.e. you a writing a read only application) you want th user to be able to work on old views then set this to false and Mark the according SComponents to be not epoch checked (i.e. SAbstractButton.setEpochCheckEnabled(boolean))

Parameters:

noCaching - The noCaching to set.

See Also:

LowLevelEventListener.isEpochCheckEnabled(), LowLevelEventDispatcher

show

public void show()

Shows this frame. This means it gets registered at the session.

See Also:

Session.getFrames()

hide

public void hide()

Hides this frame. This means it gets removed at the session.

See Also:

Session.getFrames()

setVisible

public void setVisible(boolean visible)

Shows or hide this frame. This means it gets (un)registered at the session.

Overrides:

setVisible in class SComponent

Parameters:

visible - wether this component will show or not

See Also:

Session.getFrames()

propertyChange

public void propertyChange(PropertyChangeEvent pe)

Specified by:

propertyChange in interface PropertyChangeListener

setCG

public void setCG(FrameCG cg)

invite

public void invite(ComponentVisitor visitor)
            throws Exception

Description copied from class: SContainer

Invite a ComponentVisitor. Invokes visit(SContainer) on the ComponentVisitor.

Overrides:

invite in class SContainer

Parameters:

visitor - the visitor to be invited

Throws:

Exception

setFocus

public void setFocus(SComponent focusOnComponent)

Choose which component rendered inside this frame should gain the edit focus on next rendering This function is called by SComponent.requestFocus()

Parameters:

focusOnComponent - the component which requests the focus.

getFocus

public SComponent getFocus()

See Also:

setFocus(SComponent)

processLowLevelEvent

public void processLowLevelEvent(String name,
                                 String[] values)

Description copied from interface: LowLevelEventListener

Deliver low level/http events (parameters). The name-value-pairs of the HTTPRequest are considered low level events.

Specified by:

processLowLevelEvent in interface LowLevelEventListener

Overrides:

processLowLevelEvent in class SComponent

Parameters:

name - the name-value-pair's name

values - the name-value-pair's values

addInvalidLowLevelEventListener

public final void addInvalidLowLevelEventListener(SInvalidLowLevelEventListener l)

Registers an SInvalidLowLevelEventListener in this frame.

Parameters:

l - The listener to notify about outdated reqests

See Also:

InvalidLowLevelEvent

removeDispatchListener

public final void removeDispatchListener(SInvalidLowLevelEventListener l)

Removes the passed SInvalidLowLevelEventListener from this frame.

Parameters:

l - The listener to remove

See Also:

InvalidLowLevelEvent

fireInvalidLowLevelEventListener

public final void fireInvalidLowLevelEventListener(LowLevelEventListener source)

Notify all SInvalidLowLevelEventListener about an outdated request on the passed component

Parameters:

source - The SComponent received an outdated event

See Also:

LowLevelEventDispatcher

getBackButton

public SButton getBackButton()

A button activated on detected browser back clicks.

Returns:

Returns the backButton.

See Also:

setBackButton(SButton)

setBackButton

public void setBackButton(SButton defaultBackButton)

This button allows you to programattically react on Back buttons pressed in the browser itselfs. This is a convenience method in contrast to addInvalidLowLevelEventListener(SInvalidLowLevelEventListener). While the listener throws an event on every detected component receiving an invalid request, this button is only activated if

• Maximum once per request
• Only if some time passed by to avoid double-clicks to be recognized as back button clicks.

Note: To work correctly you should set use GET posting SForm.setPostMethod(boolean) and use setNoCaching(boolean) for no caching. This will advise the browser to reload every back page.

Parameters:

defaultBackButton - A button to trigger upon detected invalid epochs.

fireIntermediateEvents

public void fireIntermediateEvents()

Description copied from interface: LowLevelEventListener

fire events which describes a "in progress" state change, like TreeWillExpand, or ListSelectionEvent with getIsAdjusting() true, ...

Specified by:

fireIntermediateEvents in interface LowLevelEventListener

isEpochCheckEnabled

public boolean isEpochCheckEnabled()

Description copied from interface: LowLevelEventListener

Asks the low-level event listener if epoch checking should be perfomed on it. If true the Dispatcher will ignore request originating from old views (typically iniated by triggering browser back and clicking somewhere.)

Specified by:

isEpochCheckEnabled in interface LowLevelEventListener

Returns:

true if epoch checking should be perfomed, false if all request for this component should be processed.

See Also:

LowLevelEventListener.isEpochCheckEnabled()

setEpochCheckEnabled

public void setEpochCheckEnabled(boolean epochCheckEnabled)

See Also:

LowLevelEventListener.isEpochCheckEnabled()

handleError

public boolean handleError(Throwable e)

custom error handling. If you want to catch application errors, return true here.

Parameters:

e - The throwable causing this.

Returns:

does this frame handle errors...

getInputMap

public InputMap getInputMap(int condition)

Overrides:

getInputMap in class SComponent

Parameters:

condition - Either SComponent.WHEN_FOCUSED_OR_ANCESTOR_OF_FOCUSED_COMPONENT or SComponent.WHEN_IN_FOCUSED_FRAME

Returns:

The input map for the given condition.

See Also:

SComponent.setInputMap(int, javax.swing.InputMap)

setInputMap

public void setInputMap(int condition,
                        InputMap inputMap)

Description copied from class: SComponent

Sets The current input map.

Overrides:

setInputMap in class SComponent

Parameters:

condition - Either SComponent.WHEN_FOCUSED_OR_ANCESTOR_OF_FOCUSED_COMPONENT or SComponent.WHEN_IN_FOCUSED_FRAME

inputMap - The new input map

See Also:

JComponent.setInputMap(int, javax.swing.InputMap)

registerGlobalInputMapComponent

public void registerGlobalInputMapComponent(SComponent comp)

deregisterGlobalInputMapComponent

public void deregisterGlobalInputMapComponent(SComponent comp)

getGlobalInputMapComponents

public Set<SComponent> getGlobalInputMapComponents()

isUpdateEnabled

public boolean isUpdateEnabled()

setUpdateEnabled

public void setUpdateEnabled(boolean enabled)

getUpdateCursor

public Map<String,Object> getUpdateCursor()

setUpdateCursor

public void setUpdateCursor(Map<String,Object> updateCursor)

getAutoAdjustLayout

public Map<String,Object> getAutoAdjustLayout()

setAutoAdjustLayout

public void setAutoAdjustLayout(Map<String,Object> autoAdjustLayout)

initializeContentPane

protected void initializeContentPane()

Overrides:

initializeContentPane in class SRootContainer

isFormContentPane

public boolean isFormContentPane()

Tell wether the contentPane is an SForm.

Returns:

true if the contentPane is an SForm, false otherwise

setFormContentPane

public void setFormContentPane(boolean contentPaneForm)

Determine wether the contentPane shall be an SForm. The property is true by default.

Parameters:

contentPaneForm - true if the contentPane shall be an SForm, false otherwise

getLogLevel

public String getLogLevel()

Returns:

isDebugJs

public boolean isDebugJs()