org.youscope.clientinterfaces

Interface YouScopeFrame

public interface YouScopeFrame

Generalized interface for frames. YouScope does not use generic classes like JFrame or JInternalFrame to make it easier to switch between the setup of the program. This might be e.g. useful if YouScope should later on be modified to also work directly on microscopes, e.g. over a integrated touch screen. Furthermore, most UI frameworks are not thread save. Since microscope communication should be done in separate threads to not block the UI, we implemented these methods to be thread save.

Author:

langmo

Method Summary

Modifier and Type	Method and Description
void	addChildFrame(YouScopeFrame childFrame) Adds the frame as a child frame to this frame.
void	addFrameListener(YouScopeFrameListener listener) Adds a listener to the frame which is informed e.g.
void	addModalChildFrame(YouScopeFrame childFrame) Adds the frame as a modal child frame to this frame.
YouScopeFrame	createChildFrame() Creates a non-modal child frame.
YouScopeFrame	createFrame() Creates a new non-modal frame.
YouScopeFrame	createModalChildFrame() Creates a modal child frame.
void	endLoading() Removes the indication from this frame that it is loaded or initialized.
java.awt.Dimension	getSize() Returns the size of the frame.
java.lang.String	getTitle() Returns the title of the frame.
boolean	isClosable() Returns if frame is closable by the user.
boolean	isMaximizable() Returns if frame is maximizable.
boolean	isResizable() Returns if frame is resizable.
boolean	isVisible() Returns if frame is visible.
void	pack() Sets the size of the frame such that all UI elements will be (optimally) sized.
void	relocateFrameTo(YouScopeFrame targetFrame) Relocates all calls to this object's functions to the corresponding functions of the target frame.
void	removeFrameListener(YouScopeFrameListener listener) Removes a previously added listener.
void	setClosable(boolean closable) Sets if the frame is closable by the user (i.e.
void	setContentPane(java.awt.Component contentPane) Sets the content pane of this frame.
void	setMargins(int left, int top, int right, int bottom) Sets the margins between the frame borders and the frame content (i.e.
void	setMaximizable(boolean maximizable) Sets if the user should be able to maximize the frame.
void	setMaximum(boolean maximum) Maximizes the frame (if maximum == true) or restores the actual frame's size (if maximum == false).
void	setResizable(boolean resizable) Sets if the frame is resizable or not.This might only be interpreted as a hint by certain implementations.
void	setSize(java.awt.Dimension size) Sets the size of the frame.
void	setTitle(java.lang.String title) Sets the title of the frame.
void	setToErrorState(java.lang.String message, java.lang.Exception e) Removes all previously added UI elements from the frame and displays instead the given error.
void	setVisible(boolean visible) Sets the visibility of the frame and its content.
void	startInitializing() Indicates to the user, in one or the other way, that the content of the frame is currently initialized.
void	startLoading() Similar to startInitializing(), only that in this case the UI is already initialized, but certain data has to be loaded e.g.
void	toFront() Positions the frame at the front and sets the focus to this frame.

Method Detail

setContentPane

void setContentPane(java.awt.Component contentPane)

Sets the content pane of this frame. The content pane can be set from any thread (setting is guaranteed to be thread-save), however, after setting the content pane it should be only manipulated by the UI thread (e.g. the thread processing action events of a button, but not a worker thread). To change the content pane after setting it from a thread which is not the UI thread, see SwingUtilities.invokeLater and SwingUtilities.invokeAndWait().

Parameters:

contentPane - The new content pane of the frame.

setVisible

void setVisible(boolean visible)

Sets the visibility of the frame and its content. This function is guaranteed to be thread save.

Parameters:

visible - True if frame should be visible, false otherwise.

setMargins

void setMargins(int left,
                int top,
                int right,
                int bottom)

Sets the margins between the frame borders and the frame content (i.e. the margins around the content pane).

Parameters:

left - margin left, in pixels.

top - margin top, in pixels.

right - margin right, in pixels.

bottom - margin bottom, in pixels.

isVisible

boolean isVisible()

Returns if frame is visible. This function is guaranteed to be thread save.

Returns:

True if frame is visible, false otherwise.

setMaximum

void setMaximum(boolean maximum)

Maximizes the frame (if maximum == true) or restores the actual frame's size (if maximum == false). This function is guaranteed to be thread save.

Parameters:

maximum - True if frame should be maximized.

createChildFrame

YouScopeFrame createChildFrame()

Creates a non-modal child frame. Child frames get automatically closed if the parent frame is closed. This function is guaranteed to be thread save. Same as calling createFrame() and addChildFrame().

Returns:

A new frame.

createModalChildFrame

YouScopeFrame createModalChildFrame()

Creates a modal child frame. The parent frame gets blocked until the child frame is closed. This function is guaranteed to be thread save. Same as calling createFrame() and addModalChildFrame().

Returns:

A new frame.

createFrame

YouScopeFrame createFrame()

Creates a new non-modal frame. This frame gets not closed if the parent frame is closed. This function is guaranteed to be thread save.

Returns:

A new frame.

addChildFrame

void addChildFrame(YouScopeFrame childFrame)

Adds the frame as a child frame to this frame. This implies that the child frame is closed when this frame is closed.

Parameters:

childFrame - The child frame to add.

addModalChildFrame

void addModalChildFrame(YouScopeFrame childFrame)

Adds the frame as a modal child frame to this frame. This implies that it becomes impossible to edit the current frame as long as the child frame is open, and that the focus is automatically transferred to the child frame whenever this frame gets it.

Parameters:

childFrame - The frame to add as a modal child frame.

setSize

void setSize(java.awt.Dimension size)

Sets the size of the frame. Be aware that this might or might not only be interpreted as a hint for the UI. This function is guaranteed to be thread save.

Parameters:

size - Size of the frame.

getSize

java.awt.Dimension getSize()

Returns the size of the frame. This function is guaranteed to be thread save.

Returns:

Size of the frame.

pack

void pack()

Sets the size of the frame such that all UI elements will be (optimally) sized. This function is guaranteed to be thread save.

setResizable

void setResizable(boolean resizable)

Sets if the frame is resizable or not.This might only be interpreted as a hint by certain implementations. This function is guaranteed to be thread save.

Parameters:

resizable - True if frame is resizable, false otherwise.

setClosable

void setClosable(boolean closable)

Sets if the frame is closable by the user (i.e. if a "close-button" is shown at the top of the frame). This might only be interpreted as a hint by certain implementations. This function is guaranteed to be thread save.

Parameters:

closable - True if user should be able to close the frame in the usual way.

setMaximizable

void setMaximizable(boolean maximizable)

Sets if the user should be able to maximize the frame. This might only be interpreted as a hint by certain implementations. This function is guaranteed to be thread save.

Parameters:

maximizable - True if frame should be maximizable.

isResizable

boolean isResizable()

Returns if frame is resizable. This function is guaranteed to be thread save.

Returns:

True if frame is resizable, otherwise false.

isClosable

boolean isClosable()

Returns if frame is closable by the user. This function is guaranteed to be thread save.

Returns:

True if frame is closable.

isMaximizable

boolean isMaximizable()

Returns if frame is maximizable. This function is guaranteed to be thread save.

Returns:

True if frame is maximizable.

addFrameListener

void addFrameListener(YouScopeFrameListener listener)

Adds a listener to the frame which is informed e.g. if the frame is closed. This function is guaranteed to be thread save.

Parameters:

listener - The listener to add.

removeFrameListener

void removeFrameListener(YouScopeFrameListener listener)

Removes a previously added listener. This function is guaranteed to be thread save.

Parameters:

listener - The listener to remove.

setTitle

void setTitle(java.lang.String title)

Sets the title of the frame. This title may be displayed or not by the implementation. This function is guaranteed to be thread save.

Parameters:

title - Title of the frame.

getTitle

java.lang.String getTitle()

Returns the title of the frame. This function is guaranteed to be thread save.

Returns:

The title of the frame.

setToErrorState

void setToErrorState(java.lang.String message,
                     java.lang.Exception e)

Removes all previously added UI elements from the frame and displays instead the given error. Should be called when an error happened which is such serious that the frame cannot be used by the user anymore. This function is guaranteed to be thread save.

Parameters:

message - The message describing the error.

e - The error.

startInitializing

void startInitializing()

Indicates to the user, in one or the other way, that the content of the frame is currently initialized. This function should be called if the initialization takes significant time (e.g. due to necessary communication with the microscope). After the function is called, a worker thread should be started doing the real initialization, such that the UI is not blocked. After initialization, the worker thread should then call setContentPane() followed by endLoading(). The content pane should not be set before all elements of the content pane were created (i.e. no components of the content pane should be manipulated by the worker thread after calling setContentPane()). This function is guaranteed to be thread save.

startLoading

void startLoading()

Similar to startInitializing(), only that in this case the UI is already initialized, but certain data has to be loaded e.g. after some user input. The loading should also be done in a worker thread which is calling endLoading() after finishing. This function is guaranteed to be thread save. However, if the content pane was already set prior to a call to this function, the worker thread should not manipulate any component of the content pane anymore. Instead, it should either create and set a new content pane (including all components of the content pane) or only manipulate the content pane by using the UI thread (see SwingUtilities.invokeLater and SwingUtilities.invokeAndWait()).

endLoading

void endLoading()

Removes the indication from this frame that it is loaded or initialized. This function should be called from a worker thread, after the main thread has called startInitializing() or startLoading(). This function is guaranteed to be thread save.

toFront

void toFront()

Positions the frame at the front and sets the focus to this frame.

relocateFrameTo

void relocateFrameTo(YouScopeFrame targetFrame)

Relocates all calls to this object's functions to the corresponding functions of the target frame. With this mechanism, the pointer to the physical frame containing the content can be switched without any other function using the frame noticing it. Should in general only be used for specific purposes.

Parameters:

targetFrame - The target frame calls to this frame should be relocated to.