LspsScreen (LSPS 3.2 SDK)

All Superinterfaces:: Serializable

All Known Implementing Classes:: AbstractScreen, CustomUIScreen, CustomUIWithContextScreen, Form, UIScreen

public interface LspsScreen
extends Serializable

Interface for rendering screens based on LSPS forms. A screen can be understood as a representation of a form which is placed in the Vaadin UI. It defines a contract between the Vaadin UI and the form in term of lifecycle methods:

In addition to that it provides services to form components rendered in the screen. The services allows the components to integrate with the event processing, garbage collection, component scopes, ...

In terms of rendering the screen can be viewed as a sandbox. Components contained in the screen should not make any attempt to change the component tree or state of components outside the screen.

The relation between the screen and the rest of the application can be depicted as follows:

 +---------------------------------------------------------+
 |                      Browser Window                     |
 +---------------------------------------------------------+
 | Application                                             |
 |                                                         |
 |              +-----------------------------------+      |
 | +--------+   |  LspsScreen                       |      |
 | |  Menu  |   |                                   |      |
 | |........|   |                                   |      |
 | |........|   |                                   |      |
 | |........|   |                                   |      |
 | |........|   |                                   |      |
 | |........|   |                                   |      |
 | |........|   |                                   |      |
 | |........|   |                                   |      |
 | |........|   |                                   |      |
 | +--------+   |                                   |      |
 |              |                                   |      |
 |              +-----------------------------------+      |
 +---------------------------------------------------------+

