A panel containing a
* {@link Displayable Displayable} object,
* with the option of a title and an
* {@link Annotation Annotation}.
The title can appear at * the top or bottom of the view. * * The object on display always appears * at the center of the view and takes up * all available space. * * The annotation can appear at * any of the four main compass directions * relative to the object on display.
* *The functionality of this container assumes use of a
* {@link BorderLayout BorderLayout}
* and effects are undefined if the user changes this layout.
The Display is the simplest and most versatile
* of the recursive container classes available in the JPT.
*
* Displays can be recursively nested to any depth,
* although screen real estate imposes a physical limit
* to the number of displays that could be contained
* within an actual visualization.
null,
* an empty DisplayPanel will be provided
* on any attempt to set a null displayed object.
*/
protected Displayable view = null;
/** The annotation for this display. */
protected Annotation caption = null;
//////////////////
// Constructors //
//////////////////
/**
* Constructs a display
* containing an empty DisplayPanel,
* with no annotation or title.
*
* @see #Display(Displayable)
* @see #Display(Displayable, String, String)
* @see #Display(Displayable, String, String, int, int)
*/
public Display() {
this(new DisplayPanel(),
null,
null,
DEFAULT_ANNOTATION_ALIGNMENT,
DEFAULT_TITLE_ALIGNMENT);
}
/**
* Constructs a display
* containing the given object,
* with no annotation or title.
*
* @param viewObject the object to display
* @see #Display()
* @see #Display(Displayable, String, String)
* @see #Display(Displayable, String, String, int, int)
*/
public Display(Displayable viewObject) {
this(viewObject,
DEFAULT_ANNOTATION_TEXT,
DEFAULT_TITLE_TEXT,
DEFAULT_ANNOTATION_ALIGNMENT,
DEFAULT_TITLE_ALIGNMENT);
}
/**
* Constructs a display
* containing the given object,
* with the given annotation text and title text.
*
* @param viewObject the object to display
* @param annotationText the annotation text
* @param titleText the title text
* @see #Display()
* @see #Display(Displayable)
* @see #Display(Displayable, String, String, int, int)
*/
public Display(Displayable viewObject,
String annotationText,
String titleText)
{
this(viewObject,
annotationText,
titleText,
DEFAULT_ANNOTATION_ALIGNMENT,
DEFAULT_TITLE_ALIGNMENT);
}
/**
* Constructors a display
* containing the given object,
* with the given annotation text and title text,
* using the given alignments for the title and annotation.
*
* @param viewObject the object to display
* @param annotationText the annotation text
* @param titleText the title text
* @param annotationAlign the relative alignment
* of the annotation relative to the object on display
* @param titleAlign the relative alignment
* of the title relative to the object on display
* @see #Display()
* @see #Display(Displayable)
* @see #Display(Displayable, String, String)
*/
public Display(
Displayable viewObject,
String annotationText,
String titleText,
int annotationAlign,
int titleAlign)
{
// set the layout to allow for the annotation
// to be in any of the four compass point positions
// with a 5 pixel gutter between components
setLayout(new BorderLayout(5, 5));
// display the given object
setDisplay(viewObject);
// initialize the annotation for the view
setAnnotation(new Annotation(annotationText));
setAnnotationAlignment(annotationAlign);
// initialize the title for the view
setTitleText(titleText);
setTitleAlignment(titleAlign);
}
/**
* Constructs a display
* containing the given object,
* with the remaining settings taken from
* the given Settings object.
*
* @param viewObject the object to display
* @param settings the object containing the desired settings
*/
public Display(Displayable viewObject, Settings settings) {
// must use inline if-then-else because constructor
// call must be first line
this(viewObject,
settings != null
? settings.annotationText
: DEFAULT_ANNOTATION_TEXT,
settings != null
? settings.titleText
: DEFAULT_TITLE_TEXT,
settings != null
? settings.annotationAlign
: DEFAULT_ANNOTATION_ALIGNMENT,
settings != null
? settings.titleAlign
: DEFAULT_TITLE_ALIGNMENT);
}
/////////////////
// Displayable //
/////////////////
public void setViewState(String data) {
view.setViewState(data);
// notify listeners of property change
firePropertyChange(
VIEW_STATE,
null,
data);
}
public String getViewState() {
return view.getViewState();
}
public void setDefaultViewState(String data) {
view.setDefaultViewState(data);
// notify listeners of property change
firePropertyChange(
DEFAULT_VIEW_STATE,
null,
data);
}
////////////////
// Public API //
////////////////
/**
* Sets the annotation text
* to the given text.
*
* If the given text is null,
* the current annotation is removed from this display
* an no annotation is displayed.
*
* If the annotation text was previously null,
* a new Annotation object is created.
*
* @param text the annotation text to display
* @see #getAnnotationText()
*/
public void setAnnotationText(String text) {
String oldText = getAnnotationText();
// set the text
if (caption == null)
setAnnotation(new Annotation(text));
else
caption.setText(text);
// if the annotation text has changed
if ((getAnnotationText() != null) &&
(!getAnnotationText().equals(oldText)))
{
// notify listeners of property change
firePropertyChange(
ANNOTATION_TEXT,
oldText,
text);
}
}
/**
* Returns the annotation text, or null
* if this display does not have an annotation.
*
* If this display does not contain an annotation,
* this method returns null.
*
* @see #setAnnotationText(String)
*/
public String getAnnotationText() {
if (caption == null)
return null;
else
return caption.getText();
}
/**
* Sets the alignment of the annotation
* relative to the displayed object.
*
* If the given alignment value is invalid,
* the annotation alignment is not changed.
*
* @param alignment the new alignment for the annotation
* relative to the displayed object
* @see #getAnnotationAlignment()
* @see #ABOVE
* @see #BELOW
* @see #LEFT
* @see #RIGHT
* @see #DEFAULT
*/
public void setAnnotationAlignment(int alignment) {
int oldAlignment = getAnnotationAlignment();
switch (alignment) {
// check for valid alignment value
case LEFT:
case RIGHT:
case ABOVE:
case BELOW:
aAlign = alignment;
break;
// check for request for default alignment value
case DEFAULT:
aAlign = DEFAULT_ANNOTATION_ALIGNMENT;
break;
// ignore alignment value out of bounds
default:
return;
}
// update and layout annotation within this display
revalidateAnnotationAndAlignment();
// if the alignment has changed
if (getAnnotationAlignment() != oldAlignment) {
// notify listeners of property change
firePropertyChange(
ANNOTATION_ALIGNMENT,
oldAlignment,
getAnnotationAlignment());
}
}
/**
* Returns the value for the alignment of the annotation
* relative to the displayed object.
*
* @see #setAnnotationAlignment(int)
* @see #ABOVE
* @see #BELOW
* @see #LEFT
* @see #RIGHT
*/
public int getAnnotationAlignment() {
return aAlign;
}
/**
* Sets the title text
* to the given text.
*
* If the given text is null,
* the current titled border is removed from this display
* and no title is displayed.
*
* If the title text was previously null,
* a new titled border is created.
*
* @param text the title text to display
* @see #getTitleText()
*/
public void setTitleText(String text) {
String oldTitle = getTitleText();
title = text;
// update and layout title visualization
revalidateTitleAndAlignment();
// if the title text has changed
if ((getTitleText() != null) &&
(!getTitleText().equals(oldTitle)))
{
// notify listeners of property change
firePropertyChange(
TITLE_TEXT,
oldTitle,
getTitleText());
}
}
/**
* Returns the title text, or null
* if this display does not have a title.
*
* @see #setTitleText(String)
*/
public String getTitleText() {
return title;
}
/**
* Sets the alignment of the title
* relative to the displayed object.
*
* If the given alignment value is invalid,
* the title alignment is not changed.
*
* @param alignment the new alignment for the title
* relative to the displayed object
* @see #getTitleAlignment()
* @see #ABOVE
* @see #BELOW
* @see #DEFAULT
*/
public void setTitleAlignment(int alignment) {
int oldAlignment = getTitleAlignment();
switch (alignment) {
// check for valid alignment value
case ABOVE:
case BELOW:
tAlign = alignment;
break;
// check for request for default alignment
case DEFAULT:
tAlign = DEFAULT_TITLE_ALIGNMENT;
break;
// ignore alignment value out of bounds
default:
return;
}
// update and layout title within this display
revalidateTitleAndAlignment();
// if the title alignment has changed
if (getTitleAlignment() != oldAlignment) {
// notify listeners of property change
firePropertyChange(
ANNOTATION_ALIGNMENT,
oldAlignment,
getTitleAlignment());
}
}
/**
* Returns the alignment value of the title
* relative to the object on display.
*
* @see #setTitleAlignment(int)
* @see #ABOVE
* @see #BELOW
*/
public int getTitleAlignment() {
return tAlign;
}
/**
* Sets the displayed object
* to the given Displayable object.
*
* If the given object is null,
* an empty DisplayPanel is created
* and displayed.
*
* @param viewObject the new object to display
* @see #getDisplay()
*/
public void setDisplay(Displayable viewObject) {
Displayable oldDisplay = getDisplay();
// as long as the display will change
if (viewObject != oldDisplay) {
// remove the old view
if (view != null)
remove((Component)view);
// create an empty panel if no view is provided
if (viewObject == null)
viewObject = new DisplayPanel();
// store the view and display it
view = viewObject;
add((Component)view, BorderLayout.CENTER);
// update the visualization
revalidate();
// notify listeners of property change
firePropertyChange(
DISPLAY,
oldDisplay,
getDisplay());
}
}
/**
* Returns the displayed object.
*
* @see #setDisplay(Displayable)
*/
public Displayable getDisplay() {
return view;
}
/**
* Sets the annotation component
* to the given Annotation.
*
* If the given object is null,
* the current annotation is removed from this display
* and no annotation is displayed.
*
* @param annotation the new Annotation
* @see #getAnnotation()
*/
public void setAnnotation(Annotation annotation) {
Annotation oldAnnotation = getAnnotation();
// remove the old annotation if necessary
if (caption != null) {
super.remove(caption);
caption = null;
}
// create a new annotation if necessary
if (annotation != null) {
caption = annotation;
super.add(
caption,
JPTUtilities.getBorderLayoutLocation(aAlign));
}
// update the visualization
revalidate();
// if the annotation has changed
if (annotation != oldAnnotation) {
// notify listeners of property change
firePropertyChange(
ANNOTATION,
oldAnnotation,
getAnnotation());
}
}
/**
* Returns the annotation component, or null
* if this display does not have an annotation.
*
* @see #setAnnotation(Annotation)
*/
public Annotation getAnnotation() {
return caption;
}
/**
* Sets the properties for this display to the settings
* taken from the given Settings object.
*
* If the given object is null,
* then all settings are reset to defaults.
*
* @param s encapsulation of the new settings for this display
*/
public void setSettings(Settings s) {
if (s != null) {
setAnnotationText(s.annotationText);
setTitleText(s.titleText);
setAnnotationAlignment(s.annotationAlign);
setTitleAlignment(s.titleAlign);
}
else {
setAnnotationText(DEFAULT_ANNOTATION_TEXT);
setTitleText(DEFAULT_TITLE_TEXT);
setAnnotationAlignment(DEFAULT_ANNOTATION_ALIGNMENT);
setTitleAlignment(DEFAULT_TITLE_ALIGNMENT);
}
}
/**
* Returns the properties for this display
* as a Settings object.
*/
public Settings getSettings() {
return new Settings(
getAnnotationText(),
getTitleText(),
getAnnotationAlignment(),
getTitleAlignment());
}
///////////////////////
// Protected methods //
///////////////////////
/**
* Rebuilds the titled border and its alignment
* based on the current title text and alignment.
*/
protected void revalidateTitleAndAlignment() {
// if there is a title
if (title != null) {
// select proper titled border location
int verticalLocation =
tAlign == ABOVE ? TitledBorder.TOP : TitledBorder.BOTTOM;
// create a titled border with the appropriate alignment
setBorder(new CompoundBorder(
new TitledBorder(
BorderFactory.createEtchedBorder(),
" " + title + " ",
TitledBorder.CENTER,
verticalLocation),
new EmptyBorder(5, 5, 5, 5)));
}
// otherwise remove the current border
else setBorder(new EmptyBorder(0, 0, 0, 0));
// update the visualization
revalidate();
}
/**
* Rebuilds the annotation and its alignment
* based on the current annotation text and alignment.
*/
protected void revalidateAnnotationAndAlignment() {
// if there is an annotation in this display
if (caption != null) {
// remove the annotation from its old position
super.remove(caption);
// and place it in the proper location
super.add(
caption,
JPTUtilities.getBorderLayoutLocation(aAlign));
}
// update the visualization
revalidate();
}
///////////////////
// Inner classes //
///////////////////
/**
* Data structure encapsulating
* the content and layout properties
* for a Display.