com.droplets.api
Class Window

java.lang.Object
  |
  +--com.droplets.api.InvalidationEventSource
        |
        +--com.droplets.api.Window

Direct Known Subclasses:

BinderPage, CalendarWindow, Dialog, Frame, ParseEditChoice

public abstract class Window

extends InvalidationEventSource

The base class of all windows in Droplet applications. This class should not be constructed directly. Use Dialog or Frame instead.

Each application must have one unique window designated as its main window. The main window is handled differently from others by the Droplet Server in certain ways. In particular, calling close on the main window terminates the application, whereas calling close on any other window just closes that window. To distinguish the main window from the rest, you must pass true to the constructor as the isMainWindow parameter.

Note that there is a restriction on the usage of Window objects. After the Droplet Client corresponding to an Application object is no longer connected to the Server, all open windows that belong to that Application may be deallocated, either immediately when the Client disconnects or after a specified period of time. In addition, Windows are always deallocated after they are closed. When a Window is deallocated, the Java object that represents it is said to become "invalid." All subsequent public method calls will throw an IllegalStateException. Any other objects that hold a reference to this one should register using InvalidationEventSource.addInvalidationListener(com.droplets.api.event.ObjectInvalidationListener) to be notified when the object becomes invalid so that they can release their references. In all cases, this notification will come after a call to stop().

Note that in the ObjectInvalidationListener's event handling code, you must not rely on the fact that the Window's Application object is still valid. However, the Window's Components are guaranteed to be valid.

Since window information is cached, it is not possible to simply add if/else logic to generate different component layouts based on context. See addAllComponents() method documentation for important restrictions on adding components in windows, and for more information on how to generate window layouts at runtime.

There are some concepts that you must understand about how Droplet Windows work. Refer to the Droplet SDK's Hello World and Sub-windows tutorials for a full explanation.

Field Summary

protected int	m_token The token that represents this object's native peer.
protected com.droplets.api.WindowComponent	m_windowComp The component used to communicate attributes and commands for Windows to clients.

Constructor Summary

Window(Application application, boolean isMainWindow)
Deprecated. Construct a Frame or Dialog instead of this class. They both derive from this class, so the usage is the same, but each class is more explicit about the type of Window you would get. Constructs a new Window.

Window(Application application, boolean isMainWindow, boolean isFrame)
Deprecated. Construct a Frame or Dialog instead of this class. They both derive from this class, so the usage is the same, but each class is more explicit about the type of Window you would get. Constructs a new Window.

Method Summary

protected void	addAllComponents() Called by the Droplet Server after the window has been created.
void	addCloseListener(WindowCloseListener l) Adds a listener to be notified when this window is about to close.
void	addComponent(Component c) Deprecated. Replaced by Panel.addComponent(). To add a component to a Window, use getMainPanel().addComponent() instead.
void	addOpenDialogListener(OpenDialogListener pl) Adds a listener to be notified when a file is chosen from an open dialog
void	close() Closes this window.
protected boolean	doRetrieve(java.io.InputStream is) A hook for your application to read its own data from a persistent stream as part of the application deserialization process.
protected boolean	doStore(java.io.OutputStream os) A hook for your application to write its own data to a persistent stream as part of the application serialization process.
protected void	fireWindowClosedEvent() Notifies all listeners that the window is closing.
protected void	flush() Sends all UI changes to the client.
protected java.lang.String	generateTypeString() Generates a name for the Droplet Server specification of this window.
Application	getApplication() Gets the Application object that contains this window.
protected Component	getComponentByName(java.lang.String name) Returns a reference to a component in this window given its internal name.
MainPanel	getMainPanel() Gets the window's main panel.
MenuBar	getMenuBar() Returns the menu bar for this window, or null if none exists.
int	getProtocolVersion() Returns the version number of the protocol currently in use.
java.lang.String	getTitle() Gets the title of the window (the text that appears in the title bar).
boolean	isMainWindow() Determines whether this is the application's main window.
protected boolean	isWindowTypeCacheable() Called to determine if the window-type is cacheable.
void	locate(int left, int top, int width, int height) Sets the dimensions and location of this window.
void	print(java.lang.String text) Prints the string to the printer.
void	removeCloseListener(WindowCloseListener l) Removes a close listener.
void	removeOpenDialogListener(OpenDialogListener pl) Removes a listener to be notified when a file is chosen from an open dialog (previously added with addOpenDialogListener(com.droplets.api.event.OpenDialogListener)).
MenuBar	setMenuBar(MenuBar menuBar) Sets the menu bar for this window.
void	setTitle(java.lang.String title) Sets the title of the window (the text that appears in the title bar).
void	signalAttentionRequired() Request a visual cue to signal that attention is required on the window.
protected void	start() Called by the Droplet Server each time the client becomes available.
protected void	stop() Called by the Droplet Server each time the client becomes unavailable.

Methods inherited from class com.droplets.api.InvalidationEventSource

addInvalidationListener, ensureValid, fireInvalidationEvent, invalidate, isValid, removeInvalidationListener