Author:: mhi
See Also:: LspsContextHolder, LspsFormConnector, LspsAppConnector

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addComponentToRefresh(UIComponent component)` Schedules a component to be refreshed during next call to `triggerEventProcessing(com.whitestein.lsps.vaadin.ui.events.UIEvent)`.
`void`	`addUploadedBinaryData(long binaryDataId)` Adds a temporary file to the list of files to be deleted once the screen is closed.
`void`	`cleanup()` Called after the screen content is removed from the Vaadin UI or submitted.
`UIComponent`	`createUIComponent(UIComponent parent, RecordHolder componentDefinition, UIComponentScope scope)` Creates a Vaadin component based on the provided component definition.
`void`	`fireApplicationEvent(UIApplicationEvent appEvent)` Schedules given application event to be fired on all registered components that have an application event listener.
`void`	`fireBrowserWindowResizeEvent(Dimension dimension)` A browser window resize has been detected.
`Set<UIComponent>`	`getAllComponents()` Returns all components contained in this screen.
`Set<UIComponent>`	`getComponentsForDefinition(RecordHolder componentDefinition, UIComponent scopeComponent)` Returns all component instances for the given component definition, visible from the scope of the given component.
`LspsContextHolder`	`getContextHolder()` Returns the the LSPS context which produced this screen.
`UIComponentScope`	`getRootScope()` Returns the root scope.
`ContextWrapper`	`getScreenContext()` Returns the "0:1" execution context for the screen.
`UIComponent`	`getTopmostComponent()` Returns the topmost component.
`Set<ValueHolder>`	`getValuesToRetain()` Returns the set of value holders that should not be garbage collected even if they are not referenced from any variables in the model.
`boolean`	`isInvalid(UIComponent component)` Checks whether given component is marked as invalid, by calling `markComponentAsInvalid(com.whitestein.lsps.vaadin.ui.components.UIComponent)`.
`void`	`markComponentAsInvalid(UIComponent component)` Marks the component as invalid.
`void`	`markComponentAsValid(UIComponent component)` Marks the component as valid again.
`void`	`registerUIComponent(UIComponent component)` Register the given UI component and its children in this screen.
`void`	`registerValueToRetain(Handle handle)` Registers the value for the given handle as one to be kept during garbage collection.
`com.vaadin.ui.Component`	`render()` Called when the screen content should be added to the Vaadin UI.
`void`	`resume()` Called after the screen component has been added to Vaadin UI.
`boolean`	`triggerEventProcessing(UIEvent triggeringEvent)` Process all events in the queue - invokes standard LSPS ui lifecycle
`void`	`unregisterUIComponent(UIComponent component)` Unregister the given UI component and its children from this screen.
`void`	`unregisterValueToRetain(Handle handle)` Unregisters the value for the given handle as one to be kept during garbage collection.
`void`	`updateContextFor(UIComponentData componentData)` Updates context dependent variables for the given `componentData`.

- Method Detail
  - render
```
com.vaadin.ui.Component render()
```
    Called when the screen content should be added to the Vaadin UI. Typically will be called shortly after the screen is created.
    This method only creates the Vaadin UI component graph and returns it - it should not attempt to show the component in some Vaadin UI.
    The resume() method is called after this method.
    This method must be called exactly once.
    
    Returns:
    
    the root component to show, never null. Returns Vaadin component instead of UIComponent because custom screens may use components other than UIComponent.
    
    Throws:
    
    IllegalStateException - if the screen is already rendered or it has been cleaned up (cleanup()).
  - resume
```
void resume()
```
    Called after the screen component has been added to Vaadin UI. Called when the screen content is shown:
    - either it is shown for the first time: in such case the render() method has already been called
    - or it is re-shown, e.g. when the user navigates back to a previously-shown screen from which he navigated away without submitting
    Throws:
    
    IllegalStateException - if render() was not yet called on this instance.
  - cleanup
```
void cleanup()
```
    Called after the screen content is removed from the Vaadin UI or submitted.
    After this method is called, no other methods may be called.
  - registerValueToRetain
```
void registerValueToRetain(Handle handle)
```
    Registers the value for the given handle as one to be kept during garbage collection. See getValuesToRetain().
    
    Parameters:
    
    handle - a handle to the model object, not null.
  - unregisterValueToRetain
```
void unregisterValueToRetain(Handle handle)
```
    Unregisters the value for the given handle as one to be kept during garbage collection. See getValuesToRetain().
    
    Parameters:
    
    handle - a handle to the model object, not null.
  - getValuesToRetain
```
Set<ValueHolder> getValuesToRetain()
```
    Returns the set of value holders that should not be garbage collected even if they are not referenced from any variables in the model. Typically this should contain the UI definition (as defined in the model, either as a task or document attribute).
    
    Returns:
    
    values to retain during garbage collection
  - getAllComponents
```
Set<UIComponent> getAllComponents()
```
    Returns all components contained in this screen. A shortcut for getRootScope().getRegisteredComponents()
    
    Returns:
    
    all components, never null.
  - getRootScope
```
UIComponentScope getRootScope()
```
    Returns the root scope.
    
    Returns:
    
    the root scope, never null.
  - fireBrowserWindowResizeEvent
```
void fireBrowserWindowResizeEvent(Dimension dimension)
```
    A browser window resize has been detected. Application event is fired, with name of internal_windowresize, having payload of type hu::Dimension which holds new window dimension. The event originator component is set to ROOT.
    Warning: browsers on Android return value in DPs instead of pixels. From Android documentation: Density-independent Pixels - an abstract unit that is based on the physical density of the screen. These units are relative to a 160 dpi screen, so one dp is one pixel on a 160 dpi screen. The ratio of dp-to-pixel will change with the screen density, but not necessarily in direct proportion. Example: a screen width of 720 on a 320 DPI screen will be reported as 360 DPs.
    Therefore, to render special page for small devices, compare screen width to the value of 400. If equal or smaller, provide small screen version.
    
    Parameters:
    
    dimension - the new dimension, in pixels (on desktop OS) or DPs (on Android phones).
  - getScreenContext
```
ContextWrapper getScreenContext()
```
    Returns the "0:1" execution context for the screen. The screen runs in this context until submitted or persisted - then it is merged to the main "0" execution context.
    
    Returns:
    
    the context wrapper, never null.
  - getContextHolder
```
LspsContextHolder getContextHolder()
```
    Returns the the LSPS context which produced this screen.
    
    Returns:
    
    context holder, never null.
  - createUIComponent
```
UIComponent createUIComponent(UIComponent parent,
                              RecordHolder componentDefinition,
                              UIComponentScope scope)
