/*
* Copyright (c) 2005 Thomas Weise
*
* E-Mail : tweise@gmx.de
* Creation Date : 2005-06-17 20:01:54
* Original Filename: org.sfc.gui.windows.IWindow.java
* Version : 3.0.1
* Last modification: 2006-06-21
* by: Thomas Weise
*
* License : GNU LESSER GENERAL PUBLIC LICENSE
* Version 2.1, February 1999
* You should have received a copy of this license along
* with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston,
* MA 02111-1307, USA or download the license under
* http://www.gnu.org/copyleft/lesser.html.
*
* Warranty : This software is provided "as is" without any
* warranty; without even the implied warranty of
* merchantability or fitness for a particular purpose.
* See the Gnu Lesser General Public License for more
* details.
*/
package org.sfc.gui.windows;
import java.awt.AWTKeyStroke;
import java.awt.Component;
import java.awt.Container;
import java.awt.Cursor;
import java.awt.Dimension;
import java.awt.Frame;
import java.awt.Graphics;
import java.awt.Image;
import java.awt.KeyboardFocusManager;
import java.awt.LayoutManager;
import java.awt.MenuContainer;
import java.awt.Toolkit;
import java.awt.Window;
import java.awt.im.InputContext;
import java.awt.image.ImageObserver;
import java.beans.PropertyChangeListener;
import java.io.Serializable;
import java.util.Locale;
import java.util.Set;
import javax.accessibility.Accessible;
import javax.swing.JMenuBar;
import javax.swing.RootPaneContainer;
import javax.swing.WindowConstants;
import org.sfc.scoped.ICloseable;
/**
* This interface is common to all stk windows. It allows you to treat all
* windows the same way, no matter if they are JFrame
s,
* JDialog
s or even JInternalFrame
s.
*
* @author Thomas Weise
*/
public interface IWindow extends ICloseable, Accessible, MenuContainer,
RootPaneContainer, ImageObserver,
Serializable
{
/**
* Sets the menubar for this window.
*
* @param p_menubar the menubar being placed in the window
*/
public abstract void setJMenuBar (final JMenuBar p_menubar);
/**
* Returns the menubar set on this window.
*
* @return the menubar for this window
*/
public abstract JMenuBar getJMenuBar ();
/**
* Returns the icon associated to the window.
*
* @return The icon of the window or null if no icon is assigned.
*/
public abstract Image get_icon ();
/**
* Sets the icon of the window.
*
* @param p_icon The icon of the window.
*/
public abstract void set_icon (final Image p_icon);
/**
* The pack method of the window.
*/
public abstract void pack ();
/**
* Returns the underlying os-window of the IWindow
.
* @return The window-instance of this IWindow
.
*/
public abstract Window get_window ();
/**
* Returns the underlying frame of the IWindow
.
* @return The frame-instance of this IWindow
.
*/
public abstract Frame get_frame ();
/**
* Sets wether the window is visible or not.
* @param p_visible true
to show the window,
* false
to hide the window.
*/
public abstract void setVisible (final boolean p_visible);
/**
* Returns wether the window is visible or not.
* @return true
if the window is visible, false
* if it is hidden.
*/
public abstract boolean isVisible ();
/**
* This method will be called when the user decided to close the window
* via some input like hitting the "close"-button in the system menu.
* You can emulate a user-close action by calling this method. The exact
* behavior of this method is not defined, it may or may not call the
* close()
method of the window.
*/
public abstract void close_by_user ();
/**
* Set the size of the frame.
* @param p_width The new width of the frame.
* @param p_height The new height of the frame.
*/
public abstract void setSize (final int p_width,
final int p_height);
/**
* Returns the current width of the frame.
* @return The current width of the frame.
*/
public abstract int getWidth ();
/**
* Returns the current height of the frame.
* @return The current height of the frame.
*/
public abstract int getHeight ();
/**
* Returns the operation that occurs when the user
* initiates a "close" on this frame.
*
* @return an integer indicating the window-close operation
* @see #setDefaultCloseOperation
*/
public abstract int getDefaultCloseOperation();
/**
* Sets the operation that will happen by default when
* the user initiates a "close" on this frame.
* You must specify one of the following choices:
*
*
DO_NOTHING_ON_CLOSE
* (defined in WindowConstants
):
* Don't do anything; require the
* program to handle the operation in the windowClosing
* method of a registered WindowListener
object.
*
* HIDE_ON_CLOSE
* (defined in WindowConstants
):
* Automatically hide the frame after
* invoking any registered WindowListener
* objects.
*
* DISPOSE_ON_CLOSE
* (defined in WindowConstants
):
* Automatically hide and dispose the
* frame after invoking any registered WindowListener
* objects.
*
* EXIT_ON_CLOSE
* (defined in JFrame
):
* Exit the application using the System
* exit
method. Use this only in applications.
*
* The value is set to HIDE_ON_CLOSE
by default.
*
* Note: When the last displayable window within the
* Java virtual machine (VM) is disposed of, the VM may
* terminate. See
* AWT Threading Issues for more information.
*
* @param p_operation the operation which should be performed when the
* user closes the frame
* @exception IllegalArgumentException if defaultCloseOperation value
* isn't one of the above valid values
* @see #getDefaultCloseOperation
* @see WindowConstants
* @throws SecurityException
* if EXIT_ON_CLOSE
has been specified and the
* SecurityManager
will
* not allow the caller to invoke System.exit
* @see java.lang.Runtime#exit(int)
*/
public abstract void setDefaultCloseOperation(final int p_operation);
/**
* Sets the LayoutManager
.
* Overridden to conditionally forward the call to the
* contentPane
.
* Refer to {@link javax.swing.RootPaneContainer} for
* more information.
*
* @param p_manager the LayoutManager
* @see javax.swing.RootPaneContainer
*/
public abstract void setLayout(final LayoutManager p_manager);
/**
* Just calls paint(g)
. This method was overridden to
* prevent an unnecessary call to clear the background.
*
* @param p_g the Graphics context in which to paint
*/
public abstract void update(final Graphics p_g);
/**
* Gets the title of the frame. The title is displayed in the
* frame's border.
* @return the title of this frame, or an empty string ("")
* if this frame doesn't have a title.
* @see #setTitle(String)
*/
public abstract String getTitle() ;
/**
* Indicates whether this frame is resizable by the user.
* By default, all frames are initially resizable.
* @return true
if the user can resize this frame;
* false
otherwise.
* @see java.awt.Frame#setResizable(boolean)
*/
public abstract boolean isResizable();
/**
* Sets whether this frame is resizable by the user.
* @param p_resizable true
if this frame is resizable;
* false
otherwise.
* @see java.awt.Frame#isResizable
*/
public abstract void setResizable(final boolean p_resizable);
/**
* Sets the title for this frame to the specified string.
* @param p_title the title to be displayed in the frame's border.
* A null
value
* is treated as an empty string, "".
* @see #getTitle
*/
public abstract void setTitle(final String p_title);
/**
* Releases all of the native screen resources used by this
* Window
, its subcomponents, and all of its owned
* children. That is, the resources for these Component
s
* will be destroyed, any memory they consume will be returned to the
* OS, and they will be marked as undisplayable.
*
* The Window
and its subcomponents can be made displayable
* again by rebuilding the native resources with a subsequent call to
* pack
or show
. The states of the recreated
* Window
and its subcomponents will be identical to the
* states of these objects at the point where the Window
* was disposed (not accounting for additional modifications between
* those actions).
*
* Note: When the last displayable window * within the Java virtual machine (VM) is disposed of, the VM may * terminate. See * AWT Threading Issues for more information. * @see Component#isDisplayable * @see #pack */ public abstract void dispose(); /** * If this Window is visible, brings this Window to the front and may make * it the focused Window. *
* Places this Window at the top of the stacking order and shows it in * front of any other Windows in this VM. No action will take place if this * Window is not visible. Some platforms do not allow Windows which own * other Windows to appear on top of those owned Windows. Some platforms * may not permit this VM to place its Windows above windows of native * applications, or Windows of other VMs. This permission may depend on * whether a Window in this VM is already focused. Every attempt will be * made to move this Window as high as possible in the stacking order; * however, developers should not assume that this method will move this * Window above all other windows in every situation. *
* Because of variations in native windowing systems, no guarantees about * changes to the focused and active Windows can be made. Developers must * never assume that this Window is the focused or active Window until this * Window receives a WINDOW_GAINED_FOCUS or WINDOW_ACTIVATED event. On * platforms where the top-most window is the focused window, this method * will probably focus this Window, if it is not already focused. On * platforms where the stacking order does not typically affect the focused * window, this method will probably leave the focused and active * Windows unchanged. *
* If this method causes this Window to be focused, and this Window is a * Frame or a Dialog, it will also become activated. If this Window is * focused, but it is not a Frame or a Dialog, then the first Frame or * Dialog that is an owner of this Window will be activated. * * @see #toBack */ public abstract void toFront(); /** * If this Window is visible, sends this Window to the back and may cause * it to lose focus or activation if it is the focused or active Window. *
* Places this Window at the bottom of the stacking order and shows it * behind any other Windows in this VM. No action will take place is this * Window is not visible. Some platforms do not allow Windows which are * owned by other Windows to appear below their owners. Every attempt will * be made to move this Window as low as possible in the stacking order; * however, developers should not assume that this method will move this * Window below all other windows in every situation. *
* Because of variations in native windowing systems, no guarantees about
* changes to the focused and active Windows can be made. Developers must
* never assume that this Window is no longer the focused or active Window
* until this Window receives a WINDOW_LOST_FOCUS or WINDOW_DEACTIVATED
* event. On platforms where the top-most window is the focused window,
* this method will probably cause this Window to lose focus. In
* that case, the next highest, focusable Window in this VM will receive
* focus. On platforms where the stacking order does not typically affect
* the focused window, this method will probably leave the focused
* and active Windows unchanged.
*
* @see #toFront
*/
public abstract void toBack();
/**
* Returns the toolkit of this frame.
* @return the toolkit of this window.
* @see Toolkit
* @see Toolkit#getDefaultToolkit
* @see Component#getToolkit
*/
public abstract Toolkit getToolkit();
/**
* Gets the warning string that is displayed with this window.
* If this window is insecure, the warning string is displayed
* somewhere in the visible area of the window. A window is
* insecure if there is a security manager, and the security
* manager's checkTopLevelWindow
method returns
* false
when this window is passed to it as an
* argument.
*
* If the window is secure, then getWarningString
* returns null
. If the window is insecure, this
* method checks for the system property
* awt.appletWarning
* and returns the string value of that property.
* @return the warning string for this window.
* @see java.lang.SecurityManager#checkTopLevelWindow(java.lang.Object)
*/
public abstract String getWarningString();
/**
* Gets the Locale
object that is associated
* with this window, if the locale has been set.
* If no locale has been set, then the default locale
* is returned.
* @return the locale that is set for this window.
* @see java.util.Locale
* @since JDK1.1
*/
public abstract Locale getLocale();
/**
* Gets the input context for this window. A window always has an input context,
* which is shared by subcomponents unless they create and set their own.
* @return The input context.
* @see Component#getInputContext
* @since 1.2
*/
public abstract InputContext getInputContext();
/**
* Set the cursor image to a specified cursor.
* @param p_cursor One of the constants defined
* by the Cursor
class. If this parameter is null
* then the cursor for this window will be set to the type
* Cursor.DEFAULT_CURSOR.
* @see Component#getCursor
* @see Cursor
* @since JDK1.1
*/
public abstract void setCursor(final Cursor p_cursor);
/**
* Returns the child Component of this Window that has focus if this Window
* is focused; returns null otherwise.
*
* @return the child Component with focus, or null if this Window is not
* focused
* @see #getMostRecentFocusOwner
*/
public abstract Component getFocusOwner();
/**
* Returns the child Component of this Window that will receive the focus
* when this Window is focused. If this Window is currently focused, this
* method returns the same Component as getFocusOwner()
. If
* this Window is not focused, then the child Component that most recently
* requested focus will be returned. If no child Component has ever
* requested focus, and this is a focusable Window, then this Window's
* initial focusable Component is returned. If no child Component has ever
* requested focus, and this is a non-focusable Window, null is returned.
*
* @return the child Component that will receive focus when this Window is
* focused
* @see #getFocusOwner
*/
public abstract Component getMostRecentFocusOwner();
/**
* Gets a focus traversal key for this Window. (See
* setFocusTraversalKeys
for a full description of each key.)
*
* If the traversal key has not been explicitly set for this Window,
* then this Window's parent's traversal key is returned. If the
* traversal key has not been explicitly set for any of this Window's
* ancestors, then the current KeyboardFocusManager's default traversal key
* is returned.
*
* @param p_id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
* KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
* @return the AWTKeyStroke for the specified key
* @see Container#setFocusTraversalKeys
* @see KeyboardFocusManager#FORWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#BACKWARD_TRAVERSAL_KEYS
* @see KeyboardFocusManager#UP_CYCLE_TRAVERSAL_KEYS
* @see KeyboardFocusManager#DOWN_CYCLE_TRAVERSAL_KEYS
* @throws IllegalArgumentException if id is not one of
* KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
* KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
* KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
*/
public abstract Set
* If listener is null, no exception is thrown and no action is performed.
*
* @param p_listener the PropertyChangeListener to be added
*
* @see #addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
*/
public abstract void addPropertyChangeListener(
final PropertyChangeListener p_listener);
/**
* Adds a PropertyChangeListener to the listener list for a specific
* property. The specified property may be user-defined, or one of the
* following:
*
* If listener is null, no exception is thrown and no action is performed.
*
* @param p_property_name one of the property names listed above
* @param p_listener the PropertyChangeListener to be added
*
* @see #addPropertyChangeListener(java.beans.PropertyChangeListener)
*/
public abstract void addPropertyChangeListener(
final String p_property_name,
final PropertyChangeListener p_listener);
/**
* Checks if this Window is showing on screen.
* @return whether the window is showing or not
* @see Component#setVisible
*/
public abstract boolean isShowing();
/**
* Set the bounds.
* @param p_x The x-origin.
* @param p_y The y-origin.
* @param p_width The width.
* @param p_height The height.
*/
public abstract void setBounds(final int p_x,
final int p_y,
final int p_width,
final int p_height);
/**
* Validates this container and all of its subcomponents.
*
* The
* If this component is a lightweight component, this method
* causes a call to this component's
* Note: For more information on the paint mechanisms utilitized
* by AWT and Swing, including information on how to write the most
* efficient painting code, see
* Painting in AWT and Swing.
*
* @see #update(Graphics)
* @since JDK1.0
*/
public abstract void repaint();
/**
* Repaints the component. If this component is a lightweight
* component, this results in a call to
* Note: For more information on the paint mechanisms utilitized
* by AWT and Swing, including information on how to write the most
* efficient painting code, see
* Painting in AWT and Swing.
*
* @param p_tm maximum time in milliseconds before update
* @see #paint
* @see #update(Graphics)
* @since JDK1.0
*/
public abstract void repaint(final long p_tm);
/**
* Repaints the specified rectangle of this component.
*
* If this component is a lightweight component, this method
* causes a call to this component's
* Note: For more information on the paint mechanisms utilitized
* by AWT and Swing, including information on how to write the most
* efficient painting code, see
* Painting in AWT and Swing.
*
* @param p_x the x coordinate
* @param p_y the y coordinate
* @param p_width the width
* @param p_height the height
* @see #update(Graphics)
* @since JDK1.0
*/
public abstract void repaint(final int p_x,
final int p_y,
final int p_width,
final int p_height);
/**
* Repaints the specified rectangle of this component within
*
* If this component is a lightweight component, this method causes
* a call to this component's
* Note: For more information on the paint mechanisms utilitized
* by AWT and Swing, including information on how to write the most
* efficient painting code, see
* Painting in AWT and Swing.
*
* @param p_tm maximum time in milliseconds before update
* @param p_x the x coordinate
* @param p_y the y coordinate
* @param p_width the width
* @param p_height the height
* @see #update(Graphics)
* @since JDK1.0
*/
public abstract void repaint(final long p_tm,
final int p_x,
final int p_y,
final int p_width,
final int p_height);
/**
* Prints this component. Applications should override this method
* for components that must do special processing before being
* printed or should be printed differently than they are painted.
*
* The default implementation of this method calls the
*
* The origin of the graphics context, its
* (
* The origin of the graphics context, its
* (
* This method is called when the contents of the component should
* be painted; such as when the component is first being shown or
* is damaged and in need of repair. The clip rectangle in the
*
* For performance reasons,
* Note: For more information on the paint mechanisms utilitized
* by AWT and Swing, including information on how to write the most
* efficient painting code, see
* Painting in AWT and Swing.
*
* @param p_g the graphics context to use for painting
* @see #update
* @since JDK1.0
*/
public abstract void paint(final Graphics p_g);
/**
* Paints this component and all of its subcomponents.
*
* The origin of the graphics context, its
* (true
because all Windows must be roots of a
* focus traversal cycle.
*
* @return true
* @see #setFocusCycleRoot
* @see Container#setFocusTraversalPolicy
* @see Container#getFocusTraversalPolicy
*/
public abstract boolean isFocusCycleRoot();
/**
* Always returns null
because Windows have no ancestors; they
* represent the top of the Component hierarchy.
*
* @return null
* @see Container#isFocusCycleRoot()
*/
public abstract Container getFocusCycleRootAncestor();
/**
* Adds a PropertyChangeListener to the listener list. The listener is
* registered for all bound properties of this class, including the
* following:
*
*
* Note that if this Window is inheriting a bound property, then no
* event will be fired in response to a change in the inherited property.
*
*
* Note that if this Window is inheriting a bound property, then no
* event will be fired in response to a change in the inherited property.
* validate
method is used to cause a container
* to lay out its subcomponents again. It should be invoked when
* this container's subcomponents are modified (added to or
* removed from the container, or layout-related information
* changed) after the container has been displayed.
*
* @see Component#invalidate
* @see javax.swing.JComponent#revalidate()
*/
public abstract void validate();
/**
* Returns the preferred size of this container.
* @return an instance of Dimension
that represents
* the preferred size of this container.
* @see #getMinimumSize
* @see LayoutManager#preferredLayoutSize(Container)
* @see Component#getPreferredSize
*/
public abstract Dimension getPreferredSize();
/**
* Returns the minimum size of this container.
* @return an instance of Dimension
that represents
* the minimum size of this container.
* @see #getPreferredSize
* @see LayoutManager#minimumLayoutSize(Container)
* @see Component#getMinimumSize
* @since JDK1.1
*/
public abstract Dimension getMinimumSize();
/**
* Returns the maximum size of this container.
* @return The maximum size.
* @see #getPreferredSize
*/
public abstract Dimension getMaximumSize();
/**
* Transfer the focus backwards.
*/
public abstract void transferFocusBackward();
/**
* Transfers the focus down one focus traversal cycle. If this Container is
* a focus cycle root, then the focus owner is set to this Container's
* default Component to focus, and the current focus cycle root is set to
* this Container. If this Container is not a focus cycle root, then no
* focus traversal operation occurs.
*
* @see Component#requestFocus()
* @see #isFocusCycleRoot
* @see #setFocusCycleRoot
*/
public abstract void transferFocusDownCycle();
/**
* Repaints this component.
* paint
* method as soon as possible. Otherwise, this method causes
* a call to this component's update
method as soon
* as possible.
* paint
* within tm
milliseconds.
* paint
method
* as soon as possible. Otherwise, this method causes a call to
* this component's update
method as soon as possible.
* tm
milliseconds.
* paint
method.
* Otherwise, this method causes a call to this component's
* update
method.
* paint
method.
* 0
, 0
) coordinate point, is the
* top-left corner of this component. The clipping region of the
* graphics context is the bounding rectangle of this component.
* @param p_g the graphics context to use for printing
* @see #paint(Graphics)
* @since JDK1.0
*/
public abstract void print(final Graphics p_g);
/**
* Prints this component and all of its subcomponents.
* 0
, 0
) coordinate point, is the
* top-left corner of this component. The clipping region of the
* graphics context is the bounding rectangle of this component.
* @param p_g the graphics context to use for printing
* @see #print(Graphics)
* @since JDK1.0
*/
public abstract void printAll(final Graphics p_g);
/**
* Paints this component.
* Graphics
parameter is set to the area
* which needs to be painted.
* Subclasses of Component
that override this
* method need not call super.paint(g)
.
* Component
s with zero width
* or height aren't considered to need painting when they are first shown,
* and also aren't considered to need repair.
* 0
, 0
) coordinate point, is the
* top-left corner of this component. The clipping region of the
* graphics context is the bounding rectangle of this component.
*
* @param p_g the graphics context to use for painting
* @see #paint
* @since JDK1.0
*/
public abstract void paintAll(final Graphics p_g);
}