*** This interface is subject to change. ***

com.sas.swing.visuals
Interface PanelInterface

All Known Implementing Classes:

BaseSwingSelectorPanel, DataItemSelector, EntityAttributeValuePanel, FilterAndRankSelector, FormatSelectorPanel, OLAPSortSelector, PercentCalculationsSelector, RankingSelector, ShowDetailSelector, SimpleCalculatedItemEditPanel, SimpleCalculatedItemSelector, SortSelector, TotalsSelector

@SASScope(value="ALL")
@SubjectToChange
public interface PanelInterface

Defines a common set of functionality that a panel should surface to be hosted in an application.

Instead of writing a panel, a developer often writes a tabbed pane or dialog that contains the definitions of the components that are contained within. Then later it is determined that those components have use elsewhere in an application. To solve this problem those components must be abstracted out or the source code must be cloned. If those components were originally abstracted out into a single reusable component (i.e. panel) it would be simple to reuse the panel wherever it is needed. The problem with this approach is that there is not a common way to do this. Each application would determine what the definition of a "common" panel is. PanelInterface solves this problem by defining the required functionality for a panel to be embedded in some container and to be correctly notified of the lifetime of that panel (when to apply changes, when to hide it, etc).

Lifetime

Sometimes panels simply convey information (i.e. properties), however, they often provide some editing capabilities. Therefore, then need to know when to apply or cancel any changes that have been during that panel's lifetime. The following methods provides a means of determining certain events that can occur on a panel:

• onApply
• onCancel
• onClose

Host Containers

Often panels are embedded in tabbed panes or dialogs. The user then must decide on a title for the tab or dialog that the panel is embedded in. The panel can provide the title itself through the following methods:

• getDialogTitle
• getTabTitle

Context-Sensitive Help

Some panels want to provide context-sensitive help (i.e. via a help button on a hosting dialog). The following method provides a means of doing this:

• getHelpID

Invalid Contents

If a panel is going to live primarily in a dialog, it may be important for that panel to control whether or not any changes can be applied based on the state of its contents. If the panel considers its contents invalid it may want to disable the "ok" and "apply" buttons in the hosting dialog. PanelInterface solves this with the contentsValid property. A PanelInterface-aware dialog can listen for this property such that when it receives notification that it has changed, the dialog can update its buttons accordingly. Likewise, an implementation of PanelInterface should fire a PropertyChangeEvent for the contentsValid property whenever the state changes.

Field Summary

static java.lang.String

CONTENTS_VALID_PROPERTY Property identifier for the "contentsValid" property.

Method Summary

abstract java.lang.String	getDialogTitle() Returns a title for this panel that should be displayed on a dialog's title bar.
abstract java.lang.String	getHelpID() Returns the help id for this panel.
abstract javax.swing.JComponent	getPanel() Returns the panel to be displayed.
abstract java.lang.String	getTabTitle() Returns a title for this panel that should be displayed as a title on a tab.
abstract boolean	isContentsValid() Indicates if the panel's contents are in a valid state.
abstract boolean	isYesNo() Indicates if the panel asks a yes-no or ok type question.
abstract void	onApply() Apply any changes that may have been made in the panel.
abstract void	onCancel() Cancel any changes that may have been made in the panel.
abstract void	onClose() Indicates that the panel is being closed.
abstract void	setContentsValid(boolean newValue) Sets the valid state of the panel's contents.

Field Detail

CONTENTS_VALID_PROPERTY

static final java.lang.String CONTENTS_VALID_PROPERTY

Property identifier for the "contentsValid" property.

See Also:

isContentsValid(), setContentsValid(boolean), Constant Field Values

Method Detail

onApply

void onApply()

Apply any changes that may have been made in the panel. For example, a dialog may call this in response to its "apply" or "ok" button being pressed.

onCancel

void onCancel()

Cancel any changes that may have been made in the panel. For example, a dialog may call this in response to its "cancel" button being pressed.

onClose

void onClose()

Indicates that the panel is being closed. Any necessary cleanup that is needed can be performed in this method. This should be called after onApply() or onClose() is called.

getDialogTitle

java.lang.String getDialogTitle()

Returns a title for this panel that should be displayed on a dialog's title bar.

Returns:

the title to display if used in a dialog

getTabTitle

java.lang.String getTabTitle()

Returns a title for this panel that should be displayed as a title on a tab.

Returns:

the title to display if used in a tabbed pane

getPanel

javax.swing.JComponent getPanel()

Returns the panel to be displayed. Most panels will implement this interface and therefore return this.

getHelpID

java.lang.String getHelpID()

Returns the help id for this panel. If null is returned, a help button is not added for this panel.

Returns:

the help id for this panel or null

isYesNo

boolean isYesNo()

Indicates if the panel asks a yes-no or ok type question. This information can be used, for instance, by a dialog to determine if it should display an "OK" button or "Yes" and "No" buttons.

Returns:

true if the panel asks a yes-no type question, false if the panel asks an ok type question

isContentsValid

boolean isContentsValid()

Indicates if the panel's contents are in a valid state. This should always be true except for when the panel is behaving as an editor and incomplete information has been entered. This state can be used by a dialog, for example, to enable/disable the its "apply" buttons ("OK", "Yes", etc).

Returns:

true if the panel's contents are valid, otherwise false

See Also:

setContentsValid(boolean)

setContentsValid

void setContentsValid(boolean newValue)

Sets the valid state of the panel's contents. This should be implemented as a bound property so that containers can receive notification to update properly. PanelInterface provides the property name identifier CONTENTS_VALID_PROPERTY as a convenience for implementing this as a bound property.

Parameters:

newValue - the new valid state for the panel's contents

See Also:

isContentsValid()

*** This interface is subject to change. ***