```
    Creates a Vaadin component based on the provided component definition. Shortcut to UIComponentFactory.createComponent(LspsScreen, com.whitestein.lsps.vaadin.ui.components.UIComponent, com.whitestein.lsps.lang.exec.RecordHolder, com.whitestein.lsps.vaadin.ui.UIComponentScope) .
    
    Parameters:
    
    parent - parent of the component in the LSPS component hierarchy
    
    componentDefinition - definition of the component to create
    
    scope - component scope; if null, same scope as parent will be used
    
    Returns:
    
    created component
  - triggerEventProcessing
```
boolean triggerEventProcessing(UIEvent triggeringEvent)
```
    Process all events in the queue - invokes standard LSPS ui lifecycle
    
    Parameters:
    
    triggeringEvent - the event that triggered this round of processing; can be null if there is no such event.
    
    Returns:
    
    false if processing could not be started, either because the event processing is already in progress, or any of the components to process is marked as invalid (via markComponentAsInvalid(com.whitestein.lsps.vaadin.ui.components.UIComponent).
  - markComponentAsInvalid
```
void markComponentAsInvalid(UIComponent component)
```
    Marks the component as invalid. This will cause triggerEventProcessing(com.whitestein.lsps.vaadin.ui.events.UIEvent) to return false for events which processes given component.
    Note that this will not cause the component to show an error icon.
    
    Parameters:
    
    component - the component, not null.
  - markComponentAsValid
```
void markComponentAsValid(UIComponent component)
```
    Marks the component as valid again.
    Note that this will not cause the component to hide an error icon.
    
    Parameters:
    
    component - the component, not null.
  - isInvalid
```
boolean isInvalid(UIComponent component)
```
    Checks whether given component is marked as invalid, by calling markComponentAsInvalid(com.whitestein.lsps.vaadin.ui.components.UIComponent).
    
    Parameters:
    
    component - the component, not null.
    
    Returns:
    
    true if the component is marked invalid, false if it has not yet been marked as invalid or has been marked as valid, by calling markComponentAsValid(com.whitestein.lsps.vaadin.ui.components.UIComponent).
  - registerUIComponent
```
void registerUIComponent(UIComponent component)
```
    Register the given UI component and its children in this screen. Registration of components is needed, so that the application is able to use references between lsps objects and vaadin components for various reasons (such as refresh functionality).
    
    Parameters:
    
    component - not null. The component parent must already be registered.
  - unregisterUIComponent
```
void unregisterUIComponent(UIComponent component)
```
    Unregister the given UI component and its children from this screen.
    
    Parameters:
    
    component - not null. The component parent must already be registered.
  - addComponentToRefresh
```
void addComponentToRefresh(UIComponent component)
```
    Schedules a component to be refreshed during next call to triggerEventProcessing(com.whitestein.lsps.vaadin.ui.events.UIEvent).
    
    Parameters:
    
    component - the component, not null. The component must be initialized.
    
    Throws:
    
    IllegalArgumentException - if the component is not initialized.
  - updateContextFor
```
void updateContextFor(UIComponentData componentData)
```
    Updates context dependent variables for the given componentData. See UIComponentScope.updateContext().
    
    Parameters:
    
    componentData - a component data, may not be null
  - getTopmostComponent
```
UIComponent getTopmostComponent()
```
    Returns the topmost component.
    
    Returns:
    
    the topmost component, never null.
    
    Throws:
    
    IllegalStateException - if the screen is not yet rendered or has been closed.
  - fireApplicationEvent
```
void fireApplicationEvent(UIApplicationEvent appEvent)
```
    Schedules given application event to be fired on all registered components that have an application event listener.
    The event is not fired until triggerEventProcessing(com.whitestein.lsps.vaadin.ui.events.UIEvent) is called.
    
    Parameters:
    
    appEvent - the event, not null.
  - getComponentsForDefinition
```
Set<UIComponent> getComponentsForDefinition(RecordHolder componentDefinition,
                                            UIComponent scopeComponent)
```
    Returns all component instances for the given component definition, visible from the scope of the given component.
    
    Parameters:
    
    componentDefinition - the definition, not null.
    
    scopeComponent - find the components in this scope only. Not null.
    
    Returns:
    
    instances of UIComponent associated with the given component definition. Never null, never contains nulls.
  - addUploadedBinaryData
```
void addUploadedBinaryData(long binaryDataId)
```
    Adds a temporary file to the list of files to be deleted once the screen is closed.
    
    Parameters:
    
    binaryDataId -

Interface LspsScreen

Method Summary

Method Detail

render

resume

cleanup

registerValueToRetain

unregisterValueToRetain

getValuesToRetain

getAllComponents

getRootScope

fireBrowserWindowResizeEvent

getScreenContext

getContextHolder

createUIComponent

triggerEventProcessing

markComponentAsInvalid

markComponentAsValid

isInvalid

registerUIComponent

unregisterUIComponent

addComponentToRefresh

updateContextFor

getTopmostComponent

fireApplicationEvent

getComponentsForDefinition

addUploadedBinaryData