Methods inherited from class java.lang.Object

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

Field Detail

m_windowComp

protected com.droplets.api.WindowComponent m_windowComp

The component used to communicate attributes and commands for Windows to clients.

m_token

protected int m_token

The token that represents this object's native peer.

Constructor Detail

Window

public Window(Application application,
              boolean isMainWindow)

Deprecated. Construct a Frame or Dialog instead of this class. They both derive from this class, so the usage is the same, but each class is more explicit about the type of Window you would get. Constructs a new Window.

Parameters:

application - the application object representing the user session in which this window will appear

isMainWindow - pass true if this is the main window of the application, otherwise false. Only one window per Application object (i.e. in each user session) can be the main window.

Window

public Window(Application application,
              boolean isMainWindow,
              boolean isFrame)

Deprecated. Construct a Frame or Dialog instead of this class. They both derive from this class, so the usage is the same, but each class is more explicit about the type of Window you would get. Constructs a new Window.

Parameters:

application - the application object representing the user session in which this window will appear

isMainWindow - pass true if this is the main window of the application, otherwise false. Only one window per Application object (i.e. in each user session) can be the main window.

isFrame - pass true if the window is a Frame, false if it's a Dialog.

Method Detail

start

protected void start()

Called by the Droplet Server each time the client becomes available. The Droplet start() method and the stop() methods are analogous the methods by the same name in java.applet.Applet. The idea is that within a given usage session, the client may periodically be unavailable to receive information from the server. Each time the client state changes from an unavailable state to an available state, start() is called. When the opposite transition occurs, stop() is called.

This default implementation does nothing. Subclasses should override it to do whatever is appropriate.

Typically, a subclass would set the instance-specific values of any components during the first call to this method, while class-specific values would be set in the addAllComponents() method.

stop

protected void stop()

Called by the Droplet Server each time the client becomes unavailable. The Droplet start() method and the stop() methods are analogous the methods by the same name in java.applet.Applet. The idea is that within a given usage session, the client may periodically be unavailable to receive information from the server. Each time the client state changes from an unavailable state to an available state, start() is called. When the opposite transition occurs, stop() is called.

This default implementation does nothing. Subclasses should override it to do whatever is appropriate.

addAllComponents

protected void addAllComponents()

Called by the Droplet Server after the window has been created. This is where you should add the window's components. You cannot add any components after this method returns. This default implementation does nothing. Override to add the components you want.

In a typical application, each Window subclass will generate the same set of components (with the same attributes) for every instance of the class when this method is called. This allows the window description to be cached on the client, greatly reducing the bandwidth required to open a second window of this class.

Important Note!: Because the window description is cached on the client, you must set instance-specific values for components in the start() method, and NOT in addAllComponents().

For example, if a window contains TextFields for entering data, the values of the TextFields should be set in the start() method, while the values of the Labels explaining what data each TextField contains would be set in addAllComponents().

If this is impossible -- typically because your window's contents are determined at runtime -- your window subclass must instead override two Window methods:

1. generateTypeString(). This method sets the key for the hash which the caches are using. You can provide a different name for each window configuration by using a different type string for each different window.

2. isWindowTypeCacheable(). This method disables the client side cache. You must override and return false, if the window has an unknown or large number of possible component sets. See Building Windows at Runtime for more information on this.

flush

protected final void flush()

Sends all UI changes to the client.

getComponentByName

protected Component getComponentByName(java.lang.String name)

Returns a reference to a component in this window given its internal name. This method is necessary because subclasses of Component sometimes get called with names of components rather than references (the action method, for example).

Note that this is a case where we actually want to grant package and subclass access at the same time, which is exactly what the protected keyword does.

Parameters:

name - name of the component to get

Returns:

the component by the given name in this window, or null if there is no such component

getMainPanel

public MainPanel getMainPanel()

Gets the window's main panel. Each window contains a main panel to hold its components. The main panel can be manipulated like other panels (for example, its background color and image can be set).

The main panel is lazily constructed.

Returns:

the main panel of this window

signalAttentionRequired

public void signalAttentionRequired()

Request a visual cue to signal that attention is required on the window. The signal persists until the window is activated.

If the window is a Dialog, the signal stops if either the dialog or its parent window is activated.

Call this method anytime after addAllComponents(). The Droplets platform throws an exception if it is called before or within addAllComponents().

isMainWindow

public boolean isMainWindow()

Determines whether this is the application's main window.

Returns:

true if this is the main window, false if not

getApplication

public Application getApplication()

Gets the Application object that contains this window. Note: this method should not be called in your stop() method.

Returns:

the Application object

getTitle

public java.lang.String getTitle()

Gets the title of the window (the text that appears in the title bar).

Returns:

The title of the window

setTitle

public void setTitle(java.lang.String title)

Sets the title of the window (the text that appears in the title bar).

Parameters:

title - the title of the window (the text that appears in the title bar)

getMenuBar

public MenuBar getMenuBar()

Returns the menu bar for this window, or null if none exists.

setMenuBar

public MenuBar setMenuBar(MenuBar menuBar)

