001package jmri.util.swing;
002
003import java.awt.Frame;
004
005/**
006 * Interface for an object that can arrange for a {@link JmriPanel} to be
007 * displayed.
008 * <p>
009 * Typically used by some component that wants to display a pane (for example,
010 * in an independent JmriJFrame or as part of a paned interface) to do some more
011 * stuff. Rather than have the component build its own window, etc it invokes
012 * one of these, so that the position and display of that component can be
013 * controlled.
014 * <p>
015 * Any {@link JmriAbstractAction} that uses the show() method will have its
016 * dispose() invoked when the associated frame goes away. It should dispose()
017 * any cached panes at that time.
018 *
019 * @author Bob Jacobsen Copyright 2010
020 * @since 2.9.4
021 */
022public interface WindowInterface {
023
024    /**
025     * Show, in whatever way is appropriate, a specific JmriPanel
026     *
027     * @param child  new JmriPanel to show
028     * @param action JmriAbstractAction making the request
029     */
030    void show(jmri.util.swing.JmriPanel child, JmriAbstractAction action);
031
032    /**
033     * Show, in whatever way is appropriate, a specific JmriPanel, in a hinted
034     * location
035     *
036     * @param child  new JmriPanel to show
037     * @param action JmriAbstractAction making the request
038     * @param hint   suggestion on where to put the content
039     */
040    void show(jmri.util.swing.JmriPanel child, JmriAbstractAction action, Hint hint);
041
042    /**
043     * Should 2nd and subsequent requests for a panel create a new instance, or
044     * provide the 1st one for reuse?
045     *
046     * @return true if multiple instances should be provided, false if only one
047     *         should be provided
048     */
049    boolean multipleInstances();
050
051    void dispose();
052
053    /**
054     * Returns the WindowInterface as a Frame or null.
055     *
056     * @return a Frame or null
057     */
058    Frame getFrame();
059
060    /**
061     * Suggested location for subsequent panels
062     */
063    enum Hint {
064        DEFAULT, // let the interface pick
065        REPLACE, // replace the current content with new
066        EXTEND     // place nearby
067    }
068}