Sets the menu bar for this window.

Parameters:

menuBar - the menu bar to attach to the frame of this window.

print

public void print(java.lang.String text)

Prints the string to the printer. Substrings of the form "[[tag]]" are replaced on the client side with the value of the component with the tag "tag". Use Component.getTag() to get the tag of a component.

Parameters:

text - the text to print with component tag substitutions

addComponent

public void addComponent(Component c)

Deprecated. Replaced by Panel.addComponent(). To add a component to a Window, use getMainPanel().addComponent() instead.

Adds a component to the window. Components should be added in the addAllComponents method, which is called by the server. Calling this method after that one has returned results in an IllegalStateException.

Parameters:

c - The component to add to this window

Throws:

java.lang.IllegalStateException - if this method is invoked after addAllComponents has returned.

See Also:

Panel

close

public void close()

Closes this window. If this is the main window of the application, this method will call Application.requestExit, eventually causing the session to be suspended and the Client to exit.

This is the method that clients should call to programmatically close the window. It is not a callback method and does not get called when the server closes the window (including when the user clicks on the close box).

locate

public void locate(int left,
                   int top,
                   int width,
                   int height)

Sets the dimensions and location of this window.

Parameters:

left - Number of pixels in from the left side of the screen, or -1 to place it in the center

top - Number of pixels down from the top of the screen, or -1 to place it in the center

width - Width of the window in pixels

height - Height of the window in pixels

getProtocolVersion

public int getProtocolVersion()

Returns the version number of the protocol currently in use.

doStore

protected boolean doStore(java.io.OutputStream os)
                   throws java.lang.Exception

A hook for your application to write its own data to a persistent stream as part of the application serialization process. This method is invoked by the Droplet Server when the application is in the process of persisting itself. If you implement this method, you must implement doRetrieve(java.io.InputStream) to read whatever you write here.

If your application does not support serialization, or if an error occurs while storing your data, return false. Be aware that this will cause the entire serialization process to fail.

Throwing any kind of exception is equivalent to returning false.

Parameters:

os - OutputStream to which data can be written

Returns:

true on success, false on failure or if your application does not support serialization

doRetrieve

protected boolean doRetrieve(java.io.InputStream is)
                      throws java.lang.Exception

A hook for your application to read its own data from a persistent stream as part of the application deserialization process. This method is invoked by the Droplet Server when the application is in the process of restoring its state through deserialization. If a subclass implements doStore(java.io.OutputStream), it should implement doRetrieve(java.io.InputStream) to read whatever data it wrote in doStore(java.io.OutputStream).

If your application does not support serialization, or if an error occurs while storing your data, return false. Be aware that this will cause the entire serialization process to fail.

Throwing any kind of exception is equivalent to returning false.

Parameters:

is - InputStream from which data should be read

Returns:

true on success, false on failure or if your application does not support serialization

addCloseListener

public void addCloseListener(WindowCloseListener l)

Adds a listener to be notified when this window is about to close. Note that all listeners will be automatically removed upon closing - no need for client code to do that. Also note that windows can be destroyed without being closed. Listeners only get notified if the window actually gets closed.

Parameters:

l - the listener to add

removeCloseListener

public void removeCloseListener(WindowCloseListener l)

Removes a close listener. Note that all listeners will be automatically removed upon closing - no need for client code to do that.

Parameters:

l - the listener to remove

addOpenDialogListener

public void addOpenDialogListener(OpenDialogListener pl)

Adds a listener to be notified when a file is chosen from an open dialog

Parameters:

pl - the listener to add

See Also:

Application.showOpenDialog(com.droplets.api.Window)

removeOpenDialogListener

public void removeOpenDialogListener(OpenDialogListener pl)

Removes a listener to be notified when a file is chosen from an open dialog (previously added with addOpenDialogListener(com.droplets.api.event.OpenDialogListener)).

Parameters:

pl - the listener to remove

See Also:

Application.sendFile(com.droplets.api.Window, java.lang.String, int, java.lang.String)

fireWindowClosedEvent

protected void fireWindowClosedEvent()

Notifies all listeners that the window is closing.

generateTypeString

protected java.lang.String generateTypeString()

Generates a name for the Droplet Server specification of this window. This method is called by the Droplet Server and returns a string that will be used internally as the name of this window type.

This default implementation simply returns the fully qualified concrete class name of the object it is called on. If you do not override this implementation, then all objects created from a given concrete subclass of Window will be expected to conform to the same window specification -- in other words, they will all need to contain the same components in the same initial configuration.

If you override this method, make sure to return a unique string for each different initial configuration of components within the window.

The Droplets Platform caches window configurations using this string as a key. If your window configuration should not be cached, then you must override isWindowTypeCacheable() to return false.

Returns:

a unique name for this window type

isWindowTypeCacheable

protected boolean isWindowTypeCacheable()

Called to determine if the window-type is cacheable. If your window's components are truly dynamic -- this window configuration will not be used again -- then this method should return false.

Returns:

true if the window-type is cacheable, false otherwise.